brefledev/stop-subagent-fanout

README preview

# stop-subagent-fanout

A Claude Code hook that makes the model ask before it spawns a subagent. One prompt per spawn, and you can refuse any of them.

Left alone, a model can decide to launch a batch of subagents on its own. Each one costs tokens, and each one does work you never watched happen. Telling it "ask me first" in `CLAUDE.md` or a system prompt is a suggestion — a fresh session or a confident model steps over it. This wires the rule to something that runs whether the model cooperates or not.

If the model tries to spawn eight subagents, you get eight prompts. In an unattended run, spawns are denied by default. One environment variable lets you pre-approve a run, and the model can't set that variable itself.

## If you'd rather DIY

The gate is one small script and one hook entry. If you'd rather have your own model write it, paste the description below, (and read what it produces before you trust it).

Paste this:

> Write a Claude Code `PreToolUse` hook script called `subagent-gate.mjs` — Node, no dependencies — for the `Task`, `Agent`, and `Workflow` tools. It reads the hook JSON from stdin. Default: print a permission decision of `ask` so Claude Code prompts me before each subagent spawn. If the environment variable `SUBAGENT_GATE=allow` is set, print `allow` and skip the prompt. On any missing input or JSON parse error, exit 0 so a broken hook never wedges my tools. Append every decision to a `.subagent-gate.log` beside the script. Then wire the matching `PreToolUse` hook — matcher `Task|Agent|Workflow` — into `.claude/settings.json`, leaving my existing hooks in place.

You get the same behavior this repo ships.

## "haha tokens go brrrr"

View full repository on GitHub →