Claude Code PostToolUse フックが動かない：ログ確認とデバッグの手順

PostToolUse フックにスクリプトを設定したのに、どうやら動いていない——そういう状況で最初に困るのが「どこを見ればエラーが分かるか」という点です。Claude Code のフックは失敗しても Claude の返答には影響が出ないため、無音で落ちていることがあります。この記事では設定の確認から自前ログの仕込み方、よくある失敗パターンと対処まで、順を追って説明します。

PostToolUse フックの設定と動作の概要

Claude Code の hooks は .claude/settings.json（プロジェクト単位）または ~/.claude/settings.json（グローバル）に記述します。

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

PostToolUse は Claude がツールの実行を終えた直後に呼ばれます。スクリプトには標準入力（stdin）経由で JSON が渡され、tool_name・tool_input・tool_response などのフィールドが含まれています（公式ドキュメント「Hooks」より）。

出力の扱いは次のとおりです。

stdout が表示されないことを知らないと、「echo で確認しているのに何も出ない」という状況になります。

まずスクリプトが呼ばれているかを確認する

原因を絞る前に、「そもそもスクリプトが起動しているか」を確認します。以下のようなログ専用の最小スクリプトを一時的に設定してください。

#!/bin/bash
# /tmp/hook-debug.log に実行の痕跡を残す
echo "$(date '+%Y-%m-%d %H:%M:%S') hook called" >> /tmp/hook-debug.log
cat >> /tmp/hook-debug.log   # stdin も捨てずに記録

スクリプトに実行権限を付与し、settings.json の command に絶対パスで指定します。

chmod +x /path/to/debug-hook.sh

Claude Code でファイルを編集したあとに /tmp/hook-debug.log が作られなければ、スクリプトが一切呼ばれていません。以下を順に確認します。

1. JSON の構文エラー — jq . ~/.claude/settings.json を実行してエラーが出ないか確認します。
2. matcher の不一致 — matcher は正規表現で、Claude が使うツール名（Write・Edit・Bash など）と照合されます。大文字小文字も含めて正確に書く必要があります。使ったツール名が不明なら "matcher": ".*" で全マッチにして確認します。
3. 実行権限の不足 — ls -l /path/to/your-script.sh で x ビットが付いているか確認します。

よくある失敗パターンと対処法

ログが出ても処理が途中で止まる場合は、以下のパターンを疑います。

PATH が通っていない

Claude Code が起動している環境の PATH は、通常のターミナルと異なることがあります。スクリプト内で python3・node・jq などをコマンド名だけで呼ぶと「コマンドが見つからない」エラーになります。

#!/bin/bash
# スクリプト冒頭で PATH を明示する
export PATH="/usr/local/bin:/usr/bin:/bin:$PATH"

which python3 などで事前に確認したフルパスをそのまま使う方法が確実です。

stdin を読まずに終了している

フックに渡された JSON は stdin から届きます。スクリプトが stdin を読まないと、パイプが詰まって予期しない挙動が起きることがあります。stdin は必ず読み取るか捨ててください。

Bash の場合：

INPUT=$(cat)   # stdin を変数に取る
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
echo "$(date) tool=$TOOL_NAME" >> /tmp/hook-debug.log

Python の場合：

#!/usr/bin/env python3
import sys, json, datetime

try:
    payload = json.load(sys.stdin)
except json.JSONDecodeError:
    payload = {}

tool_name = payload.get("tool_name", "unknown")
with open("/tmp/hook-debug.log", "a") as f:
    f.write(f"{datetime.datetime.now()} tool={tool_name}\n")

終了コードが意図せず非0になる

set -e を使っているスクリプトでは、途中のどこかのコマンドが失敗すると即座に非0で終了します。デバッグ中は set -e をコメントアウトし、エラーになりうる行に || true を付けて最後まで実行させ、原因箇所を特定します。

#!/bin/bash
# set -e    ← デバッグ中はコメントアウト
INPUT=$(cat)
jq -r '.tool_name' <<< "$INPUT" || true
echo "処理完了" >> /tmp/hook-debug.log

処理が重くてタイムアウトする

API コールやファイルの大量処理をフックの中で同期実行すると、Claude Code 側のタイムアウトに引っかかることがあります。具体的なタイムアウト値はバージョンによって変わる可能性があるため、公式ドキュメントの Hooks セクションを確認してください。

重い処理はバックグラウンドに逃がし、フック自体は素早く終わらせます。

#!/bin/bash
INPUT=$(cat)
# バックグラウンドで非同期実行
/path/to/heavy-script.sh <<< "$INPUT" &
exit 0

症状別チェックリスト

まとめ

PostToolUse フックのデバッグは、まず /tmp/hook-debug.log に一行書くだけの最小スクリプトで「呼ばれているか」を確認するところから始めます。呼ばれていなければ settings.json の JSON 構文・matcher・実行権限を順に確認します。呼ばれているが途中で止まるなら、stdin の読み取り・PATH・終了コードを疑います。

次の一手は、デバッグ用の最小スクリプトを settings.json に設定して、実際に Claude Code でファイルを編集し、/tmp/hook-debug.log の有無を確認することです。ここが通れば、あとは本来の処理（フォーマッタの起動・Slack 通知・差分ログの記録など）を組み込んでいくだけです。