Subagent Delegation — Three Isolation Modes

## Full reference: subagent delegation in production

Derived from architecture.md §Subagent Delegation and build-your-own-agent.md Decision 5 of the VILA-Lab/Dive-into-Claude-Code paper (arXiv 2604.14228). All section references below are to architecture.md unless noted.

### 1. The central decision — SkillTool vs AgentTool

The paper (§Subagent Delegation — "Key Design: SkillTool vs AgentTool") names this as *the* design knob, and it is the one new harness engineers get wrong first:

- **SkillTool** — Injects a SKILL.md body into the CURRENT context window. Zero new conversation. Same model state. Cheap.
- **AgentTool** — Spawns a new isolated context window. The paper cites subagent sessions costing ~7x tokens of standard sessions (§build-your-own-agent Decision 5). Context-safe. Expensive.

One-line heuristic: if the step needs new instructions that fit the current trace, use SkillTool. If the step needs a fresh window (read-heavy, parallelizable, or must-not-pollute), pay the AgentTool cost.

Pathological patterns you will see in your first rollout:

- **AgentTool for a helper nudge**: "spawn a subagent to remind me of the naming convention." The parent's context has headroom; SkillTool is the right tool. AgentTool here is a 7x overcharge for a single guidance message.
- **SkillTool during a read-heavy phase**: parent is about to Read 20 files while its context is at 70%. Injecting a skill does not protect the window — spawn an Explore subagent instead and let the summary come back.

### 2. Six built-in subagent types

The paper lists these as the built-in types in §Subagent Delegation:

1. **Explore** — Read/Grep/Glob only. Returns a summary across many files. The most common subagent you will spawn.
2. **Plan** — Emits a todo tree without execution. Useful when the parent wants a plan reviewed before starting.
3. **General-purpose** — Full tool access. Use when the sub-task is itself an agentic loop.
4. **Claude Code Guide** — Specialised to answer "how does the harness work" questions without polluting the parent.
5. **Verification** — Runs tests / type checks / lint and returns pass/fail with a terse summary. Pairs with the Stop hook.
6. **Statusline-setup** — Configures the terminal statusline; rarely spawned by application code but documented in the architecture.

You will overwhelmingly use Explore, Plan, and Verification. The other three are niche.

### 3. Custom agents — the YAML frontmatter

Custom agents live at `.claude/agents/<name>.md`. The paper (README §Subagent Delegation) enumerates the frontmatter fields. Minimal set:

```markdown
---
name: verify-migration
description: Runs the migration safety harness after a Prisma schema change. Use when the parent has just edited prisma/schema.prisma.
tools: [Bash, Read]
disallowedTools: [Write, Edit]
model: claude-sonnet-4.6
effort: low
permissionMode: default
mcpServers: []
hooks: {}
maxTurns: 8
skills: [prisma-migration-recipe]
memory: scoped
background: false
isolation: worktree
---

# Migration verifier
...
```

Field semantics worth internalising:

- **tools / disallowedTools** — union with parent's pool, then deny-filtered. Subagent's allow-list is NOT the union — it's the parent's pool narrowed by these fields.
- **permissionMode** — per §Subagent Delegation in the paper: the subagent's permissionMode applies UNLESS the parent is in bypassPermissions / acceptEdits / auto (explicit user decisions propagate down).
- **memory: scoped** — the subagent sees only its own CLAUDE.md + skills; parent memory is hidden.
- **isolation** — one of `in-process` (default), `worktree` (git worktree, filesystem isolation), `remote` (internal-only, hosted).
- **background** — if true, spawn returns immediately with a task_id; caller polls.

### 4. Three isolation modes

From architecture.md §Three Isolation Modes:

| Mode | Mechanism | Default | When to use |
|:--|:--|:--|:--|
| in-process | Shared filesystem, isolated conversation | Yes | Almost always. Parent and child see the same files; only the conversation is split. |
| worktree | Git worktree, filesystem + conversation isolation | No | Exploratory edits you do NOT want to contaminate the parent's working tree. |
| remote | Hosted / remote-execution subagent | No | Internal-only. Do not rely on it in open-source harnesses. |

