agentshim 0.10.0__tar.gz → 0.11.0__tar.gz

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

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.11.0 (2026-10-03)
+
+A failed turn says why it failed. Additive except that a classified failure of
+a resumed Claude turn is no longer a `SessionResumeError`.
+
+### Added
+
+- `FailureKind` (`TRANSIENT`, `USAGE_LIMIT`, `AUTH`, `OTHER`) on
+  `CliExitError.kind`, and the stream's error text on `CliExitError.detail`.
+  Claude Code classifies from the assistant frame's `error` kind, the result
+  frame's `api_error_status`, and `API Error: <status>` text; Codex from its
+  `error` and `turn.failed` messages. Copilot, Gemini and opencode report
+  `OTHER`.
+- `ParsedTurn.error_kind`, set by a provider's parser.
+- `agentshim.testing.scripted_failure(provider, kind)` and
+  `providers.get_failure_lines`: a real failed Claude or Codex run of each kind.
+
+### Changed
+
+- A resumed Claude turn that failed with a classified kind (an overload, a
+  usage limit, a login problem) raises `CliExitError` with that kind instead of
+  `SessionResumeError`, and the session keeps the conversation.
+
+### Fixed
+
+- `CliExitError`'s message was empty when Claude reported the failure only in
+  its stream (for example `error_max_structured_output_retries`): the message
+  now carries the stream's error text as well as stderr.
+
+## 0.10.1 (2026-10-03)
+
+### Fixed
+
+- Codex `McpScope.SESSION` failed the whole turn with `invalid transport`
+  when the CLI could not see a config file agentshim had scanned (a confined
+  or containerized home): `enabled=false` alone defines an entry with no
+  transport. Each disabled server now restates its own `command` or `url`, so
+  the override is a complete, disabled entry whether or not the file is seen.
+
 ## 0.10.0 (2026-10-03)
 
 MCP isolation. Additive: the default scope keeps today's behaviour. Adds a

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.10.0
+Version: 0.11.0
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Requires-Dist: tomli>=2; python_full_version < '3.11'
@@ -188,7 +188,8 @@ Everything that escapes `turn()` is an `AgentShimError`:
 AgentShimError
   CliNotFoundError            binary not on PATH
   CliCheckError               binary found but the health check failed
