feat(sandbox): add A3S Box sandbox integration as built-in tool

- New `sandbox` Cargo feature with optional `a3s-box-sdk` dependency
- `SandboxConfig` + `BashSandbox` trait in src/sandbox.rs
- `BoxSandboxHandle`: lazy MicroVM boot, workspace mount at /workspace, Drop cleanup
- `BashTool`: delegates to sandbox when ctx.sandbox is set (transparent routing)
- New `SandboxTool` built-in: LLM-callable, registered under `sandbox` feature
- `ToolContext::with_sandbox()` + `ToolRegistry::set_sandbox()` for wiring
- `SessionOptions::with_sandbox(SandboxConfig)` builder
- `AgentSession::bash()` now uses execute_with_context (sandbox-aware)
- 13 new tests covering config, trait, BashTool delegation, SessionOptions
- Docs: sandbox section in sessions.mdx + README, test count 1166→1179

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ZhiXiao-Lin

Cargo.lock

@@ -11,7 +11,7 @@ let result = session.send("Refactor auth to use JWT").await?;
 [![Crates.io](https://img.shields.io/crates/v/a3s-code-core.svg)](https://crates.io/crates/a3s-code-core)
 [![Documentation](https://docs.rs/a3s-code-core/badge.svg)](https://docs.rs/a3s-code-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Tests](https://img.shields.io/badge/tests-1166%20passing-brightgreen.svg)](./core/tests)
+[![Tests](https://img.shields.io/badge/tests-1179%20passing-brightgreen.svg)](./core/tests)
 
 ---
 
@@ -123,13 +123,14 @@ print(result.text)
 
 ## Core Features
 
-### 🛠️ Built-in Tools (11)
+### 🛠️ Built-in Tools (11 + 1 optional)
 
 | Category | Tools | Description |
 |----------|-------|-------------|
 | **File Operations** | `read`, `write`, `edit`, `patch` | Read/write files, apply diffs |
 | **Search** | `grep`, `glob`, `ls` | Search content, find files, list directories |
 | **Execution** | `bash` | Execute shell commands |
+| **Sandbox** | `sandbox` | MicroVM execution via A3S Box (`sandbox` feature) |
 | **Web** | `web_fetch`, `web_search` | Fetch URLs, search the web |
 | **Subagents** | `task` | Delegate to specialized child agents |
 
@@ -237,6 +238,33 @@ Advanced features: retry policies, rate limiting, priority boost, pressure monit
 
 ---
 
+### 🔒 Sandbox Execution (A3S Box Integration)
+
+Route `bash` commands through an A3S Box MicroVM for isolated execution. Requires the `sandbox` Cargo feature.
+
+**Transparent routing** — configure once, bash tool uses sandbox automatically:
+
+```rust
+use a3s_code_core::{SessionOptions, SandboxConfig};
+
+SessionOptions::new().with_sandbox(SandboxConfig {
+    image: "ubuntu:22.04".into(),
+    memory_mb: 512,
+    network: false,
+    ..SandboxConfig::default()
+})
+```
+
+**Explicit `sandbox` tool** — with `sandbox` feature enabled, the LLM can call the `sandbox` tool directly. Workspace is mounted at `/workspace` inside the MicroVM.
+
+Enable:
+
+```toml
+a3s-code-core = { version = "0.7", features = ["sandbox"] }
+```
+
+---
+
 ### 🌐 Multi-Machine Distribution
 
 Offload tool execution to external workers via three handler modes:
@@ -476,7 +504,7 @@ cargo test          # All tests
 cargo test --lib    # Unit tests only
 ```
 
-**Test Coverage:** 1166 tests, 100% pass rate
+**Test Coverage:** 1179 tests, 100% pass rate
 
 ---
 

README.md

@@ -16,6 +16,8 @@ path = "src/lib.rs"
 a3s-common = { version = "0.1", path = "../../common" }
 a3s-lane = { version = "0.4", path = "../../lane" }
 a3s-search = { version = "0.8", path = "../../search", default-features = false }
+# Sandbox integration (optional — requires `sandbox` feature)
+a3s-box-sdk = { version = "0.5", path = "../../box/src/sdk", optional = true }
 
 # Async runtime
 tokio = { version = "1.35", features = [
@@ -89,6 +91,10 @@ chrono = { version = "0.4", features = ["serde"] }
 
 [features]
 default = []
+# Enable A3S Box sandbox integration for the `bash` tool.
+# When active, `SessionOptions::with_sandbox()` routes bash commands through
+# a MicroVM sandbox instead of `std::process::Command`.
+sandbox = ["dep:a3s-box-sdk"]
 
 [dev-dependencies]
 tempfile = "3.10"

core/Cargo.toml

@@ -96,6 +96,12 @@ pub struct SessionOptions {
     /// aborting in non-streaming mode (overrides default of 3).
     /// `None` uses the `AgentConfig` default.
     pub circuit_breaker_threshold: Option<u32>,
+    /// Optional sandbox configuration.
+    ///
+    /// When set, `bash` tool commands are routed through an A3S Box MicroVM
+    /// sandbox instead of `std::process::Command`. Requires the `sandbox`
+    /// Cargo feature to be enabled.
+    pub sandbox_config: Option<crate::sandbox::SandboxConfig>,
 }
 
 impl std::fmt::Debug for SessionOptions {
@@ -124,6 +130,7 @@ impl std::fmt::Debug for SessionOptions {
             .field("max_parse_retries", &self.max_parse_retries)
             .field("tool_timeout_ms", &self.tool_timeout_ms)
             .field("circuit_breaker_threshold", &self.circuit_breaker_threshold)
+            .field("sandbox_config", &self.sandbox_config)
             .finish()
     }
 }
@@ -334,6 +341,29 @@ impl SessionOptions {
             .with_tool_timeout(120_000)
             .with_circuit_breaker(3)
     }
+
+    /// Route `bash` tool execution through an A3S Box MicroVM sandbox.
+    ///
+    /// The workspace directory is mounted read-write at `/workspace` inside
+    /// the sandbox. Requires the `sandbox` Cargo feature; without it a warning
+    /// is logged and bash commands continue to run locally.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// use a3s_code_core::{SessionOptions, SandboxConfig};
+    ///
+    /// SessionOptions::new().with_sandbox(SandboxConfig {
+    ///     image: "ubuntu:22.04".into(),
+    ///     memory_mb: 512,
+    ///     network: false,
+    ///     ..SandboxConfig::default()
+    /// });
+    /// ```
+    pub fn with_sandbox(mut self, config: crate::sandbox::SandboxConfig) -> Self {
+        self.sandbox_config = Some(config);
+        self
+    }
 }
 
 // ============================================================================
@@ -592,6 +622,28 @@ impl Agent {
             tool_context = tool_context.with_search_config(search_config.clone());
         }
 
+        // Wire sandbox when configured.
+        #[cfg(feature = "sandbox")]
+        if let Some(ref sandbox_cfg) = opts.sandbox_config {
+            let handle: Arc<dyn crate::sandbox::BashSandbox> = Arc::new(
+                crate::sandbox::BoxSandboxHandle::new(
+                    sandbox_cfg.clone(),
+                    canonical.display().to_string(),
+                ),
+            );
+            // Update the registry's default context so that direct
+            // `AgentSession::bash()` calls also use the sandbox.
+            tool_executor.registry().set_sandbox(Arc::clone(&handle));
+            tool_context = tool_context.with_sandbox(handle);
+        }
+        #[cfg(not(feature = "sandbox"))]
+        if opts.sandbox_config.is_some() {
+            tracing::warn!(
+                "sandbox_config is set but the `sandbox` Cargo feature is not enabled \
+                 — bash commands will run locally"
+            );
+        }
+
         // Resolve memory store: explicit store takes priority, then file_memory_dir
         let memory = {
             let store = if let Some(ref store) = opts.memory_store {
@@ -837,9 +889,15 @@ impl AgentSession {
     }
 
     /// Execute a bash command in the workspace.
+    ///
+    /// When a sandbox is configured via [`SessionOptions::with_sandbox()`],
+    /// the command is routed through the A3S Box sandbox.
     pub async fn bash(&self, command: &str) -> Result<String> {
         let args = serde_json::json!({ "command": command });
-        let result = self.tool_executor.execute("bash", &args).await?;
+        let result = self
+            .tool_executor
+            .execute_with_context("bash", &args, &self.tool_context)
+            .await?;
         Ok(result.output)
     }
 
@@ -1425,4 +1483,49 @@ mod tests {
         assert_eq!(opts.session_id, Some("test-id".to_string()));
         assert!(opts.auto_save);
     }
+
+    // ========================================================================
+    // Sandbox Tests
+    // ========================================================================
+
+    #[test]
+    fn test_session_options_with_sandbox_sets_config() {
+        use crate::sandbox::SandboxConfig;
+        let cfg = SandboxConfig {
+            image: "ubuntu:22.04".into(),
+            memory_mb: 1024,
+            ..SandboxConfig::default()
+        };
+        let opts = SessionOptions::new().with_sandbox(cfg);
+        assert!(opts.sandbox_config.is_some());
+        let sc = opts.sandbox_config.unwrap();
+        assert_eq!(sc.image, "ubuntu:22.04");
+        assert_eq!(sc.memory_mb, 1024);
+    }
+
+    #[test]
+    fn test_session_options_default_has_no_sandbox() {
+        let opts = SessionOptions::default();
+        assert!(opts.sandbox_config.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_session_debug_includes_sandbox_config() {
+        use crate::sandbox::SandboxConfig;
+        let opts = SessionOptions::new().with_sandbox(SandboxConfig::default());
+        let debug = format!("{:?}", opts);
+        assert!(debug.contains("sandbox_config"));
+    }
+
+    #[tokio::test]
+    async fn test_session_build_with_sandbox_config_no_feature_warn() {
+        // When feature is not enabled, build_session should still succeed
+        // (it just logs a warning). With feature enabled, it creates a handle.
+        let agent = Agent::from_config(test_config()).await.unwrap();
+        let opts = SessionOptions::new()
+            .with_sandbox(crate::sandbox::SandboxConfig::default());
+        // build_session should not fail even if sandbox feature is off
+        let session = agent.session("/tmp/test-sandbox-session", Some(opts));
+        assert!(session.is_ok());
+    }
 }

core/src/agent_api.rs

@@ -56,6 +56,7 @@
 pub mod agent;
 pub mod agent_api;
 pub mod config;
+pub mod sandbox;
 pub mod context;
 pub mod error;
 pub mod file_history;
@@ -94,4 +95,5 @@ pub use queue::{
 pub use session::{SessionConfig, SessionManager, SessionState};
 pub use session_lane_queue::SessionLaneQueue;
 pub use skills::{builtin_skills, Skill, SkillKind};
+pub use sandbox::SandboxConfig;
 pub use tools::{ToolContext, ToolExecutor, ToolResult};