Agentty/ドキュメント

プラグインの権限

5 つの権限、権限がないときにプラグインが見るもの、そして WebAssembly プラグインがプログラムとまったく別物である理由。

プラグインができることは agentty-plugin.json にあらかじめ宣言され、インストール前に利用者へ示されます。権限のない呼び出しはエラー -32001 で失敗します。

5 つの権限#

権限利用者に示される文言メソッド
net.request指定したアドレスへ HTTP リクエストを送りますnet/fetch
prompt.injectエージェントのセッション開始・プロンプト送信prompt/inject
terminal.writeターミナルへ入力し Enter までterminal/send
session.readAgentty で開いている AI セッションの会話を読みますsession/get
workspace.read開いているワークスペース・タブ・フォルダとエージェントの状態を見ますworkspace/list, host/revealPath, pane/status
mcp.toolsAgentty で実行されている AI エージェントが提供するツールに応答します (MCP)tools/call
terminal.proxy新しいターミナルをプラグインのプロキシ経由にします(API バージョン 6 が必要)terminal/setProxy

プラグイン自身のストレージとパネルに権限は要りません。storage/get・storage/set・storage/keys は自分のフォルダ(<データフォルダ>/plugin-data/<id>/storage.json、0600 で作成)で、キー 64 個・合計 1 MB までです。WebAssembly プラグインには自分のファイルがないので、何かを覚える手段はこれだけです。

Important

net.request と session.read または workspace.read を併せ持つと、プラグインがあなたの仕事を読んでどこかへ送れるという意味になります。両方を求めるプラグインは説明にその理由をはっきり書くべきで、書いていないものはマーケットプレイスが拒否します。

2 種類のプラグイン#

もっとも重要な区別で、プラグインページの情報 → 実行方式に示されます。

wasmAgentty がモジュールを自分で実行します。ファイルもソケットも環境変数もプロセスもありません。どう書かれていてもプロトコルが許したものにしか触れられません。
node, python, executable利用者の権限で動くプログラムです。利用者が起動する他のものと同じファイル・ネットワークのアクセス権を持ちます。上の権限はプロトコル越しの動作だけを制限し、プログラム自体は何も制限されません。

ですから権限一覧の意味は 2 つの間で変わります。WebAssembly プラグインでは、それがそのプラグインにできることのすべてです。プログラムでは、Agentty を通してできることのすべてにすぎません。ファイルはもともと自分で開けたのですから。

プログラム型のプラグインは作者を信頼できるときだけインストールしてください。マーケットプレイスがソース公開の WebAssembly モジュールだけを扱うのは、まさにこのためです。

権限がないときにプラグインが見るもの#

コンテキストは宣言した権限で絞られます。workspace.read がなければフォルダとタイトルのフィールドが外れ、session.read がなければセッション id が外れます。残るのは id、kind、tool、status、running、言語です。どのペインがフォーカスされ作業中かはわかっても、どこで何をしているかはわかりません。

json
{
  "pane": { "id": 12, "kind": "claude", "tool": "claude", "status": "working", "running": true },
  "language": "ja"
}

プロンプトがどこへ行き、誰が選んだのか#

ダイアログは境界ではありません。ここははっきりさせておく価値があります。prompt.inject は、プラグインが確認なしに自分のエージェントセッションを開いてテキストを送ることを許します。意図した設計です。AgentOS は自分が開いたセッションでステップを進めることが仕事のすべてであり、ダイアログ越しではそれができません。

プラグインが選択を利用者に委ねることもできます。target: "ask" で呼ぶと**送信先…が開き、利用者がテキストを見てエージェントと宛先を選び、送信を押すまで何も起きません。それ以外の target — newTab、newWorkspace、active、pane、workspace — はこれを飛ばします。ですから外から来たものを受けて動くプラグインは常に ask を使うべきです。リンクから実行されたプラグインは制約を受けます。newTab および newWorkspace で Claude Code または Codex(またはエージェント指定なしで Claude Code が既定)なら直接開かれ、Enter は押されません。それ以外のすべてのケースは送信先…**を通り、Enter は押されません。

