agent-relay-runner 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -84,6 +84,9 @@ export interface RunnerSpawnConfig {
   providerConfig: ProviderConfig;
   env: Record<string, string>;
   controlPort: number;
+  // Stage 2 (#215): the MCP endpoint the agent connects to — the runner-local proxy URL when the
+  // proxy is active. Undefined → the adapter targets the relay's MCP endpoint directly (Stage 1).
+  relayMcpEndpoint?: string;
   monitor?: {
     deliver(messages: Message[]): Promise<number[]>;
   };

package/src/adapters/claude.ts

@@ -204,7 +204,7 @@ export class ClaudeAdapter implements ProviderAdapter {
     const args = [
       ...rigPrefix,
       ...pluginDirs.flatMap((dir) => ["--plugin-dir", dir]),
-      ...(profileAllowsRelayFeature(config, "mcp") ? relayMcpClaudeConfigArg(config.relayUrl) : []),
+      ...(profileAllowsRelayFeature(config, "mcp") ? relayMcpClaudeConfigArg(config.relayUrl, config.relayMcpEndpoint) : []),
       ...(profileAllowsRelayFeature(config, "statusLine") ? sessionStatusLineSettingsArgs(defaultArgs, config.providerArgs) : []),
       ...(config.systemPromptAppend ? ["--append-system-prompt", config.systemPromptAppend] : []),
       ...providerArgs,

package/src/adapters/codex.ts

@@ -261,7 +261,7 @@ export class CodexAdapter implements ProviderAdapter {
         ...codexModelConfigArgs(config.model, config.effort),
         ...codexApprovalConfigArgs(config.approvalMode),
         ...(profileAllowsRelayFeature(config, "skills") ? bundledSkillConfigArgs() : []),
-        ...(profileAllowsRelayFeature(config, "mcp") ? relayMcpCodexConfigArgs(config.relayUrl) : []),
+        ...(profileAllowsRelayFeature(config, "mcp") ? relayMcpCodexConfigArgs(config.relayUrl, config.relayMcpEndpoint) : []),
         ...codexToolOutputTokenLimitConfigArgs(config),
         ...codexManagedConfigArgs(),
         "--listen",

package/src/relay-mcp-proxy.ts

@@ -0,0 +1,383 @@
+import { errMessage, isRecord } from "agent-relay-sdk";
+import { logger } from "./logger";
+
+// Loose fetch signature so tests can inject a plain async stub without Bun's `preconnect`
+// member; the real global `fetch` satisfies it.
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+// Stage 2 of #213/#215 — the Runner becomes the MCP endpoint the agent connects to,
+// fronting the relay. The agent's MCP client points at this localhost server instead of
+// directly at the relay, so the Runner owns the relay connection, reconnect/backoff, and a
+// durable buffer. A relay restart/crash becomes invisible to the agent.
+//
+// This is a TRANSPARENT JSON-RPC pass-through to the relay's `/api/mcp` (which stays the
+// sole enforcement authority). It intervenes in exactly four places:
+//
+//   1. `initialize`   — forward, then advertise `capabilities.tools.listChanged: true`,
+//                       the live-tool-set capability the relay's static endpoint can't.
+//   2. `tools/list`   — forward (the relay already scope-filters per token), then context-
+//                       NARROW: hide tools that don't apply to this agent's workspace mode/
+//                       state (e.g. `relay_workspace_*` for a non-worktree agent). Strictly
+//                       a subset — never widens. Served from a last-known cache during a blip.
+//   3. `tools/call`   — forward with the runner's LIVE token; for bufferable writes during a
+//                       relay outage, enqueue durably + return a synthetic "queued" ok so the
+//                       call is never lost. Mutating spawn/shutdown are forwarded, never local.
+//   4. `GET` (SSE)    — the server→client notification channel; emits
+//                       `notifications/tools/list_changed` when a transition changes the
+//                       narrowed set, so the agent's tool menu updates mid-session.
+//
+// Narrow-never-widen is the safety invariant: filtering `tools/list` is UX/token-efficiency,
+// NEVER enforcement. The proxy can only ever surface a subset of what the relay's scope filter
+// already returned, so a proxy bug can never become an auth bypass — the relay owns the lock at
+// `tools/call`, the proxy owns the menu.
+
+const PROXY_PATH = "/mcp";
+// Relay-side failures we treat as "relay down" (buffer/serve-cache), as opposed to a real 4xx
+// rejection that must be surfaced to the agent verbatim.
+const GATEWAY_STATUSES = new Set([502, 503, 504]);
+const SSE_KEEPALIVE_MS = 25_000;
+
+// The write tools whose loss during a relay outage is unacceptable and whose result the agent
+// does not need synchronously — safe to queue durably and replay on reconnect. Reads, claims
+// (409 contention), spawn/shutdown (need a real ack) are deliberately NOT bufferable.
+export const DEFAULT_BUFFERABLE_TOOLS = new Set<string>([
+  "relay_send_message",
+  "relay_reply",
+  "relay_workspace_ready",
+]);
+
+// Tools surfaced ONLY to an agent that owns a live isolated worktree. For any other agent the
+// proxy narrows them out of `tools/list` even though the token scope permits them (the relay
+// would return them). This is the context the coarse token scope can't express (#214/#215).
+const WORKTREE_ONLY_TOOLS = new Set<string>([
+  "relay_workspace_status",
+  "relay_workspace_ready",
+  "relay_workspace_deps",
+  "relay_workspace_list",
+  "relay_workspace_claim",
+  "relay_workspace_release",
+  "relay_workspace_land",
+]);
+
+export interface ProxyContext {
+  // The agent owns a live (non-terminal) isolated git worktree → workspace tools apply.
+  isolatedWorktree: boolean;
+}
+
+export interface BufferedToolCall {
+  tool: string;
+  arguments: Record<string, unknown>;
+  idempotencyKey: string;
+}
+
+export interface RelayMcpProxyOptions {
+  // The relay's MCP endpoint, e.g. http://localhost:4850/api/mcp.
+  relayMcpEndpoint: string;
+  // The runner's LIVE relay token (read on every forward so rotation is invisible to the agent).
+  getToken(): string | undefined;
+  // The bearer the agent must present to this localhost proxy (a per-session secret the runner
+  // mints and injects into the agent env). Decouples the agent from the rotating relay token.
+  authSecret: string;
+  // Persist a bufferable write durably for replay on reconnect (wired to the runner outbox).
+  enqueueBuffered(call: BufferedToolCall): void;
+  initialContext?: ProxyContext;
+  bufferableTools?: Set<string>;
+  // Test seam.
+  fetchImpl?: FetchLike;
+}
+
+interface JsonRpcMessage {
+  jsonrpc?: string;
+  id?: string | number | null;
+  method?: string;
+  params?: unknown;
+}
+
+interface SseClient {
+  controller: ReadableStreamDefaultController<Uint8Array>;
+  keepalive: ReturnType<typeof setInterval>;
+}
+
+export class RelayMcpProxy {
+  private readonly relayMcpEndpoint: string;
+  private readonly getToken: () => string | undefined;
+  private readonly authSecret: string;
+  private readonly enqueueBuffered: (call: BufferedToolCall) => void;
+  private readonly bufferableTools: Set<string>;
+  private readonly fetchImpl: FetchLike;
+  private readonly encoder = new TextEncoder();
+
+  private context: ProxyContext;
+  private server?: ReturnType<typeof Bun.serve>;
+  private readonly sseClients = new Set<SseClient>();
+  // Last successful relay tools/list — narrowed and served when the relay is briefly down so a
+  // read still works (reads serve from last-known where safe).
+  private lastRelayTools: Array<Record<string, unknown>> = [];
+  private lastNarrowedNames = "";
+
+  constructor(options: RelayMcpProxyOptions) {
+    this.relayMcpEndpoint = options.relayMcpEndpoint;
+    this.getToken = options.getToken;
+    this.authSecret = options.authSecret;
+    this.enqueueBuffered = options.enqueueBuffered;
+    this.bufferableTools = options.bufferableTools ?? DEFAULT_BUFFERABLE_TOOLS;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.context = options.initialContext ?? { isolatedWorktree: false };
+  }
+
+  start(): { url: string; port: number } {
+    const self = this;
+    this.server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      // SSE streams are long-lived; disable Bun's idle timeout and keep them alive with pings.
+      idleTimeout: 0,
+      fetch(req) {
+        return self.handle(req);
+      },
+    });
+    const port = this.server.port;
+    if (port === undefined) throw new Error("relay MCP proxy did not bind a port");
+    return { url: `http://127.0.0.1:${port}${PROXY_PATH}`, port };
+  }
+
+  stop(): void {
+    for (const client of this.sseClients) {
+      clearInterval(client.keepalive);
+      try { client.controller.close(); } catch { /* already closed */ }
+    }
+    this.sseClients.clear();
+    this.server?.stop(true);
+    this.server = undefined;
+  }
+
+  // The runner calls this on a workspace mode/state transition (active→ready→merged→terminal,
+  // or shared↔worktree). If it changes which tools the agent can see, emit list_changed so the
+  // agent's menu updates mid-session instead of staying frozen until reconnect.
+  setContext(context: ProxyContext): void {
+    this.context = context;
+    this.maybeEmitListChanged();
+  }
+
+  // The runner calls this after re-minting its runtime token (scope may have changed — e.g. a
+  // profile change grants/revokes command:spawn). Re-fetch the relay's now-differently-scoped
+  // tool list with the live token and emit list_changed if the visible set changed. This is the
+  // "token scope transition" path; setContext covers the workspace mode/state path. Best-effort —
+  // a failed refresh keeps the last-known list (the next tools/list refreshes it anyway).
+  async refreshTools(): Promise<void> {
+    const relay = await this.forward({ method: "tools/list", id: 0 }).catch(() => null);
+    const tools = relay && isRecord(relay.body?.result) && Array.isArray((relay.body!.result as Record<string, unknown>).tools)
+      ? ((relay.body!.result as Record<string, unknown>).tools as Array<Record<string, unknown>>)
+      : null;
+    if (!tools) return;
+    this.lastRelayTools = tools;
+    this.maybeEmitListChanged();
+  }
+
+  private async handle(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    if (url.pathname !== PROXY_PATH) return new Response("not found", { status: 404 });
+    if (!this.authorized(req)) {
+      return Response.json(jsonRpcError(null, -32001, "proxy auth required"), { status: 401 });
+    }
+    // GET → open the server→client SSE notification channel (streamable-HTTP transport).
+    if (req.method === "GET") return this.openSse();
+    if (req.method === "DELETE") return new Response(null, { status: 204 });
+    if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+    return this.handleRpc(req);
+  }
+
+  private authorized(req: Request): boolean {
+    const header = req.headers.get("authorization") ?? "";
+    const bearer = header.startsWith("Bearer ") ? header.slice(7) : "";
+    return bearer === this.authSecret;
+  }
+
+  private async handleRpc(req: Request): Promise<Response> {
+    let message: JsonRpcMessage;
+    try {
+      const body = await req.json();
+      if (!body || typeof body !== "object" || Array.isArray(body)) {
+        return Response.json(jsonRpcError(null, -32600, "JSON-RPC body must be an object"));
+      }
+      message = body as JsonRpcMessage;
+    } catch {
+      return Response.json(jsonRpcError(null, -32700, "invalid JSON-RPC body"));
+    }
+    const id = message.id ?? null;
+    const method = message.method;
+
+    if (method === "initialize") return this.handleInitialize(id, message);
+    if (method === "tools/list") return this.handleToolsList(id, message);
+    if (method === "tools/call") return this.handleToolsCall(id, message);
+    // Everything else (notifications/initialized, ping, …) forwards verbatim.
+    return this.forwardRaw(message);
+  }
+
+  private async handleInitialize(id: string | number | null, message: JsonRpcMessage): Promise<Response> {
+    const relay = await this.forward({ ...message, method: "initialize", id }).catch((error) => {
+      logger.warn("mcp-proxy", `initialize forward failed: ${errMessage(error)}`);
+      return null;
+    });
+    // Degrade gracefully if the relay is momentarily down at connect: still hand the agent a
+    // usable initialize result advertising the proxy's capabilities.
+    const result: Record<string, unknown> = isRecord(relay?.body?.result) ? { ...(relay!.body!.result as Record<string, unknown>) } : {
+      protocolVersion: "2024-11-05",
+      serverInfo: { name: "agent-relay", title: "Agent Relay (via runner)", version: "proxy" },
+    };
+    const caps = isRecord(result.capabilities) ? { ...result.capabilities } : {};
+    // The capability the relay's static endpoint doesn't advertise: live tool sets.
+    caps.tools = { ...(isRecord(caps.tools) ? caps.tools : {}), listChanged: true };
+    result.capabilities = caps;
+    return Response.json(jsonRpcResult(id, result));
+  }
+
+  private async handleToolsList(id: string | number | null, message: JsonRpcMessage): Promise<Response> {
+    const relay = await this.forward({ ...message, method: "tools/list", id }).catch(() => null);
+    const tools = relay && isRecord(relay.body?.result) && Array.isArray((relay.body!.result as Record<string, unknown>).tools)
+      ? ((relay.body!.result as Record<string, unknown>).tools as Array<Record<string, unknown>>)
+      : null;
+    if (tools) this.lastRelayTools = tools; // refresh the last-known base list
+    // If the relay is down and we have no cache yet, surface an empty list rather than erroring —
+    // the agent can still operate (writes buffer; tools/list refreshes on the next call).
+    const base = tools ?? this.lastRelayTools;
+    const narrowed = this.narrow(base);
+    this.lastNarrowedNames = toolNames(narrowed);
+    return Response.json(jsonRpcResult(id, { tools: narrowed }));
+  }
+
+  // Strict subset of the relay's already-scope-filtered list. Only removes — never adds. The one
+  // narrowing rule today: workspace tools apply only to an agent that owns a live worktree.
+  private narrow(tools: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
+    return tools.filter((tool) => {
+      const name = typeof tool.name === "string" ? tool.name : "";
+      if (WORKTREE_ONLY_TOOLS.has(name) && !this.context.isolatedWorktree) return false;
+      return true;
+    });
+  }
+
+  private async handleToolsCall(id: string | number | null, message: JsonRpcMessage): Promise<Response> {
+    const params = isRecord(message.params) ? message.params : {};
+    const toolName = typeof params.name === "string" ? params.name : "";
+    const args = isRecord(params.arguments) ? params.arguments : {};
+
+    const relay = await this.forward(message).catch((error) => {
+      // A thrown fetch = transport failure (relay unreachable / DNS / connection refused).
+      return { ok: false, status: 0, body: null, transportError: errMessage(error) } as ForwardResult;
+    });
+
+    const relayDown = !relay.ok && (relay.status === 0 || GATEWAY_STATUSES.has(relay.status));
+    if (relayDown && this.bufferableTools.has(toolName)) {
+      // Durably queue the write and tell the agent it's safely accepted. It replays on reconnect.
+      const idempotencyKey = typeof args.idempotencyKey === "string" && args.idempotencyKey
+        ? args.idempotencyKey
+        : `mcp-${toolName}-${crypto.randomUUID()}`;
+      this.enqueueBuffered({ tool: toolName, arguments: { ...args, idempotencyKey }, idempotencyKey });
+      logger.info("mcp-proxy", `relay unreachable — buffered ${toolName} (idempotencyKey=${idempotencyKey})`);
+      return Response.json(jsonRpcResult(id, toolResult({
+        queued: true,
+        tool: toolName,
+        idempotencyKey,
+        note: "Relay was unreachable; your call was queued durably and will be delivered automatically when the relay comes back. It is not lost.",
+      })));
+    }
+
+    if (relay.body) return Response.json(relay.body);
+    // Relay down and not bufferable: a real error the agent must see (and can retry).
+    return Response.json(jsonRpcError(id, -32002, `relay unreachable: ${relay.transportError ?? `status ${relay.status}`}`));
+  }
+
+  // Verbatim forward for methods with no proxy-specific handling. Returns the relay's response
+  // body+status unchanged (or a JSON-RPC error if the relay is down).
+  private async forwardRaw(message: JsonRpcMessage): Promise<Response> {
+    const relay = await this.forward(message).catch((error) => {
+      return { ok: false, status: 0, body: null, transportError: errMessage(error) } as ForwardResult;
+    });
+    if (relay.body) return Response.json(relay.body, { status: relay.status || 200 });
+    // Notifications (no id) tolerate a down relay — ack locally; requests get an error.
+    if (message.id === undefined || message.id === null) return new Response(null, { status: 202 });
+    return Response.json(jsonRpcError(message.id, -32002, `relay unreachable: ${relay.transportError ?? `status ${relay.status}`}`));
+  }
+
+  // POST the JSON-RPC message to the relay with the runner's LIVE token. The agent's incoming
+  // bearer is the proxy secret; we substitute the real relay credential here so the agent never
+  // holds it and token rotation is invisible. The body is re-serialized from the already-parsed
+  // message (the request stream was consumed during dispatch and can't be re-read).
+  private async forward(message: JsonRpcMessage): Promise<ForwardResult> {
+    const token = this.getToken();
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    if (token) headers.authorization = `Bearer ${token}`;
+    const payload: Record<string, unknown> = { jsonrpc: "2.0", method: message.method };
+    if (message.id !== undefined) payload.id = message.id;
+    if (message.params !== undefined) payload.params = message.params;
+    const response = await this.fetchImpl(this.relayMcpEndpoint, { method: "POST", headers, body: JSON.stringify(payload) });
+    const text = await response.text();
+    let parsed: Record<string, unknown> | null = null;
+    if (text) { try { parsed = JSON.parse(text); } catch { parsed = null; } }
+    return { ok: response.ok, status: response.status, body: parsed };
+  }
+
+  private openSse(): Response {
+    const self = this;
+    let client: SseClient;
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(self.encoder.encode(": connected\n\n"));
+        const keepalive = setInterval(() => {
+          try { controller.enqueue(self.encoder.encode(": keepalive\n\n")); } catch { /* closed */ }
+        }, SSE_KEEPALIVE_MS);
+        keepalive.unref?.();
+        client = { controller, keepalive };
+        self.sseClients.add(client);
+      },
+      cancel() {
+        if (client) {
+          clearInterval(client.keepalive);
+          self.sseClients.delete(client);
+        }
+      },
+    });
+    return new Response(stream, {
+      headers: { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" },
+    });
+  }
+
+  private maybeEmitListChanged(): void {
+    const narrowed = this.narrow(this.lastRelayTools);
+    const names = toolNames(narrowed);
+    if (names === this.lastNarrowedNames) return; // no visible change → no notification
+    this.lastNarrowedNames = names;
+    const frame = this.encoder.encode(`event: message\ndata: ${JSON.stringify({ jsonrpc: "2.0", method: "notifications/tools/list_changed" })}\n\n`);
+    for (const client of this.sseClients) {
+      try { client.controller.enqueue(frame); } catch { /* dropped client; cancel() cleans up */ }
+    }
+    logger.debug("mcp-proxy", `tools/list_changed emitted to ${this.sseClients.size} client(s)`);
+  }
+
+  // Test/observability hooks.
+  sseClientCount(): number { return this.sseClients.size; }
+  narrowedToolNames(): string[] { return this.narrow(this.lastRelayTools).map((t) => String(t.name)); }
+}
+
+interface ForwardResult {
+  ok: boolean;
+  status: number;
+  body: Record<string, unknown> | null;
+  transportError?: string;
+}
+
+function toolNames(tools: Array<Record<string, unknown>>): string {
+  return tools.map((t) => String(t.name)).sort().join(",");
+}
+
+function jsonRpcResult(id: string | number | null, result: unknown): Record<string, unknown> {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function jsonRpcError(id: string | number | null, code: number, message: string): Record<string, unknown> {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+function toolResult(result: unknown): Record<string, unknown> {
+  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], structuredContent: result };
+}

package/src/relay-mcp.ts

@@ -26,14 +26,17 @@ export function relayMcpEndpoint(relayUrl: string): string {
 // Claude: additive `--mcp-config` JSON (NOT --strict-mcp-config, which would clobber
 // the user's own servers). HTTP transport, token via env-var expansion so it never
 // hits argv. Returns the full ["--mcp-config", "<json>"] arg pair.
-export function relayMcpClaudeConfigArg(relayUrl: string): string[] {
+//
+// `endpoint` overrides the target URL: the runner passes its local MCP proxy URL (Stage 2,
+// #215) so the agent connects to the Runner, not the relay. Omitted → the direct relay endpoint.
+export function relayMcpClaudeConfigArg(relayUrl: string, endpoint?: string): string[] {
   return [
     "--mcp-config",
     JSON.stringify({
       mcpServers: {
         [RELAY_MCP_SERVER_NAME]: {
           type: "http",
-          url: relayMcpEndpoint(relayUrl),
+          url: endpoint ?? relayMcpEndpoint(relayUrl),
           headers: { Authorization: `Bearer \${${RELAY_MCP_TOKEN_ENV}}` },
         },
       },
@@ -43,11 +46,12 @@ export function relayMcpClaudeConfigArg(relayUrl: string): string[] {
 
 // Codex: `-c mcp_servers.<name>.*` overrides. `bearer_token_env_var` tells Codex to
 // read the token from the env var itself → transport resolves to streamable_http.
-export function relayMcpCodexConfigArgs(relayUrl: string): string[] {
+// `endpoint` overrides the target URL (runner-local proxy, Stage 2 #215) — see above.
+export function relayMcpCodexConfigArgs(relayUrl: string, endpoint?: string): string[] {
   const key = `mcp_servers.${RELAY_MCP_SERVER_NAME}`;
   return [
     "-c",
-    `${key}.url=${tomlString(relayMcpEndpoint(relayUrl))}`,
+    `${key}.url=${tomlString(endpoint ?? relayMcpEndpoint(relayUrl))}`,
     "-c",
     `${key}.bearer_token_env_var=${tomlString(RELAY_MCP_TOKEN_ENV)}`,
   ];

package/src/runner.ts

@@ -14,7 +14,8 @@ import { Outbox, type OutboxRecord } from "./outbox";
 import { extractLastAssistantTurn, extractFinalAssistantMessage, extractHookAssistantMessage, extractLatestTurnSteps, transcriptLooksComplete, analyzeSession } from "./adapters/claude-transcript";
 import { agentProfileProjectionReport } from "./profile-projection";
 import { profileUsesHostProviderGlobals } from "./profile-home";
-import { RELAY_MCP_TOKEN_ENV } from "./relay-mcp";
+import { RELAY_MCP_TOKEN_ENV, relayMcpEndpoint } from "./relay-mcp";
+import { RelayMcpProxy } from "./relay-mcp-proxy";
 import { runtimeMetadata } from "./version";
 import { logger, parseLogLevel } from "./logger";
 import { ensureSessionScratch, reapSessionScratch, sweepStaleSessions, type SessionScratchLayout } from "./session-scratch";
@@ -131,6 +132,15 @@ export class AgentRunner {
   private currentTokenProfileId?: string;
   private currentTokenExpiresAt?: number;
   private control?: ControlServer;
+  // Stage 2 (#215): the local MCP endpoint the agent connects to, fronting the relay so the
+  // Runner owns reconnect/backoff + a durable buffer. Disabled via AGENT_RELAY_MCP_PROXY=0
+  // (then the agent connects to the relay directly, Stage-1 behaviour). The proxy secret is the
+  // bearer the agent presents to the localhost proxy — it decouples the agent from the rotating
+  // relay token (the proxy injects the live token relay-side).
+  private proxy?: RelayMcpProxy;
+  private mcpProxyEndpoint?: string;
+  private readonly mcpProxyEnabled: boolean;
+  private readonly mcpProxySecret: string;
   private process?: ManagedProcess;
   private stopped = false;
   private exitCommandInProgress = false;
@@ -200,6 +210,8 @@ export class AgentRunner {
     this.currentTokenJti = options.tokenJti;
     this.currentTokenProfileId = options.tokenProfileId;
     this.currentTokenExpiresAt = options.tokenExpiresAt;
+    this.mcpProxyEnabled = !["0", "false", "off"].includes((process.env.AGENT_RELAY_MCP_PROXY ?? "").trim().toLowerCase());
+    this.mcpProxySecret = crypto.randomUUID();
     const runtime = runtimeMetadata(options.provider);
     this.http = new RelayHttpClient({ baseUrl: options.relayUrl, token: this.currentToken });
     this.obligationCache = new ReplyObligationCache({ fetch: () => this.http.listReplyObligations(this.agentId) });
@@ -284,6 +296,7 @@ export class AgentRunner {
       onSessionEnd: (input) => this.handleSessionEnd(input),
       onHookFatal: (report) => this.reportHookFatal(report),
     });
+    this.startMcpProxy();
     this.writeRunnerInfoFile();
     this.options.adapter.onStatusChange((status) => {
       if (this.restartInProgress || this.restartPending) return;
@@ -350,10 +363,45 @@ export class AgentRunner {
     this.stopReasoningTail();
     this.obligationCache.stop();
     this.outbox.close();
+    this.proxy?.stop();
     this.control?.stop();
     await this.bus.close();
   }
 
+  // Start the local MCP proxy the agent connects to (Stage 2, #215). Forwards tool calls to the
+  // relay with the runner's LIVE token, buffers bufferable writes durably during a relay outage,
+  // and narrows the tool list to this agent's workspace context. Best-effort: if it can't bind,
+  // we fall back to a direct relay MCP connection (the agent env still works, no resilience).
+  private startMcpProxy(): void {
+    if (!this.mcpProxyEnabled) return;
+    try {
+      this.proxy = new RelayMcpProxy({
+        relayMcpEndpoint: relayMcpEndpoint(this.options.relayUrl),
+        getToken: () => this.currentToken,
+        authSecret: this.mcpProxySecret,
+        enqueueBuffered: (call) => {
+          this.outbox.enqueue({
+            kind: "mcp-tool-call",
+            payload: { tool: call.tool, arguments: call.arguments },
+            idempotencyKey: call.idempotencyKey,
+          });
+        },
+        initialContext: { isolatedWorktree: this.ownsIsolatedWorktree() },
+      });
+      this.mcpProxyEndpoint = this.proxy.start().url;
+      logger.info("mcp-proxy", `runner MCP proxy listening at ${this.mcpProxyEndpoint} (worktree=${this.ownsIsolatedWorktree()})`);
+    } catch (error) {
+      this.proxy = undefined;
+      this.mcpProxyEndpoint = undefined;
+      logger.warn("mcp-proxy", `failed to start MCP proxy; agent will connect to the relay directly: ${errMessage(error)}`);
+    }
+  }
+
+  private ownsIsolatedWorktree(): boolean {
+    const mode = this.options.workspace?.requestedMode ?? this.options.workspace?.mode ?? process.env.AGENT_RELAY_WORKSPACE_MODE;
+    return mode === "isolated";
+  }
+
   private async spawnProvider(): Promise<ManagedProcess> {
     this.providerSessionId = crypto.randomUUID();
     this.lastTranscriptPath = undefined;
@@ -369,11 +417,18 @@ export class AgentRunner {
       AGENT_RELAY_URL: this.options.relayUrl,
       AGENT_RELAY_APPROVAL: this.options.approvalMode,
       ...(this.currentToken ? { AGENT_RELAY_TOKEN: this.currentToken } : {}),
-      // Dedicated, un-clobberable credential for the injected relay MCP endpoint. A rig's
+      // Dedicated, un-clobberable credential for the injected MCP endpoint. A rig's
       // settings.json `env.AGENT_RELAY_TOKEN` would override the scoped token above at
       // MCP-parse time → server-actor auth, no identity (#233). The MCP config references
       // ${AGENT_RELAY_SESSION_TOKEN}, which rigs never set. See runner/src/relay-mcp.ts.
-      ...(this.currentToken ? { [RELAY_MCP_TOKEN_ENV]: this.currentToken } : {}),
+      //
+      // Stage 2 (#215): when the proxy is active the agent connects to the LOCAL proxy, so this
+      // holds the per-session PROXY SECRET (not the relay token). The proxy injects the live
+      // relay token itself — the agent never holds it, and token rotation is invisible. With the
+      // proxy disabled this stays the scoped relay token (Stage-1 direct connection).
+      ...(this.proxy
+        ? { [RELAY_MCP_TOKEN_ENV]: this.mcpProxySecret }
+        : (this.currentToken ? { [RELAY_MCP_TOKEN_ENV]: this.currentToken } : {})),
       ...(this.currentTokenJti ? { AGENT_RELAY_TOKEN_JTI: this.currentTokenJti } : {}),
       ...(this.currentTokenProfileId ? { AGENT_RELAY_TOKEN_PROFILE: this.currentTokenProfileId } : {}),
       ...(this.currentTokenExpiresAt ? { AGENT_RELAY_TOKEN_EXPIRES_AT: String(this.currentTokenExpiresAt) } : {}),
@@ -400,6 +455,9 @@ export class AgentRunner {
       providerConfig: this.options.providerConfig,
       env,
       controlPort: this.control!.port,
+      // Stage 2 (#215): the MCP endpoint the agent's client should target — the runner-local
+      // proxy when active, undefined when disabled (adapters fall back to the direct relay URL).
+      ...(this.mcpProxyEndpoint ? { relayMcpEndpoint: this.mcpProxyEndpoint } : {}),
       monitor: {
         deliver: (messages) => this.control!.deliverToMonitor(messages),
       },
@@ -1057,6 +1115,10 @@ export class AgentRunner {
         });
         return;
       }
+      if (record.kind === "mcp-tool-call") {
+        await this.deliverBufferedMcpCall(record);
+        return;
+      }
       logger.warn("outbox", `dropping event with unknown kind: ${record.kind}`);
     } catch (error) {
       // 409 = the server intentionally rejected it (e.g. Insights/feature toggled off). That
@@ -1067,6 +1129,40 @@ export class AgentRunner {
     }
   }
 
+  // Replay a buffered MCP tool call (Stage 2, #215) that the proxy queued while the relay was
+  // unreachable. POST it to the relay MCP endpoint with the LIVE token — same path the live call
+  // would have taken. Throw to retry (transient), return to ack (delivered or permanently
+  // rejected). The proxy stamped an idempotencyKey into the arguments so a retry that already
+  // landed server-side is deduped, not double-sent.
+  private async deliverBufferedMcpCall(record: OutboxRecord): Promise<void> {
+    const payload = record.payload as { tool: string; arguments: Record<string, unknown> };
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    if (this.currentToken) headers.authorization = `Bearer ${this.currentToken}`;
+    const response = await fetch(relayMcpEndpoint(this.options.relayUrl), {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: payload.tool, arguments: payload.arguments } }),
+    });
+    if (response.status === 401 || response.status === 403) {
+      this.recoverRuntimeTokenAfterAuthFailure("mcp-outbox");
+      throw new Error(`relay rejected buffered ${payload.tool} with ${response.status}`);
+    }
+    if (response.status >= 500) throw new Error(`relay ${response.status} on buffered ${payload.tool}`);
+    if (!response.ok) {
+      // A 4xx (e.g. target gone, validation) is a permanent rejection — retrying won't help.
+      // Ack so it doesn't block the queue, but log loudly: a queued write did not land.
+      const body = await response.text().catch(() => "");
+      logger.warn("mcp-outbox", `buffered ${payload.tool} permanently rejected (${response.status}); dropping: ${body.slice(0, 200)}`);
+      return;
+    }
+    // HTTP 200 but the JSON-RPC body may still carry a tool-level error. Those reflect the same
+    // permanent-rejection semantics (bad target, validation) — ack and log, don't loop.
+    const json = await response.json().catch(() => null) as { error?: { message?: string } } | null;
+    if (json?.error) {
+      logger.warn("mcp-outbox", `buffered ${payload.tool} returned a tool error; dropping: ${json.error.message ?? "(no detail)"}`);
+    }
+  }
+
   // A hook reported an unhandled failure (#198 seam). Already logged FATAL by the control
   // server; here we additionally surface it durably to the server as a generic insight so
   // it shows up in observability rather than only in the per-agent log (#196).
@@ -1607,6 +1703,10 @@ export class AgentRunner {
     this.options.tokenExpiresAt = this.currentTokenExpiresAt;
     this.http.setToken(token);
     this.bus.setToken(token);
+    // The proxy reads the token live via getToken(), so forwarding already uses the new one.
+    // A re-mint can change scope (e.g. a profile change), so refresh the relay tool list and
+    // emit tools/list_changed if the visible set changed (#215 — token-scope transition).
+    void this.proxy?.refreshTools().catch(() => {});
     this.httpLivenessAuthFailed = false;
     this.reactiveTokenRecoveryAt = undefined;
     // An earlier auth failure may have stopped the liveness loop; restart it so the