Show HN：agent-usage-guard – 針對 Claude Code 的使用視窗保護模組

阻止 Claude Code 在十分鐘內消耗你的五小時使用視窗。

agent-usage-guard 是一個 Claude Code mod：它在 Claude Code 內部執行，並在消耗發生前阻止過度消耗。它會讀取你計畫的即時使用量，並限制子代理的分發、過載大量上下文與重試迴圈。

_{錄製自已載入守衛的 Claude Code 互動式 UI。指令碼化本機 API 取代 Claude，故會議與令牌計數皆為模擬，並未實際消耗使用量。螢幕上每個問題皆為守衛自行產生。從 Northstar fixture 重新建構它。}

它在消耗前執行，而非之後：在代理開始、提示被送出或工具呼叫執行前。代理限制跨越你機器上所有 Claude Code 會話，分發與大量上下文均在任何使用層級被限制，而非僅在接近上限時。當你在鍵盤前時，它會以 Claude Code 自己的問題對話方塊詢問你。若沒有人能回答，它會拒絕並告知 Claude 原因，讓模型可等待、批次處理或停止。/agent-guard report 展示其執行情形。

計畫感知。它會讀取 Claude Code 報告的 5 小時與每週百分比，並為你保留視窗結尾。
一次回答可覆蓋一段時間。獲得批准後，其條件會解除，直至清除或逾時，避免同一問題一次次被重新呼叫。
本機且隱私最小。不使用網路，也不啟動額外程序。它只儲存計數與粗略分桶，永不儲存提示文字、工具輸入或模型輸出。
失效時保持開放。若其某個掛鉤失敗，事件仍繼續：損壞的守衛不會中斷你的會話。唯一例外是無法及時判斷的代理，將被拒絕，讓 Claude 重新啟動。

安裝

在 Claude Code v2.1.287 或更新版本中執行以下指令：

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

接著執行 /agent-guard 以檢視其觀察結果。模組預設為啟用；概覽列出停用它們的設定。

為何存在此功能

某個下午，我以最大努力給 Claude Code 一個研究提示。它產生了 394 個子代理呼叫，其中 341 個同時執行，並在十分鐘內透過 API 推送 84M 上下文令牌。會話結束："Claude usage limit reached."直到視窗重置才解除鎖定。

那並非一次性事件。六十天的個人日誌顯示 12 次鎖定 以及 166 個十分鐘視窗內的代理激增。失效模式呈乘法關係：大量上下文 × 快速工具迴圈 × 並行代理 × 盲目重試。以下每項保護都能消除一個因素。

而且不只是我：單一提示產生 339 個子代理，每週 Max 計畫的一半被遞迴產生消耗，以及多代理執行使用約 15 倍於聊天會話的令牌。

功能說明

區域	規則	預設	發生情況
計畫視窗	當視窗滿到此程度時，新代理需要批准	80%	詢問；批准持續至視窗重置
	當視窗已滿時，新的代理程式將被拒絕	95%	拒絕
	當 5 小時視窗快速升高時，新的代理程式需要審批	20 分 / 10 分鐘	詢問
代理程式	同時執行的代理程式，跨越此機器上的所有會話	4	詢問
	每 10 分鐘啟動或恢復的代理程式，跨越此機器	12	詢問
	每 10 分鐘子代理程式處理的 tokens，跨越此機器	10M	詢問
	子代理程式不得自行啟動代理程式	深度 1	拒絕
上下文	Claude 被告知一次保持回合有限	300k tokens	在提示中加入備註
	一個會重新閱讀這麼多上下文的提示	500k tokens	詢問：先壓縮再送，直接送，或取消
	在對話或代理執行此量時，每 10 分鐘的工具呼叫次數	20 次呼叫，400k	詢問：繼續、此回合後壓縮，或停止
	一個繁重的會話閒置足夠長，使其提示快取過期	150k 代幣，1 小時閒置	在重新寫入快取前詢問
迴圈	同一工具呼叫反覆失敗，且之間沒有其他呼叫	3 次相同失敗	拒絕相同的重試
	在 10 分鐘內被拒絕的代理呼叫	5	暫停代理產生 10 分鐘

代理涵蓋子代理、代理團隊隊友、工作流程代理，以及使用 SendMessage 重新啟動的已完成子代理。每一次工具呼叫都根據產生它的迴圈上下文來判斷，因此小型子代理永遠不會繼承主對話的大小。

當它詢問時。 詢問出現在 Claude Code 自己的對話方塊中，即 Claude 用來向你提問的那個，並且呼叫會等待你的回答。當它開啟時，並行啟動的代理會被暫停，Claude 會在你回答後再次啟動它們。如果你允許，該條件會保持一段時間：計畫視窗直到重置、繁重語境直到縮小（對工具呼叫最多一小時）、代理計數持續 10 分鐘。若你拒絕或忽略該問題，Claude 會被告知在接下來的 10 分鐘內不要啟動代理（AGENT_GUARD_WINDOW_SECONDS），並且在此期間不再詢問。鍵入的文字會送到 Claude，因此你可以回答「use haiku agents instead」

