---
name: subagents-pattern
description: When subagents earn their cost and how to compose them — swarm, pipeline, and guard patterns.
layer: pattern
cc_feature: subagents
source: https://docs.claude.com/en/docs/claude-code/sub-agents
concept: subagent-composition
last_verified: 2026-04-18
ngram_overlap_score: null
review_status: approved
---

# Subagents — Pattern

## When to delegate

Delegation earns its cost when at least one of these holds:

- **Context isolation** — the subtask needs to read 50+ files or run
  many greps, and the parent conversation does not need the raw
  results. Summaries survive; raw output stays in the subagent.
- **Parallelism** — multiple independent subtasks can run at once,
  compressing wall-clock time.
- **Specialization** — the subagent has a tailored system prompt that
  changes its behavior meaningfully (e.g., adversarial reviewer).
- **Tool scoping** — the subtask should run with fewer tools than the
  parent (principle of least privilege).

If none of these apply, inline the work. A subagent call costs a full
model turn; do not pay it for routine reads.

## Common patterns

### Pattern A: Exploration swarm

Parent launches 4-8 specialized subagents in parallel, each with a
narrow brief (architecture, dependencies, risks, tests, ...). Each
returns a summary. Parent synthesizes.

Used by: `ultraplan-local` Phase 2 exploration.

Cost shape: N × Sonnet call, wall-clock ≈ slowest subagent.

### Pattern B: Adversarial review

Parent writes an artifact (plan, design note). Launches a reviewer
subagent with a system prompt that demands problems, never praise.
Reviewer returns findings. Parent revises.

Used by: `plan-critic`, `scope-guardian`, `architecture-critic`.

Cost shape: 1 × Sonnet call per review pass.

### Pattern C: Background orchestrator

Parent kicks off a long-running orchestrator subagent with
`run_in_background: true`, then continues. Orchestrator runs its own
subagents, synthesizes, writes output to disk. Parent is notified on
completion.

Used by: `planning-orchestrator`, `research-orchestrator`.

Cost shape: 1 × Opus orchestrator + N × Sonnet workers. Overlaps with
other user work.

### Pattern D: Guard subagent

A hook delegates an "is this safe?" question to a subagent when the
answer needs judgment. The subagent returns a verdict; the hook
enforces it.

Cost shape: 1 × Sonnet call per hook invocation. Use sparingly —
adds seconds of latency per tool call.

## Pitfalls

- **Delegate-understanding anti-pattern** — do not write "based on your
  findings, fix the bug" to a subagent. The subagent is not inside your
  head; it cannot see what you synthesized. Pass concrete context.
- **Prompt-on-top-of-prompt drift** — if the parent's prompt to a
  subagent contradicts the subagent's own system prompt, the subagent
  follows its system prompt. Do not try to re-style a reviewer into a
  cheerleader by prompting harder.
- **Silent failure** — a subagent that returns "done" without evidence
  may have done nothing. Trust but verify: check for the concrete
  artifacts the subagent was asked to produce.
- **Orchestration explosion** — a three-level-deep subagent tree costs
  exponentially. Flatten wherever the inner levels don't need their own
  context isolation.
- **Token budget fights** — parent and all active subagents share the
  harness's overall budget. Cap subagent output length ("report in
  under 200 words") when the summary is what matters.

## Composition with other features

- Subagents + hooks: hooks fire during subagent tool calls too. A
  subagent with only `Read` tools is already constrained; hooks add
  defense in depth.
- Subagents + worktrees: an `isolation: "worktree"` subagent works in
  an isolated copy of the repo, so its writes never clash with the
  parent's writes.
- Subagents + background: run heavy exploration in background while the
  user continues other work.