hooks でアクションを自動化する

​

最初の hook をセットアップする

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

​

自動化できること

​

Claude が入力を必要としているときに通知を受け取る

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

osascript -e 'display notification "test"'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

notify-send 'Claude Code' 'test'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

編集後にコードを自動フォーマットする

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

​

保護されたファイルへの編集をブロックする

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
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

chmod +x .claude/hooks/protect-files.sh

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

​

コンテキスト圧縮後にコンテキストを再注入する

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

​

設定の変更を監査する

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

ディレクトリやファイルが変更されたときに環境を再読み込みする

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

​

特定の権限プロンプトを自動承認する

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

​

hooks の仕組み

• "type": "http"：イベントデータを URL に POST します。HTTP hooks を参照してください。
• "type": "mcp_tool"：設定済みの MCP サーバー上のツールを呼び出します。MCP tool hooks を参照してください。
• "type": "prompt"：シングルターン LLM 評価。プロンプトベースの hooks を参照してください。
• "type": "agent"：ツールアクセス付きマルチターン検証。エージェント hooks は実験的であり、変更される可能性があります。エージェントベースの hooks を参照してください。

​

複数の hooks からの結果を組み合わせる

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

​

入力を読み取り、出力を返す

​

Hook 入力

• hook_event_name：hook をトリガーしたイベント
• tool_name：Claude が使用しようとしているツール
• tool_input：Claude がツールに渡した引数。Bash の場合、その command フィールドはシェルコマンドを保持します。

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

​

Hook 出力

#!/bin/bash
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  # stderr は Claude のフィードバックになります
  exit 2 # exit 2 = アクションをブロック
fi

exit 0  # exit 0 = 決定なし。通常の権限フローが適用されます

• 終了 0：PreToolUse hook から 0 で終了しても、ツール呼び出しは通常の 権限フロー を経由します。終了 0 はツール呼び出しを承認しないためです。UserPromptSubmit、UserPromptExpansion、SessionStart、および PostModelSwitch hooks の場合、Claude Code は プレーンテキストとして扱う stdout を Claude のコンテキストに追加します。
• 終了 2：stderr に理由を書き込みます。イベントによって、Claude がそれをフィードバックとして受け取って調整できる場合、ユーザーに表示される場合、ConfigChange や Elicitation のようにメッセージが表示されない場合があります。一部のイベントはブロックできません：SessionStart などの場合、終了 2 は stderr をユーザーに表示し、実行は続行されます。イベントごとの終了コード 2 の動作 で完全なリストを参照してください。
• その他の終了コード：WorktreeCreate がゼロ以外の終了で失敗するなどのイベントごとの例外については、終了コード出力 を参照してください。その他のイベントでは、そのフックが失敗時にアクションをブロックするものでない限り、フックが stdout に出力した内容から該当するケースを確認してください：
  • スキーマ検証に合格した解析済みオブジェクト：Claude Code は終了コードを無視し、JSON だけが結果を決定し、フックはエラーとして報告されません。
  • スキーマ検証に失敗した解析済みオブジェクト、または Claude Code が JSON として解析しようとする ものの有効な JSON ではない stdout：アクションはブロックしないエラーとして続行されます。検証またはパースのメッセージについては、<hook name> hook error 通知を確認してください。
  • Claude Code が プレーンテキストとして扱う stdout、または空の stdout：アクションはブロックしないエラーとして続行されます。トランスクリプトには <hook name> hook error 通知が表示され、続いて Failed with non-blocking status code: を先頭に付けた stderr の最初の行が表示されます。stderr 全体をキャプチャするには、claude --debug を使用するか、セッション中に /debug を実行して デバッグログ を有効にしてください。

​

構造化 JSON 出力

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• ネットワークパス からの読み取り
• requiresUserInteraction とマークされた MCP ツール
• その設定が Claude Code に届くセッションで 組織が ask に設定した コネクタツール plan モードでの "allow" の動作については、plan モードでのフックによる承認 を参照してください。

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

​

マッチャーで hooks をフィルタリングする

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

if フィールドでツール名と引数でフィルタリングする

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

​

hook の場所を設定する

​

プロンプトベースの hooks

