docs(#1724): add sandboxed tool execution to Phase 3 roadmap

Names three opt-in SandboxedExecutor backends:

- ProcessSandbox — sandbox-exec (macOS) / bwrap / firejail (Linux)
- WasmSandbox — JAR-embedded WASM via Chicory (pure-Java; no host setup)
- DockerSandbox — opt-in extras module via docker-java (not embeddable)

Default executor stays in-process for backward compat. README's
Limitations section gains an honest "no tool sandboxing today"
entry pointing at the Phase 3 plan.

Pairs with grants { } as the security-conscious differentiator:
permissions control which tools run; sandboxing controls what they
can do once invoked.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Skobeltsyn

README.md

@@ -163,6 +163,7 @@ What the framework does **not** enforce — your responsibility:
 - **No native binary** — JVM-only (≥ JDK 21). GraalVM and `jlink` bundles are Phase 2 priorities.
 - **No A2A protocol yet** — agent-to-agent over network (Phase 2 / 3).
 - **Inline-tool-call fallback model variance** — small Ollama models (e.g. `gemma3:4b`) reliably emit single tool calls via the inline format but may produce thin final-turn text after multi-step tool sequences. For multi-step reasoning, a tool-native model (`gpt-oss:20b-cloud` and similar) is the better fit.
+- **No tool sandboxing** — tool executors run in-process with full JVM privileges. `grants { }` controls *which* tools an agent can call, not *what they can do* once invoked. Sandboxed execution (`ProcessSandbox` / `WasmSandbox` / `DockerSandbox` opt-in backends) is on the Phase 3 roadmap.
 
 For planned features beyond these limitations, see [docs/roadmap.md](docs/roadmap.md).
 
@@ -222,7 +223,7 @@ Testing details — task names, integration test setup, mutation testing, how to
 
 **Phase 2 — Runtime + Distribution** *(Q2 2026)*: remaining provider (Google), `Flow<...>` streaming on every adapter, KSP compile-time `@Generable`, native CLI / jlink, `Tool<IN, OUT>` hierarchy, `grants {}` permissions, session model, Flow-based observability, `agent.json` serialization, Gradle plugin. *(Anthropic and OpenAI adapters already landed in #1644 and #1656.)*
 
-**Phase 3 — Production** *(Q3 2026)*: Layer 2 Structure DSL, all 37 compile-time validations, AgentUnit, A2A protocol, file-based knowledge with RAG, OpenTelemetry.
+**Phase 3 — Production** *(Q3 2026)*: Layer 2 Structure DSL, all 37 compile-time validations, AgentUnit, A2A protocol, file-based knowledge with RAG, OpenTelemetry, **sandboxed tool execution** (`SandboxedExecutor` with `ProcessSandbox` / `WasmSandbox` / `DockerSandbox` backends — opt-in per tool, default executor stays in-process).
 
 **Phase 4 — Ecosystem** *(Q4 2026)*: knowledge packs, NL → DSL generation, Skillify, visual editor, knowledge marketplace.
 

docs/roadmap.md

@@ -60,6 +60,11 @@
 - [ ] File-based knowledge: `skill.md`, `reference`, `examples`, `checklist` + RAG pipeline
 - [ ] Production observability: OpenTelemetry traces
 - [ ] Team DSL — swarm coordination (if isolated execution available)
+- [ ] **Sandboxed tool execution** — `SandboxedExecutor` interface with three backends, opt-in per tool (`tool(..., sandbox = ...)`) or per skill (`sandbox { }` block). Default executor stays in-process for backward compatibility.
+  - `ProcessSandbox` — subprocess executor with env / cwd / timeout / network constraints. Backends: `sandbox-exec` on macOS (built into the OS), `bwrap` or `firejail` on Linux. Falls back to plain `ProcessBuilder` with a loud warning on platforms with no native sandboxing tool. **Most pragmatic** — every dev box has at least one path.
+  - `WasmSandbox` — JAR-embedded WASM runtime via Chicory (pure-Java; no host setup). Tools compiled to WASM; filesystem and network capabilities granted explicitly at registration. **Most truly embedded** — works anywhere a JVM runs.
+  - `DockerSandbox` — opt-in extras module (`agents-kt-docker-sandbox`) via `docker-java`. Talks to whatever Docker daemon the host already runs. **Not embeddable** — library ships in the JAR, daemon does not. For teams that already operate Docker.
+  - Why this axis matters: today `grants { tools(writeFile, compile) }` controls *which* tools an agent can call; sandboxing controls *what those tools can do* once invoked. Pairs with frozen agents + typed args to give a security model that's strictly stronger than "trust the executor lambda."
 
 **Phase 4 — Ecosystem** *(Q4 2026)*
 - [ ] Knowledge packs — battle-tested prompt libraries for common domains