GitHub Copilot CLI フック リファレンス

          Copilot CLI (コパイロット CLI)のフック イベント、構成形式、および入力ペイロードを検索します。

この記事で

フックは、セッション中に特定のライフサイクル ポイントで実行される外部コマンドであり、カスタム自動化、セキュリティ制御、統合を有効にします。 フック構成ファイルは、リポジトリ内の .github/hooks/*.json から自動的に読み込まれます。

フック構成形式

フック構成ファイルでは、バージョン 1で 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文字列の 1 つ bash/powershellUnix のシェル コマンド。
cwd文字列いいえコマンドの作業ディレクトリ (リポジトリルートまたは絶対ディレクトリに対する相対ディレクトリ)。
envオブジェクトいいえ設定する環境変数 (変数拡張をサポート)。
powershell文字列の 1 つ bash/powershellWindowsのシェル コマンド。
timeoutSec数値いいえタイムアウト (秒単位)。 既定値: 30。
type"command"はい
          `"command"`である必要があります。 |

プロンプトフック

プロンプトは、ユーザーが入力したかのように自動送信テキストをフックします。 これらは sessionStart でのみサポートされ、 新しい対話型セッションでのみ起動されます。 再開時には起動せず、非対話型プロンプト モード (-p) では起動しません。 テキストには、自然言語プロンプトまたはスラッシュ コマンドを指定できます。

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "prompt",
        "prompt": "Your prompt text or /slash-command"
      }
    ]
  }
}
フィールドタイプ必須Description
type"prompt"はい
          `"prompt"`である必要があります。 |

| prompt | 文字列 | はい | 送信するテキストは、自然言語メッセージまたはスラッシュ コマンドです。 |

フック イベント

イベント次の場合に起動します。処理された出力
agentStopメイン エージェントがターンを終了します。はい — 継続をブロックして強制できます。
errorOccurred実行中にエラーが発生します。いいえ
notificationCLI がシステム通知 (シェルの完了、エージェントの完了またはアイドル状態、アクセス許可プロンプト、引き出しダイアログ) を出力すると非同期的に起動します。 Fire-and-forget: セッションをブロックしません。
          `matcher`
          `notification_type`正規表現をサポートします。 | 省略可能 — セッションに `additionalContext` を挿入できます。 |

| permissionRequest | アクセス許可サービスが実行される前に発生します (ルール エンジン、セッション承認、自動許可/自動拒否、ユーザー プロンプト)。 マージされたフック出力が behavior: "allow" または "deny"を返した場合、その決定は通常のアクセス許可フローを短絡します。 matcher toolName正規表現をサポートします。 | はい — プログラムで許可または拒否できます。 | | postToolUse | 各ツールが正常に完了した後。 | はい — 成功した結果を置き換えることができます (SDK プログラムフックのみ)。 | | postToolUseFailure | ツールがエラーで完了した後。 | はい — additionalContext を介して復旧ガイダンスを提供できます (コマンド フックの終了コード 2 )。 | | preCompact | コンテキストの圧縮が開始されようとしています (手動または自動)。 トリガー (matcherまたは"manual") によってフィルターをするための"auto"をサポートします。 | いいえ - 通知のみ。 | | preToolUse | 各ツールが実行される前。 | はい — 許可、拒否、または変更できます。 | | sessionEnd | セッションが終了します。 | いいえ | | sessionStart | 新しいセッションまたは再開されたセッションが開始されます。 | いいえ | | subagentStart | サブエージェントが生成されます (実行前)。 サブエージェントのプロンプトの前に付加された additionalContext を返します。 エージェント名でフィルター処理する matcher をサポートします。 | いいえ — 作成をブロックできません。 | | subagentStop | サブエージェントが作業を完了しました。 | はい — 継続をブロックして強制できます。 | | userPromptSubmitted | ユーザーがプロンプトを送信します。 | いいえ |

フック イベント入力ペイロード

各フック イベントは、フック ハンドラーに JSON ペイロードを配信します。 フック構成で使用されるイベント名によって選択される 2 つのペイロード形式がサポートされています。

  • camelCase 形式 — camelCase でイベント名を構成します (例: sessionStart)。 フィールドには camelCase が使用されます。
  • 互換性のある形式VS Code — PascalCase でイベント名を構成します (例: SessionStart)。 フィールドはsnake_caseを使用してVS CodeCopilotの拡張形式と一致させます。

sessionStart / SessionStart

          **camelCase の入力:**

{
    sessionId: string;
    timestamp: number;      // Unix timestamp in milliseconds
    cwd: string;
    source: "startup" | "resume" | "new";
    initialPrompt?: string;
}

          **
          VS Code 互換性のある入力:**

{
    hook_event_name: "SessionStart";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    source: "startup" | "resume" | "new";
    initial_prompt?: string;
}

sessionEnd / SessionEnd

          **camelCase の入力:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

          **
          VS Code 互換性のある入力:**

{
    hook_event_name: "SessionEnd";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

userPromptSubmitted / UserPromptSubmit

          **camelCase の入力:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    prompt: string;
}

          **
          VS Code 互換性のある入力:**

{
    hook_event_name: "UserPromptSubmit";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    prompt: string;
}

preToolUse / PreToolUse

          **camelCase の入力:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
}

          **
          VS Code 互換性のある入力:**

PascalCase イベント名 PreToolUseで構成されている場合、ペイロードはsnake_caseフィールド名を使用して、 VS CodeCopilot 拡張形式と一致します。

{
    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 の入力:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    toolResult: {
        resultType: "success";
        textResultForLlm: string;
    }
}

          **
          VS Code 互換性のある入力:**

{
    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" | "failure" | "denied" | "error";
        text_result_for_llm: string;
    }
}

postToolUseFailure / PostToolUseFailure

          **camelCase の入力:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    error: string;
}

          **
          VS Code 互換性のある入力:**

{
    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 の入力:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    stopReason: "end_turn";
}

          **
          VS Code 互換性のある入力:**

{
    hook_event_name: "Stop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    stop_reason: "end_turn";
}

subagentStart

          **入力：**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    agentDescription?: string;
}

subagentStop / SubagentStop

          **camelCase の入力:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    stopReason: "end_turn";
}

          **
          VS Code 互換性のある入力:**

{
    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 の入力:**

{
    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 互換性のある入力:**

{
    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 の入力:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    trigger: "manual" | "auto";
    customInstructions: string;
}

          **
          VS Code 互換性のある入力:**

{
    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"` | ツールが実行されるかどうか。 空の出力では、既定の動作が使用されます。 |

| permissionDecisionReason | 文字列 | エージェントに表示される理由。 決定が "deny"場合に必要です。 | | modifiedArgs | オブジェクト | 元のツールの代わりに使用するツール引数を置き換えます。 |

          `agentStop`
           / 
          `subagentStop` デシジョン コントロール
フィールド価値観Description
decision
          `"block"`、`"allow"` | 
          `"block"` は、別のエージェントがプロンプトとして `reason` を使用するように強制します。 |

| reason | 文字列 | decisionが"block"されたら、次のターンを求めるメッセージを表示します。 |

          `permissionRequest` デシジョン コントロール

          `permissionRequest`フックは、アクセス許可サービスが実行される前 (ルール チェック、セッション承認、自動許可/自動拒否、ユーザー プロンプトの前) に起動します。 フックが `behavior: "allow"` または `"deny"`を返した場合、その決定は通常のアクセス許可フローをショートします。 何も返されない場合は、通常のアクセス許可処理に移行します。 これを使用して、ツール呼び出しをプログラムで承認または拒否します。特に、対話型プロンプトが使用できないパイプ モード (`-p`) および 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` フック

          `notification` フックは、CLI がシステム通知を出力するときに非同期的に起動します。 これらのフックは「ファイア・アンド・フォーゲット」で、セッションをブロックすることは決してなく、エラーはログに記録され、スキップされます。

          **入力：**

{
    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エージェントがユーザーに追加情報を要求する
          **アウトプット：**

{
    additionalContext?: string; // Injected into the session as a user message
}

          `additionalContext`が返された場合、テキストは、そのセッションに先頭に追加されたユーザーメッセージとして挿入されます。 これにより、セッションがアイドル状態の場合に、さらにエージェントの処理がトリガーされる可能性があります。 アクションを実行しない場合は、 `{}` または空の出力を返します。

          **Matcher：**`notification_type`の省略可能な正規表現。 パターンは `^(?:pattern)$`として固定されます。 すべての通知の種類を受信するには、 `matcher` を省略します。

フックマッチング用のツール名

ツール名Description
ask_userユーザーに明確な質問をします。
bashシェル コマンド (Unix) を実行します。
create新しいファイルを作成します。
editファイルの内容を変更します。
globパターンでファイルを検索します。
grepファイルの内容を検索します。
powershellシェル コマンドを実行する (Windows)。
taskサブエージェント タスクを実行します。
viewファイルの内容を読み取ります。
web_fetchWeb ページを取得します。

同じ種類の複数のフックが構成されている場合は、順番に実行されます。 preToolUseの場合、フックが"deny"を返した場合、ツールはブロックされます。 postToolUseFailureコマンド フックの場合、コード 2で終了すると、アシスタントの回復ガイダンスとして stderr が返されます。 フックエラー (0 以外の終了コードまたはタイムアウト) はログに記録され、スキップされます。エージェントの実行はブロックされません。

詳細については、次を参照してください。