Claude Code のフック（hooks）：イベント、例、仕組み

Claude Code のフックイベント

リファレンスには 30 以上のイベントが載っています。ここでは多くのフックが使うものを挙げます。matcher を使うと、フックの対象を特定のツール、ファイル、ソースに絞り込めます。

フックを置く場所

Claude Code のフックの例をステップごとに

各ブロックを設定ファイルの hooks キーの下に追加します。ファイルにすでに hooks オブジェクトがある場合は、置き換えずにイベントを同じ階層のキーとして追加してください。/hooks を実行すると、Claude Code が読み込んだか確認できます。Claude にフックを書いてもらうこともできます。

1. Claude があなたを必要としたらデスクトップ通知を受け取る

   ~/.claude/settings.json に Notification フックを追加します。この例は macOS の osascript を使っています。Linux では notify-send、Windows では PowerShell を使います。

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

2. Claude が編集したファイルをすべて自動フォーマットする

   Edit|Write にマッチする PostToolUse フックが、stdin の JSON から編集されたファイルのパスを jq で読み取り、Prettier を実行します。.claude/settings.json に置けばチームで共有できます。

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

3. 危険なコマンドをブロックする

   Bash に対する PreToolUse フックがこのスクリプトを実行します。終了コード 2 で呼び出しをブロックし、stderr に書いた内容は Claude へのフィードバックになるので、Claude は方針を変えられます。終了コード 0 は「判断なし」を意味し、通常の権限チェックがそのまま適用されます。

   #!/bin/bash
   # .claude/hooks/block-drop-table.sh。Bash の PreToolUse フックとして実行
   INPUT=$(cat)
   COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
   
   if echo "$COMMAND" | grep -q "drop table"; then
     echo "Blocked: dropping tables is not allowed" >&2  # Claude へのフィードバックになる
     exit 2                                               # 2 = 操作をブロック
   fi
   
   exit 0  # 判断なし：通常の権限フローが適用される

4. タスクが終わるまで Claude に作業を続けさせる

   prompt タイプの Stop フックが、すべて終わったかをモデルに確認します。答えが ok: false なら、Claude は reason を次の指示として作業を続けます。これが Stop フックの定番の例です。

   {
     "hooks": {
       "Stop": [
         {
           "hooks": [
             {
               "type": "prompt",
               "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
             }
           ]
         }
       ]
     }
   }

出典：Claude Code ドキュメント、Automate actions with hooks

フックが動作を決める仕組み

• 入力：各フックは、ツール名や tool_input、セッション ID、cwd などのイベント情報を JSON として stdin で受け取ります。
• 終了コード 0：異議なし。SessionStart や UserPromptSubmit など一部のイベントでは、通常の stdout が Claude のコンテキストに追加されます。
• 終了コード 2：イベントが許す場合はブロック。stderr はイベントに応じて Claude またはあなたに返されます。
• stdout への JSON 出力：より細かい制御。権限の判断を含む hookSpecificOutput、ツールの入力を書き換える updatedInput、additionalContext などです。
• その他の終了コード：フックで onFailure: "block" を設定していない限り、通常はブロックしないエラーとして扱われます。
• 1 つのイベントにマッチした複数のフックは並列に実行されます。

command・prompt・agent・HTTP フック

フックとスキルと CLAUDE.md の違い、その他の注意点

• CLAUDE.md とスキルは Claude がたいてい従う指示で、フックは必ず実行されます。絶対に飛ばしてはいけないことはフックに書きましょう。
• PostToolUse ではすでに実行された操作を取り消せません。止めたいなら PreToolUse を使います。
• Stop はタスクの終わりだけでなく Claude が応答を終えるたびに発火し、ユーザーが中断したときには発火しません。
• フック自身はスラッシュコマンドを実行したりツールを呼び出したりできません。やり取りの手段は終了コード、stdout、stderr、JSON だけです。
• "disableAllHooks": true でフックを無効にできます。ただし管理フックは、管理設定側でも無効にしない限り実行されます。
• フックはあなたの Claude Code 環境の中だけで動きます。すべての Claude 製品にかかる組織全体のチェックは別の機能です：Claude の inference hooks。
• テスト出力をフィルタする PreToolUse フックは、トークン使用量を減らす最も効果的な方法の 1 つでもあります。

フックは Claude Code にルールを守らせ、Crewmark は Claude Code を働かせ続けます。

無人で動くエージェントを安全にするのがフックです。フォーマット、テスト、ガードレールが毎回実行されます。Crewmark は、Claude Code、Codex、DeepSeek Harness、OpenCode のセッションを、職種・目標・勤務時間を持つ AI 社員に変え、ハートビートで起こしてボードから次の issue を取らせます。プロジェクトのフックも有効な状態です。

1. フックをコミットする

   .claude/settings.json のフックは、あなたのセッションと同じように社員のセッションでも読み込まれるので、社員の編集はフォーマットされ、危険なコマンドはブロックされます。

2. ハートビートで仕事を始めさせる

   勤務時間中、社員は15分、30分、60分ごとに同じ会話の中で起きます。Claude Code を能動的にする方法もご覧ください。

3. あなたが必要なことにだけ答える

   社員は自分の issue にコメントし、判断が必要なときはメッセージを送ってきます。AI 社員とはもご覧ください。

Claude Code のフックのよくある質問