智能体、任务与通知事件

Notification

Claude Code 发出通知时运行，按通知类型匹配；省略 matcher 则对所有类型运行。即使关闭了桌面通知你也会收到这些 Hook 事件：preferredNotifChannel 设置（含 notifications_disabled）只改变提醒你的方式，不改变 Hook 是否运行。

matcher	触发时机
permission_prompt	Claude 需要你批准工具使用或沙箱命令的网络请求，且提示已等待约六秒
idle_prompt	Claude 约 60 秒前回复完毕，此后你没有输入
auth_success	认证完成
elicitation_dialog	MCP 服务器打开了 elicitation 表单且你约六秒没有输入
elicitation_url_dialog	MCP 服务器请求你打开浏览器 URL 且约六秒没有输入
elicitation_complete	MCP 服务器报告 URL 模式的 elicitation 已完成
elicitation_response	一个 MCP elicitation 响应被发回服务器
agent_needs_input	后台会话开始等待你的输入，且终端里开着智能体视图（v2.1.198+）
agent_completed	后台会话完成或失败，仅在终端里开着智能体视图时触发（v2.1.198+）
quota_auto_resume_fired	claude.ai 用量上限暂停任务后 Claude Code 自动继续（v2.1.234+）
quota_auto_resume_stale	用量上限重置时电脑休眠超过约 30 分钟，Claude Code 等你按 Enter 而不是继续
quota_auto_resume_disabled	Claude Code 结束对用量上限的等待而不继续任务（如 autoContinueAtUsageLimit 被关闭）

permission_prompt、idle_prompt、elicitation_dialog、elicitation_url_dialog 与桌面通知共用时序：终端会话里只在你看起来不在场时才触发——permission_prompt 在约六秒没有输入后（计时从权限提示出现起算，每次击键会推迟它；想在 Claude 请求权限时立刻运行 Hook 用 PermissionRequest）；idle_prompt 在 Claude 回复完约 60 秒后（等待 claude.ai 用量上限重置期间不发）。另一个对话框正显示时到达的请求沿用同一个六秒门。把权限请求发给 Agent SDK canUseTool 回调的会话（Claude Desktop 和 VS Code 扩展就是这样）里，permission_prompt 在 Claude 请求权限约六秒后触发、不随你输入推迟，你或 PermissionRequest Hook 更早回答时不触发；设置 CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS=1 可在这类会话里关闭。可以用不同 matcher 为不同通知类型运行不同的处理器。输入：message（通知文本）、可选 title、notification_type。Notification Hook 不能阻止或修改通知，其 systemMessage 和 continue 被丢弃，但 terminalSequence 仍会发出（桌面通知就靠它）。

SubagentStart

Claude 用 Agent 工具派生子智能体、恢复子智能体、以及进程内的智能体团队队友每处理一条新消息时运行。matcher 按智能体类型名过滤：内置智能体是 general-purpose、Explore、Plan 等名称；自定义子智能体是前置信息里的 name（不是文件名）；插件提供的子智能体是插件作用域的标识（如 my-plugin:reviewer）。输入：agent_id（子智能体唯一标识）、agent_type。不能阻止子智能体创建，但可以向它注入上下文：返回 additionalContext，加到子智能体对话开头、第一个提示之前；同一子智能体再次运行该 Hook 时，只在子智能体上下文里还没有早先那份副本时才注入。

SubagentStop

Claude Code 子智能体回复完毕时运行，matcher 同 SubagentStart。输入：stop_hook_active、agent_id、agent_type、agent_transcript_path（子智能体自己的转录；transcript_path 则是主会话的）、last_assistant_message，以及与 Stop 相同的 background_tasks 和 session_crons（都限定在父会话范围内）。并非每个 SubagentStop 都来自 Claude 派生的子智能体：Claude Code 也为自己的一些功能（如提示建议）运行内部智能体，此时 agent_type 为空；点名智能体类型的 matcher 匹配不到空的 agent_type，而省略、""、"*" 或能匹配空串的正则会对这些事件运行。在 v2.1.271 及以上，带 SubagentHandback 工具（auto 模式提供）运行的子智能体会通过该工具交付报告。决策控制与 Stop 相同（见下），包括 hookSpecificOutput.additionalContext（hookEventName 设为 "SubagentStop"）。

