/dispatching-subagents

name: dispatching-subagents
description: Chooses how to launch subagents from Claude Code (the Agent tool, a Workflow script, or headless claude -p children) and runs a headless fan-out from one background command. Use for "fan this out to 50 agents", "run these tasks in parallel", "launch subagents for each file", "should I spawn agents or write a workflow", "batch this through Haiku", "run claude -p in parallel", "dispatch a task list without the launches eating my context", or before any launch of more than a handful of subagents, where the launching itself is the cost. Covers the parent-turn cost of each mechanism, concurrency ceilings, what context and tools each child gets, effort control, output contracts, a cost ledger, and resume after interruption.
metadata:
  version: 0.2.2

Dispatching subagents

Claude Code has three ways to start a subagent. They differ most in what the launching costs the parent.

| | Agent tool | Workflow tool | `claude -p` children (`scripts/headless_fanout.py`) | |---|---|---|---| | parent cost | one parent turn per launch and one per completion | one tool call per run | one Bash call per run | | concurrency | 20, and a 21st launch errors (it does not queue) | min(16, vCPUs − 2): **2** on a 4-vCPU CCotw container | RAM-bound, about 210 MB per child: 40 ran clean on 4 vCPU / 15 GB | | child context | session prefix (~32–55K tokens), plus parent transcript chunks if a context hook is installed | session prefix | what you pass: about 1.2K tokens with `--system-prompt` and no tools, 39K with the default prompt | | tools | agent type's tools, the session's MCP connectors, hooks | as Agent | built-in tools named in `--tools`, write paths allowlisted; no MCP, hooks or skills | | effort | session's level, or the `effort:` in a named agent type's frontmatter | `agent(prompt, {effort})` | `--effort` (measured: low gave 0 thinking tokens, high gave 112–197) | | needs user opt-in | no | **yes**: an explicit request, ultracode, or a skill that calls it | no | | cost visibility | none per child | none per child | `total_cost_usd` and tokens per child, in a ledger | | output check | yours | in-script | file plus JSON Schema, or CLI-validated `--json-schema` |

The headless runner is the default for volume. On 2026-10-11 a codex build dispatched 314 Haiku children through the Agent tool. The children cost $11.61. The 1,458 Opus parent turns the dispatching took (each re-reading a context of about 400K tokens) cost roughly $160–170, about 14× the work. Five of the same tasks through `headless_fanout.py` cost $0.10, $0.02 each against $0.033 per Agent-tool child, and one parent call.

Choosing

Answer in order. The first yes picks the mechanism.

1. **Does the child need what only the session has?** That means MCP connectors (Muninn, Gmail, GitHub MCP), a context hook's transcript chunks, a worktree, or a custom agent type with guard hooks such as `auditor`. If so, use the **Agent tool**. Keep the count small, or batch many items into each child, because every launch costs a parent turn. 2. **Do you need to read each result before deciding the next launch?** That is iterative work where task N+1 depends on N's answer. Use the **Agent tool**. 3. **Did the user opt in to a workflow, and does the procedure have phases a script should enforce** (find → verify → fix, with retries and gates)? Use **Workflow**, and load `workflow-authoring` first. Accept 2-way concurrency on a 4-vCPU container, or move the bulk phase to headless children. 4. **Are there ten or more independent tasks whose inputs fit in a prompt or in files, and whose output a script can check?** Use **headless children**. This covers judges, graders, extractors, page writers, verifiers and per-file reviews. 5. Fewer than ten small independent tasks: use the Agent tool in one message. The parent-turn cost is still small at that size.

Earned exceptions

| rule | banned when | earned when | |---|---|---| | Use headless for volume | the child needs an MCP connector or the parent's transcript | the inputs can be written into the prompt or a file first | | Agent tool for small counts | the parent context is already past ~300K tokens, so each launch turn is expensive | the parent context is small, or the results feed the next launch | | Judges in headless children | — | always: a child with no hooks cannot see the parent discussing the items it scores |

Headless fan-out procedure

1. **Write one task per line** to `tasks.jsonl`: `{"id", "prompt"}` plus any of `out` (absolute path of a JSON file the child writes), `json_schema` (structured output, no file), `model`, `tools`, `allow`, `deny`, `system_prompt`, `timeout`. `{out}` in a prompt expands to the out path. This is the same `{id, prompt, out}` shape claude-workspace's `scripts/fanout.py` dispatches over the Agent tool, so one file runs on either engine. 2. **Put everything the child needs into the prompt or into files it can Read.** The child has no hooks, no CLAUDE.md, no skills, no MCP and no memory of this session. For no-tool tasks (judges, classifiers) inline the inputs and pass `"tools": ""`. Put a large prefix shared by every task in `system_prompt`, since that is the cacheable part. 3. **Dry-run.** This prints the first three commands:

   S=/mnt/skills/user/dispatching-subagents/scripts/headless_fanout.py
   python3 $S run tasks.jsonl --work RUN --schema schema.json --dry-run

Check `--model`, `--tools` and the `Edit(//...)` rule against the out path. 4. **Launch as a background Bash command, never as a waiting loop.** Run the job itself in the background and end the turn. The completion notification brings you back.

   python3 $S run tasks.jsonl --work RUN --schema schema.json \
       --model haiku --concurrency 16 --max-usd 5 > RUN.log 2>&1; python3 $S status RUN

(`Bash run_in_background: true`.) Defaults are `--tools R