Metadata-Version: 2.4
Name: blackwall-hermes-plugin
Version: 0.1.0
Summary: BLACK_WALL pre-action guardrail for Hermes Agent (NousResearch). Hooks pre_tool_call to call forecast() before any tool runs; blocks STOP verdicts; auto-reports outcomes via observe(). Decision receipts are Ed25519-signed and verifiable offline.
Project-URL: Homepage, https://blackwalltier.com
Project-URL: Source, https://github.com/bluetieroperations-create/blackwall-hermes-plugin
Project-URL: Issues, https://github.com/bluetieroperations-create/blackwall-hermes-plugin/issues
Project-URL: Free API key, https://blackwalltier.com/dashboard/keys
Project-URL: BLACK_WALL SDK, https://pypi.org/project/blackwall-sdk/
Author-email: BlueTier Operations <bluetier.operations@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai-agents,ai-safety,blackwall,decision-receipt,guardrails,hermes,hermes-agent,nousresearch,preflight
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: blackwall-sdk>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# blackwall-hermes-plugin

Pre-action risk check for [Hermes Agent](https://github.com/NousResearch/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](https://blackwalltier.com). Get a free key at [blackwalltier.com/dashboard/keys](https://blackwalltier.com/dashboard/keys).

## Install

```bash
pip install blackwall-hermes-plugin
```

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

```yaml
plugins:
  enabled:
    - blackwall
```

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

```bash
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](https://blackwalltier.com/.well-known/blackwall-signing-keys.json)

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`](https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/plugins.py) 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`](https://pypi.org/project/blackwall-hermes-plugin/) · [`blackwall-sdk`](https://pypi.org/project/blackwall-sdk/)
- Source: https://github.com/bluetieroperations-create/blackwall-hermes-plugin
- Sibling plugins: [`blackwall-eliza-guardrail`](https://www.npmjs.com/package/blackwall-eliza-guardrail) (npm) · [`blackwall-openclaw-plugin`](https://www.npmjs.com/package/blackwall-openclaw-plugin) (npm)

## License

MIT
