claude-subagents
A Subagent is a claude-code instance the main session spawns to do one bounded task with its own context window and a restricted tool set; it reports back a summary. Per tw93 the primary value is isolation, not parallelism (2026-04-27-claude-code-architecture-governance-engineering).
Why isolation matters
Codebase scans, test runs, and reviews produce large outputs. Run them in the main session and effective context evaporates. Run them in a Subagent and the main thread gets back a small summary — main context stays clean (context-engineering).
Built-in Subagents
| Name | Role | Default model |
|---|---|---|
| Explore | Read-only repo scans / lookups | Haiku (cost) |
| Plan | Planning and design research | — |
| General-purpose | Open-ended | — |
Custom Subagents go in .claude/agents/.
Constrain explicitly
| Setting | Why |
|---|---|
tools / disallowedTools | Don’t grant the same wide permissions as the main thread; if the Subagent has the same powers there’s nothing to isolate |
model | Haiku/Sonnet for exploration; Opus for serious review |
maxTurns | Stops runaway loops |
isolation: worktree | When the Subagent must touch files, give it its own git worktree |
Background pattern
Long-running bash commands: Ctrl+B to background — Claude can read results later via BashOutput without blocking the main thread. Same idea works for Subagents — tell one to “run in the background” and continue (2026-04-27-claude-code-architecture-governance-engineering).
Anti-patterns
- Subagent inherits the main thread’s full permissions → no real isolation.
- Output format unspecified → main thread gets back unstructured prose it can’t act on.
- Sub-tasks tightly coupled, needing constant shared state → Subagent is the wrong primitive for this; do it in-line.
Pattern: model handoff
Switching models mid-session destroys the cache. If a different model is genuinely needed, use a Subagent: have the current model write a short briefing message, hand the task off — the other model runs in its own session with its own cache lifecycle.
Two non-negotiables for sub-Agents
2026-04-27-agent-principles-architecture-engineering sharpens two boundaries that apply equally to Claude Code Subagents and to the multi-Agent worker pattern more generally:
- Hard depth limit. Cap recursion. Without one, sub-Agents spawning grandchild sub-Agents is a real failure mode.
- Minimal system prompt. Sub-Agents get only Tooling, Workspace, Runtime — no Skills, no Memory directives inherited from the parent. Two reasons: prevent permission leakage from the parent’s privileges, and keep the isolation boundary that justifies using a sub-Agent at all.
These are the same instincts behind tools / disallowedTools / maxTurns above — codify the boundary explicitly rather than trusting inheritance.