核心功能：事前拦截资源滥用
agent-usage-guard 是一款专为 Claude Code 设计的插件（Mod），旨在防止用户在短时间内耗尽高额使用额度。该插件在 Claude Code内部运行，能够在资源过度消耗发生前进行拦截。它通过读取套餐的实时使用情况，对子代理的扇出（fan-out）、大量上下文轮换以及重试循环实施限制。
与事后补救不同，该插件在代理启动、提示词发送或工具调用执行前介入。无论当前使用量水平如何，它都会对本机所有 Claude Code 会话中的扇出和大量上下文进行封顶。当触发限制时，插件会在 Claude Code 原生对话框中向用户请示；若无人应答，则拒绝执行并告知模型原因，促使模型等待、批量处理或停止。/agent-guard report 命令可查看操作记录。
- 感知套餐计划： 读取5小时及每周百分比使用情况，保留额度余量。
- 一次性批准机制： 获得批准后，限制在重置或超时前不再重复询问。
- 本地化与隐私保护： 无需联网，不启动额外进程。仅存储计数和粗略分类，绝不存储提示词、工具输入或模型输出。
- 故障开放（Fails Open）： 若钩子失效，事件继续执行，确保会话不被破坏。唯一例外是无法及时判断的代理，将被拒绝以促使其重启。
开发背景：避免额度瞬间耗尽
该插件源于作者的一次经历：单个研究提示词在最高努力程度下，生成了394个子代理调用（其中341个并行运行），在十分钟内消耗了8400万上下文令牌，导致“已达到 Claude 使用限制”并被锁定。过去六十天的日志显示，此类锁定发生了12次，另有166个持续十分钟的代理爆发窗口。这种故障模式由大上下文、快速工具循环、并行代理和盲目重试共同导致。
功能详解与默认规则
插件通过以下规则消除风险因素：
| 区域 | 规则 | 默认值 | 后果 |
|---|---|---|---|
| 套餐窗口 | 新代理需批准的填充比例 | 80% | 询问；批准持续至窗口重置 |
| 新代理被拒绝的填充比例 | 95% | 拒绝 | |
| 5小时窗口上升速度阈值 | 20点/10分钟 | 询问 | |
| 代理 | 本机所有会话中并发代理数 | 4 | 询问 |
| 每10分钟启动或恢复的代理数 | 12 | 询问 | |
| 每10分钟子代理处理令牌数 | 1000万 | 询问 | |
| 子代理递归深度 | 深度 1 | 拒绝 | |
| 上下文 | 保持回合有界的上下文阈值 | 30万令牌 | 添加备注 |
| 重读上下文阈值 | 50万令牌 | 询问：压缩、发送或取消 | |
| 高上下文时每10分钟工具调用数 | 20次 @ 40万 | 询问：继续、压缩或停止 | |
| 重型会话缓存过期条件 | 15万令牌，空闲1小时 | 重写前询问 | |
| 循环 | 相同工具调用失败次数 | 3次 | 拒绝重试 |
| 10分钟内被拒绝的代理调用数 | 5 | 暂停生成10分钟 |
交互逻辑： 问题出现在 Claude Code 原生对话框中。若用户允许，条件在一段时间内保持宽松（如套餐窗口直至重置，代理计数维持10分钟）。若拒绝或忽略，Claude 将在接下来10分钟内不启动代理，且不再询问。用户可通过输入字符（如“改用 Haiku 代理”）进行响应。
无人应答处理： 在 claude -p、Agent SDK 和 dontAsk 模式下，直接拒绝而非询问。拒绝信息会逐级升级，指出必须由用户决定。
不干预内容： 不阻止后台任务通知或其他会话消息。自 v2.1.234 起，Claude Code 会在达到限制时自动等待重置，插件职责是避免达到该限制。
命令与可见性
常用命令包括：/agent-guard [status] 查看状态，/agent-guard allow 解除限制，/agent-guard pause 暂停所有限制，/agent-guard resume 恢复限制，/agent-guard report [days] 显示记录。
针对 Claude Code v2.1.295 测试的覆盖范围：
- 拦截： 子代理、队友、工作流代理及通过
SendMessage恢复的子代理。 - 不计入/不可见： Claude Code 内部代理（如提示建议）、各自终端窗格中运行的队友、其他机器上的会话、API自行运行的工具。
- 部分支持：
/subtask分叉等非agent.spawn启动的操作仅计数不拦截。
插件在终端 claude、桌面应用 Code 标签页、claude -p 和 Agent SDK 中运行，但不支持桌面应用的 WSL 会话。
安全、隐私与配置
插件约2400行 TypeScript 代码，无外部依赖。它不发起网络请求，不存储提示词文本、工具输入或模型输出，仅保存计数、日志和状态于本地 JSON 文件。超过90天的日志会自动删除。
配置可通过环境变量或 ~/.claude/settings.json 设置。关键变量包括 AGENT_GUARD（开关）、AGENT_GUARD_AGENT_MAX（最大并发代理数）、AGENT_GUARD_CONTEXT_WARN（上下文警告阈值）等。休眠默认值假设订阅享有一小时提示缓存，API 密钥用户需设置 AGENT_GUARD_DORMANT_SECONDS=300。
架构与测试
核心规则位于框架无关的 core/ 目录，Claude Code 插件是其首个适配器。测试通过 claude plugin validate . --strict 和 claude plugin test 进行，涵盖单元测试及真实事件触发测试，无需会话、模型或网络。
许可证：MIT