veract 0.3.0__py3-none-any.whl

agent_runtime/__init__.py

@@ -0,0 +1,3 @@
+"""agent-runtime: give your agent a mission, not a prompt."""
+__version__ = "0.3.0"
+from .runtime import Runtime  # noqa: E402,F401

agent_runtime/capabilities.py

@@ -0,0 +1,221 @@
+"""Capability broker: every action is checked against policy and written to an inspectable audit log.
+
+Design rules (each one closes a hole seen in the v0.1 benchmark run):
+* Network reads are http(s) only. ``file://`` and other schemes are denied (no local-file exfil via urlopen).
+* File reads/writes must resolve inside the allowed roots; the runtime's own state (``.agent/``) and ``.git/``
+  are never writable by the agent, so it cannot rewrite its audit log, checkpoints or history.
+* Commands are matched on argv, not on a shell glob: a small set of programs and sub-commands, every
+  path-like argument must stay inside the workspace, ``python -c`` / pytest plugins are refused, and code the
+  agent created during the mission cannot be executed without a human approving it.
+* Every decision — allowed or denied — is appended to the mission's JSONL audit log.
+"""
+import fnmatch
+import ipaddress
+import json
+import os
+import re
+import shlex
+import socket
+import threading
+import time
+from pathlib import Path
+from urllib.parse import urlparse
+
+DEFAULT_POLICY = {
+    "fs_read": ["{workspace}"],
+    "fs_write": ["{workspace}"],
+    "fs_protected": [".agent", ".git"],          # never writable by the agent (relative to workspace)
+    "net_domains": ["*"],
+    "block_private_net": True,
+    "private_allow": [],                           # hosts exempt from the private-net block (e.g. self-hosted SearXNG)
+    "mcp_allow": [],                               # "server.tool" patterns callable without approval
+    "exec_allow": [],                              # extra user globs; still subject to the argv/path rules
+    "exec_new_code": "approve",                    # approve|deny|allow: running code the agent itself created
+}
+
+# program -> allowed first arguments (None = any args, still path-checked)
+EXEC_RULES = {
+    "python": {"-m": {"pytest", "unittest"}},
+    "python3": {"-m": {"pytest", "unittest"}},
+    "py": {"-m": {"pytest", "unittest"}},
+    "pytest": None,
+    "git": {"status", "diff", "log", "show"},
+    "ls": None,
+    "dir": None,
+}
+BANNED_ARGS = {"-c", "--rootdir", "-p", "--pyargs", "--confcutdir", "--import-mode", "-o", "--override-ini"}
+NET_SCHEMES = ("http", "https")
+
+
+def plausible_test_command(cmd):
+    """Static pre-check (no workspace needed): python -m pytest|unittest or pytest, no banned/absolute args."""
+    try:
+        argv = shlex.split(cmd)
+    except ValueError:
+        return False
+    if not argv:
+        return False
+    prog = Path(argv[0]).name.lower().removesuffix(".exe")
+    if prog in ("python", "python3", "py"):
+        if argv[1:3] not in (["-m", "pytest"], ["-m", "unittest"]):
+            return False
+    elif prog != "pytest":
+        return False
+    return not any(a.split("=", 1)[0] in BANNED_ARGS or re.match(r"^(?:[A-Za-z]:[\\/]|[\\/]|~|\.\.)", a.split("=", 1)[-1])
+                   for a in argv[1:])
+
+
+class PermissionDenied(Exception):
+    pass
+
+
+def _is_pathlike(tok):
+    return bool(re.match(r"^(?:[A-Za-z]:[\\/]|[\\/]|~|\.\.(?:[\\/]|$))", tok)) or "/" in tok or "\\" in tok
+
+
+class CapabilityBroker:
+    def __init__(self, workspace, audit_path, policy=None, approver=None):
+        self.workspace = Path(workspace).resolve()
+        self.audit_path = Path(audit_path)
+        self.audit_path.parent.mkdir(parents=True, exist_ok=True)
+        p = dict(DEFAULT_POLICY)
+        p.update(policy or {})
+        self.policy = p
+        self.approver = approver      # callable(request_dict) -> bool, for interactive approval
+        self.grants = []              # (action, pattern, expires)
+        self.created = set()          # files the agent created during this mission (resolved paths)
+        self._lock = threading.Lock()
+
+    def grant(self, action, pattern, ttl=3600):
+        self.grants.append((action, pattern, time.time() + ttl))
+
+    def _roots(self, key):
+        return [Path(r.replace("{workspace}", str(self.workspace))).expanduser().resolve() for r in self.policy[key]]
+
+    def path(self, target):
+        t = str(target)
+        if os.name != "nt":
+            if re.match(r"^[A-Za-z]:[\\/]", t):          # a Windows drive path is never inside a POSIX workspace
+                return Path("/__windows_drive__") / t[0]
+            t = t.replace("\\", "/")                    # "..\\secret" must not become a harmless filename
+        p = Path(t).expanduser()
+        return (p if p.is_absolute() else self.workspace / p).resolve()
+
+    def inside(self, target, key="fs_read"):
+        try:
+            rp = self.path(target)
+        except (OSError, ValueError):
+            return False
+        return any(rp.is_relative_to(r) for r in self._roots(key))
+
+    def _protected(self, rp):
+        return any(rp.is_relative_to((self.workspace / d).resolve()) for d in self.policy["fs_protected"])
+
+    # ------------------------------------------------------------------ exec
+    def _eval_exec(self, cmd):
+        try:
+            argv = shlex.split(cmd, posix=os.name != "nt")
+        except ValueError as e:
+            return False, f"unparseable command: {e}"
+        if not argv:
+            return False, "empty command"
+        prog = Path(argv[0]).name.lower()
+        prog = prog[:-4] if prog.endswith(".exe") else prog
+        user_ok = any(fnmatch.fnmatch(cmd, pat) for pat in self.policy["exec_allow"])
+        if prog not in EXEC_RULES and not user_ok:
+            return False, f"program '{prog}' not allow-listed"
+        rule = EXEC_RULES.get(prog)
+        args = argv[1:]
+        if isinstance(rule, dict):                                  # python -m pytest|unittest
+            if len(args) < 2 or args[0] not in rule or args[1] not in rule[args[0]]:
+                if not user_ok:
+                    return False, f"only '{prog} -m pytest|unittest' allowed"
+        elif isinstance(rule, set):                                 # git sub-commands
+            if not args or args[0] not in rule:
+                if not user_ok:
+                    return False, f"'{prog} {args[0] if args else ''}' not allowed"
+        for a in args:
+            key = a.split("=", 1)[0]
+            if key in BANNED_ARGS:
+                return False, f"argument '{key}' not allowed"
+            if _is_pathlike(a) and not self.inside(a.split("=", 1)[-1] if "=" in a else a):
+                return False, f"argument '{a}' points outside the workspace"
+        new_code = sorted(str(p.relative_to(self.workspace)) for p in self.created
+                          if p.suffix in (".py", ".pyc", ".pth", ".so", ".dll") and p.exists())
+        if new_code:
+            mode = self.policy["exec_new_code"]
+            if mode == "deny":
+                return False, f"workspace contains code created by the agent: {new_code}"
+            if mode == "approve":
+                return False, f"needs approval: would execute code created by the agent: {new_code}"
+        return True, "command allowed (argv rules)"
+
+    # ------------------------------------------------------------------ evaluate
+    def _evaluate(self, action, target):
+        for a, pat, exp in self.grants:
+            if a == action and exp > time.time() and fnmatch.fnmatch(target, pat):
+                return True, "temporary grant", exp
+        if action == "read" and "://" in str(target):
+            u = urlparse(target)
+            if u.scheme.lower() not in NET_SCHEMES:
+                return False, f"scheme '{u.scheme}' not allowed (http/https only)", None
+            host = u.hostname or ""
+            if not host:
+                return False, "url without host", None
+            if not any(fnmatch.fnmatch(host, d) for d in self.policy["net_domains"]):
+                return False, f"domain {host} not allowed", None
+            if self.policy["block_private_net"] and host not in self.policy.get("private_allow", []):
+                try:
+                    for info in socket.getaddrinfo(host, None):
+                        ip = ipaddress.ip_address(info[4][0])
+                        if ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved:
+                            return False, "private/loopback address blocked", None
+                except socket.gaierror:
+                    pass
+            return True, "domain allowed", None
+        if action in ("read", "write"):
+            if "://" in str(target):
+                return False, "urls cannot be written", None
+            try:
+                rp = self.path(target)
+            except (OSError, ValueError) as e:
+                return False, f"bad path: {e}", None
+            ok = any(rp.is_relative_to(r) for r in self._roots("fs_read" if action == "read" else "fs_write"))
+            if not ok:
+                return False, "path outside allowed roots", None
+            if action == "write" and self._protected(rp):
+                return False, "runtime state (.agent/.git) is not writable by the agent", None
+            return True, "inside allowed roots", None
+        if action == "execute":
+            ok, why = self._eval_exec(target)
+            return ok, why, None
+        if action == "mcp":
+            if any(fnmatch.fnmatch(target, p) for p in self.policy.get("mcp_allow", [])):
+                return True, "mcp tool allow-listed", None
+            return False, "needs approval: mcp tool not in mcp_allow", None
+        return False, "unknown action", None
+
+    def check(self, action, target):
+        """Dry-run evaluation (no audit, no approval prompt)."""
+        return self._evaluate(action, target)[:2]
+
+    def note_created(self, target):
+        rp = self.path(target)
+        self.created.add(rp)
+
+    def require(self, who, mission, step, tool, action, target, why=""):
+        ok, reason, exp = self._evaluate(action, target)
+        if not ok and self.approver and not reason.startswith(("scheme", "runtime state")):
+            req = dict(who=who, tool=tool, action=action, target=target, why=why, reason=reason)
+            if self.approver(req):
+                ok, reason = True, "approved interactively"
+        self.audit(who, mission, step, tool, action, target, why, ok, reason, exp)
+        if not ok:
+            raise PermissionDenied(f"{action} {target!r} denied: {reason}")
+        return {"allowed": ok, "reason": reason}
+
+    def audit(self, who, mission, step, tool, action, target, why, allowed, reason, exp=None):
+        rec = {"ts": time.time(), "mission": mission, "step": step, "who": who, "tool": tool, "action": action,
+               "target": target, "why": why, "allowed": allowed, "reason": reason, "expires": exp}
+        with self._lock, open(self.audit_path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(rec) + "\n")

