@iislee/opencodex 2.11.0 → 2.35.0

package/src/adapters/registry.ts

@@ -0,0 +1,175 @@
+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";
+import { createKiroAdapter } from "./kiro";
+import { createMimoFreeAdapter } from "./mimo-free";
+import { createOpenAIChatAdapter } from "./openai-chat";
+import { createResponsesPassthroughAdapter } from "./openai-responses";
+import type { OcxProviderConfig } from "../types";
+import { createAdapterTierMetadata } from "../providers/fastwire";
+
+export type AdapterCacheRetention = "none" | "short" | "long";
+
+export interface AdapterFactoryContext {
+  cacheRetention?: AdapterCacheRetention;
+}
+
+export type AdapterWire =
+  | "command-code"
+  | "openai-chat"
+  | "anthropic"
+  | "openai-responses"
+  | "google"
+  | "kiro"
+  | "cursor";
+
+export type AdapterMutationContract =
+  | "codex-owned"
+  | "codex-owned-with-gated-native-fallback";
+
+type AdapterFactory = (
+  provider: OcxProviderConfig,
+  context: AdapterFactoryContext,
+) => ProviderAdapter;
+
+type DirectAdapterDefinition = {
+  wire: AdapterWire;
+  mutation: AdapterMutationContract;
+  create: AdapterFactory;
+};
+
+type InheritedAdapterDefinition = {
+  /** Semantic contract inheritance only. Runtime construction remains independent. */
+  contractParent: string;
+  create: AdapterFactory;
+};
+
+type AdapterDefinition = DirectAdapterDefinition | InheritedAdapterDefinition;
+
+export const ADAPTER_REGISTRY = {
+  "command-code": {
+    wire: "command-code",
+    mutation: "codex-owned",
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createCommandCodeAdapter(provider),
+  },
+  "openai-chat": {
+    wire: "openai-chat",
+    mutation: "codex-owned",
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) =>
+      withClinePassDeepSeekV4ToolReplayCompatibility(createOpenAIChatAdapter(provider)),
+  },
+  anthropic: {
+    wire: "anthropic",
+    mutation: "codex-owned",
+    create: (provider: OcxProviderConfig, context: AdapterFactoryContext) =>
+      createAnthropicAdapter(provider, context.cacheRetention),
+  },
+  "openai-responses": {
+    wire: "openai-responses",
+    mutation: "codex-owned",
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) =>
+      createResponsesPassthroughAdapter(provider),
+  },
+  google: {
+    wire: "google",
+    mutation: "codex-owned",
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createGoogleAdapter(provider),
+  },
+  kiro: {
+    wire: "kiro",
+    mutation: "codex-owned",
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createKiroAdapter(provider),
+  },
+  azure: {
+    contractParent: "openai-responses",
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createAzureAdapter(provider),
+  },
+  "azure-openai": {
+    contractParent: "openai-responses",
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createAzureAdapter(provider),
+  },
+  cursor: {
+    wire: "cursor",
+    mutation: "codex-owned-with-gated-native-fallback",
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createCursorAdapter(provider),
+  },
+  "mimo-free": {
+    contractParent: "openai-chat",
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createMimoFreeAdapter(provider),
+  },
+} as const satisfies Record<string, AdapterDefinition>;
+
+export type AdapterId = keyof typeof ADAPTER_REGISTRY;
+export type RegisteredAdapterDefinition = typeof ADAPTER_REGISTRY[AdapterId];
+
+export function adapterDefinitions(): Array<[AdapterId, RegisteredAdapterDefinition]> {
+  return Object.entries(ADAPTER_REGISTRY) as Array<[AdapterId, RegisteredAdapterDefinition]>;
+}
+
+export function getAdapterDefinition(adapterId: unknown): RegisteredAdapterDefinition | undefined {
+  if (typeof adapterId !== "string" || !Object.hasOwn(ADAPTER_REGISTRY, adapterId)) return undefined;
+  return ADAPTER_REGISTRY[adapterId as AdapterId];
+}
+
+export function effectiveAdapterContract(adapterId: string): Readonly<{
+  wire: AdapterWire;
+  mutation: AdapterMutationContract;
+}> {
+  const visited = new Set<string>();
+  let current = adapterId;
+
+  while (true) {
+    if (visited.has(current)) {
+      throw new Error(`Adapter contract cycle detected at ${current}`);
+    }
+    visited.add(current);
+
+    const definition = getAdapterDefinition(current);
+    if (!definition) throw new Error(`Unknown adapter: ${current}`);
+    if ("wire" in definition) {
+      return { wire: definition.wire, mutation: definition.mutation };
+    }
+    current = definition.contractParent;
+  }
+}
+
+export function createRegisteredAdapter(
+  provider: OcxProviderConfig,
+  context: AdapterFactoryContext = {},
+): ProviderAdapter {
+  const definition = getAdapterDefinition(provider.adapter);
+  if (!definition) throw new Error(`Unknown adapter: ${provider.adapter}`);
+  const adapter = definition.create(provider, context);
+  const buildRequest = adapter.buildRequest.bind(adapter);
+  adapter.buildRequest = (parsed, incoming) => {
+    const attachTierMetadata = (request: Awaited<ReturnType<ProviderAdapter["buildRequest"]>>) => {
+      // OpenAI-family adapters report the exact emitted field themselves. Other adapters
+      // still report an exact absence at this serialization boundary, which makes a routed
+      // Fast downgrade observable without asking core to infer an outbound body shape.
+      request.tierLog ??= createAdapterTierMetadata(
+        parsed.options.tierObservation,
+        parsed.options.tierDecision,
+        null,
+        null,
+      );
+      return request;
+    };
+    const request = buildRequest(parsed, incoming);
+    return request instanceof Promise
+      ? request.then(attachTierMetadata)
+      : attachTierMetadata(request);
+  };
+  if (adapter.runTurn && !adapter.tierLogForRunTurn) {
+    adapter.tierLogForRunTurn = parsed => createAdapterTierMetadata(
+      parsed.options.tierObservation,
+      parsed.options.tierDecision,
+      null,
+      null,
+    );
+  }
+  return adapter;
+}

