feat: Phase 47 — Tool Execution With Sandboxing (v4.0.0-alpha.7)

ARCHITECTURE_V4.md

@@ -825,6 +825,13 @@ attack surface for "convince the model to execute something dangerous"
 bounded by what a human operator pre-approved, not by what the model
 can be talked into requesting.
 
+> **Implemented in v4.0.0-alpha.7** as `crates/aarambh-studio-agent/src/{sandbox,authorization}.rs`.
+> `SandboxedToolProvider` implements `ToolResultProvider`, so execution plugs
+> into the existing `ToolChain` with zero chain changes. See
+> `docs/phase47_sandbox.md` for the runbook and the honesty boundary
+> (pure-Rust CPU sandbox: wall-clock timeout + output/argument-size ceilings;
+> OS-level isolation is out of scope for the source release).
+
 ---
 
 ## 62. Multi-Agent Orchestration

CHANGELOG.md

@@ -2,6 +2,92 @@
 
 > From first principles. From zero. From Rust.
 
+## [4.0.0-alpha.7] - 2026-08-23
+
+### Added
+
+- **Phase 47 — Tool Execution With Sandboxing:** Closes the boundary v2
+  §30 opened (tool calls are emitted, never executed) and v3 §46 extended
+  (multi-step chains, still emit-only): the model's tool calls can now be
+  **actually executed** by aarambh-studio itself, but only inside a strict,
+  closed-world sandbox. This is the highest-risk phase before Phase 51 and
+  is scoped conservatively on purpose — there is no generic "run a shell
+  command" or "eval this code" executor anywhere in the crate, by design.
+  - New `sandbox` module (`aarambh-studio-agent`: `sandbox.rs`): the
+    `ToolExecutor` trait (one specific, named capability per implementor),
+    `ToolSandbox` (closed-world registry + compiled JSON Schemas +
+    authorization + limits), `SandboxLimits` (wall-clock `timeout_ms`,
+    `max_output_bytes`, `max_args_bytes`), `ExecContext` (limits +
+    cooperative cancellation flag + deadline), `ValidatedArgs` (newtype
+    guarantee — executors never receive untrusted input), `ExecError`
+    (`UnknownTool`/`Unauthorized`/`InvalidArgs`/`Timeout`/
+    `ResourceLimitExceeded`/`Executor`), and `SandboxedToolProvider`
+    (implements `ToolResultProvider`, so execution plugs into the existing
+    `ToolChain` with **zero chain changes** — results re-enter via the
+    unchanged `result_ingestion` path, execution is purely additive to what
+    v3 §46 built).
+  - New `authorization` module (`aarambh-studio-agent`: `authorization.rs`):
+    `AuthorizationScope` — the closed set of tool names an operator
+    explicitly enabled at startup. Per-tool authorization is an **operator**
+    decision, not a model decision: the model can request execution of
+    anything in its declared schema, but only authorized tools are ever
+    executed. `AuthorizationScope::intersect` supports Phase 48's
+    multi-agent orchestration, where a sub-agent's scope can only be a
+    *subset* of its orchestrator's — orchestration can never escalate tool
+    access beyond what the operator enabled at the top level.
+  - Two reference `ToolExecutor` implementations: `ReadFileInWorkdir` (the
+    milestone executor — a read-only file lookup confined to a fixed working
+    directory; refuses absolute paths and `..` traversal, caps output bytes,
+    no network or write access by construction) and `StaticLookup` (an
+    in-memory key→text executor for deterministic tests and smoke runs).
+  - The full §61 execution pipeline is enforced by `ToolSandbox::execute`:
+    (1) closed-world allowlist — the name must match a registered executor;
+    (2) operator authorization — distinct from `UnknownTool`, a capability
+    can exist and be declared but unauthorized; (3) argument-size ceiling;
+    (4) schema re-validation, defense-in-depth on top of the
+    grammar-constrained decoder — malformed or schema-invalid calls are
+    never executed; (5) bounded envelope — worker thread with
+    `recv_timeout` wall-clock timeout, cooperative cancellation via an
+    `AtomicBool` flag, detached-on-timeout since safe Rust cannot
+    force-kill a thread; (6) output-size ceiling. Every failure yields a
+    fail-closed `ToolResult{status:Error, error:...}` — the chain records
+    the refusal and continues, it never silently drops a call.
+  - New `agent` CLI flags: `--execute-tools` (switch from caller-executed
+    stdin/replay results to sandboxed execution), `--allow-tool <NAME>`
+    (repeatable operator authorization), `--exec-timeout-ms`,
+    `--exec-max-output-bytes`, `--exec-workdir <DIR>` (binds the
+    `ReadFileInWorkdir` executor).
+  - Six roadmap-named acceptance tests in `sandbox.rs` (plus supporting
+    tests for authorization intersect, read-file traversal refusal, and
+    limits validation): `unlisted_tool_name_is_hard_refused_never_attempted`,
+    `unauthorized_but_declared_tool_is_refused_at_execution_not_declaration`,
+    `execution_timeout_kills_a_hanging_tool_call`,
+    `execution_respects_configured_memory_and_cpu_ceiling`,
+    `malformed_tool_call_json_is_never_executed`, and
+    `execution_result_re_ingests_correctly_into_the_next_chain_step` (this
+    last one drives the real `ToolChain` with a `FakeDecoder` +
+    `SandboxedToolProvider` + `StaticLookup` and asserts the executed
+    result is re-ingested into the chain state).
+  - New `scripts/phase47_smoke.sh`: runs the agent-crate sandbox unit tests,
+    verifies `agent --help` surfaces the new flags, and writes a scorecard
+    to `artifacts/phase47_sandbox_smoke.json`.
+  - New `docs/phase47_sandbox.md`: dedicated Phase 47 runbook (mirrors
+    `docs/phase46_rlaif.md` structure).
+
+### Honesty boundary
+
+Phase 47's sandbox is pure-Rust and CPU-only: wall-clock timeout
+(cooperative cancellation + thread-detachment on timeout, since safe Rust
+cannot force-kill a thread), output-size ceiling, argument-size ceiling,
+closed-world allowlist, operator authorization, and schema re-validation.
+OS-level isolation (seccomp, cgroups, namespaces) is out of scope for the
+source release, consistent with the project's CPU-first posture. The
+safety-relevant property — a runaway or hung call never blocks the chain
+and always produces a fail-closed result — holds under every tested failure
+condition. A general-purpose code-execution sandbox remains explicitly out
+of scope: Phase 47's execution is strictly closed-world, named-capability
+tool execution, never arbitrary code or shell execution.
+
 ## [4.0.0-alpha.6] - 2026-08-16
 
 ### Added

