How to delegate a large task in Claude Code using nested subagents

What changed in Claude Code v2.1.172?#

If you've read anything about AI agents in Claude Code over the past few months, you've come across the same phrase. It's in the official documentation, in my guide about subagents, and in every competitor's analysis. It goes like this: “a subagent cannot spawn another subagent.” As of June 11, 2026, that line is still in three different places on code.claude.com/docs/en/sub-agents. Anthropic simply hasn't updated it yet.

On June 10 at 20:44 UTC, Claude Code v2.1.172 appeared on GitHub Releases. The main changelog item was one line:

This same release also fixed a bug that could only happen with nesting: a background subagent would remain highlighted as active in the agents panel after the nested subagent it had launched had already been stopped.

This is a rare case where the official docs still contradict the shipped build. Next I'll explain how nesting differs from parallel subagents, what “depth 5” means, and the three scenarios where it's genuinely useful today.

How are nested subagents different from parallel and sequential ones?#

I spent a long time trying these three approaches by hand, and here's how I think of them: delegation has three dimensions. Width, length, and depth. Each solves a different problem.

Width—parallel subagents. The main chat launches N independent subagents on the same level. Each gets a narrow task, works in its own isolated window, and returns only the result. Width solves speed: 5 subagents working in parallel finish in the time it takes one to do the same work sequentially. This is the model I covered in my guide about parallel subagents using worktrees.

Length—a chain of subagents. A works, hands the result to B, B works, hands it to C. Each sees the input from the previous one. Length establishes order: B can't start until it gets data from A. A classic example: first a research subagent gathers sources, then an editing subagent writes an article based on those sources, and then a fact-checking subagent checks the article. It's a flat sequence; the main chat holds the whole storyline.

Depth—nested subagents. A launches B, B launches C, C launches D. Each child works inside its parent, in its own isolated window, and returns only the result to its parent. The main chat sees none of what happens in the children, grandchildren, and great-grandchildren. This is what's new in v2.1.172.

The main confusion is that people think depth 5 means “you can launch 5 subagents simultaneously.” That's not so. Depth is a vertical level in the tree, not the number of simultaneous children. There can be one subagent or a hundred at each level. Depth 5 means the delegation chain can go down 5 steps: main chat → grandchild-1 → grandchild-2 → grandchild-3 → grandchild-4 → grandchild-5. And there can be branching at every level.

Version 2.1.172 removed the rule that a subagent couldn't spawn another subagent.

If you're after speed, you need width. If you have a strict execution order, you need length. Depth is useful in exactly one case: when one of your tasks contains a noisy subtask (15 web requests, log traversal, reading a dozen files). And you don't want that noise flooding your main window.

What does “depth 5 levels” mean in practice?#

Here's an important point of honesty. I spent half a day on documentation and community analyses to find that Anthropic hasn't given a precise definition. Here's what you need to know.

It's a cap, not a setting.

The limit is built into the server side. Reverse engineering of client v2.1.172 found no MAX_DEPTH constant. That means the check happens somewhere in the Anthropic API, not locally on your machine. You can't set --max-depth 7 to make the tree deeper. Nor can you set --max-depth 2 to establish a lower, safer cap. The only control you have is the Agent(agent_type) allowlist in the frontmatter—but it limits the types of child agents, not the depth.

Anthropic hasn't precisely defined “5.” Official sources don't specify whether depth=5 means five levels below the root or five agents total, including the root.

I use this convention in my experiments: the main chat is level 0, its direct children are level 1, and so on up to level 5. But this isn't recorded in the public documentation.

The limit is already enabled, with no flags. You don't need to activate anything. After updating Claude Code to v2.1.172, you can add Agent to a child agent's tools, and it will launch another subagent. The key is that the parent agent must allow it (tools: Agent(...)).

Where does your delegation happen today: width, length, or depth?#

Go through your last 5 prompts. How often have you done this: a task starts, Claude begins grepping files, makes 10 web requests, dumps a whole wall of logs into the context—and 20 minutes later you realize the window is full. The final answer is already running on a meager token budget because 70 percent of the context was consumed by intermediate dumps.

That's a scenario where you need depth. Not parallelism, not a chain—depth. The main chat should delegate “research” to one subagent, which then launches its own children from within for specific web searches, file reads, and greps. The children return only distilled judgments. A grandchild tells its parent, “found it, confirmed,” or “didn't find it, reason X.” The parent assembles that into a single summary and returns it to you. The main chat stays clean.

Before June 9, I emulated this by hand. I opened a second instance of Claude Code, copied the prompt “research this,” ran it, then manually transferred the result back to the main window. I described this setup in detail in my guide about delegating coding to many AI agents. With v2.1.172, you can describe it directly in the orchestrator's system prompt—Claude will build the tree itself.

In which 3 scenarios are nested subagents actually useful?#

Scenario 1. Deep research with fact-checking

