Claude Code の Hooks 入門！PreToolUse / PostToolUse / Stop で実務を自動化する 4 つの型

監修者_SD以外

監修者プロフィール

森下浩志

日本最大級のAI情報プラットフォーム「romptn ai」編集長。著書に「0からはじめるStable Diffusion」「0からはじめるStable Diffusion モデル・拡張機能集編」など、AmazonベストセラーのAI関連書籍を多数執筆。AIにおける情報の非対称性を解消するための社内研修や出張講義も行う。

Hooks がワークフローのどこに刺さるか

公式リファレンスを読んでも手が止まるのは、Hooks の発火点が自分のレビュー・通知・CI ワークフローのどこに刺さるか結べていないからです。まずは定義ではなく、Claude Code が 1 タスクを進める流れの「どの瞬間」に割り込めるかという地図から押さえます。

代表的な 4 つの発火点は、1 サイクルの別々の位置に刺さります。

つまり「tool 実行の前後」と「ターンが止まる前後」の 2 軸で分かれており、自動化したい業務がどちらに乗るかで使う発火点が決まります。仕様の細部は記事ごとに揺れがあるため、本記事は 2026年5月時点の Anthropic 公式リファレンスを起点に整理しています。

位置取りが見えたら、次はその設定をどのファイルに書けば実際に発火するかを押さえます。

settings.json の置き場所と適用範囲

前の章で発火位置の地図を掴んだので、次は その設定をどのファイルに書けば自分の手元で動くか を確定させます。

Claude Code は次の 3 つの settings.json を読み込みます。読み込み順序は「ユーザー全体 → リポジトリ → ローカル個別」で、後勝ちです。

選び方はシンプルで、チーム全員に同じ hook を効かせたいなら .claude/settings.json、自分の作業環境だけで動かしたいなら .claude/settings.local.json か ~/.claude/settings.json を使います。リポジトリを跨いで効かせたい設定はユーザー全体に、特定プロジェクトだけに効かせたい設定はリポジトリ側に置く、という分け方になります。

試しに発火を確認するなら、まず ~/.claude/settings.json に下の最小設定を貼ってみてください。Claude Code がツール呼び出しを終えるたびに /tmp/claude-hooks.log に 1 行が追記されます。

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"fired: $(date -Iseconds)\" >> /tmp/claude-hooks.log"
          }
        ]
      }
    ]
  }
}

この最小構造を押さえておくと、後の章で出てくるブロック・通知・ログ・フォーマットの設定も、すべて同じ hooks キーの下に並べるだけで足りるようになります。

発火対象を絞りたい時は matcher を併記しますが、matcher はツール名の完全一致 + ワイルドカード () で評価され、正規表現ではありません。コミュニティ記事で正規表現として書かれている例が流通しているので、後の章で matcher を使う時はこの仕様を念頭に置いてください。

4 大ユースケースで Hooks を覚える

設定ファイルの置き場所がわかったところで、ここからは実際に何を書けば現場の仕事に刺さるかを 4 つの型で覚えていきます。

コミュニティで定着している「ブロック / 通知 / ログ / フォーマット」の 4 ユースケースは、それぞれ Hooks のどのイベントに乗せるかが概ね決まっています。次の章から、この 4 つを最短経路の動くサンプルで並べていきます。

まずは auto モードで git push や rm -rf が突然走る恐怖を止める PreToolUse によるブロックから入ります。ここが固まると、残りの 3 つも同じ発火モデルで読み解けるようになります。

① 危険な操作を PreToolUse でブロック

auto モードで git push --force や rm -rf が突然走る恐怖を止める一番確実な手段が、PreToolUse hook + exit 2 の組み合わせです。tool 実行の直前にスクリプトが呼ばれ、stderr に理由を書いて exit code 2 で終了すると、Claude Code は当該 tool 呼び出しを必ず中断します。

まず settings.json に貼る最小設定は次のとおりです。check-dangerous.sh の中で stdin の JSON から tool_input.command を読み、危険パターンに当たれば exit 2 するだけの素朴な実装で構いません。

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

