Claude Codeのフックで警告を出したいならadditionalContextではなくsystemMessageを使う

Claude Codeのセッション開始時に自動実行されるフック機構では、特定の条件下で警告メッセージを表示させたいというニーズがある。例えば、壁打ち専用のリポジトリを常に参照できる専用エイリアス経由で起動すべき場面を逃したとき、ユーザーに即座に知らせたいという場合だ。最初の実装ではadditionalContextフィールドで警告を返していたが、同じ仕組みなのに「警告が出たり出なかったり」という再現性のない挙動が生じてしまった。

ここで分かったのが、ドキュメントの微妙な差だ。additionalContextはClaudeへの文脈注入に過ぎず、Claudeがそれを実際の応答で言及するかは保証されない。つまり、Claudeが話題に挙げるかどうかは確率的であり、起動直後にユーザーが何も発言していなければ、Claudeはそもそも何も話さない。一方、systemMessageフィールドはユーザー端末へ直接表示される。確実性が必要な警告・通知の類は、こちらを使うべきだということだ。これはドキュメントに明記されていない部分だったため、claude-code-guideサブエージェントで公式ドキュメントを調査し、実装して動かして検証することで初めて確実になった。複数フックが同時にsystemMessageを返した場合の挙動も、テストフック経由で実地検証されている。

中小企業の実務では、「仕組みが確実に動く」ことが無視できない。Slackへの定期通知が時々落ちる、メール配信が失敗することがある、警告が出ずに問題が放置されるといった局面は多い。ドキュメントの「これで大丈夫」を信じるのではなく、実装後に「本当に動いているか」を自分の目で見て確かめる。思い込みで運用を始めるのではなく、小さなテストで動作を検証してから本番に移す。この地味な確認作業が、後々の無駄なトラブルシューティングを何時間も削れる。