TaskCreated

通过 TaskCreate 工具创建任务时运行，用于强制命名约定、要求任务描述或阻止创建某些任务；没有任务工具的会话里不触发。不支持 matcher，每次都触发。输入：task_id、task_subject，可选 task_description、teammate_name、team_name（已弃用，将来移除）。阻止创建两种方式（Claude Code 都会删除该任务并把你的消息作为工具错误返回给 Claude，且忽略此事件的 continue: false）：退出 2（stderr 文本作为消息）；JSON {"decision": "block", "reason": "..."}（reason 作为消息）。

TaskCompleted

任务被标记为完成时运行，两种情形：任一智能体通过 TaskUpdate 工具显式把任务标为完成；或智能体团队的队友在仍有进行中任务时结束它的回合。用于在任务关闭前强制完成标准（测试通过、lint 通过）。不支持 matcher。输入：task_id、task_subject，可选 task_description、teammate_name、team_name。控制：退出 2 使任务不被标为完成，stderr 作为反馈回给模型；JSON {"continue": false, "stopReason": "..."} 在由队友结束回合触发该事件时完全停止该队友（与 Stop Hook 行为一致），stopReason 显示给用户。

Stop

主 Claude Code 智能体回复完毕时运行；用户中断造成的停止不运行，API 错误改触发 StopFailure。/goal 命令就是「会话级的基于提示的 Stop Hook」的内置快捷方式，想让 Claude 持续工作到满足某个条件而又不想写 Hook 配置时用它。输入：stop_hook_active（Claude Code 已经因 Stop Hook 而继续运行时为真，用来避免死循环）、last_assistant_message（Claude 最后回复的文本，无需解析转录）、background_tasks、session_crons——后两个数组让 Hook 区分「会话完成了」和「会话在等后台工作把它唤醒而处于暂停」。background_tasks 每项描述一个进行中的任务：id、type（shell、subagent、monitor、workflow、teammate、cloud session、MCP task）、status、description（上限 1000 字符）、command（仅 shell，上限 1000 字符）、agent_type（仅 subagent）、server/tool（仅 monitor 和 MCP task）、name（仅 workflow）；session_crons 每项描述一个会话级定时唤醒（来自 CronCreate、ScheduleWakeup、/loop）：id、schedule（cron 表达式）、recurring、prompt（上限 1000 字符）。决策控制（Stop 和 SubagentStop）：

字段	说明
decision	"block" 阻止 Claude 停止；省略则允许停止
reason	decision 为 block 时必填，告诉 Claude 为什么应该继续
hookSpecificOutput.additionalContext	非错误的反馈：对话继续以便 Claude 据此行动，但与 decision: "block" 不同，它在转录里显示为 Hook 反馈

退出 2 阻止的方式与 reason 相同：Claude 收到 stderr 作为应该继续的解释。Hook 按设计工作、只是给 Claude 指导（如「完成前先运行测试套件」）时用 additionalContext，它通过同样的循环保护让对话继续。

StopFailure

回合因 API 错误结束时代替 Stop 运行；Claude Code 忽略其输出和退出码（terminalSequence 除外）；用于记录失败、发告警或做恢复动作（限流、认证问题等其他 API 错误）。输入：error（错误类型：rate_limit、overloaded、authentication_failed、oauth_org_not_allowed、account_on_hold、billing_error、invalid_request、model_not_found、server_error、max_output_tokens 等，完整取值以官方为准）、可选 error_details、可选 last_assistant_message（与 Stop/SubagentStop 里是 Claude 的对话输出不同，这里是对话里显示的错误文本）。没有决策控制，仅用于通知和日志。

TeammateIdle

智能体团队的队友完成回合、即将进入空闲时运行；用于在队友停止前强制质量门槛（如要求 lint 通过、验证输出文件存在）。不支持 matcher。输入：teammate_name、team_name（已弃用）。控制：退出 2 让队友收到 stderr 作为反馈并继续工作而不是空闲；JSON {"continue": false, "stopReason": "..."} 完全停止该队友（与 Stop Hook 行为一致），stopReason 显示给用户。