AutomaterWhen the Coordinator Spawns a Thousand Subagents: Metering Subagent Token Cost at Fan-Out
Subagent token cost climbs one worker at a time. Cap concurrent workers, budget per task, log every spawn, and kill orphans before a coordinator fans out.
Go deeper. Build your own.
At 9:40 a.m. the coordinator’s status line reads 212 workers active, and the meter those workers are draining is yours. Nobody typed 212. The coordinator decided the work needed it, which is exactly what it was built to do. Subagent token cost is the number nobody put on that status line, and by the time you compute it by hand the fan-out has doubled.
This piece is the runbook for that morning. By Tuesday every spawn in your fleet carries a budget, a parent, and a kill path; concurrency has a ceiling that is yours rather than the coordinator’s; research and write workers run on different envelopes; and you know, in dollars, what one worker costs before any coordinator picks the fan-out. The parallel is real. So is the bill.
Chatbots suggest; agents act; and coordinators now act by spawning other agents, which moves the unit of spend from a session to a tree of sessions whose shape is decided at runtime. A meter that only sees sessions is watching the wrong thing.
Sep 10: Cursor Projects puts “thousands of subagents” in the launch copy
On Sep 10, 2026, Cursor shipped Projects in beta, and the changelog entry leads with scale: Projects “maintains context over months of work, delegates tasks to thousands of subagents, and performs recurring work without being prompted.” The launch post by Alexi Robbins and Fredrika Lindh states the mechanism plainly: “The coordinator agent in a project doesn’t write code itself; it plans the work, delegates it to agents that implement it, and brings the finished work back to you to check. Coordinators create and manage agents on your behalf, running as many in parallel as the work needs.”
Screenshot: Cursor changelog, “Cursor Projects” (Sep 10, 2026), captured Sep 13, 2026.
Two more lines matter for cost: “A Project runs on its own computer in the cloud, so closing your laptop doesn’t stop it,” which “lets a Project run more subagents in parallel than your laptop could support.” The laptop used to be the concurrency cap. It is not anymore.
Screenshot: Cursor blog, “Introducing Projects” (Sep 10, 2026), captured Sep 13, 2026.
The groundwork landed on Aug 19, 2026, in the changelog’s “Cloud Agents and Cursor Harness Improvements”: subagents run on their own machines, and “each gets an isolated copy of the project with clean context in its own cloud environment.” Clean context per worker is good engineering and also the cost model: every worker re-reads what it needs from zero.
The Sep 10 entry contains no pricing, limits, or permission language, which is what a beta looks like. The limits are yours to write, in the same week OpenAI’s Agents API went to public beta (Sep 10, 2026) with subagents on the feature list and billing, per the docs overview, “at the selected model’s API rates” plus tool rates plus “standard container rates.” Fan-out is a feature on every managed harness now, and on at least one of them a worker has three meters.
Why subagent token cost scales worse than the work does
The arithmetic behind fan-out cost is not exotic. A worker with clean context pays the fixed tax on every spawn: the repo brief, the rules file, the tool schemas, whatever memory layer you bolted on. One session pays that tax once. A fan-out of N pays it N times, and then the coordinator pays again to read N reports. Memory that replays into every session rides into every worker too, so the multiplier multiplies.
The second-order effect is the one that surprises people. Each worker’s turns re-send its growing context, so per-worker cost is closer to context × turns than to context. Prompt caching may reduce repeated input, but it does not remove the fixed cost of loading separate workers. The fan-out that finishes fastest is often the one that read the most.
None of this argues against fan-out; a migration spread across a few hundred PRs may benefit from it. It argues for metering the tree rather than the session, with the ceiling somewhere the coordinator cannot move it.
Step 1: Write the per-worker cost envelope before the first spawn
The envelope is one number: what a typical worker costs from spawn to report. You get it by modeling, then replace the model with your ledger after a week. Here is an illustrative model with round parameters; the shape matters more than the values.
| Fan-out | Worker input (N × 8 turns × 35k) | Worker output (N × 8 × 1.5k) | Coordinator ingest (N × 40k in, 2k out) | Total tokens | Illustrative cost |
|---|---|---|---|---|---|
| 1 worker | 280k | 12k | 42k | ~0.33M | ~$1.20 |
| 8 workers | 2.24M | 96k | 336k | ~2.7M | ~$9.40 |
| 64 workers | 17.9M | 768k | 2.7M | ~21M | ~$75 |
| 512 workers | 143M | 6.1M | 21.5M | ~171M | ~$600 |
Illustrative pricing: $3 per million input, $15 per million output, no cache credit, one report per worker. Change any parameter and the column moves; the line stays straight. There is no economy of scale in a fan-out, only an economy of wall clock.
Illustrative. The cap does not make a worker cheaper; it decides how many workers exist before a human looks. Log axis.
Two things to take from the table. The marginal worker costs about the same as the first, so the coordinator’s fan-out decision is a spend decision with a slope of one. And the coordinator’s own ingest is small per worker and not small in total; at 512 workers it is roughly $65 of reading reports.
Write your envelope down as a range, because a research worker and a write worker are different animals (step 4), and set per_worker_usd at about twice the modeled figure. That gap is where legitimate variance lives; anything past it is a worker that has lost the plot.
Step 2: Cap concurrent workers before you cap tokens
A token budget bounds the total. A concurrency cap bounds the velocity, and velocity is what hurts at 9:40 a.m., because a budget is checked when a worker reports and a fan-out of 512 has committed the spend before the first report arrives. Cap concurrency first; the budget then has time to act.
Pick the cap from the envelope rather than from ambition. At an illustrative $1.20 per worker and ten-minute workers, eight concurrent workers burn about $58 an hour at full tilt; 64 burn about $460. Decide which of those numbers you are willing to discover at lunch and set the cap there; an illustrative starting cap is four to twelve, with write workers far lower. If the coordinator’s product exposes no cap, wrap the spawn call in one. The Projects-versus-tray decision is partly about who owns this knob.
# fleet-policy.yaml (illustrative shape); enforced by the spawn wrapper, never by the prompt
project: billing-migration
concurrency:
max_workers: 8 # hard ceiling, all roles
max_research: 6 # read-only workers
max_write: 2 # may edit, commit, push
spawn_queue: wait # queue past the cap; never drop silently
budget:
per_worker_usd: 2.50 # ~2x the modeled envelope
per_task_usd: 60
per_project_day_usd: 400
on_exceeded: pause_spawns # then page (step 6)The spawn_queue: wait line matters more than it looks. A cap that silently drops spawns produces a coordinator that believes it delegated work nobody did. Queue, log, and let the coordinator see the queue depth.
Step 3: Budget per Project and per task, in a hierarchy the coordinator cannot rewrite
Budgets nest: fleet per day, Project per day, task, worker. Every level is a ceiling on the level below it, and the coordinator gets to allocate inside its task budget but never to raise it. Raising a budget is a human action with a name on it.
The per-task budget is the one you will argue about, so anchor it in the envelope: task budget = expected workers × per-worker envelope × 1.5. A task the coordinator scoped for eight workers gets about $15; if it comes back asking for $60, that is a scoping error surfacing as a bill, and you want to see it rather than fund it. Track consumption against the ledger in real time, because the vendor’s invoice arrives after the decision window has closed; that real-time view is what the operating bill pays for.
One rule I have never regretted: no task budget carries over. Unspent money at the end of a task goes back to the Project, not into the next fan-out.
Step 4: Separate research workers from write workers
Two roles, two envelopes, two tool lists. Research workers read, search, and summarize; they get a cheaper model, a read-only tool set, a small context, and most of the concurrency slots. Write workers edit, run tests, and commit; they get the strong model, the full context, the git tools, and a slot count you can count on one hand. Claude Code’s current subagent definitions expose tools, disallowedTools, and model controls in the official documentation, and the same split is expressible in any harness that lets a spawn declare its role.
| Research worker | Write worker | |
|---|---|---|
| Model | mid-tier | strong |
| Tools | read, grep, search, fetch | read, edit, shell, git |
| Context budget | small (brief + slice) | full (brief + files + tests) |
| Concurrency | up to 6 | up to 2 |
| Envelope (illustrative) | ~$0.40 | ~$2.00 |
| Kills safely at | any time | tool-call boundary only |
The split is a cost control and a safety control at once, which is why it belongs in policy rather than in a prompt. It also gives you the cleanest cost signal there is: write-worker spend rising while research spend stays flat means the coordinator is editing without reading. The subagent orchestration primer covers the pattern; this is the metered version.
Step 5: Log every spawn, and log the parent
A meter that cannot answer “who spawned this and why” is a receipt. The spawn ledger is what turns it into a control: one JSONL line per spawn plus one per state change.
| Field | Why it is there |
|---|---|
spawn_id, parent_id, task_id, project |
The tree; orphans are found by walking it |
role (research / write), model, host |
Which envelope applies, and where |
budget_usd, spent_usd, tokens_in, tokens_out, cache_read |
Envelope versus reality |
turns, tool_calls, last_tool_call_at |
Idle detection; the safe kill boundary |
state (queued / running / reported / killed), killed_by |
Whether the kill switch works |
reason (one line from the coordinator) |
The audit answer to “why 212” |
{
"ts": "2026-09-13T09:41:12Z",
"spawn_id": "w-0417",
"parent_id": "coord-billing-07",
"task_id": "t-migrate-invoices",
"role": "write",
"model": "strong",
"host": "cloud-vm-2",
"budget_usd": 2.5,
"spent_usd": 0.0,
"cap_slot": "2/2",
"state": "running",
"reason": "apply invoice model migration and run tests"
}
Three meters and one switch. The switch cuts new spawns first, then running workers at their next tool call.
Three metering points, top to bottom. At the coordinator: spawn count, queue depth, and ingest tokens. At the worker: the envelope fields above. At the tool call: tool name, duration, and bytes returned, because a worker that pulls a 400 KB file into context on every turn is a cost problem disguised as a tool problem. Ship the ledger to wherever your fleet’s other evidence lives, and export it before vendor access or retention changes.
Step 6: Kill orphans at the tool-call boundary
An orphan is a worker whose reason to exist has gone: its parent died or was paused, its task closed, its budget is spent, or it has made no tool call in ten minutes. Sweep for all four every five minutes. Cursor’s Aug 19 steering change is the right model for the cut: “Follow-ups wait for the next tool call instead of cutting the agent off mid-action.” Kill research workers immediately; kill write workers only at a tool-call boundary, after they have finished the edit they are in and before they start the next one. A half-applied migration costs more to unwind than the tokens the kill saves.
# Illustrative sweep; `fleet kill` stands for whatever your wrapper exposes
ledger=~/.fleet/spawns.jsonl
jq -r 'select(.state=="running")
| select(.parent_alive==false or .spent_usd > .budget_usd or .idle_min > 10 or .task_state=="closed")
| .spawn_id' "$ledger" \
| xargs -r -n1 fleet kill --at tool-call-boundary --reason orphan-sweepThe kill switch needs two positions, and both must work without the coordinator’s cooperation: stop new spawns (cheap; use it first and often) and abort running workers (expensive; use it at the boundary). Test both on a Tuesday with nothing at stake. Interruptible coordinators goes deeper on what pause and abort must mean across CLIs.
Subagent token cost failure modes, and the signal for each
The subscription storm. A coordinator watching a busy channel or every PR spawns a worker per event, and events arrive faster than workers finish. Signal: queue depth climbing while spend velocity sits pinned at the cap. Fix: rate-limit the subscription upstream; Slack-to-agent subscriptions without a control plane covers that side.
Duplicate writers, one file. Two write workers, one target, one revert. Signal: two running ledger rows with the same task_id and overlapping file lists. Fix: write concurrency of one per file path, enforced at spawn.
The ingest cliff. The coordinator re-reads every report on every re-plan, so its context grows with the fan-out and its own turns get expensive. Signal: coordinator tokens per turn rising while worker count is flat. Fix: workers report summaries under a size cap; the coordinator reads diffs, never transcripts. The same cliff appears one level down when a tool returns a huge payload on every turn; bytes_returned at the tool meter dominating tokens_in at the worker meter is the signal, and a payload cap at the tool layer is the fix.
Budget met, work not done. The task hits its ceiling with half the files migrated. This is the system working. Signal: on_exceeded: pause_spawns fired and the page arrived. Response: a human reads the ledger, then raises the budget with a name attached or kills the task. The paging side is its own piece: cost anomaly alerts for agent fleets.
No cap because the vendor has no cap. The coordinator’s product exposes no ceiling, so the desk has none. Signal: you cannot answer “what is the most this Project can spend by noon.” Fix: the wrapper, the account limit, or the decision to keep that coordinator off that work; when not to use a fleet coordinator makes the case.
The meter is operating-layer infrastructure, not a smarter prompt
Nothing above is a prompt. A coordinator told to be frugal will be frugal until the work argues otherwise, and the work always argues. Caps, budgets, ledgers, and kill switches live outside the model, in the layer that runs the fleet: the wrapper around spawn, the policy file the coordinator reads but cannot edit, the sweep on a timer, the pager. That layer is what a multi-agent command center is once you strip the dashboard off it, and no vendor’s usage view supplies it, because the view sees one vendor’s sessions and your fleet has several.
Fan-out is a good idea with a slope of one. Meter the slope, cap the velocity, and let the coordinator spend inside a box you drew.
FAQ: subagent token cost and fan-out controls
How do I cap subagent token cost?
Set both a per-task dollar budget and a concurrency ceiling outside the coordinator. Log each spawn with its parent, role, model, tokens, spend, and state. Stop new spawns when either limit trips, then let running write workers reach the next tool-call boundary before killing them.
What should a subagent spawn ledger record?
Record the spawn and parent IDs, task and role, model and host, budget and actual spend, input and output tokens, tool calls, last activity, state, kill actor, and the coordinator’s one-line reason. Those fields expose cost velocity, orphaned workers, and duplicate work without reading every transcript.
Sources
- Cursor: Introducing Projects — Sep 10, 2026; the coordinator runs “as many in parallel as the work needs”
- Cursor changelog — “Cursor Projects” (Sep 10, 2026); “Cloud Agents and Cursor Harness Improvements” (Aug 19, 2026)
- OpenAI: Introducing the Agents API — public beta Sep 10, 2026
- OpenAI Agents API docs overview — subagents; model, tool, and container billing
- Claude Docs — subagent
tools,disallowedTools, andmodelcontrols - Cursor (@cursor_ai), Projects launch post on X (Sep 10, 2026)
