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

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

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

読了目安 約12分

allowManagedHooksOnlyとは

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

スコープはManagedです。書けるのはmanaged-settings.jsonかMDM経由の配布、またはサーバー管理設定だけです。既定値は未設定で、この場合は従来どおりすべてのスコープとプラグインのhookが動きます。

{
  "allowManagedHooksOnly": true
}

配布経路そのもの(サーバー管理・MDM・managed-settings.json・policy helperの使い分け)はClaude Code組織管理ガイドにあります。プラグインのhookを通す絞り方はstrictPluginOnlyCustomizationの記事が扱っています。

有効にすると何が動き、何が止まるか

trueにしたときの境界線は、hookの「出所」で引かれます。

くらべる

allowManagedHooksOnly: true のとき

組織の配布物

動く

  • 管理設定に書かれたhook
  • Agent SDKがプロセス内で登録するhook
  • 管理設定のenabledPluginsで強制有効化したプラグインのhook
それ以外すべて

止まる

  • ユーザー・プロジェクト・ローカルの設定ファイルのhook
  • 強制有効化されていないプラグインのhook
  • サブエージェントのfrontmatterに書いたhook

プラグインは名前ではなくplugin@marketplaceのフルIDで照合されます。同名でも別マーケットプレイス由来のプラグインは止まったままです。この仕様があるので、組織のマーケットプレイスで審査したhookだけを配り、残りを止める運用が成立します。

未設定のときのhookは、全ソースからマージされて動きます。組織のhookを配っても個人のhookは消えず、両方が並行して発火するのが既定です。allowManagedHooksOnlyはそのマージをやめ、管理設定側だけを残す一方向の絞り込みです。

HTTP型のhookには別の軸が1つ加わります。allowedHttpHookUrls(宛先URLの許可リスト)とhttpHookAllowedEnvVars(ヘッダーに埋め込める環境変数の許可リスト)は、管理設定を含むすべてのソースのHTTP hookに適用されます。前者が「どのソースのhookを動かすか」、後者が「動くhookがどこへ何を送れるか」を決めます。

無警告で消えるステータスラインとfile suggestion

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

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

同じ絞り込みは、allowManagedHooksOnlyを使っていなくても起きます。設定リファレンスでは、次の2つでも同じく「管理設定の値だけに絞る」と書かれています。

  • disableAllHooksをtrueにした設定が、管理設定以外のファイルで優先順位を経て有効になっている
  • claude --safe-modeで起動した

管理設定のdisableAllHooksと、ワークスペースの信頼を得ていないフォルダでは、絞り込みではなくそもそも無効になります。

Claude Code v2.1.287の--helpでは、--safe-modeは次のように説明されています。

claude --help
  --safe-mode   Start with all customizations (CLAUDE.md, skills, installed
                plugins, hooks, MCP servers, custom commands and agents, output
                styles, workflows, custom themes, keybindings, and more)
                disabled — useful for troubleshooting a broken configuration.
                Admin-managed (policy) settings still apply.

最後の1文が、ここまでの話と同じ構造です。管理設定は--safe-modeでも残るので、管理設定側のstatusLineは--safe-mode中も動きます。

コマンドソースプラグインと/goalの停止

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

マーケットプレイスのheadersHelperコマンドも同様にブロックされ、管理設定自身が宣言したマーケットプレイスだけが対象外です(v2.1.238以降)。

/goalは評価器がhookの仕組みの上で動くため、allowManagedHooksOnlyが設定されている間は実行できません。公式のgoalページでは、実行できないときにコマンドが理由を表示すると説明されています。変更履歴を見ると、v2.1.139で/goalが追加され、翌日のv2.1.140で「disableAllHooksかallowManagedHooksOnlyの設定時に応答が返らないまま止まる」不具合が修正されています。挙動の詳細は/goalコマンドの記事にあります。

hookだけ絞りたいのか、mod(プラグイン)だけ絞りたいのか

Claude Codeのプラグインには、コードでhookを登録する「mod」があります。modの管理ポリシーを説明する公式の管理者向けページは、似た3つのキーの射程を次のように並べています。

比較

modとhookを止める3つのキーの射程

  • allowManagedModsOnly

    組み込みガードのオプション(pluginConfigsにcc-plugin-sec-default@builtinをキーに書く)。ユーザー自身のmodだけを止め、ユーザーの設定ファイルのhook・ステータスライン・/goalは動き続けます。

  • allowManagedHooksOnly

    より広い設定です。組織のmodと組み込みmodだけが読み込まれ、ユーザーが入れたmodは止まります。加えてユーザー設定ファイルのhookも止まります。

  • disableAllHooks(管理設定)

    最も広い設定です。全プラグインのmodと、設定ファイルの全hookが止まります。管理設定のPreToolUse hookも何もブロックしなくなり、/goalとカスタムステータスラインも止まります。

