Claude Code ガイド

Appearance

フックエラーのトランスクリプトへのstderrの最初の行の表示改善 ​

原文（日本語に翻訳） ​

トランスクリプト内のフックエラーを改善し、--debug なしで自己診断できるよう stderr の最初の行を含めるようになりました。

原文（英語） ​

Improved hook errors in the transcript to include the first line of stderr for self-diagnosis without --debug

概要 ​

Claude Code のフックでエラーが発生した場合、これまでトランスクリプトにはエラーの詳細が表示されず、原因を調べるには --debug フラグを使った再実行が必要でした。今回の改善により、フックエラー発生時にトランスクリプト上で stderr の最初の行が表示されるようになり、デバッグなしで素早くエラーの原因を把握できます。

基本的な使い方 ​

フックが失敗した場合、トランスクリプトには自動的に stderr の最初の行が表示されます。特別な設定は不要です。

bash
# フックが失敗した場合のトランスクリプト表示例（改善後）
# Hook failed: pre-edit
# Error: permission denied: /protected/file.txt  ← stderr の最初の行が表示される

# 改善前は以下のように詳細なし
# Hook failed: pre-edit

実践例 ​

フックスクリプトのデバッグを迅速化する ​

フックが失敗したとき、原因をすぐに確認できるようになります。

bash
# フックスクリプトの例 (~/.claude/hooks/pre-edit.sh)
#!/bin/bash
if [ ! -w "$1" ]; then
  echo "Error: File $1 is not writable" >&2
  exit 1
fi

# 改善前: エラーが出ても原因不明
# Hook failed: pre-edit

# 改善後: stderr の最初の行が表示される
# Hook failed: pre-edit
# Error: File /protected/config.json is not writable

設定ミスによるフックエラーの診断 ​

フックスクリプトのパスや実行権限の設定ミスなども、トランスクリプトから即座に確認できます。

bash
# フックが見つからない場合の表示例
# Hook failed: post-write
# bash: /usr/local/bin/my-hook.sh: No such file or directory

# 実行権限がない場合
# Hook failed: pre-read
# bash: /hooks/validate.sh: Permission denied

外部コマンドの失敗を診断する ​

フックスクリプトが外部コマンドを呼び出して失敗した場合も、その原因がトランスクリプトに表示されます。

bash
# フックスクリプト内でデータベース接続が失敗した場合
#!/bin/bash
psql -c "SELECT 1" 2>&1 | head -1 >&2
exit 1

# トランスクリプトに表示される:
# Hook failed: pre-commit
# psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed

--debug との使い分け ​

通常のエラー診断には改善されたトランスクリプト表示を活用し、詳細な調査が必要な場合のみ --debug を使用します。

bash
# 通常: トランスクリプトの stderr 最初の行で原因を把握
claude
# → Hook failed: validate-branch
# → Error: Branch name must start with 'feature/' or 'bugfix/'

# 詳細調査が必要な場合のみ --debug を使用
claude --debug
# → フックの全ての出力、実行時間などの詳細情報

注意点 ​

  • 表示されるのは stderr の最初の行のみです。詳細なエラー情報が必要な場合は --debug フラグを使用してください。
  • フックスクリプトで重要なエラーメッセージを最初の行に出力するよう設計することで、この機能を最大限に活用できます。
  • stderr に何も出力しないフックエラーの場合、エラーの詳細は表示されません。
  • セキュリティ上の機密情報をエラーメッセージの最初の行に含めないよう注意してください。

関連情報 ​