Hooks：在指定事件執行檢查

Hooks（事件掛鉤）讓 Gemini CLI 在特定事件發生時執行你寫的程式。本篇用一個小型檢查器示範：在 CLI 準備呼叫 shell 工具前先回傳阻擋原因，讓練習階段保持唯讀。學完後，你會知道事件、設定與程式輸出如何接起來，以及如何分開驗證每一層。

開始前：先理解事件與執行位置

準備 Gemini CLI 0.59.0、Python 與獨立練習資料夾，先讀settings.json 設定和shell 命令。本文設定依官方 Hooks 檔案整理，Python 範例可先在終端機獨立測試；完整觸發還需要自己的 CLI 登入與工具呼叫環境。

Hook 是會在電腦上執行的程式，與純文字自訂指令不同。它不需要模型逐次重新理解檢查邏輯，但程式錯誤、事件選錯或設定未載入，仍會影響結果。測試時先使用假資料，將範圍縮小到單一工具，避免第一次就把複雜處理放進所有事件。

BeforeTool 發生在工具執行前，可用來判斷是否允許這次操作；AfterTool 發生在工具執行後，適合觀察結果，但不能倒轉已發生的寫入。這個時間差是選事件最重要的依據。需要阻止動作時，不能只在事後輸出一段警告。

資料流：標準輸入進來，JSON 結果出去

CLI 會把事件資料以 JSON 送到程式的標準輸入 stdin。BeforeTool 資料包含工具名稱與引數；程式透過標準輸出 stdout 回傳 JSON。除最後的 JSON 外，不要在 stdout 印出「開始檢查」等文字；診斷訊息應寫到 stderr，避免破壞解析。

本例只檢查 tool_name 是否為 run_shell_command，不試圖分析每一種 shell 語法。若符合就回傳 decision 為 deny 與原因，否則回傳 allow。這個簡單規則容易驗證，也清楚表達限制：它只處理被指定的工具，不是所有檔案操作的完整防護，仍需搭配權限與沙箱。

實作：建立檢查器並接上設定

1. 在練習專案建立 .gemini/hooks/block-shell.py，貼上下面的 Python 程式。
2. 先用兩份虛構事件測試程式，一份是 shell、一份是讀檔，核對 deny 與 allow。
3. 把 hooks 物件合併到既有 .gemini/settings.json，不要覆蓋其他模型或記憶設定。
4. 重新啟動 CLI，檢視 /hooks 的清單與狀態，確認設定來源及名稱。
5. 請 CLI 嘗試用 shell 顯示目前資料夾，觀察掛鉤是否回傳教學設定的拒絕原因。

import json
import sys

event = json.load(sys.stdin)
if event.get("tool_name") == "run_shell_command":
    result = {"decision": "deny", "reason": "本次練習禁止 shell，請改用讀檔工具。"}
else:
    result = {"decision": "allow"}
json.dump(result, sys.stdout, ensure_ascii=False)
sys.stdout.write("\n")

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "^run_shell_command$",
        "hooks": [
          {
            "name": "lesson-block-shell",
            "type": "command",
            "command": "python .gemini/hooks/block-shell.py",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

'{"tool_name":"run_shell_command","tool_input":{}}' | python .gemini/hooks/block-shell.py
'{"tool_name":"read_file","tool_input":{}}' | python .gemini/hooks/block-shell.py

預期第一行回傳 deny 與原因，第二行回傳 allow。這證明檢查器邏輯與 JSON 輸出可用；還不能單憑這兩行就宣稱 CLI 已載入掛鉤。完整驗證要看到 CLI 的掛鉤狀態，並確認 shell 沒有實際執行。若 CLI 選了其他工具，表示此次沒有觸發 matcher，應重新設計測試提示詞。

判斷失敗：程式、設定與模型分開看

假如程式獨立測試成功，但 CLI 沒有顯示掛鉤，優先查設定層級與信任狀態。假如掛鉤存在卻報找不到 Python，檢查 CLI 啟動時繼承的 PATH；必要時把 command 的 Python 換成實際執行檔路徑，含空格的路徑需正確引號。不要先修改模型提示詞來修正作業系統找不到程式的問題。

官方文件定義退出碼零表示成功解析輸出，二可阻擋動作，其他非零值通常形成警告。本文採成功退出並回傳明確的 JSON 決策，較容易做測試。若要把例外視為阻擋，應刻意寫出錯誤處理並驗證；不能假設任何程式崩潰都會安全停止後續工作。

常見問題與停用方式

「加了掛鉤後每次都卡住」檢視程式是否等待第二段輸入、呼叫無法結束的外部工具，或把網路等待放進事件內。本例只讀一次 JSON 並立即輸出，適合用來比較。先縮短工作內容，再決定合理逾時；延長逾時不是修復無限等待的方法。

「回傳了 deny 還看到模型回答」拒絕的是那次工具動作，主對話仍可能繼續，模型可以解釋原因或改用其他方法。要驗證的是工具有沒有執行，而不是回答有沒有停止。需要停止整個代理迴圈時，應依對應事件的 continue 行為另行設計。

「如何恢復一般操作」先保留設定備份，從這個專案的 BeforeTool 清單移除本例，重新啟動並檢視 /hooks。再次執行相同無害測試，確認不再被此規則阻擋。別把其他人建立的檢查一起刪除，尤其是專案已有多個 Hook 的情況。

當你要把掛鉤用於正式流程，儲存事件樣本、預期輸出與錯誤測試，並記錄 CLI 版本。搭配Headless 批次處理時，還需確認沒有互動視窗能回答問題的情況下會如何結束，避免排程只留下空白結果卻被當作成功。

完成後的檢核

接著可以閱讀 CLI 權限、Headless 模式，把本篇的操作接到下一個工作流程。

返回 Gemini 教學總目錄

• AI 工具
• 教學
• Gemini CLI 與 API