Skip to content

Use Claude Code with your ChatGPT, Kimi, Cursor or Grok subscription via a local Anthropic-compatible proxy

Rust

cursor: decode the native exec frame, and stop reading tool calls as text

Hector Bernstorffbb49a7badd92
diff --git a/src/providers/cursor/proto.rs b/src/providers/cursor/proto.rs
index 2a93f14..7b7427c 100644
--- a/src/providers/cursor/proto.rs
+++ b/src/providers/cursor/proto.rs
@@ -141,17 +141,23 @@ pub struct SelectedImage {
pub struct AgentServerMessage {
#[prost(message, optional, tag = "1")]
pub interaction_update: Option<InteractionUpdate>,
- #[prost(message, optional, tag = "3")]
+ #[prost(message, optional, tag = "2")]
pub exec_server_message: Option<ExecServerMessage>,
}
+// Tag numbers verified against the Cursor Agent bundle's protobuf descriptors
+// (2026.10.01-e373342, 12/10/2026): 1 text_delta, 2 tool_call_started,
+// 3 tool_call_completed, 4 thinking_delta, 14 turn_ended. The previous mapping
+// (thinking 1, text 2, turn_ended 3) read tool_call_started as the model's text,
+// which is why a Cursor tool call reached Claude Code as the literal string
+// "call_...\nfc_..." instead of a tool_use block.
#[derive(Clone, PartialEq, Message)]
pub struct InteractionUpdate {
#[prost(message, optional, tag = "1")]
- pub thinking_delta: Option<ThinkingDelta>,
- #[prost(message, optional, tag = "2")]
pub text_delta: Option<TextDelta>,
- #[prost(message, optional, tag = "3")]
+ #[prost(message, optional, tag = "4")]
+ pub thinking_delta: Option<ThinkingDelta>,
+ #[prost(message, optional, tag = "14")]
pub turn_ended: Option<TurnEnded>,
}
@@ -179,8 +185,53 @@ pub struct TurnEnded {
pub cache_write_tokens: u64,
}
+// The frame in which Cursor asks the CLIENT to run a tool. Field numbers from
+// the same descriptors: 1 id, 2 shell_args, 3 write_args, 7 read_args,
+// 14 shell_stream_args, 15 exec_id. Measured live 12/10/2026: a Read arrives as
+// read_args{path, tool_call_id} and a Bash as shell_stream_args with the same
+// ShellArgs shape.
#[derive(Clone, PartialEq, Message)]
pub struct ExecServerMessage {
- #[prost(string, optional, tag = "1")]
- pub notes_session_id: Option<String>,
+ #[prost(uint64, optional, tag = "1")]
+ pub id: Option<u64>,
+ #[prost(message, optional, tag = "2")]
+ pub shell_args: Option<ShellArgs>,
+ #[prost(message, optional, tag = "3")]
+ pub write_args: Option<WriteArgs>,
+ #[prost(message, optional, tag = "7")]
+ pub read_args: Option<ReadArgs>,
+ #[prost(message, optional, tag = "14")]
+ pub shell_stream_args: Option<ShellArgs>,
+ #[prost(string, optional, tag = "15")]
+ pub exec_id: Option<String>,
+}
+
+#[derive(Clone, PartialEq, Message)]
+pub struct ReadArgs {
+ #[prost(string, tag = "1")]
+ pub path: String,
+ #[prost(string, optional, tag = "2")]
+ pub tool_call_id: Option<String>,
+}
+
+#[derive(Clone, PartialEq, Message)]
+pub struct WriteArgs {
+ #[prost(string, tag = "1")]
+ pub path: String,
+ #[prost(string, tag = "2")]
+ pub file_text: String,
+ #[prost(string, optional, tag = "3")]
+ pub tool_call_id: Option<String>,
+}
+
+#[derive(Clone, PartialEq, Message)]
+pub struct ShellArgs {
+ #[prost(string, tag = "1")]
+ pub command: String,
+ #[prost(string, optional, tag = "2")]
+ pub working_directory: Option<String>,
+ #[prost(uint64, optional, tag = "3")]
+ pub timeout: Option<u64>,
+ #[prost(string, optional, tag = "4")]
+ pub tool_call_id: Option<String>,
}
diff --git a/src/providers/cursor/response.rs b/src/providers/cursor/response.rs
index c4067af..6c406d4 100644
--- a/src/providers/cursor/response.rs
+++ b/src/providers/cursor/response.rs
@@ -17,6 +17,9 @@ pub enum CursorStreamEvent {
TextDelta {
text: String,
},
+ /// A native exec request: Cursor asking the client to run Read, Write or a
+ /// shell command. Decoded from ExecServerMessage.
+ Exec(CursorExecRequest),
Usage {
input_tokens: u64,
output_tokens: u64,
@@ -26,6 +29,30 @@ pub enum CursorStreamEvent {
End,
}
+/// A tool the Cursor upstream wants the client to execute.
+#[derive(Debug, Clone, PartialEq)]
+pub struct CursorExecRequest {
+ pub exec_id: Option<String>,
+ pub tool_call_id: Option<String>,
+ pub kind: CursorExecKind,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum CursorExecKind {
+ Read {
+ path: String,
+ },
+ Write {
+ path: String,
+ content: String,
+ },
+ Shell {
+ command: String,
+ working_directory: Option<String>,
+ timeout_ms: Option<u64>,
+ },
+}
+
#[derive(Debug, Clone)]
pub enum CursorDecodeError {
ConnectEnd(ConnectEndError),
@@ -279,14 +306,40 @@ fn events_from_current_payload(payload: &[u8], events: &mut Vec<CursorStreamEven
}
fn events_from_message(msg: &AgentServerMessage, events: &mut Vec<CursorStreamEvent>) {
- // Check for exec_server_message with session info
- if let Some(ref exec) = msg.exec_server_message
- && let Some(ref session_id) = exec.notes_session_id
- && !session_id.is_empty()
- {
- events.push(CursorStreamEvent::Session {
- session_id: session_id.clone(),
- });
+ // Native exec request: Cursor asks the client to run the tool itself.
+ if let Some(ref exec) = msg.exec_server_message {
+ let read = exec.read_args.as_ref();
+ let write = exec.write_args.as_ref();
+ let shell = exec.shell_stream_args.as_ref().or(exec.shell_args.as_ref());
+
+ let kind = if let Some(read) = read {
+ Some(CursorExecKind::Read {
+ path: read.path.clone(),
+ })
+ } else if let Some(write) = write {
+ Some(CursorExecKind::Write {
+ path: write.path.clone(),
+ content: write.file_text.clone(),
+ })
+ } else {
+ shell.map(|shell| CursorExecKind::Shell {
+ command: shell.command.clone(),
+ working_directory: shell.working_directory.clone(),
+ timeout_ms: shell.timeout,
+ })
+ };
+
+ if let Some(kind) = kind {
+ let tool_call_id = read
+ .and_then(|r| r.tool_call_id.clone())
+ .or_else(|| write.and_then(|w| w.tool_call_id.clone()))
+ .or_else(|| shell.and_then(|s| s.tool_call_id.clone()));
+ events.push(CursorStreamEvent::Exec(CursorExecRequest {
+ exec_id: exec.exec_id.clone(),
+ tool_call_id,
+ kind,
+ }));
+ }
}
if let Some(ref update) = msg.interaction_update {
@@ -366,27 +419,46 @@ mod tests {
}
}
+ // The frame a Cursor Read tool call actually arrives in, built with the
+ // field numbers measured from the live upstream on 2026-10-12: tag 2 is the
+ // exec server message, tag 7 inside it is read_args, tag 1 of read_args is
+ // the path and tag 2 is Cursor's own tool_call_id.
#[test]
- fn decodes_session_event() {
- let msg = AgentServerMessage {
- interaction_update: None,
- exec_server_message: Some(ExecServerMessage {
- notes_session_id: Some("session-123".to_string()),
- }),
- };
- let mut payload = Vec::new();
- msg.encode(&mut payload).unwrap();
- let body = encode_connect_frame(&payload, 0).to_vec();
+ fn decodes_native_read_exec() {
+ let body = test_frames::native_read_exec_frame("/etc/hostname", "tool_abc", "exec-1");
let events = decode_upstream_response(&body).unwrap();
assert_eq!(events.len(), 1);
- if let CursorStreamEvent::Session { session_id } = &events[0] {
- assert_eq!(session_id, "session-123");
- } else {
- panic!("expected Session");
+ match &events[0] {
+ CursorStreamEvent::Exec(exec) => {
+ assert_eq!(exec.exec_id.as_deref(), Some("exec-1"));
+ assert_eq!(exec.tool_call_id.as_deref(), Some("tool_abc"));
+ assert_eq!(
+ exec.kind,
+ CursorExecKind::Read {
+ path: "/etc/hostname".to_string()
+ }
+ );
+ }
+ other => panic!("expected Exec, got {other:?}"),
}
}
+ /// A model tool call must never reach Claude Code as the model's prose: the
+ /// shipped mapping read tool_call_started (tag 2) as if it were text_delta.
+ #[test]
+ fn tool_call_started_is_not_text() {
+ let body = test_frames::tool_call_started_frame("call_abc\nfc_123");
+
+ let events = decode_upstream_response(&body).unwrap();
+ assert!(
+ !events
+ .iter()
+ .any(|event| matches!(event, CursorStreamEvent::TextDelta { .. })),
+ "tool_call_started leaked into the text channel: {events:?}"
+ );
+ }
+
#[test]
fn accumulate_response_produces_anthropic_json() {
let mut body = Vec::new();
diff --git a/src/providers/cursor/sse.rs b/src/providers/cursor/sse.rs
index 681b1ff..84b15a2 100644
--- a/src/providers/cursor/sse.rs
+++ b/src/providers/cursor/sse.rs
@@ -43,6 +43,11 @@ pub fn frame_cursor_stream(
CursorStreamEvent::TextDelta { text } => {
framer.emit_text_delta(text);
}
+ CursorStreamEvent::Exec(_) => {
+ // Without an advertised Claude tool and a session id the proxy
+ // cannot hand this exec to the client, and the upstream never
+ // emitted it as text. Dropping it is the honest outcome.
+ }
CursorStreamEvent::Usage {
input_tokens,
output_tokens,
diff --git a/src/providers/cursor/test_frames.rs b/src/providers/cursor/test_frames.rs
index 1a75368..672cb90 100644
--- a/src/providers/cursor/test_frames.rs
+++ b/src/providers/cursor/test_frames.rs
@@ -53,6 +53,27 @@ pub(crate) fn usage_frame_full(
interaction_frame(14, &usage)
}
+/// The frame a Cursor Read tool call arrives in: AgentServerMessage tag 2
+/// (exec_server_message) -> read_args (tag 7) -> path (tag 1), tool_call_id
+/// (tag 2), with exec_id at tag 15. Field numbers measured from the live
+/// upstream 2026-10-12.
+pub(crate) fn native_read_exec_frame(path: &str, tool_call_id: &str, exec_id: &str) -> Vec<u8> {
+ let mut read_args = bytes_field(1, path.as_bytes());
+ read_args.extend(bytes_field(2, tool_call_id.as_bytes()));
+ let mut exec = varint_field(1, 1);
+ exec.extend(bytes_field(7, &read_args));
+ exec.extend(bytes_field(15, exec_id.as_bytes()));
+ encode_connect_frame(bytes_field(2, &exec), 0).to_vec()
+}
+
+/// InteractionUpdate tool_call_started (tag 2). The old proto mapping read this
+/// as text_delta and sent Cursor's tool call to Claude Code as prose.
+pub(crate) fn tool_call_started_frame(tool_call_id: &str) -> Vec<u8> {
+ let mut started = bytes_field(1, tool_call_id.as_bytes());
+ started.extend(bytes_field(3, b"be193bcf-0000-0000-0000-000000000000-0-aho4"));
+ interaction_frame(2, &started)
+}
+
pub(crate) fn end_frame() -> Vec<u8> {
encode_connect_frame(b"", 2).to_vec()
}
diff --git a/src/providers/cursor/tool_bridge.rs b/src/providers/cursor/tool_bridge.rs
index 3c740ad..5e56262 100644
--- a/src/providers/cursor/tool_bridge.rs
+++ b/src/providers/cursor/tool_bridge.rs
@@ -13,7 +13,7 @@ use std::sync::Mutex;
use once_cell::sync::Lazy;
use crate::anthropic::schema::MessagesRequest;
-use crate::providers::cursor::response::CursorStreamEvent;
+use crate::providers::cursor::response::{CursorExecKind, CursorExecRequest, CursorStreamEvent};
use crate::providers::cursor::sse::CursorSseFramer;
use crate::providers::cursor::tool_use_xml::{CursorToolUseXmlParser, RecoveredCursorEvent};
@@ -503,6 +503,33 @@ pub fn build_shell_stream_result(
messages
}
+// ---------------------------------------------------------------------------
+// Native exec mapping
+// ---------------------------------------------------------------------------
+
+/// Map a Cursor native exec request onto the Claude tool call that fulfils it.
+///
+/// Cursor asks the client to run its own tools (ExecServerMessage). The three
+/// Claude Code can answer are Read, Write and Bash. `working_directory` is
+/// dropped on purpose: Claude Code already runs Bash in the session's project
+/// directory, and its Bash input has no cwd field.
+pub fn claude_tool_for_exec(exec: &CursorExecRequest) -> Option<(&'static str, serde_json::Value)> {
+ match &exec.kind {
+ CursorExecKind::Read { path } => Some((
+ "Read",
+ serde_json::json!({ "file_path": path }),
+ )),
+ CursorExecKind::Write { path, content } => Some((
+ "Write",
+ serde_json::json!({ "file_path": path, "content": content }),
+ )),
+ CursorExecKind::Shell { command, .. } => Some((
+ "Bash",
+ serde_json::json!({ "command": command }),
+ )),
+ }
+}
+
// ---------------------------------------------------------------------------
// Bridge start and resume
// ---------------------------------------------------------------------------
@@ -574,6 +601,28 @@ pub fn start_cursor_tool_bridge(
}
}
}
+ CursorStreamEvent::Exec(exec) => {
+ // Cursor asked the client to run one of its own tools. Emit the
+ // equivalent Claude tool_use and stop: Claude Code runs it and
+ // its tool_result travels back in the NEXT request, where
+ // render_cursor_prompt turns it into a <tool_result> block for
+ // the upstream. No pending tool is stored, precisely so that
+ // next request reaches Cursor instead of being answered from
+ // stored events.
+ let bridged = claude_tool_for_exec(exec).filter(|(name, _)| {
+ state
+ .allowed_tool_names
+ .as_ref()
+ .map_or(true, |allowed| allowed.contains(*name))
+ });
+ if let Some((name, input)) = bridged {
+ let tool_use_id = format!("toolu_{}", uuid::Uuid::new_v4().simple());
+ let input_json =
+ serde_json::to_string(&input).unwrap_or_else(|_| "{}".to_string());
+ framer.emit_tool_pause(&tool_use_id, name, &input_json);
+ paused = true;
+ }
+ }
CursorStreamEvent::Usage {
input_tokens,
output_tokens,
@@ -738,6 +787,11 @@ pub fn resume_cursor_tool_bridge(
}
}
}
+ CursorStreamEvent::Exec(_) => {
+ // Native exec requests are handled when the bridge starts;
+ // a buffered tail carrying one is dropped rather than
+ // replayed, because its tool call was already emitted.
+ }
CursorStreamEvent::Usage {
input_tokens,
output_tokens,