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/

src/synthorg/observability/events/sandbox.py

@@ -14,3 +14,6 @@
 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_RESOLVE: Final[str] = "sandbox.factory.resolve"
+SANDBOX_FACTORY_CLEANUP: Final[str] = "sandbox.factory.cleanup"

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
@@ -132,17 +138,30 @@ 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.
@@ -154,8 +173,30 @@ def build_default_tools_from_config(
         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,
+        )
+
+    # Per-category resolution
+    if sandbox_backends is None:
+        sandbox_backends = build_sandbox_backends(
+            config=config.sandboxing,
+            workspace=workspace,
+        )
+
+    vc_sandbox = resolve_sandbox_for_category(
+        config=config.sandboxing,
+        backends=sandbox_backends,
+        category=ToolCategory.VERSION_CONTROL,
+    )
+
     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")

src/synthorg/tools/sandbox/factory.py

@@ -0,0 +1,153 @@
+"""Sandbox backend factory -- build and resolve backends from config.
+
+Provides ``build_sandbox_backends`` to instantiate only the backends
+referenced by a ``SandboxingConfig``, ``resolve_sandbox_for_category``
+to look up the correct backend for a tool category, and
+``cleanup_sandbox_backends`` to release resources.
+"""
+
+import asyncio
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+from synthorg.observability import get_logger
+from synthorg.observability.events.sandbox import (
+    SANDBOX_FACTORY_BUILT,
+    SANDBOX_FACTORY_CLEANUP,
+    SANDBOX_FACTORY_RESOLVE,
+)
+from synthorg.tools.sandbox.docker_sandbox import DockerSandbox
+from synthorg.tools.sandbox.subprocess_sandbox import SubprocessSandbox
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+    from synthorg.core.enums import ToolCategory
+    from synthorg.tools.sandbox.protocol import SandboxBackend
+    from synthorg.tools.sandbox.sandboxing_config import SandboxingConfig
+
+logger = get_logger(__name__)
+
+
+def build_sandbox_backends(
+    *,
+    config: SandboxingConfig,
+    workspace: Path,
+) -> MappingProxyType[str, SandboxBackend]:
+    """Build only the backend instances actually referenced by *config*.
+
+    Collects which backend names are needed (the default plus all
+    override values), then instantiates ``SubprocessSandbox`` and/or
+    ``DockerSandbox`` with their respective sub-configs.
+
+    Args:
+        config: Top-level sandboxing configuration.
+        workspace: Absolute path to the agent workspace root.
+
+    Returns:
+        A read-only mapping of backend name to backend instance.
+        Only contains keys for backends that are actually referenced.
+    """
+    needed: set[str] = {config.default_backend}
+    needed.update(config.overrides.values())
+
+    backends: dict[str, SandboxBackend] = {}
+
+    if "subprocess" in needed:
+        backends["subprocess"] = SubprocessSandbox(
+            config=config.subprocess,
+            workspace=workspace,
+        )
+
+    if "docker" in needed:
+        backends["docker"] = DockerSandbox(
+            config=config.docker,
+            workspace=workspace,
+        )
+
+    logger.info(
+        SANDBOX_FACTORY_BUILT,
+        backends=sorted(backends.keys()),
+        default=config.default_backend,
+        override_count=len(config.overrides),
+    )
+    return MappingProxyType(backends)
+
+
+def resolve_sandbox_for_category(
+    *,
+    config: SandboxingConfig,
+    backends: Mapping[str, SandboxBackend],
+    category: ToolCategory,
+) -> SandboxBackend:
+    """Look up the correct backend for a tool category.
+
+    Uses ``config.backend_for_category()`` to determine the backend
+    name, then returns the corresponding instance from *backends*.
+
+    Args:
+        config: Top-level sandboxing configuration.
+        backends: Mapping of backend name to backend instance.
+        category: The tool category to resolve.
+
+    Returns:
+        The ``SandboxBackend`` instance for the given category.
+
+    Raises:
+        KeyError: If the resolved backend name is not present in
+            *backends*.
+    """
+    backend_name = config.backend_for_category(category.value)
+    try:
+        backend = backends[backend_name]
+    except KeyError:
+        msg = (
+            f"Backend {backend_name!r} resolved for category "
+            f"{category.value!r} not found in backends mapping "
+            f"(available: {sorted(backends.keys())})"
+        )
+        logger.warning(
+            SANDBOX_FACTORY_RESOLVE,
+            category=category.value,
+            backend=backend_name,
+            error=msg,
+        )
+        raise KeyError(msg) from None
+
+    logger.debug(
+        SANDBOX_FACTORY_RESOLVE,
+        category=category.value,
+        backend=backend_name,
+    )
+    return backend
+
+
+async def cleanup_sandbox_backends(
+    backends: Mapping[str, SandboxBackend],
+) -> None:
+    """Clean up all backends by calling ``cleanup()`` on each.
+
+    Errors from individual backends are logged but do not prevent
+    cleanup of remaining backends.  Uses ``asyncio.TaskGroup`` for
+    parallel cleanup.
+
+    Args:
+        backends: Mapping of backend name to backend instance.
+    """
+
+    async def _cleanup_one(name: str, backend: SandboxBackend) -> None:
+        logger.debug(SANDBOX_FACTORY_CLEANUP, backend=name)
+        try:
+            await backend.cleanup()
+        except Exception:
+            logger.warning(
+                SANDBOX_FACTORY_CLEANUP,
+                backend=name,
+                error=f"cleanup failed for backend {name!r}",
+                exc_info=True,
+            )
+
+    async with asyncio.TaskGroup() as tg:
+        for name, backend in backends.items():
+            tg.create_task(_cleanup_one(name, backend))