Lifecycle hook の exit 127 は hook 定義の実コマンドを再現して切り分ける
開発環境
トラブルシューティング
Codex
知識
運用
AI 開発ツールや CLI の lifecycle hook が exit 127 で失敗する場合、まず hook runner や本体アップデートの不具合と決めつけず、設定に書かれている実行コマンドと参照先ファイルを一次情報として確認する。
exit 127 は多くの shell で「コマンドまたは実行対象が見つからない」を示す。hook 設定が古いパスを指したまま、スクリプトだけ別ディレクトリへ移動・削除された場合、hook のイベントごとに同じエラーが繰り返し出る。特に複数ツール間で hook 設定を移行したあとや、未追跡のローカル設定が残っている場合は、リポジトリ側の最新設定とローカル設定がずれやすい。
切り分けでは、設定ファイルに残っている hook source、対象イベントと matcher、実行コマンド、参照先ファイルの存在、対象プロジェクトが trusted で project-local hook を読む状態かを順に見る。次に、hook runner を介さず同じ実行対象を直接起動して 127 が再現するか確認する。直接再現するなら hook 本体ではなく参照先 path や PATH の問題として扱う。直接成功するなら、hook 実行時の working directory、環境変数、PATH、trust 状態を疑う。
予防策は、hook 設定とスクリプトの配置を同じ移行単位で更新すること、削除した hook スクリプトへの参照が別の設定層に残っていないか確認すること、ローカル未追跡の設定も診断対象に入れること。