プラグインの権限

プラグインにできること、Agentty がそれを制限する方法、そして求めた権限に見合うプラグインを書くための規則。

プラグインは利用者のファイルとネットワークにアクセスできる通常のプログラムとして動きます。Agentty はこれをサンドボックスに閉じ込めません。代わりに、プロンプト送信・ターミナル入力・会話の読み取りといった重要な機能を事前に宣言させ、インストール前に利用者へ見せます。

4 つの権限#

権限	できること	なぜ重要か
`prompt.inject`	エージェントへのプロンプト送信	プロンプトは通常送信先…ダイアログで先に表示されます
`terminal.write`	開いているペインへの入力	ダイアログなしにテキストがペインへ届きます
`session.read`	AI 会話の読み取り	会話ログには話した内容がすべて含まれます
`workspace.read`	ワークスペース一覧とフォルダ・タイトル項目の参照	どこで作業しているかが分かります

権限なしの呼び出しは -32001 エラーで失敗します。プラグインページは、インストール前のカードとインストール後のカードの両方に宣言された権限を表示します。

権限がないときに見えるもの#

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

json

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

ダイアログが境界です#

target: "ask" で prompt.inject を呼ぶと**送信先…**が開きます。利用者がテキストを見てエージェントと行き先を選び、送信を押すまで何も起きません。他の target はこのダイアログを飛ばすため、外部からの入力で動くプラグインは常に ask を使うべきです。

injectPrompt がターミナルで Enter を代わりに押すことはありません。テキストを入力して利用者に委ねます。

リンクは信用されません#

agentty:// リンクはウェブページを含めどこからでも来ます。リンクがプラグインに届いてから 1 分間、Agentty は

そのプラグインの injectPrompt を target に関わらず**送信先…**へ回し、
sendToTerminal を拒否します。

リンクが開いたパネルでクリックしてもこの制限は解けません。リンク 1 回がターミナルへの入力に変わることはありません。

Important

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

作るときの規則#

使う権限だけを求めること。 すべて利用者に表示されるので、使わない権限は信頼を損なうだけです。
認証情報を読んだり送ったりしないこと。 他のアプリの設定を読むなら必要な項目だけにしてください。Cosmica プラグインは notes.path とローカルポートしか読みません。
データは AGENTTY_PLUGIN_DATA に置くこと。 他のアプリが読むファイルは慎重に作り、利用者のファイルを頼まれずに上書きしないでください。
127.0.0.1 とだけ通信すること。 利用者が自分で別のエンドポイントを設定した場合を除きます。
入力の前に pane.status を確認すること。 working、permission、question は邪魔してはいけません。
外から来たものは何でも検証すること。 リンクでもファイルでもサーバーの応答でも、そのまま信じて動かないでください。

レート制限と暴走の防止#

Agentty は、故意かどうかに関わらず不適切に振る舞うプラグインから自らを守ります。

制限	挙動
パネルの再描画	最短 50ms 間隔
通知	最短 700ms 間隔。超過分は正常に応答したうえで破棄
メッセージ	毎秒 240 件を超えると暴走とみなしてプラグインを停止
UI ツリー	要素 2,000 個、深さ 12 階層、テキスト 1 つあたり 20,000 文字
行の長さ	stdout・stderr それぞれ 16MB

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

カードの権限を読んでください。ノート用プラグインが terminal.write を求めるなら理由が説明されているべきです。
ソースを読めるプラグインを選びましょう。カードの links はたいていリポジトリを指しています。
インストール後にログを見れば、そのプラグインが実際に何を出力しているか手早く確認できます。
無効化は即座に効き、削除はプラグインを取り除きます。データフォルダは自分で消すまで残ります。