agent-usage-guard 发布以保护 Claude Code 使用窗口

该工具是一个运行在 Claude Code v2.1.287 及更高版本内部的 TypeScript 插件，旨在通过拦截子代理（subagents）的启动、重试循环和上下文膨胀来保护用户的五小时使用窗口不被瞬间耗尽。它不依赖网络请求，而是直接读取订阅计划报告的实时使用数据，在代理开始执行前对并发数量、每十分钟的启动次数以及处理的 token 总量进行阈值判断，一旦触发预设规则即暂停执行并弹出对话框请求用户批准。 核心机制包含多层防御：当使用窗口达到 80% 时新代理需单次批准，95% 时直接拒绝；限制机器上同时运行的代理数为 4 个，每十分钟启动不超过 12 个，子代理处理 token 上限为 1000 万；针对深度嵌套限制为 1 层，防止递归调用。对于工具调用，若上下文超过 40 万 token 且每十分钟调用达 20 次则触发询问；若出现连续 3 次相同失败则拒绝重试。所有决策逻辑基于本地存储的计数器和粗粒度桶，绝不记录提示词文本、工具输入或模型输出，仅保留 13 字符指纹和会话元数据，确保隐私最小化。 事实层面，该插件通过 hooks 模块介入 agent.spawn 和 SendMessage 等事件，能识别跨会话的机器级统计，但无法监控其他终端进程或 API Key 会话（因无计划百分比数据）。推断层面，这种架构将原本不可逆的“用完即锁”模式转化为可管理的审批流，允许用户在紧急情况下授权特定任务，同时通过熔断机制（如 10 分钟暂停期）防止无限重试。猜测层面，由于插件仅能拦截由 agent.spawn 触发的事件，对于通过内部工具启动的 Forks 或后台通知可能无法完全控制，实际防护效果取决于用户配置的全局阈值与具体工作负载的匹配度。