Suppose you're gathering material for an article or a sales proposal. First you need to pull 5–10 claims from public sources, then verify each one—find the original source, make sure the quote is exact, and calculate the actual figures.

Before v2.1.172, you had two options. Either you did it all with one subagent, which slogged through 30 web requests, stuffing everything into its context. Or you split it up manually: one prompt to extract the claims, then a loop over the claims, launching a separate subagent for each one. The main chat would fill up with walls of intermediate lists.

In the recipe below, the main chat delegates to research-orchestrator (level 1). The orchestrator extracts claims itself, sends each to fact-verifier (level 2), and each verifier delegates focused searches to web-deep-search (level 3). The main chat receives only an array of verified claims with sources. Everything else stays in child windows and never enters your context.

Scenario 2. Analyzing a large repository

You've been handed a project with 200 files. You need to understand the architecture, find the main modules, and assess technical debt. Run Glob plus a dozen Read calls by hand and you'll fill the window in 10 minutes.

Depth solves it this way: the main chat launches an “architect” subagent. The architect spawns three children internally—one inspects the directory structure (runs Glob and summarizes), the second reads 5 key configuration files, and the third greps for the main patterns. Each returns a concise summary to the architect. The architect assembles the picture and gives the main chat a final report half a screen long. You get a map of the project without flooding the context with a wall of cat output from all the files.

Scenario 3. Analyzing end-to-end dependencies

You're changing a database schema, an API contract, or a shared configuration file. You need to understand where the effects will show up. This task kills context fastest because there are many dependencies, and each one needs to be checked in the source.

With depth, the main chat launches an “impact-analyzer” (level 1). It launches one dependency-tracer for each affected file (level 2). Each tracer launches a consumer-finder internally (level 3), which greps the codebase for consumers of that dependency. Each then returns just the gist: “these three places will break.” The main chat assembles a table of “affected files → impact” without knowing about the grep results.

How to set up nested subagents in 10 minutes#

Step 1. Make sure you're on v2.1.172 or higher.

claude --version

If it's lower, update. The release's main feature is one line in the changelog: “Subagents can now spawn their own subagents, up to 5 levels deep” (full text).

Step 2. Create a parent agent that can spawn children.

File .claude/agents/research-orchestrator.md:

---
name: research-orchestrator
description: Delegates research with a deep fact-check
tools: Agent(fact-verifier), Read, WebFetch
model: opus
---

You are a research orchestrator. When you get a topic:
1. Read the supplied material or fetch the supplied public source URLs.
   Extract up to 5 concrete claims yourself. For each, record the claim text,
   its source URL or file, and the exact supporting passage.
   If no source material was supplied, ask for it before delegating.
2. For each claim call fact-verifier - it spawns
   its own child subagents for web search and cross-checking.
3. fact-verifier returns only the final verdicts to you -
   do not load intermediate dumps into your context.

Final report - only an array { claim, sources[], confidence }.

The tools line grants only the fact-verifier child type. Claim extraction is the orchestrator’s own first step, so no undefined claim-extractor file is needed. A type allowlist constrains which child can be called; it does not cap how many times that type is launched. Keep the recipe bounded to at most five extracted claims.

Step 3. Create a child agent that can spawn grandchildren itself.

File .claude/agents/fact-verifier.md:

---
name: fact-verifier
description: Checks a claim through child web searches
tools: Agent(web-deep-search), Read
model: sonnet
---

You are a fact-checker. When you get a claim:
1. Write 2-3 search queries.
2. For each one run web-deep-search - it will do
   WebSearch and WebFetch itself and return verified snippets.
3. Combine them into one verdict: { claim, sources[], confidence }.

See the key part? tools again says Agent(web-deep-search). That means the fact-verifier (level 2 in our tree) can launch another subagent itself (level 3). Previously, this line had no effect—the docs still contain the phrase:

With v2.1.172, that line is outdated. The syntax is the same, but now it works at any depth in the tree.

Step 4. Create a grandchild.

File .claude/agents/web-deep-search.md:

---
name: web-deep-search
description: Runs a web search and returns snippets
tools: WebSearch, WebFetch
model: haiku
---

You received a search query. Run WebSearch, pick the top 3
relevant URLs, use WebFetch to pull verbatim confirmations
of the claim. Return an array { url, snippet, supports_claim: yes|no }.

The grandchild doesn't have Agent in tools, so it doesn't spawn further down the tree.

Step 5. Run the orchestrator.

claude --agent research-orchestrator

Then supply the source text or public source URLs in the chat: “Extract and verify up to 5 concrete claims from these sources; return claims, sources, and confidence.” With --agent research-orchestrator, the session itself is the orchestrator; its verifier and search children add two delegated levels below it. If an ordinary main session delegates to this orchestrator instead, there are three delegated levels below that main session.

Which 5 anti-patterns waste tokens and destroy observability?#

