# Claude Code プラグインのフック設計
プラグインにおける hooks は、LLM の確率的な振る舞いを決定論的な制御で包むための仕組みである。どのタイミングで何を差し込むかを誤ると、開発体験を損なうだけでなくセキュリティホールにもなりうる。本稿では四つの主要フックの使い分けと、実運用で得た教訓をまとめる。
四つのライフサイクル
Claude Code が公開している主要フックは次の四種類である。`SessionStart` はセッション開始時に一度だけ呼ばれ、環境変数や初期コンテキストを注入する用途に向く。`UserPromptSubmit` はユーザーがプロンプトを送信するたびに発火し、入力の前処理や禁止語チェックに使える。`PreToolUse` は任意のツール実行前に呼ばれ、引数の検証や承認フローに組み込む。`PostToolUse` はツール実行後に呼ばれ、監査ログや後処理を担う。
この四点を押さえるだけで、プラグインの骨格は概ね組み立てられる。
PreToolUse による事前検証
最も強力なのが `PreToolUse` である。終了コードがゼロでなければツール実行をキャンセルできるため、危険なコマンドの網を張れる。我々のチームでは以下のようなシェルスクリプトを置き、`rm -rf /` に類するパターンや、本番 DB への直接接続を機械的に止めている。
```bash #!/usr/bin/env bash payload=$(cat) cmd=$(echo "$payload" | jq -r '.tool_input.command // empty') if echo "$cmd" | grep -qE 'rm +-rf +/|DROP +DATABASE'; then echo '{"decision":"block","reason":"危険操作のため遮断"}' >&2 exit 2 fi exit 0 ```
標準入力で JSON を受け取り、標準エラーに構造化された拒否理由を返すのが現在の契約である。モデルには拒否理由がフィードバックされ、自己修正を促せる。
PostToolUse と監査証跡
`PostToolUse` は副作用を起こすフックではなく、起こった結果を記録するためのものと捉えるべきだ。ここで重い処理を入れるとユーザー体感が悪化するため、基本は append-only のログ書き出しに留める。我々は実行されたツール名、引数のハッシュ、終了コード、所要時間を JSON Lines として `audit.log` に出し、別プロセスが集計ダッシュボードへ流している。
監査ログの設計で重要なのは、引数そのものを生で保存しないことだ。秘匿情報が混入しうるため、SHA-256 などでハッシュ化して保持し、必要時のみ別経路で原本を取り出せるようにしておく。
UserPromptSubmit の賢い使い方
`UserPromptSubmit` は入力前処理の唯一の合法的な場所だ。ここでは二つの用途が実用的である。一つは社内用語の展開で、独自の略語を正式名称に置換することでモデルの誤解を減らせる。もう一つは PII の検知で、クレジットカード番号や電話番号が含まれていたら警告を表示し、送信を一旦止める。過剰なフィルタリングはユーザー体験を損なうため、ブロックより警告を優先するのが経験則である。
SessionStart で文脈を揃える
`SessionStart` は起動時に一度しか呼ばれないため、高コストな処理を置いても影響は限定的だ。我々はここで git ブランチ名、直近の CI 結果、オープン中の issue タイトルを取得し、エージェントのシステムプロンプトに追記している。これによりモデルは「今どの作業をしているか」を把握した状態で会話を始められる。
フック設計の原則
現場で得た教訓は三つある。第一に、フックは冪等にする。二度実行されても副作用が変わらない設計にしておくと再試行が怖くなくなる。第二に、タイムアウトを必ず入れる。外部 API を叩くフックが固まるとセッション全体が止まる。第三に、失敗時の出力をモデルに読めるメッセージにする。ブロック理由が「エラー」だけでは、モデルは次の手を打てない。
まとめ
hooks はプラグインの安全装置であり、同時に組織のポリシーをコードで表現する手段でもある。小さく始め、監査ログとタイムアウトの二点さえ押さえれば、後からルールを追加しても破綻しない土台が組める。