フックとは？AIエージェントの操作をコードで止める仕組み

「このコマンドは使わないで」と指示ファイルに書いたのに、AIコーディングエージェントがまた同じ操作をしてしまうことがあります。

そんな場面に、心当たりはありませんか？

実は CLAUDE.md や AGENTS.md のような指示ファイルは、守るかどうかの判断をモデルに委ねる仕組みです。

これに対して、決まった時点で必ず実行される処理を差し込めるのが「フック（hooks）」です。

一言で表すなら、指示ファイルは「お願い」、フックは「強制」という違いになります。

1 指示ファイルは「お願い」、フックは「強制」
2 フックを差し込めるのは「決まった時点」
3 止めるときは「終了コード 2」か JSON で返す
4 向いている用途と、向かない用途
5 取り入れる前に知っておきたい落とし穴
6 最後に

指示ファイルは「お願い」、フックは「強制」

指示ファイルのルールは、モデルの文脈に読み込まれる「文章」にすぎません。

読んだうえでどう動くかはモデル次第なので、読んでいても守られないことがあるわけです。

指示ファイルの役割と書き方は、こちらにまとめました。

AGENTS.md とは？AIコーディングエージェントに渡す『プロジェクトの取扱説明書』

毎回AIに同じ前提を説明する消耗を断つのが AGENTS.md。技術スタックや規約・手順を1ファイルに畳んで渡す標準として、なぜ広まったのか、何を書き、どう更新し続けるかを整理します。

フックを差し込めるのは「決まった時点」

フックは、エージェントの動きの中に用意された「イベント」に結び付けて登録する仕組みです。

Claude Code のフックリファレンスを見ると、代表的なイベントは次のとおりでした。

Hooks reference – Claude Code Docs

Reference for Claude Code hook events, configuration schema, JSON input/output f…

Claude Code Docs

SessionStart / SessionEnd: セッションの開始時・終了時
UserPromptSubmit: プロンプトを送信し、Claude が処理する前
PreToolUse / PostToolUse: ツールの実行前・実行が成功した後
Stop: Claude が応答を終えたとき

2026年9月時点のリファレンスには30を超えるイベントが並び、中でも使いどころが多いのがツールの実行直前に割り込める PreToolUseです。

設定は ~/.claude/settings.json やリポジトリの .claude/settings.json に、「イベント → matcher（対象の絞り込み）→ 実行する処理」の3段で書きます。

Bash ツールの実行前に Python スクリプトを呼ぶ例を、公式の書式に沿って示すと次のとおりです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/block_rm.py"]
          }
        ]
      }
    ]
  }
}

これは書式の例で、私の手元の設定には登録していません。

Cursor の Hooks も同じ発想の仕組みで、イベント名の体系は異なるものの、終了コード 2 で止める点は Claude Code に合わせてあると明記されていました。

Hooks | Cursor Docs

Built-in hooks and how to use them effectively in Cursor.

Cursor Documentation

止めるときは「終了コード 2」か JSON で返す

フックには、これから起きる操作の中身が JSON で渡されます。

コマンド型なら標準入力で受け取り、終了コードで結果を返すのが基本で、2026年9月時点のリファレンスが定める意味は次の3つです。

0: 成功。何も出力しなければ「判断なし」で、通常の許可確認へ進む
2: ブロック。PreToolUse ならツールを止め、標準エラー出力が理由として Claude に届く
それ以外（1 など）: 多くのイベントでは、それだけではブロックしないエラー扱いで処理が続く

一般的な失敗の合図である 1 では止まらない点に注意してください。

止める側のスクリプトは、概念を示すと次のような形になります。

import json
import sys

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

if "rm -rf" in command:
    print("Blocked: rm -rf is not allowed in this project", file=sys.stderr)
    sys.exit(2)  # 2 で止める（1 では止まらない）

sys.exit(0)  # 判断なし＝通常の許可確認へ進む

スクリプト単体に JSON を流して試すと、rm -rf を含む入力では終了コード 2、ls では 0 で終わりました（Python 3.12.10・Claude Code には未登録）。

止められた理由は Claude に届くので、エージェントは別のやり方を考え直せるわけです。

PreToolUse なら、0 で終えて JSON を返すことで deny・allow・ask・defer（拒否・許可・確認・保留）も指示できます。

公式ガイドによれば、deny は権限確認を省く bypassPermissions モードでも効く一方、allow では設定の拒否ルールを覆せません。

つまり、フックは制限を強められても、権限設定より緩めることはできないという関係です。