Mod（モッド）を使う

Mod（モッド、mod）は、Claude Code の見た目と振る舞いを変えるプラグインです。JavaScript か TypeScript で書いたイベントのハンドラーでできています。ツール呼び出し・送信したプロンプト・画面の一部の描画などのイベントが起きると、Claude Code がハンドラーを呼びます。ハンドラーはそのイベントを見るだけにも、変えることにも、肩代わりすることにも使えます。たとえば、リクエストのたびにコンテキストの埋まり具合をグラフにするペインのような、自分用の機能を足せます。

mod は次の4ページに分けています。

• このページ：何ができるか・入れ方・信頼・オンオフ・仕組み・組織での管理
• Mod を作る・試す：作り方・自動テスト・トラブルシューティング
• Mod で画面に描く：ペイン・帯・ボタン・入力欄・要素の見本
• Mod のリファレンス：ファイルの形・イベント・API のメソッド・要素の一覧

mod でできること#

設定のフック・スキル・ステータスライン・MCP サーバーは、Claude Code の外から働きます（スクリプトを動かす、Claude にテキストやツールを渡す）。mod は Claude Code の中で動くので、これらにできないことができます。

• 操作できる画面を描く：トランスクリプトの横のペインや、プロンプトの上の帯。タブ・ボタン・入力欄が使えます
• Claude Code が描く画面を描き直す：ツール呼び出しの行・スピナー・Claude が質問するダイアログなど、本体が描く部分を差し替えたり見た目を変えたりします
• ツール呼び出しやリクエストに割り込む：ユーザーに質問するあいだツール呼び出しを止める、ツールを実行せずに答える、1つのリクエストだけ別のモデルへ送る、など
• コマンドで自分のコードを動かす：Claude のターンを挟まず、Claude が作業中でも、/command で関数をすぐ実行します
• フック間でデータを共有する：1つの mod のフックは、そのファイルの変数を共有します。ツール呼び出しを数えるフックと、その数をスピナーの横に出すフックを分ける、リクエストごとのトークン使用量を読むフックと、それをペインにグラフで描くフックを分ける、などができます

mod は Claude Code の CLI と、Claude デスクトップアプリの Code タブで動きます。VS Code 拡張・claude -p・クラウドセッションでの動きは、下の「mod が動く場所」を見てください。設定のフック・スキル・MCP サーバーで足りるなら、mod を書く前に下の比較表で見比べます。

mod を手に入れる#

• すでにあるものを使う：/diff のように、Claude Code 自体の機能の一部が mod です（下の「最初から入っている mod」）
• 作る：やりたいことを Claude Code のセッションで説明すると、Claude が mod を書きます。コードの仕組みを知りたいときは自分で書きます（Mod を作る・試す）
• 入れる：下の手順で入れるか、サンプルを試します

mod を入れる・更新する#

mod はマーケットプレイスからプラグインとして入れます。プラグイン名、@、マーケットプレイス名の順に書きます。次は、マーケットプレイス your-org のプラグイン token-chart を入れる例です。

• セッションの中：/plugin install token-chart@your-org
• シェル：claude plugin install token-chart@your-org

マーケットプレイス・スコープ・VS Code 拡張とデスクトップアプリ・更新の保ち方は、mod を含むプラグインでもそのまま当てはまります（プラグインを使う）。

セッションを開いたまま、シェルから mod を入れる・更新したときは、そのセッションで /reload-plugins を実行すると読み込まれます。実行しなければ、次に Claude Code を起動したときに読み込まれます。

サンプルの mod を試す#

Anthropic が、claude-code-playground リポジトリの claude-code/mods ディレクトリにサンプルの mod を公開しています。どれも完成したプラグインで、README に作り方が書いてあります。サポートなしで、そのまま共有されています。

サンプルも、あなたの権限で動きます。読み込む前に何をするかを見るには、下の「入れる前に、mod がすることを一覧する」を使います。

