From d922d95f62dc2a4645bf03c6bb3f3b12829b41b4 Mon Sep 17 00:00:00 2001
From: tumberger <jens.ernstberger@gmail.com>
Date: Sun, 17 May 2026 20:49:39 +0200
Subject: [PATCH] docs: document Hermes local start support

---
 README.md     |  7 +++++--
 docs/guard.md | 32 +++++++++++++++++++++++++++++++-
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index c1c51bf..d438af3 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,7 @@ brew install kontext-security/tap/kontext
 kontext start
 ```
 
-This starts the currently supported adapter, Claude Code, with a local Kontext runtime. No hosted login is required.
+By default, this starts Claude Code with a local Kontext runtime. Use `kontext start --agent hermes` to start Hermes Agent instead. No hosted login is required for local sessions.
 
 By default, Kontext runs in observe mode: the agent keeps running, while Kontext records `would allow`, `would ask`, and `would deny` decisions in the local dashboard. The dashboard is served on loopback, with the URL printed at startup.
 
@@ -100,6 +100,7 @@ For enterprise identity, audit retention, organization controls, deployment plan
 | Agent | Status | Start command | Support level |
 | --- | --- | --- | --- |
 | Claude Code | Active | `kontext start` or `kontext start --agent claude` | Local observe/enforce, dashboard diagnostics, managed sessions. |
+| Hermes Agent | Beta | `kontext start --agent hermes` | Local observe/enforce for `pre_tool_call` and `post_tool_call`; no managed sessions or native approval prompts yet. |
 | Goose | Planned | Coming soon | Adapter not shipped yet. |
 | Codex | Planned | Coming soon | Adapter not shipped yet. |
 | Cursor | Planned | Coming soon | Adapter not shipped yet. |
@@ -111,9 +112,11 @@ Additional agents can be added through adapters that send compatible tool events
 ```text
 kontext start
   |
-  |-- Agent hook adapter (Claude Code today)
+  |-- Agent hook adapter
   |     |-- PreToolUse  -> kontext hook --agent claude --mode observe --socket /tmp/kontext/.../kontext.sock
   |     |-- PostToolUse -> kontext hook --agent claude --mode observe --socket /tmp/kontext/.../kontext.sock
+  |     |-- pre_tool_call  -> kontext hook --agent hermes --mode observe --socket /tmp/kontext/.../kontext.sock
+  |     |-- post_tool_call -> kontext hook --agent hermes --mode observe --socket /tmp/kontext/.../kontext.sock
   |
   |-- Local runtime: Unix socket service + RuntimeCore
   |-- Local dashboard: 127.0.0.1:4765
diff --git a/docs/guard.md b/docs/guard.md
index d744b8b..25e92d1 100644
--- a/docs/guard.md
+++ b/docs/guard.md
@@ -19,6 +19,36 @@ go run ./cmd/kontext guard start
 claude
 ```
 
+## Hermes Agent
+
+Hermes Agent can run under the local Kontext runtime with the Hermes shell-hook adapter:
+
+```bash
+kontext start --agent hermes
+KONTEXT_MODE=enforce kontext start --agent hermes
+```
+
+Kontext creates a per-session temporary Hermes home shaped as a Hermes profile, snapshots the required Hermes config/auth/env state, and writes temporary shell-hook config that points back to the local Kontext socket. It does not edit `~/.hermes/config.yaml`, does not preserve user-defined shell hooks in the generated session config, and pre-approves only the generated Kontext hook commands in the temporary allowlist.
+
+In observe mode, the generated Hermes hook config uses this shape. Enforce sessions use `--mode enforce` in the same command positions:
+
+```yaml
+hooks:
+  pre_tool_call:
+    - command: "kontext hook --agent hermes --mode observe --socket /tmp/kontext/.../kontext.sock"
+      timeout: 20
+  post_tool_call:
+    - command: "kontext hook --agent hermes --mode observe --socket /tmp/kontext/.../kontext.sock"
+      timeout: 20
+```
+
+Current limitations:
+
+- `ask` approval is not supported through Hermes shell hooks. In observe mode, Kontext records would-ask decisions. In enforce mode, Kontext maps `ask` and `deny` decisions to a Hermes block response.
+- `updatedInput` is not supported through Hermes shell hooks.
+- Managed sessions remain Claude-only.
+- If Hermes cannot run the hook subprocess, the hook times out, or the hook emits malformed output, Hermes logs the problem and continues the agent loop.
+
 ## Runtime boundary
 
 Guard mode is local-first by default:
@@ -34,7 +64,7 @@ Guard mode is local-first by default:
 Hosted mode remains separate:
 
 ```bash
-kontext start --agent claude
+kontext start --managed
 ```
 
 Hosted mode owns login, provider connection, short-lived scoped credentials, hosted traces, and team governance.