Starting with Claude Code v2.1.172 (June 10, 2026), a subagent can once again spawn subagents of its own. In a structure where a parent creates children and children create grandchildren, you can slice a big task into fine pieces. The depth is fixed at a maximum of five levels, and an agent that reaches level five can no longer create anything beneath it.
Until now, Claude Code’s subagents were, in practice, all about “main conversation → one layer of subagent.” The main thread handed off work, the subagent worked in its own context window and returned only a summary — a one-level delegation. But in June 2026, that changed so a subagent can spawn subagents of its own again. A tree grows: a child under a parent, a grandchild under the child.
This blog has already covered ‘subagent basics’ and multi-agent-based ‘agent orchestration.’ This post focuses only on the layer on top of that — so a developer can follow along with the Anthropic official docs open alongside — namely: why hierarchy is needed, how it works, and where the cost blows up.
Why hierarchical subagents are needed
A single subagent receives the task whole. If that task contains several independent subtasks, it’s more efficient for the subagent to split them again into lower-level agents and parallelize or divide the work. That’s because the intermediate output doesn’t leak into the main conversation — only the top-level summary comes back to the user.
The core is multi-tiered context isolation. The official docs say to use hierarchy “when the delegated task itself splits again into parallel subtasks.” For example, a code-review agent spins up one verification subagent per problem it finds. Each verification agent’s verbose logs are consumed only inside the review agent, and only the review agent’s tidied conclusion rises to the main thread.
I first used this structure seriously while refactoring one legacy pipeline module in-house. I spun up a single “refactoring lead” agent from the main thread, and beneath it split the work into three child agents: dependency analysis, test collection, and style cleanup. In the old days all three kinds of output would have piled up in my main window and quickly gotten messy; this time I received just one lump of summary from the lead agent, and it was far cleaner.
How it works — parent → child → grandchild
The mechanism is surprisingly simple. A subagent that has the Agent tool can spawn subagents again. To borrow the official docs’ phrasing, if Agent is in a subagent definition’s tools list, that agent can spin up nested subagents.
There’s one point that’s easy to get confused about here. In the main thread (when launched with claude --agent), you can restrict the spawnable types to a whitelist inside the parentheses, like Agent(worker, researcher). But inside a subagent definition, this list of types in the parentheses is ignored. That is, from a subagent’s standpoint, only a binary rule applies: “if Agent is present, nested spawning is possible; if not, it isn’t.” To keep a particular subagent from creating anything beneath it, remove Agent from its definition or put it in disallowedTools.
Each layer starts in a completely new context window unrelated to the parent. A child agent can’t see the parent’s conversation history and works only with the delegation message, system prompt, and environment info the parent handed over (give it isolation: worktree and even a copy of the repository is separated). When the work finishes, the result is returned only to the parent, and traveling back up the tree, only the top-level summary reaches the user.
Depth limit: up to five levels, a fixed value
The most important safeguard is the depth limit. According to the official docs, depth is counted as the number of subagent levels below the main conversation, regardless of whether they run in the foreground or background. Quoting the docs verbatim — “A subagent at depth five doesn’t receive the Agent tool and can’t spawn further. The limit is fixed and not configurable.” In other words, an agent that reaches level five doesn’t receive the Agent tool at all, so it can no longer create anything below it, and this limit can’t be changed via settings.
Also, as of v2.1.187 (June 23, 2026), a background subagent’s depth is fixed when it is first created. Even if you later resume that agent from a shallower position, it can’t create additional levels beyond its already-set depth. It reads as a device to prevent infinitely branching agent chains.
Three hierarchy patterns used in practice
Combining the patterns the docs present with the forms I’ve actually run, here’s the summary.
| Pattern | Structure | When it fits |
|---|---|---|
| Fan-out | 1 lead → N independent children | When a big task splits into chunks that don’t depend on each other |
| Verification-paired | Working agent → a verification child per finding | When you need item-by-item cross-checking, as in reviews and audits |
| Chain | Stage 1 result → stage 2 input → … | A workflow whose stages connect in order |
- Fan-out shines most when investigation paths don’t tangle with each other — like “investigate the auth, DB, and API modules in parallel, each as a separate subagent.”
- Verification-paired is a structure where a review agent finds problems and spins up a verification grandchild agent per problem. The key gain is that the verification logs stay trapped inside the review agent.
- Chain is a serial flow that passes one agent’s result to the next. That said, for serial work it’s often simpler to delegate sequentially from the main thread than to go for deep nesting.
In my experience, cutting off at two or three levels and spreading wide was easier to manage than digging deep into hierarchy. The deeper the tree grows, the greater the burden of tracking what’s running at which layer. Claude Code shows the whole tree in a panel below the prompt input (each row displays the number of children in a (+N) form), but even so, there’s a limit to what a person can follow in their head.
Cost and context explosion — the part to watch most
The biggest trap of hierarchy is that results accumulate upward. The official docs warn about it too — run many subagents that each return detailed results, and the main conversation’s context can be consumed considerably. Add nesting and this effect multiplies per layer. If five children each create five grandchildren, the call count balloons fast by simple arithmetic alone.
An embarrassing confession: when I first tried fan-out, I didn’t explicitly state the constraint “return a summary only” to each lower agent. As a result, long output flowed straight back up into the lead agent, and tokens drained faster than expected. After that I formed the habit of always nailing down “return only the key conclusions and changes” in the delegation prompt.
Here are the practical rules for protecting cost and context.
- Specify a narrow return format for lower agents (summary, conclusion, file paths only, and so on).
- Instead of an expensive model, route a light, fast model to lower agents used for exploration and search. The official docs list one of the subagents’ advantages as “controlling cost with a faster, cheaper model.”
- Keep depth to only what’s needed. Just because five levels are possible is no reason to fill five.
- Check the tree panel often to track which layer is running with your own eyes.
Wrapping up
Hierarchical subagents can be summed up in one sentence: “Rather than one agent embracing a big task whole, it delegates to independent children and isolates the intermediate noise.” It was introduced in v2.1.172, the depth is fixed at up to five levels, and the presence or absence of the Agent tool decides whether nested spawning is possible. As powerful as it is, you have to use it mindful of the context and cost explosion from accumulating results. Test small, narrow the returns, and follow the tree with your own eyes — that’s the conclusion I reached after several rounds of trial and error.
The features and versions in this post may change with updates and are current as of June 2026.
Sources: Claude Code official docs — Subagents, Claude Code official changelog