refactor(workspace): pluggable backend abstraction + 16 optimizations

Introduces a workspace capability abstraction so built-in tools (read,
write, edit, patch, ls, bash, grep, glob, git, git_stash, git_worktree)
route through trait-based providers instead of hard-coded local
filesystem calls. The default LocalWorkspaceBackend preserves existing
behavior; future remote/browser/DFS/container backends can plug in via
WorkspaceServicesBuilder without changing tool schemas.

Key changes:

- Split workspace.rs into workspace/{mod.rs, local.rs}: trait definitions
  + LocalWorkspaceBackend in separate files (CLAUDE.md file-size rule).
- New traits: WorkspaceFileSystem, WorkspaceCommandRunner, WorkspaceSearch,
  WorkspaceGit (slim core) + optional WorkspaceGitStashProvider and
  WorkspaceGitWorktreeProvider, CommandOutputObserver.
- WorkspaceServices: assembled via WorkspaceServicesBuilder; auto-downgrades
  capabilities when matching providers are missing; carries an optional
  per-operation timeout enforced by run_with_timeout helper.
- Capability gating: register_builtins(registry, &capabilities) only
  registers tools whose required capability is provided — bash, grep,
  glob, git can be hidden from the model when the backend lacks them.
- Local backend now implements WorkspaceCommandRunner (no more
  bash-specific local fallback in the tool).
- CommandRequest carries Arc<dyn CommandOutputObserver> instead of leaking
  ToolEventSender into the abstraction.
- ChildRunContext propagates workspace_services to child runs.
- New Session direct-tool APIs: write_file, ls, edit_file, patch_file.
- WorkspaceFileSystemExt policy: future trait extensions go to a
  separate extension trait (additive only).
- Removed dead WorkspaceCapabilities flags (watch, atomic_write),
  unreachable bash fallback branch, set_workspace_services mutation
  hazard, redundant ToolExecutor private constructors.
- Deprecated ToolContext::resolve_path / resolve_path_for_write under
  non-local backends.

Tests:
- 17 new unit + integration tests in workspace + tools modules.
- All 1553 lib tests + integration tests pass.
- cargo clippy --all-targets --all-features -D warnings clean.

Author: claude

core/src/agent_api.rs

