$ 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 に届いたかどうかは、送信本文の列で決まります。
| 目印 | 出し方 | 送信本文 | transcript | debugログ |
|---|---|---|---|---|
| OUT0 | exit 0、stdout に平文 | 0 | 2 | 1 |
| ERR0 | exit 0、stderr | 0 | 1 | 1 |
| ERR1 | exit 1、stderr | 0 | 1 | 1 |
| ERR2 | exit 2、stderr | 1 | 3 | 1 |
| OUT2 | exit 2、stdout に平文 | 0 | 0 | 1 |
| CTX | exit 0、hookSpecificOutput.additionalContext | 1 | 4 | 3 |
| CTXTOP | exit 0、トップレベルの additionalContext | 0 | 1 | 3 |
| BLOCK | exit 0、decision: "block" と reason | 1 | 3 | 4 |
| SYS | exit 0、systemMessage | 0 | 2 | 3 |
| PROF | exit 0、echo の後に JSON | 0 | 2 | 1 |
送信本文の列は、公式の “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_turns | Claude が受け取った文面(stream-json の user メッセージ) |
|---|---|---|---|
| nf | exit 2、stderr に No such file or directory | 1 | なし(そのまま終了) |
| plain | exit 2、stderr に別の文言 | 5 | Stop hook feedback: の後に [python3 /tmp/hooklab/bin/stop.py plain]: CANARY-STOPPLAIN src/app.ts is missing a test |
| json | exit 0、reason に No such file or directory | 5 | Stop 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 して確かめる