Claude Media
allowManagedHooksOnlyでhookを組織限定にする際の連鎖的な影響
Claude CodeTips

allowManagedHooksOnlyでhookを組織限定にする際の連鎖的な影響

allowManagedHooksOnlyはhookの実行元を管理設定に絞る一方、statuslineやfile suggestion、/goalの動作まで連鎖的に制限します。設定例とdisableAllHooksとの違いを扱います。

読了目安 約8分

allowManagedHooksOnlyとは

allowManagedHooksOnlyは、管理設定(managed settings)で配布したhookだけを動かし、ユーザー・プロジェクト・ローカルの設定ファイルやプラグインが持ち込むhookを止める設定キーです。trueにすると、実行できるhookの出所が組織側の配布物だけに絞られます。効果はhookの発火そのものにとどまりません。ステータスラインとファイル候補コマンド、コマンドソース型プラグイン、/goalコマンドまで連鎖的に制限がかかります。

スコープはManaged。つまり書けるのはmanaged-settings.jsonかMDM経由の配布、またはサーバー管理設定に限られ、ユーザーの~/.claude/settings.jsonやプロジェクトの.claude/settings.jsonに書いても無視されます。既定値は未設定で、この場合は従来どおりすべてのスコープとプラグインのhookが動きます。設定できるのは組織の管理者側だけで、開発者本人が自分の設定ファイルで有効・無効を切り替えることはできません。

managed settingsへの書き方と反映確認

配布経路そのもの(サーバー管理・MDM・managed-settings.json・policy helperの使い分け)はClaude Code組織管理ガイドに譲ります。ここではallowManagedHooksOnly単体の書き方だけを示します。

{
  "allowManagedHooksOnly": true
}

反映されたかどうかは、対象マシンでClaude Codeを起動して/statusを実行し、Setting sources行を見れば確認できます。

/status

managed-settings.jsonから読み込んだ場合はEnterprise managed settings (file)のように表示されます。サーバー管理設定なら(remote)、MDMやOSポリシーなら(plist)または(HKLM)です。複数の管理設定ソースをマージした環境では(remote + file, merged)のような表記になり、Skipped sources行で読み込まれなかったソースも確認できます(この行はv2.1.242以降)。

ファイルを静的に配る以外に、policyHelperで管理設定を動的に生成する方法もあります。MDMポリシーやmanaged-settings.jsonで実行可能ファイルを指定すると、Claude Codeは起動のたびにそれを実行し、標準出力のmanagedSettingsオブジェクトをそのセッションの管理設定として扱います。組織や役職ごとにallowManagedHooksOnlyの値を出し分けたい場合など、静的なJSONでは対応しにくいケースに向いています。

個々のhookがどこから来ているかは/hooksコマンドでも読み取り専用で確認できます。イベントごとの件数とmatcher、ハンドラの中身まで見られますが、allowManagedHooksOnlyが実際に効いているかどうかの一次確認は/statusのSetting sources行で行うのが確実です。

hookの実行元はどこまで絞られるか

allowManagedHooksOnlyを有効にすると、Claude Codeは次のhookだけを実行します。

  • 管理設定(managed settings)に書かれたhook
  • Agent SDKがプロセス内で登録するhook
  • 管理設定のenabledPluginsで強制有効化されているプラグインが持つhook(プラグイン名だけでなくplugin@marketplaceのフルIDで一致を見るため、同名でも別マーケットプレイス由来のプラグインは対象外になります)

ユーザー・プロジェクト・ローカルの設定ファイルのhook、それ以外のプラグインのhook、スキルやサブエージェントのfrontmatterに書いたhookはすべて動きません。この設定を敷いていない状態では、hookは全ソースからマージされて動きます。組織のhookを配っても個人やプロジェクトのhookは消えず、両方が並行して発火するのが既定の挙動です。allowManagedHooksOnlyはこのマージをやめ、管理設定側だけを残す一方向の絞り込みです。

HTTP型のhookに限っては、絞り込みの軸がもう一つ増えます。allowedHttpHookUrls(宛先URLの許可リスト)とhttpHookAllowedEnvVars(ヘッダーに埋め込める環境変数の許可リスト)は、管理設定を含むすべてのソースのHTTP hookに一律で適用されます。allowManagedHooksOnlyが「どのソースのhookを動かすか」を決めるのに対し、この2つは「動くhookがどこへ何を送れるか」を決める別軸の制限です。両方を管理設定に書けば、実行元と送信先の両方を組織側で固定できます。

statuslineとfile suggestionが連鎖して止まる理由

allowManagedHooksOnlyという名前からは権限まわりの設定に見えますが、実際に読みに行く対象はhookだけではありません。statusLine・subagentStatusLine・fileSuggestionの3つも、管理設定の値だけに絞られます。

管理設定側でこれらのキーを配っていれば、その値が動きます。配っていなければ、ユーザーが自分の設定ファイルに書いたカスタムステータスラインやファイル候補コマンドは、警告なしにスキップされます。ステータスラインは非表示になり、@によるファイル候補は組み込みの検索にフォールバックします。

同じ絞り込みは、allowManagedHooksOnlyを設定していない場合にも起こり得ます。管理設定側でdisableAllHooksをtrueにしたとき、フォルダがワークスペースの信頼を得ていないとき、そして--safe-mode付きで起動したときも、同じ「管理設定の値だけに絞る」ゲートを通ります。管理設定に値が無ければ、これらのどのケースでもステータスラインとfile suggestionは無警告で無効化されるという結果は同じです。

コマンドソースプラグインと/goalへの影響

