Session Hook

透過 hooks 可於 Copilot session 的各生命週期插入處理。可在不改動核心實作的情況下，加入工具執行控制、稽核日誌、prompt 補強、錯誤處理等功能。這與自訂 agent 定義中的宣告式 hooks 及檔案型 hook 載入是不同的功能。Agent 層級的設定請參閱自訂 Agent。

檔案型 hook 的探索

hookDirectories 可指定用於探索檔案型 hook 的明確根目錄。此設定僅用於探索，不會授予 agent 一般的檔案存取權限。即使停用 enableConfigDiscovery 或 enableFileHooks，仍可使用明確指定的根目錄。相對路徑會以指定當下有效的 workingDirectory 為基準，僅解析一次。

省略或 null：不變更其他探索來源
[]：僅清除明確指定的 SDK 根目錄

Hook 來源的停用設定與 Managed Settings 仍會套用。 enableFileHooks 控制來自儲存庫的檔案型 hook（.github/hooks/ 及受信任儲存庫設定中的根目錄）。它不會停用明確指定的 hookDirectories 或 PHP 回呼的 hooks。

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    workingDirectory: '/workspace/project',
    enableFileHooks: false,
    hookDirectories: ['../shared-hooks'],
);

Hook 流程

基本用法

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionHooks;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookInput;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookOutput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\SessionEndHookInput;
use Revolution\Copilot\Types\Hooks\SessionEndHookOutput;
use Revolution\Copilot\Types\Hooks\SessionStartHookInput;
use Revolution\Copilot\Types\Hooks\SessionStartHookOutput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookInput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookOutput;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: '請摘要 README 的重點');
    dump($response->content());
}, config: [
    'model' => 'gpt-5',
    'hooks' => new SessionHooks(
        onSessionStart: function (SessionStartHookInput $input): ?SessionStartHookOutput {
            return new SessionStartHookOutput(
                additionalContext: "Project root: {$input->cwd}",
            );
        },

        onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
            if (str_starts_with($input->prompt, '/fix')) {
                return new UserPromptSubmittedHookOutput(
                    modifiedPrompt: '請修正目前的錯誤，並摘要變更點。',
                );
            }

            return null;
        },

        onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
            $blocked = ['bash', 'shell', 'delete_file'];

            if (in_array($input->toolName, $blocked, true)) {
                return new PreToolUseHookOutput(
                    permissionDecision: 'deny',
                    permissionDecisionReason: "{$input->toolName} 在此環境不被允許",
                );
            }

            return new PreToolUseHookOutput(permissionDecision: 'allow');
        },

        onPostToolUse: function (PostToolUseHookInput $input): ?PostToolUseHookOutput {
            if ($input->toolName === 'read_file') {
                return new PostToolUseHookOutput(
                    additionalContext: '如有需要請也探索相關檔案並比較。',
                );
            }

            return null;
        },

        onErrorOccurred: function (ErrorOccurredHookInput $input): ?ErrorOccurredHookOutput {
            if ($input->errorContext === 'model_call' && $input->recoverable) {
                return new ErrorOccurredHookOutput(
                    errorHandling: 'retry',
                    retryCount: 2,
                    userNotification: '因暫時性的模型錯誤將進行重試。',
                );
            }

            return null;
        },

        onSessionEnd: function (SessionEndHookInput $input): ?SessionEndHookOutput {
            if ($input->reason !== 'complete') {
                return new SessionEndHookOutput(
                    sessionSummary: "Session ended with reason: {$input->reason}",
                );
            }

            return null;
        },
    ),
]);

可用 hook

Hook	觸發時機	主要用途
`onSessionStart`	Session 開始（`new` / `resume` / `startup`）	注入初始脈絡、覆寫設定
`onUserPromptSubmitted`	使用者送出 prompt 時	Prompt 補強、範本展開、輸入過濾
`onPreToolUse`	工具執行前	允許 / 拒絕 / 需確認、參數修改、輸出抑制
`onPostToolUse`	工具執行後	結果修改、機密資訊遮罩、稽核日誌
`onErrorOccurred`	Session 內發生錯誤時	重試、通知、錯誤分類
`onSessionEnd`	Session 結束時	清理、指標、結束摘要

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

封鎖 prompt

onUserPromptSubmitted 可回傳 decision: 'block' 來拒絕 prompt。被拒絕時不會開始模型 turn，也不會記錄使用者訊息。若指定 reason，其內容會包含在 warningType: "policy_blocked" 的暫時性 session.warning 事件中。

onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
    if (str_contains($input->prompt, 'restricted')) {
        return new UserPromptSubmittedHookOutput(
            decision: 'block',
            reason: '此 prompt 不被允許。',
        );
    }

    return 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`）

屬性	型別	說明
`sessionId`	`string`	相關的執行期 session ID。子工具的 hook 為子 session，subagent 的開始/停止 hook 則為父 session ID
`timestamp`	`int`	Hook 觸發時間（Unix ms）
`cwd`	`string`	目前工作目錄
`agentId`	`?string`	執行 hook 的 subagent 的 actor ID
`agentType`	`?string`	Subagent 的類型
`parentAgentId`	`?string`	直接上層的 actor ID

agentId / agentType / parentAgentId 可在由 subagent 作為 actor 的 hook 中使用。根 agent 的 hook 不會包含這些欄位。在較舊的執行期中，缺少資訊時會直接省略欄位本身。因此，這些值都可能為 null。

onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
    if ($input->agentId !== null) {
        logger()->info('Subagent tool use', [
            'agentId' => $input->agentId,
            'agentType' => $input->agentType,
            'parentAgentId' => $input->parentAgentId,
            'tool' => $input->toolName,
        ]);
    }

    return null;
},

`PreToolUseHookInput`

屬性	型別	說明
`toolName`	`string`	即將執行的工具名稱
`toolArgs`	`mixed`	即將執行的參數

`PreToolUseHookOutput`

屬性	型別	說明
`permissionDecision`	`?string`	`allow` / `deny` / `ask`
`permissionDecisionReason`	`?string`	拒絕 / 確認時的理由
`modifiedArgs`	`mixed`	覆寫後的參數
`additionalContext`	`?string`	追加脈絡
`suppressOutput`	`?bool`	抑制工具輸出

`PostToolUseHookInput`

屬性	型別	說明
`toolName`	`string`	已執行工具名稱
`toolArgs`	`mixed`	執行時的參數
`toolResult`	`ToolResultObject\|array`	工具結果

`PostToolUseHookOutput`

屬性	型別	說明
`modifiedResult`	`ToolResultObject\|array\|null`	修改後的結果
`additionalContext`	`?string`	追加脈絡
`suppressOutput`	`?bool`	抑制工具結果顯示

`UserPromptSubmittedHookInput`

屬性	型別	說明
`prompt`	`string`	使用者輸入的 prompt

`UserPromptSubmittedHookOutput`

屬性	型別	說明
`modifiedPrompt`	`?string`	修改後的 prompt
`additionalContext`	`?string`	補充脈絡
`suppressOutput`	`?bool`	抑制回應顯示
`decision`	`?string`	設為 `block` 時拒絕 prompt，並抑制模型 turn 與使用者訊息的記錄
`reason`	`?string`	拒絕理由。會包含在 `session.warning` 事件中

`SessionStartHookInput`

屬性	型別	說明
`source`	`string`	`startup` / `resume` / `new`
`initialPrompt`	`?string`	初始 prompt

`SessionStartHookOutput`

屬性	型別	說明
`additionalContext`	`?string`	Session 初始脈絡
`modifiedConfig`	`?array`	Session 設定的部分覆寫

`SessionEndHookInput`

屬性	型別	說明
`reason`	`string`	`complete` / `error` / `abort` / `timeout` / `user_exit`
`finalMessage`	`?string`	最終訊息
`error`	`?string`	結束時的錯誤。若執行期傳入錯誤物件，當 `message` 為字串時使用該值，否則為物件的 JSON 字串

`SessionEndHookOutput`

屬性	型別	說明
`suppressOutput`	`?bool`	抑制最終輸出
`cleanupActions`	`?array`	已執行的清理資訊
`sessionSummary`	`?string`	Session 摘要

`ErrorOccurredHookInput`

屬性	型別	說明
`error`	`string`	錯誤訊息。若執行期傳入錯誤物件，當 `message` 為字串時使用該值，否則為物件的 JSON 字串
`errorContext`	`string`	`model_call` / `tool_execution` / `system` / `user_input` 其中之一
`recoverable`	`bool`	是否可回復

`ErrorOccurredHookOutput`

屬性	型別	說明
`suppressOutput`	`?bool`	抑制錯誤顯示
`errorHandling`	`?string`	`retry` / `skip` / `abort`
`retryCount`	`?int`	重試次數
`userNotification`	`?string`	對使用者的通知文字

ToolResultObject

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

屬性	型別	說明
`textResultForLlm`	`?string`	交給 LLM 的文字結果
`resultType`	`?string`	`success` / `failure` / `rejected` / `denied`
`resultForAssistant`	`?array`	給助理的結果資料

最佳實踐

不要在 hook 內直接執行過重的同步處理，如有必要請改為非同步。
不需變更時回傳 null，交由預設行為。
盡可能明確指定 permissionDecision。
對關鍵錯誤不要過度抑制，保有日誌 / 通知的路徑。
Session 層級狀態以 session id 為基準管理，並於 onSessionEnd 清理。

最新資訊請參考 GitHub 儲存庫。

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

Session Hook

Session Hook

檔案型 hook 的探索

Hook 流程

基本用法

可用 hook

封鎖 prompt

常見的使用情境

1) Permission control（執行控制）

2) Auditing / compliance（稽核）

3) Prompt enrichment（輸入補強）

4) Result filtering（結果整理）

5) Error recovery（故障復原）

6) Session metrics（度量）

Hook input / output 型別

共用輸入（`BaseHookInput`）

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

最佳實踐

​Session Hook

​檔案型 hook 的探索

​Hook 流程

​基本用法

​可用 hook

​封鎖 prompt

​常見的使用情境

​1) Permission control（執行控制）

​2) Auditing / compliance（稽核）

​3) Prompt enrichment（輸入補強）

​4) Result filtering（結果整理）

​5) Error recovery（故障復原）

​6) Session metrics（度量）

​Hook input / output 型別

​共用輸入（BaseHookInput）

​PreToolUseHookInput

​PreToolUseHookOutput

​PostToolUseHookInput

​PostToolUseHookOutput

​UserPromptSubmittedHookInput

​UserPromptSubmittedHookOutput

​SessionStartHookInput

​SessionStartHookOutput

​SessionEndHookInput

​SessionEndHookOutput

​ErrorOccurredHookInput

​ErrorOccurredHookOutput

​ToolResultObject

​最佳實踐

Session Hook

檔案型 hook 的探索

Hook 流程

基本用法

可用 hook

封鎖 prompt

常見的使用情境

1) Permission control（執行控制）

2) Auditing / compliance（稽核）

3) Prompt enrichment（輸入補強）

4) Result filtering（結果整理）

5) Error recovery（故障復原）

6) Session metrics（度量）

Hook input / output 型別

共用輸入（`BaseHookInput`）

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

最佳實踐