Claude Codeのhooks早見表

Claude Codeのhookのイベントは33個で、16個はexit 2で止められます。イベントとexit codeを表で引けます。

hooks は、Claude Code の決まった時点で自動で動く、利用者が書いたシェルのコマンド、HTTP のエンドポイント、MCP のツール、LLM のプロンプト、サブエージェントです。ターミナル、IDE の拡張、デスクトップアプリ、クラウドのセッションのどこでも、同じイベントで動きます。このページは早見表です。全イベントの表、exit code と JSON の表、最小の例、hook ごとに動かして確かめた記事への案内を載せています。どれも2026年10月24日に公式のリファレンスと照らし合わせ、Claude Code 2.1.310 で確かめました。

全イベントの一覧

公式ドキュメントに載っているイベントは33個です。「exit 2」の列は、そのイベントの hook が終了コード 2 で終わったときに起きること、「matcher」の列は matcher が何と比べられるかです。「なし」は matcher に対応せず、毎回動くイベントです。

出典：https://code.claude.com/docs/en/hooks 、2026-10-24確認

exit 2 で止められるのは、PreToolUse、UserPromptSubmit、UserPromptExpansion、Stop、SubagentStop、TeammateIdle、TaskCreated、TaskCompleted、ConfigChange、PostToolBatch、PreCompact、PreModelSwitch、Elicitation、ElicitationResult、WorktreeCreate、WorktreeRemove の16個です。WorktreeCreate と WorktreeRemove は 0 以外の終了コードで失敗し、WorktreeRemove はその後もディレクトリが残っているときだけ失敗します。

exit code と JSON の早見表

よく使う JSON のフィールドです。

出典：https://code.claude.com/docs/en/hooks 、2026-10-24確認

置き場所と最小の例

hook の設定は、これらの階層で上書きされず足し合わされます（出典：https://code.claude.com/docs/en/hooks 、2026-10-24確認）。

一番小さい PreToolUse の hook は、1つのコマンドを止めるものです。ダミーのプロジェクトで npm publish を止める例です。

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/no-publish.sh" } ] }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/no-publish.sh  (PreToolUse, matcher: Bash)
cmd=$(jq -r '.tool_input.command // ""')
case "$cmd" in
  *"npm publish"*) echo "Blocked: publishing is done by a human." >&2; exit 2 ;;
esac
exit 0

2026年10月24日に、ダミーの JSON を流して確かめました。{"tool_name":"Bash","tool_input":{"command":"npm publish"}} では Blocked: publishing is done by a human. と出て exit 2、npm test では exit 0 でした。設定ファイルは jq と claude doctor を通りました。実際のセッションの中で発火するところは見ていません（未実行）。

hooks の記事を読む順番

考え方から入り、例を写し、動かないときの確かめ方を知り、最後に設計を考える順に並べました。

• Claude Code hooks実践：hook が散文のルールより効く理由と、終了コードの意味を実測で確かめた入門
• PreToolUse hookの例集：rm -rf / や秘密ファイル、強制 push を止める、貼って使える6本
• PostToolUseで整形とテストを自動化：編集のたびに整形とテストを回す hook
• UserPromptSubmitの使い方：文脈を足す hook と、API キーを含むプロンプトを止める hook
• Stop hookで完了を確かめる：テストが通るまで止めない hook と、ループの防ぎ方
• hooksが動かないときの確認：発火しない・止まらない原因を再現して並べたチェックリスト
• AIの「完了しました」を信じない仕組み：完了報告を hook と git の実数で確かめる
• AIエージェントの権限設計：拒否ルールと hook の評価の順番
• permissions設定の早見表：hook と組み合わせる allow・ask・deny の書き方

まとめ

• Claude Code の hook のイベントは33個で、そのうち16個は exit 2 で止められる
• exit 0 は成功、exit 2 は止められるイベントで止める。それ以外の終了コードは、正しい JSON で別の判断を返さない限り処理を通す
• "onFailure": "block"（v2.1.295 以降）で、落ちた hook やタイムアウトした hook でも止められる。Stop 系と非同期の hook には効かない
• ツールを止めるなら PreToolUse、動いたあとに知らせるなら PostToolUse、終わる前に確かめるなら Stop
• ユーザー、プロジェクト、ローカル、組織、plugin の hook は、上書きされず足し合わされる