All plugins

hermes-proof

Deterministically verify agent task outcomes and persist auditable evidence reports.

CodedAccornToolsv0.2.0Updated 7 days ago

HermesProof v0.2

HermesProof independently evaluates explicit, deterministic local-file requirements and writes auditable JSON evidence. It preserves the MVP proof_verify and proof_report tool names and calling conventions.

This is the hackathon release. It verifies declared conditions; it does not infer whether an entire task is complete, treat tool success as outcome proof, or enforce policy through passive hooks.

What v0.2 implements

  • Strict contracts for file_exists, file_contains, file_sha256, and local-file json_equals.
  • Exactly three outcomes: verified, failed, and unverified.
  • Evidence IDs, UTC timestamps, expected/observed values, check-level status, and verification root.
  • Atomic JSON persistence and retrieval by report ID or latest report.
  • Root confinement, absolute/traversal rejection, symlink/junction escape checks, a 1 MiB content limit, and fail-closed parsing.
  • No LLM judging, shell execution, credential handling, or network requests in v0.2 verification handlers.

Architecture

ModuleResponsibility
contracts.pyStrict request parsing and supported check definitions
engine.pyDeterministic, root-confined file evaluation
evidence.pyAtomic persistent report storage and retrieval
handlers.pyBackward-compatible tool handlers and aggregate status
schemas.pyHermes-facing JSON schemas
tools.pyStable public import surface for the MVP tool names

File verification has no implicit root and refuses to run until verification_root is configured in the plugin settings. This prevents a gateway launched from a home directory from exposing that directory. Standalone development may explicitly set HERMES_PROOF_ROOT; it never falls back to the process working directory.

plugins:
  entries:
    hermes-proof:
      settings:
        verification_root: C:\\path\\to\\the\\project

Evidence is stored per active Hermes profile under <HERMES_HOME>/hermes-proof/evidence using Hermes' official get_hermes_home() API. Targets inside the active Hermes profile are forbidden. HermesProof also refuses common credential locations and file types including .env*, auth.json, private-key formats, .ssh, .aws, and .config/gcloud, even when they are inside the configured verification root.

Contracts

{
  "label": "release artifact",
  "checks": [
    {"name": "marker", "type": "file_contains", "target": "demo.txt", "expected": "DEPLOYED"},
    {"name": "state", "type": "json_equals", "target": "state.json", "path": "$.release.ready", "expected": true}
  ]
}

json_equals.path supports $ and dot-separated object keys/list indexes such as $.release.items.0. Malformed contracts and inaccessible or unsafe targets are unverified; an observed mismatch is failed.

Install and Hermes validation

Copy the directory to ~/.hermes/plugins/hermes-proof (or %LOCALAPPDATA%\hermes\plugins\hermes-proof on native Windows), enable it using the instructions for your installed Hermes version, then run that version's plugin doctor/validation command. The manifest advertises tools only; no lifecycle hook signature has been assumed.

Native validation record

On 2026-11-11, the v0.2 tools were manually validated through a native Hermes Windows session with the verification root explicitly set to the project directory:

  • A matching file_contains check returned verified with persisted report d41c8682-0995-4c08-bac5-6fac3736a1a0.
  • The same contract against changed content returned failed with persisted report 52b18913-5e27-4c29-b3f8-9166597db34d.
  • Both reports were retrieved successfully by ID after a Hermes gateway restart.
  • hermes plugins doctor ... --ci completed successfully against the installed plugin.

This records plugin-doctor success, live tool execution, and restart persistence. Lifecycle-hook compatibility remains outside the v0.2 scope and is not claimed.

Demo

Run the standalone demonstration:

python demo.py

It produces a verified positive result, changes the observed artifact, produces failed, then retrieves the persisted negative report by ID. In Hermes, the equivalent call is:

{"label":"demo deployment","checks":[{"type":"file_contains","target":"demo.txt","expected":"DEPLOYED"}]}

Test

python -m pytest -q

The suite covers positive/negative MVP regression behavior, an unset root, malformed contracts, inaccessible content targets, traversal, absolute paths, symlink escape where the OS permits creating one, Hermes-profile and credential denial, hashes, JSON paths, per-profile persistence, and report-ID traversal.

v1.0 roadmap (not implemented)

  • Hardened HTTPS verification with pinned destinations, public-address policy, redirect revalidation, DNS-rebinding resistance, response limits, and credential redaction.
  • Lifecycle association and policy-driven enforcement only where verified against the installed official Hermes plugin API.
  • Retention/indexing, signatures or tamper evidence, richer audit queries, and concurrency hardening for multiple gateway processes.

These are future capabilities, not v0.2 claims.

README from the reviewed commit 216afb3; it updates when the author re-pins.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section