@bitkyc08/opencodex 2.41.0 → 2.43.0-preview.20260906

package/src/adapters/responses-code-mode.ts

@@ -0,0 +1,59 @@
+import { toolChoiceToolPredicate, type OcxParsedRequest, type OcxProviderConfig } from "../types";
+import { isOpenAiOperatedResponsesDestination } from "../providers/openai-tiers";
+import { CODE_MODE_RESULT_ECHO_SENTENCE, normalizeEmptyExecToolResultText } from "./exec-tool-result-normalize";
+import { isBareShellBridgeTool, isCodexCodeModeExecTool } from "./tool-catalog-nudge";
+
+function record(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Inspect the whole result, not just its empty header: later text or media is real output. */
+function textOnlyOutput(output: unknown): string | undefined {
+  if (typeof output === "string") return output;
+  if (!Array.isArray(output)) return undefined;
+  if (!output.every(part => record(part)
+    && ["text", "input_text", "output_text"].includes(String(part.type))
+    && typeof part.text === "string")) return undefined;
+  return output.map(part => part.text).join("\n");
+}
+
+function withExecInputGuidance(tool: unknown): unknown {
+  if (!record(tool) || tool.type !== "function" || tool.name !== "exec" || tool.namespace !== undefined) return tool;
+  if (!record(tool.parameters) || !record(tool.parameters.properties) || !record(tool.parameters.properties.input)) return tool;
+  return { ...tool, parameters: { ...tool.parameters, properties: {
+    ...tool.parameters.properties,
+    input: {
+      ...tool.parameters.properties.input,
+      description: `JavaScript source for unified exec; do not provide a bare shell command. ${CODE_MODE_RESULT_ECHO_SENTENCE}`,
+    },
+  } } };
+}
+
+/** Native routed Responses needs the same first-call/output contract as translated adapters. */
+export function normalizeResponsesCodeMode(body: unknown, parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown {
+  if (!record(body) || parsed._compactionRequest || isOpenAiOperatedResponsesDestination(provider)) return body;
+  const visible = parsed.context.tools?.filter(toolChoiceToolPredicate(parsed.options.toolChoice, parsed.context.tools));
+  if (!visible?.some(isCodexCodeModeExecTool) || visible.some(isBareShellBridgeTool)) return body;
+  const instructions = typeof body.instructions === "string" ? body.instructions : "";
+  const input = Array.isArray(body.input) ? body.input : undefined;
+  const execCalls = new Set(input?.filter(item => record(item)
+    && (item.type === "function_call" || item.type === "custom_tool_call")
+    && item.name === "exec" && item.namespace === undefined && typeof item.call_id === "string")
+    .map(item => item.call_id));
+  return {
+    ...body,
+    instructions: instructions.includes(CODE_MODE_RESULT_ECHO_SENTENCE)
+      ? instructions : [instructions, CODE_MODE_RESULT_ECHO_SENTENCE].filter(Boolean).join("\n\n"),
+    ...(Array.isArray(body.tools) ? { tools: body.tools.map(withExecInputGuidance) } : {}),
+    ...(input ? { input: input.map(item => {
+      if (!record(item)) return item;
+      if (item.type === "additional_tools" && Array.isArray(item.tools)) {
+        return { ...item, tools: item.tools.map(withExecInputGuidance) };
+      }
+      if ((item.type !== "function_call_output" && item.type !== "custom_tool_call_output") || !execCalls.has(item.call_id)) return item;
+      const text = textOnlyOutput(item.output);
+      const normalized = text === undefined ? undefined : normalizeEmptyExecToolResultText(text, { toolName: "exec" });
+      return normalized === undefined ? item : { ...item, output: normalized };
+    }) } : {}),
+  };
+}

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

@@ -121,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. " + 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."
+      ? "`" + 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`, each marker line being three asterisks, one space, the two words, then end of line with no further asterisks. OpenCodex does not rewrite JavaScript inside exec, so extra asterisks on a marker line are 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-schema-analysis.ts

@@ -0,0 +1,86 @@
+export function isSchemaObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function decodeJsonPointerToken(token: string): string {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/** Resolve a local `#/`-rooted JSON Pointer against `root`; undefined when it does not resolve. */
+export function lookupLocalJsonPointer(root: unknown, ref: string): unknown {
+  if (ref === "#" || ref === "#/") return root;
+  if (!ref.startsWith("#/")) return undefined;
+  let current: unknown = root;
+  for (const token of ref.slice(2).split("/").map(decodeJsonPointerToken)) {
+    if (!isSchemaObject(current) || !Object.hasOwn(current, token)) return undefined;
+    current = current[token];
+  }
+  return current;
+}
+
+/** Values a schema pins through `const`/`enum`, or undefined when it pins none. */
+function xaiLiteralValues(schema: unknown): unknown[] | undefined {
+  if (!isSchemaObject(schema)) return undefined;
+  if (Object.hasOwn(schema, "const")) return [schema.const];
+  if (Array.isArray(schema.enum)) return schema.enum;
+  return undefined;
+}
+
+/** JSON type name for a literal, so it can be compared against a `type` keyword. */
+function xaiJsonTypeOf(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "string") return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  return "object";
+}
+
+/** Types a schema declares, or undefined when it constrains none. */
+function xaiDeclaredTypes(schema: unknown): Set<string> | undefined {
+  if (!isSchemaObject(schema)) return undefined;
+  const type = schema.type;
+  if (typeof type === "string") return new Set([type]);
+  if (Array.isArray(type) && type.every(item => typeof item === "string")) return new Set(type as string[]);
+  return undefined;
+}
+
+/** `integer` is a subset of `number`, so those two names overlap rather than exclude. */
+function xaiTypesOverlap(left: string, right: string): boolean {
+  if (left === right) return true;
+  return (left === "integer" && right === "number") || (left === "number" && right === "integer");
+}
+
+/**
+ * Conservative mutual-exclusion test: true only when no instance can satisfy both schemas.
+ * Proof comes from disjoint literal sets or disjoint declared types; anything it cannot prove
+ * is reported as overlapping so the caller refuses the merge instead of widening the schema.
+ */
+function xaiSchemasAreProvablyDisjoint(left: unknown, right: unknown): boolean {
+  const leftValues = xaiLiteralValues(left);
+  const rightValues = xaiLiteralValues(right);
+  if (leftValues && rightValues) {
+    const seen = new Set(rightValues.map(value => JSON.stringify(value)));
+    return leftValues.every(value => !seen.has(JSON.stringify(value)));
+  }
+  const leftTypes = xaiDeclaredTypes(left);
+  const rightTypes = xaiDeclaredTypes(right);
+  const literalsExcludedByTypes = (values: unknown[], types: Set<string>): boolean =>
+    values.every(value => ![...types].some(type => xaiTypesOverlap(xaiJsonTypeOf(value), type)));
+  if (leftValues && rightTypes) return literalsExcludedByTypes(leftValues, rightTypes);
+  if (rightValues && leftTypes) return literalsExcludedByTypes(rightValues, leftTypes);
+  if (leftTypes && rightTypes) {
+    return ![...leftTypes].some(leftType => [...rightTypes].some(rightType => xaiTypesOverlap(leftType, rightType)));
+  }
+  return false;
+}
+
+/** Every pair provably disjoint, so a union over them accepts each instance exactly once. */
+export function xaiSchemasArePairwiseDisjoint(schemas: unknown[]): boolean {
+  for (let i = 0; i < schemas.length; i += 1) {
+    for (let j = i + 1; j < schemas.length; j += 1) {
+      if (!xaiSchemasAreProvablyDisjoint(schemas[i], schemas[j])) return false;
+    }
+  }
+  return true;
+}

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

@@ -1,8 +1,6 @@
 import type { OcxProviderConfig } from "../types";
-
-function isSchemaObject(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
+export { lookupLocalJsonPointer } from "./xai-schema-analysis";
+import { isSchemaObject, lookupLocalJsonPointer, xaiSchemasArePairwiseDisjoint } from "./xai-schema-analysis";
 
 export function isXaiSchemaTarget(provider: Pick<OcxProviderConfig, "baseUrl">): boolean {
   try {
@@ -58,22 +56,6 @@ function createXaiSchemaBudget(): XaiSchemaBudget {
   return { remainingNodes: XAI_MAX_SCHEMA_NODES, remainingVariants: XAI_MAX_ROOT_VARIANTS };
 }
 
-function decodeJsonPointerToken(token: string): string {
-  return token.replace(/~1/g, "/").replace(/~0/g, "~");
-}
-
-/** Resolve a local `#/`-rooted JSON Pointer against `root`; undefined when it does not resolve. */
-export function lookupLocalJsonPointer(root: unknown, ref: string): unknown {
-  if (ref === "#" || ref === "#/") return root;
-  if (!ref.startsWith("#/")) return undefined;
-  let current: unknown = root;
-  for (const token of ref.slice(2).split("/").map(decodeJsonPointerToken)) {
-    if (!isSchemaObject(current) || !Object.hasOwn(current, token)) return undefined;
-    current = current[token];
-  }
-  return current;
-}
-
 /** Resolve local `#/` `$ref`s. Unresolvable, cyclic, or over-budget refs return undefined. */
 function resolveXaiSchemaRefs(
   schema: unknown,
@@ -168,73 +150,6 @@ function xaiRequiredSetsMatch(variants: Record<string, unknown>[]): boolean {
   return serialized.every(value => value === serialized[0]);
 }
 
-/** Values a schema pins through `const`/`enum`, or undefined when it pins none. */
-function xaiLiteralValues(schema: unknown): unknown[] | undefined {
-  if (!isSchemaObject(schema)) return undefined;
-  if (Object.hasOwn(schema, "const")) return [schema.const];
-  if (Array.isArray(schema.enum)) return schema.enum;
-  return undefined;
-}
-
-/** JSON type name for a literal, so it can be compared against a `type` keyword. */
-function xaiJsonTypeOf(value: unknown): string {
-  if (value === null) return "null";
-  if (Array.isArray(value)) return "array";
-  if (typeof value === "string") return "string";
-  if (typeof value === "boolean") return "boolean";
-  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
-  return "object";
-}
-
-/** Types a schema declares, or undefined when it constrains none. */
-function xaiDeclaredTypes(schema: unknown): Set<string> | undefined {
-  if (!isSchemaObject(schema)) return undefined;
-  const type = schema.type;
-  if (typeof type === "string") return new Set([type]);
-  if (Array.isArray(type) && type.every(item => typeof item === "string")) return new Set(type as string[]);
-  return undefined;
-}
-
-/** `integer` is a subset of `number`, so those two names overlap rather than exclude. */
-function xaiTypesOverlap(left: string, right: string): boolean {
-  if (left === right) return true;
-  return (left === "integer" && right === "number") || (left === "number" && right === "integer");
-}
-
-/**
- * Conservative mutual-exclusion test: true only when no instance can satisfy both schemas.
- * Proof comes from disjoint literal sets or disjoint declared types; anything it cannot prove
- * is reported as overlapping so the caller refuses the merge instead of widening the schema.
- */
-function xaiSchemasAreProvablyDisjoint(left: unknown, right: unknown): boolean {
-  const leftValues = xaiLiteralValues(left);
-  const rightValues = xaiLiteralValues(right);
-  if (leftValues && rightValues) {
-    const seen = new Set(rightValues.map(value => JSON.stringify(value)));
-    return leftValues.every(value => !seen.has(JSON.stringify(value)));
-  }
-  const leftTypes = xaiDeclaredTypes(left);
-  const rightTypes = xaiDeclaredTypes(right);
-  const literalsExcludedByTypes = (values: unknown[], types: Set<string>): boolean =>
-    values.every(value => ![...types].some(type => xaiTypesOverlap(xaiJsonTypeOf(value), type)));
-  if (leftValues && rightTypes) return literalsExcludedByTypes(leftValues, rightTypes);
-  if (rightValues && leftTypes) return literalsExcludedByTypes(rightValues, leftTypes);
-  if (leftTypes && rightTypes) {
-    return ![...leftTypes].some(leftType => [...rightTypes].some(rightType => xaiTypesOverlap(leftType, rightType)));
-  }
-  return false;
-}
-
-/** Every pair provably disjoint, so a union over them accepts each instance exactly once. */
-function xaiSchemasArePairwiseDisjoint(schemas: unknown[]): boolean {
-  for (let i = 0; i < schemas.length; i += 1) {
-    for (let j = i + 1; j < schemas.length; j += 1) {
-      if (!xaiSchemasAreProvablyDisjoint(schemas[i], schemas[j])) return false;
-    }
-  }
-  return true;
-}
-
 /** Deduplicate schemas by serialized shape, preserving first-seen order. */
 function uniqueXaiSchemas(values: unknown[]): unknown[] {
   const unique: unknown[] = [];

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

@@ -55,7 +55,7 @@ function normalizeToolGroup(tools: unknown[]): ToolGroupRewrite {
     // `search_context_size` 400s, while `user_location`, `search_content_types`, `filters` and
     // `enable_image_search` are all accepted. Deleting the accepted ones was a silent capability
     // loss, and it contradicted the sibling layer, whose own probe note already records
-    // user_location/filters as accepted (tests/responses-routed-web-search-fields.test.ts).
+    // user_location/filters as accepted (tests/responses/responses-routed-web-search-fields.test.ts).
     delete next.external_web_access;
     delete next.search_context_size;
     if (enableImageSearch && !Object.hasOwn(next, "enable_image_search")) {

package/src/bridge.ts

@@ -16,9 +16,9 @@ import {
   type OcxErrorPayload,
 } from "./lib/errors";
 import { redactSecretString } from "./lib/redact";
-import { repairFreeformToolInput } from "./responses/apply-patch-envelope";
+import { mayBecomePatchEnvelope, repairFreeformToolInput } from "./responses/apply-patch-envelope";
 import { encodeCompactionSummary } from "./responses/compaction";
-import { compileCodeModeHelperInput } from "./responses/code-mode-helper-compat";
+import { compileCodeModeHelperInput, resolveCodeModeHelperName } from "./responses/code-mode-helper-compat";
 import { isTruncatedStopReason, truncationReasonFor } from "./responses/truncated-stop-reason";
 import { encodeReasoningEnvelope, type ReasoningEnvelope } from "./responses/reasoning-envelope";
 import { rememberReasoningForCall } from "./responses/reasoning-replay-cache";
@@ -33,7 +33,7 @@ import {
   stripCitationMarkers,
   type CitationMarkerFilter,
 } from "./responses/citation-markers";
-import { normalizeDeclaredToolName } from "./types";
+import { declaresCodeModeExec, normalizeDeclaredToolName } from "./types";
 import { usageDisplayTotalTokens } from "./usage/totals";
 import { appendSafeWebSearchSource, safeWebSearchSources } from "./web-search/sources";
 import {
@@ -59,6 +59,10 @@ function sseEvent(name: string, data: Record<string, unknown>): string {
   return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
 function responsesUsage(usage: OcxUsage | undefined): Record<string, unknown> {
   // input_tokens_details / output_tokens_details are ALWAYS emitted (zero defaults):
   // strict Responses clients deserialize them as required fields — grok-build's pinned
@@ -80,7 +84,24 @@ function responsesUsage(usage: OcxUsage | undefined): Record<string, unknown> {
   const inputTokens = usage.contextTotalTokens !== undefined
     ? Math.max(0, usage.contextTotalTokens - usage.outputTokens)
     : usage.inputTokens;
+  // openai/codex#41980 parity: unknown upstream usage fields (subscription metadata, future
+  // counters) pass through the rebuild. Normalized values stay authoritative for the known
+  // keys (they are derived from the same raw values, so this never disagrees with upstream).
+  const raw: Record<string, unknown> = usage.rawUsage ?? {};
+  // cache_write_tokens is a KNOWN key: it is emitted only from the validated normalized
+  // value below, never copied through raw (an unknown-shaped value must not leak into the
+  // normalized contract).
+  const rawInputDetails = isRecord(raw.input_tokens_details)
+    ? Object.fromEntries(Object.entries(raw.input_tokens_details as Record<string, unknown>)
+      .filter(([key]) => key !== "cache_write_tokens"))
+    : {} as Record<string, unknown>;
+  const rawOutputDetails = isRecord(raw.output_tokens_details)
+    ? raw.output_tokens_details as Record<string, unknown>
+    : {} as Record<string, unknown>;
   const out: Record<string, unknown> = {
+    ...Object.fromEntries(Object.entries(raw).filter(([key]) =>
+      key !== "input_tokens" && key !== "output_tokens" && key !== "total_tokens"
+      && key !== "input_tokens_details" && key !== "output_tokens_details")),
     input_tokens: inputTokens,
     output_tokens: usage.outputTokens,
     total_tokens: usage.contextTotalTokens !== undefined
@@ -90,18 +111,19 @@ function responsesUsage(usage: OcxUsage | undefined): Record<string, unknown> {
   // cached_tokens carries cache READS only, matching OpenAI semantics, and is always present
   // (zero default) for strict clients. Clamp to inputTokens so a provider's absolute
   // checkpoint can never report more cache reads than input.
-  const inputDetails: Record<string, number> = {
+  const inputDetails: Record<string, unknown> = {
+    ...rawInputDetails,
     cached_tokens: Math.min(usage.cachedInputTokens ?? 0, inputTokens),
   };
   if (usage.cacheCreationInputTokens !== undefined) {
-    const cacheRead = inputDetails.cached_tokens ?? 0;
+    const cacheRead = typeof inputDetails.cached_tokens === "number" ? inputDetails.cached_tokens : 0;
     inputDetails.cache_write_tokens = Math.min(
       usage.cacheCreationInputTokens,
       Math.max(0, inputTokens - cacheRead),
     );
   }
   out.input_tokens_details = inputDetails;
-  out.output_tokens_details = { reasoning_tokens: usage.reasoningOutputTokens ?? 0 };
+  out.output_tokens_details = { ...rawOutputDetails, reasoning_tokens: usage.reasoningOutputTokens ?? 0 };
   return out;
 }
 
@@ -255,9 +277,12 @@ export function bridgeToResponsesSSE(
     toolName: string,
     namespace?: string,
     codeModeHelperName?: string,
-  ): string => codeModeHelperName
-    ? compileCodeModeHelperInput(args, codeModeHelperName)
-    : repairFreeformToolInput(args, toolName, namespace);
+  ): string => {
+    const helper = resolveCodeModeHelperName(codeModeHelperName, toolName, args, namespace, options?.declaredToolNames);
+    return helper
+      ? compileCodeModeHelperInput(args, helper)
+      : repairFreeformToolInput(args, toolName, namespace);
+  };
   // Best-effort unwrap of a PARTIAL freeform arg buffer for live input streaming
   // (`response.custom_tool_call_input.delta` — codex-rs uses it for UI preview only;
   // the completed custom_tool_call item stays authoritative). Compact `{"input":"...`
@@ -1150,7 +1175,13 @@ export function bridgeToResponsesSSE(
                   if (!FREEFORM_WRAP_PREFIX.startsWith(currentToolCall.args)) {
                     const full = freeformPartialInput(currentToolCall.args);
                     const emitted = currentToolCall.inputEmitted ?? "";
-                    if (full.startsWith(emitted) && full.length > emitted.length) {
+                    // Also hold a buffer that could still become a complete patch envelope:
+                    // at completion such a body is recompiled into an apply_patch helper call,
+                    // and streaming the envelope bytes first would be that same rewind.
+                    const mayCompile = declaresCodeModeExec(options?.declaredToolNames)
+                      && !currentToolCall.namespace
+                      && currentToolCall.name === "exec";
+                    if (!(mayCompile && mayBecomePatchEnvelope(full)) && full.startsWith(emitted) && full.length > emitted.length) {
                       emit("response.custom_tool_call_input.delta", {
                         item_id: currentToolCall.itemId, output_index: currentToolCall.outputIndex,
                         delta: full.slice(emitted.length),
@@ -1644,9 +1675,12 @@ function buildResponseJSONWithBudget(
     toolName: string,
     namespace?: string,
     codeModeHelperName?: string,
-  ): string => codeModeHelperName
-    ? compileCodeModeHelperInput(args, codeModeHelperName)
-    : repairFreeformToolInput(args, toolName, namespace);
+  ): string => {
+    const helper = resolveCodeModeHelperName(codeModeHelperName, toolName, args, namespace, options?.declaredToolNames);
+    return helper
+      ? compileCodeModeHelperInput(args, helper)
+      : repairFreeformToolInput(args, toolName, namespace);
+  };
   const parseArgsObj = (args: string): Record<string, unknown> => {
     try { const o = JSON.parse(args); return o && typeof o === "object" ? o : {}; } catch { return {}; }
   };

package/src/chat/inbound.ts

@@ -73,13 +73,18 @@ function userContentToBlocks(content: unknown): Rec[] {
       continue;
     }
     if (!isRec(raw)) continue;
-    if ((raw.type === "text" || raw.type === "input_text") && typeof raw.text === "string") {
+    if ((raw.type === "text" || raw.type === "input_text" || raw.type === "output_text") && typeof raw.text === "string") {
       blocks.push({ type: "input_text", text: raw.text });
       continue;
     }
     const imageUrl = imageUrlFromPart(raw);
     if (imageUrl) {
-      blocks.push({ type: "input_image", image_url: imageUrl });
+      const detail = isRec(raw.image_url) ? raw.image_url.detail : raw.detail;
+      blocks.push({
+        type: "input_image",
+        image_url: imageUrl,
+        ...(detail === "auto" || detail === "low" || detail === "high" ? { detail } : {}),
+      });
       continue;
     }
     const videoUrl = videoUrlFromPart(raw);
@@ -275,7 +280,10 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
           : typeof msg.tool_use_id === "string" ? msg.tool_use_id
           : "";
         if (!callId) throw new ChatCompletionsRequestError("tool messages require tool_call_id");
-        const output = typeof msg.content === "string" ? msg.content : contentToText(msg.content);
+        const blocks = userContentToBlocks(msg.content);
+        const output = blocks.some(part => part.type === "input_image")
+          ? blocks.filter(part => part.type === "input_text" || part.type === "input_image")
+          : contentToText(msg.content);
         input.push({ type: "function_call_output", call_id: callId, output });
         break;
       }

package/src/claude/inbound-content-options.ts

@@ -0,0 +1,60 @@
+import { isClaudeWebSearchToolName } from "./outbound";
+import { AnthropicRequestError, isRec, type Rec } from "./inbound-records";
+
+export function systemToInstructions(system: unknown): string | undefined {
+  if (typeof system === "string") return system.length > 0 ? system : undefined;
+  if (Array.isArray(system)) {
+    const parts: string[] = [];
+    for (const block of system) {
+      if (isRec(block) && block.type === "text" && typeof block.text === "string") parts.push(block.text);
+    }
+    return parts.length > 0 ? parts.join("\n\n") : undefined;
+  }
+  return undefined;
+}
+
+export function toolsToResponses(tools: unknown): Rec[] | undefined {
+  if (!Array.isArray(tools) || tools.length === 0) return undefined;
+  const out: Rec[] = [];
+  for (const raw of tools) {
+    if (!isRec(raw)) continue;
+    const type = typeof raw.type === "string" ? raw.type : "";
+    if (type.startsWith("web_search")) {
+      out.push({ type: "web_search" }); // hosted sidecar path
+      continue;
+    }
+    if (typeof raw.name === "string" && raw.name.length > 0 && isRec(raw.input_schema)) {
+      out.push({
+        type: "function",
+        name: raw.name,
+        ...(typeof raw.description === "string" ? { description: raw.description } : {}),
+        parameters: raw.input_schema as Record<string, unknown>,
+      });
+      continue;
+    }
+    // Other server tools (bash_*, text_editor_*, ...) have no routed equivalent: drop.
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+export function toolChoiceToResponses(choice: unknown, body: Rec): void {
+  if (!isRec(choice)) return;
+  if (choice.disable_parallel_tool_use === true) body.parallel_tool_calls = false;
+  switch (choice.type) {
+    case "auto": body.tool_choice = "auto"; break;
+    case "none": body.tool_choice = "none"; break;
+    case "any": body.tool_choice = "required"; break;
+    case "tool":
+      if (typeof choice.name !== "string" || choice.name.length === 0) {
+        throw new AnthropicRequestError("tool_choice.tool requires a name");
+      }
+      // Anthropic represents hosted WebSearch as a named tool choice, while
+      // Responses requires the choice type to match the hosted declaration.
+      // Preserve forced-tool intent rather than weakening it to `auto`.
+      body.tool_choice = isClaudeWebSearchToolName(choice.name)
+        ? { type: "web_search" }
+        : { type: "function", name: choice.name };
+      break;
+    default: break;
+  }
+}

package/src/claude/inbound-model-options.ts

@@ -0,0 +1,142 @@
+import type { OcxClaudeCodeConfig } from "../types";
+import { isAnthropicOutputSchema } from "../adapters/anthropic-output-schema";
+import { resolveAlias } from "./alias";
+import { stripOneMillionMarker } from "./context-windows";
+import { resolveDesktop3pAlias } from "./desktop-3p";
+import { isRec, type Rec } from "./inbound-records";
+
+function isClaudeClassifierModel(model: string): boolean {
+  const stripped = model.replace(/-\d{8}$/, "");
+  return /^claude-opus-[45]/.test(stripped);
+}
+
+/**
+ * Explicitly configured classifier route for Claude Code Auto Mode safety checks (#1697).
+ *
+ * Only OPERATOR-DECLARED targets are used: `classifierModel`, then the ordered
+ * `classifierFallbacks`. Both are qualified `provider/model` strings the operator chose, so
+ * routing them crosses no boundary the operator did not ask for.
+ *
+ * Deliberately NOT here: inferring a provider from `claudeCode.model`. That value is the
+ * injected/default config slot, not the provider the live session actually selected, so it goes
+ * stale the moment the user changes the model picker -- and acting on it would silently move a
+ * classifier turn onto a provider with its own privacy and billing consequences. Live session
+ * affinity needs the request/session state this function does not have; it is tracked as
+ * follow-up work rather than approximated from static config.
+ */
+function configuredClassifierRoute(cc?: OcxClaudeCodeConfig): string | undefined {
+  const explicit = typeof cc?.classifierModel === "string" ? cc.classifierModel.trim() : "";
+  if (explicit.length > 0) return explicit;
+  if (Array.isArray(cc?.classifierFallbacks)) {
+    for (const candidate of cc.classifierFallbacks) {
+      if (typeof candidate === "string" && candidate.trim().length > 0) return candidate.trim();
+    }
+  }
+  return undefined;
+}
+
+/** Alias first, then modelMap: exact id, then date-suffix-stripped (`-\d{8}$`), then classifier affinity/config, else passthrough. */
+export function resolveInboundModel(model: string, cc?: OcxClaudeCodeConfig): string {
+  // Defensive: Desktop/CLI strip the [1m] context-variant marker client-side, but a
+  // leaking build must not break alias decode (devlog 138 — the 1M signal is the
+  // anthropic-beta header, never the id). Case-insensitive: the CLI matches /\[1m\]/i.
+  model = stripOneMillionMarker(model);
+  const aliased = resolveAlias(model);
+  if (aliased) return aliased;
+  // Desktop 3P aliases: claude-opus-4-{code} → provider/model route key
+  const desktop3p = resolveDesktop3pAlias(model);
+  if (desktop3p) {
+    // Native pseudo-provider returns bare slug; routed returns provider/model
+    const sep = desktop3p.indexOf("/");
+    if (sep > 0 && desktop3p.slice(0, sep) === "native") return desktop3p.slice(sep + 1);
+    return desktop3p;
+  }
+  const map = cc?.modelMap ?? {};
+  const exact = map[model];
+  if (typeof exact === "string" && exact.length > 0) return exact;
+  const stripped = model.replace(/-\d{8}$/, "");
+  const dateless = map[stripped];
+  if (typeof dateless === "string" && dateless.length > 0) return dateless;
+
+  // Claude Code Auto Mode classifier routing (#1697). Bare classifier checks such as
+  // `claude-opus-5` carry no provider, so without this they fall through to defaultProvider --
+  // which may not speak Anthropic at all. Only an operator-declared target is used.
+  if (isClaudeClassifierModel(model)) {
+    const configured = configuredClassifierRoute(cc);
+    if (configured) return configured;
+  }
+  return model;
+}
+
+/** budget_tokens ladder -> Responses reasoning effort (003: real API min is 1024; never forward raw). */
+export function effortForThinkingBudget(budget: number): string {
+  if (budget <= 4096) return "low";
+  if (budget <= 16384) return "medium";
+  return "high";
+}
+
+/**
+ * Adaptive-thinking wire (devlog 080): Claude Code /effort sends
+ * `thinking:{type:"adaptive"}` + `output_config:{effort:"..."}` (verified by local
+ * capture of claude 2.1.207 and CLIProxyAPI#1540). Forward the level verbatim when it
+ * is a known Responses effort; unknown strings are dropped so downstream defaults win.
+ */
+const OUTPUT_CONFIG_EFFORTS = new Set(["minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
+export function effortFromOutputConfig(outputConfig: unknown): string | undefined {
+  if (!isRec(outputConfig)) return undefined;
+  const effort = outputConfig.effort;
+  return typeof effort === "string" && OUTPUT_CONFIG_EFFORTS.has(effort) ? effort : undefined;
+}
+
+export function formatFromOutputConfig(outputConfig: unknown): Rec | undefined {
+  if (!isRec(outputConfig) || !isRec(outputConfig.format)) return undefined;
+  const format = outputConfig.format;
+  if (
+    format.type !== "json_schema"
+    || !isRec(format.schema)
+    || !isAnthropicOutputSchema(format.schema)
+  ) return undefined;
+  return { type: "json_schema", name: "response", schema: format.schema };
+}
+
+/**
+ * ocx-route directive (devlog 072): injected agent-definition bodies carry
+ * `<!-- ocx-route: <model> -->` because Claude Code 2.1.207 ignores custom
+ * gateway ids in agent frontmatter (live-proven fallback to sonnet). The body
+ * rides the subagent's system prompt, so the proxy re-routes here. Only the
+ * FIRST directive wins; the scan is bounded to the system field.
+ */
+const OCX_ROUTE_RE = /<!--\s*ocx-route:\s*([^\s]+)\s*-->/;
+const OCX_EFFORT_RE = /<!--\s*ocx-effort:\s*(low|medium|high|xhigh|max)\s*-->/;
+
+function systemText(body: unknown): string | null {
+  if (!isRec(body)) return null;
+  const system = body.system;
+  if (typeof system === "string") return system || null;
+  if (!Array.isArray(system)) return null;
+  const text = system
+    .filter((b): b is Rec => isRec(b) && b.type === "text" && typeof b.text === "string")
+    .map(b => b.text as string)
+    .join("\n");
+  return text || null;
+}
+
+export function extractOcxRouteDirective(body: unknown): string | null {
+  const text = systemText(body);
+  if (!text) return null;
+  const match = OCX_ROUTE_RE.exec(text);
+  return match ? match[1]! : null;
+}
+
+/**
+ * Claude Code 2.1.220 collapses custom-agent frontmatter `effort: max` and
+ * `effort: xhigh` into the legacy `thinking.budget_tokens` shape. Preserve the
+ * exact generated-agent setting through the same trusted system-body channel as
+ * ocx-route so the inbound translator can restore `output_config.effort`.
+ */
+export function extractOcxEffortDirective(body: unknown): NonNullable<OcxClaudeCodeConfig["subagentEffort"]> | null {
+  const text = systemText(body);
+  if (!text) return null;
+  const match = OCX_EFFORT_RE.exec(text);
+  return match ? match[1] as NonNullable<OcxClaudeCodeConfig["subagentEffort"]> : null;
+}

package/src/claude/inbound-records.ts

@@ -0,0 +1,7 @@
+export class AnthropicRequestError extends Error {}
+
+export type Rec = Record<string, unknown>;
+
+export function isRec(v: unknown): v is Rec {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}