agent_runtime/checkpoint.py

@@ -0,0 +1,34 @@
+import json
+import os
+import time
+import uuid
+from pathlib import Path
+from .models import RunState
+
+
+class CheckpointStore:
+    def __init__(self, root):
+        self.root = Path(root)
+
+    def dir(self, mission_id):
+        d = self.root / mission_id
+        d.mkdir(parents=True, exist_ok=True)
+        return d
+
+    def save(self, state: RunState):
+        d = self.dir(state.mission.id)
+        tmp = d / f"state.json.{uuid.uuid4().hex[:6]}.tmp"
+        tmp.write_text(json.dumps(state.to_dict(), indent=1, default=str), encoding="utf-8")
+        for attempt in range(8):                    # atomic; retried because Windows AV/indexers briefly lock files
+            try:
+                os.replace(tmp, d / "state.json")
+                return
+            except PermissionError:
+                time.sleep(0.05 * 2 ** attempt)
+        os.replace(tmp, d / "state.json")
+
+    def load(self, mission_id) -> RunState:
+        return RunState.from_dict(json.loads((self.root / mission_id / "state.json").read_text(encoding="utf-8")))
+
+    def list(self):
+        return sorted(p.parent.name for p in self.root.glob("*/state.json")) if self.root.exists() else []

agent_runtime/cli.py

@@ -0,0 +1,132 @@
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from .runtime import Runtime
+from .scaffold import create_tool, publish_tool
+from .tools import trust_plugin
+from . import config as cfg
+
+
+def _rt(a, interactive=False):
+    _, rt = cfg.load(a.workspace)
+    yes = getattr(a, "yes", False)
+    if yes:
+        print("  ! --yes: every action the policy denies will be approved automatically", file=sys.stderr)
+    appr = cfg.make_approver(rt["approve"], interactive=interactive and sys.stdin.isatty(), yes=yes)
+    return Runtime(a.workspace, approver=appr, max_replans=getattr(a, "max_replans", 2),
+                   deadline=getattr(a, "deadline", None), on_event=lambda m: print("  ·", m))
+
+
+EXIT = {"passed": 0, "failed": 1, "partial": 1, "unverified": 1, "refused": 3}   # scriptable in CI
+
+
+def _show_mission(state, store):
+    m = state.mission
+    print(f"mission {m.id}  [{state.status}]  kind={m.kind}  replans={state.replans}")
+    print(f"  text: {m.text}")
+    print("  contract:")
+    res = {r["id"]: r for r in (state.report or {}).get("results", [])}
+    for c in m.criteria:
+        r = res.get(c.id)
+        mark = "·" if r is None else ("✓" if r["passed"] else "✗")
+        print(f"    [{mark}] {c.id:6} {c.check:16} {c.description}" + (f"  — {r['detail'][:90]}" if r else ""))
+    print("  plan:")
+    for s in state.plan.steps:
+        ev = state.evidence.get(s.id, {})
+        print(f"    {s.id:10} {s.tool:18} {s.status:10} items={len(ev.get('items', []))}"
+              + (f"  error: {s.error[:80]}" if s.error else ""))
+    print("  log:")
+    for e in state.log[-12:]:
+        print(f"    - {e['msg'][:140]}")
+    art = store.dir(m.id) / "artifact.json"
+    if art.exists():
+        import json as _j
+        st = _j.loads(art.read_text(encoding="utf-8")).get("stats", {})
+        print(f"  stats: {st}")
+
+
+def _show(state):
+    print(f"\nmission {state.mission.id}: {state.status.upper()}  (replans: {state.replans})")
+    for r in (state.report or {}).get("results", []):
+        print(f"  [{'✓' if r['passed'] else '✗'}] {r['description']} — {r['detail']}")
+    if state.status != "passed" and state.log:
+        print("  reason:", state.log[-1]["msg"])
+    if state.status in ("partial", "unverified"):
+        print("  note: NOT a pass — only verified evidence was written")
+    print(f"  artifact: .agent/missions/{state.mission.id}/artifact.json")
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="agent", description="Give your agent a mission, not a prompt.")
+    p.add_argument("--workspace", default=".")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("run"); r.add_argument("mission"); r.add_argument("--yes", action="store_true", help="auto-approve ungranted actions"); r.add_argument("--max-replans", type=int, default=2)
+    r.add_argument("--deadline", type=float, default=None, help="wall-clock budget in seconds; on expiry an honest partial result is written")
+    s = sub.add_parser("resume"); s.add_argument("id"); s.add_argument("--yes", action="store_true"); s.add_argument("--deadline", type=float, default=None)
+    po = sub.add_parser("policy", help="show the effective policy (or --init to write .agent/policy.json)")
+    po.add_argument("--init", action="store_true")
+    sh = sub.add_parser("show", help="contract, plan, evidence and log of one mission"); sh.add_argument("id")
+    tr = sub.add_parser("trust", help="allow a plugin in ./tools/<name> to load (pins its tool.py hash)"); tr.add_argument("name")
+    st = sub.add_parser("status"); st.add_argument("id", nargs="?")
+    au = sub.add_parser("audit"); au.add_argument("id")
+    me = sub.add_parser("memory"); me.add_argument("query", nargs="?", default="")
+    cr = sub.add_parser("create"); cr.add_argument("what", choices=["tool"]); cr.add_argument("name")
+    sub.add_parser("test")
+    pu = sub.add_parser("publish"); pu.add_argument("name")
+    a = p.parse_args(argv)
+    try:
+        if not (a.cmd == "policy" and a.init):
+            cfg.load(a.workspace)                   # a broken policy.json is reported by every command
+        return _dispatch(a)
+    except cfg.ConfigError as e:
+        print(f"config error: {e}", file=sys.stderr)
+        return 2
+    except BrokenPipeError:                 # `agent show <id> | head` — exit quietly
+        import os
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return 0
+
+
+def _dispatch(a):
+
+    if a.cmd in ("run", "resume"):
+        rt = _rt(a, True)
+        st = rt.start(a.mission) if a.cmd == "run" else rt.resume(a.id)
+        _show(st)
+        return EXIT.get(st.status, 1)
+    elif a.cmd == "status":
+        rt = Runtime(a.workspace, llm=None, judge=None, tools={}, config={})
+        for mid in ([a.id] if a.id else rt.store.list()):
+            s = rt.store.load(mid)
+            print(f"{mid}  {s.status:10} {s.mission.text[:70]}")
+    elif a.cmd == "audit":
+        for line in (Path(a.workspace) / ".agent/missions" / a.id / "audit.jsonl").read_text().splitlines():
+            e = json.loads(line)
+            print(f"{'ALLOW' if e['allowed'] else 'DENY '} {e['who']:8} {e['tool']:16} {e['action']:8} {e['target'][:60]}  ← {e['why']} ({e['reason']})")
+    elif a.cmd == "memory":
+        for m in Runtime(a.workspace, llm=None, judge=None, tools={}, config={}).memory.recall(a.query):
+            print(f"[{m['kind']}/{m['status']} c={m['confidence']}] {m['content']}  (src: {m['provenance']})")
+    elif a.cmd == "policy":
+        if a.init:
+            print("wrote", cfg.init(a.workspace))
+        else:
+            print(json.dumps(cfg.effective(a.workspace), indent=2))
+    elif a.cmd == "show":
+        rt = Runtime(a.workspace, llm=None, judge=None, tools={}, config={})
+        _show_mission(rt.store.load(a.id), rt.store)
+    elif a.cmd == "trust":
+        name, h = trust_plugin(a.workspace, a.name)
+        print(f"trusted {name} (sha256 {h[:12]}…) — re-run trust after editing its tool.py")
+    elif a.cmd == "create":
+        print("created", create_tool(a.name, Path(a.workspace) / "tools"))
+    elif a.cmd == "test":
+        sys.exit(max((subprocess.call([sys.executable, "-m", "unittest", "discover", "-s", "tests"], cwd=d)
+                      for d in (Path(a.workspace) / "tools").glob("*/")), default=0))
+    elif a.cmd == "publish":
+        print("packed", publish_tool(a.name, Path(a.workspace) / "tools", Path(a.workspace) / "dist"))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_runtime/compiler.py

