GitHub Copilot hooksは、AIエージェントの実行を「後から監査する」だけでなく、実行前に止めるための仕組みです。公式ドキュメントでは、hooksはエージェントのワークフロー上の重要な時点でカスタムシェルコマンドを実行し、JSON入力を受け取って文脈に応じた自動化ができると説明されています。特にpreToolUseは、bash、edit、viewなどのツール実行前に動き、承認または拒否に使えるため、企業導入では最初に設計すべき統制ポイントです。
この記事では、2026年9月時点のGitHub公式ドキュメントをもとに、8種類のhook、repository hooksとpersonal hooksの違い、preToolUseで止めるべき操作、30日PoCの進め方を整理します。対象はGitHub Copilot cloud agentやGitHub Copilot CLIを、開発チームに広げる管理者・セキュリティ担当・Engineering Managerです。
結論：hooksは「AIエージェント用の実行ゲート」として設計する
Copilot hooksの価値は、AIが何をしたかをログに残すだけではありません。危険なコマンド、秘密情報の出力、社内標準に反する編集、承認なしの外部通信などを、実行前・実行後・セッション終了時に分けて扱える点にあります。従来のCIはPR作成後の検査に強い一方、agentic codingではツール実行の途中で判断したい場面が増えます。hooksはその隙間を埋める仕組みです。
導入判断は3つに分けると明確です。第一に、どの操作を即時拒否するか。第二に、どの操作をログだけに留めるか。第三に、どの操作を人間のレビューに回すか。最初から全操作をブロックすると開発体験が崩れるため、preToolUseは高リスク操作に絞り、postToolUseとsessionEndで監査証跡を補うのが現実的です。
Copilot hooksやAI coding agentの安全な導入設計を相談したい場合は、 HelloCraftAIにご相談ください。
公式仕様：8種類のhookでどの時点を制御できるか
GitHub公式ドキュメントでは、利用可能なhookとして sessionStart、sessionEnd、userPromptSubmitted、preToolUse、postToolUse、agentStop、subagentStop、errorOccurred の8種類が示されています。sessionStartは環境初期化や監査ログ開始、sessionEndは一時リソースの削除やレポート保存、userPromptSubmittedは依頼内容の記録に向きます。errorOccurredは失敗パターンの検知や通知に使えます。
なかでもpreToolUseは最も強い統制点です。ツール実行前に動き、危険なコマンドをブロックしたり、セキュリティポリシーやコーディング標準を強制したり、コンプライアンス用途でツール利用を記録したりできます。postToolUseは実行結果、利用統計、監査証跡、失敗アラートに向きます。agentStopとsubagentStopは、親エージェントやサブエージェントが完了した時点で結果確認や要約保存を行う用途に適しています。
repository hooksとpersonal hooksの違い
hooksはJSONファイルで定義します。リポジトリに置く場合は .github/hooks/*.json に保存し、そのリポジトリでCopilot agentsを使うときに適用されます。Copilot CLIでは、ホームディレクトリの ~/.copilot/hooks/*.json に置くpersonal hooksも使えます。企業利用では、まずrepository hooksでチーム共通の最低基準を定義し、個人の作業補助はpersonal hooksに分けるのが管理しやすい設計です。
設定ファイルには version: 1 と hooks オブジェクトを置きます。各hookは type: command を持ち、Unix系ではbash、Windowsではpowershellを指定します。cwd、env、timeoutSecも設定できます。timeoutSecの既定値は30秒ですが、公式ドキュメントは可能なら5秒未満に保つことを推奨しています。重い処理を同期hookに詰め込むと、エージェント体験が遅くなるため注意が必要です。
preToolUseで最初に止めるべき3つの操作
1つ目は、秘密情報を外部に出す可能性がある操作です。公式ドキュメントも、tokensやpasswordsなどの機密情報をログに残さないこと、入力を必ず検証・サニタイズすることを求めています。hook側では、環境変数の一括出力、認証ファイルの表示、外部URLへの送信を検知対象にします。
2つ目は、破壊的なファイル操作です。例として、広範囲の削除、履歴を書き換えるGit操作、生成物ではなくソースを直接上書きするスクリプトなどがあります。すべてを禁止するのではなく、対象パス、ブランチ、ユーザーの意図、CI状況をJSON入力から確認し、条件に合わない場合だけ拒否する設計にします。
3つ目は、社内標準を迂回する実行です。たとえば、テストを省略したコミット、未承認のパッケージ追加、社内で許可されていない外部ネットワーク呼び出しなどです。Copilot cloud agentの環境設定やfirewall、MCP allowlistと組み合わせると、hooksは「現場ごとの最後の確認ゲート」として機能します。
30日PoC：ログだけから始めて拒否ルールへ移行する
PoCは30日で3段階に分けるのが現実的です。1週目はpostToolUseとsessionEndでログだけを集めます。2週目は危険操作の候補を分類し、誤検知が多いルールを除外します。3週目からpreToolUseで低リスクな拒否ルールを1つだけ有効にし、4週目に対象リポジトリを広げます。いきなり全社強制にすると、開発者はhookを回避する方法を探し始めます。
評価指標は、拒否件数、誤検知率、hook実行時間、開発者からの解除依頼、CI失敗率の5つです。特にhook実行時間は重要です。公式ドキュメントはhooksが同期的に実行されエージェント処理をブロックすると説明しているため、重いスキャンはバックグラウンド処理やキャッシュに逃がし、preToolUseは短い判定だけに絞ります。
管理者チェックリスト：8項目
導入前に確認する項目は次の8つです。1. 適用対象はcloud agentかCLIか。2. repository hooksとpersonal hooksの責務を分けたか。3. preToolUseで拒否する操作を3種類以内に絞ったか。4. ログに秘密情報を残さない設計か。5. timeoutSecを短く設定したか。6. Windows利用者向けにpowershellも用意したか。7. 誤検知時の解除フローを決めたか。8. sessionEndで監査レポートを保存するか。
この8項目を満たすと、hooksは単なる便利機能ではなく、AI coding agentの運用標準になります。特にEnterpriseでは、GitHub Copilot policies、audit logs、managed settings、MCP allowlist、cloud agentの環境設定と組み合わせて、どの層で何を止めるかを整理する必要があります。hooksだけで全リスクを消すのではなく、複数の制御を重ねる前提で設計します。
既存のCI・セキュリティツールとの使い分け
CIは成果物の品質確認に向いています。静的解析、テスト、ライセンスチェック、SASTなどはPR後にまとめて実行できます。一方、hooksはエージェントの行動中に介入できます。つまり、CIは「出力の検査」、hooksは「行動の制御」です。両者を混同すると、hookに重い検査を入れすぎて遅くなり、CIに任せるべきものまで同期実行してしまいます。
おすすめは、preToolUseで高リスク操作の入口を閉じ、postToolUseで実行結果をJSONLなどに追記し、CIで最終品質を確認する流れです。社内の監査観点では、誰が何を依頼し、エージェントがどのツールを使い、どの操作が拒否され、最終的にどのPRに反映されたかを追える状態が理想です。
FAQ：Copilot hooks導入でよくある質問
Q. hooksはCopilot cloud agentだけの機能ですか？ A. 公式ドキュメントでは、Copilot cloud agent on GitHub と GitHub Copilot CLI の両方で利用できると説明されています。ただしpersonal hooksはCopilot CLI向けの使い分けとして扱うのが自然です。
Q. preToolUseですべての危険操作を止められますか？ A. すべてを止める前提ではなく、明確に定義できる高リスク操作から始めます。入力の検証、shell escaping、秘密情報ログ禁止、権限設定、外部ネットワーク呼び出しの扱いを組み合わせる必要があります。
Q. hooksの処理が遅い場合はどうすべきですか？ A. 公式ドキュメントはhooksが同期的に実行されると説明しています。重い処理はバックグラウンド化し、キャッシュを使い、preToolUseは5秒未満を目安に短く保つのがよいです。
まとめ：最初の1本はpreToolUseの拒否ルールにする
Copilot hooksは、AI coding agentを企業で使うときの「実行前ガードレール」です。8種類のhookを全部使う必要はありません。最初はログ収集から始め、30日PoCで危険操作を見極め、preToolUseに1つだけ拒否ルールを入れるのが現実的です。開発速度を落とさずに統制を入れるには、CI、監査ログ、managed settings、MCP allowlistと役割分担することが重要です。
GitHub Copilot hooks、cloud agent、AI coding agentの安全な展開設計を進めたい方は、 HelloCraftAIへお問い合わせください。
