@bitkyc08/opencodex 2.24.1 → 2.25.0-preview.20260818

package/src/adapters/cursor/protobuf-request.ts

@@ -8,12 +8,14 @@ import { isCursorExternalWireModel } from "./discovery";
 import { debugProviderDiagnostic } from "../../lib/debug";
 import {
   createCursorBlobRequestScope,
+  cursorBlobMaxEntryBytes,
   releaseCursorBlobRequestScope,
   sealCursorBlobRequestScope,
   storeCursorBlob,
   type CursorBlobRequestScopeToken,
 } from "./native-exec";
 import { estimateTokens } from "../../lib/token-estimate";
+import { parseDataUrl } from "../image";
 import {
   AgentClientMessageSchema,
   AgentConversationTurnStructureSchema,
@@ -26,6 +28,7 @@ import {
   McpArgsSchema,
   McpSuccessSchema,
   McpTextContentSchema,
+  McpImageContentSchema,
   McpToolCallSchema,
   McpToolResultContentItemSchema,
   McpToolResultSchema,
@@ -318,7 +321,7 @@ function contentText(message: OcxMessage): string {
     .map(part => {
       if (part.type === "text") return part.text;
       if (part.type === "thinking") return part.thinking;
-      if (part.type === "image") return `[image input unsupported by Cursor adapter phase 3: ${part.detail ?? "auto"}]`;
+      if (part.type === "image") return `[image produced by this tool, omitted from Cursor text replay: ${part.detail ?? "auto"}]`;
       return undefined;
     })
     .filter((value): value is string => typeof value === "string" && value.length > 0)
@@ -328,10 +331,146 @@ function contentText(message: OcxMessage): string {
 function contentToText(content: OcxToolResultMessage["content"]): string {
   if (typeof content === "string") return content;
   return content
-    .map(part => part.type === "text" ? part.text : `[image input unsupported by Cursor adapter phase 3: ${part.detail ?? "auto"}]`)
+    .map(part => part.type === "text" ? part.text : `[image produced by this tool, omitted from Cursor text replay: ${part.detail ?? "auto"}]`)
     .join("\n");
 }
 
+const BASE64_PATTERN = /^[A-Za-z0-9+/]*={0,2}$/;
+
+/**
+ * Decode a Codex inline image into Cursor wire bytes.
+ *
+ * `OcxImageContent.imageUrl` is either a `data:` URL or a remote https URL, so this cannot reuse
+ * the MCP helper (which takes bare base64 plus a separate mime). It layers strict validation over
+ * the shared `parseDataUrl` rather than tightening it, because Anthropic, Google, and Command Code
+ * share that parser. `Buffer.from(x, "base64")` accepts many invalid strings silently, so the
+ * charset is checked explicitly. Remote URLs are out of scope: `McpImageContent` needs bytes, and
+ * fetching here would put network IO inside request construction.
+ */
+function decodeInlineImage(imageUrl: string): { bytes: Uint8Array; mimeType: string } | undefined {
+  const parsed = parseDataUrl(imageUrl);
+  if (!parsed) return undefined;
+  const base64 = parsed.base64.trim();
+  if (base64.length === 0 || base64.length % 4 !== 0 || !BASE64_PATTERN.test(base64)) return undefined;
+  try {
+    const bytes = Uint8Array.from(Buffer.from(base64, "base64"));
+    if (bytes.length === 0) return undefined;
+    return { bytes, mimeType: parsed.mediaType || "application/octet-stream" };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * A degraded image must never make a step LARGER than the legacy encoding did, or this change
+ * could fail admission for a request that previously fit. The old placeholder was
+ * `[image input unsupported by Cursor adapter phase 3: <detail>]`; anything we emit in its place
+ * is truncated to that budget so the zero-image case is byte-bounded by the pre-change behavior.
+ */
+const LEGACY_IMAGE_PLACEHOLDER_BUDGET =
+  "[image input unsupported by Cursor adapter phase 3: auto]".length;
+
+function imagePlaceholder(reason: string): string {
+  const text = `[image omitted: ${reason}]`;
+  return text.length <= LEGACY_IMAGE_PLACEHOLDER_BUDGET
+    ? text
+    : `${text.slice(0, LEGACY_IMAGE_PLACEHOLDER_BUDGET - 1)}]`;
+}
+
+type DecodedResultPart =
+  | { kind: "text"; text: string }
+  | { kind: "image"; bytes: Uint8Array; mimeType: string }
+  | { kind: "undecodable" };
+
+/**
+ * Decode a tool result's parts ONCE. `toolCallStep` may re-serialize a step several times while
+ * shrinking it to fit blob admission, and decoding base64 on every attempt made that loop
+ * quadratic (an audit measured ~3s for 100 images).
+ */
+function decodeResultParts(message: OcxToolResultMessage): DecodedResultPart[] | undefined {
+  const content = message.content;
+  if (typeof content === "string") return undefined;
+  return content.map((part): DecodedResultPart => {
+    if (part.type === "text") return { kind: "text", text: part.text };
+    const decoded = decodeInlineImage(part.imageUrl);
+    return decoded ? { kind: "image", ...decoded } : { kind: "undecodable" };
+  });
+}
+
+function countImages(parts: DecodedResultPart[] | undefined): number {
+  return parts ? parts.filter(p => p.kind === "image").length : 0;
+}
+
+/**
+ * Build the wire content items for a tool result, preserving part order.
+ *
+ * Images become real `McpImageContent` — the Cursor schema has an image case on
+ * `McpToolResultContentItem`, and `native-exec-mcp.ts` already uses it for MCP-invoked tools.
+ * Flattening them to placeholder text blinded every screenshot-returning tool (Computer Use,
+ * browser QA) that Codex routes through this path.
+ */
+function toolResultContentItems(
+  message: OcxToolResultMessage,
+  decoded?: DecodedResultPart[],
+  maxImages = Number.POSITIVE_INFINITY,
+) {
+  const parts = decoded ?? decodeResultParts(message);
+  if (!parts) {
+    const text = typeof message.content === "string" ? message.content : "";
+    return [create(McpToolResultContentItemSchema, {
+      content: { case: "text" as const, value: create(McpTextContentSchema, { text }) },
+    })];
+  }
+  // Images are dropped OLDEST first when the step must shrink: the most recent screenshot is the
+  // one the model is reasoning about, so it is the last to go.
+  const totalImages = countImages(parts);
+  const allowed = Math.max(0, Math.min(totalImages, maxImages));
+  let seen = 0;
+  // Consecutive text runs are newline-joined into ONE item, exactly as the legacy encoding did.
+  // Emitting one protobuf item per part adds per-item framing, which was enough to push a
+  // previously admissible step past the blob ceiling (round-3 audit: 1020 -> 1025 bytes at a
+  // 1024 limit). A result with no images must serialize identically to before this feature.
+  const items: ReturnType<typeof create<typeof McpToolResultContentItemSchema>>[] = [];
+  let pendingText: string[] = [];
+  const flushText = () => {
+    if (pendingText.length === 0) return;
+    const text = pendingText.join("\n");
+    pendingText = [];
+    items.push(create(McpToolResultContentItemSchema, {
+      content: { case: "text" as const, value: create(McpTextContentSchema, { text }) },
+    }));
+  };
+  for (const part of parts) {
+    if (part.kind === "text") {
+      pendingText.push(part.text);
+      continue;
+    }
+    if (part.kind === "undecodable") {
+      pendingText.push(imagePlaceholder("no inline data"));
+      continue;
+    }
+    seen++;
+    if (seen <= totalImages - allowed) {
+      pendingText.push(imagePlaceholder(`${part.bytes.byteLength}B over step limit`));
+      continue;
+    }
+    flushText();
+    items.push(create(McpToolResultContentItemSchema, {
+      content: { case: "image" as const, value: create(McpImageContentSchema, {
+        data: part.bytes,
+        mimeType: part.mimeType,
+      }) },
+    }));
+  }
+  flushText();
+  if (items.length === 0) {
+    items.push(create(McpToolResultContentItemSchema, {
+      content: { case: "text" as const, value: create(McpTextContentSchema, { text: "" }) },
+    }));
+  }
+  return items;
+}
+
 function toolResultToText(message: OcxToolResultMessage): string {
   return [
     "[tool_result]",
@@ -359,7 +498,8 @@ function toolCallStep(
   const args: Record<string, Uint8Array> = {};
   for (const [key, value] of Object.entries(part.arguments ?? {})) args[key] = argBytes(value);
   const toolName = namespacedToolName(part.namespace, part.name);
-  return storeCursorBlob(toBinary(ConversationStepSchema, create(ConversationStepSchema, {
+  const decodedResult = result ? decodeResultParts(result) : undefined;
+  const serialize = (maxImages: number): Uint8Array => toBinary(ConversationStepSchema, create(ConversationStepSchema, {
     message: {
       case: "toolCall",
       value: create(ToolCallSchema, {
@@ -373,23 +513,34 @@ function toolCallStep(
               providerIdentifier: OCX_RESPONSES_TOOL_PROVIDER,
               args,
             }),
-            ...(result ? { result: toolResultPart(result) } : {}),
+            ...(result ? { result: toolResultPart(result, decodedResult, maxImages) } : {}),
           }),
         },
       }),
     },
-  })), requestScope);
+  }));
+
+  // A step is stored as ONE blob, so its images share an entry with the call's arguments, text,
+  // mime strings, and protobuf framing. A byte budget over decoded images alone cannot bound that
+  // (an audit reproduced a 448-byte-argument call whose 460-byte image pushed a previously
+  // admitted step past the ceiling). Measure the real serialized size instead, then drop images —
+  // oldest first, so the most recent screenshot survives — until the step fits.
+  const limit = cursorBlobMaxEntryBytes();
+  const imageCount = countImages(decodedResult);
+  let encoded = serialize(imageCount);
+  for (let allowed = imageCount - 1; allowed >= 0 && encoded.byteLength > limit; allowed--) {
+    encoded = serialize(allowed);
+  }
+  return storeCursorBlob(encoded, requestScope);
 }
 
-function toolResultPart(message: OcxToolResultMessage) {
+function toolResultPart(message: OcxToolResultMessage, decoded?: DecodedResultPart[], maxImages?: number) {
   return create(McpToolResultSchema, {
     result: {
       case: "success",
       value: create(McpSuccessSchema, {
         isError: message.isError,
-        content: [create(McpToolResultContentItemSchema, {
-          content: { case: "text", value: create(McpTextContentSchema, { text: contentToText(message.content) }) },
-        })],
+        content: toolResultContentItems(message, decoded, maxImages),
       }),
     },
   });

package/src/adapters/cursor/request-builder.ts

@@ -205,7 +205,15 @@ function contentPartToText(part: OcxContentPart | OcxAssistantContentPart): stri
     case "thinking":
       return part.thinking;
     case "image":
-      return `[image input unsupported by Cursor adapter phase 3: ${part.detail ?? "auto"}]`;
+      // User-message images are still flattened here: this path builds the plain-text prompt, and
+      // the schema slot that could carry them (UserMessage.selectedContext.selectedImages) is not
+      // populated by this adapter. The tool-result ENCODER does build real McpImageContent
+      // (see protobuf-request.ts), so the old "unsupported by Cursor adapter" wording is no
+      // longer true of the encoder — but note that nothing reaches Cursor today either way:
+      // every Cursor model is in noVisionModels (providers/registry.ts), so the vision sidecar
+      // describes or strips images before this adapter runs. Kept the same length to avoid
+      // shifting any byte-budgeted prompt path.
+      return `[image omitted from this Cursor text prompt: ${part.detail ?? "auto"}]`;
     case "toolCall":
       // Cursor does not accept OpenAI Responses assistant tool-call parts as native history here.
       // Rendering them as visible "[tool_call]" text leaks synthetic protocol markers back into

package/src/adapters/cursor/tool-definitions.ts

@@ -525,7 +525,12 @@ export function nonEmptyShellBridgeCommandFromArgs(
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
   const record = parsed as Record<string, unknown>;
-  for (const key of shellBridgeRequiredCommandKeys(toolName, schema)) {
+  const requiredKeys = shellBridgeRequiredCommandKeys(toolName, schema);
+  const candidateKeys = new Set<"cmd" | "command">([
+    ...requiredKeys,
+    requiredKeys.includes("cmd") ? "command" : "cmd",
+  ]);
+  for (const key of candidateKeys) {
     const value = record[key];
     if (typeof value === "string" && value.trim().length > 0) return value.trim();
   }
@@ -615,7 +620,7 @@ export function buildCursorToolGuidanceSystemNote(
     // Code mode: shell/edit/MCP live inside freeform `exec` as nested helpers. Without this the
     // model probes for a top-level shell tool that is not there.
     codeMode
-      ? `\`${CODEX_UNIFIED_EXEC_TOOL}\` is Codex code mode: its body is JavaScript evaluated in a V8 isolate, not a shell command and not Node. Shell, file edits, and MCP are nested helpers called INSIDE that body as \`await tools.<name>(...)\`, for example \`await tools.exec_command({cmd: \"ls\"})\`. Read the tool description for the exact nested helpers this turn provides. Those nested helpers are not themselves top-level tools, so do not call \`exec_command\`, \`shell_command\`, or \`apply_patch\` at the top level here${codeModeOtherTopLevelNames.length > 0 ? `; every other tool this turn lists, including ${quotedNames(codeModeOtherTopLevelNames)}, remains callable at the top level as usual` : ""}.`
+      ? `\`${CODEX_UNIFIED_EXEC_TOOL}\` is Codex code mode: its body is JavaScript evaluated in a V8 isolate, not a shell command and not Node. Shell, file edits, and MCP are nested helpers called INSIDE that body as \`await tools.<name>(...)\`, for example \`await tools.exec_command({cmd: \"ls\"})\`. Read the tool description and the isolate global \`ALL_TOOLS\` (not \`tools.ALL_TOOLS\`) for helpers this turn provides; absence from the top-level catalog or from \`exec\`'s description is not absence. Those nested helpers are not themselves top-level tools, so do not call \`exec_command\` or \`shell_command\` at the top level here${codeModeOtherTopLevelNames.length > 0 ? `; every other tool this turn lists, including ${quotedNames(codeModeOtherTopLevelNames)}, remains callable at the top level as usual` : ""}.`
       : undefined,
     codeMode
       ? "In code mode the isolate returns nothing on its own: call `text(...)` (or `notify(...)`) on any value you need to see, or the call completes with empty output. There is no `require`, no `module`, and no filesystem or network globals; reach the host only through the nested helpers."

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

@@ -9,7 +9,7 @@ import { antigravityUserAgent } from "./client-fingerprint";
  * sends. The IDE client family is also required to unlock newer agent models (the backend 404s
  * CLI-shaped UAs for `gemini-3.7-*`). A `GOOGLE_ANTIGRAVITY_USER_AGENT` override still wins.
  */
-export const ANTIGRAVITY_REQUEST_UA = process.env.GOOGLE_ANTIGRAVITY_USER_AGENT || antigravityUserAgent();
+export const ANTIGRAVITY_REQUEST_UA = antigravityUserAgent();
 
 /**
  * Whether a stored `OcxToolCall.thoughtSignature` is a REAL upstream Gemini signature versus a

package/src/adapters/google.ts

@@ -48,19 +48,17 @@ const GOOGLE_BREVITY_INSTRUCTION = [
 ].join("\n");
 
 /**
- * Google renamed the current Gemini Flash generations on the Generative Language API,
- * appending a `-tiered` suffix (`gemini-3.7-flash` -> `gemini-3.7-flash-tiered`). The
- * old `gemini-3.7-flash` path 404s, so a saved config or registry entry naming the base
- * id must be resolved here before it reaches the URL. The user-facing id is deliberately
- * left alone: the picker, the catalog, the usage log and the price overlays all stay
- * keyed on the base id, and only the wire path learns the new spelling.
+ * Some Google direct deployments expose current Gemini Flash generations with a `-tiered`
+ * wire suffix (`gemini-3.7-flash` -> `gemini-3.7-flash-tiered`). Keep the picker-visible id
+ * stable and make the mapping configurable for deployments that still serve the bare id.
  */
 const GEMINI_DIRECT_WIRE_RENAMES: Record<string, string> = {
   "gemini-3.7-flash": "gemini-3.7-flash-tiered",
   "gemini-3.6-flash": "gemini-3.6-flash-tiered",
 };
 
-function resolveDirectGeminiWireModelId(modelId: string): string {
+function resolveDirectGeminiWireModelId(modelId: string, applyRenames: boolean): string {
+  if (!applyRenames) return modelId;
   return Object.hasOwn(GEMINI_DIRECT_WIRE_RENAMES, modelId)
     ? GEMINI_DIRECT_WIRE_RENAMES[modelId]!
     : modelId;
@@ -147,7 +145,7 @@ function geminiToolResultText(content: string | OcxContentPart[]): string {
 
 function messagesToGeminiFormat(
   parsed: OcxParsedRequest,
-  routedModelId = parsed.modelId,
+  identityModelId: string,
 ): { systemInstruction?: unknown; contents: unknown[] } {
   // Neutralize Codex's GPT-5 identity line (Gemini/Antigravity share this path) so a routed model
   // never misreports as GPT-5/OpenAI, and never leaks the proxy identity upstream.
@@ -156,7 +154,7 @@ function messagesToGeminiFormat(
     ...(parsed.context.systemPrompt ?? []),
     ...(toolCatalogNudge ? [toolCatalogNudge] : []),
     GOOGLE_BREVITY_INSTRUCTION,
-  ].join("\n\n"), routedModelId);
+  ].join("\n\n"), identityModelId);
   const systemInstruction = { parts: [{ text: systemText }] };
 
   const contents: unknown[] = [];
@@ -395,9 +393,14 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         ? resolveAntigravityEffortWireModel(
             parsed.modelId,
             mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning),
+            provider.baseUrl,
           ).wireModelId
-        : resolveDirectGeminiWireModelId(parsed.modelId);
-      const { systemInstruction, contents } = messagesToGeminiFormat(parsed, routedModelId);
+        : provider.googleMode === "vertex"
+          ? parsed.modelId
+          : resolveDirectGeminiWireModelId(parsed.modelId, provider.directGeminiWireRenames !== false);
+      // AI Studio's `-tiered` spelling is wire-only; CCA aliases may migrate to another generation.
+      const identityModelId = provider.googleMode === "cloud-code-assist" ? routedModelId : parsed.modelId;
+      const { systemInstruction, contents } = messagesToGeminiFormat(parsed, identityModelId);
       const tools = toolsToGeminiFormat(parsed);
 
       const body: Record<string, unknown> = { contents };
@@ -450,7 +453,11 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         if (!project) throw new Error("Antigravity requires a discovered Cloud Code Assist project id (re-run `ocx login google-antigravity`).");
         const sessionId = antigravitySessionId(parsed);
         const mappedEffort = mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning);
-        const { wireModelId, thinkingLevel } = resolveAntigravityEffortWireModel(parsed.modelId, mappedEffort);
+        const { wireModelId, thinkingLevel } = resolveAntigravityEffortWireModel(
+          parsed.modelId,
+          mappedEffort,
+          provider.baseUrl,
+        );
         antigravityModel = wireModelId;
         antigravitySession = sessionId;
         // Effort → thinkingConfig for CCA (CLIProxyAPI proven: request.generationConfig.thinkingConfig).
@@ -939,9 +946,20 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
       }
 
       const usage = json.usageMetadata as Record<string, number> | undefined;
+      // Mirror the streaming path: a buffered turn cut off by the token limit or a content filter
+      // must carry its stop reason, or the bridge sees a clean `done` and reports the truncated
+      // turn as completed — and, on a compaction turn, installs the half-written summary as
+      // replacement history (#422).
+      const finishReason = candidates?.[0]?.finishReason as string | undefined;
+      const stopReason = finishReason === "MAX_TOKENS"
+        ? "max_tokens"
+        : ["SAFETY", "RECITATION", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII"].includes(finishReason ?? "")
+          ? "content_filter"
+          : undefined;
       events.push({
         type: "done",
         usage: usageFromGemini(usage),
+        ...(stopReason ? { stopReason } : {}),
       });
       return finish(events);
     },

package/src/adapters/openai-responses-url.ts

@@ -7,8 +7,10 @@ const TRAILING_V1 = /\/v1\/?$/;
  *  Custom `responsesPath` stays on the adapter; this helper is only the legacy /v1/responses branch.
  */
 export function openaiResponsesUrl(baseUrl: string): string {
-  const trimmed = baseUrl.trim().replace(TRAILING_SLASHES, "");
-  const withoutEndpoint = trimmed.replace(TRAILING_RESPONSES, "");
+  const url = new URL(baseUrl.trim());
+  const trimmedPath = url.pathname.replace(TRAILING_SLASHES, "");
+  const withoutEndpoint = trimmedPath.replace(TRAILING_RESPONSES, "");
   const withoutV1 = withoutEndpoint.replace(TRAILING_V1, "");
-  return `${withoutV1}/v1/responses`;
+  url.pathname = `${withoutV1}/v1/responses`;
+  return url.toString();
 }

package/src/adapters/registry.ts

@@ -1,6 +1,7 @@
 import { createAnthropicAdapter } from "./anthropic";
 import { createAzureAdapter } from "./azure";
 import type { ProviderAdapter } from "./base";
+import { withClinePassDeepSeekV4ToolReplayCompatibility } from "./cline-pass-deepseek-v4-tool-replay";
 import { createCommandCodeAdapter } from "./command-code";
 import { createCursorAdapter } from "./cursor";
 import { createGoogleAdapter } from "./google";
@@ -57,7 +58,8 @@ export const ADAPTER_REGISTRY = {
   "openai-chat": {
     wire: "openai-chat",
     mutation: "codex-owned",
-    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createOpenAIChatAdapter(provider),
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) =>
+      withClinePassDeepSeekV4ToolReplayCompatibility(createOpenAIChatAdapter(provider)),
   },
   anthropic: {
     wire: "anthropic",

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

@@ -17,8 +17,40 @@ import {
 // included it either.
 const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS"] as const;
 
+/**
+ * The two halves of the code-mode shape, kept provider-neutral here.
+ *
+ * `./cursor/tool-definitions.ts` owns the Cursor-scoped versions of these
+ * (`isCursorCodeModeExecTool` / `isBareCodexShellBridgeTool`), but those additionally require
+ * the Cursor Responses namespace. This nudge is shared by Anthropic, Google, Kiro,
+ * OpenAI-chat and command-code, so it needs the same semantics without that provider gate.
+ */
+const CODEX_UNIFIED_EXEC_TOOL_NAME = "exec";
+const CODEX_SHELL_BRIDGE_TOOL_NAMES = ["exec_command", "shell_command"] as const;
+
+function isCodexCodeModeExecTool(tool: Pick<OcxTool, "namespace" | "name" | "freeform">): boolean {
+  return !tool.namespace && tool.name === CODEX_UNIFIED_EXEC_TOOL_NAME && tool.freeform === true;
+}
+
+/**
+ * BARE means un-namespaced, and the word is load-bearing.
+ *
+ * An MCP server can advertise its own `exec_command` or `shell_command` — a docker, k8s or ssh
+ * server plausibly does — and those arrive namespaced (`mcp__docker__exec_command`). They are
+ * not Codex's shell bridge, so they must not cancel code mode: a genuine code-mode turn that
+ * merely happens to sit beside an MCP shell tool would lose its guidance and fall back to the
+ * generic sentence.
+ *
+ * The Cursor original this was ported from (`isBareCodexShellBridgeTool`) carries the same
+ * `!tool.namespace` requirement; dropping it here made the name assert a check the body did not
+ * perform.
+ */
+function isBareShellBridgeTool(tool: Pick<OcxTool, "namespace" | "name">): boolean {
+  return !tool.namespace && (CODEX_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).includes(tool.name);
+}
+
 function quoteNames(names: readonly string[]): string {
-  return names.map(name => `\`${name}\``).join(", ");
+  return names.map(name => "`" + name + "`").join(", ");
 }
 
 function uniqueNames(names: readonly string[]): string[] {
@@ -40,9 +72,33 @@ export function shouldInjectNonOpenAIToolCatalogNudge(provider: Pick<OcxProvider
   }
 }
 
+/**
+ * Codex code mode is a SEMANTIC property, not a name.
+ *
+ * The tool that carries it is a `freeform` `exec` whose body is JavaScript evaluated in a V8
+ * isolate, advertised alongside no bare shell bridge. A provider is free to advertise an
+ * ordinary structured tool called `exec` that runs a shell string — and a catalog can list
+ * `exec` next to `exec_command`/`shell_command`, which is the flat-bridge shape, not code mode.
+ *
+ * Classifying on the name alone would tell those turns that `exec` takes JavaScript and that
+ * shell is only reachable as a nested `tools.*` helper. Both are false there, and a model that
+ * believes them sends the wrong arguments or avoids a legitimate execution tool entirely.
+ *
+ * So callers that HAVE the tool objects decide with the semantic predicate and pass the verified
+ * wire name in; the name-only entry point cannot decide it and does not try.
+ */
+function codeModeExecWireName(
+  advertised: ReadonlySet<string>,
+  verifiedName: string | undefined,
+): string | undefined {
+  if (!verifiedName) return undefined;
+  return advertised.has(verifiedName) ? verifiedName : undefined;
+}
+
 export function buildNonOpenAIToolCatalogNudgeFromNames(
   wireNames: readonly string[] | undefined,
   toWireName: (name: string) => string = name => name,
+  codeModeExecName?: string,
 ): string | undefined {
   const names = uniqueNames(wireNames ?? []);
   if (names.length === 0) return undefined;
@@ -50,21 +106,24 @@ export function buildNonOpenAIToolCatalogNudgeFromNames(
   const advertised = new Set(names);
   // Compare in the catalog's own coordinate system. `advertised` holds WIRE names, so a
   // provider that rewrites them (Claude OAuth `custom_`, Anthropic compat `cx_`) would never
-  // match a bare neighbor name and would forbid tools the turn actually advertises — the
+  // match a bare neighbor name and would forbid tools the turn actually advertises -- the
   // catalog would list `custom_apply_patch` while the same sentence banned `apply_patch`.
   const unavailableNeighborNames = NEIGHBOR_AGENT_TOOL_NAMES.filter(
     name => !advertised.has(name) && !advertised.has(toWireName(name)),
   );
+  const verifiedCodeModeExecName = codeModeExecWireName(advertised, codeModeExecName);
 
   return [
     "Tool contract: use the current tool catalog as ground truth.",
-    `Valid tool names for this turn are exactly ${quoteNames(names)}.`,
+    "Valid tool names for this turn are exactly " + quoteNames(names) + ".",
     "These listed names are the complete top-level tool-call surface for this turn.",
     "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.",
-    "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.",
+    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."
+      : "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.`
+      ? "Do not use neighboring-agent tool names " + quoteNames(unavailableNeighborNames) + " unless this turn's catalog lists those exact names."
       : undefined,
     "If you need shell, file search, file read, edit, or discovery behavior, choose the listed tool that provides that capability.",
     "Count a tool call only after its tool result returns; batch independent read-only calls when the runtime supports it.",
@@ -72,16 +131,24 @@ export function buildNonOpenAIToolCatalogNudgeFromNames(
 }
 
 export function buildNonOpenAIToolCatalogNudgeForTools(
-  tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
+  tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
   toolChoice?: OcxRequestOptions["toolChoice"],
   toWireName: (tool: Pick<OcxTool, "namespace" | "name">) => string = tool => namespacedToolName(tool.namespace, tool.name),
 ): string | undefined {
-  const visibleNames = tools
-    ?.filter(toolChoiceToolPredicate(toolChoice))
-    .map(toWireName);
+  const visible = tools?.filter(toolChoiceToolPredicate(toolChoice));
+  const visibleNames = visible?.map(toWireName);
+  // Decide code mode from the tool OBJECTS, while the `freeform` flag still exists — reducing
+  // to wire names first throws away the only thing that distinguishes Codex's JavaScript
+  // `exec` from an ordinary structured tool that happens to share the name.
+  const codeModeExecTool = visible?.find(isCodexCodeModeExecTool);
+  const codeModeExecName = codeModeExecTool
+    && !visible?.some(isBareShellBridgeTool)
+    ? toWireName(codeModeExecTool)
+    : undefined;
   // Neighbor names are bare and un-namespaced, so probe the same transform with a bare tool.
   return buildNonOpenAIToolCatalogNudgeFromNames(
     visibleNames,
     name => toWireName({ name }),
+    codeModeExecName,
   );
 }