Hook Flow¶
目的：Hook 完整流图 关联：docs/HOOKS.md、tutorials/build-hook.md
1. 9 事件触发流¶
graph TD
A[Claude Code] --> B{event}
B -->|tool call| C[PreToolUse]
B -->|tool return| D[PostToolUse]
B -->|session start| E[SessionStart]
B -->|session end| F[SessionEnd]
B -->|notification| G[Notification]
B -->|stop| H[Stop]
B -->|subagent stop| I[SubagentStop]
B -->|user prompt| J[UserPromptSubmit]
B -->|compact| K[PreCompact]
C --> L[run hook]
D --> L
E --> L
F --> L
G --> L
H --> L
I --> L
J --> L
K --> L
L -->|exit 0| M[allow]
L -->|exit 2| N[block]
L -->|non-0| O[error, allow]9 事件 → 统一执行。
2. 3 Hook 类型执行¶
graph TD
A[hook triggered] --> B{type}
B -->|command| C[stdin JSON]
C -->|exec shell| D[wait for exit]
D -->|exit 0| E[allow]
D -->|exit 2| F[block + stderr]
B -->|prompt| G[stdin JSON + prompt]
G -->|LLM| H[wait response]
H -->|approve| E
H -->|block| F
B -->|agent| I[stdin + agent prompt]
I -->|run agent| J[wait result]
J -->|approve| E
J -->|block| F3 类型 → 3 执行。
3. 4 步 Hook Input¶
graph LR
A[Hook event] --> B[stdin JSON]
B --> C[8 fields]
C --> C1[session_id]
C --> C2[transcript_path]
C --> C3[cwd]
C --> C4[hook_event_name]
C --> C5[tool_name]
C --> C6[tool_input]
C --> C7[... etc]4 步。
4. 3 步 Hook 决策¶
graph TD
A[hook output] --> B{decision}
B -->|approve| C[allow + log]
B -->|block| D[block + reason]
B -->|non-0 exit 2| E[block + stderr]
C --> F[next step]
D --> F
E --> F3 步。
5. 5 步 PreToolUse 完整流¶
sequenceDiagram
participant Claude
participant Hook as PreToolUse hook
participant Tool as Tool
participant User
Claude->>Tool: tool_use (Bash, "git status")
Tool->>Hook: stdin JSON
Note over Hook: matcher = "Bash"
Hook->>Hook: 解析 tool_input.command
Hook->>Hook: check rules
alt allow
Hook-->>Tool: exit 0
Tool->>Tool: exec("git status")
Tool-->>Claude: result
else block
Hook-->>Tool: exit 2 + stderr
Tool-->>Claude: tool_result (is_error: true)
Claude->>User: blocked
end5 步。
6. 4 步 PostToolUse 完整流¶
sequenceDiagram
participant Tool
participant Hook as PostToolUse hook
participant User
Tool->>Tool: exec tool
Tool-->>Tool: result
Tool->>Hook: stdin JSON
Note over Hook: matcher = "Edit|Write"
Hook->>Hook: 解析 tool_input
Hook->>Hook: post-process (e.g. format)
Hook-->>Tool: exit 0
Tool-->>User: result4 步。
7. 5 步 SessionStart¶
sequenceDiagram
participant CC as Claude Code
participant Hook as SessionStart hook
participant User
User->>CC: claude
CC->>CC: init
CC->>Hook: stdin JSON (cwd, env)
Note over Hook: SessionStart context
Hook->>Hook: load project context
Hook->>Hook: log session start
Hook-->>CC: exit 0
CC-->>User: ready5 步。
8. 4 步 SessionEnd 备份¶
sequenceDiagram
participant CC as Claude Code
participant Hook as SessionEnd hook
participant FS as FileSystem
CC->>CC: user exit
CC->>CC: save session
CC->>Hook: stdin JSON (session_id)
Note over Hook: SessionEnd
Hook->>FS: cp session.jsonl backup/
Hook-->>CC: exit 0
CC: exit4 步。
9. 4 步 UserPromptSubmit¶
sequenceDiagram
participant User
participant CC as Claude Code
participant Hook as UserPromptSubmit hook
participant LLM
User->>CC: prompt
CC->>Hook: stdin JSON (prompt)
Note over Hook: UserPromptSubmit
Hook->>Hook: log / context
Hook-->>CC: exit 0
CC->>LLM: send prompt + context
LLM-->>CC: response4 步。
10. 5 步 PreCompact 备份¶
sequenceDiagram
participant CC as Claude Code
participant Hook as PreCompact hook
participant FS as FileSystem
Note over CC: 准备 compact
CC->>Hook: stdin JSON (session_id, transcript_path)
Note over Hook: PreCompact
Hook->>FS: backup transcript
Hook-->>CC: exit 0
CC->>CC: compact
CC: continue5 步。
11. 3 步 Notification 流¶
sequenceDiagram
participant CC as Claude Code
participant Hook as Notification hook
participant User
Note over CC: notification
CC->>Hook: stdin JSON (message)
Hook->>Hook: log / display
Hook-->>CC: exit 0
Note over User: User sees notification3 步。
12. 4 步 Stop / SubagentStop¶
sequenceDiagram
participant LLM
participant CC as Claude Code
participant Hook as Stop hook
LLM-->>CC: stop_reason
CC->>Hook: stdin JSON (transcript)
Note over Hook: Stop
Hook->>Hook: post-process
Hook-->>CC: exit 0
CC: 结束 turn4 步。
13. 5 步 Hook 配置加载¶
graph TD
A[Claude Code start] --> B[load settings.json]
B --> C{4 sources}
C -->|user| D[~/.claude/settings.json]
C -->|project| E[.claude/settings.json]
C -->|local| F[.claude/settings.local.json]
C -->|policy| G[/etc/claude-code/policy.json]
D --> H[merge]
E --> H
F --> H
G --> H
H --> I[hooks config]
I --> J[register]5 步。
14. 3 步 Hook matcher 匹配¶
graph TD
A[hook event] --> B{matcher?}
B -->|empty| C[match all]
B -->|Bash| D[match Bash]
B -->|Edit|Write| E[match Edit or Write]
B -->|mcp__github__*| F[match MCP github]
C --> G[run hooks]
D --> G
E --> G
F --> G3 步。
15. 5 步 Exit Code 语义¶
graph TD
A[hook exit] --> B{code}
B -->|0| C[allow + log]
B -->|2| D[block + stderr → user]
B -->|其他| E[error log, allow]
C --> F[next step]
D --> F
E --> F5 步。
16. 4 步 Matcher 通配¶
graph TD
A[matcher pattern] --> B{contains *}
B -->|yes| C{wildcard}
B -->|no| D{exact}
C -->|Bash(git:*)| E[match git *]
C -->|Bash(*)| F[match all bash]
D -->|Bash(git status)| G[match exact]
D -->|Bash(rm -rf /)| H[match exact]4 步。
17. 5 步 hook chain (多个)¶
graph TD
A[event] --> B[hook 1]
B -->|allow| C[hook 2]
B -->|block| Z[stop]
C -->|allow| D[hook 3]
C -->|block| Z
D -->|allow| E[all approved]
D -->|block| Z5 步。
18. 3 步 hook timeout¶
graph TD
A[run hook] --> B{timer > timeout?}
B -->|no| C[wait]
C --> D{completed?}
D -->|yes| E[exit code]
D -->|no| B
B -->|yes| F[timeout, treat as error]
F --> G[allow + log error]3 步。
19. 4 步 hook 输出捕获¶
graph TD
A[hook output] --> B{stdout JSON?}
B -->|yes| C[parse]
C --> D{decision?}
B -->|no| E[ignore stdout]
D -->|approve| F[allow]
D -->|block| G[block + reason]4 步。
20. 5 步 hook 安全¶
graph TD
A[hook config] --> B{path safe?}
B -->|no| C[deny]
B -->|yes| D{command in path?}
D -->|no| E[deny]
D -->|yes| F{timeout set?}
F -->|no| G[set default 30s]
F -->|yes| H[use config]
G --> I[run]
H --> I
I --> J{exit 0?}
J -->|yes| K[allow]
J -->|no| L[error]5 步。
21. 总结¶
Hook Flow = 9 事件 × 3 类型。
核心： - 22 mermaid 图 - 9 事件触发 - 3 类型执行 - 5 步完整流 - 安全 5 步
下一步： - 渲染 SVG - 加到 mkdocs