feat(gateway): honor _mcpmux_context on call_tool and meta tools

Strip and validate the reserved hook argument, route that call from the
exact root, and thread it through MetaToolCall so bind and search stay
on the same binding.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>

Author: crimsonsunset

crates/mcpmux-gateway/src/mcp/handler.rs

@@ -230,6 +230,32 @@ impl McpMuxGatewayHandler {
         Ok((space_id, resolved.feature_set_ids))
     }
 
+    /// `call_tool` routing: a valid `_mcpmux_context.workspace_root` wins
+    /// for this invocation only. List handlers keep using [`Self::resolve_routing`].
+    async fn resolve_call_routing(
+        &self,
+        session_id: Option<&str>,
+        client_id: &str,
+        request_machine_id: Option<uuid::Uuid>,
+        explicit_root: Option<&str>,
+    ) -> Result<(uuid::Uuid, Vec<String>), McpError> {
+        let Some(root) = explicit_root else {
+            return self
+                .resolve_routing(session_id, client_id, request_machine_id)
+                .await;
+        };
+        let resolved = self
+            .services
+            .authorization_service
+            .resolve_for_workspace_root(root, Some(client_id), request_machine_id)
+            .await
+            .map_err(|e| McpError::internal_error(format!("Failed to resolve: {e}"), None))?;
+        let space_id = resolved.space_id.ok_or_else(|| {
+            McpError::internal_error("No space resolved (no default space configured)", None)
+        })?;
+        Ok((space_id, resolved.feature_set_ids))
+    }
+
     /// On-demand `roots/list` probe for sessions that initialized as
     /// roots-capable but have no roots yet — typically because the first
     /// `list_roots()` from `on_initialized` raced this request, or its
