agentshim 0.11.0__tar.gz → 0.12.0__tar.gz

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.11.0
+Version: 0.12.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.12.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.12.0}/agentshim/__init__.py

@@ -99,7 +99,7 @@ from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
 
-__version__ = "0.11.0"
+__version__ = "0.12.0"
 
 __all__ = [
     "AgentEvent",

{agentshim-0.11.0 → agentshim-0.12.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.11.0 → agentshim-0.12.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.12.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.12.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.12.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.12.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.12.0}/pyproject.toml

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