Subagents (experimental)
Subagents let the agent delegate independent parts of a complex task through the agent.task tool. Each subagent works in an isolated context, and the parent agent collects and summarizes the results. This can speed up batch processing, reviews from multiple perspectives, and parallel research. The feature is experimental, and agent.task is disabled by default. Enable it from Ctrl+P > Settings > Subagents in the TUI.
Execution model
Subagents use a synchronous execution model. After launching them, the parent agent waits until every subagent finishes or reaches its budget, then collects their results. Each subagent has an independent context window and tool-call budget, and multiple subagents can run in parallel.
| Feature | Behavior |
|---|---|
| Execution | Synchronous: the parent waits for all subagents, then summarizes their results |
| Tool permissions | The parent session, subagent descriptor, and gateway jointly restrict available tools; a subagent cannot exceed the parent's capabilities |
| Tool budget | Each subagent has its own tool-call limit; if exhausted, execution stops but partial results are returned |
| Step budget | Each subagent has its own inference-step limit |
| Context | Each subagent has an independent context window that does not consume the parent's context |
| Parallelism | Multiple subagents can run concurrently |
| Nesting | Unsupported; a subagent cannot create another subagent |
Permission control
A subagent does not select one of the session-level read, workspace, auto, or yolo policies. Its effective toolset is the intersection of three layers: tools currently available to the parent session, allowedTools / deniedTools / readOnly constraints in the subagent descriptor, and the tool gateway's final permission check.
Built-in subagents currently focus on read-only exploration and review. They can read and search files, load Skills, and use known read-only MCP tools exposed by the host. They cannot write files, run shell commands, create nested subagents, or invoke tools with write side effects. A tool unavailable to the parent is also unavailable to its subagents.
The rule is simple: subagents can narrow the capabilities exposed by the parent session, but they cannot expand them.
Budget mechanism
Each subagent has a tool-call budget and an inference-step budget. Reaching either limit stops the subagent, but any partial result is still returned to the parent. Set budgets according to task complexity: a budget that is too small may stop useful work early, while an unnecessarily large budget consumes more resources.
Applicable scenarios
Subagents work best for independent tasks that can run in parallel. Examples include processing multiple files, reviewing the same code for security, performance, and style, or gathering information from several sources. They are less suitable when tasks have strict sequential dependencies or require extensive shared context.
| Suitable | Not suitable |
|---|---|
| Batch file processing | Strict serial dependency |
| Multi-perspective code review (security, performance, and style) | Close collaboration that requires extensive shared context |
| Parallel information collection | Simple single-step operation (overhead exceeds benefits) |
| Parallel testing of independent modules | Frequent interaction between subagents |
Export
26.9.11 does not provide a dedicated subagent-audit export option. For the parent conversation, see Session export; this is not a complete subagent audit archive.
Known limitations
As an experimental feature, subagents have several limitations. They cannot be nested, which prevents recursive delegation. Their context windows are independent and relatively small, making them better for focused tasks than broad exploration. They cannot access the parent agent's session history or memory, and parallel subagents cannot share results directly; all information must pass through the parent agent.
| Limitations | Description |
|---|---|
| No nesting | Subagents cannot create subagents |
| Independent context | The context window is independent and isolated from the parent agent |
| No memory | No access to parent agent session history and memory |
| No direct sharing | Parallel subagent results need to be forwarded through the parent agent |