08-Hooks

状态：草稿，未发布。 「如何指定触发时机」这一半已经写全；「触发后执行什么动作」还没展开。

Hook 是在特定时机触发指定动作的机制。简单来说就是，用户指定什么时候干一些用户自己想干的事。

所以，Claude Hook 的学习大块上就可以分为：

• 如何指定触发时机（本篇写完了）
• 如何执行指定动作（待补，目前只有下面例子里的 type: command）

如何指定触发时机

触发时机的指定是三层机制，设计思想是逐步收窄触发范围：

• 生命周期事件 Event：粗粒度，确定生命周期阶段
• 匹配器 Matcher：中粒度，确定具体工具/操作
• if：细粒度，基于上下文条件做最终判断

先看一个例子：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": ".claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

• 生命周期事件 Event：PreToolUse
• 匹配器 Matcher：Bash 工具
• if：Bash(rm *)——当执行的是 rm * 命令时，会执行一个 command 类型动作。这个动作是执行一个具体的 sh 脚本。

生命周期事件

Matcher 和 If 详解

核心区别

Matcher 和 If 构成了两层过滤机制：

• Matcher：一级过滤器，决定整个 hook 组是否激活
• If：二级过滤器，决定具体的 hook 处理程序是否运行

Matcher 详解

评估规则

Matcher 的解析取决于其内容：

按事件类型的 Matcher 目标

// 工具事件（PreToolUse、PostToolUse）
"matcher": "Bash"              // 仅过滤 Bash 工具
"matcher": "Edit|Write"        // Edit 或 Write 工具

// SessionStart 事件
"matcher": "startup|resume"    // 区分新会话或恢复

// Notification 事件
"matcher": "permission_prompt" // 权限提示通知

// 某些事件不支持 matcher
// UserPromptSubmit、PostToolBatch、Stop 等总是触发

If 详解

用途和约束

• 只用于工具事件：PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest 等
• 其他事件忽略 If：在非工具事件上配置 if 的 hook 永不运行
• 权限规则语法：格式为 "工具名(模式)"，如 "Bash(rm *)" 或 "Edit(*.ts)"

执行流程

以上面开头那个 block-rm.sh 的配置为例：

1. 触发事件 → Bash 工具调用
2. Matcher 检查："Bash" ✓ 匹配
3. If 检查："Bash(rm *)" ✓ 匹配 rm -rf
4. Hook 执行：运行 block-rm.sh

Bash 模式匹配规则

性能优化

• Matcher 失败 → 整个 hook 组跳过（避免启动进程）
• If 失败 → 跳过单个 handler（更精细的过滤）

这样可以避免不必要的脚本执行开销。

解析流程

解析顺序（必须全部匹配，hook 才运行）：

1. 事件触发 → 2. Matcher 检查 → 3. If 条件检查 → 4. Hook 执行

关键要点总结