regent-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{regent_cli-0.5.0/src/regent_cli.egg-info → regent_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regent-cli
-Version: 0.5.0
+Version: 0.7.0
 Summary: Autonomous conduction and mediated adversarial deliberation between AI agents, pluggable into any project.
 Author-email: Flavio Alvim <flavioalvim@gmail.com>
 License: MIT
@@ -53,7 +53,12 @@ phase 1 mechanizes the two most error-prone sub-steps: `regent advisor consult
 --prompt-file … --artifact … --linkage …` (read-only sandboxed consultation with the
 REQ-003 §5 evidence pair generated by the command, fail-closed verdict expectation) and
 `regent gate run --command … --declared-in <plan> --artifact … --linkage …` (verbatim
-provenance check, process-group-killing timeout, integral output preserved).
+provenance check, process-group-killing timeout, integral output preserved). Conduction
+phase 2 adds `regent turn run`: one supervised, CONFINED `claude -p` turn — the agent may
+only write inside a declared envelope (a PreToolUse hook denies the rest), the supervisor
+proves what changed via git (blob shas vs authenticated post events) and commits through a
+private index with a HEAD compare-and-swap. The agent never commits; a violation, a
+tampered log or a red gate never yields a product commit.
 
 Development: `PYTHONPATH=src python3 -m unittest discover -s tests`; packaging gate:
 `bash scripts/gate-package.sh`. Canonical skill content lives in `src/regent/templates/`

{regent_cli-0.5.0 → regent_cli-0.7.0}/README.md

@@ -37,7 +37,12 @@ phase 1 mechanizes the two most error-prone sub-steps: `regent advisor consult
 --prompt-file … --artifact … --linkage …` (read-only sandboxed consultation with the
 REQ-003 §5 evidence pair generated by the command, fail-closed verdict expectation) and
 `regent gate run --command … --declared-in <plan> --artifact … --linkage …` (verbatim
-provenance check, process-group-killing timeout, integral output preserved).
+provenance check, process-group-killing timeout, integral output preserved). Conduction
+phase 2 adds `regent turn run`: one supervised, CONFINED `claude -p` turn — the agent may
+only write inside a declared envelope (a PreToolUse hook denies the rest), the supervisor
+proves what changed via git (blob shas vs authenticated post events) and commits through a
+private index with a HEAD compare-and-swap. The agent never commits; a violation, a
+tampered log or a red gate never yields a product commit.
 
 Development: `PYTHONPATH=src python3 -m unittest discover -s tests`; packaging gate:
 `bash scripts/gate-package.sh`. Canonical skill content lives in `src/regent/templates/`

