docs(approval): say that save_permanent_allowlist can only add, and that a revocation waits for the next write

Review follow-up. Two of the three items taken as written; the third declined
with a reason.

1. Taken. The reconcile semantics mean `patterns` may only ADD -- an entry left
   out of it is not removed, because the on-disk list wins for anything this
   process did not approve itself. Every caller in the tree is additive today,
   so nothing breaks, but the signature does not say so. Stated in the
   docstring, and pinned by
   `test_a_caller_that_passes_a_smaller_set_does_not_remove` so a future
   `allowlist remove` finds out here instead of in production.

   NOT taken: the `reconcile: bool = True` opt-out. There is no caller that
   wants it, and AGENTS.md:98-101 names exactly this -- "Speculative
   infrastructure. Hooks, callbacks, or extension points with no concrete
   consumer." The removal path is editing config.yaml, which the docstring now
   says.

2. Taken. website/docs/user-guide/security.md, next to the existing
   `hermes config edit` tip, which is where an operator reads about removing a
   pattern: the list is read at startup, a pattern removed while a session is
   running stays approved in that session until the next write or a restart,
   and if it was removed for safety reasons, restart.

3. Taken. `test_save_failure_is_logged_not_raised` asserted non-raising but
   never asserted the log its name promises. Now asserts
   "Could not save allowlist" via caplog.

    scripts/run_tests.sh tests/tools/test_permanent_allowlist_reconcile.py
    === Summary: 1 files, 9 tests passed, 0 failed (100% complete) in 0.4s
This commit is contained in:
durden
2026-08-23 15:04:23 +05:00
committed by Teknium
parent 9b06d3d081
commit 98d54ee7b3
3 changed files with 31 additions and 2 deletions

View File

@@ -413,6 +413,10 @@ def save_permanent_allowlist(patterns: set):
plus ``what this process approved since its own baseline``; revoked entries are
also dropped from the governing permanent set so ``is_approved()`` stops
honouring them. Nothing re-reads the file on the approval hot path.
``patterns`` may only ADD: an entry left out of it is not removed, because the
on-disk list wins for anything this process did not approve itself. Remove
entries by editing ``command_allowlist`` in config.yaml.
"""
try:
from hermes_cli.config import load_config, save_config