feat(tools): wire per-category sandbox backend selection

CLAUDE.md

@@ -133,7 +133,7 @@ src/synthorg/
     subscribers/  # Concrete settings subscribers (ProviderSettingsSubscriber — rebuilds ModelRouter on strategy change, MemorySettingsSubscriber — advisory logging for memory config)
   security/       # SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies: disabled/weighted/per-category/milestone), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume)
   templates/      # Pre-built company templates, personality presets, and builder
-  tools/          # Tool registry, built-in tools (file_system/, git, sandbox/, code_runner), git clone SSRF prevention (git_url_validator), MCP bridge (mcp/), role-based access, approval tool (request_human_approval), tool factory (build_default_tools, build_default_tools_from_config)
+  tools/          # Tool registry, built-in tools (file_system/, git, sandbox/, code_runner), git clone SSRF prevention (git_url_validator), MCP bridge (mcp/), role-based access, approval tool (request_human_approval), tool factory (build_default_tools, build_default_tools_from_config), sandbox factory (sandbox/factory.py: build_sandbox_backends, resolve_sandbox_for_category, cleanup_sandbox_backends -- per-category backend selection from SandboxingConfig)
 
 web/              # Vue 3 + PrimeVue + Tailwind CSS dashboard
   src/

docs/architecture/tech-stack.md

@@ -111,7 +111,7 @@ These conventions are used throughout the codebase. For full details on each, se
 | **Parallel tool execution** | Adopted | `asyncio.TaskGroup` in `ToolInvoker.invoke_all` with optional `max_concurrency` semaphore and structured error collection. |
 | **Parallel agent execution** | Adopted | `ParallelExecutor` with `TaskGroup` + `Semaphore` concurrency limits, `ResourceLock` for exclusive file-path claims, progress tracking, and shutdown awareness. |
 | **Tool permission checking** | Adopted | Category-level gating based on `ToolAccessLevel`. Priority-based resolution: denied list, allowed list, level categories, then deny. |
-| **Tool sandboxing** | Adopted | Layered: in-process path validation for file system tools, `SubprocessSandbox` for git tools, `DockerSandbox` planned for code execution. |
+| **Tool sandboxing** | Adopted | Layered: in-process path validation for file system tools, `SubprocessSandbox` for git tools, `DockerSandbox` for code execution. Per-category backend selection via `SandboxingConfig` and sandbox factory. |
 | **Crash recovery** | Adopted | Pluggable `RecoveryStrategy` protocol. Current: `FailAndReassignStrategy`. Planned: `CheckpointStrategy` for per-turn state persistence. |
 | **Personality compatibility** | Adopted | Weighted composite scoring: 60% Big Five similarity, 20% collaboration alignment, 20% conflict approach. |
 | **Agent behavior testing** | Planned | Scripted `FakeProvider` for unit tests; behavioral outcome assertions for integration tests. |

docs/design/operations.md

