Subagent Orchestration

Pain Signals — You Need This Pattern When:

• A single agent's context is filling with tool output the parent will not need again (verbose searches, large file reads, exploratory dead ends)
• Multiple independent investigations could run in parallel — the parent is the bottleneck
• A specialized capability (security review, planning, search) is better served by a focused agent with a tighter prompt
• A risky operation should run in an isolated workspace (worktree, container) without polluting the parent's state
• The task scope is too large for a single context window even with compaction

Subagents are not free. Each spawn has setup cost, briefing cost, and merge complexity. Use them when context isolation or parallelism is the actual win — not as default decomposition.

Core Principle

A subagent is a bounded computation with its own context, tool set, and termination condition. The parent delegates a self-contained subtask, waits for a single structured result, and integrates it. The parent does not observe the subagent's intermediate steps.