Skip to main content
plugin

subagent-spawn-cap — Claude Code plugin: subagent spawn budget

subagent-spawn-cap counts subagent spawns per session: asks at 20, asks again every 10, refuses at 60. Puts back the cap Claude dropped in 2.1.224.

MIT ★ 586 updated 2026-10-26

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add karanb192/claude-code-hooks
/plugin install subagent-spawn-cap@claude-code-hooks
Open on GitHub

What subagent-spawn-cap does

The plugin adds a PreToolUse hook to the Agent tool, called Task in older builds. Every spawn appends a line to the session ledger, and the line count is the budget spent. Spawn 20 returns ask, then every 10 spawns after, and spawn 60 returns deny.

The ledger sits at ~/.claude/subagent-spawn-cap/<session_id>.jsonl and only ever grows. That append-only shape is deliberate: parallel calls in one turn start parallel hook processes, and a counter that reads then writes would lose entries. A denied spawn is never recorded, while an asked one is written before you answer, so declining still costs a unit. Nested spawns inside subagents carry the parent's session_id, so a fan-out within a fan-out draws on the same budget.

Thresholds are SPAWN_CAP_ASK, SPAWN_CAP_ASK_STEP and SPAWN_CAP_DENY, read from the env block of settings.json; change them and restart, a malformed value falls back to the default. Headless claude -p without a permission host, and dontAsk mode, turn any prompt into a refusal, so on defaults an unattended run stops at spawn 20 rather than 60 — set SPAWN_CAP_ASK equal to SPAWN_CAP_DENY for CI. Only spawns through Agent are seen, and the ledger is a plain file an agent with Bash could delete.

What it helps with

  • stop a fan-out that keeps spawning subagents in a loop
  • put a fixed ceiling on spawns for a long session
  • count spawns again after the native per-session cap was removed in 2.1.224
  • keep a CI run inside a known spawn budget
  • read back how many subagents a session actually launched

Example prompts for the agent

  • Split the refactor across subagents, one per module
  • Fan out a subagent per package and merge the reports
  • Keep going in this session, the spawn budget isn't spent yet

How to install subagent-spawn-cap

Plugin marketplace

/plugin marketplace add karanb192/claude-code-hooks
/plugin install subagent-spawn-cap@claude-code-hooks

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about subagent-spawn-cap

How do I install subagent-spawn-cap in Claude Code?

Add the marketplace first: /plugin marketplace add karanb192/claude-code-hooks. Then install the plugin: /plugin install subagent-spawn-cap@claude-code-hooks. Restart Claude afterwards.

What does subagent-spawn-cap do?

It keeps a per-session count of subagent spawns, interrupts at 20, asks again every 10 after that, and blocks at 60. Spawns started from inside a subagent count against the same budget.

Does it work alongside guard-pack?

guard-pack already ships this guard, so running both adds nothing. Pick one.

Source text

subagent-spawn-cap · MIT
# subagent-spawn-cap

> A total-spawns-per-session budget for subagents: asks from spawn 20, again every 10, denies at 60, counted across nested fan-outs. The cap Claude Code shipped in 2.1.212 and removed in 2.1.224, back as a hook you control.

