@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/sandbox.py

@@ -0,0 +1,856 @@
+"""Sandbox — audit hook + permission enforcement for the xactor Python shell.
+
+Uses sys.addaudithook() (PEP 578) to intercept all security-sensitive
+operations at the C level. Once installed, hooks CANNOT be removed by
+executing code.
+
+Two nested scopes decide how strictly an operation is judged:
+
+* **user-code scope** — the agent's own code, running inside the exec
+  wrapper. Direct OS access is denied outright here: files, processes,
+  sockets and imports must go through ``api.*``.
+* **api scope** — the body of a ``StdlibAPI`` method, entered from inside
+  user code. Denials relax back to the path/subprocess/network rules, since
+  the API is the sanctioned way to touch the outside world.
+
+Both are ContextVars, so concurrent execs (each its own asyncio task) and
+the bridge's own I/O never see each other's scope.
+
+Permission config is set at startup from TypeScript and can be updated
+via bridge messages at runtime.
+"""
+
+import contextlib
+import contextvars
+import fnmatch
+import os
+import sys
+from pathlib import Path
+from typing import Any, Iterator
+
+# Imported at load rather than inside the hook: an import raised from inside an
+# audit hook is the kind of thing that fails in ways nobody sees. `seals`
+# imports nothing from this package, so there is no cycle.
+from . import seals as _seals
+
+# ── Permission state (set by TypeScript before any user code runs) ─────
+
+_config = {
+    # Working directory — all relative paths resolve against this
+    "cwd": os.getcwd(),
+
+    # Allowed path prefixes for read access (absolute paths)
+    "read_allow": [],    # type: list[str]
+
+    # Allowed path prefixes for write access (absolute paths)
+    "write_allow": [],   # type: list[str]
+
+    # Whether subprocess execution is allowed
+    "allow_subprocess": False,
+
+    # Whether network access is allowed
+    "allow_network": False,
+
+    # Permission mode: "strict", "permissive", "open"
+    "mode": "permissive",
+
+    # Blocked modules (always blocked regardless of mode)
+    "blocked_modules": {"ctypes", "ctypes.util", "_ctypes"},
+
+    # A drive-channel task's folder, or None. When set the mode is strict and
+    # `cwd` is this folder; see `fence_allows`. '' is a fence whose folder the
+    # host could not name, and admits nothing.
+    "fence": None,  # type: str | None
+}
+
+
+class FenceDenied(PermissionError):
+    """A path outside a drive-channel task's folder, refused so it can be asked.
+
+    Its own class so the api wrapper can tell "outside the folder, ask the user"
+    from every other refusal, which it must not turn into a card.
+    """
+
+    def __init__(self, path: str, write: bool, message: str) -> None:
+        super().__init__(message)
+        self.path = path
+        self.write = write
+
+# Track whether the hook has been installed (one-shot)
+_installed = False
+
+# Scratch space, pre-cached to avoid re-entrant audit calls from path
+# resolution.
+#
+# `gettempdir()` alone is not enough and the gap is invisible from the code: on
+# macOS it answers with the per-user `/private/var/folders/…/T`, so `/tmp` —
+# which is what an agent writes when it wants a scratch file, and what every
+# tool it shells out to expects — was refused. Twice reported, both times worked
+# around by putting scratch files inside the user's repository instead, which is
+# the outcome the allowance exists to prevent.
+#
+# Both, then, and each resolved: on macOS `/tmp` is a symlink to `/private/tmp`
+# and the audit hook sees the resolved path.
+import tempfile as _tempfile
+
+
+def _resolved(path: str) -> str | None:
+    try:
+        return str(Path(path).resolve())
+    except (OSError, ValueError):
+        return None
+
+
+_TMP_DIRS: list[str] = []
+for _candidate in (_tempfile.gettempdir(), "/tmp", os.environ.get("TMPDIR", "")):
+    if not _candidate:
+        continue
+    _r = _resolved(_candidate)
+    if _r and _r not in _TMP_DIRS:
+        _TMP_DIRS.append(_r)
+# What Git Bash mounts at `/tmp` on Windows — see `native_path`.
+_USER_TEMP = _tempfile.gettempdir()
+del _tempfile
+
+# Python's own directories — always allowed for reads (stdlib, site-packages)
+_python_prefixes: list[str] = []
+for _p in sys.path:
+    if _p:
+        try:
+            _python_prefixes.append(str(Path(_p).resolve()))
+        except (OSError, ValueError):
+            pass
+# Also allow the Python executable's directory
+try:
+    _python_prefixes.append(str(Path(sys.executable).parent.resolve()))
+except (OSError, ValueError):
+    pass
+
+# Re-entrancy guard — the hook must not trigger itself
+_in_hook = False
+
+# ── Execution scopes ───────────────────────────────────────────────────
+
+# Depth of agent-authored code on the stack (set by the exec wrapper).
+_user_depth: contextvars.ContextVar[int] = contextvars.ContextVar("user_depth", default=0)
+
+# Depth of StdlibAPI method bodies on the stack (set by the @api_method
+# decorator). Non-zero means the operation was requested through the API.
+_api_depth: contextvars.ContextVar[int] = contextvars.ContextVar("api_depth", default=0)
+
+# Audit-event prefixes that constitute "direct OS access" — denied whenever
+# agent code performs them itself instead of calling api.*.
+_OS_EVENT_PREFIXES = (
+    "os.", "shutil.", "subprocess.", "socket.", "pty.", "fcntl.",
+    "msvcrt.", "winreg.", "ctypes.", "glob.", "webbrowser.", "tempfile.",
+)
+
+_USE_API = (
+    "Use the api.* methods instead — the shell exposes file, shell, search "
+    "and session operations through `api` (see the tool description)."
+)
+
+# Attributes of `os` that read or write the process environment. The audit
+# hook cannot cover these: `os.environ` is an ordinary mapping and `os.getenv`
+# an ordinary lookup, so CPython raises **no audit event** for either. Every
+# other route into the OS announces itself and is denied above; this one is
+# silent, which is exactly why it needs naming here.
+_ENV_ATTRS = frozenset({
+    "environ", "environb", "getenv", "getenvb", "putenv", "unsetenv",
+})
+
+
+class _GuardedOS:
+    """`os` as agent code sees it: everything except the environment.
+
+    `os` is bound into the exec scope so agent code can do path and data
+    manipulation — `os.path.join`, `os.sep`, `os.pathsep` — which is worth
+    keeping. What came with it was the whole process environment, readable by
+    anything the agent cared to write, in every permission mode. That is the
+    one hole in the sandbox's stated contract that the outside world is
+    reached through `api.*`.
+
+    Three things this deliberately does not touch, because each would be a
+    regression rather than a fix:
+
+    - **The real `os` module is untouched.** `StdlibAPI` imports it normally
+      and keeps reading PATH to resolve a shell. This proxy exists only in the
+      namespace agent code runs in.
+    - **`api.bash` subprocesses still inherit the real environment**, so a
+      build that needs registry or git credentials still works. Scrubbing the
+      daemon's environment at spawn would have taken that away, which is why
+      the guard is here and not there.
+    - **It restores the point of `api.extract_secret`**, whose contract is to
+      read a value into an env var *without it passing through this layer*.
+      Agent code that could read the variable back defeated that entirely.
+
+    **The honest limit**, so nobody reads more into this than it claims: this
+    closes the direct route, not every escape. Python's object graph can
+    generally be walked back to a module, and nothing here pretends otherwise.
+    It makes the contract true for the obvious path — the same standard the
+    `open()` denial meets — rather than being a containment boundary against
+    a determined attempt.
+    """
+
+    __slots__ = ()
+
+    def __getattr__(self, name: str) -> Any:
+        if name in _ENV_ATTRS:
+            raise PermissionError(
+                f"Sandbox: os.{name} is not available to shell code — the "
+                "process environment is not readable from here. To use a "
+                "secret in a command, api.bash() inherits the real "
+                "environment, and api.extract_secret() puts a value there "
+                "without it passing through this layer."
+            )
+        return getattr(os, name)
+
+    def __dir__(self) -> list[str]:
+        # Honest about what is missing, so `dir(os)` does not advertise an
+        # attribute that raises. The difflib "did you mean" hints elsewhere in
+        # the shell read this kind of listing.
+        return [n for n in dir(os) if n not in _ENV_ATTRS]
+
+    def __repr__(self) -> str:
+        return "<module 'os' (sandboxed: no environment access)>"
+
+
+def guarded_os() -> _GuardedOS:
+    """The `os` to bind into the agent's exec scope. See `_GuardedOS`."""
+    return _GuardedOS()
+
+
+class _GuardedTime:
+    """`time` as agent code sees it: every clock, but no blocking sleep.
+
+    `time.sleep` would stop the daemon's event loop, and with it every other
+    exec in flight — a delegate shares its parent's shell — and the reads that
+    deliver api results. Agents reached for it to wait on something, and the
+    only route they found was `api.bash('powershell -c "Start-Sleep 5"')`, 54
+    times: a third interpreter to do what `await asyncio.sleep` does in place.
+    """
+
+    __slots__ = ()
+
+    def __getattr__(self, name: str) -> Any:
+        if name == "sleep":
+            raise PermissionError(
+                "Sandbox: time.sleep() would freeze the whole shell, including "
+                "other calls in flight. Write `await asyncio.sleep(seconds)`."
+            )
+        import time
+        return getattr(time, name)
+
+    def __dir__(self) -> list[str]:
+        import time
+        return [n for n in dir(time) if n != "sleep"]
+
+    def __repr__(self) -> str:
+        return "<module 'time' (sandboxed: use await asyncio.sleep)>"
+
+
+# ── Imports from agent code ────────────────────────────────────────────
+#
+# `import json` used to be refused outright — while `json` was already bound in
+# the very scope the import ran in. 111 refused calls in the transcripts, most
+# of them for modules the shell already had (json 34, os 28, asyncio 10), and a
+# refused import kills every line of the call, used or not.
+#
+# Worse than the cost was where it sent people: with no `re`, no `base64` and no
+# way to decode a screenshot, agents moved the work into
+# `api.bash("python -c ...")` — a second, *unsandboxed* interpreter reached
+# through two more quoting layers. The refusal made the sandbox weaker and the
+# scripts more fragile at once.
+#
+# So pure computation imports normally. Nothing here can reach the outside world
+# by itself: any file, process or socket a module could open still raises the
+# audit event the hook denies from user code.
+
+IMPORTABLE_MODULES = frozenset({
+    "abc", "ast", "base64", "binascii", "bisect", "calendar", "cmath",
+    "collections", "collections.abc", "contextlib", "copy", "csv",
+    "dataclasses", "datetime", "decimal", "difflib", "enum", "fnmatch",
+    "fractions", "functools", "gzip", "hashlib", "heapq", "hmac", "html",
+    "html.parser", "inspect", "io", "itertools", "json", "keyword", "math",
+    "numbers", "operator", "pprint", "random", "re", "secrets", "shlex",
+    "statistics", "string", "struct", "textwrap", "tomllib", "traceback",
+    "types", "typing", "unicodedata", "urllib", "urllib.parse", "uuid",
+    "xml", "xml.etree", "xml.etree.ElementTree", "zlib",
+    # Bound or substituted, below: the real module is never handed out.
+    "asyncio", "os", "os.path", "pathlib", "time",
+})
+
+# Where to go instead, for the modules people actually reached for. Keyed on the
+# top-level name. Anything unlisted gets the general answer.
+_IMPORT_REDIRECTS = {
+    "subprocess": "run a program with api.run([...]) — no shell, no quoting — or a command line with api.bash(cmd)",
+    "shutil": "copy or move with api.bash('cp …'), and write with api.write_file()",
+    "glob": "find files with api.glob(pattern)",
+    "requests": "fetch with api.run(['curl', '-s', url])",
+    "http": "fetch with api.run(['curl', '-s', url])",
+    "socket": "fetch with api.run(['curl', '-s', url])",
+    "tempfile": "write scratch files under /tmp or the working directory with api.write_file()",
+    "sys": "print() already writes to your result, and api.cwd is the working directory",
+    "xactor": "PageState, Observation, Transition, Step and registry are already bound",
+}
+
+_GENERAL_REDIRECT = (
+    "modules that reach the system, and third-party ones, are not importable "
+    "here — run that code as a script with api.run(['python', '-'], input=source)"
+)
+
+
+def _refuse_import(name: str) -> ImportError:
+    top = name.split(".")[0]
+    where = _IMPORT_REDIRECTS.get(top, _GENERAL_REDIRECT)
+    return ImportError(
+        f"Sandbox: `import {name}` is not available in shell code — {where}. "
+        "Pure standard-library modules import normally (json, re, math, "
+        "datetime, collections, itertools, base64, hashlib, textwrap, difflib, "
+        "…); api.man('sandbox') lists them all."
+    )
+
+
+def _load(name: str) -> Any:
+    """The module `name`, imported on the api's authority if not yet loaded."""
+    if name == "os":
+        return _GuardedOS()
+    if name == "time":
+        return _GuardedTime()
+    module = sys.modules.get(name)
+    if module is None:
+        import importlib
+        # The audit hook refuses an `import` raised from user code; this one is
+        # the shell's own doing, on a name it has already vetted.
+        with api_scope():
+            module = importlib.import_module(name)
+    return module
+
+
+def sandboxed_import(
+    name: str,
+    globals: Any = None,
+    locals: Any = None,
+    fromlist: Any = (),
+    level: int = 0,
+) -> Any:
+    """`__import__` for agent code: the allowlist above, and nothing else.
+
+    Mirrors the builtin's return contract, which is what the import statement
+    relies on: `import a.b` binds `a`, so the top-level package comes back;
+    `from a.b import c` needs `a.b` itself, so the named module comes back.
+    """
+    if level != 0:
+        raise _refuse_import("." * level + (name or ""))
+    if name not in IMPORTABLE_MODULES:
+        raise _refuse_import(name)
+
+    module = _load(name)
+    for item in fromlist or ():
+        sub = f"{name}.{item}"
+        if sub in IMPORTABLE_MODULES and name not in ("os", "time"):
+            _load(sub)
+    if fromlist:
+        return module
+    return _load(name.split(".")[0])
+
+
+@contextlib.contextmanager
+def user_code_scope() -> Iterator[None]:
+    """Mark the enclosed block as agent-authored code (strict denials)."""
+    token = _user_depth.set(_user_depth.get() + 1)
+    try:
+        yield
+    finally:
+        _user_depth.reset(token)
+
+
+@contextlib.contextmanager
+def api_scope() -> Iterator[None]:
+    """Mark the enclosed block as a sanctioned StdlibAPI call."""
+    token = _api_depth.set(_api_depth.get() + 1)
+    try:
+        yield
+    finally:
+        _api_depth.reset(token)
+
+
+def _is_raw_user_code() -> bool:
+    """True when agent code is touching the OS without going through api.*."""
+    return _user_depth.get() > 0 and _api_depth.get() == 0
+
+
+def configure(**kwargs: Any) -> None:
+    """Update sandbox configuration. Call before install()."""
+    for k, v in kwargs.items():
+        if k in _config:
+            _config[k] = v
+
+
+def install() -> None:
+    """Install the audit hook. Idempotent but irreversible."""
+    global _installed
+    if _installed:
+        return
+    _installed = True
+    sys.addaudithook(_audit_hook)
+
+
+# ── One path dialect ───────────────────────────────────────────────────
+#
+# On Windows the shell speaks two. `api.bash` is Git Bash, where `pwd` prints
+# `/c/Users/…`, `/tmp` is the user's temp directory and `$HOME` is
+# `/c/Users/Andy`; every `api.*` path went through pathlib, where `/c/Users` is
+# a rooted path on the current drive — `C:\c\Users` — and `/tmp` is `C:\tmp`.
+# So a path copied from one half of the shell to the other pointed somewhere
+# else: `api.write_file('/tmp/rr.sh')` succeeded and `bash /tmp/rr.sh` found
+# nothing, and widget files were refused at `C:\c\Users\Andy\.widgex\…`.
+# `~` was not expanded anywhere, and `os.path.expanduser` is not reachable
+# from agent code, so a home-relative path had no spelling at all.
+#
+# The translation is Git for Windows' own mount table, which is fixed rather
+# than configured: cygdrive at `/` (so `/c` is `C:`), `/tmp` is the user temp
+# directory, `/bin` is `/usr/bin`, and the rest is under the install root.
+# Derived rather than asked of `cygpath`, because asking means a subprocess and
+# strict mode allows none.
+
+_msys_root_finder: Any = None
+
+
+def set_msys_root_finder(finder: Any) -> None:
+    """Tell the sandbox how to find Git Bash's install root (stdlib_api does)."""
+    global _msys_root_finder
+    _msys_root_finder = finder
+
+
+def _msys_root() -> str | None:
+    try:
+        return _msys_root_finder() if _msys_root_finder else None
+    except Exception:
+        return None
+
+
+def native_path(p: str) -> str:
+    """`p` as this platform spells it: `~` expanded, and on Windows, MSYS paths
+    translated to the Windows paths Git Bash means by them.
+
+    Anything that is already native — `C:\\x`, `C:/x`, a relative path, a UNC
+    share — comes back unchanged.
+    """
+    if not isinstance(p, str) or not p:
+        return p
+    if p == "~" or p.startswith(("~/", "~\\")):
+        p = str(Path.home()) + p[1:]
+    if sys.platform != "win32" or not p.startswith("/") or p.startswith("//"):
+        return p
+
+    parts = [s for s in p.split("/") if s]
+    if not parts:
+        root = _msys_root()
+        return root if root else p
+    head, rest = parts[0], parts[1:]
+    if len(head) == 1 and head.isalpha():
+        return f"{head.upper()}:\\" + "\\".join(rest)
+    if head == "tmp":
+        return str(Path(_USER_TEMP, *rest))
+    root = _msys_root()
+    if root is None:
+        raise FileNotFoundError(
+            f"{p!r} is a Git Bash path, and no Git Bash was found to say what it "
+            "means on Windows. Pass a Windows path such as C:/Users/... instead."
+        )
+    if head == "bin":
+        return str(Path(root, "usr", "bin", *rest))
+    return str(Path(root, *parts))
+
+
+def _resolve_path(p: str) -> str:
+    """Resolve a path to absolute form against the configured cwd."""
+    # Never raises: this runs inside the audit hook, where an exception would
+    # refuse an open that the path rules might well allow.
+    try:
+        p = native_path(p)
+    except Exception:
+        pass
+    path = Path(p)
+    if not path.is_absolute():
+        path = Path(_config["cwd"]) / path
+    try:
+        return str(path.resolve())
+    except (OSError, ValueError):
+        return str(path)
+
+
+def _contains(root: str, resolved: str) -> bool:
+    """Whether `resolved` is `root` or sits beneath it.
+
+    Containment, not string prefix: `startswith` let `/repo/foobar` pass as if
+    it were inside `/repo/foo`.
+    """
+    return resolved == root or resolved.startswith(root.rstrip(os.sep) + os.sep)
+
+
+def _writable_roots() -> list[str]:
+    """Where a write is permitted, in the order the checks try them.
+
+    Exists so the refusal can name them. The old message ended with
+    `Mode: permissive`, which is true, is not the reason, and reads as a
+    contradiction to whoever was just refused by it — the mode is what allows
+    *reads* outside the cwd, and it has no bearing on the write that failed.
+    """
+    roots = [str(Path(_config["cwd"]).resolve())]
+    roots.extend(_TMP_DIRS)
+    roots.extend(str(Path(p).resolve()) for p in _config["write_allow"])
+    roots.extend(_widget_dirs())
+    return roots
+
+
+def _widget_dirs() -> list[str]:
+    """Where authored widgets live: ``~/.widgex/widgets``.
+
+    `writing-a-widget` tells an author to save the widget there and the loader
+    reads nothing else, yet it is outside every workspace, so the write was
+    refused. Authors fell back to a bash heredoc, which corrupted at least one
+    file with nothing to say so. Resolved on each call, not at import, so a
+    changed HOME is honoured.
+    """
+    d = _resolved(os.path.join(os.path.expanduser("~"), ".widgex", "widgets"))
+    return [d] if d else []
+
+
+def _is_path_allowed(resolved: str, write: bool = False) -> bool:
+    """Check if a resolved absolute path is within allowed prefixes."""
+    mode = _config["mode"]
+
+    # Open mode allows everything
+    if mode == "open":
+        return True
+
+    # Always allow reading/writing within cwd — except under a fence the host
+    # could not name (`--fence ''`), which admits no folder at all.
+    if _config.get("fence") != "" and _contains(str(Path(_config["cwd"]).resolve()), resolved):
+        return True
+
+    # Always allow temp directories (cached to avoid re-entrant audit calls)
+    if any(_contains(root, resolved) for root in _TMP_DIRS):
+        return True
+
+    # The authored-widgets directory is writable (and, being outside the cwd,
+    # would otherwise be readable only). See `_widget_dirs`.
+    if any(_contains(root, resolved) for root in _widget_dirs()):
+        return True
+
+    # Always allow Python's own directories (stdlib, site-packages) for reads
+    if not write:
+        for prefix in _python_prefixes:
+            if resolved.startswith(prefix):
+                return True
+
+    # Check explicit allow lists. Containment, as everywhere else here: these
+    # carry the folders a fenced session was allowed into, and `startswith` let
+    # an allowed `C:\x\foo` admit `C:\x\foobar`.
+    allow_list = _config["write_allow"] if write else _config["read_allow"]
+    for prefix in allow_list:
+        if _contains(str(Path(prefix).resolve()), resolved):
+            return True
+    if _fence_transient_allows(resolved, write):
+        return True
+
+    # Permissive mode: allow reads outside cwd, block writes
+    if mode == "permissive" and not write:
+        return True
+
+    return False
+
+
+# ── The folder fence ───────────────────────────────────────────────────
+#
+# A drive-channel task may use its folder freely and must ask for anything
+# else. Two checks, and they draw the line in different places on purpose.
+#
+# `fence_allows` is the question asked about a path the *agent named* —
+# `api.read_file(p)`, `api.glob(pattern, path)` — before the call runs. It
+# admits the folder and what the user has allowed since, and nothing else: not
+# the temp directory, not the widgets folder, since the agent choosing to read
+# `/tmp/x` is exactly as much "outside" as choosing `C:/Users`.
+#
+# The audit hook is the backstop for what an api *body* opens on its own, and
+# keeps the ordinary exemptions: `api.powershell` writes its script to a temp
+# file, and refusing that would break the shell rather than fence anything.
+
+
+def _fence_key(p: str) -> str:
+    return os.path.normcase(os.path.normpath(p))
+
+
+def fenced() -> bool:
+    """Whether this shell is fenced at all — including to a folder nobody could name."""
+    return _config.get("fence") is not None
+
+
+def fence_root() -> str | None:
+    """The folder this session is fenced to; '' when the host could not say
+    which (every path is asked about), None for an ordinary session."""
+    return _config.get("fence")
+
+
+# Paths allowed for one api call only, as (resolved, write): what an allow
+# grants when the folder it would cover is a drive root or the home folder.
+# A ContextVar holding a list, set per call by the api wrapper, so a grant made
+# while the call runs is seen by the rest of that call and by nothing after it.
+_fence_transient: contextvars.ContextVar[list[tuple[str, bool]] | None] = contextvars.ContextVar(
+    "fence_transient", default=None)
+
+
+@contextlib.contextmanager
+def fence_call_scope() -> Iterator[None]:
+    """One api call's lifetime for the grants `fence_grant` will not keep."""
+    token = _fence_transient.set([])
+    try:
+        yield
+    finally:
+        _fence_transient.reset(token)
+
+
+def _fence_transient_allows(resolved: str, write: bool) -> bool:
+    target = _fence_key(resolved)
+    for path, writes in _fence_transient.get() or ():
+        if (writes or not write) and _contains(_fence_key(path), target):
+            return True
+    return False
+
+
+def fence_allows(resolved: str, write: bool = False) -> bool:
+    """Whether an agent-named path is inside the fence or a folder allowed since.
+
+    True for every path when there is no fence. Case-blind on Windows, like
+    the filesystem; `_contains` alone is not, and a path spelled `c:\\` against
+    a fence spelled `C:\\` would ask about the agent's own folder.
+    """
+    if not fenced():
+        return True
+    root = fence_root()
+    target = _fence_key(resolved)
+    allowed = ([root] if root else []) + list(_config["write_allow"])
+    if not write:
+        allowed += _config["read_allow"]
+    for prefix in allowed:
+        try:
+            base = _fence_key(str(Path(prefix).resolve()))
+        except (OSError, ValueError):
+            base = _fence_key(prefix)
+        if _contains(base, target):
+            return True
+    return _fence_transient_allows(resolved, write)
+
+
+def _too_broad_to_keep(folder: str) -> bool:
+    """A drive root or the home folder: an allow there covers the one call."""
+    resolved = _resolved(folder) or folder
+    if os.path.dirname(resolved) == resolved:
+        return True
+    home = _resolved(os.path.expanduser("~"))
+    return bool(home) and _fence_key(resolved) == _fence_key(home)
+
+
+def fence_grant(path: str, folder: str, write: bool) -> None:
+    """Remember what the user allowed.
+
+    The folder, for the rest of this shell's life — unless it is a drive root
+    or the home folder, where remembering it would take the fence down for
+    everything. Then only `path` is allowed, and only for the call in progress.
+    """
+    if _too_broad_to_keep(folder):
+        transient = _fence_transient.get()
+        if transient is not None:
+            transient.append((_resolved(path) or path, write))
+        return
+    resolved = _resolved(folder) or folder
+    if resolved not in _config["read_allow"]:
+        _config["read_allow"].append(resolved)
+    if write and resolved not in _config["write_allow"]:
+        _config["write_allow"].append(resolved)
+
+
+def _audit_hook(event: str, args: tuple) -> None:
+    """The audit hook — called by CPython on every security-sensitive op."""
+    global _in_hook
+    if _in_hook:
+        return  # Prevent re-entrant calls (e.g. path resolution triggering open)
+    _in_hook = True
+    try:
+        _audit_hook_inner(event, args)
+    finally:
+        _in_hook = False
+
+
+def _event_path(value: Any) -> str | None:
+    if isinstance(value, bytes):
+        value = value.decode(errors="replace")
+    if isinstance(value, os.PathLike):
+        value = os.fspath(value)
+    return _resolve_path(value) if isinstance(value, str) and value else None
+
+
+def _seal_event(event: str, args: tuple) -> None:
+    """Seals, for a file an api body touches. Raises `seals.SealDenied`.
+
+    The backstop described in `seals.py`: `check_call` judges a call by its
+    arguments, and this judges what its body actually opened. Only api bodies
+    reach here — raw agent code is refused every file outright, above.
+    """
+    seals = _seals
+    if not seals.backstop_active():
+        return
+    if event == "open":
+        path = _event_path(args[0] if args else None)
+        if not path:
+            return
+        file_mode = (args[1] if len(args) > 1 else "r") or "r"
+        writes = any(c in file_mode for c in "wxa+")
+        if "r" in file_mode or "+" in file_mode or not writes:
+            seals.check_event("R", path)
+        if writes:
+            seals.check_event("W", path)
+    elif event in ("os.remove", "os.unlink", "os.rmdir", "os.truncate"):
+        path = _event_path(args[0] if args else None)
+        if path:
+            seals.check_event("W", path)
+    elif event in ("os.rename", "os.replace"):
+        src = _event_path(args[0] if args else None)
+        dst = _event_path(args[1] if len(args) > 1 else None)
+        if src:
+            seals.check_event("M", src)
+        if dst:
+            seals.check_event("W", dst)
+    elif event in ("shutil.copyfile", "shutil.copytree"):
+        src = _event_path(args[0] if args else None)
+        dst = _event_path(args[1] if len(args) > 1 else None)
+        if src:
+            seals.check_event("C", src)
+        if dst:
+            seals.check_event("W", dst)
+
+
+def _audit_hook_inner(event: str, args: tuple) -> None:
+    """Inner audit logic (called with re-entrancy guard held)."""
+    mode = _config["mode"]
+
+    # Seals first, and ahead of `open` mode: a seal is org policy, and no
+    # sandbox mode is a way around it.
+    if _api_depth.get() > 0 and not _is_raw_user_code():
+        _seal_event(event, args)
+
+    # Open mode: no restrictions (useful for trusted sessions)
+    if mode == "open":
+        return
+
+    # ── Direct OS access from agent code ──
+    # Enforced in every mode: the shell's contract is that the outside world
+    # is reached through api.*, so raw access is refused before the softer
+    # path/subprocess/network rules below get a say.
+    if _is_raw_user_code():
+        if event == "open":
+            path_arg = args[0] if args else ""
+            p = path_arg.decode() if isinstance(path_arg, bytes) else path_arg
+            raise PermissionError(
+                f"Sandbox: direct file access is not allowed from shell code ({p!r}). "
+                f"Use api.read_file() / api.write_file() / api.edit_file() instead."
+            )
+        if event == "import":
+            module_name = args[0] if args else ""
+            raise ImportError(
+                f"Sandbox: importing {module_name!r} is not allowed from shell code. "
+                f"{_USE_API}"
+            )
+        if event.startswith(_OS_EVENT_PREFIXES) or event == "exec":
+            raise PermissionError(
+                f"Sandbox: direct OS access is not allowed from shell code "
+                f"(attempted {event!r}). {_USE_API}"
+            )
+
+    # ── File access ──
+    if event == "open":
+        path_arg, file_mode, _flags = args
+        if isinstance(path_arg, (str, bytes)):
+            p = path_arg.decode() if isinstance(path_arg, bytes) else path_arg
+            resolved = _resolve_path(p)
+            is_write = any(c in (file_mode or "r") for c in "wxa+")
+            if not _is_path_allowed(resolved, write=is_write):
+                op = "write" if is_write else "read"
+                # Name the roots, not the mode. `Mode: permissive` was true and
+                # actively misleading: permissive is what allows reads outside
+                # the cwd and says nothing about writes, so a refusal that ends
+                # with it reads as a contradiction and sends the reader looking
+                # at configuration instead of at the path.
+                where = (
+                    " Writable: " + ", ".join(_writable_roots()) + ". A file "
+                    "elsewhere is changed by a command (api.powershell or "
+                    "api.bash), which asks the user first; parse what you "
+                    "wrote afterwards, since an invalid settings or config "
+                    "file stops its app saving anything."
+                    if is_write else
+                    f" Mode: {mode}."
+                )
+                if fenced():
+                    # Raised as its own class so the api wrapper asks the user
+                    # about this path rather than failing with no card.
+                    raise FenceDenied(
+                        resolved, is_write,
+                        f"Sandbox: {p!r} (resolved: {resolved}) is outside this "
+                        f"task's folder, {fence_root() or '(unknown)'}.",
+                    )
+                raise PermissionError(
+                    f"Sandbox: {op} access denied for {p!r} "
+                    f"(resolved: {resolved}).{where}"
+                )
+
+    # ── Subprocess execution ──
+    elif event in ("subprocess.Popen", "os.system"):
+        if not _config["allow_subprocess"]:
+            raise PermissionError(
+                f"Sandbox: subprocess execution denied. "
+                f"Event: {event}, Mode: {mode}"
+            )
+
+    elif event.startswith("os.exec") or event.startswith("os.spawn"):
+        if not _config["allow_subprocess"]:
+            raise PermissionError(
+                f"Sandbox: exec/spawn denied. Event: {event}, Mode: {mode}"
+            )
+
+    # ── Network access ──
+    elif event in ("socket.connect", "socket.bind", "socket.sendto"):
+        if not _config["allow_network"]:
+            # Allow asyncio's internal socketpair (127.0.0.1 loopback for self-pipe)
+            if event == "socket.bind" and args:
+                addr = args[1] if len(args) > 1 else args[0]
+                if isinstance(addr, tuple) and addr[0] in ("127.0.0.1", "::1", ""):
+                    return  # asyncio internal
+            if event == "socket.connect" and args:
+                addr = args[1] if len(args) > 1 else args[0]
+                if isinstance(addr, tuple) and addr[0] in ("127.0.0.1", "::1"):
+                    return  # asyncio internal / localhost
+            raise PermissionError(
+                f"Sandbox: network access denied. "
+                f"Event: {event}, Mode: {mode}"
+            )
+
+    # ── Dangerous builtins ──
+    elif event == "compile" and mode == "strict":
+        # In strict mode, only allow compilation from our own exec wrapper
+        source = args[0] if args else ""
+        if isinstance(source, str) and "<xactor-exec>" not in source:
+            pass  # Allow — can't easily distinguish in strict mode
+
+    # ── Module imports ──
+    elif event == "import":
+        module_name = args[0] if args else ""
+        if isinstance(module_name, str) and module_name in _config["blocked_modules"]:
+            raise ImportError(
+                f"Sandbox: import of {module_name!r} is blocked"
+            )
+
+    # ── ctypes / native code loading ──
+    elif event == "ctypes.dlopen":
+        raise PermissionError("Sandbox: loading native libraries via ctypes is blocked")