package/src/adapters/responses-tool-schema.ts

@@ -0,0 +1,67 @@
+// Codex multi-agent v2 stamps a Responses-only `encrypted: true` marker on
+// collaboration tool schemas (openai/codex 5f4d06ef; issue #85). It is an
+// annotation for the ChatGPT backend only, so translated provider schemas must
+// drop it without removing properties or definitions literally named `encrypted`.
+const ENCRYPTED_MARKER_NAME_BAG_KEYS = new Set([
+  "properties",
+  "patternProperties",
+  "$defs",
+  "definitions",
+  "dependencies",
+  "dependentSchemas",
+  "dependentRequired",
+]);
+const ENCRYPTED_MARKER_LITERAL_VALUE_KEYS = new Set(["const", "default", "enum", "examples"]);
+
+/**
+ * The schema is caller-supplied, so its nesting depth is attacker-influenced. Native recursion
+ * would turn a deep schema into a stack overflow that takes down the request path, so this walks
+ * an explicit stack instead: depth costs heap, which is bounded and recoverable.
+ */
+export function stripResponsesOnlyEncryptedMarker(node: unknown, inNameBag = false): unknown {
+  type Assign = (value: unknown) => void;
+  interface Frame { node: unknown; inNameBag: boolean; assign: Assign }
+
+  let result: unknown;
+  const stack: Frame[] = [{ node, inNameBag, assign: value => { result = value; } }];
+
+  while (stack.length > 0) {
+    const frame = stack.pop()!;
+    const current = frame.node;
+
+    if (Array.isArray(current)) {
+      const out: unknown[] = new Array(current.length);
+      frame.assign(out);
+      // Array items are schemas in their own right, never a name bag.
+      for (let i = current.length - 1; i >= 0; i--) {
+        stack.push({ node: current[i], inNameBag: false, assign: value => { out[i] = value; } });
+      }
+      continue;
+    }
+    if (!current || typeof current !== "object") {
+      frame.assign(current);
+      continue;
+    }
+
+    // A schema name may be `__proto__`; a null-prototype record keeps it as data.
+    const out: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    frame.assign(out);
+
+    for (const [key, value] of Object.entries(current as Record<string, unknown>)) {
+      if (frame.inNameBag) {
+        // Inside a name bag every key is a caller-chosen name, so `encrypted` here is data.
+        stack.push({ node: value, inNameBag: false, assign: v => { out[key] = v; } });
+      } else if (key !== "encrypted") {
+        if (ENCRYPTED_MARKER_LITERAL_VALUE_KEYS.has(key)) {
+          // Literal payloads are values, not schemas: an `encrypted` key inside them is data.
+          out[key] = value;
+        } else {
+          const childInNameBag = ENCRYPTED_MARKER_NAME_BAG_KEYS.has(key);
+          stack.push({ node: value, inNameBag: childInNameBag, assign: v => { out[key] = v; } });
+        }
+      }
+    }
+  }
+
+  return result;
+}

