Mingyu's Library主页
2026年10月15日

第 59 课:新功能速用 —— v2.1.299 / v2.1.300(空闲压缩、hook 失败即拦截、MCP 放行收紧、OTel GenAI 属性)

📅 2026-10-15 · 依据:Claude Code Changelog(v2.1.299 与 v2.1.300 均于 10-14)与 Monitoring usage 上一课(第 58 课)讲了 v2.1.293–296。本课只讲这两个新版本里「升级后会直接改变你行为」的四件事。changelog 没给取值/示例的地方,我都标注了,不编。

场景:午饭回来,会话还在,账单却悄悄变了

你让 Claude 跑完一个大重构就去吃饭,回来继续聊。升级到 v2.1.299 之后,这段「空闲后回来」的体验变了;同时你的 hook 脚本如果依赖的工具没装,以前是静默放行,现在可能直接拦住动作。下面四条按「立刻能用 → 需要改配置」递进。

技巧 1:认识「空闲压缩」,并按需调或关

解决的问题:长会话停一阵再回来,第一轮往往要重新处理一大段上下文。

v2.1.299 changelog:对空闲约 54 分钟、上下文 ≥200K token 的会话做空闲压缩;阈值可用 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS 调整,也可以用 "idleCompaction": false 关闭。changelog 没解释为什么是 54 分钟(我推测与提示缓存的有效期有关,但这是推测,未证实)。

// ~/.claude/settings.json —— 想完全保留原始上下文(例如正在做精细调试)就关掉
{ "idleCompaction": false }

# 只想让更长的会话才触发:把最小 token 数调高(数值仅为举例)
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS=400000 claude

建议:回来后先 /context 看一眼占用;如果刚好有一段必须逐字保留的日志,在离开前把它写进文件,别指望会话里的原文。 文档:Changelog

技巧 2:hook「失败即关闭」——补齐 onFailure: "block"

解决的问题:安全类 hook 因为脚本缺失、超时而静默放行,护栏形同虚设。

两个版本叠加:v2.1.295 给 command/HTTP hook 加了 onFailure: "block";v2.1.299 又规定「无法接收输入或无法返回答案的 hook 现在会拦截动作」;v2.1.300 起 hook 的 updatedInput 与 Claude 自己的输入一样被校验。写法示意(字段位置请对照 Hooks 文档 核对):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": ".claude/hooks/check-bash.sh", "onFailure": "block" }]
    }]
  }
}

先在脚本里故意 exit 1 或改个不存在的路径,确认动作真的被拦住,再上线。另外 v2.1.299 让 UserPromptSubmit hook 在 skill/命令展开之前运行——如果你的 hook 是靠匹配展开后的文本做判断,需要复查。

技巧 3:收紧 MCP 放行规则

解决的问题:一条宽松的 allow 规则意外放行了名字相近的另一个 MCP server。

v2.1.299:MCP allow 规则只匹配所写明的 server。放行整个 server 用 mcp__<server>__*,放行单个工具用完整名。

{
  "permissions": {
    "allow": ["mcp__github__*", "mcp__memory__memory_read"]
  }
}

升级后跑一遍 /permissions,把旧的前缀写法改成上面的显式形式。同版本里云端与 Remote Control 的 MCP 连接器默认协商 2026-07-28 协议——自己写的 server 要确认兼容。 文档:Permissions

技巧 4:把 agent 行为送进标准可观测性(OTel GenAI 属性 + agent.spawn)

解决的问题:想知道「哪个 agent、调了什么工具、缓存写了多少」,而不是只看总账单。

v2.1.300 在 span 上加入 OpenTelemetry GenAI 语义约定属性(如 gen_ai.provider.name、gen_ai.tool.name、error.type);api_request 事件新增 cache_creation_5m_tokens 与 cache_creation_1h_tokens;agent.spawn hook 可改写工作流 agent 的 prompt 和 model。开启 traces 的最小配置(来自官方监控文档,traces 仍是 beta):

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces

隐私默认值:prompt、工具内容默认脱敏,要逐项开(OTEL_LOG_USER_PROMPTS=1、OTEL_LOG_TOOL_DETAILS=1 等)。agent.spawn 的具体写法属于 mod 体系,changelog 没给示例,我这里不贴代码;今天的深度文档会讲这些属性背后的标准。 文档:Monitoring usage

今日实操(10-15 分钟)

  1. claude --version 确认 ≥2.1.300。
  2. 在测试仓库加一个 onFailure: "block" 的 PreToolUse hook,让脚本故意失败,验收:对应 Bash 动作被拦住并有提示。
  3. 跑 /permissions,验收:没有任何一条 mcp__ 规则是靠前缀碰巧放行的。
  4. 可选:/context 记下离开前的占用,午休回来再看。