{"meta":{"title":"GitHub Copilot CLI フック リファレンス","intro":"Copilot CLI (コパイロット CLI)のフック イベント、構成形式、および入力ペイロードを検索します。","product":"GitHub Copilot","breadcrumbs":[{"href":"/ja/copilot","title":"GitHub Copilot"},{"href":"/ja/copilot/reference","title":"リファレンス"},{"href":"/ja/copilot/reference/copilot-cli-reference","title":"\n              Copilot CLI (コパイロット CLI) リファレンス"},{"href":"/ja/copilot/reference/copilot-cli-reference/cli-hooks-reference","title":"CLI フック リファレンス"}],"documentType":"article"},"body":"# GitHub Copilot CLI フック リファレンス\n\nCopilot CLI (コパイロット CLI)のフック イベント、構成形式、および入力ペイロードを検索します。\n\nフックは、セッション中に特定のライフサイクル ポイントで実行される外部コマンドであり、カスタム自動化、セキュリティ制御、統合を有効にします。 フック構成ファイルは、リポジトリ内の `.github/hooks/*.json` から自動的に読み込まれます。\n\n## フック構成形式\n\nフック構成ファイルでは、バージョン `1`で JSON 形式が使用されます。\n\n### コマンド フック\n\nコマンド フックはシェル スクリプトを実行し、すべての種類のフックでサポートされています。\n\n```json\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"preToolUse\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"your-bash-command\",\n        \"powershell\": \"your-powershell-command\",\n        \"cwd\": \"optional/working/directory\",\n        \"env\": { \"VAR\": \"value\" },\n        \"timeoutSec\": 30\n      }\n    ]\n  }\n}\n```\n\n| フィールド        | タイプ         | 必須                        | Description                                      |\n| ------------ | ----------- | ------------------------- | ------------------------------------------------ |\n| `bash`       | 文字列         | の 1 つ `bash`/`powershell` | Unix のシェル コマンド。                                  |\n| `cwd`        | 文字列         | いいえ                       | コマンドの作業ディレクトリ (リポジトリルートまたは絶対ディレクトリに対する相対ディレクトリ)。 |\n| `env`        | オブジェクト      | いいえ                       | 設定する環境変数 (変数拡張をサポート)。                            |\n| `powershell` | 文字列         | の 1 つ `bash`/`powershell` | Windowsのシェル コマンド。                                |\n| `timeoutSec` | 数値          | いいえ                       | タイムアウト (秒単位)。 既定値: `30`。                         |\n| `type`       | `\"command\"` | はい                        |                                                  |\n\n```\n          `\"command\"`である必要があります。 |\n```\n\n### プロンプトフック\n\nプロンプトは、ユーザーが入力したかのように自動送信テキストをフックします。 これらは `sessionStart` でのみサポートされ、 **新しい対話型セッション**でのみ起動されます。 再開時には起動せず、非対話型プロンプト モード (`-p`) では起動しません。 テキストには、自然言語プロンプトまたはスラッシュ コマンドを指定できます。\n\n```json\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"sessionStart\": [\n      {\n        \"type\": \"prompt\",\n        \"prompt\": \"Your prompt text or /slash-command\"\n      }\n    ]\n  }\n}\n```\n\n| フィールド  | タイプ        | 必須 | Description |\n| ------ | ---------- | -- | ----------- |\n| `type` | `\"prompt\"` | はい |             |\n\n```\n          `\"prompt\"`である必要があります。 |\n```\n\n\\| `prompt` | 文字列 | はい | 送信するテキストは、自然言語メッセージまたはスラッシュ コマンドです。 |\n\n## フック イベント\n\n| イベント            | 次の場合に起動します。                                                                                                      | 処理された出力               |\n| --------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------- |\n| `agentStop`     | メイン エージェントがターンを終了します。                                                                                            | はい — 継続をブロックして強制できます。 |\n| `errorOccurred` | 実行中にエラーが発生します。                                                                                                   | いいえ                   |\n| `notification`  | CLI がシステム通知 (シェルの完了、エージェントの完了またはアイドル状態、アクセス許可プロンプト、引き出しダイアログ) を出力すると非同期的に起動します。 Fire-and-forget: セッションをブロックしません。 |                       |\n\n```\n          `matcher`\n          `notification_type`正規表現をサポートします。 | 省略可能 — セッションに `additionalContext` を挿入できます。 |\n```\n\n\\| `permissionRequest` | アクセス許可サービスが実行される前に発生します (ルール エンジン、セッション承認、自動許可/自動拒否、ユーザー プロンプト)。 マージされたフック出力が `behavior: \"allow\"` または `\"deny\"`を返した場合、その決定は通常のアクセス許可フローを短絡します。\n`matcher`\n`toolName`正規表現をサポートします。 | はい — プログラムで許可または拒否できます。 |\n\\| `postToolUse` | 各ツールが正常に完了した後。 | はい — 成功した結果を置き換えることができます (SDK プログラムフックのみ)。 |\n\\| `postToolUseFailure` | ツールがエラーで完了した後。 | はい — `additionalContext` を介して復旧ガイダンスを提供できます (コマンド フックの終了コード `2` )。 |\n\\| `preCompact` | コンテキストの圧縮が開始されようとしています (手動または自動)。 トリガー (`matcher`または`\"manual\"`) によってフィルターをするための`\"auto\"`をサポートします。 | いいえ - 通知のみ。 |\n\\| `preToolUse` | 各ツールが実行される前。 | はい — 許可、拒否、または変更できます。 |\n\\| `sessionEnd` | セッションが終了します。 | いいえ |\n\\| `sessionStart` | 新しいセッションまたは再開されたセッションが開始されます。 | いいえ |\n\\| `subagentStart` | サブエージェントが生成されます (実行前)。 サブエージェントのプロンプトの前に付加された `additionalContext` を返します。 エージェント名でフィルター処理する `matcher` をサポートします。 | いいえ — 作成をブロックできません。 |\n\\| `subagentStop` | サブエージェントが作業を完了しました。 | はい — 継続をブロックして強制できます。 |\n\\| `userPromptSubmitted` | ユーザーがプロンプトを送信します。 | いいえ |\n\n## フック イベント入力ペイロード\n\n各フック イベントは、フック ハンドラーに JSON ペイロードを配信します。 フック構成で使用されるイベント名によって選択される 2 つのペイロード形式がサポートされています。\n\n* **camelCase 形式 — camelCase** でイベント名を構成します (例: `sessionStart`)。 フィールドには camelCase が使用されます。\n* **互換性のある形式VS Code** — PascalCase でイベント名を構成します (例: `SessionStart`)。 フィールドはsnake\\_caseを使用してVS CodeCopilotの拡張形式と一致させます。\n\n### `sessionStart` / `SessionStart`\n\n```\n          **camelCase の入力:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;      // Unix timestamp in milliseconds\n    cwd: string;\n    source: \"startup\" | \"resume\" | \"new\";\n    initialPrompt?: string;\n}\n```\n\n```\n          **\n          VS Code 互換性のある入力:**\n```\n\n```typescript\n{\n    hook_event_name: \"SessionStart\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    source: \"startup\" | \"resume\" | \"new\";\n    initial_prompt?: string;\n}\n```\n\n### `sessionEnd` / `SessionEnd`\n\n```\n          **camelCase の入力:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    reason: \"complete\" | \"error\" | \"abort\" | \"timeout\" | \"user_exit\";\n}\n```\n\n```\n          **\n          VS Code 互換性のある入力:**\n```\n\n```typescript\n{\n    hook_event_name: \"SessionEnd\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    reason: \"complete\" | \"error\" | \"abort\" | \"timeout\" | \"user_exit\";\n}\n```\n\n### `userPromptSubmitted` / `UserPromptSubmit`\n\n```\n          **camelCase の入力:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    prompt: string;\n}\n```\n\n```\n          **\n          VS Code 互換性のある入力:**\n```\n\n```typescript\n{\n    hook_event_name: \"UserPromptSubmit\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    prompt: string;\n}\n```\n\n### `preToolUse` / `PreToolUse`\n\n```\n          **camelCase の入力:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    toolName: string;\n    toolArgs: unknown;\n}\n```\n\n```\n          **\n          VS Code 互換性のある入力:**\n```\n\nPascalCase イベント名 `PreToolUse`で構成されている場合、ペイロードはsnake\\_caseフィールド名を使用して、 VS CodeCopilot 拡張形式と一致します。\n\n```typescript\n{\n    hook_event_name: \"PreToolUse\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    tool_name: string;\n    tool_input: unknown;    // Tool arguments (parsed from JSON string when possible)\n}\n```\n\n### `postToolUse` / `PostToolUse`\n\n```\n          **camelCase の入力:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    toolName: string;\n    toolArgs: unknown;\n    toolResult: {\n        resultType: \"success\";\n        textResultForLlm: string;\n    }\n}\n```\n\n```\n          **\n          VS Code 互換性のある入力:**\n```\n\n```typescript\n{\n    hook_event_name: \"PostToolUse\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    tool_name: string;\n    tool_input: unknown;\n    tool_result: {\n        result_type: \"success\" | \"failure\" | \"denied\" | \"error\";\n        text_result_for_llm: string;\n    }\n}\n```\n\n### `postToolUseFailure` / `PostToolUseFailure`\n\n```\n          **camelCase の入力:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    toolName: string;\n    toolArgs: unknown;\n    error: string;\n}\n```\n\n```\n          **\n          VS Code 互換性のある入力:**\n```\n\n```typescript\n{\n    hook_event_name: \"PostToolUseFailure\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    tool_name: string;\n    tool_input: unknown;\n    error: string;\n}\n```\n\n### `agentStop` / `Stop`\n\n```\n          **camelCase の入力:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    transcriptPath: string;\n    stopReason: \"end_turn\";\n}\n```\n\n```\n          **\n          VS Code 互換性のある入力:**\n```\n\n```typescript\n{\n    hook_event_name: \"Stop\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    transcript_path: string;\n    stop_reason: \"end_turn\";\n}\n```\n\n### `subagentStart`\n\n```\n          **入力：**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    transcriptPath: string;\n    agentName: string;\n    agentDisplayName?: string;\n    agentDescription?: string;\n}\n```\n\n### `subagentStop` / `SubagentStop`\n\n```\n          **camelCase の入力:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    transcriptPath: string;\n    agentName: string;\n    agentDisplayName?: string;\n    stopReason: \"end_turn\";\n}\n```\n\n```\n          **\n          VS Code 互換性のある入力:**\n```\n\n```typescript\n{\n    hook_event_name: \"SubagentStop\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    transcript_path: string;\n    agent_name: string;\n    agent_display_name?: string;\n    stop_reason: \"end_turn\";\n}\n```\n\n### `errorOccurred` / `ErrorOccurred`\n\n```\n          **camelCase の入力:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    error: {\n        message: string;\n        name: string;\n        stack?: string;\n    };\n    errorContext: \"model_call\" | \"tool_execution\" | \"system\" | \"user_input\";\n    recoverable: boolean;\n}\n```\n\n```\n          **\n          VS Code 互換性のある入力:**\n```\n\n```typescript\n{\n    hook_event_name: \"ErrorOccurred\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    error: {\n        message: string;\n        name: string;\n        stack?: string;\n    };\n    error_context: \"model_call\" | \"tool_execution\" | \"system\" | \"user_input\";\n    recoverable: boolean;\n}\n```\n\n### `preCompact` / `PreCompact`\n\n```\n          **camelCase の入力:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    transcriptPath: string;\n    trigger: \"manual\" | \"auto\";\n    customInstructions: string;\n}\n```\n\n```\n          **\n          VS Code 互換性のある入力:**\n```\n\n```typescript\n{\n    hook_event_name: \"PreCompact\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    transcript_path: string;\n    trigger: \"manual\" | \"auto\";\n    custom_instructions: string;\n}\n```\n\n##\n\n```\n          `preToolUse` デシジョン コントロール\n\n          `preToolUse` フックは、JSON オブジェクトを stdout に書き込むことでツールの実行を制御できます。\n```\n\n| フィールド                | 価値観 | Description |\n| -------------------- | --- | ----------- |\n| `permissionDecision` |     |             |\n\n```\n          `\"allow\"`、`\"deny\"`、`\"ask\"` | ツールが実行されるかどうか。 空の出力では、既定の動作が使用されます。 |\n```\n\n\\| `permissionDecisionReason` | 文字列 | エージェントに表示される理由。 決定が `\"deny\"`場合に必要です。 |\n\\| `modifiedArgs` | オブジェクト | 元のツールの代わりに使用するツール引数を置き換えます。 |\n\n##\n\n```\n          `agentStop`\n           / \n          `subagentStop` デシジョン コントロール\n```\n\n| フィールド      | 価値観 | Description |\n| ---------- | --- | ----------- |\n| `decision` |     |             |\n\n```\n          `\"block\"`、`\"allow\"` | \n          `\"block\"` は、別のエージェントがプロンプトとして `reason` を使用するように強制します。 |\n```\n\n\\| `reason` | 文字列 |\n`decision`が`\"block\"`されたら、次のターンを求めるメッセージを表示します。 |\n\n##\n\n```\n          `permissionRequest` デシジョン コントロール\n\n          `permissionRequest`フックは、アクセス許可サービスが実行される前 (ルール チェック、セッション承認、自動許可/自動拒否、ユーザー プロンプトの前) に起動します。 フックが `behavior: \"allow\"` または `\"deny\"`を返した場合、その決定は通常のアクセス許可フローをショートします。 何も返されない場合は、通常のアクセス許可処理に移行します。 これを使用して、ツール呼び出しをプログラムで承認または拒否します。特に、対話型プロンプトが使用できないパイプ モード (`-p`) および CI 環境で役立ちます。\n```\n\n構成されているすべての `permissionRequest` フックは、要求ごとに実行されます ( `read` と `hook` アクセス許可の種類を除き、フックの前にショートサーキットします)。 フック出力は、後のフック出力が以前の出力を上書きする形でマージされます。\n\n```\n          **Matcher：**`toolName`に対してテストされた省略可能な正規表現。 \n          `^(?:pattern)$`として固定されます。完全なツール名と一致する必要があります。 設定すると、フックは一致するツール名に対してのみ起動します。\n```\n\nアクセス許可の決定を制御するために、JSON を stdout に出力します。\n\n| フィールド      | 価値観 | Description |\n| ---------- | --- | ----------- |\n| `behavior` |     |             |\n\n```\n          `\"allow\"`、`\"deny\"` | ツール呼び出しを承認または拒否するかどうか。 |\n```\n\n\\| `message` | 文字列 | 拒否時に LLM にフェールバックされる理由。 |\n\\| `interrupt` | boolean |\n`true`\n`\"deny\"`と組み合わせると、エージェントが完全に停止します。 |\n\n空の出力または`{}`を返して通常のアクセス許可フローに移行します。 コマンド フックの場合、終了コード `2` は拒否として扱われ、stdout JSON (ある場合) は `{\"behavior\":\"deny\"}`とマージされ、stderr は無視されます。\n\n##\n\n```\n          `notification` フック\n\n          `notification` フックは、CLI がシステム通知を出力するときに非同期的に起動します。 これらのフックは「ファイア・アンド・フォーゲット」で、セッションをブロックすることは決してなく、エラーはログに記録され、スキップされます。\n\n          **入力：**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    hook_event_name: \"Notification\";\n    message: string;           // Human-readable notification text\n    title?: string;            // Short title (e.g., \"Permission needed\", \"Shell completed\")\n    notification_type: string; // One of the types listed below\n}\n```\n\n```\n          **通知の種類:**\n```\n\n| タイプ                        | 起動時                                                    |\n| -------------------------- | ------------------------------------------------------ |\n| `shell_completed`          | バックグラウンド (非同期) シェル コマンドが終了する                           |\n| `shell_detached_completed` | デタッチされたシェル セッションが完了する                                  |\n| `agent_completed`          | バックグラウンド サブエージェントの終了 (完了または失敗)                         |\n| `agent_idle`               | バックグラウンド エージェントがターンを完了し、アイドル状態になり、`write_agent`を待機します。 |\n| `permission_prompt`        | エージェントがツールを実行するためのアクセス許可を要求する                          |\n| `elicitation_dialog`       | エージェントがユーザーに追加情報を要求する                                  |\n\n```\n          **アウトプット：**\n```\n\n```typescript\n{\n    additionalContext?: string; // Injected into the session as a user message\n}\n```\n\n```\n          `additionalContext`が返された場合、テキストは、そのセッションに先頭に追加されたユーザーメッセージとして挿入されます。 これにより、セッションがアイドル状態の場合に、さらにエージェントの処理がトリガーされる可能性があります。 アクションを実行しない場合は、 `{}` または空の出力を返します。\n\n          **Matcher：**`notification_type`の省略可能な正規表現。 パターンは `^(?:pattern)$`として固定されます。 すべての通知の種類を受信するには、 `matcher` を省略します。\n```\n\n## フックマッチング用のツール名\n\n| ツール名         | Description              |\n| ------------ | ------------------------ |\n| `ask_user`   | ユーザーに明確な質問をします。          |\n| `bash`       | シェル コマンド (Unix) を実行します。  |\n| `create`     | 新しいファイルを作成します。           |\n| `edit`       | ファイルの内容を変更します。           |\n| `glob`       | パターンでファイルを検索します。         |\n| `grep`       | ファイルの内容を検索します。           |\n| `powershell` | シェル コマンドを実行する (Windows)。 |\n| `task`       | サブエージェント タスクを実行します。      |\n| `view`       | ファイルの内容を読み取ります。          |\n| `web_fetch`  | Web ページを取得します。           |\n\n同じ種類の複数のフックが構成されている場合は、順番に実行されます。\n`preToolUse`の場合、フックが`\"deny\"`を返した場合、ツールはブロックされます。\n`postToolUseFailure`コマンド フックの場合、コード `2`で終了すると、アシスタントの回復ガイダンスとして stderr が返されます。 フックエラー (0 以外の終了コードまたはタイムアウト) はログに記録され、スキップされます。エージェントの実行はブロックされません。\n\n## 詳細については、次を参照してください。\n\n* [GitHub Copilot CLI（コマンドラインインターフェース） を使用するフック](/ja/copilot/how-tos/copilot-cli/use-hooks)\n* [フックの構成](/ja/copilot/reference/hooks-configuration)\n* [GITHUB COPILOT CLI コマンド リファレンス](/ja/copilot/reference/copilot-cli-reference/cli-command-reference)"}