當沒有人能回答時。 在 claude -p、Agent SDK 與 dontAsk 模式下，代理或工具閘口會拒絕而非詢問。繁重提示會附帶原因被保留，同樣地，當機器全域每 10 分鐘上限達到時，休眠的繁重續行也會被保留。Claude 將每一次拒絕視為工具的結果。相同條件的重複拒絕會以不同措辭表達並升級：第二次說未改變並嘗試其他方式，第三次說結束此回合。若像 /goal 這樣的停止鉤子持續重新開啟回合，拒絕會說使用者必須決定。

它不會處理什麼。 它永遠不會保留背景任務的通知或其他會話的訊息，因為那樣會遺失結果。它不再在使用上限後阻塞提示：自 v2.1.234 起，Claude Code 在達到限制時會等待，並在重置時自行繼續（autoContinueAtUsageLimit）。守衛的工作是防止你達到上限，其日誌會統計未能阻止的鎖定。

命令

/agent-guard [status]                          what the guard sees right now
/agent-guard allow [agents|context] [minutes]  lift its limits for this session (default: all, 10 min)
/agent-guard pause [minutes]                   the same as allow, for every limit
/agent-guard resume                            end an allow early, lift the agent pause, and let declined questions ask again
/agent-guard report [days]                     what it did on this machine (default: 7 days)
/agent-guard help                              these commands

/agent-guard 立即執行，即使在回合中途，也永遠不會啟動模型回合，因此 Claude 永遠不會看到覆寫，也無法將其視為授權。單獨以提示方式傳送 [allow-usage-guard] 或 [allow-agent-burst]，即舊版標記，與傳送 /agent-guard allow 或 allow agents 的效果相同。

它能看到與不能看到的專案

以 Claude Code v2.1.295 為基準檢查：

路徑	覆蓋率
子代理、隊友與工作流程代理	在啟動前被保留（`agent.spawn`）
已完成的子代理使用 `SendMessage` 傳送新工作	在恢復前被保留，並計為一次啟動
`/subtask` 分支，以及任何未使用 `agent.spawn` 啟動的專案	在啟動時計數，從未被保留：Claude Code 在它們啟動前不提供任何事件。透過 Agent 工具啟動的分支會像任何代理一樣被保留
Claude Code 的內部代理（提示建議、壓縮）	未計數
計畫視窗百分比	來自訂閱的最後一次 API 回應，同樣在 `claude -p`。API 金鑰會話不報告任何值，因此只適用代幣與計數預算
在各自終端窗格中執行的隊友	不可見：他們的迴圈在其他程序中執行
其他機器上的會話	未計數：跨會話記錄存於此機器的模組儲存區
API 自行執行的工具，例如顧問	無法保持：沒有工具事件為其觸發

Mods 會在 claude 的終端機、桌面應用程式的 Code 分頁、claude -p 與 Agent SDK 執行。它們不會在桌面應用程式的 WSL 會話中執行（mods 執行的位置）。

本機限制仍然有效。 Claude Code 將一個會話限制為 20 個同時執行的子代理（CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS）和三層巢狀（CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH）。它對一個會話啟動的代理總數沒有上限。Guard 的預設更嚴格，跨會話；本機上限仍是 Guard 只計算的路徑的外牆。

檢視它執行了什麼

/agent-guard report 30

報告統計使用限制鎖定（每個被鎖定的視窗一次）、計畫視窗閾值穿越，以及每個按規則的問題與拒絕，並記錄您的回答。它會讀取此機器上每個會話的日誌，且永不離開。設定 AGENT_GUARD_JOURNAL=0 以停止記錄。

安全與隱私

一個 mod 在 Claude Code 內以您的許可權執行；在安裝前先閱讀 mod 可存取的範圍。此 mod 約 2,400 行 TypeScript，無任何相依性，且 claude plugin validate . 列出它呼叫的每個 API 及讀取的環境變數：