allowManagedHooksOnlyはプラグインの取得元にも波及します。マーケットプレイスのコマンドソース(コマンドを実行してプラグインを配る方式)は、disableCommandPluginSourcesを明示的にfalseにしない限り既定でブロックされます。disableCommandPluginSources自体は未設定だとallowManagedHooksOnlyの値に従う仕様なので、コマンドソースを使い続けたい組織はfalseを明示する一手間が要ります。これは管理設定のenabledPluginsで強制有効化したプラグインでも例外ではありません(コマンドソース自体はv2.1.229以降の機能)。マーケットプレイスのheadersHelperコマンドも同様にブロックされ、こちらは管理設定自身が宣言したマーケットプレイスだけが対象外です(v2.1.238以降)。

もう一つの影響先が/goalコマンドです。/goalは内部でhookの仕組みに依存しているため、allowManagedHooksOnlyが設定されている間は実行できません。v2.1.139で/goalが追加された直後は、この状態で呼ぶとインジケータが回り続けたまま応答が返らない不具合がありましたが、v2.1.140で「hookポリシーにより実行できません」という明示メッセージを返す形に修正されています。挙動の詳細は/goalコマンドの記事で扱っています。

disableAllHooksとの使い分け

同じ「hookを止める」系のキーにdisableAllHooksがあり、役割が違うため混同すると設定ミスにつながります。

観点allowManagedHooksOnlydisableAllHooks
書ける場所allowManagedHooksOnly管理設定のみdisableAllHooks任意の設定ファイル(管理設定以外に書くと管理hookは止められない)
効果allowManagedHooksOnlyhookの実行元を管理設定・SDK・強制有効化プラグインに絞るdisableAllHookshook自体をオン/オフする(削除はしない)
ステータスライン・file suggestionallowManagedHooksOnly管理設定の値だけに絞る(未配布なら無警告で無効)disableAllHooks管理設定でtrueにした場合は全停止、それ以外の場所では自分のhook・ステータスライン・file suggestionだけ止まる
向く場面allowManagedHooksOnly個人・プロジェクトのhookを恒久的に締め出し、組織配布だけを許可したいdisableAllHooks一時的に全hookを止めて動作確認したい、または管理設定側で緊急停止したい

管理設定に両方を同時に書く運用も可能です。disableAllHooksで全体を一時停止しつつ、解除後はallowManagedHooksOnlyで個人・プロジェクトのhookが混ざらない状態に戻す、という組み合わせが使えます。どちらも管理設定側からしか管理hookを止められない点は共通しています。

allowManagedPermissionRulesOnly・allowManagedMcpServersOnlyとの違い

設定リファレンスの索引では、allowManagedHooksOnlyはallowManagedMcpServersOnly・allowManagedPermissionRulesOnlyと並んで載っています。名前が似ているため、1つ設定すれば他も一緒に絞られると誤解しやすいところですが、対象はキーごとに完全に分かれています。

キー絞り込む対象
allowManagedHooksOnly絞り込む対象hookの実行元(managed / SDK / 強制有効化プラグインのみ)。statusline・file suggestion・コマンドソースプラグインも道連れ
allowManagedPermissionRulesOnly絞り込む対象権限ルールの定義元。managed設定以外のpermissions設定を無効化する
allowManagedMcpServersOnly絞り込む対象有効なMCPサーバーの一覧。managed設定のallowedMcpServersだけを適用する

組織のhook・権限・MCPサーバーをすべて管理設定側に固定したい場合は、この3つを同時にtrueへ設定する必要があります。1つだけでは、残り2つの領域はユーザー・プロジェクトの設定がそのまま生き続けます。

導入前に確認しておきたいこと

  • コマンドソース型プラグインを使っているか: 使っている場合はdisableCommandPluginSources: falseを明示しないと、allowManagedHooksOnlyを有効にした瞬間にそのプラグインが動かなくなります
  • /goalを運用フローに組み込んでいないか: 組み込んでいる場合、このキーを敷くと代替の指示手段(対話モードでの段階指示など)に切り替える必要があります
  • カスタムステータスラインやfile suggestionを配布していないユーザーがいないか: 管理設定側でstatusLineやfileSuggestionを配っていない場合、そうしたユーザーの表示は静かに標準へ戻ります。展開前に管理設定側でも同じ値を配るかどうかを決めておくと、問い合わせを減らせます
  • 反映確認は/statusで行う: Setting sourcesとSkipped sources(v2.1.242以降)を見れば、意図した管理設定ソースが実際に選ばれているかが分かります。設定ファイルを置いただけでは、優先順位の高い別のソースに上書きされていないかまでは分かりません
  • ローカル管理者権限を持つ開発者がいないか: マシン上で管理者権限を持つ開発者は、managed-settings.json本体やレジストリ/plistの管理設定を自分で書き換えられます。全社一律で強制したい場合は、MDMによる定期再配布などローカル改変を上書きする仕組みと組み合わせる必要があります

プラグインが配布するsubagentStatusLineの扱いなど、プラグイン配布側の細部はプラグインのsettings.json記事にあります。

まとめ

allowManagedHooksOnlyはhookの実行元を管理設定に絞る一本のキーですが、実際に触れる範囲はhookだけではありません。ステータスライン、file suggestion、コマンドソース型プラグイン、/goalまで、hookの仕組みに乗っている機能はまとめて管理設定の管轄に入ります。権限やMCPサーバーまで含めて組織側に固定したいときは、allowManagedPermissionRulesOnlyやallowManagedMcpServersOnlyとの組み合わせも合わせて検討します。導入するなら、対象になる機能を先に洗い出してから配布するのが安全です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →