RFD: Multi-Client Session Attach

[joaommartins]

Summary

This RFD proposes a session/attach method that allows multiple ACP clients to connect to and interact with the same live agent session simultaneously — enabling a unified notification and approval UI across concurrent coding agent workflows.

Key features

• Controller/observer roles — Controllers can send prompts and respond to permissions; observers receive the live stream read-only
• First-writer-wins permission routing — request_permission is broadcast to all controllers; the first response wins and all clients are notified via permission_resolved
• historyPolicy parameter — Clients control history replay on attach: full (default), pending_only, or none
• Proxy-based architecture — A proxy/multiplexer sits between agents and clients, meaning existing agents require zero changes
• WebSocket + SSE transport — Multi-client attach requires a network-capable transport; the proxy handles this
• Graceful detach and lifecycle — session/detach lets clients leave voluntarily; the session continues as long as one controller remains

Problem

ACP currently assumes a 1:1 relationship between a client and an agent session. For developers running multiple concurrent agent sessions (Claude Code, Codex, Gemini, etc.), this creates a significant context-switching tax:

• Permission requests block in whichever terminal started the session — there is no way to respond from a unified dashboard
• There is no way to passively observe an active session from a second client
• session/load supports sequential handoff only — not concurrent access to a live session

Example

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "session/attach",
  "params": {
    "sessionId": "sess_abc123def456",
    "role": "controller",
    "historyPolicy": "pending_only",
    "clientInfo": {
      "name": "notification-dashboard",
      "version": "1.0.0"
    }
  }
}

Capability negotiation

{
  "agentCapabilities": {
    "sessionCapabilities": {
      "attach": {
        "roles": ["controller", "observer"]
      }
    }
  }
}

Relationship to existing RFDs

This proposal builds directly on the Agent Extensions via ACP Proxies RFD — the proxy architecture established there is the recommended implementation pattern for multi-client attach. It also depends on Session List for session discovery and complements Resuming of existing sessions.

[ElleNajt]

I have a use case for this and found this issue because I was considering building the same thing:

I've been building (WIP, I can't guarantee it's safe at the moment) github.com/ElleNajt/agent-to-go , where the idea is that I forward claude code terminal sessions via tmux/ttyd/tailscale to my phone.

There are similar projects, but I'm trying to build something minimal that just provides easily auditable glue interacting with and and managing coding agent CLIs on the phone -- and multiplexing an ACP session between a mobile friendly ACP front end and whatever ACP front end is on the dev machine is ideal for this.

[ElleNajt]

Claude and I vibed out a multiplexer here: https://github.com/ElleNajt/acp-multiplex -- the gist is that there's a single primary process that talks to the acp backend like claude-code-acp through a proxy, and that proxy spawns a socket that secondary front ends can connect to.

Here's an example where agent-shell is the primary and toad is the secondary:

Curious for takes on this approach -- I haven't reviewed this in depth yet (Claude's walk through is here: https://github.com/ElleNajt/acp-multiplex/blob/master/docs/walkthrough.org#L509 )... I just really want this to exist, and would love to collaborate with someone on manifesting a stable and safe way to mirror acp sessions on my phone. :)