メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://kawax.biz/llms.txt

Use this file to discover all available pages before exploring further.

セッションフック

hooks を使うと、Copilot セッションの各ライフサイクルで処理を差し込めます。
ツール実行制御、監査ログ、プロンプト補強、エラーハンドリングなどを、コア実装を変更せずに追加できます。

フックの流れ

基本的な使い方

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 を返すとデフォルト動作が継続されます。

代表的なユースケース

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(障害復旧)

  • onErrorOccurredmodel_call かつ recoverable=true のときだけ retry
  • 非回復系は userNotification で利用者向けに簡潔に通知

6) Session metrics(計測)

  • onSessionStart で開始時刻を記録
  • onPreToolUse / onUserPromptSubmitted でカウンタ更新
  • onSessionEnd で所要時間・ツール回数・終了理由を出力

Hook input / output 型

共通入力(BaseHookInput

プロパティ説明
timestampintフック発火時刻(Unix ms)
cwdstring現在の作業ディレクトリ

PreToolUseHookInput

プロパティ説明
toolNamestring実行予定ツール名
toolArgsmixed実行予定引数

PreToolUseHookOutput

プロパティ説明
permissionDecision?stringallow / deny / ask
permissionDecisionReason?string拒否/確認時の理由
modifiedArgsmixed上書き後の引数
additionalContext?string追加コンテキスト
suppressOutput?boolツール出力を抑制

PostToolUseHookInput

プロパティ説明
toolNamestring実行済みツール名
toolArgsmixed実行時引数
toolResultToolResultObject|arrayツール結果

PostToolUseHookOutput

プロパティ説明
modifiedResultToolResultObject|array|null改変後の結果
additionalContext?string追加コンテキスト
suppressOutput?boolツール結果表示を抑制

UserPromptSubmittedHookInput

プロパティ説明
promptstringユーザー入力プロンプト

UserPromptSubmittedHookOutput

プロパティ説明
modifiedPrompt?string改変後プロンプト
additionalContext?string補足コンテキスト
suppressOutput?bool応答表示の抑制

SessionStartHookInput

プロパティ説明
sourcestringstartup / resume / new
initialPrompt?string初期プロンプト

SessionStartHookOutput

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

SessionEndHookInput

プロパティ説明
reasonstringcomplete / error / abort / timeout / user_exit
finalMessage?string最終メッセージ
error?string終了時エラー

SessionEndHookOutput

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

ErrorOccurredHookInput

プロパティ説明
errorstringエラーメッセージ
errorContext?stringmodel_call / tool_execution / system / user_input のいずれか
recoverablebool回復可能か

ErrorOccurredHookOutput

プロパティ説明
suppressOutput?boolエラー表示の抑制
errorHandling?stringretry / skip / abort
retryCount?intリトライ回数
userNotification?string利用者への通知文

ToolResultObject

ツール実行結果の標準オブジェクトです。
プロパティ説明
textResultForLlm?stringLLM に渡すテキスト結果
resultType?stringsuccess / failure / rejected / denied
resultForAssistant?arrayアシスタント向け結果データ

ベストプラクティス

  1. 重い同期処理はフック内で直接実行しすぎない。必要なら非同期化する。
  2. 変更不要なときは null を返してデフォルト動作に任せる。
  3. permissionDecision は可能な限り明示する。
  4. クリティカルエラーは抑制しすぎず、ログ/通知経路を持つ。
  5. セッション単位の状態は session id ベースで管理し、onSessionEnd で掃除する。
最新情報は GitHub リポジトリ を参照してください。
Last modified on April 22, 2026