agentshim 0.11.0__tar.gz → 0.13.0__tar.gz

{agentshim-0.11.0 → agentshim-0.13.0}/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.13.0 (2026-10-03)
+
+A session can leave out the user's own CLI configuration. Additive.
+
+### Added
+
+- `ConfigScope` (`ALL`, `PROJECT`) as a session option on `start_session` and
+  `run`, `ProviderProfile.config_scopes`, and `ArgvContext.config_scope`.
+  `PROJECT` keeps the user's settings, hooks, global instructions, notify
+  commands, profiles and memory out of every turn. Claude Code:
+  `--setting-sources project,local` and `autoMemoryEnabled=false`. Codex: a
+  dedicated `CODEX_HOME` plus `--ignore-user-config --disable memories`;
+  `build_argv` refuses the scope in the user's own home. Copilot, Gemini and
+  opencode refuse it.
+- `ProviderProfile.config_home_files` and `prepare_config_home`, which build
+  that dedicated home holding only the login and return the environment that
+  points the CLI at it. The login is a symlink to the user's own `auth.json`,
+  so a refresh token Codex rotates in either home stays valid in both.
+
+## 0.12.0 (2026-10-03)
+
+A turn whose output never matched its schema says so. Additive except that
+Claude's `error_max_structured_output_retries` is no longer `OTHER`.
+
+### Added
+
+- `FailureKind.SCHEMA`: the provider gave up producing output that matches the
+  requested schema. Claude Code reports it for the
+  `error_max_structured_output_retries` result, with the validation errors of
+  the last rejected `StructuredOutput` call on `CliExitError.detail`. A resumed
+  turn that fails this way keeps its conversation. Codex never reports it:
+  `--output-schema` constrains decoding, so its output always parses against
+  the schema.
+- `scripted_failure("claude", FailureKind.SCHEMA)`.
+
+### Changed
+
+- `scripted_failure(provider, FailureKind.OTHER)` scripts a failure that is
+  not about the schema (Claude `error_during_execution`, Codex running out of
+  context). `scripted_failure("codex", FailureKind.SCHEMA)` raises
+  `ValueError`.
+
 ## 0.11.0 (2026-10-03)
 
 A failed turn says why it failed. Additive except that a classified failure of

{agentshim-0.11.0 → agentshim-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.11.0
+Version: 0.13.0
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Requires-Dist: tomli>=2; python_full_version < '3.11'
@@ -200,8 +200,11 @@ AgentShimError
 `CliExitError.kind` says why a turn failed, so a caller can pick a policy
 without knowing how any CLI words its errors: `TRANSIENT` (an overload, rate
 limit or server error that waiting may outlast), `USAGE_LIMIT` (a quota or
-billing limit), `AUTH` (credentials), or `OTHER`. Claude Code and Codex
-classify their failures; the other providers report `OTHER`.
+billing limit), `AUTH` (credentials), `SCHEMA` (the provider gave up producing
+output that matches the requested schema; `.detail` holds the last validation
+errors and the conversation survives, so a correction can follow), or `OTHER`.
+Claude Code and Codex classify their failures; the other providers report
+`OTHER`. Codex never reports `SCHEMA`: it constrains decoding to the schema.
 `agentshim.testing.scripted_failure(provider, kind)` scripts each one.
 
 ## Adding a provider

{agentshim-0.11.0 → agentshim-0.13.0}/README.md

@@ -190,8 +190,11 @@ AgentShimError
 `CliExitError.kind` says why a turn failed, so a caller can pick a policy
 without knowing how any CLI words its errors: `TRANSIENT` (an overload, rate
 limit or server error that waiting may outlast), `USAGE_LIMIT` (a quota or
-billing limit), `AUTH` (credentials), or `OTHER`. Claude Code and Codex
-classify their failures; the other providers report `OTHER`.
+billing limit), `AUTH` (credentials), `SCHEMA` (the provider gave up producing
+output that matches the requested schema; `.detail` holds the last validation
+errors and the conversation survives, so a correction can follow), or `OTHER`.
+Claude Code and Codex classify their failures; the other providers report
+`OTHER`. Codex never reports `SCHEMA`: it constrains decoding to the schema.
 `agentshim.testing.scripted_failure(provider, kind)` scripts each one.
 
 ## Adding a provider

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/__init__.py

