Claude Code Just Added Nested Sub-Agents (5 Levels Deep + Safe Mode)

Claude Code Nested Sub-Agents: What 5-Level Deep Recursion Actually Means for Builders

On June 16, 2026, Anthropic shipped a Claude Code update that changes the fundamental agent architecture model available to builders. Sub-agents can now spawn their own sub-agents, up to five levels deep, with a full tree visualisation in the panel. This is not just a depth increase — it is a shift from flat parallel agents to genuinely hierarchical agent orchestration. Combined with Safe Mode, this update gives enterprise builders the recursive decomposition capability they have been waiting for.

How Nested Sub-Agents Work

Previously, Claude Code could spawn sub-agents from an orchestrator — but those sub-agents could not themselves delegate further. You had one level of hierarchy: orchestrator spawns workers, workers execute tasks, results bubble back up. This works for many workloads but hits limits on complex, deeply decomposable problems.

With the new update, the model is genuinely recursive:

• Level 1: Root orchestrator receives the task
• Level 2: Orchestrator decomposes into domain sub-agents (e.g. backend, frontend, testing)
• Level 3: Each domain sub-agent further decomposes into specific task agents
• Level 4: Task agents spawn specialist agents for narrow execution (e.g. a security audit agent, a performance profiling agent)
• Level 5: Specialist agents spawn tool-execution agents for atomic operations

The tree panel shows the full hierarchy live — you can see which agents are active, what they are working on, and where results are flowing. This visibility is essential for debugging recursive agent behaviour.

Why the 5-Level Limit Exists

Anthropic capped recursion at five levels deliberately. Beyond five levels, two problems compound: cost explodes because token consumption multiplies at every level, and observability collapses because the tree becomes too complex for a human to meaningfully review. Five levels is a pragmatic ceiling that covers nearly every realistic enterprise use case while keeping both cost and debuggability manageable.

When Nested Agents Beat Flat Parallel Agents

Not every problem benefits from deep nesting. Flat parallel agents remain better for:

• Embarrassingly parallel tasks with no interdependency (e.g. processing 1,000 independent documents)
• Tasks where all sub-tasks have the same type and require the same tool set

Nested agents win when:

• The problem has natural hierarchical decomposition (e.g. migrate a monolith — separate agents for database, API layer, frontend, infrastructure)
• Sub-tasks require further specialisation that the parent agent should not handle itself
• You want different permission levels at different depths — outer agents with broad permissions, inner agents with tightly scoped tool access

Safe Mode: The Feature That Makes This Production-Ready

Safe Mode is the governance layer that makes nested agents deployable in enterprise contexts. Enable it with the --safe-mode flag or the CLAUDE_CODE_SAFE_MODE environment variable.

In Safe Mode, any agent at any depth that is about to take an irreversible action — deleting files, pushing to production, making payments, sending external communications — must receive explicit approval before proceeding. The approval request surfaces at the top of the tree with full context of which agent is requesting it and why.

This prevents the failure mode that makes agentic systems dangerous: a deeply nested agent taking a destructive action that was never intended by the original instruction. For enterprise deployments, Safe Mode is not optional — it is the minimum viable governance posture.

3 Things to Do This Week

• Update Claude Code immediately: Run npm update -g @anthropic-ai/claude-code to get the nested sub-agent update. Verify the version in /doctor output.
• Identify one hierarchical problem in your backlog: Look for a task that you have been breaking into stages manually because it was too complex for a single agent pass. Design the agent tree on paper first, then implement.
• Always enable Safe Mode for new agent workflows: Do not disable it until you have run the workflow in a non-production environment at least five times and verified every irreversible action point is behaving as expected.

Key Takeaways

• Claude Code now supports nested sub-agents up to 5 levels deep — enabling genuine hierarchical agent orchestration, not just flat parallel spawning
• The tree panel provides live visibility into the full agent hierarchy, which is essential for debugging recursive behaviour
• The 5-level cap is deliberate — beyond that, cost and observability both degrade to the point of impracticality
• Safe Mode prevents irreversible actions at any depth without explicit approval — this is the minimum governance requirement for enterprise deployments
• Nested agents excel at hierarchically decomposable problems; flat parallel agents remain better for embarrassingly parallel, homogeneous tasks