{regent_cli-0.5.0 → regent_cli-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "regent-cli"
-version = "0.5.0"
+version = "0.7.0"
 description = "Autonomous conduction and mediated adversarial deliberation between AI agents, pluggable into any project."
 readme = "README.md"
 requires-python = ">=3.10"

{regent_cli-0.5.0 → regent_cli-0.7.0}/src/regent/__init__.py

@@ -1,3 +1,3 @@
 """regent — autonomous conduction and mediated adversarial deliberation between AI agents."""
 
-__version__ = "0.5.0"
+__version__ = "0.7.0"

{regent_cli-0.5.0 → regent_cli-0.7.0}/src/regent/activity_cli.py

@@ -25,6 +25,12 @@ _EXIT_BY_CODE = {
     "TOKEN_MISMATCH": 3, "LOCK_HELD": 3, "LOCK_SUSPECT": 3, "BUSY": 3,
     "CONFLICT": 3, "UNATTRIBUTABLE": 3, "CORRUPT_CONTROL": 4, "IO": 5,
     "ADVISOR_FAILED": 3, "ADVISOR_UNAVAILABLE": 2, "GATE_RED": 3, "PROVENANCE": 3,
+    "TURN_VIOLATION": 3, "TURN_TAMPERED": 3, "TURN_FAILED": 3, "NOT_ACTIVE": 2,
+    "STEP_MISMATCH": 2, "ARTIFACT_OUTSIDE_REGENT": 2, "STEP_ALREADY_DONE": 2,
+    "WORKTREE_DIRTY": 3,
+    "LOOP_HALTED": 3, "LOOP_ABORTED": 3, "LOOP_MAX_TURNS": 3, "LOOP_STOPPED": 2,
+    "LOOP_BUSY": 3, "PLAN_NOT_EXECUTABLE": 2, "LOOP_CONFLICT": 3, "LOOP_DIRTY": 3,
+    "LOOP_MISCONFIGURED": 2, "ABORT_PENDING": 3,
 }
 
 
@@ -102,6 +108,38 @@ def build_parser(sub) -> None:
     p.add_argument("--timeout", type=float, default=600.0)
     p.add_argument("--expect-verdict", default=None, dest="expect_verdict")
 
+    p_loop = sub.add_parser("loop", help="chain supervised turns over a plan")
+    p_loop.add_argument("--project", default=None)
+    loop_sub = p_loop.add_subparsers(dest="loop_command", required=True)
+    p = loop_sub.add_parser("run")
+    p.add_argument("--plan", required=True)
+    p.add_argument("--prompt-template", required=True, dest="prompt_template")
+    p.add_argument("--envelope", action="append", required=True)
+    p.add_argument("--gate-envelope", action="append", default=[], dest="gate_envelope")
+    p.add_argument("--declared-in", required=True, dest="declared_in")
+    p.add_argument("--artifact-dir", required=True, dest="artifact_dir")
+    p.add_argument("--max-turns", type=int, default=20, dest="max_turns")
+    p.add_argument("--timeout", type=float, default=900.0)
+    p.add_argument("--claude-bin", default="claude", dest="claude_bin")
+    p = loop_sub.add_parser("abort")
+    p.add_argument("--reason", required=True)
+
+    p_turn = sub.add_parser("turn", help="supervised confined production turn")
+    p_turn.add_argument("--project", default=None)
+    turn_sub = p_turn.add_subparsers(dest="turn_command", required=True)
+    p = turn_sub.add_parser("run")
+    p.add_argument("--prompt-file", required=True, dest="prompt_file")
+    p.add_argument("--envelope", action="append", required=True)
+    p.add_argument("--gate-envelope", action="append", default=[],
+                   dest="gate_envelope")
+    p.add_argument("--gate-command", required=True, dest="gate_command")
+    p.add_argument("--declared-in", required=True, dest="declared_in")
+    p.add_argument("--step", required=True)
+    p.add_argument("--artifact-dir", required=True, dest="artifact_dir")
+    p.add_argument("--linkage", required=True)
+    p.add_argument("--timeout", type=float, default=900.0)
+    p.add_argument("--claude-bin", default="claude", dest="claude_bin")
+
     p_gate = sub.add_parser("gate", help="mechanized gate execution")
     p_gate.add_argument("--project", default=None)
     gate_sub = p_gate.add_subparsers(dest="gate_command", required=True)
@@ -160,6 +198,66 @@ def run(args, out=None) -> int:
                               "verdict": result["verdict"],
                               "artifact": result["artifact"]}, out)
             return _emit(result, 0, out)
+        if args.command == "loop":
+            if args.loop_command == "abort":
+                from .conduction.abort import AbortPending, write_abort_request
+                control = service.store.load()
+                activity = control.get("activity")
+                if activity is None:
+                    return _fail("NO_ACTIVITY", {"state": "idle"}, out)
+                token = (activity.get("turn") or {}).get("token")
+                try:
+                    req = write_abort_request(
+                        service.state_dir, activity_id=activity["id"],
+                        activity_epoch=activity["epoch"], turn_token=token,
+                        reason=args.reason)
+                except AbortPending:
+                    return _fail("ABORT_PENDING", {"reason": "an abort is already "
+                                                   "pending"}, out)
+                return _emit({"ok": True, "abort_id": req["id"]}, 0, out)
+            from .conduction.loop import LoopError, run_loop
+            try:
+                result = run_loop(
+                    root, plan_id=args.plan, prompt_template=Path(args.prompt_template),
+                    envelope=args.envelope, gate_envelope=args.gate_envelope,
+                    declared_in=Path(args.declared_in),
+                    artifact_dir=Path(args.artifact_dir), max_turns=args.max_turns,
+                    timeout=args.timeout, claude_bin=args.claude_bin)
+            except LoopError as exc:
+                return _fail(exc.code, exc.detail, out)
+            if not result["ok"]:
+                cond = result["stop_condition"]
+                code = {"HALTED": "LOOP_HALTED", "ABORTED": "LOOP_ABORTED",
+                        "MAX_TURNS": "LOOP_MAX_TURNS", "STOPPED": "LOOP_STOPPED",
+                        }.get(cond, cond if cond in _EXIT_BY_CODE else "LOOP_HALTED")
+                return _fail(code, {"stop_condition": cond, "turns": result["turns"],
+                                    "count": result["count"]}, out)
+            return _emit(result, 0, out)
+        if args.command == "turn":
+            from .conduction.turn import TurnError, run_turn
+            from .conduction.gate import ProvenanceError
+            from .conduction.evidence import EvidenceConflict
+            try:
+                result = run_turn(
+                    root, prompt_file=Path(args.prompt_file),
+                    envelope=args.envelope, gate_envelope=args.gate_envelope,
+                    gate_command=args.gate_command,
+                    declared_in=Path(args.declared_in), step=args.step,
+                    artifact_dir=Path(args.artifact_dir), linkage=args.linkage,
+                    timeout=args.timeout, claude_bin=args.claude_bin)
+            except TurnError as exc:
+                return _fail(exc.code, exc.detail, out)
+            except ProvenanceError as exc:
+                return _fail("PROVENANCE", {"reason": str(exc)}, out)
+            except EvidenceConflict as exc:
+                return _fail("CONFLICT", {"paths": exc.paths}, out)
+            if not result["ok"]:
+                code = ({"TURN_VIOLATION": "TURN_VIOLATION",
+                         "TURN_TAMPERED": "TURN_TAMPERED",
+                         "GATE_RED": "GATE_RED"}.get(result["outcome"], "TURN_FAILED"))
+                return _fail(code, {"outcome": result["outcome"],
+                                    "artifact": result["artifact"]}, out)
+            return _emit(result, 0, out)
         if args.command == "gate":
             from .conduction.gate import ProvenanceError, run_gate
             from .conduction.evidence import EvidenceConflict

