Skip to content

Commit 9099e4b

Browse files
geunwoojun99claudelidge-jun
authored
fix(cursor): use factual tool redirects for Claude-family models (#6664)
* fix(cursor): use factual tool redirects for Claude-family models Explicit Claude-family Cursor targets now receive factual tool guidance and native-tool refusals, without instructions to conceal the redirect. The routing-commentary sniffer is no longer armed for them. Empty catalogs report no available tools; other model families keep their legacy wording. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * test(layout): keep the cursor-tool-wording registration under the layout file-size threshold * fix(cursor): name redirect tools with the request catalog --------- Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]> Co-authored-by: JUN <[email protected]>
1 parent 0cd680a commit 9099e4b

13 files changed

Lines changed: 493 additions & 21 deletions

File tree

‎docs-site/src/content/docs/reference/adapters.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -544,7 +544,13 @@ compatibility pair: `agent.v1.AgentService/RunSSE` for server output and
544544
Foreground `shellArgs` and `shellStreamArgs` are an exception: both are rejected before spawn
545545
on every platform until kernel-backed descendant ownership is available. Use client shell tools;
546546
background-shell execution and other native operations retain their existing policy.
547-
- The denial reply is a silent redirect whose wording follows the request catalog.
547+
- The denial reply follows the request catalog. Explicit Claude-family Cursor models receive
548+
factual wording that names the available tools without instructions to hide or avoid discussing
549+
the redirect. Factual routing commentary can precede the next tool call without ending the turn.
550+
When no client or configured MCP tools are available, Claude models are asked to answer without
551+
tools or report the limitation instead of calling nonexistent shell/edit tools.
552+
Other models, including Auto/default, retain the existing silent-redirect wording and commentary
553+
guard. Tool availability, execution policy, and approval/sandbox behavior are unchanged.
548554
In code mode — a freeform unified `exec` and no bare shell bridge — the redirect points inside `exec`, where
549555
shell, file, search, and fetch are nested `tools.<name>(...)` helpers of the JavaScript cell,
550556
and never recommends the top-level shell bridge code mode does not expose. A flat catalog that

‎scripts/test-layout/layout.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -818,7 +818,7 @@
818818
"cursor-tool-finalize-race.test.ts": "providers/cursor",
819819
"cursor-tool-result-image.test.ts": "providers/cursor",
820820
"cursor-tool-result-invocation.test.ts": "providers/cursor",
821-
"cursor-tool-suspended-checkpoint.test.ts": "providers/cursor",
821+
"cursor-tool-suspended-checkpoint.test.ts": "providers/cursor", "cursor-tool-wording.test.ts": "providers/cursor",
822822
"cursor-toolresult-normalize.test.ts": "providers/cursor",
823823
"cursor-transport-retry.test.ts": "providers/cursor",
824824
"cursor-ultra-mode.test.ts": "providers/cursor",

‎src/adapters/cursor.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ import {
6565
type CursorTransportFactory,
6666
} from "./cursor/transport";
6767
import { cursorLiveRosterScope } from "./cursor/catalog";
68+
import { cursorUsesPlainToolWording } from "./cursor/tool-wording";
6869

6970
export const CURSOR_API_URL = "https://api2.cursor.sh";
7071

