【ITニュース解説】Claude Code Hooks: Which Ones Add Tokens, Which Cut Them

Claude Codeのフックは、あなたが利用するAIアシスタントであるClaude Codeが特定の状況で自動的に実行するプログラムや処理のことだ。これは、例えばシェルコマンド、ウェブサービスへのHTTPリクエスト、あるいは別のAIモデルへのプロンプトなど、さまざまな形式がある。これらのフックは、セッションの開始時、プロンプトの送信時、ツールが使われる前や後など、全部で33種類の決まったタイミング（イベント）で動作する。フックを賢く使うことで、Claude Codeの動作をカスタマイズできるが、その使い方によっては、AIの利用料金に直結する「トークン」の消費量を大きく増減させる可能性がある。

トークンとは、AIモデルが言語を理解し、生成する際の最小単位であり、あなたのAI利用料金の主な計算基準となる。フックがトークンを「追加」してしまう最も一般的なパターンはいくつかある。一つは、特定のイベントでフックが標準出力（stdout）にテキストを書き出した場合だ。特に「UserPromptSubmit」「UserPromptExpansion」「SessionStart」「PostModelSwitch」の四つのイベントでは、フックが出力したプレーンなテキストが直接Claudeのコンテキスト、つまりAIが考慮すべき情報として追加される。例えば、「SessionStart」フックで会社の規約を「echo」コマンドで出力すると、そのテキストはセッション開始時に一度だけClaudeのコンテキストに追加される。しかし、「UserPromptSubmit」フックで同じことをすると、あなたがプロンプトを送るたびにその規約が再度コンテキストに追加され、毎回トークンコストが発生する。これらのテキストは、システムからのリマインダーとして追加されるため、画面上では見えないことも多く、気づかないうちにトークン料金が増えてしまう原因となることがある。

additionalContextフィールドを使って、フックが構造化されたテキストをClaudeのコンテキストに追加することもできる。これはより多くのイベントで利用可能だが、やはりトークンコストを発生させる。例えば、ツールの実行前後に警告メッセージなどを追加する場合に用いられる。また、「PostToolUse」イベントでフックがエラーコード「2」を返すと、標準エラー出力（stderr）に書かれた内容がClaudeに警告として表示される。これも会話にテキストが追加されるため、トークンコストが発生する。例えば、コードの構文チェックフックが毎回80行のエラーメッセージを返すと、その都度80行分のトークンが加算される。さらに、「Stop」イベントでexit 2を返すと、Claudeの作業終了を阻止し、新たな会話ターンを開始させてしまう。これにより、セッションの全履歴が再度AIに送られるため、非常に大きなトークンコストがかかる。

プロンプトベースのフックやエージェントベースのフックもトークンコストに直結する。これらは、フック自身が別のAIモデルを呼び出すため、メインのClaude Codeセッションとは別にモデル利用料金が発生する。特にツール呼び出しごとに動作するような高頻度イベントでこれらを使うと、コストは急速に増大する。フックがテキストをコンテキストに注入する際は、そのテキストが短く、AIの次の行動に影響を与え、かつ可能な限り低頻度のイベントで実行されるように設計することが重要だ。常に表示する必要のない長い情報は、「CLAUDE.md」ファイルに記載するなど、キャッシュされるプレフィックスの一部として扱うべきだ。

一方で、フックを使ってトークンを「削減」することも可能だ。これは主に二つのフィールドで行われる。「PreToolUse」イベントで利用できるupdatedInputフィールドは、ツールが実行される前にその入力パラメータを書き換えることができる。例えば、ファイルを読むツールがあったとして、フックで読み込む範囲を制限したり、テストコマンドの結果をフィルターしたりすることで、AIが処理する情報量を減らせる。これにより、AIは元々予定されていた大きな入力ではなく、フックによってトリミングされた小さな入力のみを読むため、トークンコストを削減できる。

