agentshim 0.6.4__tar.gz → 0.6.6__tar.gz

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

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.6.6 (2026-09-27)
+
+Additive: every new option defaults to earlier behaviour.
+
+### Added
+
+- `CodexProvider(sandbox=CodexSandboxConfig(...))` keeps Codex's own OS
+  sandbox on instead of bypassing it. `mode` is `read-only`,
+  `workspace-write` (default) or `danger-full-access`; `workspace-write` also
+  takes absolute `writable_roots`, `network_access` and `writable_tmp`. The
+  config is rendered as `--config` overrides so resumed turns keep it, pins
+  every `workspace-write` key so user config cannot widen it, and pins
+  `approval_policy="never"`. Invalid combinations raise on construction.
+  Without a config the argv is unchanged.
+- `agentshim.providers.codex.parse_sandbox(argv)` inverts that rendering.
+- `ClaudeProvider(hooks=[ClaudeHook(event, command, matcher, timeout_s)])`
+  adds caller hooks to the turn's inline settings, after agentshim's own
+  read-confinement hook. `command` is an argv quoted with `shlex.join`. Hooks
+  work with or without a sandbox. `build_settings` now takes
+  `SandboxConfig | None` and a keyword `hooks`; existing calls are unchanged.
+- Hypothesis property tests, with a `fuzz` profile (`HYPOTHESIS_PROFILE=fuzz`).
+- Cheap-model e2e knobs `AGENTSHIM_E2E_CLAUDE_MODEL` and
+  `AGENTSHIM_E2E_CODEX_MODEL`, and a credential-free Codex sandbox
+  enforcement matrix that runs whenever `codex` is installed.
+
+### Fixed
+
+- Codex `--config` string values escape control characters. A newline or
+  other control character in an MCP command, argument, env value or `PATH`
+  used to produce invalid TOML, which Codex silently keeps as a raw string.
+
+## 0.6.5 (2026-09-27)
+
+- Mark invocation-scoped Codex MCP servers as required so slow servers remain
+  in the initial tool catalog and honor their configured startup timeout.
+
 ## 0.6.4 (2026-09-27)
 
 - Add optional positive finite `startup_timeout_s` to stdio and HTTP MCP

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

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

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

@@ -78,13 +78,13 @@ from .execution import (
     TransformingExecutor,
 )
 from .providers import get_provider, provider_names
-from .providers.claude import ClaudeProvider, SandboxConfig
-from .providers.codex import CodexProvider
+from .providers.claude import ClaudeHook, ClaudeProvider, SandboxConfig
+from .providers.codex import CodexProvider, CodexSandboxConfig
 from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
 