2 つの呼び出しは Enter で分かれ、その違いが terminal.write のすべてです。

  • injectPrompt はターミナルで Enter を代わりに押しません。テキストを入力しておいて、あとは利用者に任せます。
  • sendToTerminal は別物で、Enter を押します。シェルならそのコマンドが実行されます。

リンクは信用しません#

agentty:// リンクはウェブページを含めどこからでも来ます。リンクがプラグインに一度届いたら、そのプラグインが動いているあいだずっと:

  • prompt/inject の target が newTab または newWorkspace で Claude Code または Codex(またはエージェント指定なし、Claude Code が既定)なら、その新しいエージェントタブまたはワークスペースが直接開かれ、テキストはプロンプトに入力されますが Enter は押されません。こうして直接開くタブは数秒に 1 つだけで、リンクを続けざまに開くページもタブは 1 つしか得られず、残りは**送信先…で順番を待ちます。それ以外のすべてのケース — すでに開いているターミナル(active、pane、workspace)、split、own、シェル/ターミナルエージェント、target なし — は送信先…**を通り、Enter は押されません。
  • terminal/send はテキストを Enter を押さずに入力します(submit は false に強制されます)。入力先は Claude Code か Codex のターミナルだけで、シェルには入力しません。シェルのコマンドラインに残った文字は、ユーザーが次に打つコマンドと一緒に実行されかねないからです。入力だけでは何も実行されません。テキストは制御文字を除いて貼り付けられ、改行は bracketed paste で囲まれるかスペースに変わります。
  • Enter を利用者に任せたときは、両方の呼び出しとも submitted: false で応答します。

ブラウザは引き続き拒否されます(-32001)。host/openUrl はリンクが届いたプラグインが Agentty の外へできる唯一のことで、一度に 1 つのアドレスです。リンクが開いたパネルでのクリックは、プラグインが入力したものを実行してよいという同意ではありませんし、待つことも同じです。解けるのはプラグインの再起動だけです。

Agentty には良いアドレスと悪いアドレスの区別がつかないので、そこは書き手の責任です。リンクが渡してきたものは見知らぬ相手からのテキストとして扱い、そこで得たアドレスを確かめずに開かないでください。

Important

リンクを扱うプラグインなら、すべてのパラメータを検証してください。Cosmica プラグインは Cosmica のノートフォルダ内の .md ファイルだけを開き、外のパスは拒否します。

net.request でできること#

net/fetch はプラグインがネットワークに届く唯一の方法で、Agentty が範囲を区切ります。

メソッドhttp・https で GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
ヘッダ最大 32 個。Host, Content-Length, Transfer-Encoding, Connection, Upgrade, Expect は不可、改行を含むものも不可
リクエストボディ1 MB
レスポンス4 MB まで保持(truncated がそれ以上来たかを伝えます)
タイムアウト既定 15 秒、最大 60 秒
同時実行プラグインごとに 4 件

リクエストにあなたのものは何も載りません。 クッキーも保存された資格情報もなく、プラグインが自分で入れたものだけが行きます。呼び出しごとに URL を伏せてプラグインのログに記録されます。

リダイレクトは 3 回まで追い、その行き先も最初の要求と同じ検査を受けます。http か https であること、リンクローカルやメタデータのアドレスでないこと。そうでなければサーバーが 302 Location: http://169.254.169.254/… と答えて検査を迂回できてしまいます。Authorization や Cookie ヘッダは別のホストへ持ち越されず、リダイレクトされた POST・PUT・PATCH は応答が 307 か 308 でない限りボディなしの GET になります。

レート制限と暴走対策#

Agentty は、故意かどうかに関わらず、ふるまいのおかしいプラグインから自身を守ります。

