# Claude Code Hooks 说明

## 结构

```
hooks/
├── run-hook.ps1           # Windows dispatcher（读取 settings.local.json 后分发）
├── session-init.ps1       # SessionStart hook（PowerShell 版）
├── session-init.sh        # SessionStart hook（bash 版）
├── check-changelog.ps1    # Stop hook（PowerShell 版）
├── check-changelog.sh     # Stop hook（bash 版）
└── README.md              # 本文件
```

## 事件对应关系

Claude Code 的 hook 事件名与 Cursor 不同：

| Cursor 事件 | Claude Code 事件 | 用途 |
|-------------|------------------|------|
| `sessionStart` | `SessionStart` | 会话启动时触发 |
| `stop` | `Stop` | 会话停止或即将输出最终回复时触发 |

配置位置为 `.claude/settings.json` 的 `hooks` 字段，格式参考
[Claude Code 官方 hooks 文档](https://docs.claude.com/en/docs/claude-code/hooks)。

## 跨平台适配

`settings.json` 中的 `command` 字段是**平台绑定的**——Windows 用 `powershell`，macOS/Linux 用 `bash`。

### Windows（当前默认）

settings.json 使用 `powershell ... run-hook.ps1` 作为入口，dispatcher 根据
`.claude/settings.local.json` 的 `shell` 字段决定执行 `.ps1` 还是 `.sh` 脚本。

### 迁移到 macOS / Linux

将 settings.json 的 command 改为直接调用 `.sh` 脚本：

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/session-init.sh", "timeout": 5 }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/check-changelog.sh", "timeout": 10 }
        ]
      }
    ]
  }
}
```

同时把 `settings.local.example.json` 复制为 `settings.local.json`，将 `shell` 字段改为 `bash` 或 `zsh`。

## 与 Cursor 版本的关键差异

1. **删除 `composer_mode` 检测** —— Claude Code 没有 IDE 模式概念，相关豁免逻辑已移除
2. **使用 `transcript_path` 做 edit evidence 检查** —— Stop hook 通过读取 Claude Code 传入的 transcript 文件，Grep `Write`/`Edit`/`NotebookEdit`/`MultiEdit` 工具调用判断本次会话是否实际修改过文件；没有则静默退出，避免跨会话残留 mtime 误触发
3. **无 `loop_limit` 字段** —— Claude Code hooks 配置中不存在此字段；`stop_hook_active` 由 Claude Code 通过 stdin 的 JSON 传入，避免死循环由 hook 脚本自行判断
4. **SessionStart Hook 双重职责** —— 除清除 ack 标记外，还会检查 `.claude/.init-done` sentinel：缺失时创建 `.claude/.pending-init` 标记文件，供 `claude-init-recall` 规则检测，确保首次会话确定性地触发 claude-init 流程。sentinel 存在时自动清理残留的 pending 标记。