agentshim 0.6.6__tar.gz → 0.6.7__tar.gz

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

@@ -1,5 +1,36 @@
 # Changelog
 
+## 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.7}/PKG-INFO

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

{agentshim-0.6.6 → agentshim-0.6.7}/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.7"
 
 __all__ = [
     "AgentEvent",

{agentshim-0.6.6 → agentshim-0.6.7}/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.7}/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.6 → agentshim-0.6.7}/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.7}/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.

agentshim-0.6.7/agentshim/providers/codex/rules.py

@@ -0,0 +1,125 @@
+"""Codex exec-policy rules that let named commands run outside the sandbox.
+
+Codex decides per command whether to sandbox it by evaluating exec-policy
+rules, Starlark files named ``*.rules``. A command whose words start with a
+``prefix_rule(..., decision="allow")`` pattern skips the sandbox; every other
+command stays confined. That is the Codex counterpart of Claude Code's
+``excludedCommands``, and the only per-command exemption Codex has: network
+and filesystem settings apply to the whole session.
+
+Codex reads rules only from files: ``$CODEX_HOME/rules/`` and the
+``.codex/rules/`` of trusted projects. There is no ``--config`` key for them,
+so ``CodexSandboxConfig.excluded_commands`` cannot travel in argv like the
+rest of the sandbox. ``install_rules`` writes them into a Codex home the
+caller dedicates to the sandboxed agent, and the turn points ``CODEX_HOME``
+at it. A sandboxed turn without exemptions passes ``--ignore-rules`` instead,
+so no rules file, the user's included, can widen it.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .sandbox import CodexSandboxConfig
+
+#: The file ``install_rules`` owns inside ``$CODEX_HOME/rules/``.
+RULES_FILENAME = "agentshim.rules"
+
+_HEADER = (
+    "# Written by agentshim from CodexSandboxConfig.excluded_commands.\n"
+    "# Each rule lets commands starting with these words run outside Codex's sandbox.\n"
+)
+_RULE_RE = re.compile(r'^prefix_rule\(pattern=\[(.*)\], decision="allow"\)$')
+_STRING_RE = re.compile(r'"((?:[^"\\]|\\["\\])*)"')
+
+
+def command_words(command: str) -> list[str]:
+    """Split one ``excluded_commands`` entry into the words Codex matches."""
+    return shlex.split(command)
+
+
+def render_rules(config: CodexSandboxConfig) -> str:
+    """Render *config*'s ``excluded_commands`` as a Codex ``.rules`` file."""
+    lines = [_HEADER]
+    for command in config.excluded_commands:
+        words = ", ".join(_starlark_str(word) for word in command_words(command))
+        lines.append(f'prefix_rule(pattern=[{words}], decision="allow")\n')
+    return "".join(lines)
+
+
+def parse_rules(text: str) -> list[list[str]]:
+    """Recover the word prefixes ``render_rules`` wrote, in order.
+
+    Raises:
+        ValueError: *text* holds a line ``render_rules`` never writes.
+    """
+    prefixes: list[list[str]] = []
+    for line in text.splitlines():
+        if not line or line.startswith("#"):
+            continue
+        match = _RULE_RE.match(line)
+        if match is None:
+            msg = f"not a rule agentshim writes: {line!r}"
+            raise ValueError(msg)
+        prefixes.append([_unescape(body) for body in _STRING_RE.findall(match.group(1))])
+    return prefixes
+
+
+def install_rules(codex_home: str | os.PathLike[str], config: CodexSandboxConfig) -> Path:
+    """Write *config*'s exemptions to ``<codex_home>/rules/agentshim.rules``.
+
+    Run the turn with ``CODEX_HOME`` set to *codex_home*. The home should be
+    dedicated to the sandboxed agent: every Codex process that uses it, and
+    does not pass ``--ignore-rules``, applies these rules. It must also lie
+    outside every directory the sandbox lets commands write, or a command
+    could add a rule of its own; ``CodexProvider`` refuses such a home.
+
+    The write is atomic, so a turn starting concurrently reads either the old
+    rules or the new ones.
+
+    Returns:
+        The path of the rules file.
+
+    Raises:
+        ValueError: ``rules/`` already holds another ``*.rules`` file. Codex
+            would load it too, so it could exempt commands the config does not.
+    """
+    rules_dir = Path(codex_home) / "rules"
+    rules_dir.mkdir(parents=True, exist_ok=True)
+    others = sorted(p.name for p in rules_dir.glob("*.rules") if p.name != RULES_FILENAME)
+    if others:
+        msg = (
+            f"{rules_dir} also holds {', '.join(others)}; Codex would load them "
+            "alongside the exemptions, so use a dedicated CODEX_HOME"
+        )
+        raise ValueError(msg)
+    target = rules_dir / RULES_FILENAME
+    fd, tmp = tempfile.mkstemp(dir=rules_dir, prefix=".agentshim-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(render_rules(config))
+        Path(tmp).replace(target)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+    return target
+
+
+def _starlark_str(word: str) -> str:
+    """Quote *word* as a Starlark string literal.
+
+    ``CodexSandboxConfig`` rejects control characters, so only the quote and
+    the backslash need escaping; everything else is written literally, which
+    Starlark accepts for any code point outside the surrogate range.
+    """
+    return '"' + word.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _unescape(body: str) -> str:
+    return re.sub(r'\\(["\\])', r"\1", body)

{agentshim-0.6.6 → agentshim-0.6.7}/agentshim/providers/codex/sandbox.py

@@ -10,7 +10,11 @@ Every setting is rendered as a ``--config`` override rather than ``--sandbox``,
 because ``codex exec resume`` accepts ``--config`` but not ``--sandbox``: one
 rendering serves fresh and resumed turns alike. For ``workspace-write`` every
 key is emitted explicitly, even at its default, so a user's
-``~/.codex/config.toml`` cannot widen the sandbox a caller asked for.
+``~/.codex/config.toml`` cannot widen the sandbox a caller asked for, and
+``--ignore-rules`` keeps its exec-policy ``.rules`` files from exempting
+commands. ``excluded_commands`` is the one exception: Codex reads exemptions
+only from rules files, so they go in a dedicated ``CODEX_HOME`` (see
+``rules.py``).
 
 See https://developers.openai.com/codex/security.
 """
@@ -18,6 +22,7 @@ See https://developers.openai.com/codex/security.
 from __future__ import annotations
 
 import os
+import shlex
 from collections.abc import Sequence
 from dataclasses import dataclass, field
 from typing import Literal, cast, get_args
@@ -30,12 +35,18 @@ SandboxMode = Literal["read-only", "workspace-write", "danger-full-access"]
 SANDBOX_MODES: tuple[SandboxMode, ...] = get_args(SandboxMode)
 
 _WORKSPACE_WRITE: SandboxMode = "workspace-write"
+_FIRST_PRINTABLE = 0x20
+_DEL = 0x7F
 
 
 def _roots() -> tuple[str, ...]:
     return ()
 
 
+def _commands() -> tuple[str, ...]:
+    return ()
+
+
 @dataclass(frozen=True)
 class CodexSandboxConfig:
     """How Codex sandboxes the commands the model runs.
@@ -53,12 +64,25 @@ class CodexSandboxConfig:
             ones such as the Docker socket. ``workspace-write`` only.
         writable_tmp: Keep ``/tmp`` and ``$TMPDIR`` writable, which is Codex's
             own default. ``workspace-write`` only.
+        excluded_commands: Commands that run outside the sandbox, each written
+            as shell words, e.g. ``"sdo detector check"``. An exempt command
+            runs with no confinement at all: it can write anywhere and reach
+            any socket the user can, so exempt only commands you trust with
+            whatever arguments the model adds. A command the model
+            runs is exempt when its words start with one of these, so
+            ``sdo detector check --all`` is exempt and ``sdo detector`` is not.
+            Anything else on the same command line (``&&``, ``|``, ``;``,
+            ``$(...)``) keeps the whole line sandboxed. ``read-only`` and
+            ``workspace-write`` only. Rendered as Codex exec-policy rules,
+            which must be installed in a dedicated ``CODEX_HOME`` with
+            ``install_rules``; see ``agentshim.providers.codex.rules``.
     """
 
     mode: SandboxMode = _WORKSPACE_WRITE
     writable_roots: Sequence[str] = field(default_factory=_roots)
     network_access: bool = False
     writable_tmp: bool = True
+    excluded_commands: Sequence[str] = field(default_factory=_commands)
 
     def __post_init__(self) -> None:
         """Reject a config Codex would reject or silently ignore."""
@@ -77,6 +101,10 @@ class CodexSandboxConfig:
                 f"workspace-write; {self.mode} would ignore them"
             )
             raise ValueError(msg)
+        object.__setattr__(self, "excluded_commands", _as_commands(self.excluded_commands))
+        if self.mode == "danger-full-access" and self.excluded_commands:
+            msg = "excluded_commands needs a sandbox to exempt from; danger-full-access has none"
+            raise ValueError(msg)
 
     def _widens_workspace_write(self) -> bool:
         return bool(self.writable_roots) or self.network_access or not self.writable_tmp
@@ -113,6 +141,37 @@ def _check_root(root: object) -> None:
         raise ValueError(msg)
 
 
+def _as_commands(value: object) -> tuple[str, ...]:
+    """Validate ``excluded_commands`` and freeze it into a tuple."""
+    if isinstance(value, str) or not isinstance(value, Sequence):
+        msg = f"excluded_commands must be a sequence of commands, not {type(value).__name__}"
+        raise TypeError(msg)
+    commands = tuple(cast("Sequence[object]", value))
+    for command in commands:
+        _check_command(command)
+    return cast("tuple[str, ...]", commands)
+
+
+def _check_command(command: object) -> None:
+    if not isinstance(command, str):
+        msg = f"excluded_commands entries must be str, got {type(command).__name__}"
+        raise TypeError(msg)
+    if any(ord(char) < _FIRST_PRINTABLE or ord(char) == _DEL for char in command):
+        msg = f"excluded_commands entry contains a control character: {command!r}"
+        raise ValueError(msg)
+    if not _is_utf8(command):
+        msg = f"excluded_commands entry is not valid UTF-8 text: {command!r}"
+        raise ValueError(msg)
+    try:
+        words = shlex.split(command)
+    except ValueError as exc:
+        msg = f"excluded_commands entry is not valid shell words ({exc}): {command!r}"
+        raise ValueError(msg) from exc
+    if not words or not all(words):
+        msg = f"excluded_commands entry must be non-empty words: {command!r}"
+        raise ValueError(msg)
+
+
 def _is_utf8(text: str) -> bool:
     """TOML and argv both need text that encodes; a lone surrogate does not."""
     try:

{agentshim-0.6.6 → agentshim-0.6.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentshim"
-version = "0.6.6"
+version = "0.6.7"
 description = "Provider-agnostic coding-agent CLI shims"
 readme = "README.md"
 requires-python = ">=3.10"