Pluggable agent runtime per session via ACP: run Codex CLI, Claude Code, or other agents inside app sessions

### Feature summary

Let a session's *agent runtime* be selectable — Copilot CLI (default), Codex CLI, Claude Code, Gemini CLI, OpenCode — by adopting ACP (Agent Client Protocol) as the boundary between the app shell and the agent process, while the app keeps owning worktrees, My Work, canvases, diffs, and the PR lifecycle.

### What problem are you trying to solve?

The most valuable part of this app is not the agent — it is everything *around* the agent:

- one isolated git worktree per session, so parallel work never collides
- My Work as a single queue of sessions, issues, and PRs
- canvases (plan, terminal, browser, editor) that make agent work inspectable
- plan mode and approval gates
- the commit → push → PR → review → agent merge path
- automations and the session store

All of that is runtime-agnostic in principle, but today it is hard-wired to one agent. So people who also use Codex CLI or Claude Code have to drop out of the app entirely to use them — losing the worktree isolation, the queue, and the PR flow, which is the whole reason to be in the app. The result is exactly the context-switching this app was built to remove.

This is different from the existing provider-level requests. #120 and #128 ask to swap the *model or credentials* behind Copilot's own agent loop. This asks to swap the *agent loop itself*, keeping its own tool set, prompts, config files, memory, and skills. #2167 raised the ACP idea in one line; this is a fleshed-out version of it.

### Proposed solution

**1. ACP as the runtime boundary**

Speak [ACP](https://agentclientprotocol.com) to the agent process instead of hard-coding one CLI's protocol. Zed already does this to host Claude Code, Codex, and Gemini side by side, so there is a proven precedent and a growing set of agents that already implement the agent side.

**2. Agent registry in settings**

An "Agents" list, each entry defining:

- display name and icon
- command + args, and how the working directory is passed
- environment variables and which secrets it may read
- auth mode (its own login vs app-managed credentials)
- declared capabilities (see below)

Ship presets for **Copilot CLI** (default, unchanged), **Codex CLI**, **Claude Code**, **Gemini CLI**, and **OpenCode**, plus a "custom command" entry so any ACP-speaking binary works. Presets should detect an already-installed binary and its existing auth rather than asking users to reconfigure.

**3. Runtime selector alongside the model selector**

- A per-project default runtime, overridable per session at creation.
- The chosen runtime is persisted on the session, so reopening or resuming a session uses the same runtime — no silent swaps mid-thread.
- The session list shows which runtime a session is running, so a mixed set of sessions stays legible.

**4. Capability negotiation, so the UI degrades instead of breaking**

The app should ask the runtime what it supports — canvases, plan mode, subagents/orchestration, MCP servers, custom agents, background tasks, structured diffs — and hide affordances a given runtime cannot serve rather than showing dead buttons. A runtime that only supports plain streaming chat + tool calls should still get a fully working session, just with fewer surfaces.

**5. Keep the app-owned layer runtime-agnostic**

Worktree creation and cleanup, branch and PR lifecycle, diff review and inline comments, My Work, automations, agent merge, and the session store should all be implemented against the runtime interface rather than against one agent. That is what makes this a boundary rather than an integration.

**6. Phased rollout, so it does not have to land all at once**

- **Phase 1** — run a non-Copilot agent in a terminal-backed session with worktree isolation and the full commit/push/PR flow intact. No canvases, no plan mode. Already useful on its own.
- **Phase 2** — ACP streaming into the normal session transcript, structured tool calls, and diff review.
- **Phase 3** — canvases, plan mode, and orchestration for runtimes that declare support.

### Workflow impact

Two groups benefit. People who already pay for and are fluent in another agent CLI get to keep the app as their control center instead of choosing between the shell and the agent. And teams standardizing on the app get a hedge: the surrounding workflow stops being coupled to a single agent's release cadence or capabilities.

For the app itself, a clean runtime boundary is also a testing and extensibility win — canvases, extensions, and automations become contracts rather than internal calls.

### Installation context

Desktop app, local sessions primarily. Cloud sessions would presumably stay Copilot-only at first, which is fine; the local case is where users already have these CLIs installed and authenticated.

### Additional context

Related: #2167 (ACP registry for existing local agents), #120 (ChatGPT subscription / Codex CLI as a provider), #128 (Antigravity CLI as a provider), #221 (connectors for Codex/Claude Desktop), #1137 (existing Claude and Codex subscriptions).

Worth being explicit about the risks so they can be designed for rather than discovered: sandboxing and permission prompts differ per agent, so the app's approval UX needs a common denominator; a foreign agent's own config (e.g. `.claude/settings.json` hooks, see #1717) can surprise users if picked up implicitly, so config sources should be visible and opt-in; and telemetry/session-store shape will differ per runtime, so the session store should record which runtime produced a turn.

Không có tệp, bài kiểm thử hoặc điểm vào nào được nêu tên. Trước tiên, hãy đọc đề xuất về ranh giới ACP và các issue liên quan, sau đó lập sơ đồ vòng đời hiện có của session, worktree và PR trước khi chọn một giai đoạn rollout. Hoàn tất nghĩa là có một lựa chọn lúc runtime duy trì workflow do ứng dụng sở hữu, với các capability không được hỗ trợ được suy giảm như mô tả.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.