@cartanova/qgrid-cli 2.6.11 → 2.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartanova/qgrid-cli",
-  "version": "2.6.11",
+  "version": "2.7.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/cartanova-ai/qgrid"

package/skills/qgrid/references/ai-sdk-provider-contract.md

@@ -145,9 +145,12 @@ Payload responsibilities:
 - Send AI SDK multimodal image/file message parts as qgrid `input` only when `imageGeneration` is enabled. Normal non-image-generation calls keep `user_prompt` text-only and do not forward image input.
 - Reject oversized reference-image data URLs before the request leaves the SDK. Reference images travel as JSON data URLs; callers should compress/resize large photos, preferably to WebP/JPEG.
 
-Tools and `jsonSchema` can be used together as of qgrid 2.5.4. The server composes
-them into one strict action envelope for every provider turn. `toolChoice` is not
-part of the current qgrid wire contract and must not be described as supported.
+Tools and `jsonSchema` can be used together as of qgrid 2.5.4. On OpenAI the
+server composes them into one strict action envelope enforced by constrained
+decoding; on Anthropic (SON-532) the same envelope contract is rendered as text
+at the end of the system prompt and the reply is validated by `parseEnvelope`.
+`toolChoice` is not part of the current qgrid wire contract and must not be
+described as supported.
 
 Before provider dispatch, qgrid validates caller output schemas and every tool
 input schema with an iterative preflight. Output/tool schema serialization, tool
@@ -155,24 +158,26 @@ names, descriptions, JSON escaping, and composition framing share an aggregate
 512 KiB UTF-8 budget. Schema JSON values are limited to 20,000 in aggregate, and
 each schema is limited to depth 128. Malformed, unsupported top-level output, or
 over-budget schemas fail with HTTP 400 before request-log creation or stream ID
-allocation. The fully composed and strictified schema is checked again against
-the 512 KiB budget. Anthropic routes additionally enforce a 64 KiB UTF-8 ceiling
-because Claude Code receives that schema as one `--json-schema` argv value.
+allocation. On OpenAI the fully composed and strictified schema is checked again
+against the 512 KiB budget. Anthropic performs only this syntax/complexity
+preflight — no strictify, no argv ceiling (the old 64 KiB `--json-schema` limit
+is gone; large schema contracts ride the system-prompt file branch).
 
 OpenAI normalizes positional tuple schemas in supported positive schema
 positions and enforces their positional constraints. Tuples in negative,
 conditional, or otherwise non-normalizable schema positions fail with HTTP 400
 instead of being rewritten with changed semantics. References from those
 positions fail for the same reason because definitions are normalized globally.
-Anthropic positional tuple schemas fail with HTTP 400 because Claude Code cannot
-preserve positional semantics. Tuple nodes must explicitly declare
-`type: "array"`; express nullable tuples with an `anyOf` array/null branch.
-
-Structured schemas accept only local root-relative JSON Pointer `$ref` values
-targeting the document root or a chain of `$defs`/`definitions` entry roots.
-References into properties, tuple internals, conditionals, or literal values
-fail with HTTP 400 because normalization can move or rewrite those targets.
-Resource IDs, anchors, external refs, dynamic refs, and recursive refs are also
+Tuple nodes must explicitly declare `type: "array"`; express nullable tuples
+with an `anyOf` array/null branch. These normalization restrictions are
+OpenAI-only: the Anthropic route injects the schema verbatim as prompt text, so
+positional tuples and arbitrary `$ref` forms pass through unchanged.
+
+On OpenAI, structured schemas accept only local root-relative JSON Pointer
+`$ref` values targeting the document root or a chain of `$defs`/`definitions`
+entry roots. References into properties, tuple internals, conditionals, or
+literal values fail with HTTP 400 because normalization can move or rewrite
+those targets. Resource IDs, anchors, external refs, dynamic refs, and recursive refs are also
 rejected.
 
 When tools are present, qgrid sends tool definitions to the server as `tools`; it does not send them to OpenAI or Anthropic as native provider tools. The server converts them into a strict structured-output schema and maps the model's structured result back into AI SDK `tool-call` content.

package/skills/qgrid/references/anthropic-claude-code-runtime.md

@@ -61,7 +61,7 @@ Refresh is attempted through `QgridFrame.refreshToken` with provider set to `ant
 ```text
 claude -p
   --tools ""
-  --allowed-tools StructuredOutput        # only when jsonSchema exists
+  --allowed-tools StructuredOutput        # legacy structured path only — unused since SON-532
   --disallowedTools Monitor PushNotification RemoteTrigger
   --input-format stream-json
   --output-format stream-json
