Last updated: July 5, 2026 — run on Claude Code v2.1.201, Windows 11
Since v2.1.172, subagents in Claude Code can spawn their own subagents, up to five levels deep. (Not seeing it? Your CLI may be running an older version than you think.) Most write-ups restate the changelog. Instead, I built the docs’ canonical use case — a code reviewer that dispatches one verifier per finding — pointed it at a real project, and watched the tree grow. Here’s the working setup, what the panel actually shows, the trap that Windows users will hit, and what it all cost in tokens.
TL;DR: Nesting works exactly as advertised and the isolation is real — my reviewer (Sonnet) consumed 43% of the day’s usage while its four Haiku verifiers barely registered at 4% combined. Two traps: on Windows, PowerShell’s default UTF-8 adds a BOM that silently breaks agent files, and the Agent(name1, name2) allowlist syntax is ignored inside subagent definitions.
What changed in v2.1.172
One changelog line: “Sub-agents can now spawn their own sub-agents (up to 5 levels deep).” Before that, delegation was flat. The agent panel below the prompt caught up over June — it now renders the full tree, with sibling/child drill-down since v2.1.193, and idle agents auto-hide after 30 seconds.
Two rules with teeth, from the docs:
- At depth 5, the Agent tool is silently removed — a fifth-level subagent can’t spawn further. Fixed, not configurable.
- Depth is fixed at spawn — resuming a background subagent later doesn’t reset it.
The pipeline: reviewer → one verifier per finding
Three files in .claude/agents/. The design choices: verifier and inspector run on haiku (narrow tasks, cheap), and inspector has no Agent tool at all — the chain terminates by design at level 3, well short of the cap.
reviewer.md (level 1 — orchestrates):
---
name: reviewer
description: Reviews code and dispatches one verifier per finding
tools: Read, Grep, Glob, Agent
model: sonnet
---
Review the given code. For each potential issue you find, spawn a
verifier subagent with the specific claim and file references.
Collect verifier verdicts and return only confirmed issues, each with
severity and a one-line fix suggestion.verifier.md (level 2 — checks one claim):
---
name: verifier
description: Verifies a single review finding against the codebase
tools: Read, Grep, Agent
model: haiku
---
You get one claimed issue. Verify it against the actual code. If the
claim depends on how a symbol is used elsewhere, spawn an inspector
for that file. Return CONFIRMED or FALSE-POSITIVE with a two-line reason.inspector.md (level 3 — leaf, cannot nest):
---
name: inspector
description: Inspects one file for how a symbol is used
tools: Read, Grep
model: haiku
---
Report how the given symbol is used in the given file. Be terse.
The Windows trap that cost me ten minutes
I created those files with PowerShell’s Out-File -Encoding utf8 — and Claude Code responded with “There’s no agent literally named ‘reviewer’ in this setup.” The files were right there.
The culprit: Windows PowerShell 5.1’s utf8 encoding writes a BOM (an invisible byte-order mark) at the start of the file. That puts bytes before the --- frontmatter delimiter, so the agent file fails to parse — silently. No error, the agent just doesn’t exist.
The fix, since these files are plain ASCII anyway:
"..." | Out-File -Encoding ascii .claude\agents\reviewer.md(Or save from any editor as “UTF-8 without BOM.” PowerShell 7+ doesn’t have this problem — its default UTF-8 is BOM-less.)
Watching the tree grow
With the files fixed, one prompt:
Use the reviewer subagent to review the code quality of this project.The reviewer read 14 files, thought for a couple of minutes, then started dispatching. The agent panel told the story in real time — one verifier per suspected bug, each labeled with its specific claim:
( ) main
● reviewer Review code quality of Modules folder
├ ( ) verifier Verify Plots.luau duplicate PointLight bug
├ ( ) verifier Verify PlotFind.luau substring match bug
├ ( ) verifier Verify Format.luau rounding boundary bug
└ ( ) verifier Verify ProfileStore.luau is not vendoredNavigation that isn’t obvious: ← jumps into an agent’s own session (you can watch the exact prompt it received), ↓ opens the management view. And when verifiers finish, they vanish from the panel — that’s the 30-second idle auto-hide, not a crash. They’ve already handed their verdicts up to the reviewer.
One honest note: in my run, the verifiers resolved every claim without reaching for a level-3 inspector. The depth is there when a claim genuinely needs a sub-investigation; a well-scoped pipeline often won’t use it. That’s a feature.
What came back
Only the reviewer’s final summary reached my main conversation — none of the intermediate greps, file reads, or verifier back-and-forth. Seven findings, ranked, each with a verdict and a one-line fix — including a real HIGH (a manually-created light instantly destroyed by another module, meaning wasted allocations and a visual feature that never renders) and a subtle substring-match bug that would misresolve player names.
That’s the entire point of nesting: the verbose work happened two levels down, and my context got a verdict.
The token bill (measured, not estimated)
/usage has an attribution section — here’s mine right after the run:
- reviewer (Sonnet): 43% of recent usage
- verifier (Haiku, four of them): 4% combined
Four verification agents cost a tenth of one orchestrator, because they ran on Haiku with tight prompts. This is the whole cost model in one screenshot: nesting isn’t expensive; big-model orchestrators are. Route children to model: haiku and the tree is nearly free.
(The scary “7x tokens” figure you may have seen applies to agent teams — a separate, experimental feature where each teammate is a full Claude instance — not to subagents.)
Two silent gotchas
1. The BOM trap (above) — Windows-only, maddening because it’s invisible.
2. The Agent(name1, name2) allowlist is ignored in subagent definitions. In a main-thread agent launched with claude --agent, tools: Agent(worker, researcher) restricts what can be spawned. Per the docs, inside a subagent definition the parenthesized list is silently ignored — Agent in the tools list means it can spawn anything. Need real restrictions inside the tree? Use permissions.deny.
When NOT to nest
- Parallel independent lookups → flat fan-out from main (up to 10 concurrent by default)
- One verbose operation → a single subagent for context isolation
- Anything interactive → subagents can’t use AskUserQuestion at any depth
- Nest when the task itself is recursive: review→verify-per-finding, migrate→check-per-module, research→drill-per-source
FAQ
Do I need special setup for nesting? No — any subagent whose tools include Agent (or that inherits all tools) can spawn. Depth caps at 5 automatically.
Can nested subagents use MCP tools? They inherit MCP access by the same rules as everything else; mcpServers frontmatter scopes it per-agent.
My subagents disappeared from the panel mid-run — crashed? Almost certainly the 30-second idle auto-hide after completion. Check the parent’s output; the verdicts are already in.
Does the /agents wizard still exist? Removed in v2.1.198 — create files in .claude/agents/ directly (mind the BOM on Windows).
WorkflowDen is an independent site, not affiliated with or endorsed by Anthropic, PBC. The pipeline, the bug it found, and the token numbers are all from my own machine — screenshots unedited.