Hooks

概念

学习概念最好的方法就是参考官方文档：code.claude.com/docs/en/hooks

以下内容全都基于官方文档解释总结

Hooks 是用户定义的 shell 命令、HTTP 端点或 LLM 提示，它们在 Claude Code 的生命周期中的特定点自动执行。用于参考查找事件模式、配置选项、JSON 输入/输出格式以及异步 hooks、HTTP hooks 和 MCP 工具 hooks 等高级功能。

生命周期（Lifecycle）

Hook 在 Claude Code 会话的特定时间点触发。当事件被触发且匹配器匹配时，Claude Code 会将关于该事件的 JSON 上下文传递给您的钩子处理器。

• 对于命令 Hook，输入会通过标准输入（stdin）到达
• 对于 HTTP Hook，输入会作为 POST 请求体到达

然后你的处理器可以检查输入、采取行动，并可选择返回一个决策。

事件分为三种节奏：每次会话一次（ SessionStart ， SessionEnd ）、每次回合一次（ UserPromptSubmit ， Stop ， StopFailure ），以及在每个工具调用中（在代理循环内）（ PreToolUse ， PostToolUse ），如图：

执行时间

下表总结了每个事件触发的时间。Hooks 事件部分记录了每个事件的完整输入模式和决策控制选项。

如何解析

要了解这些部分如何协同工作，可以以 PreToolUse 钩子举例，它用于阻止破坏性 shell 命令。 matcher 会缩小到 Bash 工具调用，而 if 条件会进一步缩小到以 rm 开头的命令，因此 block-rm.sh 只会在两个过滤器都匹配时才会触发

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

该脚本从标准输入读取 JSON 输入，提取命令，如果包含 rm -rf ，则返回 permissionDecision 的 “deny” ：

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # allow the command
fi

现在假设 Claude Code 决定运行 Bash “rm -rf /tmp/build” 。以下是解析流程图

如何配置

Hooks 在 JSON 配置文件中定义。配置具有三个级别的嵌套：

1. 选择要响应的 hook 事件，例如 PreToolUse 或 Stop

2. 添加一个匹配器组来过滤何时触发，例如“仅适用于 Bash 工具”

3. 定义一个或多个 hook 处理器来在匹配时运行

具体 hook 实现可参考官方文档：https://code.claude.com/docs/en/hooks-guide#reload-environment-w…

如果不知道如何手动配置，那就把网站丢给他让它给你配置就好了~！

画图不易，如果对你有帮助的可以点个小赞~

希望对你有所帮助，祝你身体健康！