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

> Claude Code hooksはexit 1やタイムアウトでは止まらない。exit 2とonFailure: blockで統制をフェイルクローズにする設計と、managed settingsでの強制手順を解説。

- Canonical: https://kuucorp.com/blog/claude-code-hooks-fail-closed-onfailure-design/
- Date: 2026-10-29
- Last modified: 2026-10-29
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
全社ポリシーをClaude Codeのhooksで強制したつもりが、フックスクリプトがクラッシュした瞬間に素通しになる。この構造は、終了コードの意味を取り違えたときに実際に起こります。統制の可否は「ルールの中身」より「フック自身が失敗したとき何が起きるか」で決まります。

本記事は[エージェントガバナンス](/ai-governance/)の技術統制の一部です。全社規模の統制設計は[KuuのRDE](https://kuucorp.com/services/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` の呼び出しはブロックされません。スクリプトが存在しない場合も、未設定なら非ブロッキングエラーとして処理が進みます。

```json
{
  "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で監査証跡を自動記録する](/blog/claude-code-hooks-audit-policy-enforcement-smb/)を参照してください。

## 参考

- [Hooks reference（Claude Code Docs）](https://code.claude.com/docs/en/hooks)
- [Changelog（Claude Code Docs）](https://code.claude.com/docs/en/changelog)
- [Claude Platform release notes](https://platform.claude.com/docs/en/release-notes/overview)

## まとめ

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