Claude Codeのplugin hookをvalidateとcatchで審査する

結論：validateの成功と導入許可を分ける

一次情報は公式changelog、Plugins公式概要、Plugins referenceです。pluginはskill、agent、hook、MCPなどを一単位で配布できますが、検証が通ったことは、そのcomponentが自社データへ安全に触れることを意味しません。既存のmarketplaceとplugin validateの記事はsourceとmanifestの分離が主題で、本稿はhookの失敗と監査情報に絞ります。

2.1.290の検証項目を読む

項目	何が分かるか	導入審査で追加すること
gatingHooks	gating siteのhookとcatch有無	失敗時に止まるか、通るか、通知するか
agentId	subagentかmain sessionか	権限と監査担当を分ける
serverToolUses	modがAPIへ実行したtool call	対象、時刻、目的、保持範囲を決める
validate結果	構造・登録内容の確認	source、SHA、component、rollbackを照合

.catchがあるから失敗が安全に処理されるとは限りません。例外を握りつぶす実装なら監査価値を失います。逆に失敗を必ず通さない設計なら、業務停止の影響を説明できるように、対象操作と代替手順を台帳へ入れます。

8手順でplugin hookを検証する

1. Claude Codeのversion、pluginのrevision、取得元、SHAを保存します。
2. 本番データのないsandbox repositoryで対象pluginを展開します。
3. claude plugin validate --jsonを実行し、出力原本と実行環境を記録します。
4. gatingHooksの一覧、hook名、site、catch有無を表にします。
5. catchがあるhookへ成功・拒否・例外の3ケースを入力し、挙動を確認します。
6. main sessionとsubagentを分け、tool.checkのagentIdが監査記録に残るか確認します。
7. modのturn.stepが使うserver tool、引数の分類、外部通信先、保持期間をレビューします。
8. 不合格時の無効化、前revisionへのrollback、再検証責任者を決めてから限定配布します。

hookのテストで実サービスへ書き込まず、read-only endpointとダミー入力を使います。ログへprompt本文、token、社内pathを出さないようにし、必要な監査項目はIDと分類で残します。validateの終了コードだけを承認根拠にしないことがポイントです。

hookの失敗処理を比較する

設計	向く場面	確認するリスク
fail closed	外部送信、権限変更、破壊的操作	業務停止時の代替手順と承認者
fail open	表示・計測など副作用のない補助処理	例外が見えず監査が欠ける可能性
catchして通知	監視や診断を継続したい処理	通知先、再試行、重複実行、秘密情報

権限設計はPermissionsガイド、拡張の到達範囲はModsの安全確認、動的な読み込みはplugin-dirの手順と接続できます。ただし、hookのcatchを導入するときは、利用者への通知と監査ログの責任者まで決めます。

レビュー記録に残すべき差分

hook審査では、JSONの全量を保存するだけでは不足します。前回revisionから変わったhook名、gating site、catchの有無、参照する環境変数、呼び出すtoolを差分表にします。hookが読み取るpromptやファイルの分類も、本文を保存せず「顧客情報」「ソースコード」「公開情報」のような区分で残します。serverToolUsesは件数だけでなく、失敗時の再試行と同一IDの重複を確認します。

審査会では、技術担当が「動く」ことを示し、業務責任者が「動いてよい」範囲を決めます。catchで処理を継続する場合は、利用者に表示する警告、監視が拾うイベント、再実行を止める条件を一枚にします。pluginを更新するたびに同じ試験を再実行できるfixtureを用意し、担当者が変わっても判断基準が変わらないようにします。

審査結果には、合格・条件付き・保留の三つの状態を持たせます。catchがあるが通知がない、agentIdは取れるが保持期間が未決定、serverToolUsesが記録されるが目的が説明できない、といった場合は条件付きにします。条件付きのpluginを全員へ配布せず、期限と所有者を付けて少人数の検証へ戻すことで、検証情報を安全な導入判断へつなげられます。

hookのログは、監査に必要な識別子と、秘密情報・顧客本文を分けて設計します。失敗したhookを自動retryすると外部toolが二重に動くことがあるため、retry回数、backoff、重複排除キーを決めます。gating hookの失敗を利用者へ見せる場合は、内部例外をそのまま表示せず、問い合わせIDと安全な次の行動を提示します。これが運用設計まで含めた審査の境界です。

公開前チェックリスト

• 2.1.290以上とplugin revisionを記録した
• validateのJSON原本を保存した
• gatingHooksとcatch有無を一覧化した
• 成功・拒否・例外をsandboxでテストした
• agentIdでmainとsubagentを区別した
• serverToolUsesの対象・目的・保持を決めた
• 無効化、rollback、再検証の担当を決めた

企業導入では、hookを作った人と配布を承認する人を分けます。pluginのversionが変わらなくてもsourceやhookが変わる運用なら停止条件にし、marketplaceのcatalog、個別plugin、実行時設定を同じレビュー単位にしません。変更差分と検証結果を一緒に保管すれば、問題発生時に「どのhookが、誰のsessionで、何をしたか」を説明できます。

FAQ

plugin validateが通れば安全に導入できますか？

いいえ。validateは構造・検証結果の確認であり、hookの権限、外部通信、対象データ、更新、rollbackは別に審査します。

gating hookにcatchが必要なのはなぜですか？

gating siteで例外処理がないhookは、失敗時の挙動を説明しにくいためです。JSON結果と実行テストを併用します。

plugin審査の設計を相談できますか？

できます。source、component、hook、権限、監査、rollbackを無料診断（60秒）で整理します。