チェック対象は rm -rf / git push --force / :(){:|:&};: のような fork bomb / 認証情報を含むパスへの書き込みなど、自分の運用で「絶対に通したくない」コマンドだけを正規表現で並べます。

ここで気になるのが、settings.json の permissions.deny で十分ではないかという点です。実際には permissions.deny には 2 つの抜け穴があります。1 つはコマンド連結の検査上限で、; や && で 50 個以上にチェーンされた長い 1 行は全体までは検査されません(内部定数で上限が決まっています)。もう 1 つは Task tool 経由のサブエージェント実行で、サブエージェントが発火する Bash には親側の permissions.deny がそのまま適用されないため、ここを通り抜ける危険があります。

そこで、permissions.deny を粗い 1 段目のガード、PreToolUse hook + exit 2 を確実に止める 2 段目の堰として重ねるのが現実的です。前者で「明らかに許可しないコマンド」を宣言的に弾き、後者で「許可ルールの隙間から漏れた危険コマンド」を実コードで止めます。この 2 段防御まで組んで初めて、auto モードを安心して回せる土台になります。

② Stop と通知でタスク完了を知らせる

長時間ジョブが終わったのに気づかず別タブを開きっぱなし、というストレスは Stop と Notification の 2 つの hook で消せます。Stop はアシスタントのターンが終わった瞬間に、Notification は権限プロンプトや入力待ちが発生した瞬間に発火します。両者を別エントリーで書くと、発火タイミングの違いがそのまま設定の形に現れます。

どちらの hook も stdin に JSON が流れ、hook_event_name フィールドにイベント種別 (Stop / Notification) が入ります。スクリプトで分岐させる時はここを見ます。

macOS なら brew install terminal-notifier を入れて ~/.claude/settings.json に次を貼るだけで動きます。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -message 'タスク完了'"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -message '入力待ち'"
          }
        ]
      }
    ]
  }
}

保存して Claude Code を再起動すれば次のターンから鳴り始めます。Linux なら notify-send、Windows / WSL なら PowerShell の BurntToast に置き換えれば同じ形が使えます。

③ PostToolUse で実行ログを残す

auto モードで Claude Code を回していると、気付いたら複数の編集とコマンドが終わっていて、「いま何が走ったのか」を後から追えないことが起きます。

PostToolUse は tool 実行の直後に発火する hook です。ここで全 tool 呼び出しを 1 行ずつログファイルに追記しておけば、auto モードでも実行履歴を確実に残せます。

~/.claude/settings.json に次を追記します。matcher を空文字にして「全 tool 対象」とした最小構成です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c . >> /tmp/claude-hooks.log"
          }
        ]
      }
    ]
  }
}

PostToolUse の標準入力には session_id / tool_name / tool_input / tool_response を含む JSON が 1 件流れてきます。jq -c . で 1 行 JSON に整形して /tmp/claude-hooks.log に追記しているだけです。

挙動を確認するときは、別ターミナルで次を開きっぱなしにします。

tail -f /tmp/claude-hooks.log

この状態で Claude Code に作業させると、Edit / Write / Bash が走るたびに JSON が 1 行ずつ流れます。tool 名と引数が時系列で残るので、「何が起きたかわからない」が「ログを見れば再現できる」に変わります。

なお PostToolUse は tool 完了後に呼ばれる hook なので、ここで止めても副作用は戻せません。ブロックは前の節の PreToolUse、観測は PostToolUse、と役割を分けて重ねます。

④ PostToolUse で保存後フォーマット

Claude Code が編集したファイルを、自分の手で prettier や ruff を叩く前に整える hook です。PostToolUse で Edit / Write 系の tool 名にマッチさせ、書き換えが終わった直後に拡張子別のフォーマッタを走らせます。

Lint 漏れや差分ノイズを Hooks 層で固定できるので、レビューでの「formatter 走らせ忘れ」を Claude 任せにせず止められます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | while read -r f; do case \"$f\" in *.ts|*.tsx|*.js|*.jsx|*.json|*.md) prettier --write \"$f\" ;; *.py) ruff format \"$f\" ;; *.go) gofmt -w \"$f\" ;; esac; done"
          }
        ]
      }
    ]
  }
}