@@ -313,8 +314,10 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
313314
const armMidstreamEcho = cursorNeedsExternalToolContinuation(activeRequest.modelId) && replaysToolResult;
314315
const midstreamObserver = armMidstreamEcho ? new CursorMidstreamEchoObserver() : undefined;
315316
const midstreamFilter = armMidstreamEcho ? new ToolEnvelopeEchoFilter() : undefined;
317+
// Claude's factual redirects allow truthful routing prose; it is not a failure claim.
316318
const armRoutingCommentarySniffer =
317319
isCursorExternalWireModel(activeRequest.modelId)
320+
&& !cursorUsesPlainToolWording(activeRequest.modelId)
318321
&& (
319322
cursorRequestUsesCodeMode(activeRequest.tools, activeRequest.toolChoice)
320323
|| cursorRequestHasShellAlias(activeRequest.tools)

‎src/adapters/cursor/live-transport.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import {
1616
import { activePromptText, prepareCursorRunRequest } from "./protobuf-request";
1717
import { prepareCursorRawMessages, resolveActiveCursorImages } from "./images";
1818
import { isCursorExternalWireModel } from "./discovery";
19+
import { cursorUsesPlainToolWording } from "./tool-wording";
1920
import { cursorRequestMessagesFromRaw } from "./request-builder";
2021
import {
2122
createCursorContextUsageTracker,
@@ -718,7 +719,8 @@ class LiveCursorTransport implements CursorTransport {
718719
clientToolDefs,
719720
rejectNativeFileMutations: cursorRequestAdvertisesApplyPatch(request.tools, request.toolChoice),
720721
structuredEditAvailable: syntheticStructuredEditToolNames.size > 0,
721-
nativeExecRedirectHint: cursorNativeExecRedirectHint(cursorVisibleTools, this.execContext.mcpToolDefs ?? []),
722+
nativeExecRedirectHint: cursorNativeExecRedirectHint(cursorVisibleTools, this.execContext.mcpToolDefs ?? [], activeRequest.modelId),
723+
plainToolWording: cursorUsesPlainToolWording(activeRequest.modelId),
722724
};
723725
const toolSchemas = new Map<string, unknown>();
724726
const cursorToolNameMap = new Map<string, string>();

‎src/adapters/cursor/native-exec-fs.ts‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,17 @@ import {
3535
} from "./gen/agent_pb";
3636
import { errorText, execBytes, lineCount, textDecoder, textEncoder } from "./native-exec-common";
3737

38+
import { CURSOR_TOOL_CALL_CONTINUATION } from "./tool-wording";
39+
3840
const MAX_GREP_FILES = 500;
3941
const MAX_GREP_RESULTS = 200;
4042
const MAX_FILE_BYTES = 1_000_000;
4143

42-
function codexNativeMutationRefusal(operation: "write" | "delete", structuredEditAvailable: boolean): string {
44+
function codexNativeMutationRefusal(operation: "write" | "delete", structuredEditAvailable: boolean, plainToolWording = false): string {
4345
const structuredHint = structuredEditAvailable
4446
? " Use the structured edit tools (`edit_file` / `multi_edit`) or the `apply_patch` tool for file edits so Codex can approve the change, enforce sandbox policy, show diffs, and record rollout."
4547
: " Use the `apply_patch` tool for file edits so Codex can approve the change, enforce sandbox policy, show diffs, and record rollout.";
48+
if (plainToolWording) return `Cursor-native ${operation} is not available for this request.${structuredHint} No file was changed. ${CURSOR_TOOL_CALL_CONTINUATION}`;
4649
return `Make this ${operation} through the Codex edit path instead.${structuredHint} No file was changed. Do NOT narrate this redirect or comment on tool availability — just make the edit call.`;
4750
}
4851

@@ -87,24 +90,24 @@ export function readExec(execMsg: ExecServerMessage): Uint8Array {
8790
}
8891
}
8992

90-
export function rejectWriteExecForApplyPatch(execMsg: ExecServerMessage, structuredEditAvailable = false): Uint8Array {
93+
export function rejectWriteExecForApplyPatch(execMsg: ExecServerMessage, structuredEditAvailable = false, plainToolWording = false): Uint8Array {
9194
if (execMsg.message.case !== "writeArgs") throw new Error("invalid write exec");
9295
const path = resolve(execMsg.message.value.path);
9396
return execBytes(execMsg, "writeResult", create(WriteResultSchema, {
9497
result: {
9598
case: "rejected",
96-
value: create(WriteRejectedSchema, { path, reason: codexNativeMutationRefusal("write", structuredEditAvailable) }),
99+
value: create(WriteRejectedSchema, { path, reason: codexNativeMutationRefusal("write", structuredEditAvailable, plainToolWording) }),
97100
},
98101
}));
99102
}
100103

101-
export function rejectWriteExecForPolicy(execMsg: ExecServerMessage, hint?: string): Uint8Array {
104+
export function rejectWriteExecForPolicy(execMsg: ExecServerMessage, hint?: string, plainToolWording = false): Uint8Array {
102105
if (execMsg.message.case !== "writeArgs") throw new Error("invalid write exec");
103106
const path = resolve(execMsg.message.value.path);
104107
return execBytes(execMsg, "writeResult", create(WriteResultSchema, {
105108
result: {
106109
case: "rejected",
107-
value: create(WriteRejectedSchema, { path, reason: `${hint ?? NATIVE_LOCAL_EXEC_DISABLED} No file was changed.` }),
110+
value: create(WriteRejectedSchema, { path, reason: plainToolWording ? `No file was changed. ${hint ?? NATIVE_LOCAL_EXEC_DISABLED}` : `${hint ?? NATIVE_LOCAL_EXEC_DISABLED} No file was changed.` }),
108111
},
109112
}));
110113
}
@@ -136,24 +139,24 @@ export function writeExec(execMsg: ExecServerMessage): Uint8Array {
136139
}
137140
}
138141

139-
export function rejectDeleteExecForApplyPatch(execMsg: ExecServerMessage, structuredEditAvailable = false): Uint8Array {
142+
export function rejectDeleteExecForApplyPatch(execMsg: ExecServerMessage, structuredEditAvailable = false, plainToolWording = false): Uint8Array {
140143
if (execMsg.message.case !== "deleteArgs") throw new Error("invalid delete exec");
141144
const path = resolve(execMsg.message.value.path);
142145
return execBytes(execMsg, "deleteResult", create(DeleteResultSchema, {
143146
result: {
144147
case: "rejected",
145-
value: create(DeleteRejectedSchema, { path, reason: codexNativeMutationRefusal("delete", structuredEditAvailable) }),
148+
value: create(DeleteRejectedSchema, { path, reason: codexNativeMutationRefusal("delete", structuredEditAvailable, plainToolWording) }),
146149
},
147150
}));
148151
}
149152

150-
export function rejectDeleteExecForPolicy(execMsg: ExecServerMessage, hint?: string): Uint8Array {
153+
export function rejectDeleteExecForPolicy(execMsg: ExecServerMessage, hint?: string, plainToolWording = false): Uint8Array {
151154
if (execMsg.message.case !== "deleteArgs") throw new Error("invalid delete exec");
152155
const path = resolve(execMsg.message.value.path);
153156
return execBytes(execMsg, "deleteResult", create(DeleteResultSchema, {
154157
result: {
155158
case: "rejected",
156-
value: create(DeleteRejectedSchema, { path, reason: `${hint ?? NATIVE_LOCAL_EXEC_DISABLED} No file was changed.` }),
159+
value: create(DeleteRejectedSchema, { path, reason: plainToolWording ? `No file was changed. ${hint ?? NATIVE_LOCAL_EXEC_DISABLED}` : `${hint ?? NATIVE_LOCAL_EXEC_DISABLED} No file was changed.` }),
157160
},
158161
}));
159162
}

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

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ import { OCX_RESPONSES_TOOL_PROVIDER } from "./tool-definitions";
5757
import { CODEX_UNIFIED_EXEC_TOOL, cursorRequestHasExecutionPath, cursorRequestHasShellAlias, cursorRequestUsesCodeMode, cursorToolWireName } from "./tool-naming";
5858
import { CODE_MODE_RESULT_ECHO_SENTENCE } from "../exec-tool-result-normalize";
5959
import type { OcxTool } from "../../types";
60+
import { cursorPlainNativeExecFallback, cursorPlainNativeExecRedirectHint, cursorUsesPlainToolWording } from "./tool-wording";
6061

6162
export type CursorNativeExecDeps = CursorNativeNetworkDeps & CursorNativeToolDeps;
6263

@@ -80,6 +81,8 @@ export interface CursorNativeExecContext extends CursorNativeExecDeps {
8081
structuredEditAvailable?: boolean;
8182
/** Catalog-aware redirect text for denied native fs/shell attempts (undefined = default bridge wording). */
8283
nativeExecRedirectHint?: string;
84+
/** Claude-family Cursor targets receive factual redirects, without narration restrictions. */
85+
plainToolWording?: boolean;
8386
}
8487

8588
const REDIRECT_HINT_MAX_TOOLS = 16;
@@ -93,7 +96,9 @@ const REDIRECT_HINT_MAX_TOOLS = 16;
9396
export function cursorNativeExecRedirectHint(
9497
tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
9598
mcpToolDefs: readonly Pick<McpToolDefinition, "name" | "providerIdentifier">[] = [],
99+
modelId?: string,
96100
): string | undefined {
101+
if (cursorUsesPlainToolWording(modelId)) return cursorPlainNativeExecRedirectHint(tools, mcpToolDefs);
97102
const clientTools = tools ?? [];
98103
if (cursorRequestHasShellAlias(clientTools)) return undefined;
99104
// Code mode (freeform unified `exec`, no bare shell bridge): the default bridge wording names
@@ -704,6 +709,9 @@ export function cursorBlobStoreDebugSnapshotForTests(): Array<{
704709

705710
export async function handleCursorNativeExec(execMsg: ExecServerMessage, deps: CursorNativeExecContext = {}): Promise<Uint8Array[]> {
706711
const execCase = execMsg.message.case;
712+
if (deps.plainToolWording && !deps.nativeExecRedirectHint) {
713+
deps = { ...deps, nativeExecRedirectHint: cursorPlainNativeExecFallback([...(deps.clientToolDefs ?? []), ...(deps.mcpToolDefs ?? [])]) };
714+
}
707715
if (execCase === "requestContextArgs") {
708716
const tools = [...(deps.mcpToolDefs ?? []), ...(deps.clientToolDefs ?? [])];
709717
return [execBytes(execMsg, "requestContextResult", create(RequestContextResultSchema, {
@@ -712,8 +720,8 @@ export async function handleCursorNativeExec(execMsg: ExecServerMessage, deps: C
712720
}
713721
if (!cursorUnsafeNativeLocalExecEnabled(deps)) {
714722
if (execCase === "readArgs") return [rejectReadExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
715-
if (execCase === "writeArgs") return [rejectWriteExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
716-
if (execCase === "deleteArgs") return [rejectDeleteExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
723+
if (execCase === "writeArgs") return [rejectWriteExecForPolicy(execMsg, deps.nativeExecRedirectHint, deps.plainToolWording)];
724+
if (execCase === "deleteArgs") return [rejectDeleteExecForPolicy(execMsg, deps.nativeExecRedirectHint, deps.plainToolWording)];
717725
if (execCase === "lsArgs") return [rejectLsExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
718726
if (execCase === "grepArgs") return [rejectGrepExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
719727
if (execCase === "shellArgs") return [rejectShellExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
@@ -723,8 +731,8 @@ export async function handleCursorNativeExec(execMsg: ExecServerMessage, deps: C
723731
if (execCase === "fetchArgs") return [rejectFetchExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
724732
}
725733
if (execCase === "readArgs") return [readExec(execMsg)];
726-
if (execCase === "writeArgs") return [deps.rejectNativeFileMutations ? rejectWriteExecForApplyPatch(execMsg, deps.structuredEditAvailable === true) : writeExec(execMsg)];
727-
if (execCase === "deleteArgs") return [deps.rejectNativeFileMutations ? rejectDeleteExecForApplyPatch(execMsg, deps.structuredEditAvailable === true) : deleteExec(execMsg)];
734+
if (execCase === "writeArgs") return [deps.rejectNativeFileMutations ? rejectWriteExecForApplyPatch(execMsg, deps.structuredEditAvailable === true, deps.plainToolWording) : writeExec(execMsg)];
735+
if (execCase === "deleteArgs") return [deps.rejectNativeFileMutations ? rejectDeleteExecForApplyPatch(execMsg, deps.structuredEditAvailable === true, deps.plainToolWording) : deleteExec(execMsg)];
728736
if (execCase === "lsArgs") return [lsExec(execMsg)];
729737
if (execCase === "grepArgs") return [grepExec(execMsg)];
730738
if (execCase === "shellArgs") return [shellExec(execMsg, deps.nativeExecRedirectHint)];

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,7 @@ function systemPromptBlobs(request: CursorRunRequest): RootBlobCandidate[] {
224224
const cursorToolGuidance = buildCursorToolGuidanceSystemNote(
225225
cursorToolsForActivePrompt(request.tools, activePromptText(request), request.toolChoice),
226226
request.toolChoice,
227+
request.modelId,
227228
);
228229
if (cursorToolGuidance) prompts.push(cursorToolGuidance);
229230
return prompts.map(content => rootBlobCandidate({ role: "system", content }, "system"));

0 commit comments

Comments
 (0)