@yansigit/opencodex 2.33.0 → 2.35.0

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

@@ -1,9 +1,10 @@
 import { create, fromBinary, toBinary, toJson } from "@bufbuild/protobuf";
 import { fromJson, type JsonValue } from "@bufbuild/protobuf";
 import { ValueSchema } from "@bufbuild/protobuf/wkt";
-import type { OcxAssistantContentPart, OcxMessage, OcxRequestOptions, OcxToolResultMessage } from "../../types";
+import type { OcxAssistantContentPart, OcxMessage, OcxToolResultMessage } from "../../types";
 import { namespacedToolName } from "../../types";
 import type { CursorRunRequest } from "./types";
+import { decodeCursorCallId } from "./call-id";
 import { cursorNeedsExternalToolContinuation, isCursorExternalWireModel } from "./discovery";
 import { normalizeCursorToolResultText } from "./tool-result-normalize";
 import { debugProviderDiagnostic } from "../../lib/debug";
@@ -77,7 +78,22 @@ export const CURSOR_EXTERNAL_ROOT_BYTE_LIMIT = 512 * 1024;
  * results already stored in history blobs are visible without a ResumeAction.
  */
 export const CURSOR_EXTERNAL_TOOL_CONTINUATION_TEXT =
-  "Continue: the requested tool results are provided in the conversation history above.";
+  "Continue: the requested tool results are provided in the conversation history above. Answer the user request or proceed with the next step directly without repeating status summaries or greetings.";
+
+export function externalToolContinuationText(rawMessages?: readonly OcxMessage[]): string {
+  const last = rawMessages?.at(-1);
+  if (last?.role === "toolResult") {
+    const raw = typeof last.content === "string" ? last.content : JSON.stringify(last.content ?? "");
+    const trimmed = raw.trim();
+    if (
+      (last.toolName?.includes("list_agents") || last.toolName?.includes("search"))
+      && (trimmed === "[]" || trimmed === "" || trimmed === "{}" || trimmed === "null")
+    ) {
+      return `${CURSOR_EXTERNAL_TOOL_CONTINUATION_TEXT} If a prior discovery or list tool returned empty results (e.g. no sub-agents currently active), proceed directly with your next concrete action using available tools.`;
+    }
+  }
+  return CURSOR_EXTERNAL_TOOL_CONTINUATION_TEXT;
+}
 
 /** Runtime timezone for protobuf RequestContextEnv (dynamic, never hardcoded). */
 function runtimeTimeZone(): string {
@@ -165,26 +181,9 @@ function truncateToolResultBlob(entry: RootBlobCandidate, maxBytes: number): Roo
   return markerOnly.byteLength <= maxBytes ? markerOnly : null;
 }
 
