@yansigit/opencodex 2.33.0 → 2.33.1

package/src/adapters/cursor/native-exec-shell.ts

@@ -19,6 +19,8 @@ import {
   type ExecServerMessage,
 } from "./gen/agent_pb";
 import { errorText, execBytes, execStreamCloseBytes } from "./native-exec-common";
+export { nativeShellDisabledMessage, type CursorNativeExecPolicyContext } from "./native-exec-policy";
+import { nativeShellDisabledMessage, type CursorNativeExecPolicyContext } from "./native-exec-policy";
 import {
   createAdmissionGate,
   type AdmissionLease,
@@ -81,21 +83,7 @@ let absoluteTerminations = 0;
 let unresolvedKills = 0;
 let killFailures = 0;
 
-/** Rejection text when Cursor-native shell is denied by policy (issue #604). */
-export function nativeShellDisabledMessage(): string {
-  // Do not insist on "the same command" — that steers models into replaying bash/CMD
-  // idioms through the Codex bridge on Windows PowerShell 5.1 and looping (#604).
-  // Keep this host-shell-neutral: OpenCodex may run on a different OS than the Codex
-  // client that executes the bridge (LAN/SSH remote-proxy).
-  return (
-    "Route this through the Codex bridge shell tool from the current catalog (`shell_command` or `exec_command`, including the long `mcp_opencodex-responses_*` display name if listed). "
-    + "Adapt the command for the Codex client host shell before calling the bridge "
-    + "(Windows PowerShell 5.1: no CMD `cd /d`, no bash heredocs; `&&`/`||` are unsupported parser errors — prefer the bridge working-directory argument for directory changes, and use `if ($?) { ... }` for success-gated follow-up steps; do not treat `;` as a substitute for `&&`). "
-    + "Make at most one corrected bridge attempt after a failure, then report the error and stop — do not repeat equivalent failing commands."
-  );
-}
-
-function rejectedShellResult(command: string, cwd: string, started: number) {
+function rejectedShellResult(command: string, cwd: string, started: number, opts: CursorNativeExecPolicyContext = {}) {
   return create(ShellResultSchema, {
     result: {
       case: "failure",
@@ -105,7 +93,7 @@ function rejectedShellResult(command: string, cwd: string, started: number) {
         exitCode: 1,
         signal: "",
         stdout: "",
-        stderr: nativeShellDisabledMessage(),
+        stderr: nativeShellDisabledMessage(opts),
         executionTime: Date.now() - started,
         aborted: true,
       }),
@@ -113,10 +101,10 @@ function rejectedShellResult(command: string, cwd: string, started: number) {
   });
 }
 
-export function rejectShellExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectShellExecForPolicy(execMsg: ExecServerMessage, opts: CursorNativeExecPolicyContext = {}): Uint8Array {
   if (execMsg.message.case !== "shellArgs") throw new Error("invalid shell exec");
   const args = execMsg.message.value;
-  return execBytes(execMsg, "shellResult", rejectedShellResult(args.command, resolve(args.workingDirectory || process.cwd()), Date.now()));
+  return execBytes(execMsg, "shellResult", rejectedShellResult(args.command, resolve(args.workingDirectory || process.cwd()), Date.now(), opts));
 }
 
 export function shellExec(execMsg: ExecServerMessage): Uint8Array {
@@ -154,7 +142,7 @@ export function shellExec(execMsg: ExecServerMessage): Uint8Array {
   }));
 }
 
-export function rejectShellStreamExecForPolicy(execMsg: ExecServerMessage): Uint8Array[] {
+export function rejectShellStreamExecForPolicy(execMsg: ExecServerMessage, opts: CursorNativeExecPolicyContext = {}): Uint8Array[] {
   if (execMsg.message.case !== "shellStreamArgs") throw new Error("invalid shell stream exec");
   const args = execMsg.message.value;
   const cwd = resolve(args.workingDirectory || process.cwd());
@@ -164,12 +152,12 @@ export function rejectShellStreamExecForPolicy(execMsg: ExecServerMessage): Uint
       event: { case: "start", value: create(ShellStreamStartSchema, { sandboxPolicy: args.requestedSandboxPolicy }) },
     })),
     execBytes(execMsg, "shellStream", create(ShellStreamSchema, {
-      event: { case: "stderr", value: create(ShellStreamStderrSchema, { data: nativeShellDisabledMessage() }) },
+      event: { case: "stderr", value: create(ShellStreamStderrSchema, { data: nativeShellDisabledMessage(opts) }) },
     })),
     execBytes(execMsg, "shellStream", create(ShellStreamSchema, {
       event: { case: "exit", value: create(ShellStreamExitSchema, { code: 1, cwd, aborted: true }) },
     })),
