約 4 分で読めます

フック失敗時もブロックする全社統制設計

全社ポリシーを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つあります。

  1. updatedInput は入力全体を置換する: 変更しないフィールドも含めて返す必要があります。権限ルールの評価は、Claudeが送った入力ではなくフックが返した入力に対して行われます
  2. updatedInput は検証される: v2.1.300以降、Claude自身の入力と同様に検証され、不明なキーは破棄され、ツールが拒否する入力は呼び出しの拒否になります
  3. 同時実行数に上限がある: prompt と agent フックは同一イベントで最大12個ずつ並列に走り、超えた分は待機します。待機中のフックのタイムアウトは、そのフックが開始してから数えます

組織としてフックの迂回をどう防ぐか

managed settingsの allowManagedHooksOnly で、ユーザー・プロジェクト・プラグインのフックを止め、管理者のフックだけを走らせられます。

フックの書き方が正しくても、開発者が disableAllHooks で無効化できれば統制になりません。公式ドキュメントでは、managed policyで設定されたフックは、ユーザー・プロジェクト・ローカル設定側の disableAllHooks では無効にできず、managedレベルの設定だけが無効化できると説明されています。さらに allowManagedHooksOnly を使うと、管理対象外のユーザー・プロジェクト・ローカル・プラグインのフックをブロックできます(managed設定の enabledPlugins で強制有効化されたプラグインのフックは対象外)。HTTPフックは allowedHttpHookUrls でURL許可リストを定義でき、宛先の迂回を防げます。

実装の順序は次のとおりです。

  1. 拒否ルールを持つ PreToolUse フックをmanaged設定で配布する
  2. 全フックに exit 2 と onFailure: "block" を適用する
  3. allowManagedHooksOnly で管理対象外のフックを止める
  4. 変更のたびにフック自体を回帰テストする(スクリプトが落ちたとき実際にブロックされるかを確認する)

規模別の留意点(SMB / エンタープライズ)

数百〜数千人規模では、フェイルクローズが全開発者の作業停止につながります。まずシャドー運用(ログのみ)で誤検知率を測り、その後ブロックへ段階移行する運用が現実的です。拠点が少ない組織では、Bash に絞ったexit 2の運用だけでも効果があります。中小企業向けの導入手順はClaude Codeのhooksで監査証跡を自動記録するを参照してください。

参考

まとめ

Claude Code hooksは、既定ではフェイルオープンです。exit 2、onFailure: "block"、managed settingsの allowManagedHooksOnly の3点を組み合わせて、初めて全社で使える統制になります。フック設計と全社展開の相談は、KuuのRDEまでお問い合わせください。

関連記事

Claude Code Mods——権限モデルとガバナンス設計Security posture逸脱をSIEMで検知する設計NISTエージェントID・認可構想を統制設計に写像するClaude全端末サインアウトAPIが止める範囲と残す範囲