atbash-hermes-plugin 0.9.12.dev0__tar.gz → 0.11.1__tar.gz

{atbash_hermes_plugin-0.9.12.dev0/atbash_hermes_plugin.egg-info → atbash_hermes_plugin-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atbash-hermes-plugin
-Version: 0.9.12.dev0
+Version: 0.11.1
 Summary: Atbash safety plugin for Hermes Agent
 Author: atbash
 License-Expression: Apache-2.0
@@ -11,7 +11,7 @@ Requires-Python: <3.13,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: atbash-sdk==0.9.12.dev0
+Requires-Dist: atbash-sdk==0.11.0
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.29
 Requires-Dist: opentelemetry-sdk<2,>=1.29
@@ -124,8 +124,10 @@ hermes
 ## Optional Settings
 
 ```bash
-# Override the Atbash API endpoint.
-ATBASH_ENDPOINT=https://api.atbash.io
+# Override the Atbash API endpoint. Must be a trusted judge host
+# (atbash.ai / www.atbash.ai under the default policy); other hosts need
+# ATBASH_JUDGE_ENDPOINT_POLICY=self-hosted plus ATBASH_JUDGE_VERIFY_PUBKEY.
+ATBASH_ENDPOINT=https://atbash.ai
 
 # Set to self-hosted when using your own judge endpoint. Self-hosted judges
 # require ATBASH_JUDGE_VERIFY_PUBKEY so the SDK can verify signed responses.
@@ -274,7 +276,9 @@ Hermes sessions.
   - `ATBASH_ENFORCE_DECISION=false`: fail open and allow.
 - Memory writes (`MEMORY.md`, `CLAUDE.md`, `memory/` paths) with `No verdict`: allowed
   and recorded as the new tamper baseline only when the judge marks the response as the
-  AUDIT tier (`status: "logged"`). Any other missing verdict — empty body, truncated
+  AUDIT tier (`status: "logged"`) **and** the deployment opts in to monitor-only with
+  `ATBASH_ALLOW_AUDIT_TIER=1`. Without the opt-in a `logged` answer is refused like any
+  other unjudged one. Any other missing verdict — empty body, truncated
   payload, a proxy error served as 200, a compromised judge — is blocked under
   `ATBASH_ENFORCE_DECISION=true`; under `false` the write proceeds but is never
   recorded as the baseline, because it was not judged.
@@ -299,6 +303,64 @@ After dashboard approval or rejection, the SDK can query held-action status with
 the judgment ID. The Hermes plugin blocks the original tool call and asks the
 user to retry after review, rather than automatically re-running the action.
 
+## Guard Self-Protection And Memory Baselines
+
+- **The guard's own state is not writable by the agent.** Write tools (`write`, `edit`,
+  `multiedit`, `write_file`, `create_file`, `patch`, `apply_patch`, `str_replace_editor`,
+  `fs_write`, `notebook_edit`, and anything the tool map classes as `filesystem_write`)
+  are refused, before judging and in monitor mode too, when they target
+  `~/.config/atbash`, the configured tool map, agent key and hash baseline, a dedicated
+  key directory (such as `/opt/data/atbash`), the Hermes home's `.env`, `.op.env`,
+  `config.yaml` and `SOUL.md` (`~/.hermes`, `$HERMES_HOME`, and `%LOCALAPPDATA%\hermes` on
+  Windows), the Hermes install folder's `.env`, or the plugin's install directory. To
+  change one of these (for example your persona in `SOUL.md`), edit the file yourself;
+  the agent's write is refused even if you approve it inside Hermes. Paths are
+  compared by file identity, so hard links and case variants count. Patch tools are also
+  refused when their body names one of those paths.
+- **A memory file with no trusted baseline is blocked, and nothing is sent anywhere.**
+  A memory file is one of `AGENTS.md`, `AGENTS.override.md`, `CLAUDE.md`, `MEMORY.md`,
+  `USER.md`, `DREAMS.md`, `.hermes.md`, `HERMES.md`, `.cursorrules` (by exact name, and on
+  Windows also the spellings Windows opens as that file, such as `AGENTS.md.`), a
+  `.cursor/rules/*.mdc` file, a `.md`/`.txt` document inside a `memory/` or `memories/`
+  folder, or a file under `~/.claude/projects/` or `~/.openclaw/{workspace,memory}/`.
+  Ordinary code such as `src/memory/alloc.rs` is not memory and is judged like any other
+  file.
+  Files the guard records itself (judged writes) are trusted. For files that existed
+  before the guard (a repository's `AGENTS.md`), review them and trust them yourself,
+  outside the agent:
+
+  ```bash
+  python -m atbash_hermes_plugin seed AGENTS.md memory/notes.md
+  ```
+
+  Run it from outside the repository you are trusting, with absolute paths (for example
+  `cd ~ && python -m atbash_hermes_plugin seed /path/to/repo/AGENTS.md`): `python -m`
+  puts the current folder first on Python's import path, so a hostile repository could
+  otherwise shadow a standard module. The command itself never imports Hermes code.
+
+  It prints the baseline file it wrote. That is the one the guard reads:
+  `ATBASH_MEMORY_HASH_PATH` from your environment or from the Hermes home `.env`, else
+  `~/.config/atbash/hermes-memory-hashes.json`. Pass `--store <file>` to choose it
+  explicitly. If any file in the list cannot be read, nothing is trusted.
+
+  The guard refuses agent tool calls that look like they run the seeder (the command,
+  `seed_memory_baselines`, the baseline file's name, including quoted, variable-split or
+  base64-encoded forms). This is best effort - see the known limit below - and it also
+  refuses harmless agent calls that merely mention those names (editing these docs, a
+  grep for the command).
+
+  In Docker, point the baseline file at the mounted volume so trust survives restarts,
+  e.g. `-e ATBASH_MEMORY_HASH_PATH=/opt/data/atbash/hermes-memory-hashes.json`, and run
+  the seed command inside the container.
+- **What the guard sees:** tool calls only. Hermes loads its context files (`AGENTS.md`,
+  `.hermes.md`, `SOUL.md`, ...) into a new session's instructions without a tool call, so
+  baselines protect the agent's tool reads, and the real control on those files is that
+  agent writes to them are scanned and judged.
+- **Known limit:** the baseline file (`~/.config/atbash/hermes-memory-hashes.json`) is
+  plain JSON. The guard refuses the agent's file tools on it, but a shell command that
+  rewrites a memory file and recomputes its SHA-256 is left to the judge. Closing that
+  needs an authenticated baseline (a MAC) or state outside the agent's reach.
+
 ## Troubleshooting
 
 If Hermes does not show the plugin:

{atbash_hermes_plugin-0.9.12.dev0 → atbash_hermes_plugin-0.11.1}/README.md

@@ -105,8 +105,10 @@ hermes
 ## Optional Settings
 
 ```bash
-# Override the Atbash API endpoint.
-ATBASH_ENDPOINT=https://api.atbash.io
+# Override the Atbash API endpoint. Must be a trusted judge host
+# (atbash.ai / www.atbash.ai under the default policy); other hosts need
+# ATBASH_JUDGE_ENDPOINT_POLICY=self-hosted plus ATBASH_JUDGE_VERIFY_PUBKEY.
+ATBASH_ENDPOINT=https://atbash.ai
 
 # Set to self-hosted when using your own judge endpoint. Self-hosted judges
 # require ATBASH_JUDGE_VERIFY_PUBKEY so the SDK can verify signed responses.
@@ -255,7 +257,9 @@ Hermes sessions.
   - `ATBASH_ENFORCE_DECISION=false`: fail open and allow.
 - Memory writes (`MEMORY.md`, `CLAUDE.md`, `memory/` paths) with `No verdict`: allowed
   and recorded as the new tamper baseline only when the judge marks the response as the
-  AUDIT tier (`status: "logged"`). Any other missing verdict — empty body, truncated
+  AUDIT tier (`status: "logged"`) **and** the deployment opts in to monitor-only with
+  `ATBASH_ALLOW_AUDIT_TIER=1`. Without the opt-in a `logged` answer is refused like any
+  other unjudged one. Any other missing verdict — empty body, truncated
   payload, a proxy error served as 200, a compromised judge — is blocked under
   `ATBASH_ENFORCE_DECISION=true`; under `false` the write proceeds but is never
   recorded as the baseline, because it was not judged.
@@ -280,6 +284,64 @@ After dashboard approval or rejection, the SDK can query held-action status with
 the judgment ID. The Hermes plugin blocks the original tool call and asks the
 user to retry after review, rather than automatically re-running the action.
 
+## Guard Self-Protection And Memory Baselines
+
+- **The guard's own state is not writable by the agent.** Write tools (`write`, `edit`,
+  `multiedit`, `write_file`, `create_file`, `patch`, `apply_patch`, `str_replace_editor`,
+  `fs_write`, `notebook_edit`, and anything the tool map classes as `filesystem_write`)
+  are refused, before judging and in monitor mode too, when they target
+  `~/.config/atbash`, the configured tool map, agent key and hash baseline, a dedicated
+  key directory (such as `/opt/data/atbash`), the Hermes home's `.env`, `.op.env`,
+  `config.yaml` and `SOUL.md` (`~/.hermes`, `$HERMES_HOME`, and `%LOCALAPPDATA%\hermes` on
+  Windows), the Hermes install folder's `.env`, or the plugin's install directory. To
+  change one of these (for example your persona in `SOUL.md`), edit the file yourself;
+  the agent's write is refused even if you approve it inside Hermes. Paths are
+  compared by file identity, so hard links and case variants count. Patch tools are also
+  refused when their body names one of those paths.
+- **A memory file with no trusted baseline is blocked, and nothing is sent anywhere.**
+  A memory file is one of `AGENTS.md`, `AGENTS.override.md`, `CLAUDE.md`, `MEMORY.md`,
+  `USER.md`, `DREAMS.md`, `.hermes.md`, `HERMES.md`, `.cursorrules` (by exact name, and on
+  Windows also the spellings Windows opens as that file, such as `AGENTS.md.`), a
+  `.cursor/rules/*.mdc` file, a `.md`/`.txt` document inside a `memory/` or `memories/`
+  folder, or a file under `~/.claude/projects/` or `~/.openclaw/{workspace,memory}/`.
+  Ordinary code such as `src/memory/alloc.rs` is not memory and is judged like any other
+  file.
+  Files the guard records itself (judged writes) are trusted. For files that existed
+  before the guard (a repository's `AGENTS.md`), review them and trust them yourself,
+  outside the agent:
+
+  ```bash
+  python -m atbash_hermes_plugin seed AGENTS.md memory/notes.md
+  ```
+
+  Run it from outside the repository you are trusting, with absolute paths (for example
+  `cd ~ && python -m atbash_hermes_plugin seed /path/to/repo/AGENTS.md`): `python -m`
+  puts the current folder first on Python's import path, so a hostile repository could
+  otherwise shadow a standard module. The command itself never imports Hermes code.
+
+  It prints the baseline file it wrote. That is the one the guard reads:
+  `ATBASH_MEMORY_HASH_PATH` from your environment or from the Hermes home `.env`, else
+  `~/.config/atbash/hermes-memory-hashes.json`. Pass `--store <file>` to choose it
+  explicitly. If any file in the list cannot be read, nothing is trusted.
+
+  The guard refuses agent tool calls that look like they run the seeder (the command,
+  `seed_memory_baselines`, the baseline file's name, including quoted, variable-split or
+  base64-encoded forms). This is best effort - see the known limit below - and it also
+  refuses harmless agent calls that merely mention those names (editing these docs, a
+  grep for the command).
+
+  In Docker, point the baseline file at the mounted volume so trust survives restarts,
+  e.g. `-e ATBASH_MEMORY_HASH_PATH=/opt/data/atbash/hermes-memory-hashes.json`, and run
+  the seed command inside the container.
+- **What the guard sees:** tool calls only. Hermes loads its context files (`AGENTS.md`,
+  `.hermes.md`, `SOUL.md`, ...) into a new session's instructions without a tool call, so
+  baselines protect the agent's tool reads, and the real control on those files is that
+  agent writes to them are scanned and judged.
+- **Known limit:** the baseline file (`~/.config/atbash/hermes-memory-hashes.json`) is
+  plain JSON. The guard refuses the agent's file tools on it, but a shell command that
+  rewrites a memory file and recomputes its SHA-256 is left to the judge. Closing that
+  needs an authenticated baseline (a MAC) or state outside the agent's reach.
+
 ## Troubleshooting
 
 If Hermes does not show the plugin: