feat: support hermes agent integration

refs #144

4 files changed, 54 insertions, 2 deletions

diff --git a/docs/next/CHANGELOG.md b/docs/next/CHANGELOG.md
index c7df66e4..7e60e568 100644
--- a/docs/next/CHANGELOG.md
+++ b/docs/next/CHANGELOG.md
@@ -3,8 +3,13 @@
 ## Unreleased
 
 ### Added
+- Added Hermes Agent foreground-process detection with basic idle, working, and blocked heuristics.
+- Added a Hermes Agent plugin integration for direct state reporting.
 - Added `ui.sidebar_min_width` and `ui.sidebar_max_width` to configure the sidebar's expanded resize bounds. Defaults remain 18 and 36 columns; existing configs are unchanged.
 
+### Breaking Changes
+- The client/server protocol is now version 7. Stop and restart any running v0.5.10 server before attaching with this release.
+
 ## [0.5.10] - 2026-05-17
 
 ### Added
diff --git a/docs/next/CONFIGURATION.md b/docs/next/CONFIGURATION.md
index 4425cc59..9d85b53b 100644
--- a/docs/next/CONFIGURATION.md
+++ b/docs/next/CONFIGURATION.md
@@ -409,6 +409,7 @@ available agent keys:
 - `droid`
 - `amp`
 - `grok`
+- `hermes`
 
 ## experimental
 
diff --git a/docs/next/INTEGRATIONS.md b/docs/next/INTEGRATIONS.md
index 23b41ab8..fc47bbc0 100644
--- a/docs/next/INTEGRATIONS.md
+++ b/docs/next/INTEGRATIONS.md
@@ -12,6 +12,7 @@ if you want to inspect the exact files herdr installs, they are versioned in thi
 - [claude code hook](./src/integration/assets/claude/herdr-agent-state.sh)
 - [codex hook](./src/integration/assets/codex/herdr-agent-state.sh)
 - [opencode plugin](./src/integration/assets/opencode/herdr-agent-state.js)
+- [hermes plugin](./src/integration/assets/hermes/__init__.py)
 
 ## how herdr uses integrations
 
@@ -30,6 +31,7 @@ herdr integration install pi
 herdr integration install claude
 herdr integration install codex
 herdr integration install opencode
+herdr integration install hermes
 ```
 
 ## uninstall commands
@@ -39,6 +41,7 @@ herdr integration uninstall pi
 herdr integration uninstall claude
 herdr integration uninstall codex
 herdr integration uninstall opencode
+herdr integration uninstall hermes
 ```
 
 ## pi
@@ -210,6 +213,47 @@ this removes:
 ~/.config/opencode/plugins/herdr-agent-state.js
 ```
 
+## hermes agent
+
+install:
+
+```bash
+herdr integration install hermes
+```
+
+this:
+
+- writes the bundled plugin to `~/.hermes/plugins/herdr-agent-state/`
+- updates `~/.hermes/config.yaml` so `plugins.enabled` contains `herdr-agent-state`
+
+bundled source: [`src/integration/assets/hermes/__init__.py`](./src/integration/assets/hermes/__init__.py)
+
+current plugin mapping:
+
+- `on_session_start` → `idle`
+- `pre_llm_call` → `working`
+- `pre_api_request` → `working`
+- `pre_tool_call` → `working`
+- `post_tool_call` → `working`
+- `pre_approval_request` → `blocked`
+- `post_approval_response` → `working`
+- `post_llm_call` → `idle`
+- `on_session_end` → `idle`
+- `on_session_finalize` → `release`
+
+notes:
+
+- hermes plugins are opt-in, so install also enables the plugin in `config.yaml`.
+- herdr still keeps native process detection and screen heuristics for hermes. the plugin improves state accuracy when the hook surface fires.
+
+uninstall:
+
+```bash
+herdr integration uninstall hermes
+```
+
+this removes `~/.hermes/plugins/herdr-agent-state/` and removes the matching `plugins.enabled` entry from `~/.hermes/config.yaml`.
+
 ## grok cli
 
 herdr does not currently install a grok hook or plugin.
diff --git a/docs/next/README.md b/docs/next/README.md
index 808cc1a8..5ace7525 100644
--- a/docs/next/README.md
+++ b/docs/next/README.md
@@ -178,6 +178,7 @@ automatic detection works out of the box. process name matching plus terminal ou
 | [amp](https://ampcode.com) | ✓ | ✓ | ✓ |
 | [opencode](https://github.com/anomalyco/opencode) | ✓ | ✓ | ✓ |
 | [grok cli](https://x.ai/grok) | ✓ | ✓ | ✓ |
+| [hermes agent](https://github.com/NousResearch/hermes-agent) | ✓ | ✓ | ✓ |
 
 detected but not fully tested: gemini cli, cursor agent, cline, kimi, github copilot cli.
 
@@ -185,13 +186,14 @@ for agents outside the built-in list, herdr still works as a terminal multiplexe
 
 ### direct integrations
 
-the built-in pi, claude code, codex, and opencode integrations forward semantic state to herdr over the socket api. install with:
+the built-in pi, claude code, codex, opencode, and hermes integrations forward semantic state to herdr over the socket api. install with:
 
 ```bash
 herdr integration install pi
 herdr integration install claude
 herdr integration install codex
 herdr integration install opencode
+herdr integration install hermes
 ```
 
 see [`INTEGRATIONS.md`](./INTEGRATIONS.md) for setup details.
@@ -263,7 +265,7 @@ full logging and environment variable details: [`CONFIGURATION.md`](./CONFIGURAT
 ## docs
 
 - [`CONFIGURATION.md`](./CONFIGURATION.md) — keybindings, themes, notifications, environment variables
-- [`INTEGRATIONS.md`](./INTEGRATIONS.md) — pi, claude code, codex, opencode integrations
+- [`INTEGRATIONS.md`](./INTEGRATIONS.md) — pi, claude code, codex, opencode, hermes integrations
 - [`SKILL.md`](./SKILL.md) — reusable agent skill
 - [`SOCKET_API.md`](./SOCKET_API.md) — socket protocol and cli reference