マルチエージェントClaude Codeのフックとは？AIの作業に安全柵を付ける方法
この記事の要点
- フックは、AIの作業の決まった場面で自動で動く小さな仕組み。止める・記録する・知らせるに使う
- 大事な決まりは「権限の設定」で守り、フックはその外側の見張り役として足す
- 2026年10月の更新で、フック自体が失敗したときに作業を止める設定（onFailure）が加わった
Claude Code に仕事を任せ始めると、次のような心配が出てきます。
- 消してはいけないファイルを、AIが消してしまわないか
- AIが何をしたのか、後から確かめられるか
- 長い作業が終わったことに、気づけるか
こうした心配に、人が毎回つきっきりで答えるのは大変です。Claude Code には、作業の決まった場面で自動で動く「フック（hooks）」という仕組みがあります。この記事では、公式ドキュメントにもとづいて、フックで AI の作業に安全柵を付ける考え方と、仕事で使う前に知っておきたい注意点を紹介します。
フックとは：決まった場面で自動で動く小さな仕組み
フックは、Claude Code の作業の流れの中の決まった場面で、自動で動く処理です。公式ドキュメントでは、シェルのコマンド・HTTP の送り先・MCP のツール・AIへの短い問いかけ・サブエージェントのどれかを、フックとして動かせると説明されています。ターミナル・IDE・デスクトップ・クラウドのどの使い方でも同じように動きます。
仕事で使う場面は、大きく3つに分けると考えやすくなります。
| 場面 | 主なイベント名 | 仕事での使い道 |
|---|---|---|
| 実行の前 | PreToolUse | 危ないコマンドや、触ってはいけない場所への書き込みを止める |
| 実行のあと | PostToolUse | 何をしたかを記録する・書いたファイルの形を整える |
| 終わったら | Stop・SubagentStop | 作業の終わりをチャットや通知で知らせる |
ほかにも、会話の始まり（SessionStart）、指示を送ったとき（UserPromptSubmit）、サブエージェントが動き始めたとき（SubagentStart）など、多くの場面が用意されています。
実行の前に止める：いちばん効く使い方
仕事で最初に入れたいのは「実行の前に止める」フックです。たとえば、ファイルを消すコマンドや、本番環境に関わる操作の前で止めます。
止め方は2通りあります。
- フックのコマンドが「終了コード2」で終わる：その操作は止まり、エラー出力に書いた理由が AI に伝わる
- 終了コード0で、決まった形の JSON を返す：「拒否する」「確認を求める」などを細かく指定できる
ここで注意したいのは、終了コード1などのそれ以外の終わり方は「止めない」扱いになることです。公式ドキュメントも、決まりを守らせたいフックでは終了コード2を使うように書いています。
設定の例（考え方を示すための一般的な形）は次のとおりです。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"if": "Bash(rm *)",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-delete.sh"
}
]
}
]
}
}matcher でどの道具（ここではコマンドの実行）に反応するかを選び、if でさらに「削除のコマンドのときだけ」と絞り込んでいます。
どこに書くか：個人・チーム・会社の3段階
フックの設定は、置き場所で効く範囲が変わります。
| 置き場所 | 効く範囲 |
|---|---|
| 自分の設定（ホームの .claude/settings.json） | 自分のすべてのプロジェクト |
| プロジェクトの .claude/settings.json | そのプロジェクト。チームで共有できる |
| プロジェクトの .claude/settings.local.json | そのプロジェクト。自分だけ |
| 管理者が配る設定（managed） | 会社全体。管理者が決める |
置き場所の違うフックは、置き換わるのではなく合わさって動きます。会社として必ず守りたい決まりは管理者が配る設定に、チームの約束はプロジェクトの設定に、個人の便利な仕組みは自分の設定に、と分けると整理しやすくなります。
仕事で使う前に知っておきたい3つの注意
公式ドキュメントには、フックを過信しないための注意も書かれています。
1. フックは「絶対の壁」ではない
if による絞り込みは「できる限り」の判定だとされています。必ず守りたい許可・禁止は、フックではなく権限（permissions）の設定で決めるのが基本です。フックは、その外側で見張る役と考えます。
2. フックが止まると、作業はそのまま進むことがある
フックには時間の上限があり、上限を超えたり、うまく起動しなかったりすると、初期設定では作業がそのまま進みます。2026年10月8日の更新（2.1.295）で、"onFailure": "block" を付けると、フック自体が失敗したときに作業を止められるようになりました。止める役のフックには付けておくと安心です。
3. プロジェクトのフックは「信頼」してから動く
プロジェクトに入っているサブエージェントのフックは、そのフォルダを信頼する確認に同意してから動きます。社外から受け取ったプロジェクトを開くときは、中のフックを読んでから信頼するようにします。また、フックは作業中の環境変数を読めるので、鍵などの秘密の値をフックの出力に出さない書き方にします。
導入の順番：小さく始めて、1つずつ足す
いきなり多くのフックを入れると、どれが効いているのか分からなくなります。次の順番がおすすめです。
- まず権限の設定で、使ってよい道具・使ってはいけない道具を決める
- 「実行の前に止める」フックを1つだけ入れ、止めたい操作で本当に止まるかを試す
- 「終わったら知らせる」フックを足し、長い作業を待つ時間を減らす
- 必要になってから「実行のあとに記録する」フックを足す
サブエージェントを何人も並べて動かすときほど、止める・知らせる仕組みが効いてきます。サブエージェントの並べ方はClaude Codeのマルチエージェント入門、役割ごとの深さの選び方はサブエージェントのeffortとモデルの使い分けで解説しています。
そのまま使える指示文の例（フックの下書き）
フックの中身も、Claude Code に下書きさせられます。
このプロジェクトに、次のフックを追加したい。下書きを作って、私が確認してから保存して。
・ファイルを削除するコマンドの前に止めて、理由を表示する（終了コード2で止める）
・フック自体が失敗したときも止める（onFailure を block にする）
・秘密の値は表示しない
最後に、止まることを確かめる手順も書いて。「確認してから保存」と書いておくと、設定が知らないうちに変わる心配が減ります。
よくある質問
プログラミングが分からなくても使えますか？
フックの中身は短いコマンドが多く、Claude Code に下書きを作らせて、説明を読みながら確かめる形で十分に始められます。止まることを自分の目で1回確かめるのが大事です。
権限の設定とフックは、どちらを先に入れますか？
権限の設定が先です。権限で「使ってよい・いけない」を決め、フックで「止まらなかったときの見張り」や「記録・通知」を足す順番にすると、役割が重なりません。
フックが原因で作業が遅くなりませんか？
フックが重いと、そのぶん作業が待たされます。止める役のフックは短く速い処理にし、時間のかかる記録や通知は、作業の終わり（Stop）にまとめると影響を小さくできます。
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