regent_cli-0.7.0/src/regent/conduction/abort.py

@@ -0,0 +1,130 @@
+"""Durable abort-request signalling (PLAN-005 STEP-01).
+
+A `regent loop abort` writes an abort-request into the DISPOSABLE XDG state
+(outside the repo), bound to {activity_id, activity_epoch, turn_token} plus the
+in-flight turn nonce. The in-flight turn's keep-alive reads it (~1s), validates
+the binding, and — only if a matching turn is in flight — signals cancellation.
+Honored exactly once (rename to `.claimed`); a request whose binding no longer
+matches is discarded with an audit record. Creation is O_EXCL: one pending
+abort at a time.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from pathlib import Path
+
+from ..protocol.audit import AuditLog, utcnow
+
+
+class AbortPending(Exception):
+    """An abort-request is already pending (O_EXCL)."""
+
+
+def request_path(state_dir: Path) -> Path:
+    return Path(state_dir) / "abort.request"
+
+
+def write_abort_request(state_dir: Path, *, activity_id: str, activity_epoch: int,
+                        turn_token: str | None, reason: str) -> dict:
+    state_dir = Path(state_dir)
+    state_dir.mkdir(parents=True, exist_ok=True)
+    payload = {"id": uuid.uuid4().hex, "activity_id": activity_id,
+               "activity_epoch": activity_epoch, "turn_token": turn_token,
+               "turn_nonce": _turn_in_flight(state_dir),  # bind to the CURRENT turn
+               "reason": reason, "requested_at": utcnow()}
+    path = request_path(state_dir)
+    try:
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError:
+        raise AbortPending(str(path)) from None
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        json.dump(payload, handle)
+    return payload
+
+
+def write_turn_nonce(state_dir: Path, nonce: str) -> None:
+    """Marks a turn in flight (atomic tmp+replace)."""
+    target = Path(state_dir) / "turn.nonce"
+    tmp = target.with_name(".turn.nonce.tmp")
+    tmp.write_text(nonce, encoding="utf-8")
+    os.replace(tmp, target)
+
+
+def clear_turn_nonce(state_dir: Path) -> None:
+    try:
+        (Path(state_dir) / "turn.nonce").unlink()
+    except OSError:
+        pass
+
+
+def _turn_in_flight(state_dir: Path) -> str | None:
+    try:
+        return (Path(state_dir) / "turn.nonce").read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+
+
+def claim_matching_abort(state_dir: Path, audit: AuditLog, *, activity_id: str,
+                         activity_epoch: int, turn_token: str | None) -> dict | None:
+    """Returns and CLAIMS (rename → .claimed) a valid abort-request bound to the
+    current activity while a turn is in flight; discards a stale one (audited);
+    returns None if there is none/not honorable."""
+    path = request_path(state_dir)
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    in_flight = _turn_in_flight(state_dir)
+    bound = (payload.get("activity_id") == activity_id
+             and payload.get("activity_epoch") == activity_epoch
+             and payload.get("turn_token") == turn_token
+             and payload.get("turn_nonce") is not None
+             and payload.get("turn_nonce") == in_flight)  # SAME turn, not just any
+    if not bound:
+        _discard(path, audit, payload, "binding mismatch or wrong/absent turn nonce")
+        return None
+    claimed = path.with_name(f"abort.claimed-{payload['id']}")  # unique, never clobbered
+    try:
+        os.replace(path, claimed)  # single claim
+    except OSError:
+        return None
+    return payload
+
+
+def pending_claimed(state_dir: Path) -> list[Path]:
+    """Unfinished aborts (claimed but not yet reconciled) — for recovery."""
+    return sorted(Path(state_dir).glob("abort.claimed-*"))
+
+
+def clear_claimed(state_dir: Path, *, activity_id: str | None = None,
+                  activity_epoch: int | None = None,
+                  turn_token: str | None = None) -> None:
+    """Removes claimed markers. If a binding is given, ONLY markers matching it
+    (never unrelated aborts)."""
+    import json as _json
+    for p in pending_claimed(state_dir):
+        if activity_id is not None:
+            try:
+                m = _json.loads(p.read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                continue
+            if not (m.get("activity_id") == activity_id
+                    and m.get("activity_epoch") == activity_epoch
+                    and m.get("turn_token") == turn_token):
+                continue  # a different abort — leave it
+        try:
+            p.unlink()
+        except OSError:
+            pass
+
+
+def _discard(path: Path, audit: AuditLog, payload: dict, reason: str) -> None:
+    audit.append({"event": "abort_request_discarded", "request_id": payload.get("id"),
+                  "reason": reason})
+    try:
+        path.unlink()
+    except OSError:
+        pass

regent_cli-0.7.0/src/regent/conduction/confine.py

@@ -0,0 +1,79 @@
+"""Confined-turn composition (PLAN-004 STEP-02).
+
+Builds an immutable per-turn PRIVATE dir (outside the repo) with a generated
+settings.json that wires the Pre/PostToolUse hooks to a private copy of
+hookscript.py, and returns the `claude -p` argv + minimal environment. The
+launch inherits NO config (`--setting-sources ""`), restricts tools, and forces
+acceptEdits (the confinement IS the hook's deny; dontAsk would deny even
+in-envelope writes — empirical IMP-003 lesson).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import shutil
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+ALLOWED_TOOLS = "Read,Write,Edit,MultiEdit"
+ENV_ALLOWLIST = ("PATH", "HOME", "LANG", "LC_ALL")
+
+
+@dataclass
+class ConfinedTurn:
+    private_dir: Path
+    settings_path: Path
+    event_log: Path
+    secret: str
+    envelope: list[str]
+
+    def cleanup(self) -> None:
+        shutil.rmtree(self.private_dir, ignore_errors=True)
+
+
+def compose(*, envelope: list[str], claude_bin: str = "claude") -> ConfinedTurn:
+    private_dir = Path(tempfile.mkdtemp(prefix="regent-turn-"))
+    hook_copy = private_dir / "hookscript.py"
+    shutil.copy(Path(__file__).with_name("hookscript.py"), hook_copy)
+    event_log = private_dir / "events.log"
+    secret = secrets.token_hex(32)
+    envelope = [str(Path(p).resolve()) for p in envelope]
+
+    hook_cmd = f"{_python()} {hook_copy}"
+    settings = {
+        "hooks": {
+            "PreToolUse": [{"hooks": [{"type": "command", "command": hook_cmd}]}],
+            "PostToolUse": [{"hooks": [{"type": "command", "command": hook_cmd}]}],
+        }
+    }
+    settings_path = private_dir / "settings.json"
+    settings_path.write_text(json.dumps(settings, indent=2), encoding="utf-8")
+    # Freeze the composition (read-only) so nothing mutates it mid-turn.
+    for path in (hook_copy, settings_path):
+        path.chmod(0o400)
+    return ConfinedTurn(private_dir, settings_path, event_log, secret, envelope)
+
+
+def launch_argv(turn: ConfinedTurn, *, prompt: str,
+                claude_bin: str = "claude") -> list[str]:
+    return [claude_bin, "-p", prompt,
+            "--setting-sources", "",              # inherit NOTHING
+            "--settings", str(turn.settings_path),
+            "--tools", ALLOWED_TOOLS,
+            "--permission-mode", "acceptEdits"]
+
+
+def launch_env(turn: ConfinedTurn) -> dict[str, str]:
+    env = {k: os.environ[k] for k in ENV_ALLOWLIST if k in os.environ}
+    env["REGENT_TURN_SECRET"] = turn.secret
+    env["REGENT_ENVELOPE"] = json.dumps(turn.envelope)
+    env["REGENT_EVENT_LOG"] = str(turn.event_log)
+    return env
+
+
+def _python() -> str:
+    import sys
+    return sys.executable or "python3"

