Subagents Can Nest Three Deep Now: How to Structure Multi-Layer Agent Hierarchies in Claude Code

Claude Code v2.1.219 reinstated nested subagent spawning at depth 3 by default — here's the orchestrator → coordinator → worker pattern that makes it useful.

What changed

In v2.1.217 (July 21), Anthropic capped concurrent subagents at 20 and disabled nesting entirely. In v2.1.219 (July 24, shipping with Opus 5), nesting came back at depth 3:

• A top-level agent can spawn depth-1 subagents (coordinators)
• Each coordinator can spawn depth-2 subagents (workers)
• Workers cannot spawn further — depth 3 is the hard ceiling

To revert to the previous flat behavior: export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1

The orchestrator → coordinator → worker pattern

Depth-3 nesting maps cleanly to three responsibilities:

Depth 0 (orchestrator) — the top-level session or prompt. Owns the plan; assembles the final result; delegates everything it can.

Depth 1 (coordinator) — spawns worker agents and synthesizes their results. One coordinator per domain: test-coordinator, migration-coordinator, security-coordinator.

Depth 2 (worker) — single-responsibility, short-lived. Runs one test suite, migrates one file, checks one module. This is where the actual work happens.

Example CLAUDE.md workflow directive:

When asked to run the full test suite, spawn a test-coordinator agent.
The coordinator should spawn one worker per test category (unit, integration, e2e)
and collect their pass/fail summaries before reporting back.

What to watch for

Token budget: each nested layer inherits a fraction of the parent's context budget. Pass explicit budget hints in the coordinator's initial prompt so workers don't overrun.

Fan-out risk: depth-3 nesting with wide fan-out at each level can still hit the 20-concurrent subagent cap. Have coordinators stagger worker spawns or batch them.

Depth is not the goal. Flat (depth-1) agents are faster to debug and reason about. Only add a coordinator layer when the coordinator genuinely needs to synthesize cross-worker results before the orchestrator can proceed. Two levels is almost always enough; three is the exception.

Sources: Claude Code v2.1.219 Release — GitHub · Opus 5 is the default now, and subagents can nest three deep (mager.co) · Claude Code subagent depth limits and budget caps (digitalapplied.com)