atbash-hermes-plugin 0.4.8.dev0__tar.gz → 0.4.10.dev0__tar.gz

atbash_hermes_plugin-0.4.10.dev0/MANIFEST.in

@@ -0,0 +1 @@
+include plugin.yaml

{atbash_hermes_plugin-0.4.8.dev0 → atbash_hermes_plugin-0.4.10.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atbash-hermes-plugin
-Version: 0.4.8.dev0
+Version: 0.4.10.dev0
 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.5.0
+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.8.dev0 → atbash_hermes_plugin-0.4.10.dev0}/README.md

@@ -12,37 +12,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
 
@@ -52,10 +41,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":"..."}'
@@ -63,7 +52,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:
 
@@ -74,7 +63,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
@@ -114,11 +103,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
@@ -136,13 +121,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
@@ -153,7 +144,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:
@@ -227,13 +218,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
@@ -248,24 +247,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,