[Feature] Approval system: customizable smart prompt context (quick win) + pluggable hook handler (long-term)

[Emidomenge]

Summary

The current approval system supports three fixed modes (manual, smart, off). This feature request is for a fourth extensibility point: a custom approval hook — a user-defined script or command that Hermes calls to make the approve/deny decision, similar to how Claude Code's PreToolUse hooks work.

How Claude Code does it

In Claude Code, you can configure a shell command as a PreToolUse hook in settings.json. Before any tool runs, Claude Code calls that command with tool details on stdin and reads a JSON decision from stdout:

{ "decision": "deny", "reason": "Curl over plain HTTP to an internal host is not allowed in this context." }

The hook can be anything — a Python script, a local LLM call, a webhook to an external service. This makes the approval system fully extensible without forking the agent.

Requested behavior for Hermes

Add a custom approval mode (or a hook field alongside smart) that lets users define a command to call:

approvals:
  mode: custom
  hook: "/opt/data/scripts/approval_hook.py"
  timeout: 30
  on_deny_notify_gateway: true    # post denial reason to the active platform channel
  on_approve_notify_gateway: false  # optionally post approval confirmation too (default: false)

When a dangerous command is detected, Hermes calls the hook with a JSON payload on stdin:

{
  "tool": "terminal",
  "command": "python3 -c \"import os; print(os.environ['HA_TOKEN'])\"",
  "reason": "script execution via -c flag",
  "session_id": "abc123",
  "platform": "discord",
  "user_id": "364815244633178123"
}

The hook returns a decision on stdout:

{ "decision": "approve" }
{ "decision": "approve", "reason": "Safe read-only env introspection, no exfiltration risk." }
{ "decision": "deny", "reason": "Printing the HA token to the terminal is not safe in this context." }
{ "decision": "escalate", "reason": "Uncertain — routing to human." }

• approve → execute; if on_approve_notify_gateway: true and a reason is present, post it to the active platform channel (useful for audit trails)
• deny → block; if on_deny_notify_gateway: true, post the reason to the active platform channel with optional human override prompt
• escalate → fall back to the existing manual gateway prompt

Why this matters / use case

Running a Home Assistant admin agent on Discord. The built-in smart mode works well for obvious cases, but:

1. The smart LLM's judgement is a closed box — no visibility, no tuning
2. Different agents have very different risk profiles. An HA agent legitimately runs curl to local IPs and python -c env introspections constantly. A finance bot should never touch network calls. A fixed global policy can't capture this.
3. With a pluggable hook, you can use a fast/cheap LLM with a custom system prompt tailored to the agent's context, make it context-aware, and have it post a clear approval or denial message to the Discord channel for full visibility into what the agent is doing and why

A simple hook script using any LLM API could be a 50-line Python file that gives far better context-aware decisions than a generic smart mode — and doubles as an audit log.

Prior art

• Claude Code PreToolUse hooks: shell command called with tool details on stdin, returns JSON decision
• Standard Unix philosophy: the agent provides the interface, the user provides the logic

[Emidomenge]

As a simpler first iteration / quick win before the full pluggable hook system: allow the smart mode prompt to be customized via config.

The current prompt in tools/approval.py (_smart_approve) is hardcoded and entirely generic. There is no way to inject agent-specific context, which causes false positives for agents that have legitimate unusual patterns — for example, a Home Assistant admin agent that routinely runs curl to local IPs or python -c env introspections as part of normal operation will get flagged constantly even though these are safe in context.

A minimal improvement would be a approvals.smart_prompt (or approvals.context) config key that appends agent-specific context to the assessment prompt:

approvals:
  mode: smart
  context: |
    This agent manages a Home Assistant instance. The following are always safe in this context:
    - curl requests to homeassistant.atoplix.com or local LAN addresses (192.168.x.x)
    - python -c commands that read environment variables
    - SSH commands to ha@192.168.xxxx

This would slot directly into _smart_approve() with minimal code change, and would make smart mode significantly more useful for specialized agents without requiring the full custom hook infrastructure.

The pluggable hook system from the original request remains the right long-term solution — but this prompt customization could ship much faster and already solve the most common pain point.

[Emidomenge]

Quick win implemented in PR #16483 — adds an optional approvals.context config key that injects agent-specific guidance into the smart-approval prompt. This addresses the most common pain point (false positives for specialized agents) with a minimal change, while keeping the full pluggable hook system as a future enhancement.

[teknium1]

Closing at maintainer direction. We are not adding customizable Smart Approval prompt context or a pluggable approval handler. The approval boundary will remain fixed rather than configurable through prompt guidance.