Kiro 的 Agent Hooks 提供 9 种触发类型，覆盖从用户提交 prompt、agent 完成响应、工具调用前后，到文件创建/保存/删除，再到 spec 任务执行的完整生命周期。每种类型针对不同自动化场景设计，理解它们的触发时机是构建可靠工作流的前提。

Agent Hooks 支持多种触发类型，每种类型针对 IDE 工作流中的特定时间点。了解各类型的触发时机和适用场景，有助于选择最合适的自动化策略。

Prompt Submit

触发时机：用户提交 prompt 时。

在使用 shell command action 时，用户输入的 prompt 内容可通过环境变量 USER_PROMPT 获取。

典型用途：

• 向 agent 补充与当前 prompt 相关的额外上下文
• 根据 prompt 内容拦截特定类型的请求
• 将所有用户 prompt 记录到集中日志

Agent Stop

触发时机：agent 完成本轮响应、结束回复时。

典型用途：

• 编译代码并将失败信息反馈给 agent
• 格式化或审查 agent 生成的代码
• 审核 agent 所做的变更并提供补充指令

Pre Tool Use

触发时机：agent 即将调用某个工具之前。

在 Tool name 字段中填写需要监听的工具名，支持多个。以下是内置分类关键词：

关键词	匹配范围
read	所有内置文件读取工具
write	所有内置文件写入工具
shell	所有内置 shell 命令工具
web	所有内置网页工具
spec	所有内置 spec 工具
*	全部工具（内置 + MCP）

还支持前缀过滤器，按来源定位工具：

• @mcp — 所有 MCP 工具
• @powers — 所有 powers 工具
• @builtin — 所有内置工具

以 @ 开头的前缀采用正则匹配，例如 @mcp.*sql.* 可精确匹配名称含 sql 的 MCP 工具。

如需查询可用工具名，直接询问 Kiro 即可。

典型用途：

• 拦截特定工具调用
• 在 agent 调用工具前注入额外指令

Post Tool Use

触发时机：agent 完成工具调用之后。

Tool name 字段的用法与 Pre Tool Use 相同。

典型用途：

• 记录工具调用日志用于审计
• 在 write 工具完成后格式化或审查更新的文件
• 在工具响应基础上向 agent 提供额外指令

File Create

触发时机：工作区中符合指定模式的新文件被创建时。

典型用途：

• 为新组件生成样板代码
• 为新文件自动添加 license 头
• 创建实现文件时自动生成对应的测试文件

File Save

触发时机：符合指定模式的文件保存时。

典型用途：

• 运行 lint 和代码格式化
• 更新关联文件
• 生成文档
• 对改动文件运行测试

File Delete

触发时机：符合指定模式的文件被删除时。

典型用途：

• 清理关联文件
• 更新其他文件中的 import 引用
• 维护项目完整性

Pre Task Execution

触发时机：spec 任务开始执行时（任务状态变为 in_progress）。

典型用途：

• 在任务执行前运行环境准备脚本
• 验证任务所需的前置条件是否满足
• 记录任务开始事件

Post Task Execution

触发时机：spec 任务执行完成时（任务状态变为 completed）。

典型用途：

• 任务完成后运行测试验证正确性
• 对改动文件执行 lint 或格式化
• 为完成的工作生成文档
• 通知外部系统任务已完成

Manual Trigger

触发时机：用户手动执行。

典型用途：

• 按需代码审查
• 按需生成文档
• 安全扫描
• 性能优化分析

常见问题

Q：Pre Tool Use 和 Post Tool Use 可以同时监听同一个工具吗？

可以。两者可以独立配置，分别在工具调用前和调用后执行不同的操作，例如"调用前注入上下文 + 调用后审查结果"。

Q：File Save 和 Agent Stop 该怎么选择？

如果想在每次保存文件时立即触发（包括手动保存），用 File Save；如果只关心 agent 完成一轮操作后的最终状态，用 Agent Stop，可以避免 agent 修改多个文件时重复触发。

Q：Pre Task Execution 中的"spec 任务"是指什么？

指的是 Kiro spec 工作流中定义的任务条目（task），当任务状态从 pending 变为 in_progress 时触发。适合在 spec 驱动开发流程中插入环境检查或准备步骤。