The Editor-Agent Protocol Everyone's Adopting Has a Version Field Bug Waiting to Happen

The Agent Client Protocol (ACP) is quietly becoming the LSP of AI coding agents — one JSON-RPC wire format so a code editor can talk to any agent, and an agent can talk to any editor, without a bespoke integration on either side. Zed originated it, it hit a stable v1.0, and it's now spoken by 25+ agents including Gemini CLI and JetBrains' tooling. If you're building an agent or an editor integration right now, you're probably hand-implementing at least the handshake yourself.

Here's the mistake I'd bet money on seeing in the wild: protocolVersion is a plain integer, not a version string. Every other AI-adjacent protocol I've looked at lately — MCP, Agent Plugins — uses a date-like string for its version field ("2026-07-28", that sort of thing). ACP doesn't. It's 1, a bare JSON number, and it's only bumped for breaking changes. Send "1" as text out of habit from writing three other integrations this month, and you get a rejection with no obvious clue why, because the JSON itself is perfectly valid — just the wrong type.

The other one that'll bite you: ACP's baseline is exactly four methods every agent must support — session/new, session/prompt, session/cancel, and session/update — and two of those four are notifications, not requests. session/cancel in particular is easy to send with an id attached out of muscle memory (every other action in the protocol is a request/response pair), and if you do, the agent that correctly treats it as fire-and-forget will never send back the response your client is sitting there waiting for.

I went and pulled the actual published stable schema — the real JSON Schema shipped in @agentclientprotocol/sdk, not a summary or a blog post — and built a validator against it: paste a JSON-RPC message, get back exactly which required field is missing or which type is wrong, checked against the handshake plus all four baseline methods, with the rest of the ~30 real ACP methods recognized by name even where field-level depth isn't worth building yet. It also tells you the direction — client→agent or agent→client — since half the "why isn't this working" bugs I'd guess are just a message sent the wrong way down the pipe.

Free, runs entirely in your browser, nothing you paste leaves your machine: bracketly.pages.dev/tools/acp-message-validator