agentshim 0.6.6__tar.gz → 0.6.8__tar.gz

{agentshim-0.6.6 → agentshim-0.6.8}/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 0.6.8 (2026-09-27)
+
+A tightening of the Codex (`STRICT`) schema check: schemas it now rejects
+were already rejected by the API, after a full model turn.
+
+### Fixed
+
+- A Codex output schema is checked against OpenAI's strict structured-output
+  rules before the CLI starts. `turn()` raises `SchemaDialectError`, naming
+  each offending node by JSON pointer, when an object leaves a property out
+  of `required` (declare it required and nullable instead), lists a
+  `required` name missing from `properties`, omits `properties` (`{}` is
+  fine) or `additionalProperties: false` (including on a nullable
+  `["object", "null"]` object), uses `anyOf` at
+  the root, or has a `$ref` that resolves to nothing. Codex used to fail such
+  a turn with `invalid_json_schema` only after the model ran. The Claude
+  (`OPEN`) dialect is unchanged.
+- A `$ref` of `"#"` (root recursion) is accepted as local in both dialects.
+- Problem pointers escape `/` and `~` in property names (RFC 6901), and
+  `enum`, `const` and `required` values are no longer inspected as schemas.
+- `normalize` closes a nullable object node too, and gives an object with
+  no `properties` an empty one, so its output passes the `STRICT` check.
+
+## 0.6.7 (2026-09-27)
+
+Additive, with one tightening: a sandboxed Codex turn no longer applies the
+user's exec-policy rules (see Fixed).
+
+### Added
+
+- `CodexSandboxConfig(excluded_commands=[...])` lets named commands run
+  outside Codex's sandbox while everything else stays confined, the Codex
+  counterpart of Claude's `excludedCommands`. Each entry is shell words
+  matched as a command prefix. Codex supports this only as exec-policy
+  `prefix_rule(decision="allow")` rules read from `$CODEX_HOME/rules/`, so
+  `agentshim.providers.codex.install_rules(home, config)` writes them into a
+  dedicated Codex home and the turn runs with `CODEX_HOME` set to it. The
+  provider refuses a missing or relative `CODEX_HOME`, or one the sandbox lets
+  commands write. `render_rules` and `parse_rules` expose the rules file.
+- `ArgvContext.cwd` (default `None`): the turn's cwd, for a provider to
+  validate paths against. It is never rendered into argv.
+
+### Fixed
+
+- Sandboxed Codex turns pass `--ignore-rules`. An `allow` rule in the user's
+  `~/.codex/rules/` (which the TUI writes when a command is approved) used to
+  run its command outside a sandbox agentshim had asked for.
+
+### Documented
+
+- Codex often omits commands its sandbox denied from `--json` output, and
+  exposes them nowhere else in structured form, so no `ToolCall` event is
+  emitted for them.
+
 ## 0.6.6 (2026-09-27)
 
 Additive: every new option defaults to earlier behaviour.

{agentshim-0.6.6 → agentshim-0.6.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.6.6
+Version: 0.6.8
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Provides-Extra: test

{agentshim-0.6.6 → agentshim-0.6.8}/agentshim/__init__.py

@@ -84,7 +84,7 @@ from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
 
-__version__ = "0.6.6"
+__version__ = "0.6.8"
 
 __all__ = [
     "AgentEvent",

{agentshim-0.6.6 → agentshim-0.6.8}/agentshim/agent.py

@@ -258,6 +258,7 @@ class AgentSession:
                     schema_path=schema_path,
                     mcp_argv=installation.argv,
                     extra_args=req.extra_args,
+                    cwd=cwd,
                 )
             )
             command = CommandRequest(argv=argv, stdin=req.prompt, cwd=cwd, env=env, timeout=timeout)

{agentshim-0.6.6 → agentshim-0.6.8}/agentshim/core/profile.py

@@ -34,9 +34,12 @@ class OutputSchemaStyle(Enum):
 class SchemaDialect(Enum):
     """Which JSON Schema subset a provider accepts.
 
-    ``STRICT`` is Codex's ``--output-schema`` subset: every object declares
-    its properties and forbids undeclared keys. ``OPEN`` also accepts a
-    schema-valued or ``true`` ``additionalProperties``.
+    ``STRICT`` is Codex's ``--output-schema`` subset, which is OpenAI's strict
+    structured outputs: every object declares ``properties``, sets
+    ``additionalProperties: false`` and lists every property in ``required`` (optional values are made
+    nullable instead), the root is not an ``anyOf``, and every ``$ref``
+    resolves. ``OPEN`` also accepts optional properties and a schema-valued,
+    ``true`` or absent ``additionalProperties``.
     """
 
     STRICT = "strict"

