Add a "sandbox" built-in toolset to run code snippets in an ephemeral, isolated container

[dwin-gharibi]

Overview

Add a new built-in toolset, sandbox, that lets an agent execute a code snippet (python, node, or bash) inside an ephemeral, isolated Docker container and get back stdout, stderr, and the exit code. Every run is throwaway (--rm), network-disabled by default (--network none), and capped with memory, CPU, PID, and time limits.

Tool: run_code(language, code, timeout_seconds?, network?).

Motivation

Agents frequently need to run code to compute a result, transform data, or verify an approach — not just read or write files. Today the only option is the shell tool, which runs on the host with full access. A dedicated sandbox tool:

• runs untrusted / model-generated code in a disposable container, isolated from the host filesystem and (by default) the network;
• is safe by construction — resource-limited and auto-removed;
• fits docker-agent perfectly, since Docker is already the runtime it ships on.

Use cases

1. "Compute this / transform this data" → run_code(language="python", code="…").
2. Quickly test a snippet or reproduce a bug in a clean environment.
3. Let a hardened agent run code without granting host shell access.

Proposed solution

New toolset type sandbox in pkg/tools/builtin/sandbox/, registered in pkg/teamloader/toolsets/toolsets.go and documented in the built-in toolset catalog (pkg/teamloader/toolsets/catalog.go) — the catalog drift-guard test forces the catalog entry.

Execution model (via the docker CLI, consistent with pkg/sandbox):

docker run --rm -i --network none --memory 512m --cpus 1 --pids-limit 256 <image> <interpreter>

with the code piped to the container's stdin. Supported languages map to pinned images (python:3.12-slim, node:22-alpine, bash:5). network: true opts into a network (e.g. to pip install); default is no network. timeout_seconds bounds the run (default 30s, capped).

Design for testability: the command construction is a pure buildRunArgs function, and execution goes through an injectable Executor interface. Tests cover argument construction, language aliasing, timeout capping, output formatting, and error paths with a fake executor — everything except the literal docker run, which needs a daemon (covered by CI/integration).

Alternatives

• shell — runs on the host with full access; not isolated, not disposable, no resource limits. The sandbox tool is the safe counterpart for running arbitrary/model-generated code.
• The run-level --sandbox isolates the whole agent; this tool isolates an individual code run on demand.

Related issues

No response

Additional context

Requires a working Docker engine at runtime; run_code returns a clear error if Docker is unavailable. Custom images and configurable limits are noted as future enhancements to keep v1 focused.