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_call且recoverable=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
工具執行結果的標準物件。最佳實踐
- 不要在 hook 內直接執行過重的同步處理,如有必要請改為非同步。
- 不需變更時回傳
null,交由預設行為。 - 盡可能明確指定
permissionDecision。 - 對關鍵錯誤不要過度抑制,保有日誌 / 通知的路徑。
- Session 層級狀態以 session id 為基準管理,並於
onSessionEnd清理。
最新資訊請參考 GitHub 儲存庫。