第8章：钩子系统 -- Agent 的生命周期扩展点

flowchart TD
    event["生命周期事件触发"] --> collect["收集所有匹配的钩子"]
    collect --> security["安全门禁检查"]
    security -->|"未通过"| reject["跳过钩子执行"]
    security -->|"通过"| sort["按优先级排序<br/>userSettings > projectSettings<br/>> localSettings > plugin"]
    sort --> execute["依次执行钩子"]
    execute --> check{"钩子返回<br/>decision: block?"}
    check -->|"是"| blocked["操作被阻止"]
    check -->|"否"| next{"还有下一个钩子?"}
    next -->|"是"| execute
    next -->|"否"| done["继续正常流程"]

    classDef event fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px,color:#1a237e
    classDef process fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef decision fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#e65100
    classDef blocked_node fill:#ffcdd2,stroke:#d32f2f,stroke-width:2px,color:#b71c1c
    classDef success fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#1b5e20

    class event event
    class collect,security,sort,execute process
    class check,next decision
    class reject,blocked blocked_node
    class done success

graph TD
    subgraph 五种钩子类型["五种钩子类型能力图谱"]
        cmd["Command 钩子<br/>──────────<br/>执行引擎: Shell<br/>可持久化: 是<br/>配置格式: JSON<br/>复杂度: 低<br/>延迟: 毫秒级<br/>典型场景: 脚本检查"]
        prompt["Prompt 钩子<br/>──────────<br/>执行引擎: LLM 推理<br/>可持久化: 是<br/>配置格式: JSON<br/>复杂度: 中<br/>延迟: 秒级<br/>典型场景: 内容审核"]
        agent["Agent 钩子<br/>──────────<br/>执行引擎: LLM 多步<br/>可持久化: 是<br/>配置格式: JSON<br/>复杂度: 高<br/>延迟: 秒~分钟<br/>典型场景: 测试验证"]
        http["HTTP 钩子<br/>──────────<br/>执行引擎: HTTP 请求<br/>可持久化: 是<br/>配置格式: JSON<br/>复杂度: 中<br/>延迟: 网络依赖<br/>典型场景: CI 集成"]
        func["Function 钩子<br/>──────────<br/>执行引擎: TS 回调函数<br/>可持久化: 否<br/>配置格式: TypeScript API<br/>复杂度: 低<br/>延迟: 毫秒级<br/>典型场景: 运行时拦截"]
    end

    classDef cmd fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef prompt fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#1b5e20
    classDef agent fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#e65100
    classDef http fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
    classDef func fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#880e4f

    class cmd cmd
    class prompt prompt
    class agent agent
    class http http
    class func func

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "python3 scripts/validate_command.py",
        "timeout": 5000,
        "message": "Validating bash command safety..."
      }]
    }]
  }
}

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "prompt",
        "prompt": "Analyze this file write operation. If it modifies any file in src/core/, respond with {\"decision\": \"block\", \"reason\": \"Core module changes require code review\"}. Otherwise respond with {\"decision\": \"approve\"}. Input: $ARGUMENTS"
      }]
    }]
  }
}

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "http",
        "url": "https://audit.example.com/api/log",
        "headers": {
          "Authorization": "Bearer $AUDIT_TOKEN",
          "Content-Type": "application/json"
        },
        "allowedEnvVars": ["AUDIT_TOKEN"]
      }]
    }]
  }
}

flowchart TD
    subgraph sync_mode["同步模式（默认）"]
        direction TB
        s1["Agent 执行操作"] -->|"暂停等待"| s2["Hook 执行"]
        s2 -->|"根据结果"| s3["继续 / 阻止"]
    end

    subgraph async_mode["异步模式（async）"]
        direction TB
        a1["Agent 执行操作"] -->|"不等待"| a2["Hook 后台执行"]
        a1 --> a3["正常流程继续"]
    end

    subgraph async_rewake["异步唤醒模式（asyncRewake）"]
        direction TB
        ar1["Agent 执行操作"] -->|"不等待"| ar2["Hook 后台执行"]
        ar2 -->|"退出码 ≠ 2"| ar3["正常运行"]
        ar2 -->|"退出码 = 2"| ar4["唤醒模型继续对话"]
    end

    classDef agent fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef hook fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#e65100
    classDef result fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#1b5e20
    classDef alert fill:#ffebee,stroke:#f44336,stroke-width:2px,color:#b71c1c

    class s1,a1,ar1 agent
    class s2,a2,ar2 hook
    class s3,a3,ar3 result
    class ar4 alert

