全社ポリシーをClaude Codeのhooksで強制したつもりが、フックスクリプトがクラッシュした瞬間に素通しになる。この構造は、終了コードの意味を取り違えたときに実際に起こります。統制の可否は「ルールの中身」より「フック自身が失敗したとき何が起きるか」で決まります。
本記事はエージェントガバナンスの技術統制の一部です。全社規模の統制設計はKuuのRDEで支援しています。
Claude Code hooksはなぜフェイルオープンになりやすいのか
exit 2だけがブロックで、exit 1や127は非ブロッキングエラーです。ポリシー用フックでexit 1を使うと、操作はそのまま実行されます。
公式ドキュメントでは、終了コードの意味が明確に分かれています。
- exit 0: 成功。stdoutのJSONがあれば適用される
- exit 2: ブロッキングエラー。
PreToolUseなどブロック可能なイベントで操作を止める。stdoutにJSONがあってもブロックされ、permissionDecision: "allow"でも覆せない - それ以外の非ゼロ(1、3、127など): 非ブロッキングエラー。エラー通知は出るが操作は続行する
多くのシェルスクリプトは失敗時にexit 1を返します。Unixの慣習どおりに書いたポリシーフックは、検知してもブロックしません。公式も「ポリシーを強制するフックはexit 2を使う」と明記しています。
タイムアウトやクラッシュでも止めるにはどうするか
onFailure: "block"を指定すると、フックの失敗時に操作がブロックされます。未指定ではタイムアウトしてもPreToolUseは止まりません。
command と http のフックには onFailure フィールドがあり、値は "continue" か "block" です(Claude Code v2.1.295以降)。公式ドキュメントによると、command・http・mcp_tool フックのデフォルトタイムアウトは600秒で、タイムアウトしたフックの出力は破棄され、onFailure: "block" を設定していなければ PreToolUse の呼び出しはブロックされません。スクリプトが存在しない場合も、未設定なら非ブロッキングエラーとして処理が進みます。
{
"type": "command",
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
"onFailure": "block"
}
フェイルクローズの最小構成は、判定ロジックの拒否に exit 2、フック自体の失敗に onFailure: "block" を使う二段構えです。ただし、ブロックされた開発者の作業は止まります。可用性とのトレードオフとして、重要度の高いイベント(Bash、本番系MCPツール)に限定して適用してください。
複数のフックが矛盾した判定を返したらどうなるか
判定の優先順位は deny > defer > ask > allow です。複数のフックで1つでも拒否があれば、その操作は拒否されます。
同一イベントに一致するフックは並列に実行されます。ユーザー・プロジェクト・ローカル・プラグイン・managedの各設定のフックは置き換えではなく加算されます。PreToolUse で判定が割れた場合の優先順位は deny > defer > ask > allow と公式に定められているため、全社の拒否ルールをmanagedで1つ足せば、下位の設定が許可を返しても覆せません。
注意すべき点が3つあります。
updatedInputは入力全体を置換する: 変更しないフィールドも含めて返す必要があります。権限ルールの評価は、Claudeが送った入力ではなくフックが返した入力に対して行われますupdatedInputは検証される: v2.1.300以降、Claude自身の入力と同様に検証され、不明なキーは破棄され、ツールが拒否する入力は呼び出しの拒否になります- 同時実行数に上限がある:
promptとagentフックは同一イベントで最大12個ずつ並列に走り、超えた分は待機します。待機中のフックのタイムアウトは、そのフックが開始してから数えます
組織としてフックの迂回をどう防ぐか
managed settingsの
allowManagedHooksOnlyで、ユーザー・プロジェクト・プラグインのフックを止め、管理者のフックだけを走らせられます。
フックの書き方が正しくても、開発者が disableAllHooks で無効化できれば統制になりません。公式ドキュメントでは、managed policyで設定されたフックは、ユーザー・プロジェクト・ローカル設定側の disableAllHooks では無効にできず、managedレベルの設定だけが無効化できると説明されています。さらに allowManagedHooksOnly を使うと、管理対象外のユーザー・プロジェクト・ローカル・プラグインのフックをブロックできます(managed設定の enabledPlugins で強制有効化されたプラグインのフックは対象外)。HTTPフックは allowedHttpHookUrls でURL許可リストを定義でき、宛先の迂回を防げます。
実装の順序は次のとおりです。
- 拒否ルールを持つ
PreToolUseフックをmanaged設定で配布する - 全フックに exit 2 と
onFailure: "block"を適用する allowManagedHooksOnlyで管理対象外のフックを止める- 変更のたびにフック自体を回帰テストする(スクリプトが落ちたとき実際にブロックされるかを確認する)
規模別の留意点(SMB / エンタープライズ)
数百〜数千人規模では、フェイルクローズが全開発者の作業停止につながります。まずシャドー運用(ログのみ)で誤検知率を測り、その後ブロックへ段階移行する運用が現実的です。拠点が少ない組織では、Bash に絞ったexit 2の運用だけでも効果があります。中小企業向けの導入手順はClaude Codeのhooksで監査証跡を自動記録するを参照してください。
参考
まとめ
Claude Code hooksは、既定ではフェイルオープンです。exit 2、onFailure: "block"、managed settingsの allowManagedHooksOnly の3点を組み合わせて、初めて全社で使える統制になります。フック設計と全社展開の相談は、KuuのRDEまでお問い合わせください。
