hooks.PreToolUse

変更前

フックの実行中は、スピナーにはフック名などが statusMessage で設定されていない限り表示されず、何が実行されているか分かりにくかった。特に SessionStart フックが完了するまでプロンプト送信は待たされ、途中で中断する手段もなかった。

変更後

SessionStart・UserPromptSubmit・PreToolUse・SessionEnd フックの実行中、スピナーにフックが動いていることと経過時間が表示されるようになった。さらに、SessionStart フックの完了待ちで停止しているプロンプトを Esc でキャンセルできるようになった。

ユーザーへの恩恵

どのフックが実行中かと経過時間が分かるようになり、遅い SessionStart フックで待たされた場合も Esc で即座にキャンセルできるようになる。

変更前

PermissionRequest や PreToolUse フックが無効な JSON を出力した際、バックグラウンドセッションはエラーメッセージを表示せずに待機し続けました。ユーザーはどのフックが失敗したのか、何が問題だったのかを知ることができませんでした。

変更後

claude agents の行に、どのフックが無効な回答を出力したのか、そしてスキーマエラーの内容が表示されるようになりました。これにより、バックグラウンドセッションの問題を特定しやすくなりました。

ユーザーへの恩恵

フックのエラー原因を即座に特定できるようになり、バックグラウンドセッションの待機状態を解消できます。

変更前

分散トレース（Tracing）を有効化している際、PreToolUse フックが介入して一時的に保留されたツール実行処理が、親の実行コンテキストから切り離され、独立した別のルートトレースとして記録されてしまっていました。このため、実行フローの依存関係を追跡するのが困難でした。

変更後

フック経由で遅延実行されるツールのスパンが、元の親ターン（claude_code.interaction）のコンテキストを正しく引き継ぎ、同一のトレースツリー内に子スパンとして一元的に記録されるようになります。

ユーザーへの恩恵

可観測性プラットフォーム側でトレースログを調査する際、フック処理されたイベントを1つの文脈としてスムーズに追跡できます。

変更前

オートモード(auto mode)では、フックがユーザーへの確認(ask)を求めた場合でも、分類器が安全だと判断するとプロンプトを出さずにサイレントで承認してしまうことがありました。フックによる明示的な制限が無視される場面がありました。

変更後

フックが「ask」を返した場合、オートモードであっても必ずユーザーにプロンプトを表示するように変更されました。分類器は拒否(deny)することはできますが、フックの要求を無視して勝手に承認することはできなくなります。

ユーザーへの恩恵

セキュリティや検証のために設定したフックによる確認要求が、オートモードでも確実に守られるようになる。

変更前

フックからツールの実行時間を把握することが難しく、どの操作に時間がかかっているかの正確な計測が困難でした。

変更後

フックへの入力データにミリ秒単位の duration_ms が追加され、ユーザーの承認待ち時間を除いた純粋な処理時間を取得できるようになりました。

ユーザーへの恩恵

独自のメトリクス収集や、処理の重いツール呼び出しの検知など、開発プロセスの分析と最適化がより精緻に行えるようになります。

変更前

フックを使ってAIに補足情報を与えていても、その直後のツール実行が一度失敗すると、せっかくの補足情報が消えてしまい、AIが状況を正しくリトライできないことがありました。

変更後

ツール実行の成否にかかわらず、フックによって注入されたコンテキストが正しく保持され、AIに共有され続けるようになりました。

ユーザーへの恩恵

失敗の原因をAIがフックの情報を元に深く理解し、より的確に再試行できるようになるため、エラーからの自己復旧率が高まります。

変更前

設定ファイルで特定のコマンドを「拒否(deny)」していても、フックの設定によってはユーザーに「確認(ask)」を求めてしまい、拒否ルールをバイパスできてしまう場合がありました。

変更後

「拒否」ルールが常に最優先されるようになり、フックによって承認待ちにダウングレードされることがなくなります。

ユーザーへの恩恵

セキュリティ設定の優先順位が明確になり、意図しないツールの実行をより確実に防止できます。

変更前

特定の条件でツール実行を拒否しようとしても、フックの出力形式や終了コードの組み合わせによってはブロック処理が正しく動作しない不具合がありました。

変更後

フックからのブロック指示が確実に処理され、セキュリティ上の制約やバリデーションが厳密に適用されます。

ユーザーへの恩恵

独自に作成したフックによる実行制限(破壊的なコマンドの禁止など)が意図通りに機能し、安全性が向上します。

