插件 Hooks 与事件

插件可以返回事件处理和专门 hooks。事件通知用于观察已经发生的变化，执行前后 hook 用于相应流程；不能把所有事件名称都当成具有相同 input/output 的函数。

可订阅事件类别

类别	官方列出的名称
命令、安装与服务	command.executed、installation.updated、server.connected
文件	file.edited、file.watcher.updated
LSP	lsp.client.diagnostics、lsp.updated
消息	message.part.removed、message.part.updated、message.removed、message.updated
权限	permission.asked、permission.replied
会话	session.created、session.compacted、session.deleted、session.diff、session.error、session.idle、session.status、session.updated
待办	todo.updated
TUI	tui.prompt.append、tui.command.execute、tui.toast.show

官方通知示例在返回的 event 回调里检查 event.type === "session.idle"。该示例使用 macOS osascript，不能直接当成跨平台通知命令；桌面应用本身也支持响应完成或错误通知。

工具执行前后

tool.execute.before 和 tool.execute.after 围绕工具执行运行。官方示例可通过 input.tool 区分工具，在相应 output.args 中处理参数。

.env 保护示例只针对 read 工具，并检查 filePath 是否包含 .env。这不是涵盖 shell、所有路径别名和其他工具的完整访问控制，应结合权限理解。

对于补丁工具，名称是 apply_patch，参数使用 patchText，路径位于补丁标记中，而不是统一的 filePath。细节见工具参考。

Shell 环境

shell.env 可向 output.env 注入值，input.cwd 提供该次 shell 的工作目录。官方说明该 hook 涉及 AI 工具与用户终端的 shell 执行。

如果注入凭据，应确认哪些 shell 都会接收到它，不要因为变量只出现在一个插件文件中就假定只有某个工具能访问。官方示例里的明文 secret 只是演示，不是共享配置的推荐保存方式。

压缩前的上下文

实验性 experimental.session.compacting 在模型生成继续工作摘要前运行。向 output.context 数组追加内容，可补充当前任务状态、重要决定或仍在处理的文件。

如果设置 output.prompt，它会完全替换默认压缩提示，且 output.context 被忽略。二者不是叠加关系；选择替换时应自行覆盖后续会话需要保留的内容。

验证扩展

按插件加载顺序检查是否有多个 hook 连续修改同一数据。用小任务验证触发时机、参数和错误结果，再检查日志。一个通知收到或一次 hook 成功，不足以证明所有执行路径都受到同样控制。