Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / agent-client-protocol

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 initialize capability claims aligned with the session methods and update types that clients can actually use.
  • Keep the prompt admission and terminal-outcome contract aligned between GatewayACPAgent and 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, and session/resume.
  • Keep stdout free of logs or agent output. ACP clients read stdout as JSON-RPC transport.

Important failure modes

TriggerConsequenceGuard
ACP dependencies or provider credentials are missingThe client cannot complete setup or start a useful sessionUse hermes acp --check and the advertised terminal setup method
The ACP process writes non-protocol text to stdoutJSON-RPC framing breaks and the client disconnectsRoute human-readable logs and agent output to stderr
The gateway connection ends before a prompt result arrivesThe turn outcome is unknown; resubmitting can run the work twiceResume the session and resolve the unknown admission before continuing
A client resumes with changed editor MCP settingsThe session tool surface no longer matches the saved session policyReattach with the original server definition or start a new session
An approval request times out or the bridge failsThe protected action is deniedTreat approval as fail-closed and retry only after a new decision

Key files

FileWhy to read it
acp_adapter/entry.pyACP process entry points, setup checks, and stdio rules
acp_adapter/server.pyMain protocol contract for discovery, sessions, prompts, and updates
acp_adapter/gateway_server.pyGateway-backed session projection and prompt observation
acp_adapter/session.pySession identity, workspace binding, tool surface, and persistence boundary
acp_adapter/events.pyMapping from agent activity to client-visible updates
acp_adapter/gateway_commands.pyMapping from editor slash commands to gateway operations
gateway/session_acp_lifecycle.pyGateway-owned ACP session end and reopen behavior