relay_tool 0.9.4 で追加

relay_tool を使うと、エージェントはほかのセッションを扱えます。セッションの一覧表示と読み取り、プロンプトの送信、新しいセッションの開始、返信の待機、相手のエージェントが出した質問への回答、セッションの停止やアーカイブができます。また、見守っているセッションで何かが起きたときに起こしてもらうよう依頼することもできます。

このツールが扱えるリレーは 2 種類です。

• このリレー：エージェント自身が動いているリレーです。エージェントは自分のタスクの一部を、ここにあるほかのセッションに任せられます。有効にするまではオフです。0.9.7 で追加
• ペアリングしたリレー：このリレーとペアリングしたほかの OAR リレーです。例：ワークステーションのリレーとサーバーのリレー。各会話では、あなたがそのリレーに言及するまでロックされています。

このツールは、これを備えたすべてのプロバイダーで共通です。どのプロバイダーがどの名前で備えているかは、プロバイダー別を参照してください。

名前 0.9.18 で追加 #

0.9.17 までは、このツールは remote_relay という名前でした。現在はすべてのプロバイダーで relay_tool として提示され（Claude のエージェントからは mcp__relay__relay_tool に見えます）、アクションとフィールドは同じです。古い名前で記録されたツールの行も、このツールとして表示されます。

• 更新時に実行中だったセッション。 セッションのエージェントは、ワーカーの起動時にツールの一覧を受け取ります。ワーカーはリレーの再起動をまたいで動き続けます。そのようなセッションのエージェントは、Kill session（セッションを強制終了）の後などにワーカーが再び起動するまで、このツールを remote_relay として持ち続けます。その呼び出しはそのまま動作します。どちらの名前でも、同じ方法でリレーに届きます。リレーを Linux のサービスとして動かしている場合は、ワーカーがリレーと一緒に停止し、新しい名前で戻ってくることがあります。
• OAR 独自の MCP サーバー（Grok と Copilot の拡張機能エンジンが使います）は、remote_relay の呼び出しを引き続き実行しますが、一覧には載せなくなりました。
• あなた自身の指示。 指示、権限ルール、フックで remote_relay または mcp__relay__remote_relay を指定している場合は、relay_tool または mcp__relay__relay_tool に変更してください。OAR の MCP サーバー以外では、古い名前は拒否されます。

表示される内容 #

• 承認カード。 質問カードが確認を求めるのは、会話の中でエージェントが最初のセッションを開始する前、初めてセッションを見守る前、そして会話が ask または plan のリレーモードにある間の書き込みアクションの前（毎回）です。
• 返信の中のツール呼び出し。 エージェントのアクティビティには、各呼び出しが 🛰️、アクション、リレー、セッションとともに表示されます。
• "via agent"： エージェントが開始したセッションには、会話リストとタイトルの下に via agent · "title"（エージェント経由 · 「title」）が表示され、エージェントが動いている会話の名前が示されます。0.9.11 で追加 そのセッションは、その会話の下のセッショングループに入ります。0.9.16 で追加 エージェントが既存のグループを指定した場合は、そのグループに入ります。
• "↗ from …"（… から）：エージェントが送ったプロンプトには、受け取った側で、送信元のリレー、セッション、モデルを示すバッジが付きます。
• 見守り。 ほかのセッションを見守っている会話のヘッダーには watching N sessions（N 件のセッションを監視中）が表示されます。チップにはその購読が一覧表示され、それぞれに Unsubscribe（購読を解除）ボタンがあります。見守られているセッションには watched（監視中）バッジが付きます。

有効にする #

次のうち少なくとも 1 つが当てはまると、relay_tool がエージェントに提示されます。

セッションがこのツールを受け取るかどうかは、エージェントのプロセスが起動したときに決まります。そのため、すでに動いていた会話では、エージェントが起動し直すまでツールを使えないことがあります。

リレーの指定 #

list_relays 以外のすべてのアクションは、relay で指定した 1 つのリレーに対して動作します。

• "this"、またはこのリレー自身の名前は、エージェントが動いているリレーを指します。言及は不要です。
• ペアリングしたリレーは、list_relays が示すとおりのリレー名またはホストで指定します。

4 つの購読アクション、0.9.16 で追加 3 つの予約アクション、3 つの質問アクションでは、relay を省略でき、その場合は "this" を意味します。予約はこのリレーでのみ動作します。

ロックとロック解除 #

ペアリングしたリレーは、次のいずれかが起きるまで、会話の中でロックされたままです。

• あなたが自分のメッセージの中でそのリレーに言及する：@ を入力して選ぶか、その名前またはホスト名を書きます。名前が IP アドレスまたは localhost のリレーは、先頭に @ を付けた場合にだけ言及と見なされます。
• そのリレー上のエージェントが会話に書き込む。すると、こちらのエージェントが回答できるように、そのリレーが開かれます。

一度ロックが解除されると、その会話の残りの間は開いたままです。ロックされたリレーは list_relays 以外のすべてのアクションを拒否し、エージェントには、そのリレーに言及するようあなたに頼むよう伝えられます。

権限と承認 #

ペアリングしたリレーで許可されること #

ペアリングした各リレーには、Settings → Relays に Agents may（エージェントの権限）のレベルがあります。新しいペアリングは Full（フルアクセス）から始まります。

list_relays にはレベルは不要です。このリレー自身は常に Full として扱われます。

相手側では、Accept prompts from other relays' agents（他のリレーのエージェントからのプロンプトを受け付ける）（ペアリングしたリレーの Settings → Relays）をオフにすると、ほかのリレーのエージェントがそこで変更または監視できることがすべて無効になります。プロンプトの送信、セッションの開始、回答、停止、アーカイブ、セッションの購読です。セッションの一覧表示と読み取り、タスク出力の読み取り、待機、relay_info と usage は引き続き動作します。

確認を求められるとき #

このリレー上のセッションのルール #