試すには、リポジトリをクローンし、--plugin-dir で mod のディレクトリを1回のセッションだけ読み込みます。読み込まれたかは、下の「セッションが読み込んだ mod を見る」で確かめます。残すには、クローンの claude-code/mods ディレクトリをマーケットプレイスとして追加し、claude-code-playground-mods から入れます。マーケットプレイスはクローンを指すので、クローンを動かす・消すと mod は読み込まれなくなります。

mod を信頼してよいか決める#

mod は、Claude Code の中であなたの権限で動くコードです。信頼できる作者とマーケットプレイスのものだけを入れます。

mod が届く範囲#

読み込まれた mod は、あなたのアカウントでできることを一通りできます。

とくに気をつけたいのは次の3点です。

• サンドボックスの外で動く：サンドボックスが隔離するのは Claude が実行する Bash コマンドで、mod が起動したプロセスは対象外です
• 確認やフックを越えて承認できる：ツール呼び出しを承認する mod は、ask ルールの確認や、自分の PreToolUse フックの拒否があっても承認できます。deny ルールの呼び出しまで承認できる場合を含め、一覧は権限ルールにあります
• 権限の確認画面だけは変えられない：画面の多くを描き直せても、確認画面が見せる内容は変えられません

入れる前に、mod がすることを一覧する#

実行せずに、mod が扱うイベントと、Claude Code に頼むこと（ファイルの読み込み・ネットワークリクエストなど）を一覧できます。先にプラグインのファイルを手に入れ（リポジトリをクローンするなど）、シェルでそのディレクトリに claude plugin validate を実行します。

claude plugin validate ./some-mod

出力の hooks: の行が mod の扱うイベント、calls: の行が頼むことの一覧です。出力例と、見るべき呼び出しは、下の「組織で mod を管理する」の「mod ができることを点検する」にあります。

mod をオン・オフする#

mod には Claude Code v2.1.287 以降が要り、既定でオンです。claude --version で版を確かめ、古ければ更新します。

オフにするには、止める数と期間を選びます。戻すときは同じ変更を取り消します。

"disableAllHooks": true は、設定のフックとカスタムのステータスラインも止めます。組織が管理するものは動き続けます。

組織で Claude Code を使っているときは、管理者がどの mod を読み込むかを制限することもできます（下の「組織で mod を管理する」）。

disableAllHooks と組織の allowManagedModsOnly が止めるのは mod だけで、プラグインのほかの部分は残ります。プラグインは入ったままで、スキル・コマンド・エージェント・MCP サーバーは読み込まれます。ほかの設定やフラグは、もっと広く効きます。それぞれがプラグインと設定のフックに何をするかは、設定キー一覧にあります。

自分に mod が読み込めるかを調べるには、Mod を作る・試すのトラブルシューティングを見ます。

セッションが読み込んだ mod を見る#

ターミナルのセッションが読み込んだ mod は、プロンプトで /plugin を実行すると分かります。タブの下の薄い行に、数と名前が出ます（例：1 mod active · first-mod）。入れたはずの mod の名前がないときは、Mod を作る・試すの「Mod が何もしない原因を探す」を見てください。

mod の仕組み#

mod は、コードがイベントのハンドラー（フック）を登録するプラグインです。Claude が1つのツールを呼ぶとき、スピナーが描かれるときなど、そのイベントが起きると、Claude Code がフックを実行します。小さな mod のファイルは3つです。

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

• plugin.json：プラグインのマニフェスト
• hooks.json：コードのファイルを指す
• register.js：自分のコード（フックのモジュール）。どのイベントでどの関数を動かすかを Claude Code に伝える

次は完成した register.js です。Claude が呼んだツールの数を数え、作業中にスピナーの横に Thinking · tool calls: 3… のように出します。

// 下の2つのフックが共有する数
let calls = 0