変更前

PreToolUse フックが返せる判断は allow、deny、ask の3種類で、ツール実行を後から再開できる形で一時停止する手段がなかった。ヘッドレスモードでユーザー入力が必要になった場合、呼び出し側プロセスは中断されたセッションをツール呼び出しの状態のまま保持して再開する仕組みを持てなかった。

変更後

PreToolUse フックに、ツール実行を中断したままセッションを終了できる permissionDecision: 'defer' が追加される。ヘッドレスモードで defer が返されると stop_reason: 'tool_deferred' でプロセスが終了し、未実行のツール呼び出しがトランスクリプトに保持される。呼び出し側プロセスが claude -p --resume で再開すると、同じツール呼び出しに対して PreToolUse フックが再度評価される。

ユーザーへの恩恵

Agent SDK アプリやカスタム UI から Claude Code を呼び出す際、ツール呼び出しの時点でセッションを一時停止して自前のインターフェースで入力を収集し、-p --resume で中断箇所から再開できる。

変更前

Write/Edit/Read ツール実行時、PreToolUse/PostToolUse フックに渡される file_path が相対パスになることがあり、フックスクリプト側でパス判定が正しく動かないケースがあった。

変更後

Write/Edit/Read ツール実行時、PreToolUse/PostToolUse フックの入力の file_path が絶対パスとして渡されるようになった。

ユーザーへの恩恵

拡張後の file_path を前提にして書かれた公式ドキュメントやガイドのフックスクリプトが、意図どおりに動くようになる。

変更前

フック機能でファイルの変更を監視・処理する際、ファイルパスが相対パスで渡されることがあり、実行ディレクトリが異なると正しいファイルを特定できないリスクがありました。

変更後

常にルートからの絶対パスが渡されるようになり、どのディレクトリから実行しても確実に対象ファイルを処理できるようになりました。

ユーザーへの恩恵

自動フォーマットやバリデーションなどのフックの信頼性が高まり、複雑なプロジェクト構造でも誤作動の心配なく自動化を任せられます。

変更前

ヘッドレス(非対話)モードでの実行中、Claudeがユーザーに質問(AskUserQuestion)を投げると、外部から動的に回答を供給するスマートな方法が不足していました。

変更後

フック経由で質問への回答(updatedInput)を返せるようになったため、独自のUIや自動化スクリプトを介してClaudeの質問に回答できます。

ユーザーへの恩恵

CLIを直接操作できないCI/CD環境やカスタムアプリ経由の利用において、Claudeとの対話を自動化または外部UI化することが可能になります。

変更前

フック側で許可(allow)を出すと、エンタープライズの管理ポリシー等で定義された強力な拒否ルールすら上書きされてしまう脆弱な状態でした。

変更後

パーミッション評価順序が厳格化され、フックの出力に関わらず拒否ルールが常に優先されるようになりました。

ユーザーへの恩恵

組織レベルで設定したセキュリティポリシーが確実に適用されるため、安全にフック機能を活用できます。

変更前

Windows環境では、cmd.exeが使用されていたため、フック(PreToolUse、PostToolUse)がサイレントに失敗し、実行されない問題がありました。

変更後

Windows環境でhooks(PreToolUse、PostToolUse)がサイレントに失敗する問題が修正されました。Git Bashが使用されるようになり、フックが正しく実行されるようになりました。

ユーザーへの恩恵

Windows環境でのフック実行が安定し、Git Bashの利用によりPreToolUseやPostToolUseといった重要な自動化処理が正しく機能するようになりました。

変更前

ツール実行前のPreToolUseフックは、モデルに渡す追加情報を提供できませんでした。

変更後

PreToolUseフックは、ツールの実行前にモデルにadditionalContextとして追加情報を提供できるようになりました。

ユーザーへの恩恵

これにより、フックはツールの実行前にモデルに追加のコンテキストを提供できるようになり、よりインテリジェントな意思決定や、フックによるツール実行の制御が可能になります。

変更前

フックでツール入力を変更した場合、即座に実行を許可(allow)するか拒否(deny)するかの二択になり、変更後の内容をユーザーに確認させることができませんでした。

変更後

安全のために特定の引数を修正しつつ、「この内容で実行して良いですか？」というプロンプトをユーザーに表示する高度な制御が可能になりました。

ユーザーへの恩恵

不適切なコマンド引数を自動補正しながら最終判断は人間に委ねるという、安全性と柔軟性を両立した高度なガードレールを構築できます。