Practical defaults: start in-process. Promote to worktree when the subagent's plan includes Edit/Write that you want to isolate until a human confirms the diff.

### 5. Sidechain transcripts and POSIX flock()

Every AgentTool-spawned subagent writes its full conversation to a separate JSONL file. The paper is blunt (§Sidechain Transcripts):

> Each subagent writes its own .jsonl file. Only summary returns to parent. Full history never enters parent context. Multi-instance coordination via POSIX flock() — zero external dependencies.

Implementation discipline:

1. Sidechain path: `.sidechains/<task-id>.jsonl`. Do NOT put these in the session transcript directory — they have different retention semantics.
2. Acquire `flock(LOCK_EX)` on the file before append. Release on each write. The paper's contribution here is that this is sufficient — do not add Redis, SQLite, or a message broker.
3. The parent MUST NOT read the sidechain during or after the subagent run. The summary is the contract; reading the full transcript defeats the context-protection design.
4. Cap total sidechain bytes across children. Pathological loops can fill the disk faster than the parent notices — bound at 10 MiB aggregate by default.

### 6. The spawn rules of thumb

Derived from the "Do / Do not" heuristics (paraphrased and tightened from the paper):

**Spawn a subagent when**:
- A step scans >10 files and you only need a 500-token summary back.
- Two or more hypotheses can be investigated independently.
- The parent's context is approaching 60% utilisation and the next step is read-heavy.
- You are processing an untrusted input you want quarantined.

**Do NOT spawn a subagent when**:
- Files are already in the parent's context.
- You need fine-grained state that lives only in the parent.
- You are one step from a terminal answer.
- The work is a guidance nudge — use SkillTool instead.

### 7. Coordinating parallel subagents

A parent can spawn 2-4 subagents in the same turn. Two coordination patterns:

- **Fan-out / fan-in**: parent spawns N children, awaits all summaries, merges. Use when children are independent.
- **Race-to-first**: parent spawns N children and takes the first non-error summary. Use for speculative investigation where any correct answer suffices.

Over 20 parallel subagents, the paper's POSIX-flock model shows measurable contention. Keep fan-out ≤ 10 in production harnesses; above that, serialise in batches.

### 8. Error propagation

The documented failure mode is "summary-only return hides error signal needed by parent." Guard against it:

```
merge_subagent_result(parent_trace, child):
    if child.completion_status != 'completed':
        emit error_marker(task_id=child.task_id, status=child.completion_status)
    append child.summary to parent_trace
    return parent_trace + propagated_errors[]
```

The parent's next step should branch on `propagated_errors` — silent treatment of a timeout or abort is the staff-level bug.

### 9. Anti-patterns catalogued from community reimplementations

From the community reimplementations catalogued in the paper's related-resources (claw-code, nano-claude-code, open-claude-code), several recurring mis-implementations are worth naming:

1. **Loading the sidechain back into the parent** — defeats the entire context-conservation design.
2. **Inheriting permissions silently** — subagent runs with parent's bypassPermissions without re-prompting. The paper accepts this ONLY when the parent is already in an explicitly-bypassing mode; custom reimplementations often drop the guard.
3. **Ignoring the 2-level spawn depth cap** — a subagent that can spawn its own subagent can burn context exponentially. Cap at depth 2 unless you have an explicit reason.
4. **No aggregate byte cap** — a runaway loop fills the disk. 10 MiB is a reasonable default.

### 10. Relationship to the "parallelization" canonical pattern

This harness instantiates the parallelization pattern from Anthropic's "Building effective agents" taxonomy. The subagent-summary-only-return design is what makes the parallelization economically viable in practice — without it, N children cost N × context_window tokens and the pattern collapses above N=2 or 3.

See also:
- `claude-code-guide` — the broader harness reference; subagent delegation is one of its 11 sections.
- `advisor-pattern-v2` — an evaluator-optimizer loop; different pattern class but shares the cost-routing instinct.
- `turn-execution-pipeline` — the 9-step pipeline each subagent runs internally.