Kiro hooks 的触发事件确定后，需要为每个 hook 配置一个动作。系统支持两种动作类型：Agent Prompt（发送 prompt 让 Kiro 处理）和 Shell Command（执行本地 Shell 命令）。两者在速度、成本和适用场景上各有不同——Agent Prompt 适合需要 AI 判断和上下文理解的任务，Shell Command 适合确定性操作且不消耗 credits。理解两者的差异有助于设计出更高效的 hook 工作流。

Hook 动作类型

确定好触发事件后，下一步是选择 hook 的动作类型。Kiro 支持两种动作：Agent Prompt（"Ask Kiro"）和 Shell Command（"Run Command"）。

Agent Prompt 动作

通过这种动作，你可以定义一段 prompt，在 hook 触发时自动发送给 Agent。Agent 会像处理聊天面板中的普通 prompt 一样响应并执行。

对于 PromptSubmit 触发器，这种动作被称为 "Add to prompt"：hook 中定义的 prompt 会追加到用户的原始 prompt 后面，合并后一起发送给 Agent。

Shell Command 动作

通过这种动作，你可以定义一段 Shell 命令，在 hook 触发时直接执行。

命令成功时（退出码为 0）：命令的 stdout 输出会被添加到 Agent 的上下文中。

命令失败时（退出码非 0）：stderr 输出会被发送给 Agent，同时通知 Agent hook 执行出错。此外：

• 对于 Pre Tool Use hook：对应的工具调用会被阻断
• 对于 Prompt Submit hook：用户的 prompt 提交会被阻断

可以为 Shell Command 配置执行超时时间，默认超时为 60 秒。设置为 0 可禁用超时。

如何选择动作类型

选择 Agent Prompt 动作，当你希望在触发事件发生后，用自然语言指示 Agent 根据当前上下文执行某些操作时。例如：分析保存的文件、检查代码规范、生成文档说明。

选择 Shell Command 动作，当你需要执行特定命令或一组确定性操作，且这些操作不依赖 Agent 的当前上下文时。例如：格式化代码、运行测试、调用外部 API。

关于成本和速度的重要差异：

• Agent Prompt 动作会消耗 credits，因为每次触发都启动一个新的 Agent 循环
• Shell Command 动作不消耗 credits，在本地执行，速度也更快

如果某个任务可以用确定性命令完成，优先选择 Shell Command 动作；只有在需要 AI 的判断和理解能力时，才选择 Agent Prompt 动作。

常见问题

Q：Shell Command 动作的执行环境是什么？

A：Shell Command 在你的本地机器上执行，使用的是系统默认 Shell 环境（macOS/Linux 为 bash/zsh，Windows 为 PowerShell 或 cmd）。你可以使用系统中已安装的任何命令行工具，但要注意 PATH 环境变量是否包含你需要的工具路径。

Q：Agent Prompt 动作中能引用触发事件的上下文吗？比如哪个文件被保存了？

A：可以。Kiro 会自动将触发事件的相关信息（如文件路径、变更内容）注入到 Agent 的上下文中。你只需在 prompt 中描述任务，Agent 能感知到是哪个文件触发了这次 hook。

Q：一个 hook 可以同时配置两种动作吗？

A：不可以，每个 hook 只能选择一种动作类型。如果你需要先执行 Shell 命令再让 Agent 处理，可以创建两个独立的 hook，或者在 Shell Command 中将 stdout 结果写入文件，再由另一个 hook 的 Agent Prompt 读取处理。