• "ok": true：アクションが続行されます
• "ok": false：何が起こるかはイベントによって異なります：
  • Stop および SubagentStop：reason は Claude にフィードバックとして返されるため、作業を続けます。ただし、応答が "impossible": true も設定している場合は、その条件が決して満たされることのない条件として印付けられ、その場合 Claude Code は停止を許可してターンが終了します
  • PreToolUse：ツール呼び出しが拒否されます。デフォルトではターンが終了し、拒否の reason は警告行としてチャットに表示されます。フックに continueOnBlock: true を設定すると、代わりに reason を Claude にツールエラーとして返すため、調整して続行できます
  • PostToolUse：デフォルトではターンが終了し、reason は警告行としてチャットに表示されます。continueOnBlock: true を設定すると、reason を Claude にフィードバックとして返し、代わりにターンを続行します
  • PostToolBatch、UserPromptSubmit、および UserPromptExpansion：ターンが終了し、reason は警告行としてチャットに表示されます

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

​

エージェントベースの hooks

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

• 2xx ステータス：ツール呼び出しをブロックするには、ボディで適切な hookSpecificOutput フィールドを返します。
• その他のステータス、またはリクエストが失敗した場合：Claude Code は ノンブロッキングエラー を報告し、アクションを続行させます。失敗したエンドポイントでアクションをブロックするには、フックに onFailure: "block" を設定します。

​

制限事項とトラブルシューティング

​

制限事項

• コマンドフックは stdout、stderr、終了コードのみを介して通信します。/ コマンドやツール呼び出しをトリガーすることはできません。additionalContext を介して返されたテキストはシステムリマインダーとして挿入され、Claude はこれをプレーンテキストとして読み取ります。HTTP フックは代わりにレスポンスボディを介して通信します。
• フックのタイムアウトはタイプによって異なります。フックごとに timeout フィールド（秒単位）で上書きできます。
  • command、http、mcp_tool：10 分。Claude Code は、UserPromptSubmit、PreModelSwitch、PostModelSwitch フックではこのデフォルトを 30 秒に、MessageDisplay では 10 秒に引き下げます。
  • prompt：30 秒。
  • agent：60 秒。
  • SessionEnd フックは、タイプを問わず 1.5 秒の割り当て時間を共有します。設定でフックごとにより長い timeout を指定している場合、Claude Code は最大 60 秒までそれに合わせて割り当て時間を引き上げます。
• PostToolUse フックは、ツールがすでに実行されているため、アクションを元に戻すことはできません。
• PermissionRequest フックは、Claude Code がユーザーに権限を求めようとするとき、またはプロンプトを表示できない呼び出しをそのままでは自動的に拒否するときに発火します。-p フラグを使用した非対話モードでも、dontAsk モード以外では引き続き実行され、どのフックも判断せず、他に応答できるものもない呼び出しは拒否されます。
• Stop フックは、タスクの完了時だけでなく、Claude が応答を終えるたびに発火します。ユーザーによる中断では発火しません。API エラーの場合は代わりに StopFailure が発火します。
• 複数の PreToolUse フックがツールの引数を書き換えるために updatedInput を返す場合、最後に完了したものが有効になります。フックは並列に実行されるため、順序は非決定的です。同じツールの入力を複数のフックで変更することは避けてください。

​

フックと権限モード

• "allow" に対して引き続き有効なもの："allow" を返すフックは、設定の拒否ルールを回避することはできず、以下のプロンプトを抑制することもできません。
  • ネットワークパスからの読み取り
  • requiresUserInteraction が指定された MCP ツール
  • その設定が Claude Code に反映されるセッションにおいて、組織が ask に設定したコネクタツール

• すべての権限モードでの "deny"：permissionDecision: "deny" を返すフックは、bypassPermissions モードや --dangerously-skip-permissions を使用している場合でもツールをブロックします。PreToolUse フックは、dontAsk を含むすべての権限モードにおいて、権限モードのチェックより前に発火します。これにより、ユーザーが権限モードを変更しても回避できないポリシーを適用できます。

​

フックが発火しない

• /hooks を実行し、フックが正しいイベントの下に表示されていることを確認します
• matcher のパターンがツール名と正確に一致していることを確認します。matcher は大文字と小文字を区別します
• 正しいイベントタイプをトリガーしていることを確認します。PreToolUse はツールの実行前に、PostToolUse は実行後に発火します。PermissionRequest フックは Claude Code がユーザーに権限を求めようとするときに発火します。非対話の場合については制限事項を参照してください

​

出力にフックエラーが表示される

• スクリプトが予期せずゼロ以外のコードで終了しています。サンプルの JSON をパイプで渡して手動でテストします。
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  
• 「command not found」と表示される場合は、絶対パスまたは ${CLAUDE_PROJECT_DIR} を使用してスクリプトを参照します。シェルのクォートを完全に回避するには、"args": [] を追加して exec 形式に切り替えます。これにより、シェルを介さずにスクリプトが直接起動されます
• 「jq: command not found」と表示される場合は、jq をインストールするか、JSON の解析に Python/Node.js を使用します
• メッセージに blocking because Git Bash wasn't found が含まれる場合は、Windows 上で Claude Code が Git Bash を見つけられず、失敗またはタイムアウトしたフックがツール呼び出しをブロックしています。修正方法については Git Bash のない Windows で失敗したフックを参照してください
• 通知に JSON 検証メッセージが表示される場合、フックの stdout は JSON として解析されましたが、スキーマ検証に失敗しています。JSON 解析メッセージが表示される場合、stdout は JSON オブジェクトのように見えましたが、有効な JSON ではありませんでした。どちらも終了コード 0 の場合でも発生します。 解析の失敗を修正するには、文字列の連結ではなく jq などの JSON エンコーダーを使用してペイロードを組み立て、値に含まれる引用符やバックスラッシュがエスケープされるようにします。終了コードと JSON の組み合わせについては、リファレンスの終了コードの出力セクションで説明しています
• スクリプトがまったく実行されていない場合は、実行可能にします：chmod +x ./my-hook.sh

​

/hooks にフックが設定されていないと表示される

• ファイルの編集は通常自動的に反映されます。数秒経っても表示されない場合は、ファイルウォッチャーが変更を検出できなかった可能性があります。セッションを再起動して強制的に再読み込みしてください。
• JSON が有効であることを確認します。末尾のカンマやコメントは使用できません
• 設定ファイルが正しい場所にあることを確認します。プロジェクトのフックは .claude/settings.json、グローバルのフックは ~/.claude/settings.json です
• メニューに Only hooks from managed settings run here と表示される場合は、組織が allowManagedHooksOnly を設定しています。ユーザー、プロジェクト、ローカルの設定ファイル内のフックは実行されず、一覧にも表示されません

​

Stop フックがブロック上限に達する

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

​

フックの JSON が効果を持たない

• JSON の前に余分な出力がある：他の何かが先に stdout に書き込んでいます。通常はシェルプロファイル内の無条件の echo です。そのため出力が { で始まらなくなります。JSON の前に出力されるシェルプロファイルの出力を参照してください。
• フィールドの階層が間違っている：各フィールドの配置を JSON 出力の形式と比較してください。たとえば、permissionDecision はトップレベルではなく hookSpecificOutput の内側に配置する必要があります。フィールドの階層が間違っているを参照してください。

​

JSON の前に出力されるシェルプロファイルの出力

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# In ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

フィールドの階層が間違っている

​

フックの動作を確認する

• 成功：フックの JSON が systemMessage や Stop フックのフィードバックなどを表示しない限り、何も表示されません。
  • フックが実行されたことを確認するには、ファイルが再フォーマットされたなどの効果を確認します
• ブロッキングエラー：ほとんどのイベントでは、ブロックに伴うメッセージが表示されます（例：Blocked: rm commands are not allowed）。ConfigChange や Elicitation などの一部のイベントでは、メッセージは表示されません。メッセージの出どころについては終了コード 2 で説明しています。
• 非ブロッキングエラー：<hook name> hook error という通知と短い説明が表示されます。説明は、Failed with non-blocking status code: の後に続く stderr の最初の行や、JSON の検証メッセージまたは解析メッセージなどです。アクションは続行されています。

​

詳細を学ぶ

• Hooks リファレンス：完全なイベントスキーマ、JSON 出力形式、非同期 hooks、および MCP ツール hooks
• セキュリティに関する考慮事項：共有または本番環境に hooks をデプロイする前に確認してください
• Bash コマンドバリデーター例：完全なリファレンス実装