Cargo.toml

@@ -24,7 +24,7 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "4.0.0-alpha.6"
+version = "4.0.0-alpha.7"
 edition = "2024"
 rust-version = "1.89"
 description = "From first principles. From zero. From Rust."

README.md

@@ -34,11 +34,17 @@ Best-of-N / self-consistency / verifier-guided / process-reward
 selection that generates N independent candidate completions and selects
 the best one at inference time — a new axis alongside the existing
 thinking-mode budget system, distinct from controlling how many tokens
-one generation spends reasoning — and RLAIF, a third alignment signal
+one generation spends reasoning — RLAIF, a third alignment signal
 alongside GRPO and DPO where a frozen judge model scores pairs of
 self-sampled completions (judged in both orderings to correct position
 bias) and the resulting `(chosen, rejected)` pairs feed the existing
-unmodified `finetune dpo` pipeline.
+unmodified `finetune dpo` pipeline — and **sandboxed tool execution**
+(Phase 47), which closes the boundary v2 §30 opened (emit-only) and
+v3 §46 extended (multi-step, still emit-only): the model's tool calls can
+now be **actually executed** by aarambh-studio itself, but only inside a
+strict, closed-world sandbox (registered named executors, operator
+authorization, schema re-validation, wall-clock timeout, and output-size
+ceiling — there is no generic shell or eval executor, ever, by design).
 
 > [!IMPORTANT]
 > This is a source and engineering project. It does not publish crates to
@@ -136,6 +142,7 @@ See the phase-specific docs for full walkthroughs with smoke fixtures:
 | Train (CPU/GPU, MTP, MoE, distillation, QAT) | `aarambh-studio train --help` + [configs/](configs/) TOML examples |
 | Inference (text, thinking, image, video, document, audio) | [docs/aarambh-studio-complete-guide.md](docs/aarambh-studio-complete-guide.md) |
 | Tool-use agent chains | [docs/phase37_agent.md](docs/phase37_agent.md) |
+| Sandboxed tool execution | [docs/phase47_sandbox.md](docs/phase47_sandbox.md) |
 | Video understanding | [docs/phase35_video.md](docs/phase35_video.md) |
 | Document understanding | [docs/phase36_document.md](docs/phase36_document.md) |
 | Audio understanding | [docs/phase42_audio.md](docs/phase42_audio.md) |
@@ -281,7 +288,13 @@ CUDA checks require a CUDA-capable environment and are intentionally opt-in.
   Multi-node training is data-parallel only (Phase 44), not model/pipeline-parallel.
   Test-time compute scaling (Phase 45) is text-only and ships a heuristic
   process-reward scorer plus a trait for a future trained head.
-- Tool chains are generated and orchestrated but never executed by the runtime.
+- Tool chains were historically generated and orchestrated but never
+  executed by the runtime; Phase 47 adds opt-in sandboxed execution
+  (`agent --execute-tools`) that executes only operator-authorized,
+  closed-world named capabilities (e.g. `read_file_in_workdir`) inside a
+  bounded envelope. A general-purpose code-execution sandbox remains out
+  of scope — execution is strictly closed-world, never arbitrary code or
+  shell execution.
 - Video is visual-only H.264 MP4; audio is WAV PCM only (no MP3/FLAC/Ogg).
 - Documents are pixel-based (no OCR/table parser).
 - The server is local/single-model; vision, audio, and self-learning are CLI workflows.
@@ -303,7 +316,7 @@ reproducible bugs and scoped feature requests. Report vulnerabilities through
   author  = {Aarambh Dev Hub},
   year    = {2026},
   url     = {https://github.com/AarambhDevHub/aarambh-studio},
-  version = {4.0.0-alpha.6},
+  version = {4.0.0-alpha.7},
   license = {Apache-2.0}
 }
 ```