Anthropic Lifts Sub-Agent Nesting Restriction in Claude Code v2.1.172, Enabling Five-Level Hierarchies
Key Takeaways
- ▸Sub-agents can now spawn up to five levels of nested sub-agents, with the five-level cap enforced server-side and immutable
- ▸Primary use case is context isolation: leaf agents handle noisy, token-heavy work (log reads, grep, test generation) and return clean summaries to parent agents
- ▸Token consumption compounds at approximately 7× per branch per level; unchecked nesting has caused unexpected billing escalations ($47k+ observed)
Summary
Anthropic released Claude Code v2.1.172 on June 10, quietly lifting a two-year restriction that prevented sub-agents from spawning their own sub-agents. The update enables nested agent hierarchies up to five levels deep, with a hard server-side cap enforced at that depth. According to Boris Cherny, who leads Claude Code at Anthropic, the feature is designed to manage context more efficiently by isolating token-heavy tasks—such as log analysis—in separate context frames, allowing parent agents to receive clean summaries rather than raw output floods.
The practical benefit centers on context isolation: rather than a parent agent viewing thousands of raw log tokens that consume additional tokens for re-grounding, a nested Haiku agent can perform the log work in isolation and return only the summary. The mental model mirrors call-stack recursion, where each of the five possible levels carries its own system prompt, model selection, and 200K token context window. Best practice chains exist at depth 2–3, with depth 5 as the absolute ceiling.
However, the feature carries significant cost implications. Token consumption multiplies roughly 7× per branch per level—a figure derived from observed overhead in agent orchestration and context initialization. One developer reported consuming 887,000 tokens per minute before noticing; a financial services team running 23 agents on a 'simple' code quality project received a $47,000 invoice in three days. Anthropic recommends implementing per-session spend limits before deploying nested agents in production, and suggests model tiering (Opus for orchestration, Sonnet for mid-level work, Haiku for leaf tasks) to optimize costs to roughly $0.98 per session versus $2.02 for uniform Opus.
- Configuration requires explicit allowlisting via the Agent() field in sub-agent definitions; model tiering (Opus → Sonnet → Haiku) is critical for cost management
- Production deployments must implement per-session spend limits; most useful chains operate at depth 2–3, not the five-level maximum