它不會傳送任何網路請求，也不會啟動任何程序。
它僅決定上述規則所描述的事項：代理是否啟動、提示是否傳送、工具呼叫是否執行。當您能回答時會詢問您，拒絕時會給出理由。它會讀取許可權模式但不會更改，亦不會寫入任何設定。
它唯一提交的提示是您自己的：在「Compact, then send」之後，它會在壓縮完成後送出您輸入的提示，保持不變。
它的提示掛鉤將您的提示保持不變，並在上下文超過 300k 時為 Claude 加上一筆一次性備註，或先保留提示以先詢問您（當沒有人能回答時，它會說明原因）。其 SessionStart 掛鉤不做任何更改。
它將狀態儲存在 mod 儲存區，一個位於 ~/.claude/plugins/store/ 的 JSON 檔案。每個會話會寫入自己的計數（執行中的代理、最近啟動與休眠恢復、每分鐘子代理代幣、最新 5 小時讀取），以及最後一次活躍時間（保留 30 天，讓恢復的會話知道空閒了多久），以及其日誌列（時間、會話 ID 字首、規則、工具名稱、上下文桶如 400-500k、計畫視窗與百分比、拒絕編號與您的回答）。
它從不儲存提示文字、工具輸入、錯誤文字或模型輸出。工具呼叫被縮減為 13 個字元的指紋。代理名稱保留在記憶體中，永不寫入。
日誌中超過 90 天的日期會被刪除（AGENT_GUARD_JOURNAL_DAYS）。
demo/，負責建立上方的 GIF，並非執行的一部分。它會在一個臨時主目錄中啟動 Claude Code，使用虛構的 API 金鑰來呼叫指令碼化的本機 API，且不會讀取任何您的憑證。

設定 AGENT_GUARD=0 以在不解除安裝的情況下關閉它。

設定

將這些設定為環境變數，或在 env 的 ~/.claude/settings.json 下設定。時間以秒為單位；若值不是範圍內的數字則保留預設，/agent-guard 會說明。

變數	說明（預設）
`AGENT_GUARD`	`0`、`false`、`off` 或 `no` 會關閉 Guard（`1`）
`AGENT_GUARD_JOURNAL`	`0` 停止日誌 (`1`)
`AGENT_GUARD_JOURNAL_DAYS`	保留日誌天數 (`90`)
`AGENT_GUARD_WINDOW_SECONDS`	預算、消耗與拒絕的滾動視窗 (`600`)
`AGENT_GUARD_AGENT_MAX`	此機器同時執行的代理數量 (`4`)
`AGENT_GUARD_ROLLING_MAX`	此機器每個視窗的代理啟動與恢復次數 (`12`)
`AGENT_GUARD_AGENT_TOKENS_MAX`	此機器每個視窗的子代理令牌數 (`10000000`)
`AGENT_GUARD_DEPTH_MAX`	主對話之下的代理層數 (`1`)
`AGENT_GUARD_LIMIT_ASK_PERCENT`	新代理詢問的計畫視窗百分比 (`80`)
`AGENT_GUARD_LIMIT_DENY_PERCENT`	新代理被拒絕的計畫視窗百分比 (`95`)
`AGENT_GUARD_BURN_PERCENT`	每個 5 小時視窗使新代理詢問的點數 (`20`)
`AGENT_GUARD_CONTEXT_WARN`	Claude 被告知一次保持回合限制的上下文 (`300000`)
`AGENT_GUARD_CONTEXT_HARD`	提示傳送前詢問的上下文 (`500000`)
`AGENT_GUARD_TOOL_CONTEXT`	工具呼叫計入工具預算的上限上下文 (`400000`)
`AGENT_GUARD_TOOL_MAX`	在該上下文之上每個視窗的工具呼叫數量 (`20`)
`AGENT_GUARD_DORMANT_SECONDS`	閒置時間，超過後重型會話的快取被視為過期 (`3600`)
`AGENT_GUARD_DORMANT_CONTEXT`	閒置會話被視為重型的上下文 (`150000`)
`AGENT_GUARD_DORMANT_MAX`	此機器上無人可詢問時，每個視窗的重型休眠恢復數量 (`1`)
`AGENT_GUARD_TOOL_FAILURE_MAX`	相同失敗次數，超過後相同重試被拒絕 (`3`)
`AGENT_GUARD_FUSE_MAX`	每個熔斷期被拒絕的代理呼叫數，觸發暫停 (`5`)
`AGENT_GUARD_FUSE_SECONDS`	熔斷期間以及暫停持續時間 (`600`)
`AGENT_GUARD_PEER_TTL_SECONDS`	另一個會話的計數，或無活動跡象的代理，仍算入的時間 (`900`)

休眠預設假設訂閱在方案使用內可獲得的一小時提示快取。若使用 API 金鑰或額外使用，快取持續五分鐘，請設定 AGENT_GUARD_DORMANT_SECONDS=300。

超出 Claude Code

規則存在於與 harness 無關的核心 (core/)，該核心不執行任何 I/O。Claude Code 模組是其第一個介面卡。docs/architecture.md 描述了介面卡所維持的協議，以及另一個代理 harness 必須提供以執行每個規則的內容。

測試

claude plugin validate . --strict
claude plugin test

claude plugin test 在 Claude Code 自己的測試套件中執行測試：核心的單元測試，以及透過 hooks 模組觸發真實 Claude Code 事件、無會話、模型或網路的測試。TESTING.md 覆蓋了各層級以及每個測試所證明的內容。

授權

MIT