atbash-hermes-plugin 0.4.9.dev0__py3-none-any.whl → 0.4.10.dev1__py3-none-any.whl

atbash_hermes_plugin/__init__.py

@@ -4,6 +4,7 @@ import atexit
 import hashlib
 import json
 import logging
+import inspect
 import os
 import re
 import time
@@ -336,6 +337,134 @@ def _resolve_asset(token: str) -> str:
     return "other"
 
 
+_STATEMENT_SEP_RE = re.compile(r"[;&|<>$`\r\n]")
+
+def _flag_values(command: str, name: str) -> list:
+    return [
+        value.strip("'\"")
+        for value in re.findall(rf"--{re.escape(name)}[= ]+(\S+)", command)
+    ]
+
+def _numeric_amount(value: Optional[str]) -> Optional[str]:
+    """Return ``value`` only if it is a plain ASCII decimal, else ``None``.
+
+    ``[0-9]`` rather than ``\\d``: in Python ``\\d`` matches every Unicode
+    decimal digit, so ``--amount ١٢٣`` passed the check and was forwarded
+    verbatim into the un-redacted ``resolved`` block. Callers must treat a
+    ``None`` here as "unparsable", not as "no amount given" — see
+    ``_canonicalize_financial``.
+    """
+    if value is None or len(value) > 64:
+        return None
+    return value if re.fullmatch(r"(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)", value) else None
+
+
+_TRUE_VALUES = {"1", "true", "yes", "on"}
+
+_FALSE_VALUES = {"0", "false", "no", "off"}
+
+def _enforcement_enabled(value: Optional[str]) -> bool:
+    """Parse ATBASH_ENFORCE_DECISION as opt-OUT, not opt-in.
+
+    This flag guards every fail-open branch in the guard, so it must take an
+    explicit, recognised falsey value to switch off. Read with the truthy
+    matching used for the other flags, an empty string — which is what
+    docker-compose passes for `ATBASH_ENFORCE_DECISION=${VAR}` when the host
+    variable is unset — or a typo like "y" or "strict" silently put the guard
+    in fail-open mode with nothing in the log to show for it.
+    """
+    if value is None:
+        return True
+    normalized = value.strip().lower()
+    if normalized in _FALSE_VALUES:
+        return False
+    if normalized and normalized not in _TRUE_VALUES:
+        logger.error(
+            "ATBASH_ENFORCE_DECISION=%r is not a recognized value; "
+            "keeping enforcement on (fail-closed)",
+            value,
+        )
+    return True
+
+
+def _strict_reading(
+    command: str,
+    recipient_allowlist: set,
+    may_hide_other_actions: bool,
+) -> Dict[str, Any]:
+    """The most conservative concrete facts that survive an ambiguous command.
+
+    Replacing every fact with "ambiguous" makes asset-specific policy ("never
+    lifts ETH or ATBASH rules") unreachable for any command carrying a
+    separator. So report every asset named, the largest amount named (or
+    "unparsable"), and whether *every* recipient named is allowlisted.
+
+    Every field describes only the text that was parsed. When the command can
+    expand or chain into statements this never saw, `may_hide_other_actions` is
+    True and none of these facts bound what actually runs — which is why they
+    are named "…_named" and why nothing here may be read as permission.
+    """
+    recipients = _flag_values(command, "to") + _flag_values(command, "recipient")
+    lowered_recipients = {r.lower() for r in recipients}
+    tokens = _flag_values(command, "token")
+    addresses = [
+        address
+        for address in _ERC20_RE.findall(command)
+        if address.lower() not in lowered_recipients
+    ]
+    assets = sorted({_resolve_asset(t) for t in tokens + addresses}) or ["ETH"]
+
+    raw_amounts = _flag_values(command, "amount") + _flag_values(command, "max-usd")
+    parsed = [_numeric_amount(v) for v in raw_amounts]
+    if any(p is None for p in parsed):
+        max_amount: Optional[str] = "unparsable"
+    elif parsed:
+        max_amount = max(parsed, key=lambda v: float(v))
+    else:
+        max_amount = None
+
+    return {
+        "assets_named": assets,
+        "max_amount_named": max_amount,
+        "recipients_named": len(recipients),
+        "all_named_recipients_allowlisted": bool(recipients)
+        and all(r.lower() in recipient_allowlist for r in recipients),
+        "may_hide_other_actions": may_hide_other_actions,
+    }
+
+
+def _assert_sdk_capabilities(
+    sdk: Any,
+    atbash_class: Any,
+    tool_call_input_class: Any,
+) -> None:
+    guard_api_version = getattr(sdk, "GUARD_API_VERSION", 0)
+    if not isinstance(guard_api_version, int) or guard_api_version < 1:
+        raise RuntimeError(
+            "atbash-sdk does not expose hardened guard API version 1; "
+            "install atbash-sdk==0.2.0"
+        )
+    if not callable(getattr(atbash_class, "from_config", None)):
+        raise RuntimeError("atbash-sdk is missing Atbash.from_config")
+    if not callable(getattr(atbash_class, "audit_tool_call", None)):
+        raise RuntimeError("atbash-sdk is missing Atbash.audit_tool_call")
+    try:
+        from_config_parameters = inspect.signature(
+            atbash_class.from_config
+        ).parameters
+        parameters = inspect.signature(tool_call_input_class).parameters
+    except (TypeError, ValueError) as error:
+        raise RuntimeError("cannot inspect atbash-sdk guard APIs") from error
+    for required_parameter in ("judge", "org_name", "fail_closed"):
+        if required_parameter not in from_config_parameters:
+            raise RuntimeError(
+                "atbash-sdk Atbash.from_config is missing "
+                f"{required_parameter} support"
+            )
+    if "resolved" not in parameters:
+        raise RuntimeError("atbash-sdk ToolCallInput is missing resolved support")
+
+
 def _canonicalize_financial(command: str, recipient_allowlist: set) -> Optional[Dict[str, Any]]:
     if not command:
         return None
@@ -345,18 +474,90 @@ def _canonicalize_financial(command: str, recipient_allowlist: set) -> Optional[
         return None
 
     def _flag(name: str) -> Optional[str]:
-        m = re.search(rf"--{name}[= ]+(\S+)", command)
-        return m.group(1).strip("'\"") if m else None
+        values = _flag_values(command, name)
+        return values[0] if values else None
 
+    op = (
+        "swap" if re.search(r"\bswap\b", command, re.IGNORECASE)
+        else "approve" if re.search(r"\b(approve|erc20)\b", command, re.IGNORECASE)
+        else "transfer"
+    )
+
+    # The judge rules on this block rather than on the raw command — the SDK
+    # redacts every 0x address out of args before it is sent — so reading only
+    # the first occurrence of a flag lets a prompt-injected command assert an
+    # allowlisted 1-unit transfer while what actually executes is a second one.
+    # CLI parsers are last-flag-wins and a shell runs every `;`-separated
+    # statement. When the text can mean more than one thing, say so instead of
+    # picking a reading and asserting it.
+    repeated_recipient = len(_flag_values(command, "to")) + len(
+        _flag_values(command, "recipient")
+    ) > 1
+    repeated_flag = any(
+        len(_flag_values(command, name)) > 1
+        for name in ("token", "amount", "max-usd")
+    )
+    multi_statement = bool(_STATEMENT_SEP_RE.search(command))
+
+    # "absent" and "present but unparsable" must not collapse to the same
+    # signal. `--amount 1e9` parses as no plain decimal, and reporting it as
+    # amount=None next to recipient_status="allowlisted" hands the judge
+    # "allowlisted recipient, no amount stated" for a command that names a very
+    # large one — which is exactly what an "allow allowlisted USDT under N"
+    # policy would let through.
+    raw_amount = _flag("amount")
+    raw_max_usd = _flag("max-usd")
+    amount = _numeric_amount(raw_amount)
+    max_usd = _numeric_amount(raw_max_usd)
+    amount_unparsed = (raw_amount is not None and amount is None) or (
+        raw_max_usd is not None and max_usd is None
+    )
+
+    if repeated_recipient or repeated_flag or multi_statement or amount_unparsed:
+        return {
+            "operation": op,
+            "asset": "ambiguous",
+            "amount": None,
+            "max_usd": None,
+            "recipient_status": "ambiguous",
+            "ambiguous": True,
+            "amount_unparsed": amount_unparsed,
+            "ambiguous_reason": (
+                "multiple statements, redirection or substitution"
+                if multi_statement
+                else "repeated flag"
+                if (repeated_recipient or repeated_flag)
+                else "amount is not a plain decimal number"
+            ),
+            # Conservative facts, so an asset-specific rule is still reachable.
+            # Never grant on these: recipient_status above stays "ambiguous".
+            "strict_reading": _strict_reading(
+                command, recipient_allowlist, multi_statement
+            ),
+            "allowlist_scope": "USDT transfers/approvals only; never lifts ETH or ATBASH rules",
+            "note": (
+                "canonicalization withheld: the command carries more than one "
+                "transfer or flag value, an unreadable amount, or text that a "
+                "shell would expand, so no asset/amount/recipient claim here "
+                "can be trusted"
+            ),
+        }
+
+    to = _flag("to") or _flag("recipient")
     token = _flag("token")
     if not token:
-        m = _ERC20_RE.search(command)
-        if m:
-            token = m.group(1)
+        # Only an address that is not the recipient can be the token contract.
+        # Taking the first 0x in the command picked up the RECIPIENT of a
+        # native send, resolved it to "other", and made the stricter ETH rule
+        # unreachable for every command that names an address.
+        candidates = [
+            address
+            for address in _ERC20_RE.findall(command)
+            if not to or address.lower() != to.lower()
+        ]
+        if candidates:
+            token = candidates[0]
 
-    to = _flag("to") or _flag("recipient")
-    amount = _flag("amount")
-    max_usd = _flag("max-usd")
     asset = _resolve_asset(token or "")
 
     on_allow = bool(to) and to.lower() in recipient_allowlist
@@ -365,18 +566,16 @@ def _canonicalize_financial(command: str, recipient_allowlist: set) -> Optional[
     else:
         recipient_status = "external" if to else "unspecified"
 
-    op = (
-        "swap" if re.search(r"\bswap\b", command, re.IGNORECASE)
-        else "approve" if re.search(r"\b(approve|erc20)\b", command, re.IGNORECASE)
-        else "transfer"
-    )
-
     return {
         "operation": op,
         "asset": asset,
         "amount": amount,
         "max_usd": max_usd,
         "recipient_status": recipient_status,
+        "ambiguous": False,
+        # Always present so that its absence is never the thing that has to be
+        # noticed: here it is False, so amount=None really does mean "not given".
+        "amount_unparsed": False,
         "allowlist_scope": "USDT transfers/approvals only; never lifts ETH or ATBASH rules",
         "note": "canonicalized pre-judge; raw 0x addresses omitted (redacted upstream)",
     }
@@ -416,9 +615,29 @@ def _infer_action_class(tool_name: str) -> str:
 
 
 def _as_bool(value: Optional[str], default: bool) -> bool:
+    """Parse a boolean env var, refusing to guess.
+
+    This used to be ``value.strip().lower() in {"1","true","yes","on"}``, so
+    every value outside that set read as False. ``ATBASH_ENFORCE_DECISION=``
+    (empty, the normal shape when a .env entry is left blank) or a typo like
+    ``enabled`` therefore turned enforcement OFF silently, on the one setting
+    that decides whether this plugin blocks anything at all. An unrecognised
+    value now keeps the default and says so.
+    """
     if value is None:
         return default
-    return value.strip().lower() in {"1", "true", "yes", "on"}
+    v = value.strip().lower()
+    if v in {"1", "true", "yes", "on"}:
+        return True
+    if v in {"0", "false", "no", "off"}:
+        return False
+    logger.warning(
+        "Atbash: unrecognized boolean value %r; keeping the default (%s). "
+        "Use one of 1/true/yes/on or 0/false/no/off.",
+        value,
+        default,
+    )
+    return default
 
 
 def _normalize_verdict(raw: Any) -> str:
@@ -550,14 +769,13 @@ def _setup_telemetry() -> None:
 class AtbashHermesGuard:
     def __init__(self) -> None:
         self.debug = _as_bool(os.getenv("ATBASH_DEBUG"), False)
-        self.fail_closed = _as_bool(os.getenv("ATBASH_ENFORCE_DECISION"), True)
+        self.fail_closed = _enforcement_enabled(os.getenv("ATBASH_ENFORCE_DECISION"))
         self.endpoint = os.getenv("ATBASH_ENDPOINT")
         self.judge_endpoint_policy = os.getenv("ATBASH_JUDGE_ENDPOINT_POLICY")
         self.judge_verify_pubkey = os.getenv("ATBASH_JUDGE_VERIFY_PUBKEY")
-        self.key_path = os.path.expandvars(os.path.expanduser(os.getenv("ATBASH_KEY_PATH") or "")) or None
+        self.key_path = os.getenv("ATBASH_KEY_PATH")
         self.privkey = os.getenv("ATBASH_AGENT_PRIVKEY")
         self.org_name = os.getenv("ATBASH_ORG_NAME")
-        self.request_timeout = float(os.getenv("ATBASH_REQUEST_TIMEOUT") or 60.0)
         self.provider = os.getenv("HERMES_PROVIDER")
         self.model = os.getenv("HERMES_MODEL")
         self.tool_map_path = Path(
@@ -600,7 +818,7 @@ class AtbashHermesGuard:
                 from atbash import Atbash  # type: ignore
                 from atbash.types import ToolCallInput  # type: ignore
             except Exception:
-                raise RuntimeError("atbash-sdk is required. Install with: pip install atbash-sdk==0.4.10.dev0") from e
+                raise RuntimeError("atbash-sdk is required. Install with: pip install atbash-sdk==0.4.3.dev0") from e
 
         self.ToolCallInput = ToolCallInput
         judge_cfg = self._judge_config()
@@ -613,7 +831,6 @@ class AtbashHermesGuard:
                     judge=judge_cfg,
                     org_name=self.org_name,
                     fail_closed=self.fail_closed,
-                    timeout=self.request_timeout,
                 )
             except TypeError:
                 kwargs: Dict[str, Any] = {
@@ -632,7 +849,6 @@ class AtbashHermesGuard:
             judge=judge_cfg,
             org_name=self.org_name,
             fail_closed=self.fail_closed,
-            timeout=self.request_timeout,
         )
 
     def _judge_config(self) -> Optional[Dict[str, str]]:
@@ -856,7 +1072,7 @@ class AtbashHermesGuard:
                 return None
 
             allow_flag = _extract_allow(verdict_raw)
-            if verdict == "ALLOW" and allow_flag is True:
+            if verdict == "ALLOW" and allow_flag is not False:
                 self._snapshots[path] = new_content
                 self._hash_store.set(path, _sha256_hex(new_content))
                 return None
@@ -1036,20 +1252,30 @@ class AtbashHermesGuard:
                     }
                 return None
 
+            # Strict allowlist. _normalize_verdict passes any unrecognised
+            # string straight through (it only maps None to ERROR), and this
+            # used to end in a bare `return None`, i.e. run the tool. So a
+            # renamed verdict, a typo, an SDK newer than this plugin, or a
+            # response the SDK itself marked allow=False all executed the
+            # call. Only an exact ALLOW that the SDK also vouches for runs;
+            # a missing allow flag is not permission.
             allow_flag = _extract_allow(verdict_raw)
             if verdict == "ALLOW" and allow_flag is True:
                 return None
 
             logger.warning(
-                "Atbash unusable verdict tool=%s verdict=%s allow=%s",
+                "Atbash unusable verdict tool=%s verdict=%s allow=%s reason=%s",
                 tool_name,
                 verdict,
                 allow_flag,
+                reason,
             )
             if self.fail_closed:
                 return {
                     "action": "block",
-                    "message": f"Blocked (unrecognized verdict {verdict!r}): {reason}",
+                    "message": (
+                        f"Blocked (unusable Atbash verdict {verdict!r}): {reason}"
+                    ),
                 }
             return None
         except Exception as e:
@@ -1064,7 +1290,34 @@ class AtbashHermesGuard:
 
 def register(ctx):
     _setup_telemetry()
-    guard = AtbashHermesGuard()
-    guard._run_boot_probe()
-    ctx.register_hook("pre_tool_call", guard.pre_tool_call)
-    logger.info("[atbash-hermes-plugin] registered pre_tool_call hook")
+    state: Dict[str, Any] = {"guard": None, "error": "guard initialization incomplete"}
+
+    def fail_closed_pre_tool_call(**kwargs: Any):
+        guard = state["guard"]
+        if guard is None:
+            return {
+                "action": "block",
+                "message": f"Blocked (Atbash guard unavailable): {state['error']}",
+            }
+        return guard.pre_tool_call(**kwargs)
+
+    # Hermes isolates plugin-load exceptions and continues startup, so install
+    # the blocking hook before any SDK/config initialization can fail.
+    ctx.register_hook("pre_tool_call", fail_closed_pre_tool_call)
+    try:
+        state["guard"] = AtbashHermesGuard()
+    except Exception as error:
+        state["error"] = str(error)
+        logger.error(
+            "[atbash-hermes-plugin] guard initialization failed; "
+            "pre_tool_call remains fail-closed err=%s",
+            error,
+        )
+        return
+    # Say which mode actually registered — operators read this line as
+    # confirmation that enforcement is on, so it must not claim fail-closed
+    # when ATBASH_ENFORCE_DECISION turned enforcement off.
+    logger.info(
+        "[atbash-hermes-plugin] registered pre_tool_call hook mode=%s",
+        "fail-closed" if state["guard"].fail_closed else "fail-open",
+    )

{atbash_hermes_plugin-0.4.9.dev0.dist-info → atbash_hermes_plugin-0.4.10.dev1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atbash-hermes-plugin
-Version: 0.4.9.dev0
+Version: 0.4.10.dev1
 Summary: Atbash safety plugin for Hermes Agent
 Author: atbash
 License-Expression: LicenseRef-Atbash-Proprietary
@@ -10,7 +10,7 @@ Keywords: atbash,hermes,hermes-agent,agent-safety,ai-safety,tool-guard,judge,pol
 Requires-Python: <3.13,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: atbash-sdk==0.4.10.dev0
+Requires-Dist: atbash-sdk==0.5.2.dev0
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.29
 Requires-Dist: opentelemetry-sdk<2,>=1.29
@@ -30,37 +30,26 @@ stopped before execution.
 - Intercepts Hermes tool calls through `pre_tool_call`.
 - Sends the tool name, arguments, command-like payload, session metadata, and
   inferred action class to Atbash.
-- Blocks tool execution on `BLOCK`, `DENY`, `REJECT`, or `DISALLOW`; holds it for operator review on `HOLD`.
+- Blocks tool execution on `BLOCK`, `DENY`, `REJECT`, `DISALLOW`, or `HOLD`.
 - Persists learned Hermes tool classifications across sessions.
 
 ## Install
 
-Hermes manages its own Python environment. Install the plugin directly into it —
-do **not** use your system `pip` — on macOS and some Linux distros it will be blocked by the OS.
-
-**If you installed Hermes via the official install script (`curl … | bash`):**
+Install the plugin into the same Python environment that runs Hermes.
+This prerelease requires Python 3.10 through 3.12, matching `atbash-sdk==0.4.3.dev0`.
 
 ```bash
-~/.hermes/hermes-agent/venv/bin/pip3 install atbash-hermes-plugin
+pip install --pre atbash-hermes-plugin==0.4.3.dev0
 ```
 
-**If you installed Hermes via `uv`:**
+If Hermes is installed in a virtual environment, use that environment's Python:
 
 ```bash
-uv pip install --python ~/.hermes/hermes-agent/venv/bin/python atbash-hermes-plugin
+/path/to/hermes/venv/bin/python -m pip install --pre atbash-hermes-plugin==0.4.3.dev0
 ```
 
-To install the latest dev release, add `--pre` (pip) or `--prerelease=allow` (uv):
-
-```bash
-# pip
-~/.hermes/hermes-agent/venv/bin/pip3 install --pre atbash-hermes-plugin
-
-# uv
-uv pip install --python ~/.hermes/hermes-agent/venv/bin/python --prerelease=allow atbash-hermes-plugin
-```
-
-No further activation step is needed — Hermes discovers the plugin automatically on next start.
+Maintainers: releases use clean staged source, live PyPI monotonic checks, and
+Trusted Publishing. See [the release process](docs/release.md).
 
 ## Configure Atbash
 
@@ -70,10 +59,10 @@ The plugin needs an Atbash agent key. Configure either `ATBASH_KEY_PATH` or
 Recommended:
 
 ```bash
-ATBASH_KEY_PATH=~/.config/atbash/guard-client-key
+ATBASH_KEY_PATH=$HOME/.config/atbash/guard-client-key
 ```
 
-Alternative (paste the key JSON directly):
+Alternative:
 
 ```bash
 ATBASH_AGENT_PRIVKEY='{"pubkey":"...","privkey":"..."}'
@@ -81,7 +70,7 @@ ATBASH_AGENT_PRIVKEY='{"pubkey":"...","privkey":"..."}'
 
 ## Where To Set Environment Variables
 
-Hermes loads environment variables from `~/.hermes/.env`.
+Hermes commonly loads environment variables from `~/.hermes/.env`.
 
 Create or edit that file:
 
@@ -92,7 +81,7 @@ nano ~/.hermes/.env
 Add:
 
 ```bash
-ATBASH_KEY_PATH=~/.config/atbash/guard-client-key
+ATBASH_KEY_PATH=$HOME/.config/atbash/guard-client-key
 ATBASH_ENFORCE_DECISION=true
 ATBASH_DEBUG=false
 ATBASH_ORG_NAME=your-org-name
@@ -132,11 +121,7 @@ ATBASH_DEBUG=false
 ATBASH_ORG_NAME=your-org-name
 
 # Override where learned Hermes tool classifications are saved.
-ATBASH_TOOL_MAP_PATH=~/.config/atbash/hermes-tool-map.json
-
-# HTTP request timeout in seconds for judge API calls. Default: 60.
-# Raise this if you see "read operation timed out" errors on a slow endpoint.
-ATBASH_REQUEST_TIMEOUT=60
+ATBASH_TOOL_MAP_PATH=$HOME/.config/atbash/hermes-tool-map.json
 ```
 
 ## Telemetry
@@ -154,13 +139,19 @@ printf '{"enabled": false}\n' > ~/.config/atbash/telemetry.json
 
 ## Enable Or Check The Plugin
 
-Hermes discovers the plugin automatically via Python entry points — no manual
-enable step is needed. Restarting Hermes after installation is sufficient.
+Hermes should discover installed Python packages that expose the
+`hermes_agent.plugins` entry point.
 
-To confirm the package is installed in the right environment:
+Check whether Hermes sees the plugin:
 
 ```bash
-~/.hermes/hermes-agent/venv/bin/pip3 show atbash-hermes-plugin
+hermes plugins list | grep atbash
+```
+
+If needed, enable it:
+
+```bash
+hermes plugins enable atbash-hermes-plugin
 ```
 
 ## Verify It Is Working
@@ -171,7 +162,7 @@ file or opening a website.
 In another terminal, watch the Hermes log:
 
 ```bash
-tail -f ~/.hermes/logs/agent.log | grep -i atbash
+tail -f ~/.hermes/logs/agent.log
 ```
 
 With `ATBASH_DEBUG=true`, you should see lines similar to:
@@ -245,13 +236,21 @@ Hermes sessions.
 
 ## Verdict Behavior
 
-- `ALLOW`: the tool proceeds.
+- `ALLOW` with `allow is True`: the tool proceeds. A missing `allow` flag is denied.
 - `HOLD`: the tool is blocked with a review message.
 - `BLOCK`, `DENY`, `REJECT`, `DISALLOW`: the tool is blocked.
 - Atbash API error:
   - `ATBASH_ENFORCE_DECISION=true`: fail closed and block.
   - `ATBASH_ENFORCE_DECISION=false`: fail open and allow.
 
+Atbash ships fail-closed on every tier. Setting `ATBASH_ENFORCE_DECISION=false`
+inverts that for this agent: a judge outage becomes a silent allow, and the
+governance layer stops governing for as long as it lasts. That is supported, but
+record a written risk acceptance in the deployment's security summary before
+turning it off, so the trade-off is auditable after an incident rather than
+discovered during one. See decision 0003 (fail-closed default) in the dashboard
+repo.
+
 For `HOLD`, the user-facing block message is:
 
 ```text
@@ -266,24 +265,26 @@ user to retry after review, rather than automatically re-running the action.
 
 ## Troubleshooting
 
-If the plugin is not being picked up, confirm it is installed in the Hermes
-environment (not the system Python):
+If Hermes does not show the plugin:
 
 ```bash
-~/.hermes/hermes-agent/venv/bin/pip3 show atbash-hermes-plugin
+hermes plugins list | grep atbash
+python -m pip show atbash-hermes-plugin
 ```
 
-If Atbash verdicts are not appearing in logs, enable debug mode by adding this
-to `~/.hermes/.env`:
+Make sure the package was installed into the same Python environment that runs
+Hermes.
+
+If Atbash verdicts are not appearing in logs:
 
 ```bash
 ATBASH_DEBUG=true
 ```
 
-Then restart Hermes and watch in a second terminal:
+Then restart Hermes and watch:
 
 ```bash
-tail -f ~/.hermes/logs/agent.log | grep -i atbash
+tail -f ~/.hermes/logs/agent.log
 ```
 
 If the plugin blocks everything with an unavailable-key or authentication error,

atbash_hermes_plugin-0.4.10.dev1.dist-info/RECORD

@@ -0,0 +1,7 @@
+atbash_hermes_plugin/__init__.py,sha256=vd7kxSnqMGrU3oYttRM6bLw5WwU4Rg5UsDXFXtO0pt8,53307
+atbash_hermes_plugin-0.4.10.dev1.dist-info/licenses/LICENSE,sha256=1vOJDJvAuOLDHJ8-Q0qDdOXZJJVli6Lr9mKKaFsOa5w,1600
+atbash_hermes_plugin-0.4.10.dev1.dist-info/METADATA,sha256=Hc4ffzsDOASmiNASYWQ38KvfB4wt6Q4zENxAOqO3qbY,8069
+atbash_hermes_plugin-0.4.10.dev1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+atbash_hermes_plugin-0.4.10.dev1.dist-info/entry_points.txt,sha256=YezkmasjRBXrSlXpqhSJdFhDCdBbENp-_THYtkcRTBo,67
+atbash_hermes_plugin-0.4.10.dev1.dist-info/top_level.txt,sha256=0nT35m8jNxzbQB3CerGf5kgH7hm_pc6GLadlf69w_JM,21
+atbash_hermes_plugin-0.4.10.dev1.dist-info/RECORD,,

atbash_hermes_plugin-0.4.9.dev0.dist-info/RECORD

@@ -1,7 +0,0 @@
-atbash_hermes_plugin/__init__.py,sha256=ww06aPT4JT_N7ghxK6aeqqunAm-LlRVMv_DFcmwu_io,42419
-atbash_hermes_plugin-0.4.9.dev0.dist-info/licenses/LICENSE,sha256=1vOJDJvAuOLDHJ8-Q0qDdOXZJJVli6Lr9mKKaFsOa5w,1600
-atbash_hermes_plugin-0.4.9.dev0.dist-info/METADATA,sha256=ZtC0MWooKrBr8BNOXZKJXUVw2lZP_CMz-PLSOqEBin0,8184
-atbash_hermes_plugin-0.4.9.dev0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-atbash_hermes_plugin-0.4.9.dev0.dist-info/entry_points.txt,sha256=YezkmasjRBXrSlXpqhSJdFhDCdBbENp-_THYtkcRTBo,67
-atbash_hermes_plugin-0.4.9.dev0.dist-info/top_level.txt,sha256=0nT35m8jNxzbQB3CerGf5kgH7hm_pc6GLadlf69w_JM,21
-atbash_hermes_plugin-0.4.9.dev0.dist-info/RECORD,,