• 作業できるのは最大 4 つ。 1 つの会話のエージェントが開始したセッションのうち、ターンがキューに入っているか実行中でいられるのは同時に 4 つまでです。5 つ目は、どれかが終わるまで拒否されます。
• 1 階層のみ。 エージェントが作成したセッションは、自分ではセッションを作成できません。0.9.16 で追加 ただし、そのセッションに対してあなたが Agents in this conversation may start sessions（この会話のエージェントにセッションの開始を許可）をオンにした場合は別です。そのとき list_sessions と read_session には "mayCreateSessions": true が表示されます。このスイッチはどのエージェントも設定できません。
• 自分自身は対象外。 エージェントは、自分が動いている会話に対して send、wait、stop、archive を行うことも、自分の質問に回答することも、0.9.16 で追加 その設定を変更することもできません。
• あなたのアカウント。 エージェントが開始したセッションは、このリレーのプロバイダーアカウントを使い、その使用状況に計上されます。
• リレーがこれらのセッションを自動でアーカイブすることはありません。あなたがアーカイブまたは削除するか、エージェントがアーカイブするまで、一覧に残ります。

リレーをまたぐ場合 #

• すでに 2 つのリレーを経由したプロンプトは、あなた自身がロックを解除したリレーでない限り、3 つ目のリレーには渡されません。読み取りと待機は、この制限を受けません。
• 相手のエージェントが受け取るプロンプトは、別のエージェントが話しかけていることを示す行で始まります。 [Remote prompt from an agent on relay "…" · session "…" · model · acting for the user]
• この方法で開始したターンでは、相手のリレーで「reply ready」の通知は送られません。質問カードの通知は引き続き届きます。
• リモートのアドレスには https:// を使う必要があります。プレーンな http:// は、ループバックアドレスとプライベートネットワークの範囲でのみ受け付けられます。

アクション #

どの呼び出しも action を指定します。表には、それぞれに必要なものを示します。レベルは、ペアリングしたリレーでそのアクションを許可する最も低い Agents may の設定です。

結果は JSON です。成功した呼び出しには "ok": true、対象の relay、1 行の summary が含まれます。失敗した呼び出しには "ok": false、code、error のテキストが含まれます（エラー）。以下の例では、架空の名前と ID を使って主なフィールドを示します。

0.9.16 で追加 アクションが受け取らない引数が、何の知らせもなく捨てられることはありません。create_session と update_session は REMOTE_RELAY_INVALID_INPUT で呼び出しを拒否し、自分の引数を挙げ、何も変更しません。 create_session does not take: session. Its arguments: relay, text, provider, model, cwd, repo, branch, mode, effort, title, group, wait_seconds. Nothing was created. ほかのアクションはそのまま実行され、受け取らなかった引数を結果の ignored に最大 20 件まで挙げます。空の値（null、""、false、空のリスト）は引数なしと見なされます。プロバイダーによっては、すべてのフィールドを送ってくるためです。

リレーとセッションを探す #

list_relays #

ペアリングしたリレーを、name、url、online、version、permission、unlocked とともに一覧表示します。エージェントセッションが有効なときは、このリレーが "self": true の印付きで先頭に来ます。このリレーの待機の上限も返します。言及なしでも、relay なしでも動作する唯一のアクションです。

{ "action": "list_relays" }

{
  "ok": true,
  "summary": "list_relays: 2 relays, 1 unlocked",
  "self": { "name": "desk" },
  "relays": [
    { "name": "desk", "self": true, "online": true, "version": "0.9.19", "permission": "full", "unlocked": true },
    { "name": "build-box", "url": "https://build-box.example.com", "online": true, "version": "0.9.19", "permission": "full", "unlocked": false }
  ],
  "limits": { "maxWaitSeconds": 600, "maxActiveSessions": 4 }
}

relay_info #

リレーが提供するものを返し、エージェントが新しいセッションのプロバイダー、モデル、フォルダーを選べるようにします。名前、バージョン、プラットフォーム、エージェントのプロンプトを受け付けるかどうか、各プロバイダーとその既定のモデル、モデル、reasoning effort、既定の作業フォルダーと最近の作業フォルダー、リレーモードです。

{ "action": "relay_info", "relay": "build-box" }

0.9.16 で追加 リレーのセッショングループも groups に挙げます。そこでの create_session が指定できるグループです。それぞれに id、name（サイドバーに表示される名前。誰も名前を付けていないグループでは先頭セッションのタイトル）、memberCount があり、最近のアクティビティがあるグループから順に並びます。削除されていないセッションが少なくとも 1 つあるグループだけが、最大 50 件まで挙げられます。それより多い場合は、groupsTotal が総数を示します。メンバーの ID とタイトルは含まれません。リレーのグループを読み取れない場合（例：古い OAR が動いている）、groups は null になり、groupsNote がその理由と、そこでは create_session が group を受け取れないことを示します。

"groups": [
  { "id": "grp_…", "name": "Release 2.4", "memberCount": 3 },
  { "id": "grp_…", "name": "Review: server/", "memberCount": 2 }
]

usage 0.9.10 で追加 #

リレー上の各プロバイダーのプランに何が残っているかを返します（Check Usage を参照）。エージェントはこれで、コストのかかる作業を始める前に確認できます。プロバイダーごとのステータスとメーター（使用量、枠、残り、使用率、リセット時刻）、そこで Claude の使用量の上限によってターンが一時停止しているかどうかです。設定されていないプロバイダーや追跡されていないプロバイダーは、そのように示されます。アカウント名、アドレス、トークンが含まれることはありません。

{ "action": "usage", "relay": "this" }

list_sessions #

セッションを、id、title、provider、model、state、cwd、最後のアクティビティの時刻、メッセージ数とともに一覧表示します。state は running_turn、background_only（エージェントは回答済みで、バックグラウンドの作業がまだ動いている）、idle のいずれかです。tasks には、バックグラウンドエージェントとシェルタスクが挙げられます。