Anti-pattern 1. The task fits in one window.

If one subagent can handle it without noise, don't add levels: nesting adds cost and latency for nothing.

Anti-pattern 2. You're after speed instead of isolation.

If you want speed, you need parallelism, not depth. Launch 5 subagents side by side at the same level instead of building a chain. Depth exists to move noisy preparatory work into a child window, not to speed things up.

Anti-pattern 3. The work is inherently shallow.

“Find this file and show it to me” is a two-step request; it doesn't need a three-level hierarchy. Nesting is worthwhile when a task contains a noisy subtask. If there's no noise, don't add subagents.

Anti-pattern 4. Vague prompts at the first level.

This is the most dangerous scenario. If you give the level 1 orchestrator a vague prompt, the vagueness multiplies. One vague level 1 prompt becomes 4 vague prompts at level 2 and 16 at level 3. By the time the grandchildren start working, they don't even know what they're looking for.

Anti-pattern 5. Geometric cost growth.

The main economic argument: nesting multiplies token use, and the multiplication compounds with depth.

A rough calculator: a depth-3 chain with a fan-out of 3 at each level means 27 subagents. That's at least 27 times more tokens than a simple request. On Claude's Pro plan, that calculation burns through the daily limit in a couple of hours. If you're on a Max plan, you'll burn through a week's allowance in a day.

Bonus anti-pattern (my experience): “50 agents doing pointless work.”

When I look at other people's projects, I often see this: “I have 50 agents working.” I ask, what are they doing? And those 50 agents are doing pointless work. They generate piles of unnecessary output, tons of raw summaries, duplicates, and walls of logs. Each does something “generally useful,” and the result is a context drowning and a token bill like that of a small company. Depth 5 doesn't solve this problem—it makes it worse. If it's already unclear at level 1 who's doing what, depth 5 means five levels of confusion.

Before launching any subagent, test it by answering 4 questions in half a minute:

• What exactly does it do (in one sentence)?
• Which files does it touch?
• What does it return to its parent?
• Who checks it?

If you can't answer in 30 seconds, this subagent shouldn't exist. I explained this rule separately in my guide about parallel subagents.

Why does nesting without context engineering mean 5 levels of hallucinations?#

This is where people often ask: “I updated Claude Code, added Agent to tools, the tree is building—but the final answer is still off. Why?”

The answer is simple. Every subagent in Claude Code starts from scratch. From the official documentation:

At level 1, this is manageable: the orchestrator passes a short task description to its child. But at level 3, the grandchild gets a delegation message from its parent, which also had only a delegation message. Each passed along a little. At level 5, you have a subagent whose window contains the phrase “check claim X,” and nothing else. It doesn't know which project it's working in, what task it's solving, or what to focus on.

Without CLAUDE.md, a level-five grandchild is like an employee showing up at the office for the first time in their life without any orientation. It will do something because it got a task. But it won't be what the project needs.

That's why the setup is essential. Depth 5 without a properly configured CLAUDE.md, business/, and skills pipeline is a casino. With them, it's a tool.

What else changed in v2.1.172 besides nesting?#

Open the full v2.1.172 changelog and you'll see the whole release is about subagents.

Fix 1. A background subagent no longer remains “stuck” as active in the agents panel after the nested subagent it launched is stopped. This bug can occur only with nesting.

Fix 2. availableModels restrictions now apply to subagents too. Previously, if you limited which models the team could use (for example, forbidding opus to save money), subagents could bypass the rule with an override in their own config. With v2.1.172, the rule applies everywhere.

Fix 3. The up arrow in prompt history now shows prompts from the subagent's current tab, not the main agent's. An observability polish.

Fix 4. Idle CPU use is reduced: the /goal indicator no longer redraws the terminal at 5 Hz while idle, and the UI redraws less often while parallel subagents are working.

I'll point out that all four fixes concern subagents. That means Anthropic released the whole nesting infrastructure stack, not just one line in the changelog. Nesting had already been in use inside Anthropic for some time before publication.

Checklist: when nesting helps and when it hurts#

Use nesting if:

• The task contains a subtask with a large volume of web requests, greps, or file reads.
• It's acceptable to lose that subtask (if the grandchild returns “found nothing,” the orchestrator can continue).
• You don't need intermediate results in the main window.
• You have a CLAUDE.md and assembled project context that the subagent can rely on.
• You can clearly describe what each level will return (input, output, format).
• You're on a Max plan or have a buffer for ×27 tokens.

Don't use nesting if:

• One subagent can solve the task without noise.
• You need intermediate results in the main window (that means you want parallelism).
• The project has no CLAUDE.md or only sparse business context.
• The level 1 prompts are vague (the vagueness will multiply exponentially down the tree).
• You need speed—parallelism is faster than depth for a comparable result.
• You're on the Pro plan and work all day—you'll burn through the limit in a couple of hours.

More materials are available on Ailoot.