制限動作
パネルの再描画50 ms に 1 回まで
通知700 ms に 1 回まで。超過分は正常に応答したうえで破棄。メッセージは 300 文字で切られます
URL を開く700 ms に 1 回まで。host/openUrl も通知と同じように絞られます
メッセージ毎秒 240 件を超えると暴走とみなしてプラグインを停止
UI ツリー要素 2,000 個、深さ 12 段、文字列 1 つあたり 20,000 文字。choice の選択肢とリスト項目のボタンもそれぞれ要素として数えます
行の長さstdout・stderr それぞれ 16 MB
WebAssemblyモジュール 64 MB、メモリ 64 MB、メッセージ 1 件 16 MB、1 件の処理中に 256 メッセージ — send と log の合計

AI エージェント向けツール (MCP)#

プラグインは Agentty で動いている AI エージェント (Claude Code、Codex) へツールを提供できます。Agentty が用意する MCP サーバー (agentty-plugins MCP サーバー) 経由で動作します。権限を持ち contributes.tools にツールを列挙したプラグインが 1 つ以上有効になっていれば、エージェントが自動的にサーバーを受け取ります。

プラグインは権限とツールを一緒に宣言する必要があります。権限だけあるか、ツールだけあるのはマニフェストエラーです。mcp.tools 権限は API バージョン 5 が必須です。

mcp.tools を宣言していないプラグインは MCP でサポートされていません。エージェントはこれを見ることができません。そのプラグインのページは「MCP 接続 — 非対応」と表示されます。

mcp.tools を宣言したプラグインの権限タブには 「MCP 接続を許可」 スイッチがあり、既定値は ON です。利用者がそれを OFF にすると、エージェントはもはやそのプラグインのツールを列挙・呼び出せません。

プラグインあたり最大 32 個のツール。ツール name は 1~48 文字で、小文字・数字・アンダースコアのみ、文字で始まります。各呼び出しは 120 秒でタイムアウト。引数とエージェントに渡されるテキストにはサイズ制限があるので、プロトコルの詳細を見てください。

プラグインの応答はエージェントのコンテキストに入るので、他のツール出力と同じように扱ってください。各呼び出しはログ (ログタブ) に記録され、それを呼び出したペインが表示されます。

ターミナルのプロキシ#

プラグインは、利用者が開くターミナルと AI セッションを、このコンピューター(127.0.0.1)上でプラグインが動かすプロキシ経由にするよう求められます。そのためプラグインは、それらがどのホストに接続し、どれだけ送信するかを見られます。利用者には 新しいターミナルを自分のプロキシ経由にする と表示されます。すでに開いているターミナルは変わらず、プラグインを停止すると終わります。アドレスは Agentty がポートから組み立てるので、プラグインはターミナルを別の場所へ向けられません。同時に保持できるプラグインは 1 つだけです。

求めた権限に値するプラグインを書く#

  • 使う権限だけを求める。 すべて利用者に示され、使わない権限は信頼を削るだけです。
  • 資格情報を読まない・送らない。 他のアプリの設定を読むなら必要なフィールドだけを。Cosmica プラグインは notes.path とポートだけを読みます。
  • データはプラグイン自身のストレージへ。 他のアプリが読むファイルは慎重に作り、利用者のファイルを断りなく上書きしないこと。
  • 127.0.0.1 とだけ話す。 利用者が自分で別の宛先を設定した場合を除いて。
  • 入力の前に pane.status を見る。 working, permission, question は邪魔してはいけません。
  • 外から来たものはすべて検証する。 リンクもファイルもサーバーの応答も、そのまま信じないこと。

他人のプラグインを入れる前に#

  • カードの権限を読んでください。ノートのプラグインが terminal.write を求めるなら、その理由が書かれているはずです。
  • 実行方式を確かめてください。WebAssembly モジュールは、プログラムよりずっと小さな信頼で済みます。
  • ソースを読めるプラグインを選んでください。カードのリンクがたいていリポジトリを指しています。
  • インストール後のログを見れば、そのプラグインが実際に何をしているかがわかります。
  • 無効化はすぐ効き、アンインストールは本体を消します。データフォルダは自分で消すまで残ります。