0.9.11 で追加 セッショングループに入っているセッションには group もあります。その id、name、そのグループでのセッションの role（head または member）です。0.9.16 で追加 create_session は、作成するセッションを既存のグループに入れられます。update_session は、セッションをグループ（新しいグループを含む）に移動したり、グループから外したりできます。グループの名前変更、解除、並べ替えはあなたが行います。

{ "action": "list_sessions", "relay": "build-box", "scope": "active" }

read_session #

セッションの最近のメッセージを、そこで起きていることとあわせて読みます。state、まだ書かれている途中の返信（inFlight）、回答を待っている pendingQuestions（0.9.16 で追加 それぞれに kind があり、ask なら ask、セッションが待っているカードなら ask_user）です。0.9.11 で追加 グループに入っているセッションでは、group にほかのメンバーが最大 50 件まで加わります。それぞれに id、title、role、state があり、アーカイブされている場合は archived もあります。

{ "action": "read_session", "relay": "build-box", "session": "3f9c…", "last": 5 }

0.9.12 で追加 セッションの各 tasks には、taskId と output（read_task_output で読める出力があるかどうか）もあります。出力がファイルに書かれるコマンドでは、実行中は health があり、minutesSinceOutput、quiet、quietAfterMinutes（リレーの無出力の設定）を示します。テスト実行の counts があれば、それも含まれます。

read_task_output 0.9.12 で追加 #

バックグラウンドのシェルコマンドまたはモニターの出力の末尾を読みます。タスクコンソールに表示されるのと同じ出力で、タスクの実行中と、終了後 1 時間の間読めます。エージェントは、別のリレー上のビルドがまだ動いているか、無出力になったか、テストが失敗したかを、それを開始したエージェントに尋ねずに確認できます。

結果には次のものが含まれます。task（説明、種類、開始時刻、status、exitCode）、tail（行。色なしのプレーンテキストで、繰り返された行には [×N] の印が付きます）、その前にまだ行がある場合の truncated、タスクの実行中は stall（最後の出力からの分数と、リレーの設定に照らした quiet）、出力がテスト実行の場合はランナーと、成功・失敗・スキップしたテストの数を示す counts です。認証情報はコンソールと同じように伏せられます。出力の末尾しか存在しない場合、出力がもう残っていない場合、エージェントのプロセスに出力を要求したため数秒後に呼び出しを繰り返すべき場合は、note がそのことを伝えます。

{ "action": "read_task_output", "relay": "build-box", "session": "3f9c…", "task_id": "b7k2…", "lines": 50 }

{
  "ok": true,
  "summary": "read_task_output → build-box session 3f9c2a1e task b7k2m9q4: 50 lines, running, last output 14 min ago, 412 passed, 2 failed",
  "task": { "id": "b7k2…", "description": "npm test", "type": "local_bash", "status": "running", "exitCode": null },
  "stall": { "minutes": 14, "since": "2026-10-18T09:12:00.000Z", "quiet": true, "quietAfterMinutes": 10 },
  "counts": { "runner": "vitest", "passed": 412, "failed": 2, "skipped": 0, "final": false },
  "tail": ["…"],
  "truncated": true
}

実行中ではなく、過去 1 時間以内に終了したのでもないタスクには REMOTE_RELAY_NOT_FOUND が返ります。0.9.12 より古いリレーは REMOTE_RELAY_UNSUPPORTED を返します。

プロンプトの送信 #

send #

既存のセッションにプロンプトをキューに入れ、返信を待ちます。

{ "action": "send", "relay": "build-box", "session": "3f9c…", "text": "Did last night's deploy go through? Answer in two lines." }

{
  "ok": true,
  "relay": "build-box",
  "status": "done",
  "session": "3f9c…",
  "message_id": "b41e…",
  "reply": { "text": "Yes. The deploy finished at 02:14 and the health check is green.", "model": "…" }
}

Claude セッションの課金の切り替え 0.9.18 で追加 #

provider を付けた send は、Claude のセッションをサブスクリプションと Claude API キーの間で移し、メッセージを送ることを 1 回の呼び出しで行います。切り替えが拒否されれば何も送られず、メッセージが拒否されれば何も切り替わりません。もう一方の課金が、対象のリレーで設定されている必要があります。承認カードが出る場合、そこには Switches billing to API key または Switches billing to subscription と表示されます。

• 対象のリレーが切り替えを拒否した場合、そこで Claude API または Claude が設定されていないか月間上限に達しているときは REMOTE_RELAY_PROVIDER_UNAVAILABLE が、セッションのモデルが相手側の一覧にないときは REMOTE_RELAY_UNKNOWN_MODEL が返ります。remoteCode には、そのリレー自身のコードが入ります。例：CLAUDE_API_CAP_REACHED。
• 0.9.18 より前のリレーは切り替えられません。呼び出しは REMOTE_RELAY_UNSUPPORTED で拒否され、何も送られません。
• provider がなければ、セッションは課金方法を維持します。上限に達している間に API キーで動くセッションへ send すると拒否され、何もキューに入りません。provider: "claude" を付けて送ってサブスクリプションに移すか、上限を引き上げるようユーザーに頼んでください。

create_session #

新しいセッションを開始し、最初のプロンプトを渡します。新しいセッションは開始元の会話について何も知らないため、プロンプトはそれだけで意味が通じる必要があります。

send と同じく text、wait_seconds、mode、model、effort を受け取り、さらに次のものを受け取ります。

エージェントが省略したものは、対象のリレーが提供する範囲で、エージェントが作業しているセッションに合わせられます。OpenAI Image のチャットはこの方法では開始できません。

{
  "action": "create_session",
  "relay": "this",
  "title": "Review: server/",
  "cwd": "/home/dev/projects/shop",
  "text": "Review the code under server/ for missing input checks. List findings with file and line. Change nothing."
}

Claude Cloud のセッションは、フォルダーの代わりにリポジトリを受け取ります。