-  CliExitError                nonzero exit: argv, returncode, stdout, stderr
+  CliExitError                nonzero exit: argv, returncode, stdout, stderr,
+                              kind (FailureKind), detail (the stream's error text)
     SessionResumeError        the conversation is gone: session_id
   CliTimeoutError             argv, timeout
   ProviderCapabilityError     the provider cannot do what the request asked
@@ -196,6 +197,13 @@ AgentShimError
   McpConfigError              config file unreadable or not an object
 ```
 
+`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`.
+`agentshim.testing.scripted_failure(provider, kind)` scripts each one.
+
 ## Adding a provider
 
 See [`docs/extending.md`](docs/extending.md) and

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

@@ -178,7 +178,8 @@ Everything that escapes `turn()` is an `AgentShimError`:
 AgentShimError
   CliNotFoundError            binary not on PATH
   CliCheckError               binary found but the health check failed
-  CliExitError                nonzero exit: argv, returncode, stdout, stderr
+  CliExitError                nonzero exit: argv, returncode, stdout, stderr,
+                              kind (FailureKind), detail (the stream's error text)
     SessionResumeError        the conversation is gone: session_id
   CliTimeoutError             argv, timeout
   ProviderCapabilityError     the provider cannot do what the request asked
@@ -186,6 +187,13 @@ AgentShimError
   McpConfigError              config file unreadable or not an object
 ```
 
+`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`.
+`agentshim.testing.scripted_failure(provider, kind)` scripts each one.
+
 ## Adding a provider
 
 See [`docs/extending.md`](docs/extending.md) and

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

@@ -21,6 +21,7 @@ from .core import (
     ConfigFileInstallation,
     ConsoleEventHandler,
     EventHandlerBase,
+    FailureKind,
     FlagsInstallation,
     HttpMcpServer,
     Lifecycle,
@@ -98,7 +99,7 @@ from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
 
-__version__ = "0.10.0"
+__version__ = "0.11.0"
 
 __all__ = [
     "AgentEvent",
@@ -127,6 +128,7 @@ __all__ = [
     "ConsoleEventHandler",
     "CopilotProvider",
     "EventHandlerBase",
+    "FailureKind",
     "FlagsInstallation",
     "GeminiProvider",
     "HostCommandExecutor",

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

@@ -397,7 +397,14 @@ class AgentSession:
         error: AgentShimError | None = None
         if result.returncode != 0:
             error = self._agent.provider.classify_exit(
-                CliExitError(argv, result.returncode, result.stdout, result.stderr),
+                CliExitError(
+                    argv,
+                    result.returncode,
+                    result.stdout,
+                    result.stderr,
+                    kind=parsed.error_kind,
+                    detail=parsed.error or "",
+                ),
                 resumed=resumed,
             )
         if parsed.session_id and not isinstance(error, SessionResumeError):

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

@@ -14,6 +14,7 @@ from .errors import (
     CliExitError,
     CliNotFoundError,
     CliTimeoutError,
+    FailureKind,
     McpConfigError,
     ProviderCapabilityError,
     SchemaDialectError,
@@ -83,6 +84,7 @@ __all__ = [
     "ConfigFileInstallation",
     "ConsoleEventHandler",
     "EventHandlerBase",
+    "FailureKind",
     "FlagsInstallation",
     "HttpMcpServer",
     "Lifecycle",

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from enum import Enum
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -14,6 +15,24 @@ class AgentShimError(Exception):
     """Base class for every error agentshim raises."""
 
 
+class FailureKind(str, Enum):
+    """Why a provider turn failed, as far as the provider let agentshim tell.
+
+    The provider package decides the kind from what its CLI reported (a
+    structured error field, an HTTP status, or its own error text), so a caller
+    can choose a policy without knowing how any CLI phrases its failures.
+    """
+
+    #: An overload, rate limit, or server error that waiting may outlast.
+    TRANSIENT = "transient"
+    #: A usage quota, spend limit, or billing problem: waiting minutes will not help.
+    USAGE_LIMIT = "usage_limit"
+    #: Missing, expired, or rejected credentials.
+    AUTH = "auth"
+    #: Anything else, including every failure a provider cannot classify.
+    OTHER = "other"
+
+
 class CliNotFoundError(AgentShimError):
     """The provider binary is not on PATH."""
 
@@ -45,44 +64,58 @@ class CliCheckError(AgentShimError):
 class CliExitError(AgentShimError):
     """The provider CLI exited nonzero."""
 
-    def __init__(
+    def __init__(  # noqa: PLR0913  # one field per part of the outcome; a bundle would hide them
         self,
         argv: Sequence[str],
         returncode: int,
         stdout: str = "",
         stderr: str = "",
         message: str | None = None,
+        *,
+        kind: FailureKind = FailureKind.OTHER,
+        detail: str = "",
     ) -> None:
         """Capture the whole outcome of a nonzero CLI exit.
 
         Both streams are retained because a provider may report the real cause
         on either one, and ``argv`` is copied so the error stays accurate after
-        the caller mutates its command list. Passing ``message`` replaces the
-        generated summary.
+        the caller mutates its command list. ``kind`` is the provider's
+        classification of the failure and ``detail`` the error text its stream
+        reported; the generated summary carries ``detail`` because a CLI that
+        reports its failure in the stream leaves stderr empty. Passing
+        ``message`` replaces the generated summary.
         """
         self.argv = tuple(argv)
         self.returncode = returncode
         self.stdout = stdout
         self.stderr = stderr
+        self.kind = kind
+        self.detail = detail
         binary = self.argv[0] if self.argv else "cli"
-        super().__init__(message or f"{binary} exited with code {returncode}: {stderr.strip()}")
+        super().__init__(
+            message or f"{binary} exited with code {returncode}: {_describe(detail, stderr)}"
+        )
 
 
 class SessionResumeError(CliExitError):
     """A resumed turn failed because the provider conversation is gone."""
 
-    def __init__(
+    def __init__(  # noqa: PLR0913  # the parent's fields plus the session id
         self,
         argv: Sequence[str],
         returncode: int,
         session_id: str,
         stdout: str = "",
         stderr: str = "",
+        *,
+        detail: str = "",
     ) -> None:
         """Attach the conversation id that the provider refused to resume.
 
         Raised instead of a plain ``CliExitError`` so a caller can tell a dead
-        conversation apart from a failed turn and retry from scratch.
+        conversation apart from a failed turn and retry from scratch. Its kind
+        is always ``OTHER``: a provider that classified the failure as anything
+        else has shown that the conversation is not what failed.
         """
         self.session_id = session_id
         super().__init__(
@@ -90,7 +123,11 @@ class SessionResumeError(CliExitError):
             returncode,
             stdout,
             stderr,
-            message=f"cannot resume session {session_id!r} (exit code {returncode}): {stderr.strip()}",
+            message=(
+                f"cannot resume session {session_id!r} (exit code {returncode}): "
+                f"{_describe(detail, stderr)}"
+            ),
+            detail=detail,
         )
 
 
@@ -135,3 +172,8 @@ class SchemaDialectError(ProviderCapabilityError):
 
 class McpConfigError(AgentShimError):
     """An MCP config file is unreadable, unwritable, or is not a JSON object."""
+
+
+def _describe(detail: str, stderr: str) -> str:
+    """Join the stream's error text and stderr, skipping whichever is empty."""
+    return "; ".join(part for part in (detail.strip(), stderr.strip()) if part)

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

@@ -5,6 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Protocol
 
+from .errors import FailureKind
 from .profile import McpScope, SkillScope
 from .usage import ProviderUsage
 
@@ -59,7 +60,10 @@ class ParsedTurn:
     session_id: str | None = None
     usage: ProviderUsage = field(default_factory=ProviderUsage)
     cost_usd: float | None = None
+    #: The error text the stream reported, or ``None`` when it reported none.
     error: str | None = None
+    #: The parser's classification of ``error``; ``OTHER`` when it cannot tell.
+    error_kind: FailureKind = FailureKind.OTHER
 
 
 class StreamParser(Protocol):

{agentshim-0.10.0 → agentshim-0.11.0}/agentshim/providers/__init__.py

@@ -11,9 +11,11 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Protocol
 
 from .claude import ClaudeProvider
+from .claude import failure_lines as _claude_failure
 from .claude import resume_failure_lines as _claude_resume_failure
 from .claude import scripted_lines as _claude_scripted
 from .codex import CodexProvider
+from .codex import failure_lines as _codex_failure
 from .codex import resume_failure_lines as _codex_resume_failure
 from .codex import scripted_lines as _codex_scripted
 from .copilot import CopilotProvider
@@ -29,6 +31,7 @@ from .opencode import scripted_lines as _opencode_scripted
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping, Sequence
 
+    from agentshim.core.errors import FailureKind
     from agentshim.core.provider import Provider
     from agentshim.core.usage import TokenUsage
 
@@ -74,6 +77,20 @@ class ResumeFailureLines(Protocol):
         ...
 
 
+class FailureLines(Protocol):
+    """Builds the stdout, stderr and exit code of a turn that failed with a given kind."""
+
+    def __call__(
+        self, kind: FailureKind, *, session_id: str | None = None
+    ) -> tuple[Sequence[str], Sequence[str], int]:
+        """Return ``(stdout, stderr, returncode)`` for a ``FakeRun``.
+
+        The run must classify as *kind* through the provider's real parser.
+        ``session_id`` is the conversation the failed run names, if any.
+        """
+        ...
+
+
 # To add a provider: implement providers/<name>/ (provider.py, parser.py,
 # events.py, scripted.py) and add one entry to each dict below.
 _FACTORIES: dict[str, Callable[[], Provider]] = {
@@ -101,6 +118,14 @@ _RESUME_FAILURES: dict[str, ResumeFailureLines] = {
 }
 
 
+# Only the providers whose stream reports why a turn failed: every other
+# provider classifies each failure as ``FailureKind.OTHER``.
+_FAILURES: dict[str, FailureLines] = {
+    "claude": _claude_failure,
+    "codex": _codex_failure,
+}
+
+
 def provider_names() -> list[str]:
     """Return the supported provider names, sorted."""
     return sorted(_FACTORIES)
@@ -135,14 +160,25 @@ def get_resume_failure_lines(name: str) -> ResumeFailureLines:
     return resume_failure
 
 
+def get_failure_lines(name: str) -> FailureLines:
+    """Return the test-double classified-failure builder for *name*."""
+    failure = _FAILURES.get(name)
+    if failure is None:
+        msg = f"no classified-failure stream for provider {name!r}; available: {sorted(_FAILURES)}"
+        raise ValueError(msg)
+    return failure
+
+
 __all__ = [
     "ClaudeProvider",
     "CodexProvider",
     "CopilotProvider",
+    "FailureLines",
     "GeminiProvider",
     "OpencodeProvider",
     "ResumeFailureLines",
     "ScriptedLines",
+    "get_failure_lines",
     "get_provider",
     "get_resume_failure_lines",
     "get_scripted_lines",

{agentshim-0.10.0 → agentshim-0.11.0}/agentshim/providers/claude/__init__.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 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 .scripted import failure_lines, resume_failure_lines, scripted_lines
 from .user_hooks import ClaudeHook
 
 __all__ = [
@@ -15,6 +15,7 @@ __all__ = [
     "ClaudeStreamParser",
     "SandboxConfig",
     "build_settings",
+    "failure_lines",
     "mcp_entry",
     "resolve_sandbox",
     "resume_failure_lines",

{agentshim-0.10.0 → agentshim-0.11.0}/agentshim/providers/claude/events.py

@@ -60,6 +60,10 @@ class AssistantMessage:
 
     blocks: Sequence[ContentBlock] = ()
     usage: Mapping[str, Any] | None = None
+    #: The API error kind Claude stamps on the synthetic message it writes
+    #: when a request fails (``overloaded``, ``rate_limit``, ...); ``None`` on
+    #: a normal reply.
+    error: str | None = None
 
 
 @dataclass(frozen=True)
@@ -83,6 +87,10 @@ class ResultFrame:
     duration_ms: int | None = None
     is_error: bool = False
     subtype: str | None = None
+    #: The HTTP status of the API error that ended the turn, if one did.
+    api_error_status: int | None = None
+    #: The messages an ``error_*`` subtype reports instead of ``result`` text.
+    errors: tuple[str, ...] = ()
 
 
 ClaudeFrame = SystemInit | AssistantMessage | ToolResultBlock | ResultFrame
@@ -111,6 +119,8 @@ def parse_frame(data: Mapping[str, Any]) -> ClaudeFrame | None:
             duration_ms=_int_or_none(data.get("duration_ms")),
             is_error=bool(data.get("is_error")),
             subtype=_str_or_none(data.get("subtype")),
+            api_error_status=_int_or_none(data.get("api_error_status")),
+            errors=_str_tuple_or_none(data.get("errors")) or (),
         )
     return None
 
@@ -128,9 +138,10 @@ def _assistant(data: Mapping[str, Any]) -> AssistantMessage | None:
             if block is not None:
                 blocks.append(block)
     usage = _mapping_or_none(payload.get("usage"))
-    if not blocks and usage is None:
+    error = _str_or_none(data.get("error"))
+    if not blocks and usage is None and error is None:
         return None
-    return AssistantMessage(blocks=tuple(blocks), usage=usage)
+    return AssistantMessage(blocks=tuple(blocks), usage=usage, error=error)
 
 
 def _content_block(raw: object) -> ContentBlock | None:

agentshim-0.11.0/agentshim/providers/claude/failures.py

@@ -0,0 +1,74 @@
+"""How Claude Code says why a turn failed, mapped to ``FailureKind``.
+
+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.
+"""
+
+from __future__ import annotations
+
+import re
+
+from agentshim.core.errors import FailureKind
+
+#: Assistant ``error`` kinds that a later request may not hit.
+_TRANSIENT_KINDS = frozenset({"overloaded", "rate_limit", "server_error"})
+#: Assistant ``error`` kinds that need the user to sign in or fix an account.
+_AUTH_KINDS = frozenset(
+    {
+        "authentication_failed",
+        "oauth_org_not_allowed",
+        "account_on_hold",
+        "verification_required",
+        "cloud_credential_error",
+    }
+)
+_USAGE_LIMIT_KINDS = frozenset({"billing_error"})
+
+#: Anthropic API error types that name an overload or a server fault.
+_TRANSIENT_TYPES = re.compile(r"\b(?:overloaded_error|rate_limit_error|api_error)\b")
+_AUTH_TYPES = re.compile(r"\b(?:authentication_error|permission_error)\b")
+_API_ERROR_STATUS = re.compile(r"\bAPI Error: (\d{3})\b")
+#: A 429 that is a subscription or spend quota rather than a rate limit.
+#: Claude words these itself ("You've hit your limit", "usage limit reached")
+#: or relays a gateway's own sentence about a spend limit or credit balance.
+_QUOTA_TEXT = re.compile(r"hit your limit|usage limit|credit balance|spend limit", re.IGNORECASE)
+_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)
+
+
+def classify_failure(*, 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
+    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 api_error in _AUTH_KINDS:
+        return FailureKind.AUTH
+    if api_error in _USAGE_LIMIT_KINDS:
+        return FailureKind.USAGE_LIMIT
+    if status is None:
+        match = _API_ERROR_STATUS.search(text)
+        status = int(match.group(1)) if match else None
+    if (
+        api_error in _TRANSIENT_KINDS
+        or _is_transient_status(status)
+        or _TRANSIENT_TYPES.search(text)
+    ):
+        return FailureKind.USAGE_LIMIT if _QUOTA_TEXT.search(text) else FailureKind.TRANSIENT
+    if status in _AUTH_STATUSES or _AUTH_TYPES.search(text):
+        return FailureKind.AUTH
+    if _QUOTA_TEXT.search(text):
+        return FailureKind.USAGE_LIMIT
+    return FailureKind.OTHER
+
+
+def _is_transient_status(status: int | None) -> bool:
+    return status is not None and (status in _TRANSIENT_STATUSES or status in _SERVER_ERRORS)

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

@@ -32,10 +32,12 @@ from .events import (
     ToolResultBlock,
     parse_frame,
 )
+from .failures import classify_failure
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
 
+    from agentshim.core.errors import FailureKind
     from agentshim.core.events import AgentEvent
 
 PROVIDER_NAME = "claude"
@@ -136,6 +138,11 @@ class ClaudeStreamParser:
         self._usage = ProviderUsage(provider=PROVIDER_NAME)
         self._cost_usd: float | None = None
         self._error: str | None = None
+        # What the stream said about a failed API request, for classifying it.
+        self._api_error: str | None = None
+        self._api_error_text: str | None = None
+        self._api_error_status: int | None = None
+        self._stderr: list[str] = []
 
     def feed_stdout(self, line: str) -> None:
         """Consume one stdout line, emitting the events its frame implies.
@@ -158,6 +165,7 @@ class ClaudeStreamParser:
         """Emit one non-blank stderr line as a ``Stderr`` event."""
         stripped = line.rstrip("\n")
         if stripped:
+            self._stderr.append(stripped)
             self._emit(Stderr(stripped))
 
     def finish(self) -> ParsedTurn:
@@ -170,8 +178,19 @@ class ClaudeStreamParser:
             usage=self._usage,
             cost_usd=self._cost_usd,
             error=self._error,
+            error_kind=self._error_kind(),
         )
 
+    def _error_kind(self) -> FailureKind:
+        """Classify the failure from the stream, or from stderr if it had none.
+
+        A CLI that dies before writing a ``result`` frame leaves stderr as the
+        only account of why, so stderr is read only then.
+        """
+        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)
+
     def _handle(self, frame: object) -> None:
         if isinstance(frame, SystemInit):
             if self._session_id is None and frame.session_id:
@@ -187,6 +206,11 @@ class ClaudeStreamParser:
             self._result(frame)
 
     def _assistant(self, frame: AssistantMessage) -> None:
+        if frame.error is not None:
+            self._api_error = frame.error
+            self._api_error_text = "\n".join(
+                block.text for block in frame.blocks if isinstance(block, TextBlock)
+            )
         if frame.usage is not None:
             self._emit(
                 UsageReport(
@@ -237,7 +261,8 @@ class ClaudeStreamParser:
         )
         self._emit(UsageReport(self._usage, frame.total_cost_usd))
         if frame.is_error:
-            self._error = frame.text or (frame.subtype or "claude reported an error")
+            self._api_error_status = frame.api_error_status
+            self._error = _error_text(frame)
             self._emit(ProviderError(self._error))
 
     def _structured_payload(self, frame: ResultFrame) -> object | None:
@@ -255,3 +280,13 @@ class ClaudeStreamParser:
             return json.loads(frame.text)
         except (json.JSONDecodeError, ValueError):
             return None
+
+
+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"

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

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 from typing import TYPE_CHECKING, Any
 
-from agentshim.core.errors import ProviderCapabilityError, SessionResumeError
+from agentshim.core.errors import FailureKind, ProviderCapabilityError, SessionResumeError
 from agentshim.core.mcp import HttpMcpServer, NoopInstallation, StdioMcpServer, install_config_file
 from agentshim.core.profile import (
     McpMechanism,
@@ -178,17 +178,24 @@ class ClaudeProvider:
         )
 
     def classify_exit(self, error: CliExitError, *, resumed: bool) -> AgentShimError:
-        """Any nonzero exit on a resumed turn means the conversation is gone.
+        """A resumed turn that failed for no reason the stream named lost its conversation.
 
         ``claude --resume`` gives no distinguishable exit code for a missing
-        transcript, and a resumed turn that fails is unusable either way:
-        the caller has to start a fresh conversation.
+        transcript, so a resumed turn whose failure the parser could not
+        classify is treated as a dead conversation. A failure the stream did
+        classify (an overload, a usage limit, a login problem) happened inside
+        a conversation that resumed, so it keeps its own kind.
         """
-        if resumed:
+        if resumed and error.kind is FailureKind.OTHER:
             session_id = _resumed_session_id(error.argv)
             if session_id is not None:
                 return SessionResumeError(
-                    error.argv, error.returncode, session_id, error.stdout, error.stderr
+                    error.argv,
+                    error.returncode,
+                    session_id,
+                    error.stdout,
+                    error.stderr,
+                    detail=error.detail,
                 )
         return error
 

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

@@ -10,6 +10,8 @@ from __future__ import annotations
 import json
 from typing import TYPE_CHECKING, Any
 
+from agentshim.core.errors import FailureKind
+
 if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
 
@@ -117,6 +119,56 @@ def resume_failure_lines(*, session_id: str | None = None) -> tuple[list[str], l
     return [], stderr, 1
 
 
+#: 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.
+_FAILURES: dict[FailureKind, tuple[str, int, str]] = {
+    FailureKind.TRANSIENT: (
+        "overloaded",
+        529,
+        'API Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}',
+    ),
+    FailureKind.USAGE_LIMIT: ("rate_limit", 429, "You've hit your limit \u00b7 resets 3pm (UTC)"),
+    FailureKind.AUTH: ("authentication_failed", 401, "Invalid API key \u00b7 Please run /login"),
+}
+
+
+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*.
+
+    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.
+
+    Args:
+        kind: The classification the scripted failure must produce.
+        session_id: Conversation id the ``init`` frame names, if any.
+
+    Returns:
+        ``(stdout, stderr, returncode)`` for a ``FakeRun``.
+    """
+    lines: list[str] = []
+    if session_id is not None:
+        lines.append(_line({"type": "system", "subtype": "init", "session_id": session_id}))
+    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"]
+    else:
+        error, status, text = failure
+        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)
+    lines.append(_line(result))
+    return lines, [], 1
+
+
 def _usage_payload(usage: TokenUsage | None) -> dict[str, Any]:
     if usage is None:
         return {

{agentshim-0.10.0 → agentshim-0.11.0}/agentshim/providers/codex/__init__.py

@@ -13,7 +13,7 @@ from .provider import (
 )
 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
+from .scripted import failure_lines, resume_failure_lines, scripted_lines
 
 __all__ = [
     "BYPASS_FLAG",
@@ -25,6 +25,7 @@ __all__ = [
     "CodexSandboxConfig",
     "CodexStreamParser",
     "SandboxMode",
+    "failure_lines",
     "install_rules",
     "parse_mcp_servers",
     "parse_rules",

agentshim-0.11.0/agentshim/providers/codex/failures.py

@@ -0,0 +1,43 @@
+"""How Codex says why a turn failed, mapped to ``FailureKind``.
+
+``codex exec --json`` reports a failure only as the text of an ``error`` or
+``turn.failed`` event, so the classification reads that text. The phrases are
+Codex's own: it names a usage limit ("You've hit your usage limit",
+``usage_limit_reached``), retries a lost stream ("stream disconnected",
+"Reconnecting...") and, once its retries run out, reports
+"exceeded retry limit, last status: <status>".
+"""
+
+from __future__ import annotations
+
+import re
+
+from agentshim.core.errors import FailureKind
+
+_USAGE_LIMIT = re.compile(
+    r"hit your usage limit|usage_limit_(?:reached|exceeded)|insufficient_quota", re.IGNORECASE
+)
+_AUTH = re.compile(r"\b(?:401|403)\b|unauthorized|forbidden|not logged in", re.IGNORECASE)
+_TRANSIENT = re.compile(
+    r"exceeded retry limit|stream disconnected|reconnecting|server_overloaded|overloaded"
+    r"|internal_server_error|internal server error|service unavailable|bad gateway"
+    r"|too many requests|rate limit|at capacity|http_connection_failed"
+    r"|\bstatus:? (?:429|5\d\d)\b",
+    re.IGNORECASE,
+)
+
+
+def classify_failure(text: str) -> FailureKind:
+    """Classify the error text of one failed Codex turn.
+
+    The order matters: a usage limit is also reported with a 429 status, and
+    an exhausted retry can end on a 401, so the specific kinds are checked
+    before the generic transient one.
+    """
+    if _USAGE_LIMIT.search(text):
+        return FailureKind.USAGE_LIMIT
+    if _AUTH.search(text):
+        return FailureKind.AUTH
+    if _TRANSIENT.search(text):
+        return FailureKind.TRANSIENT
+    return FailureKind.OTHER

{agentshim-0.10.0 → agentshim-0.11.0}/agentshim/providers/codex/mcp_scope.py

@@ -22,7 +22,7 @@ else:  # pragma: no cover - exercised on the 3.10 CI leg
     import tomli as tomllib  # pyright: ignore[reportMissingImports]
 
 if TYPE_CHECKING:
-    from collections.abc import Collection, Iterable, Mapping
+    from collections.abc import Collection, Mapping
 
 _SYSTEM_CONFIG = "/etc/codex/config.toml"
 _BARE_KEY = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-")
@@ -32,32 +32,47 @@ _BARE_KEY = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz01234
 _MCP_FEATURES = ("plugins", "apps")
 
 
-def configured_server_keys(env: Mapping[str, str], cwd: str | None) -> list[str]:
-    """Every ``mcp_servers`` key the config files Codex would read define.
+def configured_servers(env: Mapping[str, str], cwd: str | None) -> dict[str, str]:
+    """Every configured ``mcp_servers`` key, with a ``--config`` flag pinning its transport.
 
     Reads the user's ``$CODEX_HOME/config.toml`` (default ``~/.codex``), the
     system config, and ``<cwd>/.codex/config.toml``. A file that is missing or
     not valid TOML contributes nothing (Codex reports a broken config itself).
-    The scan runs where agentshim runs, so a CLI in a container is only
-    covered when the container shares these files.
+    The value is the entry's own ``command`` or ``url`` rendered as an
+    override (empty when it has neither). Disabling an entry with
+    ``enabled=false`` alone fails the whole turn ("invalid transport") when
+    the CLI cannot see the file agentshim scanned, as in a container or a
+    confined home; restating the transport makes the override a complete,
+    disabled entry either way.
     """
     home = env.get("HOME") or os.path.expanduser("~")  # noqa: PTH111 - a str contract, not a Path
     codex_home = env.get("CODEX_HOME") or os.path.join(home, ".codex")  # noqa: PTH118
     paths = [os.path.join(codex_home, "config.toml"), _SYSTEM_CONFIG]  # noqa: PTH118
     if cwd is not None:
         paths.append(os.path.join(cwd, ".codex", "config.toml"))  # noqa: PTH118
-    keys: list[str] = []
+    servers: dict[str, str] = {}
     for path in paths:
-        keys += _server_keys(path)
-    return list(dict.fromkeys(keys))
+        servers.update(_servers(path))
+    return servers
 
 
-def _server_keys(path: str) -> Iterable[str]:
+def _servers(path: str) -> dict[str, str]:
     config = _read_toml(path)
-    servers: object = config.get("mcp_servers")
-    if not isinstance(servers, dict):
-        return []
-    return [str(key) for key in cast("dict[object, object]", servers)]
+    table: object = config.get("mcp_servers")
+    if not isinstance(table, dict):
+        return {}
+    found: dict[str, str] = {}
+    for key, entry in cast("dict[object, object]", table).items():
+        pinned = ""
+        if isinstance(entry, dict):
+            fields = cast("dict[str, object]", entry)
+            for field in ("command", "url"):
+                value = fields.get(field)
+                if isinstance(value, str):
+                    pinned = f"{field}={toml_str(value)}"
+                    break
+        found[str(key)] = pinned
+    return found
 
 
 def _read_toml(path: str) -> dict[str, Any]:
@@ -85,9 +100,14 @@ def session_scope_overrides(
     names the user's config does not use.
     """
     flags: list[str] = []
-    for key in configured_server_keys(env, cwd):
-        if key not in given_keys:
-            flags += ["--config", f"mcp_servers.{_table_key(key)}.enabled=false"]
+    for key, pinned in configured_servers(env, cwd).items():
+        if key in given_keys:
+            continue
+        prefix = f"mcp_servers.{_table_key(key)}"
+        if pinned:
+            name, _, value = pinned.partition("=")
+            flags += ["--config", f"{prefix}.{name}={value}"]
+        flags += ["--config", f"{prefix}.enabled=false"]
     for feature in _MCP_FEATURES:
         flags += ["--config", f"features.{feature}=false"]
     return flags

{agentshim-0.10.0 → agentshim-0.11.0}/agentshim/providers/codex/parser.py

@@ -34,6 +34,7 @@ from .events import (
     parse_frame,
     summarize_item,
 )
+from .failures import classify_failure
 from .skills import skill_reads
 
 if TYPE_CHECKING:
@@ -96,6 +97,7 @@ class CodexStreamParser:
         self._tokens = TokenUsage()
         self._usage = ProviderUsage(provider=PROVIDER_NAME)
         self._error: str | None = None
+        self._stderr: list[str] = []
 
     def feed_stdout(self, line: str) -> None:
         """Parse one stdout line, emitting whatever events it carries."""
@@ -114,6 +116,7 @@ class CodexStreamParser:
         """Emit one stderr line as a ``Stderr`` event."""
         stripped = line.rstrip("\n")
         if stripped:
+            self._stderr.append(stripped)
             self._emit(Stderr(stripped))
 
     def finish(self) -> ParsedTurn:
@@ -125,6 +128,11 @@ class CodexStreamParser:
             usage=self._usage,
             cost_usd=None,
             error=self._error,
+            # The last error event is the one that ended the turn; a CLI that
+            # died before writing one left its reason on stderr.
+            error_kind=classify_failure(
+                self._error if self._error is not None else "\n".join(self._stderr)
+            ),
         )
 
     def _handle(self, frame: CodexFrame) -> None:

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

@@ -202,7 +202,12 @@ class CodexProvider:
         if session_id is None:
             return error
         return SessionResumeError(
-            error.argv, error.returncode, session_id, error.stdout, error.stderr
+            error.argv,
+            error.returncode,
+            session_id,
+            error.stdout,
+            error.stderr,
+            detail=error.detail,
         )
 
 
@@ -334,6 +339,10 @@ _CONFIG_OVERRIDE_RE = re.compile(r"^mcp_servers\.([^.=]+)\.(.+)$")
 _TOML_STRING_RE = re.compile(r'"((?:[^"\\]|\\.)*)"')
 
 
+_DISABLED = "\0disabled"
+"""Scratch key marking an entry an ``enabled=false`` override switched off."""
+
+
 def parse_mcp_servers(argv: Sequence[str]) -> dict[str, dict[str, Any]]:
     """Recover the MCP servers rendered into *argv* by ``_server_flags``.
 
@@ -355,9 +364,14 @@ def parse_mcp_servers(argv: Sequence[str]) -> dict[str, dict[str, Any]]:
     servers: dict[str, dict[str, Any]] = {}
     for key, field, raw_value in _mcp_config_overrides(argv):
         _apply_mcp_override(servers.setdefault(key, {}), field, raw_value)
-    # ``McpScope.SESSION`` also emits ``enabled=false`` overrides for servers
-    # the user configured; those define no server, so they are not reported.
-    servers = {key: entry for key, entry in servers.items() if "command" in entry or "url" in entry}
+    # ``McpScope.SESSION`` also emits overrides that disable the servers the
+    # user configured (their transport plus ``enabled=false``); those are not
+    # servers the turn was given, so they are not reported.
+    servers = {
+        key: entry
+        for key, entry in servers.items()
+        if not entry.pop(_DISABLED, False) and ("command" in entry or "url" in entry)
+    }
     for entry in servers.values():
         if "url" not in entry:
             entry.setdefault("args", [])
@@ -385,6 +399,8 @@ def _apply_mcp_override(entry: dict[str, Any], field: str, raw_value: str) -> No
     elif field == "url":
         entry["url"] = _parsetoml_str(raw_value)
         entry["transport"] = "http"
+    elif field == "enabled":
+        entry[_DISABLED] = raw_value.strip() == "false"
     elif field == "tool_timeout_sec":
         entry["tool_timeout_s"] = float(raw_value)
     elif field == "startup_timeout_sec":

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

@@ -10,6 +10,8 @@ from __future__ import annotations
 import json
 from typing import TYPE_CHECKING, Any
 
+from agentshim.core.errors import FailureKind
+
 if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
 
@@ -120,6 +122,43 @@ def resume_failure_lines(*, session_id: str | None = None) -> tuple[list[str], l
     return [], stderr, 1
 
 
+#: The message Codex reports for a failed turn of each kind.
+_FAILURES: dict[FailureKind, str] = {
+    FailureKind.TRANSIENT: "exceeded retry limit, last status: 500 Internal Server Error",
+    FailureKind.USAGE_LIMIT: (
+        "You've hit your usage limit. Upgrade to Plus to continue using Codex "
+        "(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",
+}
+
+
+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.
+
+    Args:
+        kind: The classification the scripted failure must produce.
+        session_id: Thread id ``thread.started`` names, if any.
+
+    Returns:
+        ``(stdout, stderr, returncode)`` for a ``FakeRun``.
+    """
+    message = _FAILURES[kind]
+    lines: list[str] = []
+    if session_id is not None:
+        lines.append(_line({"type": "thread.started", "thread_id": session_id}))
+    lines.append(_line({"type": "turn.started"}))
+    lines.append(_line({"type": "error", "message": message}))
+    lines.append(_line({"type": "turn.failed", "error": {"message": message}}))
+    return lines, [], 1
+
+
 def _usage_payload(usage: TokenUsage | None) -> dict[str, int]:
     if usage is None:
         return {

{agentshim-0.10.0 → agentshim-0.11.0}/agentshim/providers/gemini/provider.py

@@ -133,7 +133,12 @@ class GeminiProvider:
             session_id = _resumed_session_id(error.argv, "--resume")
             if session_id is not None:
                 return SessionResumeError(
-                    error.argv, error.returncode, session_id, error.stdout, error.stderr
+                    error.argv,
+                    error.returncode,
+                    session_id,
+                    error.stdout,
+                    error.stderr,
+                    detail=error.detail,
                 )
         return error
 

{agentshim-0.10.0 → agentshim-0.11.0}/agentshim/providers/opencode/provider.py

@@ -136,7 +136,12 @@ class OpencodeProvider:
             session_id = _resumed_session_id(error.argv, "--session")
             if session_id is not None:
                 return SessionResumeError(
-                    error.argv, error.returncode, session_id, error.stdout, error.stderr
+                    error.argv,
+                    error.returncode,
+                    session_id,
+                    error.stdout,
+                    error.stderr,
+                    detail=error.detail,
                 )
         return error
 

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

@@ -14,7 +14,12 @@ from agentshim.core.errors import CliNotFoundError, CliTimeoutError
 from agentshim.core.profile import McpMechanism
 from agentshim.core.usage import TokenUsage
 from agentshim.execution.executor import CommandResult
-from agentshim.providers import get_provider, get_resume_failure_lines, get_scripted_lines
+from agentshim.providers import (
+    get_failure_lines,
+    get_provider,
+    get_resume_failure_lines,
+    get_scripted_lines,
+)
 from agentshim.providers.claude import provider as _claude
 from agentshim.providers.codex.provider import parse_mcp_servers as _parse_codex_mcp_servers
 from agentshim.providers.copilot.provider import parse_mcp_servers as _parse_copilot_mcp_servers
@@ -25,6 +30,7 @@ if TYPE_CHECKING:
     from collections.abc import Callable, Mapping, Sequence
     from pathlib import Path
 
+    from agentshim.core.errors import FailureKind
     from agentshim.core.events import AgentEvent
     from agentshim.execution.executor import CommandRequest, CommandStreamSink
 
@@ -212,6 +218,28 @@ def scripted_resume_failure(provider: str, *, session_id: str | None = None) ->
     return FakeRun(stdout=list(stdout), stderr=list(stderr), returncode=returncode)
 
 
+def scripted_failure(provider: str, kind: FailureKind, *, session_id: str | None = None) -> FakeRun:
+    """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
+    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``.
+        kind: The ``FailureKind`` the raised error must carry.
+        session_id: The conversation the failed run names, if any.
+
+    Returns:
+        A ``FakeRun`` with a nonzero exit code.
+    """
+    stdout, stderr, returncode = get_failure_lines(provider)(kind, session_id=session_id)
+    return FakeRun(stdout=list(stdout), stderr=list(stderr), returncode=returncode)
+
+
 def installed_mcp_servers(
     provider: str, request: CommandRequest, workspace: Path
 ) -> dict[str, dict[str, Any]]:
@@ -325,6 +353,7 @@ __all__ = [
     "RecordingEventHandler",
     "TokenUsage",
     "installed_mcp_servers",
+    "scripted_failure",
     "scripted_resume_failure",
     "scripted_turn",
 ]

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

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