flowchart TD
    subgraph 会话层["会话层"]
        SessionStart["SessionStart"] --> UserLoop["用户交互循环"]
        UserLoop --> SessionEnd["SessionEnd"]
    end

    subgraph 用户交互层["用户交互层"]
        UserPromptSubmit["UserPromptSubmit"] --> AgentProcess["Agent 处理"]
        AgentProcess --> Stop["Stop / StopFailure"]
    end

    subgraph 工具调用层["工具调用层"]
        PreToolUse["PreToolUse"] --> ToolExec["工具执行"]
        ToolExec --> PostToolUse["PostToolUse / PostToolUseFailure"]
    end

    subgraph 子代理层["子代理层"]
        SubagentStart["SubagentStart"] --> SubagentExec["子代理执行"]
        SubagentExec --> SubagentStop["SubagentStop"]
    end

    subgraph 压缩层["压缩层"]
        PreCompact["PreCompact"] --> CompactExec["压缩执行"]
        CompactExec --> PostCompact["PostCompact"]
    end

    subgraph 其他事件["其他事件"]
        Other["PermissionRequest / PermissionDenied<br/>ConfigChange / CwdChanged / FileChanged<br/>Notification / Setup / Elicitation / InstructionsLoaded"]
    end

    UserLoop --> UserPromptSubmit
    AgentProcess --> PreToolUse
    AgentProcess --> SubagentStart
    AgentProcess --> PreCompact

    classDef session fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px,color:#1a237e
    classDef user fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef tool fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#e65100
    classDef sub fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#1b5e20
    classDef compact fill:#fce4ec,stroke:#e91e63,stroke-width:2px,color:#880e4f
    classDef other fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#4a148c
    classDef process fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px,color:#616161

    class SessionStart,SessionEnd session
    class UserPromptSubmit,Stop user
    class PreToolUse,PostToolUse,PostToolUseFailure tool
    class SubagentStart,SubagentStop sub
    class PreCompact,PostCompact compact
    class Other 其他事件
    class ToolExec,AgentProcess,SubagentExec,CompactExec,UserLoop process

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "echo $INPUT_JSON | python3 -c \"import sys,json; d=json.load(sys.stdin); exit(2) if 'prod' in d.get('file_path','') else exit(0)\"",
        "message": "Checking production file protection..."
      }]
    }]
  }
}

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "echo '{\"additionalContext\": \"Current git branch: '$(git branch --show-current)'. Recent commits: '$(git log --oneline -3)'\"}'",
        "message": "Attaching git context..."
      }]
    }]
  }
}

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "echo 'Project: '$(basename $(pwd))', Branch: '$(git branch --show-current)', Status: '$(git status --short | head -5)",
        "message": "Loading project context..."
      }]
    }]
  }
}

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "if echo \"$CLAUDE_OUTPUT\" | grep -q '```'; then exit 0; else echo 'Please include code examples in your response.' >&2; exit 2; fi",
        "message": "Checking response completeness..."
      }]
    }]
  }
}

graph TD
    subgraph 钩子响应协议["钩子 JSON 响应协议"]
        root["钩子响应 JSON"]
        root --> decision["decision<br/>approve | block<br/>全局决策"]
        root --> reason["reason<br/>阻止原因（block 时）"]
        root --> context["additionalContext<br/>注入额外上下文"]
        root --> cont["continue<br/>true | false<br/>是否继续生成"]
        root --> stop["stopReason<br/>停止原因"]
        root --> hook_specific["hookSpecificOutput<br/>事件特定输出"]
        hook_specific --> event_name["hookEventName<br/>目标事件名"]
        hook_specific --> event_fields["事件特定字段..."]
    end

    subgraph 双通道["双通道输出"]
        stdout["stdout<br/>非 JSON 部分 → 展示给用户<br/>（退出码非 0 时）"]
        stderr["stderr<br/>展示给模型（退出码 2 时）<br/>或用户（其他非 0 退出码时）"]
    end

    classDef main fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef field fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px,color:#424242
    classDef channel fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#e65100

    class root,decision,reason,context,cont,stop,hook_specific main
    class event_name,event_fields field
    class stdout,stderr channel

flowchart TD
    hook["钩子执行完成"] --> exit{"退出码是多少？"}
    exit -->|"0"| e0{"JSON decision?"}
    e0 -->|"approve 或无"| pass["正常通过"]
    e0 -->|"block"| json_block["阻止（JSON 优先）"]

    exit -->|"2"| e2["阻止<br/>stderr 展示给模型"]
    e2 --> json_any["无论 JSON decision 如何"]

    exit -->|"其他非 0"| e3{"JSON decision?"}
    e3 -->|"approve"| warn["警告但继续"]
    e3 -->|"block"| other_block["阻止"]

    classDef decision fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#e65100
    classDef pass_node fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#1b5e20
    classDef block_node fill:#ffcdd2,stroke:#d32f2f,stroke-width:2px,color:#b71c1c
    classDef warn_node fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#f57f17

    class exit,e0,e3 decision
    class pass pass_node
    class json_block,e2,json_any,other_block block_node
    class warn warn_node

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 scripts/check_bash_safety.py",
            "timeout": 5000
          }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if this file write is safe. $ARGUMENTS"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat .claude/context.md 2>/dev/null || echo 'No project context file found'",
            "message": "Loading project context..."
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 scripts/check_task_completion.py",
            "asyncRewake": true
          }
        ]
      }
    ]
  }
}

