Supporting the Agent Client Protocol (ACP)

[joshvoigts]

Pi already has a headless RPC mode for embedding in other applications. That works but it's pi-specific. Every editor that wants to integrate needs to write a custom client that speaks pi's dialect.

The Agent Client Protocol (ACP) is a standard for agent to editor communication (LSP but for coding agents). It's backed by zed and uses json-rpc over stdio. It defines a session lifecycle and covers tool calls, permission requests, file/terminal access, and streaming updates. Many agents and editors already support it.

The pitch: if pi supported ACP, any ACP-compatible editor could use pi out of the box. Pi already has the hard parts built (session management, agent loop, tool execution, persistence). ACP support would mostly be a translation layer.

There's already a community-built pi-acp adapter, works with Zed today, and pi is listed on the ACP agents page. It bridges ACP json-rpc to pi's RPC mode, with session persistence, slash commands, skill support, structured diffs, and follow-along file locations. It has some limitations (no filesystem or terminal delegation, no MCP passthrough).

Discussion

Pi's extension system already gives power users a lot of what ACP provides on the editor side. But ACP lowers the barrier for editor developers who just want to plug in any compatible agent.

Pi's RPC mode already exists and is more pi-native.

UI-only extensions wouldn't make sense headlessly, but tool-providing and prompt-modifying extensions should work fine.

[qiine]

This would allow use of pi in nvim with codecompanion.nvim, that could be neat!

[JacobNWolf]

I agree that that this should be first party, rather than an extension. This is a core feature that comes out the box with most other agent CLIs. I don't think it'd bloat install size and it'd make Pi more compatible in IDEs that are increasing market share.

[JacobNWolf]

I've given this considerable thought over the past few days.

I'm a heavy Zed user with the Cursor Agent and though I love the Cursor Agent CLI, it's missing parts of the ACP spec that affect my workflow in my day job. I love how extendable Pi is and I'd love to spend my free time contributing back to it with this contribution, building on the great work done in the aforementioned extension and complete the rest of the build. So I've put together a proposal that I wanted to run by the community and the maintainers before starting this work.

Happy to implement this in stacked PRs behind the experimental flag if this direction is acceptable.

---

Proposal: native --mode acp (same shape as RPC)

Problem

Pi already has headless embedding via --mode rpc. That works, but every editor must speak Pi's private JSONL dialect.

ACP is becoming the shared editor ↔ agent stdio contract (Zed, JetBrains, others). The community adapter svkozak/pi-acp already lists Pi on the ACP agents page by spawning pi --mode rpc and translating. That proves demand, but the bridge has structural limits:

• no client FS / terminal delegation (breaks SSH/WSL/remote + unsaved buffers)
• no real session/request_permission path into the IDE
• MCP from session/new is accept-and-ignore
• dual session identity (session-map.json vs Pi session files)
• version skew forever between adapter and Pi RPC

Pi already owns the hard parts (session loop, tools, persistence, extensions). What's missing is a first-party transport, not another product surface.

Why this belongs in core (not an extension)

I know the CONTRIBUTING guide emphasizes minimalism. Extensions can register tools, hooks, commands, and providers, but they cannot own the process stdin/stdout framing or register a CLI run mode. RPC is already a core mode for that reason; ACP would be the same kind of thing: another I/O adapter over AgentSession / AgentSessionRuntime.

An external adapter can only approximate ACP by shelling into RPC. A native mode can call the session directly and override tool backends (ReadOperations / WriteOperations / BashOperations already exist for this).

This does not replace RPC. RPC stays the Pi-native embed API. ACP is the standard editor protocol.

Minimalism / bundle size

I want to be upfront about the dependency cost. The @agentclientprotocol/sdk@1.2.1 tarball is ~329 KB. zod is already in the tree, so no new peer deps. That's real weight, and I expect it to get reviewed like any lockfile change.

My thinking on mitigations:

1. exact pin + normal dep review / shrinkwrap flow
2. keep ACP code under packages/coding-agent/src/modes/acp/ (parallel to modes/rpc/)
3. experimental gate so unfinished ACP never becomes default CLI behavior
4. advertise only capabilities we actually implement in each PR

If the SDK cost is the blocker, I'm open to a thin hand-rolled JSON-RPC subset for just the methods we need. My gut says the official SDK is lower maintenance risk for protocol drift, but I could be wrong here.

Proposed shape

editor (Zed / JetBrains / ...)
  ↕ ACP JSON-RPC stdio
pi --mode acp
  ↕ in-process
AgentSession / AgentSessionRuntime  (same as RPC/interactive/print)

Not:

editor → pi-acp → pi --mode rpc → AgentSession

Initial product defaults I'd want agreement on:

• Ask/Code session config option for IDE tool permissions (session/request_permission in Ask; auto-allow in Code). Default Ask in ACP mode only. This does not add a global permission system to interactive Pi; the README's "no built-in sandbox" stance stays for the TUI/CLI.
• Prefer client FS/terminal when the client advertises those capabilities; fall back to local ops otherwise.
• Mid-turn prompts map to Pi steer, not a client-side queue.
• Honest capability flags (don't advertise MCP/FS/load until implemented).

Proposed PR outline

I know this is a lot, so I've tried to sequence the proposed PRs for reviewability:

1. Plumbing: dep + --mode acp stub initialize
2. Session loop: new / prompt / cancel + event mapping (local tools)
3. IDE config: model / thinking configOptions, commands, auth
4. Permissions: Ask/Code + request_permission
5. Persistence: load / list / history replay + steer
6. Client FS + additionalDirectories
7. Client terminal
8. MCP from session/new (most likely to need separate design discussion; can stay false longer)
9. Docs + ungate

Open questions for maintainers

1. Is "another mode next to RPC" an acceptable core addition, or do you want ACP to remain community-adapter-only?
2. Is @agentclientprotocol/sdk acceptable as a direct dep if pinned/reviewed, or prefer a minimal hand-rolled subset?
3. Should MCP-over-ACP be in-scope for native mode, or remain extension territory (pi-mcp-adapter) with mcpCapabilities false?
4. For ACP-only Ask mode permissions: any objection to IDE permission prompts that do not change interactive Pi's trust/security model?

I can start with PR 1 (gated stub) once there's a thumbs-up on direction.

[ofekron]

AI-GENERATED FOLLOW-UP, reviewed under the Better Agent maintainer’s authorization.

A native mode seems justified specifically because session identity, permissions, and delegated filesystem/terminal ownership cannot be represented reliably through a long-lived RPC translation shim.

I would make one invariant explicit in the first session-loop PR: the ACP sessionId maps to exactly one authoritative Pi session record, and that mapping is persisted by Pi—not by the editor and not by a sidecar file. session/load should reconstruct the same history and pending lifecycle state after either side reconnects.

Two related recommendations:

• advertise each capability only when the native path can honor it across new/load/cancel/reconnect, not merely on the happy path;
• treat Ask/Code as a client-requested policy bounded by Pi’s maximum authority. The client may request fewer prompts, but it must not silently grant authority Pi or the host did not provide.

For mid-turn input, ACP’s emerging queue/steer distinction also matters: mapping every injection to steer will be incorrect for clients or providers that only support next-turn queueing. Capability negotiation should expose the actual mode.

We encountered these exact translation boundaries while integrating persistent native Claude, Codex, and Gemini sessions in Better Agent. I maintain it; the project is source-available and free for non-commercial use, while commercial use requires separate permission: https://github.com/ofekron/better-agent

AI-assistance disclosure: drafted by Codex and reviewed in Better Agent.