# 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.

By Ki Moon · 2026-07-14 · technique · current
Canonical: https://kihmoon.com/bench-notes/p/cap-swarm-fail-open/

**Symptom:** A 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.

## Check your setup (read-only)

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 if:** No sub-agent spawned another, or a per-session spawn cap in the hook config covers every spawn in the session.

**Access needed:** agent-transcripts, local-config

## If it fails (changes to make later, not part of the check)

1. Count agent spawns per session in a pre-tool hook. Deny spawns past a fixed cap.
2. Make a cost cap fail open: any error in the hook allows the spawn. Make guards on sends, writes and deletes fail closed.
3. Note that hook errors and timeouts allow the call by default, per the Claude Code hooks reference. Configure fail-closed guards to block on failure.
4. Give builder and checker agents no spawn tool.
5. Route large intended fan-outs through a runner with its own concurrency and total caps.
6. Put a code prefilter and a small-model labeler ahead of any large-model call in a watcher.

**Applies if:** An agent's tool list or config in your setup includes a tool that spawns other agents.

**Skip if:** No agent's tool list or config in your setup includes a tool that spawns agents.

Tags: agents, cost, reliability