@@ -463,6 +463,13 @@ isolation for high-risk tools.
         network_policy: "deny-all"         # default deny, allowlist per tool
     ```
 
+Per-category backend selection is implemented in `tools/sandbox/factory.py` via three functions:
+`build_sandbox_backends` (instantiates only the backends referenced by config),
+`resolve_sandbox_for_category` (looks up the correct backend for a `ToolCategory`), and
+`cleanup_sandbox_backends` (parallel cleanup with error isolation). The tool factory
+(`build_default_tools_from_config`) wires `VERSION_CONTROL` category; other categories will
+be wired as their tool builders are added.
+
 Docker is optional -- only required when code execution, terminal, web, or database tools are
 enabled. File system and git tools work out of the box with subprocess isolation. This keeps
 the local-first experience lightweight while providing strong isolation where it matters.

src/synthorg/observability/events/sandbox.py

@@ -14,3 +14,9 @@
 SANDBOX_HEALTH_CHECK: Final[str] = "sandbox.health_check"
 SANDBOX_KILL_FAILED: Final[str] = "sandbox.kill.failed"
 SANDBOX_KILL_FALLBACK: Final[str] = "sandbox.kill.fallback"
+SANDBOX_FACTORY_BUILT: Final[str] = "sandbox.factory.built"
+SANDBOX_FACTORY_BUILD_FAILED: Final[str] = "sandbox.factory.built.failed"
+SANDBOX_FACTORY_RESOLVE: Final[str] = "sandbox.factory.resolve"
+SANDBOX_FACTORY_RESOLVE_FAILED: Final[str] = "sandbox.factory.resolve.failed"
+SANDBOX_FACTORY_CLEANUP: Final[str] = "sandbox.factory.cleanup"
+SANDBOX_FACTORY_CLEANUP_FAILED: Final[str] = "sandbox.factory.cleanup.failed"

src/synthorg/tools/factory.py

@@ -1,4 +1,4 @@
-"""Tool factory — instantiate built-in workspace tools with config-driven parameters.
+"""Tool factory -- instantiate built-in workspace tools with config-driven parameters.
 
 Provides ``build_default_tools`` (core factory) and
 ``build_default_tools_from_config`` (convenience wrapper that
@@ -9,6 +9,7 @@
 
 from typing import TYPE_CHECKING
 
+from synthorg.core.enums import ToolCategory
 from synthorg.observability import get_logger
 from synthorg.observability.events.tool import (
     TOOL_FACTORY_BUILT,
@@ -30,8 +31,13 @@
     GitLogTool,
     GitStatusTool,
 )
+from synthorg.tools.sandbox.factory import (
+    build_sandbox_backends,
+    resolve_sandbox_for_category,
+)
 
 if TYPE_CHECKING:
+    from collections.abc import Mapping
     from pathlib import Path
 
     from synthorg.config.schema import RootConfig
@@ -127,35 +133,87 @@ def build_default_tools(
     return result
 
 
+def _resolve_vc_sandbox(
+    *,
+    config: RootConfig,
+    sandbox_backends: Mapping[str, SandboxBackend] | None,
+    workspace: Path,
+) -> SandboxBackend:
+    """Resolve the sandbox backend for the VERSION_CONTROL category.
+
+    Builds backends from config when *sandbox_backends* is ``None``.
+    """
+    if sandbox_backends is None:
+        sandbox_backends = build_sandbox_backends(
+            config=config.sandboxing,
+            workspace=workspace,
+        )
+    return resolve_sandbox_for_category(
+        config=config.sandboxing,
+        backends=sandbox_backends,
+        category=ToolCategory.VERSION_CONTROL,
+    )
+
+
 def build_default_tools_from_config(
     *,
     workspace: Path,
     config: RootConfig,
     sandbox: SandboxBackend | None = None,
+    sandbox_backends: Mapping[str, SandboxBackend] | None = None,
 ) -> tuple[BaseTool, ...]:
     """Build default tools using parameters from a ``RootConfig``.
 
     Convenience wrapper that extracts ``config.git_clone`` and
-    delegates to :func:`build_default_tools`.
+    ``config.sandboxing`` to resolve per-category sandbox backends.
+
+    Currently wires the ``VERSION_CONTROL`` category (git tools).
+    Other categories (e.g. ``CODE_EXECUTION``) will be wired as
+    their respective tool builders are added to the factory.
+
+    Sandbox resolution priority:
+        1. Explicit *sandbox* -- backward-compat single backend for all tools.
+        2. Explicit *sandbox_backends* -- per-category resolution via config.
+        3. Neither -- auto-build backends from ``config.sandboxing``.
 
     Args:
         workspace: Absolute path to the agent workspace root.
         config: Validated root configuration.
-        sandbox: Optional sandbox backend for subprocess
-            isolation (passed to git tools).
+        sandbox: Optional single sandbox backend (overrides per-category
+            resolution when provided).
+        sandbox_backends: Pre-built mapping of backend name to instance.
+            When provided, per-category resolution uses this map
+            instead of auto-building backends.
 
     Returns:
         Sorted tuple of ``BaseTool`` instances.
 
     Raises:
         ValueError: If *workspace* is not an absolute path.
+        KeyError: If per-category sandbox resolution finds a backend
+            name not present in the built or provided backends mapping.
     """
     logger.debug(
         TOOL_FACTORY_CONFIG_ENTRY,
         source="config",
     )
+
+    if sandbox is not None:
+        # Explicit single backend -- backward compat
+        return build_default_tools(
+            workspace=workspace,
+            git_clone_policy=config.git_clone,
+            sandbox=sandbox,
+        )
+
+    vc_sandbox = _resolve_vc_sandbox(
+        config=config,
+        sandbox_backends=sandbox_backends,
+        workspace=workspace,
+    )
+
     return build_default_tools(
         workspace=workspace,
         git_clone_policy=config.git_clone,
-        sandbox=sandbox,
+        sandbox=vc_sandbox,
     )

src/synthorg/tools/sandbox/__init__.py

@@ -4,6 +4,11 @@
 from .docker_config import DockerSandboxConfig
 from .docker_sandbox import DockerSandbox
 from .errors import SandboxError, SandboxStartError, SandboxTimeoutError
+from .factory import (
+    build_sandbox_backends,
+    cleanup_sandbox_backends,
+    resolve_sandbox_for_category,
+)
 from .protocol import SandboxBackend
 from .result import SandboxResult
 from .sandboxing_config import SandboxingConfig
@@ -20,4 +25,7 @@
     "SandboxingConfig",
     "SubprocessSandbox",
     "SubprocessSandboxConfig",
+    "build_sandbox_backends",
+    "cleanup_sandbox_backends",
+    "resolve_sandbox_for_category",
 ]

src/synthorg/tools/sandbox/docker_sandbox.py

@@ -13,6 +13,7 @@
 import aiodocker
 import aiodocker.containers
 
+from synthorg.core.types import NotBlankStr
 from synthorg.observability import get_logger
 from synthorg.observability.events.docker import (
     DOCKER_CLEANUP,
@@ -35,8 +36,6 @@
 if TYPE_CHECKING:
     from collections.abc import Mapping
 
-    from synthorg.core.types import NotBlankStr
-
 logger = get_logger(__name__)
 
 _DEFAULT_CONFIG = DockerSandboxConfig()
@@ -645,4 +644,4 @@ async def health_check(self) -> bool:
 
     def get_backend_type(self) -> NotBlankStr:
         """Return ``'docker'``."""
-        return "docker"
+        return NotBlankStr("docker")