強制有効化したプラグインのmodには条件があります。GitHub・git・URL・npmのソースからキャッシュにコピーされたプラグインは、管理設定のenabledPluginsで有効にしてもユーザーのものとして数えられます。そのためallowManagedModsOnlyやallowManagedHooksOnlyの下では読み込まれません。

allowManagedHooksOnlyの連鎖(ステータスライン・file suggestion・/goal)を避けたいときは、allowManagedModsOnlyという選択肢があります。

modが読み込まれなかった理由は、ユーザー側のデバッグログに出ます。公式のトラブルシュートページでは、allowManagedHooksOnlyが設定されている場合と、管理設定以外でdisableAllHooksが設定されている場合の拒否メッセージがonly managed plugins and built-in plugins runと載っています。

disableAllHooksとの使い分け

同じ「hookを止める」系のキーにdisableAllHooksがあり、役割が違います。

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

管理設定以外に書いたdisableAllHooksは、管理hookを止められません。管理設定に書くと、管理hookを含む設定済みのhookがすべて止まります。このとき動き続けるのはAgent SDKがプロセス内で登録するhookだけです(v2.1.242以降)。

管理設定のdisableAllHooksが不正な値だと、引用符付きの真偽値であっても警告つきで破棄されます。trueとして強制すると、組織自身が配るhookまで外れてしまうためです。展開前に値の型を確かめておくと安全です。

したがって、両方を管理設定に書く組み合わせに意味はありません。disableAllHooks: trueが効いている間は管理hookも止まるため、「全体停止」と「実行元の絞り込み」は別々の場面で選ぶ設定です。

allowManagedPermissionRulesOnly・allowManagedMcpServersOnlyとの違い

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

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

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

複数の管理設定ソースがあるときの値の決まり方

管理設定を複数の経路(たとえばサーバー管理とmanaged-settings.json)で配る組織では、managedSourcesBehaviorを"merge"にすると、すべての管理ソースが合成されます。管理設定ページの表では、allowManagedHooksOnlyは「Locks」に分類されています。

Locksは、どのソースかがtrueにしていればtrueが適用され、緩い値(falseなど)が効くのは最上位ソースが書いたときだけです。下位ソースでfalseと書いても、締める方向の値は覆りません。hooksのような配列キーが全ソースの合算になるのとは扱いが違います。

反映を確かめる

反映の確認は、対象マシンでClaude Codeを起動して/statusを実行し、Setting sources行を見ます。

/status

管理ソースが有効なとき、この行はEnterprise managed settingsに、選ばれたソースを括弧で添えて表示されます。

表示配布経路
(file) / (drop-ins) / (file + drop-ins)配布経路managed-settings.json、ドロップインディレクトリ、またはその両方
(remote)配布経路claude.aiまたはゲートウェイのサーバー管理設定
(plist) / (HKLM)配布経路MDMまたはOSのポリシー
(helper)配布経路MDMまたはファイルで指定したpolicyHelper(起動時に実行して管理設定を算出する実行ファイル)
(remote + file, merged)など配布経路複数ソースを合成した場合(v2.1.242以降)

管理ソースが見つかったのに選ばれなかった場合は、Skipped sources行がそのソースを挙げます。ポリシーがそもそも届いていないのか、届いたが優先度の高い別ソースに上書きされたのかを切り分けられます。公式の管理設定ページはこの行をv2.1.242以降としていますが、変更履歴でSkipped sourcesが追加された項目はv2.1.243の欄に載っています。v2.1.242の環境では、この行が表示されない可能性があります。

個々のhookの出所は、/hooksで読み取り専用で見られます。v2.1.281の変更履歴によると、フックが無効のとき、セーフモードのとき、managed-hooks-onlyのときにそれぞれ短い通知が出ます。効いているかどうかの一次確認は、/statusのSetting sources行が確実です。

展開前の確認手順

手順

allowManagedHooksOnlyを配る前に洗い出すこと

  1. 1

    コマンドソース型プラグインの有無

    使っているならdisableCommandPluginSources: falseを同時に書きます。書かないと、有効にした瞬間にそのプラグインが動かなくなります。

  2. 2

    /goalを使う運用フロー

    組み込んでいるなら、このキーを敷くと/goalが使えなくなります。段階指示など別の手段が必要になります。

  3. 3

    ステータスラインとfile suggestionを自前で使っているユーザー

    管理設定側でstatusLineやfileSuggestionを配るかどうかを先に決めます。配らなければ、ユーザーの表示は静かに標準へ戻ります。

  4. 4

    `/status`で反映を確認

    Setting sourcesとSkipped sourcesを見て、意図した管理設定ソースが選ばれているかを確かめます。

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

まとめ

止まる機能の代わりをどうするかが決まっていれば、敷く時期は組織の都合で選べます。決まっていないうちは、止まる範囲が狭いallowManagedModsOnlyから始める手があります。

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

関連する記事

Claude Code をもっと見る →