@@ -19,6 +19,7 @@ from .core import (
     CliTimeoutError,
     CompositeEventHandler,
     ConfigFileInstallation,
+    ConfigScope,
     ConsoleEventHandler,
     EventHandlerBase,
     FailureKind,
@@ -79,6 +80,7 @@ from .core import (
     normalize,
     normalized_usage,
     parse_json_object,
+    prepare_config_home,
     price_for,
 )
 from .execution import (
@@ -99,7 +101,7 @@ from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
 
-__version__ = "0.11.0"
+__version__ = "0.13.0"
 
 __all__ = [
     "AgentEvent",
@@ -125,6 +127,7 @@ __all__ = [
     "CommandStreamSink",
     "CompositeEventHandler",
     "ConfigFileInstallation",
+    "ConfigScope",
     "ConsoleEventHandler",
     "CopilotProvider",
     "EventHandlerBase",
@@ -194,6 +197,7 @@ __all__ = [
     "normalize",
     "normalized_usage",
     "parse_json_object",
+    "prepare_config_home",
     "price_for",
     "provider_names",
 ]

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/agent.py

@@ -24,6 +24,7 @@ from agentshim.core.errors import (
 )
 from agentshim.core.events import RunFinished, RunStarted, compose_event_handlers
 from agentshim.core.profile import (
+    ConfigScope,
     McpMechanism,
     McpScope,
     OutputSchemaStyle,
@@ -114,7 +115,7 @@ class CliAgent:
         self.executor.check_binary(self.binary_path, self.env, timeout=check_timeout)
         self.log(f"{self.profile.display_name} ready at {self.binary_path}")
 
-    def start_session(
+    def start_session(  # noqa: PLR0913 - one keyword per independent session option
         self,
         *,
         cwd: str | None = None,
@@ -122,11 +123,12 @@ class CliAgent:
         session_id: str | None = None,
         skill_scope: SkillScope = SkillScope.ALL,
         mcp_scope: McpScope = McpScope.ALL,
+        config_scope: ConfigScope = ConfigScope.ALL,
     ) -> AgentSession:
         """Open a conversation whose turns resume one another.
 
-        ``skill_scope`` and ``mcp_scope`` are fixed for the conversation (see
-        ``AgentSession``).
+        ``skill_scope``, ``mcp_scope`` and ``config_scope`` are fixed for the
+        conversation (see ``AgentSession``).
         """
         return AgentSession(
             self,
@@ -135,9 +137,10 @@ class CliAgent:
             session_id=session_id,
             skill_scope=skill_scope,
             mcp_scope=mcp_scope,
+            config_scope=config_scope,
         )
 
-    def run(
+    def run(  # noqa: PLR0913 - one keyword per independent session option
         self,
         request: TurnRequest | str,
         *,
@@ -145,10 +148,15 @@ class CliAgent:
         timeout: float | None = None,
         skill_scope: SkillScope = SkillScope.ALL,
         mcp_scope: McpScope = McpScope.ALL,
+        config_scope: ConfigScope = ConfigScope.ALL,
     ) -> TurnResult:
         """Run one turn in a throwaway session."""
         session = self.start_session(
-            cwd=cwd, timeout=timeout, skill_scope=skill_scope, mcp_scope=mcp_scope
+            cwd=cwd,
+            timeout=timeout,
+            skill_scope=skill_scope,
+            mcp_scope=mcp_scope,
+            config_scope=config_scope,
         )
         return session.turn(request)
 
@@ -169,6 +177,7 @@ class AgentSession:
         session_id: str | None = None,
         skill_scope: SkillScope = SkillScope.ALL,
         mcp_scope: McpScope = McpScope.ALL,
+        config_scope: ConfigScope = ConfigScope.ALL,
     ) -> None:
         """Bind a conversation to one agent, with per-turn defaults.
 
@@ -183,6 +192,11 @@ class AgentSession:
         limits which MCP servers every turn's CLI may connect to
         (``McpScope.SESSION``: only those in ``TurnRequest.mcp_servers``) and
         is checked against ``profile.mcp_scopes`` the same way.
+        ``config_scope`` limits which of the user's own CLI configuration
+        (settings, hooks, global instructions, memory) every turn loads, and
+        is checked against ``profile.config_scopes``; a provider with
+        ``profile.config_home_files`` additionally needs its state root
+        pointed at a home from ``prepare_config_home``.
         """
         if skill_scope not in agent.profile.skill_scopes:
             msg = f"{agent.profile.name} cannot limit skills to scope {skill_scope.value!r}"
@@ -190,7 +204,11 @@ class AgentSession:
         if mcp_scope not in agent.profile.mcp_scopes:
             msg = f"{agent.profile.name} cannot limit MCP servers to scope {mcp_scope.value!r}"
             raise ProviderCapabilityError(msg)
+        if config_scope not in agent.profile.config_scopes:
+            msg = f"{agent.profile.name} cannot limit user configuration to scope {config_scope.value!r}"
+            raise ProviderCapabilityError(msg)
         self.skill_scope = skill_scope
+        self.config_scope = config_scope
         self.mcp_scope = mcp_scope
         self._agent = agent
         self._cwd = cwd
@@ -302,6 +320,7 @@ class AgentSession:
                     cwd=cwd,
                     skill_scope=self.skill_scope,
                     mcp_scope=self.mcp_scope,
+                    config_scope=self.config_scope,
                     mcp_servers=tuple(req.mcp_servers),
                 )
             )

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/core/__init__.py

@@ -43,6 +43,7 @@ from .events import (
     UsageReport,
     compose_event_handlers,
 )
+from .home import prepare_config_home
 from .mcp import (
     ConfigFileInstallation,
     FlagsInstallation,
@@ -55,6 +56,7 @@ from .mcp import (
 )
 from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
 from .profile import (
+    ConfigScope,
     McpMechanism,
     McpScope,
     OutputSchemaStyle,
@@ -82,6 +84,7 @@ __all__ = [
     "CliTimeoutError",
     "CompositeEventHandler",
     "ConfigFileInstallation",
+    "ConfigScope",
     "ConsoleEventHandler",
     "EventHandlerBase",
     "FailureKind",
@@ -142,5 +145,6 @@ __all__ = [
     "normalize",
     "normalized_usage",
     "parse_json_object",
+    "prepare_config_home",
     "price_for",
 ]

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/core/errors.py

@@ -29,6 +29,10 @@ class FailureKind(str, Enum):
     USAGE_LIMIT = "usage_limit"
     #: Missing, expired, or rejected credentials.
     AUTH = "auth"
+    #: The provider gave up producing output that matches the requested output
+    #: schema. ``detail`` carries the last validation errors it reported, and
+    #: the conversation survives: a correction can be sent as the next turn.
+    SCHEMA = "schema"
     #: Anything else, including every failure a provider cannot classify.
     OTHER = "other"
 

agentshim-0.13.0/agentshim/core/home.py

@@ -0,0 +1,90 @@
+"""Dedicated CLI homes for ``ConfigScope.PROJECT``.
+
+Some CLIs read the user's global instructions, hooks and memory from their
+state root (Codex: ``$CODEX_HOME/AGENTS.md``, ``hooks.json``, ``memories/``)
+with no flag to skip them. The only way to keep them out is to run the CLI
+against another state root that holds nothing but the credentials. That root
+is the caller's to own, because the CLI keeps its conversations there too: a
+session resumes only from the home it started in.
+
+The credentials are linked, not copied. Codex rotates its OAuth refresh token
+on refresh (the server rejects a reused one with ``refresh_token_reused``) and
+saves ``auth.json`` by opening it with ``O_TRUNC`` and writing in place
+(codex-rs ``login/src/auth/storage.rs``, ``FileAuthStorage::save``), which
+follows a symlink. A copy would strand one of the two logins after the first
+refresh; a link keeps a single file that every process rereads before it
+refreshes (``AuthManager::refresh_token``'s guarded reload).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ._files import real_path
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from .profile import ProviderProfile
+
+
+def state_root(profile: ProviderProfile, env: Mapping[str, str]) -> Path | None:
+    """The state root the CLI run with *env* reads, or ``None`` if it has none.
+
+    ``$<state_root_env>`` when set, else ``$HOME/<state_dirs[0]>``.
+    """
+    if profile.state_root_env and env.get(profile.state_root_env):
+        return Path(env[profile.state_root_env]).expanduser()
+    if not profile.state_dirs:
+        return None
+    home = env.get("HOME") or os.path.expanduser("~")  # noqa: PTH111 - a str contract, not a Path
+    return Path(home) / profile.state_dirs[0]
+
+
+def prepare_config_home(
+    profile: ProviderProfile, home: Path, env: Mapping[str, str]
+) -> dict[str, str]:
+    """Make *home* a state root holding only the credentials, and point at it.
+
+    Links each of ``profile.config_home_files`` that exists in the state root
+    *env* selects into *home* as a symlink to that file's real path (replacing
+    whatever was there, such as a copy from an older agentshim), so a token
+    the CLI refreshes in either home is the one both read next. Returns the
+    environment overrides that make the CLI use *home*. A sandbox that runs
+    the CLI must expose the link's target read-write. Everything else in *home* (conversations, caches) is the
+    CLI's own and is left alone. A provider with no ``config_home_files``
+    isolates by flags alone: nothing is written and the result is empty.
+
+    Raises:
+        ValueError: *home* is not absolute, or is the state root *env*
+            already selects, which would isolate nothing.
+    """
+    if not profile.config_home_files:
+        return {}
+    if not home.is_absolute():
+        msg = f"{profile.name} config home must be an absolute path, got {home}"
+        raise ValueError(msg)
+    assert profile.state_root_env is not None, "config_home_files needs a state_root_env"  # noqa: S101 - profile invariant
+    source = state_root(profile, env)
+    if source is not None and real_path(source) == real_path(home):
+        msg = f"{profile.name} config home {home} is the user's own state root"
+        raise ValueError(msg)
+    home.mkdir(parents=True, exist_ok=True)
+    for name in profile.config_home_files:
+        origin = None if source is None else source / name
+        if origin is not None and origin.is_file():
+            _link(home / name, real_path(origin))
+    return {profile.state_root_env: str(home)}
+
+
+def _link(link: Path, target: Path) -> None:
+    """Point *link* at *target*, atomically replacing any file already there."""
+    if link.is_symlink() and link.readlink() == target:
+        return
+    link.parent.mkdir(parents=True, exist_ok=True)
+    staged = link.with_name(f".{link.name}.{os.getpid()}.link")
+    staged.unlink(missing_ok=True)
+    staged.symlink_to(target)
+    staged.replace(link)

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/core/profile.py

@@ -93,6 +93,26 @@ class McpScope(Enum):
     SESSION = "session"
 
 
+class ConfigScope(Enum):
+    """Which of the user's own CLI configuration a session loads.
+
+    ``ALL``: whatever the CLI loads by default: the user's settings, hooks,
+    global instructions (``~/.claude/CLAUDE.md``, ``$CODEX_HOME/AGENTS.md``),
+    notify commands, profiles and memory. ``PROJECT``: none of that; the
+    session sees the workspace's own instructions and settings plus what
+    agentshim passes for the turn, so the user running agentshim does not
+    change what the agent does. Credentials keep working. A provider that
+    lists a ``ProviderProfile.config_home_files`` can only isolate through a
+    dedicated home: ``prepare_config_home`` builds it and returns the
+    environment that points the CLI at it. A provider declares the scopes it
+    can enforce in ``ProviderProfile.config_scopes``; asking for another one
+    is an error, never a silent ``ALL``.
+    """
+
+    ALL = "all"
+    PROJECT = "project"
+
+
 def _no_container_env() -> Mapping[str, str]:
     """Empty read-only default: a frozen spec must not carry a mutable one.
 
@@ -145,3 +165,10 @@ class ProviderProfile:
     skill_scopes: frozenset[SkillScope] = frozenset({SkillScope.ALL})
     #: The ``McpScope`` values a session on this provider may request.
     mcp_scopes: frozenset[McpScope] = frozenset({McpScope.ALL})
+    #: The ``ConfigScope`` values a session on this provider may request.
+    config_scopes: frozenset[ConfigScope] = frozenset({ConfigScope.ALL})
+    #: Files, relative to the state root (``state_dirs[0]``, or
+    #: ``$<state_root_env>``), that ``prepare_config_home`` copies into a
+    #: dedicated home for ``ConfigScope.PROJECT``. Empty when the provider
+    #: isolates by flags alone and needs no home.
+    config_home_files: tuple[str, ...] = ()

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/core/provider.py

@@ -6,7 +6,7 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Protocol
 
 from .errors import FailureKind
-from .profile import McpScope, SkillScope
+from .profile import ConfigScope, McpScope, SkillScope
 from .usage import ProviderUsage
 
 if TYPE_CHECKING:
@@ -49,6 +49,9 @@ class ArgvContext:
     #: A provider enforcing ``McpScope.SESSION`` renders them itself when its
     #: installed config file is not enough to exclude the user's own.
     mcp_servers: Sequence[McpServer] = ()
+    #: Which of the user's own CLI configuration the CLI may load; the
+    #: session has already checked that the provider's profile supports it.
+    config_scope: ConfigScope = ConfigScope.ALL
 
 
 @dataclass(frozen=True)

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/providers/claude/failures.py

@@ -4,7 +4,9 @@ Claude reports a failed API request three ways, newest first: an ``error``
 kind on the synthetic assistant message it writes for the failure, an
 ``api_error_status`` on the final ``result`` frame, and the text
 ``API Error: <status> <body>`` in that frame's ``result``. Older builds only
-have the text, so all three are read.
+have the text, so all three are read. A turn whose ``StructuredOutput`` calls
+never validated ends with the ``result`` subtype
+``error_max_structured_output_retries`` instead.
 """
 
 from __future__ import annotations
@@ -39,17 +41,29 @@ _AUTH_STATUSES = frozenset({401, 403})
 #: A request timeout or a rate limit; every 5xx (529 is an overload) is transient too.
 _TRANSIENT_STATUSES = frozenset({408, 429})
 _SERVER_ERRORS = range(500, 600)
+#: The ``result`` subtype of a turn that used up its output-schema retries.
+SCHEMA_RETRIES_SUBTYPE = "error_max_structured_output_retries"
 
 
-def classify_failure(*, api_error: str | None, status: int | None, text: str) -> FailureKind:
+def classify_failure(
+    *, subtype: str | None, api_error: str | None, status: int | None, text: str
+) -> FailureKind:
     """Classify one failed turn from what Claude reported about it.
 
-    ``api_error`` is the assistant frame's ``error`` kind, ``status`` the
+    ``subtype`` is the error ``result`` frame's subtype, ``api_error`` the
+    assistant frame's ``error`` kind, ``status`` the
     result frame's ``api_error_status``, and ``text`` the error text the
     stream (or, when the stream had none, stderr) carried. Tool output is
     never part of ``text``, so a tool that printed an API error cannot make
     the turn look like one.
     """
+    if subtype == SCHEMA_RETRIES_SUBTYPE:
+        return FailureKind.SCHEMA
+    return _classify_api_failure(api_error=api_error, status=status, text=text)
+
+
+def _classify_api_failure(*, api_error: str | None, status: int | None, text: str) -> FailureKind:
+    """Classify a failure from the API error Claude reported, if it reported one."""
     if api_error in _AUTH_KINDS:
         return FailureKind.AUTH
     if api_error in _USAGE_LIMIT_KINDS:

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/providers/claude/parser.py

@@ -32,7 +32,7 @@ from .events import (
     ToolResultBlock,
     parse_frame,
 )
-from .failures import classify_failure
+from .failures import SCHEMA_RETRIES_SUBTYPE, classify_failure
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
@@ -45,6 +45,10 @@ PROVIDER_NAME = "claude"
 #: The built-in tool through which Claude Code loads a skill.
 SKILL_TOOL = "Skill"
 
+#: The tool through which Claude Code submits a schema-constrained answer;
+#: its error result is the validation failure of one submission.
+STRUCTURED_OUTPUT_TOOL = "StructuredOutput"
+
 #: The built-in tool through which Claude Code reads a file.
 READ_TOOL = "Read"
 
@@ -142,6 +146,9 @@ class ClaudeStreamParser:
         self._api_error: str | None = None
         self._api_error_text: str | None = None
         self._api_error_status: int | None = None
+        self._subtype: str | None = None
+        # The validation errors of the last rejected StructuredOutput call.
+        self._schema_errors: str | None = None
         self._stderr: list[str] = []
 
     def feed_stdout(self, line: str) -> None:
@@ -189,7 +196,12 @@ class ClaudeStreamParser:
         """
         reported = [text for text in (self._error, self._api_error_text) if text]
         text = "\n".join(reported) if reported else "\n".join(self._stderr)
-        return classify_failure(api_error=self._api_error, status=self._api_error_status, text=text)
+        return classify_failure(
+            subtype=self._subtype,
+            api_error=self._api_error,
+            status=self._api_error_status,
+            text=text,
+        )
 
     def _handle(self, frame: object) -> None:
         if isinstance(frame, SystemInit):
@@ -238,6 +250,8 @@ class ClaudeStreamParser:
 
     def _tool_result(self, frame: ToolResultBlock) -> None:
         name = self._tools.name(frame.tool_id)
+        if name == STRUCTURED_OUTPUT_TOOL and frame.is_error:
+            self._schema_errors = frame.output
         self._emit(
             ToolResult(
                 tool_id=frame.tool_id,
@@ -262,7 +276,8 @@ class ClaudeStreamParser:
         self._emit(UsageReport(self._usage, frame.total_cost_usd))
         if frame.is_error:
             self._api_error_status = frame.api_error_status
-            self._error = _error_text(frame)
+            self._subtype = frame.subtype
+            self._error = self._error_text(frame)
             self._emit(ProviderError(self._error))
 
     def _structured_payload(self, frame: ResultFrame) -> object | None:
@@ -281,12 +296,16 @@ class ClaudeStreamParser:
         except (json.JSONDecodeError, ValueError):
             return None
 
+    def _error_text(self, frame: ResultFrame) -> str:
+        """Say what an error ``result`` frame reported.
 
-def _error_text(frame: ResultFrame) -> str:
-    """Say what an error ``result`` frame reported.
-
-    An ``error_*`` subtype carries its messages in ``errors`` and often no
-    ``result`` text at all, so both are read before falling back to the
-    subtype, which is the only part that names some failures.
-    """
-    return frame.text or "; ".join(frame.errors) or frame.subtype or "claude reported an error"
+        A turn that used up its schema retries is described by the validation
+        errors of its last rejected submission, which only the
+        ``StructuredOutput`` tool result carries. Otherwise an ``error_*``
+        subtype carries its messages in ``errors`` and often no ``result``
+        text at all, so both are read before falling back to the subtype,
+        which is the only part that names some failures.
+        """
+        if frame.subtype == SCHEMA_RETRIES_SUBTYPE and self._schema_errors:
+            return self._schema_errors
+        return frame.text or "; ".join(frame.errors) or frame.subtype or "claude reported an error"

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/providers/claude/provider.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, Any
 from agentshim.core.errors import FailureKind, ProviderCapabilityError, SessionResumeError
 from agentshim.core.mcp import HttpMcpServer, NoopInstallation, StdioMcpServer, install_config_file
 from agentshim.core.profile import (
+    ConfigScope,
     McpMechanism,
     McpScope,
     OutputSchemaStyle,
@@ -44,6 +45,14 @@ MCP_SERVER_KEY = "mcpServers"
 #: account connectors are not user settings and stay.
 PROJECT_SETTING_SOURCES = ("--setting-sources", "project,local")
 
+#: ``ConfigScope.PROJECT``: the same ``--setting-sources`` drops the user's
+#: settings (hooks, ``env``, permissions, default model), ``~/.claude/CLAUDE.md``
+#: and plugins; auto-memory is not a setting source and is switched off in the
+#: turn's ``--settings`` instead, so ``~/.claude/projects/*/memory`` is neither
+#: read nor written. Built-in skills, the workspace's ``CLAUDE.md``,
+#: ``.claude/`` settings and skills, and credentials keep working.
+NO_AUTO_MEMORY_SETTINGS = {"autoMemoryEnabled": False}
+
 #: ``McpScope.SESSION``: ``--strict-mcp-config`` makes ``--mcp-config`` the
 #: only source of MCP servers. It drops the user's and the project's
 #: (``.mcp.json``) servers, plugin servers and claude.ai account connectors,
@@ -75,6 +84,7 @@ PROFILE = ProviderProfile(
     skill_invocation=SkillSignal.STRUCTURED,
     skill_scopes=frozenset({SkillScope.ALL, SkillScope.PROJECT}),
     mcp_scopes=frozenset({McpScope.ALL, McpScope.SESSION}),
+    config_scopes=frozenset({ConfigScope.ALL, ConfigScope.PROJECT}),
     container_install=(
         "apt-get update && apt-get install -y --no-install-recommends curl ca-certificates",
         "curl -fsSL https://claude.ai/install.sh | bash",
@@ -138,7 +148,8 @@ class ClaudeProvider:
             "stream-json",
             "--verbose",
         ]
-        if ctx.skill_scope is SkillScope.PROJECT:
+        isolate_config = ctx.config_scope is ConfigScope.PROJECT
+        if ctx.skill_scope is SkillScope.PROJECT or isolate_config:
             argv += PROJECT_SETTING_SOURCES
         if ctx.model:
             argv += ["--model", ctx.model]
@@ -147,6 +158,8 @@ class ClaudeProvider:
         if ctx.schema_inline:
             argv += ["--json-schema", ctx.schema_inline]
         settings = build_settings(self.sandbox, hooks=self.hooks)
+        if isolate_config:
+            settings.update(NO_AUTO_MEMORY_SETTINGS)
         if settings:
             argv += ["--settings", json.dumps(settings)]
         if ctx.mcp_scope is McpScope.SESSION:

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/providers/claude/scripted.py

@@ -120,9 +120,7 @@ def resume_failure_lines(*, session_id: str | None = None) -> tuple[list[str], l
 
 
 #: What Claude writes for a failed request of each kind: the assistant
-#: ``error`` kind, the HTTP status, and the message. ``OTHER`` is a turn that
-#: ran but could not satisfy its output schema, the subtype Claude reports
-#: when no StructuredOutput call validated.
+#: ``error`` kind, the HTTP status, and the message.
 _FAILURES: dict[FailureKind, tuple[str, int, str]] = {
     FailureKind.TRANSIENT: (
         "overloaded",
@@ -133,6 +131,10 @@ _FAILURES: dict[FailureKind, tuple[str, int, str]] = {
     FailureKind.AUTH: ("authentication_failed", 401, "Invalid API key \u00b7 Please run /login"),
 }
 
+#: The validation errors Claude's ``StructuredOutput`` tool returns for a
+#: submission that does not match the schema.
+SCHEMA_ERRORS = "Output does not match required schema: root: must have required property 'answer'"
+
 
 def failure_lines(
     kind: FailureKind, *, session_id: str | None = None
@@ -140,8 +142,10 @@ def failure_lines(
     """Build the stdout, stderr and exit code of a turn that fails with *kind*.
 
     An API failure is the synthetic assistant message Claude writes for it,
-    then an error ``result`` frame with the HTTP status. ``OTHER`` is an
-    ``error_max_structured_output_retries`` result, which names no API error.
+    then an error ``result`` frame with the HTTP status. ``SCHEMA`` is a
+    ``StructuredOutput`` call the tool rejects, then an
+    ``error_max_structured_output_retries`` result. ``OTHER`` is an
+    ``error_during_execution`` result, which names no API error.
 
     Args:
         kind: The classification the scripted failure must produce.
@@ -156,12 +160,13 @@ def failure_lines(
     result: dict[str, Any] = {"type": "result", "is_error": True, "num_turns": 1}
     if session_id is not None:
         result["session_id"] = session_id
-    failure = _FAILURES.get(kind)
-    if failure is None:
-        result["subtype"] = "error_max_structured_output_retries"
-        result["errors"] = ["no StructuredOutput call produced a valid output"]
+    if kind is FailureKind.SCHEMA:
+        lines.extend(_rejected_structured_output())
+        result.update(subtype="error_max_structured_output_retries", errors=[])
+    elif kind is FailureKind.OTHER:
+        result.update(subtype="error_during_execution", errors=["the turn stopped unexpectedly"])
     else:
-        error, status, text = failure
+        error, status, text = _FAILURES[kind]
         message = {"role": "assistant", "content": [{"type": "text", "text": text}]}
         lines.append(_line({"type": "assistant", "message": message, "error": error}))
         result.update(subtype="success", result=text, api_error_status=status)
@@ -169,6 +174,26 @@ def failure_lines(
     return lines, [], 1
 
 
+def _rejected_structured_output() -> list[str]:
+    """One ``StructuredOutput`` call and the validation error it got back."""
+    call: dict[str, Any] = {
+        "type": "tool_use",
+        "id": "toolu_schema",
+        "name": "StructuredOutput",
+        "input": {},
+    }
+    rejection = {
+        "type": "tool_result",
+        "tool_use_id": "toolu_schema",
+        "content": SCHEMA_ERRORS,
+        "is_error": True,
+    }
+    return [
+        _line({"type": "assistant", "message": {"role": "assistant", "content": [call]}}),
+        _line({"type": "user", "message": {"role": "user", "content": [rejection]}}),
+    ]
+
+
 def _usage_payload(usage: TokenUsage | None) -> dict[str, Any]:
     if usage is None:
         return {

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/providers/codex/provider.py

@@ -7,8 +7,10 @@ import re
 from typing import TYPE_CHECKING, Any
 
 from agentshim.core.errors import ProviderCapabilityError, SessionResumeError
+from agentshim.core.home import state_root
 from agentshim.core.mcp import FlagsInstallation, HttpMcpServer, NoopInstallation
 from agentshim.core.profile import (
+    ConfigScope,
     McpMechanism,
     McpScope,
     OutputSchemaStyle,
@@ -85,6 +87,10 @@ PROFILE = ProviderProfile(
     skill_invocation=SkillSignal.INFERRED,
     skill_scopes=frozenset({SkillScope.ALL, SkillScope.PROJECT}),
     mcp_scopes=frozenset({McpScope.ALL, McpScope.SESSION}),
+    config_scopes=frozenset({ConfigScope.ALL, ConfigScope.PROJECT}),
+    # Codex reads AGENTS.md, hooks.json and memories/ from $CODEX_HOME with no
+    # flag to skip them, so ConfigScope.PROJECT needs a home of its own.
+    config_home_files=("auth.json",),
     container_install=(_NODE_INSTALL, _CODEX_INSTALL),
     # Documented Codex CLI variable that relocates ~/.codex (``codex --help``:
     # "Layer $CODEX_HOME/<name>.config.toml on top of the base user config";
@@ -105,6 +111,13 @@ BYPASS_FLAG = "--dangerously-bypass-approvals-and-sandbox"
 #: Keeps user and project ``.rules`` files out of a sandboxed turn.
 IGNORE_RULES_FLAG = "--ignore-rules"
 
+#: ``ConfigScope.PROJECT``: ``$CODEX_HOME/config.toml`` (profiles, notify,
+#: ``developer_instructions``, project trust) is not loaded, and the memories
+#: Codex would otherwise write and reread across sessions in the home stay
+#: off. The global ``AGENTS.md``, ``hooks.json`` and existing memories are
+#: kept out by the dedicated home itself (``prepare_config_home``).
+PROJECT_CONFIG_FLAGS = ("--ignore-user-config", "--disable", "memories")
+
 
 class CodexProvider:
     """Codex (``codex exec --json``). ``sandbox`` is a provider option."""
@@ -136,6 +149,9 @@ class CodexProvider:
         if ctx.model:
             argv += ["--model", ctx.model]
         argv += _shell_path_config(ctx.env)
+        if ctx.config_scope is ConfigScope.PROJECT:
+            _check_config_home(ctx)
+            argv += PROJECT_CONFIG_FLAGS
         argv += _scope_overrides(ctx)
         if ctx.reasoning_effort:
             argv += ["--config", f"model_reasoning_effort={toml_str(ctx.reasoning_effort)}"]
@@ -250,6 +266,26 @@ def _writable_dirs(config: CodexSandboxConfig, ctx: ArgvContext) -> list[str]:
     return dirs
 
 
+def _check_config_home(ctx: ArgvContext) -> None:
+    """Refuse ``ConfigScope.PROJECT`` unless the turn runs in a home of its own.
+
+    The user's global ``AGENTS.md``, hooks and memories live in the state root
+    and no flag skips them, so a turn still pointed at the user's root would
+    load them while claiming to be isolated.
+    """
+    home = ctx.env.get("CODEX_HOME")
+    if not home or not os.path.isabs(home):  # noqa: PTH117 - a str contract, not a Path
+        msg = (
+            "ConfigScope.PROJECT needs CODEX_HOME set to the absolute path of a "
+            f"dedicated home prepared with prepare_config_home (got {home!r})"
+        )
+        raise ProviderCapabilityError(msg)
+    user_root = state_root(PROFILE, {key: v for key, v in ctx.env.items() if key != "CODEX_HOME"})
+    if user_root is not None and os.path.realpath(home) == os.path.realpath(user_root):
+        msg = f"ConfigScope.PROJECT needs a dedicated CODEX_HOME, not the user's own {home}"
+        raise ProviderCapabilityError(msg)
+
+
 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)

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/providers/codex/scripted.py

@@ -130,17 +130,25 @@ _FAILURES: dict[FailureKind, str] = {
         "(https://chatgpt.com/explore/plus), or try again in 2 hours."
     ),
     FailureKind.AUTH: "unexpected status 401 Unauthorized: Missing bearer authentication",
-    FailureKind.OTHER: "model response did not match the output schema",
+    FailureKind.OTHER: "Codex ran out of room in the model's context window.",
 }
 
 
+#: Codex sends ``--output-schema`` to the model as a strict response format,
+#: so decoding is constrained to the schema and a turn never fails over it.
+_NO_SCHEMA_FAILURE = (
+    "codex never fails a turn over its output schema: decoding is constrained to the schema"
+)
+
+
 def failure_lines(
     kind: FailureKind, *, session_id: str | None = None
 ) -> tuple[list[str], list[str], int]:
     """Build the stdout, stderr and exit code of a turn that fails with *kind*.
 
     Codex reports the failure as an ``error`` event followed by
-    ``turn.failed``, both carrying the same message.
+    ``turn.failed``, both carrying the same message. ``SCHEMA`` raises
+    ``ValueError``: Codex has no such failure.
 
     Args:
         kind: The classification the scripted failure must produce.
@@ -149,7 +157,9 @@ def failure_lines(
     Returns:
         ``(stdout, stderr, returncode)`` for a ``FakeRun``.
     """
-    message = _FAILURES[kind]
+    message = _FAILURES.get(kind)
+    if message is None:
+        raise ValueError(_NO_SCHEMA_FAILURE)
     lines: list[str] = []
     if session_id is not None:
         lines.append(_line({"type": "thread.started", "thread_id": session_id}))

{agentshim-0.11.0 → agentshim-0.13.0}/agentshim/testing/__init__.py

@@ -222,14 +222,17 @@ def scripted_failure(provider: str, kind: FailureKind, *, session_id: str | None
     """Build a ``FakeRun`` for a turn that fails and classifies as *kind*.
 
     The run is *provider*'s real report of such a failure (an overload, a
-    usage limit, a rejected login, or an unclassifiable failure), so the
+    usage limit, a rejected login, output that never matched the requested
+    schema, or an unclassifiable failure), so the
     raised ``CliExitError`` carries ``kind`` through the real parser. A
     consumer can therefore test its retry policy without knowing how any
     CLI phrases a failure.
 
     Args:
         provider: A provider whose stream reports failure kinds (``claude``
-            or ``codex``); any other raises ``ValueError``.
+            or ``codex``); any other raises ``ValueError``, as does
+            ``FailureKind.SCHEMA`` on ``codex``, whose decoding is
+            constrained to the schema.
         kind: The ``FailureKind`` the raised error must carry.
         session_id: The conversation the failed run names, if any.
 

{agentshim-0.11.0 → agentshim-0.13.0}/pyproject.toml

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