もう一つは、「PostToolUse」イベントで利用できるupdatedToolOutputフィールドだ。これは、ツールの実行結果をClaudeが読む前に、別の値に置き換えることができる。例えば、非常に長いビルドログからエラー行とサマリーだけを抜き出したり、JSONレスポンスからAIが必要なキーだけを抽出したりすることが可能だ。このように、モデルが必要としない余分な情報を削ぎ落とすことで、読み込むべきトークン数を大幅に減らすことができる。これらの機能によって、AIが不必要な情報を処理するのを防ぎ、結果としてトークン使用量を大幅に削減できるのだ。実際には、平均トークン使用量が42%や90%削減されたという報告もあるが、これはあくまで特定の条件下でのベンチマークであり、自身の環境で測定することが重要だ。

フックがClaudeに注入する文字列には、一回あたり10,000文字という厳格な上限がある。additionalContext、システムメッセージ、プレーンな標準出力など、それぞれの文字列が個別にこの制限の対象となる。この上限を超えた場合、Claude Codeはテキストを途中で切るのではなく、その内容をセッションディレクトリ内のファイルに保存し、Claudeにはそのファイルのパスと、最初の2,000文字のプレビューのみを提供する。Claudeは必要であればそのファイルをツール呼び出しで読むことができるが、その場合はプレビュー、ツール呼び出し、そして完全なコンテンツのそれぞれにコストがかかるため、結果的にコストが増大する可能性もある。フックの出力が定期的に数百文字を超えるようであれば、フック内で直接ファイルに書き出し、そのファイルへの短いパスだけをAIに伝える方が効率的で、意図しないコスト増加を防ぐことができるだろう。

ほとんどのフックはセッションのトークンやコストに関する情報に直接アクセスできない。しかし、「PreModelSwitch」イベントは例外で、このフックの入力には、次にAIモデルが切り替わる際に再送されるコンテキストのトークン数や、キャッシュ書き込みにかかる推定コストといった情報が含まれている。これにより、モデル切り替えが高価な操作であることを認識し、その決定を下す前にコストを確認できる。例えば、18万を超えるトークンを扱うモデル切り替えが1ドル以上のコストになる場合、フックを使って確認を促すことができる。

フックを導入する際には、いくつかの一般的な間違いにも注意が必要だ。例えば、ブロックしたい場合にexit 1を使うのは誤りだ。フックがアクションをブロックするには、必ずexit 2を返す必要がある。また、「PreToolUse」フックがタイムアウトした場合、そのフックはツールの実行をブロックせず、元のツール呼び出しがそのまま実行されてしまう。スクリプトのパスを誤入力した場合も、フックがサイレントに無効化され、何の警告もなく機能しないことがあるので、初回実行時には注意深く監視すべきだ。

フックのコストを最適化するために、今すぐにでもできることがある。まず、自身の設定ファイルにあるフックをイベントごとにリストアップし、「UserPromptSubmit」「SessionStart」「PreToolUse」「PostToolUse」で動くものに注目する。これらの中で、プレーンな標準出力を表示したり、additionalContextを返したり、exit 2でエラーを出すフックがトークン追加の原因となる。次に、「UserPromptSubmit」のような高頻度で実行されるイベントに設定されているフックで、プロンプトごとに内容が変わらないテキストがあるなら、「SessionStart」などの低頻度イベントに移動するか、「CLAUDE.md」に記載してキャッシュを活用するように変更する。これにより、同じ情報を支払う回数を減らせる。最も出力が大きくなる傾向のあるツール（例えばテストやビルドを実行するBashコマンドなど）に対しては、「PostToolUse」フックを追加し、updatedToolOutputを使ってエラーやサマリーだけを返すように設定すると良いだろう。そして、何かをブロックしたいポリシーフックは必ずexit 2を返し、実際にブロックされることを確認するためのテストを行うべきだ。最後に、「PreModelSwitch」フックを設定し、askオプションと合わせて推定コストを表示させることで、意図しないモデル切り替えによる高額な請求を防ぐことができる。

Claude Codeのフックは強力なカスタマイズ機能であり、正しく理解して利用することで、AIアシスタントの効率を高め、同時にトークンコストを管理する重要な手段となる。