{regent_cli-0.5.0 → regent_cli-0.7.0}/src/regent/conduction/gate.py

@@ -22,7 +22,7 @@ class ProvenanceError(Exception):
 
 
 def run_gate(root: Path, *, command: str, declared_in: Path, artifact: Path,
-             linkage: str, timeout: float = 1800.0, runner=None) -> dict:
+             linkage: str, timeout: float = 1800.0, runner=None, cancel=None) -> dict:
     root = Path(root)
     if not command.strip():
         raise ProvenanceError("empty gate command is never declared")
@@ -41,7 +41,7 @@ def run_gate(root: Path, *, command: str, declared_in: Path, artifact: Path,
     # ONE cleanup guard around execution + both publishes (see consult.py).
     try:
         result = runner.run(["bash", "-c", command], cwd=str(root),
-                            timeout=timeout)
+                            timeout=timeout, cancel=cancel)
         raw = result.output_bytes
         output_bytes = len(raw)
         truncated = output_bytes > TAIL_LIMIT

regent_cli-0.7.0/src/regent/conduction/hookscript.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Standalone Claude Code hook for confined turns (PLAN-004 STEP-01).
+
+Copied into a per-turn PRIVATE dir and referenced by the generated
+settings.json. Reads REGENT_ENVELOPE (JSON list of allowed write roots),
+REGENT_EVENT_LOG (private append log) and REGENT_TURN_SECRET (HMAC key for the
+audit chain — NOT an anti-forgery proof against the agent; see PLAN-004 trust
+model) from its own environment.
+
+Semantics (official Claude Code hooks):
+- PreToolUse decides allow/deny. Write/Edit/MultiEdit are allowed ONLY if the
+  canonical real-path of the target is inside the envelope; every other
+  write/exec tool (Bash included, defense in depth) is denied; read-only tools
+  are allowed. A `pre` event is appended.
+- PostToolUse (only fires after a successful tool) appends a `post` event with
+  the resulting file's content sha256, correlated by tool_use_id.
+Fails CLOSED: any internal error → deny + `hook_error` event.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import hmac
+import json
+import os
+import sys
+from pathlib import Path
+
+WRITE_TOOLS = {"Write", "Edit", "MultiEdit", "NotebookEdit"}
+READ_ONLY_TOOLS = {"Read", "Glob", "Grep", "NotebookRead", "TodoWrite",
+                   "WebFetch", "WebSearch", "Task"}
+
+
+def _canonical(line: dict) -> str:
+    return json.dumps(line, sort_keys=True, separators=(",", ":"))
+
+
+def _append_event(event: dict) -> None:
+    log_path = os.environ["REGENT_EVENT_LOG"]
+    secret = os.environ["REGENT_TURN_SECRET"].encode()
+    fd = os.open(log_path, os.O_RDWR | os.O_CREAT | os.O_APPEND, 0o600)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX)  # serialize concurrent hooks
+        existing = _read_last_line(log_path)
+        prev_hmac = existing.get("hmac", "") if existing else ""
+        seq = (existing.get("seq", -1) + 1) if existing else 0
+        event["seq"] = seq
+        payload = _canonical(event)
+        event["hmac"] = hmac.new(secret, (payload + prev_hmac).encode(),
+                                 hashlib.sha256).hexdigest()
+        os.write(fd, (json.dumps(event, sort_keys=True) + "\n").encode())
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def _read_last_line(path: str) -> dict | None:
+    try:
+        lines = [l for l in Path(path).read_text(encoding="utf-8").splitlines()
+                 if l.strip()]
+    except OSError:
+        return None
+    return json.loads(lines[-1]) if lines else None
+
+
+def _target_paths(tool_name: str, tool_input: dict) -> list[str]:
+    if tool_name in ("Write", "Edit", "NotebookEdit"):
+        p = tool_input.get("file_path") or tool_input.get("notebook_path")
+        return [p] if p else []
+    if tool_name == "MultiEdit":
+        p = tool_input.get("file_path")
+        return [p] if p else []
+    return []
+
+
+def _inside_envelope(path: str, envelope: list[str]) -> bool:
+    try:
+        real = Path(path).resolve()
+    except (OSError, RuntimeError):
+        return False
+    for root in envelope:
+        try:
+            root_real = Path(root).resolve()
+        except (OSError, RuntimeError):
+            continue
+        if real == root_real or root_real in real.parents:
+            return True
+    return False
+
+
+def _decide(payload: dict) -> dict:
+    tool_name = payload.get("tool_name", "")
+    tool_input = payload.get("tool_input")
+    tool_use_id = payload.get("tool_use_id", "")
+    envelope = json.loads(os.environ.get("REGENT_ENVELOPE", "[]"))
+
+    # Malformed payload → deny (fail closed), even for an allowlisted tool.
+    if not isinstance(tool_input, dict):
+        _append_event({"kind": "pre", "tool": tool_name or "<unknown>",
+                       "tool_use_id": tool_use_id, "paths": [],
+                       "decision": "deny", "reason": "malformed tool_input"})
+        return {"hookSpecificOutput": {"hookEventName": "PreToolUse",
+                                       "permissionDecision": "deny",
+                                       "permissionDecisionReason":
+                                       "malformed tool_input (fail closed)"}}
+
+    if tool_name in WRITE_TOOLS:
+        targets = _target_paths(tool_name, tool_input)
+        allow = bool(targets) and all(_inside_envelope(p, envelope)
+                                      for p in targets)
+        decision = "allow" if allow else "deny"
+        _append_event({"kind": "pre", "tool": tool_name, "tool_use_id": tool_use_id,
+                       "paths": targets, "decision": decision})
+        if allow:
+            return {}  # allow (no explicit permission decision needed)
+        return {"hookSpecificOutput": {"hookEventName": "PreToolUse",
+                                       "permissionDecision": "deny",
+                                       "permissionDecisionReason":
+                                       "outside the turn envelope"}}
+    # Default-deny: only an ALLOWLIST of known read-only tools passes silently.
+    # Anything else — Bash/exec, an unknown/future tool, a malformed payload —
+    # is denied (a write/exec we do not recognize must never slip through).
+    if tool_name in READ_ONLY_TOOLS:
+        return {}
+    _append_event({"kind": "pre", "tool": tool_name or "<unknown>",
+                   "tool_use_id": tool_use_id, "paths": [], "decision": "deny"})
+    return {"hookSpecificOutput": {"hookEventName": "PreToolUse",
+                                   "permissionDecision": "deny",
+                                   "permissionDecisionReason":
+                                   "tool not in the confined-turn allowlist"}}
+
+
+def _post(payload: dict) -> dict:
+    tool_name = payload.get("tool_name", "")
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return {}
+    tool_use_id = payload.get("tool_use_id", "")
+    for path in _target_paths(tool_name, tool_input):
+        try:
+            if os.path.islink(path):
+                digest, mode = None, None  # symlink target: not attributable
+            else:
+                digest = hashlib.sha256(Path(path).read_bytes()).hexdigest()
+                mode = oct(os.lstat(path).st_mode & 0o777)
+        except OSError:
+            digest, mode = None, None
+        _append_event({"kind": "post", "tool": tool_name,
+                       "tool_use_id": tool_use_id, "path": path,
+                       "content_sha256": digest, "mode": mode})
+    return {}
+
+
+def main(argv: list[str], stdin_text: str) -> int:
+    try:
+        payload = json.loads(stdin_text or "{}")
+        event_name = payload.get("hook_event_name") \
+            or (argv[1] if len(argv) > 1 else "")
+        if event_name == "PreToolUse":
+            output = _decide(payload)
+        elif event_name == "PostToolUse":
+            output = _post(payload)
+        else:
+            output = {}
+        if output:
+            sys.stdout.write(json.dumps(output))
+        return 0
+    except Exception as exc:  # noqa: BLE001 — fail CLOSED
+        try:
+            _append_event({"kind": "hook_error", "error": repr(exc)})
+        except Exception:  # noqa: BLE001
+            pass
+        sys.stdout.write(json.dumps({"hookSpecificOutput": {
+            "hookEventName": "PreToolUse", "permissionDecision": "deny",
+            "permissionDecisionReason": "hook internal error (fail closed)"}}))
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv, sys.stdin.read()))