Hooks

在 Gemini CLI 智能体循环的固定点运行脚本：事件列表、严格的 JSON 规则、退出码、matcher、配置层级与 schema。

Hooks 是 Gemini CLI 在智能体循环的特定点执行的脚本或程序，让你无需修改 CLI 源码就能拦截和定制行为。hooks 作为智能体循环的一部分同步运行：hook 事件触发时，Gemini CLI 会等所有匹配的 hooks 完成后才继续。用 hooks 可以：添加上下文（在模型处理请求前注入 git 历史等相关信息）、验证动作（审查工具参数并阻止可能危险的操作）、强制策略（实现安全扫描器和合规检查）、记录交互（跟踪工具使用和模型回复用于审计）、优化行为（动态过滤可用工具或调整模型参数）。

事件

事件	何时触发	影响	常见用途
`SessionStart`	会话开始时（启动、恢复、清除）	注入上下文	初始化资源、加载上下文
`SessionEnd`	会话结束时（退出、清除）	仅供参考	清理、保存状态
`BeforeAgent`	用户提交提示之后、规划之前	阻止回合 / 上下文	添加上下文、验证提示、阻止回合
`AfterAgent`	智能体循环结束时	重试 / 中止	审查输出、强制重试或中止执行
`BeforeModel`	向 LLM 发送请求之前	阻止回合 / 模拟	修改提示、切换模型、模拟回复
`AfterModel`	收到 LLM 回复之后	阻止回合 / 脱敏	过滤/脱敏回复、记录交互
`BeforeToolSelection`	LLM 选择工具之前	过滤工具	过滤可用工具、优化选择
`BeforeTool`	工具执行之前	阻止工具 / 改写	验证参数、阻止危险操作
`AfterTool`	工具执行之后	阻止结果 / 上下文	处理结果、运行测试、隐藏结果
`PreCompress`	上下文压缩之前	仅供参考	保存状态、通知用户
`Notification`	发生系统通知时	仅供参考	转发到桌面提醒、日志

全局规则

hooks 通过 stdin（输入）和 stdout（输出）通信，官方称之为「黄金法则」：

必须沉默：脚本不得向 stdout 打印最终 JSON 对象之外的任何纯文本，哪怕在 JSON 之前有一个 echo 或 print 调用都会破坏解析
污染等于失败：stdout 含有非 JSON 文本时解析会失败，CLI 会默认「允许」并把整个输出当作 systemMessage
用 stderr 调试：所有日志和调试用 stderr（如 echo "debug" >&2），Gemini CLI 捕获 stderr 但从不尝试把它当 JSON 解析

退出码：

退出码	标签	行为影响
0	成功	`stdout` 被解析为 JSON；所有逻辑（包括有意的阻止，如 `{"decision": "deny"}`）的首选退出码
2	系统阻止	关键阻止：目标动作（工具、回合或停止）被中止，`stderr` 作为拒绝原因；严重程度高，用于安全拦截或脚本失败
其他	警告	非致命失败，显示警告，但交互使用原始参数继续

Matcher：用 matcher 字段过滤哪些具体工具或触发器触发你的 hook。工具事件（BeforeTool、AfterTool）的 matcher 是正则表达式（如 "write_.*"）；生命周期事件的 matcher 是精确字符串（如 "startup"）；通配符 "*" 或空字符串 "" 匹配所有。

配置

hooks 在 settings.json 里配置。Gemini CLI 按以下优先顺序（从高到低）合并多层配置：项目设置（当前目录的 .gemini/settings.json）、用户设置（~/.gemini/settings.json）、系统设置（/etc/gemini-cli/settings.json）、扩展（已安装扩展定义的 hooks）。配置 schema 示例：

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "name": "security-check",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

每个事件的输入输出 JSON schema、可用的环境变量、timeout 默认值，以及安全和性能最佳实践，以官方 Hooks reference 页为准。