model-guard：贵模型预算闸

使用方式始终一套：贵模型只做思考、方案、审阅，重活派便宜 subagent。套餐余量充足时这是 CLAUDE.md 里的软提示；余量越过保留线后，PreToolUse hook 把它变成硬约束（强制分工，不是禁用贵模型）。

机制

触发线随时间走：对 5h、7d 窗口各算 remaining = clamp(距重置秒数 / 窗口秒数, 0, 1)，保留线 = max(保留额 × remaining, min(下限, 保留额))，余量 100 - 已用% 小于保留线即越线，任一窗口越线就进入强制分工。下限（reserve_floor_5h / reserve_floor_7d，默认 15%）防止临近重置时保留线趋近 0：没有下限时 7d 已用 96% 还剩 1 小时，保留线只有约 0.3%，闸不触发，额度照样被烧光。实际生效的下限是 min(下限, 保留额)，--status 与软提示显示的也是这个值；保留额设 0 仍等于关闭该窗口的闸。

Claude Code 越线后 Read 只放行带 limit≤200 且不带 pages 的读取；用 offset 分段连续读仍可读完整文件，这是有意保留的小口子，大段阅读应派 subagent。模型判定取 transcript 最后一条 assistant 消息（实测首个工具调用时本条消息已写入）；/model 切换后的第一次调用可能仍按上一条消息的模型判定。

宿主按 hook 输入自动识别：带 model 字段的是 Codex，模型直接取该字段，用量取本 session rollout 里最后一条 token_count 的 rate_limits（window_minutes≤360 按 5h 口径，否则按 7d）；否则是 Claude Code，模型取 transcript 末尾 assistant 消息，用量取状态栏落盘文件。Codex 没有状态栏命令，不需要旁路。

用量数据缺失、超过 6 小时未更新、或非套餐用户（rate_limits 为 null）时一律放行。subagent 内的工具调用按 subagent 自己的模型判定，便宜 subagent 不受影响。

执行步骤

1. 展示现状

bash scripts/install.sh --status

把输出的现状表原样给用户：是否已装、模型列表、保留额、hook / 状态栏旁路 / 软提示是否就位、Codex 状态、当前用量是否已触发。python3 缺失时脚本直接报错，停止并提示安装。

2. 用 AskUserQuestion 一次问两件事

• 保留额：推荐默认 5h 40% / 7d 50%（给其它 session 留的余量），保留线下限默认 5h/7d 各 15%；可自定 0-100。已安装时以现有值为推荐项。
• 贵模型列表：默认 fable、astra（模型名子串，大小写不敏感）；可增删。

用户只是"更新贵模型列表"或"改保留额"时，只问对应的一项。

3. 一次性请求授权

列出将改动的文件，等用户确认：

• ~/.claude/settings.json：注册 PreToolUse hook、包一层状态栏（改前自动备份为 settings.json.bak-<时间戳>）
• ~/.claude/CLAUDE.md：写入 <!-- model-guard:start --> 标记块
• ~/.codex/hooks.json：仅当 ~/.codex 存在时，注册同一个 guard.sh（改前备份）
• ~/.codex/AGENTS.md：仅当 ~/.codex 存在时；若 CLAUDE.md 软链到它，只写一次

4. 执行安装

bash scripts/install.sh --models fable,astra --reserve-5h 40 --reserve-7d 50 --reserve-floor-5h 15 --reserve-floor-7d 15

未传的参数沿用已有配置。重跑即更新：hook 与状态栏不会重复注册，标记块按块替换。

5. 自检

bash scripts/install.sh --selftest

确认 settings.json（及 Codex hooks.json）已注册可执行的 guard.sh，并在临时目录伪造贵模型 transcript 与越线用量，验证两种宿主下 Bash 被拒（exit 2）、派便宜子 agent 放行。任一项失败即如实报告，不得说已完成。

Codex 只执行用户信任过的 hook。--status 显示"已注册，✗ 未信任"时，告诉用户：下次启动交互式 Codex 会提示 Hooks need review，选 Review hooks 或 Trust all and continue；codex exec 不提示，未信任的 hook 静默不执行。不要替用户写信任登记。

6. 汇报

给出：改动的文件（绝对路径）、备份文件路径、最终模型列表、保留额与下限、自检结果、Codex 信任状态。提醒用户 Claude Code 要等状态栏下次刷新才有用量数据，Codex 要等每个 session 跑完第一轮，此前 hook 放行。

卸载

bash scripts/install.sh --uninstall

移除 settings.json 与 Codex hooks.json 中的 hook、还原原 statusLine、删除软提示标记块，保留 ~/.claude/model-guard.json 供重装沿用。执行前同样列出改动文件请求确认。

被拦时怎么办

拒绝原因会回灌给模型，含当前模型、5h/7d 用量与剩余时间、越过了哪条线。按提示三选一：

• Claude Code：派 subagent，Agent 工具显式传 model=opus|sonnet|haiku，禁止 subagent_type=fork
• Codex：spawn_agent 显式传便宜模型（默认 sol/luna/terra/reserve），不传会继承贵模型
• /model 切到便宜模型继续
• /compact 减小上下文，降低每轮消耗

错误处理

测试

bash tests/test_guard.sh      # 规则矩阵：两种宿主的越线、窗口首尾与保留线下限、子 agent 规则、subagent 判定、fail open
bash tests/test_install.sh    # 临时 HOME：幂等、软链、状态栏旁路、Codex 注册与信任检测、更新、百分比配置与参数的坏值类别测试、卸载还原