Environment

• Hermes Agent: v0.14.0 (2026.5.16)
• • OS: Debian 13 (Trixie)

Description

The hooks documentation mentions ~/.hermes/shell-hooks-allowlist.json and explains that consent decisions are persisted there, but does not document the JSON structure of the file. Users who need to write it manually — for example on a service account with no TTY where hooks_auto_accept: true is too broad — must inspect the source code to discover the format.

More critically, the intuitive format (keyed by file path with a sha256) is silently wrong: hermes hooks list continues to show ✗ not allowlisted even when this format is present and the file is valid JSON.

Incorrect Format (silently does not work)

{
  "/home/hermes/.hermes/hooks/my-hook.py": {
    "sha256": "b8d40b7d887a6bd838db363983da3b077b345cbaac9dceb427de4cba28eec6f2"
  }
}

With this format, hermes hooks list shows ✗ not allowlisted despite the file existing and being valid JSON. No error or warning is emitted.

Correct Format (discovered from source)

Found by reading _is_allowlisted() and load_allowlist() in agent/shell_hooks.py:

{
  "approvals": [
    {
      "event": "post_llm_call",
      "command": "/home/hermes/.hermes/hooks/my-hook.py"
    }
  ]
}

With this format, hermes hooks list correctly shows ✓ allowed.

Suggested Documentation Addition

Add a "Manual allowlisting" subsection to the hooks documentation consent model section:

# Write the allowlist manually (for non-TTY / service account deployments)
python3 -c "
import json
from pathlib import Path
script    = '/absolute/path/to/hook.py'
allowlist = Path.home() / '.hermes/shell-hooks-allowlist.json'
try:
    data = json.loads(allowlist.read_text())
except FileNotFoundError:
    data = {'approvals': []}
data['approvals'].append({'event': 'post_llm_call', 'command': script})
allowlist.write_text(json.dumps(data, indent=2))
"

# Verify:
hermes hooks list   # should show ✓ allowed

Note: the allowlist keys on the exact command string, not the script's content hash, so editing the script on disk does not invalidate consent (as mentioned in the docs). This means adding a sha256 field has no effect — which is another reason the incorrect format should be explicitly called out.