Sub-agents can now “have children”? Claude Code 5-layer nesting test + detailed tutorial

Claude Code v2.1.172 added a capability:

A sub-agent can generate its own sub-agents. Up to 5 layers.

Less than a week after the Loop Engineering concept came out, this capability followed suit.

What we need to think about is what this means for us and how to use it. Let me break it down for you.

What changes when going from one layer to multiple

Previously, sub-agents could only have one layer.

The workflow used to be:

• Open a main session. The main agent breaks down tasks and assigns them to sub-agents. Sub-agents finish the work and return results to the main agent.

Problems followed:

• When a sub-agent encounters a complex problem, it can’t break it down further. It either has to tough it out alone or toss it back to the main agent for re-distribution.

Now it’s different.

• During execution, if a sub-agent finds a subtask it can’t handle on its own, it can spawn a grandchild agent.

For example, a security audit agent finds 12 third-party dependency packages, but it’s not familiar with each package’s vulnerabilities.

• It can spawn a grandchild agent.

• The grandchild agent cross-references the CVE database and checks each package one by one. After running, it reports the vulnerability IDs and impact scope back to the sub-agent.

• The sub-agent then consolidates that part into the security audit report.

Grandchild agents can create another layer.

Up to 5 layers.

• Each layer has a clear division of labor and acceptance criteria.

• The upper-layer agent acts as the client — setting requirements, verifying output, and consolidating results.

• The lower-layer agent acts as the contractor — focusing on one narrow domain.

When to use and when not to use

Nesting isn’t free.

Each additional layer introduces one more step of information loss.

A sub-agent summarizes the grandchild agent’s report for the main agent, and the main agent summarizes it again for you.

By the 4th or 5th layer, the initial details may be largely lost.

So the judgment is simple:

If the task is tree-shaped, use it.

• For example, code review.

The main agent reviews structure, the sub-agent reviews security. If the sub-agent finds dependency issues, it spawns a grandchild agent for dependency auditing.

• For example, data analysis.

The main agent sets direction, the sub-agent writes queries. If the sub-agent finds issues with data sources, it spawns a grandchild agent for cleaning.

Each step in such tasks can be parallelized, and each subtask has its own acceptance criteria, making it suitable for nesting.

If the task is linear, don’t use it.

For example, changing a few lines of code, looking up API documentation, formatting a file.

One layer is enough; nesting only adds latency.

Here’s an even more intuitive way to judge:

When you normally do this task, would you need to call a colleague who specializes in something?

If yes, it’s worth nesting.

If no, one layer is enough.

How to configure

In the .claude/agents/ directory, one file per agent.

An example audit agent:

**You are the code review agent. Review project structure, code style, and security risks.

When encountering the following situations, spawn a specialized sub-agent:

• Third-party dependencies need security auditing, and you’re not familiar with these packages
• Performance issues need profiling that’s beyond your capability
• Database queries need an optimization expert’s involvement

The spawned sub-agent must:

• Only do one narrow thing
• Come with clear acceptance criteria, e.g., “Output each vulnerability’s CVE ID and affected version”
• Return output directly to you, not to the main agent
• Automatically destroy itself after completion**

No need to configure the number of layers.

Claude Code manages it automatically, with a max of 5 layers.

An example

The main agent receives a web project audit with 50 files.

It breaks it into three chunks:

• Code style audit to sub-agent A.

• Security vulnerability audit to sub-agent B.

• Performance audit to sub-agent C.

• Sub-agent B scans dependencies and finds 12 third-party packages.

• It decides it’s not familiar with every package, so it spawns a grandchild agent.

• The grandchild agent checks each of the 12 packages against the CVE database, finding 3 with high-risk vulnerabilities.

• The grandchild agent returns CVE IDs, affected versions, and remediation suggestions to sub-agent B.

• Sub-agent B consolidates this into the security audit report.

Sub-agent A, halfway through scanning, finds three different naming styles mixed in the project.

It also spawns a grandchild agent, asking it to label each file’s style type and provide unified recommendations.

The grandchild agent runs through all 50 files and returns a naming convention issue list.

Finally, the main agent consolidates the results from all three sub-agents and generates the final audit report.

You only sent one instruction:

Audit this project

• The intermediate sub-agent decisions, grandchild agent spawning, and result consolidation — all automatic.

Two pitfalls encountered

First: The nesting process is invisible.

The main agent tells you the sub-agent’s result, but it may not tell you how many layers of nesting happened inside the sub-agent.

If the grandchild agent’s conclusion is wrong, the sub-agent might continue working based on the wrong conclusion.

When debugging, you need to dig layer by layer.

First confirm whether the sub-agent’s judgment is correct, then confirm whether the grandchild agent’s data is accurate.

Second: Beyond 3 layers, information compression is too aggressive.

The sub-agent summarizes the grandchild agent’s full report into a paragraph, and the main agent summarizes it into a sentence.

After a 5-layer chain, the bottom-level details may already be compressed away.

So for nesting above 3 layers, you need to judge for yourself:

Can the summarized information still support decision-making?

How to upgrade

Upgrade to v2.1.172:

npm update -g @anthropic-ai/claude-code

First, create an audit agent under .claude/agents/.

Run a project with external dependencies.

Focus on three things:

• Whether the sub-agent spawned a grandchild agent.

• Whether the grandchild agent’s output was correctly referenced.

• After the two-layer nesting works, add more layers.

This is also a direction worth paying more attention to after Loop Engineering — above traditional workflows, the task system itself begins to grow an organizational structure.