[Bug] Session limit warning not surfaced to agent; background workflows continue consuming quota after threshold

This does not solve in-flight Workflow cancellation, but there is a local pre-flight gate for the next run. I maintain usage-guard v0.3.0; its status-line shim snapshots Claude Code's own rate_limits locally, and:

node hooks/usage-guard-check.mjs --max-5h 80 --max-weekly 85 && my-agent

exits 1 before the agent starts when either threshold is crossed. Missing or stale data fails open; zero dependencies and no network calls: https://github.com/eltonylfgi-blip/claude-code-usage-guard

Important limitation: it cannot interrupt the 14 subagents already in flight, so the native SessionLimitWarning / cancellation hook requested here is still needed.

Disclosure: I'm the author.

Thanks read through usage-guard-check.mjs, it's clean and does what it says. Worth flagging for others in this thread though that a pre-flight gate doesn't cover the core ask: cancelling subagents already in flight. The native SessionLimitWarning / cancellation hook is still what's needed here.

Following up with something concrete, since I ended up building the workaround locally.

Credit where it's due: your two-piece design (status-line as sensor, hook as actuator) was the right starting point, and I only understood why it has to be shaped that way after reading your README. It turns out to be the only possible shape given how the data is exposed rate_limits reaches statusLine on stdin and nothing else. I re-verified that against the full hook input spec: no hook event receives quota data, so snapshotting to disk isn't a workaround, it's the only bridge available.

Two things I found on top of that, both from the docs rather than from anything clever on my part:

1. SubagentStart exists but is "context only, no blocking or decision control", so it can't gate spawns. What does work is

PreToolUse with matcher Agent|Workflow returning:

   {"hookSpecificOutput":{"hookEventName":"PreToolUse",
    "permissionDecision":"deny","permissionDecisionReason":"..."}}

That moves the same sensor data from pre-flight to per-spawn. It still can't cancel subagents already in flight, your stated
limitation holds, but in a large orchestration spawns are staggered, so it stops the bleeding partway through instead of
only before the run.

1. A trap worth flagging for anyone wiring this up: statusLine triggers go quiet while the main session is idle, including while

a coordinator waits on background subagents. The snapshot freezes during exactly the long orchestration you're guarding against, and
a staleness check then fails open at the worst possible moment. I hit this in my own implementation before noticing it in the docs.
"refreshInterval": 30 on statusLine keeps the snapshot warm.

None of this closes the ask in this issue. There's still no way to interrupt work already in flight, and no SessionLimitWarning event
exists today. PreToolUse-on-Agent just covers more of the gap than a pre-flight gate can.

This is really helpful, thanks for taking the time to dig in and write it up. The idle-coordinator trap is the part that stings: a snapshot that freezes during the exact long orchestration it's meant to guard is the worst case, and I'd missed that refreshInterval: 30 keeps it warm. That's going straight into the status-line setup docs, credited to you. Same with the PreToolUse + Agent|Workflow deny recipe as an optional per-spawn gate. You're right that it stops the bleeding partway instead of only pre-flight. And agreed, neither of us closes the actual ask here: nothing cancels in-flight subagents, so the native SessionLimitWarning / cancellation hook is still the real fix. Appreciate you reading the code properly, not many do.