Claude Code Nested Sub-Agents — Your Token Bill Is Recursive

Boris Cherny announced nested sub-agent support for Claude Code on June 9, 2026. The feature shipped the next day in v2.1.172. One quiet changelog line broke a hard constraint that had stood for two years: sub-agents can now spawn their own sub-agents, recursively, up to five levels deep. The official sub-agents documentation page still says nesting is impossible. Your token invoice will disagree.

TL;DR

• What: Claude Code v2.1.172 enables recursive sub-agent nesting — background chains capped at depth 5, foreground chains self-limiting
• Cost: Community reports flag up to 7× token usage at full nesting depth
• Control: New Agent(model:opus) permission syntax shipped same day — your primary cost brake
• Action: Stay at 2–3 levels with mixed model tiers. Do not wire 5-level chains into CI without a budget cap.

Nested Sub-Agents — What Happened

Cherny’s stated motivation is context management, not parallelism. Each nested sub-agent gets a fresh context window, so nesting lets a parent offload work before its own context fills. The leaf agent’s summary bubbles upward; everything in between — system prompts, tool definitions, intermediate reasoning — costs tokens and disappears.

Background sub-agents are hard-capped at five levels deep to prevent runaway concurrent trees. Foreground chains can spawn at any depth and are self-limiting — there is no enforced cap, but the model tends to stop nesting once the task decomposition bottoms out.

The same release introduced Tool(param:value) syntax for permission rules. This lets you match a tool’s input parameters with wildcard support. The critical example: Agent(model:opus) blocks Opus-class sub-agents from spawning further children. This is not a convenience feature. It is the cost-control mechanism, and it shipped on the same day as nesting for a reason.

Here is the permission syntax in a .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Agent(child_name)",
      "Agent(model:sonnet)"
    ],
    "deny": [
      "Agent(model:opus)"
    ]
  }
}

Write an allowlist with Agent(child_name) to block entry points for runaway processes. Deny Opus at nested layers where you do not need its reasoning capability. This is the single most important configuration decision you will make with this feature.

Why This Matters

The token multiplication math is the part Anthropic’s framing underplays. Each depth level carries its own system prompt, model context, and tool definitions. Community reports consistently cite up to 7× token usage at full five-level depth. That number is not a benchmark artifact — it is the structural consequence of duplicating context windows across every layer of the tree.

At full 5-level depth, token costs compound per layer. A task that costs $0.50 at depth 1 can cost $3.50 at depth 5. I found no evidence of a built-in per-run budget cap in the current controls — treat this as an operational gap unless you configure permissions explicitly.

The realistic safe operating range is 2–3 levels with mixed model tiers: Opus at L1 for high-level reasoning, Sonnet at L2 for execution, Haiku at L3+ for leaf tasks that need speed over depth. This is not my opinion — it is the consensus emerging from teams that have actually run these chains in production over the past week. Beyond three levels, the cost-to-insight ratio degrades fast. The intermediate layers do not contribute reasoning that survives the summarization step; they just burn tokens managing context that could have been managed with a better prompt at L1.

The intended use cases are narrow and specific: deep debugging chains where each layer investigates a different stack level, codebase impact analysis where a sub-agent traces dependency graphs while another checks test coverage, and research tasks where one agent generates hypotheses and another fact-checks them. These are legitimate. They are also the minority of how people will actually use this feature.

The hype use cases — replacing horizontal parallelism, building “agentic CI/CD pipelines,” wiring five-level trees into scheduled routines — are where the cost shock lives. Teams already running Claude Code in automated pipelines face a compounding risk. A nested agent tree triggered automatically has no human approval gate. If your L1 agent decides a task needs four sub-levels of investigation at 3 AM, your only defense is the permission rules you configured beforehand.

Before deploying nested chains in any automated context, set explicit model tier restrictions per depth level. Agent(model:opus) in your deny list prevents Opus from spawning at nested layers where Haiku would suffice. Community reports suggest the cost difference between an all-Opus tree and a tiered tree at depth 3 is roughly 4× in many observed cases.

This matters beyond Claude Code because it reveals a broader tension in agentic infrastructure. The industry is converging on recursive agent architectures — LangGraph has chain nesting, CrewAI has hierarchical crews, AutoGen has nested conversations. But none of them have shipped the cost-control primitives alongside the nesting primitives. Anthropic did, which is either admirable engineering discipline or a tacit admission that the feature is dangerous without guardrails. Probably both.

The comparison to existing orchestration frameworks is instructive. LangGraph gives you explicit graph control over every node transition. CrewAI lets you define crew hierarchies with role assignments. Both require you to build the nesting logic yourself, which means you see the complexity and cost surface before you deploy. Claude Code’s approach is different: the model decides when to nest. That is more flexible and more dangerous. You are delegating cost decisions to an agent that has no concept of your budget.

The Take

I keep coming back to Cherny’s framing: “context management, not parallelism.” He is being precise, and precision matters here because the feature will be misused by everyone who reads “nested agents” and thinks “distributed computing.” It is not. It is a way to give a sub-agent a clean context window when its parent’s context is getting crowded. That is a real problem with a real solution, and at 2–3 levels with mixed model tiers, the cost is manageable and the value is genuine.

But the 5-level cap exists because Anthropic tested what happens without one, and the answer was runaway token trees. The permission syntax shipped the same day because the feature is incomplete without it. If you adopt nested sub-agents without configuring Agent(model:opus) deny rules and without setting explicit allowlists for child agents, you are handing your billing API key to a recursive function with no base case.

My recommendation: use nested sub-agents for deep debugging and impact analysis tasks where each layer genuinely operates on a different abstraction level. Stay at 2–3 levels. Tier your models aggressively. And do not put this in a scheduled pipeline until you have per-run budget controls in place — based on the permission syntax groundwork Anthropic shipped alongside this feature, I expect built-in budget caps within the next two releases.

The feature is good engineering. The default configuration is a cost trap. Act accordingly.