Understand Hermes ACP Session, Permission, and Event Bridges

The ACP adapter lets compatible editors use Hermes without a separate agent runtime. It wraps synchronous AIAgent runs in an asynchronous JSON-RPC stdio service and translates sessions, tools, permissions, and events.

Operating checklist

• Validate the ACP start path.
• Complete Hermes provider setup first.
• Bind each session to the intended editor cwd.
• Keep stdout reserved for JSON-RPC.
• Preserve approval prompts.
• Test new, resume, fork, cancel, and list operations.
• Verify editor rendering of diffs and terminal activity.

How the workflow works

Each session stores its agent, cwd, model, history, and cancellation event. Worker-thread callbacks are forwarded to the async protocol loop. Dangerous terminal prompts become ACP permission requests; rejection, timeout, or bridge failure denies the action. Forks copy history but receive independent IDs and workspace bindings. Provider credentials come from the shared Hermes runtime resolver rather than an ACP-only store.

Common pitfalls

• Writing debug logs to stdout.
• Treating ACP as a separate credential store.
• Ignoring workspace binding.
• Losing IDs for parallel same-name tools.
• Failing open on approval timeout.
• Assuming every content block is text.

Verification steps

1. Start ACP without stdout noise.
2. Read and patch a file in a disposable repo.
3. Inspect editor-rendered diffs.
4. Test allow-once, denial, and timeout.
5. Fork and confirm history/cwd isolation.
6. Cancel a long prompt and verify the stop reason.

Use the official Hermes documentation for the current source of truth.