# GitHub Copilotフックリファレンス Copilot CLI (コパイロット CLI)とCopilot クラウドエージェントのフックのフック イベント、構成形式、入力ペイロードを検索します。 ## Introduction フックは、セッション中に特定のライフサイクル ポイントで実行される外部コマンドであり、カスタム自動化、セキュリティ制御、統合を有効にします。 フックは、CopilotとCopilot CLI (コパイロット CLI)の 2 つのCopilot クラウドエージェントサーフェスでサポートされています。 構成形式とイベント ペイロードのほとんどは同じですが、実行環境と発生する可能性のあるイベントのセットは異なります。 この記事全体を通して、2 つのサーフェス間で異なる動作については、"CLI のみ" と "クラウド エージェントのみ" に関するメモで説明します。 マークされていないものは両方に適用されます。 ## フックの場所 フックが実行される場所と、フック構成ファイルを格納できる場所は、サーフェスによって異なります。 * **Copilot CLI (コパイロット CLI)** — フックは、CLI と同じシェル内の開発者のローカル コンピューターで実行されます。 この記事で説明するすべてのフック イベントは、CLI でサポートされています。 フックは、次のソース (ユーザー、プロジェクト、プラグイン) から順に読み込まれ、結合されます。 同じイベントが複数のソースに出現すると、すべてのソースからのすべてのフック エントリが実行されます。 * **リポジトリ レベルのフック ファイル** — リポジトリ ルートに `.github/hooks/*.json` 。 * **ユーザーレベルのフックファイル** — ユーザーレベルの hooks ディレクトリ内のファイル。 既定では、これは macOS と Linux では `~/.copilot/hooks/`、Windows では `%USERPROFILE%\.copilot\hooks\` です。 `COPILOT_HOME`が設定されている場合は`$COPILOT_HOME/hooks/`。 * **リポジトリ設定のインライン `hooks` ブロック — リポジトリ**の最上位レベルの `hooks` (Git committed) または `.github/copilot/settings.json` (通常は gitignored およびユーザー固有) の`.github/copilot/settings.local.json` フィールド。 リポジトリ内のツール間 `.claude/settings.json` ファイルと `.claude/settings.local.json` ファイルも読み取られます。 * **ユーザー レベルの構成のインライン `hooks` ブロック** — `hooks`の最上位にある`~/.copilot/settings.json` フィールド。 * **インストールされたプラグインによって提供されるフック** - プラグインのインストールディレクトリ内の独自の `hooks.json` (または `hooks/hooks.json`の下)で各プラグインによって宣言されます。 * **Copilot クラウドエージェント** — フックは、クラウド エージェントがジョブごとにプロビジョニングする一時的な Linux サンドボックス内で実行されます。 サンドボックスは非対話型であり、ネットワークが制限されており、ジョブが終了すると破棄されます。 イベントのサブセットが発生し、`bash` (または `command`) エントリのみが受け入れられます。 フック構成は、複製されたリポジトリ `.github/hooks/*.json` ファイルから読み込まれます。 ## クラウド エージェントの実行環境 このセクションは **、Copilot クラウドエージェントにのみ**適用されます。 フック スクリプトの記述方法とクラウド エージェント ジョブのフック エントリの構成方法に影響する制約について説明します。 | 財産 | 値 | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | オペレーティング システム | Linux。 コマンド フックの `bash` フィールドのみが受け入れられます。 `powershell` エントリは無視されます。 クロスプラットフォーム `command` フィールドはフォールバックとして受け入れられます。 | | 作業ディレクトリ | | | `/workspace` リポジトリを複製する場合は 。それ以外の場合は `/root`。 フック エントリに `cwd` を設定する場合、またはスクリプトからファイルを参照する場合は、このパスを使用します。 | | | Filesystem | 儚い。 フックによって書き込まれたファイル (ログ、CSV、トランスクリプト) は、ジョブの終了時に破棄されます。 フック出力を保持するには、 `http` フック エントリを介して送信します。 | | アウトバウンドネットワーク | クラウド エージェント ファイアウォールによって制限されます。 既定では、GitHubと Copilot ホスト名にのみ到達できます。他のホスト (`https://hooks.example.com` など) に到達するには、管理者が構成したファイアウォール許可規則が必要です。 | | 使用可能な環境変数 | | | `GITHUB_COPILOT_API_TOKEN` と `GITHUB_COPILOT_GIT_TOKEN` はサンドボックスで設定されます。 | | | `COPILOT_AGENT_PROMPT` は、ジョブが呼び出されたプロンプトを保持します。 | | | `HOME` は `/root`に設定されているため、 `~/...` パスを解決するすべてのフック スクリプトがエフェメラル サンドボックスに書き込まれます。 | | | `GITHUB_TOKEN` が設定されていません。 | | | 対話機能 | 完全に非対話型。 エージェントは、すべてのツールのアクセス許可が事前に付与された状態で実行されるため、アクセス許可ダイアログは表示されないため、ユーザーに通知は表示されません。 | | 構成の検出 | クラウド エージェント ジョブでは、既定で存在するフック構成は、複製されたリポジトリ内で `.github/hooks/*.json` のみです。 サンドボックスには、ユーザー レベルのフック ファイル、 `settings.json`、 `config.json`、またはインストールされているプラグインは付属していません。 | ## フック構成形式 フック構成ファイルでは、バージョン `1`で JSON 形式が使用されます。 ### コマンド フック コマンド フックはシェル スクリプトを実行し、すべての種類のフックでサポートされています。 > \[!NOTE] > **クラウド エージェントのみ。** クラウド エージェントは、Linux サンドボックスでフックを実行します。 `bash` フィールドのみが有効です。`powershell`エントリは無視されます。 クロスプラットフォーム `command` フィールドはフォールバックとして受け入れられます。 ```json { "version": 1, "hooks": { "preToolUse": [ { "type": "command", "bash": "your-bash-command", "powershell": "your-powershell-command", "cwd": "optional/working/directory", "env": { "VAR": "value" }, "timeoutSec": 30 } ] } } ``` | フィールド | タイプ | 必須 | Description | | --------------------------------------- | ------------------------------------------------------------------------ | --- | ------------------------------------------------ | | `bash` | 文字列 | | | | `bash`、`powershell`、または `command` のいずれか | Unix のシェル コマンド。 | | | | `command` | 文字列 | | | | `bash`、`powershell`、または `command` のいずれか | 現在のプラットフォームに `bash` も `powershell` も設定されていない場合に使用されるクロスプラットフォーム フォールバック。 | | | | `cwd` | 文字列 | いいえ | コマンドの作業ディレクトリ (リポジトリルートまたは絶対ディレクトリに対する相対ディレクトリ)。 | | `env` | オブジェクト | いいえ | 設定する環境変数 (変数拡張をサポート)。 | | `powershell` | 文字列 | | | | `bash`、`powershell`、または `command` のいずれか | Windowsのシェル コマンド。 | | | | `timeoutSec` | 数値 | いいえ | タイムアウト (秒単位)。 既定値: `30`。 | | `type` | `"command"` | イエス | `"command"`である必要があります。 | ### HTTP フック HTTP フックは、入力ペイロードを JSON `POST` として URL に送信します。 > \[!NOTE] > **クラウド エージェントのみ。** サンドボックスからの送信ネットワークはクラウド エージェント ファイアウォールによって制限されるため、 `url` は許可リストのホストをターゲットにする必要があります。 ```json { "version": 1, "hooks": { "postToolUse": [ { "type": "http", "url": "https://hooks.example.com/copilot", "headers": { "X-Source": "copilot-cli" }, "allowedEnvVars": ["GITHUB_TOKEN"], "timeoutSec": 30 } ] } } ``` | フィールド | タイプ | 必須 | Description | | -------------------------------------------------------------------------------- | --------- | --- | ------------------------ | | `allowedEnvVars` | string\[] | いいえ | | | `headers`値内で展開できる環境変数の名前。 設定する場合、 `url` は `https://`を使用する必要があります。 | | | | | `headers` | オブジェクト | いいえ | 要求ヘッダーには次が含まれます。 | | `timeoutSec` | 数値 | いいえ | タイムアウト (秒単位)。 既定値: `30`。 | | `type` | `"http"` | イエス | `"http"`である必要があります。 | | `url` | 文字列 | イエス | ターゲット URL。 | | `http:`または`https:`を使用する必要があります。 | | | | | `preToolUse`と`permissionRequest`では、応答でツールのアクセス許可を付与できるため、`https://`を使用する必要があります。 | | | | ### プロンプト フック プロンプトは、ユーザーが入力したかのように自動送信テキストをフックします。 これらは、 `sessionStart`でのみサポートされます。 テキストには、自然言語プロンプトまたはスラッシュ コマンドを指定できます。 > \[!NOTE] > **Copilot CLI (コパイロット CLI) だけ。** プロンプト フックは、 **新しい対話型セッション**でのみ起動します。 再開時には起動せず、非対話型プロンプト モード (`-p`) では起動しません。 > \[!NOTE] > **クラウド エージェント。** クラウド エージェント ジョブは非対話形式で ( `-p`と同様に) 実行されるため、 `prompt` フック エントリが起動しない可能性があります。 依存する前に、環境内の動作を確認します。 ```json { "version": 1, "hooks": { "sessionStart": [ { "type": "prompt", "prompt": "Your prompt text or /slash-command" } ] } } ``` | フィールド | タイプ | 必須 | Description | | -------- | ---------- | --- | ----------------------------------- | | `type` | `"prompt"` | イエス | `"prompt"`である必要があります。 | | `prompt` | 文字列 | イエス | 送信するテキストは、自然言語メッセージまたはスラッシュ コマンドです。 | ## フック イベント 次の表に、サポートされているすべてのイベントを示します。 **\[クラウド エージェント**] 列には、クラウド エージェントの下でイベントが発生したかどうかを示し、動作の違いをメモします。 | Event | 次の場合に起動します。 | 処理された出力 | クラウド エージェント | | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `agentStop` | メイン エージェントがターンを終了します。 | はい — 継続をブロックして強制できます。 | 火災。 `decision: "block"` により、さらに 1 ターンが消費されますが、このターンはジョブのタイムアウト時間にもカウントされます。 | | `errorOccurred` | 実行中にエラーが発生します。 | いいえ | 火災。 | | `notification` | CLI がシステム通知 (シェルの完了、エージェントの完了またはアイドル状態、アクセス許可プロンプト、引き出しダイアログ) を出力すると非同期的に起動します。 Fire-and-forget: セッションをブロックしません。 | | | | `matcher` | | | | | `notification_type`正規表現をサポートします。 | 省略可能 — セッションに `additionalContext` を挿入できます。 | | | | **起動しません。** クラウド エージェントは、ユーザーに通知を表示しません (上記のクラウド エージェント実行環境の表の **\[対話機能** ] 行を参照してください)。 | | | | | `permissionRequest` | アクセス許可サービスが実行される前に発生します (ルール エンジン、セッション承認、自動許可/自動拒否、ユーザー プロンプト)。 マージされたフック出力が `behavior: "allow"` または `"deny"`を返した場合、その決定は通常のアクセス許可フローを短絡します。 | | | | `matcher` | | | | | `toolName`正規表現をサポートします。 | はい — プログラムで許可または拒否できます。 | ツール呼び出しは事前に承認されているため、このフックは起動しないか、効果がありません。 代わりに、 `preToolUse` を使用してアクセス許可を決定します。 | | | `postToolUse` | 各ツールが正常に完了した後。 | はい - ツールの結果を変更したり、モデルの追加のコンテキストを挿入したりできます。 | 火災。 | | `postToolUseFailure` | ツールがエラーで完了した後。 | はい — `additionalContext` を介して復旧ガイダンスを提供できます (コマンド フックの終了コード `2` )。 | 火災。 | | `preCompact` | コンテキストの圧縮が開始されようとしています (手動または自動)。 トリガー (`matcher`または`"manual"`) によってフィルターをするための`"auto"`をサポートします。 | いいえ - 通知のみ。 | | | `trigger: "auto"`でのみ発生します。 手動圧縮を要求するユーザーはいません。 | | | | | `preToolUse` | 各ツールが実行される前。 | はい — 許可、拒否、または変更できます。 | 火災。 | | `"ask"`の決定は、ユーザーが回答できないため、`"deny"`として扱われます。 | | | | | `sessionEnd` | セッションが終了します。 | いいえ | ジョブごとに 1 回起動します。 | | `reason` は通常、 `"complete"`、 `"error"`、または `"timeout"`です。ユーザーがいないため、 `"abort"` と `"user_exit"` は想定されません。 | | | | | `sessionStart` | 新しいセッションまたは再開されたセッションが開始されます。 | 省略可能 — セッションに `additionalContext` を挿入できます。 | ジョブごとに 1 回、新しいセッションとして実行されます (再開ではありません)。 クラウド エージェントでの `prompt` エントリの動作については、上記のプロンプト フックに関するメモを参照してください。 | | `subagentStart` | サブエージェントが生成されます (実行前)。 エージェント名でフィルター処理する `matcher` をサポートします。 | 省略可能 — 作成をブロックすることはできませんが、 `additionalContext` はサブエージェントのプロンプトの前に付加されます。 | 火災。 | | `subagentStop` | サブエージェントが作業を完了しました。 | はい — 継続をブロックして強制できます。 | 火災。 | | `userPromptSubmitted` | ユーザーがプロンプトを送信します。 | いいえ | ジョブに指定されたプロンプトに対して、最大 1 回だけ実行されます。 フォローアップのユーザー入力はありません。 | ## フック イベント入力ペイロード 各フック イベントは、フック ハンドラーに JSON ペイロードを配信します。 フック構成で使用されるイベント名によって選択される 2 つのペイロード形式がサポートされています。 * **camelCase 形式 — camelCase** でイベント名を構成します (例: `sessionStart`)。 フィールドには camelCase が使用されます。 * **互換性のある形式VS Code** — PascalCase でイベント名を構成します (例: `SessionStart`)。 フィールドはsnake\_caseを使用してVS CodeCopilotの拡張形式と一致させます。 ### `sessionStart` / `SessionStart` **camelCase の入力:** ```typescript { sessionId: string; timestamp: number; // Unix timestamp in milliseconds cwd: string; source: "startup" | "resume" | "new"; initialPrompt?: string; } ``` \*\* VS Code 互換性のある入力:\*\* ```typescript { hook_event_name: "SessionStart"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; source: "startup" | "resume" | "new"; initial_prompt?: string; } ``` ### `sessionEnd` / `SessionEnd` **camelCase の入力:** ```typescript { sessionId: string; timestamp: number; cwd: string; reason: "complete" | "error" | "abort" | "timeout" | "user_exit"; } ``` \*\* VS Code 互換性のある入力:\*\* ```typescript { hook_event_name: "SessionEnd"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; reason: "complete" | "error" | "abort" | "timeout" | "user_exit"; } ``` ### `userPromptSubmitted` / `UserPromptSubmit` **camelCase の入力:** ```typescript { sessionId: string; timestamp: number; cwd: string; prompt: string; } ``` \*\* VS Code 互換性のある入力:\*\* ```typescript { hook_event_name: "UserPromptSubmit"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; prompt: string; } ``` ### `preToolUse` / `PreToolUse` **camelCase の入力:** ```typescript { sessionId: string; timestamp: number; cwd: string; toolName: string; toolArgs: unknown; } ``` \*\* VS Code 互換性のある入力:\*\* PascalCase イベント名 `PreToolUse` で構成されている場合、ペイロードは snake\_case フィールド名を使用して、VS CodeCopilot 拡張形式と一致します。 ```typescript { hook_event_name: "PreToolUse"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; tool_name: string; tool_input: unknown; // Tool arguments (parsed from JSON string when possible) } ``` ### `postToolUse` / `PostToolUse` **camelCase の入力:** ```typescript { sessionId: string; timestamp: number; cwd: string; toolName: string; toolArgs: unknown; toolResult: { resultType: "success"; textResultForLlm: string; } } ``` \*\* VS Code 互換性のある入力:\*\* ```typescript { hook_event_name: "PostToolUse"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; tool_name: string; tool_input: unknown; tool_result: { result_type: "success"; text_result_for_llm: string; } } ``` ### `postToolUseFailure` / `PostToolUseFailure` **camelCase の入力:** ```typescript { sessionId: string; timestamp: number; cwd: string; toolName: string; toolArgs: unknown; error: string; } ``` \*\* VS Code 互換性のある入力:\*\* ```typescript { hook_event_name: "PostToolUseFailure"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; tool_name: string; tool_input: unknown; error: string; } ``` ### `agentStop` / `Stop` **camelCase の入力:** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; stopReason: "end_turn"; } ``` \*\* VS Code 互換性のある入力:\*\* ```typescript { hook_event_name: "Stop"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; transcript_path: string; stop_reason: "end_turn"; } ``` ### `subagentStart` **入力：** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; agentName: string; agentDisplayName?: string; agentDescription?: string; } ``` ### `subagentStop` / `SubagentStop` **camelCase の入力:** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; agentName: string; agentDisplayName?: string; stopReason: "end_turn"; } ``` \*\* VS Code 互換性のある入力:\*\* ```typescript { hook_event_name: "SubagentStop"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; transcript_path: string; agent_name: string; agent_display_name?: string; stop_reason: "end_turn"; } ``` ### `errorOccurred` / `ErrorOccurred` **camelCase の入力:** ```typescript { sessionId: string; timestamp: number; cwd: string; error: { message: string; name: string; stack?: string; }; errorContext: "model_call" | "tool_execution" | "system" | "user_input"; recoverable: boolean; } ``` \*\* VS Code 互換性のある入力:\*\* ```typescript { hook_event_name: "ErrorOccurred"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; error: { message: string; name: string; stack?: string; }; error_context: "model_call" | "tool_execution" | "system" | "user_input"; recoverable: boolean; } ``` ### `preCompact` / `PreCompact` **camelCase の入力:** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; trigger: "manual" | "auto"; customInstructions: string; } ``` \*\* VS Code 互換性のある入力:\*\* ```typescript { hook_event_name: "PreCompact"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; transcript_path: string; trigger: "manual" | "auto"; custom_instructions: string; } ``` ## `preToolUse` デシジョン コントロール `preToolUse` フックは、JSON オブジェクトを stdout に書き込むことでツールの実行を制御できます。 | フィールド | 価値観 | Description | | ---------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------ | | `permissionDecision` | | | | `"allow"`、 `"deny"`、 `"ask"` | ツールが実行されるかどうか。 空の出力では、既定の動作が使用されます。 クラウド エージェントでは、ユーザーが応答できないため、 `"ask"` は `"deny"` として扱われます。 | | | `permissionDecisionReason` | 文字列 | エージェントに表示される理由。 決定が `"deny"`場合に必要です。 | | `modifiedArgs` | オブジェクト | 元のツールの代わりに使用するツール引数を置き換えます。 | ## `agentStop`/ `subagentStop` デシジョン コントロール | フィールド | 価値観 | Description | | ----------------------------------------------------- | --- | ----------- | | `decision` | | | | `"block"`、`"allow"` | | | | `"block"` は、別のエージェントがプロンプトとして `reason` を使用するように強制します。 | | | | `reason` | 文字列 | | | `decision`が`"block"`されたら、次のターンを求めるメッセージを表示します。 | | | ## `postToolUse`出力 `postToolUse`フックは、JSON オブジェクトを stdout に書き込むことで、ツールの結果を変更したり、モデルの追加のコンテキストを挿入したりできます。 ```typescript { modifiedResult?: { resultType: "success"; textResultForLlm: string; }; additionalContext?: string; } ``` | フィールド | タイプ | Description | | ----------------------------------------------------------------------------------------------------------------------- | ------ | ----------- | | `modifiedResult` | オブジェクト | 置換ツールの結果。 | | `resultType: "success"`が必要です。 | | | | `resultType: "failure"`とともに返されると、障害は下流へルーティングされ、その後に`postToolUseFailure`が実行されます。 | | | | `additionalContext` | 文字列 | | | `textResultForLlm`に追加のガイダンスが追加され、同じターンのツール出力後にモデルに表示されます。 複数のフックが `additionalContext`を返すと、結果は二重改行で結合され、上限は 10 KB になります。 | | | 元の正常な結果を維持するために、 `{}` または空の出力を返します。 > \[!NOTE] > `modifiedResult` は、SDK プログラム フックと command/HTTP config-file `postToolUse` フックの両方によって受け入れられます。 ## `permissionRequest` デシジョン コントロール > \[!NOTE] > **Copilot CLI (コパイロット CLI) だけ。** `permissionRequest` フックは、Copilot クラウドエージェントの下には適用されません。ツール呼び出しには、事前に承認されています (クラウド エージェント実行環境テーブルの **\[対話]** 行を参照)。 `preToolUse`を使用して、クラウド エージェントでアクセス許可を決定します。 `permissionRequest`フックは、アクセス許可サービスが実行される前 (ルール チェック、セッション承認、自動許可/自動拒否、ユーザー プロンプトの前) に起動します。 フックが `behavior: "allow"` または `"deny"`を返した場合、その決定は通常のアクセス許可フローをショートします。 何も返されない場合は、通常のアクセス許可処理に移行します。 これを使用して、ツール呼び出しをプログラムで承認または拒否します。特に、対話型プロンプトが使用できない CLI パイプ モード (`-p`) やその他の CLI CI の使用に便利です。 クラウド エージェントには適用されません。 構成されているすべての `permissionRequest` フックは、要求ごとに実行されます (`read` と `hook` アクセス許可の種類を除き、フックの前にショートサーキットします)。 フック出力は、後のフック出力が以前の出力を上書きする形でマージされます。 **Matcher：**`toolName`に対してテストされた省略可能な正規表現。 `^(?:pattern)$`として固定されます。完全なツール名と一致する必要があります。 設定すると、フックは一致するツール名に対してのみ起動します。 アクセス許可の決定を制御するために、JSON を stdout に出力します。 | フィールド | 価値観 | Description | | --------------------------------- | ---------------------- | ----------------------- | | `behavior` | | | | `"allow"`、`"deny"` | ツール呼び出しを承認または拒否するかどうか。 | | | `message` | 文字列 | 拒否時に LLM にフェールバックされる理由。 | | `interrupt` | boolean | | | `true` | | | | `"deny"`と組み合わせると、エージェントが完全に停止します。 | | | 空の出力または`{}`を返して通常のアクセス許可フローに移行します。 コマンド フックの場合、終了コード `2` は拒否として扱われ、stdout JSON (ある場合) は `{"behavior":"deny"}`とマージされ、stderr は無視されます。 ## `notification` フック > \[!NOTE] > **Copilot CLI (コパイロット CLI) だけ。** `notification`フックはCopilot クラウドエージェントの下では起動しません。 `notification` フックは、CLI がシステム通知を出力するときに非同期的に起動します。 これらのフックは「ファイア・アンド・フォーゲット」で、セッションをブロックすることは決してなく、エラーはログに記録され、スキップされます。 **入力：** ```typescript { sessionId: string; timestamp: number; cwd: string; hook_event_name: "Notification"; message: string; // Human-readable notification text title?: string; // Short title (e.g., "Permission needed", "Shell completed") notification_type: string; // One of the types listed below } ``` **通知の種類:** | タイプ | 起動時 | | -------------------------- | ------------------------------------------------------ | | `shell_completed` | バックグラウンド (非同期) シェル コマンドが終了する | | `shell_detached_completed` | デタッチされたシェル セッションが完了する | | `agent_completed` | バックグラウンド サブエージェントの終了 (完了または失敗) | | `agent_idle` | バックグラウンド エージェントがターンを完了し、アイドル状態になり、`write_agent` を待機します | | `permission_prompt` | エージェントがツールを実行するためのアクセス許可を要求する | | `elicitation_dialog` | エージェントがユーザーに追加情報を要求する | **Output:** ```typescript { additionalContext?: string; // Injected into the session as a user message } ``` `additionalContext`が返された場合、テキストは、そのセッションに先頭に追加されたユーザーメッセージとして挿入されます。 これにより、セッションがアイドル状態の場合に、さらにエージェントの処理がトリガーされる可能性があります。 アクションを実行しない場合は、 `{}` または空の出力を返します。 **Matcher：**`notification_type`の省略可能な正規表現。 パターンは `^(?:pattern)$`として固定されます。 すべての通知の種類を受信するには、 `matcher` を省略します。 ## マッチャーのフィルタリング いくつかのイベントでは、各フック エントリに対してオプションの `matcher` 正規表現を受け付け、フックがどの呼び出しに対して起動するかをフィルターします。 パターンは `^(?:matcher)$` として固定され、完全な値と一致する必要があります。 無効な正規表現を指定すると、フック エントリがスキップされます。 | Event | `matcher` が照合される | | ----------------------------------- | ------------------- | | `notification` | `notification_type` | | `permissionRequest` | `toolName` | | `preCompact` | | | `trigger` (`"manual"` または `"auto"`) | | | `preToolUse` | `toolName` | | `subagentStart` | `agentName` | ## フックマッチング用のツール名 | ツール名 | Description | | ------------ | ------------------------------------------------------------------- | | `ask_user` | ユーザーに明確な質問をします。 クラウド エージェントの下にはユーザーがないため、 `ask_user` は有用な結果を生成しません。 | | `bash` | シェル コマンド (Unix) を実行します。 | | `create` | 新しいファイルを作成します。 | | `edit` | ファイルの内容を変更します。 | | `glob` | パターンでファイルを検索します。 | | `grep` | ファイルの内容を検索します。 | | `powershell` | シェル コマンドを実行する (Windows)。 クラウド エージェント (Linux サンドボックス) の下には表示されません。 | | `task` | サブエージェント タスクを実行します。 | | `view` | ファイルの内容を読み取ります。 | | `web_fetch` | Web ページを取得します。 | 同じ種類の複数のフックが構成されている場合は、順番に実行されます。 `preToolUse`の場合、フックが`"deny"`を返した場合、ツールはブロックされます。 フックエラー ( `2`以外の 0 以外の終了コード、またはタイムアウト) はログに記録され、スキップされます。エージェントの実行はブロックされません。 ## コマンド フックの終了コード | 終了コード | Meaning | | ---------------------------------------------------------------------------------------- | ---------------------------------------- | | `0` | 成功しました。 | | `stdout` は、フック出力 JSON (存在する場合) として解析されます。 | | | `2` | 既定では警告として扱われます。 | | `stderr` はユーザーに表示されますが、実行は続行されます。 | | | `permissionRequest`の場合、終了`2`は`{"behavior":"deny"}`として扱われ、`stdout` JSON がマージされます。 | | | `postToolUseFailure`の場合、終了`2`は`additionalContext`として扱われ、エージェントに表示されるエラーに`stdout`が追加されます。 | | | その他の 0 以外 | フックエラーとしてログに記録されます。 実行は継続されます（フェイルオープン）。 | ## すべてのフックを無効にする `disableAllHooks`は、フック構成をディスク上に保持し、実行を停止する場合に使用します。次に例を示します。 * 問題をデバッグし、構成を削除せずにフックが原因であることを確認する必要があります。 * セットアップを失うことなく、機密性の高いタスク (コード レビュー、リリース ブランチ、シークレットの操作) 中に自動化を一時停止します。 (**Copilot CLI (コパイロット CLI) のみ**)。 * ソース管理にフックファイルを配置し、共同作成者が自身のリポジトリ `settings.json` でオプションを設定することで、ローカルでその適用を無効にできるようにします。 (**Copilot CLI (コパイロット CLI) のみ**)。 * 対話型セッション中に低速またはノイズの多いフックを一時的に消音する。 (**Copilot CLI (コパイロット CLI) のみ**)。 ファイル内のすべてのフックを削除せずにスキップするには、 `disableAllHooks` を最上位レベルで `true` に設定します。 ```json { "version": 1, "disableAllHooks": false, "hooks": { "preToolUse": [ /* hook entries */ ] } } ``` 動作は、フラグを設定する場所によって異なります。 * **1 つの `.github/hooks/*.json` ファイル内** では、そのファイルで宣言されているフックのみがスキップされます。 Copilot CLI (コパイロット CLI)とCopilot クラウドエージェントの両方によって称賛されます。 * **リポジトリの最上位レベルの `settings.json`** — **Copilot CLI (コパイロット CLI) のみ。** すべてのソース (リポジトリ ファイル、ユーザー ファイル、プラグイン、インライン フック ブロック) のすべてのフックは、そのリポジトリ内のセッションではスキップされます。 クラウド エージェントは `settings.json`を読み込まない。 ## 詳細については、次を参照してください。 * [GitHub Copilot CLI（コマンドラインインターフェース） でフックを使用する](/ja/copilot/how-tos/copilot-cli/use-hooks) * [GitHub Copilotフックリファレンス](/ja/copilot/reference/hooks-configuration) * [GITHUB COPILOT CLI コマンド リファレンス](/ja/copilot/reference/copilot-cli-reference/cli-command-reference) * [GitHub Copilot クラウド エージェントの概念](/ja/copilot/concepts/agents/cloud-agent)