# Claude Code Hooks 自动化

> Claude Code Hooks 生命周期、事件、matcher、command/http/mcp_tool/prompt/agent handler,以及常见安全自动化模板。

URL: https://docs.passion8.cc/docs/claude-code/hooks
Language: zh-CN
Publisher: Passion8

Hooks 是 Claude Code 的自动化层。它能在会话开始、用户提交 prompt、工具执行前后、配置变化、上下文压缩等节点运行脚本、HTTP 请求、MCP 工具或 LLM 检查。




Hooks 是把团队规范变成机制的地方:格式化、审计、阻止危险命令、记录工具调用、通知长任务完成,都适合放这里。




## 生命周期

| 频率 | 事件示例 | 用途 |
| --- | --- | --- |
| 会话级 | `SessionStart`, `SessionEnd`, `Setup` | 初始化环境、打印说明、记录会话 |
| 每轮对话 | `UserPromptSubmit`, `Stop`, `StopFailure` | 检查 prompt、通知完成、错误诊断 |
| 工具调用 | `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PostToolUseFailure` | 阻止、审计、格式化、自动验证 |
| 批处理/子代理 | `PostToolBatch`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted` | 追踪并行任务 |
| 配置/上下文 | `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `PreCompact`, `PostCompact` | 观察配置和记忆加载 |
| MCP 交互 | `Elicitation`, `ElicitationResult` | 处理 MCP 请求用户输入 |

常用事件:

- `PreToolUse`:工具执行前,可阻止危险动作
- `PostToolUse`:工具成功后,可格式化或跑轻量检查
- `UserPromptSubmit`:用户输入进入模型前,可做校验或补充上下文
- `Stop`:Claude 完成一轮回复后,可通知或记录
- `ConfigChange`:settings、hooks、rules 变化时触发
- `FileChanged`:监听指定文件变化,适合 `.envrc`、锁文件等

## 基础配置

Hooks 写在 settings 文件里:

```json title=".claude/settings.json"
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}
```

Hook 由三层组成:

1. 事件,例如 `PreToolUse`
2. matcher group,例如只匹配 `Bash`
3. handler,例如 command、http、mcp_tool、prompt、agent

## Matcher 规则

| 写法 | 含义 | 示例 |
| --- | --- | --- |
| 省略、空字符串、`*` | 匹配全部 | 所有工具调用都触发 |
| `Bash` | 精确匹配工具名 | 只看 Bash |
| `Edit 和 Write` | 多个精确工具 | 编辑文件后触发 |
| `mcp__memory__.*` | 正则 | 匹配 memory server 全部 MCP 工具 |

对工具事件,还可以用 `if` 字段做更细过滤:

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

`if` 使用权限规则语法。Bash 复合命令会按子命令检查,不是只匹配整行字符串。

## Handler 类型

| 类型 | 做什么 | 适合场景 |
| --- | --- | --- |
| `command` | 执行本地命令,stdin 接收 JSON | 本地格式化、审计、阻止 |
| `http` | POST JSON 到 URL | 集中审计、通知系统 |
| `mcp_tool` | 调用已连接 MCP 工具 | 把检查逻辑放进 MCP |
| `prompt` | 让模型做单轮判断 | 轻量语义检查 |
| `agent` | 启动子代理验证 | 需要读文件或复杂判断 |

Command hook 的 stdin 是事件 JSON。输出可以是空,也可以返回 JSON 决策。

## 阻止危险命令

```bash title=".claude/hooks/block-rm.sh"
#!/usr/bin/env bash
set -euo pipefail

COMMAND=$(jq -r '.tool_input.command // ""')

if echo "$COMMAND" | grep -Eq 'rm -rf (~/|/|\\$HOME)'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Refuse to remove home or root paths"
    }
  }'
fi
```

对应配置:

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




Hook 保持沉默不等于批准。空输出或 exit 0 只是让 Claude Code 继续走正常权限流程。




## 自动格式化

```json title=".claude/settings.json"
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix"
          }
        ]
      }
    ]
  }
}
```

大型项目不要每次编辑后跑完整构建。Hook 应该短、稳定、可预期。完整验证更适合让 Claude 在任务结束后手动跑。

## 配置位置

| 位置 | 作用 |
| --- | --- |
| `~/.claude/settings.json` | 个人全局 Hook |
| `.claude/settings.json` | 团队共享 Hook |
| `.claude/settings.local.json` | 本项目个人 Hook |
| Managed settings | 组织强制 Hook |
| Plugin hooks | 插件启用时加载 |
| Skill/agent frontmatter | 技能或子代理激活时加载 |

## 排错

| 现象 | 检查 |
| --- | --- |
| Hook 没触发 | `/hooks` 看实际加载和 matcher |
| settings 改了没生效 | 看 `ConfigChange`,确认 JSON 合法 |
| 命令找不到 | 用绝对路径或 `${CLAUDE_PROJECT_DIR}` |
| 太慢 | 加 `if` 缩小范围,避免每次都 spawn |
| MCP 工具没匹配 | 工具名应为 `mcp__server__tool` |
| 想验证是否配置干扰 | `claude --safe-mode` 临时禁用自定义项 |

## 官方参考

- [Hooks reference](https://code.claude.com/docs/en/hooks.md)
- [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide.md)
- [Permissions and hooks](https://code.claude.com/docs/en/permissions.md)