feat(plugins): add hermes-approval-guard dual-agent supervision plugin

[kkangg1]

What

hermes-approval-guard — a two-stage semantic approval plugin via pre_tool_call hook covering ALL tools, not just terminal.

Architecture:

Tool call → pre_tool_call hook
  ├─ SAFE_TOOLS (21 read/query tools) → ALLOW (0ms)
  ├─ extract_context — reuses system detect_dangerous/hardline_command
  ├─ Terminal fast-path: no DANGEROUS signal → ALLOW (0ms)
  │   • HARDLINE-only signals (rm -rf /) → skip LLM, let system handle it
  ├─ Stage 1: LLM fast-classify → ALLOW / ESCALATE (~500ms)
  │   • Uses call_llm(task="approval") with context-aware prompt
  │   • NEVER outputs DENY — DENY reserved for Stage 2 / system HARDLINE
  │   • LLM config: provider/model optional; unset → defaults to main Agent LLM
  │   • On terminal ALLOW: calls approve_session() to pre-mark patterns
  │     → system's check_all_command_guards skips redundant LLM
  └─ Stage 2: hermes chat -q --profile approval deep review (3-8s, optional)
      • Stateless: no persistent session; all context injected in prompt
      • Context from SessionDB: conversation + full tool call chain
      • Hindsight-backed: session-level + cross-session pattern memory
      • Toolsets restricted to file,memory,session_search (no terminal)
      • Timeout kills entire process group (Popen + start_new_session + killpg)
      • Outputs: ALLOW / DENY / MODIFY with structured JSON feedback

System HARDLINE (rm -rf /, mkfs, dd, shutdown, etc.) always active — cannot be bypassed.

Terminal Handling (detailed)

terminal command
  ├─ extract_context()
  │   ├─ detect_hardline_command() → HARDLINE signal (descriptive only)
  │   └─ detect_dangerous_command() → DANGEROUS signal + pattern_key
  ├─ fast-path check
  │   has_real_risk = any("WARNING" in s AND "HARDLINE" not in s)
  │   ├─ False (git status, ls, echo) → 0ms pass
  │   ├─ False BUT HARDLINE-only (rm -rf /) → pass, system blocks
  │   └─ True (rm -rf node_modules, chmod 777 /etc, curl | bash) → Stage 1
  ├─ Stage 1 LLM (ALLOW? ESCALATE?)
  │   ├─ ALLOW → approve_session(pattern_keys) → pre-mark → system skips DANGEROUS
  │   └─ ESCALATE → Stage 2 ACP
  └─ Stage 2 ACP → ALLOW / DENY / MODIFY

Command	Plugin path	System	Outcome
git status	fast-path (0ms)	—	Execute
pip install pkg	fast-path → Stage1 ALLOW → pre-mark	—	Execute
rm -rf node_modules	Stage1 → ALLOW → pre-mark	skipped	Execute
rm -rf /	fast-path (HARDLINE-only)	BLOCKED	Denied
curl url | bash	Stage1 → ESCALATE → Stage2	—	ACP decides

Design Principles

Principle	Explanation
No hardcoded DENY in Stage 1	Risk signals are LLM context only — never hard-block
LLM: ALLOW / ESCALATE only	Stage 1 mirrors system's _smart_approve; DENY reserved for Stage 2 / HARDLINE
Stateless ACP	No --resume; all context from SessionDB + Hindsight; concurrent-safe
Fail-open	Broken guard is never more restrictive than no guard
Terminal fast-path	No DANGEROUS regex match → 0ms skip; HARDLINE-only also skips
approve_session pre-marking	Stage 1 ALLOW → pre-mark patterns → system skips redundant DANGEROUS LLM
Explicit config only	Memory backend config fully explicit in plugin_guard.memory; no cross-plugin cascade

Why

Aspect	Built-in approvals.mode	This plugin
Coverage	terminal only	ALL 25+ tools (write_file, patch, delegate_task, execute_code, etc.)
Decision	Regex + zero-context LLM (16 tokens)	Semantic LLM + ACP agent with full session context
Memory	Session-level (_session_approved)	Hindsight cross-session pattern bank
Context	Command string only	Conversation + tool chain + historical patterns
Denial feedback	"BLOCKED: xxx"	Structured: reason + alternatives + approval_id

