Build Acp Agent

Build ACP Agent

Build the agent process that an ACP client launches. Do not build an editor plug-in or MCP server when the requirement is an editor-native coding agent. Read references/acp-implementation-map.md before selecting an SDK or registry distribution.

Implementation Workflow

1. Define concrete client targets and the user-visible behavior they require.
2. Use ACP v1, the current latest protocol, and an official SDK when its language and runtime fit. Treat v2 and non-completed RFDs as experimental; do not ship them as the portable baseline. Use raw JSON-RPC only when an SDK cannot support a required platform or feature.
3. Implement initialization first:
   • negotiate protocolVersion
   • advertise only implemented agent capabilities
   • inspect client filesystem and terminal capabilities before using them
   • advertise real authentication methods and implementation information
4. Implement the required session baseline: new, prompt, cancel, and update.
5. Add optional load, resume, fork, list, close, modes, configuration, plans, slash commands, rich prompt content, or MCP transports only with matching capability declarations and tests. Keep draft session/delete, logout, elicitation, additional directories, and remote transports behind explicit experimental flags and interoperability tests.
6. Render tool calls, diffs, terminals, plans, and streamed content in the ACP structures the target clients understand.
7. Route dangerous operations through permission requests and fail closed when approval transport fails or times out.
8. Keep stdout exclusively for ACP JSON-RPC. Send logs and diagnostics to stderr without leaking credentials or prompt content unnecessarily.
9. Bind every session to its client-provided cwd and any negotiated additional roots. Isolate cancellation, model choice, history, and mutable state by session.
10. Test initialization, authentication, session lifecycle, streaming, cancellation, permissions, invalid messages, process shutdown, and each advertised optional capability against representative clients.

Distribution And Registry

• Treat source support, package publication, and canonical registry publication as three separate states.
• Publish a fetchable binary, npx, or uvx distribution that launches the ACP process directly and reproducibly.
• Keep the source-owned registry manifest version aligned with the published package.
• Submit the manifest to the canonical ACP Registry and do not claim registry availability until the live registry feed contains the entry.
• Require a genuine agent-owned or terminal authentication method when the registry requires authentication discovery.
• Do not replace an official package with an unrelated third-party launcher merely to satisfy a distribution shape.

Host Validation

• Validate Zed with a custom agent during development, inspect ACP logs, then verify the canonical registry path after publication.
• Validate Xcode through its documented Add an Agent flow and Xcode-owned permissions. Keep Xcode tool behavior separate from protocol conformance.
• Validate Hermes-specific changes against hermes acp --check plus the Hermes adapter's session, approval, cwd, and provider behavior.

Guards

• Do not infer wire compatibility from SDK, schema-artifact, or package version numbers; use negotiated ACP protocol version and capabilities.
• Do not present a v2 or draft RFD implementation as ACP v1 conformance.
• Do not advertise methods that are stubs or only work in one client.
• Do not make ACP a general agent-to-agent orchestration layer.
• Do not embed provider secrets in registry manifests, launch arguments, logs, or test fixtures.

Report

Report client targets, SDK and protocol version, required and optional methods, capability matrix, auth flow, session/state model, permission behavior, distribution source, registry state, tests, and client-specific limitations.