sid-code

主题

Hook 事件 ​

全部 Hook 事件的配置键名、是否会触发与触发时机。

共 37 类 Hook 事件（从 HookEventName 枚举导出）， 其中 31 类当前有真实触发点。

第一列就是你写进 settings.json 的键名。 两种写法运行时等价 （pre_tool_use 与 PreToolUse 都认，内部会归一化），本表第一列给 snake_case， 第三列是 PascalCase（与 Claude Code 同名，Hook 指南的示例用这种）。 第一列是 PascalCase、枚举名列为 — 的 4 个事件没有 snake_case 别名， 配置里只能写这一种（不是漏写）。

「会触发」列标 ✗ 的事件配了不会被调用，分两种，触发时机列写明是哪一种： 「内部事件」写进配置会被跳过并在启动时告警；「刻意不做」能通过配置校验， 但 sid 没有对应场景，恒不触发（原因见 Hook 指南的刻意偏离表）。

配置里写会触发枚举名（源码内部）触发时机
pre_tool_use✓PreToolUse工具执行前、权限检查之前触发。可 block（返回 deny 则工具不执行）。
post_tool_use✓PostToolUse工具执行成功返回结果后触发。不可 block，仅可注入附加上下文。
post_tool_use_failure✓PostToolUseFailure工具执行了但失败（返回错误或抛异常）后触发；权限拒绝走 PermissionDenied，不触发本事件。不可 block。
user_prompt_submit✓UserPromptSubmit用户输入提交后、入上下文前触发。可 block（原 prompt 不入上下文）。
after_agent✓AfterAgent模型 end_turn 且无待执行工具后触发。不可 block，仅可请求清除上下文。
before_model✓BeforeModel每轮 LLM 请求发出前触发。可 block（阻止本次请求并结束循环）。
after_model✓AfterModel每轮 LLM 响应收全后触发。可 block（丢弃响应并结束循环）。
session_start✓SessionStart会话启动 / resume / /clear 之后 / 压缩之后触发（matcher：source = startup / resume / clear / compact）。stdout 进上下文，不可 block。
session_end✓SessionEnd会话退出前触发（exit / error / abort）。不可 block，超时即放弃。
pre_compact✓PreCompact上下文压缩执行前触发。可 block（跳过本次压缩）。
post_compact✓PostCompact上下文压缩完成后触发。不可 block，异常也不影响压缩结果。
subagent_start✓SubagentStart子代理任务启动前触发。不可 block（block 降级为告警）。
subagent_stop✓SubagentStop子代理任务结束后触发（finally）。不可 block，fire-and-forget。
notification✓NotificationTUI 等待权限确认时触发（matcher：permission_prompt；sid 没有空闲提醒，不发 idle_prompt）。仅通知。
stop✓Stop助手回答收尾、准备停止时触发。可 block（注入错误并重试修复）。
stop_failure✓StopFailure轮次因 API 错误终止时触发（matcher：error_type）。仅通知。
setup✗Setup刻意不做：sid 没有 --init / --maintenance，此事件恒不触发。
permission_request✓PermissionRequest权限需用户确认时触发，与分类器、用户弹窗并行竞争、先到先决。可 block（返回 deny 则拒绝该工具）。
permission_denied✓PermissionDenied权限拒绝后触发（主循环弹窗被拒 / 超时 / 规则直拒，子代理规则直拒 / 自动拒），仅通知、不可改判。
config_change✓ConfigChangesettings 文件被外部修改后触发（matcher：user_settings / project_settings / local_settings / policy_settings）。可 block（回退到变更前的设置，policy_settings 除外）。
file_changed✗FileChanged刻意不做：sid 没有监视任意文件的机制，此事件恒不触发。
cwd_changed✓CwdChangedbash cd 改变工作目录后触发。仅通知。
task_created✓TaskCreatedtask_create 创建任务成功后触发。仅通知（sid 暂不支持 exit 2 回滚创建）。
task_completed✓TaskCompletedtask_update 把任务置为 completed 后触发。仅通知。
BeforePermissionCheck✗—（内部事件，不支持用户配置；写进配置会被跳过并告警）
AfterPermissionCheck✗—（内部事件，不支持用户配置；写进配置会被跳过并告警）
BeforeHookExecution✗—（内部事件，不支持用户配置；写进配置会被跳过并告警）
AfterHookExecution✗—（内部事件，不支持用户配置；写进配置会被跳过并告警）
instructions_loaded✓InstructionsLoaded指令加载到上下文（CLAUDE.md / rules 加载后触发）
teammate_idle✓TeammateIdle团队代理空闲（可 block，用于团队协作场景）
elicitation✓ElicitationMCP server 发来 elicitation 请求、弹给用户之前触发（matcher：server 名）。仅通知。
elicitation_result✓ElicitationResult用户回复 MCP elicitation 之后触发（matcher：server 名）。仅通知。
post_tool_batch✓PostToolBatch一批工具（含并行）全部执行完、结果回灌模型之前触发。仅通知。
pre_model_switch✓PreModelSwitch切换模型之前触发（matcher：trigger = manual / fallback / config）。仅通知（sid 切换路径同步，不支持拒绝）。
post_model_switch✓PostModelSwitch模型切换之后触发，含降级链自动切换（matcher：trigger = manual / fallback / config）。仅通知。
user_prompt_expansion✓UserPromptExpansion斜杠命令 / skill 展开成 prompt 之后、提交之前触发（matcher：命令名）。exit 0 的纯文本 stdout 与 additionalContext 追加到展开结果后。可 block。
directory_added✓DirectoryAdded/add-dir 把目录加入会话白名单之后触发。仅通知。

子代理事件的关联字段（2026-10-14 起） ​

SubagentStart / SubagentStop 以及子代理内工具事件（PreToolUse / PostToolUse …）的 stdin 携带：

字段含义
agent_id规范子代理 id：<parent_session_id>-sub-<taskId>。与该子代理在轨迹里的 StreamPhase / RetryTelemetry / BilledRequest 同值
legacy_agent_id旧形态 subagent-<type>-<taskId>（此前的 agent_id），过渡期保留，后续版本移除
parent_session_id派发子代理的父会话 id
parent_tool_use_id派发它的那次 sub_agent 工具调用 id，等于父会话 PreToolUse 的 tool_use_id；swarm / workflow / skill 派出的子代理无此字段

按旧形态匹配 agent_id 的 hook 脚本请改用 legacy_agent_id 或 agent_type。