-__version__ = "0.6.4"
+__version__ = "0.6.6"
 
 __all__ = [
     "AgentEvent",
@@ -94,6 +94,7 @@ __all__ = [
     "ArgvContext",
     "AssistantText",
     "CallbackCommandStreamSink",
+    "ClaudeHook",
     "ClaudeProvider",
     "CliAgent",
     "CliCheckError",
@@ -101,6 +102,7 @@ __all__ = [
     "CliNotFoundError",
     "CliTimeoutError",
     "CodexProvider",
+    "CodexSandboxConfig",
     "CommandExecutor",
     "CommandHandle",
     "CommandRequest",

{agentshim-0.6.4 → agentshim-0.6.6}/agentshim/providers/claude/__init__.py

@@ -6,9 +6,11 @@ from .parser import ClaudeStreamParser
 from .provider import PROFILE, ClaudeProvider, mcp_entry
 from .sandbox import SandboxConfig, build_settings, resolve_sandbox
 from .scripted import resume_failure_lines, scripted_lines
+from .user_hooks import ClaudeHook
 
 __all__ = [
     "PROFILE",
+    "ClaudeHook",
     "ClaudeProvider",
     "ClaudeStreamParser",
     "SandboxConfig",

{agentshim-0.6.4 → agentshim-0.6.6}/agentshim/providers/claude/provider.py

@@ -11,6 +11,7 @@ from agentshim.core.profile import McpMechanism, OutputSchemaStyle, ProviderProf
 
 from .parser import ClaudeStreamParser
 from .sandbox import SANDBOX_ENV, SandboxConfig, build_settings, resolve_sandbox
+from .user_hooks import ClaudeHook, resolve_hooks
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
@@ -66,17 +67,24 @@ PROFILE = ProviderProfile(
 
 
 class ClaudeProvider:
-    """Claude Code. ``sandbox`` is a provider option, not a portable one."""
+    """Claude Code. ``sandbox`` and ``hooks`` are provider options, not portable ones."""
 
     profile = PROFILE
 
-    def __init__(self, *, sandbox: bool | SandboxConfig | None = None) -> None:
-        """Fix the sandbox option for every turn this provider runs.
-
-        ``True`` takes the default config; ``None`` and ``False`` both mean
-        unsandboxed.
+    def __init__(
+        self,
+        *,
+        sandbox: bool | SandboxConfig | None = None,
+        hooks: Sequence[ClaudeHook] = (),
+    ) -> None:
+        """Fix the sandbox and hooks for every turn this provider runs.
+
+        ``sandbox=True`` takes the default config; ``None`` and ``False`` both
+        mean unsandboxed. ``hooks`` are added to the settings Claude Code
+        loads for the turn, after agentshim's own read-confinement hook.
         """
         self.sandbox: SandboxConfig | None = resolve_sandbox(sandbox)
+        self.hooks: tuple[ClaudeHook, ...] = resolve_hooks(hooks)
 
     @property
     def sandbox_env(self) -> dict[str, str]:
@@ -106,8 +114,9 @@ class ClaudeProvider:
             argv += ["--effort", ctx.reasoning_effort]
         if ctx.schema_inline:
             argv += ["--json-schema", ctx.schema_inline]
-        if self.sandbox is not None:
-            argv += ["--settings", json.dumps(build_settings(self.sandbox))]
+        settings = build_settings(self.sandbox, hooks=self.hooks)
+        if settings:
+            argv += ["--settings", json.dumps(settings)]
         argv += list(ctx.mcp_argv)
         argv += list(ctx.extra_args)
         return argv

{agentshim-0.6.4 → agentshim-0.6.6}/agentshim/providers/claude/sandbox.py

@@ -16,7 +16,14 @@ import shlex
 import sys
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+from .user_hooks import merge_hooks, render_hooks
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from .user_hooks import ClaudeHook
 
 # ``absolute()`` rather than ``resolve()``: the hook path is only handed back to
 # the interpreter, and an install reached through a symlinked tree should keep
@@ -94,8 +101,33 @@ def resolve_sandbox(value: object) -> SandboxConfig | None:
     raise TypeError(msg)
 
 
-def build_settings(config: SandboxConfig) -> dict[str, Any]:
-    """Build the ``settings.json`` payload that enables the sandbox."""
+def build_settings(
+    config: SandboxConfig | None, *, hooks: Sequence[ClaudeHook] = ()
+) -> dict[str, Any]:
+    """Build the inline ``settings.json`` payload for a turn.
+
+    Args:
+        config: The sandbox to enable, or ``None`` for no ``sandbox`` block.
+        hooks: Caller hooks, appended after agentshim's own read-confinement
+            hook on the same event, so neither replaces the other.
+
+    Returns:
+        The settings object; empty when there is nothing to set.
+    """
+    settings: dict[str, Any] = {}
+    own_hooks: dict[str, list[dict[str, Any]]] = {}
+    if config is not None:
+        settings["sandbox"] = _sandbox_block(config)
+        if config.confine_native_reads_to:
+            own_hooks = _confine_reads_hook(config.confine_native_reads_to)
+    merged = merge_hooks(own_hooks, render_hooks(hooks))
+    if merged:
+        settings["hooks"] = merged
+    return settings
+
+
+def _sandbox_block(config: SandboxConfig) -> dict[str, Any]:
+    """Build the ``sandbox`` key of the settings object."""
     sandbox: dict[str, Any] = {
         "enabled": True,
         "failIfUnavailable": config.fail_if_unavailable,
@@ -121,11 +153,7 @@ def build_settings(config: SandboxConfig) -> dict[str, Any]:
         sandbox["network"] = {"allowedDomains": list(config.allowed_domains)}
 
     sandbox.update(config.extra_settings)
-
-    settings: dict[str, Any] = {"sandbox": sandbox}
-    if config.confine_native_reads_to:
-        settings["hooks"] = _confine_reads_hook(config.confine_native_reads_to)
-    return settings
+    return sandbox
 
 
 def _confine_reads_hook(roots: list[str]) -> dict[str, Any]:

agentshim-0.6.6/agentshim/providers/claude/user_hooks.py

@@ -0,0 +1,142 @@
+"""Caller-supplied Claude Code hooks.
+
+Claude Code runs a hook command on an event such as ``PreToolUse`` and acts
+on the JSON it prints, which is how a caller enforces a policy the sandbox
+cannot express, for example refusing one executable in Bash. agentshim
+already passes its own settings inline through ``--settings``; a second
+``--settings`` in ``extra_args`` would compete with that one, so the provider
+takes hooks as an option and merges them into the single settings object.
+
+See https://code.claude.com/docs/en/hooks.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import shlex
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, cast
+
+#: Claude Code's hook events are PascalCase names. New events appear between
+#: CLI releases, so the shape is checked rather than a closed list.
+_EVENT_RE = re.compile(r"[A-Z][A-Za-z]*")
+
+
+@dataclass(frozen=True)
+class ClaudeHook:
+    """One command Claude Code runs on a hook event.
+
+    Attributes:
+        event: The hook event, such as ``PreToolUse`` or ``PostToolUse``.
+        command: The hook's argv. Claude Code runs hooks through a shell, so
+            agentshim quotes it with ``shlex.join``: every element reaches the
+            process literally, whatever it contains. Use an absolute
+            executable path; the agent's PATH is not the caller's. Any
+            sequence of strings is accepted and stored as a tuple.
+        matcher: For tool events, the tool-name pattern the hook applies to,
+            such as ``Bash`` or ``Edit|Write``. ``None`` matches every tool.
+        timeout_s: Seconds Claude Code allows the hook before giving up;
+            ``None`` keeps the CLI default.
+    """
+
+    event: str
+    command: Sequence[str]
+    matcher: str | None = None
+    timeout_s: float | None = None
+
+    def __post_init__(self) -> None:
+        """Reject a hook Claude Code would refuse or run incorrectly."""
+        _check_event(self.event)
+        object.__setattr__(self, "command", _as_argv(self.command))
+        _check_matcher(self.matcher)
+        if self.timeout_s is not None and not _positive_finite(self.timeout_s):
+            msg = f"timeout_s must be a positive finite number, got {self.timeout_s!r}"
+            raise ValueError(msg)
+
+
+def _check_event(event: object) -> None:
+    if not isinstance(event, str) or not _EVENT_RE.fullmatch(event):
+        msg = f"event must be a PascalCase hook event name, got {event!r}"
+        raise ValueError(msg)
+
+
+def _check_matcher(matcher: object) -> None:
+    if matcher is not None and (not isinstance(matcher, str) or not matcher):
+        msg = f"matcher must be a non-empty string or None, got {matcher!r}"
+        raise ValueError(msg)
+
+
+def _as_argv(value: object) -> tuple[str, ...]:
+    """Validate a hook command and freeze it into a tuple.
+
+    A bare string is rejected rather than split: ``"python3 hook.py"`` would
+    otherwise become one argv element naming a file that does not exist.
+    """
+    if isinstance(value, str) or not isinstance(value, Sequence):
+        msg = f"command must be an argv sequence, not {type(value).__name__}"
+        raise TypeError(msg)
+    argv = tuple(cast("Sequence[object]", value))
+    if not argv:
+        msg = "command must not be empty"
+        raise ValueError(msg)
+    for arg in argv:
+        if not isinstance(arg, str):
+            msg = f"command elements must be str, got {type(arg).__name__}"
+            raise TypeError(msg)
+        if "\x00" in arg:
+            msg = f"command element contains a NUL byte: {arg!r}"
+            raise ValueError(msg)
+        try:
+            arg.encode("utf-8")
+        except UnicodeEncodeError:
+            msg = f"command element is not valid UTF-8 text: {arg!r}"
+            raise ValueError(msg) from None
+    return cast("tuple[str, ...]", argv)
+
+
+def _positive_finite(value: object) -> bool:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return False
+    return math.isfinite(value) and value > 0
+
+
+def resolve_hooks(value: object) -> tuple[ClaudeHook, ...]:
+    """Normalize the ``hooks`` provider option to a tuple of hooks."""
+    if isinstance(value, ClaudeHook) or not isinstance(value, Sequence):
+        msg = f"hooks must be a sequence of ClaudeHook, got {type(value).__name__}"
+        raise TypeError(msg)
+    hooks = tuple(cast("Sequence[object]", value))
+    for hook in hooks:
+        if not isinstance(hook, ClaudeHook):
+            msg = f"hooks must contain ClaudeHook, got {type(hook).__name__}"
+            raise TypeError(msg)
+    return cast("tuple[ClaudeHook, ...]", hooks)
+
+
+def render_hooks(hooks: Sequence[ClaudeHook]) -> dict[str, list[dict[str, Any]]]:
+    """Render *hooks* as a settings ``hooks`` block, one entry per hook.
+
+    Entries keep the caller's order within each event. One entry per hook,
+    rather than grouping by matcher, keeps every hook's timeout its own.
+    """
+    block: dict[str, list[dict[str, Any]]] = {}
+    for hook in hooks:
+        handler: dict[str, Any] = {"type": "command", "command": shlex.join(hook.command)}
+        if hook.timeout_s is not None:
+            handler["timeout"] = hook.timeout_s
+        entry: dict[str, Any] = {"hooks": [handler]}
+        if hook.matcher is not None:
+            entry["matcher"] = hook.matcher
+        block.setdefault(hook.event, []).append(entry)
+    return block
+
+
+def merge_hooks(*blocks: dict[str, list[dict[str, Any]]]) -> dict[str, list[dict[str, Any]]]:
+    """Concatenate hook blocks event by event, earlier blocks first."""
+    merged: dict[str, list[dict[str, Any]]] = {}
+    for block in blocks:
+        for event, entries in block.items():
+            merged.setdefault(event, []).extend(entries)
+    return merged

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

@@ -3,14 +3,20 @@
 from __future__ import annotations
 
 from .parser import CodexStreamParser
-from .provider import PROFILE, CodexProvider, parse_mcp_servers
+from .provider import BYPASS_FLAG, PROFILE, CodexProvider, parse_mcp_servers, parse_sandbox
+from .sandbox import SANDBOX_MODES, CodexSandboxConfig, SandboxMode
 from .scripted import resume_failure_lines, scripted_lines
 
 __all__ = [
+    "BYPASS_FLAG",
     "PROFILE",
+    "SANDBOX_MODES",
     "CodexProvider",
+    "CodexSandboxConfig",
     "CodexStreamParser",
+    "SandboxMode",
     "parse_mcp_servers",
+    "parse_sandbox",
     "resume_failure_lines",
     "scripted_lines",
 ]

agentshim-0.6.6/agentshim/providers/codex/_toml.py

@@ -0,0 +1,90 @@
+"""TOML literals for Codex's ``--config key=value`` overrides.
+
+Codex parses the value of each override as TOML and, when that fails, uses
+the raw text as a string instead. A malformed literal therefore does not
+error: it silently changes the value's type. Everything this provider puts in
+an override goes through these helpers, and ``unescape_toml`` inverts
+``toml_str`` so the argv parsers can read back exactly what was rendered.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+#: TOML's short escapes. Every other control character becomes ``\\uXXXX``.
+_SHORT_ESCAPES = {
+    "\\": "\\\\",
+    '"': '\\"',
+    "\b": "\\b",
+    "\t": "\\t",
+    "\n": "\\n",
+    "\f": "\\f",
+    "\r": "\\r",
+}
+_UNESCAPES = {escape[1]: char for char, escape in _SHORT_ESCAPES.items()}
+_UNICODE_ESCAPE_WIDTHS = {"u": 4, "U": 8}
+_DEL = 0x7F
+_FIRST_PRINTABLE = 0x20
+
+
+def toml_str(value: str) -> str:
+    """Quote *value* as a TOML basic string that parses back to *value*.
+
+    TOML forbids raw control characters in a basic string, and Codex treats
+    an override that fails to parse as TOML as a raw literal instead, so an
+    unescaped newline would silently change the value's type.
+    """
+    parts: list[str] = []
+    for char in value:
+        if char in _SHORT_ESCAPES:
+            parts.append(_SHORT_ESCAPES[char])
+        elif ord(char) < _FIRST_PRINTABLE or ord(char) == _DEL:
+            parts.append(f"\\u{ord(char):04X}")
+        else:
+            parts.append(char)
+    return '"' + "".join(parts) + '"'
+
+
+def toml_array(values: Sequence[str]) -> str:
+    """Render strings as a TOML inline array."""
+    return "[" + ",".join(toml_str(value) for value in values) + "]"
+
+
+def toml_bool(value: bool) -> str:  # noqa: FBT001 - a value, not a mode switch
+    """Render a TOML boolean."""
+    return "true" if value else "false"
+
+
+def unescape_toml(body: str) -> str:
+    """Invert ``toml_str`` on the text between the quotes.
+
+    Raises:
+        ValueError: *body* holds an escape ``toml_str`` never writes.
+    """
+    result: list[str] = []
+    index = 0
+    while index < len(body):
+        char = body[index]
+        if char != "\\":
+            result.append(char)
+            index += 1
+            continue
+        code = body[index + 1 : index + 2]
+        if code in _UNESCAPES:
+            result.append(_UNESCAPES[code])
+            index += 2
+        elif code in _UNICODE_ESCAPE_WIDTHS:
+            width = _UNICODE_ESCAPE_WIDTHS[code]
+            digits = body[index + 2 : index + 2 + width]
+            if len(digits) != width:
+                msg = f"truncated \\{code} escape in {body!r}"
+                raise ValueError(msg)
+            result.append(chr(int(digits, 16)))
+            index += 2 + width
+        else:
+            msg = f"invalid TOML escape \\{code} in {body!r}"
+            raise ValueError(msg)
+    return "".join(result)

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

@@ -14,7 +14,9 @@ from agentshim.core.profile import (
     SchemaDialect,
 )
 
+from ._toml import toml_array, toml_str, unescape_toml
 from .parser import CodexStreamParser
+from .sandbox import CodexSandboxConfig, resolve_sandbox, sandbox_overrides
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping, Sequence
@@ -85,11 +87,24 @@ PROFILE = ProviderProfile(
 )
 
 
+#: Turns off both Codex's sandbox and its approval prompts.
+BYPASS_FLAG = "--dangerously-bypass-approvals-and-sandbox"
+
+
 class CodexProvider:
-    """Codex (``codex exec --json``)."""
+    """Codex (``codex exec --json``). ``sandbox`` is a provider option."""
 
     profile = PROFILE
 
+    def __init__(self, *, sandbox: CodexSandboxConfig | None = None) -> None:
+        """Fix the sandbox for every turn this provider runs.
+
+        ``None``, the default, bypasses Codex's sandbox and approvals, for a
+        caller that isolates the whole process itself. A
+        ``CodexSandboxConfig`` keeps the CLI's own sandbox on instead.
+        """
+        self.sandbox: CodexSandboxConfig | None = resolve_sandbox(sandbox)
+
     def build_argv(self, ctx: ArgvContext) -> list[str]:
         """Build the ``codex exec`` command line for one turn.
 
@@ -101,18 +116,27 @@ class CodexProvider:
         argv = [ctx.binary_path, "exec"]
         if ctx.resume_session_id:
             argv += ["resume", ctx.resume_session_id, "-"]
-        argv += ["--dangerously-bypass-approvals-and-sandbox", "--skip-git-repo-check", "--json"]
+        argv += self._sandbox_argv()
+        argv += ["--skip-git-repo-check", "--json"]
         if ctx.model:
             argv += ["--model", ctx.model]
         argv += _shell_path_config(ctx.env)
         if ctx.reasoning_effort:
-            argv += ["--config", f"model_reasoning_effort={_toml_str(ctx.reasoning_effort)}"]
+            argv += ["--config", f"model_reasoning_effort={toml_str(ctx.reasoning_effort)}"]
         argv += list(ctx.mcp_argv)
         if ctx.schema_path:
             argv += ["--output-schema", ctx.schema_path]
         argv += list(ctx.extra_args)
         return argv
 
+    def _sandbox_argv(self) -> list[str]:
+        if self.sandbox is None:
+            return [BYPASS_FLAG]
+        argv: list[str] = []
+        for key, value in sandbox_overrides(self.sandbox):
+            argv += ["--config", f"{key}={value}"]
+        return argv
+
     def new_parser(
         self,
         emit: Callable[[AgentEvent], None],
@@ -173,7 +197,7 @@ def _shell_path_config(env: Mapping[str, str]) -> list[str]:
     path = env.get("PATH")
     if not path:
         return []
-    return ["--config", f"shell_environment_policy.set.PATH={_toml_str(path)}"]
+    return ["--config", f"shell_environment_policy.set.PATH={toml_str(path)}"]
 
 
 def _server_flags(server: McpServer) -> list[str]:
@@ -189,16 +213,23 @@ def _server_flags(server: McpServer) -> list[str]:
             raise ProviderCapabilityError(_HTTP_HEADERS_UNSUPPORTED)
         # A ``--config`` override carries the address and nothing else, so
         # Codex works the transport out from the endpoint itself.
-        flags = ["--config", f"{prefix}.url={_toml_str(server.url)}"]
+        flags = [
+            "--config",
+            f"{prefix}.url={toml_str(server.url)}",
+            "--config",
+            f"{prefix}.required=true",
+        ]
         return flags + _timeout_flags(prefix, server)
     flags = [
         "--config",
-        f"{prefix}.command={_toml_str(server.command)}",
+        f"{prefix}.command={toml_str(server.command)}",
+        "--config",
+        f"{prefix}.args={toml_array(list(server.args))}",
         "--config",
-        f"{prefix}.args={_toml_array(list(server.args))}",
+        f"{prefix}.required=true",
     ]
     for env_key, env_value in server.env.items():
-        flags += ["--config", f"{prefix}.env.{env_key}={_toml_str(env_value)}"]
+        flags += ["--config", f"{prefix}.env.{env_key}={toml_str(env_value)}"]
     return flags + _timeout_flags(prefix, server)
 
 
@@ -212,17 +243,6 @@ def _timeout_flags(prefix: str, server: McpServer) -> list[str]:
     return flags
 
 
-def _toml_str(value: str) -> str:
-    """Quote *value* as a TOML basic string literal."""
-    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
-    return f'"{escaped}"'
-
-
-def _toml_array(values: Sequence[str]) -> str:
-    """Render a sequence of strings as a TOML inline array."""
-    return "[" + ",".join(_toml_str(value) for value in values) + "]"
-
-
 _CONFIG_OVERRIDE_RE = re.compile(r"^mcp_servers\.([^.=]+)\.(.+)$")
 _TOML_STRING_RE = re.compile(r'"((?:[^"\\]|\\.)*)"')
 
@@ -257,14 +277,8 @@ def parse_mcp_servers(argv: Sequence[str]) -> dict[str, dict[str, Any]]:
 
 def _mcp_config_overrides(argv: Sequence[str]) -> list[tuple[str, str, str]]:
     """Pull every ``mcp_servers.<key>.<field>=<value>`` override out of *argv*."""
-    args = list(argv)
     overrides: list[tuple[str, str, str]] = []
-    for index, arg in enumerate(args):
-        if arg != "--config" or index + 1 >= len(args):
-            continue
-        path, sep, raw_value = args[index + 1].partition("=")
-        if not sep:
-            continue
+    for path, raw_value in _config_overrides(argv):
         match = _CONFIG_OVERRIDE_RE.match(path)
         if match is not None:
             key, field = match.groups()
@@ -275,43 +289,79 @@ def _mcp_config_overrides(argv: Sequence[str]) -> list[tuple[str, str, str]]:
 def _apply_mcp_override(entry: dict[str, Any], field: str, raw_value: str) -> None:
     """Fold one dotted-path override into the entry being rebuilt for it."""
     if field == "command":
-        entry["command"] = _parse_toml_str(raw_value)
+        entry["command"] = _parsetoml_str(raw_value)
     elif field == "args":
-        entry["args"] = _parse_toml_array(raw_value)
+        entry["args"] = _parsetoml_array(raw_value)
     elif field == "url":
-        entry["url"] = _parse_toml_str(raw_value)
+        entry["url"] = _parsetoml_str(raw_value)
         entry["transport"] = "http"
     elif field == "tool_timeout_sec":
         entry["tool_timeout_s"] = float(raw_value)
     elif field == "startup_timeout_sec":
         entry["startup_timeout_s"] = float(raw_value)
     elif field.startswith("env."):
-        entry.setdefault("env", {})[field.removeprefix("env.")] = _parse_toml_str(raw_value)
+        entry.setdefault("env", {})[field.removeprefix("env.")] = _parsetoml_str(raw_value)
 
 
-def _parse_toml_str(literal: str) -> str:
-    """Reverse ``_toml_str``: unescape one TOML basic string literal."""
+def _parsetoml_str(literal: str) -> str:
+    """Reverse ``toml_str``: unescape one TOML basic string literal."""
     match = _TOML_STRING_RE.fullmatch(literal)
     if match is None:
         return literal
-    return _unescape_toml(match.group(1))
-
-
-def _parse_toml_array(literal: str) -> list[str]:
-    """Reverse ``_toml_array``: unescape every string in a TOML inline array."""
-    return [_unescape_toml(inner) for inner in _TOML_STRING_RE.findall(literal)]
-
-
-def _unescape_toml(escaped: str) -> str:
-    """Undo the backslash-escaping ``_toml_str`` applies to a string body."""
-    result: list[str] = []
-    index = 0
-    while index < len(escaped):
-        char = escaped[index]
-        if char == "\\" and index + 1 < len(escaped):
-            result.append(escaped[index + 1])
-            index += 2
-        else:
-            result.append(char)
-            index += 1
-    return "".join(result)
+    return unescape_toml(match.group(1))
+
+
+def _parsetoml_array(literal: str) -> list[str]:
+    """Reverse ``toml_array``: unescape every string in a TOML inline array."""
+    return [unescape_toml(inner) for inner in _TOML_STRING_RE.findall(literal)]
+
+
+_SANDBOX_KEYS = {
+    "sandbox_mode",
+    "sandbox_workspace_write.writable_roots",
+    "sandbox_workspace_write.network_access",
+    "sandbox_workspace_write.exclude_slash_tmp",
+}
+
+
+def parse_sandbox(argv: Sequence[str]) -> CodexSandboxConfig | None:
+    """Recover the sandbox rendered into *argv* by ``CodexProvider``.
+
+    The inverse of ``CodexProvider._sandbox_argv``, kept next to it so the
+    two cannot drift.
+
+    Args:
+        argv: The argv a turn actually ran, as recorded on a ``CommandRequest``.
+
+    Returns:
+        ``None`` when the turn bypassed Codex's sandbox, else the config it
+        imposed.
+
+    Raises:
+        ValueError: *argv* neither bypasses the sandbox nor selects a mode.
+    """
+    if BYPASS_FLAG in argv:
+        return None
+    overrides = {key: value for key, value in _config_overrides(argv) if key in _SANDBOX_KEYS}
+    if "sandbox_mode" not in overrides:
+        msg = f"argv neither bypasses nor selects a Codex sandbox: {list(argv)!r}"
+        raise ValueError(msg)
+    prefix = "sandbox_workspace_write"
+    return CodexSandboxConfig(
+        mode=_parsetoml_str(overrides["sandbox_mode"]),  # pyright: ignore[reportArgumentType]
+        writable_roots=_parsetoml_array(overrides.get(f"{prefix}.writable_roots", "[]")),
+        network_access=overrides.get(f"{prefix}.network_access") == "true",
+        writable_tmp=overrides.get(f"{prefix}.exclude_slash_tmp", "false") == "false",
+    )
+
+
+def _config_overrides(argv: Sequence[str]) -> list[tuple[str, str]]:
+    """Pull every ``--config key=value`` pair out of *argv*, in order."""
+    args = list(argv)
+    pairs: list[tuple[str, str]] = []
+    for index, arg in enumerate(args[:-1]):
+        if arg == "--config":
+            key, sep, value = args[index + 1].partition("=")
+            if sep:
+                pairs.append((key, value))
+    return pairs

agentshim-0.6.6/agentshim/providers/codex/sandbox.py

@@ -0,0 +1,158 @@
+"""Codex's OS sandbox for the commands the model runs.
+
+Codex confines model-generated shell commands itself (Landlock and seccomp on
+Linux, Seatbelt on macOS). By default agentshim turns that off with
+``--dangerously-bypass-approvals-and-sandbox``, which suits a caller that
+already isolates the whole process. ``CodexSandboxConfig`` keeps the CLI's own
+sandbox on instead.
+
+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.
+
+See https://developers.openai.com/codex/security.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Literal, cast, get_args
+
+from ._toml import toml_array, toml_bool, toml_str
+
+SandboxMode = Literal["read-only", "workspace-write", "danger-full-access"]
+
+#: Every mode Codex accepts, in its own spelling.
+SANDBOX_MODES: tuple[SandboxMode, ...] = get_args(SandboxMode)
+
+_WORKSPACE_WRITE: SandboxMode = "workspace-write"
+
+
+def _roots() -> tuple[str, ...]:
+    return ()
+
+
+@dataclass(frozen=True)
+class CodexSandboxConfig:
+    """How Codex sandboxes the commands the model runs.
+
+    Attributes:
+        mode: ``read-only`` lets commands read but not write anywhere and
+            blocks the network. ``workspace-write`` also lets them write the
+            working directory, ``writable_roots`` and (by default) the temp
+            directories. ``danger-full-access`` removes the sandbox but, unlike
+            the bypass flag, keeps Codex's approval policy in force.
+        writable_roots: Extra absolute directories commands may write.
+            ``workspace-write`` only. Any sequence of strings is accepted and
+            stored as a tuple, so equal configs compare and hash equal.
+        network_access: Let commands open network sockets, including local
+            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.
+    """
+
+    mode: SandboxMode = _WORKSPACE_WRITE
+    writable_roots: Sequence[str] = field(default_factory=_roots)
+    network_access: bool = False
+    writable_tmp: bool = True
+
+    def __post_init__(self) -> None:
+        """Reject a config Codex would reject or silently ignore."""
+        if self.mode not in SANDBOX_MODES:
+            msg = f"mode must be one of {', '.join(SANDBOX_MODES)}; got {self.mode!r}"
+            raise ValueError(msg)
+        object.__setattr__(self, "writable_roots", _as_roots(self.writable_roots))
+        for name in ("network_access", "writable_tmp"):
+            value: object = getattr(self, name)
+            if not isinstance(value, bool):
+                msg = f"{name} must be a bool, got {type(value).__name__}"
+                raise TypeError(msg)
+        if self.mode != _WORKSPACE_WRITE and self._widens_workspace_write():
+            msg = (
+                "writable_roots, network_access and writable_tmp only apply to "
+                f"workspace-write; {self.mode} would ignore them"
+            )
+            raise ValueError(msg)
+
+    def _widens_workspace_write(self) -> bool:
+        return bool(self.writable_roots) or self.network_access or not self.writable_tmp
+
+
+def _as_roots(value: object) -> tuple[str, ...]:
+    """Validate ``writable_roots`` and freeze it into a tuple.
+
+    A bare string is rejected rather than iterated, which would turn
+    ``"/data"`` into the roots ``"/"``, ``"d"``, ``"a"``, ... A set is
+    rejected too: its order is arbitrary, so the rendered argv would be.
+    """
+    if isinstance(value, str) or not isinstance(value, Sequence):
+        msg = f"writable_roots must be a sequence of paths, not {type(value).__name__}"
+        raise TypeError(msg)
+    roots = tuple(cast("Sequence[object]", value))
+    for root in roots:
+        _check_root(root)
+    return cast("tuple[str, ...]", roots)
+
+
+def _check_root(root: object) -> None:
+    if not isinstance(root, str):
+        msg = f"writable_roots entries must be str, got {type(root).__name__}"
+        raise TypeError(msg)
+    if "\x00" in root:
+        msg = f"writable_roots entry contains a NUL byte: {root!r}"
+        raise ValueError(msg)
+    if not _is_utf8(root):
+        msg = f"writable_roots entry is not valid UTF-8 text: {root!r}"
+        raise ValueError(msg)
+    if not os.path.isabs(root):  # noqa: PTH117 - a str contract, not a Path
+        msg = f"writable_roots entries must be absolute; got {root!r}"
+        raise ValueError(msg)
+
+
+def _is_utf8(text: str) -> bool:
+    """TOML and argv both need text that encodes; a lone surrogate does not."""
+    try:
+        text.encode("utf-8")
+    except UnicodeEncodeError:
+        return False
+    return True
+
+
+def resolve_sandbox(value: object) -> CodexSandboxConfig | None:
+    """Normalize the ``sandbox`` provider option to a config or ``None``.
+
+    ``None`` keeps agentshim's historical behaviour: Codex's sandbox and
+    approvals are bypassed. There is deliberately no ``True`` shorthand,
+    because no one mode is an obvious default for every caller.
+    """
+    if value is None or isinstance(value, CodexSandboxConfig):
+        return value
+    msg = f"sandbox must be a CodexSandboxConfig or None, got {type(value).__name__}"
+    raise TypeError(msg)
+
+
+def sandbox_overrides(config: CodexSandboxConfig) -> list[tuple[str, str]]:
+    """Return the ``(key, TOML value)`` pairs that impose *config*.
+
+    ``approval_policy = "never"`` rides along because a headless turn has no
+    one to approve anything: without it a command the sandbox refuses would
+    wait for an answer that never comes.
+    """
+    pairs = [
+        ("sandbox_mode", toml_str(config.mode)),
+        ("approval_policy", toml_str("never")),
+    ]
+    if config.mode == _WORKSPACE_WRITE:
+        prefix = "sandbox_workspace_write"
+        excluded = toml_bool(not config.writable_tmp)
+        pairs += [
+            (f"{prefix}.writable_roots", toml_array(config.writable_roots)),
+            (f"{prefix}.network_access", toml_bool(config.network_access)),
+            (f"{prefix}.exclude_slash_tmp", excluded),
+            (f"{prefix}.exclude_tmpdir_env_var", excluded),
+        ]
+    return pairs

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

@@ -1,6 +1,6 @@
 [project]
 name = "agentshim"
-version = "0.6.4"
+version = "0.6.6"
 description = "Provider-agnostic coding-agent CLI shims"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,10 +17,12 @@ build-backend = "hatchling.build"
 
 [dependency-groups]
 dev = [
+    "hypothesis>=6.168.1",
     "import-linter>=2.0",
     "pyright>=1.1.408",
     "pytest>=8.0.0",
     "ruff==0.15.12",
+    "tomli>=2 ; python_full_version < '3.11'",
 ]
 docs = [
     "mkdocs>=1.6.1",