Skip to content

C.md

Latest commit

 

History

History
48 lines (42 loc) · 13.1 KB

C.md

File metadata and controls

48 lines (42 loc) · 13.1 KB
Raw

附录 C · Hooks 事件表

生成脚本：scripts/gen-hooks-table.ts；source_commit: 290fdc9481a70612bc5823aa4ed225c52c52aad3

  • HOOK_EVENTS：27 个
  • Hook command type：4 类
  • 已补齐 trigger/payload：27/27

HOOK_EVENTS（来源：entrypoints/sdk/coreSchemas.ts:355-383）

事件名 触发时机 Payload 字段 源码位置
PreToolUse 工具被调度执行之前；可用 exit 2 / decision:'block' 阻断本次工具调用，hook 输出会作为 system reminder 反馈给模型。 session_id
transcript_path
cwd
permission_mode?
agent_id?
agent_type?
hook_event_name='PreToolUse'
tool_name
tool_input
tool_use_id		 schema: entrypoints/sdk/coreSchemas.ts:414-423
dispatch: utils/hooks.ts:3394-3436
call: services/tools/toolHooks.ts (executePreToolHooks)
PostToolUse 工具调用成功完成之后；hook 可通过 decision:'block' 给模型注入反馈（不影响工具结果本身）。 ...BaseHookInput
hook_event_name='PostToolUse'
tool_name
tool_input
tool_response
tool_use_id		 schema: entrypoints/sdk/coreSchemas.ts:436-446
dispatch: utils/hooks.ts:3450-3477
call: services/tools/toolHooks.ts:56
PostToolUseFailure 工具调用失败 / 被中断之后；payload 携带 error 字符串与 is_interrupt 标记，hook 可向模型注入修复建议。 ...BaseHookInput
hook_event_name='PostToolUseFailure'
tool_name
tool_input
tool_use_id
error
is_interrupt?		 schema: entrypoints/sdk/coreSchemas.ts:448-459
dispatch: utils/hooks.ts:3492-3527
call: services/tools/toolHooks.ts:212
Notification 需要向用户弹出系统通知前（待权限确认 / 待 elicitation / 输入空闲提醒等）；hook 可替换或抑制通知。在 REPL 之外执行。 ...BaseHookInput
hook_event_name='Notification'
message
title?
notification_type		 schema: entrypoints/sdk/coreSchemas.ts:473-482
dispatch: utils/hooks.ts:3570-3592
call: services/notifier.ts:25
call: cli/print.ts:1366
call: services/mcp/elicitationHandler.ts:183
call: services/mcp/elicitationHandler.ts:283
call: services/mcp/elicitationHandler.ts:298
call: services/mcp/elicitationHandler.ts:307
UserPromptSubmit 用户在 REPL 中提交 prompt 之后、消息入队 QueryEngine 之前；hook 可改写 prompt 或注入额外 system 消息。 ...BaseHookInput
hook_event_name='UserPromptSubmit'
prompt		 schema: entrypoints/sdk/coreSchemas.ts:484-491
dispatch: utils/hooks.ts:3826-3855
call: utils/processUserInput/processUserInput.ts:182
SessionStart 会话开始或 resume/clear/compact 后重启 session；hook 可注入 system reminder（如自定义 agent 引导语）。 ...BaseHookInput
hook_event_name='SessionStart'
source='startup'|'resume'|'clear'|'compact'
agent_type?
model?		 schema: entrypoints/sdk/coreSchemas.ts:493-502
dispatch: utils/hooks.ts:3867-3892
call: utils/sessionStart.ts:132
SessionEnd 会话结束（logout / clear / resume 切换 / prompt_input_exit 等）；同步触发，关停 Ink 之后直接写 stderr。默认 1.5s 超时（CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS 覆盖）。 ...BaseHookInput
hook_event_name='SessionEnd'
reason ∈ EXIT_REASONS		 schema: entrypoints/sdk/coreSchemas.ts:758-765
dispatch: utils/hooks.ts:4097-4141
call: utils/gracefulShutdown.ts:473
call: screens/REPL.tsx:1774
call: commands/clear/conversation.ts:69
Stop 主线程在一轮回合结束、准备进入 idle 之前；hook 可 exit 2 / decision:'block' 让模型继续执行，用于强制完成额外步骤。 ...BaseHookInput
hook_event_name='Stop'
stop_hook_active
last_assistant_message?		 schema: entrypoints/sdk/coreSchemas.ts:513-527
dispatch: utils/hooks.ts:3639-3697
call: query/stopHooks.ts:180
StopFailure 回合以 assistant 错误（API 错误 / 取消 / overload）收尾时，与 Stop 互斥；payload 携带最后一条 assistant message 与错误字段，主要用于审计 / 告警。 ...BaseHookInput
hook_event_name='StopFailure'
error (SDKAssistantMessageError, 缺省 'unknown')
error_details?
last_assistant_message?		 schema: entrypoints/sdk/coreSchemas.ts:529-538
dispatch: utils/hooks.ts:3594-3627
call: query.ts:1174
call: query.ts:1181
call: query.ts:1263
SubagentStart AgentTool 创建并启动一个 subagent 之前；payload 给出 agent_id + agent_type，便于 hook 给子 agent 注入额外 system reminder。 ...BaseHookInput
hook_event_name='SubagentStart'
agent_id
agent_type		 schema: entrypoints/sdk/coreSchemas.ts:540-548
dispatch: utils/hooks.ts:3932-3952
call: tools/AgentTool/runAgent.ts:532
SubagentStop subagent 完成回合、准备返回结果给父 agent 之前；Stop 的 subagent 变体，executeStopHooks 在传入 subagentId 时切到此事件。可阻断让子 agent 继续工作。 ...BaseHookInput
hook_event_name='SubagentStop'
stop_hook_active
agent_id
agent_transcript_path
agent_type
last_assistant_message?		 schema: entrypoints/sdk/coreSchemas.ts:550-567
dispatch: utils/hooks.ts:3639-3697
call: query/stopHooks.ts:180
PreCompact 压缩流程开始之前（手动 /compact 或 token 自动压缩）；hook 可返回 newCustomInstructions 覆盖默认指令，并把 displayMessage 显示给用户。 ...BaseHookInput
hook_event_name='PreCompact'
trigger='manual'|'auto'
custom_instructions: string|null		 schema: entrypoints/sdk/coreSchemas.ts:569-577
dispatch: utils/hooks.ts:3961-4025
call: services/compact/compact.ts:413
call: services/compact/compact.ts:818
call: commands/compact/compact.ts:160
PostCompact 压缩完成、summary 已写入会话之后；hook 输出仅作为 displayMessage 展示给用户，不参与后续模型上下文。 ...BaseHookInput
hook_event_name='PostCompact'
trigger='manual'|'auto'
compact_summary		 schema: entrypoints/sdk/coreSchemas.ts:579-589
dispatch: utils/hooks.ts:4034-4089
call: services/compact/compact.ts:723
call: services/compact/compact.ts:1069
PermissionRequest 权限引擎判定需要弹出权限对话框之前；hook 可程序化批准 / 拒绝，免去交互。在 REPL（含 SDK structuredIO 通道）与 PermissionContext 内都会触发。 ...BaseHookInput
hook_event_name='PermissionRequest'
tool_name
tool_input
permission_suggestions?: PermissionUpdate[]		 schema: entrypoints/sdk/coreSchemas.ts:425-434
dispatch: utils/hooks.ts:4157-4192
call: utils/permissions/permissions.ts:409
call: cli/structuredIO.ts:798
call: hooks/toolPermission/PermissionContext.ts:222
PermissionDenied 权限引擎判定一次工具调用被拒绝之后，先于错误结果返回模型；fire-and-forget，主要用于审计 / 告警。 ...BaseHookInput
hook_event_name='PermissionDenied'
tool_name
tool_input
tool_use_id
reason		 schema: entrypoints/sdk/coreSchemas.ts:461-471
dispatch: utils/hooks.ts:3529-3562
call: services/tools/toolExecution.ts:1081
Setup 会话初始化 / 周期性维护阶段，紧随 SessionStart 之后；payload trigger 区分 'init' 与 'maintenance'。 ...BaseHookInput
hook_event_name='Setup'
trigger='init'|'maintenance'		 schema: entrypoints/sdk/coreSchemas.ts:504-511
dispatch: utils/hooks.ts:3902-3922
call: utils/sessionStart.ts:203
TeammateIdle teammate（多人协作中的另一个 agent）即将进入 idle 状态时；hook 可 exit 2 让其继续工作，用于强制完成轮询任务。 ...BaseHookInput
hook_event_name='TeammateIdle'
teammate_name
team_name		 schema: entrypoints/sdk/coreSchemas.ts:591-599
dispatch: utils/hooks.ts:3709-3729
call: query/stopHooks.ts:403
TaskCreated TaskCreateTool 创建任务前；hook 可阻断创建并向模型回馈拒绝理由（如校验任务标题命名规范）。 ...BaseHookInput
hook_event_name='TaskCreated'
task_id
task_subject
task_description?
teammate_name?
team_name?		 schema: entrypoints/sdk/coreSchemas.ts:601-612
dispatch: utils/hooks.ts:3745-3773
call: tools/TaskCreateTool/TaskCreateTool.ts:93
TaskCompleted TaskUpdateTool 将任务置为 completed 之前；hook 可阻断完成（例如强制要求附录 / 验收脚本通过）。 ...BaseHookInput
hook_event_name='TaskCompleted'
task_id
task_subject
task_description?
teammate_name?
team_name?		 schema: entrypoints/sdk/coreSchemas.ts:614-625
dispatch: utils/hooks.ts:3789-3817
call: tools/TaskUpdateTool/TaskUpdateTool.ts:235
Elicitation MCP 服务器发起 elicitation 请求、需要向用户弹出对话框前；hook 可程序化返回 accept/decline/cancel 与表单内容，跳过 UI。 ...BaseHookInput
hook_event_name='Elicitation'
mcp_server_name
message
mode='form'|'url'?
url?
elicitation_id?
requested_schema?		 schema: entrypoints/sdk/coreSchemas.ts:627-643
dispatch: utils/hooks.ts:4470-4523
call: services/mcp/elicitationHandler.ts:228
ElicitationResult 用户已经响应 MCP elicitation、即将把结果发回服务器之前；hook 可观察或改写最终响应（含 decline 转 block）。 ...BaseHookInput
hook_event_name='ElicitationResult'
mcp_server_name
elicitation_id?
mode='form'|'url'?
action='accept'|'decline'|'cancel'
content?		 schema: entrypoints/sdk/coreSchemas.ts:645-660
dispatch: utils/hooks.ts:4525-4575
call: services/mcp/elicitationHandler.ts:273
ConfigChange 配置文件 watcher 检测到 user/project/local/policy settings 或 skills 目录变化时；hook 可 exit 2 阻断本次变更生效（policy_settings 例外，hook 仅审计、不可阻断）。 ...BaseHookInput
hook_event_name='ConfigChange'
source ∈ CONFIG_CHANGE_SOURCES
file_path?		 schema: entrypoints/sdk/coreSchemas.ts:670-678
dispatch: utils/hooks.ts:4214-4239
call: utils/settings/changeDetector.ts:292
call: utils/settings/changeDetector.ts:344
call: utils/skills/skillChangeDetector.ts:267
WorktreeCreate 需要为本会话创建 worktree 时；若用户配置了该 hook，则替代默认 git worktree 流程，stdout 中的路径作为新 worktree 根目录。无配置时回退到 git worktree。 ...BaseHookInput
hook_event_name='WorktreeCreate'
name (slug，已经过 validateWorktreeSlug)		 schema: entrypoints/sdk/coreSchemas.ts:709-716
dispatch: utils/hooks.ts:4928-4958
call: utils/worktree.ts:716
call: utils/worktree.ts:913
call: utils/worktree.ts:1262
WorktreeRemove 会话结束 / 用户主动清理 worktree 时；若 hook 配置存在则替代默认 git worktree remove；返回 false 表示无 hook 配置、走默认路径。 ...BaseHookInput
hook_event_name='WorktreeRemove'
worktree_path		 schema: entrypoints/sdk/coreSchemas.ts:718-725
dispatch: utils/hooks.ts:4967-5003
call: utils/worktree.ts:827
call: utils/worktree.ts:968
InstructionsLoaded CLAUDE.md 或 .claude/rules/*.md 等指令文件被加载进上下文时（session_start / nested_traversal / path_glob_match / include / compact 五种场景）；fire-and-forget，仅用于观察与审计，不能阻断。 ...BaseHookInput
hook_event_name='InstructionsLoaded'
file_path
memory_type ∈ {User, Project, Local, Managed}
load_reason ∈ INSTRUCTIONS_LOAD_REASONS
globs?
trigger_file_path?
parent_file_path?		 schema: entrypoints/sdk/coreSchemas.ts:695-707
dispatch: utils/hooks.ts:4335-4369
call: utils/claudemd.ts:1060
call: utils/attachments.ts:1760
CwdChanged 会话 cwd 发生切换之后（如 /cd 命令、worktree 切换）；hook 输出可声明 watchPaths 让 FileChanged watcher 重新订阅，并向 REPL 推 systemMessage。 ...BaseHookInput
hook_event_name='CwdChanged'
old_cwd
new_cwd		 schema: entrypoints/sdk/coreSchemas.ts:727-735
dispatch: utils/hooks.ts:4260-4276
call: utils/hooks/fileChangedWatcher.ts:148
FileChanged FileChangedWatcher 监听到 watchPaths 内文件 add/change/unlink 之后；hook 可输出新的 watchPaths 动态扩缩订阅集，输出失败将作为系统消息提示用户。 ...BaseHookInput
hook_event_name='FileChanged'
file_path
event='change'|'add'|'unlink'		 schema: entrypoints/sdk/coreSchemas.ts:737-745
dispatch: utils/hooks.ts:4278-4294
call: utils/hooks/fileChangedWatcher.ts:85

Hook command type（来源：schemas/hooks.ts）

类型 行号
agent 129
command 33
http 98
prompt 68