Agent client protocol
Hermes exposes an Agent Client Protocol (ACP) server for editors and other compatible clients. The surface lets a client discover Hermes, open or restore a workspace session, submit agent work, and receive live work updates while Hermes keeps its normal models, tools, memory, and session state.
Protocol surface
ACP is a JSON-RPC interface over stdio. A client starts hermes acp, hermes-acp, or python -m acp_adapter; stdout carries only protocol messages and logs go to stderr. The client can use the same surface from an editor, a desktop host, or another collaboration bridge.
Discovery and authentication
The client begins with initialize. Hermes returns its protocol version, identity, supported session actions, prompt features, and authentication methods. A configured provider can authenticate through Hermes runtime credentials; a new installation can use the advertised terminal setup method to configure a provider before it starts work.
The discovery contract includes:
- session creation, loading, resuming, listing, and forking
- text and image prompt support
- model information and session mode information
- provider authentication or terminal setup
References: acp_adapter/server.py• L534-572 acp_adapter/auth.py• L8-51
Capability catalog
The client sees a Hermes tool surface suited to agent work in a workspace. It can include file and terminal work, web and browser work, memory, skills, task tracking, session search, vision, code execution, delegation, enabled plugins, and MCP tools. Configuration can narrow this surface for ACP without changing the core protocol.
Editor-provided MCP servers are session-scoped additions. Their tools become part of that session's working surface and are not shared as a global editor process state.
References: acp_adapter/session.py• L103-108 acp_adapter/session.py• L519-530 acp_adapter/server.py• L433-479
Session lifecycle
An ACP session is the stable conversation handle that connects a client workspace to Hermes work. The session carries the workspace path, model choice, conversation history, cancellation state, and the relationship to durable Hermes session state.
flowchart LR
A[Client initializes] --> B[Create or attach session]
B --> C[Bind workspace and tools]
C --> D[Submit prompt]
D --> E[Stream work updates]
E --> F[Persist conversation]
F --> G[Load, resume, or fork later]
Session creation and attachment
session/new creates a session for the client's current working directory. session/load and session/resume attach to an existing conversation and replay its history before the response completes. session/fork creates a separate conversation with copied history, while session/list lets clients find durable sessions for a workspace.
The workspace is part of the session contract. Hermes uses it when it runs file and terminal work, so the agent acts in the editor's project rather than in the server's launch directory.
References: acp_adapter/server.py• L576-710 acp_adapter/session.py• L176-243 acp_adapter/session.py• L253-267
Session persistence
Non-empty ACP conversations use the shared Hermes session store. This allows a client to reconnect after the ACP process stops and continue the conversation with its history and model context. Empty discovery sessions remain temporary until they have work to save.
The gateway owns the live session when ACP runs as a viewer. It ends an idle ACP session when its last viewer leaves, but a later load or resume can reopen the conversation. This keeps session lifetime separate from the lifetime of one editor process.
References: acp_adapter/session.py• L1-6 acp_adapter/session.py• L343-401 gateway/session_acp_lifecycle.py• L1-7 gateway/session_acp_lifecycle.py• L16-32
Agent work
The client submits a prompt to a session and receives a terminal response together with live session/update notifications. The protocol carries both the result of the turn and the steps that make the turn visible in an editor.
Prompt submission
session/prompt accepts text and supported content blocks. Text stays a normal Hermes prompt; images and file-like resources become context for the agent when the client supplies them. A prompt can run ordinary agent work or invoke a supported Hermes slash command.
The response reports whether the turn completed, was cancelled, or was refused. If a turn is already active, the surface can redirect supported live work or queue later text for the session's next turn.
References: acp_adapter/server.py• L712-758 acp_adapter/server.py• L824-889 acp_adapter/content.py• L231-282
Work updates
Hermes streams the parts of a turn that a client needs to render an agent workspace. The update stream can show assistant text, reasoning text, tool start and completion, file edit views, terminal activity, plans, titles, context use, and token use. Tool calls reach a terminal status even when a guard, denial, interruption, or error stops the call.
The client should treat updates as display state for the session, not as a second execution path. The gateway remains the source of the accepted work and its final outcome.
References: acp_adapter/events.py• L30-52 acp_adapter/events.py• L97-115 acp_adapter/events.py• L119-177 acp_adapter/gateway_server.py• L714-845
Approval and clarification
Some agent actions need a client decision. Hermes sends permission requests for protected terminal or edit actions and clarification requests when the agent needs an answer. The client may allow or deny an action, or provide the requested clarification; a timeout or bridge error fails closed for approval.
The client host controls how these requests appear. An unattended host can answer them itself, so a protocol-level approval option does not always mean that a human saw a prompt.
References: acp_adapter/permissions.py• L1-20 acp_adapter/server.py• L902-952 acp_adapter/gateway_server.py• L847-900
Protocol bridge
The ACP process is a protocol projection over Hermes execution. In gateway mode it connects to the profile gateway, creates or attaches to the gateway's canonical session, submits admitted prompts, and projects the gateway event stream back to the client.
This split keeps execution, admission, durable state, approvals, and work ownership in the gateway. It also lets more than one viewer observe a session without giving each viewer a separate agent run. The detailed gateway startup, session attachment, command mapping, and recovery rules are described in ACP gateway bridge.
Work admission and observation
The bridge submits each client turn to the gateway and waits for that admission's terminal result. It forwards streamed events while preserving the distinction between accepted work, cancelled work, failed work, and work whose result became unknown after a transport or gateway restart.
If the bridge loses the connection before it receives the result, it does not guess that the turn failed or submit it again. The client must resume the session and use the gateway's recovery path before continuing.
References: acp_adapter/gateway_server.py• L280-320 acp_adapter/gateway_server.py• L551-637 acp_adapter/gateway_server.py• L686-712
Client controls
ACP clients can expose session commands as editor actions. These controls use the gateway's existing session operations so a client command changes the same conversation state that other Hermes surfaces see.
Session commands
The advertised commands cover inspection, model choice, tool display, context management, reset, compression, steering, queuing, usage, status, and version information. Unknown slash commands remain ordinary agent prompts; a command that the ACP surface does not support is refused before it reaches the gateway.
The model picker uses provider-qualified choices. A client can therefore change the model for its session without changing Hermes' global default model.
References: acp_adapter/gateway_session_meta.py• L27-55 acp_adapter/gateway_commands.py• L19-41 acp_adapter/gateway_commands.py• L71-94 acp_adapter/model_catalog.py• L146-152
Change checklist
When these files or sections are changed, remember to consider these:
- Keep
initializecapability claims aligned with the session methods and update types that clients can actually use. - Keep the prompt admission and terminal-outcome contract aligned between
GatewayACPAgentand gateway event names. A mismatch can make a client wait forever or retry accepted work. - Keep session identity, workspace binding, and compression lineage aligned across ACP IDs, gateway session IDs, and the shared session store.
- Keep tool and MCP capability claims aligned with the tool surface attached during
session/new,session/load, andsession/resume. - Keep stdout free of logs or agent output. ACP clients read stdout as JSON-RPC transport.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| ACP dependencies or provider credentials are missing | The client cannot complete setup or start a useful session | Use hermes acp --check and the advertised terminal setup method |
| The ACP process writes non-protocol text to stdout | JSON-RPC framing breaks and the client disconnects | Route human-readable logs and agent output to stderr |
| The gateway connection ends before a prompt result arrives | The turn outcome is unknown; resubmitting can run the work twice | Resume the session and resolve the unknown admission before continuing |
| A client resumes with changed editor MCP settings | The session tool surface no longer matches the saved session policy | Reattach with the original server definition or start a new session |
| An approval request times out or the bridge fails | The protected action is denied | Treat approval as fail-closed and retry only after a new decision |
Key files
| File | Why to read it |
|---|---|
| acp_adapter/entry.py | ACP process entry points, setup checks, and stdio rules |
| acp_adapter/server.py | Main protocol contract for discovery, sessions, prompts, and updates |
| acp_adapter/gateway_server.py | Gateway-backed session projection and prompt observation |
| acp_adapter/session.py | Session identity, workspace binding, tool surface, and persistence boundary |
| acp_adapter/events.py | Mapping from agent activity to client-visible updates |
| acp_adapter/gateway_commands.py | Mapping from editor slash commands to gateway operations |
| gateway/session_acp_lifecycle.py | Gateway-owned ACP session end and reopen behavior |