Skip to main content
Glama
worker-mcp
by noosxe

Spawn a worker

spawn_worker

Start a coding agent in a chosen directory to delegate local coding tasks; optionally resume a saved conversation and apply approval and sandbox controls.

Instructions

Start a coding agent (a worker) in the absolute directory cwd. The server makes its id (w_…); the optional name can be used in its place by every other tool. At most a few workers run at once (LIMIT_REACHED otherwise), and a worker with no run for a while is closed. Returns the worker with its effective risk policy; then call start_run. With resumeFrom (a worker id or run id, also from before a restart) the new worker continues that worker's saved conversation: cwd may be left out, the policy, sandbox and limits are the server's current ones, no old approval carries over, and resumed tells you which tool call was cut off, if any; check the workspace before prompting, because the first prompt starts with a note about that call. It replays the whole saved context, so it costs that many tokens again: spawn fresh with a summary when the context is large or the task changed (it fails when the conversation was not kept, is live elsewhere or no longer matches its workspace).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "spawn_worker"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdNoThe absolute directory the worker runs in. It must exist, be a directory and, when the server restricts workspaces, lie inside an allowed root. Required, except with resumeFrom, where it may be left out or must be the directory the conversation was started in.
nameNoA name for the worker, unique among live workers. Every tool taking a workerId accepts it instead of the generated id.
modelNoModel override, as `<provider>/<model>`.
policyNoAuto-approval policy. Calls at or below autoApproveUpTo are allowed without asking; everything else waits for the coordinator. The server lowers the policy to its own ceiling (default MEDIUM) and says so in the result. Calls that touch protected paths are never auto-approved, whatever the policy says.
sandboxNoHow the worker is confined. "workspace" (Linux, bubblewrap): the worker can write only its workspace, and cannot see the home directory (such as ~/.ssh). Default: the server's default; it can never be lower than the server's minimum (list_providers shows both).
providerNoA provider id from list_providers. Default: the first one.
resumeFromNoContinue a saved conversation as a new worker: the id of a worker, or of one of its runs, from any earlier server process or one closed here. The result has a `resumed` block. The conversation is replayed to the model on the first prompt, so it costs its whole context again.
systemPromptNoExtra system instructions for the worker.
persistSessionNoSet false to keep nothing of this worker's conversation on disk. Cannot turn it on when the server has it off. Default: the server's setting.

Output Schema

