Skip to main content
Sub-agents are background agent runs spawned from an existing agent run. Each one runs in its own session (agent:<agentId>:subagent:<uuid>) and, by default, announces its result back to the requester for review. Every sub-agent run is tracked as a background task. Goals:
  • Parallelize research, long tasks, and slow tool work without blocking the main run.
  • Keep sub-agents isolated by default (session separation, optional sandboxing).
  • Keep the tool surface hard to misuse: sub-agents do not get session or message tools by default.
  • Support configurable nesting depth for orchestrator patterns.
Cost note: each sub-agent has its own context and token usage by default. For heavy or repetitive tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model via agents.defaults.subagents.model or per-agent overrides. When a child genuinely needs the requester’s current transcript, spawn it with context: "fork". Thread-bound subagent sessions default to context: "fork" because they branch the current conversation into a follow-up thread.
A subagent run ends; a session does not. When you open a subagent run in the Control UI, its transcript is view-only. Use Open parent session in the composer area to continue the conversation with the parent. You can still use Stop when the Gateway reports an abortable run. Persistent sessions created with visible: true are ordinary sessions in the session tree: they keep their parent for navigation and completion announcements, and you can always type in them and steer them like any other session. Use ordinary subagents for internal QA, research, coding, review, and test lanes, with results returning to the parent task. Create a persistent visible session only when the user requests a separate session or needs to return to and steer that work independently. A PR or report, a long run, or an isolated worktree alone does not make a worker a separate user-facing task. Asking for subagents does not ask for new sidebar sessions or categories. This page is an index. Sub-agents are documented on seven pages, one per reader job. Open the page that matches your task.

​
Where each section moved

Every section heading, accordion, step, and parameter id from the previous single-page version keeps its anchor here, so an existing link such as /tools/subagents#thread-bound-sessions still resolves. Each entry points at the page that now holds the content.