Subagent Patterns
Subagents are a system for delegating work to independent agents separated from the main conversation. Each subagent runs in its own context, so it can handle complex work in parallel while protecting the main conversation's context.
Built-in Subagentsโ
Claude Code comes with built-in subagents that are used automatically as the situation calls for them:
| Subagent | Model | Tools | Purpose |
|---|---|---|---|
| Explore | Inherited (capped at Opus) | Read-only | File exploration, code search, codebase understanding |
| Plan | Inherited | Read-only | Codebase investigation in Plan mode |
| general-purpose | Inherited | Full | Complex research, multi-step work, code changes |
| Bash | Inherited | - | Running terminal commands in a separate context |
| statusline-setup | Sonnet | - | Used when configuring /statusline |
| Claude Code Guide | Haiku | - | Answering questions about Claude Code features |
Claude automatically picks the right subagent based on the nature of the task. Explore is used for exploring the codebase, and general-purpose for complex work that requires changes. As of v2.1.198, Explore inherits the main session's model instead of Haiku (capped at Opus).
Core Characteristics of Subagentsโ
Context Separationโ
Subagents run in a context independent from the main conversation. Only their results are summarized back into the main conversation. This provides:
- Context protection: Exploration results don't take up the main context
- Parallel processing: Multiple subagents can run at the same time
- Isolated experimentation: A failure has no effect on the main conversation
Nesting (Up to 5 Levels)โ
As of v2.1.172, subagents can create their own subagents โ up to 5 levels deep. Previously, a subagent couldn't create another subagent, so nested delegation required skills or sequential chaining; now a subagent can re-delegate subtasks directly.
The depth is limited to 5 levels for both foreground and background (to prevent infinite nesting; v2.1.181 applied the same limit to foreground as well).
Foreground vs Backgroundโ
As of v2.1.198, subagents run in the background by default. While a subagent works, Claude keeps working in the main conversation and is notified when it finishes.
| Background (default) | Foreground | |
|---|---|---|
| Behavior | Works concurrently with the main conversation | Blocks the main conversation until done |
| Permissions | Permission prompts appear in the main session | Interactive permission prompts |
| On failure | Can be resumed in the foreground | Immediate interactive fixes |
A background subagent's permission requests are not auto-denied; they appear as a dialog in the main session (v2.1.186) โ it also shows which agent made the request, and pressing Esc denies only that request.
Resuming Subagentsโ
You can have a subagent continue its work after it finishes:
> Review the auth module with the code-reviewer subagent
[agent finishes]
> Continuing that code review, also analyze the authorization logic
[the subagent resumes with its previous context intact]
A resumed subagent keeps all of its previous tool calls, results, and reasoning.
Disabling Subagentsโ
You can block specific subagents:
{
"permissions": {
"deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
}
}
# Via CLI flag
claude --disallowedTools "Agent(Explore)"
In version 2.1.63, the Task tool was renamed to Agent. Existing Task(...) references continue to work as an alias for compatibility.
Practical Patternsโ
Parallel Code Analysisโ
> Analyze frontend performance issues and backend API response times at the same time
Claude automatically creates several subagents, analyzes in parallel, and synthesizes the results.
Large-Scale Refactoringโ
> Add error handling to every API endpoint
Each endpoint is handled in a separate subagent, managing context efficiently.
Multi-Step Workflowsโ
> 1. Analyze the DB schema,
2. write the migration,
3. and write the tests
Each step is delegated to a subagent and the results are coordinated sequentially.
If you need ongoing parallel work, consider Agent Teams instead of subagents. Subagents each return their results to the main context, whereas Agent Teams operate independently and coordinate through a shared task list.