はじめに
GitHub CopilotのHooks（フック）機能は、Copilotエージェントのセッション中の特定のタイミングで、任意のコマンドを自動実行できる仕組みです。「危険なコマンドを実行前にブロックしたい」「ツール実行後に必ずログを残したい」といった、エージェント任せにできない部分をルールとして固定できます。
Copilot CLIとCopilot cloud agentの両方に対応しており、対応イベントの種類・設定方法を理解しておくと、Copilotをより安全かつ自動化された形で使えるようになります。この記事では、Hooksの仕組みと設定方法を実例つきで解説します。
この記事で分かること
- GitHub Copilot Hooksの仕組みと対応サーフェス
- 主要なフックイベントの種類と使いどころ
- 設定ファイルの書き方（JSON構造・具体例）
GitHub Copilot Hooksとは
Hooksは、Copilotエージェントのセッション中のライフサイクル上の特定ポイントで、外部コマンドを同期的に実行する仕組みです。エージェントの動作を「監視する」だけでなく、「制御する」（実行を許可・拒否する）こともできるのが特徴です。
■ Hooksの位置づけ
└→ Copilot CLI（ターミナル）で利用可能
└→ Copilot cloud agent（GitHub上）で利用可能
└→ セッション開始・ツール実行前後・セッション終了などのタイミングで発火
└→ コマンド実行結果に応じてエージェントの動作を制御可能対応言語は限定的で、Copilot CLIではBash・PowerShellのスクリプトを指定でき、Cloud AgentはLinuxサンドボックス上で動くためBashのみに対応しています（PowerShellの指定は無視されます）。
主要なフックイベント一覧
代表的なフックイベントは以下の通りです。
| フック | 発火タイミング | 主な用途 |
|---|---|---|
sessionStart | セッション開始時 | 環境の初期化、監査ログの記録 |
sessionEnd | セッション終了時 | リソースのクリーンアップ、レポート生成 |
userPromptSubmitted | ユーザーがプロンプトを送信した時 | 利用状況の記録 |
preToolUse | ツール実行の直前 | 危険なコマンドのブロック、セキュリティ検証 |
postToolUse | ツール実行完了後 | 実行結果のログ記録、監査証跡の生成 |
postToolUseFailure | ツール実行が失敗した後 | エラー通知、リトライ判断 |
agentStop | メインエージェントがターンを終える時 | 応答完了のトラッキング |
errorOccurred | エラー発生時 | エラーログの記録、アラート送信 |
このうち最も強力なのが**preToolUse**です。エージェントがファイル編集やコマンド実行といったツールを使う直前に割り込み、実行を「許可（allow）」「拒否（deny）」「確認を求める（ask）」のいずれかに振り分けられます。危険な操作の防止や、特定の承認フローを強制したい場合に使います。
設定ファイルの書き方
Hooksの設定はJSONファイルとして、以下の場所に配置します。
- リポジトリ単位：
.github/hooks/*.json（そのリポジトリでCopilotエージェントを使う際に常に適用） - 個人設定（CLI）：
~/.copilot/hooks/*.json
基本構造
{
"version": 1,
"hooks": {
"preToolUse": [],
"postToolUse": []
}
}コマンドフックの例
{
"version": 1,
"hooks": {
"sessionStart": [
{
"type": "command",
"bash": "echo \"Session started\" >> logs/session.log",
"timeoutSec": 10
}
],
"preToolUse": [
{
"type": "command",
"bash": "./scripts/security-check.sh",
"timeoutSec": 15
}
]
}
}typeにはcommand（シェルコマンド実行）以外に、http（外部エンドポイントへのリクエスト）やprompt（Copilot自身への追加指示）も指定できます。用途に応じて使い分けます。
主なプロパティ
| プロパティ | 必須性 | 説明 |
|---|---|---|
type | 必須 | command / http / prompt のいずれか |
bash | Unix系で必須 | 実行するBashスクリプト（コマンドフックの場合） |
powershell | Windows・CLI限定 | 実行するPowerShellスクリプト |
cwd | 任意 | コマンドの実行ディレクトリ |
env | 任意 | 渡す環境変数 |
timeoutSec | 任意 | タイムアウト秒数（デフォルト30秒） |
動作の注意点
- 同期実行でブロックする：Hooksはエージェントの処理を止めて実行されるため、実行時間の目安は5秒以下に収めるのが推奨されています。外部API呼び出しなど重い処理を
preToolUseに入れると、Copilot自体の応答が遅くなります - 失敗時の挙動が違う：
preToolUseはコマンドが失敗すると「拒否（deny）」扱いになる一方、タイムアウト時は「許可（allow）」扱いになります。この非対称な挙動を把握した上で設計する必要があります - 入力のサニタイズが必須：Hooksはエージェントの動作に関する詳細情報をJSONで受け取れますが、外部コマンドに渡す際はシェルエスケープや、トークンなど機密情報をログに残さない配慮が必要です
こんな場面で使うと効果的
- セキュリティポリシーの強制：
preToolUseで特定のファイルパスへの書き込みや、危険なシェルコマンドの実行を機械的にブロックする - 監査ログの自動記録：
postToolUseでツールの実行結果を毎回ログに残し、後から何をしたか追跡できるようにする - チーム全体への一律適用：
.github/hooks/*.jsonをリポジトリにコミットしておけば、そのリポジトリでCopilotエージェントを使う全員に同じルールを強制できる
エンタープライズ向けには、管理者がリポジトリ横断でHooksとMCP設定を常時有効化できる「Enterprise-managed plugins」も別途用意されています。組織全体でガバナンスを効かせたい場合はあわせて検討するとよいでしょう。
まとめ
GitHub Copilot Hooksは、エージェントの自律的な動作に「人間が決めたルール」を組み込むための仕組みです。特にpreToolUseによるツール実行の許可・拒否は、Copilotを安全に自動化していく上で欠かせない機能になっていくと考えられます。まずはsessionStartでのログ記録など、影響範囲の小さいフックから試してみるのがおすすめです。
GitHub Copilotの他の機能を含めて全体像を押さえたい方は、こちらの記事もあわせてご覧ください。
👉 GitHub Copilot完全ガイド｜AIコーディングアシスタントの全貌【2026年7月版】
Copilot CLIの基本的な使い方から知りたい方はこちら。
コメント