-function structuredOutputPrompt(textFormat: OcxRequestOptions["textFormat"]): string | undefined {
-  if (!textFormat) return undefined;
-  if (textFormat.type === "json_schema" && textFormat.schema) {
-    return [
-      "Your response must be a single valid JSON object strictly conforming to this JSON schema:",
-      JSON.stringify(textFormat.schema),
-      "Do not include any surrounding markdown fences, preamble, or commentary; return raw JSON only.",
-    ].join("\n");
-  }
-  if (textFormat.type === "json_object") {
-    return "Your response must be a single valid JSON object. Do not include any markdown fences or commentary; return raw JSON only.";
-  }
-  return undefined;
-}
-
 function systemPromptBlobs(request: CursorRunRequest): RootBlobCandidate[] {
   const prompts = request.system.length > 0 ? [...request.system] : ["You are a helpful assistant."];
   if (cursorRequestHasShellAlias(request.tools)) prompts.push(CURSOR_SHELL_ALIAS_SYSTEM_NOTE);
-  const structuredPrompt = structuredOutputPrompt(request.textFormat);
-  if (structuredPrompt) prompts.push(structuredPrompt);
   const cursorToolGuidance = buildCursorToolGuidanceSystemNote(
     cursorToolsForActivePrompt(request.tools, activePromptText(request), request.toolChoice),
     request.toolChoice,
@@ -207,11 +206,10 @@ function assistantRootText(
 // Cursor builds the actual model prompt from rootPromptMessagesJson (turns[] is UI/display metadata),
 // so prior history must be replayed here or a ResumeAction has nothing model-visible to continue from.
 // The active user message is excluded because it travels in the action. When the continuation cannot
-// rely on native MCP turn state, tool results stay assistant-role text so Cursor does not wrap them
-// as `<user_query>` (#1992). External replay uses a neutral "Tool output" label; protocol markers
-// such as [Tool Result] are reserved for native wire encoding because external models echo them.
-// Native resume models already carry the paired MCP result on turns[], so it is omitted from root
-// replay. Each entry is a SHA-256 blob ID.
+// rely on native MCP turn state, tool results stay assistant-role text with a [Tool Result] /
+// [Tool Error] marker so Cursor does not wrap them as `<user_query>` (#1992). Native resume models
+// already carry the paired MCP result on turns[], so that marker is omitted from root replay — Auto
+// few-shot-mimics it as chat text otherwise. Each entry is a SHA-256 blob ID.
 function rootPromptMessages(request: CursorRunRequest, requestScope: CursorBlobRequestScopeToken): {
   ids: Uint8Array[];
   byteLength: number;
@@ -235,6 +233,42 @@ function rootPromptMessages(request: CursorRunRequest, requestScope: CursorBlobR
   const echoToolResultInRoot = cursorNeedsExternalToolContinuation(request.modelId);
   const lastRawIsToolResult = messages.at(-1)?.role === "toolResult";
   const activeUserIndex = lastRawIsToolResult ? -1 : lastActionIndex(messages);
+  // Repetition breaker (devlog 260826 gap-9): external full-replay flattens history to text,
+  // so N identical assistant/tool-result rounds replay as N identical lines and PRIME the model
+  // to emit the same line again (self-reinforcing loop: S2a 180x, identical-probe repetition).
+  // Collapse consecutive duplicates into one entry + a count marker, and count collapses so a
+  // strategy-change note can be appended when the pattern is severe.
+  let lastReplayText: string | undefined;
+  let lastReplayEntry: RootBlobCandidate | undefined;
+  let collapsedRepeats = 0;
+  let maxRunLength = 1;
+  let currentRun = 1;
+  const pushDeduped = (
+    payload: { role: string; content: [{ type: "text"; text: string }] },
+    role: RootBlobCandidate["role"],
+    opts: { messageIndex: number; text?: string },
+    normalized: string,
+  ): void => {
+    if (externalModel && lastReplayText !== undefined && normalized === lastReplayText && lastReplayEntry) {
+      collapsedRepeats++;
+      currentRun++;
+      if (currentRun > maxRunLength) maxRunLength = currentRun;
+      const marked = `${normalized}\n[note: this exact output was produced ${currentRun} times in a row]`;
+      const replacement = rootBlobCandidate(
+        { role: payload.role, content: [{ type: "text", text: marked }] },
+        role,
+        opts,
+      );
+      entries[entries.indexOf(lastReplayEntry)] = replacement;
+      lastReplayEntry = replacement;
+      return;
+    }
+    currentRun = 1;
+    const entry = rootBlobCandidate(payload, role, opts);
+    entries.push(entry);
+    lastReplayText = normalized;
+    lastReplayEntry = entry;
+  };
 
   for (let i = 0; i < messages.length; i++) {
     if (i === activeUserIndex) break;
@@ -246,6 +280,9 @@ function rootPromptMessages(request: CursorRunRequest, requestScope: CursorBlobR
       // A bare string survives blob hydration but external workers reject the completed replay
       // before tokenization (`usedTokens: 0`, then invalid_argument).
       if (text.length > 0) {
+        lastReplayText = undefined;
+        lastReplayEntry = undefined;
+        currentRun = 1;
         entries.push(rootBlobCandidate({
           role: "user",
           content: [{ type: "text", text }],
@@ -256,25 +293,30 @@ function rootPromptMessages(request: CursorRunRequest, requestScope: CursorBlobR
       // Native Composer state can preserve it through ThinkingMessage/history structures.
       const text = assistantRootText(message, !externalModel).trim();
       if (text.length > 0) {
-        entries.push(rootBlobCandidate(
+        pushDeduped(
           { role: "assistant", content: [{ type: "text", text }] },
           "assistant",
           { messageIndex: i },
-        ));
+          text,
+        );
       }
       // Assistant tool CALLS are intentionally NOT replayed as visible "[Tool Call]" text here.
     } else if (message.role === "toolResult") {
-      // Native resume models already receive the paired MCP result through turns[]. External
-      // replay uses neutral text here so models do not echo protocol envelopes as chat.
+      // Native resume models already receive the paired MCP result through turns[]. Replaying
+      // the same payload as assistant-role "[Tool Result]" / "[tool_result]" text teaches Auto
+      // to echo that envelope as chat instead of continuing from the structured result.
       if (!echoToolResultInRoot) continue;
       const text = externalToolResultToText(message);
-      entries.push(rootBlobCandidate(
-        toolResultRootPayload(text),
-        "toolResult",
-        { messageIndex: i, text },
-      ));
+      pushDeduped(toolResultRootPayload(text), "toolResult", { messageIndex: i, text }, text);
     }
   }
+  // Severe repetition: tell the model ONCE, imperatively, to change strategy.
+  if (externalModel && maxRunLength >= 3) {
+    entries.push(rootBlobCandidate({
+      role: "user",
+      content: [{ type: "text", text: `[context note] The transcript above contains the same output repeated ${maxRunLength} times in a row. Repeating it again is a failure. Take a DIFFERENT action now, or state plainly what is blocking progress.` }],
+    }, "user", {}));
+  }
 
   let selected = entries;
   let historyMessageStart = 0;
@@ -450,6 +492,7 @@ function decodeResultParts(message: OcxToolResultMessage): DecodedResultPart[] |
   if (typeof content === "string") return undefined;
   return content.map((part): DecodedResultPart => {
     if (part.type === "text") return { kind: "text", text: part.text };
+    if (part.type === "video") return { kind: "text", text: "[video]" };
     const decoded = decodeInlineImage(part.imageUrl);
     return decoded ? { kind: "image", ...decoded } : { kind: "undecodable" };
   });
@@ -544,7 +587,7 @@ function toolResultToText(message: OcxToolResultMessage): string {
   const normalized = normalizedToolResult(message, contentToText(message.content));
   return [
     "[tool_result]",
-    `call_id: ${message.toolCallId}`,
+    `call_id: ${decodeCursorCallId(message.toolCallId)}`,
     `name: ${namespacedToolName(message.toolNamespace, message.toolName)}`,
     `is_error: ${normalized.isError}`,
     "output:",
@@ -555,7 +598,7 @@ function toolResultToText(message: OcxToolResultMessage): string {
 function externalToolResultToText(message: OcxToolResultMessage): string {
   const normalized = normalizedToolResult(message, contentToText(message.content));
   const label = normalized.isError ? "Tool error" : "Tool output";
-  return `${label} for ${namespacedToolName(message.toolNamespace, message.toolName)} (call_id: ${message.toolCallId}, is_error: ${normalized.isError}):\n${normalized.text}`;
+  return `${label} for ${namespacedToolName(message.toolNamespace, message.toolName)} (call_id: ${decodeCursorCallId(message.toolCallId)}, is_error: ${normalized.isError}):\n${normalized.text}`;
 }
 
 /**
@@ -611,7 +654,7 @@ function toolCallStep(
             args: create(McpArgsSchema, {
               name: toolName,
               toolName,
-              toolCallId: part.id,
+              toolCallId: decodeCursorCallId(part.id),
               providerIdentifier: OCX_RESPONSES_TOOL_PROVIDER,
               args,
             }),
@@ -855,8 +898,10 @@ function buildPreparedCursorRunRequest(
     ? "userMessageAction"
     : "resumeAction";
   const actionText = externalToolContinuation
-    ? CURSOR_EXTERNAL_TOOL_CONTINUATION_TEXT
-    : text;
+    ? (request.echoRetryContinuationText ?? CURSOR_EXTERNAL_TOOL_CONTINUATION_TEXT)
+    : request.echoRetryContinuationText
+      ? `${text}\n\n[correction] ${request.echoRetryContinuationText}`
+      : text;
   const action = create(ConversationActionSchema, {
     action: actionCase === "userMessageAction"
       ? {
@@ -983,12 +1028,15 @@ function buildPreparedCursorRunRequest(
         displayName: request.modelId,
         displayNameShort: request.modelId,
         aliases: [],
+        ...(request.maxMode === true ? { maxMode: true } : {}),
       }),
     } : {}),
-    ...(requestedModelParameters.length > 0 ? {
+    ...(requestedModelParameters.length > 0 || request.maxMode === true ? {
       requestedModel: create(RequestedModelSchema, {
         modelId: request.modelId,
-        maxMode: false,
+        // Max Mode must be raised on BOTH RequestedModel and ModelDetails; missing either
+        // can invalid_argument upstream (devlog 260826 070).
+        maxMode: request.maxMode === true,
         parameters: requestedModelParameters.map(parameter =>
           create(RequestedModel_ModelParameterbytesSchema, parameter)),
       }),
@@ -1006,7 +1054,11 @@ function buildPreparedCursorRunRequest(
     // the event-state `clientToolNames` use (live-transport.ts). Advertising the raw `request.tools`
     // here would let mcp_tools expose a tool that the event state does not recognize for a generic
     // tool-count prompt, so a call to it would be rejected as an unknown Responses tool.
-    ...(mcpToolDefs.length > 0 ? { mcpTools: create(McpToolsSchema, { mcpTools: mcpToolDefs }) } : {}),
+    // An explicitly empty McpTools wrapper (bare API callers) suppresses Cursor's default
+    // native catalog; an absent field lets identified Codex sessions keep it (devlog 260826 040).
+    ...(mcpToolDefs.length > 0 || request.suppressDefaultCursorToolCatalog === true
+      ? { mcpTools: create(McpToolsSchema, { mcpTools: mcpToolDefs }) }
+      : {}),
   });
 
   const message = create(AgentClientMessageSchema, {

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

@@ -10,6 +10,8 @@ import type {
 import { isAllowedToolChoice, namespacedToolName, toolChoiceAliases, type OcxTool, type OcxToolChoice } from "../../types";
 import type { CursorRequestMessage, CursorRequestedModelParameter, CursorRunRequest } from "./types";
 import { cursorCheckpointModelAffinityId, cursorWireModelSelection, type CursorRoutingLevel } from "./discovery";
+import { cursorUltraBaseModelId } from "./discovery";
+import { decodeCursorCallId } from "./call-id";
 import { cursorEffortSuffix, cursorRequestWireModelIdWithEffort } from "./effort-map";
 import {
   cursorMcpToolEncodedSize,
@@ -188,13 +190,19 @@ function normalizeCursorModelId(modelId: string, reasoning?: string): {
   modelId: string;
   requestedModelParameters?: readonly CursorRequestedModelParameter[];
   routingLevel?: CursorRoutingLevel;
+  maxMode?: boolean;
 } {
-  const selection = cursorWireModelSelection(modelId);
+  // Synthetic ultra (-1m) picker rows resolve to their wire base with Max Mode on
+  // (devlog 260826 070); the marker never reaches the wire.
+  const ultraBase = cursorUltraBaseModelId(modelId);
+  const selection = cursorWireModelSelection(ultraBase ?? modelId);
+  const maxMode = ultraBase !== undefined ? { maxMode: true } : {};
   const id = selection.modelId;
   const suffix = cursorEffortSuffix(id, reasoning);
   if ((id === "grok-4.5-fast" || id === "grok-4.6-fast") && suffix) {
     return {
       ...selection,
+      ...maxMode,
       modelId: id.slice(0, -"-fast".length),
       requestedModelParameters: [
         { id: "effort", value: suffix },
@@ -202,7 +210,14 @@ function normalizeCursorModelId(modelId: string, reasoning?: string): {
       ],
     };
   }
-  return { ...selection, modelId: suffix ? cursorRequestWireModelIdWithEffort(id, suffix) : id };
+  if (id === "composer-2.5") {
+    return {
+      ...selection,
+      modelId: id,
+      requestedModelParameters: [{ id: "fast", value: "false" }],
+    };
+  }
+  return { ...selection, ...maxMode, modelId: suffix ? cursorRequestWireModelIdWithEffort(id, suffix) : id };
 }
 
 function contentPartToText(part: OcxContentPart | OcxAssistantContentPart): string | undefined {
@@ -226,7 +241,7 @@ function contentPartToText(part: OcxContentPart | OcxAssistantContentPart): stri
 function toolResultToText(message: OcxToolResultMessage): string {
   return [
     "[tool_result]",
-    `call_id: ${message.toolCallId}`,
+    `call_id: ${decodeCursorCallId(message.toolCallId)}`,
     `name: ${namespacedToolName(message.toolNamespace, message.toolName)}`,
     `is_error: ${message.isError}`,
     "output:",
@@ -298,7 +313,7 @@ export function cursorConversationIdFromClientThread(threadId: string, identityS
 
 /**
  * Resolve the Cursor conversation id for this turn.
- * Priority: force-fresh → isolate helper → remembered → thread override → client thread → random.
+ * Priority: force-fresh → isolate helper → remembered → client thread owner → random.
  * Never use OpenAI Responses `previous_response_id` (resp_*) or shared `prompt_cache_key`
  * (cache-cohort fingerprint, not conversation ownership).
  */
@@ -310,7 +325,7 @@ export function resolveCursorConversationId(
   if (options.forceFreshConversation === true) return generatedCursorConversationId();
   if (parsed._cursorIsolateConversation === true) return generatedCursorConversationId();
   if (parsed._cursorConversationId) return parsed._cursorConversationId;
-  const threadId = parsed._clientThreadId?.trim();
+  const threadId = cursorClientThreadOwner(parsed);
   if (threadId) {
     const recovered = lookupCursorThreadConversation(threadId, parsed._cursorIdentityScope);
     if (recovered) return recovered;
@@ -319,6 +334,10 @@ export function resolveCursorConversationId(
   return generatedCursorConversationId();
 }
 
+export function cursorClientThreadOwner(parsed: OcxParsedRequest): string | undefined {
+  return parsed._clientThreadId?.trim() || parsed._cursorClientThreadId?.trim() || undefined;
+}
+
 function updateFramed(hash: ReturnType<typeof createHash>, value: string): void {
   const bytes = Buffer.from(value, "utf8");
   const length = Buffer.allocUnsafe(4);
@@ -361,6 +380,7 @@ function lookupPrefixSnapshot(
   const modelId = cursorCheckpointModelAffinityId(request.modelId);
   for (let covered = parsed.context.messages.length; covered >= 1; covered--) {
     const snapshot = getCursorCheckpointForPrefix({
+      conversationId: request.conversationId,
       prefixDigest: cursorCoveredPrefixDigest(parsed, covered),
       systemDigest,
       coveredMessageCount: covered,
@@ -404,10 +424,14 @@ function resolveCursorCheckpoint(
     snapshot = getCursorCheckpoint(ref);
     if (!snapshot) return { reason: "expired" };
   } else {
+    if (
+      isolated
+      || (!parsed._cursorConversationId && !cursorClientThreadOwner(parsed))
+    ) return { reason: "missing_ref" };
     snapshot = lookupPrefixSnapshot(parsed, request, identityScope);
     if (!snapshot) return { reason: "missing_ref" };
   }
-  if (!isolated && snapshot.conversationId !== request.conversationId && ref) {
+  if (snapshot.conversationId !== request.conversationId) {
     return { reason: "conversation_changed" };
   }
   if (snapshot.identityScope !== identityScope) return { reason: "identity_changed" };
@@ -436,16 +460,21 @@ export function createCursorRequest(
     modelId: model.modelId,
     ...(model.requestedModelParameters ? { requestedModelParameters: model.requestedModelParameters } : {}),
     ...(model.routingLevel ? { routingLevel: model.routingLevel } : {}),
+    ...(model.maxMode ? { maxMode: true } : {}),
     conversationId: resolveCursorConversationId(parsed, model.modelId, options),
     system: [...(parsed.context.systemPrompt ?? []), ...(limitNote ? [limitNote] : [])],
     messages,
     rawMessages: parsed.context.messages,
     ...(parsed._compactionRequest === true || parsed._contextCompactionBoundary === true ? { contextUsageReset: true } : {}),
     ...(parsed._compactionRequest === true ? { contextUsageStoreCheckpoints: false } : {}),
-   ...(budget.tools.length ? { tools: budget.tools } : {}),
-   ...(parsed.options.toolChoice ? { toolChoice: parsed.options.toolChoice } : {}),
-    ...(parsed.options.textFormat ? { textFormat: parsed.options.textFormat } : {}),
-   ...(parsed.options.parallelToolCalls !== undefined ? { parallelToolCalls: parsed.options.parallelToolCalls } : {}),
+    ...(budget.tools.length ? { tools: budget.tools } : {}),
+    // Bare API caller (no tools, no Codex thread identity): suppress Cursor's default
+    // native tool catalog instead of paying its ~10-15K token preamble (devlog 260826 040).
+    ...(budget.tools.length === 0 && !cursorClientThreadOwner(parsed)
+      ? { suppressDefaultCursorToolCatalog: true }
+      : {}),
+    ...(parsed.options.toolChoice ? { toolChoice: parsed.options.toolChoice } : {}),
+    ...(parsed.options.parallelToolCalls !== undefined ? { parallelToolCalls: parsed.options.parallelToolCalls } : {}),
   };
   const resolved = resolveCursorCheckpoint(parsed, request, options);
   if ("reason" in resolved) {

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

@@ -71,6 +71,13 @@ export const CURSOR_EXEC_COMMAND_INPUT_SCHEMA = {
   additionalProperties: false,
 } as const;
 
+/** Cursor requires freeform custom tools to advertise their body as one string input. */
+export const CURSOR_FREEFORM_INPUT_SCHEMA = {
+  type: "object",
+  properties: { input: { type: "string" } },
+  required: ["input"],
+} as const;
+
 /**
  * Structured single-replacement schema advertised to Cursor models in addition to the freeform
  * `apply_patch` tool. Cursor-trained models reliably emit exact-match replacements (the native
@@ -386,6 +393,7 @@ export function responsesToolNameFromCursorWire(name: string, cursorToolNameMap?
 
 /** Schema advertised to Cursor for this tool (may use Cursor-preferred field names like `cmd`). */
 export function cursorToolInputSchema(tool: OcxTool): unknown {
+  if (tool.freeform) return CURSOR_FREEFORM_INPUT_SCHEMA;
   return isBareCodexExecCommandTool(tool) ? CURSOR_EXEC_COMMAND_INPUT_SCHEMA : (tool.parameters ?? {});
 }
 
@@ -395,6 +403,7 @@ export function cursorToolInputSchema(tool: OcxTool): unknown {
  * treating `cmd` as canonical prevents the `cmd` → `command` rewrite Codex requires (#399).
  */
 export function cursorToolArgNormalizeSchema(tool: OcxTool): unknown {
+  if (tool.freeform) return CURSOR_FREEFORM_INPUT_SCHEMA;
   if (isBareCodexShellBridgeTool(tool)) {
     return shellBridgeArgNormalizeSchema(tool);
   }
@@ -673,11 +682,20 @@ export function buildCursorToolGuidanceSystemNote(
     // Code mode: shell/edit/MCP live inside freeform `exec` as nested helpers. Without this the
     // model probes for a top-level shell tool that is not there.
     codeMode
-      ? `\`${CODEX_UNIFIED_EXEC_TOOL}\` is Codex code mode: its body is JavaScript evaluated in a V8 isolate, not a shell command and not Node. Shell, file edits, and MCP are nested helpers called INSIDE that body as \`await tools.<name>(...)\`, for example \`await tools.exec_command({cmd: \"ls\"})\`. When commands require network access, file writes outside workspace, or fail due to sandbox/permission restrictions, pass \`sandbox_permissions: "require_escalated"\` and a clear \`justification: "..."\` to \`tools.exec_command\`. Read the tool description and the isolate global \`ALL_TOOLS\` (not \`tools.ALL_TOOLS\`) for helpers this turn provides; absence from the top-level catalog or from \`exec\`'s description is not absence. Those nested helpers are not themselves top-level tools, so do not call \`exec_command\` or \`shell_command\` at the top level here${codeModeOtherTopLevelNames.length > 0 ? `; every other tool this turn lists, including ${quotedNames(codeModeOtherTopLevelNames)}, remains callable at the top level as usual` : ""}. Your tool list may display tools under a longer \`mcp_opencodex-responses_*\` name; call whichever your list shows. 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.`
+      ? `\`${CODEX_UNIFIED_EXEC_TOOL}\` is Codex code mode: its body is JavaScript evaluated in a V8 isolate, not a shell command and not Node. Shell, file edits, and MCP are nested helpers called INSIDE that body as \`await tools.<name>(...)\`, for example \`await tools.exec_command({cmd: \"ls\"})\`. Read the tool description and the isolate global \`ALL_TOOLS\` (not \`tools.ALL_TOOLS\`) for helpers this turn provides; absence from the top-level catalog or from \`exec\`'s description is not absence. Those nested helpers are not themselves top-level tools, so do not call \`exec_command\` or \`shell_command\` at the top level here${codeModeOtherTopLevelNames.length > 0 ? `; every other tool this turn lists, including ${quotedNames(codeModeOtherTopLevelNames)}, remains callable at the top level as usual` : ""}. 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.`
       : undefined,
     codeMode
       ? "In code mode the isolate returns nothing on its own: call `text(...)` (or `notify(...)`) on any value you need to see, or the call completes with empty output. There is no `require`, no `module`, and no filesystem or network globals; reach the host only through the nested helpers."
       : undefined,
+    codeMode
+      ? 'When commands require network access, file writes outside workspace, or fail due to sandbox/permission restrictions, pass `sandbox_permissions: "require_escalated"` and a clear `justification: "..."` to `tools.exec_command`.'
+      : undefined,
+    codeMode
+      ? "Nested helpers may appear under longer `mcp_opencodex-responses_*` display names; use the exact helper names exposed by this turn."
+      : undefined,
+    codeMode
+      ? "NEVER attempt Cursor-native Shell, Read, Grep, List, or any tool absent from the catalog — they are not executed in this environment and every probe wastes a turn. The exec code cell (with its nested helpers) is the ONLY execution surface; go to it directly on the FIRST attempt and do not narrate switching surfaces."
+      : undefined,
     hasBareExec
       ? `${shellBridgeLabel} is the Codex Responses shell bridge for this turn, exposed through Cursor's tool protocol; it is not an external MCP server tool. \`shell_command\` and \`exec_command\` are aliases of the same bridge.`
       : undefined,
@@ -685,7 +703,10 @@ export function buildCursorToolGuidanceSystemNote(
       ? "Your tool list may display it under a longer `mcp_opencodex-responses_shell_command` / `mcp_opencodex-responses_exec_command` name; those are the SAME tool — call whichever your list shows, and do not comment on the naming difference to the user."
       : undefined,
     hasBareExec
-      ? `Prefer the Codex shell bridge over Cursor-native Shell/Read. If a Cursor-native file read, directory listing, grep, or shell operation is rejected, continue with the listed catalog tool ${shellBridgeLabel}.`
+      ? `NEVER attempt Cursor-native Shell, Read, Grep, List, or any tool not in the catalog above — they are not executed locally in this environment and every attempt wastes a turn and can stall the session. ${shellBridgeLabel} is the ONLY shell surface; go to it directly on the FIRST attempt, never as a fallback after probing a native tool. Do not narrate switching surfaces ("native is blocked, using the bridge instead") — there is exactly one surface.`
+      : undefined,
+    hasBareExec
+      ? "Tool-selection commentary is forbidden: for any shell, read, grep, list, or file operation, your FIRST visible action is the bridge call itself — never a sentence about which tool you will use, which tool was redirected, or switching surfaces. Words like 차단/전환/blocked/switching must not appear in your output for tool-routing reasons."
       : undefined,
     hasBareExec
       ? 'When a command requires network access, file writes outside workspace, or fails due to sandbox restrictions, include `sandbox_permissions: "require_escalated"` and `justification: "..."`.'
@@ -700,6 +721,9 @@ export function buildCursorToolGuidanceSystemNote(
         ? `For file edits, prefer the structured edit tools ${quotedNames(structuredEditNames)} — they take replacements that OpenCodex converts into Codex \`apply_patch\` changes. Include exact leading whitespace in old_string/new_string. Use \`apply_patch\` directly only with a \`*** Begin Patch\` envelope and bare \`@@\` hunks (never git-style \`@@ -n,m +n,m @@\`); never emit patch-like plain text as tool arguments.`
         : "For file edits, use the `apply_patch` tool, not built-in file write/delete tools."
       : undefined,
+    hasApplyPatch
+      ? "Creating or modifying file CONTENT via shell redirection (`>`, `>>`, `printf`/`echo` into a file, `cat <<EOF`, `sed -i`) is forbidden while apply_patch or the structured edit tools are advertised — use those edit tools so the change is reviewable. Shell output redirection is fine for logs/scratch pipes that are not the deliverable file."
+      : undefined,
     hasBareExec
       ? "For tool-count demos, each counted tool must be a separate Codex shell-bridge invocation/result; do not collapse several requested tools into one chained shell command."
       : undefined,
@@ -713,7 +737,7 @@ export function buildCursorToolGuidanceSystemNote(
     "Do not count or report a tool call unless a tool result was actually returned.",
     "When pursuing a multi-step task, check, or verification, do not stop or narrate intended future actions in plain text; immediately call the tool to execute the next step until the task is complete.",
     hasBareExec
-      ? `If a Cursor-native file read, directory listing, grep, or shell operation is rejected by the runtime, use ${shellBridgeLabel} with an equivalent host-shell-safe command (POSIX: \`cat\`/\`ls\`/\`rg\`; Windows PowerShell: \`Get-Content\`/\`Get-ChildItem\`/\`Select-String\`). For file edits, use ${structuredEditNames.length > 0 ? `the structured edit tools (${quotedNames(structuredEditNames)}) or ` : ""}\`apply_patch\` when available.`
+      ? `For every file read, directory listing, grep, or shell operation use ${shellBridgeLabel} directly with host-shell-safe commands (POSIX: \`cat\`/\`ls\`/\`rg\`; Windows PowerShell: \`Get-Content\`/\`Get-ChildItem\`/\`Select-String\`). For file edits, use ${structuredEditNames.length > 0 ? `the structured edit tools (${quotedNames(structuredEditNames)}) or ` : ""}\`apply_patch\` when available.`
       : undefined,
   ].filter((note): note is string => typeof note === "string");
   return notes.join(" ");

package/src/adapters/cursor/tool-result-normalize.ts

@@ -29,6 +29,31 @@ function isNodeReplOrComputerUseTool(toolName?: string, toolNamespace?: string):
   return lower.startsWith("mcp__node_repl") || lower.startsWith("mcp__computer_use");
 }
 
+/**
+ * Codex exec / shell-bridge tool names (flat and MCP-prefixed display aliases). An empty result
+ * here is almost always a code-mode cell that never called text()/notify() — the cursor model
+ * reads the blank [tool_result], concludes prior results were lost, and spirals into
+ * re-orientation retries (devlog 260826_cursor_responses_gap, live subagent transcripts).
+ */
+function isCodexExecBridgeTool(toolName?: string, toolNamespace?: string): boolean {
+  if (toolNamespace && toolNamespace.includes("opencodex-responses")) return true;
+  if (!toolName) return false;
+  const lower = toolName.toLowerCase();
+  return (
+    lower === "exec"
+    || lower === "exec_command"
+    || lower === "shell_command"
+    // Codex CLI/desktop native tool names: the multi-round "이전 출력이 비어 있어 처음부터"
+    // restart loop reproduced via codex exec because `shell` was not in this set
+    // (devlog 260826 gap-8 QA round 2).
+    || lower === "shell"
+    || lower === "local_shell"
+    || lower === "container.exec"
+    || lower.startsWith("mcp_opencodex-responses_")
+    || lower.startsWith("mcp__opencodex-responses__")
+  );
+}
+
 /** Failure states the Computer Use / node_repl runtime reports as PLAIN TEXT inside a non-error result. */
 const RUNTIME_FAILURE_GUIDANCE: ReadonlyArray<{ marker: string; guidance: string }> = [
   {
@@ -47,6 +72,22 @@ const RUNTIME_FAILURE_GUIDANCE: ReadonlyArray<{ marker: string; guidance: string
     marker: "unsupported import in exec",
     guidance: "Imports are not available in this exec context; use the injected globals instead.",
   },
+  {
+    marker: "require is not defined",
+    guidance: "In Codex code-mode exec (a V8 isolate, not Node.js), require/fs/process are not available. Use await tools.exec_command({ cmd: '...' }) inside exec to inspect files or run CLI tools.",
+  },
+  {
+    marker: "fs is not defined",
+    guidance: "In Codex code-mode exec (a V8 isolate, not Node.js), require/fs/process are not available. Use await tools.exec_command({ cmd: '...' }) inside exec to inspect files or run CLI tools.",
+  },
+  {
+    marker: "process is not defined",
+    guidance: "In Codex code-mode exec (a V8 isolate, not Node.js), require/fs/process are not available. Use await tools.exec_command({ cmd: '...' }) inside exec to inspect files or run CLI tools.",
+  },
+  {
+    marker: "module is not defined",
+    guidance: "In Codex code-mode exec (a V8 isolate, not Node.js), require/fs/process are not available. Use await tools.exec_command({ cmd: '...' }) inside exec to inspect files or run CLI tools.",
+  },
 ];
 
 /** Matches exec wrappers whose only payload is an empty-output marker. */
@@ -80,13 +121,17 @@ export function normalizeCursorToolResultText(
       changed: true,
     };
   }
-  if (!isError) {
-    for (const { marker, guidance } of RUNTIME_FAILURE_GUIDANCE) {
-      if (text.includes(marker)) {
-        return { text: `${text}\n[recovery: ${guidance}]`, isError: true, changed: true };
-      }
+  if (isCodexExecBridgeTool(options.toolName, options.toolNamespace) && EMPTY_EXEC_OUTPUT_REGEX.test(text.trim())) {
+    return {
+      text: "[empty output: the exec cell completed but emitted nothing. This is NOT lost context and NOT a blocked tool — in code mode call text(...) or notify(...) on any value you need to see (a bare await tools.exec_command(...) is not echoed automatically); in shell mode the command simply printed nothing. Do not re-run the same call expecting different output.]",
+      isError: false,
+      changed: true,
+    };
+  }
+  for (const { marker, guidance } of RUNTIME_FAILURE_GUIDANCE) {
+    if (text.includes(marker) && !text.includes("[recovery:") && !text.includes(guidance)) {
+      return { text: `${text}\n[recovery: ${guidance}]`, isError: true, changed: true };
     }
   }
   return { text, isError, changed: false };
 }
-

package/src/adapters/cursor/types.ts

@@ -15,6 +15,26 @@ export interface CursorRunRequest {
   requestedModelParameters?: readonly CursorRequestedModelParameter[];
   /** Cursor Router optimization parameter; valid only while modelId is the `default` wire model. */
   routingLevel?: CursorRoutingLevel;
+  /**
+   * Cursor Max Mode (ultra/big-context). Set from a synthetic `-1m` picker variant; the wire
+   * keeps the original model id and raises RequestedModel.maxMode + ModelDetails.maxMode
+   * (both fields — missing either can invalid_argument upstream). Devlog 260826 070.
+   */
+  maxMode?: boolean;
+  /**
+   * Bare API callers (no caller tools, no Codex thread identity) pay a ~10-15K input-token
+   * preamble because an absent AgentRunRequest.mcp_tools field makes Cursor inject its default
+   * native tool catalog. When true, an explicitly empty McpTools wrapper is serialized instead,
+   * suppressing that default. Codex-identified sessions keep the absent-field behavior.
+   */
+  suppressDefaultCursorToolCatalog?: boolean;
+  /**
+   * Corrective active-turn text for the single envelope-echo retry (devlog 260826 gap-10).
+   * When set on an external tool-result continuation, buildPreparedCursorRunRequest uses it as
+   * the userMessageAction text instead of the standard continuation text; rawMessages stay
+   * untouched so history replay is unchanged.
+   */
+  echoRetryContinuationText?: string;
   conversationId: string;
   system: string[];
   messages: CursorRequestMessage[];
@@ -25,10 +45,9 @@ export interface CursorRunRequest {
    * hydration). History stays text-only. data: URLs only in this slice.
    */
   selectedImages?: readonly ResolvedCursorImage[];
- tools?: OcxTool[];
- toolChoice?: OcxRequestOptions["toolChoice"];
-  textFormat?: OcxRequestOptions["textFormat"];
- parallelToolCalls?: boolean;
+  tools?: OcxTool[];
+  toolChoice?: OcxRequestOptions["toolChoice"];
+  parallelToolCalls?: boolean;
   /**
    * Clear provider-private context-usage carry-forward before this run. Used when Codex starts a
    * newly observed compacted context epoch, so pre-compaction totals are not over-reported while