graph TD
    subgraph 钩子优先级["钩子优先级（从高到低）"]
        p1["1. userSettings<br/>用户全局设置 ~/.claude/settings.json"]
        p2["2. projectSettings<br/>项目设置 .claude/settings.json"]
        p3["3. localSettings<br/>本地设置 .claude/settings.local.json"]
        p4["4. pluginHook<br/>插件钩子（优先级 = 999）"]
        p5["5. builtinHook<br/>内置钩子"]
        p6["6. sessionHook<br/>会话临时钩子"]
    end

    p1 --> p2 --> p3 --> p4 --> p5 --> p6

    classDef high fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#1b5e20
    classDef mid fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#e65100
    classDef low fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px,color:#757575

    class p1 high
    class p2,p3 mid
    class p4,p5,p6 low

userSettings:    [钩子 A: 审计日志]
projectSettings: [钩子 B: 安全检查]
localSettings:   [钩子 C: 本地调试]

执行顺序（按优先级从高到低）：
  1. 钩子 A（userSettings）—— 先执行
  2. 钩子 B（projectSettings）—— 后执行
  3. 钩子 C（localSettings）—— 最后执行

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(rm *)",
        "hooks": [{"type": "command", "command": "python3 check_delete.py"}]
      },
      {
        "matcher": "Bash(npm publish *)",
        "hooks": [{"type": "command", "command": "python3 check_publish.py"}]
      },
      {
        "matcher": "Write",
        "hooks": [{"type": "command", "command": "python3 check_write.py"}]
      }
    ]
  }
}

flowchart TD
    start["钩子触发"] --> layer1{"第一层：全局禁用开关<br/>disableAllHooks: true?"}
    layer1 -->|"是"| disabled["所有钩子全部禁用<br/>（紧急安全事件 / 故障排查）"]
    layer1 -->|"否"| layer2{"第二层：托管模式检查<br/>allowManagedHooksOnly: true?"}
    layer2 -->|"是"| managed["只允许企业策略配置的钩子<br/>（企业合规环境）"]
    layer2 -->|"否"| layer3{"第三层：工作区信任检查<br/>工作区是否已被信任？"}
    layer3 -->|"否"| untrusted["拒绝执行用户/项目配置中的钩子<br/>（克隆的第三方仓库）"]
    layer3 -->|"是"| execute["正常执行钩子"]

    classDef gate fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#e65100
    classDef blocked fill:#ffcdd2,stroke:#d32f2f,stroke-width:2px,color:#b71c1c
    classDef allowed fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#1b5e20
    classDef managed_node fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1

    class layer1,layer2,layer3 gate
    class disabled,untrusted blocked
    class execute allowed
    class managed managed_node

// 反模式：在每次工具调用前执行完整的代码审查
{
  "PreToolUse": [{
    "hooks": [{
      "type": "command",
      "command": "npm run full-code-review",
      "timeout": 300000
    }]
  }]
}

// 反模式：静默修改所有 Bash 命令
{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "echo $INPUT_JSON | jq '.tool_input.command |= \"sudo \" + .' | jq '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"updatedInput\": .tool_input}}'"
    }]
  }]
}

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "python3 scripts/session_init.py --report-env",
        "message": "Initializing security audit session..."
      }]
    }],
    "PreToolUse": [
      {
        "matcher": "Bash(rm *)",
        "hooks": [{
          "type": "command",
          "command": "python3 scripts/validate_delete.py",
          "timeout": 3000,
          "message": "Validating delete operation..."
        }]
      },
      {
        "matcher": "Write",
        "hooks": [{
          "type": "prompt",
          "prompt": "Analyze the file being written. If it modifies production config files (*.production.*), return {\"decision\": \"block\", \"reason\": \"Production config changes require approval\"}. Otherwise return {\"decision\": \"approve\"}. File content: $ARGUMENTS"
        }]
      }
    ],
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "http",
        "url": "https://audit.internal.company.com/api/log",
        "headers": {
          "Authorization": "Bearer $AUDIT_TOKEN"
        },
        "allowedEnvVars": ["AUDIT_TOKEN"],
        "async": true
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "python3 scripts/check_completion.py",
        "asyncRewake": true
      }]
    }],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "python3 scripts/session_summary.py",
        "timeout": 1500
      }]
    }]
  }
}