@@ -175,6 +175,13 @@ pub struct SessionOptions {
     /// of `std::process::Command`. The host application constructs and owns
     /// the implementation (e.g., an A3S Box–backed handle).
     pub sandbox_handle: Option<Arc<dyn crate::sandbox::BashSandbox>>,
+    /// Optional host-provided workspace backend.
+    ///
+    /// When set, built-in tools such as `read`, `write`, `ls`, and `bash`
+    /// execute against these workspace capabilities instead of assuming the
+    /// server-local filesystem. This is the primary extension point for DFS,
+    /// browser, container, and remote workspace deployments.
+    pub workspace_services: Option<Arc<crate::workspace::WorkspaceServices>>,
     /// Enable auto-compaction when context usage exceeds threshold.
     pub auto_compact: bool,
     /// Context usage percentage threshold for auto-compaction (0.0 - 1.0).
@@ -691,6 +698,38 @@ impl AgentSession {
         DirectToolRuntime::from_session(self).read_file(path).await
     }
 
+    /// Write a file in the workspace.
+    pub async fn write_file(&self, path: &str, content: &str) -> Result<ToolCallResult> {
+        DirectToolRuntime::from_session(self)
+            .write_file(path, content)
+            .await
+    }
+
+    /// List a directory in the workspace.
+    pub async fn ls(&self, path: Option<&str>) -> Result<ToolCallResult> {
+        DirectToolRuntime::from_session(self).ls(path).await
+    }
+
+    /// Edit a file by replacing text in the workspace.
+    pub async fn edit_file(
+        &self,
+        path: &str,
+        old_string: &str,
+        new_string: &str,
+        replace_all: bool,
+    ) -> Result<ToolCallResult> {
+        DirectToolRuntime::from_session(self)
+            .edit_file(path, old_string, new_string, replace_all)
+            .await
+    }
+
+    /// Apply a unified diff patch to a workspace file.
+    pub async fn patch_file(&self, path: &str, diff: &str) -> Result<ToolCallResult> {
+        DirectToolRuntime::from_session(self)
+            .patch_file(path, diff)
+            .await
+    }
+
     /// Execute a bash command in the workspace.
     ///
     /// When a sandbox handle is configured via

core/src/agent_api/capabilities.rs

@@ -39,10 +39,18 @@ pub(super) struct SessionCapabilities {
 
 pub(super) fn build_session_capabilities(input: SessionCapabilityInput<'_>) -> SessionCapabilities {
     let artifact_limits = input.opts.artifact_store_limits.unwrap_or_default();
-    let tool_executor = Arc::new(ToolExecutor::new_with_artifact_limits(
-        input.workspace.display().to_string(),
-        artifact_limits,
-    ));
+    let workspace_services = input
+        .opts
+        .workspace_services
+        .clone()
+        .unwrap_or_else(|| crate::workspace::WorkspaceServices::local(input.workspace));
+    let tool_executor = Arc::new(
+        ToolExecutor::new_with_workspace_services_and_artifact_limits(
+            input.workspace.display().to_string(),
+            workspace_services,
+            artifact_limits,
+        ),
+    );
     let trace_sink = crate::trace::InMemoryTraceSink::default();
     tool_executor.set_trace_sink(Arc::new(trace_sink.clone()));
 
@@ -151,6 +159,7 @@ fn register_task_capability(
         max_execution_time_ms: opts.max_execution_time_ms,
         circuit_breaker_threshold: opts.circuit_breaker_threshold,
         confirmation_manager: opts.confirmation_manager.clone(),
+        workspace_services: opts.workspace_services.clone(),
     };
 
     let registry = Arc::new(registry);

core/src/agent_api/direct_tools.rs

@@ -45,6 +45,40 @@ impl DirectToolRuntime {
         Ok(result.output)
     }
 
+    pub(super) async fn write_file(&self, path: &str, content: &str) -> Result<ToolCallResult> {
+        let args = serde_json::json!({ "file_path": path, "content": content });
+        self.call("write", args).await
+    }
+
+    pub(super) async fn ls(&self, path: Option<&str>) -> Result<ToolCallResult> {
+        let args = match path {
+            Some(path) => serde_json::json!({ "path": path }),
+            None => serde_json::json!({}),
+        };
+        self.call("ls", args).await
+    }
+
+    pub(super) async fn edit_file(
+        &self,
+        path: &str,
+        old_string: &str,
+        new_string: &str,
+        replace_all: bool,
+    ) -> Result<ToolCallResult> {
+        let args = serde_json::json!({
+            "file_path": path,
+            "old_string": old_string,
+            "new_string": new_string,
+            "replace_all": replace_all,
+        });
+        self.call("edit", args).await
+    }
+
+    pub(super) async fn patch_file(&self, path: &str, diff: &str) -> Result<ToolCallResult> {
+        let args = serde_json::json!({ "file_path": path, "diff": diff });
+        self.call("patch", args).await
+    }
+
     pub(super) async fn bash(&self, command: &str) -> Result<String> {
         let args = serde_json::json!({ "command": command });
         let result = self

core/src/agent_api/session_options.rs

@@ -43,6 +43,7 @@ impl std::fmt::Debug for SessionOptions {
             .field("tool_timeout_ms", &self.tool_timeout_ms)
             .field("circuit_breaker_threshold", &self.circuit_breaker_threshold)
             .field("sandbox_handle", &self.sandbox_handle.is_some())
+            .field("workspace_services", &self.workspace_services.is_some())
             .field("auto_compact", &self.auto_compact)
             .field("auto_compact_threshold", &self.auto_compact_threshold)
             .field("continuation_enabled", &self.continuation_enabled)
@@ -335,6 +336,19 @@ impl SessionOptions {
         self
     }
 
+    /// Provide a workspace backend for this session.
+    ///
+    /// Built-in tools keep their stable names and schemas, while their backing
+    /// implementation can target a DFS, browser workspace, remote runner, or
+    /// any other host-provided backend.
+    pub fn with_workspace_backend(
+        mut self,
+        services: Arc<crate::workspace::WorkspaceServices>,
+    ) -> Self {
+        self.workspace_services = Some(services);
+        self
+    }
+
     /// Enable auto-compaction when context usage exceeds threshold.
     ///
     /// When enabled, the agent loop automatically prunes large tool outputs

core/src/agent_api/session_runtime.rs

@@ -105,12 +105,12 @@ fn build_command_queue(
 
 fn build_tool_context(
     code_config: &CodeConfig,
-    workspace: &Path,
+    _workspace: &Path,
     opts: &SessionOptions,
     tool_executor: Arc<ToolExecutor>,
     agent_event_tx: broadcast::Sender<AgentEvent>,
 ) -> ToolContext {
-    let mut tool_context = ToolContext::new(workspace.to_path_buf());
+    let mut tool_context = tool_executor.registry().context();
     if let Some(ref search_config) = code_config.search {
         tool_context = tool_context.with_search_config(search_config.clone());
     }

core/src/agent_api/tests.rs

@@ -53,6 +53,98 @@ struct CapturingContextProvider {
     session_ids: std::sync::Mutex<Vec<Option<String>>>,
 }
 
+#[derive(Default)]
+struct TestWorkspaceFs {
+    files: std::sync::RwLock<std::collections::HashMap<String, String>>,
+}
+
+impl TestWorkspaceFs {
+    fn insert(&self, path: &str, content: &str) {
+        self.files
+            .write()
+            .unwrap()
+            .insert(path.to_string(), content.to_string());
+    }
+
+    fn read_raw(&self, path: &str) -> Option<String> {
+        self.files.read().unwrap().get(path).cloned()
+    }
+}
+
+#[async_trait::async_trait]
+impl crate::workspace::WorkspaceFileSystem for TestWorkspaceFs {
+    async fn read_text(&self, path: &crate::workspace::WorkspacePath) -> anyhow::Result<String> {
+        self.files
+            .read()
+            .unwrap()
+            .get(path.as_str())
+            .cloned()
+            .ok_or_else(|| anyhow::anyhow!("missing test workspace file: {}", path.as_str()))
+    }
+
+    async fn write_text(
+        &self,
+        path: &crate::workspace::WorkspacePath,
+        content: &str,
+    ) -> anyhow::Result<crate::workspace::WorkspaceWriteOutcome> {
+        self.insert(path.as_str(), content);
+        Ok(crate::workspace::WorkspaceWriteOutcome {
+            bytes: content.len(),
+            lines: content.lines().count(),
+        })
+    }
+
+    async fn list_dir(
+        &self,
+        path: &crate::workspace::WorkspacePath,
+    ) -> anyhow::Result<Vec<crate::workspace::WorkspaceDirEntry>> {
+        let prefix = if path.is_root() {
+            String::new()
+        } else {
+            format!("{}/", path.as_str())
+        };
+        let files = self.files.read().unwrap();
+        let mut entries = Vec::new();
+
+        for (file_path, content) in files.iter() {
+            if !file_path.starts_with(&prefix) {
+                continue;
+            }
+            let remaining = &file_path[prefix.len()..];
+            if remaining.is_empty() || remaining.contains('/') {
+                continue;
+            }
+            entries.push(crate::workspace::WorkspaceDirEntry {
+                name: remaining.to_string(),
+                kind: crate::workspace::WorkspaceFileType::File,
+                size: content.len() as u64,
+            });
+        }
+
+        Ok(entries)
+    }
+}
+
+#[derive(Default)]
+struct TestWorkspaceRunner {
+    commands: std::sync::RwLock<Vec<String>>,
+}
+
+#[async_trait::async_trait]
+impl crate::workspace::WorkspaceCommandRunner for TestWorkspaceRunner {
+    async fn exec(
+        &self,
+        request: crate::workspace::CommandRequest,
+    ) -> anyhow::Result<crate::workspace::CommandOutput> {
+        self.commands.write().unwrap().push(request.command.clone());
+        Ok(crate::workspace::CommandOutput {
+            output: format!("session runner: {}\n", request.command),
+            exit_code: 0,
+            timed_out: false,
+        })
+    }
+}
+
 #[async_trait::async_trait]
 impl crate::context::ContextProvider for CapturingContextProvider {
     fn name(&self) -> &str {
@@ -250,6 +342,69 @@ async fn test_session_default() {
     assert!(debug.contains("AgentSession"));
 }
 
+#[tokio::test]
+async fn test_session_uses_workspace_backend_for_direct_tools() {
+    let fs = Arc::new(TestWorkspaceFs::default());
+    fs.insert("app.txt", "hello from backend\n");
+    let fs_backend: Arc<dyn crate::workspace::WorkspaceFileSystem> = fs.clone();
+    let runner = Arc::new(TestWorkspaceRunner::default());
+    let runner_backend: Arc<dyn crate::workspace::WorkspaceCommandRunner> = runner.clone();
+    let services = crate::workspace::WorkspaceServices::builder(
+        crate::workspace::WorkspaceRef::new("session-workspace", "session://workspace"),
+        fs_backend,
+    )
+    .command_runner(runner_backend)
+    .build();
+
+    let agent = Agent::from_config(test_config()).await.unwrap();
+    let session = agent
+        .session(
+            "/server/local-placeholder",
+            Some(SessionOptions::new().with_workspace_backend(services)),
+        )
+        .unwrap();
+
+    let tool_names = session.tool_names();
+    assert!(tool_names.contains(&"read".to_string()));
+    assert!(tool_names.contains(&"write".to_string()));
+    assert!(tool_names.contains(&"ls".to_string()));
+    assert!(tool_names.contains(&"bash".to_string()));
+    assert!(!tool_names.contains(&"grep".to_string()));
+    assert!(!tool_names.contains(&"glob".to_string()));
+    assert!(!tool_names.contains(&"git".to_string()));
+
+    let read = session.read_file("app.txt").await.unwrap();
+    assert!(read.contains("hello from backend"));
+
+    let write = session
+        .write_file("created.txt", "one\ntwo\n")
+        .await
+        .unwrap();
+    assert_eq!(write.exit_code, 0, "{}", write.output);
+    assert_eq!(fs.read_raw("created.txt").as_deref(), Some("one\ntwo\n"));
+
+    let listing = session.ls(None).await.unwrap();
+    assert_eq!(listing.exit_code, 0, "{}", listing.output);
+    assert!(listing.output.contains("created.txt"));
+
+    let edit = session
+        .edit_file("created.txt", "one", "uno", false)
+        .await
+        .unwrap();
+    assert_eq!(edit.exit_code, 0, "{}", edit.output);
+    assert_eq!(fs.read_raw("created.txt").as_deref(), Some("uno\ntwo\n"));
+
+    let patch = session
+        .patch_file("created.txt", "@@ -1,2 +1,2 @@\n uno\n-two\n+dos")
+        .await
+        .unwrap();
+    assert_eq!(patch.exit_code, 0, "{}", patch.output);
+    assert_eq!(fs.read_raw("created.txt").as_deref(), Some("uno\ndos\n"));
+
+    let bash = session.bash("pwd").await.unwrap();
+    assert_eq!(bash, "session runner: pwd\n");
+}
+
 #[tokio::test]
 async fn test_session_routes_agents_md_through_context_provider() {
     let temp_dir = tempfile::tempdir().unwrap();

core/src/child_run.rs

@@ -15,6 +15,7 @@
 //! | max_execution_time_ms   | Yes       | Prevents runaway child runs                    |
 //! | circuit_breaker_threshold | Yes     | LLM failure handling should be consistent      |
 //! | confirmation_manager    | Depends   | Governed by ConfirmationInheritance            |
+//! | workspace_services      | Yes       | Child tools must operate on the same workspace |
 //! | memory                  | No        | Child has isolated context                     |
 //! | queue_config            | No        | Child runs are synchronous within parent       |
 //! | planning_mode           | No        | Child tasks are pre-planned by parent          |
@@ -39,6 +40,7 @@ pub struct ChildRunContext {
     pub max_execution_time_ms: Option<u64>,
     pub circuit_breaker_threshold: Option<u32>,
     pub confirmation_manager: Option<Arc<dyn ConfirmationProvider>>,
+    pub workspace_services: Option<Arc<crate::workspace::WorkspaceServices>>,
 }
 
 impl ChildRunContext {

core/src/lib.rs

@@ -113,6 +113,7 @@ pub(crate) mod tool_confirmation;
 pub mod tools;
 pub mod trace;
 pub mod verification;
+pub mod workspace;
 
 // Re-export key types at crate root for ergonomic usage
 pub use agent::{AgentEvent, AgentResult};
@@ -133,3 +134,16 @@ pub use subagent::{
     AgentDefinition, AgentRegistry, CattleAgentKind, CattleAgentSpec, ConfirmationInheritance,
     WorkerAgentKind, WorkerAgentSpec,
 };
+pub use workspace::{
+    CommandOutput, CommandOutputObserver, CommandRequest, LocalWorkspaceBackend,
+    VirtualPathResolver, WorkspaceCapabilities, WorkspaceCommandRunner, WorkspaceDirEntry,
+    WorkspaceFileSystem, WorkspaceFileType, WorkspaceGit, WorkspaceGitBranch,
+    WorkspaceGitCheckoutOutput, WorkspaceGitCheckoutRequest, WorkspaceGitCommit,
+    WorkspaceGitCreateBranchRequest, WorkspaceGitCreateWorktreeRequest, WorkspaceGitDiffRequest,
+    WorkspaceGitRemote, WorkspaceGitRemoveWorktreeRequest, WorkspaceGitStash,
+    WorkspaceGitStashProvider, WorkspaceGitStashRequest, WorkspaceGitStatus, WorkspaceGitWorktree,
+    WorkspaceGitWorktreeMutation, WorkspaceGitWorktreeProvider, WorkspaceGlobRequest,
+    WorkspaceGlobResult, WorkspaceGrepRequest, WorkspaceGrepResult, WorkspacePath,
+    WorkspacePathResolver, WorkspaceRef, WorkspaceSearch, WorkspaceServices,
+    WorkspaceServicesBuilder, WorkspaceWriteOutcome,
+};

core/src/llm/structured_tests.rs

@@ -1176,7 +1176,7 @@ async fn test_integration_generate_blocking_prompt_mode() {
     let result = result.unwrap();
     assert_eq!(result.object["sentiment"], "positive");
     let confidence = result.object["confidence"].as_f64().unwrap();
-    assert!(confidence >= 0.0 && confidence <= 1.0);
+    assert!((0.0..=1.0).contains(&confidence));
     eprintln!(
         "Integration test passed: sentiment={}, confidence={}, repairs={}",
         result.object["sentiment"], confidence, result.repair_rounds
@@ -1243,7 +1243,7 @@ async fn test_integration_generate_streaming_tool_mode() {
     for lang in languages {
         assert!(lang["name"].is_string());
         let year = lang["year"].as_i64().unwrap();
-        assert!(year >= 1950 && year <= 2030);
+        assert!((1950..=2030).contains(&year));
     }
 
     let partial_count = partials.lock().unwrap().len();