Claude CodeのallowedHttpHookUrlsでHTTP hookの送信先を制限する

allowedHttpHookUrlsは、type: "http"のHooksが送信先にできるURLをワイルドカードパターンで絞り込む設定キーです。既定は未設定で、どのURLでも呼び出せます。HTTP hookそのものの設定方法はClaude CodeのHooksをHTTPエンドポイントで受けるにあります。ここでは、送信先を制限する仕組みと、組織で配るときに起きやすい抜け道を扱います。

止まるのはHTTP hookだけ

Claude Codeは、このキーを定義すると、パターンのいずれかに一致するURLを持つHTTP hookだけを実行し、一致しないものは実行せずにブロックします。空の配列なら、すべてのHTTP hookがブロックされます。

HTTP hookだけを止めたいときは、すべての設定ファイルで合算した結果が空になっていれば、HTTP hookはすべて止まります。managed settingsだけを空配列にしても、User・Project・Localのパターンが残るため、組織で確実に止めるにはallowManagedHooksOnlyを併用します。Hooks全体を一時的に止めたいときは、送信先の許可リストではなくdisableAllHooksのほうが目的に合います。

ワイルドカードの書き方とホスト名の比較

パターンは*をワイルドカードとして使う文字列の配列です。次の例は、https://hooks.example.com/配下の任意のパスと、任意のポートのhttp://localhost宛てを許可します。

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

ホスト名の比較は大文字小文字を区別しません。末尾にピリオドを付けた完全修飾ドメイン名(hooks.example.com.)も、付けないhooks.example.comと同じホストとして扱われます。DNSが両者を同じ名前として解決する挙動に合わせた仕様なので、パターンの側で表記ゆれを気にする必要はありません。

個人の検証用途なら、http://localhost:*だけに絞れば足ります。手元に立てたHTTP hookサーバーの動作確認に向いた構成です。

配列は設定ファイルをまたいで合算される

このキーのスコープはAny fileで、~/.claude/settings.json・.claude/settings.json・.claude/settings.local.json・managed settingsのどれにも書けます。同名の配列は上書きではなく合算されるので、個人用のパターンをUser側に、プロジェクト固有のパターンをProject側に分けて書いても、実行時には両方が有効な許可リストになります。

この合算は、組織で配布する場合に効いてきます。managed settingsでallowedHttpHookUrlsを社内ドメインだけに絞ったとします。そこへ、リポジトリの.claude/settings.jsonや開発者の.claude/settings.local.jsonが別のパターンを足せば、そのセッションの許可リストは合算後の広い範囲になります。共有リポジトリの設定ファイルを信頼できない人が書き換えられる環境では、「managedで絞ったから安全」とは言えません。

同じ性質は、後述するhttpHookAllowedEnvVarsにもあります。許可リストで送信先を固定する発想は、Claude Code Channels組織管理で扱った許可プラグインの制限と同じ構図です。下位スコープが追記できる設定と、Managedにしか書けない設定を混同すると、意図より緩い状態で運用することになります。

ヘッダーの環境変数を絞るhttpHookAllowedEnvVars

HTTP hookはheadersに$MY_TOKENのような形で環境変数の値を埋め込めます。ただし埋め込めるのは、Hook自身のallowedEnvVarsに変数名を列挙したものだけで、列挙のない参照は空文字列に置き換わります。

httpHookAllowedEnvVarsは、このallowedEnvVarsに外側から上限をかけるキーです。変数がヘッダーに載るのは、Hook側のallowedEnvVarsとこのキーの両方がその名前を挙げているときに限ります。

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

Hookの定義が想定外のシークレットを要求しても、グローバル側に名前がなければ読み出せません。スコープはAny fileで配列が合算される点、managed settings由来のHookにも適用される点は、allowedHttpHookUrlsと同じです。

管理設定の値が不正なときは空の許可リストになる

managed settingsのallowedHttpHookUrlsにタイプミスや型違いがあった場合の挙動は、Claude Codeのバージョンで分かれます。

この境目はv2.1.267です。changelogには「managedのallowedHttpHookUrls・httpHookAllowedEnvVars・allowedChannelPluginsは、読めないときに何も許可しない」という修正項目があります。古いクライアントが混じるフリートでは、管理側の1文字の誤りが制限の消失に直結します。配布前のJSON検証と、クライアントのバージョンをそろえる運用に意味があるのは、このためです。

allowManagedHooksOnlyとの役割分担

似た目的のキーにallowManagedHooksOnlyがあります。制限する対象がまったく違います。

allowManagedHooksOnlyはManagedスコープにしか書けないので、ユーザーやプロジェクトが独自のHTTP hookを足せないようにしたいなら、allowedHttpHookUrls単体より確実です。有効な間は、statusLine・fileSuggestion・subagentStatusLineもmanaged settings由来に絞られ、Hookに依存する/goalは使えなくなります。

送信先・ヘッダー・実行元を組織側で固定する

3つのキーを組み合わせたmanaged-settings.jsonの例です。送信先、ヘッダーに載せられる変数、実行できるHookの出どころを、すべて組織側に寄せています。

{
  "allowedHttpHookUrls": ["https://hooks.internal.example.com/*"],
  "httpHookAllowedEnvVars": ["HOOK_SECRET"],
  "allowManagedHooksOnly": true
}

Agent Teams Hooksで強制する品質ゲートの仕組みのように、Hookで品質ゲートを全社に強制する構成に向いた形です。ゲート用HTTP hookの送信先とシークレットを固定でき、開発者が独自のHookでゲートを迂回する道も塞げます。

信頼していないリポジトリを-pで回すとき

合算の影響が最も出やすいのは、他人が書いた.claude/settings.jsonを含むリポジトリを実行する場面です。ワークスペースの信頼の扱いは、セッションの種類で分かれます。

対話セッションでは、フォルダの信頼ダイアログを承認するまで、~/.claude/settings.jsonを含むすべての設定ファイル由来のHookが保留されます。-pやAgent SDKのセッションではダイアログが出ず、フォルダは信頼済みとして扱われるため、リポジトリにコミットされたHookもそのまま走ります。

他人のリポジトリでclaude -pをスクリプト実行するときは、次のフラグで読み込む設定を絞れます(claude --help、v2.1.289)。

--settings '{"disableAllHooks": true}'で、その実行だけHookを止める方法もあります。許可リストは下位スコープからの追記で広がることがあるため、信頼できないリポジトリでは、これらのフラグで読み込み自体を絞る手があります。

まとめ

allowedHttpHookUrlsはHTTP hookのurlだけを見る設定キーで、Hookの出どころまでは縛れません。組織で送信先を固定するなら、managed settingsでの定義に加えて、下位スコープからの追記を許さないallowManagedHooksOnlyと、クライアントのバージョンをそろえる運用が組み合わせの要になります。配布前にJSONを検証し、/statusで効いている設定を確かめる流れまで含めて運用します。