// mod が読み込まれたとき、Claude Code が1回呼ぶ
export function register(on) {
  // Claude がツールを使おうとするたびに動く
  on('tool.call', async ($, e, next) => {
    calls += 1
    // 新しい数が出るよう、画面の描き直しを頼む
    $.ui.invalidate('ui.render')
    // ツールはいつもどおり動かす
    return next(e)
  })

  // Claude Code がスピナーを描くたびに動く
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // 本体のスピナーに、言葉のあとへ数を足して使う
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

2つのフックは、先頭の calls を共有します。

• tool.call のフック：Claude がツールを使おうとするたびに動き、calls に1を足し、画面の描き直しを頼み、ツールをそのまま動かす
• ui.render のフック：Claude Code がスピナーを描くたびに動き、本体のスピナーを残したまま、言葉のあとに数を足す

フックがイベントにできること#

Claude Code は、イベントに対して動く前にフックを実行するので、次に何が起きるかをフックが決められます。

• 見る（observe）：何が起きているかを記録し、変えずに先へ進める。例の tool.call のフックがこれ
• 書き換える（rewrite）：先へ進む前にイベントを変える。例の ui.render のフックが、スピナーに数を足すのがこれ
• 答える（answer）：イベントを自分で処理し、通常の動作を走らせない。コマンドを断る、など

自分のコードの外のこと（描く・コマンドを足す・モデルを呼ぶ・ファイルを読む・プロセスを起動する・ネットワークへリクエストする）をするには、フックが mod の API を呼びます。ほかの方法はありません。そのため、入れる前に Claude Code が mod のすることを一覧できます。

各選択肢のコードはMod のリファレンスを見てください。

mod が動く場所#

mod のフックは、そのプラグインを読み込むあらゆる種類のセッションで動きます。描画は範囲が狭く、mod のペイン・帯・差し替えた行を表示するのは、ターミナルとデスクトップアプリだけです。

描く mod は、どのアプリで動いているかを調べて、何も描けない場所ではトランスクリプトの1行やコマンドのテキストの返事に切り替えられます。

mod・設定のフック・スキル・MCP サーバーの比べ方#

4つは役割が重なります。それぞれが何で、いつ選ぶかを表にします。

それぞれの詳しい説明は、フックの使い方・スキル・MCP サーバーをつなぐにあります。プラグインはこれらをすべて持てるので、mod はスキルや MCP サーバーと同じプラグインで配れます。

最初から入っている mod#

Claude Code 自体の機能の一部は mod です。いまのセッションにあるものは、/plugin の「Installed」タブの「Built-in」に並びます。組み込みの mod は更新もアンインストールもできません。止め方は表の最後の列のとおりです。上の mods active の行には、組み込みの mod は数えられません。

次の表は、/plugin に出る名前ごとの一覧です。

disableAllHooks・--bare・--safe-mode のように、入れた mod を止める設定やフラグは、組み込みの mod を止めません。

組み込みの mod のソースを読む#

一部の mod は、Claude Code のリポジトリの mods ディレクトリでソースが公開されています。どれもフックのモジュールとテストを持つ完成したプラグインです。

組織で mod を管理する#

ここからは管理者向けです。mod を動かすか、どの mod を動かすかは管理設定で決めます。管理設定をファイル・MDM・claude.ai の管理コンソールのどれで配っても同じです。v2.1.287 以降、mod は既定でオンです。

mod はプラグインのほかの部分より強い力を持ちます。Claude Code の中で動くので、すべてのプロンプトとツール呼び出しを見て変えられ、権限の確認より前にツール呼び出しを許可・拒否できます。

ユーザーがインストールした mod を読み込ませない#

組み込みの守り（下の「既定で何が起きるか」）のオプション allowManagedModsOnly を使います。守りは、ユーザーのどの mod よりも先に読み込まれるポリシー mod です。管理設定の pluginConfigs に、cc-plugin-sec-default@builtin をキーにして書きます。

{
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": {
        "allowManagedModsOnly": true
      }
    }
  }
}

これを管理設定に置いたときの効き方です。