{
  "action": "create_session",
  "relay": "this",
  "provider": "claude-cloud",
  "repo": "example-org/sample-repo",
  "branch": "feature/banner",
  "text": "On branch feature/banner, change the sample banner text to \"Hello\" and push. Report what changed.",
  "wait_seconds": 60
}

結果は send と同じで、それに加えてセッションの開始時の設定が含まれます。provider、model、mode、effort、title、クラウドセッションでは repo / branch です。0.9.16 で追加 また group もあり、新しいセッションが入ったセッショングループを list_sessions と同じ形（id、name、role）で、または null で示します。

グループに入れる 0.9.16 で追加 #

group がない場合、このリレーで開始したセッションは、開始元のセッションのグループに加わるか、開始元のセッションを先頭とするグループを新しく作ります。ペアリングしたリレーで開始したセッションは、どのグループにも入りません。

group がある場合、新しいセッションは代わりにその既存のグループに入ります。このリレーでも、ペアリングしたリレーでも同じです。エージェントはグループを、その id で、または relay_info が挙げる名前（大文字と小文字は区別しません）で指定します。空の group は指定なしと見なされます。

{
  "action": "create_session",
  "relay": "build-box",
  "group": "Release 2.4",
  "text": "Run the release checklist in docs/RELEASE.md up to the tag. Report each step."
}

リレーは、モデルの場合と同じく、承認カードを表示する前に対象でグループを調べます。カードにはそのグループが示されます（Group: Release 2.4 (grp_…)）。次の場合は何も作成されません。

• 対象に、その ID または名前のグループがない。呼び出しは REMOTE_RELAY_UNKNOWN_GROUP で拒否され、error と groups にそこにあるグループが挙げられます（最大 20 件。それより多い場合は groupsTotal）。 Relay "build-box" has no session group "Relase". Groups there: Release 2.4 (grp_…), … No session was created.
• その名前が複数のグループに当てはまる。同じコードで、その名前のグループが挙げられます：… Pass the id.
• 調べてから開始するまでの間にグループが解除された。同じコードです。
• 対象のグループを読み取れない。group に対応していない古いリレーは REMOTE_RELAY_UNSUPPORTED（The target relay doesn't support groups on create_session yet: …）を返します。応答しないリレーやトークンを拒否するリレーは、通常のコードを返します。

セッションは作成されたものの、指定したグループに入らなかった場合、結果には groupWarning が含まれ、summary は (no group: …) で終わり、note がエージェントにそれをあなたに伝えるよう求めます。その後、あなたが手動でセッションを移動できます。

create_session が受け取るのは既存のグループだけです。セッションを新しいグループに入れるには、エージェントが後からその名前で update_session を呼び出します。グループの名前変更、解除、並べ替えはあなたが行います。

update_session 0.9.16 で追加 #

ほかのセッションの次のターン以降の設定を、プロンプトを送らずに変更し、現在の設定と変更された内容を返します。このリレーでも、ペアリングしたリレーでも動作します。

少なくとも 1 つの設定が必要です。それ以外の引数は拒否され、何も変更されません。mayCreateSessions は設定に含まれません：Whether a session may start sessions is the owner's setting alone.

{ "action": "update_session", "relay": "this", "session": "3f9c…", "model": "claude-sonnet-5-5", "effort": "low", "group": "Release 2.4" }

{
  "ok": true,
  "summary": "update_session → desk session 3f9c2a1e: model, effort, group",
  "session": "3f9c…",
  "settings": {
    "model": "claude-sonnet-5-5", "effort": "low", "mode": "agent", "auto_compact_window": "auto",
    "title": "Review: server/", "group": { "id": "grp_…", "name": "Release 2.4", "role": "member" },
    "thinking_enabled": true, "thinking_display": "summarized", "cwd": "/home/dev/projects/shop"
  },
  "changed": ["model", "effort", "group"]
}

新しいフォルダーへの変更では、CLI が再起動されたかどうか（relaunched）も返され、新しいグループは groupCreated として返されます。何も変更しない呼び出しは changed: [] を返し、誰にも確認しません。note には、エージェントが知っておくべきことが入ります。例：ウィンドウが最も近い値に丸められたこと、ウィンドウと思考は Claude のセッション（0.9.18 で追加 Claude API のセッションを含む）にだけ適用され、ほかのプロバイダーでは何も変わらないこと。0.9.17 で追加 DeepSeek のセッションにもそのメモが付きますが、そこではウィンドウは有効になり、0 は 400,000 トークンを意味します。thinking_enabled は効きません。DeepSeek のセッションは常に思考するためです。

誰が何を変更できるか。 エージェントが自由に変更できるのは、自分の会話が開始したセッションだけです。このリレー上のセッション、または、ペアリングしたリレーがこの会話を開始元として記録しているそのリレー上のセッションです。それ以外のセッション（あなたのもの、別のエージェントのもの、またはそのエージェントを開始したもの）は、先にあなたの Allow が必要です。質問カードは会話とリレーごとに一度確認し、セッションを示して変更内容を挙げます（Model: … · Effort: … · Group: …）。Allow は、その会話がそこでそのようなセッションに対して後で行う変更に適用されます。Deny は呼び出しを REMOTE_RELAY_PERMISSION で拒否します。確認に使える実行中のターンがない会話には REMOTE_RELAY_NO_ACTIVE_TURN が返ります。相手のリレーも同じルールを自分で守ります。エージェントが自分の動いている会話を変更することはありません。ask と plan のモードでは、書き込みアクションに対する通常のカードもあわせて適用されます。

何かが変更される前に、リレーは対象で呼び出し全体を確認します。モデルと reasoning effort、グループ、フォルダー、あなたへの確認が必要かどうかです。不明なモデル、不明なグループ ID、2 つのグループに当てはまるグループ名、リレーが使えないフォルダー、作業中のセッションに対する新しいフォルダーのいずれかがあると、カードを出す前に呼び出しが拒否され、何も変更されません。

グループ。

