This document explains Claude Code's hierarchical agent architecture, which enables parallel task execution through subagents. It covers the Task tool for creating subagents, agent configuration parameters, lifecycle hooks, async communication mechanisms, and monitoring capabilities.
For information about the Tool System and how permissions control agent behavior, see Tool System & Permissions. For details about the Hook System that intercepts agent actions, see Hook System.
The agent system implements hierarchical task decomposition where a main agent can spawn independent subagent instances to execute subtasks in parallel. Each subagent maintains its own context window, model configuration, and permission scope, enabling complex multi-step workflows while avoiding token limit issues in the main thread.
As of version 2.1.32, an experimental Agent Teams feature enables multi-agent collaboration, where multiple agents work together with coordination mechanisms. This is a research preview feature requiring CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 to be set.
Sources: CHANGELOG.md64
Sources: CHANGELOG.md148 CHANGELOG.md533 CHANGELOG.md563
The main agent maintains the primary conversation with the user, while subagents execute delegated tasks independently. Each agent has its own context window, preventing one task's context usage from affecting others.
| Component | Description | Configuration |
|---|---|---|
| Main Agent | Primary conversation thread with user | Configured via --agent flag or agent setting |
| Task Tool | Built-in tool for spawning subagents | Always available unless explicitly disallowed via disallowedTools or Task(agent_type) syntax |
| Subagent Instance | Independent agent with isolated context | Configured via Task tool parameters and agent frontmatter |
| TaskUpdate | Status reporting from subagent to main | Used for progress updates and task deletion |
| TaskOutputTool | Final result delivery | Unified tool replacing deprecated AgentOutputTool/BashOutputTool |
| Async Messages | Wake mechanism for main agent | Enables subagents to interrupt main thread when needing input |
| Agent Memory | Persistent memory system | Scoped to user, project, or local via memory frontmatter field |
| Agent Teams | Multi-agent collaboration (experimental) | Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 |
Sources: CHANGELOG.md23 CHANGELOG.md47-48 CHANGELOG.md64 CHANGELOG.md169 CHANGELOG.md545 CHANGELOG.md618
The main agent creates subagents by invoking the Task tool with task parameters. The subagent executes independently and reports results back through TaskOutputTool.
Sources: CHANGELOG.md658 CHANGELOG.md545
When the main agent invokes the Task tool, it can specify:
haiku, sonnet, opus)Task(agent_type) syntax)allowed-tools parameterallow, ask, deny)context: forkSources: CHANGELOG.md47 CHANGELOG.md311-312 CHANGELOG.md655 CHANGELOG.md657
Sources: CHANGELOG.md572-573
The main agent can be configured with a specific agent profile using the agent setting in settings.json or the --agent CLI flag. This applies a predefined system prompt, tool restrictions, and model selection.
Example agent configuration structure:
model: Default model for the agentallowed-tools: Tool allowlistpermissions: Permission rules specific to this agentskill inheritance: Skills available to the agentSources: CHANGELOG.md572-573
Subagents inherit configuration from their parent but can override specific settings through the Task tool invocation and SubagentStart hooks.
The SubagentStart hook fires when a subagent is created, allowing customization before execution begins:
Sources: CHANGELOG.md658 CHANGELOG.md335
Hook input includes:
agent_type: Populated from --agent flag if specifiedSources: CHANGELOG.md290
Agents defined in configuration files or skill frontmatter support several fields:
| Field | Description | Example Values |
|---|---|---|
model | Default model for the agent | opus, sonnet, haiku |
tools | Restricted set of allowed tools, with optional Task(agent_type) syntax to limit spawnable sub-agents | ["Read", "Write", "Task(ReviewAgent)"] |
memory | Persistent memory scope | user, project, local |
hooks | Lifecycle hooks scoped to agent | PreToolUse, PostToolUse, Stop |
agent | Agent type for skill execution | Agent profile name |
context | Context mode for execution | fork to fork conversation |
Hooks Supported in Agent Frontmatter:
PreToolUse: Execute before any tool invocationPostToolUse: Execute after tool completionStop: Execute when agent completes or is interruptedSources: CHANGELOG.md47-48 CHANGELOG.md311-312 CHANGELOG.md335
Diagram: Subagent State Machine
Sources: CHANGELOG.md34 CHANGELOG.md46 CHANGELOG.md96 CHANGELOG.md169 CHANGELOG.md398
Subagents can run in the background, allowing the main agent to continue accepting user input:
| Trigger | Description |
|---|---|
| Ctrl+B | Manual backgrounding of active agents |
| Auto-background | Automatic when subagent doesn't need immediate user input |
| Task Tool default | Background execution is the default behavior |
Sources: CHANGELOG.md331 CHANGELOG.md563
The CLAUDE_CODE_DISABLE_BACKGROUND_TASKS environment variable can disable all background task functionality.
Sources: CHANGELOG.md264
Several hooks fire at different points in the subagent lifecycle:
| Hook Event | When Triggered | Input Parameters |
|---|---|---|
SessionStart | Subagent initialization | agent_type (if --agent specified) |
Setup | Repository setup/maintenance | Triggered via --init, --init-only, or --maintenance |
PreToolUse | Before tool invocation | Tool name, parameters, can return additionalContext or updatedInput |
PostToolUse | After tool execution | Tool name, result |
TeammateIdle | Teammate waiting for work (agent teams) | Agent state information |
TaskCompleted | Task completion (agent teams) | Completion status |
Stop | Agent termination | agent_id, agent_transcript_path |
Sources: CHANGELOG.md46 CHANGELOG.md219 CHANGELOG.md290 CHANGELOG.md323 CHANGELOG.md666
Subagents can asynchronously wake the main agent to request input or report critical updates. Bash commands and agents running in the background can also send messages to wake up the main agent.
Diagram: Async Message Flow
Sources: CHANGELOG.md118 CHANGELOG.md533 CHANGELOG.md606
Subagents use TaskUpdate to report progress without completing:
Sources: CHANGELOG.md96
Final results are delivered through TaskOutputTool, which replaced the deprecated AgentOutputTool and BashOutputTool:
Sources: CHANGELOG.md23 CHANGELOG.md216 CHANGELOG.md545
The /tasks dialog shows all active background tasks:
Sources: CHANGELOG.md106 CHANGELOG.md111 CHANGELOG.md250 CHANGELOG.md348
The status bar shows a background task indicator when subagents are active:
Sources: CHANGELOG.md50 CHANGELOG.md274
When background tasks complete, notifications appear with:
Sources: CHANGELOG.md216 CHANGELOG.md253 CHANGELOG.md372-373
Tasks can be stopped through:
| Method | Description |
|---|---|
| TaskStop tool | Agent-invoked termination |
| User cancellation | Manual interruption (Esc) |
| TaskUpdate deletion | Programmatic removal from task list |
Sources: CHANGELOG.md34 CHANGELOG.md96
Specific agents can be disabled using the Task(AgentName) syntax in multiple contexts:
| Configuration Location | Syntax | Effect |
|---|---|---|
settings.json permissions | Task(AgentName) in disallowedTools | Blocks spawning of specific agent type |
--disallowedTools CLI flag | --disallowedTools Task(AgentName) | Session-level blocking of agent type |
Agent frontmatter tools | Task(agent_type) in allowed tools list | Restricts which sub-agents can be spawned |
Example:
This prevents the main agent from spawning ReviewAgent or TestAgent subagent types.
Sources: CHANGELOG.md47 CHANGELOG.md334 CHANGELOG.md339
Each subagent maintains a completely independent context window:
Sources: CHANGELOG.md168 CHANGELOG.md220
The system implements several optimizations for parallel subagent execution:
Sources: CHANGELOG.md33 CHANGELOG.md151 CHANGELOG.md169-170
Subagents can operate with different permission modes:
permissionMode in agent configurationSources: CHANGELOG.md117 CHANGELOG.md655
Subagents continue working after permission denial, allowing them to try alternative approaches rather than failing the entire task.
Sources: CHANGELOG.md398 CHANGELOG.md634
The task system underwent a major revision in version 2.1.16, introducing:
A temporary environment variable CLAUDE_CODE_ENABLE_TASKS was provided to keep the old system during the transition.
Refresh this wiki