守りはこのオプションを管理設定からだけ読みます。ユーザー・プロジェクト・ローカルの設定ファイルや --settings のファイルに同じ項目を書いても変わらないので、ユーザーには取り消せません。ファイルか MDM で配れば、Amazon Bedrock・Google Cloud の Agent Platform・Microsoft Foundry でも同じように効きます。claude.ai の管理コンソールから配るときの提供状況は、サーバー管理設定で確かめます。

効いているかは、ユーザーの端末で claude --plugin-dir ./first-mod のように mod のディレクトリを指して起動すると分かります。効いていれば mod のフックは動かず、mod の名前と allowManagedModsOnly を挙げる守りのメッセージが、トランスクリプトとデバッグログに出ます。mod が読み込まれてしまったら、管理設定が端末に届いているか（確かめ方は組織への導入と管理設定）と、下の「守りのオプション」の規則を見直します。

既定で何が起きるか#

mod の設定を何も足さないときの状態です。

• mod はオン：プラグイン設定が許すマーケットプレイスから、mod を含むプラグインを入れられます。--plugin-dir でディレクトリから読み込むこともできます
• 組み込みの守りが先に入る：sec-default@builtin（/plugin とデバッグログでは cc-plugin-sec-default）という組み込みの mod が、ユーザーのどの mod よりも先に読み込まれ、ユーザーには止められません。入るのは、端末に管理設定があるとき、または Team か Enterprise のプランでサインインしているときです。API キー・Amazon Bedrock・Google Cloud の Agent Platform・Microsoft Foundry で認証する人には、管理設定のある端末でだけ入ります

守りが入った場所では、ユーザーの mod にできることが次のように分かれます。

deny ルールと管理されたフックが効くのは、Claude のツール呼び出しだけです。mod 自身の $.fs・$.process の呼び出しには効きません。Read(.env) を deny にしても、mod は $.fs.read でそのファイルを読めますし、そのファイルを読むプログラムを起動することもできます。これを止めるには、mod を読み込ませないか、ポリシー mod でその呼び出しを扱います（下の「自前の mod でポリシーを強制する」）。

守りのソースは、Claude Code のリポジトリの mods/sec-default ディレクトリで公開されています。

いまの管理が引き続き効くところ#

mod は、すでにある管理を置き換えません。ただし、どの管理も mod をサンドボックスに入れるものではありません。許した mod は、ユーザーのファイル・プロセス・ネットワークへのアクセスで動きます。

mod をオンのままにするかを決める#

ユーザーが mod として読み込めるものは、いまのプラグイン管理で決まります。

プラグインが読み込まれる経路と、それぞれを制御する設定は組織への導入と管理設定にあります。ユーザーが入れる前にマーケットプレイスの mod を点検するには、次の節を使います。

mod ができることを点検する#

実行せずに、mod にできることを見られます。シェルでプラグインのディレクトリに claude plugin validate を実行します。

claude plugin validate ./some-mod

出力の2行が、mod のコードを表します。

  ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}
  ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

hooks: の行は mod が受け取るイベント、calls: の行は mod のコードが呼ぶ mod API のメソッドです。mod のコードで $ と書く mod API が、ファイル・プロセス・ネットワークへ届く手段です。このコマンドが読めない形で mod API を使う mod は、Claude Code が読み込みを拒みます。

calls: の行では、次を見ます。

hooks: の行では、次の意味があります。

• tool.call、prompt.submit：すべてのツール呼び出し・プロンプトを見て、変えられる
• session.append：保存前の会話の各行を書き換えられる
• ui.render{component=AskUserQuestion}：Claude がユーザーに質問するダイアログを描き直せる
• tool.check：権限の確認が出る前に、ツール呼び出しを承認・拒否できる

どのルールとフックがその答えより優先されるかは、上の「既定で何が起きるか」にあります。

どれだけ許すかを選ぶ#

mod の方針は、入れた mod を1つも許さないものから、ユーザーが選ぶどの mod も許し、自前の mod がほかを検査するものまであります。どれも数個の管理設定です。1列目から方針を選び、2列目の設定をします。