Changes

11 files, 1,918 insertions:

File	Purpose
plugin.yaml	Manifest (standalone, pre_tool_call hook)
__init__.py	PluginContext.register_hook entry point
guard.py	Dispatcher, SessionDB context query, terminal fast-path, SAFE_TOOLS bypass
stage1_rules.py	Risk signal extraction, reuses system detect_dangerous/hardline_command — never blocks
stage1_llm.py	LLM classify: ALLOW/ESCALATE only, _smart_approve-style prompt
stage2_acp.py	Stateless ACP: 5-section prompt, SessionDB + Hindsight injection, process-group timeout cleanup
hindsight_store.py	Hindsight/Honcho/none memory backends, pattern key generation, session/pattern queries
feedback.py	Structured denial: reason + alternative suggestions + approval_id + override paths
test_integration.py	7 scenarios, 41 test cases
README.md	Architecture, terminal handling, design principles, failure modes, config reference
recommended-config.yaml	Annotated config template with all options

Test Plan

cd plugins/hermes-approval-guard
python3 test_integration.py

7 scenarios, 41 test cases. Covers: SAFE_TOOLS bypass (9 of 21 tools sampled), context extraction (no hard DENY — signals only), write_file path/signal tests, delegate_task danger keywords, terminal HARDLINE vs DANGEROUS separation, structured feedback messages, pattern key generation (write_file/terminal/delegate_task), and Stage 1 LLM prompt structure (ALLOW/ESCALATE only, false-positive examples).

Config

plugin_guard:
  enabled: true
  # provider: your_provider_name     # optional, defaults to main Agent LLM
  # model: your_model_name           # optional, defaults to main Agent LLM
  fail_open: true

  stage2:
    enabled: false                 # ACP deep review (test first)
    profile: approval              # hermes --profile name

  memory:
    backend: hindsight             # hindsight | honcho | none
    bank: approval
    hindsight_url: "http://localhost:8888"

approvals:
  mode: off   # plugin handles all tools; HARDLINE remains active

Configuration Reference

Key	Type	Default	Description
plugin_guard.enabled	bool	false	Master switch
plugin_guard.provider	str	—	LLM provider (optional, defaults to main LLM)
plugin_guard.model	str	—	Model name (optional, defaults to main LLM)
plugin_guard.fail_open	bool	true	LLM failure → allow (safe default)
plugin_guard.stage1.timeout	int	5	Seconds for LLM classification
plugin_guard.stage2.enabled	bool	false	Enable ACP deep review
plugin_guard.stage2.profile	str	"approval"	Hermes profile for review agent
plugin_guard.stage2.timeout	int	15	Seconds for deep review
plugin_guard.memory.backend	str	"hindsight"	hindsight, honcho, or none
plugin_guard.memory.bank	str	"approval"	Hindsight bank or Honcho user_id
plugin_guard.memory.hindsight_url	str	"http://localhost:8888"	Hindsight server address
plugin_guard.memory.honcho_url	str	"http://localhost:1819"	Honcho server address

Also set approvals.mode: off when plugin is enabled — system DANGEROUS check is redundant; system HARDLINE remains active regardless.

Failure Modes

Failure	Behavior
plugin_guard.enabled: false	Handler returns None immediately (~0.1ms)
Config missing/corrupt	Plugin self-disables; all tools pass
Stage 1 LLM unavailable	fail_open:true → ALLOW; fail_open:false → ESCALATE
Stage 2 ACP crash/timeout	fail_open:true → ALLOW; fail_open:false → DENY
Hindsight backend down	Silent skip; tool execution unaffected
Module import failure	Caught by Hermes plugin loader; not registered

Compatibility

• Hermes ≥ 0.14.0
• Uses pre_tool_call plugin hook (hermes_cli/plugins.py)
• Imports tools.approval for detect_dangerous/hardline_command
• Imports hermes_state.SessionDB for conversation context
• Optional: Hindsight HTTP API for approval memory

Checklist

