Spawning Sub-Agents

Tier 2 · Building 8 min read

Before this, read:

Anatomy of an agent — understand the package shape you’re delegating to

A single agent can go deep on one task. But some problems — run a QA suite, backfill a database, ship three independent features in parallel — are better broken into pieces that run concurrently. Claude Code provides the Agent tool to spawn a sub-agent: a separate process that carries its own context, uses its own tools, and reports back when done.

This page covers when to delegate, how to invoke the Agent tool, and the two non-negotiable rules that keep parallel agents from stepping on each other.

Foreground vs. background

The Agent tool has two modes, and picking the wrong one is a common mistake.

Foreground (synchronous): the parent session blocks until the sub-agent finishes. Use this when you need the result before continuing — a research task whose output feeds into the next step, a code review that must approve before the merge.

Background (run_in_background: true): the parent session keeps moving; the sub-agent runs in parallel. Use this for independent work that doesn’t block the current thread — shipping three separate features, running QA while you’re doing something else, long-running tasks that would otherwise fill the context window while you wait.

The decision is: does the parent need the output of this sub-agent before it can do its next action? If yes, foreground. If no, background.

The two non-negotiable rules

Rule 1: Any background agent that may write files or run git gets `isolation: "worktree"`

{
  "subagent_type": "general-purpose",
  "isolation": "worktree",
  "run_in_background": true,
  "prompt": "..."
}

Without worktree isolation, sub-agents share the same git working tree as the parent session. A sub-agent doing git checkout feature-branch mid-flight reassigns the parent’s checkout — your edits end up on the wrong branch. This happened twice in May 2026 (documented in the CHANGELOG 2026-05-22): sub-agents running git checkout mid-edit caused the parent session’s page.tsx changes to land on the wrong branch. Recovery required git reflog and cherry-picks.

Worktree isolation creates a separate copy of the checkout for that sub-agent. The parent session’s files don’t move.

The rule in full:

Background agent that may write files or run git → isolation: "worktree" always
Foreground agent that will commit → same rule
Foreground agent that is read-only (search, research, no file writes) → worktree optional

Rule 2: Tell the sub-agent in its prompt that it’s in a worktree

"You ARE in a worktree (isolation: 'worktree' was passed). Confirm with `pwd`.
Don't touch other branches in the parent checkout."

This sounds redundant, but it’s not. The Agent tool creates the worktree; it doesn’t explain what that means to the sub-agent. Without the instruction, a sub-agent may cd to the main checkout path and make changes there. The prompt is the guardrail.

When to use the Agent tool vs. the CLI directly

The Agent tool spawns a full Claude Code session — it has tools, it can read and write files, it can call sub-agents of its own. It’s the right choice when the sub-task requires judgment.

For deterministic work — running a Python module, calling a known CLI, formatting output — use Bash directly. Spawning an agent to run python3.12 -m agents.researcher.main "query" is wasteful; just call it.

A heuristic: if you’d have to give the sub-agent a paragraph of instructions about what to do, use the Agent tool. If the sub-task is “run this command and return the output,” use Bash.

What to put in a sub-agent prompt

A good sub-agent prompt includes four things:

The specific goal. Not “help with the PR” — “write src/lib/utils.ts, implement the formatDate function per this spec, run npm test, report pass/fail.”
The worktree reminder (if isolation is on).
The “no live sessions” guard if the agent will interact with any persistent system: “Do NOT spawn or POST to any live CEO, domain, or cockpit session. Use read-only inspection or a disposable session you delete after.” (This rule exists because build/QA agents once sent “[QA smoke]” messages into JD’s real CEO chat — permanent, unremovable pollution.)
The output contract. What should the sub-agent return? A file path? A JSON blob? A pass/fail verdict? Be specific.

The “Inventory Before Spawning” check

Before spawning a general-purpose sub-agent for a task type, check whether a specialist agent already handles it:

bash ~/agent-system/scripts/list-agents.sh <keyword>

If agents/qa_agent/ exists and does Playwright testing, spawning a general-purpose agent to do Playwright testing wastes token budget and produces output in a format the canonical store can’t read. The canonical agent is the right choice.

Parallel build agents in practice

In April 2026, the “Fleet of Claudes” shipped 6 PRs concurrently, with 48/48 tests green. Each agent ran in its own worktree, received a specific objective, and committed to its own feature branch. The parent session monitored their completion and merged when all gates passed.

The Infinity Fleet drainer (agents/shared/drainer.py, shipped 2026-06-08) generalizes this pattern: a Supabase-backed queue holds objectives; the drainer claims one per worker, spawns a worktree-isolated Claude Code session via fleet.py, and marks it done or failed from the stream-json result. Capacity scales by attaching more workers — each one connects to the queue and takes the next unclaimed task.

The unit is still the same: one agent, one worktree, one clear goal, one commit. The drainer just lets you run many of them without managing each one by hand.

Next: The worktree incidents — what went wrong, how the machine-enforced fix works, and why behavioral instructions alone can’t prevent this class of bug. Worktree isolation.