• リレーにない名前を指定すると、その名前で新しいグループができます。グループ ID は存在している必要があります（REMOTE_RELAY_UNKNOWN_GROUP）。
• あなたが作ったグループが、この方法で削除されることはありません。エージェントが最後のセッションを外しても、グループは残り、サイドバーに group · empty（グループ · 空）と表示されます。そのメニューから名前を変更するか解除するか、エージェントに再び指定させてください。自動で削除されることはありません。
• エージェントが作ったグループ（名前の指定によるものでも、セッションの開始によるものでも）は、空になると消えます。

フォルダー。 新しい cwd を指定すると、セッションの CLI がそのフォルダーで再起動します。そこでターンがキューに入っているか実行中の間、またはバックグラウンドタスクが動いている間は、REMOTE_RELAY_BUSY で拒否されます：The session cannot move to another folder now: …。フォルダーは、リレーが使えるものである必要があります。まだ開始していないセッションは、そのフォルダーを最初の開始時に使います。CLI が再起動しない場合でも、フォルダーは次の開始のために保存され、結果にそのことが示されます。Claude Cloud では使えません。Claude Cloud はリポジトリのクローン上で作業するためです。

モードをこの方法で設定すると、別のモードを指定するか、別のモードの呼び出し元から来る、次の send まで有効です。mode のない send は、呼び出し元自身のモードを渡します。

ほかの項目が書き込まれた後に 1 つの手順が失敗した場合でも、結果の changed には書き込まれたものが挙げられます。開いているページには、すべての変更がすぐに反映されます。古い OAR が動いているリレーは REMOTE_RELAY_UNSUPPORTED を返します。

受け付けられるモデル 0.9.13 で追加 #

send または create_session の model は、承認カードを出す前に、対象のリレーでそのプロバイダーについて New Chat（新しいチャット）が提示する一覧（relay_info が示すのと同じ一覧）と照合されます。一覧にないモデルは REMOTE_RELAY_UNKNOWN_MODEL で拒否され、何も作成も送信もされません。

Unknown model 'gpt-5-4' for Copilot on relay "build-box"; did you mean 'gpt-5.4'? Valid ids: … Nothing was sent.

結果には、近い候補を示す suggestions と、有効な ID を示す models も含まれます。0.9.13 より前は、そのような ID で別のモデルのセッションが作成され、後からその ID で send を呼び出してもそのセッションに届きませんでした。

0.9.19 で追加 Copilot のモデル ID は区切りにドットを使います。Claude の claude-opus-5-5 ではなく claude-opus-5.5 です。Copilot はほかのプロバイダーの ID を、何かを作成する前に拒否します。通常は COPILOT_MODEL_UNAVAILABLE と最も近い候補を返しますが、create_session でその ID をほかの 1 つのプロバイダーだけが載せている場合は、CLAUDE_PROVIDER_REQUIRED のようにそのプロバイダーのコードを返します。また、Copilot のセッションがモデル名を理由に別のプロバイダーへ移ることはありません。

実行されるモデルが要求したものと異なる場合は、結果の modelNote がそのことを示します。対象のリレーにそのプロバイダーの一覧がまだない場合（モデルの検出がまだ実行されていないか失敗した場合）、モデルは確認されないまま渡され、modelNote がそのことも示します。リレーは、ほかのリレーのエージェントがそのリレーでセッションを開始するときにも、不明な Copilot のモデルを拒否します。

wait #

send または create_session が時間内に受け取れなかった返信を待ち続けます。

{ "action": "wait", "relay": "build-box", "session": "3f9c…", "message_id": "b41e…", "wait_seconds": 300 }

待機と返される内容 #

send、create_session、wait は、エージェントが wait_seconds で求めた時間だけ返信を待ちます。上限は、エージェントが動いているリレーの Longest wait per tool call（ツール呼び出しごとの最長待機時間）（Settings → Relays → Agent sessions）で、既定では 10 分、2 分から 60 分の間で調整できます。呼び出しがリレーの許す時間より長く求めた場合は、結果の note がそのことを示します。時間切れになると、エージェントはその時点までの内容を受け取り、もう一度 wait を呼び出せます。

待機しているターンも、Settings → General（設定 → 一般）の Max turn duration（ターンの最大時間）に計上されます。

結果の status は、相手のセッションの状況を示します。

このような結果にはどれも session と message_id が含まれ、リレーにセッションを開くリンクがあれば openUrl も含まれます。

ほかのセッションを操作する #

answer_question #

ほかのセッションで待っている質問カードに回答します。エージェントは、あなたが自分で判断するよう指示していない限り、まずあなたに尋ねるよう指示されています。

choices と answer のどちらかが必要です。エージェントは自分の質問には回答できず、リレーの承認カードにも回答できません。それらはあなたが回答するものです。0.9.16 で追加 ask にも回答できません。answer_question は、誰かを呼び出す前に REMOTE_RELAY_FORBIDDEN でそれを拒否します。

{ "action": "answer_question", "relay": "build-box", "question_id": "q_7d2…", "choices": ["Merge"] }

stop #

UI の Stop（停止）と同じように、セッションで実行中のターンを停止します。結果は、停止が要求されたのか、何も実行されていなかったのかを示します。

{ "action": "stop", "relay": "this", "session": "3f9c…" }

archive #

セッションをアーカイブします。

{ "action": "archive", "relay": "this", "session": "3f9c…" }

セッションの監視 #

0.9.10 で追加 エージェントは、何度も尋ねる代わりにセッションを購読し、そこで何かが起きたときに起こしてもらえます。このリレー（エージェントセッションが有効な場合）でも、ペアリングしたリレーでも動作します。

購読は通知するだけです。何も承認せず、何にも回答しません。イベントが求めることは、これまでどおり、あなたが判断するか、エージェントがもともと許された範囲で判断します。

subscribe #

1 つの会話が同時に持てる購読は 20 件です。エージェント自身の会話が見守られることはありません。

{ "action": "subscribe", "sessions": ["3f9c…", "a12b…"], "events": ["question_asked", "error", "all_idle"] }