@@ -0,0 +1,82 @@
+"""Mission compiler: free text -> objective + constraints + machine-checkable success criteria."""
+import json
+import re
+from .llm import extract_json
+from .models import Mission, Criterion, CHECKS
+from . import contract
+
+RESEARCH = ("find", "research", "list", "compare", "investigate", "who ", "which ", "companies", "sources")
+CODING = ("implement", "fix", "refactor", "bug", "function", "write code", "unit test", "repo")
+SYSTEM = ("You compile a user's mission into JSON: {\"objective\": str, \"kind\": \"research|coding|general\", "
+          "\"constraints\": {}, \"criteria\": [{\"id\": str, \"description\": str, \"check\": one of "
+          "min_items|unique_items|all_sourced|file_exists|command_ok|contains|llm, \"params\": {}}]}. "
+          "params: min_items {n}, file_exists {path}, command_ok {command}, contains {path,text}, llm {question}. "
+          "Criteria must be objectively verifiable. Reply with JSON only.")
+
+
+def _heuristic(text, mid):
+    low = text.lower()
+    kind = "coding" if any(k in low for k in CODING) else "research" if any(k in low for k in RESEARCH) else "general"
+    crit, cid = [], iter(range(1, 99))
+    n = re.search(r"\b(\d{1,5})\s+(?:\w+\s+){0,2}?[a-z]{3,}", text)
+    if kind == "research":
+        crit.append(Criterion(f"c{next(cid)}", f"at least {n.group(1) if n else 1} item(s)", "min_items", {"n": int(n.group(1)) if n else 1}))
+        crit.append(Criterion(f"c{next(cid)}", "no duplicate items", "unique_items"))
+        crit.append(Criterion(f"c{next(cid)}", "every item cites a source that was actually retrieved", "all_sourced"))
+    f = re.search(r"(?:to|into|as|in)\s+([\w./-]+\.(?:md|txt|json|csv|py|html))\b", text)
+    if f:
+        crit.append(Criterion(f"c{next(cid)}", f"file {f.group(1)} exists", "file_exists", {"path": f.group(1)}))
+    if kind == "coding" and "test" in low:
+        crit.append(Criterion(f"c{next(cid)}", "test suite passes", "command_ok", {"command": "python -m pytest -q"}))
+    return Mission(mid, text, text.strip().rstrip("."), kind, {}, crit)
+
+
+def valid_criteria(crits):
+    """Reject criteria that can never be satisfied (a URL is not a file path) and drop duplicates."""
+    seen, out = set(), []
+    for c in crits:
+        p = c.params or {}
+        if c.check in ("file_exists", "contains"):
+            path = str(p.get("path", ""))
+            if not path or "://" in path or path.startswith("mailto:"):
+                continue
+        elif c.check == "min_items":
+            try:
+                if int(p.get("n", 0)) <= 0:
+                    continue
+            except (TypeError, ValueError):
+                continue
+        elif c.check == "command_ok" and not str(p.get("command", "")).strip():
+            continue
+        elif c.check == "llm" and not str(p.get("question", "")).strip() and not c.description:
+            continue
+        key = (c.check, json.dumps(p, sort_keys=True, default=str))
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(c)
+    return out
+
+
+def compile_mission(text, llm=None, memory_hints="", workspace=None):
+    """LLM (or rules) proposes criteria; the contract floor then guarantees the minimum the text demands."""
+    mid = Mission.new_id()
+    base = None
+    if llm:
+        try:
+            d = extract_json(llm.complete(SYSTEM, f"Mission: {text}\n{memory_hints}"))
+            crit = valid_criteria([Criterion(str(c["id"]), str(c.get("description", c["check"])), c["check"],
+                                             c.get("params") or {})
+                                   for c in d["criteria"] if isinstance(c, dict) and c.get("check") in CHECKS])
+            base = Mission(mid, text, str(d.get("objective") or text), str(d.get("kind") or "general"),
+                           d.get("constraints") if isinstance(d.get("constraints"), dict) else {}, crit)
+        except Exception:
+            base = None  # fall back to rules
+    if base is None:
+        base = _heuristic(text, mid)
+    kind, fl = contract.floor(text, workspace, base.kind)
+    base.kind = kind if kind != "general" else base.kind
+    base.criteria = contract.merge(base.criteria, fl)
+    base.constraints = dict(base.constraints or {})
+    base.constraints["verifiable"] = contract.verifiable(base.criteria)
+    return base

