If you build with Claude Code, one line in the 2.1.219 changelog changes how you structure agent work: "Subagents can now spawn nested subagents up to depth 3 by default (was 1)." That is the difference between a flat team of workers you orchestrate by hand and a real hierarchy — a planner that spawns workers that spawn verifiers — running inside a single invocation. Here's what shipped, and how to use the depth without letting it run away with your token bill.
The one number that matters: depth 1 → 3#
Before this release, a subagent was a leaf. It could do work and return, but it could not delegate further, so any multi-level pattern — decompose a task, fan out across the pieces, verify each result — had to be assembled in your own code or driven turn-by-turn from the top agent.
Now the top-level agent can delegate to a worker, and that worker can delegate again, up to three levels deep by default. The canonical shape this unlocks:
- Level 1 — orchestrator: reads the task, splits it into independent units.
- Level 2 — workers: each owns one unit and does the actual edits or research.
- Level 3 — verifiers: a worker spawns a skeptic to check its own output before returning.
That third level is the valuable one. A worker that can spawn its own verifier turns "trust the subagent" into "the subagent proves its work," which is exactly the pattern that made adversarial verification worth the tokens in the first place.
Depth is a budget, not a free win#
Every level of nesting multiplies two costs: tokens (each child is a fresh context) and traceability (a failure three levels down is three hops from the message you see). So treat the default of 3 as a ceiling to spend deliberately, not a target.
Turn nesting off for anything shallow and mechanical:
export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1Keep depth 2–3 for tasks that genuinely decompose — a migration across many files, a review that fans out by dimension, research that splits by source. And cap the fan-out itself with the new workflowSizeGuideline settings key, which lets the advisory Dynamic workflow size guideline be set from any settings file, so a dynamic workflow doesn't quietly grow a dozen agents where three would do. The rule of thumb: prefer breadth you can bound over depth you can't trace. Concurrent children at depth 2 are easier to reason about than a five-hop chain.
The setting that makes unattended nesting safe#
A nested run is only useful if you can leave it running, and that's what sandbox.network.strictAllowlist is for. It denies any host not on your allowlist for sandboxed commands — without prompting. On an attended session, an out-of-allowlist request pauses for your approval; in a deep, unattended fan-out, that pause would stall the whole tree behind one worker waiting on a confirmation that never comes. strictAllowlist replaces the prompt with a hard deny, so the network boundary is fixed before the run starts and no child can hang the loop asking to reach a new host.
Pair it with an explicit allowlist of exactly the hosts your task needs (your package registry, your API, your git remote) and a nested run becomes something you can start and walk away from.
Two additions for SDK drivers#
If you drive Claude Code headlessly:
DirectoryAddedhook — fires after/add-diror the SDKregister_repo_rootcontrol request registers a new working directory mid-session. Wire it to re-run whatever needs to know about a new root: re-index, re-scope a linter, refresh a file map. Before this, a directory added mid-session was invisible to your tooling.mcp_server_errorsin the headless stream-json init event — lists any--mcp-configentries skipped by config validation. A malformed MCP server config used to drop out silently; now the init event tells you which servers didn't load, so a broken tool connection surfaces at startup instead of as a mysterious missing capability later.
And the default model moved#
Quietly bundled in the same release: claude-opus-5 is now the default Opus model, with a 1M-token context window. /fast now applies to Opus 5 and Opus 4.8 at $10/$50 per million tokens — twice the $5/$25 base rate — and Opus 4.7 was dropped from fast mode. For orchestration that's latency-sensitive (a human waiting on the loop), fast mode earns its premium; for long background fan-outs where nobody's watching the clock, run the base tier and spend the savings on more verifiers.
Do this before your next multi-agent run: decide the depth your task actually needs and cap it, set an explicit network allowlist with strictAllowlist on, and lower workflowSizeGuideline until a fan-out spawns only as many agents as the work warrants. Depth 3 is a capability, not an instruction — the teams that get value from it are the ones that treat each level as a line item.
Related: we tracked the earlier July changes in Claude Code now stacks skills and pauses by default, and compared runaway-subagent controls across tools in who actually stops a runaway subagent.