{
  "ok": true,
  "summary": "subscribe → desk: 2 sessions (sub_ab12cd34ef)",
  "subscription": {
    "id": "sub_ab12cd34ef",
    "sessions": [ { "id": "3f9c…", "title": "Review: server/" }, { "id": "a12b…", "title": "Review: web/" } ],
    "events": ["question_asked", "error", "all_idle"],
    "once": false,
    "stalledMinutes": 15
  }
}

起こす回数を減らす 0.9.16 で追加 #

起こされるたびに、見守る側では 1 回の完全なターンが実行されます。subscribe の 3 つのオプションで、その回数を減らせます。question_asked、question_answered、error は、どのオプションでも保留されません。それ以外のイベントは、task_failed、stalled、all_idle も含めて保留されます。

{
  "action": "subscribe",
  "sessions": ["all"],
  "exclude": ["77aa…"],
  "digest_minutes": 30,
  "quiet_hours": { "from": "23:00", "to": "06:00", "tz": "Europe/Berlin" }
}

• digest_minutes。 購読のイベントがまとめられ、N 分ごとに 1 つのメッセージとして届きます。最も早くて購読の作成から N 分後に最初のメッセージが届き、以降は前回から N 分後に届きます。メッセージには Digest of 4 events (subscription sub_… every 30 min; questions and errors come at once): と書かれます。イベントが 1 つだけのダイジェストは、そのイベントとして表示されます。
• quiet_hours。 IANA タイムゾーンの現地時刻による、毎日の時間帯です。from と to は時刻（HH:MM、00:00 から 23:59）で、異なる値にする必要があります。時間帯は午前 0 時をまたいでもかまいません。その間に起きたことは待機し、時間帯が終わると 1 つのメッセージとして、Held during quiet hours (23:00–06:00 Europe/Berlin): 3 events, delivered now that the window has ended; questions and errors came at once. という行とともに届きます。時間帯の中ではハートビートは作られません。ダイジェストが時間帯の中で届けるはずのイベントは、時間帯の終わりに移ります。
• exclude。 all セッションへの購読は、これらのセッションを無視します。all_idle、stalled、ハートビートでも同じです。セッションのリストと一緒に指定すると拒否されます：exclude goes with sessions ["all"] only; a list of sessions names what it watches。

時計の変更。 時間帯は、そのタイムゾーンの時計に従います。時計が戻されて to が 2 回来る夜は、時間帯は 1 回目で終わり、繰り返される 1 時間の間に再び入ることはありません。時計が進められて to が飛ばされる夜は、時計が進んだ瞬間に終わります。既知の制限が 1 つあります。繰り返される 1 時間の中に from がある場合、時間帯は 1 回目で始まり、2 回目では from より前の分は時間帯の外として扱われます。

誤った値は、何が誤っているかとともに拒否されます。例：quiet_hours from and to must be times of day as "HH:MM" (00:00 to 23:59)、quiet_hours from and to must differ、quiet_hours tz "Berlin" is not an IANA time zone (for example "Europe/Berlin", "America/New_York", "UTC")。すべてのフィールドが空の quiet_hours は指定なしと見なされます。

• once との組み合わせ。 1 回限りの購読を終わらせるイベントも、ダイジェストとサイレント時間に従います。購読はすぐに終了し、イベントはそれらが許したときに届きます。
• 複数の購読。 見守る側の複数の購読が受け取ったイベントは、そのうち最初に許した購読のタイミングで届きます。オプションのない購読は、すぐに届けます。
• 1 時間に 20 回という1 時間あたりの上限は、オプションに加えて引き続き適用されます（イベントの届き方）。
• 保留されたイベントと、その配信予定時刻は、リレーの再起動後も保持されます。
• 承認カードには、オプションが示されます（digest every 30 min、quiet 23:00–06:00 Europe/Berlin、except 1 it leaves out）。

見守る側自身のプロンプトは繰り返し届きません。 見守る側が自分で send または create_session でセッションにプロンプトを送り、その呼び出しまたは後の wait で完了した返信を受け取った場合、そのターンの turn_end で 2 回目に起こされることはありません。まだ待っている間は、turn_end は保留されます。そのターンのエラーと質問は引き続き届きます。待たなかったプロンプト（wait_seconds: 0 で wait もなし）では、これまでどおり turn_end で起こされます。once の購読を終わらせる turn_end でも同じです。

イベント #

既定のイベント 0.9.13 で追加 #

events を指定しない購読は、question_asked、error、turn_end、subagent_finished、task_failed、stalled、all_idle を受け取ります。終了したバックグラウンドのサブエージェントは見守る側を起こし、失敗したタスクや 0 以外で終了したタスクも同様ですが、正常に終了したシェルコマンドやモニターは起こしません。作業中のセッションは 1 分ほどごとにそうしたタスクを終え、そのたびに見守る側はコンテキスト全体を使う 1 回のターンを費やすことになるためです。すべてのタスクの終了を受け取るには、subagent_finished の代わりに task_finished を含めてイベントを指定し、開始も受け取るには task_started を加えます。

0.9.13 より前に events なしで作られた購読は、自動でこの既定に切り替わります。イベントを指定した購読は、その指定を維持します。古い OAR が動いているペアリングしたリレーは独自の既定を適用し、subagent_finished を名前で指定すると拒否します。

イベントの届き方 #

OAR は、見守る側の会話に短いメッセージを書き込みます。それはコンパクトなイベント行として表示され、あなたのメッセージとして表示されることはありません。冒頭には、それが何であるかを示す行が付きます。

[relay event · automated message from OAR, not from the user; it approves nothing]
[relay event] session "Review: server/" (3f9c…): turn_end (done) "Found 4 places without input checks: …"
[relay event] all_idle: no turn or task is running in the 2 watched sessions (subscription sub_ab12cd34ef)

