settings.json

hooks.PreToolUse

型array

ツールの呼び出し前に実行されるフック。

使い方・用途

  • 破壊的なコマンドの実行を事前に検知してブロックしたり、AI にツール実行前の追加コンテキストを提供して意思決定を支援したりします。
  • ヘッドレス環境において AI からの質問(AskUserQuestion)に自動回答するミドルウェアとしても活用可能です。
英語原文(公式ドキュメントより)

Hooks that run before tool calls

関連ドキュメント

関連する変更履歴

v2.1.304(1件)

Fixed
同じツール呼び出しに対する Agent SDK のコールバックフックがタイムアウトした際に、PreToolUse フックの拒否理由がタイムアウトエラーで置き換えられる問題を修正した
英語原文を表示
Fixed a PreToolUse hook's deny reason being replaced by a timeout error when an Agent SDK callback hook on the same tool call timed out

v2.1.301(1件)

Fixed
Edit または Write を対象とする PreToolUse フックが設定されている場合にアーティファクトの更新が拒否される問題を修正した。publish 呼び出し内でファイルを変更する代わりに、Claude がファイルを編集してから再公開するようになった。
英語原文を表示
Fixed artifact updates being refused where a PreToolUse hook covers Edit or Write; Claude now edits the file and then republishes instead of changing it in the publish call

関連ドキュメント

v2.1.300(1件)

Changed
フックを変更した: PreToolUse および PermissionRequest フックからの updatedInput が Claude 自身の入力と同様に検証されるようになり、未知のキーは破棄され、ツールが拒否する入力はその呼び出しを拒否する
英語原文を表示
Changed hooks: updatedInput from PreToolUse and PermissionRequest hooks is now validated like Claude's own input: unknown keys are dropped, and input the tool rejects denies the call

変更後

フックが返す updatedInput が、Claude 本体のツール入力と同じ検証を受けるようになり、不正な引数が権限評価前に弾かれて、予期しない入力でツールが実行されるのを防げる。

v2.1.299(2件)

