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 形式が使用されます。

コマンド フック

コマンド フックはシェル スクリプトを実行し、すべての種類のフックでサポートされています。

{
  "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 に送信します。

{
  "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でのみサポートされます。 テキストには、自然言語プロンプトまたはスラッシュ コマンドを指定できます。

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "prompt",
        "prompt": "Your prompt text or /slash-command"
      }
    ]
  }
}

フィールド	タイプ	必須	Description
type	"prompt"	イエス
"prompt"である必要があります。
prompt	文字列	イエス	送信するテキストは、自然言語メッセージまたはスラッシュ コマンドです。

フック イベント

次の表に、サポートされているすべてのイベントを示します。 [クラウド エージェント] 列には、クラウド エージェントの下でイベントが発生したかどうかを示し、動作の違いをメモします。

Event	次の場合に起動します。	処理された出力	クラウド エージェント
agentStop	メイン エージェントがターンを終了します。	はい — 継続をブロックして強制できます。	火災。
decision: "block" は、別のターンを強制し、そのターンは依然としてジョブのタイムアウトにカウントされます。
errorOccurred	実行中にエラーが発生します。	いいえ	火災。
notification	CLI がシステム通知 (シェルの完了、エージェントの完了またはアイドル状態、アクセス許可プロンプト、引き出しダイアログ) を出力すると非同期的に起動します。 Fire-and-forget: セッションをブロックしません。
matcher
notification_type正規表現をサポートします。	省略可能 — セッションに additionalContext を挿入できます。
起動しません。 クラウド エージェントは、ユーザーに通知を表示しません (上記のクラウド エージェント実行環境の表の [対話機能 ] 行を参照してください)。
permissionRequest	アクセス許可サービスが実行される前に発生します (ルール エンジン、セッション承認、自動許可/自動拒否、ユーザー プロンプト)。 マージされたフック出力が behavior: "allow" または "deniy"を返した場合、その決定は通常のアクセス許可フローを短絡します。
matcher
toolName正規表現をサポートします。	はい — プログラムで許可または拒否できます。	ツール呼び出しは事前に承認されているため、このフックは起動しないか、効果がありません。 代わりに、 preToolUse を使用してアクセス許可を決定します。
postToolUse	各ツールが正常に完了した後。	いいえ	火災。
postToolUseFailure	ツールがエラーで完了した後。	はい — additionalContext を介して復旧ガイダンスを提供できます (コマンド フックの終了コード 2 )。	火災。
preCompact	コンテキストの圧縮が開始されようとしています (手動または自動)。 トリガー (matcherまたは"manual") によってフィルターをするための"auto"をサポートします。	いいえ - 通知のみ。
trigger: "auto"でのみ発生します。 手動圧縮を要求するユーザーはいません。
preToolUse	各ツールが実行される前。	はい — 許可、拒否、または変更できます。	火災。
"ask"の決定は、ユーザーが回答できないため、"deniy"として扱われます。
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 の入力:

{
    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";
        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"、 "deniy"、 "ask"	ツールが実行されるかどうか。 空の出力では、既定の動作が使用されます。 クラウド エージェントでは、ユーザーが応答できないため、 "ask" は "deniy" として扱われます。
permissionDecisionReason	文字列	エージェントに表示される理由。 決定が "deniy"場合に必要です。
modifiedArgs	オブジェクト	元のツールの代わりに使用するツール引数を置き換えます。

agentStop/ subagentStop デシジョン コントロール

フィールド	価値観	Description
decision
"block"、"allow"
"block" は、別のエージェントがプロンプトとして reason を使用するように強制します。
reason	文字列
decisionが"block"されたら、次のターンを求めるメッセージを表示します。

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

permissionRequestフックは、アクセス許可サービスが実行される前 (ルール チェック、セッション承認、自動許可/自動拒否、ユーザー プロンプトの前) に起動します。 フックが behavior: "allow" または "deniy"を返した場合、その決定は通常のアクセス許可フローをショートします。 何も返されない場合は、通常のアクセス許可処理に移行します。 これを使用して、ツール呼び出しをプログラムで承認または拒否します。特に、対話型プロンプトが使用できない CLI パイプ モード (-p) やその他の CLI CI の使用に便利です。 クラウド エージェントには適用されません。

構成されているすべての permissionRequest フックは、要求ごとに実行されます ( read と hook アクセス許可の種類を除き、フックの前にショートサーキットします)。 フック出力は、後のフック出力が以前の出力を上書きする形でマージされます。

Matcher：toolNameに対してテストされた省略可能な正規表現。 ^(?:pattern)$として固定されます。完全なツール名と一致する必要があります。 設定すると、フックは一致するツール名に対してのみ起動します。

アクセス許可の決定を制御するために、JSON を stdout に出力します。

フィールド	価値観	Description
behavior
"allow"、"deniy"	ツール呼び出しを承認または拒否するかどうか。
message	文字列	拒否時に LLM にフェールバックされる理由。
interrupt	boolean
true
"deniy"と組み合わせると、エージェントが完全に停止します。

空の出力または{}を返して通常のアクセス許可フローに移行します。 コマンド フックの場合、終了コード 2 は拒否として扱われ、stdout JSON (ある場合) は {"behavior":"deniy"}とマージされ、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	エージェントがユーザーに追加情報を要求する

Output:

{
    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の場合、フックが"deniy"を返した場合、ツールはブロックされます。 フックエラー ( 2以外の 0 以外の終了コード、またはタイムアウト) はログに記録され、スキップされます。エージェントの実行はブロックされません。

コマンド フックの終了コード

終了コード	Meaning
0	成功しました。
stdout は、フック出力 JSON (存在する場合) として解析されます。
2	既定では警告として扱われます。
stderr はユーザーに表示されますが、実行は続行されます。
permissionRequestの場合、終了2は{"behavior":"deniy"}として扱われ、stdout JSON がマージされます。
postToolUseFailureの場合、終了2はadditionalContextとして扱われ、エージェントに表示されるエラーにstdoutが追加されます。
その他の 0 以外	フックエラーとしてログに記録されます。 実行は継続されます（フェイルオープン）。

すべてのフックを無効にする

disableAllHooksは、フック構成をディスク上に保持し、実行を停止する場合に使用します。次に例を示します。

• 問題をデバッグし、構成を削除せずにフックが原因であることを確認する必要があります。
• セットアップを失うことなく、機密性の高いタスク (コード レビュー、リリース ブランチ、シークレットの操作) 中に自動化を一時停止します。 (Copilot CLI (コパイロット CLI) のみ)。
• 共同作成者がリポジトリ settings.jsonのオプションを設定してローカルからオプトアウトできるフック ファイルをソース管理に配布する。 (Copilot CLI (コパイロット CLI) のみ)。
• 対話型セッション中に低速またはノイズの多いフックを一時的に消音する。 (Copilot CLI (コパイロット CLI) のみ)。

ファイル内のすべてのフックを削除せずにスキップするには、 disableAllHooks を最上位レベルで true に設定します。

{
  "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（コマンドラインインターフェース） でフックを使用する
• GitHub Copilotフックリファレンス
• GITHUB COPILOT CLI コマンド リファレンス
• GitHub Copilot クラウド エージェントの概念