Hooks
Gemini CLI hooks 的事件、配置、JSON I/O、退出码、安全边界和管理命令。
Hooks 是 Gemini CLI agent loop 里的同步拦截点。它允许你在不改 CLI 源码的情况下，注入上下文、校验工具调用、记录审计日志或阻断危险动作。
Hooks 会以当前用户权限执行命令。陌生项目的项目级 hooks 必须先审查，不要直接信任。
典型用途
- 会话开始时加载项目状态。
- 模型请求前补充或过滤上下文。
- 工具执行前检查参数。
- 工具执行后解析结果。
- 对输出做脱敏或审计。
- 按策略禁用部分工具。
常见事件
常见事件包括 SessionStart、SessionEnd、BeforeAgent、AfterAgent、BeforeModel、AfterModel、BeforeToolSelection、BeforeTool、AfterTool、PreCompress、Notification。其中 BeforeTool 和 AfterTool 最常用于工具参数校验、结果过滤和审计记录。
配置位置
优先级从高到低：
- 项目配置：
.gemini/settings.json - 用户配置：
~/.gemini/settings.json - 系统配置：
/etc/gemini-cli/settings.json - extensions 内置 hooks
配置通常写在 hooks.BeforeTool、hooks.AfterTool 等事件下，用 matcher 匹配工具，再指定 hook 的 name、type、command、timeout。安全检查脚本可以放在 $GEMINI_PROJECT_DIR/.gemini/hooks/。
JSON 规则
Hook 通过 stdin 接收 JSON，通过 stdout 返回 JSON。
stdout 只能输出最终 JSON，不能夹杂 echo、日志或调试文本。调试信息写到 stderr。
退出码
0 表示成功且 stdout JSON 会被解析；2 表示系统级阻断，目标动作中止；其他退出码会作为非致命警告处理，原流程通常继续。
管理命令
常用命令包括 /hooks panel、/hooks enable-all、/hooks disable-all、/hooks enable <name>、/hooks disable <name>。
安全边界
Hooks 会以当前用户权限执行任意命令。陌生项目里的项目级 hooks 不能直接信任，尤其不要让 hooks 读取密钥、上传文件或静默执行部署。
| Hook 类型 | 适合做什么 | 不适合做什么 |
|---|---|---|
BeforeTool | 校验命令、路径、MCP 参数 | 大型网络请求 |
AfterTool | 记录审计、解析失败原因 | 修改真实产物 |
BeforeModel | 注入少量上下文 | 拼接大文件 |
AfterAgent | 最终 QA、总结检查 | 高频重活 |
性能和调试
Hooks 是同步执行的，慢 hook 会拖慢 agent loop。高频事件不要做网络请求或大文件扫描；确实需要时，缓存结果并用 matcher 缩小触发范围。只想做最终质量检查时，用 AfterAgent，不要在 AfterModel 的每个输出片段上做重活。
调试 hook 时，先用样例 JSON 手动运行脚本，确认 stdout 是合法 JSON、退出码符合预期。复杂 hook 单独写日志文件，不要把调试文本写到 stdout。
验收方式
至少测试三条路径：允许、阻断、脚本异常。允许路径返回 {"decision":"allow"} 或空 JSON；阻断路径要给出可读原因；脚本异常不能静默放过高风险工具。项目级 hook 被 git pull 改动后，也要确认 CLI 会重新提示信任。
接下来去哪
Headless mode
hooks 稳定后，继续看脚本和 CI 的非交互式运行。
Policy engine
权限边界优先写 policy，hooks 用于补充校验和审计。
Automation
准备把 hooks 放入流水线时，继续看自动化脚本设计。