A `PreToolUse` hook on the `Agent` tool (older name `Task`). Every spawn in a session appends one line to a per-session ledger; the line count is the budget spent. Spawn `SPAWN_CAP_ASK` (default 20) prompts you, then every `SPAWN_CAP_ASK_STEP` spawns (default 10) prompts again, and spawn `SPAWN_CAP_DENY` (default 60) is denied. Hooks also fire inside subagents ([`agent_id` / `agent_type`](https://code.claude.com/docs/en/hooks#common-input-fields)) with the parent's `session_id` (observed in local subagent transcripts; the docs do not state it), so nested fan-outs share the budget.

**Why:** Claude Code had this cap natively from 2.1.212 ("Added a per-session cap on subagent spawns (default 200, override with `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION`)") to 2.1.224 ("Removed the 200-subagent-per-session spawn cap; long-running sessions no longer refuse new agents (concurrency and depth limits still apply)"), per the [CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md). The remaining native caps bound the rate (20 concurrent) and depth, not the total, which is the shape of [#92349](https://github.com/anthropics/claude-code/issues/92349) (325 agents for a settings audit), [#91942](https://github.com/anthropics/claude-code/issues/91942) (160 subagents, session limit exhausted), [#69206](https://github.com/anthropics/claude-code/issues/69206) (218 spawned, about 10 intended) and [#69578](https://github.com/anthropics/claude-code/issues/69578) (recursive loop, about 800k tokens).

## Install

```
/plugin marketplace add karanb192/claude-code-hooks   # once per machine
/plugin install subagent-spawn-cap@claude-code-hooks
```

Restart Claude Code, done. Already running [guard-pack](../guard-pack)? It includes this guard; do not install both.

## What it does

| Event | Matcher | What happens |
|-------|---------|--------------|
| PreToolUse | `Agent\|Task` | Counts the session's ledger lines plus this call. At `SPAWN_CAP_ASK` and every `SPAWN_CAP_ASK_STEP` after it: appends, returns `"ask"`. At or above `SPAWN_CAP_DENY`: returns `"deny"`, no append. Otherwise: appends, returns `{}`. Other tools: `{}` with no filesystem work. |

Per the [hooks reference](https://code.claude.com/docs/en/hooks#pretooluse-decision-control) an `ask` reason is shown to you and a `deny` reason to Claude, so the two texts have different readers. What you see in the permission prompt at spawn 20:

```
⚠️ [spawn-cap] Subagent spawn #20 in this session (ask threshold SPAWN_CAP_ASK=20, next check at #30, hard cap SPAWN_CAP_DENY=60). Approve to continue; the next 9 spawns then pass without asking. Deny to stop the fan-out. Reset this session's count by deleting ~/.claude/subagent-spawn-cap/<session_id>.jsonl; change the cadence via SPAWN_CAP_ASK / SPAWN_CAP_ASK_STEP in the settings.json env block (restart needed).
```

What Claude sees at spawn 60:

```
🚨 [spawn-cap] Subagent spawn #60 in this session hit the hard cap (SPAWN_CAP_DENY=60). Do not retry: finish with the results you already have and tell the user the session's spawn budget is spent. The user can reset it by deleting ~/.claude/subagent-spawn-cap/<session_id>.jsonl, or raise SPAWN_CAP_DENY in the settings.json env block and restart.
```

## Configuration

Hook processes inherit the environment Claude Code was launched with: set these in the `env` block of `settings.json` and restart. Invalid values fall back to the default.

| Variable | Default | Purpose |
|----------|---------|---------|
| `SPAWN_CAP_ASK` | `20` | First spawn number that prompts. Positive integer. |
| `SPAWN_CAP_ASK_STEP` | `10` | Prompt again every this many spawns after `SPAWN_CAP_ASK`; `1` prompts on every spawn. Positive integer. |
| `SPAWN_CAP_DENY` | `60` | Spawn number denied outright. Clamped up to `SPAWN_CAP_ASK` if set lower; equal to it skips the ask stage. |
| `SPAWN_CAP_ALLOW` | unset | The literal string `true` lets spawns through past both thresholds while set; each is still recorded and logged `ALLOW_OVERRIDE`. |

`HOOK_SAFETY_LEVEL` is not read: the repo's levels pick pattern sets, a budget is a number, and a hidden level-to-number table would move your budget whenever you tune the level for another guard.

**Unattended runs.** In `claude -p` with no permission host and in `dontAsk` mode, anything that would prompt is denied ([headless reference](https://code.claude.com/docs/en/headless)), so the ask threshold is the effective hard stop: with the defaults an unattended session ends at spawn 20, not 60. Set `SPAWN_CAP_ASK` equal to `SPAWN_CAP_DENY` for CI so Claude gets the deny text it can act on.

## State

One append-only JSONL per session at `~/.claude/subagent-spawn-cap/<session_id>.jsonl`, one line per allowed or asked spawn (`ts`, `n`, `decision`, `subagent_type`, `description` truncated to 80 chars, plus `agent_id` / `agent_type` inside subagents). Append-only because parallel tool calls in one turn fire parallel hook processes; `O_APPEND` writes survive that, a read-modify-write counter does not. Denied calls are not written. An asked call is written before you answer, so a declined ask still consumed one budget unit. Ledgers untouched for 7 days are pruned, at most once a day. Delete a session's file to reset its budget. Verdicts, `ALLOW_OVERRIDE` bypasses and config warnings go to `~/.claude/hooks-logs/`; the ledger never stores the prompt; no network calls.

## Known limits

- Only spawns through the `Agent` tool are seen; a Workflow script or other non-tool path is invisible to `PreToolUse`.
- Counts key on `session_id`, so a resumed session continues its count.
- Parallel calls in one turn each read the count before any appends; a batch can overshoot a threshold by up to the native concurrency limit, and the next call is judged on the full count.
- The ledger is a plain file; an agent with Bash could delete it. [config-guard](../config-guard) does not cover that directory yet.
- Session ids are sanitised to `[A-Za-z0-9._-]` for the file name (real ids are UUIDs); `O_APPEND` atomicity holds on macOS and Linux, Windows makes no cross-process guarantee.

## Uninstall

```
/plugin uninstall subagent-spawn-cap@claude-code-hooks
```

Part of [claude-code-hooks](https://github.com/karanb192/claude-code-hooks).

© Karan Bansal · MIT · karanb192/claude-code-hooks

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set28

The whole set →
session-logger session-logger is a Claude Code plugin that keeps a Markdown record of each session. Its hooks track the repository, touched file paths, and Bash commands. ★ 586repo stars format-code format-code — a PostToolUse hook that formats each file right after Claude writes or edits it: ruff for Python, prettier for JS, TS, JSON, MD, YAML and HTML. ★ 586repo stars auto-stage auto-stage stages modified files in Git automatically whenever Claude Code writes or edits them, keeping pre-commit reviews clean without manual git add calls. ★ 586repo stars config-watch config-watch makes every mid-session change to settings or skills visible in the session, or blocks it outright. Aimed at installers and npm scripts that rewrite config while the agent works. ★ 586repo stars config-guard config-guard — a PreToolUse hook that stops the agent from rewriting the files holding its own guardrails: settings, hook scripts, plugin manifests. Reads pass. ★ 586repo stars case-insensitive-guard case-insensitive-guard is a Claude Code plugin that blocks destructive Bash commands aimed at a path with a different letter case. It checks commands such as rm -rf before they run. ★ 586repo stars protect-tests protect-tests blocks the "fake green" trap: stops the agent from deleting, renaming, or skipping tests instead of fixing the code. Works with pytest, jest, Go, JUnit, RSpec, and more. ★ 586repo stars git-safety git-safety — a PreToolUse Bash hook for Claude Code that intercepts destructive git and gh CLI actions before execution. ★ 586repo stars

Project sponsors

Companies that keep this analytics open