-    execBytes(execMsg, "shellResult", rejectedShellResult(args.command, cwd, started)),
+    execBytes(execMsg, "shellResult", rejectedShellResult(args.command, cwd, started, opts)),
     execStreamCloseBytes(execMsg),
   ];
 }
@@ -260,12 +248,12 @@ export async function shellStreamExec(execMsg: ExecServerMessage): Promise<Uint8
   return replies;
 }
 
-export function rejectBackgroundShellSpawnExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectBackgroundShellSpawnExecForPolicy(execMsg: ExecServerMessage, opts: CursorNativeExecPolicyContext = {}): Uint8Array {
   if (execMsg.message.case !== "backgroundShellSpawnArgs") throw new Error("invalid background shell exec");
   const args = execMsg.message.value;
   const cwd = resolve(args.workingDirectory || process.cwd());
   return execBytes(execMsg, "backgroundShellSpawnResult", create(BackgroundShellSpawnResultSchema, {
-    result: { case: "error", value: create(BackgroundShellSpawnErrorSchema, { command: args.command, workingDirectory: cwd, error: nativeShellDisabledMessage() }) },
+    result: { case: "error", value: create(BackgroundShellSpawnErrorSchema, { command: args.command, workingDirectory: cwd, error: nativeShellDisabledMessage(opts) }) },
   }));
 }
 
@@ -517,10 +505,10 @@ export function backgroundShellSpawnExec(execMsg: ExecServerMessage, sessionId:
   }
 }
 
-export function rejectWriteShellStdinExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
+export function rejectWriteShellStdinExecForPolicy(execMsg: ExecServerMessage, opts: CursorNativeExecPolicyContext = {}): Uint8Array {
   if (execMsg.message.case !== "writeShellStdinArgs") throw new Error("invalid shell stdin exec");
   return execBytes(execMsg, "writeShellStdinResult", create(WriteShellStdinResultSchema, {
-    result: { case: "error", value: create(WriteShellStdinErrorSchema, { error: nativeShellDisabledMessage() }) },
+    result: { case: "error", value: create(WriteShellStdinErrorSchema, { error: nativeShellDisabledMessage(opts) }) },
   }));
 }
 

package/src/adapters/cursor/native-exec.ts

@@ -51,6 +51,7 @@ import {
   type CursorNativeToolDeps,
 } from "./native-exec-tools";
 import { clientBytes, execBytes, execStreamCloseBytes, execThrowBytes } from "./native-exec-common";
+import { type CursorNativeExecPolicyContext } from "./native-exec-policy";
 import type { McpToolDefinition } from "./gen/agent_pb";
 import { OCX_RESPONSES_TOOL_PROVIDER } from "./tool-definitions";
 
@@ -72,12 +73,18 @@ export interface CursorNativeExecContext extends CursorNativeExecDeps {
   rejectNativeFileMutations?: boolean;
   /** The synthetic exact-match edit tools (edit_file / multi_edit) are advertised this request. */
   structuredEditAvailable?: boolean;
+  /** Codex code mode advertises one freeform exec tool; native rejections must steer to nested helpers. */
+  codeMode?: boolean;
 }
 
 export function cursorUnsafeNativeLocalExecEnabled(input: Pick<CursorNativeExecContext, "unsafeAllowNativeLocalExec"> = {}): boolean {
   return input.unsafeAllowNativeLocalExec === true;
 }
 