Fixed
プランモードで、PreToolUse フックや mod の tool.check フックが許可した書き込み(MCP ツール、ファイル、シェルコマンド)が実行されてしまう問題を修正した
英語原文を表示
Fixed plan mode running a write (an MCP tool's, a file's, a shell command's) that a PreToolUse hook or a mod's tool.check hook allowed

関連ドキュメント

Changed
Windows: Git for Windows がインストールされていない環境で、シェルを指定しない PreToolUse フックや PermissionRequest フックがフェイルオープンする問題を修正した。失敗したガードは現在呼び出しをブロックする
英語原文を表示
Windows: Fixed PreToolUse and PermissionRequest hooks that set no shell failing open when Git for Windows isn't installed; a guard that fails now blocks the call

変更後

Git for Windows がインストールされていない環境でも、シェルを指定していない PreToolUse フックや PermissionRequest フックの失敗時に、ツールの実行を確実にブロックできるようになる。

関連ドキュメント

v2.1.296(1件)

Fixed
マネージド設定の PreToolUse フックが 'continue': false でツール呼び出しを拒否する場合や、マネージドの prompt フックがツール呼び出しをブロックする場合に、呼び出しは拒否されるもののターンまで終了してしまっていた問題を修正した
英語原文を表示
Fixed managed-settings PreToolUse hooks that deny a tool call with "continue": false, and managed prompt hooks that block one, refusing the call but not ending the turn

関連ドキュメント

v2.1.292(1件)

Changed
セキュリティ:PreToolUse フックの承認と auto モードが、ネットワーク (UNC) パスからのファイル読み取りの権限プロンプトをバイパスする問題を修正した
英語原文を表示
Security: Fixed PreToolUse hook approvals and auto mode bypassing the permission prompt for file reads from network (UNC) paths

変更後

ネットワークパス (UNC パス) からのファイル読み取りについて、PreToolUse フックの承認や自動モードによって権限確認をスキップされなくなります。そのため、意図しないネットワーク上のホストへのアクセスや認証情報の漏洩リスクを抑えながら、ファイル読み取り時に必ず確認を受け取れるようになります。

v2.1.290(1件)

Fixed
PreToolUse フックがツール呼び出しの入力を書き換えた後に、一部の許可ルールやセーフティチェックがそのツール呼び出しに適用されない問題を修正した。
英語原文を表示
Fixed some permission rules and safety checks not being applied to a tool call after a PreToolUse hook rewrote its input

関連ドキュメント

v2.1.288(2件)

Fixed
-p や SDK セッション、および PreToolUse フックの承認において、OpenTelemetry の claude_code.tool.blocked_on_user スパンがソースや判断として unknown を報告する問題を修正した
英語原文を表示
Fixed OpenTelemetry claude_code.tool.blocked_on_user spans reporting unknown source or decision in -p and SDK sessions and for PreToolUse hook approvals
Fixed
マッチ処理に失敗した場合やツールの入力を JSON にシリアライズできなかった場合に、PreToolUse フックと PermissionRequest フックがスキップされる問題を修正した。現在はその呼び出しをブロックする
英語原文を表示
Fixed PreToolUse and PermissionRequest hooks being skipped when matching them failed or the tool's input could not be serialized to JSON; the call is now blocked

関連ドキュメント

v2.1.281(1件)

Fixed
ブロッキングイベント(PreToolUse など)における mcp_tool hooks が、MCP サーバーの接続完了前にはスキップされる問題を修正した。MCP 接続タイムアウトまで待つようになった
英語原文を表示
Fixed mcp_tool hooks on blocking events (PreToolUse and similar) being skipped while their MCP server was still connecting; they now wait for it, up to the MCP connect timeout

関連ドキュメント

v2.1.271(1件)

Improved
hook フィードバックを改善し、SessionStart、UserPromptSubmit、PreToolUse、SessionEnd の各 hook 実行中はスピナーが経過時間付きでその旨を表示し、Esc で SessionStart hook の待機中のプロンプトをキャンセルできるようになった
英語原文を表示
Improved hook feedback: while a SessionStart, UserPromptSubmit, PreToolUse or SessionEnd hook runs, the spinner says so with elapsed time, and Esc cancels a prompt waiting on a SessionStart hook

変更後

SessionStart、UserPromptSubmit、PreToolUse、SessionEnd フックの実行中に、どのフックが動いているのかと経過時間がスピナー表示で分かるようになり、フックが長引いたときの状況を把握しやすくなる。また、SessionStart フックで待たされているプロンプトを Esc キーでキャンセルできるようになる。

v2.1.248(1件)

Fixed
PermissionRequest または PreToolUse フックが不正な回答を出力した際に、バックグラウンドセッションが黙って待ち続ける問題を修正した。claude agents の行にフック名とスキーマエラーが表示されるようになった
英語原文を表示
Fixed background sessions waiting silently when a PermissionRequest or PreToolUse hook prints an invalid answer: the claude agents row now names the hook and the schema error

関連ドキュメント

v2.1.239(1件)

Fixed
OpenTelemetry のトレース分断を修正した。PreToolUse フックによって保留されたツール実行が新規トレースを開始するのではなく、元のターンのトレース内で再開するようになった
英語原文を表示
Fixed OpenTelemetry trace fragmentation: tool executions deferred by a PreToolUse hook now resume in the original turn's trace instead of starting a new trace

v2.1.222(1件)

Fixed
バックグラウンドエージェントタスク(要約、圧縮、リネーム処理など)において、PreToolUse自動承認フックがツール制限をバイパスして動作してしまう問題を修正しました。
英語原文を表示
Fixed PreToolUse auto-allow hooks bypassing tool restrictions in background agent tasks (summaries, compaction, renames)

v2.1.211(1件)

Fixed
サンドボックス外で実行されるBashに対するPreToolUseフックのask決定が、オートモードによって上書きされる問題を修正した
英語原文を表示
Fixed auto mode overriding a PreToolUse hook's ask decision for unsandboxed Bash — a hook ask now floors the decision at a prompt

変更後

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

関連ドキュメント

v2.1.119(1件)

Added
フック機能の改善:PostToolUse および PostToolUseFailure の入力 JSON に、ツールの純粋な実行時間を示す duration_ms が含まれるようになりました(承認待機時間は除く)
英語原文を表示
Hooks: PostToolUse and PostToolUseFailure hook inputs now include duration_ms (tool execution time, excluding permission prompts and PreToolUse hooks)

変更後

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

関連ドキュメント

v2.1.110(1件)

Fixed
ツール実行失敗時にPreToolUseフックから提供された追加コンテキスト(additionalContext)が失われる問題を修正
英語原文を表示
Fixed PreToolUse hook additionalContext being dropped when the tool call fails

変更後

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

関連ドキュメント

v2.1.101(1件)

Fixed
permissions.deny ルールが PreToolUse フックの permissionDecision: "ask" よりも優先されるよう修正
英語原文を表示
Fixed permissions.deny rules not overriding a PreToolUse hook's permissionDecision: "ask" — previously the hook could downgrade a deny into a prompt

変更後

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

関連ドキュメント

v2.1.90(1件)

Fixed
JSON を標準出力に書き出し、終了コード 2 で終了する PreToolUse フックが、正しくツール実行をブロックできない問題を修正しました。
英語原文を表示
Fixed PreToolUse hooks that emit JSON to stdout and exit with code 2 not correctly blocking the tool call

変更後

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

関連ドキュメント

v2.1.89(2件)

Added
PreToolUse フックに permission decision `
英語原文を表示
Added "defer" permission decision to PreToolUse hooks — headless sessions can pause at a tool call and resume with -p --resume to have the hook re-evaluate

変更後

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

関連ドキュメント

Fixed
Write/Edit/Read ツールの実行時、PreToolUse/PostToolUse フックに file_path が絶対パスとして渡されるよう修正し、ドキュメントに記載された動作と一致させた。
英語原文を表示
Fixed PreToolUse/PostToolUse hooks to receive file_path as an absolute path for Write/Edit/Read tools, matching the documented behavior

変更後

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

関連ドキュメント

v2.1.88(1件)

Fixed
Write/Edit/Readツールにおいて、PreToolUse/PostToolUseフックが file_path を絶対パスで提供していなかった問題を修正しました
英語原文を表示
Fixed PreToolUse/PostToolUse hooks not providing file_path as an absolute path for Write/Edit/Read tools

変更後

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

関連ドキュメント

v2.1.85(1件)

Added
PreToolUseフックがupdatedInputとpermissionDecision: "allow"を返すことで、AskUserQuestionに応答可能になり、ヘッドレス環境での対話をサポート
英語原文を表示
PreToolUse hooks can now satisfy AskUserQuestion by returning updatedInput alongside permissionDecision: "allow", enabling headless integrations that collect answers via their own UI

変更後

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

関連ドキュメント

v2.1.77(1件)

Fixed
PreToolUse フックが "allow" を返した際に、管理設定などの拒否ルールをバイパスしてしまう問題を修正しました
英語原文を表示
Fixed PreToolUse hooks returning "allow" bypassing deny permission rules, including enterprise managed settings

変更後

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

関連ドキュメント

v2.1.47(1件)

Fixed
WindowsでGit Bashではなくcmd.exeを使用していたため、フック(PreToolUse、PostToolUse)がサイレントに実行に失敗する問題を修正しました(anthropics/claude-code#25981)。
英語原文を表示
Fixed hooks (PreToolUse, PostToolUse) silently failing to execute on Windows by using Git Bash instead of cmd.exe (anthropics/claude-code#25981)

変更後

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

v2.1.9(1件)

Added
PreToolUse フックがモデルに追加のコンテキストを返すサポートを追加しました。
英語原文を表示
Added support for PreToolUse hooks to return additionalContext to the model

変更後

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

関連ドキュメント

v2.1.0(2件)

Fixed
PreToolUse フックで、ユーザーへの確認(ask)を返しつつ入力を書き換える(updatedInput)ことが可能になり、ユーザーの同意を得ながら動作するミドルウェアとしてフックを利用できるようになりました。
英語原文を表示
Fixed PreToolUse hooks to allow updatedInput when returning ask permission decision, enabling hooks to act as middleware while still requesting user consent

変更後

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

関連ドキュメント

Added
エージェントのフロントマターでフック設定が可能になり、エージェントの生存期間に限定したフックを定義できるようになりました。
英語原文を表示
Added hooks support to agent frontmatter, allowing agents to define PreToolUse, PostToolUse, and Stop hooks scoped to the agent's lifecycle

v2.0.43(1件)

Added
Added tool_use_id field to PreToolUseHookInput and PostToolUseHookInput types

関連ドキュメント

v2.0.10(1件)

Added
PreToolUse hooks can now modify tool inputs