{agentshim-0.6.6 → agentshim-0.6.8}/agentshim/core/provider.py

@@ -34,6 +34,9 @@ class ArgvContext:
     schema_path: str | None
     mcp_argv: Sequence[str] = ()
     extra_args: Sequence[str] = ()
+    #: The directory the CLI will run in, or ``None`` for the executor's own.
+    #: Argv never carries it; a provider reads it to validate paths against it.
+    cwd: str | None = None
 
 
 @dataclass(frozen=True)

agentshim-0.6.8/agentshim/core/schema.py

@@ -0,0 +1,352 @@
+"""Output-schema dialect checks and materialization.
+
+Providers disagree about which JSON Schema subset their structured-output
+flag accepts, and the failure mode is an expensive agent turn that ends in a
+CLI parse error. These checks run before the process starts.
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, cast
+
+from ._files import atomic_write
+from .errors import ProviderCapabilityError
+from .profile import SchemaDialect
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+# Keywords that need schema-evaluation features outside the subset the
+# provider CLIs implement. Field names are never inspected as keywords:
+# ``properties``, ``$defs`` and ``definitions`` are traversed as maps of
+# subschemas, so a property literally named ``if`` is fine.
+UNSUPPORTED_KEYWORDS = frozenset(
+    {
+        "$anchor",
+        "$dynamicAnchor",
+        "$dynamicRef",
+        "$id",
+        "$schema",
+        "allOf",
+        "contains",
+        "dependentRequired",
+        "dependentSchemas",
+        "else",
+        "if",
+        "maxContains",
+        "minContains",
+        "not",
+        "oneOf",
+        "patternProperties",
+        "prefixItems",
+        "propertyNames",
+        "then",
+        "unevaluatedItems",
+        "unevaluatedProperties",
+    }
+)
+
+_SUBSCHEMA_MAPS = frozenset({"properties", "$defs", "definitions"})
+
+# Annotations that describe a schema rather than constrain a value. They are
+# what a generator such as Pydantic emits alongside the real constraints, and
+# what the strictest CLI subset refuses to read, so ``normalize`` removes
+# them. Field names are never matched against this set: ``properties`` is
+# traversed as a map of subschemas, so a property named ``title`` survives.
+_METADATA_KEYWORDS = frozenset({"$schema", "$id", "title", "description", "examples"})
+
+# ``$schema`` and ``$id`` identify the dialect and the document; a CLI that
+# accepts open-ended schemas ignores them rather than failing on them. Codex's
+# ``--output-schema`` subset does not, so ``STRICT`` keeps reporting them.
+_OPEN_DIALECT_TOLERATES = frozenset({"$schema", "$id"})
+
+# Keywords whose values are data, never subschemas. ``required`` is a list of
+# field names and ``enum``/``const`` hold instance values, so a name such as
+# ``"$ref"`` inside them must not be read as a keyword.
+_NON_SCHEMA_KEYWORDS = frozenset({"required", "enum", "const"})
+
+
+def dialect_problems(schema: Mapping[str, Any], dialect: SchemaDialect) -> list[str]:
+    """Return every reason *schema* is not expressible in *dialect*.
+
+    An empty list means the provider will accept it. The list is returned
+    rather than raised so a caller can decide between failing and falling
+    back to a prompt-level schema instruction. Each problem starts with the
+    JSON pointer of the offending node.
+
+    ``STRICT`` is OpenAI's strict structured-output subset, which Codex sends
+    with ``strict: true``: every object declares ``properties``, sets
+    ``additionalProperties: false`` and lists exactly its ``properties`` in
+    ``required`` (an optional value is
+    expressed as nullable instead), the root is not an ``anyOf``, and every
+    ``$ref`` resolves inside the document.
+    """
+    root = dict(schema)
+    walk = _Walk(root=root, dialect=dialect, problems=[])
+    if schema.get("type") != "object":
+        walk.problems.append("# root must be a schema with type 'object'")
+    if dialect is SchemaDialect.STRICT and "anyOf" in schema:
+        walk.problems.append("# root must not use 'anyOf'")
+    walk.visit(root, "#")
+    return walk.problems
+
+
+def _pointer_token(name: str) -> str:
+    """Escape a field name as one JSON pointer reference token (RFC 6901)."""
+    return name.replace("~", "~0").replace("/", "~1")
+
+
+def _is_object_node(mapping: dict[str, Any]) -> bool:
+    """Say whether a node describes an object, nullable or not."""
+    if mapping.get("properties") is not None:
+        return True
+    declared = mapping.get("type")
+    if isinstance(declared, list):
+        return "object" in cast("list[object]", declared)
+    return declared == "object"
+
+
+@dataclass
+class _Walk:
+    """One pass of ``dialect_problems`` over a schema document.
+
+    Traversal is by JSON pointer so each problem names the offending node.
+    """
+
+    root: dict[str, Any]
+    dialect: SchemaDialect
+    problems: list[str]
+
+    def visit(self, node: object, location: str) -> None:
+        """Walk one schema node, appending a problem for every unsupported construct.
+
+        A ``$ref`` node terminates the walk: its siblings are annotations the
+        strict subset ignores, and the target is checked where it is defined,
+        since every local target is inside the document this walk covers.
+        """
+        if isinstance(node, list):
+            for index, value in enumerate(cast("list[object]", node)):
+                self.visit(value, f"{location}/{index}")
+            return
+        if not isinstance(node, dict):
+            return
+        mapping = cast("dict[str, Any]", node)
+
+        reference = mapping.get("$ref")
+        if reference is not None:
+            self._check_ref(reference, location)
+            return
+
+        if not self._check_properties_shape(mapping, location):
+            return
+        if self.dialect is SchemaDialect.STRICT and _is_object_node(mapping):
+            self._check_closed_object(mapping, location)
+            self._check_all_required(mapping, location)
+        self._visit_members(mapping, location)
+
+    def _check_ref(self, reference: object, location: str) -> None:
+        """Reject a ``$ref`` the CLI would have to fetch, or one that dangles."""
+        if not isinstance(reference, str) or not (reference == "#" or reference.startswith("#/")):
+            self.problems.append(f"{location} uses a non-local $ref")
+            return
+        if self.dialect is SchemaDialect.STRICT and not _resolves(self.root, reference):
+            self.problems.append(f"{location} has a $ref {reference!r} that resolves to nothing")
+
+    def _check_properties_shape(self, mapping: dict[str, Any], location: str) -> bool:
+        """Check that ``properties``, if present, is an object.
+
+        Returns ``False`` when it is not, in which case the caller stops:
+        nothing below a malformed ``properties`` can be read as a schema, and
+        descending would only report the same defect once per child.
+        """
+        properties = mapping.get("properties")
+        if properties is not None and not isinstance(properties, dict):
+            self.problems.append(f"{location}/properties must be an object")
+            return False
+        return True
+
+    def _check_closed_object(self, mapping: dict[str, Any], location: str) -> None:
+        """Require an object node to declare ``properties`` and close itself.
+
+        Strict mode needs ``additionalProperties`` present, not merely not
+        ``true``: an absent one is an open object in JSON Schema. It also
+        refuses an object with no ``properties`` at all, even an empty one.
+        """
+        if "properties" not in mapping:
+            self.problems.append(f"{location} must declare properties (use {{}} for none)")
+        if "additionalProperties" not in mapping:
+            self.problems.append(f"{location} must set additionalProperties: false")
+        elif mapping["additionalProperties"] is not False:
+            self.problems.append(f"{location} allows arbitrary object keys")
+
+    def _check_all_required(self, mapping: dict[str, Any], location: str) -> None:
+        """Require ``required`` to list exactly the declared properties.
+
+        Strict mode has no optional properties: a value that may be absent is
+        declared required and nullable, e.g. ``{"type": ["string", "null"]}``.
+        """
+        properties = cast("dict[str, Any]", mapping.get("properties") or {})
+        required = mapping.get("required", [])
+        if not isinstance(required, list) or not all(
+            isinstance(name, str) for name in cast("list[object]", required)
+        ):
+            self.problems.append(f"{location}/required must be an array of property names")
+            return
+        listed = set(cast("list[str]", required))
+        for name in properties:
+            if name not in listed:
+                self.problems.append(
+                    f"{location}/properties/{_pointer_token(name)} is optional; strict mode "
+                    "requires every property in 'required' (make it nullable instead)"
+                )
+        for name in cast("list[str]", required):
+            if name not in properties:
+                self.problems.append(
+                    f"{location}/required names {name!r}, which is not in 'properties'"
+                )
+
+    def _visit_members(self, mapping: dict[str, Any], location: str) -> None:
+        """Check every entry of a schema node, keyword or subschema.
+
+        Only keys reached here are matched against ``UNSUPPORTED_KEYWORDS``,
+        which is what keeps a property named ``if`` from being read as the
+        ``if`` keyword.
+        """
+        for key, value in mapping.items():
+            if key in _SUBSCHEMA_MAPS:
+                self._visit_subschema_map(value, f"{location}/{key}")
+            elif key in UNSUPPORTED_KEYWORDS:
+                if self.dialect is not SchemaDialect.STRICT and key in _OPEN_DIALECT_TOLERATES:
+                    continue
+                self.problems.append(f"{location} uses unsupported keyword {key!r}")
+            elif key in _METADATA_KEYWORDS or key in _NON_SCHEMA_KEYWORDS:
+                # Annotations or plain values: nothing below them is a schema.
+                continue
+            else:
+                self.visit(value, f"{location}/{key}")
+
+    def _visit_subschema_map(self, value: object, location: str) -> None:
+        """Walk a map of named subschemas such as ``properties`` or ``$defs``.
+
+        The names are user-chosen field names, so they are traversed as data
+        and never inspected as schema keywords.
+        """
+        if not isinstance(value, dict):
+            self.problems.append(f"{location} must be an object")
+            return
+        for name, subschema in cast("dict[str, Any]", value).items():
+            self.visit(subschema, f"{location}/{_pointer_token(name)}")
+
+
+def _resolves(root: dict[str, Any], reference: str) -> bool:
+    """Say whether a local ``$ref`` names a schema inside *root*."""
+    node: object = root
+    for raw in reference[2:].split("/") if reference != "#" else []:
+        token = raw.replace("~1", "/").replace("~0", "~")
+        if isinstance(node, dict):
+            mapping = cast("dict[str, object]", node)
+            if token not in mapping:
+                return False
+            node = mapping[token]
+        elif isinstance(node, list):
+            items = cast("list[object]", node)
+            if not token.isdigit() or int(token) >= len(items):
+                return False
+            node = items[int(token)]
+        else:
+            return False
+    return isinstance(node, dict)
+
+
+def normalize(schema: Mapping[str, Any], dialect: SchemaDialect) -> dict[str, Any]:
+    """Return a copy of *schema* rewritten into the provider's house style.
+
+    Generators such as Pydantic omit defaulted properties from ``required``
+    and leave ``additionalProperties`` unset, which the CLIs read as "any
+    subset of these keys, plus anything else". This closes every object,
+    requires every declared property, drops ``default``, strips the annotation
+    siblings of a ``$ref`` that the strict subset forbids, and removes the
+    document metadata (``$schema``, ``$id``, ``title``, ``description``,
+    ``examples``) that ``dialect_problems`` reports under ``STRICT``. What
+    comes back is therefore a schema the strict subset accepts. Callers that
+    want the schema passed through untouched skip this.
+    """
+    return cast("dict[str, Any]", _normalized(copy.deepcopy(dict(schema)), dialect))
+
+
+def _normalized(node: object, dialect: SchemaDialect) -> object:
+    if isinstance(node, list):
+        return [_normalized(value, dialect) for value in cast("list[object]", node)]
+    if not isinstance(node, dict):
+        return node
+    mapping = cast("dict[str, Any]", node)
+
+    reference = mapping.get("$ref")
+    if isinstance(reference, str):
+        return {"$ref": reference}
+
+    mapping.pop("default", None)
+    for annotation in _METADATA_KEYWORDS:
+        mapping.pop(annotation, None)
+    properties = mapping.get("properties")
+    if isinstance(properties, dict):
+        _close_object(mapping, dialect)
+        mapping["required"] = list(cast("dict[str, Any]", properties))
+    elif _is_object_node(mapping):
+        _close_object(mapping, dialect)
+        mapping["properties"] = {}
+        mapping["required"] = []
+
+    for key, value in list(mapping.items()):
+        if key in _SUBSCHEMA_MAPS and isinstance(value, dict):
+            mapping[key] = {
+                name: _normalized(subschema, dialect)
+                for name, subschema in cast("dict[str, Any]", value).items()
+            }
+            continue
+        mapping[key] = _normalized(value, dialect)
+    return mapping
+
+
+def _close_object(mapping: dict[str, Any], dialect: SchemaDialect) -> None:
+    additional = mapping.get("additionalProperties")
+    if additional in (None, False):
+        mapping["additionalProperties"] = False
+        return
+    if dialect is SchemaDialect.STRICT:
+        # dialect_problems already reported this; normalize does not guess.
+        mapping["additionalProperties"] = False
+
+
+def compact_json(schema: Mapping[str, Any]) -> str:
+    """Serialize *schema* for an inline CLI flag, keeping argv small."""
+    return json.dumps(dict(schema), separators=(",", ":"))
+
+
+def materialize(schema: Mapping[str, Any], host_dir: Path) -> Path:
+    """Write *schema* under *host_dir* as ``<sha>.json`` and return the path.
+
+    The name is content-addressed so repeated turns with the same schema
+    reuse one file, and the write is atomic so a CLI reading the path
+    concurrently never sees a partial document.
+
+    A schema carrying a value JSON cannot express, a ``NaN`` or an infinity,
+    raises ``ProviderCapabilityError``: the provider cannot be given this
+    schema, which is the same answer a dialect problem gets, and it is what
+    keeps a bare ``ValueError`` out of ``turn()``.
+    """
+    try:
+        serialized = json.dumps(dict(schema), indent=2, sort_keys=True, allow_nan=False)
+    except ValueError as exc:
+        msg = f"output schema cannot be serialized as JSON: {exc}"
+        raise ProviderCapabilityError(msg) from exc
+    encoded = (serialized + "\n").encode()
+    digest = hashlib.sha256(encoded).hexdigest()[:16]
+    target = host_dir / f"{digest}.json"
+    atomic_write(target, encoded)
+    return target

{agentshim-0.6.6 → agentshim-0.6.8}/agentshim/providers/codex/__init__.py

@@ -3,20 +3,33 @@
 from __future__ import annotations
 
 from .parser import CodexStreamParser
-from .provider import BYPASS_FLAG, PROFILE, CodexProvider, parse_mcp_servers, parse_sandbox
+from .provider import (
+    BYPASS_FLAG,
+    IGNORE_RULES_FLAG,
+    PROFILE,
+    CodexProvider,
+    parse_mcp_servers,
+    parse_sandbox,
+)
+from .rules import RULES_FILENAME, install_rules, parse_rules, render_rules
 from .sandbox import SANDBOX_MODES, CodexSandboxConfig, SandboxMode
 from .scripted import resume_failure_lines, scripted_lines
 
 __all__ = [
     "BYPASS_FLAG",
+    "IGNORE_RULES_FLAG",
     "PROFILE",
+    "RULES_FILENAME",
     "SANDBOX_MODES",
     "CodexProvider",
     "CodexSandboxConfig",
     "CodexStreamParser",
     "SandboxMode",
+    "install_rules",
     "parse_mcp_servers",
+    "parse_rules",
     "parse_sandbox",
+    "render_rules",
     "resume_failure_lines",
     "scripted_lines",
 ]

{agentshim-0.6.6 → agentshim-0.6.8}/agentshim/providers/codex/provider.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import re
 from typing import TYPE_CHECKING, Any
 
@@ -16,6 +17,7 @@ from agentshim.core.profile import (
 
 from ._toml import toml_array, toml_str, unescape_toml
 from .parser import CodexStreamParser
+from .rules import RULES_FILENAME
 from .sandbox import CodexSandboxConfig, resolve_sandbox, sandbox_overrides
 
 if TYPE_CHECKING:
@@ -90,6 +92,9 @@ PROFILE = ProviderProfile(
 #: Turns off both Codex's sandbox and its approval prompts.
 BYPASS_FLAG = "--dangerously-bypass-approvals-and-sandbox"
 
+#: Keeps user and project ``.rules`` files out of a sandboxed turn.
+IGNORE_RULES_FLAG = "--ignore-rules"
+
 
 class CodexProvider:
     """Codex (``codex exec --json``). ``sandbox`` is a provider option."""
@@ -116,7 +121,7 @@ class CodexProvider:
         argv = [ctx.binary_path, "exec"]
         if ctx.resume_session_id:
             argv += ["resume", ctx.resume_session_id, "-"]
-        argv += self._sandbox_argv()
+        argv += self._sandbox_argv(ctx)
         argv += ["--skip-git-repo-check", "--json"]
         if ctx.model:
             argv += ["--model", ctx.model]
@@ -129,12 +134,24 @@ class CodexProvider:
         argv += list(ctx.extra_args)
         return argv
 
-    def _sandbox_argv(self) -> list[str]:
+    def _sandbox_argv(self, ctx: ArgvContext) -> list[str]:
+        """Render the sandbox, and decide which exec-policy rules may apply.
+
+        Codex runs a command that an ``allow`` rule matches outside its
+        sandbox, and loads rules from ``$CODEX_HOME/rules`` and trusted
+        projects. Without exemptions ``--ignore-rules`` keeps every such file
+        out, the user's own included. With them the rules have to load, so
+        the home they come from is checked instead.
+        """
         if self.sandbox is None:
             return [BYPASS_FLAG]
         argv: list[str] = []
         for key, value in sandbox_overrides(self.sandbox):
             argv += ["--config", f"{key}={value}"]
+        if self.sandbox.excluded_commands:
+            _check_rules_home(self.sandbox, ctx)
+        else:
+            argv.append(IGNORE_RULES_FLAG)
         return argv
 
     def new_parser(
@@ -178,6 +195,50 @@ class CodexProvider:
         )
 
 
+def _check_rules_home(config: CodexSandboxConfig, ctx: ArgvContext) -> None:
+    """Refuse a ``CODEX_HOME`` that cannot hold the exemptions safely.
+
+    The rules are read from ``$CODEX_HOME/rules`` on every turn, so a home the
+    sandbox lets commands write would let the model install a rule exempting
+    anything, and have it apply from the next turn on.
+    """
+    home = ctx.env.get("CODEX_HOME")
+    if not home or not os.path.isabs(home):  # noqa: PTH117 - a str contract, not a Path
+        msg = (
+            "excluded_commands are read from $CODEX_HOME/rules/"
+            f"{RULES_FILENAME}: run the turn with CODEX_HOME set to the absolute "
+            f"path of a dedicated home prepared with install_rules (got {home!r})"
+        )
+        raise ProviderCapabilityError(msg)
+    for directory in _writable_dirs(config, ctx):
+        if _is_within(home, directory) or _is_within(directory, home):
+            msg = (
+                f"CODEX_HOME {home} overlaps {directory}, which the sandbox lets "
+                "commands write, so a command could add rules exempting itself"
+            )
+            raise ProviderCapabilityError(msg)
+
+
+def _writable_dirs(config: CodexSandboxConfig, ctx: ArgvContext) -> list[str]:
+    """The directories *config* lets sandboxed commands write, where known."""
+    if config.mode != "workspace-write":
+        return []
+    dirs = list(config.writable_roots)
+    if ctx.cwd:
+        dirs.append(ctx.cwd)
+    if config.writable_tmp:
+        dirs.append("/tmp")  # noqa: S108 - Codex's own writable /tmp
+        tmpdir = ctx.env.get("TMPDIR")
+        if tmpdir:
+            dirs.append(tmpdir)
+    return dirs
+
+
+def _is_within(path: str, directory: str) -> bool:
+    resolved, parent = os.path.realpath(path), os.path.realpath(directory)
+    return resolved == parent or resolved.startswith(parent.rstrip(os.sep) + os.sep)
+
+
 def _is_missing_rollout(stderr: str) -> bool:
     return "thread/resume failed" in stderr and "no rollout found" in stderr
 
@@ -335,7 +396,10 @@ def parse_sandbox(argv: Sequence[str]) -> CodexSandboxConfig | None:
 
     Returns:
         ``None`` when the turn bypassed Codex's sandbox, else the config it
-        imposed.
+        imposed. ``excluded_commands`` is always empty: exemptions live in the
+        rules file under ``CODEX_HOME``, not in argv (read them back with
+        ``parse_rules``). The absence of ``--ignore-rules`` is the argv's only
+        sign that the turn loaded rules.
 
     Raises:
         ValueError: *argv* neither bypasses the sandbox nor selects a mode.