钩子

钩子在智能体生命周期边界执行经过审查的行为。Kairo Code 有两个 Hook 能力面：

• Host 所有的 Java Hook 与 guard 执行产品安全、证据和呈现政策；
• 已激活插件可以贡献任务范围的 command、http、prompt、agent 与 mcp_tool Action。

Hook 不是智能体或技能；它没有独立对话，也不能扩大任务工作区、权限配置、网络政策或管理员安全上限。

编写插件 Hook

在插件的 hooks/hooks.json 中定义 Hook，例如：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${KAIRO_PLUGIN_ROOT}/scripts/check.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Matcher 大小写敏感并匹配完整目标；| 分隔备选，* 匹配任意序列，? 匹配一个 Unicode 码点， 缺失或空白 matcher 匹配全部。它是有界通配语言，不是任意正则表达式。

插件必须先安装、审查并激活。新任务取得不可变能力快照；插件启停或回滚不会改变已经运行的任务。 受控安装流程见插件。

运行与失败合同

Kairo Code 为插件 Hook 只安装一个任务范围的框架桥，并保持插件、binding 与 Action 的声明顺序。 每个 Action 接收有界结构化 JSON；command 通过任务执行沙箱运行，http 使用经审查网络路径， 模型、智能体和 MCP Action 使用产品所有的适配器。

在工具、提示词、压缩、权限、子智能体、setup、worktree 或完成决策前，适配器缺失、Action 失败、 无效决策或截断决策都会失败关闭，并停止后续 Action。观察阶段记录失败并保持原事件不变。插件决策目前 支持拒绝、修改工具输入和修改提示词，不会映射成 core 的 SKIP、INJECT 或 COMPLETE。

每个插件 Hook 都是可执行代码。激活前应审查来源、固定修订、命令、URL、模型提示、MCP 目标和请求 数据。Hook 日志不会记录提示词、工具输入、命令或凭据 payload。

已退役的本地 shell 格式

Kairo Code 不读取 ~/.kairo-code/hooks.json 或项目 .kairo-code/hooks.json。旧 flat {matcher, command} 格式依赖独立异步执行器，不是受支持的兼容路径。请把经过审查的行为迁移到插件， 不要继续复制占位符命令到本地文件。

检查 Hook 与守卫

打开 Settings → Extensions → Hooks 检查 Host 所有的 Hook 与 guard 政策。插件 Hook 在 Settings → Extensions → Plugins 中随完整插件快照审查和回滚；Hooks 没有独立的命令管理入口。