Hooks 事件参考

Claude Code 的 Hook 系统支持 29 种事件类型、5 种 Hook 类型、按事件的匹配器 以及 智能行为。Hook 是智能体 Harness 中唯一保证"一定会执行"的确定性 (deterministic) 控制点 — 提示词可能被忽略，但 Hook 不会。

Hook 的基本概念与配置方法请参阅 Hooks 指南。本页是完整的事件参考。

可用的 Hook 类型有五种。

MoAI-ADK 的 Hook 超越简单的事件处理，执行智能化的行为。

当只读工具（Read、Grep、Glob）的权限被拒时，Hook 会自动触发重试。这缓解了后台智能体中权限提示不显示的问题。

智能体停止失败时，按错误类型提供差异化响应。保障长时间运行会话的稳定性。

上下文压缩后自动恢复重要的会话备忘（进度状态、SPEC 引用）。上下文压缩是一笔用信息换代币的交易，而这个 Hook 在损失中守住了核心信息。

子智能体启动时自动注入所需上下文（项目规则、MX 标签、进度状态）。

使用匹配器可以过滤 Hook，使其只在特定条件下执行。给所有事件都挂 Hook 会相应增加执行成本，因此用匹配器收窄范围是基本做法。

{
  "hooks": {
    "PreToolUse": [{
      "matcher": { "toolName": "Bash" },
      "hooks": [{
        "type": "command",
        "command": "echo 'Bash tool detected'",
        "timeout": 5
      }]
    }]
  }
}

通过 CwdChanged 与 FileChanged Hook 可以持续管理环境变量。

# .claude/hooks/moai/handle-cwd-changed.sh
# 通过 CLAUDE_ENV_FILE 持久化环境变量
echo "MOAI_PROJECT_DIR=$(pwd)" >> "$CLAUDE_ENV_FILE"

由此可以在会话之间保持环境变量，并在目录变更时自动重置环境。

• Hooks 指南 — Hook 基本概念与配置方法
• settings.json 指南 — settings.json 完整参考
• CLI 参考 — moai hook 命令详解