/build-acp-agent

name: build-acp-agent
description: Design, implement, test, and package an ACP agent/server. Use for protocol negotiation, sessions, streaming updates, tool rendering, permissions, authentication, SDK choice, and registry submission.
metadata:
  hermes:
    category: agent-portability
    tags: [acp, json-rpc, sdk, registry, agent-development]

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.