agent_runtime/config.py

@@ -0,0 +1,105 @@
+"""User configuration: `.agent/policy.json` in the workspace (the agent itself can never write `.agent/`).
+
+{
+  "net_domains": ["*"],                 # broker keys (see capabilities.DEFAULT_POLICY)
+  "exec_new_code": "approve",
+  "approve": [{"action": "execute", "pattern": "python -m pytest*"}],   # auto-approved when policy denies
+  "search": {"provider": "duckduckgo"},  # duckduckgo | searxng {url} | brave {api_key_env}
+  "sandbox": {"mode": "limits", "cpu_seconds": 120, "memory_mb": 1024},   # none | limits | docker {image}
+  "mcp": {"files": {"command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."]}}
+}
+"""
+import fnmatch
+import json
+import sys
+from pathlib import Path
+from .capabilities import DEFAULT_POLICY
+
+SCHEMA = 2
+RUNTIME_KEYS = {"approve", "search", "sandbox", "mcp"}
+DEFAULTS = {
+    "approve": [],
+    "search": {"provider": "duckduckgo"},
+    "sandbox": {"mode": "limits", "cpu_seconds": 300, "memory_mb": 2048, "image": "python:3.12-slim"},
+    "mcp": {},
+}
+
+
+class ConfigError(ValueError):
+    pass
+
+
+def policy_path(workspace):
+    return Path(workspace) / ".agent" / "policy.json"
+
+
+def load(workspace):
+    """Return (broker_policy, runtime_config). Unknown keys are an error, not silently ignored."""
+    f = policy_path(workspace)
+    raw = {}
+    if f.exists():
+        try:
+            raw = json.loads(f.read_text(encoding="utf-8"))
+        except ValueError as e:
+            raise ConfigError(f"{f}: invalid JSON ({e})") from e
+        if not isinstance(raw, dict):
+            raise ConfigError(f"{f}: must be a JSON object")
+    unknown = set(raw) - set(DEFAULT_POLICY) - RUNTIME_KEYS
+    if unknown:
+        raise ConfigError(f"{f}: unknown key(s) {sorted(unknown)}; allowed: {sorted(set(DEFAULT_POLICY) | RUNTIME_KEYS)}")
+    broker = {k: v for k, v in raw.items() if k in DEFAULT_POLICY}
+    rt = {k: (dict(DEFAULTS[k], **raw[k]) if isinstance(DEFAULTS[k], dict) and isinstance(raw.get(k), dict)
+              else raw.get(k, DEFAULTS[k])) for k in RUNTIME_KEYS}
+    if rt["sandbox"].get("mode") not in ("none", "limits", "docker"):
+        raise ConfigError("sandbox.mode must be none | limits | docker")
+    if rt["search"].get("provider") not in ("duckduckgo", "searxng", "brave"):
+        raise ConfigError("search.provider must be duckduckgo | searxng | brave")
+    for rule in rt["approve"]:
+        if not isinstance(rule, dict) or not {"action", "pattern"} <= set(rule):
+            raise ConfigError("approve rules look like {\"action\": \"execute\", \"pattern\": \"python -m pytest*\"}")
+    return broker, rt
+
+
+def effective(workspace):
+    broker, rt = load(workspace)
+    out = dict(DEFAULT_POLICY)
+    out.update(broker)
+    out.update(rt)
+    return out
+
+
+def init(workspace):
+    f = policy_path(workspace)
+    if f.exists():
+        raise ConfigError(f"{f} already exists")
+    f.parent.mkdir(parents=True, exist_ok=True)
+    body = {k: v for k, v in DEFAULT_POLICY.items()}
+    body.update({k: v for k, v in DEFAULTS.items()})
+    f.write_text(json.dumps(body, indent=2), encoding="utf-8")
+    return f
+
+
+def make_approver(rules=(), interactive=False, yes=False, ask=None, out=sys.stderr):
+    """Approval chain: --yes > policy rules > interactive prompt (y / N / a = always this session) > deny."""
+    session = []
+
+    def approve(req):
+        target, action = str(req.get("target", "")), req.get("action")
+        if yes:
+            return True
+        for r in list(rules) + session:
+            if r["action"] == action and fnmatch.fnmatch(target, r["pattern"]):
+                return True
+        if not interactive:
+            return False
+        prompt = (f"\n[approval needed] {req.get('tool')} wants to {action} {target!r}\n"
+                  f"  why: {req.get('why') or '-'}\n  policy said: {req.get('reason', '-')}\n  allow? [y]es / [N]o / [a]lways this session: ")
+        try:
+            ans = (ask or input)(prompt).strip().lower()
+        except EOFError:
+            return False
+        if ans == "a":
+            session.append({"action": action, "pattern": target})
+            return True
+        return ans in ("y", "yes")
+    return approve