Claude Code Hooksとは — 33イベントの選び方とexit codeの規則

Claude Code Hooksとは、ツール実行の前後・セッション開始・応答完了といった節目で、自分が登録したコマンドをClaude Codeに必ず実行させる仕組みです。登録先は settings.json の hooks キー。イベントの情報はJSONでコマンドの標準入力(stdin)に渡され、終了コード(exit code)で結果を返します。

CLAUDE.mdの指示はClaudeが読んで従うものなので、守られない余地が残ります。Hooksは条件が合えば毎回動きます。整形・遮断・通知のような「忘れてはいけない処理」を任せる場所です。

最初の1個を手順どおりに動かしたい場合はClaude Code Hooksの設定方法、用途別のコピペ用レシピはClaude Code Hooks実例カタログが受け持ちます。ここでは、イベントの選び方、設定の置き場所、終了コードの規則、動かないときの切り分けを扱います。

最小の動くHooks — 3階層の設定を読む

Hooksの設定は「イベント → matcherグループ → handler」の3階層です。次の例は、Edit か Write が成功するたびに、編集したファイルのパスをログへ追記します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path // empty' >> /tmp/hooks-demo.log"
          }
        ]
      }
    ]
  }
}

PostToolUse がイベント、matcher が対象ツールの絞り込み、hooks 配列の中身がhandlerです。command のhandlerには、イベントのJSONがstdinで届きます。jq はそのJSONから値を取り出しています。

登録できたかは、セッション内の /hooks で見ます。このメニューは閲覧専用で、追加や変更は設定ファイルを直接編集します。

/hooks

ファイルを書き換えた後は、通常は数秒で反映されます。反映されないときだけ、セッションを再起動します。

設定はどこに書くか — 7つの置き場所

置き場所でスコープと共有範囲が決まります。同じイベントのhookを複数の場所に置くと、すべてが実行されます。

チームで同じ遮断ルールを使うなら .claude/settings.json です。個人の通知設定なら ~/.claude/settings.json が向きます。同じhandlerを複数の設定ファイルに書いても、実行は1回に統合されます。

管理者が allowManagedHooksOnly を設定した環境では、ユーザー・プロジェクト・ローカル・プラグインのhookはブロックされます。/hooks に「Only hooks from managed settings run here」と出たら、これが原因です。

全hookを一時的に止めたいときは、設定に "disableAllHooks": true を書きます。1回の起動だけ止めるなら、--settings '{"disableAllHooks": true}' を渡します。個別のhookだけを残したまま無効にする方法はありません。

33イベントの一覧 — 発火のタイミングと止められるか

イベントは33種類です。「止められる」列は、exit code 2が処理を止める効果を持つかどうかを表します。×のイベントは、すでに起きたことを扱うか、止める手段を持たないイベントです。

セッションと設定まわり(12)

1ターンの入出力(6)

ツール呼び出し(6)

サブエージェント・タスク・外部連携(9)

33種類すべてを覚える必要はありません。まずは PreToolUse・PostToolUse・Stop・Notification・SessionStart の5つで足ります。残りは「その節目で何かしたい」と思ったときに引く索引です。

やりたいことから選ぶ

「止めたいなら Pre*、観察して副作用を起こしたいなら Post* と Stop」が、選ぶときの基本の軸です。

Stop に付ける完了条件の判定は、組み込みの /goal コマンドが同じことをします。公式ドキュメントでは、セッション単位のpromptタイプのStop hookへの近道として紹介されています。設定を書かずに済むなら、まず /goal を試す選択肢があります。

matcherの3つの評価ルール

matcher は、書いた文字の種類で評価方法が切り替わります。

Edit|Write は正規表現ではなく、2つの名前の列挙です。逆に正規表現になった側は部分一致で、Edit.* は NotebookEdit にも当たります。全体一致にしたいときは ^Edit$ と書きます。matcherは大文字小文字を区別するので、bash では Bash に当たりません。

matcherが見るものは、イベントごとに違います。

FileChanged と StopFailure は、完全一致の文字種がさらに狭く、英数字・_・| だけです。ハイフン・空白・カンマを含めた時点で正規表現として扱われます。

ifでツール名の先まで絞る

if フィールドは、権限ルールと同じ書き方(Bash(git *) や Edit(*.ts))で、引数まで見て発火を絞ります。

{
  "type": "command",
  "if": "Bash(git *)",
  "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
}

使える場所は、ツール系の5イベント(PreToolUse・PostToolUse・PostToolUseFailure・PermissionRequest・PermissionDenied)に限られます。それ以外のイベントに if を付けたhookは、一度も実行されません。エラーも出ません。

if に書けるルールは1つです。&& や ||、リストは使えません。複数の条件が要るなら、handlerを分けます。コマンドの中身を解析できないときは、条件に関係なくhookが走ります。確実に遮断したい処理は、if ではなく権限システムに任せる設計です。

handlerの5つのtype

handlerの type は5種類です。既定のタイムアウトは種類ごとに違います。

