@yansigit/opencodex 2.36.1-dev.20260829.48 → 2.36.1

package/src/adapters/google-antigravity-replay.ts

@@ -513,10 +513,10 @@ export function antigravityReplaySessionKeysForTests(): string[] {
 
 function extractSignature(part: Record<string, unknown>): string | undefined {
   const direct = part.thoughtSignature ?? part.thought_signature;
-  if (typeof direct === "string" && direct.length >= MIN_SIGNATURE_LEN && direct !== ANTIGRAVITY_SIGNATURE_BYPASS_SENTINEL) return direct;
+  if (typeof direct === "string" && direct.length >= MIN_SIGNATURE_LEN && direct !== THOUGHT_SIGNATURE_BYPASS) return direct;
   const extra = part.extra_content as { google?: { thought_signature?: unknown } } | undefined;
   const nested = extra?.google?.thought_signature;
-  if (typeof nested === "string" && nested.length >= MIN_SIGNATURE_LEN && nested !== ANTIGRAVITY_SIGNATURE_BYPASS_SENTINEL) return nested;
+  if (typeof nested === "string" && nested.length >= MIN_SIGNATURE_LEN && nested !== THOUGHT_SIGNATURE_BYPASS) return nested;
   return undefined;
 }
 
@@ -625,6 +625,75 @@ export function antigravityUsesReplayCache(model: string): boolean {
   return !/claude/i.test(model);
 }
 
+/**
+ * Gemini 3 rejects a turn whose FIRST functionCall part carries no thought signature. When
+ * neither the wire metadata nor the replay cache can supply a real one, this is the official
+ * validator-bypass token.
+ */
+const THOUGHT_SIGNATURE_BYPASS = "skip_thought_signature_validator";
+
+/**
+ * True when the model speaks the Gemini wire dialect that requires a thought signature on the
+ * first functionCall of a turn — and therefore accepts the validator-bypass sentinel.
+ *
+ * Deliberately NOT `antigravityUsesReplayCache`. That predicate is broad on purpose (every
+ * non-Claude model participates in signature replay), and reusing it for the sentinel is how a
+ * Gemini-only control token was observed being injected into `gpt-oss-120b-medium`. Replaying a
+ * signature upstream gave us is harmless for any model; *fabricating* a Gemini token is not.
+ *
+ * The identity must be REDUCED to its model component before matching, not scanned whole. The
+ * Vertex replay key is built in `src/adapters/google.ts` as
+ * `vertex:<project>:<location>:<modelId>`, and the project id is operator-chosen: a project
+ * named `gemini-prod` made a whole-string scan return true for
+ * `vertex:gemini-prod:global:gpt-oss-120b`, arming the Gemini-only sentinel for a non-Gemini
+ * model — the exact class of defect this predicate exists to prevent, reintroduced one layer up.
+ *
+ * So: take the last `:` segment for a Vertex identity, then the last `/` segment for a
+ * namespaced id (`google/gemini-3-pro`), and match only that. The trailing `[-.\d]` keeps
+ * `geminibot` and `my-gemini-clone` out. A model outside this set that genuinely needs the
+ * sentinel must arrive with a captured accepted CCA contract, not by widening this predicate.
+ */
+export function antigravitySupportsThoughtSignatureSentinel(model: string): boolean {
+  const afterTransport = model.slice(model.lastIndexOf(":") + 1);
+  const wireModel = afterTransport.slice(afterTransport.lastIndexOf("/") + 1);
+  return /^gemini[-.\d]/i.test(wireModel);
+}
+
+/**
+ * Ensure every model turn's FIRST functionCall carries a thought signature, injecting the
+ * validator-bypass sentinel only where one is genuinely absent.
+ *
+ * Split out of `applyAntigravityReplay` on purpose. Replay answers "what did upstream already
+ * tell us about this call", and its absence of a signature is meaningful — 18 assertions in the
+ * suite read `thoughtSignature === undefined` as "the cache did not match", covering eviction,
+ * TTL expiry, oversize refusal and clear-on-invalid. Folding a fabricated token into that
+ * function would overwrite the very signal those tests read. Keeping the sentinel as its own
+ * pass means a cache miss still looks like a cache miss.
+ *
+ * Three properties this must hold, each of which a naive presence-check gets wrong:
+ *  - it decides from `extractSignature`, so a valid NESTED
+ *    `extra_content.google.thought_signature` counts as signed (no competing sentinel) and a
+ *    present-but-too-short value does not (the fallback still fires);
+ *  - it looks at the FIRST functionCall only, so a later sibling receiving a cached signature
+ *    cannot vote away the sentinel the first call requires;
+ *  - it is gated on the Gemini wire dialect, not on replay-cache participation.
+ */
+export function applyAntigravityThoughtSignatureFallback(model: string, contents: unknown[]): unknown[] {
+  if (!antigravitySupportsThoughtSignatureSentinel(model) || !Array.isArray(contents)) return contents;
+  for (const rawContent of contents as { role?: string; parts?: unknown[] }[]) {
+    if (!rawContent || typeof rawContent !== "object" || rawContent.role !== "model") continue;
+    if (!Array.isArray(rawContent.parts)) continue;
+    for (const rawPart of rawContent.parts) {
+      if (!rawPart || typeof rawPart !== "object") continue;
+      const part = rawPart as Record<string, unknown>;
+      if (!part.functionCall) continue;
+      if (!extractSignature(part)) part.thoughtSignature = THOUGHT_SIGNATURE_BYPASS;
+      break;
+    }
+  }
+  return contents;
+}
+
 /**
  * Observe a parsed CCA chunk's `candidates[0].content.parts` and record thought signatures keyed by
  * the functionCall identity (name + args). Accumulates across the whole session so a sequential

package/src/adapters/google.ts

@@ -28,7 +28,13 @@ import { canonicalAntigravityHttpsHost, isAntigravityHttpsHost } from "./google-
 import { compileGoogleWireBody } from "./google-wire-compiler";
 import { sanitizeGeminiToolParameters } from "./google-tool-schema";
 import { identifyRoutedModel } from "./identity";
-import { antigravityUsesReplayCache, applyAntigravityReplay, clearAntigravityReplay, observeAntigravityReplay } from "./google-antigravity-replay";
+import {
+  antigravityUsesReplayCache,
+  applyAntigravityReplay,
+  applyAntigravityThoughtSignatureFallback,
+  clearAntigravityReplay,
+  observeAntigravityReplay,
+} from "./google-antigravity-replay";
 import { resolveAntigravityEffortWireModel } from "../providers/antigravity-models";
 import {
   extractCcaGroundingSources,
@@ -996,6 +1002,10 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
           } else {
             sanitizeAntigravityClaudeSignatures(contents);
           }
+          // After replay, not instead of it: a real signature always wins, and the sentinel only
+          // fills a first functionCall that replay could not sign. Outside the cache branch too,
+          // because the turn still needs a signature when no session was ever recorded.
+          applyAntigravityThoughtSignatureFallback(wireModelId, contents);
           // Claude-on-Antigravity rejects assistant-tail (model-tail in Gemini terms) histories
           // as prefill: "This model does not support assistant message prefill. The conversation
           // must end with a user message." Context compaction, previous_response_id expansion,
@@ -1045,6 +1055,10 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
             vertexReplaySession,
             (compiled.body as { contents: unknown[] }).contents,
           );
+          applyAntigravityThoughtSignatureFallback(
+            vertexReplayModel,
+            (compiled.body as { contents: unknown[] }).contents,
+          );
         }
         // Vertex AI: project/location endpoint with GCP ADC, or x-goog-api-key fast path.
         const apiKey = resolveVertexApiKey(provider.apiKey);
@@ -1678,9 +1692,10 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         if (invalidFunctionCall) return finish([invalidGoogleFunctionCallEvent(invalidFunctionCall)]);
         // Non-streaming Google-family response: observe thought signatures for the next turn,
         // using the same transport-scoped namespace as the streaming path.
-        const replayModel = vertexReplayModel;
-        const replaySession = vertexReplaySession;
-        if (provider.googleMode === "vertex" && replayModel && replaySession) {
+        const replayModel = provider.googleMode === "cloud-code-assist" ? antigravityModel : vertexReplayModel;
+        const replaySession = provider.googleMode === "cloud-code-assist" ? antigravitySession : vertexReplaySession;
+        if ((provider.googleMode === "cloud-code-assist" || provider.googleMode === "vertex")
+          && replayModel && replaySession) {
           observeAntigravityReplay(replayModel, replaySession, parts as unknown[]);
         }
         let pendingThoughtSig: string | undefined;

package/src/adapters/kiro-constants.ts

@@ -22,6 +22,18 @@ export const KIRO_COMPLETION_RETRY_MESSAGE =
 export const KIRO_TOOL_RESULT_CARRIER_MESSAGE = "The requested tool result is attached.";
 export const KIRO_EMPTY_TOOL_RESULT_MESSAGE = "The tool completed without textual output.";
 
+/**
+ * Placeholder for the user turn Kiro requires after an assistant turn that ALREADY delivered its
+ * final answer.
+ *
+ * The protocol needs a trailing user turn, but the usual continuation/retry text instructs the
+ * model to keep working, which reopens a finished task and reads as a still-open goal. This states
+ * the delivered state and explicitly withholds a new request, so the turn stays structurally valid
+ * without asking for more work.
+ */
+export const KIRO_ANSWER_DELIVERED_MESSAGE =
+  "The previous final answer was delivered to the user and that task is closed. No new request has been made yet. Do not repeat, revise, or continue that work; wait for the user's next instruction.";
+
 export const KIRO_COMPLETION_INSTRUCTIONS =
   `When tools are available, ordinary assistant text is mid-task commentary and does not end the turn. Continue using tools after progress updates. When the task is fully complete and no more tool calls are needed, call ${KIRO_COMPLETION_TOOL_NAME} exactly once with the complete user-facing final answer in \`answer\`. Do not provide the final answer as ordinary assistant text.`;
 

package/src/adapters/kiro.ts

@@ -36,15 +36,18 @@ import type {
   OcxTool,
   OcxUsage,
 } from "../types";
+import { hasRecordedTrailingDeliveredFinalAnswer } from "../responses/turn-termination";
 import type { ProviderAdapter } from "./base";
 import type { AdapterFetchContext, AdapterRequest } from "./base";
 import { extractKiroImages, normalizeKiroImages, type KiroImage } from "./kiro-images";
 import { sniffImageDimensions } from "./anthropic-image-guard";
 import { fetchKiroWithRetry, noteKiroTransientThrottle } from "./kiro-retry";
 import { convertKiroToolContext } from "./kiro-tools";
+import { normalizeEmptyExecToolResultText } from "./exec-tool-result-normalize";
 import { identifyRoutedModel } from "./identity";
 import { buildNonOpenAIToolCatalogNudgeFromNames, isBareShellBridgeTool, isCodexCodeModeExecTool } from "./tool-catalog-nudge";
 import {
+  KIRO_ANSWER_DELIVERED_MESSAGE,
   KIRO_COMPLETION_INSTRUCTIONS,
   KIRO_COMPLETION_RETRY_MESSAGE,
   KIRO_COMPLETION_TOOL_NAME,
@@ -343,8 +346,54 @@ function validateKiroCapabilities(parsed: OcxParsedRequest): void {
 }
 
 type KiroTurn =
-  | { kind: "user"; content: string; images: KiroImage[]; toolResults: KiroToolResult[] }
-  | { kind: "assistant"; content: string; toolUses: KiroToolUse[]; redactedReasoning?: string };
+  | {
+      kind: "user";
+      content: string;
+      images: KiroImage[];
+      toolResults: KiroToolResult[];
+      /**
+       * True only for the proxy-generated acknowledgement that follows a delivered final answer.
+       * A flag rather than a content comparison: a real user message may legitimately quote the
+       * same sentence, and treating that as internal state would strip its thinking tags and
+       * completion retry.
+       */
+       answerDeliveredAck?: boolean;
+    }
+  | {
+      kind: "assistant";
+      content: string;
+      toolUses: KiroToolUse[];
+      redactedReasoning?: string;
+      /**
+       * True when this assistant turn was the DELIVERED final answer (Responses
+       * `phase: "final_answer"`). A trailing assistant turn normally means the model stopped
+       * mid-task and needs a continuation prompt, but a delivered final answer already ended its
+       * turn — prompting it again restarts finished work as if a goal were still open.
+       */
+      finalAnswer?: boolean;
+    };
+
+/**
+ * True when the LAST content-bearing message is an assistant final answer that closed its turn.
+ *
+ * Mirrors the turn-merge rule: a tool call in that message, or any later user/tool-result message,
+ * means work continued, so the turn is no longer terminal. Empty assistant messages are skipped
+ * rather than treated as continuation, since they carry no visible turn.
+ */
+function hasTrailingDeliveredFinalAnswer(messages: readonly OcxMessage[], parsed?: OcxParsedRequest): boolean {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role !== "assistant") return false;
+    const aMsg = msg as OcxAssistantMessage;
+    const hasToolCall = (aMsg.content ?? []).some(part => part.type === "toolCall");
+    if (hasToolCall) return false;
+    const hasText = (aMsg.content ?? []).some(part => part.type === "text" && part.text.trim());
+    if (!hasText) continue;
+    return aMsg.phase === "final_answer"
+      || (parsed !== undefined && hasRecordedTrailingDeliveredFinalAnswer(parsed, messages));
+  }
+  return false;
+}
 
 function appendTurnText(target: string, next: string): string {
   if (!next) return target;
@@ -453,8 +502,19 @@ export function buildKiroPayload(
   const registry = createKiroToolNameRegistry();
   const toolContext = convertKiroToolContext(parsed, registry);
   const ordinaryTools = toolContext.tools;
+  // A turn whose history already ENDS with a delivered final answer has nothing to complete.
+  // Leaving completion "required" here would keep advertising codex_kiro_final_answer with its
+  // instructions, so the model answers again, or replies with ordinary text and trips the
+  // `needsFallback` retry, which ends its payload with KIRO_COMPLETION_RETRY_MESSAGE and reopens
+  // the finished task. Suppressing the mode is what actually closes that loop; the neutral
+  // acknowledgement below only stops the resume wording.
+  //
+  // Read from parsed messages because `completionMode` is needed to build the tool catalog, which
+  // happens before the turn list exists. `forcedCompletionMode` still wins: the fallback retry
+  // passes "text_fallback" explicitly and must not be silently downgraded.
+  const trailingDeliveredAnswer = hasTrailingDeliveredFinalAnswer(kiroPayloadMessages(parsed), parsed);
   const completionMode: KiroCompletionMode = forcedCompletionMode
-    ?? (ordinaryTools.length > 0 ? "required" : "disabled");
+    ?? (ordinaryTools.length > 0 && !trailingDeliveredAnswer ? "required" : "disabled");
   const kiroTools = completionMode === "disabled"
     ? ordinaryTools
     : [...ordinaryTools, kiroCompletionTool()];
@@ -521,15 +581,24 @@ export function buildKiroPayload(
       turns.push({ kind: "user", content, images: [...images], toolResults: [...toolResults] });
     }
   };
-  const pushAssistant = (content: string, toolUses: KiroToolUse[], redactedReasoning?: string): void => {
+  const pushAssistant = (content: string, toolUses: KiroToolUse[], redactedReasoning?: string, finalAnswer?: boolean): void => {
     const last = turns.at(-1);
     if (last?.kind === "assistant") {
       last.content = appendTurnText(last.content, content);
       last.toolUses.push(...toolUses);
       // Merged turns keep the newest blob: it covers the reasoning up to the merged turn's end.
       if (redactedReasoning) last.redactedReasoning = redactedReasoning;
+      // A merged turn is final only if its LAST component was: commentary appended after a final
+      // answer means the model kept working, so the turn is no longer terminal.
+      last.finalAnswer = finalAnswer === true;
     } else {
-      turns.push({ kind: "assistant", content, toolUses: [...toolUses], ...(redactedReasoning ? { redactedReasoning } : {}) });
+      turns.push({
+        kind: "assistant",
+        content,
+        toolUses: [...toolUses],
+        ...(redactedReasoning ? { redactedReasoning } : {}),
+        ...(finalAnswer ? { finalAnswer: true } : {}),
+      });
     }
   };
 
@@ -559,14 +628,24 @@ export function buildKiroPayload(
         const hasReasoning = aMsg.content.some(part => part.type === "thinking" && part.thinking.trim());
         if (hasReasoning) continue;
       }
-      pushAssistant(text, toolUses, aMsg.kiroRedactedReasoning);
+      // `phase` survives the Responses round trip (parser.ts assistant branch), so a replayed
+      // final answer is identifiable here rather than guessed from turn position.
+      pushAssistant(text, toolUses, aMsg.kiroRedactedReasoning, aMsg.phase === "final_answer" && toolUses.length === 0);
     } else if (msg.role === "toolResult") {
       const tr = msg as OcxToolResultMessage;
       if (tr.containsEncryptedContent) {
         throw new Error(`Kiro cannot translate encrypted output for tool call ${JSON.stringify(tr.toolCallId)}`);
       }
       const text = userContentText(tr.content);
-      const resultText = text.trim() ? text : KIRO_EMPTY_TOOL_RESULT_MESSAGE;
+      // An empty code-mode exec result needs the SPECIFIC reason, not the generic fallback: the
+      // model otherwise reads a blank result, concludes its earlier context was lost, and restarts
+      // the task instead of calling text()/notify(). Checked before `text.trim()` because the
+      // wrapper form ("Script completed\nWall time ...\nOutput:\n") is non-blank and would
+      // otherwise pass through as if it were real output.
+      const resultText = normalizeEmptyExecToolResultText(text, {
+        toolName: tr.toolName,
+        toolNamespace: tr.toolNamespace,
+      }) ?? (text.trim() ? text : KIRO_EMPTY_TOOL_RESULT_MESSAGE);
       const images = extractKiroImages(tr.content);
       const toolUseId = normalizeToolId(tr.toolCallId);
       if (!priorCalls.has(toolUseId)) {
@@ -587,12 +666,23 @@ export function buildKiroPayload(
   if (turns.length === 0 || turns[0].kind === "assistant") {
     turns.unshift({ kind: "user", content: KIRO_CONTINUATION_MESSAGE, images: [], toolResults: [] });
   }
-  if (turns.at(-1)?.kind === "assistant") {
+  // Kiro requires the request to end with a user turn, so a trailing assistant turn always gets
+  // one appended (the pop below throws otherwise). What that turn SAYS is the load-bearing part.
+  //
+  // Normally a trailing assistant turn means the model stopped mid-task, and a continuation/retry
+  // prompt is correct. A DELIVERED final answer is the exception: the turn already ended, and
+  // telling that model to "continue" or to call the completion tool again reopens finished work —
+  // the completed-task-behaves-like-an-open-goal loop. It gets a neutral acknowledgement instead:
+  // structurally valid, but carrying no instruction to resume.
+  const trailing = turns.at(-1);
+  if (trailing?.kind === "assistant") {
+    const resumeText = completionMode === "text_fallback" ? KIRO_COMPLETION_RETRY_MESSAGE : KIRO_CONTINUATION_MESSAGE;
     turns.push({
       kind: "user",
-      content: completionMode === "text_fallback" ? KIRO_COMPLETION_RETRY_MESSAGE : KIRO_CONTINUATION_MESSAGE,
+      content: trailing.finalAnswer ? KIRO_ANSWER_DELIVERED_MESSAGE : resumeText,
       images: [],
       toolResults: [],
+      ...(trailing.finalAnswer ? { answerDeliveredAck: true } : {}),
     });
   }
 
@@ -608,6 +698,8 @@ export function buildKiroPayload(
 
   const currentTurn = turns.pop();
   if (!currentTurn || currentTurn.kind !== "user") throw new Error("Kiro request must end with a user turn");
+  // Survives the pop as state, so the checks below never infer intent from user-supplied text.
+  const answerDeliveredAck = currentTurn.answerDeliveredAck === true;
   const toEntry = (turn: KiroTurn): KiroHistoryEntry => turn.kind === "assistant"
     ? {
         assistantResponseMessage: {
@@ -638,10 +730,17 @@ export function buildKiroPayload(
     currentUim.userInputMessageContext = { ...(currentUim.userInputMessageContext ?? {}), tools: kiroTools };
   }
   if (completionMode === "text_fallback") {
-    if (currentUim.content !== KIRO_COMPLETION_RETRY_MESSAGE) {
+    // Never append the retry instruction onto the answer-delivered acknowledgement: it exists
+    // precisely to avoid asking a finished turn for another completion call, and appending here
+    // would reinstate the loop it prevents.
+    if (currentUim.content !== KIRO_COMPLETION_RETRY_MESSAGE && !answerDeliveredAck) {
       currentUim.content = appendTurnText(currentUim.content, KIRO_COMPLETION_RETRY_MESSAGE);
     }
-  } else if (!currentUim.userInputMessageContext?.toolResults && currentUim.content !== KIRO_CONTINUATION_MESSAGE) {
+  } else if (
+    !currentUim.userInputMessageContext?.toolResults
+    && currentUim.content !== KIRO_CONTINUATION_MESSAGE
+    && !answerDeliveredAck
+  ) {
     currentUim.content = injectKiroThinkingTags(currentUim.content, parsed);
   }
 
@@ -1905,6 +2004,24 @@ export function createKiroAdapter(provider: OcxProviderConfig): ProviderAdapter
 
   return {
     name: "kiro",
+    // A replayed history that already ENDS with a delivered final answer has nothing to ask Kiro.
+    // Before this hook the adapter still appended a trailing user turn — a neutral acknowledgement,
+    // but structurally still a prompt — and performed a real inference, so the model answered the
+    // closed task again and the finished turn behaved like a still-open goal.
+    //
+    // Suppressing the completion contract (above) removed the instruction to complete; it could not
+    // remove the inference. This is the boundary: no request is built, nothing is sent, and no token
+    // estimate is recorded.
+    //
+    // The forced-fallback build is deliberately NOT consulted here: this hook runs on the inbound
+    // turn only, and the adapter-owned bounded retry passes "text_fallback" through `build`
+    // directly, never through this path.
+    localTerminal(parsed: OcxParsedRequest) {
+      return hasTrailingDeliveredFinalAnswer(kiroPayloadMessages(parsed), parsed)
+        ? { reason: "kiro_final_answer_already_delivered" }
+        : undefined;
+    },
+
     async buildRequest(parsed: OcxParsedRequest, incoming) {
       const built = await build(parsed);
       modelId = parsed.modelId;

package/src/adapters/openai-chat.ts

@@ -1113,7 +1113,8 @@ function intersectBound(target: unknown, sibling: unknown, direction: "max" | "m
  * Compose two `properties` maps. A property named in BOTH the referenced target and the
  * node is the same conjunction problem `required` had: letting the sibling win discards
  * the target's constraints for that member. Merge the two member schemas so neither side
- * loses its keywords, and let the node narrow on a genuine conflict.
+ * loses its keywords. Shared member bounds are the same conjunction one level down,
+ * and nested object members recurse through this helper instead of replacing the target.
  */
 function composeProperties(
   target: Record<string, unknown>,
@@ -1127,7 +1128,20 @@ function composeProperties(
       const member: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
       for (const [k, v] of Object.entries(existing)) member[k] = v;
       for (const [k, v] of Object.entries(sub)) {
-        member[k] = k === "required" ? unionRequired(member[k], v) : v;
+        if (k === "required") {
+          member[k] = unionRequired(member[k], v);
+          continue;
+        }
+        if (k === "properties" && isXaiObjectSchema(member[k]) && isXaiObjectSchema(v)) {
+          member[k] = composeProperties(member[k] as Record<string, unknown>, v);
+          continue;
+        }
+        const boundDirection = MOONSHOT_BOUND_KEYWORDS[k];
+        if (boundDirection && k in member) {
+          member[k] = intersectBound(member[k], v, boundDirection);
+          continue;
+        }
+        member[k] = v;
       }
       combined[name] = member;
       continue;

package/src/adapters/openai-responses.ts

@@ -319,8 +319,8 @@ function stripUnsupportedReasoningParams(body: unknown): unknown {
 }
 
 /**
- * GPT-5.6 replaced the legacy 24-hour retention field with `prompt_cache_options.ttl`, and the
- * ChatGPT backend 400s the whole request when the retired field is present (issue #2092).
+ * GPT-5.6 retired the legacy 24-hour retention field, and the ChatGPT backend 400s the whole
+ * request when that field is present (issue #2092).
  *
  * The retired field is NOT translated to the replacement: 5.6 carries a different TTL contract,
  * and implicit caching still applies when the caller sent no replacement options. Inventing a
@@ -340,6 +340,18 @@ function stripDeprecatedPromptCacheRetention(body: unknown, modelId: unknown): u
   return rest;
 }
 
+/**
+ * Public Responses clients can send `prompt_cache_options`, but the canonical ChatGPT Codex
+ * backend rejects the top-level field before inference (issue #2765). Custom forward gateways and
+ * API-key Responses providers own different wire contracts, so the caller applies this only after
+ * the canonical destination predicate succeeds.
+ */
+function stripCanonicalForwardPromptCacheOptions(body: unknown): unknown {
+  if (!isPlainObject(body) || !Object.hasOwn(body, "prompt_cache_options")) return body;
+  const { prompt_cache_options: _options, ...rest } = body;
+  return rest;
+}
+
 /**
  * A false model capability prevents Codex from emitting summary fields after the catalog refresh.
  * Strip them here as well so an already-running client with a stale catalog cannot keep sending an
@@ -2004,6 +2016,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         // third-party forward gateway may still accept it, so this must not be widened.
         if (isCanonicalOpenAiForwardProvider(provider)) {
           outBody = stripDeprecatedPromptCacheRetention(outBody, parsed.modelId);
+          outBody = stripCanonicalForwardPromptCacheOptions(outBody);
           outBody = normalizeCanonicalForwardPromptEnvelope(outBody);
           outBody = normalizeCanonicalForwardContinuationEnvelope(outBody);
         }

package/src/adapters/tool-catalog-nudge.ts

@@ -5,6 +5,7 @@ import {
   type OcxTool,
   type OcxProviderConfig,
 } from "../types";
+import { CODE_MODE_RESULT_ECHO_SENTENCE } from "./exec-tool-result-normalize";
 
 // Tool names that exist only in OTHER agent harnesses (Claude Code and friends). Naming one
 // here tells a routed model not to call it unless this turn's catalog really lists it.
@@ -120,7 +121,7 @@ export function buildNonOpenAIToolCatalogNudgeFromNames(
     "Call only listed names with their listed argument keys; do not invent, translate, or rename tools.",
     "Names mentioned only in instructions, tool descriptions, argument descriptions, or nested helper APIs are not additional top-level tools.",
     verifiedCodeModeExecName
-      ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.<name>(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.<name>`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names. Nested `tools.apply_patch(input)` is host-executed: the string must begin exactly with `*** Begin Patch` and end with `*** End Patch` (no trailing `***` on those lines). OpenCodex does not rewrite JavaScript inside exec, so a decorated `*** Begin Patch ***` envelope is rejected by Codex before the file is touched."
+      ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.<name>(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.<name>`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names. " + CODE_MODE_RESULT_ECHO_SENTENCE + " Nested `tools.apply_patch(input)` is host-executed: the string must begin exactly with `*** Begin Patch` and end with `*** End Patch` (no trailing `***` on those lines). OpenCodex does not rewrite JavaScript inside exec, so a decorated `*** Begin Patch ***` envelope is rejected by Codex before the file is touched."
       : "If a listed tool exposes nested helpers such as a tools.* API, call the listed parent tool and use those helpers only inside that tool's input.",
     unavailableNeighborNames.length > 0
       ? "Do not use neighboring-agent tool names " + quoteNames(unavailableNeighborNames) + " unless this turn's catalog lists those exact names."

package/src/adapters/xai-web-search.ts

@@ -1,8 +1,8 @@
 import type { OcxProviderConfig } from "../types";
+import { isXaiResponsesDestination } from "../providers/xai-transport";
 
 const CODEX_WEB_SEARCH_TOOL = "web_search";
 const CODEX_WEB_SEARCH_PREVIEW_TOOL = "web_search_preview";
-const XAI_API_HOST = "api.x.ai";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
@@ -12,18 +12,6 @@ function isCodexWebSearchToolType(value: unknown): boolean {
   return value === CODEX_WEB_SEARCH_TOOL || value === CODEX_WEB_SEARCH_PREVIEW_TOOL;
 }
 
-/** Match only xAI's documented public API, not arbitrary Responses-compatible gateways. */
-function isXaiPublicApi(provider: Pick<OcxProviderConfig, "baseUrl">): boolean {
-  try {
-    const url = new URL(provider.baseUrl);
-    return url.protocol === "https:"
-      && url.hostname.toLowerCase() === XAI_API_HOST
-      && (url.port === "" || url.port === "443");
-  } catch {
-    return false;
-  }
-}
-
 type ToolGroupRewrite = {
   tools: unknown[];
   changed: boolean;
@@ -150,12 +138,20 @@ function normalizeToolChoice(body: Record<string, unknown>): Record<string, unkn
 /**
  * Make Codex's hosted web-search declaration acceptable to xAI Responses without changing other
  * providers or mutating the caller-owned request body.
+ *
+ * Scoped to BOTH xAI Responses hosts, not just the public API. The 2026-08-22 probe recorded in
+ * `normalizeToolGroup` and in `isXaiResponsesDestination` already found the two hosts to be one
+ * dialect, but this gate stayed on `api.x.ai` alone, so the Grok CLI proxy — the OAuth lane — was
+ * left unnormalized. Re-probed 2026-08-27 against `cli-chat-proxy.grok.com`:
+ * `web_search_preview` -> 422 `unknown variant`, `external_web_access` -> 400 on every value,
+ * `search_context_size` -> 400, while `user_location` and `search_content_types` -> 200. Identical
+ * to the public API, which is what makes one shared gate correct.
  */
 export function normalizeXaiResponsesWebSearch(
   body: unknown,
   provider: Pick<OcxProviderConfig, "baseUrl">,
 ): unknown {
-  if (!isXaiPublicApi(provider) || !isPlainObject(body)) return body;
+  if (!isXaiResponsesDestination(provider) || !isPlainObject(body)) return body;
 
   let next: Record<string, unknown> = body;
   if (Array.isArray(body.tools)) {

package/src/claude/outbound.ts

@@ -11,6 +11,7 @@
  *  - errors: {type:"error", error:{type,message}}; may arrive mid-stream after HTTP 200.
  */
 import { createHash } from "node:crypto";
+import { httpStatusFromTerminalError } from "../lib/errors";
 import { isTransientUpstreamStatus } from "../lib/upstream-retry";
 import {
   isTranslatorBudgetExceededError,
@@ -555,9 +556,19 @@ export function responsesSseToAnthropicSse(
             }
             const status = code === "translation_buffer_limit"
               ? 413
-              : typeof error.status === "number" ? error.status : 500;
-            // status-absent response.failed (relaySseWithFailedTail synthetic tail) defaults
-            // to 500, which is in the transient set — the mid-stream reset shape maps to
+              : typeof error.status === "number"
+                ? error.status
+                // Internal response.failed envelopes carry the classified {type, code, message}
+                // but no numeric status. Derive it with the same mapping /api/logs uses so a
+                // classified 429/401/400 reaches Claude Code as its real Anthropic error type
+                // instead of being masked as retryable overload.
+                : httpStatusFromTerminalError({
+                  type: typeof error.type === "string" ? error.type : undefined,
+                  code: typeof error.code === "string" ? error.code : null,
+                  message,
+                });
+            // Unclassified status-absent response.failed (relaySseWithFailedTail synthetic
+            // tail) still lands on a transient 5xx here — the mid-stream reset shape maps to
             // overloaded_error by design.
             fail(
               status,

package/src/cli/access.ts

@@ -17,6 +17,51 @@ const USAGE = `Usage:
   ocx access models [--json]
   ocx access test <model> [--protocol <chat|responses|messages>] [--json]`;
 
+/**
+ * Render the key table with the usage fields the API already returns (#2705).
+ *
+ * `usage` is a DISCRIMINATED UNION server-side (`api-key-usage.ts`): the `{ambiguous:true}`
+ * variant carries no numbers at all, because when two config entries share an id there IS no
+ * per-key total. The union exists specifically so a consumer cannot print a number beside an
+ * ambiguity marker, so this renders the word `ambiguous` across the numeric columns rather
+ * than a fabricated 0 -- reporting 0 requests for a key that may be in heavy use is the
+ * dangerous answer to hand someone deciding what to delete.
+ *
+ * `attributionSince` and `historyTruncated` describe the DATA SET, not a key, so they print
+ * once as a footer. Without `attributionSince`, an absent `lastUsedAt` is unreadable: it
+ * could mean "never used" or "nothing is attributable yet".
+ */
+function formatKeyRows(payload: Record<string, unknown>, keys: Array<Record<string, unknown>>): string[] {
+  const cells: string[][] = [["ID", "NAME", "PREFIX", "REQ 7D", "TOTAL", "LAST USED"]];
+  for (const entry of keys) {
+    const usage = (entry.usage ?? {}) as Record<string, unknown>;
+    const ambiguous = usage.ambiguous === true;
+    const num = (value: unknown): string => (typeof value === "number" ? value.toLocaleString("en-US") : "-");
+    cells.push([
+      String(entry.id ?? ""),
+      String(entry.name ?? ""),
+      String(entry.prefix ?? ""),
+      // One marker spanning both numeric columns: the union guarantees neither exists.
+      ambiguous ? "ambiguous" : num(usage.requests7d),
+      ambiguous ? "" : num(usage.totalRequests),
+      ambiguous ? "" : (typeof usage.lastUsedAt === "string" ? usage.lastUsedAt : "never"),
+    ]);
+  }
+  const widths = cells[0]!.map((_, column) => Math.max(...cells.map(row => (row[column] ?? "").length)));
+  const lines = cells.map(row => row.map((cell, i) => (cell ?? "").padEnd(widths[i]!)).join("  ").trimEnd());
+  const footer: string[] = [];
+  if (typeof payload.attributionSince === "string") {
+    footer.push(`attribution since ${payload.attributionSince}`);
+  }
+  if (payload.historyTruncated === true) {
+    footer.push("older history truncated");
+  }
+  if (keys.some(entry => (entry.usage as Record<string, unknown> | undefined)?.ambiguous === true)) {
+    footer.push("ambiguous: two configured keys share an id, so per-key totals do not exist");
+  }
+  return footer.length > 0 ? [...lines, "", ...footer] : lines;
+}
+
 async function key(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const action = (args.shift() ?? "list").toLowerCase();
@@ -25,9 +70,7 @@ async function key(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     rejectArgs(args, USAGE);
     const result = await runtimeRequest<Record<string, unknown>>("/api/keys", {}, deps);
     const keys = Array.isArray(result.keys) ? result.keys as Array<Record<string, unknown>> : [];
-    printData(result, wantsJson, keys.length
-      ? keys.map(entry => `${String(entry.id)}  ${String(entry.name)}  ${String(entry.prefix ?? "")}`)
-      : ["No API access keys configured."]);
+    printData(result, wantsJson, keys.length ? formatKeyRows(result, keys) : ["No API access keys configured."]);
     return;
   }
   if (action === "create") {