+function nativeExecPolicyContext(deps: CursorNativeExecContext): CursorNativeExecPolicyContext {
+  return deps.codeMode === true ? { codeMode: true } : {};
+}
+
 /**
  * Content-addressed blob store shared across streams. Bounded: without eviction a long-running
  * proxy accumulates every conversation's prompt blobs forever (unbounded memory) and any stale
@@ -556,16 +563,17 @@ export async function handleCursorNativeExec(execMsg: ExecServerMessage, deps: C
     }))];
   }
   if (!cursorUnsafeNativeLocalExecEnabled(deps)) {
-    if (execCase === "readArgs") return [rejectReadExecForPolicy(execMsg)];
-    if (execCase === "writeArgs") return [rejectWriteExecForPolicy(execMsg)];
-    if (execCase === "deleteArgs") return [rejectDeleteExecForPolicy(execMsg)];
-    if (execCase === "lsArgs") return [rejectLsExecForPolicy(execMsg)];
-    if (execCase === "grepArgs") return [rejectGrepExecForPolicy(execMsg)];
-    if (execCase === "shellArgs") return [rejectShellExecForPolicy(execMsg)];
-    if (execCase === "shellStreamArgs") return rejectShellStreamExecForPolicy(execMsg);
-    if (execCase === "backgroundShellSpawnArgs") return [rejectBackgroundShellSpawnExecForPolicy(execMsg)];
-    if (execCase === "writeShellStdinArgs") return [rejectWriteShellStdinExecForPolicy(execMsg)];
-    if (execCase === "fetchArgs") return [rejectFetchExecForPolicy(execMsg)];
+    const policy = nativeExecPolicyContext(deps);
+    if (execCase === "readArgs") return [rejectReadExecForPolicy(execMsg, policy)];
+    if (execCase === "writeArgs") return [rejectWriteExecForPolicy(execMsg, policy)];
+    if (execCase === "deleteArgs") return [rejectDeleteExecForPolicy(execMsg, policy)];
+    if (execCase === "lsArgs") return [rejectLsExecForPolicy(execMsg, policy)];
+    if (execCase === "grepArgs") return [rejectGrepExecForPolicy(execMsg, policy)];
+    if (execCase === "shellArgs") return [rejectShellExecForPolicy(execMsg, policy)];
+    if (execCase === "shellStreamArgs") return rejectShellStreamExecForPolicy(execMsg, policy);
+    if (execCase === "backgroundShellSpawnArgs") return [rejectBackgroundShellSpawnExecForPolicy(execMsg, policy)];
+    if (execCase === "writeShellStdinArgs") return [rejectWriteShellStdinExecForPolicy(execMsg, policy)];
+    if (execCase === "fetchArgs") return [rejectFetchExecForPolicy(execMsg, policy)];
   }
   if (execCase === "readArgs") return [readExec(execMsg)];
   if (execCase === "writeArgs") return [deps.rejectNativeFileMutations ? rejectWriteExecForApplyPatch(execMsg, deps.structuredEditAvailable === true) : writeExec(execMsg)];

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

@@ -1136,6 +1136,31 @@ function cursorFreeformWrapperValid(args: string): boolean {
   }
 }
 
+/**
+ * Cursor sometimes sends a freeform body as a JSON string or as a one-key object instead of the
+ * advertised `{input: string}` wrapper. Preserve incomplete JSON for the late native-args path,
+ * but wrap complete/raw bodies before the Responses bridge validates them.
+ */
+function normalizeFreeformArgs(args: string): string {
+  if (args.length === 0) return args;
+  try {
+    const parsed = JSON.parse(args) as unknown;
+    if (typeof parsed === "string") return JSON.stringify({ input: parsed });
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      const object = parsed as Record<string, unknown>;
+      if ("input" in object || Object.keys(object).length === 0) return args;
+      const values = Object.values(object);
+      const input = values.length === 1 && typeof values[0] === "string" ? values[0] : JSON.stringify(object);
+      return JSON.stringify({ input });
+    }
+    return args;
+  } catch {
+    return args.trimStart().startsWith("{") || args.trimStart().startsWith("[")
+      ? args
+      : JSON.stringify({ input: args });
+  }
+}
+
 function dropInvalidFreeformCall(state: CursorProtobufEventState, callId: string, toolName: string): CursorServerMessage[] {
   state.openToolCalls.delete(callId);
   state.translatorBudget?.closeCall(callId);
@@ -1162,6 +1187,7 @@ function dropStructuredEditCall(state: CursorProtobufEventState, callId: string,
 function commitToolCall(state: CursorProtobufEventState, callId: string, finalArgs: string): CursorServerMessage[] {
   const open = state.openToolCalls.get(callId);
   if (!open) return [];
+  if (state.freeformToolNames?.has(open.name)) finalArgs = normalizeFreeformArgs(finalArgs);
   if (state.freeformToolNames?.has(open.name) && !cursorFreeformWrapperValid(finalArgs)) {
     return dropInvalidFreeformCall(state, callId, open.name);
   }
@@ -1436,7 +1462,7 @@ function parseCursorTextToolCalls(text: string, state: CursorProtobufEventState)
         && (
           (name !== undefined && openBeforeStart.args.length === 0)
           || (state.freeformToolNames?.has(openBeforeStart.name) === true
-            && !cursorFreeformWrapperValid(openBeforeStart.args)
+            && !cursorFreeformWrapperValid(normalizeFreeformArgs(openBeforeStart.args))
           )
         )
       ) {
@@ -1460,7 +1486,7 @@ function parseCursorTextToolCalls(text: string, state: CursorProtobufEventState)
       if (
         !openBeforeStart && open && !hasMcpArgBytes(args)
         && state.freeformToolNames?.has(open.name) === true
-        && !cursorFreeformWrapperValid(open.args)
+        && !cursorFreeformWrapperValid(normalizeFreeformArgs(open.args))
       ) {
         open.awaitingNativeArgs = true;
         return [];

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

@@ -77,7 +77,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 {
@@ -855,8 +870,10 @@ function buildPreparedCursorRunRequest(
     ? "userMessageAction"
     : "resumeAction";
   const actionText = externalToolContinuation
-    ? CURSOR_EXTERNAL_TOOL_CONTINUATION_TEXT
-    : text;
+    ? (request.echoRetryContinuationText ?? externalToolContinuationText(request.rawMessages))
+    : request.echoRetryContinuationText
+      ? `${text}\n\n[correction] ${request.echoRetryContinuationText}`
+      : text;
   const action = create(ConversationActionSchema, {
     action: actionCase === "userMessageAction"
       ? {

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

@@ -202,6 +202,13 @@ function normalizeCursorModelId(modelId: string, reasoning?: string): {
       ],
     };
   }
+  if (id === "composer-2.5") {
+    return {
+      ...selection,
+      modelId: id,
+      requestedModelParameters: [{ id: "fast", value: "false" }],
+    };
+  }
   return { ...selection, modelId: suffix ? cursorRequestWireModelIdWithEffort(id, suffix) : id };
 }
 

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

@@ -112,6 +112,13 @@ export const CURSOR_MULTI_EDIT_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;
+
 /**
  * Responses/Codex-side schema used ONLY for arg-key normalization after Cursor returns a call.
  * Cursor models are trained to emit `cmd`; Codex `shell_command` / `exec_command` validate
@@ -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);
   }
@@ -678,6 +687,12 @@ export function buildCursorToolGuidanceSystemNote(
     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
+      ? "To read, search, or inspect files or run CLI commands, call `await tools.exec_command({ cmd: '...' })` inside `exec`. Do not write Node.js scripts or `require('fs')`."
+      : 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 +700,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 +718,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,

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

@@ -44,8 +44,24 @@ const RUNTIME_FAILURE_GUIDANCE: ReadonlyArray<{ marker: string; guidance: string
     guidance: "The node_repl session keeps earlier declarations; rename the variable or use var/reassignment instead of redeclaring.",
   },
   {
-    marker: "unsupported import in exec",
-    guidance: "Imports are not available in this exec context; use the injected globals instead.",
+   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.",
   },
 ];
 
@@ -80,13 +96,10 @@ 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 };
-      }
+  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,13 @@ export interface CursorRunRequest {
   requestedModelParameters?: readonly CursorRequestedModelParameter[];
   /** Cursor Router optimization parameter; valid only while modelId is the `default` wire model. */
   routingLevel?: CursorRoutingLevel;
+  /**
+   * 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[];

package/src/adapters/cursor.ts

@@ -41,6 +41,15 @@ import {
   shouldSurfaceCursorOverflowFirst,
 } from "./cursor/thread-continuity";
 import { runCursorTurnWithRetry } from "./cursor/transport-retry";
+import { cursorRequestHasShellAlias, cursorRequestUsesCodeMode } from "./cursor/tool-definitions";
+import {
+  CURSOR_ECHO_RETRY_CONTINUATION_TEXT,
+  CURSOR_ROUTING_COMMENTARY_RETRY_TEXT,
+  CursorEnvelopeEchoSniffer,
+  CursorRoutingCommentaryError,
+  CursorRoutingCommentarySniffer,
+  CursorToolResultEchoError,
+} from "./cursor/envelope-echo";
 import {
   createDisabledCursorTransport,
   CursorTransportDisabledError,
@@ -216,6 +225,30 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
             || activeRequest.modelId.includes("kimi-k3")
             || activeRequest.modelId.includes("opus-4-8");
           const heartbeatOnlyMs = isHeavyReasoning ? 300_000 : 180_000;
+          const armEchoSniffer =
+            isCursorExternalWireModel(activeRequest.modelId)
+            && (_parsed.context.messages ?? []).some(message => message.role === "toolResult");
+          const echoSniffer = armEchoSniffer ? new CursorEnvelopeEchoSniffer() : undefined;
+          const armRoutingCommentarySniffer =
+            isCursorExternalWireModel(activeRequest.modelId)
+            && (
+              cursorRequestUsesCodeMode(activeRequest.tools, activeRequest.toolChoice)
+              || cursorRequestHasShellAlias(activeRequest.tools)
+            );
+          const routingCommentarySniffer = armRoutingCommentarySniffer
+            ? new CursorRoutingCommentarySniffer()
+            : undefined;
+          let guardHeld: AdapterEvent[] = [];
+          const releaseGuardHeld = () => {
+            for (const held of guardHeld) {
+              if (held.type !== "heartbeat") emittedOutput = true;
+              emit(held);
+            }
+            guardHeld = [];
+          };
+          const guardsSettled = () =>
+            (!echoSniffer || echoSniffer.settled)
+            && (!routingCommentarySniffer || routingCommentarySniffer.settled);
           await runCursorTurnWithRetry(
             makeTransport,
             {
@@ -246,6 +279,43 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
                 },
               });
               for (const event of events) {
+                if (!guardsSettled()) {
+                  if (event.type === "text_delta") {
+                    guardHeld.push(event);
+                    if (echoSniffer && !echoSniffer.settled) {
+                      const decision = echoSniffer.feed(event.text);
+                      if (decision.kind === "echo") {
+                        guardHeld = [];
+                        throw new CursorToolResultEchoError(decision.marker);
+                      }
+                    }
+                    if (routingCommentarySniffer && !routingCommentarySniffer.settled) {
+                      const decision = routingCommentarySniffer.feed(event.text);
+                      if (decision.kind === "hallucination") {
+                        guardHeld = [];
+                        throw new CursorRoutingCommentaryError();
+                      }
+                    }
+                    if (guardsSettled()) releaseGuardHeld();
+                    continue;
+                  } else if (event.type === "thinking_delta" || event.type === "heartbeat") {
+                    // Reasoning before first text stays ordered; liveness still passes through.
+                    if (event.type === "thinking_delta") {
+                      guardHeld.push(event);
+                      continue;
+                    }
+                  } else {
+                    // A tool call, done, or error closes the text quarantine. Re-check the full
+                    // held first line before release so a fragmented routing claim cannot leak.
+                    echoSniffer?.finish();
+                    const routingDecision = routingCommentarySniffer?.finish();
+                    if (routingDecision?.kind === "hallucination") {
+                      guardHeld = [];
+                      throw new CursorRoutingCommentaryError();
+                    }
+                    releaseGuardHeld();
+                  }
+                }
                 if (event.type !== "heartbeat") emittedOutput = true;
                 if (event.type === "done") {
                   commitCapturedCheckpoint(activeRequest);
@@ -299,6 +369,50 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
             await runOnce(request);
             break;
           } catch (err) {
+            const outputGuardRetryText =
+              err instanceof CursorToolResultEchoError
+                ? CURSOR_ECHO_RETRY_CONTINUATION_TEXT
+                : err instanceof CursorRoutingCommentaryError
+                  ? CURSOR_ROUTING_COMMENTARY_RETRY_TEXT
+                  : undefined;
+            // One-shot corrective retry for guarded external output (devlog 260826 gap-10/11).
+            // The quarantine guarantees no client-visible delta escaped, so a fresh-conversation
+            // retry is safe. A second rejection propagates as an error rather than looping.
+            if (
+              outputGuardRetryText
+              && !emittedOutput
+              && !replayUnsafe
+              && !incoming.abortSignal?.aborted
+            ) {
+              debugProviderDiagnostic(
+                "cursor",
+                err instanceof CursorToolResultEchoError
+                  ? "envelope-echo-retry"
+                  : "routing-commentary-retry",
+                {
+                  wireModel: request.modelId,
+                  conversationHash: request.conversationId.slice(0, 16),
+                },
+              );
+              const echoedConversationId = request.conversationId;
+              lastTransport = undefined;
+              _parsed._cursorConversationId = undefined;
+              request = {
+                ...createCursorRequest(_parsed, { forceFreshConversation: true }),
+                echoRetryContinuationText: outputGuardRetryText,
+              };
+              rekeyContextUsage(echoedConversationId, request.conversationId);
+              _parsed._cursorConversationId = request.conversationId;
+              if (_parsed._clientThreadId && _parsed._cursorIsolateConversation !== true) {
+                rememberCursorThreadConversation(
+                  _parsed._clientThreadId,
+                  request.conversationId,
+                  _parsed._cursorIdentityScope,
+                );
+              }
+              await runOnce(request);
+              break;
+            }
             const overflowRemintSafe =
               !lastRawIsToolResult
               && !emittedOutput

package/src/adapters/google-aistudio-parser.ts

@@ -0,0 +1,49 @@
+/**
+ * Resilient streaming chunk parser for Google AI Studio MakerSuite private RPC protocol.
+ */
+
+export interface MakerSuiteParsedResult {
+  text: string;
+  thought?: string;
+  thoughtSignature?: string;
+}
+
+export function parseMakerSuiteChunk(raw: string): MakerSuiteParsedResult {
+  const result: MakerSuiteParsedResult = { text: "" };
+  if (!raw || typeof raw !== "string") return result;
+
+  // 1. Extract regular model response text: [null, "escaped_text"]
+  const textMatches = raw.matchAll(/\[\s*null\s*,\s*"((?:[^"\\]|\\.)*)"/g);
+  for (const m of textMatches) {
+    if (!m[1]) continue;
+    try {
+      const decoded = JSON.parse('"' + m[1] + '"');
+      if (decoded) result.text += decoded;
+    } catch (err) {
+      void err;
+      result.text += m[1];
+    }
+  }
+
+  // 2. Extract model reasoning / thoughts: [true, "escaped_thought"]
+  const thoughtMatches = raw.matchAll(/\[\s*true\s*,\s*"((?:[^"\\]|\\.)*)"/g);
+  for (const m of thoughtMatches) {
+    if (!m[1]) continue;
+    try {
+      const decoded = JSON.parse('"' + m[1] + '"');
+      if (decoded) result.thought = (result.thought ?? "") + decoded;
+    } catch (err) {
+      void err;
+      result.thought = (result.thought ?? "") + m[1];
+    }
+  }
+
+  // 3. Extract Gemini thought signature token if present
+  const sigMatch = raw.match(/"(ErQ[A-Za-z0-9+/=_-]{30,})"/);
+  if (sigMatch?.[1]) {
+    result.thoughtSignature = sigMatch[1];
+  }
+
+  return result;
+}
+