@yansigit/opencodex 2.31.2 → 2.32.0

package/src/adapters/google-http.ts

@@ -5,7 +5,7 @@ import {
   retryableGoogleStatus,
   safeGoogleHttpErrorMessage,
 } from "./google-errors";
-import { repairGoogleInvalidRequestBody } from "./google-wire-compiler";
+import { isGoogleMixedBuiltinToolError, repairGoogleInvalidRequestBody, stripGoogleBuiltinToolsFromWireBody } from "./google-wire-compiler";
 import { normalizeUpstreamHttpErrorResponse, readDisplaySafeErrorPayloadText } from "./upstream-http-error";
 import { recordAntigravityCooldown } from "../oauth/antigravity-routing";
 import {
@@ -378,7 +378,17 @@ async function fetchGoogleWithRetryInternal(
         } catch (error) {
           if (ctx.abortSignal?.aborted) throw error;
         }
-        const repairedBody = repairGoogleInvalidRequestBody(activeRequest.body, payloadText);
+        // Mixed built-in + function tools must win over schema repair: those 400s often mention
+        // function_declarations, which would otherwise empty parameters and leave google_search attached.
+        let repairedBody: string | undefined;
+        if (isGoogleMixedBuiltinToolError(payloadText)) {
+          repairedBody = stripGoogleBuiltinToolsFromWireBody(activeRequest.body);
+          if (repairedBody === undefined) {
+            repairedBody = repairGoogleInvalidRequestBody(activeRequest.body, payloadText);
+          }
+        } else {
+          repairedBody = repairGoogleInvalidRequestBody(activeRequest.body, payloadText);
+        }
         if (repairedBody !== undefined) {
           compatibilityReplayUsed = true;
           activeRequest = { ...activeRequest, body: repairedBody };

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

@@ -94,10 +94,35 @@ function compileContents(value: unknown, toWireName: (name: string) => string):
   });
 }
 
+const GOOGLE_BUILTIN_TOOL_KEYS = new Set([
+  "googleSearch", "google_search",
+  "urlContext", "url_context",
+  "codeExecution", "code_execution",
+]);
+
+function isGoogleBuiltinToolObject(rawTool: unknown): boolean {
+  if (!isObject(rawTool)) return false;
+  const keys = Object.keys(rawTool);
+  return keys.length > 0 && keys.every(key => GOOGLE_BUILTIN_TOOL_KEYS.has(key));
+}
+
+function passthroughGoogleBuiltinTools(rawTool: unknown): unknown[] {
+  if (!isObject(rawTool) || Array.isArray(rawTool.functionDeclarations)) return [];
+  if (!isGoogleBuiltinToolObject(rawTool)) return [];
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(rawTool)) {
+    if (key === "googleSearch" || key === "google_search") out.google_search = {};
+    else if (key === "urlContext" || key === "url_context") out.url_context = {};
+    else if (key === "codeExecution" || key === "code_execution") out.code_execution = rawTool[key] ?? {};
+  }
+  return Object.keys(out).length > 0 ? [out] : [];
+}
+
 function compileTools(value: unknown, toWireName: (name: string) => string): unknown[] | undefined {
   if (!Array.isArray(value)) return undefined;
   const tools = value.flatMap(rawTool => {
-    if (!isObject(rawTool) || !Array.isArray(rawTool.functionDeclarations)) return [];
+    const builtins = passthroughGoogleBuiltinTools(rawTool);
+    if (!isObject(rawTool) || !Array.isArray(rawTool.functionDeclarations)) return builtins;
     const functionDeclarations = rawTool.functionDeclarations.flatMap(rawDeclaration => {
       if (!isObject(rawDeclaration) || typeof rawDeclaration.name !== "string") return [];
       return [{
@@ -106,7 +131,10 @@ function compileTools(value: unknown, toWireName: (name: string) => string): unk
         parameters: sanitizeGeminiToolParameters(rawDeclaration.parameters),
       }];
     });
-    return functionDeclarations.length > 0 ? [{ functionDeclarations }] : [];
+    return [
+      ...builtins,
+      ...(functionDeclarations.length > 0 ? [{ functionDeclarations }] : []),
+    ];
   });
   return tools.length > 0 ? tools : undefined;
 }