4つの設定は、止める範囲の広さが違います。

allowManagedHooksOnly・disableAllHooks・disableSideloadFlags は、設定する前に設定キー一覧の各項目を読んでください。AGENTS.md への対応のような組み込みの mod は、どの設定の影響も受けず、それぞれ専用のスイッチで止めます。

mod が読み込まれなかった理由は、ユーザーのデバッグログに出ます。allowManagedHooksOnly と disableAllHooks の行はMod を作る・試すの「拒否のメッセージ」に、allowManagedModsOnly の行は同じページの「組み込みのガードのメッセージ」にあります。

組織の mod だけを許す#

組織の mod を動かし、ユーザーが持ち込む mod を止めるには、上の方針の表の「組織の mod だけ」の行の設定に disableSideloadFlags を足して配ります。次の managed-settings.json では、ユーザー自身の mod は拒まれてフックが1つも動かず、ポリシー mod がほかの mod より先に動きます。

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"],
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": { "allowManagedModsOnly": true }
    }
  },
  "disableSideloadFlags": true
}

• extraKnownMarketplaces・enabledPlugins・prependPlugins：自前の mod を、組織のものと数えられるように入れ、守りをあとにして先頭で動かす
• pluginConfigs：守りの allowManagedModsOnly を設定し、ユーザー自身の mod を拒む。設定のフック・ステータスライン・/goal は動く
• 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 の hooks module が loaded と出ているので、拒否の行を探す
• プラグインのディレクトリ：claude --plugin-dir ./any-mod は、--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags) で始まるメッセージで終了する

ユーザーが追加できるマーケットプレイスも制限するには、このファイルにマーケットプレイスの制限を組み合わせます。

mod にプラグインの管理を当てる#

mod はプラグインなので、組織のプラグインの管理のやり方は、mod を持つプラグインにも当てはまります。

• フリート全体で読み込まれるプラグインを見る：監査と点検
• 点検したプラグインをいつ更新してよいかを決める：更新ポリシーの設定
• 試験導入などで、グループごとに別の方針にする：管理設定で強制できないことへの備え
• プラグインのキーをどのアプリとセッションが適用するかを調べる：各アプリがプラグインのキーを適用する時期
• CI とコンテナを設定する：コンテナと CI の初期設定
• ユーザーが入れてよい mod を提供する：マーケットプレイスをホストする。GitHub・git・URL・npm のソースから Claude Code がコピーした mod は、組織のものではなくユーザーのものと数えられる

守りのオプション#

組み込みの守りにはオプションがあります。管理設定の pluginConfigs に、cc-plugin-sec-default@builtin をキーにして書きます（上の「ユーザーがインストールした mod を読み込ませない」の例と同じ）。

オプションが効かないのは、次のどれかに当たるときです。

• キーの id が違う：オプションは cc-plugin-sec-default@builtin のもとからだけ読まれます。prependPlugins は sec-default@builtin でも通りますが、pluginConfigs では通りません
• 管理設定の外に書いた：ユーザー・プロジェクト・ローカルの設定ファイルや --settings のファイルでは、設定することも緩めることもできません
• 守りが読み込まれていない：prependPlugins を設定するなら、そのリストに守りを入れます。守りが入らない場所では、どちらのオプションも効きません

守りは安全側に倒れます。管理設定を読めないときはユーザーの mod をすべて読み込みの時点で拒み、ユーザーの mod が承認した呼び出しの deny ルールを調べられないときは、その呼び出しを拒みます。

組織自身の mod を動かす#

自前の mod を全ユーザーに配り、ユーザーの mod の前とあとのどちらで動かすかを選び、ポリシーの強制に使えます。

組織の mod を入れ、順番を決める#

組織の mod は、ユーザーの mod が止められている場面でも読み込まれ、先に動かせます。そのため、次の3つがすべてそろった mod だけが組織のものと数えられます。

