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

Three reasons make a subagent worth spawning, and they often combine:

• 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.

A subagent runs on your full model by default, but the main model can assign a different one. general-purpose-mini exists because of how that assignment works: the main model resolves a subagent by name more consistently than it routes a model override to a general one, so a named “mini” is the reliable way to delegate to a smaller model. The same reasoning is why the @ reference picker lets you reference a model, so a model you want a subagent to use is easy to name.

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.