feat(tools): add "sandbox" toolset to run code snippets in an ephemeral, isolated container

[dwin-gharibi]

Closes #3638

---

Summary

Adds a new built-in toolset, sandbox, that runs a code snippet (python, node, or bash) inside an ephemeral, isolated container and returns stdout, stderr, and the exit code. Every run is disposable (--rm), resource-limited (memory / CPU / PID), time-bounded, and network-disabled by default.

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

Motivation

Agents often need to run code — compute a result, transform data, verify an approach — not just read/write files. Today the only option is shell, which runs on the host with full access. The sandbox runs untrusted / model-generated code in a disposable, isolated container instead. It fits docker-agent naturally, since a container runtime is already the environment it ships on.

Works with docker or other runtimes

Execution goes through an injectable Executor, and the default one auto-detects a docker-compatible CLI in order: docker → podman → nerdctl (they share run --rm -i --network none … syntax). If none is present, run_code returns a clear error.

What changed

File	Change
pkg/tools/builtin/sandbox/sandbox.go	New. The toolset: run_code, pure buildRunArgs, Executor seam, runtime detection.
pkg/tools/builtin/sandbox/sandbox_test.go	New. Args construction, language aliasing, timeout capping, output formatting, and error paths (fake executor).
pkg/teamloader/toolsets/toolsets.go	Register the sandbox creator.
pkg/teamloader/toolsets/catalog.go	Add the sandbox catalog entry (required by the drift-guard test).
docs/configuration/tools/index.md	Add sandbox to the built-in toolsets table.
docs/tools/sandbox/index.md	New. Dedicated docs page.

Design for testability

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

Example

The command it builds:

docker run --rm -i --memory 512m --cpus 1 --pids-limit 256 --network none python:3.12-slim python3 -

Tool output:

run_code(language="python", code="print(2 + 2)")

Exit code: 0

--- stdout ---
4

run_code (error)

Exit code: 1

--- stderr ---
SyntaxError: bad

Testing

go test ./pkg/tools/builtin/sandbox/ ./pkg/teamloader/toolsets/

• buildRunArgs (isolation flags, limits, image; --network none present by default and absent when network: true), language aliasing, run_code (success, non-zero exit, empty code, unknown language, timeout cap, executor error), and the tool/interface check.
• TestBuiltinToolsetsCatalogMatchesRegistry passes with sandbox in both registry and catalog.

All pass; gofmt -l and go vet clean. (CI runs task lint / task test.)

Safety / scope

• Isolated by default: --rm, --network none, --memory 512m, --cpus 1, --pids-limit 256, and a time limit (default 30s, capped 300s).
• network: true opts into a network only when the agent explicitly asks.
• Requires a container runtime at runtime; returns a clear error otherwise.
• v1 uses pinned per-language images with fixed limits; configurable images and limits are noted as future work.