• 管理設定の enabledPlugins が、その mod のプラグインを true にしている
• 管理設定が、プラグインのマーケットプレイスを、ユーザーの端末上のディレクトリとして絶対パスで指している（extraKnownMarketplaces の項目がこれに当たり、ユーザーにもマーケットプレイスを登録する）
• マーケットプレイスがプラグインを相対パスで挙げていて、Claude Code がそのディレクトリからその場で読み込む

実際には、デバイス管理でマーケットプレイスのディレクトリを全端末の同じパスへ置きます。そこに書き込める人は mod を書き換えられるので、そのディレクトリと上のすべてのディレクトリを、管理設定のファイルと同じく管理者だけが書けるようにします。claude.ai の管理コンソールから配る管理設定は、キーは運べてもディレクトリは置けません。

ディレクトリには、マーケットプレイスのマニフェストとプラグインを置きます。

/opt/acme/claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── acme-guard/
        ├── .claude-plugin/
        │   └── plugin.json
        └── hooks/
            ├── hooks.json
            └── register.js

マニフェストは、そのディレクトリからの相対パスでプラグインを挙げます。

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "acme-guard", "source": "./plugins/acme-guard", "description": "Acme policy mod" }
  ]
}

逆に、Claude Code がキャッシュへコピーするプラグイン（GitHub・git・URL・npm のソースのものはすべて）は、管理設定の enabledPlugins で有効にしてもユーザーのものと数えられます。その mod はユーザーの mod の中で動き、prependPlugins・appendPlugins からは読み飛ばされ、allowManagedModsOnly や allowManagedHooksOnly のもとでは読み込まれません。ユーザーのデバッグログには、プラグインの id と is enabled by managed settings, but で始まる行が出ます。

Claude Code は、ツールを動かすなど何かをする前にイベントを起こし、各 mod へ順に渡します。組織の mod は、どこにも挙げなくてもユーザーの mod より先に動きます。位置を決めるには、id（プラグイン名、@、マーケットプレイス名。例：acme-guard@acme-tools）を次のどちらかに書きます。

次の例は、/opt/acme/claude-plugins のマーケットプレイス acme-tools から acme-guard を有効にし、先頭で動かして、組み込みの守りをその次に置きます。

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]
}

path は .claude-plugin/marketplace.json を含むディレクトリの絶対パスです。enabledPlugins はこの管理設定を受け取る全ユーザーで acme-guard をオンにし、prependPlugins は書いた順のとおり、acme-guard、守りの順で、どちらもユーザーの mod より前に並べます。

どこで動いているかは、その端末で claude --debug でセッションを始め、デバッグログで mod の id を探すと分かります。

• hooks module acme-guard@acme-tools loaded と tier prepend：組織の mod と数えられ、先頭で動いている
• 同じ行に tier user：ユーザーの mod として扱われている。2行目に prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped があれば、リストから読み飛ばされている

2つのリストには、次の規則があります。

• 既定の並びを置き換える：管理設定に prependPlugins を書いたら、守りを残すために sec-default@builtin も挙げます。守りは組み込みなので enabledPlugins の項目は要りません
• 組織のものでない id は読み飛ばされる：管理設定でも、組織の mod の条件を満たさないプラグインの id は効きません
• リポジトリからは設定できない：どちらも管理設定から読み、リポジトリの設定ファイルからは読みません。ユーザーが ~/.claude/settings.json で自分の mod を並べられるのは、管理設定がなく、Team・Enterprise のプランでサインインしていない端末だけです。それ以外ではユーザー設定のこの2つは無視され、守りを足すことも外すこともできません

自前の mod でポリシーを強制する#

ユーザーの mod をすべて締め出すだけなら、allowManagedModsOnly で足ります。一部のユーザーの mod だけを許したいとき、または mod のしたことを記録したいときに、ポリシー mod を書きます。手がかりは2つです。

