blackwall-hermes-plugin

Pre-action risk check for Hermes Agent (NousResearch). Hooks pre_tool_call so STOP-rated tool calls abort before they run — without modifying any of your other plugins or skills.

Powered by BLACK_WALL. Get a free key at blackwalltier.com/dashboard/keys.

Install

pip install blackwall-hermes-plugin

Enable the plugin in ~/.hermes/config.yaml:

plugins:
  enabled:
    - blackwall

Set the API key (env var, ~/.hermes/.env, or your launcher):

export BLACKWALL_API_KEY=bw_live_xxx
export BLACKWALL_MODE=observe        # or 'enforce' once you trust the verdicts

That's it. Every tool the agent tries to call goes through pre_tool_call → BLACK_WALL forecast → verdict.

What you get back per tool call

• GO / CAUTION / STOP
• risk score 0–100
• reversibility class (REVERSIBLE / RECOVERABLE / IRREVERSIBLE)
• named red flags — e.g. SQL_NO_WHERE, PROMPT_INJECTION_LIKELY, IRREVERSIBLE_NO_BACKUP
• an Ed25519-signed Decision Receipt — verifiable offline against the published public key

Latency: ~4–8 seconds.

Modes

Mode	Behavior
observe (default)	Score every tool call and log to BLACK_WALL; never block. Zero behavior change — safe to drop in.
enforce	STOP → hard block (returns {"action": "block", "message": "..."}). CAUTION → configurable (default: block; set BLACKWALL_CAUTION=allow to let it proceed). GO → proceeds.

Start in observe for a few days to see what the verdicts look like on your real traffic. Switch to enforce once you trust the scoring.

Why pre_tool_call?

Hermes Agent exposes pre_tool_call as a documented plugin hook with {"action": "block", "message": "..."} return semantics — exactly the shape a pre-action guardrail needs. The plugin does not monkey-patch the dispatcher; it uses the documented extension surface.

That means:

• Multiple plugins can register pre_tool_call — first valid block directive wins
• Companion post_tool_call hook fires after the tool runs (or after a block), so we can auto-report outcomes via BLACK_WALL observe()
• The plugin is opt-in — users must add blackwall to plugins.enabled in their config

Config reference (env vars)

Variable	Default	Notes
BLACKWALL_API_KEY	(required)	Free key at https://blackwalltier.com/dashboard/keys
BLACKWALL_MODE	observe	observe (log only) or enforce (block STOP)
BLACKWALL_CAUTION	block	block (treat CAUTION as STOP) or allow (let CAUTION proceed)
BLACKWALL_BASE_URL	https://blackwalltier.com	Override for self-hosted/staging

How it works

                     ┌──────────────────────────────┐
                     │ Hermes agent decides to       │
                     │ call tool X with args Y       │
                     └─────────────┬────────────────┘
                                   │
                          pre_tool_call
                                   │
                                   ▼
            ┌──────────────────────────────────────────┐
            │ blackwall plugin: forecast(X, Y)          │
            │ ↓                                          │
            │ STOP    → return {"action": "block",       │
            │            "message": "..."}               │
            │ CAUTION → block or allow (env-configured)  │
            │ GO      → return None                      │
            └──────────────────┬───────────────────────┘
                               │ (if not blocked)
                               ▼
                       tool actually runs
                               │
                          post_tool_call
                               │
                               ▼
            ┌──────────────────────────────────────────┐
            │ blackwall plugin: observe(forecast_id,    │
            │   outcome_class)                          │
            │ matched / diverged / aborted              │
            └──────────────────────────────────────────┘

Fail-open: if BLACK_WALL is unreachable, the hook logs a warning and lets the tool proceed. A BLACK_WALL outage will never take down your agent.

Architecture

┌──────────────────────────────────────────────┐
│ BLACK_WALL HTTP API (stable, versioned)      │
└──────────────────────────────────────────────┘
              ▲
┌──────────────────────────────────────────────┐
│ blackwall-sdk  (shared Python client)        │
│   forecast()  observe()                       │
└──────────────────────────────────────────────┘
              ▲
┌──────────────────────────────────────────────┐
│ blackwall-hermes-plugin (this package)       │
│   pre_tool_call  post_tool_call               │
└──────────────────────────────────────────────┘
              ▲
            Hermes Agent

When Hermes ships breaking changes to its plugin contract, only this package needs to update. The HTTP API, the blackwall-sdk client, and every other BLACK_WALL integration remain insulated.

Links

• Site & docs: https://blackwalltier.com
• Free API key: https://blackwalltier.com/dashboard/keys
• Failure-mode taxonomy (28 named red-flag codes): https://blackwalltier.com/failure-modes
• PyPI: blackwall-hermes-plugin · blackwall-sdk
• Source: https://github.com/bluetieroperations-create/blackwall-hermes-plugin
• Sibling plugins: blackwall-eliza-guardrail (npm) · blackwall-openclaw-plugin (npm)

License

MIT