@@ -238,3 +266,56 @@ export function repairGoogleInvalidRequestBody(body: string, errorPayload: strin
   }
   return changed ? JSON.stringify(parsed) : undefined;
 }
+
+function stripBuiltinToolsFromRoot(root: JsonObject): boolean {
+  if (!Array.isArray(root.tools)) return false;
+  const before = root.tools.length;
+  const filtered = root.tools.filter(rawTool => !isGoogleBuiltinToolObject(rawTool));
+  root.tools = filtered;
+  return filtered.length !== before;
+}
+
+/** One mixed-tool 400 replay: drop known built-in siblings and keep functionDeclarations. */
+export function stripGoogleBuiltinToolsFromWireBody(body: string): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body) as unknown;
+  } catch {
+    return undefined;
+  }
+  if (!isObject(parsed)) return undefined;
+  const root = isObject(parsed.request) ? parsed.request : parsed;
+  if (!stripBuiltinToolsFromRoot(root)) return undefined;
+  return JSON.stringify(parsed);
+}
+
+export function isGoogleMixedBuiltinToolError(errorPayload: string): boolean {
+  const mentionsBuiltin = /\b(?:google[_ ]?search|url[_ ]?context|code[_ ]?execution|built[- ]?in(?:\s+tools?)?)\b/i.test(errorPayload);
+  if (!mentionsBuiltin) return false;
+
+  // A mixed-tool error names a builtin AND a function/tool term AND a coexistence verb.
+  // Builtin mention is gated above; each pattern below requires a coexistence verb to
+  // appear within a bounded window of a tool/function/declaration term (or the phrase
+  // itself implies coexistence, e.g. "mutually exclusive"). Bare "coexist"/"alongside"
+  // without a nearby tool/function term is NOT enough — a schema error can say fields
+  // "coexist" while merely mentioning a builtin.
+  const describesIncompatibleCoexistence = [
+    /\bmix\w*\b[^\n.!?]{0,80}\b(?:tool\w*|function(?:[_ ]declarations?)?|declaration\w*)\b/i,
+    /\b(?:tool\w*|function(?:[_ ]declarations?)?|declaration\w*)\b[^\n.!?]{0,80}\bmix\w*\b/i,
+    /\bcombin\w*\b[^\n.!?]{0,80}\bwith\b/i,
+    /\bcoexist\w*\b[^\n.!?]{0,80}\b(?:tool\w*|function(?:[_ ]declarations?)?|declaration\w*)\b/i,
+    /\b(?:tool\w*|function(?:[_ ]declarations?)?|declaration\w*)\b[^\n.!?]{0,80}\bcoexist\w*\b/i,
+    /\balongside\b[^\n.!?]{0,80}\b(?:tool\w*|function(?:[_ ]declarations?)?|declaration\w*)\b/i,
+    /\b(?:tool\w*|function(?:[_ ]declarations?)?|declaration\w*)\b[^\n.!?]{0,80}\balongside\b/i,
+    /\buse\w*\b[^\n.!?]{0,80}\btogether\b/i,
+    /\btogether\b[^\n.!?]{0,80}\b(?:tool\w*|function(?:[_ ]declarations?)?|declaration\w*)\b/i,
+    /\buse\w*\b[^\n.!?]{0,80}\bwith\b[^\n.!?]{0,80}\b(?:tool\w*|function(?:[_ ]declarations?)?|declaration\w*)\b/i,
+    /\b(?:tool\w*|function(?:[_ ]declarations?)?|declaration\w*)\b[^\n.!?]{0,80}\bwith\b[^\n.!?]{0,80}\buse\w*\b/i,
+    /\bnot supported with\b[^\n.!?]{0,80}\b(?:tool\w*|function(?:[_ ]declarations?)?|declaration\w*)\b/i,
+    /\bmutually exclusive\b/i,
+    /\bincompatib\w*\b[^\n.!?]{0,80}\b(?:coexist\w*|combin\w*|alongside|used together|mutually exclusive)\b/i,
+    /\b(?:coexist\w*|combin\w*|alongside|used together|mutually exclusive)\b[^\n.!?]{0,80}\bincompatib\w*\b/i,
+  ].some(pattern => pattern.test(errorPayload));
+
+  return describesIncompatibleCoexistence;
+}

