Hook 故障变通方案¶

针对当前 Claude Code 中可能影响 ECC 重度 Hook 配置的问题，提供经过社区验证的变通方案。

本页范围刻意保持较窄：它从更长的故障排查内容中收集信号最强的操作修复，而不重复推测性或未经支持的配置建议。这些是上游 Claude Code 行为，不是 ECC 缺陷。

何时使用本页¶

当你专门调试以下问题时，使用本页：

• 在原本成功的 Hook 运行中出现错误的 Hook Error 标签
• 早于预期的压缩
• MCP 连接器看似已认证，但在压缩后失败
• Hook 编辑不会热重载
• 在重度 Hook/工具压力下重复出现 529 Overloaded 响应

如需更完整的 ECC 故障排查内容，请使用 TROUBLESHOOTING.md。

高信号变通方案¶

错误的 Hook Error 标签¶

有效做法：

• 在 Shell Hook 开头读取 stdin（input=$(cat)）。
• 对于简单的允许/阻止 Hook，保持 stdout 无输出，除非你的 Hook 明确要求结构化 stdout。
• 将人类可读的诊断信息发送到 stderr。
• 使用正确的退出码：0 表示允许，2 表示阻止，其他非零值会被视为错误。

input=$(cat)
echo "[BLOCKED] Reason here" >&2
exit 2

早于预期的压缩¶

有效做法：

• 如果降低 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 会在你的构建中导致更早压缩，请移除它。
• 优先在自然任务边界处手动使用 /compact。
• 使用 ECC 的 strategic-compact 指引，而不是强制设置更低的阈值。

MCP 认证看似有效但压缩后失败¶

有效做法：

• 在压缩后，将受影响的连接器关闭再重新打开。
• 如果你的 Claude Code 构建支持，可以添加一个轻量级 PostCompact 提醒 Hook，提示你重新检查连接器认证。
• 将此视为恢复提醒，而不是永久修复。

Hook 编辑不会热重载¶

有效做法：

• 更改 Hook 后，重启 Claude Code 会话。
• 高级用户有时会使用 Shell 本地重载辅助工具，但 ECC 不提供此类工具，因为这些方法依赖于 Shell 和平台。

重复出现 529 Overloaded¶

有效做法：

• 如果你的配置支持，使用 ENABLE_TOOL_SEARCH=auto:5 降低工具定义压力。
• 对于常规工作，降低 MAX_THINKING_TOKENS。
• 如果你的配置暴露该选项，可将子代理工作路由到更便宜的模型，例如 CLAUDE_CODE_SUBAGENT_MODEL=haiku。
• 按项目禁用未使用的 MCP 服务器。
• 在自然断点处手动压缩，而不是等待自动压缩。

相关 ECC 文档¶

• TROUBLESHOOTING.md
• token-optimization.md
• hooks/README.md
• issue #644