@@ -824,7 +850,7 @@ impl ServerHandler for McpMuxGatewayHandler {
 
     async fn call_tool(
         &self,
-        params: CallToolRequestParams,
+        mut params: CallToolRequestParams,
         context: RequestContext<RoleServer>,
     ) -> Result<CallToolResult, McpError> {
         let oauth_ctx = self
@@ -841,6 +867,23 @@ impl ServerHandler for McpMuxGatewayHandler {
         let session_id_owned = extract_session_id(&context.extensions);
         let session_id = session_id_owned.as_deref();
 
+        let mut arguments = params.arguments.take().unwrap_or_default();
+        let call_ctx = super::mcpmux_context::take_mcpmux_context(
+            &mut arguments,
+            session_id,
+            &self.services.session_roots,
+        )
+        .map_err(|e| McpError::invalid_params(e, None))?;
+        if let Some(ctx) = &call_ctx {
+            info!(
+                workspace_root = %ctx.workspace_root,
+                tool_use_id = ctx.tool_use_id.as_deref().unwrap_or(""),
+                session_id = session_id.unwrap_or(""),
+                source = "cursor_pre_tool_use",
+                "call_tool exact workspace context"
+            );
+        }
+
         // Bridge the init race on the call side too: a tools/call can land
         // while a roots-capable session is still PendingRoots (client
         // resumed and immediately invoked a tool it listed on a previous
@@ -859,10 +902,11 @@ impl ServerHandler for McpMuxGatewayHandler {
         // (may differ from oauth_ctx.space_id). Needed both to gate the
         // per-Space meta tools below and to route a normal tool call.
         let (space_id, feature_set_ids) = self
-            .resolve_routing(
+            .resolve_call_routing(
                 session_id,
                 &oauth_ctx.client_id,
                 oauth_ctx.request_machine_id,
+                call_ctx.as_ref().map(|c| c.workspace_root.as_str()),
             )
             .await?;
 
@@ -878,19 +922,16 @@ impl ServerHandler for McpMuxGatewayHandler {
             // Note: client_id is the OAuth client identity (a URL for DCR-
             // registered clients like Claude, a UUID for others). The meta-
             // tool registry treats it as an opaque string identity key.
-            let args: serde_json::Value = params
-                .arguments
-                .map(|a| serde_json::to_value(a).unwrap_or(serde_json::Value::Null))
-                .unwrap_or(serde_json::Value::Null);
             return match self
                 .services
                 .meta_tool_registry
                 .call_from_device(
                     &params.name,
                     &oauth_ctx.client_id,
                     session_id,
-                    args,
+                    serde_json::Value::Object(arguments),
                     oauth_ctx.request_machine_id,
+                    call_ctx.as_ref().map(|c| c.workspace_root.clone()),
                 )
                 .await
             {
@@ -1004,7 +1045,7 @@ impl ServerHandler for McpMuxGatewayHandler {
                 space_id,
                 &feature_set_ids,
                 &params.name,
-                serde_json::to_value(params.arguments.unwrap_or_default()).unwrap_or_default(),
+                serde_json::Value::Object(arguments),
             )
             .await
             .map_err(|e| McpError::internal_error(format!("Tool call failed: {}", e), None))?;

crates/mcpmux-gateway/src/services/meta_tools/bind_workspace.rs

@@ -133,60 +133,64 @@ impl MetaTool for BindCurrentWorkspaceTool {
             .session_id
             .and_then(|sid| call.ctx.session_roots.get(sid))
             .unwrap_or_default();
-        // Same gate as FeatureSetResolver PendingRoots: never first-root-wins
-        // when multiple unpinned roots are present (header pin collapses get() to 1).
-        let root = match roots.as_slice() {
-            [] => {
-                // The window's folder set (X-Mcpmux-Workspace-Set) usually
-                // survives even when the active-folder header came through
-                // empty, so name those folders rather than making the caller
-                // guess what to declare.
-                let candidates = call
-                    .session_id
-                    .and_then(|sid| call.ctx.session_roots.get_candidates(sid))
-                    .unwrap_or_default();
-                let known = if candidates.is_empty() {
-                    String::new()
-                } else {
-                    format!(
-                        " This window has these folders open:\n{}\n",
-                        candidates
-                            .iter()
-                            .map(|c| format!("  - {c}"))
-                            .collect::<Vec<_>>()
-                            .join("\n")
-                    )
-                };
-                return Err(MetaToolError::InvalidArgument(format!(
-                    "caller did not report any MCP roots; cannot bind.{known} \
+        // Exact call context (Cursor preToolUse) names the bind target even
+        // when the shared session still reports multiple unpinned roots.
+        let root = if let Some(explicit) = call.explicit_workspace_root.as_deref() {
+            explicit.to_string()
+        } else {
+            match roots.as_slice() {
+                [] => {
+                    // The window's folder set (X-Mcpmux-Workspace-Set) usually
+                    // survives even when the active-folder header came through
+                    // empty, so name those folders rather than making the caller
+                    // guess what to declare.
+                    let candidates = call
+                        .session_id
+                        .and_then(|sid| call.ctx.session_roots.get_candidates(sid))
+                        .unwrap_or_default();
+                    let known = if candidates.is_empty() {
+                        String::new()
+                    } else {
+                        format!(
+                            " This window has these folders open:\n{}\n",
+                            candidates
+                                .iter()
+                                .map(|c| format!("  - {c}"))
+                                .collect::<Vec<_>>()
+                                .join("\n")
+                        )
+                    };
+                    return Err(MetaToolError::InvalidArgument(format!(
+                        "caller did not report any MCP roots; cannot bind.{known} \
                      Call mcpmux_set_workspace_root to declare the workspace this agent is \
                      actually working in, then retry mcpmux_bind_current_workspace."
-                )));
-            }
-            [single] => single.clone(),
-            many => {
-                info!(
-                    session_id = ?call.session_id,
-                    client_id = %call.client_id,
-                    root_count = many.len(),
-                    reported_roots = ?many,
-                    feature_set_id = %fs_id,
-                    "[meta_tools] bind_current_workspace refused — multiple unpinned roots"
-                );
-                let listed = many
-                    .iter()
-                    .map(|r| format!("  - {r}"))
-                    .collect::<Vec<_>>()
-                    .join("\n");
-                return Err(MetaToolError::InvalidArgument(format!(
-                    "cannot bind: {} workspace roots reported and none is pinned, so which \
+                    )));
+                }
+                [single] => single.clone(),
+                many => {
+                    info!(
+                        session_id = ?call.session_id,
+                        client_id = %call.client_id,
+                        root_count = many.len(),
+                        reported_roots = ?many,
+                        feature_set_id = %fs_id,
+                        "[meta_tools] bind_current_workspace refused — multiple unpinned roots"
+                    );
+                    let listed = many
+                        .iter()
+                        .map(|r| format!("  - {r}"))
+                        .collect::<Vec<_>>()
+                        .join("\n");
+                    return Err(MetaToolError::InvalidArgument(format!(
+                        "cannot bind: {} workspace roots reported and none is pinned, so which \
                      folder to mutate is ambiguous. Reported roots:\n{listed}\n\
                      Call mcpmux_set_workspace_root with exactly one of those paths (the \
                      workspace this agent is actually working in), then retry \
                      mcpmux_bind_current_workspace with the same feature_set_id. A correct \
                      X-Mcpmux-Workspace header pin also collapses this.",
-                    many.len(),
-                )));
+                        many.len(),
+                    )));
+                }
             }
         };
         let normalized = normalize_workspace_root(&root);

crates/mcpmux-gateway/src/services/meta_tools/meta_tool_common.rs

@@ -55,15 +55,7 @@ pub(crate) fn text_result(v: Value) -> CallToolResult {
 /// workspace B just because both sit under the same default-Space-flagged
 /// row in the DB.
 pub(crate) async fn caller_space_id(call: &MetaToolCall<'_>) -> Result<Uuid, MetaToolError> {
-    let resolved = call
-        .ctx
-        .resolver
-        .resolve(
-            call.session_id,
-            Some(call.client_id),
-            call.request_machine_id,
-        )
-        .await?;
+    let resolved = caller_resolution(call).await?;
     if let Some(space_id) = resolved.space_id {
         return Ok(space_id);
     }
@@ -75,9 +67,18 @@ pub(crate) async fn caller_space_id(call: &MetaToolCall<'_>) -> Result<Uuid, Met
 }
 
 /// Full resolver output for the caller — space + binding FS ids + source.
+/// Prefers an exact `_mcpmux_context` root when the handler attached one.
 pub(crate) async fn caller_resolution(
     call: &MetaToolCall<'_>,
 ) -> Result<ResolvedFeatureSet, MetaToolError> {
+    if let Some(root) = call.explicit_workspace_root.as_deref() {
+        return call
+            .ctx
+            .resolver
+            .resolve_for_workspace_root(root, Some(call.client_id), call.request_machine_id)
+            .await
+            .map_err(|e| MetaToolError::Internal(e.to_string()));
+    }
     call.ctx
         .resolver
         .resolve(

crates/mcpmux-gateway/src/services/meta_tools/registry.rs

@@ -109,6 +109,9 @@ pub struct MetaToolCall<'a> {
     /// header, when the transport carries one. `None` for local/stdio
     /// callers and for tests that don't exercise per-device routing.
     pub request_machine_id: Option<Uuid>,
+    /// Exact workspace root from `_mcpmux_context` on this call, if any.
+    /// Never written into session/window pin maps.
+    pub explicit_workspace_root: Option<String>,
 }
 
 /// Errors a meta tool can surface that map cleanly to `CallToolResult::error`.
@@ -285,7 +288,7 @@ impl MetaToolRegistry {
         session_id: Option<&str>,
         args: Value,
     ) -> Result<CallToolResult, MetaToolError> {
-        self.call_from_device(name, client_id, session_id, args, None)
+        self.call_from_device(name, client_id, session_id, args, None, None)
             .await
     }
 
@@ -300,6 +303,7 @@ impl MetaToolRegistry {
         session_id: Option<&str>,
         args: Value,
         request_machine_id: Option<Uuid>,
+        explicit_workspace_root: Option<String>,
     ) -> Result<CallToolResult, MetaToolError> {
         let tool = self
             .tools
@@ -314,6 +318,7 @@ impl MetaToolRegistry {
             ctx: &self.ctx,
             audit_decision: audit_decision.clone(),
             request_machine_id,
+            explicit_workspace_root,
         };
         let result = tool.call(call).await;
 

tests/rust/tests/integration/meta_tools.rs

@@ -1921,6 +1921,7 @@ async fn bind_current_workspace_header_targets_caller_machine_not_gateway_local(
             Some(&f.session_id),
             json!({ "feature_set_id": f.fs_android_id.to_string() }),
             Some(rohan_id),
+            None,
         )
         .await
         .unwrap();