Skip to main content

Session Hook

透過 hooks 可於 Copilot session 的各生命週期插入處理。 可在不改動核心實作的情況下,加入工具執行控制、稽核日誌、prompt 補強、錯誤處理等功能。

Hook 流程

基本用法

可用 hook

回傳 null 時會繼續預設行為。

常見的使用情境

1) Permission control(執行控制)

  • onPreToolUse 以 allow-list 方式管理允許的工具
  • 破壞性操作以 permissionDecision: 'ask' 進行人為核准
  • permissionDecisionReason 明示拒絕原因
  • toolName 的候選項可從 Tools 的清單確認(如 view, glob, bash

2) Auditing / compliance(稽核)

  • 組合生命週期 hook 蒐集稽核事件
  • 蒐集到的資料以 session ID 為單位持久化

3) Prompt enrichment(輸入補強)

  • onSessionStart 將專案資訊(語言、框架、規範)加入 additionalContext
  • onUserPromptSubmitted 展開捷徑(/fix, /test

4) Result filtering(結果整理)

  • onPostToolUse 遮罩 API key / token / password 等
  • 對過長結果進行摘要化,僅於需要時回傳細節

5) Error recovery(故障復原)

  • onErrorOccurred 僅當 model_callrecoverable=true 時執行 retry
  • 對無法回復的錯誤,以 userNotification 簡潔通知使用者

6) Session metrics(度量)

  • onSessionStart 記錄開始時間
  • onPreToolUse / onUserPromptSubmitted 更新計數器
  • onSessionEnd 輸出耗時、工具次數、結束原因

Hook input / output 型別

共用輸入(BaseHookInput

PreToolUseHookInput

PreToolUseHookOutput

PostToolUseHookInput

PostToolUseHookOutput

UserPromptSubmittedHookInput

UserPromptSubmittedHookOutput

SessionStartHookInput

SessionStartHookOutput

SessionEndHookInput

SessionEndHookOutput

ErrorOccurredHookInput

ErrorOccurredHookOutput

ToolResultObject

工具執行結果的標準物件。

最佳實踐

  1. 不要在 hook 內直接執行過重的同步處理,如有必要請改為非同步。
  2. 不需變更時回傳 null,交由預設行為。
  3. 盡可能明確指定 permissionDecision
  4. 對關鍵錯誤不要過度抑制,保有日誌 / 通知的路徑。
  5. Session 層級狀態以 session id 為基準管理,並於 onSessionEnd 清理。
最新資訊請參考 GitHub 儲存庫
最後修改於 2026年8月2日