nested-subagents

Nested Sub-Agents

Spawn a tree of sub-agents where each child can itself spawn children, up to 5 levels deep. The motivation is context management, not parallelism: each level gets a fresh context window so deep work doesn't blow the top-level agent's context budget.

When to use

• The problem decomposes into nested layers (research → expand → verify → synthesize), each of which would otherwise pollute the parent's context.
• A single agent's context window would not be enough to hold all the intermediate state.
• The leaves of the tree are different subagent_types and need their own specialized prompts (e.g., pii-detector at one leaf, tester at another).

Skip this skill when flat fan-out (Task × N in one message) suffices — nesting adds latency.

Steps

1. Invoke the coordinator — spawn nested-coordinator as your top-level agent:

   Task({
     subagent_type: "nested-coordinator",
     name: "root-coordinator",
     description: "Decompose and delegate <problem>",
     prompt: "<problem statement, with constraints and expected output shape>"
   })
   

2. The coordinator decomposes first — it lays out the spawn tree via TodoWrite before any Task call. Inspect the tree before approving deep work.

3. Children spawn children — any nested-coordinator (or any other agent whose YAML frontmatter declares tools: [..., Task]) can itself call Task to spawn the next level. Leaf agents (without Task in their tools list) cannot.

4. Each level reports a summary — children return ~200-token structured summaries, not full transcripts. The whole point is to keep the parent's context clean.

5. Tree shape is persisted — the post-task hook writes parent_agent_id and depth to AgentDB on every spawn (ADR-147 P2). Query after the run for cost attribution and pattern learning.

Depth budget

Source	Limit
Anthropic API	5 levels (announced 2026-06-09)
Ruflo default (pre-task hook)	4 levels — one-level guard band, configurable in claude-flow.config.json
Strict-mode env var	CLAUDE_FLOW_STRICT_NESTING=true to enforce the ruflo cap

The hook returns a typed NESTING_DEPTH_EXCEEDED error at the cap, with the full chain in the payload so the parent can decide to summarize, hand off, or abort.

Benefits

• Context isolation per level — top-level coordinator never sees inner chatter; leaf summaries climb back up.
• Deeper delegation without re-summarization — eliminates the "summarize at level 1 to fit it all" anti-pattern that flat fan-out forces.
• Tree-shaped cost attribution — parent_agent_id lineage gives accurate per-tree spend, not just flat per-agent.
• Maps cleanly onto ruflo's existing orchestrators — ruflo-sparc:sparc-orchestrator (5 phases ≈ 5 levels), ruflo-goals:dossier-investigator (recursive entity expansion), v3-queen-coordinator (hierarchical-mesh top).

Anti-patterns (do NOT)

• Pass Task to leaf agents. Leaves must not spawn. Add the leaf's subagent_type directly under the coordinator instead.
• Wrap a Tier-1 codemod in a coordinator. Codemods (hooks_codemod) are depth-0 deterministic transforms — never put them inside a spawn tree.
• Nest "for cleanliness". A premature nesting layer wastes latency and cost without saving context. If one agent can do the work, use one agent.
• Return full transcripts from a child. That defeats the entire purpose of nesting. Children return structured summaries.

Related

• Agent: ruflo-agent:nested-coordinator — the orchestrator
• ADR-147 — design rationale and four-phase rollout
• ADR-144 — authorization propagation shares the depth counter as AuthScope.delegationDepth
• ADR-099 — dossier investigator (recursive parallel research) is the textbook deep use case