【ITニュース解説】Claude Code 2.1.299 to 2.1.301 Changed How Your Hooks Behave: 7 Things to Recheck

Claude Codeは、開発者が日常的に行うコーディング作業を人工知能の力で効率化するためのツールであり、多くのシステムエンジニアが利用している。このツールは、ユーザーの指示（プロンプト）を解釈し、コードの生成や修正、テストの実行など、様々な開発タスクを支援する。Claude Codeの大きな特徴の一つに「フック」という仕組みがある。フックとは、特定のイベント（例えば、ユーザーがプロンプトを送信する直前や、AIが外部ツールを実行しようとする前など）が発生した際に、自動的に実行されるように設定できるプログラムの断片のことである。これにより、開発者はClaude Codeの標準的な挙動をカスタマイズし、独自のルールや処理を組み込むことができる。例えば、セキュリティのために特定のキーワードを含むプロンプトをブロックしたり、特定のコマンドの実行前に承認プロセスを挟んだりすることが可能になるのだ。

最近のClaude Codeのアップデート、特にバージョン2.1.299から2.1.301にかけての変更は、このフックの動作方法に大きな影響を与えた。これらの変更は、開発者が意図的にフックの設定ファイルを書き換えたわけではなくても、Claude Codeを新しいバージョンに更新した瞬間に適用されるため、既存のフックが予期せぬ動作をしたり、これまでの想定と異なる結果をもたらしたりする可能性がある。そのため、これらの変更点を理解し、自分の環境でフックが正しく機能しているかを確認することが非常に重要である。

まず、自身のClaude Codeのバージョンを確認する必要がある。claude --versionというコマンドを実行して表示されるバージョン番号が2.1.299よりも古い場合、以下の変更はまだ適用されていないが、claude updateを実行すると適用が始まる。

最初の大きな変更点は、「UserPromptSubmitフックがスキルの展開前に実行されるようになった」ことである。これまでは、スキル（一連の自動化されたタスク）のテキストがプロンプトに展開された後にUserPromptSubmitフックが実行されていた。しかし、バージョン2.1.299以降では、スキルが展開されるよりも早い段階でフックが実行される。この変更により、プロンプトをブロックするフックは、スキルの中に書かれたシェルコマンド（例えば、!git diff HEADのようなコマンド）も停止させられるようになった。その一方で、フックがスキルの展開後に現れる特定のキーワードやパターンを検出するように設定されていた場合、新しい実行タイミングではそれらの情報を検出できなくなり、フックが期待通りに動作しない可能性がある。この影響を受ける可能性のある設定は、grep -n -A8 UserPromptSubmit .claude/settings.json ~/.claude/settings.jsonなどのコマンドで確認できる。

次に、「スキルのUserPromptSubmitフックが、そのスキルを呼び出したプロンプトでは実行されず、次のプロンプトから実行されるようになった」点だ。これまで、スキル内で宣言されたUserPromptSubmitフックは、そのスキルが呼び出された最初のプロンプトから実行されていた。しかし、この変更により、スキルが呼び出された直後のプロンプトではなく、ユーザーが次に送るプロンプトからフックが実行されるようになる。もし、スキルが呼び出された瞬間のプロンプトに対して特定のチェックを行う必要があった場合、そのフックは機能しなくなる。このようなケースでは、チェックのタイミングをUserPromptExpansionフックに移行することが推奨される。影響を受けるスキルは、grep -rln UserPromptSubmit .claude/skills ~/.claude/skillsで探し出せる。

三つ目の変更は、「PreToolUseおよびPermissionRequestフックが返すupdatedInputが厳密に検証されるようになった」ことである。フックは、AIがツールを実行する前や、特定の操作の許可を求める際に、その入力データを変更してAIに返すことができる。この返されるデータが「updatedInput」と呼ばれる。以前は、このデータの一部だけを変更して返しても許容される場合があったが、バージョン2.1.300以降では、updatedInputがClaude Code自身の入力と同様に厳しく検証されるようになった。具体的には、AIが認識しない余計なキー（項目）は削除され、ツールが受け付けないような不適切な入力が含まれていた場合、ツールの呼び出しそのものが拒否されてしまう。フックが返すupdatedInputオブジェクトは、変更したいフィールドだけでなく、必要な他のフィールドも全て含んだ完全な形でなければならなくなったのだ。

四つ目は、「Coworkクラウドセッションにおいて、PermissionRequestフックによるsetModeの変更が無視されるようになった」ことである。PermissionRequestフックは、AIが特定の操作を行う許可を求める際に、その操作を許可するだけでなく、パーミッションモード（例えば、編集を自動的に許可するモードなど）を変更する設定もできた。しかし、バージョン2.1.300以降、特にCoworkというクラウドベースのセッションでは、このsetModeによるモード変更は無視されるようになった。つまり、フックが特定の操作を許可しても、パーミッションモードは変更されず、引き続き許可を求めるプロンプトが表示され続けることになる。モード変更を試みているフックは、grep -rn setMode .claude ~/.claude/settings.json ~/.claude/hooksで確認できる。

五つ目は、「エージェントのツールリストの解釈が厳格化された」ことである。Claude Codeでは、AIエージェントが利用できるツールをリスト形式で定義できる。これまで、mcp__<server>のような指定で、意図せず<server>__bのような関連する別のサーバーのツールまで含んでしまうことがあった。しかし、バージョン2.1.299以降、エージェントが利用できるツールは、リストで明示的に指定されたMCPサーバーのツールのみに限定されるようになった。これにより、エージェントが不要なツールにアクセスするリスクは減るが、もし複数の関連ツールを使っていたエージェントがある場合、機能しなくなる可能性がある。

六つ目は、「プラグインフックがアクションを処理できない場合の挙動が変わった」ことである。プラグインフックは、特定の「アクション」に対して応答する役割を持つ。これまでは、プラグインフックが何らかの理由でアクションを受け取れない、あるいはその応答をAIに返せない場合、そのアクションはそのまま処理が進んでいた。しかし、バージョン2.1.299以降、このような状況ではアクションは「拒否される」ようになった。もしAIがすでにツールを実行していた場合でも、その結果はAIに渡されず破棄される。これは、不完全な処理よりも安全に停止する方向に挙動が変更されたことを意味する。

七つ目は、「modフックの.catchハンドラが、re-entryイベントを捕捉しなくなった」ことである。modフックの.catchハンドラは、フック内でエラーが発生した場合やタイムアウトした場合に実行される。以前は、フック自身の内部で別のAI呼び出しが行われ、そこからイベントが「re-entry」（再入）してきた場合も、このハンドラが捕捉できた。しかし、バージョン2.1.301以降、このような内部からのイベントは、親フックの.catchハンドラでは捕捉されなくなった。これにより、re-entryを検出するためのコードは機能しなくなるため、フックの動作を監視するロジックを見直す必要がある。

これらの変更は、AIコーディングツールが進化する過程で、その内部の挙動やセキュリティ、信頼性が向上するために行われたものである。システムエンジニアにとって、このようなツールのアップデートは、日々の開発ワークフローに直接影響を与える可能性があるため、常に注意を払う必要がある。自分のフックが予期せぬ動作をしないか、上記の確認方法を用いてチェックし、必要に応じて設定やスクリプトを修正する作業が求められる。これは、AIの能力を最大限に引き出し、安全かつ効率的に利用するための「プロンプトエンジニアリング」の一部とも言える重要な作業である。アップデートを適用する際は、本番環境でいきなり行うのではなく、テスト環境で慎重に動作確認を行うことが推奨される。Hermes IDEのようなツールは、フックの変更を安全な隔離された環境でテストする機能を提供しており、このような検証作業に役立つだろう。