agent-usage-guard 发布拦截 Claude Code 超额消耗

原标题：Show HN: agent-usage-guard – a Claude Code mod to protect your usage window

68AI 研判分

核心综述

开源工具 agent-usage-guard 作为 Claude Code 插件，通过实时监控用量并在代理启动前拦截高成本操作（如子代理扇出、重试循环），防止用户快速耗尽 5 小时使用窗口。该工具支持计划感知与自动拒绝策略，旨在优化资源分配而非事后补救。

报道全文原始报道全文

本文目录3 个章节

Stops Claude Code from spending your five-hour usage window in ten minutes.

agent-usage-guard is a Claude Code mod: it runs inside Claude Code and holds runaway spend before it happens. It reads your plan's live usage, and it holds subagent fan-out, heavy-context churn and retry loops.

Recorded from Claude Code's interactive UI with the guard loaded. A scripted local API stands in for Claude, so the sessions and token counts are staged and no usage is spent. Every question on screen is the guard's own. Rebuild it from the Northstar fixture .

It acts before the spend, not after it: before an agent starts, a prompt is sent, or a tool call runs. Agent limits hold across every Claude Code session on your machine, and fan-out and heavy context are capped at any usage level, not only near the limit. When you are at the keyboard it asks you, in Claude Code's own question dialog. When nobody can answer, it refuses and tells Claude why, so the model can wait, batch the work, or stop. /agent-guard report shows what it did.

Plan-aware. It reads the 5-hour and weekly percentages Claude Code reports, and keeps the end of the window for you.
One answer covers a while. An approval lifts its condition until it clears or times out, so the same question does not come back call after call.
Local and privacy-minimal. No network, no processes. It stores counts and coarse buckets, never prompt text, tool inputs or model output.
Fails open. If one of its hooks fails, the event goes ahead: a broken guard never breaks your session. The one exception is an agent it could not judge in time, which is refused so that Claude starts it again.

Install

Run these commands inside Claude Code v2.1.287 or later:

TEXT

/plugin marketplace add rbartoli/agent-usage-guard
/plugin install agent-usage-guard@agent-usage-guard
/reload-plugins

Then run /agent-guard to see what it sees. Mods are on by default; the overview lists the settings that turn them off.

Why this exists

One afternoon I gave Claude Code a research prompt at max effort. It spawned 394 subagent calls, 341 of them running at once, and pushed 84M context tokens through the API in ten minutes. Session over: "Claude usage limit reached." Locked out until the window reset.

That wasn't a one-off. Sixty days of my own logs held 12 lockouts and 166 ten-minute windows with agent bursts. The failure mode multiplies: a large context × rapid tool loops × parallel agents × blind retries. Each protection below removes one factor.

And it's not just me: 339 subagents from a single prompt, half a weekly Max plan consumed by recursive spawning, and multi-agent runs using ~15× the tokens of a chat session.

What it does

Area	Rule	Default	What happens
Plan windows	New agents need approval once a window is this full	80%	asks; approval lasts until that window resets
	New agents are refused once a window is this full	95%	refuses
	New agents need approval when the 5-hour window rises this fast	20 points / 10 min	asks
Agents	Agents running at once, across every session on this machine	4	asks
	Agents started or resumed per 10 minutes, across this machine	12	asks
	Tokens processed by subagents per 10 minutes, across this machine	10M	asks
	Subagents may not start their own agents	depth 1	refuses
Context	Claude is told once to keep the turn bounded	300k tokens	adds a note to the prompt
	A prompt that would re-read this much context	500k tokens	asks: compact then send, send anyway, or cancel
	Tool calls per 10 minutes while a conversation or agent carries this much	20 calls at 400k	asks: keep going, compact after this turn, or stop
	A heavy session idle long enough for its prompt cache to expire	150k tokens, 1 h idle	asks before re-writing the cache
Loops	The same tool call failing again and again, with no other call in between	3 identical failures	refuses the identical retry
	Refused agent calls within 10 minutes	5	pauses agent spawns for 10 min

Agents covers subagents, agent-team teammates, workflow agents, and finished subagents resumed with SendMessage. Each tool call is judged on the context of the loop that makes it, so a small subagent never inherits the main conversation's size.

When it asks. The question appears in Claude Code's own dialog, the one Claude uses to ask you something, and the call waits for your answer. Agents started in parallel while it is open are held back, and Claude starts them again once you answer. If you allow it, that condition stays allowed for a while: a plan window until it resets, a heavy context until it shrinks (for tool calls, an hour at most), the agent counts for 10 minutes. If you decline or dismiss the question, Claude is told not to start agents for the next 10 minutes (AGENT_GUARD_WINDOW_SECONDS), and is not asked again in that time. Typed words reach Claude, so you can answer "use haiku agents instead".

When nobody can answer. In claude -p, the Agent SDK and dontAsk mode, an agent or tool gate refuses instead of asking. A heavy prompt is held with the reason, and so is a dormant heavy resume once the machine-wide cap of one per 10 minutes is reached. Claude reads each refusal as the tool's result. Repeat refusals of the same condition are worded differently each time and escalate: the second says nothing has changed and to try something else, the third says to end the turn. If a Stop hook such as /goal keeps reopening the turn, the refusal says the user has to decide.

What it leaves alone. It never holds a background task's notification or another session's message, because that would lose the result. It no longer blocks prompts after a usage limit: since v2.1.234, Claude Code waits at a limit and continues at reset on its own (autoContinueAtUsageLimit). The guard's job is to keep you from reaching the limit, and its journal counts the lockouts it did not prevent.

（注：更多技术实现细节与完整 API 文档请查阅原项目 README）