Agent coordination
Sub-agents
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.
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.
This page is an index. Sub-agents are documented on seven pages, one per reader job. Open the page that matches your task.
| Page | Read it when |
|---|---|
| Sub-agent slash command | You want to inspect a run from chat, or need the completion-delivery rules. |
| Sub-agent tool reference | You are calling sessions_spawn, sessions_yield, or subagents and need parameters. |
| Thread-bound sub-agent sessions | You are binding a sub-agent to a channel thread, or need allowlist and archive rules. |
| Nested sub-agents and authentication | You are building an orchestrator and need depth caps, the announce chain, or auth. |
| Sub-agent announce | You are debugging how a child result reaches the requester. |
| Sub-agent tool policy | You need the tools a sub-agent always loses, or want to narrow them further. |
| Sub-agent concurrency, recovery, and stopping | You are tuning concurrency, recovering after a restart, or stopping a child tree. |
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.
- Slash command
- Thread binding controls
- Spawn behavior
- Non-blocking, push-based completion
- Completion delivery
- Completion handoff metadata
- Modes and ACP runtime
- Context modes
- Tool:
sessions_spawn - Delegation prompt mode
- Tool parameters
tasktaskNamelabelagentIdcwdruntimeresumeSessionIdstreamTomodelrunTimeoutSecondsthinkingthreadmodecleanupexpectsCompletionMessagesandboxcontextvisiblegroupworktreeworktreeNameworktreeBaseRef- Task names and targeting
- Tool:
sessions_yield - Tool:
subagents - Thread-bound sessions
- Thread supporting channels
- Quick flow
- Spawn
- Bind
- Route follow-ups
- Inspect timeouts
- Detach
- Manual controls
- Config switches
- Allowlist
agents.entries.*.subagents.allowAgentsagents.defaults.subagents.allowAgentsagents.defaults.subagents.requireAgentIdagents.defaults.subagents.announceTimeoutMs- Discovery
- Auto-archive
- Nested sub-agents
- Depth levels
- Announce chain
- Tool policy by depth
- Per-agent spawn limit
- Reset a conversation
- Cascade stop
- Authentication
- Announce
- Announce context
- Stats line
- Why prefer
sessions_history - Tool policy
- Override via config
- Concurrency
- Liveness and recovery
- Stopping
- Limitations
Related
- Session tools and state changes
- ACP agents
- Agent send
- Background tasks
- Multi-agent sandbox tools
- Parallel specialist lanes — role-scoped lanes for a single job
- Steer — redirect a running agent mid-task
