Subagents

A subagent is a separate agent the model starts to handle one self-contained task, such as a piece of research, a large read, or a delimited bit of work. The subagent does the task in its own context, and only a short result returns to the main conversation. You do not start subagents yourself; the model does, when a task is bounded enough to hand off.

Why the model uses them

A subagent is worth spawning for one or more of these reasons:

• Context protection. The subagent’s work, including the false starts, the long tool output, and the dead ends, stays in its own context. Only the result reaches the main conversation, so your context stays clear for the work you care about.
• Context freshness. A subagent starts with no history, so it reads the task without the assumptions the main conversation has already built up. Even the same model, run fresh, often takes a different approach.
• Restricted permissions. A subagent can run with a narrower permission set than the main agent, which limits what it may do. See Permissions.

Built-in subagents

• researcher: investigates a question against your codebase, the web, or both. Use it when the task is to go find something out.
• general-purpose and general-purpose-mini: use these for a bounded task when no specialized subagent fits. The two are the same agent on different models: general-purpose runs on your full model, general-purpose-mini on your smaller one.

general-purpose uses your full model. general-purpose-mini uses your smaller model for bounded tasks that need less capacity.

How they run

Subagents run asynchronously, alongside the main conversation, and appear as jobs. Watch them in the async jobs pane or with /jobs, each under a handle like researcher:curie. See Managing Work.

When a subagent finishes, Polytoken sends a notification and returns a short result to the model, not the subagent’s whole conversation. By default these notifications auto-drain: as soon as the result arrives, Polytoken starts a turn so the model can act on it, even if the main conversation was idle and waiting for you to type. To have the model wait for your next prompt instead, turn auto-drain off; see the configuration reference. If a subagent reports failure, the failure notification asks the model to retry a single time only if the failure looks transient. The same notification asks the model to surface repeated or non-transient failures for you to handle. If Polytoken cannot launch a subagent, the launch error preserves the specific cause of the failure and includes the same bounded retry and escalation guidance.

Working directory

A subagent starts in the working directory the main conversation is using. If the model has pushed into a subdirectory with the pushd tool, the subagent starts there; otherwise it starts at the project root.

The model can also start a subagent in a specific directory by passing cwd when it spawns the subagent. The directory has to exist, and a relative path resolves against the main conversation’s working directory. Directories outside the project ask for chdir permission approval, and approving one also grants read access so the subagent can use file tools there without a second prompt. Once a subagent starts, it cannot popd above its start directory, though it can still pushd deeper if it has that tool.

When the model does not pass cwd, the subagent starts in the main conversation’s working directory, exactly as before.

Messaging a running subagent

The model can send a text message to a subagent that is still running using the message_subagent tool. Polytoken queues the message and delivers it before the subagent’s next step, never mid-response. The tool returns immediately after queuing. If the subagent has already completed, Polytoken drops the message. The model can check whether a subagent is still running with job_status before sending.

Messages appear in the subagent’s conversation as new input. The subagent responds to them as part of its normal work.

Only the main conversation can use message_subagent.

Resuming a subagent

A subagent’s work does not have to end when the subagent completes. The model can fork a completed subagent’s conversation into a new subagent, letting the same context carry forward into a new task. This is how the model takes a research subagent’s findings and turns them into an implementation subagent without re-explaining everything it already discovered.

The model passes resume_from with the prior subagent’s job handle, and the new prompt becomes a directive appended after the prior conversation. The fork creates a new subagent with its own job handle, so the source subagent is never modified. The fork uses the subagent type and model chosen for it, not the source’s.

Multiple forks from the same source are possible. Each fork gets a new handle and its own independent context from that point forward. The prior subagent’s history is carried as conversation history, so the forked subagent sees everything the source saw, including tool results and earlier reasoning.