Claude Codeのhooksが「失敗したら止める」側へ寄った。10月のCHANGELOGで読む安全制御の変更

Claude Codeのhooksは、ツールを実行する前後に自分のスクリプトを差し込める仕組みです。危険なコマンドを止める門番として使っている人も多いと思います。

ところが、門番そのものが動かなかったときにどうなるかは、意外と意識されていません。スクリプトが起動できない、時間切れになる、想定外の終了コードを返す。そういうとき、これまでは操作がそのまま通ってしまう場面がありました。

10月の更新で、この「門番が倒れたときの扱い」がまとめて見直されました。この記事では、公式CHANGELOGに書かれた変更だけを拾い、設定で何をすべきかを整理します。

fail-openとfail-closed

まず用語を整理します。

安全装置が故障したとき、操作を通してしまう設計をfail-open、止める設計をfail-closedと呼びます。どちらが正しいかは用途で決まります。ログを取るだけのhookなら、壊れても作業は止めたくありません。危険なコマンドを止めるhookなら、壊れたときは止まってほしいはずです。

今回の更新は、この選択を明示できるようにし、いくつかの場面では既定の動きを止める側へ変えるものです。

変更点の一覧

関係する変更をまとめます。

$$\small \def\arraystretch{1.5} \begin{array}{|l|l|} \hline \textbf{\textsf{バージョン}} & \textbf{\textsf{変更内容}} \\ \hline \textsf{v2.1.294} & \textsf{指示文で書いたhookが止めるべき操作を通す不具合を修正} \\ \hline \textsf{v2.1.295} & \textsf{onFailure: block を追加} \\ \hline \textsf{v2.1.296} & \textsf{管理設定のhookで拒否してもターンが続く不具合を修正} \\ \hline \textsf{v2.1.299} & \textsf{プラグインhookが答えられない操作は拒否に変更} \\ \hline \textsf{v2.1.299} & \textsf{UserPromptSubmitをスキル展開より前に実行} \\ \hline \textsf{v2.1.302} & \textsf{同じイベントのhookは同時に最大12件} \\ \hline \end{array}$$

順に見ていきます。

指示文で書いたhookが素通りしていた

v2.1.294は、修正が1行だけの小さなリリースでした。内容は「Block commands that...」のように指示文で書いた `prompt` hookや `agent` hookが、止めるべき操作を通してしまう不具合の修正です。

promptやagentのhookは、スクリプトではなく自然文で判断基準を書けるのが利点です。その反面、書いた文が意図どおりに解釈されているかは外から見えません。今回の不具合は、まさにその弱点が出た例です。

このバージョンより前から自然文のhookで危険な操作を止めていたなら、実際に止まっているかを一度試しておくと安心です。

onFailure: block で「壊れたら止める」を選べる

v2.1.295で、コマンド型とHTTP型のhookに `onFailure: "block"` が追加されました。CHANGELOGの説明は「起動できない、時間切れになる、想定外のコードで終了したhookが、操作を通す代わりにブロックする」です。

設定のイメージは次のとおりです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python guard.py",
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

既定値は `"continue"`（失敗しても操作を通す）です。門番の役割を持つhookには、明示的に block を付けておくのが基本になります。逆に、通知やログだけのhookに付けると、ネットワークの瞬断で作業が止まるので注意が必要です。

Windowsでは既に止める側へ

同じ時期に（v2.1.299）、Windows固有の修正も入っています。シェル指定のない `PreToolUse` や `PermissionRequest` のhookは、Git for Windowsが入っていない環境で失敗すると操作を通していました。修正後は「失敗した門番はその呼び出しを止める」動きになっています。

Windowsで新しいPCをセットアップした直後など、Git for Windowsを入れる前にClaude Codeを動かすと、hookが失敗して操作が止まる場面が出てきます。不具合ではなく、安全側に倒れた結果です。

プラグインのhookも止める側へ

v2.1.299では、プラグインのhookについて「hookに操作を渡せない、またはhookから答えが返らないとき、ブロックできる操作は通さずに拒否する」よう変わりました。すでに実行済みのツールについては、その結果をClaudeに渡さずに止めます。

また、`UserPromptSubmit` hookが、スキルやカスタムスラッシュコマンドを展開する前に実行されるようになりました。プロンプトを止めるhookが、スキルに埋め込まれたシェルコマンドも一緒に止められるようになったということです。以前は、スキル経由で実行されるコマンドが先に動いてしまう余地がありました。

管理設定での拒否がターンを終わらせるように

組織で管理設定を配っている場合に関係する修正もあります。v2.1.296で、管理設定の `PreToolUse` hookが `"continue": false` で拒否したとき、ツール呼び出しは拒否されるのにターンが終わらない不具合が直りました。

「拒否したら作業自体を止める」という意図で管理設定を書いていた組織では、これまでClaudeが別の手段で同じことを試みる余地がありました。

同時実行の上限

v2.1.302では、promptとagentのhookについて、同じイベントで同時に動くのは最大12件までになりました。残りは順番待ちになります。

hookを大量に登録している環境では、待ち時間が伸びる可能性があります。時間切れの設定が短いと、待っているうちに失敗扱いになるかもしれません。onFailure: block と組み合わせている場合は、時間切れの値に余裕を持たせておくと安全です。

設定を見直すチェックリスト

ここまでの内容を、見直しの手順にまとめます。

• [ ] 危険な操作を止めるhookを一覧にする

• [ ] それぞれに onFailure: block を付けるか決める

• [ ] ログや通知だけのhookには付けない

• [ ] 自然文で書いたhookで、止めるべき操作を実際に試す

• [ ] Windows環境ではGit for Windowsの有無を確認する

• [ ] hookの時間切れの値に余裕を持たせる

まとめ

10月のClaude Codeは、hooksが失敗したときの扱いを「通す」から「止める」へ寄せました。門番役のhookには `onFailure: "block"` を付け、ログ役のhookには付けない。この区別が設定の中心になります。

安全装置は、動いているときより壊れたときの振る舞いで価値が決まります。

まずは手元の設定から、操作を止める目的のhookを1つ選び、わざとスクリプトのパスを間違えて、本当に止まるかを試してみてください。

参考リンク

• Claude Code CHANGELOG: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md

• Claude Code hooks ドキュメント: https://code.claude.com/docs/en/hooks