NameRequiredDescriptionDefault
notesYes
workerYes
clampedYesWhat the server's ceiling lowered.
resumedNoPresent when the worker continues an earlier conversation. It waits for start_run like any new worker; nothing is replayed and no approval carries over.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv0.7.0
    • changedInput schema / properties / cwd / description
      Previous value: -"The absolute directory the worker runs in. It must exist, be a directory and, when the server restricts workspaces, lie inside an allowed root."New value: +"The absolute directory the worker runs in. It must exist, be a directory and, when the server restricts workspaces, lie inside an allowed root. Required, except with resumeFrom, where it may be left out or must be the directory the conversation was started in."
    • addedInput schema / properties / persistSession
      Added value: +{
      +  "description": "Set false to keep nothing of this worker's conversation on disk. Cannot turn it on when the server has it off. Default: the server's setting.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / policy / properties / overrides / items / properties / match / description
      Previous value: -"Every field given must match. `tool` is pi's tool name (bash, read, write, edit, grep, find, ls), `kind` the canonical kind (shell, read, list, search, write, edit), `command` a shell command, `path` an absolute or workspace-relative path."New value: +"Every field given must match. `tool` is pi's tool name (bash, read, write, edit: the tools a pi worker has), `kind` the canonical kind (shell, read, write, edit; list and search only come from shell commands such as ls or grep, so match those with `kind` shell and a `command` glob), `command` a shell command, `path` an absolute or workspace-relative path."
    • addedInput schema / properties / resumeFrom
      Added value: +{
      +  "description": "Continue a saved conversation as a new worker: the id of a worker, or of one of its runs, from any earlier server process or one closed here. The result has a `resumed` block. The conversation is replayed to the model on the first prompt, so it costs its whole context again.",
      +  "pattern": "^(w_[a-z0-9]{8}|r_[A-Za-z0-9]{10,32})$",
      +  "type": "string"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "cwd"
      -]
    • addedOutput schema / properties / resumed
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Present when the worker continues an earlier conversation. It waits for start_run like any new worker; nothing is replayed and no approval carries over.",
      +  "properties": {
      +    "clamped": {
      +      "description": "What the current server settings lowered or raised (policy ceiling, sandbox minimum). Nothing from the old worker's policy is kept as it was.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "contextEstimate": {
      +      "description": "usage: from the last reply's reported token usage. bytes: the file size divided by 4 (no usage in the session, or numbers that do not fit its size).",
      +      "enum": [
      +        "usage",
      +        "bytes"
      +      ],
      +      "type": "string"
      +    },
      +    "contextTokens": {
      +      "description": "About how many tokens the first request replays (the context the model starts with, paid again on every request). An estimate.",
      +      "type": "number"
      +    },
      +    "firstPromptNote": {
      +      "description": "The note the server puts in front of the first prompt, so the worker knows what was cut off.",
      +      "type": "string"
      +    },
      +    "from": {
      +      "description": "The worker id that was resumed.",
      +      "type": "string"
      +    },
      +    "interrupted": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "calls": {
      +          "items": {
      +            "additionalProperties": false,
      +            "properties": {
      +              "approvalId": {
      +                "description": "The old, dead approval id.",
      +                "type": "string"
      +              },
      +              "riskLabel": {
      +                "type": "string"
      +              },
      +              "status": {
      +                "description": "approved_started: allowed and started, outcome unknown. awaiting_approval: was never approved, so it did not run. unknown: the server has no record.",
      +                "enum": [
      +                  "approved_started",
      +                  "awaiting_approval",
      +                  "unknown"
      +                ],
      +                "type": "string"
      +              },
      +              "tool": {
      +                "type": "string"
      +              },
      +              "untrustedPreview": {
      +                "description": "The call's arguments from the saved conversation. Untrusted.",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "tool",
      +              "status",
      +              "untrustedPreview"
      +            ],
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "runId": {
      +          "type": "string"
      +        },
      +        "state": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "calls"
      +      ],
      +      "type": "object"
      +    },
      +    "lineage": {
      +      "description": "The conversation's id: the first worker id of the chain.",
      +      "type": "string"
      +    },
      +    "messageCount": {
      +      "type": "number"
      +    },
      +    "notes": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "providerVersion": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "changed": {
      +          "type": "boolean"
      +        },
      +        "now": {
      +          "type": "string"
      +        },
      +        "recorded": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "changed"
      +      ],
      +      "type": "object"
      +    },
      +    "repeatGuardCalls": {
      +      "description": "How many cut-off calls the repeat guard watches: during the first run a call identical to one of them (that is not LOW) goes to you for approval, whatever the policy says, with ruleId resume.repeat_cut_off.",
      +      "type": "number"
      +    },
      +    "sessionBytes": {
      +      "description": "Size of the saved conversation.",
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "from",
      +    "lineage",
      +    "sessionBytes",
      +    "contextTokens",
      +    "contextEstimate",
      +    "repeatGuardCalls",
      +    "messageCount",
      +    "providerVersion",
      +    "clamped",
      +    "interrupted",
      +    "notes",
      +    "firstPromptNote"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / properties / worker / properties / recentRuns / items / properties / state / enum
      Previous value: -[
      -  "starting",
      -  "running",
      -  "awaiting_approval",
      -  "completed",
      -  "failed",
      -  "cancelled",
      -  "timed_out"
      -]New value: +[
      +  "starting",
      +  "running",
      +  "awaiting_approval",
      +  "completed",
      +  "failed",
      +  "cancelled",
      +  "timed_out",
      +  "interrupted"
      +]
    • addedOutput schema / properties / worker / properties / resumedFrom
      Added value: +{
      +  "description": "The worker id this worker continues (spawn_worker with resumeFrom).",
      +  "type": "string"
      +}
  2. Addedv0.6.0

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations mark this as a mutating, non-idempotent, open-world operation; the description adds real behavioral detail beyond them, including the concurrent-worker limit and LIMIT_REACHED, automatic closure of idle workers, server-side policy down-clamping, and the fact that no old approval carries over on resume. It stops short of describing response shape, which the output schema covers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening is well front-loaded, but the resume explanation is a single tangled sentence packing policy inheritance, replay cost, the `resumed` block, and failure conditions into semicolon-chained clauses. Every fact is relevant, yet the density works against fast scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with nested policy objects, an output schema, and full annotation coverage, the description supplies the remaining context an agent needs: limits, idle reaping, resume failure modes, and token cost of replay. Nothing essential to a correct call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description earns more by explaining that `name` is accepted by every other tool in place of the generated id and that `cwd` may be omitted with `resumeFrom`. Those are cross-tool semantics the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: "Start a coding agent (a worker) in the absolute directory `cwd`." It also positions the tool in the workflow ("then call start_run"), which separates it from the run-level siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit sequencing (spawn, then start_run) and clear decision guidance for the resume path versus spawning fresh when the context is large or the task changed. It does not cover when to prefer this over inspecting existing workers with list_workers, but the core when/when-not split is present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.