agentshim 0.6.5__tar.gz → 0.6.7__tar.gz

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

@@ -1,5 +1,67 @@
 # 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.
+
+### 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

{agentshim-0.6.5 → agentshim-0.6.7}/PKG-INFO

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

{agentshim-0.6.5 → agentshim-0.6.7}/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.5"
+__version__ = "0.6.7"
 
 __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.5 → 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.5 → 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.5 → agentshim-0.6.7}/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.5 → agentshim-0.6.7}/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.5 → agentshim-0.6.7}/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.7/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.7/agentshim/providers/codex/__init__.py

@@ -0,0 +1,35 @@
+"""Codex."""
+
+from __future__ import annotations
+
+from .parser import CodexStreamParser
+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.7/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)