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 放入流水線時，繼續看自動化指令碼設計。