matcher は **正規表現ではなく、tool 名の完全一致とワイルドカード だけ*を受け付ける独自記法です。| は alternation のように見えますが、公式仕様では「複数の tool 名を | で並べた完全一致リスト」として扱われます。

2026 拡張で『次の一歩』を試す

ここまでで ブロック / 通知 / ログ / 保存後フォーマット の4大ユースケースは settings.json に貼れる状態になりました。ただし公式 reference はそこで止まっていません。最新仕様で追加された概念を「次の一歩」として触っていきます。

2026年5月時点の公式 reference では、初期4イベントから踏み込んだ新概念が積み上がっています。代表的なのは、PostToolUse の出力を書き換える updatedToolOutput、後段に文脈を差す additionalContext、claude -p で tool 呼び出しを保留する defer、reject に介入する PermissionDenied などです。

ここから先は Hooks が「外部コマンドを叩く仕組み」から Claude のループ内側に値を差し戻す装置 へ進化した領域で、公式 reference に戻って読み解く価値があります。

この後、新概念のうち実務で踏み込む 2 本を実装例として取り上げます。まず『updatedToolOutput で出力を差し替え』で tool 出力の書き換えと文脈注入 を、続く『defer と PermissionDenied で再開』で CI・外部 UI に処理を委譲する再開フロー を組み立てます。

① updatedToolOutput で出力を差し替え

PostToolUse の戻り値で Claude が次に読むテキストだけを書き換える 機能です。tool 自体はすでに実行済みなので、ファイル書き込みや API 呼び出しといった副作用は止まりません。書き換えられるのは Claude の視界に入る文字列だけ、と捉えてください。

軸は 2 つあります。updatedToolOutput(MCP tool なら updatedMCPToolOutput)は tool 出力そのものを別文字列に差し替え、additionalContext は元の出力を残したまま末尾に補足を継ぎ足します。長大なログを要約する前者と、警告コメントを 1 行添える後者、と使い分けます。

以下は Bash の出力を末尾 50 行に切り詰めつつ、続きで補足を渡す最小例です。

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/post-bash.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/post-bash.sh — stdin に PostToolUse の入力 JSON が届く
jq -nc \
  --arg out "$(jq -r '.tool_response.stdout // ""' | tail -n 50)" \
  --arg ctx "上の出力は末尾 50 行に切り詰めています。全文は /tmp/last-bash.log を参照してください。" \
  '{ updatedToolOutput: $out, additionalContext: $ctx }'

公式仕様で押さえる注意点が 2 つあります。

② defer と PermissionDenied で再開

defer と PermissionDenied は、止まった会話を外側から再開するための 2 つの仕組みです。defer は PreToolUse の permissionDecision 値で、claude -p 非対話モードでだけ尊重されます (v2.1.89 以降)。PermissionDenied は auto モードでだけ 発火し、PreToolUse ブロックや deny ルールでの拒否では呼ばれません。

// .claude/settings.json — 2 つ並べて登録できます
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "AskUserQuestion",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/pre-defer.sh" }
        ]
      }
    ],
    "PermissionDenied": [
      {
        "hooks": [
          { "type": "command", "command": ".claude/hooks/permission-denied.sh" }
        ]
      }
    ]
  }
}

defer 側のスクリプトは AskUserQuestion のような対話必須の tool を保留する例です。

#!/usr/bin/env bash
# .claude/hooks/pre-defer.sh
jq -nc '{
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "defer"
  }
}'

この hook を返すと claude -p は stop_reason: "tool_deferred" で終了し、保留中の呼び出しが deferred_tool_use として SDK 結果に含まれます。呼び出し側 (GitHub Actions / 独自 UI) はそれを読み、回答を自前で集めて --resume します。

# 呼び出し側 (CI / 外部 UI) — claude -p を SDK でラップしている前提
RESULT=$(claude -p "<prompt>" --output-format json)
STOP_REASON=$(echo "$RESULT" | jq -r '.stop_reason')
SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')

if [ "$STOP_REASON" = "tool_deferred" ]; then
  echo "$RESULT" | jq '.deferred_tool_use' > /tmp/deferred.json
  ANSWER=$(./collect_answer_from_ui.sh /tmp/deferred.json)
  DEFER_RESUME_INPUT="$ANSWER" claude -p --resume "$SESSION_ID"
