セッションフック

hooks を使うと、Copilot セッションの各ライフサイクルで処理を差し込めます。
ツール実行制御、監査ログ、プロンプト補強、エラーハンドリングなどを、コア実装を変更せずに追加できます。これはカスタムエージェント定義内の宣言型 hooks や、ファイルベースフック読み込みとは別の機能です。エージェント単位の設定はカスタムエージェントを参照してください。

ファイルベースフックの検出

hookDirectories には、ファイルベースフックを検出する明示的なルートを指定できます。これは検出専用で、エージェントに一般的なファイルアクセス権限を付与しません。 enableConfigDiscovery や enableFileHooks が無効でも明示ルートは利用できます。相対パスは、指定時の有効な workingDirectory を基準に一度だけ解決されます。

省略または null：他の検出元を変更しません
[]：明示したSDKルートだけをクリアします

フックのソース無効化設定や Managed Settings は引き続き適用されます。 enableFileHooks はリポジトリ由来のファイルフック（.github/hooks/ や信頼されたリポジトリ設定のルート）を制御します。明示的な hookDirectories やPHPコールバックの hooks は無効化しません。

use Revolution\Copilot\Types\SessionConfig;

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

フックの流れ

基本的な使い方

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	発火タイミング	主な用途
`onSessionStart`	セッション開始（`new` / `resume` / `startup`）	初期コンテキスト注入、設定上書き
`onUserPromptSubmitted`	ユーザープロンプト送信時	プロンプト補強、テンプレート展開、入力フィルタ
`onPreToolUse`	ツール実行前	許可/拒否/要確認、引数改変、出力抑制
`onPostToolUse`	ツール実行後	結果改変、機密情報マスク、監査ログ
`onErrorOccurred`	セッション内エラー発生時	リトライ、通知、エラー分類
`onSessionEnd`	セッション終了時	クリーンアップ、メトリクス、終了サマリ

null を返すとデフォルト動作が継続されます。

プロンプトのブロック

onUserPromptSubmitted は decision: 'block' を返してプロンプトを拒否できます。拒否された場合、モデルターンは開始されず、ユーザーメッセージも記録されません。 reason を指定すると、その内容が warningType: "policy_blocked" の一時的な session.warning イベントに含まれます。

onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
    if (str_contains($input->prompt, 'restricted')) {
        return new UserPromptSubmittedHookOutput(
            decision: 'block',
            reason: 'このプロンプトは許可されていません。',
        );
    }

    return null;
},

代表的なユースケース

1) Permission control（実行制御）

onPreToolUse で許可ツールを allow-list 方式にする
破壊的操作は permissionDecision: 'ask' で人間承認
permissionDecisionReason で拒否理由を明示
toolName の候補は Tools の一覧で確認する（例: view, glob, bash）

2) Auditing / compliance（監査）

ライフサイクルフックを組み合わせて監査イベントを収集
収集データはセッションID単位で永続化

3) Prompt enrichment（入力補強）

onSessionStart でプロジェクト情報（言語、FW、規約）を 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`	関連するランタイムセッションID。子ツールのフックでは子セッション、サブエージェントの開始/停止フックでは親セッションID
`timestamp`	`int`	フック発火時刻（Unix ms）
`cwd`	`string`	現在の作業ディレクトリ
`agentId`	`?string`	フックを実行するサブエージェントのアクターID
`agentType`	`?string`	サブエージェントの種類
`parentAgentId`	`?string`	直近の親アクターID

agentId / agentType / parentAgentId は、サブエージェントがアクターとなるフックで利用できます。ルートエージェントのフックには含まれません。古いランタイムでは情報がない場合にフィールド自体が省略されます。そのため、いずれも 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`	ユーザー入力プロンプト

`UserPromptSubmittedHookOutput`

プロパティ	型	説明
`modifiedPrompt`	`?string`	改変後プロンプト
`additionalContext`	`?string`	補足コンテキスト
`suppressOutput`	`?bool`	応答表示の抑制
`decision`	`?string`	`block` でプロンプトを拒否し、モデルターンとユーザーメッセージの記録を抑止
`reason`	`?string`	拒否理由。`session.warning` イベントに含まれる

`SessionStartHookInput`

プロパティ	型	説明
`source`	`string`	`startup` / `resume` / `new`
`initialPrompt`	`?string`	初期プロンプト

`SessionStartHookOutput`

プロパティ	型	説明
`additionalContext`	`?string`	セッション初期コンテキスト
`modifiedConfig`	`?array`	セッション設定の部分上書き

`SessionEndHookInput`

プロパティ	型	説明
`reason`	`string`	`complete` / `error` / `abort` / `timeout` / `user_exit`
`finalMessage`	`?string`	最終メッセージ
`error`	`?string`	終了時エラー。ランタイムがエラーオブジェクトを渡す場合、`message` が文字列ならその値、そうでなければオブジェクトのJSON文字列

`SessionEndHookOutput`

プロパティ	型	説明
`suppressOutput`	`?bool`	最終出力の抑制
`cleanupActions`	`?array`	実行したクリーンアップ情報
`sessionSummary`	`?string`	セッション要約

`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`	アシスタント向け結果データ

ベストプラクティス

重い同期処理はフック内で直接実行しすぎない。必要なら非同期化する。
変更不要なときは null を返してデフォルト動作に任せる。
permissionDecision は可能な限り明示する。
クリティカルエラーは抑制しすぎず、ログ/通知経路を持つ。
セッション単位の状態は session id ベースで管理し、onSessionEnd で掃除する。

最新情報は GitHub リポジトリを参照してください。

GitHub Copilot

SDK

AI SDK

VOICEVOX

スターターキット

フィード・RSS

ミドルウェア

セッションフック