package/src/adapters/run-turn-queue.ts

@@ -4,6 +4,13 @@ type QueueReader = (result: IteratorResult<AdapterEvent>) => void;
 
 export const PREFLIGHT_HEARTBEAT_RETAIN_LIMIT = 16;
 
+/**
+ * Coalescing threshold for adjacent text/thinking deltas buffered with no
+ * waiting reader (UTF-16 code units). This is a merge-size ceiling, not a
+ * byte-memory cap: a single oversized incoming event stays one item.
+ */
+export const COALESCE_MAX_CHUNK_LENGTH = 64 * 1024;
+
 export interface AdapterEventQueue {
   push(event: AdapterEvent): void;
   close(): void;
@@ -64,6 +71,33 @@ export function createAdapterEventQueue(opts?: {
   const maxBacklog = opts?.maxBacklog ?? 1_024;
   let closed = false;
 
+  // Merge an incoming delta into the buffered tail when no reader is waiting.
+  // The backlog cap counts events, not tokens, so a detached or briefly
+  // stalled consumer (e.g. a Codex app mid-reconnect whose disconnect Bun has
+  // not yet delivered) used to hit the cap within seconds of token-granular
+  // streaming and abort a healthy turn. Adjacent same-phase text deltas,
+  // adjacent thinking deltas, and consecutive heartbeats carry no ordering
+  // information between themselves, so merging them preserves every consumer
+  // contract while making the cap approximate buffered items again.
+  // Pushed objects may be retained by adapters, so the tail is REPLACED with
+  // a fresh object — never mutated (alias safety).
+  const coalesceIntoTail = (event: AdapterEvent): boolean => {
+    const tail = queued[queued.length - 1];
+    if (!tail) return false;
+    if (event.type === "heartbeat") return tail.type === "heartbeat";
+    if (event.type === "text_delta" && tail.type === "text_delta" && tail.phase === event.phase) {
+      if (tail.text.length + event.text.length > COALESCE_MAX_CHUNK_LENGTH) return false;
+      queued[queued.length - 1] = { type: "text_delta", text: tail.text + event.text, phase: tail.phase };
+      return true;
+    }
+    if (event.type === "thinking_delta" && tail.type === "thinking_delta") {
+      if (tail.thinking.length + event.thinking.length > COALESCE_MAX_CHUNK_LENGTH) return false;
+      queued[queued.length - 1] = { type: "thinking_delta", thinking: tail.thinking + event.thinking };
+      return true;
+    }
+    return false;
+  };
+
   const push = (event: AdapterEvent): void => {
     if (closed) return;
     const reader = readers.shift();
@@ -71,9 +105,10 @@ export function createAdapterEventQueue(opts?: {
       reader({ done: false, value: event });
       return;
     }
+    if (coalesceIntoTail(event)) return;
     if (queued.length >= maxBacklog) {
       opts?.onBacklogExceeded?.();
-      queued.push({ type: "error", message: "consumer backlog exceeded — turn aborted" });
+      queued.push({ type: "error", message: "consumer stalled: adapter event backlog exceeded — turn aborted" });
       close();
       return;
     }

package/src/adapters/tool-call-id.ts

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Anthropic rejects a `tool_use.id` longer than this. Collision disambiguation has to fit
+ * inside it too, which is why candidates are assembled from parts instead of sliced at the end.
+ */
+export const MAX_TOOL_CALL_ID_LENGTH = 64;
+
+/** Hex characters of the deterministic tail. Fixed width: it is a discriminator, not a payload. */
+const TOOL_CALL_ID_HASH_WIDTH = 8;
+
+const CONFORMING_TOOL_CALL_ID = /^[a-zA-Z0-9_-]+$/;
+
+/** An id Anthropic accepts as-is: right character set AND within the length bound. */
+export function isConformingToolCallId(rawId: string): boolean {
+  return rawId.length > 0
+    && rawId.length <= MAX_TOOL_CALL_ID_LENGTH
+    && CONFORMING_TOOL_CALL_ID.test(rawId);
+}
+
+/**
+ * The parts a rewritten id is built from: the sanitized prefix and a deterministic tail
+ * derived from the raw id. Kept separate so collision handling can truncate the prefix
+ * without destroying the discriminator.
+ */
+function toolCallIdComponents(rawId: string | undefined): { cleaned: string; hash: string } | undefined {
+  const raw = rawId ?? "";
+  if (raw.length === 0) return undefined;
+  const cleaned = raw.replace(/[^a-zA-Z0-9_-]/g, "_");
+  const hash = createHash("sha256").update(raw).digest("hex").slice(0, TOOL_CALL_ID_HASH_WIDTH);
+  return { cleaned, hash };
+}
+
+/** Assemble `prefix_hash`, truncating only the prefix, leaving `reserve` characters spare. */
+function fitToolCallId(cleaned: string, hash: string, reserve = 0): string {
+  const tail = `_${hash}`;
+  const room = MAX_TOOL_CALL_ID_LENGTH - reserve - tail.length;
+  return cleaned.slice(0, Math.max(1, room)) + tail;
+}
+
+/**
+ * Normalize a tool call id into the character set and length Anthropic accepts.
+ *
+ * This is the stateless view, kept for callers that only need the shape of one id. It is NOT
+ * injective on its own: `anthropicToolCallId("call:a")` returns something like `call_a_1f2e3d4c`,
+ * and a raw id that already equals that value is returned unchanged — two distinct sources, one
+ * wire id. Anything building a whole request must use {@link createToolCallIdAllocator}, which
+ * reserves the conforming ids first and resolves collisions.
+ *
+ * Returns `undefined` for an empty id. Callers must handle that rather than falling back to the
+ * raw value: restoring `""` puts an id on the wire that Anthropic rejects (#1767).
+ */
+export function anthropicToolCallId(rawId: string | undefined): string | undefined {
+  const raw = rawId ?? "";
+  if (raw.length === 0) return undefined;
+  if (isConformingToolCallId(raw)) return raw;
+  const parts = toolCallIdComponents(raw);
+  if (!parts) return undefined;
+  return fitToolCallId(parts.cleaned, parts.hash);
+}
+
+export type ToolCallIdAllocator = {
+  /** Claim an already-conforming source id so no rewrite can be handed the same value. */
+  reserve(rawId: string | undefined): void;
+  /** Wire id for a raw id, stable within the request. `undefined` means "not representable". */
+  allocate(rawId: string | undefined): string | undefined;
+  /** Wire id previously allocated for this raw id, without creating one. */
+  lookup(rawId: string | undefined): string | undefined;
+};
+
+/**
+ * Request-scoped raw-id to wire-id mapping.
+ *
+ * Two properties the stateless transform cannot provide:
+ *
+ * - **Injective.** Reserve every already-conforming id first, then allocate rewrites around them,
+ *   appending a numeric suffix when a candidate is taken. Two distinct raw ids never share a wire id,
+ *   including the case where one raw id already looks like another's normalized form, and including
+ *   an ordinary 32-bit hash collision.
+ * - **Stable.** A tool result asks for the same raw id its call used and gets the same wire id, so
+ *   call/result pairing survives normalization.
+ */
+export function createToolCallIdAllocator(): ToolCallIdAllocator {
+  const rawToWire = new Map<string, string>();
+  const occupied = new Set<string>();
+
+  return {
+    reserve(rawId) {
+      if (!rawId || rawToWire.has(rawId)) return;
+      if (!isConformingToolCallId(rawId)) return;
+      rawToWire.set(rawId, rawId);
+      occupied.add(rawId);
+    },
+    allocate(rawId) {
+      if (!rawId) return undefined;
+      const existing = rawToWire.get(rawId);
+      if (existing) return existing;
+      if (isConformingToolCallId(rawId) && !occupied.has(rawId)) {
+        rawToWire.set(rawId, rawId);
+        occupied.add(rawId);
+        return rawId;
+      }
+      const parts = toolCallIdComponents(rawId);
+      if (!parts) return undefined;
+      let candidate = fitToolCallId(parts.cleaned, parts.hash);
+      for (let n = 2; occupied.has(candidate); n++) {
+        const suffix = `_${n}`;
+        candidate = fitToolCallId(parts.cleaned, parts.hash, suffix.length) + suffix;
+      }
+      rawToWire.set(rawId, candidate);
+      occupied.add(candidate);
+      return candidate;
+    },
+    lookup(rawId) {
+      if (!rawId) return undefined;
+      return rawToWire.get(rawId);
+    },
+  };
+}

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

@@ -1,30 +1,63 @@
 import {
-  isAllowedToolChoice,
   namespacedToolName,
-  toolAllowedByChoice,
-  toolChoiceAliases,
+  toolChoiceToolPredicate,
   type OcxRequestOptions,
   type OcxTool,
   type OcxProviderConfig,
 } from "../types";
+import { CODE_MODE_RESULT_ECHO_SENTENCE } from "./exec-tool-result-normalize";
 
-const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS", "apply_patch"] as const;
+// 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.
+//
+// `apply_patch` is deliberately absent: it is Codex's own first-class edit tool, not a
+// neighbor's. Under Codex code mode it is reachable as a nested `tools.apply_patch(...)`
+// helper declared inside the `exec` tool description rather than as a top-level wire tool,
+// so a flat catalog check cannot see it and forbidding it pushed routed models into
+// `python3` heredoc edits. The sibling list in `./cursor/tool-definitions.ts` never
+// 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;
+
+export 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.
+ */
+export 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[] {
   return [...new Set(names.filter(name => name.trim().length > 0))];
 }
 
-function toolChoiceAllows(tool: Pick<OcxTool, "namespace" | "name">, toolChoice: OcxRequestOptions["toolChoice"] | undefined): boolean {
-  if (!toolChoice || toolChoice === "auto" || toolChoice === "required") return true;
-  if (toolChoice === "none") return false;
-  if (isAllowedToolChoice(toolChoice)) return toolAllowedByChoice(tool, new Set(toolChoice.allowedTools));
-  return toolChoiceAliases(tool).includes(toolChoice.name);
-}
-
 function isOpenAIOrChatGPTHost(hostname: string): boolean {
   return hostname === "openai.com"
     || hostname.endsWith(".openai.com")
@@ -40,19 +73,58 @@ export function shouldInjectNonOpenAIToolCatalogNudge(provider: Pick<OcxProvider
   }
 }
 
-export function buildNonOpenAIToolCatalogNudgeFromNames(wireNames: readonly string[] | undefined): string | undefined {
+/**
+ * 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;
 
   const advertised = new Set(names);
-  const unavailableNeighborNames = NEIGHBOR_AGENT_TOOL_NAMES.filter(name => !advertised.has(name));
+  // 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
+  // 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.",
+    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. " + 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.`
+      ? "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.",
@@ -60,12 +132,24 @@ export function buildNonOpenAIToolCatalogNudgeFromNames(wireNames: readonly stri
 }
 
 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(tool => toolChoiceAllows(tool, toolChoice))
-    .map(toWireName);
-  return buildNonOpenAIToolCatalogNudgeFromNames(visibleNames);
+  const visible = tools?.filter(toolChoiceToolPredicate(toolChoice, tools));
+  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,
+  );
 }