Subagents that spawn subagents, Claude Code's 5-level rule

Until recently a subagent setup was flat. A coordinator started workers, and that was it. A worker could not spawn another subagent itself. Since the changelog entry from early June that is different, subagents may now start their own subagents, up to five levels deep. At first that sounds like more power. In practice it is mostly a new way to blow up your cost and context if you do it without a plan. I tested this for a week at various depths and landed on a fairly conservative rule. This playbook shows it to you.

Prerequisite: you have done "Your first subagent in 30 minutes" and know the CEO worker pattern from level 5 lesson 2. If you already run a team of several subagents, "Structuring a subagent team" is a good foundation too.

1. What changed

There used to be a hard rule: only the main session starts subagents. A subagent was a dead-end worker, it does its job and returns the result. Now every subagent can start more of them itself, and that goes on recursively up to level five. Level zero is your main session, level one the first worker, and so on to level five, then the limit is reached and another spawn is refused.

Important to understand: five levels is a ceiling, not a target. Most good setups stay at level one or two. Depth is a tool for exactly one case, and we will look at that in a moment.

2. Why depth is rarely the answer

Every level multiplies. If your coordinator starts three workers and each of those workers starts three again, at level two you are already at nine parallel subagents. One level deeper it is 27. Each of them has its own context, its own tokens, its own latency. I had a test where I naively opened three by three by three, and a simple research job suddenly cost eleven dollars instead of the expected two. Not because the work was bigger, but because 27 subagents each rebuilt half the context again.

My rule of thumb: every additional level only justifies itself when the task at that level genuinely breaks into independent subtasks that can run in parallel. Otherwise you are building an expensive hierarchy for something a single worker would have handled sequentially.

3. The one place where depth really helps

The case that justifies depth is fan-out in research. Imagine you want to analyse five competitors, and per competitor there are four sub-questions. Here a second level makes sense: level one is one researcher per competitor, level two one worker per sub-question. Every worker on level two works with a narrow, clearly bounded job and does not need the large context of the levels above at all.

That works because the subtasks are genuinely independent. Competitor A does not depend on competitor B, sub-question one not on sub-question two. Exactly that independence is the condition. If your subtasks build on each other, they do not belong in parallel subagents but in a sequential plan.

4. Set a depth budget in advance

Before you start anything, write a hard limit into your CLAUDE.md or into the subagent prompt. In my coordinator prompt there is a sentence like "You may open at most level two, so you yourself start workers, and those workers may go exactly one level deeper if the task breaks into independent parts. No deeper."

That matters more than it sounds. Without that limit a coordinator tends to start another subagent at every uncertainty instead of thinking for itself. The system's five-level limit only catches you at the absolute edge, by which point you have long since burned too much money. Set your own limit well below it.

5. Understand permission inheritance

A deep subagent does not automatically inherit the same rights as its parent, and that is a good thing. You define per subagent definition which tools and which permission scopes are allowed. A researcher on level two should typically only be allowed to read and research, never to write files.

My pattern: the deeper the level, the tighter the rights. The coordinator on level one may create drafts and merge results. The workers on level two may only read and report back. That way a deep subagent can at worst research nonsense, but cannot touch your files. If you do not have permission profiles cleanly under control yet, work through the recipe on settings and permissions first.

6. Context isolation per level

Every subagent has its own context, it does not automatically see what the parent saw. You pass it exactly what it needs in the spawn job. That is the real lever against the cost explosion from step 2.

Concretely that means: do not give a worker on level two the whole research state, only the one sub-question plus the two or three facts it needs as a starting point. The narrower the job, the cheaper the subagent and the sharper the result. A worker that starts with three sentences of context and returns a clear report is exactly what you want.

7. Measure cost with /usage

Since the June update, /usage in VS Code shows a breakdown per subagent, skill, plugin and MCP server over the last 24 hours or seven days. Use it. After a deep run you look at where the tokens actually went.

In my 27-subagent disaster from step 2 exactly that breakdown showed that it was not the research itself that was expensive, but the repeated context build-up at the deepest level. Without the breakdown I would have blamed the model and optimised at the wrong end. Hit /usage after every run with more than one level.

8. Timeout and abort strategy

Deep setups have a failure pattern flat ones do not: a subagent on level three hangs, and the levels above wait. At the top you only see "Working" and do not know why. So decide in advance how long a worker may run at most, and what the parent does when a child does not come back.

My pattern: the coordinator does not wait forever. If a worker delivers nothing after a reasonable window, the coordinator carries on without that partial result and notes the gap in the report. Better a report with four out of five competitors plus a clear note than a session that has been waiting twenty minutes on a hanging subagent.

9. Debugging when a deep subagent hangs

When something jams, walk the levels from top to bottom. The agents view shows you which subagent is active. The June update fixed several bugs here, for example that a subagent stayed stuck as "active" after stopping a child it had started. If you are on an old version, update first, many of these hangs were simply bugs.

If the subagent genuinely fails at its task and not at a bug, it is almost always too much or too little context from step 6. Too little, and it does not know what to do. Too much, and it loses itself. Look at the spawn job the parent sent, the cause is in there.

10. When to stay flat instead

The honest answer for most solo founders and small teams: stay at level one. A coordinator that starts four or five workers and merges their results covers 90 percent. You only need depth once a single worker task itself breaks cleanly into independent subtasks, and that is rarer than you think.

My week of testing confirmed that. Of all the setups I ran, exactly one genuinely benefited from the second level, namely the competitor fan-out from step 3. All the others were faster, cheaper and easier to debug with one level. Being allowed to go five levels deep does not mean you should.

What next

If you are now planning a larger agent setup, continue to level 6 lesson 7, multi-agent orchestration. If you want to know whether a task needs a subagent at all or whether a skill is enough, look at "Subagent or skill or MCP tool". And if the cost worries you, "Claude Code cost controls" is the next logical step.

Source

The feature "Sub-agents can now spawn their own sub-agents (up to 5 levels deep)" and the /usage subagent breakdown come from the official Claude Code changelog, June 2026: https://code.claude.com/docs/en/changelog