Claude Code hooksの出力がClaudeに届かない原因と確かめ方

$ cd /tmp/hooklab
$ for c in OUT0 ERR0 ERR1 ERR2 OUT2 CTX CTXTOP BLOCK SYS PROF; do
    printf '%-7s %s\n' $c $(cat bodies/*.request.json | grep -o "CANARY-$c\b" | wc -l)
  done
OUT0    0
ERR0    0
ERR1    0
ERR2    1
OUT2    0
CTX     1
CTXTOP  0
BLOCK   1
SYS     0
PROF    0

PostToolUse フックに10通りの書き方で目印の文字列を出させ、Claude Code v2.1.329 が API に送ったリクエスト本文を grep した結果です。Claude まで届いたのは ERR2・CTX・BLOCK の3通りだけで、残りの7通りは debug ログに記録されていても、モデルには1文字も渡っていません。lint の警告を exit 0 の stderr で返すフックなら、その警告は Claude に1件も届いていません。

目次

PostToolUseフックの出力10通りを1回のBash呼び出しに当てる

仕様は公式の Hooks reference と、ガイドの Automate actions with hooks で確認しました。どちらも2026年11月21日時点の版で、記事中の英文は原文から引いています。

目印を出し分けるhook.sh

引数で出し方を切り替えるだけのスクリプトです。stdin に来るフック入力は使わないので読み捨てます。

#!/bin/sh
cat > /dev/null
case "$1" in
  out0)   echo "CANARY-OUT0"; exit 0 ;;
  err0)   echo "CANARY-ERR0" >&2; exit 0 ;;
  err1)   echo "CANARY-ERR1" >&2; exit 1 ;;
  err2)   echo "CANARY-ERR2" >&2; exit 2 ;;
  out2)   echo "CANARY-OUT2"; exit 2 ;;
  ctx)    echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"CANARY-CTX"}}'; exit 0 ;;
  ctxtop) echo '{"additionalContext":"CANARY-CTXTOP"}'; exit 0 ;;
  block)  echo '{"decision":"block","reason":"CANARY-BLOCK"}'; exit 0 ;;
  sys)    echo '{"systemMessage":"CANARY-SYS"}'; exit 0 ;;
  prof)   echo "Shell ready"; echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"CANARY-PROF"}}'; exit 0 ;;
esac

公式ガイドの “Hook error in output” 節にならい、サンプルの JSON を流して終了コードを見ておきます。

$ echo '{}' | /tmp/hooklab/bin/hook.sh err2; echo "exit=$?"
CANARY-ERR2
exit=2

prof は、シェルのプロファイルが起動時に1行出してしまう状況を真似ています。

settings.jsonに10本登録して1回で流す

matcher を Bash にした PostToolUse に、引数違いの10本を並べます。下は10本のうち3本の抜粋です。

{
 "hooks": {
  "PostToolUse": [
   {
    "matcher": "Bash",
    "hooks": [
     {"type": "command", "command": "/tmp/hooklab/bin/hook.sh out0"},
     {"type": "command", "command": "/tmp/hooklab/bin/hook.sh err0"},
     {"type": "command", "command": "/tmp/hooklab/bin/hook.sh prof"}
    ]
   }
  ]
 }
}

実行は claude -p の1回だけです。--setting-sources project でユーザー設定のフックを読まないようにして、--settings で渡した10本だけが動く状態にしました。

cd /tmp/hooklab/proj
CLAUDE_CODE_ENABLE_TELEMETRY=1 OTEL_LOGS_EXPORTER=none OTEL_METRICS_EXPORTER=none \
OTEL_LOG_RAW_API_BODIES=file:/tmp/hooklab/bodies \
claude -p "Run this Bash command exactly once: echo probe . After it finishes, reply with only the word DONE." \
  --model haiku --setting-sources project --settings /tmp/hooklab/settings-all.json \
  --permission-mode default --allowedTools "Bash(echo probe)" --max-turns 4 \
  --output-format stream-json --verbose --include-hook-events \
  --debug-file /tmp/hooklab/debug.log < /dev/null > /tmp/hooklab/run.jsonl

tail -1 /tmp/hooklab/run.jsonl | jq -c '{subtype, num_turns, total_cost_usd, duration_ms}'
{"subtype":"success","num_turns":2,"total_cost_usd":0.00228916,"duration_ms":3018}

モデルは haiku で、費用は $0.0023、所要は 3.0秒でした。10本のフックは、debug ログ上どれも 8〜11ms で終わっています。

送信本文・transcript・debugログに残った回数

同じ目印を3か所で数えました。Claude に届いたかどうかは、送信本文の列で決まります。

目印出し方送信本文transcriptdebugログ
OUT0exit 0、stdout に平文021
ERR0exit 0、stderr011
ERR1exit 1、stderr011
ERR2exit 2、stderr131
OUT2exit 2、stdout に平文001
CTXexit 0、hookSpecificOutput.additionalContext143
CTXTOPexit 0、トップレベルの additionalContext013
BLOCKexit 0、decision: "block" と reason134
SYSexit 0、systemMessage023
PROFexit 0、echo の後に JSON021

送信本文の列は、公式の “Exit code output” 節の記述とすべて一致しました。transcript と debug ログには届かなかった出力も残っている点は、最後の節で扱います。

Claudeが読む文面はtool_resultの直後に入る

$ req=$(tail -1 bodies/index.jsonl | jq -r .request_file)
$ jq -r '.messages[] | "\(.role): \(.content[0].type)"' "bodies/$req"
user: tool_result
system: text
$ jq -r '.messages[1].content[0].text' "bodies/$req" | sed -n 1,8p
PostToolUse:Bash hook blocking error from command: "/tmp/hooklab/bin/hook.sh err2": [/tmp/hooklab/bin/hook.sh err2]: CANARY-ERR2


PostToolUse:Bash hook additional context: CANARY-CTX

PostToolUse:Bash hook blocking error from command: "/tmp/hooklab/bin/hook.sh block": CANARY-BLOCK

PostToolUse:Bash hook blocking error from command: "/tmp/hooklab/bin/hook.sh out2": [/tmp/hooklab/bin/hook.sh out2]: No stderr output

フックの文面はsystemのテキスト1件にまとまる

ツール実行後に送られた2回目のリクエストでは、messages が2件でした。1件目は echo probe の tool_result で、中身は probe のままです。2件目は role が system のテキストで、Claude 向けのフック出力はすべてこの1件にまとめて入っていました。公式の “Add context for Claude” 節が、PostToolUse の additionalContext の位置を “next to the tool result” と書いているとおりです。

blocking error の行にはフックのコマンドが付くので、フックを何本並べても Claude はどれが止めたのかを区別できます。additionalContext の行にはコマンドが付きません。

decision:blockもblocking errorとして届く

PostToolUse の decision: "block" について、公式の “PostToolUse decision control” 表は “"block" adds the reason next to the tool result” と説明しています。ツールはもう実行済みなので、止める対象はありません。それでも Claude が受け取る見出しは、exit 2 と同じ hook blocking error from command でした。debug ログにも returned permissionDecision: deny (reason: CANARY-BLOCK) と残ります。

警告として伝えたいだけなら additionalContext を使います。見出しが hook additional context になり、ツールを止めたような文面になりません。

exit 2でstdoutに書くと「No stderr output」になる

OUT2 は exit 2 で、メッセージを stdout にだけ書いたケースです。Claude には No stderr output の1行しか届かず、フックが何かを止めたことは伝わっても、理由は伝わりません。

$ grep -F 'status code 2\nstdout' debug.log | cut -d' ' -f2-
[ERROR] "Hook PostToolUse:Bash (PostToolUse) error: status code 2\nstdout:\nCANARY-OUT2"

debug ログには中身が残るので、ログだけを見ていると気づけません。echo に >&2 を付け忘れた exit 2 のフックは、この形になります。

成功扱いで消える出力と、debugログの手がかり

困るのは、届かない出力の多くを Claude Code が失敗として扱わないことです。OUT2 を除く6通りのうち、debug ログに ERROR で残るのは exit 1 の ERR1 だけで、残りの5通りは success と記録されました。claude -p も終了コード 0 で終わります。

exit 0のstderr、exit 1、systemMessageは人間向け

exit 0 の stderr については、公式の “Exit code output” 節に一文で書かれています。

Claude never sees stderr from a hook that exits 0.

exit 1 の ERR1 は non-blocking error として扱われ、transcript に Failed with non-blocking status code: CANARY-ERR1 が残るだけでした。公式によると、PreToolUse などでは対話画面に <hook name> hook error の通知が出ます。サジェストにも出てくる「posttooluse hook error」の通知が画面に出ていても、exit 1 なら Claude には何も届いていません。systemMessage の説明は “Warning message shown to the user.” で、stream-json では次の行になります。

$ jq -c 'select(.subtype=="informational")|{subtype,content}' run.jsonl
{"subtype":"informational","content":"PostToolUse:Bash says: CANARY-SYS"}

lint の警告を返すフックがこの3つのどれかで書かれているなら、書き換えが要ります。

# NG: exit 0 の stderr は Claude に届かない
file=$(jq -r '.tool_input.file_path')
ruff check "$file" >&2
exit 0
# OK: 警告を additionalContext に入れて exit 0
file=$(jq -r '.tool_input.file_path')
out=$(ruff check --output-format concise "$file" 2>&1) && exit 0
jq -nc --arg ctx "$out" \
  '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $ctx}}'
exit 0

OK 版を手で動かすと、ruff 0.17.6 の指摘が JSON の1行になります。

$ echo '{"tool_input":{"file_path":"bad.py"}}' | ../bin/lint-ok.sh
{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"bad.py:1:8: F401 [*] `os` imported but unused\nFound 1 error.\n[*] 1 fixable with `--fix`."}}

matcher を Write|Edit にして2本を claude -p で比べると、送信本文に F401 が入ったのは OK 版だけでした(NG 版 0件、OK 版 1件)。OK 版では haiku が返答で “the import block is unsorted (I001) and os is imported but unused (F401)” と警告に触れています。I001 は、Claude が書いたファイルの import 直後に空行が無いために出たものです。NG 版の返答は警告に一言も触れていません。

公式は exit 2 で返す方法も “To surface a warning to Claude from a PostToolUse or PostToolUseFailure hook, exit 2 instead” と書いています。ただ exit 2 だと、前の節のとおり見出しが blocking error になります。編集直後の型エラーを返すだけなら、pyright-lsp プラグインを試した記事のとおり、LSP 側が会話へ自動で入れる方法もあります。

トップレベルのadditionalContextは黙って捨てられる

CTXTOP は additionalContext を hookSpecificOutput に入れずに返したケースです。公式ガイドには “if you place it at the top level of the JSON, Claude Code silently ignores it.” とあり、transcript にもエラーは残りません。手がかりは debug ログの1行だけです。

$ grep -F "unrecognized keys" debug.log | cut -d' ' -f2-
[DEBUG] Hook JSON output had unrecognized keys (ignored): additionalContext. Did you mean hookSpecificOutput.additionalContext (with a hookEventName)?

メッセージにあるとおり、hookSpecificOutput の中には hookEventName も必要です。

echoが先に出るとJSONは平文として読まれる

PROF は JSON の前に Shell ready を1行出したケースです。stdout が { で始まらないため、Claude Code は全体を平文として読みます。PostToolUse の平文 stdout は Claude に渡らないので、JSON の中身ごと消えました。公式ガイドの “Hook JSON has no effect” 節も、シェルのプロファイルの echo を原因に挙げています。

$ grep -A1 -F "hook.sh prof] finished" debug.log | cut -d' ' -f2-
[DEBUG] Hooks: PostToolUse:Bash [/tmp/hooklab/bin/hook.sh prof] finished with status 0 (10ms)
[DEBUG] Hook output does not start with {, treating as plain text

この行は OUT0 や ERR0 でも出るので、それだけで異常とは言えません。JSON を返すつもりのフックでこの行が出ていたら、stdout に余計な出力が混ざっています。

1万字を超えるadditionalContextはファイルに逃がされる

Claudeに届くのはパスと先頭2,000字

公式の “JSON output” 節は、additionalContext・systemMessage・平文の stdout について “are capped at 10,000 characters” としています。12,028字の additionalContext を返すと、Claude への文面は次のように置き換わりました(ホームディレクトリは ~ に、x の連続は省略して書いています)。

PostToolUse:Bash hook additional context: <persisted-output>
Output too large (11.7KB). Full output saved to: ~/.claude/projects/-private-tmp-hooklab-proj/10cd8e66-7e2b-420e-afbf-99c4ea3aeef2/tool-results/hook-toolu_01Uf4PyhsYc8sxPz3isE277Q-PostToolUse-6b7043be140985c4940f85fa3c3bf555-additionalContext.txt

Preview (first 2KB):
CANARY-BIGHEADxxxx(x が 1,986字続く)
...
</persisted-output>

先頭の目印は届き、末尾の目印は届いていません。公式は “Claude Code doesn’t ask Claude to read the file” と書いていて、保存されたファイルを読むかどうかは Claude 次第です。テストの失敗一覧を返すなら、落ちたテスト名を先頭2,000字に寄せます。

exit 2のstderrは12,028字でも切られなかった

同じ長さを exit 2 の stderr で返すと、先頭と末尾の目印がどちらも届きました。公式の上限の対象に stderr は挙がっておらず、v2.1.329 の実測でも切られていません。長いログを丸ごと stderr に流すと、その分だけ毎回コンテキストを使います。

Stopフックのexit 2は、stderrの文言しだいで素通りする

Stop フックの decision: "block" と stop_hook_active の基本は、Hooks の5つの型をまとめた記事に書きました。ここでは exit 2 の例外だけを扱います。Stop フックを書いたのに会話がそのまま終わる、サジェストで言う「stop hook not working」の症状は、この例外でも起きます。

No such file or directoryを含むと1ターンで終わる

公式の “Exit code output” 節には、Stop・SubagentStop・TaskCompleted などにだけ効く規則があります。

when your hook exits 2 with nothing on stdout and its stderr says a file is missing, such as No such file or directory, Claude Code treats the run as a non-blocking error.

「テスト対象のファイルが無い」と Claude に伝える Stop フックは、この文言をそのまま書きがちです。3通りを用意して比べました。2回目の Stop では stop_hook_active を見て抜けるので、ループはしません。

import json, sys
d = json.load(sys.stdin)
if d.get("stop_hook_active"):
    sys.exit(0)
mode = sys.argv[1]
if mode == "nf":
    sys.stderr.write("CANARY-STOPNF src/app.ts: No such file or directory\n"); sys.exit(2)
if mode == "plain":
    sys.stderr.write("CANARY-STOPPLAIN src/app.ts is missing a test\n"); sys.exit(2)
if mode == "json":
    print(json.dumps({"decision": "block", "reason": "CANARY-STOPJSON src/app.ts: No such file or directory"})); sys.exit(0)

プロンプトは “Reply with only the word DONE.”、--max-turns 4 で各1回流した結果です。

モード出し方num_turnsClaude が受け取った文面(stream-json の user メッセージ)
nfexit 2、stderr に No such file or directory1なし(そのまま終了)
plainexit 2、stderr に別の文言5Stop hook feedback: の後に [python3 /tmp/hooklab/bin/stop.py plain]: CANARY-STOPPLAIN src/app.ts is missing a test
jsonexit 0、reason に No such file or directory5Stop hook feedback: の後に CANARY-STOPJSON src/app.ts: No such file or directory

plain と json では、haiku が src/app.ts を探して ls を始め、--max-turns 4 の上限で止まっています。nf のほうは debug ログに Hook Stop (Stop) error: status code 2 が ERROR で残るだけで、claude -p の終了コードは 0 でした。

ファイル名を含む理由はJSONのreasonで返す

例外の条件は、exit 2 で stdout が空のときです。同じ文言でも decision: "block" の reason で返すと続行しました。

ファイル名やコマンドのエラー文を理由に入れる Stop フックは、JSON で返しておけば文言に左右されません。

届いたかどうかは送信本文で確かめる

OTEL_LOG_RAW_API_BODIES=file:で本文をファイルに残す

公式の Monitoring ページにある OTEL_LOG_RAW_API_BODIES を file:<dir> で指定すると、API に送ったリクエストと受け取ったレスポンスが1回ずつ JSON ファイルで残ります。CLAUDE_CODE_ENABLE_TELEMETRY=1 と一緒に指定すれば、OTLP の受け口を立てなくても、OTEL_LOGS_EXPORTER=none のままファイルが書かれました。

$ ls -l bodies | awk 'NR>1{print $5, $9}'
13581 79de8147-b772-4a41-bd78-35b129d6cebf.request.json
58949 aab86bb9-9297-4f7e-9a31-ed1bfbb66d9d.request.json
822 index.jsonl
1051 req_011ChFyJhBaCDU2KCaP3Unej.response.json
2816 req_011ChFyJmQpp3XZRwMfxTaLm.response.json

1回目のリクエストは 58,949バイト、ツール実行後の2回目は 13,581バイトでした。どのファイルが何回目かは、index.jsonl の request_file で引けます(v2.1.274 以降)。公式の説明に “Bodies include the entire conversation history” とあるとおり、システムプロンプトも丸ごと入るので、確認が済んだらディレクトリごと消します。

transcriptのattachmentは届いたかどうかと関係なく残る

transcript の ~/.claude/projects/-private-tmp-hooklab-proj/<session-id>.jsonl には、10本それぞれの結果が attachment として残っていました。最初の表で transcript の列が0でない行が多いのはこのためで、目印が grep で見つかっても、Claude が読んだ証拠にはなりません。

$ grep -o '"attachment":{"type":"hook_[a-z_]*"' ~/.claude/projects/-private-tmp-hooklab-proj/bd6ee91e-ce5c-4be8-a1d8-d7a7a54d7631.jsonl | sort | uniq -c
   1 "attachment":{"type":"hook_additional_context"
   3 "attachment":{"type":"hook_blocking_error"
   1 "attachment":{"type":"hook_non_blocking_error"
   6 "attachment":{"type":"hook_success"
   1 "attachment":{"type":"hook_system_message"

今回、送信本文に入っていたのは hook_blocking_error と hook_additional_context の中身だけでした。hook_success・hook_non_blocking_error・hook_system_message の中身は、送信本文のどこにもありません。本文を残せない環境では、attachment の type が hook_blocking_error か hook_additional_context かを見れば、今回の送信本文と同じ判定になります。

–include-hook-eventsで見えるのはフックが出した側

stream-json に --include-hook-events を付けると、フック1本ごとに hook_response の行が出ます。

$ jq -c 'select(.subtype=="hook_response" and .exit_code==1) | {subtype, hook_name, exit_code, outcome, stdout, stderr}' run.jsonl
{"subtype":"hook_response","hook_name":"PostToolUse:Bash","exit_code":1,"outcome":"error","stdout":"","stderr":"CANARY-ERR1\n"}

この行で分かるのは、フックが何を出して何番で終わったかまでです。Claude Code がその出力を Claude に回したかは書かれていないので、CI でフックの終了コードを検査する用途に向いています。

まとめ

  • Claude Code v2.1.329 の PostToolUse で Claude に届いたのは、exit 2 の stderr、hookSpecificOutput.additionalContext、decision: "block" の reason の3通り
  • exit 0 の stderr、exit 1、systemMessage、平文の stdout、トップレベルの additionalContext、echo の後の JSON は届かず、エラーにもならない
  • 警告を返すなら additionalContext。exit 2 と decision:block は blocking error の見出しで届き、exit 2 の stdout は No stderr output に置き換わる
  • additionalContext は1万字を超えるとパスと先頭2,000字に置き換わる。exit 2 の stderr は12,028字でも全文が届いた
  • Stop の exit 2 は、stdout が空で stderr に No such file or directory があると素通りする。理由は JSON の reason で返す
  • 届いたかどうかは transcript ではなく、OTEL_LOG_RAW_API_BODIES=file:<dir> で残した送信本文を grep して確かめる
よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!
目次