C:/Program Files/Git/clear silently carries over an exhausted subagent budget, with no indication anywhere

Summary

When /clear carries the subagent spawn budget over into the new conversation, nothing tells the user. The new conversation silently starts at 200 of 200, and every Agent call fails for the rest of its life. In my case this went unnoticed for over a day.

The carry-over itself is documented and intentional — sub-agents.md says:

Run /clear to reset the count and start a new conversation with the full budget. If work that can still spawn subagents survives the clear, such as a running workflow, the count carries over instead.

The problem is not the rule. The problem is that it is invisible at every point where the user could act on it.

What happened

Claude Code 2.1.223, Windows 11, no CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION override (default 200).

1. A heavy session made ~190 Agent calls and hit Subagent spawn limit reached (200 of 200 agents spawned).
2. I ran /clear about two minutes after the last tool activity. A new session was created one second later.
3. That brand-new session made exactly two Agent calls in its entire lifetime. Both failed with Subagent spawn limit reached (200 of 200 agents spawned) — the second one over 24 hours after the clear.

So the new conversation was born already exhausted and stayed that way. From the user's side, /clear appeared to work normally: fresh context, no warning, no message. The only symptom was that agents mysteriously stopped working, in a conversation that had barely used any.

I only found the cause by reading the session transcripts afterwards and correlating timestamps.

Why this is worth fixing

• /clear is a routine, high-frequency command whose entire promise is "start fresh". Silently inheriting an exhausted budget contradicts that promise.
• The condition that triggers carry-over — background work still alive at clear time — is not visible in the UI at the moment you type /clear. There is no prompt, and no reason for the user to suspect anything.
• After the fact there is no indicator either. A new conversation gives no way to see "your remaining budget is 0 / 200".
• The failure is easy to misattribute. My first assumption was a plan-level usage limit, then a bug in the cap being process-scoped. Both wrong. Nothing in the error message hints that a previous conversation's spend is responsible.
• The longer a session lives, the worse it gets. With Remote Control the local session can stay alive for days, so a single carry-over can poison a very long stretch of work.

Proposal

Roughly in order of preference — the first one alone would have prevented this entirely:

1. Warn at /clear time. If work that can still spawn subagents is alive, say so and offer a choice: wait for it, stop it, or clear anyway and accept the carry-over. Non-destructive, and it puts the decision where the user can actually make it.
2. Surface the inherited budget in the new conversation. If a clear carries the count over, state it once at the start of the new conversation (e.g. "Subagent budget carried over: 200 / 200 used").
3. Make the exhausted state inspectable on demand, e.g. include remaining budget in /status or /context, so the state is discoverable without reading transcripts.
4. Mention the carry-over in the error message. Subagent spawn limit reached (200 of 200 agents spawned) could add "(carried over from a previous conversation)" when that is why the count is where it is.

I would specifically argue against simply having /clear terminate all background work by default. Background agents have real side effects — file writes, commits, network calls — and killing them mid-flight to reclaim a counter trades a recoverable annoyance for potentially unrecoverable partial state. Making the situation visible is the safer fix.

Environment

• Claude Code 2.1.223
• Windows 11
• Defaults for CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION (200), CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (20), CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (3)

Related: #78406 documents that CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION is missing from the environment-variable reference. That is a separate documentation gap; this issue is about the runtime behavior being unobservable.