- ユーザーの独自 mod を除外する(独自の mod の有無を問わず): ユーザーがインストールした mod の読み込みを停止する
- 何も変更しない場合に何が起こるかを確認する: デフォルトで何が起こるかを理解する
- mod を有効にして他の制限を設定する: 許可する範囲を選択する
以下のケースは他のページで説明されています。
- 管理設定をまだデプロイしていない: 管理設定をデプロイする から始めてください
- ユーザーがインストールできるプラグインを制御したい: 組織向けのプラグインを管理する を参照してください
ユーザーがインストールした mod の読み込みを停止する
ユーザーが持ち込むすべての mod がフックを実行しないようにするには、組み込みガード(Claude Code がユーザーがインストールするすべての mod の前に読み込むポリシー mod)でallowManagedModsOnly オプションを設定します。このオプションは、管理設定の pluginConfigs に cc-plugin-sec-default@builtin をキーとして配置します。
managed-settings.json
- ユーザーが持ち込む mod はフックを実行しません:ユーザーがインストールしたプラグイン内の mod、
--plugin-dirで読み込まれた mod、および Claude がセッション中に作成した mod が対象です - 組織の mod は引き続き実行されます:組織のものとしてカウントされる mod はチェックされません。その他のすべての mod はユーザーのものとしてカウントされ、拒否されます。これには、組織が claude.ai でメンバー向けにオンにした mod も含まれます。組織のものとしてカウントされるものがない場合、インストールされた mod はいずれもフックを実行しません。
- ユーザーはこれを元に戻せません:ガードは管理設定からのみオプションを読み取るため、ユーザー、プロジェクト、またはローカル設定ファイル内の同じエントリ、または
--settingsで渡されたファイル内のエントリは何も変わりません - ファイルまたは MDM ポリシーはすべてのプロバイダーに対応します:オプションをファイルとして、または MDM を通じて配信する場合、Amazon Bedrock、Google Cloud の Agent Platform、および Microsoft Foundry で同じように機能します。claude.ai 管理コンソールからの配信については、プラットフォームの可用性 を参照してください
- ユーザーの他のカスタマイズは引き続き機能します:設定ファイル内のフックやプラグインの
hooks/hooks.json内のフック、ステータスライン、および/goalは影響を受けません - 組み込み mod は引き続き実行されます:
AGENTS.mdサポートなど Claude Code に組み込まれた mod には、それぞれ独自のスイッチ があります
--plugin-dir と mod を保持するディレクトリのパス(例:claude --plugin-dir ./first-mod)を使用して Claude Code を起動します。mod のフックは実行されず、トランスクリプトとデバッグログに ガードのメッセージ が表示されます。このメッセージは mod と allowManagedModsOnly の名前を示します。このメッセージが表示されない場合は、ポリシーが有効であることを確認する および オプションが有効になるかどうかを決定するルール を参照してください。
早期アクセス中に CLAUDE_CODE_ENABLE_FUNCTION_HOOKS を 0 に設定した場合は、このオプションに置き換えてください。Claude Code v2.1.287 以降は、任意の値で変数を無視するため、そこに 0 があると mod は有効なままになります。
デフォルトで何が起こるかを理解する
独自の mod 設定がない場合、ユーザーは以下を取得します。-
Mod は有効です。 ユーザーは、プラグイン設定が許可するマーケットプレイスから mod を含むプラグインをインストールするか、
--plugin-dirを使用してディレクトリから読み込むことができます。 -
組み込みガードが最初に実行されます。 Claude Code は、ユーザーがインストールしたすべての mod の前に、
sec-default@builtinという名前の組み込み mod を読み込みます。ユーザーはそれをオフにすることはできません。/pluginとデバッグログは、それをcc-plugin-sec-defaultとして一覧表示します。ガードは以下のいずれかが真の場合に読み込まれます。- マシンに管理設定または
managed-mcp.jsonファイルがある - セッションが Team または Enterprise プランの
/login認証情報で実行されている
managed-mcp.jsonを持つマシンでのみガードを取得します。長期間有効なCLAUDE_CODE_OAUTH_TOKENで実行されるセッションも、マシンに Team または Enterprise のログインが保存されている場合でも、そのログインとは見なされません。 - マシンに管理設定または
-
ガードは管理対象を保護します。 ユーザーの mod は、管理フックが受け取るものや判断する内容、システムプロンプト、管理対象の
CLAUDE.mdおよびその他の管理対象の指示を変更することはできません。また、いずれかの mod が設定として読み取るもの、および接続後の管理対象の MCP サーバーのツールと説明も変更できません。 -
v2.1.323 以降では、ユーザーの mod は管理対象の MCP サーバーの接続を妨げることができます。 そのユーザーのセッションでは、
/mcpはそのサーバーをその mod によって保留されているものとして一覧表示します。これを防ぐには、ユーザーがインストールした mod が読み込まれないようにします。 - 管理対象外では、ユーザーの mod はそのユーザーとして動作します。 mod はそのユーザーの権限を保持します。ファイルの読み取りと書き込み、プロセスの開始、ネットワークリクエストの実行は引き続き可能です。また、ツール呼び出しとプロンプトの書き直し、ツール呼び出しの拒否、ツールの追加や削除、インターフェイスへの描画も可能です。
-
権限ルールと
PreToolUseフックはユーザーの mod より優先されます。 ガードが読み込まれている場合、デフォルトでは、ユーザーの mod はdenyルールが拒否する呼び出しやaskルールがプロンプトを表示する呼び出しを承認できません。ルールがどの設定ファイルにあるかは問いません。また、いずれかのPreToolUseフックがブロックした呼び出しも承認できません。 権限ルールとPreToolUseフックは Claude のツール呼び出しに適用され、mod 独自の$.fsと$.process呼び出しには適用されません。Read(.env)が拒否されている場合でも、mod は$.fs.readでそのファイルを読み取ったり、それを行うプログラムを開始したりできます。mod 独自の$.fsと$.process呼び出しを制限するには、mod の読み込みを防ぐか、ポリシー mod で処理してください。 -
ユーザーの mod は一部のプロンプトを引き続きスキップできます。 auto モードでは、mod が承認する呼び出しは分類器チェックなしで実行されます。ただし、ガードが読み込まれ、セッションが
--permission-prompt-toolまたは Agent SDK のcanUseToolコールバックで実行されている場合は除きます。その場合は、分類器が先に呼び出しをチェックします。mod の承認でスキップされないプロンプトについては、フックで権限を拡張する を参照してください。
mods/sec-default ディレクトリ で公開されています。
どのコントロールが引き続き適用されるかを知る
Mod は既に持っているコントロールを置き換えません。-
設定フックは引き続き機能します。 設定ファイルおよびプラグインの
hooks/hooks.json内のコマンド、HTTP、プロンプト、エージェントフックは以前と同じように実行され、mod と並行して実行されます。 -
拒否ルールはガードが読み込まれる場所で優先されます。 ユーザーの mod は、
denyルールが拒否する呼び出しを承認することはできません。ただし、allowModsToOverrideDenyRulesを設定する場合を除きます。 -
管理フックが最初に実行されます。 管理設定の
PreToolUseフックは、いずれの mod のtool.callフックよりも前に実行され、その管理フックがツール呼び出しをブロックした場合、その呼び出しに対して mod のtool.callフックは実行されません。呼び出しが続行され、mod がそれを書き直した場合、管理フックは書き直された呼び出しで再度実行されるため、デフォルトでは引き続きブロックできます。 他の設定ファイルおよびプラグインからのPreToolUseフックは、最後の mod の後に実行されます。mod がツール呼び出しに自ら応答した場合、ツールは実行されず、それらのフックも実行されません。Mod が実行される順序 を参照してください。 -
ネットワークポリシーは
$.http.fetchをカバーします。-
組織のポリシーで WebFetch が許可されていない場合: Claude Code はすべての mod の
$.http.fetchリクエストも拒否します。WebFetch の利用可否 を参照してください。 -
管理設定またはその他の設定ファイルで、
CLAUDE_CODE_DISABLE_WEB_FETCHまたはWebFetchの拒否ルールを使用して WebFetch ツールをオフにした場合: mod は引き続き$.http.fetchリクエストを実行できます。 ユーザーがインストールするすべての mod についてこれを停止するには、ユーザーがインストールした mod が読み込まれないようにするか、ポリシー mod でhttp.fetchをフックし、ユーザーの mod からのリクエストを拒否してください。Claude Code は失敗したフックをスキップし、その場合リクエストはそのまま実行されるため、そのフックには同様に拒否する.catchハンドラーを指定してください。ユーザーがインストールできるプラグインを制限するだけの場合、読み込まれる mod は減りますが、許可した mod は引き続きこれらのリクエストを実行できます。 -
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICを設定した場合: 管理者自身またはユーザーがインストールした mod は、引き続きこれらのリクエストを実行できます。この変数が停止するのは、Claude Code に組み込まれた mod と、セッションの Anthropic 認証情報を含む$.http.fetchリクエストのみです。v2.1.288 より前は、この変数はすべての mod の$.http.fetchリクエストを停止していました。
$.process.runで開始するプログラムはカバーしません。そのプログラムはユーザー独自のアクセスでネットワークに到達します。 -
組織のポリシーで WebFetch が許可されていない場合: Claude Code はすべての mod の
-
プラグインコントロールは mod をカバーします。 Mod はプラグインであるため、ユーザーがインストールできるものを制限する設定(
strictKnownMarketplacesなど)は、それをインストールできるかどうかを決定します。 - Mod は権限プロンプトを変更できません。 Mod は Claude Code のインターフェイスの大部分を再スタイル化できますが、権限プロンプトはできないため、プロンプトが表示するものを変更できません。Mod は、デフォルトで何が起こるかを理解する で説明されているように、プロンプトが表示される前にツール呼び出しを承認または拒否できます。
- 信頼プロンプトが最初に表示されます。 ユーザーがまだ信頼していないディレクトリでのインタラクティブセッションでは、信頼プロンプトに答えるまで mod は読み込まれません。
-
--safe-modeはインストールされた mod をオフにします(独自の mod を含む)。 セッションをclaude --safe-modeで開始して、mod が問題を引き起こしたかどうかを確認します。
ユーザーの mod のどのフックが実行されないかを知る
組み込みガードが読み込まれる環境では、ユーザーの mod が以下のいずれかのイベントに登録したフックは実行されず、/plugin がそのことを注記でそのユーザーに伝えます。session.append の行では、door はフックのフィルタリング対象となる保存済みの行の種類です。
ガードは、
tool.describe での組織のツールの説明や、スキルのテキストの保存済みの行など、その他の場合にもユーザーのフックをスキップします。これらについては、/plugin は注記を表示しません。他のイベントのフックが何もしない場合は、mod が何もしない理由を調べるを参照してください。
注記は、プラグインの詳細と /plugin の Errors タブに表示されます。これには Claude Code v2.1.299 以降が必要です。注記は、次の例のように、表にある各フックを mod が登録したとおりの名前で示します。
- mod を組織のものとして実行する: mod を組織独自のものと見なされるようにインストールします。これにより、これらのイベントに対するそのフックが実行され、他のすべての mod に対してはガードが読み込まれたままになります。この mod はこれらの設定を受け取るすべてのユーザーに対して有効になります。
prependPluginsにこの mod を記載する場合は、sec-default@builtinをリストに残してください。 - ガードを削除する:
prependPluginsからsec-default@builtinを除外します。空のリスト"prependPlugins": []で十分です。失われるのはこれらのイベントだけでなく、ガード全体です。その場合、ユーザーの mod はガードが本来防いでいることを実行できるようになり、ガードのオプションも適用されません。
/plugin を開き、注記が消えていることを確認してください。
door フィルターのない session.append フックは引き続き実行され、注記も表示されませんが、表にある保存済みの行はそのフックに届きません。
Mod を有効にするかどうかを決定する
Mod は、Claude Code 内で実行されるため、プラグインの他の部分よりも多くのことができます。すべてのプロンプトとツール呼び出しを見ることができ、それらを変更でき、権限プロンプトが表示される前にツール呼び出しを許可または拒否できます。 ユーザーが mod として読み込むことができるものは、既に持っているプラグインコントロールに依存します。
組織向けのプラグインを管理する は、プラグインが読み込まれる方法と各方法を制御する設定を一覧表示しています。
ユーザーがインストールする前にマーケットプレイス内の mod を確認するには、mod が実行できることを確認する を参照してください。ユーザーの mod を確認するまで除外するには、ユーザーがインストールした mod の読み込みを停止する を参照してください。
Mod が実行できることを確認する
実行せずに mod が実行できることを確認できます。シェルで、プラグインのディレクトリでclaude plugin validate を実行します。
hooks: 行と calls: 行は mod のコードを説明しています。
hooks:: mod が受け取るイベント。default matcher key: pluginという注記は、その前にあるフックが他の mod のコントロールと描画をスキップすることを意味します。calls:: mod のコードが呼び出す mods API メソッド
$ と記述)は、mod がファイル、プロセス、ネットワークに到達する方法です。Claude Code は、このコマンドが読み取ることができない方法で mods API を使用する mod の読み込みを拒否します。
一部の失敗は mod の読み込みを妨げないため、このコマンドが失敗する mod は承認しないでください。このコマンドは Claude Code v2.1.323 以降で実行してください。このバージョンでは、長い一覧は同じラベルの付いた複数の行に続けて表示されます。すべての hooks: 行と calls: 行を読んでください。calls: 行では、次のものを探してください。
hooks: 行では、tool.call と prompt.submit は mod がすべてのツール呼び出しとすべてのプロンプトを見ることができ、それらを変更できることを意味しています。session.append は、ガードが対象外とする行を除き、mod が保存される前に会話の各行を書き直すことができることを意味しています。ui.render{component=AskUserQuestion} は mod が Claude がユーザーに質問するために使用するダイアログを再描画できることを意味しています。tool.check は mod が権限プロンプトが表示される前にツール呼び出しを承認または拒否できることを意味しています。デフォルトで何が起こるかを理解する は、設定済みのルールとフックのうち、どれがその答えより優先されるかを一覧表示しています。
許可する範囲を選択する
mod ポリシーは、インストールされた mod をまったく許可しないものから、ユーザーが選んだ任意の mod を許可し、独自の mod で他の mod をチェックするものまであり、いずれも数個の管理設定で構成されます。最初の列で必要なポリシーを見つけ、2 番目の列に記載されているものを設定します。管理設定をデプロイする は、管理設定がどこに存在するかをカバーしています。
各設定が実行すること。
allowManagedModsOnly: 組み込みガードのオプション。Claude Code はユーザー独自の mod を拒否するため、そのフックは一切実行されません。ユーザーの設定フック、ステータスライン、/goalは引き続き機能します。ユーザーがインストールした mod の読み込みを停止する はそれがカバーするものを一覧表示しています。allowManagedHooksOnly: より広い設定。組織の mod と Claude Code に組み込まれた mod のみが読み込まれます。ユーザーが自分でインストールした mod は読み込まれません。設定はユーザー独自の設定ファイル内のフックもブロックします。設定する前に 「allowManagedHooksOnlyの下で実行されるもの」 を読んでください。disableAllHooks: 最も広い設定。管理設定では、インストールされたすべてのプラグイン(組織のものを含む)の mod を停止し、設定ファイル内のすべてのフックをオフにするため、管理設定のPreToolUseフックはもはや何もブロックしません。カスタムステータスラインと/goalも機能しなくなります。設定する前にdisableAllHooksを読んでください。disableSideloadFlags: スタートアップで--plugin-dirと--plugin-urlを拒否し、Claude がセッション中に作成した mod の読み込みを防ぎます。設定は--agentsと--mcp-configも拒否します。設定する前にdisableSideloadFlagsを読んでください。
AGENTS.md サポートなど)は、これらの設定の影響を受けません。各 mod には 独自のスイッチ があります。
mod が拒否された、または読み込まれなかったユーザーは、デバッグログで理由を見つけます。拒否メッセージ は allowManagedHooksOnly と disableAllHooks の行を一覧表示し、組み込みガードからのメッセージ は allowManagedModsOnly の行を持っています。
組織の mod のみを許可する
組織の mod を実行し、ユーザーが持ち込む mod をブロックするには、ポリシー表 の 組織の mod のみ の行の設定に加えて、disableSideloadFlags をデプロイします。次の完全な managed-settings.json を使用すると、Claude Code はユーザー独自の mod を拒否するため、そのフックは一切実行されず、ポリシー mod は他の mod より先に実行されます。
managed-settings.json
extraKnownMarketplaces、enabledPlugins、prependPlugins: mod を組織のものとしてカウントされるようにインストールし、最初に実行して、その後にガードを実行します。組織の mod をインストールして順序を設定する では、これらのキーが指すディレクトリについて説明しています。pluginConfigs: ガードのallowManagedModsOnlyオプションを設定し、Claude Code がユーザー独自の mod を拒否するようにします。ユーザーの設定フック、ステータスライン、/goalは引き続き機能します。disableSideloadFlags: スタートアップ時に拒否されるフラグについては、disableSideloadFlagsを参照してください
claude --debug を使用してセッションを開始し、デバッグログを読みます。
- 組織の mod: その
hooks module行にtier prependが含まれます - ユーザーがインストールした mod:
refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly)という行があります。それより前の行では、その mod のフックモジュールがloadedと表示されるため、拒否の行を探してください。 - プラグインディレクトリ:
claude --plugin-dir ./any-modは、--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)で始まるメッセージを表示して終了します
プラグインの制御を mod に適用する
mod はプラグインであるため、組織のプラグインを管理する 方法は、mod を含むプラグインにも適用されます。- フリート全体でどのプラグインが読み込まれるかを確認する: 監査とレビュー
- レビューしたプラグインをいつ更新できるかを決定する: 更新ポリシーを設定する
- パイロットなど、1 つのグループに異なるポリシーを適用する: 管理設定で強制できないことに備える
- どのアプリとセッションの種類がプラグインキーを適用するかを確認する: 各サーフェスがプラグインキーを適用するタイミング
- CI とコンテナをセットアップする: コンテナと CI をシードする
- ユーザーがインストールできる mod を提供する: マーケットプレイスをホストする。Claude Code が GitHub、git、URL、または npm ソースからコピーする mod は、組織のものとしてインストール しない限り、ユーザーのものとしてカウントされます。
組み込みガードでオプションを設定する
組み込みガードはオプションを取ります。ユーザーがインストールした mod の読み込みを停止する の例のように、管理設定のpluginConfigs の下に、cc-plugin-sec-default@builtin をキーとして設定します。
表は、各オプションが設定されていない場合と true に設定されている場合にユーザーが取得するものを示しています。
これらのルールはオプションが有効になるかどうかを決定します。
- ID はここで 1 つのスペルを持ちます: Claude Code はオプションを
cc-plugin-sec-default@builtinの下でのみ読み取ります。prependPluginsはsec-default@builtinも受け入れ、pluginConfigsは受け入れません。 - 管理設定のみがカウントされます: ユーザー、プロジェクト、またはローカル設定ファイル内の同じエントリ、または
--settingsで渡されたファイル内のエントリは、オプションを設定したり、オプションを緩和したりしません - ガードが読み込まれる必要があります:
prependPluginsを設定する場合、リストでガードに名前を付けます。ガードが読み込まれない場所では、どちらのオプションも適用されません。 - ガードは閉じた状態で失敗します: ガードが管理設定を読み取ることができない場合、すべてのユーザーの mod を読み込み時に拒否します。ユーザーの mod が承認した呼び出しの拒否ルールをチェックできない場合、呼び出しを拒否します。
組織独自の mod を実行する
組織独自の mod をすべてのユーザーにデプロイし、ユーザーの mod との相対的な実行位置を選択し、ポリシーを強制するために使用できます。組織の mod をインストールして順序を設定する
組織の mod は、ユーザーの mod が読み込まれない状況でも読み込まれ、ユーザーの mod より先に実行できるため、Claude Code は mod が組織から来たものであることを判断できる必要があります。 GitHub リポジトリなどのリモートマーケットプレイスの mod を v2.1.324 以降で組織のものとして扱わせるには、管理設定で以下のすべてを行います。enabledPluginsで mod のプラグインをtrueに設定するextraKnownMarketplacesでマーケットプレイスを宣言する。mod のコードが変更されるタイミングを制御するには、マーケットプレイスと mod のエントリを固定します。acme-guard@acme-toolsなどの mod の id をprependPluginsまたはappendPluginsにリストする。prependPluginsを使用する場合は、組み込みガードを維持するためにsec-default@builtinもリストします。
- 管理設定の
enabledPluginsが mod のプラグインをtrueに設定している - 管理設定が、プラグインのマーケットプレイスをユーザーのマシン上のディレクトリとして、絶対パスで指定している。
extraKnownMarketplacesエントリはこれを行うと同時に、ユーザー向けにマーケットプレイスの登録も行います。 - マーケットプレイスがプラグインを相対パスでリストしているため、Claude Code はそのディレクトリからプラグインをその場で読み込む
/opt/acme/claude-plugins/.claude-plugin/marketplace.json
enabledPlugins がそれを有効にしている場合でも、ユーザーのものとして扱われます。その mod はユーザーの mod の中で実行され、prependPlugins と appendPlugins はそれをスキップし、allowManagedModsOnly はそれを拒否し、allowManagedHooksOnly の下では読み込まれません。管理設定がそれを有効にしている場合、ユーザーのデバッグログには、プラグインの id と is enabled by managed settings, but で始まる行が記録されます。
Claude Code は、ツールの実行など、アクションを実行しようとするたびにイベントを発生させ、それを順番に各 mod に渡します。ディレクトリの条件を満たす mod は、どこにもリストされていない場合でも、ユーザーの mod の前に実行されます。その位置を設定するには、その id を 2 つの設定のいずれかにリストします。id はプラグインの名前、@、マーケットプレイスの名前をつなげたもので、例えば acme-guard@acme-tools です。
prependPlugins: 組織の mod は、どのユーザーの mod よりも前にイベントを受け取り、それらの後にイベントの結果を受け取ります。イベントを変更したり、拒否したり、ユーザーの mod をスキップしたりできます。v2.1.323 以降では、フックが引き続き他の mod のコントロールと描画に到達することを確認してください。appendPlugins: 組織の mod はすべてのユーザーの mod の後に実行されるため、それらの mod が渡したイベントのみを、渡された形式で受け取ります。
acme-tools マーケットプレイスを /opt/acme/claude-plugins に宣言し、そこから acme-guard を有効にし、その mod を最初に実行し、その後に組み込みガードを実行します。
managed-settings.json
extraKnownMarketplaces:acme-toolsマーケットプレイスを保持するディレクトリを指定します。pathは.claude-plugin/marketplace.jsonを含むディレクトリの絶対パスです。enabledPlugins: これらの管理設定を受け取るすべてのユーザーに対してacme-guardをオンにします。prependPlugins:acme-guardを最初に、組み込みガードを 2 番目に配置し、両方ともユーザーがインストールするどの mod よりも前に配置します。Claude Code はリストした順序に従います。
claude --debug を使用してセッションを開始し、デバッグログで mod の id を検索します。
hooks module acme-guard@acme-tools loadedとtier prepend: mod は組織のものとして扱われ、最初に実行されます。- 同じ行に
tier user: Claude Code はそれをユーザーの mod として扱います。2 行目のprependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skippedは、リストがそれをスキップしたことを示しています。
- リストはデフォルトを置き換えます: 管理設定で
prependPluginsを設定する場合、組み込みガードを維持するには、そこにsec-default@builtinを指定します。ガードは組み込みのため、enabledPluginsエントリは必要ありません。 - 独自の id は組織のものとして扱われる必要があります: 管理設定では、Claude Code はプラグインが組織の mod の条件を満たさない id をスキップします。
- リポジトリはどちらのリストも設定できません: Claude Code はリポジトリの設定ファイル内の両方の設定を無視するため、管理設定で設定してください。
- ユーザーは独自の mod の順序を決めるためにこれらを設定できます:
~/.claude/settings.jsonで設定でき、管理設定もmanaged-mcp.jsonファイルもないマシン上でのみ、かつセッションの認証情報が Team または Enterprise の/loginではない場合のみ有効です。それ以外の場合、Claude Code はユーザー設定の両方のキーを無視します。そこにあるリストは、組み込みガードを追加も削除もしません。
独自の mod でポリシーを強制する
すべてのユーザーの mod を除外するだけなら、独自の mod は必要ありません。allowManagedModsOnly を設定してください。一部のユーザーの mod を許可して他を拒否したい場合や、mod の動作を記録したい場合は、ポリシー mod を作成します。
別の mod が読み込まれようとするたびに、組織の mod は claude plugin validate が出力するリストを、plugin.register という名前のイベントで受け取ります。prependPlugins 内の mod はそのリストを読み取り、その mod を拒否できます。また、任意の mods API 呼び出しを名前で処理して、他のすべての mod によるその呼び出しを記録または拒否することもできます。名前は $. を除いたメソッドなので、fs.write のフックはすべての $.fs.write 呼び出しを受け取ります。
v2.1.323 以降では、
ui.focus フックが他の mod の $.ui.focus 呼び出しを受け取るには、より広い matcher が必要です。他の mod の描画とコントロールをフックするを参照してください。$.process.run または $.process.spawn を呼び出すユーザーの mod を拒否します。また、監査ログを保持し、各ツール呼び出しと mod が書き込む各ファイルをデバッグログに書き込みます。最初に実行されるため、ログにはユーザーの mod が変更する前の、要求された内容が記録されます。acme-guard/hooks/register.js として保存します。
acme-guard/hooks/register.js
plugin.register: 別の mod を読み込むかどうかを決定します。ブロック対象のメソッドを呼び出すユーザーの mod を拒否し、他のすべての mod はそのまま通します。tool.call: 各ツール呼び出しについてaudit tool.call Bashのような行をデバッグログに書き込み、何も変更しません。fs.write: 別の mod が行う各$.fs.write呼び出しについてaudit fs.write by reader "/tmp/notes.md"のような行を書き込み、何も変更しません。mod の名前が先頭に来て、パスは引用符で囲まれるため、mod が選んだパスが行の別のフィールドになりすますことはできません。
plugin.register フックはイベントの 2 つのフィールドを読み取ります。
e.tier: mod が実行される位置で、prepend、user、append、builtinのいずれかです。人がインストールする mod はすべてuserです。e.uses.calls: mod が呼び出す mods API メソッドで、それぞれprocess.runのようにnamespace.methodの形式で記述され、claude plugin validateが出力する$.は付きません。
$.process.run を呼び出す mod をインストールすると、その mod は読み込まれず、ユーザーのデバッグログには refused by acme-guard: と指定した理由で終わる行が記録されます。この拒否は、プラグインディレクトリをホットリロードするセッションのトランスクリプトにも表示されます。
mod 全体を拒否せずに呼び出しだけをブロックするには、呼び出し元を確認した上で、その呼び出しの名前に対するフックから { deny: 'your reason' } を返します。
監査行をデバッグログ以外の場所に送信するには、同じフックから $.http.fetch を呼び出します。
セッションは組織の mod なしで実行される場合があります。インストールされた mod を実行するワーカースレッドが 3 回クラッシュすると、Claude Code は組み込み以外のすべての mod(組織のものを含む)をアンロードし、ユーザーが /reload-plugins を実行するか新しいセッションを開始するまでその状態が続きます。また、--safe-mode で Claude Code を開始したユーザーは、インストールされた mod(組織のものを含む)なしで実行します。
mod に必要なファイルについてはmod を作成するを参照してください。このポリシー mod のテストファイルはポリシー mod をテストするにあります。
チェックが失敗したときに mod を拒否する
plugin.register フックが例外をスローするか時間制限を超えた場合、Claude Code はそのフックをスキップするため、チェックはフェイルオープンとなり、チェック対象の mod は読み込まれます。フェイルクローズにしてユーザーの mod を拒否するには、チェックを名前付き関数に移し、拒否を返す .catch ハンドラーを追加します。このバージョンのファイルは plugin.register フックのみを示しているため、最初のバージョンにある 2 つの監査フックは register 内に残しておいてください。
acme-guard/hooks/register.js
refused by acme-guard: Acme policy check failed, so this mod was not loaded のように 2 番目の理由が記録されます。ハンドラーは user ティア以外のすべての mod を next(e) に渡すため、チェックが失敗しても組織がリストした mod は停止しません。他のイベントでの .catch については失敗するフックを処理するを参照してください。
次のステップ
- プラグインセキュリティ: ユーザーのマシンで任意のプラグインが実行できることと、インストール前にプラグインを確認する方法
- Mod の概要: mod とは何か、フック、スキル、MCP サーバーとの比較
- Mod が実行される順序:
prependPluginsとappendPluginsがユーザーの mod とどのように適合するか - 設定と環境変数: このページで名前が付けられたすべての設定を 1 つの表で