refactor: no comments left - one-line module docstrings, contracts on public fields only; jobs/job.py; example config and README

src/beaver_gateway/agents/policy.py

@@ -1,18 +1,8 @@
-"""PreToolUse policy - the boundary without permission prompts (§3.7).
+"""PreToolUse policy - the boundary without permission prompts.
 
-``bypassPermissions`` everywhere; what a model may do is decided by
-mounts, ``disallowed_tools`` and the rules here. A rule is a callable
-``(ToolCall) -> Deny | None`` declared per agent (``ClaudeAgent.policy``);
-the SDK backend registers one in-process ``PreToolUse`` hook that runs
-the rules in order and turns the first :class:`Deny` into a hook deny
-whose reason the model reads as the tool result. Rules never see
-secrets and never prompt - they only say no, with a reason.
-
-A rule that raises is a deny too: the boundary fails closed, the
-traceback lands in the log.
-
-Every tool call - allowed or denied - is reported to the audit sink the
-backend was given, so the admin audit page shows what the model touched.
+A rule is a callable ``(ToolCall) -> Deny | None`` declared per agent
+(``ClaudeAgent.policy``); the first :class:`Deny` becomes the tool result
+the model reads back. A rule that raises is a deny too: fails closed.
 """
 
 from __future__ import annotations
@@ -90,11 +80,14 @@ class ToolCall:
         return None
 
     def resolve(self, raw: str) -> Path:
+        """Absolute path for ``raw``, normalised lexically.
+
+        Not via ``Path.resolve``, which would follow symlinks on the host,
+        not the model's view.
+        """
         path = Path(raw).expanduser()
         if not path.is_absolute():
             path = self.cwd / path
-        # ``resolve`` would follow symlinks on the gateway host, which may
-        # not be the model's view; normalise lexically instead.
         return Path(*_normalize(path.parts))
 
 
@@ -136,7 +129,7 @@ async def evaluate(
             verdict = rule(call)
             if inspect.isawaitable(verdict):
                 verdict = await verdict
-        except Exception:  # noqa: BLE001 - a broken rule must fail closed
+        except Exception:  # noqa: BLE001
             name = getattr(rule, "__name__", repr(rule))
             _log.exception("policy rule %s failed on %s", name, call.tool)
             return Deny(reason=f"policy rule {name} failed; the call is refused")