prompt と agent は、機械的なルールでは書けない判定向けです。モデルは { "ok": true/false } 形式で結果を返します。model を省略すると、Claude Codeがバックグラウンド処理に使うモデルで評価されます。agent は最大50ターンまで動けますが、実験的機能とされ、本番運用では command が勧められています。詳しい使い方はagent hookでテストが通るまで止めない、prompt hookでStopを判断させる、HTTPエンドポイントで受けるにあります。

同じイベントに登録したhookは並列に実行されます。prompt と agent が13件以上あるときは、12件ずつ走ります(同時実行の上限)。

タイムアウトは、イベントによって短く設定されています。

毎プロンプトの前に走る UserPromptSubmit に重い処理を置くと、応答の開始が遅れます。長い処理は async: true でバックグラウンドへ逃がせますが、その場合は結果で遮断も書き換えもできません。

stdin・exit code・JSONの規則

hookが受け取るもの

全イベントに共通するstdinのフィールドは、session_id・transcript_path・cwd・permission_mode・hook_event_name などです。その上に、イベント固有の値が載ります。PreToolUse なら tool_name・tool_input・tool_use_id です。サブエージェント内で発火したhookには、agent_id と agent_type も付き、メインセッションと見分けられます。

イベントごとにJSONの形が違うので、実装前に手元でサンプルを流して確かめると確実です。

echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?

exit codeの意味

exit 2の効果は、前掲の33イベントの表のとおりイベントごとに違います。例外が3つあります。

• PermissionRequest:exit 2は解釈されず、権限フローが進みます。拒否するときはJSONの hookSpecificOutput.decision を使います
• SessionStart・SubagentStart・SessionEnd など:exit 2でも止まらず、stderrが利用者の画面に出るだけです
• Setup・Notification・InstructionsLoaded など:終了コードもstderrも無視されます

PreToolUse を止める最小のスクリプトは、次のようになります。

#!/bin/bash
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")
 
if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2
fi
 
exit 0

rm で始まるコマンドは、stderrの文言がClaudeに返ってブロックされます。それ以外はexit 0で、通常の権限フローに進みます。

JSON出力で細かく制御する

exit codeでは「止める」か「何もしない」かの2択です。細かい制御は、exit 0でstdoutにJSONオブジェクトを1つだけ出して行います。

複数の PreToolUse hookが違う判定を返したときの優先順位は、deny > defer > ask > allow です。updatedInput で同じツールの入力を複数のhookが書き換えると、どの書き換えが採用されるかは保証されません。書き換えるhookは、1つのツールにつき1つに絞ります。

exit 2とJSONを混ぜた場合、exit 2のブロックが優先されます。stdoutに permissionDecision: "allow" を書いても、覆りません。方式はhookごとに1つ選ぶのが安全です。

追加の文脈(additionalContext など)とstdoutは、10,000文字が上限です。超えた分はファイルに保存され、Claudeには保存先のパスと冒頭の2,000文字までのプレビューが渡ります。

よくあるつまずきと切り分け

動いているのに効かない場合は、次の表で原因を探します。

Stop hookの無限再発火は/goal Stop hookが止まらない、PowerShellの件はPowerShell hookがexit 2で止まらない問題に、症状別の詳細があります。

よくある質問

HooksとCLAUDE.mdは、どう使い分けますか?

「必ず実行する処理」はHooks、「判断の指針」はCLAUDE.mdです。CLAUDE.mdはClaudeが読んで従う前提なので、解釈の余地があります。Hooksは節目で自動実行されます。

bypassPermissionsモードでもHooksは効きますか?

効きます。PreToolUse は権限モードの確認より前に発火します。permissionDecision: "deny" を返すと、bypassPermissions や --dangerously-skip-permissions でもツールが止まります。逆に、hookの allow で設定側のdenyルールを覆すことはできません。

サブエージェントの中のツール実行にも発火しますか?

発火します。設定ファイルやプラグインのhookは、サブエージェント内でも同じように走ります。stdinの agent_id と agent_type で見分けます。サブエージェントの仕組みはSub-agents完全ガイドにあります。

hookからスラッシュコマンドやツールを呼べますか?

command のhookは、stdout・stderr・exit codeだけで結果を返します。スラッシュコマンドもツール呼び出しも起動できません。Claudeに伝えたいことは、additionalContext として文脈に足します。

settings.json全体の書き方は、どこで確認できますか?

hooks 以外のキーも含めた全体は、settings.jsonの完全ガイドで扱っています。Claude Code自体の位置付けはClaude Codeの全体像から辿れます。

まとめ

Hooksを設計する手順は、3つの問いに落ちます。止めたいのか(Pre* とexit 2)、観察して副作用を起こしたいのか(Post*・Stop・Notification)、機械的なルールで書けない判定なのか(prompt / agent)です。

最初の1個は、PostToolUse の整形か PreToolUse の保護ファイル遮断が、効果と失敗の少なさの両面で扱いやすい選択です。動いたら、実例カタログから自分の運用に近いレシピを足していけます。