• plugin.register イベント：ほかの mod が読み込まれる直前に、claude plugin validate が出すのと同じ一覧を受け取ります。prependPlugins にある mod は、これを見てその mod を拒めます
• API の呼び出しの名前のフック：$. を除いたメソッド名でフックを登録すると、ほかのすべての mod のその呼び出しを記録・拒否できます。fs.write のフックなら、すべての $.fs.write の呼び出しを見ます

次の acme-guard/hooks/register.js は、自分のコードで $.process.run か $.process.spawn を呼ぶユーザーの mod を拒みます。あわせて、ツール呼び出しと、mod が書いたファイルをデバッグログに記録します。先頭で動くので、ユーザーの mod が変える前の要求が記録されます。

// どのユーザーの mod にも呼ばせないメソッド。namespace.method の形で書く
const BLOCKED_CALLS = ['process.run', 'process.spawn']

export function register(on) {
  // ほかの mod が読み込まれようとするたびに動く
  on('plugin.register', async ($, e, next) => {
    const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
    if (e.tier === 'user' && blocked.length > 0) {
      // refuse を返すと mod は読み込まれず、文字列が理由になる
      return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
    }
    return next(e)
  })

  // ツール呼び出しを記録し、変えずに通す
  on('tool.call', async ($, e, next) => {
    $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })
    return next(e)
  })

  // ファイルを書いた mod の名前とパスを記録する。パスは mod が決めるので引用符で囲む
  on('fs.write', async ($, e, next) => {
    $.ui.log('audit fs.write by ' + next.origin.plugin + ' ' + JSON.stringify(e.path), { to: 'debug' })
    return next(e)
  })
}

記録の2つのフックは何も変えず、audit tool.call Bash や audit fs.write by reader "/tmp/notes.md" のような行を書くだけです。mod の名前を先に置き、パスを引用符で囲むので、mod が選んだパスが行のほかの項目になりすますことはありません。

plugin.register のフックが読むイベントのフィールドは2つです。

拒まれた mod は読み込まれず、ユーザーのデバッグログに refused by acme-guard: と自前の理由で終わる行が出ます。プラグインのディレクトリをホットリロードするセッションでは、トランスクリプトにも出ます。mod 全体ではなく1つの呼び出しだけを止めるなら、その呼び出しの名前のフックから { deny: 'your reason' } を返します。記録をデバッグログ以外へ送るなら、同じフックから $.http.fetch を呼びます。

mod に要るファイルと、このポリシー mod のテストは、Mod を作る・試すにあります。

検査が失敗したときに mod を拒む

plugin.register のフックが例外を投げるか制限時間を超えると、そのフックは飛ばされ、検査中の mod は読み込まれます。つまり開けた側に倒れます。拒む側に倒すには、検査を名前付きの関数へ移し、.catch で拒否を返します。次は plugin.register の部分だけです。記録の2つのフックは register に残します。

const BLOCKED_CALLS = ['process.run', 'process.spawn']

// 上と同じ検査を、名前付きの関数へ移したもの
async function checkMod($, e, next) {
  const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
  if (e.tier === 'user' && blocked.length > 0) {
    return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
  }
  return next(e)
}

export function register(on) {
  // checkMod が例外を投げるか制限時間を超えたときだけ動く
  on('plugin.register', checkMod).catch(async ($, e, next) => {
    // 組織の mod と組み込みの mod は通す
    if (e.tier !== 'user') return next(e)
    // 検査できなかったユーザーの mod を拒む
    return { refuse: 'Acme policy check failed, so this mod was not loaded' }
  })
}

検査に失敗した mod は読み込まれず、拒否の行に2つ目の理由が出ます（refused by acme-guard: Acme policy check failed, so this mod was not loaded）。user 以外の層の mod は next(e) で通すので、組織が挙げた mod は止まりません。ほかのイベントでの .catch はMod のリファレンスにあります。

次に読むページ#

• Mod を作る・試す：作り方・テスト・トラブルシューティング
• Mod で画面に描く：ペイン・帯・ボタン・入力欄
• Mod のリファレンス：イベント・メソッド・要素・上限
• プラグインを使う：プラグインのセキュリティと入れ方