feat(gateway): resolve FeatureSets from an explicit per-call workspace root

Add a non-mutating resolve_for_workspace_root path so Cursor preToolUse
context can pick a binding without writing session or window pins.

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

Author: crimsonsunset

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

@@ -0,0 +1,76 @@
+//! Per-call `_mcpmux_context` attached by Cursor's `preToolUse` hook.
+//!
+//! The reserved argument is transport metadata: parse it, validate the root,
+//! then strip it before meta-tool parsing or backend forwarding.
+
+use rmcp::model::JsonObject;
+use serde_json::Value;
+
+use crate::services::SessionRootsRegistry;
+use mcpmux_core::normalize_workspace_root;
+
+/// Reserved tool-argument key injected by the managed Cursor hook.
+pub const MCPMUX_CONTEXT_KEY: &str = "_mcpmux_context";
+
+/// Exact workspace identity carried on one `tools/call`.
+#[derive(Debug, Clone)]
+pub struct ExtractedCallContext {
+    pub workspace_root: String,
+    pub tool_use_id: Option<String>,
+}
+
+/// Remove `_mcpmux_context` from `arguments` and validate it when present.
+///
+/// `Ok(None)` means the call has no hook context and should use the session
+/// ladder. Malformed objects and candidate-set mismatches are errors.
+pub fn take_mcpmux_context(
+    arguments: &mut JsonObject,
+    session_id: Option<&str>,
+    session_roots: &SessionRootsRegistry,
+) -> Result<Option<ExtractedCallContext>, String> {
+    let Some(raw) = arguments.remove(MCPMUX_CONTEXT_KEY) else {
+        return Ok(None);
+    };
+
+    let obj = match raw {
+        Value::Object(obj) => obj,
+        _ => {
+            return Err("invalid _mcpmux_context: expected an object".into());
+        }
+    };
+
+    let raw_root = obj
+        .get("workspace_root")
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| {
+            "invalid _mcpmux_context: workspace_root must be a non-empty string".to_string()
+        })?;
+
+    let workspace_root = normalize_workspace_root(raw_root);
+    if workspace_root.is_empty() {
+        return Err("invalid _mcpmux_context: workspace_root is empty after normalize".into());
+    }
+
+    if let Some(sid) = session_id {
+        if !session_roots.is_candidate(sid, &workspace_root) {
+            return Err(
+                "invalid _mcpmux_context: workspace_root is not in this session's candidate set"
+                    .into(),
+            );
+        }
+    }
+
+    let tool_use_id = obj
+        .get("tool_use_id")
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(str::to_string);
+
+    Ok(Some(ExtractedCallContext {
+        workspace_root,
+        tool_use_id,
+    }))
+}

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

@@ -11,6 +11,7 @@
 
 pub mod context;
 pub mod handler;
+pub mod mcpmux_context;
 pub mod oauth_middleware;
 
 pub use handler::McpMuxGatewayHandler;

crates/mcpmux-gateway/src/services/authorization.rs

@@ -54,6 +54,18 @@ impl AuthorizationService {
             .await
     }
 
+    /// Per-call explicit-root resolution. Does not read or write session pins.
+    pub async fn resolve_for_workspace_root(
+        &self,
+        workspace_root: &str,
+        client_id: Option<&str>,
+        request_machine_id: Option<Uuid>,
+    ) -> Result<ResolvedFeatureSet> {
+        self.resolver
+            .resolve_for_workspace_root(workspace_root, client_id, request_machine_id)
+            .await
+    }
+
     /// Does this session/client resolve to any FeatureSet?
     pub async fn has_access(
         &self,

crates/mcpmux-gateway/src/services/feature_set_resolver.rs

@@ -795,4 +795,70 @@ impl FeatureSetResolverService {
         );
         Ok(self.unbound(deny_space_id))
     }
+
+    /// Resolve from an explicit per-call workspace root without reading or
+    /// writing [`SessionRootsRegistry`]. Used when Cursor's `preToolUse` hook
+    /// attaches `_mcpmux_context` to this exact `tools/call`.
+    pub async fn resolve_for_workspace_root(
+        &self,
+        workspace_root: &str,
+        client_id: Option<&str>,
+        request_machine_id: Option<Uuid>,
+    ) -> Result<ResolvedFeatureSet> {
+        let default_space_id = match self.space_repo.get_default().await? {
+            Some(s) => s.id,
+            None => {
+                warn!("[FeatureSetResolver] no default space — deny");
+                return Ok(ResolvedFeatureSet {
+                    feature_set_ids: vec![],
+                    space_id: None,
+                    source: ResolutionSource::Deny,
+                });
+            }
+        };
+        let space_lock = match client_id {
+            Some(cid) => self.client_repo.get_locked_space(cid).await?,
+            None => None,
+        };
+        let deny_space_id = Self::unbound_space_id(space_lock, default_space_id);
+        let reported_roots = [workspace_root.to_string()];
+
+        if let Some(binding) = self
+            .find_binding_for_roots(&reported_roots, client_id, request_machine_id)
+            .await?
+        {
+            if Self::binding_matches_space_lock(&binding, space_lock) {
+                debug!(
+                    workspace_root = %binding.workspace_root,
+                    space_id = %binding.space_id,
+                    feature_sets = ?binding.feature_set_ids,
+                    "[FeatureSetResolver] resolved via explicit workspace_root",
+                );
+                return Ok(ResolvedFeatureSet {
+                    feature_set_ids: binding.feature_set_ids,
+                    space_id: Some(binding.space_id),
+                    source: ResolutionSource::WorkspaceBinding,
+                });
+            }
+            debug!(
+                binding_space = %binding.space_id,
+                ?space_lock,
+                "[FeatureSetResolver] explicit-root binding outside locked Space — ignored",
+            );
+        }
+
+        let target_space = if space_lock.is_some() {
+            deny_space_id
+        } else {
+            self.space_for_roots(&reported_roots)
+                .await?
+                .unwrap_or(default_space_id)
+        };
+        debug!(
+            %target_space,
+            workspace_root,
+            "[FeatureSetResolver] explicit workspace_root but no binding matched — Unbound",
+        );
+        Ok(self.unbound(target_space))
+    }
 }