Claude Code の hook 解説: 全イベントとその用途

01hook の構成

hook の設定は 3 つの階層で構成されます。

1. hook イベント：PreToolUse や Stop など。
2. matcher グループ：「Bash ツールのときだけ」のように、発火する条件を絞り込みます。
3. 1 つ以上の hook ハンドラー：実際に実行される処理です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

この例では、Claude がファイルを書き込み・編集した後に lint スクリプトを実行します。別のイベントを追加するには、同じ hooks オブジェクト内に兄弟キーを追加します。

02hook の配置場所

異なるファイルの hook は置き換えられるのではなく、すべて合算されます。Claude Code で /hooks と入力すると、有効なすべての hook とその定義元を確認できます。

対話セッションでは、フォルダーのワークスペース信頼ダイアログを承認するまで、Claude Code は自分で定義したものも含めて hook を実行しません。

03ハンドラーの種類

ほとんどの hook は、シェルコマンドを実行する "type": "command" です。ほかに 4 種類あります。

• http：イベントの JSON を URL に POST し、レスポンスボディを読み取ります。
• mcp_tool：設定済みの MCP サーバーのツールを呼び出します。
• prompt：Claude モデルにシングルターンで問い合わせ、JSON 形式の判定を読み取ります。
• agent：判定前にファイルを読み込めるサブエージェントを起動します（実験的機能）。

command hook はユーザーの権限をすべて持った状態で実行されます。macOS と Linux では sh -c、Windows では Git Bash（または PowerShell）を介して実行されます。"async": true を追加するとバックグラウンドで実行されますが、その場合は判定を返せなくなります。

04matcher

matcher は、イベントのどの発生時に hook を実行するかを決めます。照合対象はイベントによって異なり、ツールイベントではツール名、Notification では通知の種類、SessionStart ではセッションの開始方法などになります。

• "*"、""、または matcher の省略は、すべてにマッチします。
• 英字、数字、_、-、スペース、|、, だけで構成される場合は完全一致の名前として扱われます。Edit|Write はどちらのツールにもマッチします。
• それ以外は JavaScript の正規表現として扱われるため、mcp__memory__.* は 1 つの MCP サーバーのすべてのツールにマッチします。

matcher は大文字と小文字を区別します。Stop や UserPromptSubmit など、一部のイベントは matcher を無視します。ツールイベントでは、"Bash(git *)" のような権限ルールを if フィールドに指定すると、個々のハンドラーをさらに絞り込めます。

05入力：hook が受け取るデータ

すべての hook は stdin で JSON を受け取ります。session_id、transcript_path、cwd、hook_event_name などの共通フィールドに加え、イベント固有のフィールドが含まれます。たとえば Bash 呼び出しに対する PreToolUse hook では、tool_name と tool_input.command も渡されます。jq などの JSON パーサーで読み取れます。

#!/bin/bash
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")
echo "Claude wants to run: $cmd" >> ~/claude-commands.log
exit 0

06出力：終了コードと JSON

hook から Claude Code へ結果を返す方法は 2 つあります。

終了コード 0 は成功です。2 はブロッキングエラーで、ブロック可能なイベントではアクションが中止され、stderr の内容がその理由として扱われます。それ以外のコード（よく使われる 1 も含む）は非ブロッキングエラーとなり、アクションはそのまま実行され、hook エラーの通知が表示されます。hook でルールを強制したい場合は、1 ではなく 2 で終了してください。

stdout への JSON 出力 より細かく制御したい場合は、0 で終了し、JSON オブジェクトを 1 つ出力します。Claude を完全に停止する continue: false のように、どのイベントでも使えるフィールドもあります。一方、イベントごとに異なるフィールドもあり、Stop では decision: "block" と reason を使い、PreToolUse と PermissionRequest では hookSpecificOutput の中に判定を入れます。stdout にはそれ以外を出力しないでください。シェルプロファイルから余計な行が 1 行でも出力されると、Claude Code は JSON を読み取れなくなります。

07すべての hook イベント

Anthropic はイベントを随時追加しているため、最新の一覧や各イベントの入力フィールドはhooks リファレンスで確認してください。

08通知に関係するイベント

通知してほしい場面のほとんどは、次の 4 つのイベントでカバーできます。

• Stop：「Claude の処理が完了した」ことを知らせます。Stop hook ガイドを参照してください。
• Notification：「Claude が入力を待っている」ことを知らせます。permission_prompt や idle_prompt などの種類があります。Notification hook ガイドを参照してください。
• PermissionRequest：許可が必要になった瞬間に通知を受けたり、その場で応答したりできます。PermissionRequest ガイドを参照してください。
• AskUserQuestion ツールに対する PreToolUse：Claude の選択式の質問を確認したり回答したりできます。スマートフォンから質問に回答する方法を参照してください。

そのまま貼り付けて使えるデスクトップ向けの設定は、Claude Code の完了時に通知を受け取る方法から始めてください。

09Claude Code Notifier の位置づけ

Claude Code Notifier は、すべてこれらの hook の上に構築されています。無料のコマンドラインツール ccn は Mac、Windows、Linux で動作します。インストールすると ~/.claude/settings.json に 7 つの hook エントリ（いずれも ccn hook を実行）が追加され、元のファイルのバックアップが一度だけ作成されます。ccn はイベントごとに数ミリ秒だけ実行されてすぐに終了するため、常駐するプロセスはありません。

単体ではデスクトップ通知を表示します。iPhone または Android アプリとペアリングすると、同じ hook を通じて回答を送り返せます。許可の承認・拒否、質問への回答、Claude が止まった後の次の指示の送信などが可能です。本ツールは独立したプロダクトであり、Anthropic が提供しているものではありません。ログや lint だけが目的なら、自分で数行書くほうがシンプルです。詳しくはccn のページをご覧ください。

10よくある質問