Hierarchical Pipelines: Agents That Spawn Agents

Nested Subagents: What Changed in June 2026

Before Claude Code v2.1.172 (released June 2026), subagents could not spawn their own subagents. The orchestration hierarchy was flat: main conversation → subagents, and that was the entire chain. Every coordination decision had to go back through the main session.

v2.1.172 changed this. Subagents can now spawn their own subagents, up to five levels deep from the main conversation. This enables genuinely hierarchical pipelines where each layer handles decisions at the appropriate level of abstraction.

When Hierarchical Outperforms Flat Fan-Out

Flat fan-out — one orchestrator spawning all workers directly — works well when tasks are uniform and independent. When tasks are varied, dependent, or require sub-coordination, hierarchical pipelines are more effective.

Consider auditing a large codebase with five subsystems (auth, payments, data layer, API, frontend). A flat approach spawns five agents from the main session. A hierarchical approach spawns five specialists, each of which spawns its own workers for specific checks within its subsystem.

The hierarchical approach is better because:

• Each specialist understands its subsystem's context and can decompose work appropriately
• The main session only receives five high-level summaries, not fifty individual findings
• Sub-coordination (a payment specialist coordinating token-validation and transaction-logging checks) happens at the specialist level without cluttering the main session

Designing a Three-Level Pipeline

A three-level hierarchy is the most common pattern: orchestrator → specialist → worker.

Level 1: Orchestrator (main session). Receives the high-level goal, decomposes it into specialist-level tasks, spawns specialists, receives their final summaries, and synthesizes the overall result.

Level 2: Specialist. Receives a bounded domain (e.g., "audit the auth subsystem"). Understands that domain's structure. Decomposes the domain into specific checks, spawns workers for each, receives their findings, and returns a structured summary to the orchestrator.

Level 3: Worker. Receives a single, specific task (e.g., "check src/auth/tokens.py for insecure token handling"). Does exactly that task using tools, and returns a structured finding.

Each level handles decisions at its own scope. Workers do not need to understand the broader audit strategy. Specialists do not need to understand how their summaries fit into the final report. The orchestrator does not need to understand the individual code paths being checked.

The Depth Limit and Why It Exists

The maximum nesting depth is five levels from the main conversation. This limit is fixed at spawn time — you cannot increase it, and the depth counter does not reset at intermediate levels.

If the main conversation spawns a specialist (depth 1), and that specialist spawns a worker (depth 2), and that worker spawns a sub-worker (depth 3), the chain can go two more levels before hitting the limit.

The limit exists to prevent runaway hierarchies that are expensive to run and difficult to debug. Five levels is enough for any realistic pipeline design. If you feel you need more than five levels, it is usually a sign that the orchestration logic should be restructured rather than deepened.

Reading Subagent Transcripts

Every subagent produces a complete transcript of its work, stored at:

~/.claude/projects/{project-hash}/{session-id}/subagents/agent-{agent-id}.jsonl

The project hash is derived from the git repository root. The session ID corresponds to your current session. Each subagent gets a unique agent ID.

These transcripts are plain JSONL files. Each line is a JSON object representing one event in the agent's execution: tool calls, tool results, model turns, and the final summary. Reading a transcript tells you exactly what the agent did, what tools it called with what inputs, and what it returned.

Transcripts are invaluable for debugging nested pipelines. When something goes wrong three levels deep, the transcript for that agent shows the exact point of failure.