@@ -76,18 +76,22 @@ claude -p
   --effort <effort-or-low>
   --disable-slash-commands
   --session-id <uuid>
-  --json-schema <schema>                  # only when jsonSchema exists
+  --json-schema <schema>                  # legacy structured path only — unused since SON-532
 ```
 
 Important details:
 
-- `--tools ""` blocks normal tools. With structured output, only `StructuredOutput` is allowed.
+- `--tools ""` blocks normal tools on every call.
+- **qgrid no longer passes `--json-schema` (SON-532).** Schema and tool-envelope contracts are
+  rendered as text (`schema-prompt.ts`) and appended to the system prompt; CC runs in plain text
+  mode, qgrid strips code fences (`fence-strip.ts`), and validation belongs to the consumer's zod
+  and qgrid's `parseEnvelope`. The `buildClaudeArgs` structured branch remains in code but is
+  unreachable from qgrid dispatch.
 - `--setting-sources project` plus seeded settings isolates user configuration.
 - `--system-prompt` or `--system-prompt-file` is always supplied. Omitting it would allow Claude Code default system prompt injection.
-- Large system prompts over 64 KiB are written to a temporary file to avoid argv `E2BIG`.
-- Final structured-output schemas are limited to 64 KiB UTF-8 because Claude Code receives each
-  schema as one `--json-schema` argv value. qgrid applies this check before request-log or stream
-  allocation and repeats it at dispatcher/session boundaries.
+- Large system prompts over 64 KiB are written to a temporary file to avoid argv `E2BIG` — this
+  same branch absorbs large injected schema contracts, so the old 64 KiB schema argv limit no
+  longer applies (only the global 512 KiB caller-schema complexity limit remains).
 - `--thinking disabled`, `MAX_THINKING_TOKENS=0`, and adaptive thinking env suppression keep thinking off for existing models. Fable 5 requires always-on adaptive thinking. Opus 5 defaults to adaptive thinking and rejects disabled thinking at `xhigh`/`max` effort. qgrid omits all three suppressors for both models and uses `effort` to control depth.
 
 ## Spawn env
@@ -209,13 +213,26 @@ Upstream references:
 
 ## Structured output
 
-qgrid strictifies schemas before provider dispatch. Claude Code `--json-schema` is not grammar-constrained decoding; it is a `StructuredOutput` tool plus post-validation behavior. Keep schemas strict and preserve error signaling for failed structured-output attempts.
-
-`MAX_STRUCTURED_OUTPUT_RETRIES` defaults to `1` and is clamped to at least 1. Avoid setting it to 0; Claude Code can fail before emitting a useful attempt.
-
-qgrid pins this env var only when the call is **structured and streaming**. The pin exists because a retry inside a stream doubles wall-clock time (SON-495); that reasoning does not apply to non-streaming `generate`, which already waits for completion. Streaming is detected via `includePartialMessages`, which only `generateStream` sets.
-
-Non-streaming structured calls therefore keep Claude Code's default retry budget. This matters because Claude models comply with structured output less reliably than OpenAI models: pinning retries to 1 turns a single rejected attempt into an immediate `error_max_structured_output_retries`. Measured on dev0 before the fix, `deti_production` on Opus 4.8 failed 39.6% of non-streaming structured calls for this reason.
+**Since SON-532 the anthropic route delivers schemas by prompt, not by `--json-schema`.** The
+consumer's original schema (no strictify — nullish/optional intent preserved) is rendered as text
+and appended to the system prompt; anthropic is cold-only, so every multi-turn step re-sends the
+contract. Responses are plain text: qgrid strips fences and trims, and validation is the
+consumer's zod (user schema) or qgrid's `parseEnvelope` (tool envelope). Prose or degenerate
+output fails honestly — retry is the caller's decision.
+
+Why: CC's `--json-schema` is not grammar-constrained decoding — it is a `StructuredOutput` tool
+plus post-hoc AJV scoring with an internal retry loop that cannot be disabled. The strictified
+scoring schema contradicted consumer intent (nullish frozen into required), so the model's
+correct-per-instructions output was rejected and retried invisibly: deti transcripts showed 2–4
+round trips per call, 216–512 s latency, and 4.7–9.1× billed output tokens, all collapsed into
+one request-log row. OpenAI keeps the strictified schema because constrained decoding actually
+enforces it there.
+
+Legacy notes (structured path, unreachable from qgrid dispatch but still in `claude-session.ts`):
+`MAX_STRUCTURED_OUTPUT_RETRIES` was pinned to 1 only for structured **streaming** calls (SON-495 —
+a retry inside a stream doubles wall-clock); non-streaming kept CC's default budget because
+pinning it caused 39.6% failures on `deti_production` Opus 4.8. Compliance measurement for the
+prompt path lives in `scripts/schema-delivery-bench.ts`.
 
 When a non-streaming retry succeeds, the result event's `structured_output` is the canonical
 schema-validated value. Do not let a previously captured assistant tool input override it. Preserve

package/skills/qgrid/references/decision-rationale.md

@@ -114,9 +114,19 @@ Key decisions:
 - Anthropic is cold-only. It does not use Codex-style thread reuse because Claude Code prompt cache is prefix-based and AI SDK consumers already send full message history for each step.
 - The shared `threadCoord` response shape may still appear for provider symmetry, but AI SDK storage/replay is disabled for `anthropic/*` models.
 - Claude Code `stream-json` drops structural assistant role replay in the outbound API payload. qgrid flattens prior history into text because structural role replay through the CLI is not reliable.
-- Claude Code `--json-schema` is not constrained native tool calling. It creates a `StructuredOutput` tool and validates after model generation. Keep schemas strict and fail on non-success subtypes or retry exhaustion.
-- `MAX_STRUCTURED_OUTPUT_RETRIES=1` means one attempt. Do not set it to 0 expecting "no retry but one attempt"; that can mean no useful attempt.
-- The retry pin is scoped to **streaming** structured calls only. SON-495 fixed retries to 1 because a retry inside a stream doubles wall-clock time — a latency argument that does not hold for non-streaming `generate`. Applying the pin to both paths made every non-streaming structured call fail on its first rejected attempt, and since Claude complies with structured output less reliably than OpenAI, that produced a 39.6% `error_max_structured_output_retries` rate for `deti_production` on Opus 4.8 (dev0, 2026-07). Non-streaming now uses Claude Code's default retry budget; `includePartialMessages` is the streaming discriminator.
+- **qgrid does not pass `--json-schema` to Claude Code (SON-532, 2026-08).** CC's mode is not
+  constrained decoding — it creates a `StructuredOutput` tool, scores the free-form output with
+  AJV afterwards, and retries internally on mismatch with no off switch. The strictified scoring
+  schema contradicted consumer intent (nullish frozen into required), so correct-per-instructions
+  outputs were rejected and retried invisibly: deti transcripts showed 2–4 round trips, 216–512 s,
+  and 4.7–9.1× billed output per call, collapsed into one request-log row. Schemas and the tool
+  envelope now travel as text at the end of the system prompt (`schema-prompt.ts`, consumer's
+  original schema, no strictify), the server strips fences only (`fence-strip.ts`), and validation
+  is consumer zod / `parseEnvelope`. Honest failure on violations is unchanged.
+- Legacy (structured path, unreachable from qgrid dispatch): `MAX_STRUCTURED_OUTPUT_RETRIES=1`
+  means one attempt (never set 0), and the retry pin was scoped to **streaming** structured calls
+  only — SON-495's latency argument does not hold for non-streaming `generate`, where pinning
+  produced a 39.6% failure rate for `deti_production` on Opus 4.8 (dev0, 2026-07).
 - 1M context support is measured per model and is a mitigation, not a guarantee. It reduces compaction/hang frequency for huge prompts, but does not make every structured prompt reliable.
 - Spawn env must be whitelisted. Never pass inherited `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `ANTHROPIC_BASE_URL` unless intentionally building an API-key/proxy path.
 - `--setting-sources project` is required for shared-service isolation. User/local Claude settings can load hooks or memory and leak context across requests.

package/skills/qgrid/references/prompt-cache-and-usage.md

@@ -63,7 +63,10 @@ Prompt cache can still work when prefixes are stable, but:
 - Full history is replayed through stream-json after flattening.
 - Cache write/read can be eventually consistent; immediate next request is not guaranteed to hit.
 - Claude Code OAuth token cache behavior has provider-specific quirks documented in `docs/solutions`.
-- Avoid putting volatile schema text into the system prompt. qgrid uses `--json-schema` / `StructuredOutput` for structured output.
+- Since SON-532, qgrid appends the schema/tool-envelope contract to the end of the system
+  prompt (no `--json-schema`). A stable schema keeps the system prefix stable and cacheable
+  across requests; a schema that changes per request invalidates the prefix cache from the
+  contract onward. Keep caller schemas deterministic (no timestamps or per-request IDs inside).
 
 ## Usage normalization
 

package/skills/qgrid/references/provider-runtime-differences.md

@@ -16,9 +16,9 @@ Use this reference when comparing OpenAI and Anthropic behavior, debugging provi
 | `sessionKey` | AI SDK stores and replays `threadCoord` for thread reuse | AI SDK intentionally disables storage/replay |
 | Multi-turn | Reuse sends delta input to existing Codex thread; cold fallback injects full history | Fresh spawn receives flattened full history through stream-json |
 | Cache key | Codex conversation/thread id is prompt-cache affinity | Anthropic prefix cache via Claude Code; fresh spawn still can cache stable prefixes |
-| Built-in tools | Codex tools/apps/plugins/skills disabled by worker config | Claude tools disabled via `--tools ""`; `StructuredOutput` allowed only for schema |
-| AI SDK tools | Emulated via qgrid structured output schema, then mapped to AI SDK `tool-call` content | Same emulation path; not native Claude Code tools |
-| Structured output | Codex `outputSchema` passed to `turn/start`; schema changes can affect prefix cache | Claude `--json-schema` through `StructuredOutput` tool; strict schemas required |
+| Built-in tools | Codex tools/apps/plugins/skills disabled by worker config | Claude tools disabled via `--tools ""` on every call |
+| AI SDK tools | Emulated via qgrid structured output schema, then mapped to AI SDK `tool-call` content | Emulated via envelope contract rendered as prompt text (SON-532); reply parsed by `parseEnvelope`; not native Claude Code tools |
+| Structured output | Codex `outputSchema` passed to `turn/start` (strictified, constrained decoding); schema changes can affect prefix cache | Schema delivered as prompt text appended to the system prompt (no `--json-schema`, no strictify); server strips fences; validation is the consumer's |
 | Usage accounting | Codex usage already reports `inputTokens` including cached input | Native Anthropic categories are mutually exclusive; qgrid sums them into total input |
 | Cost source | qgrid model price fallback | Prefer Claude Code `total_cost_usd`, else qgrid price fallback |
 | Settings isolation | Per-worker `CODEX_HOME` and config.toml | Shared project cwd plus per-token `CLAUDE_CONFIG_DIR` |

package/skills/qgrid/references/tool-calling-and-multiturn.md

@@ -102,13 +102,21 @@ The schema explicitly tells the model:
 - do not invoke listed tools as native Claude Code tools;
 - put tool arguments in `args` as a JSON string.
 
-`qgrid.dispatcher.ts` strictifies this schema through `buildStrictOutputSchema` before it reaches provider dispatchers.
+Delivery differs by provider (SON-532). OpenAI: `qgrid.dispatcher.ts` strictifies the composed
+envelope through `buildStrictOutputSchema` and passes it as the response format — constrained
+decoding enforces it. Anthropic: no schema is passed to CC at all; `schema-prompt.ts` renders the
+same envelope contract (the `{"result": ...}` wrapper, mutually exclusive variants, tool list) as
+text appended to the system prompt, the user answer schema stays unstrictified, and the server
+strips code fences before `parseEnvelope` validates the reply.
 
 ## Composing Tools With A User Output Schema
 
 This section explains why `tool-emulation-schema.ts` exists at all. Read it
 before changing schema composition; the mechanics look arbitrary without the
-failure it was built to prevent.
+failure it was built to prevent. Scope note (SON-532): this composition — and
+its `$defs` rebase with the anchor/dynamic-ref rejections below — runs only on
+the OpenAI delivery path now. Anthropic renders the contract as prompt text, so
+there is no document-root `$ref` collision and nothing to rebase or reject.
 
 ### The problem
 
@@ -242,10 +250,12 @@ Anthropic/Claude Code:
 
 - qgrid does not allow client tools as Claude Code native tools.
 - Claude is spawned with `--tools ""`.
-- When a schema exists, qgrid permits only `StructuredOutput` with `--allowed-tools StructuredOutput`.
-- qgrid passes the strict tool-call schema through `--json-schema`.
-- The stream adapter preserves `StructuredOutput` tool input as final structured text.
-- qgrid parses that text and maps it to qgrid `tool-call` content.
+- Since SON-532 qgrid does **not** pass `--json-schema` (no `StructuredOutput` tool either): the
+  envelope contract travels as text at the end of the system prompt (`schema-prompt.ts`), and the
+  answer schema inside it is the consumer's original, unstrictified.
+- The reply is plain text; the server strips code fences (`fence-strip.ts`), then `parseEnvelope`
+  validates the `{"result": ...}` envelope and maps `tool_call` to qgrid `tool-call` content.
+- Violations fail honestly — no tolerant fallback (medpath 13.5k corruption precedent).
 
 In both providers, native provider tools are not the public abstraction. The public abstraction is AI SDK tools plus qgrid structured-output emulation.