Claude Code 2.1.251：PreModelSwitch Hook 让模型切换成为可管控的运营决策

Claude Code 的 hook 系统此前给了 operator 对工具调用相当细粒度的控制，屏蔽某条 bash 命令、拦截文件写入、记录 MCP 活动。但模型选择本身是透明的。用户或 sub-agent 发出模型切换请求，请求就直接执行了。2.1.251 关掉了这个口子。

2.1.251 加了什么

这次更新有两个新 hook 事件，还有几个让客户端成为更实用的运营治理层的成本可见性功能。

PreModelSwitch 在 Claude Code 应用用户或客户端发出的任何模型切换之前触发，它是同步的，Claude Code 会等 hook 返回结果再继续。注册了这个 hook 但没有返回决策时，默认行为是阻断，切换取消。要放行，hook 必须明确返回 allow。要拒绝并附带提示，则返回 deny 加上 permissionDecisionReason。输入中包含 from_model 和 to_model，策略脚本可以直接对比 allowlist，不用解析会话上下文。

PostModelSwitch 在模型切换完成后触发，也包括会话恢复时系统自动恢复模型的情况，它是异步的，适合记录切换日志、调整下游配置或推送审计记录。

SessionStart 恢复上下文现在包含会话陈旧度和预估的重新缓存成本。在会话恢复时做上下文预热的团队，可以先判断上次的缓存是否还热，再决定是否跑完整预热流程。

消费限额可见性面向在执行月度消费上限的 Claude apps gateway 后面运行 Claude Code 的团队。/usage 里出现了消费限额进度条，状态行里出现了 rate_limits.spend_limit 字段，解析 Claude Code 机器可读状态输出的 shell 脚本可以直接读取。以前这个上限只在 gateway 的计费仪表板上可见，现在进了客户端会话里。

单会话 prompt cache 指标在 /cost 里展示，包括命中率、缓存未命中、重新缓存的 token 数，以及冷热指示。对跑长 agent 任务的团队来说，缓存利用率从猜测变成了每会话可测量的数字。

Operator 之前缺少什么

模型切换的缺口在两种运营场景下影响最大。

第一种是企业授权范围限制。很多团队部署 Claude Code 时签的企业合约只覆盖 Sonnet，不覆盖 Opus。2.1.251 之前，用户在会话中途手动切换到 Opus，或者某个 sub-agent 配置了 Opus，请求会发出去，成功还是失败取决于 gateway 是否在 API 层拦截。API 层的拦截会产生一个模糊的错误，会话报错但没有清晰说明原因。PreModelSwitch hook 可以返回带可读说明的 deny，而不是让会话崩在一个不明原因的错误上。

第二种是成本策略执行。有些 gateway 配置会根据模型名称将请求路由到不同 provider。会话中途从便宜模型切换到贵的，可能绕过在会话启动时本应生效的路由逻辑。Hook 检查 to_model 是否超过成本阈值，阻断或要求确认，就能关上这个口子。

Hook 与 enforceAvailableModels 的区别

Claude Code 自 2.1.176 起在 managed settings 里有 enforceAvailableModels。两个控制不是重复的，作用层不同。

enforceAvailableModels 是通过 managed settings 应用的静态锁，通常由组织级别的 managed settings 文件部署。任何不在配置列表里的模型 ID 会在 managed-settings 检查阶段被拒绝。要更新它，需要推送新的 managed settings 文件。

PreModelSwitch 是运行时 hook，在切换请求发出的那一刻触发，可以做动态决策，比如查询外部 API 确认用户预算、对比当前项目的配额、记录切换并附注后放行。它还可以在项目级别通过 .claude/settings.json 部署，不需要推送组织级别的 managed settings。

严格 allowlist 执行用 enforceAvailableModels。需要根据运行时状态做动态成本感知或上下文感知决策，用 PreModelSwitch。

需要审查的安全修复

2.1.251 里有三个安全修复值得对照自己的 operator 部署做检查。

文件工具的 symlink 穿透。 Read、Write 和 Edit 在权限检查完成后会跟随工作目录内被替换的 symlink。有工作目录写权限的攻击者可以在权限检查后创建指向批准路径之外的 symlink，再触发文件读写。已修复，权限检查现在覆盖解析后的路径。

插件路径穿透。 marketplace 条目里声明的插件命令可以引用插件目录之外的路径。现在这些路径在加载时会以路径穿透错误拒绝。

OTEL bypass 通过 project settings。 Project settings 可以开启原始 API 请求体日志或详细 beta tracing，以绕过 managed settings 或 host app 固定的 OTLP collector。已修复。用 managed settings 固定 OTLP 端点的团队应确认收集器正在接收全部 trace，而不只是 project settings 没有覆盖 trace 级别的那些会话。

对 gateway operator 来说，如果组织用 managed settings 控制 trace 目标和数据留存，2.1.251 的修复关掉了一条泄漏路径。如果 OTLP 固定是合规配置的一部分，升级不是可选的。

需要配置或审查的内容

PreModelSwitch hook 的最简治理策略，阻断任何不在批准列表里的模型切换，在 .claude/settings.json 里这样写

{
  "hooks": {
    "PreModelSwitch": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/check-model-policy.sh"
          }
        ]
      }
    ]
  }
}

Shell 脚本从 stdin 读取 from_model 和 to_model（JSON 格式），要么不输出（阻断），要么明确返回 allow。因为 PreModelSwitch 是同步的，脚本退出前切换会一直等待。

对于消费限额字段，如果部署中有 shell 脚本把成本数据推送到仪表板，把 rate_limits.spend_limit 加到解析的字段里。它出现说明会话在有活跃上限的 gateway 后面，它的值显示剩余预算。

对于 OTEL 修复，运行 claude --version 确认是 2.1.251，检查 trace 收集器确认日志正在接收且没有缺口。

TheRouter 用户需要关注的

对于通过 TheRouter 的开发者网关路由 Claude Code 的团队，PreModelSwitch hook 是在客户端侧执行模型路由策略最简洁的方式，在请求到达 API 层之前就能生效。Hook 把 to_model 与配置 provider 支持的模型对比，可以防止会话请求 gateway 会拒绝的模型，比在下游拿到 404 报错要清晰得多。

/cost 里的单会话缓存指标也值得监控，缓存命中率持续偏低意味着会话在重复编码上下文，即使模型定价没变，路由层的成本也会偏高。