第 7 章 · 01 事件与配置结构

第 7 章 · 01 事件与配置结构

本节摘要:Hooks 的骨架是"事件 → 配置 → handler"。31 个事件分四组:Tool(工具调用前后)、Session(会话启停与状态)、Task(任务/子代理/停止)、Lifecycle(工作树)。配置写在 settings 文件里,结构是 事件名 → matcher(匹配工具) → hooks(处理器数组);matcher 还能叠加 if 参数条件,精确到"哪个工具、哪类参数"。五种 handler 各有分工:command 跑脚本、http 发 webhook、prompt 让 LLM 评估、mcp_tool 直调 MCP 工具、agent 派子代理核查。

学习目标

阅读完本节,你应当能够:

1. 说出 31 个事件四组分类,并指出哪些事件支持阻断。
2. 说出 hooks 的五个配置位置与作用范围。
3. 写出含 matcher 与 if 条件的基本配置,并解释 matcher 与 if 的分工。
4. 说出五种 handler 类型并各举一个适用场景。

一、31 个事件:四组分类

Hooks 由事件驱动。31 个事件按触发面分为四组:

Tool 组(12 个):工具调用的前后与交互

Session 组(10 个):会话生命周期

Task 组(7 个):任务与子代理

Lifecycle 组(2 个):工作树

记忆口诀:Tool 管"用工具",Session 管"会话生灭",Task 管"任务与代理",Lifecycle 管"工作树"。能阻断的事件集中在"事情发生之前或刚结束时"——拦截窗口一旦错过,就只剩反馈权。

二、配置位置:五个落点

组件级钩子支持的事件只有三个:PreToolUse、PostToolUse、Stop——把钩子直接写进 SKILL.md、agent.md、command.md 的 frontmatter,相关代码聚在一起。特别注意:子代理 frontmatter 里的 Stop 钩子会被自动转换为 SubagentStop 并限定在该代理上,只在它完成时触发,不会连累主会话。

三、基本结构:事件 → matcher → hooks

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          { "type": "command", "command": "your-command-here", "timeout": 60 }
        ]
      }
    ]
  }
}
​

关键字段:

matcher 模式

注意(v2.1.195+):matcher 是精确匹配,带连字符的 MCP 工具名不再误伤其他工具;逗号分隔写法在旧版本里是"静默永不触发"的 bug,升级后才生效。InstructionsLoaded 事件特殊,matcher 取 session_start/nested_traversal/path_glob_match 之一。

if 条件:从"哪个工具"精确到"哪次调用"

matcher 按工具名选钩子;要按工具参数过滤(比如只在编辑 src/ 下文件时触发,或拦截读密钥文件),在单个 handler 上加 if。matcher 决定"哪个工具",if 决定"哪次调用":

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "if": "Edit(src/**)",
            "command": "./hooks/lint-src.sh"
          }
        ]
      },
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "if": "Read(.env)",
            "command": "./hooks/block-secret-read.sh"
          }
        ]
      }
    ]
  }
}
​

if 用权限规则语法(ToolName(pattern)),对工具名与参数一并求值;路径遵循 gitignore 语义,锚点与权限规则一致:裸名 .env 匹配任意深度、src/** 相对当前目录、/src/** 相对项目根、~/... 用户主目录、//... 绝对路径。常见写法:Edit(src/**)(编辑 src 下)、Read(~/.ssh/**)(读 SSH 密钥)、Bash(git push *)(仅 git push)。

四、五种 handler 类型

1. command(默认):执行 Shell 命令,通过 JSON stdin/stdout 与退出码通信。覆盖绝大多数场景——校验、格式化、日志。
2. http(v2.1.63+):POST JSON 到远端 Webhook,同样收到 JSON 响应。URL 里的环境变量插值必须显式 allowedEnvVars 白名单,防止敏感变量泄漏到远端。沙箱启用时 HTTP 钩子走沙箱路由。
3. prompt:钩子内容是一段提示词,交给 LLM 评估,返回结构化决策。主要用于 Stop/SubagentStop 的"任务是否完成"智能检查。
4. mcp_tool(v2.1.118+):直接调用已配置的 MCP 服务器上的工具,配置只写服务器名与工具名——校验逻辑本来就在 MCP 服务器里时最合适,钩子输入原样作为工具参数。
5. agent:派一个专用子代理做多步核查。与 prompt 钩子(单回合 LLM 评估)不同,agent 钩子能用工具、能多步推理,适合需要查文档、对比代码的复杂验证。

五、环境变量速查

钩子脚本可用的环境变量:所有钩子都有 CLAUDE_PROJECT_DIR(项目根绝对路径);CLAUDE_ENV_FILE 只在 SessionStart/CwdChanged/FileChanged 有(用于持久化环境变量);CLAUDE_CODE_REMOTE 标识远端运行;插件钩子有 ${CLAUDE_PLUGIN_ROOT} 与 ${CLAUDE_PLUGIN_DATA};Bash 子进程还注入 CLAUDE_CODE_SESSION_ID(与钩子 JSON 的 session_id 对应)与 CLAUDE_EFFORT(当前 effort 等级)。

小结

Hooks 的骨架一句话:31 个事件按 Tool/Session/Task/Lifecycle 四组分布,配置按"事件 → matcher → handlers"组织,matcher 选工具、if 选调用,五种 handler 从跑脚本到派子代理各有分工。能阻断的事件集中在"执行前/刚结束时",组件级钩子只有 PreToolUse/PostToolUse/Stop 三件套。下一节精读 8 个官方示例脚本,看真实钩子怎么落地。

下一节预告:第 2 节精读示例脚本——命令校验、安全扫描、自动格式化、智能 Stop、上下文追踪。