Cap sub-agent spawns with a hook, and let the cap fail open
A hook caps spawns per session, and allows them if it breaks.
SymptomA session's transcript shows sub-agents spawning sub-agents, and the token budget empties mid-session.
Sub-agents with the full tool set can spawn sub-agents of their own, and a runaway swarm drains the token budget I share with everything else. Telling an agent in prose not to spawn will not hold a limit.
So a pre-tool hook counts every agent spawn in a session and denies spawns past a fixed cap. It fires no matter which agent makes the call.
It also fails open, so any error in the hook allows the spawn. A cost guardrail should never block legitimate work. Guards on sends, CRM writes and deletes fail closed.
The agents carry their own limits too. The builder and the checker have no spawn tool. The research agent is told not to spawn, and the session cap bounds it.
Large fan-outs I intend go through a workflow runner with its own concurrency and total caps.
Watchers get a funnel instead of a swarm. Each stage costs more than the last and sees only what the earlier stage couldn't settle:
- Code prefilters by term overlap.
- A Haiku pass labels what's left.
- One Sonnet triage ranks by match strength.
- Opus audits only on a match, scoped to the affected files.
A count can't tell an intended fan-out from a runaway one, so put a person at the cap to decide whether to raise it.
Take the largest of your last 10 sessions by tokens. Count the sub-agent spawns in its transcript. Count only the tool-call records whose tool name is your spawn tool. Do not count the tool's listing or definition, which transcripts also carry. Count how many spawns came from sub-agents rather than the main session. Look in your hook config for a per-session spawn cap. Any spawn from a sub-agent with no cap behind it is a gap.
Passes ifNo sub-agent spawned another, or a per-session spawn cap in the hook config covers every spawn in the session.
Access needed:agent-transcriptslocal-config
- 01Count agent spawns per session in a pre-tool hook. Deny spawns past a fixed cap.
- 02Make a cost cap fail open: any error in the hook allows the spawn. Make guards on sends, writes and deletes fail closed.
- 03Note that hook errors and timeouts allow the call by default, per the Claude Code hooks reference. Configure fail-closed guards to block on failure.
- 04Give builder and checker agents no spawn tool.
- 05Route large intended fan-outs through a runner with its own concurrency and total caps.
- 06Put a code prefilter and a small-model labeler ahead of any large-model call in a watcher.