• 見守る側がアイドルなら、メッセージは新しいターンを開始します。ターンの途中なら、下の表を参照してください。
• 30 秒以内のイベントは 1 つのメッセージとして届きます。
• 1 時間に 20 回起こした後は、残りは 10 分ごとのダイジェストとして届きます。question_asked と error（0.9.16 で追加 と question_answered）は引き続きすぐに届きます。このダイジェストと購読の digest_minutes が重なった場合は、1 つの Digest of 行に両方が示されます。
• 0.9.16 で追加 購読の digest_minutes と quiet_hours は、それ以外のイベントをさらに長く保留します。

ペアリングしたリレーで #

そのリレーは会話の中でロックが解除され、少なくとも読み取りを許可している必要があります。また、相手のリレーがほかのリレーのエージェントを受け付けている必要があります。ペアリングは一方向で十分です。このリレーは数秒ごとにイベントを取得し、その行は相手のリレーの名前で始まります。

[relay event] build-box · session "Nightly deploy" (77aa…): turn_end (done) "Deployed. The health check is green."

接続が切れた場合、相手のリレーは起きたことを、購読ごとに最大 500 件のイベントまで 7 日間保持し、再び応答するようになると、link_lost 行と link_restored 行の間に、replayed（リプレイ）のタグが付いた 1 つの行として届けます。古い OAR が動いているリレーは、更新が必要だと応答します。

0.9.16 で追加 ペアリングしたリレーへの購読のダイジェストとサイレント時間は、見守る側がいるこちらで適用されます。exclude は相手のリレーにも渡され、all_idle、stalled、ハートビートに使われます。リプレイされたイベントも、ほかのイベントと同じくダイジェストとサイレント時間に従います。そのとき link_restored 行に、そのうち何件が保留され、後で届くかが示されます。古い OAR が動いているペアリングしたリレーは exclude を知りません。このリレーはそれらのセッションのイベントを引き続き捨てますが、相手のリレーは all_idle、停滞の判定、ハートビートの一覧でそれらを数えます。

unsubscribe #

1 つの購読を終了します。"all" を指定すると、指定したリレー上でその会話が持つすべての購読を終了します。

{ "action": "unsubscribe", "subscription_id": "sub_ab12cd34ef" }

list_subscriptions #

会話の購読を表示します。有効な購読と、過去 1 時間以内に終了した購読をその理由とともに示します。watcher を指定すると、ほかの会話の購読を表示します。エージェントは、購読を引き継ぐ前にこの方法で確認します。

{ "action": "list_subscriptions" }

各購読には、セッション、イベント、once、match、stalledMinutes、heartbeatMinutes が示され、0.9.16 で追加 設定されていれば digestMinutes、quietHours、exclude も示されます。有効な購読には、ダイジェストまたはサイレント時間によって現在保留されているイベントの数（heldCount）と、そのうち最初のものの配信予定時刻（nextDeliveryAt。保留されているものがなければ null）も示されます。終了した購読がこれらを示すのは、最後のイベントがまだ保留されている間だけです。例：サイレント時間の中で発生した once の後。

{
  "id": "sub_ab12cd34ef",
  "scope": "all",
  "sessions": "all",
  "digestMinutes": 30,
  "quietHours": { "from": "23:00", "to": "06:00", "tz": "Europe/Berlin" },
  "exclude": ["77aa…"],
  "heldCount": 3,
  "nextDeliveryAt": "2026-10-24T04:00:00.000Z"
}

transfer_subscriptions #

ほかの会話のすべての購読を、この会話に移します。例：新しいセッションが古い見守る側に代わる場合。必ず承認カードであなたに確認します。

{ "action": "transfer_subscriptions", "from": "c0de…" }

購読の有効期間 #

購読はリレーの再起動後も保持されます。購読が終了するのは次の場合です。

• エージェントが unsubscribe を呼び出すか、あなたが見守る側の一覧で Unsubscribe を押した
• 見守る側または見守られているセッションがアーカイブされた
• once 付きで作成され、通知が発生した
• ペアリングしたリレーの場合、ペアリングが削除された

予約 0.9.16 で追加 #

エージェントは、このリレーに、後でプロンプトをキューに入れさせることができます。入れる先は、エージェント自身の会話でも、ここにあるほかのセッションでもかまいません。エージェントの CLI 自体のタイマーとは異なり、予約はリレーの再起動と更新の後も保持されます。あなたの側から見た説明は、予約プロンプトを参照してください。

予約には、エージェント自身の会話に対するものであっても、Agents may start and use sessions on this relay が必要です。予約はエージェントが動いているリレーが保持します。ペアリングしたリレーを指定した呼び出しは REMOTE_RELAY_UNSUPPORTED で拒否されます。

schedule #

少なくとも at または every_minutes が必要です。

{ "action": "schedule", "title": "Nightly review", "at": "2026-11-02T02:00:00Z", "every_minutes": 1440, "text": "Review yesterday's merged changes under server/ and list anything risky." }

{
  "ok": true,
  "summary": "schedule → desk: every 1440 min, next 2026-11-02T02:00:00.000Z (sch_3f9c2a1e7b04)",
  "schedule_id": "sch_3f9c2a1e7b04",
  "schedule": { "id": "sch_3f9c2a1e7b04", "title": "Nightly review", "everyMinutes": 1440, "once": false, "nextFireAt": "2026-11-02T02:00:00.000Z" }
}

時刻になると、リレーはテキストを [relay schedule <id> "<title>" · … automated message from OAR, not from the user; it approves nothing] で始まるメッセージとしてキューに入れます。ターンは、対象のセッション自身のリレーモードで実行されます。ターンの実行中に届いたメッセージはキューに入るか、軌道修正に対応したプロバイダーではそのターンに軌道修正として入りますが、ユーザーとして話す軌道修正のメモが付くことはありません。

