## [ERR-20260321-001] Claude Code Hook 三个关键机制

**日期**: 2026-03-21
**类别**: Claude Code Hooks
**严重度**: 中（功能完全失效但无数据损失）

### 问题描述
self-improving-agent 的 `error-detector.sh` PostToolUse hook 从未触发过错误提醒。

### 根本原因（三层）

1. **数据传递方式错误**：脚本读取 `CLAUDE_TOOL_OUTPUT` 环境变量，但 Claude Code hooks 通过 **stdin JSON** 传递数据，不使用环境变量。
2. **事件类型遗漏**：Bash 命令失败时触发的是 `PostToolUseFailure`，不是 `PostToolUse`。settings.json 中只配置了 `PostToolUse`。
3. **输出格式错误**：`PostToolUse`/`PostToolUseFailure` 的 stdout 纯文本**不会**注入到 Claude 对话上下文。只有 `UserPromptSubmit` 和 `SessionStart` 的 stdout 会自动注入。其他 hook 必须输出 JSON 格式：
   ```json
   {
     "hookSpecificOutput": {
       "hookEventName": "PostToolUseFailure",
       "additionalContext": "你的提示信息"
     }
   }
   ```

### 修复方案
1. 脚本改为 `cat` 读 stdin，用 `jq` 解析 JSON
2. settings.json 增加 `PostToolUseFailure` 事件监听
3. 输出改为 JSON `additionalContext` 格式

### stdin JSON 结构参考

**PostToolUse**:
```json
{
  "session_id": "...",
  "hook_event_name": "PostToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "..." },
  "tool_response": { ... },
  "tool_use_id": "..."
}
```

**PostToolUseFailure**:
```json
{
  "session_id": "...",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": { "command": "..." },
  "error": "Exit code 2\n...",
  "is_interrupt": false,
  "tool_use_id": "..."
}
```

### 适用范围
所有 Claude Code 自定义 hook 脚本开发。

---