fi

再開時は同じ PreToolUse が再発火するので、スクリプトを permissionDecision: "allow" と updatedInput を返す側に切り替えて回答を tool に渡します。タイムアウトや再試行上限はなく、セッションは既定 30 日残ります。

PermissionDenied 側は、auto モード分類器が止めた呼び出しに対し、モデルへ「再試行してよい」メッセージだけ追加するためのものです。

#!/usr/bin/env bash
# .claude/hooks/permission-denied.sh
jq -r '.reason' >> /tmp/claude-denied.log
jq -nc '{
  hookSpecificOutput: {
    hookEventName: "PermissionDenied",
    retry: true
  }
}'

公式 Hooks reference で押さえる注意点です。

5 つのハンドラの向き不向き

新しい発火点を試した後は、改めて hook を 何で実装するか(ハンドラの選び分け)を押さえておきます。2026年5月時点の公式 reference では、hook の実体として command / http / mcp_tool / prompt / agent の 5 種類が用意されており、それぞれ向き不向きが明確に分かれます。

本記事の実装例はすべて command ハンドラで揃えています。シェルから自分の手で動かして挙動を確かめやすく、他の 4 つに置き換える判断軸も上の表でひと目で見られるためです。

安全に運用するための原則

ここまで 4 大ユースケースと 2026 拡張、5 つのハンドラまで一通り見てきました。最後に、これらを settings.json に貼る前に押さえておきたい運用原則をまとめます。

前提として、hook の command は Claude Code を起動している ユーザー権限のシェルでそのまま走ります。stdin から来る JSON の file_path や tool_input をそのままシェル展開するとコマンドインジェクションになるため、値は一度パースし、$HOME/.ssh や .env 等の機密パスは matcher 側で弾いてください。

そのうえで、本番に貼る前に必ず思い出したい落とし穴が 3 つあります。

想定どおり動かないときにまず疑う 3 点も覚えておきます。

各イベントの入出力 JSON や発火条件は更新が速いため、迷ったら一次情報である Anthropic 公式 reference に戻るのがいちばん確実です。

CLAUDE.md / Skills との住み分け

ここまでは Hooks 単体の安全運用を見てきましたが、最後に Claude Code の自動化スタック全体に視点を引き、Hooks がどこに位置するかを地図として整理します。

自分で組み上げたはずのハーネスが大きくなるほど、CLAUDE.md・Skills・Hooks・sub-agent・MCP のどれに何を寄せたか分からなくなりがちです。判断軸は 「LLM の解釈に任せる層か、決定論的に必ず走る層か」 の 1 本に絞ると整理しやすくなります。

つまり LLM の判断に揺らがせたくない処理(危険コマンドの遮断・保存後フォーマット・実行ログ・通知)は Hooks に寄せ、自然言語で柔軟に伝えたい規約や手順書は CLAUDE.md と Skills に置く、という住み分けになります。「より確実に発火させたいなら Hooks」「LLM 依存のガイダンスは CLAUDE.md」「タスク単位で繰り返す手順は Skills」と覚えておくと、新しい自動化を足す時にどの層へ書くべきかの迷いが減ります。

Claude Code Hooks のまとめ

ここまで、4 大ユースケースから 2026年5月時点の最新仕様、ハンドラ選び、安全運用、他レイヤーとの住み分けまでをひと続きで見てきました。

本記事のポイントを振り返ります。

最初の一歩としては、「PostToolUse で実行ログを残す」の章の最小設定を ~/.claude/settings.json に貼り付け、別ターミナルで tail -f /tmp/claude-hooks.log を流しながら Claude Code を 1 タスク走らせてみてください。tool 呼び出しごとに JSON が届く手応えを掴めば、PreToolUse でブロックを足す・Stop で通知を鳴らすといった応用に自然に進めます。

Hooks は記事を読むより手元で動かす方が圧倒的に早く理解できるレイヤーです。最小の 1 hook から settings.json に書き始め、自分のワークフローに必要な型だけを少しずつ重ねていきましょう。