• 逃した時刻。 リレーが停止している間に過ぎた時刻は、リレーが戻ったときに 1 回だけ実行されます。逃した間隔ごとに 1 回ずつ実行されるわけではありません。繰り返しの予約は、その後も元の刻み（1 回目の時刻に間隔の整数倍を足した時刻）を守ります。
• 積み重ならない。 前回の実行で入れたメッセージがまだキューで待っている間は、繰り返しはスキップされます（一覧の skippedCount）。
• ホップ。 メッセージは、予約を設定したターンの来歴をホップ数も含めて引き継ぎます。そのため予約が、そのターンから直接送ったプロンプトより少ないホップ数でプロンプトを先へ渡すことはありません（リレーをまたぐ場合）。

ほかのセッション。 session がある場合、予約はそのセッションにプロンプトを送ります。これは send と同じように制限されます。ask と plan のモードではカードであなたが承認し、確認が求められるまでのほかのエージェントへの 30 件のプロンプトにも数えられます。設定時に 1 回、実行のたびに 1 回です。そのカウントを使い切ると、実行は保留されます。list_schedules には heldForApproval と heldSince が表示されます。予約を設定した会話にあなたが書き込むか、その会話のエージェントがほかのエージェントへの次のプロンプトのために出すカードで Allow を選ぶと、保留は解けます。リレーは 1 分ごとに確認し直します。エージェント自身の会話に対する予約は、数えられることも保留されることもありません。

list_schedules #

その会話に対して実行される予約、またはその会話が設定した予約を一覧表示します。有効な予約と、過去 1 時間以内に終了した予約を endReason（unscheduled、fired、archived、deleted）とともに示します。

各予約には、id、session（ID とタイトル）、ほかの会話が設定した場合は setBy、title、text の冒頭、at、everyMinutes、once、nextFireAt、lastFiredAt、firedCount、スキップがあった場合は skippedCount、保留中は heldForApproval と heldSince が含まれます。

unschedule #

会話の予約を 1 つ終了します。その会話に対して実行される予約、またはその会話が設定した予約です。

予約が終了するとき #

予約が終了するのは、once の場合の実行後、unschedule またはヘッダーの ⏰ 一覧の Cancel（キャンセル）による場合、そして予約の実行先のセッションまたは予約を設定した会話がアーカイブまたは削除された場合です。コンパクト化では、どちらの種類の予約も終了せず、新しい会話に移ります。1 つの会話に対して実行される有効な予約は最大 20 件で、1 つの会話がほかのセッションに設定できる予約も最大 20 件です。それを超えると REMOTE_RELAY_SCHEDULE_LIMIT になります。

作業を止めない質問 0.9.16 で追加 #

エージェントは、あなたに質問して作業を続けることができます。質問はそのセッションと Inbox（受信箱）にカードとして表示され、エージェントは後で回答を受け取ります。あなたの側から見た説明は、質問と Inbox を参照してください。

ask #

{ "action": "ask", "question": "Ship the migration tonight or wait for the review?", "options": ["Tonight", "Wait"], "recommendation": "Wait", "detail": "The review covers the index change; the rest is tested." }

{ "ok": true, "question_id": "ask_7d2…", "status": "pending", "summary": "ask → desk: question ask_7d2… pending" }

ask は、question_id と status: "pending" を付けてすぐに戻ります。エージェントは回答に左右されない作業を続け、回答待ちの間に同じことを再び尋ねないようにします。

回答。 あなたが質問に回答するか閉じると、エージェントはリレーイベント question_answered を受け取ります。そこには question_id、あなたの answer、選んだ choice、閉じた場合は dismissed、そして回答したリレーを示す via（ask が保持されているリレー、またはあなたが Inbox を使ったペアリングしたリレー）が含まれます。購読は必要ありません。このイベントは緊急扱いで、ダイジェストやサイレント時間で保留されることはありません。自動のもので、ほかには何も承認せず、ループ防止ではあなたからのメッセージとして数えられません。ask に回答しても、エージェント同士が送り合えるプロンプトのカウントはリセットされません。

回答できる人。 あなただけです。そのセッションか Inbox（このリレーの Inbox、またはこのリレーとペアリングしたリレーの Inbox）で回答します。answer_question は ask を拒否します。

利用条件。

• エージェント自身の会話についての ask、list_questions、withdraw には、設定も言及も必要ありません。
• session がある場合、エージェントはほかのセッションに代わって質問します。このリレーでは Agents may start and use sessions on this relay が、ペアリングしたリレーでは Agents may が少なくとも Read and prompt で、かつリレーのロックが解除されていることが必要です。そのような ask は書き込みです。ask と plan のモードではカードであなたが承認し、ホップ数の制限（リレーをまたぐ場合）に従います。ループ防止ではカウントされません。カードはそのセッションに表示され、そのセッションと質問した会話の両方が回答を受け取ります。
• ペアリングしたリレー上のセッションについての ask は、そのリレーで保持されます。このリレーは、ask が開いている間、5 秒ごとに回答を確認します（そのリレーが応答しない間は 30 秒ごと）。古い OAR が動いているリレーは REMOTE_RELAY_UNSUPPORTED を返します。

回答待ちにできる ask は、質問する会話ごとに最大 20 件、対象のセッションごとに最大 20 件です。それを超えると REMOTE_RELAY_QUESTION_LIMIT になります。ask に有効期限はありません。

list_questions #

会話の ask を一覧表示します。回答待ちのものと、過去 1 日以内に回答された、閉じられた、または取り下げられたものを、ステータスと回答とともに示します。session を指定すると、ほかのセッションについての ask を示します。ペアリングしたリレーでは、この会話がそこで出した ask を一覧表示します。そこでの read_session は、セッションの回答待ちの質問をすべて一覧表示します。

withdraw #

まだ回答待ちの ask を取り下げます。取り下げられるのは、質問した会話だけです。

ask は、そのセッションがアーカイブまたは削除されたとき（誰にも知らされません）と、ask が保持されているリレーとのペアリングが削除されたときにも終了します。コンパクト化では、ask は新しい会話に移ります。

制限 #

エラー #

拒否された呼び出しは、エージェントが対処に使える code を付けて返されます。