Spawn a worker
spawn_workerStart 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
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | 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. | |
| name | No | A name for the worker, unique among live workers. Every tool taking a workerId accepts it instead of the generated id. | |
| model | No | Model override, as `<provider>/<model>`. | |
| policy | No | Auto-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. | |
| sandbox | No | How 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). | |
| provider | No | A provider id from list_providers. Default: the first one. | |
| resumeFrom | No | 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. | |
| systemPrompt | No | Extra system instructions for the worker. | |
| persistSession | No | 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notes | Yes | ||
| worker | Yes | ||
| clamped | Yes | What the server's ceiling lowered. | |
| resumed | No | 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. |