• Plugin manifest (plugin.yaml) present
• README.md with architecture, design principles, failure modes, config reference
• Integration tests (41 pass, exit code 0)
• All code, comments, docstrings, and LLM prompts in English
• No privacy-sensitive data in docs or config templates
• Explicit config only — no cross-plugin config cascade
• System HARDLINE protection confirmed independent and non-interfering
• Verified with GitNexus: 19 functions, zero external callers (hook-only), 2 cross-module deps (call_llm, load_config)

[teknium1]

Thanks for the substantial plugin implementation. Current main has moved since this branch: hermes_cli/plugins.py:2114-2128 now supports a plugin pre_tool_call approve directive that sends any tool to the native human approval gate, so the terminal-only premise needs re-scoping rather than duplication.

Problems

• guard.py:56-71 latches _config_disable; after one disabled/error read, the documented 30-second reload cannot run.
• guard.py:40 bypasses browser_console, although tools/browser_tool.py:3270-3290 evaluates supplied JavaScript expressions.
• guard.py:273-278 returns None even with fail_open: false; that permits the call after a Stage 2 exception.
• stage2_acp.py:251-259 launches with the writable file toolset (toolsets.py:191-194) and HERMES_YOLO_MODE=1, so the reviewer is not read-only.
• test_integration.py:77-80 counts a failed guard import as passing tests.

Suggested changes

• Make config reload retryable, make Stage 2 failure honor fail_open, and remove non-read-only tools from the bypass/reviewer paths.
• Add standard tests/plugins/ coverage for discovery and actual hook dispatch, including failure branches and Windows behavior.

Automated hermes-sweeper review.

[teknium1]

browser_console is not read-only when expression is supplied: current tools/browser_tool.py evaluates JavaScript in the page context. Keeping it in this unconditional bypass contradicts the all-tools guard claim; distinguish console-read mode from expression evaluation or remove it from _SAFE_TOOLS.

[teknium1]

Once a missing, invalid, or disabled config sets _config_disable, this early return prevents every later TTL refresh. The comment below promises live config refresh, but enabling the plugin after startup will never take effect.

[teknium1]

This returns None for a Stage 2 exception regardless of fail_open, which permits the tool call. Return a block directive when fail_open is false and add a regression test.

[teknium1]

Current file includes write_file and patch (toolsets.py:191-194), so this reviewer is not read-only. Combined with HERMES_YOLO_MODE=1 below, a prompt-injected reviewer can mutate files without the approval layer; use a genuinely read-only boundary.

[teknium1]

A failure to import guard.py is converted into passing checks. This masks plugin-loader and runtime import regressions; fail the test instead and add pytest coverage that exercises real plugin discovery and pre-tool dispatch.

[kkangg1]

Rebased onto current main and addressed the sweeper review point by point:

• Config reload latching (guard.py:56-71): _config_disable was already removed — a failed/disabled read returns {"enabled": False} without caching, so the next TTL cycle retries. Added TestConfigReload regression coverage (enable-after-startup takes effect).
• browser_console bypass (guard.py:40): removed from _SAFE_TOOLS. Added dispatch-level tests: browser_console(expression=...) now goes through Stage 1 LLM review while browser_snapshot stays bypassed.
• Stage 2 exception honoring fail_open (guard.py:273-278): the exception branch returns a block directive when fail_open: false. Replaced the source-regex check with a behavior-level regression test.
• Reviewer not read-only (stage2_acp.py): toolset restricted to -t session_search only; additionally the subprocess env now explicitly strips HERMES_YOLO_MODE so a parent gateway --yolo cannot leak past the approval layer. Also fixed the Windows timeout-kill path (os.killpg/SIGKILL fallback).
• Import failure counted as pass (test_integration.py): import failures now fail the test. Added tests/plugins/test_approval_guard_plugin.py (18 cases): real plugin discovery, end-to-end pre_tool_call hook dispatch, failure branches, Windows behavior. Writing the dispatch test surfaced a real bug — the core dispatcher passes extra kwargs (turn_id etc.) that made the handler a silent no-op; fixed by accepting **_extra.
• Native approve directive overlap: README now has a "Relationship with the Native approve Directive" section positioning this plugin as unattended dual-agent semantic review, complementary to the interactive human gate.

Tests: plugin suite 43 passed, new pytest suite 18 passed, ruff clean.