package/src/adapters/google.ts

@@ -14,7 +14,7 @@ import type {
   OcxToolResultMessage,
   OcxUsage,
 } from "../types";
-import { isAllowedToolChoice, namespacedToolName, resolveToolChoiceWireName, toolAllowedByChoice } from "../types";
+import { isAllowedToolChoice, namespacedToolName, resolveToolChoiceWireName, toolChoiceToolPredicate } from "../types";
 import { contentPartsToText, parseDataUrl } from "./image";
 import { getVertexAccessToken } from "../lib/gcp-adc";
 import { fetchAntigravityWithRetry, fetchVertexWithRetry } from "./google-http";
@@ -28,6 +28,12 @@ import { sanitizeGeminiToolParameters } from "./google-tool-schema";
 import { identifyRoutedModel } from "./identity";
 import { antigravityUsesReplayCache, applyAntigravityReplay, clearAntigravityReplay, observeAntigravityReplay } from "./google-antigravity-replay";
 import { resolveAntigravityEffortWireModel } from "../providers/antigravity-models";
+import {
+  extractCcaGroundingSources,
+  formatCcaGroundingSourcesAppendix,
+  isCcaSearchSuggestionHtml,
+} from "../web-search/gemini-executor";
+import type { WebSearchSource } from "../web-search/parse";
 import { googleVertexLocationConfigError } from "../providers/google-vertex-location";
 import { lookupReplayThoughtSignature } from "../responses/thought-signature-replay";
 import {
@@ -335,22 +341,26 @@ function messagesToGeminiFormat(
   return { systemInstruction, contents };
 }
 
-function toolsToGeminiFormat(parsed: OcxParsedRequest): unknown[] | undefined {
-  if (!parsed.context.tools?.length) return undefined;
-  const allowed = isAllowedToolChoice(parsed.options.toolChoice)
-    ? new Set(parsed.options.toolChoice.allowedTools)
-    : undefined;
-  const tools = allowed
-    ? parsed.context.tools.filter(t => toolAllowedByChoice(t, allowed, parsed.context.tools))
-    : parsed.context.tools;
-  if (tools.length === 0) return undefined;
-  return [{
-    functionDeclarations: tools.map(t => ({
-      name: namespacedToolName(t.namespace, t.name),
-      description: t.description,
-      parameters: t.parameters,
-    })),
-  }];
+function toolsToGeminiFormat(
+  parsed: OcxParsedRequest,
+  wireModelId: string,
+): unknown[] | undefined {
+  const grounding = parsed._ccaInTurnGrounding;
+  const tools = isAllowedToolChoice(parsed.options.toolChoice)
+    ? parsed.context.tools?.filter(toolChoiceToolPredicate(parsed.options.toolChoice, parsed.context.tools)) ?? []
+    : parsed.context.tools ?? [];
+  const functionDeclarations = tools.map(t => ({
+    name: namespacedToolName(t.namespace, t.name),
+    description: t.description,
+    parameters: t.parameters,
+  }));
+  const wireTools: unknown[] = [];
+  if (functionDeclarations.length > 0) wireTools.push({ functionDeclarations });
+  if (grounding && !/claude/i.test(wireModelId)) {
+    if (grounding.search) wireTools.push({ google_search: {} });
+    if (grounding.urlContext) wireTools.push({ url_context: {} });
+  }
+  return wireTools.length > 0 ? wireTools : undefined;
 }
 
 /**
@@ -509,11 +519,12 @@ function googleToolCallMetadataFromPart(
  * Keep that provider visibility bit authoritative here so the streaming and buffered parsers
  * cannot accidentally expose the same hidden reasoning through different event types.
  */
-function googlePartTextEvent(part: GoogleResponsePart): AdapterEvent | undefined {
+function googlePartTextEvent(part: GoogleResponsePart, filterCcaSearchSuggestionHtml = false): AdapterEvent | undefined {
   // A malformed scalar/object is not text and must not cross the AdapterEvent boundary. Dropping
   // only this optional field preserves the rest of the part without inventing assistant output by
   // coercion; an empty string keeps its existing no-event behavior.
   if (typeof part.text !== "string" || part.text.length === 0) return undefined;
+  if (filterCcaSearchSuggestionHtml && isCcaSearchSuggestionHtml(part.text)) return undefined;
   return part.thought === true
     ? { type: "reasoning_raw_delta", text: part.text }
     : { type: "text_delta", text: part.text };
@@ -669,6 +680,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
   let vertexReplayModel: string | undefined;
   let vertexReplaySession: string | undefined;
   let restoreGoogleToolName = (name: string): string => name;
+  const emitInTurnGroundingSourcesQueue: boolean[] = [];
   return {
     name: "google",
 
@@ -702,7 +714,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         identityModelId,
         provider.googleMode === "cloud-code-assist",
       );
-      const tools = toolsToGeminiFormat(parsed);
+      const tools = toolsToGeminiFormat(parsed, routedModelId);
 
       const body: Record<string, unknown> = { contents };
       if (systemInstruction) body.systemInstruction = systemInstruction;
@@ -836,6 +848,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         if (/claude/i.test(wireModelId)) {
           headers["anthropic-beta"] = "interleaved-thinking-2025-05-14";
         }
+        emitInTurnGroundingSourcesQueue.push(!!parsed._ccaInTurnGrounding);
         return { url, method: "POST", headers, body: JSON.stringify(envelope) };
       }
 
@@ -861,6 +874,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         if (apiKey) {
           const url = `https://aiplatform.googleapis.com/v1/publishers/google/models/${parsed.modelId}:${method}${streamParam}`;
           headers["x-goog-api-key"] = apiKey;
+          emitInTurnGroundingSourcesQueue.push(!!parsed._ccaInTurnGrounding);
           return { url, method: "POST", headers, body: JSON.stringify(compiled.body) };
         }
         const project = provider.project || process.env.GOOGLE_CLOUD_PROJECT || process.env.GCLOUD_PROJECT;
@@ -873,6 +887,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         const url = `https://${host}/v1/projects/${project}/locations/${location}/publishers/google/models/${parsed.modelId}:${method}${streamParam}`;
         const token = await getVertexAccessToken();
         headers["Authorization"] = `Bearer ${token}`;
+        emitInTurnGroundingSourcesQueue.push(!!parsed._ccaInTurnGrounding);
         return { url, method: "POST", headers, body: JSON.stringify(compiled.body) };
       }
 
@@ -884,10 +899,14 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
 
       const compiled = compileGoogleWireBody(body);
       restoreGoogleToolName = compiled.restoreToolName;
+      emitInTurnGroundingSourcesQueue.push(!!parsed._ccaInTurnGrounding);
       return { url, method: "POST", headers, body: JSON.stringify(compiled.body) };
     },
 
     async *parseStream(response: Response, budget: TranslatorBudget): AsyncGenerator<AdapterEvent> {
+      const emitInTurnGroundingSources = emitInTurnGroundingSourcesQueue.shift() ?? false;
+      const filterCcaSearchSuggestionHtml =
+        provider.googleMode === "cloud-code-assist" && emitInTurnGroundingSources;
       if (!response.body) {
         yield { type: "error", message: "No response body" };
         return;
@@ -912,6 +931,14 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
       let sawAnyFrame = false;
       let sawTerminalSignal = false;
       let pendingStreamThoughtSig: string | undefined;
+      const groundingSources: WebSearchSource[] = [];
+      let groundingSourcesEmitted = false;
+
+      const mergeGroundingSources = (groundingMetadata: unknown): void => {
+        for (const source of extractCcaGroundingSources(groundingMetadata)) {
+          if (!groundingSources.some(existing => existing.url === source.url)) groundingSources.push(source);
+        }
+      };
 
       const handleDataLine = async function* (line: string): AsyncGenerator<AdapterEvent, "continue" | "content" | "terminate"> {
         const payload = line.slice(5).trim();
@@ -1006,8 +1033,13 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         const candidate = rawCandidate as {
           content?: unknown;
           finishReason?: string;
+          groundingMetadata?: unknown;
         };
 
+        if (emitInTurnGroundingSources && candidate.groundingMetadata) {
+          mergeGroundingSources(candidate.groundingMetadata);
+        }
+
         if (typeof candidate.finishReason === "string" && candidate.finishReason) {
           lastFinishReason = candidate.finishReason;
           sawTerminalSignal = true;
@@ -1042,7 +1074,9 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
         const replaySession = provider.googleMode === "cloud-code-assist" ? antigravitySession : vertexReplaySession;
         if ((provider.googleMode === "cloud-code-assist" || provider.googleMode === "vertex")
           && parts && replayModel && replaySession) {
-          pendingStreamThoughtSig = observeAntigravityReplay(
+          // Observation may scan the whole frame, so use it only for replay-cache side effects.
+          // The source-order loop below exclusively owns stream carry and cannot pair backwards.
+          observeAntigravityReplay(
             replayModel,
             replaySession,
             parts as unknown[],
@@ -1055,7 +1089,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
             if (part.thought === true && sig && isLikelyRealThoughtSignature(sig)) {
               pendingStreamThoughtSig = sig;
             }
-            const textEvent = googlePartTextEvent(part);
+            const textEvent = googlePartTextEvent(part, filterCcaSearchSuggestionHtml);
             if (textEvent) {
               emittedContentEvent = true;
               yield textEvent;
@@ -1166,6 +1200,13 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
           yield { type: "error", message: "upstream stream ended without a terminal signal — possible truncation" };
           return;
         }
+        if (emitInTurnGroundingSources && !groundingSourcesEmitted && groundingSources.length > 0) {
+          const appendix = formatCcaGroundingSourcesAppendix(groundingSources);
+          if (appendix) {
+            groundingSourcesEmitted = true;
+            yield { type: "text_delta", text: appendix };
+          }
+        }
         const stopReason = lastFinishReason === "MAX_TOKENS"
           ? "max_tokens"
           : ["SAFETY", "RECITATION", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII"].includes(lastFinishReason ?? "")

package/src/adapters/kiro.ts

@@ -318,9 +318,6 @@ function validateKiroCapabilities(parsed: OcxParsedRequest): void {
   if (choice !== undefined && choice !== "auto" && choice !== "none") {
     throw new Error("Kiro supports only automatic tool choice or tool_choice:none");
   }
-  if (parsed.options.parallelToolCalls === true) {
-    throw new Error("Kiro does not support parallel tool calls");
-  }
   if (parsed.options.serviceTier !== undefined) {
     throw new Error("Kiro does not support service tiers");
   }

package/src/adapters/openai-responses.ts

@@ -1684,6 +1684,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
 
       const forward = provider.authMode === "forward";
       let convertedRoutedCustomToolNames: Set<string> | undefined;
+      let routedCustomToolRepairNames: Set<string> | undefined;
       let convertedRoutedToolSearchNames: Set<string> | undefined;
       let convertedRoutedNamespaceToolAliases: Map<string, { namespace: string; name: string }> | undefined;
       const unexpandedMiss = !!parsed.previousResponseId && parsed._previousResponseInputExpanded !== true;
@@ -1741,6 +1742,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         );
         outBody = rewritten.body;
         convertedRoutedCustomToolNames = rewritten.names;
+        routedCustomToolRepairNames = rewritten.repairNames;
       }
       if (!isCanonicalOpenAiForwardProvider(provider)) {
         // Run after custom-tool lowering so the search compatibility layer can choose a
@@ -1811,6 +1813,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         body,
         releaseBodyObservation,
         ...(convertedRoutedCustomToolNames ? { convertedRoutedCustomToolNames } : {}),
+        ...(routedCustomToolRepairNames ? { routedCustomToolRepairNames } : {}),
         ...(convertedRoutedToolSearchNames ? { convertedRoutedToolSearchNames } : {}),
         ...(convertedRoutedNamespaceToolAliases ? { convertedRoutedNamespaceToolAliases } : {}),
         ...(tierLog ? { tierLog } : {}),

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

@@ -120,7 +120,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."
+      ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.<name>(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.<name>`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names. Nested `tools.apply_patch(input)` is host-executed: the string must begin exactly with `*** Begin Patch` and end with `*** End Patch` (no trailing `***` on those lines). OpenCodex does not rewrite JavaScript inside exec, so a decorated `*** Begin Patch ***` envelope is rejected by Codex before the file is touched."
       : "If a listed tool exposes nested helpers such as a tools.* API, call the listed parent tool and use those helpers only inside that tool's input.",
     unavailableNeighborNames.length > 0
       ? "Do not use neighboring-agent tool names " + quoteNames(unavailableNeighborNames) + " unless this turn's catalog lists those exact names."

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

@@ -60,10 +60,15 @@ function normalizeToolGroup(tools: unknown[]): ToolGroupRewrite {
       : undefined;
     const enableImageSearch = searchContentTypes?.includes("image") === true;
     const next: Record<string, unknown> = { ...tool, type: CODEX_WEB_SEARCH_TOOL };
+    // Only the two fields xAI actually refuses are removed. Probed 2026-08-22, one field per
+    // request, against BOTH xAI destinations (api.x.ai and cli-chat-proxy.grok.com): they behave
+    // identically — `external_web_access` 400s on every value including `true`, and
+    // `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).
     delete next.external_web_access;
     delete next.search_context_size;
-    delete next.search_content_types;
-    delete next.user_location;
     if (enableImageSearch && !Object.hasOwn(next, "enable_image_search")) {
       next.enable_image_search = true;
     }

package/src/bridge.ts

@@ -8,6 +8,7 @@ import type {
 } from "./types";
 import { coerceIntegerToolArguments } from "./lib/tool-argument-integers";
 import { adapterFailureFromMessage, classifyError, CYBER_POLICY_ERROR_CODE, isCyberPolicyCode, type OcxErrorPayload } from "./lib/errors";
+import { repairFreeformToolInput } from "./responses/apply-patch-envelope";
 import { encodeCompactionSummary } from "./responses/compaction";
 import { isTruncatedStopReason, truncationReasonFor } from "./responses/truncated-stop-reason";
 import { encodeReasoningEnvelope, type ReasoningEnvelope } from "./responses/reasoning-envelope";
@@ -230,12 +231,12 @@ export function bridgeToResponsesSSE(
   const replayCacheScope = options?.replayCacheScope;
   const setBeatInterval = options?.timers?.setInterval ?? ((handler: () => void, ms: number) => setInterval(handler, ms));
   const clearBeatInterval = options?.timers?.clearInterval ?? ((id: unknown) => clearInterval(id as ReturnType<typeof setInterval>));
-  // Freeform/custom tools (apply_patch) carry their body in `input`; the model is given a
-  // function with `{input:string}`, so unwrap it here when relaying back as a custom_tool_call.
-  const freeformInput = (args: string): string => {
-    try { const o = JSON.parse(args); if (o && typeof o.input === "string") return o.input; } catch { /* raw */ }
-    return args;
-  };
+  // Freeform/custom tools (apply_patch, code-mode exec) carry their body in `input`; the
+  // model is given a function with `{input:string}`, so unwrap it here when relaying back
+  // as a custom_tool_call. Decorated apply_patch envelopes are repaired at this boundary.
+  const freeformInput = (args: string, toolName: string, namespace?: string): string => (
+    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":"...`
@@ -626,6 +627,7 @@ export function bridgeToResponsesSSE(
         const argsStr = coerceIntegerToolArguments(
           currentToolCall.args || "{}",
           options?.toolParameterSchemas?.get(currentToolCall.name),
+          currentToolCall.namespace === undefined ? currentToolCall.name : undefined,
         );
         // Finalize streamed function-call arguments so Codex commits the call (incl. MCP / computer_use).
         if (!currentToolCall.freeform && !currentToolCall.toolSearch) {
@@ -636,7 +638,8 @@ export function bridgeToResponsesSSE(
         if (currentToolCall.freeform) {
           emit("response.custom_tool_call_input.done", {
             item_id: currentToolCall.itemId, output_index: currentToolCall.outputIndex,
-            input: freeformInput(currentToolCall.args),
+            ...(currentToolCall.namespace ? { namespace: currentToolCall.namespace } : {}),
+            input: freeformInput(currentToolCall.args, currentToolCall.name, currentToolCall.namespace),
           });
         }
         // Freeform tools serialize as custom_tool_call without extra_content; remember the
@@ -652,7 +655,8 @@ export function bridgeToResponsesSSE(
           ? {
               type: "custom_tool_call", id: currentToolCall.itemId,
               call_id: currentToolCall.callId, name: currentToolCall.name,
-              input: freeformInput(currentToolCall.args), status: "completed",
+              ...(currentToolCall.namespace ? { namespace: currentToolCall.namespace } : {}),
+              input: freeformInput(currentToolCall.args, currentToolCall.name, currentToolCall.namespace), status: "completed",
             }
           : {
               type: "function_call", id: currentToolCall.itemId,
@@ -691,7 +695,8 @@ export function bridgeToResponsesSSE(
           ? {
               type: "custom_tool_call", id: currentToolCall.itemId,
               call_id: currentToolCall.callId, name: currentToolCall.name,
-              input: freeformInput(currentToolCall.args), status: "incomplete",
+              ...(currentToolCall.namespace ? { namespace: currentToolCall.namespace } : {}),
+              input: freeformInput(currentToolCall.args, currentToolCall.name, currentToolCall.namespace), status: "incomplete",
             }
           : {
               type: "function_call", id: currentToolCall.itemId,
@@ -1064,7 +1069,7 @@ export function bridgeToResponsesSSE(
               const item = toolSearch
                 ? { type: "tool_search_call", id: itemId, call_id: event.id, execution: "client", arguments: {}, status: "in_progress" }
                 : freeform
-                ? { type: "custom_tool_call", id: itemId, call_id: event.id, name: realName, input: "", status: "in_progress" }
+                ? { type: "custom_tool_call", id: itemId, call_id: event.id, name: realName, ...(ns ? { namespace: ns } : {}), input: "", status: "in_progress" }
                 : { type: "function_call", id: itemId, call_id: event.id, name: realName, arguments: "", status: "in_progress", ...(ns ? { namespace: ns } : {}) };
               emit("response.output_item.added", { output_index: outputIndex, item });
               currentToolCall = { itemId, outputIndex, callId: event.id, name: realName, args: "", argsBytes: 0, namespace: ns, freeform, toolSearch, providerMetadata: event.providerMetadata };
@@ -1567,10 +1572,9 @@ function buildResponseJSONWithBudget(
   // Web-search citations awaiting the next assistant message (attached as url_citation annotations).
   let pendingWebSources: { url: string; title?: string }[] = [];
 
-  const freeformInput = (args: string): string => {
-    try { const o = JSON.parse(args); if (o && typeof o.input === "string") return o.input; } catch { /* raw */ }
-    return args;
-  };
+  const freeformInput = (args: string, toolName: string, namespace?: string): string => (
+    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 {}; }
   };
@@ -1656,6 +1660,7 @@ function buildResponseJSONWithBudget(
     const coercedArgs = coerceIntegerToolArguments(
       currentToolCallArgs,
       options?.toolParameterSchemas?.get(currentToolCallName),
+      ns === undefined ? realName : undefined,
     );
     // Freeform tools serialize as custom_tool_call without extra_content; remember the
     // signature server-side regardless so the replayed call can be re-signed (#1735).
@@ -1670,7 +1675,8 @@ function buildResponseJSONWithBudget(
       pushOutput({
         type: "custom_tool_call", id: `ctc_${uuid()}`,
         call_id: currentToolCallId, name: realName,
-        input: freeformInput(currentToolCallArgs), status,
+        ...(ns ? { namespace: ns } : {}),
+        input: freeformInput(currentToolCallArgs, realName, ns), status,
       });
     } else {
       pushOutput({

package/src/cli/dispatch.ts

@@ -203,7 +203,11 @@ const commandRunners: Record<string, CommandRunner> = {
     return 0;
   },
   sync: async deps => {
-    const restartCodex = deps.args.slice(1).includes("--restart-codex");
+    const syncArgs = deps.args.slice(1);
+    const restartCodex = syncArgs.includes("--restart-codex");
+    // Separate flag on purpose: --restart-codex promises app-server-only scope,
+    // and quitting the desktop app ends live conversations.
+    const restartDesktopApp = syncArgs.includes("--restart-desktop-app");
     const live = await deps.findLiveProxy();
     const synced = await syncModelsToCodex(
       live?.port,
@@ -229,6 +233,7 @@ const commandRunners: Record<string, CommandRunner> = {
     // exactly when a long-lived app-server is holding the stale list.
     if (synced.catalogWritten || synced.cacheSynced) {
       afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
+      if (restartDesktopApp) await handleDesktopAppRestart(console);
     }
     // `ocx sync` is a direct CLI path; it does not call the management
     // `/api/sync` route. Refresh the already-connected MCode block here too,
@@ -259,7 +264,9 @@ const commandRunners: Record<string, CommandRunner> = {
     return await cmdV2(deps.args.slice(1), {}, async () => (await deps.findLiveProxy())?.port);
   },
   "sync-cache": async deps => {
-    const restartCodex = deps.args.slice(1).includes("--restart-codex");
+    const cacheArgs = deps.args.slice(1);
+    const restartCodex = cacheArgs.includes("--restart-codex");
+    const restartDesktopApp = cacheArgs.includes("--restart-desktop-app");
     const { withCatalogWriteSerialization } = await import("../codex/catalog-write-serialization");
     const { invalidateCodexModelsCacheWithPermit } = await import("../codex/catalog/sync");
     const { getCodexHome } = await import("../codex/paths");
@@ -270,6 +277,7 @@ const commandRunners: Record<string, CommandRunner> = {
     // Only warn/restart when models_cache was actually rewritten from a readable catalog.
     if (invalidated.kind === "completed" && invalidated.value) {
       afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
+      if (restartDesktopApp) await handleDesktopAppRestart(console);
     } else if (desiredDisabled) {
       console.log("Codex integration is OFF; cache sync skipped (no catalog or cache write).");
     }
@@ -583,3 +591,43 @@ export async function dispatchCommand(head: CliHead, deps: CliDispatchDeps): Pro
   }
   return await runner(deps);
 }
+
+/**
+ * Report the outcome of an opt-in desktop-app restart. Kept next to the two
+ * callers so `sync` and `sync-cache` cannot drift in what they tell the user.
+ */
+async function handleDesktopAppRestart(log: Pick<Console, "log" | "error">): Promise<void> {
+  const { restartCodexDesktopApp } = await import("../codex/desktop-app-restart");
+  const result = restartCodexDesktopApp();
+  switch (result.reason) {
+    case "windows_only":
+      log.error("--restart-desktop-app is supported on Windows only; nothing was stopped.");
+      return;
+    case "package_discovery_failed":
+      log.error(
+        "Could not identify the installed Codex desktop package. Quit and relaunch the desktop app "
+        + "manually to refresh the model picker.",
+      );
+      return;
+    case "self_ancestry":
+      log.error(
+        "Refusing to restart the desktop app because this command is running inside it. "
+        + "Run 'ocx sync --restart-desktop-app' from an external terminal instead.",
+      );
+      return;
+    case "no_targets":
+      log.log("Codex desktop app is not running; nothing to restart.");
+      return;
+    case "targets_survived":
+      log.error(
+        `Codex desktop app PID(s) ${result.surviving.join(", ")} did not exit, so it was not relaunched. `
+        + "Quit the desktop app manually to refresh the model picker.",
+      );
+      return;
+    default:
+      if (result.relaunch === "started") {
+        log.log("Codex desktop app restarted; its model picker will re-read the catalog.");
+      }
+  }
+}
+