Claude Code の hooks 入門：整形・ブロック・通知を「確実に」自動化する

hooks とは

hooks は、Claude Code の動作の途中の決まった時点で、自分で用意した処理を自動で実行する仕組みです。実行できるのは、シェルコマンド、HTTP リクエスト、MCP ツールの呼び出し、モデルへの判定の依頼（prompt）、サブエージェントのいずれかです。

公式ガイドの趣旨は、「Claude が実行するかどうかを選ぶのではなく、特定の操作が必ず起きるようにする」ことです。CLAUDE.md に「.env は編集しない」と書くのは「お願い」にとどまりますが、hooks に書けば確実に止められます。

主なイベント

イベントは多数ありますが、まず覚えるのは次の5つです。

イベント	発火するタイミング
SessionStart	セッションを始める、または再開したとき
UserPromptSubmit	プロンプトを送信した直後、Claude が処理する前
PreToolUse	ツールを実行する前（ここで止められる）
PostToolUse	ツールの実行が成功した後
Stop	Claude が応答を終えたとき

ほかに、権限の確認が必要なときの PermissionRequest、通知を出すときの Notification、サブエージェントの開始と終了を捉える SubagentStart / SubagentStop、コンテキスト圧縮の前後の PreCompact / PostCompact などがあります。

設定ファイルの置き場所

場所	範囲	チームで共有
~/.claude/settings.json	すべてのプロジェクト	しない
.claude/settings.json	そのプロジェクト	できる（リポジトリに入れる）
.claude/settings.local.json	そのプロジェクト	しない
プラグインの hooks/hooks.json	プラグインが有効な間	できる

レベルが違う設定は置き換えではなく、足し合わされます。同じイベントに合致するフックは並列に実行されます。

設定例1：編集のたびに自動整形する

ファイルを編集または作成したあとに Prettier をかける例です。matcher で対象のツールを絞ります。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

フックのコマンドには、イベントの内容が JSON で標準入力に渡されます。上の例では jq でファイルのパスを取り出しています。

設定例2：保護したいファイルへの編集を止める

PreToolUse で、終了コード 2 を返すと操作がブロックされ、標準エラーに書いた文章が Claude へのフィードバックになります。

#!/bin/bash
# protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

登録は次のとおりです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

終了コードの意味

終了コード	意味
0	判断なし。通常の権限の流れが続く（PreToolUse でも、これだけでは「許可」にはならない）
2	ブロック。標準エラーの内容が Claude に返る
それ以外	ブロックしないエラー。処理は続く

公式ガイドは、フックごとに「終了コード 2 を使う」か「JSON を出力する」かのどちらか一方を選ぶよう書いています。

matcher の書き方

• "*"、空文字、省略：すべてに合致します。
• 英数字、_、-、|、, だけ：完全一致、または Edit|Write のような完全一致の並びになります。
• ほかの文字を含む：正規表現として評価されます（先頭や末尾は固定されません）。

Edit.* は NotebookEdit にも合致します。ぴったり一致させたいときは ^Edit$ と書きます。UserPromptSubmit や Stop など、matcher を受け付けないイベントもあります。

通知を出す

Claude が入力を待っているときにデスクトップ通知を出す例です（macOS）。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

使うときの注意

• matcher は狭く：allow を返すフックで matcher を広くすると、権限の確認がまとめて自動承認されます。
• ブロックは別のフックを止めない：同じイベントのフックはすべて動きます。あるフックの拒否に、別のフックの副作用を止めることを期待しないでください。
• if は厳密な制御には向かない：確実に許可・拒否したいときは、フックではなく権限の設定を使うよう案内されています。
• Bash での書き換えは拾えない：Bash コマンドで書き換えられたファイルは、Edit|Write の PostToolUse に合致しません。ファイルの変更を拾うなら FileChanged を使います。
• Windows：ファイルパスがバックスラッシュ区切りで届くため、比較の前に正規化します（上の例のスクリプトが行っています）。
• 組織の管理：管理者は allowManagedHooksOnly で、ユーザー・プロジェクト・プラグインのフックを止められます。

どこから始めるか

最初の1本には、編集後の自動整形（設定例1）か、デスクトップ通知が向いています。失敗しても被害が小さく、効果もすぐ見えます。慣れたら、保護ファイルのブロックのように、「やってはいけないこと」を確実に止める用途に広げるとよいでしょう。