hook通信失敗時の操作拒否
CHANGELOG 原文(英語)
Changed actions a plugin hook can block to be refused, not let through, when the hook cannot be handed them or cannot hand back its answer; a tool that already ran has its result withheld 公式の変更履歴を開く ↗ 日本語での補足
プラグインhookがブロックできる操作について、hookに操作を渡せない場合やhookが回答を返せない場合は、通過させずに拒否するように変更。すでに実行済みのツールは結果を保留する。
ドキュメント
ドキュメントの抜粋(参考訳)
フックが失敗したときにアクションをブロックする
ほとんどのイベントでは、フックが失敗またはタイムアウトしても Claude Code はアクションを実行します。パスが間違っていたりスクリプトがクラッシュしたりするポリシーフックは、それによってすべてを通してしまいます。代わりにアクションをブロックするには、command、http、または mcp_tool フックに "onFailure": "block" を設定します。Claude Code v2.1.295 以降が必要です。mcp_tool フックでの onFailure には、v2.1.328 以降が必要です。
Agent SDK のコールバックフックについては、コールバックが失敗したときにアクションをブロックするを参照してください。
[!NOTE]
Git Bash のない Windows では、
onFailureを未設定のまま失敗したシェル形式のPreToolUseまたはPermissionRequestのコマンドフックが、代わりにツール呼び出しをブロックすることがあります。
次の .claude/settings.json 内の PreToolUse フックは、各 Bash コマンドの前にプロジェクトのスクリプトを実行し、スクリプトが失敗した場合はそのコマンドをブロックします。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
"onFailure": "block"
}
]
}
]
}
}
試すには、check-command.js を置かないままにして、ls などの Bash コマンドを実行するよう Claude に依頼します。Claude Code はその呼び出しをブロックし、エラーには failed; blocking because onFailure is "block" と、その後に node 自体のエラー出力が含まれます(ここでは 1 行に省略しています)。
PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"
Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'
タイムアウトの場合、メッセージには failed ではなく timed out と表示されます。onFailure を設定していない場合、同じスクリプトの欠落はブロックしないエラーとなり、ls は実行されます。
次のそれぞれが失敗として扱われます。
- 起動できない:スクリプトや実行ファイルが存在しないなどの理由で、コマンドフックの起動に失敗した
- 0 または 2 以外の終了コード:コマンドフックでは、
permissionDecision: "allow"のようにアクションを許可する JSON を出力していても失敗として扱われます。JSON で判定を返すには、終了コード 0 で終了してください - HTTP エラー:HTTP フックの接続に失敗した、またはレスポンスのステータスが 2xx でない
- MCP 失敗:
mcp_toolフックのサーバーが接続されていない、またはそのツールがエラーを返した場合。PreToolUseやUserPromptSubmitのようなイベントで"block"が設定されている場合、空でない応答も、それが{}またはreason以外のフック出力フィールドを設定する JSON でない限り、失敗として扱われます - タイムアウト:フックが
timeoutに達した - 無効な出力:JSON 出力をパースできない、またはスキーマ検証に失敗した。HTTP フックでは、空でも JSON オブジェクトでもない 2xx のボディも失敗として扱われます。コマンドフックのプレーンテキストの標準出力は失敗にはなりません
"block" を設定すると、失敗はそのイベントで終了コード 2 が行うことと同じ動作をします。ただし PermissionRequest では、リクエストを拒否します。たとえば、PreToolUse での失敗はツール呼び出しをブロックし、UserPromptSubmit での失敗はプロンプトをブロックします。
このフィールドは次のフックには影響しません。
Stop、SubagentStop、TaskCompleted、TeammateIdleフック:これらのイベントでの終了コード 2 は Claude に作業を続けさせるものであり、Claude は実行されないフックを修復できないため- バックグラウンドのコマンドフック:
asyncまたはasyncRewakeを設定したコマンドフック
[!NOTE]
Code Mode を使用している場合、
PreToolUseでの失敗は異なる動作をします。フックによるツール呼び出しの拒否を参照してください。
取得日 · 2026-11-20