robot_lab 0.2.7 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36b770d963e004a951cdf35d07a2e867e4e661a9e342e8047184cfd9dafd6e15
-  data.tar.gz: f53bb5c52efcd6169bf36afc69306a9c03e9cfcabdaf5b0a94871802e2909f55
+  metadata.gz: de87b78206bc424703b465d3a1f236db723ea38fe4235c07413466ab5b469ead
+  data.tar.gz: 6a7db14e4530e615e258415491422f297567a2f640983035f1542d88e7d200e5
 SHA512:
-  metadata.gz: 850bde0e9ac1b7d65176bd067f42751d6d9db64517ca665d4765837fc5493e204f9b333cac08019cb451962d4d95789f986dee2ff08e55ae5e6a0d3d034f4f50
-  data.tar.gz: 97eb4dc66458a9a43f861e3f9c927eb6cfa63d33ddfff150b4181a45dc2c0db9570095f2e71d1182b76b4ee85e7086a6014b5536e805d9956f0860f9b4a03f50
+  metadata.gz: f6814c9a8b86b8e6d1df2adcc2d9b4ab84c176c67211424e8404e9d83c1e08ffd353587523e4c45efec295d0e47bbd731b0cdc6f3e62754cfd4f1ce2a33d7655
+  data.tar.gz: 37682af098203ae333cc83fa6e66a95f1883aae0bed8411524a05d6795bb47b4a99f231353fe3546b2fdae8a5c098d0f45b863e531edaf237aab33e4e1bc3859

data/.envrc

@@ -1,2 +1,6 @@
+# robot_lab_project/robot_lab/.envrc
+
+source_up
+
 export RR=`pwd`
 export BUNDLE_GEMFILE=Gemfile

data/.loki

@@ -18,6 +18,11 @@ class Tasks
     sh "ruby -Ilib:test \"#{path}\""
   end
 
+  desc "Check architecture boundaries with ArchSpec"
+  def archspec
+    sh "bundle exec archspec check"
+  end
+
   class DocsCommands < Tasks
     desc "Build YARD + MkDocs documentation"
     def build

data/Archspec.rb

@@ -0,0 +1,44 @@
+component :robot,         in: "lib/robot_lab/robot.rb"
+component :robot_support, in: "lib/robot_lab/robot/**/*.rb"
+component :network,       in: ["lib/robot_lab/network.rb", "lib/robot_lab/bus_poller.rb"]
+component :memory,        in: ["lib/robot_lab/memory.rb", "lib/robot_lab/memory_change.rb"]
+component :mcp,           in: "lib/robot_lab/mcp/**/*.rb"
+component :sandbox,       in: ["lib/robot_lab/sandbox.rb", "lib/robot_lab/sandbox/**/*.rb"]
+component :streaming,     in: "lib/robot_lab/streaming/**/*.rb"
+component :budget,        in: "lib/robot_lab/budget/**/*.rb"
+component :hooks,         in: %w[
+  lib/robot_lab/hook.rb
+  lib/robot_lab/hook_context.rb
+  lib/robot_lab/hook_registry.rb
+  lib/robot_lab/hooks.rb
+]
+component :tools, in: %w[
+  lib/robot_lab/tool.rb
+  lib/robot_lab/tool_config.rb
+  lib/robot_lab/tool_manifest.rb
+  lib/robot_lab/script_tool.rb
+]
+component :config, in: ["lib/robot_lab/config.rb", "lib/robot_lab/run_config.rb"]
+
+# NOTE: every file here reopens `module RobotLab`, so a `dependencies.forbid`
+# rule keyed on components (e.g. `memory.cannot_use :robot`) treats a plain
+# `RobotLab.config` call as "depends on every component" — every file
+# "defines" the bare RobotLab constant. Naming the actual target constants
+# instead of components sidesteps that ambiguity.
+
+# Memory is a low-level primitive shared by Robot and Network; it must not
+# depend back on the things that depend on it.
+memory.cannot_reference_constants "RobotLab::Robot", "RobotLab::Network"
+
+# MCP is an external-tool integration layer that Robot/Network consume; it
+# must not reach back into the objects that use it.
+mcp.cannot_reference_constants "RobotLab::Robot", "RobotLab::Network"
+
+# Sandbox runs untrusted/generated code paths and should have the smallest
+# possible surface area — no reaching into orchestration or memory internals.
+sandbox.cannot_reference_constants "RobotLab::Robot", "RobotLab::Network", "RobotLab::Memory"
+
+# Config/RunConfig sits at the bottom of the configuration cascade
+# (RobotLab.config -> Network -> Robot -> template -> task -> runtime) and
+# must not depend upward on the objects it configures.
+config.cannot_reference_constants "RobotLab::Robot", "RobotLab::Network"

data/CHANGELOG.md

@@ -6,7 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
-## [Unreleased]
+## [0.2.8] - 2026-09-09
 
 ### Added
 - `BusMessaging#respond_to_tasks` and `#serve` — a member auto-answers inbound
@@ -16,6 +16,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   without hand-wiring `on_message`.
 - `.loki` Asgard task file: `test`, `rubocop`, `rubocop_fix`, `flog`, `flay`, `quality`, `build`, `install`, `release`, `integration`, `docs`, and `examples` tasks via the Asgard task runner
 
+### Changed (BREAKING)
+- **Sandboxing extracted to `robot_lab-sandbox`.** `RobotLab::Sandbox`,
+  `RobotLab::Sandbox::Seatbelt`, and `RobotLab::Sandbox::Null` no longer live
+  in core; they moved verbatim to the new `robot_lab-sandbox` gem. Core has no
+  execution limitations of its own: `ScriptTool.execute` now delegates to an
+  optional `ScriptTool.executor` (`nil` by default, in which case it runs the
+  unconfined `Open3.capture2e` path with no timeout exactly as before).
+  Applications that want confined skill-script execution must add
+  `gem "robot_lab-sandbox"` and `require "robot_lab/sandbox"`, which installs
+  itself as the executor; `config.sandbox.*` behavior is unchanged from there.
+  `RobotLab::Capabilities` (the declarative fs_read/fs_write/network/timeout/
+  trust manifest parsed from `SKILL.md`) stays in core since `AgentSkill` needs
+  it regardless of whether sandboxing is enforced.
+- `ScriptTool.run_with_timeout` and `ScriptTool.terminate` moved to
+  `RobotLab::Sandbox::Executor` in `robot_lab-sandbox`.
+
 ### Fixed
 - `BusMessaging` now synchronizes its message counter and outbox with a mutex, so
   concurrent sends and poller-thread reply correlation can't clobber each other.

data/Rakefile

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rake/testtask"
+# Quality gates (quality, rubocop_check, flog_check, flay_check,
+# archspec_check, ...), doc *serving*, and the gem lifecycle (build, install,
+# release) live in asgard — see .loki and the shared dev/*.loki files it
+# imports. This Rakefile keeps the tasks asgard delegates to (tests,
+# integration, examples, docs:build).
 
-RUBOCOP_ENV = { "RUBOCOP_CACHE_ROOT" => "tmp/rubocop_cache" }.freeze
+require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -36,100 +39,6 @@ Rake::TestTask.new(:integration) do |t|
   t.ruby_opts << "-rtest_helper"
 end
 
-desc "Check code complexity with Flog (warn ≥20, fail ≥50)"
-task :flog_check do
-  require 'flog'
-
-  # Target to work toward; methods above this are warned but don't fail the gate.
-  METHOD_WARN = 20.0
-  # Current baseline floor — established from first run. Reduce incrementally.
-  METHOD_FAIL = 50.0
-
-  flogger = Flog.new(all: true)
-  flogger.flog(*Dir.glob('lib/**/*.rb'))
-
-  warnings  = []
-  failures  = []
-
-  flogger.each_by_score do |method, score|
-    next if method.end_with?('#none')  # skip file-level non-method code
-    if score > METHOD_FAIL
-      failures  << "#{'%.1f' % score}: #{method}"
-    elsif score > METHOD_WARN
-      warnings  << "#{'%.1f' % score}: #{method}"
-    end
-  end
-
-  unless warnings.empty?
-    puts "\nFlog warnings (#{METHOD_WARN}–#{METHOD_FAIL}) — target for future refactoring:"
-    warnings.each { |v| puts "  #{v}" }
-  end
-
-  if failures.empty?
-    puts "\nFlog: no methods exceed the failure threshold (≥#{METHOD_FAIL})"
-  else
-    puts "\nFlog failures (≥#{METHOD_FAIL}) — must be refactored:"
-    failures.each { |v| puts "  #{v}" }
-    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{METHOD_FAIL}"
-  end
-end
-
-desc "Check for structural code duplication with Flay (mass >= 50)"
-task :flay_check do
-  require 'flay'
-
-  mass_threshold = 50
-
-  flay = Flay.new({ mass: mass_threshold, diff: false, verbose: false, summary: false, timeout: 60 })
-  flay.process(*Dir.glob('lib/**/*.rb'))
-  flay.analyze
-
-  if flay.hashes.empty?
-    puts "\nFlay: no structural duplication detected (mass >= #{mass_threshold})"
-  else
-    puts "\nFlay found structural duplication (mass >= #{mass_threshold}):"
-    flay.report
-    abort "\nFlay quality gate failed: #{flay.hashes.length} pattern(s) detected"
-  end
-end
-
-desc "Run all quality checks: tests (with coverage), RuboCop, Flog, and Flay"
-task :quality do
-  results = {}
-
-  puts "\n#{'=' * 60}"
-  puts "Quality Gate: Tests + Coverage"
-  puts '=' * 60
-  results[:tests] = system("bundle exec rake test") ? :pass : :fail
-
-  puts "\n#{'=' * 60}"
-  puts "Quality Gate: RuboCop"
-  puts '=' * 60
-  results[:rubocop] = system(RUBOCOP_ENV, "bundle exec rubocop") ? :pass : :fail
-
-  puts "\n#{'=' * 60}"
-  puts "Quality Gate: Flog Complexity"
-  puts '=' * 60
-  results[:flog] = system("bundle exec rake flog_check") ? :pass : :fail
-
-  puts "\n#{'=' * 60}"
-  puts "Quality Gate: Flay Duplication"
-  puts '=' * 60
-  results[:flay] = system("bundle exec rake flay_check") ? :pass : :fail
-
-  puts "\n#{'=' * 60}"
-  puts "Quality Summary"
-  puts '=' * 60
-  results.each do |gate, status|
-    icon = status == :pass ? 'PASS' : 'FAIL'
-    puts "  [#{icon}] #{gate}"
-  end
-  puts '=' * 60
-
-  abort "\nQuality gate failed" if results.values.any?(:fail)
-  puts "\nAll quality gates passed."
-end
-
 namespace :examples do
   # Map of subdirectory-based demos to their entry point scripts
   SUBDIR_ENTRY_POINTS = {
@@ -277,22 +186,8 @@ namespace :docs do
     sh "yard doc"
   end
 
-  namespace :yard do
-    desc "Serve YARD documentation locally"
-    task :serve do
-      sh "yard server --reload"
-    end
-  end
-
   desc "Build MkDocs documentation"
   task :mkdocs do
     sh "mkdocs build"
   end
-
-  namespace :mkdocs do
-    desc "Serve MkDocs documentation locally"
-    task :serve do
-      sh "mkdocs serve"
-    end
-  end
 end

data/_typos.toml

@@ -0,0 +1,21 @@
+# False-positive suppressions for the typos quality gate (asgard).
+# Everything here was reviewed by hand — see git history for context.
+
+[files]
+extend-exclude = [
+  # Example transcripts / articles: prose quotes real names ("Damon Clark")
+  # and SQL-ish plurals ("SELECTs") that typos mis-parses.
+  "examples/ruboruby.md",
+  "examples/25_history_search/conversation.jsonl",
+]
+
+[default.extend-identifiers]
+# Robot names in lib/robot_lab/names.rb
+BATs     = "BATs"
+Damon    = "Damon"
+Mata_Nui = "Mata_Nui"
+Pris     = "Pris"
+S1MONE   = "S1MONE"
+# Test-local variable names
+ba  = "ba"   # b→a similarity (convergence_test.rb)
+thr = "thr"  # thread handle (connection_poller_test.rb)

data/docs/api/index.md

@@ -41,8 +41,8 @@ confines them:
 | [AgentSkill](skills.md#robotlabagentskill) | One skill bundle: instructions + `scripts/` |
 | [AgentSkillCatalog](skills.md#robotlabagentskillcatalog) | Lazy registry over `~/.prompts/skills/` |
 | [Capabilities](skills.md#robotlabcapabilities) | Declared vs. ceiling filesystem / network / timeout grant |
-| [ScriptTool](skills.md#robotlabscripttool) | Wraps an executable script as a `Tool` |
-| [Sandbox](skills.md#robotlabsandbox) | macOS Seatbelt confinement, or a passthrough |
+| [ScriptTool](skills.md#robotlabscripttool) | Wraps an executable script as a `Tool`; `ScriptTool.executor` is the confinement extension point |
+| [Sandbox](skills.md#confinement-robot_lab-sandbox) | macOS Seatbelt confinement, or a passthrough — ships in the optional `robot_lab-sandbox` gem |
 
 ## Support Classes
 

data/docs/api/skills.md

@@ -1,8 +1,12 @@
 # Skills API
 
 Class-level reference for the AgentSkills subsystem: skill bundles, the scripts
-they expose as tools, the capabilities those scripts declare, and the sandbox
-that confines them. For the how-to, see
+they expose as tools, and the capabilities those scripts declare. Core itself
+has **no sandboxing and no execution limitations** — every script runs
+unconfined until the optional
+[`robot_lab-sandbox`](https://github.com/MadBomber/robot_lab-sandbox) gem is
+required, at which point it installs a confinement strategy (see
+[ScriptTool.executor](#scripttoolexecutor) below). For the how-to, see
 [Using Tools: Skill Scripts and Sandboxing](../guides/using-tools.md#skill-scripts-and-sandboxing)
 and [Building Robots: Composable Skills](../guides/building-robots.md#composable-skills).
 
@@ -27,12 +31,16 @@ graph LR
         G[effective grant<br/>declared ∩ ceiling]
     end
 
-    subgraph "Execution"
+    subgraph "Execution (core)"
         T[ScriptTool.from_path<br/>-> RobotLab::Tool]
+        EX{ScriptTool.executor<br/>set?}
+        UN[Open3.capture2e<br/>unconfined, no timeout]
+    end
+
+    subgraph "robot_lab-sandbox (optional gem)"
         SB{Sandbox.enabled?}
         SE[Sandbox::Seatbelt<br/>macOS]
         NU[Sandbox::Null<br/>passthrough]
-        P[script process]
     end
 
     R[Robot<br/>AgentSkillMatching] --> C
@@ -41,12 +49,12 @@ graph LR
     S --> T
     D --> G
     CE --> G
-    T --> SB
+    T --> EX
+    EX -- "nil (default)" --> UN
+    EX -- "installed" --> SB
     SB -- "off, or trust: core,<br/>or non-macOS" --> NU
     SB -- "on + macOS" --> SE
     G --> SE
-    SE --> P
-    NU --> P
 ```
 
 ---
@@ -264,9 +272,9 @@ of the ceiling, and `intersect` keeps the declared value.
 capabilities.core?  # => trust == "core"
 ```
 
-A `core` skill is exempt from confinement: `Sandbox.for` returns a
-[`Null`](#robotlabsandboxnull) strategy for it regardless of platform or config.
-Reserve `trust: core` for bundles you wrote and audited.
+A `core` skill is exempt from confinement: when `robot_lab-sandbox` is loaded,
+`Sandbox.for` returns a `Null` strategy for it regardless of platform or
+config. Reserve `trust: core` for bundles you wrote and audited.
 
 ### intersect
 
@@ -314,43 +322,32 @@ The generated tool takes a single optional `args` string parameter, which is
 [`derive_name`](#scripttoolderive_name) and its description from
 [`extract_description`](#scripttoolextract_description).
 
-### ScriptTool.execute
+### ScriptTool.executor
 
 ```ruby
-RobotLab::ScriptTool.execute(cmd, capabilities:, skill_dir:)  # => String
+RobotLab::ScriptTool.executor          # => #call, or nil (the default)
+RobotLab::ScriptTool.executor = obj    # any object responding to
+                                        # call(cmd, capabilities:, skill_dir:)
 ```
 
-Run a command array and return its combined stdout+stderr, or an error string.
-Two paths:
-
-- **Sandboxing off** (the default) — `Open3.capture2e`, unconfined, **no timeout**.
-- **Sandboxing on** — intersects `capabilities` with `Capabilities.ceiling`, wraps
-  the command with the strategy from `Sandbox.for`, runs it under the grant's
-  timeout, and cleans the strategy up in an `ensure`.
-
-The declared `timeout:` therefore only takes effect when sandboxing is enabled.
+The extension point core exposes for confinement. `nil` by default — core has
+no sandboxing of its own. `robot_lab-sandbox`, when required, sets this to
+`RobotLab::Sandbox::Executor`, which handles `capabilities`/timeout/cleanup
+itself. See that gem's docs for what it does when installed.
 
-### ScriptTool.run_with_timeout
+### ScriptTool.execute
 
 ```ruby
-RobotLab::ScriptTool.run_with_timeout(cmd, timeout)
-# => [String, Process::Status | nil]
+RobotLab::ScriptTool.execute(cmd, capabilities:, skill_dir:)  # => String
 ```
 
-Run `cmd` in its own process group (`pgroup: true`), reading combined output
-until `timeout` seconds elapse. On expiry it terminates the group and returns
-`["<partial output>\n[killed: exceeded <N>s]", nil]` — a `nil` status is the
-timeout signal.
-
-### ScriptTool.terminate
-
-```ruby
-RobotLab::ScriptTool.terminate(pid)
-```
+Run a command array and return its combined stdout+stderr, or an error string.
+Two paths:
 
-`Process.kill('-TERM', ...)` against the process **group** of `pid`, so a script
-that spawned children takes them down with it. Swallows every error and returns
-`nil` — a process that already exited is not an error.
+- **`executor` is `nil`** (the default) — `Open3.capture2e`, unconfined, **no timeout**.
+- **`executor` is set** — delegates entirely to `executor.call(cmd, capabilities:, skill_dir:)`.
+  Core no longer knows or cares what the executor does with `capabilities` or
+  how (or whether) it bounds execution time.
 
 ### ScriptTool.format_result
 
@@ -393,121 +390,27 @@ cannot be read.
 
 ---
 
-## RobotLab::Sandbox
+## Confinement: robot_lab-sandbox
 
-Strategy selector for confining skill-script execution. Module functions.
-
-### Sandbox.enabled?
-
-```ruby
-RobotLab::Sandbox.enabled?              # => Boolean
-RobotLab::Sandbox.enabled?(some_config)
-```
-
-`true` only when the config responds to `sandbox`, that section exists, and
-`sandbox.enabled == true`. **Sandboxing is off by default** — see the
-[`sandbox:` config section](../getting-started/configuration.md#skill-script-sandboxing-sandbox-section).
-
-### Sandbox.macos?
-
-```ruby
-RobotLab::Sandbox.macos?  # => RUBY_PLATFORM.include?("darwin")
-```
-
-### Sandbox.for
-
-```ruby
-strategy = RobotLab::Sandbox.for(grant, skill_dir:, macos: macos?)
-# => Sandbox::Seatbelt or Sandbox::Null
-```
-
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `grant` | `Capabilities` | **required** | The **already-intersected** effective grant |
-| `skill_dir` | `String` | **required** | Bundle root, always granted read access |
-| `macos` | `Boolean` | `macos?` | Injectable so both branches are testable on any host |
+`RobotLab::Sandbox`, `RobotLab::Sandbox::Seatbelt`, and `RobotLab::Sandbox::Null`
+used to live here; they now ship in the separate
+[`robot_lab-sandbox`](https://github.com/MadBomber/robot_lab-sandbox) gem, which
+core has no dependency on. Requiring it installs `RobotLab::Sandbox::Executor`
+as [`ScriptTool.executor`](#scripttoolexecutor):
 
-Selection order: a `trust: core` grant gets `Null`; otherwise macOS gets
-`Seatbelt`; anything else warns once and gets `Null`.
-
-### Sandbox.warn_once_non_macos
-
-```ruby
-RobotLab::Sandbox.warn_once_non_macos
-```
-
-Emits `"Sandbox: OS-level confinement is only available on macOS; scripts run
-unconfined here"` at `warn`, at most once per process. Idempotent, so a run with
-many scripts does not flood the log.
-
----
-
-## RobotLab::Sandbox::Null
-
-Passthrough strategy — used off macOS and for `trust: core` skills.
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `wrap(cmd)` | `cmd` | Unchanged |
-| `cleanup` | `nil` | No-op |
-
----
-
-## RobotLab::Sandbox::Seatbelt
-
-macOS strategy: generates a deny-by-default `sandbox-exec` profile from the grant
-and wraps the command as `sandbox-exec -f <profile> <cmd...>`.
-
-### Constants
-
-| Constant | Description |
-|----------|-------------|
-| `SYSTEM_READ` | `/usr /bin /sbin /System /Library /opt /private/etc /dev /var/select` — the locations an interpreter needs to boot |
-| `DEV_WRITE` | `/dev/null /dev/stdout /dev/stderr /dev/dtracehelper /dev/tty` — always writable |
-
-### Constructor
-
-```ruby
-RobotLab::Sandbox::Seatbelt.new(grant, skill_dir:)
-```
-
-### wrap / cleanup
-
-```ruby
-cmd = strategy.wrap(["bash", "script.sh"])
-# => ["sandbox-exec", "-f", "/tmp/robot_lab-sandbox-xxxx.sb", "bash", "script.sh"]
-strategy.cleanup  # unlinks the generated profile
-```
-
-`wrap` writes the profile to a `Tempfile`; `cleanup` unlinks it and swallows any
-error (an already-removed file is fine). `ScriptTool.execute` always calls
-`cleanup` in an `ensure`.
-
-### profile_text
-
-```ruby
-strategy.profile_text  # => String
-```
+- `Sandbox.enabled?` — reads `config.sandbox.enabled` (default `false`).
+- `Sandbox.for(grant, skill_dir:, macos: macos?)` — picks `Sandbox::Seatbelt` on
+  macOS, `Sandbox::Null` (passthrough) elsewhere or for `trust: core` grants.
+- `Sandbox::Seatbelt` — generates a deny-by-default `sandbox-exec` profile from
+  the effective grant (`fs_read`/`fs_write`/`network`), wrapping the command as
+  `sandbox-exec -f <profile> <cmd...>`. `$HOME` is never implicitly readable.
+- `Sandbox::Null` — `wrap(cmd)` returns `cmd` unchanged; `cleanup` is a no-op.
+- `Sandbox::Executor` — the piece that plugs into core: intersects the skill's
+  `Capabilities` with `Capabilities.ceiling`, wraps and runs the command under
+  the chosen strategy, and bounds it with the grant's `timeout`
+  (`Process.kill('-TERM', ...)` on the process group on expiry).
 
-The generated Seatbelt profile. Public so the policy can be asserted in tests
-rather than inferred from behavior. It imports `bsd.sb` (without which a
-deny-default profile aborts the binary before it starts), denies by default, then
-allows: `process-fork`, `process-exec`, `sysctl-read`, `mach-lookup`,
-`file-read-metadata` on any path, `file-read*` on `SYSTEM_READ` + the skill
-directory + granted `fs_read` paths, `file-write*` on `DEV_WRITE` + granted
-`fs_write` paths, and `network*` only when the grant allows it.
-
-Every path is canonicalized to its symlink-free real path first, because macOS
-symlinks `/tmp` → `/private/tmp` and the kernel matches against the real path. For
-write targets that do not exist yet, the nearest existing ancestor is resolved and
-the remainder re-appended.
-
-!!! warning "`$HOME` is never implicitly readable"
-    Which is the point — SSH keys and cloud credentials stay out of reach. But it
-    also means an interpreter installed under `$HOME` (rbenv, asdf, mise, a
-    Homebrew prefix in `~`) is **invisible** to the sandboxed process and the
-    script fails to start. Grant that path explicitly in `fs_read`, or mark the
-    skill `trust: core`.
+Full reference lives in that gem's own docs.
 
 ---
 
@@ -515,5 +418,6 @@ the remainder re-appended.
 
 - [Using Tools: Skill Scripts and Sandboxing](../guides/using-tools.md#skill-scripts-and-sandboxing)
 - [Configuration: `sandbox:` section](../getting-started/configuration.md#skill-script-sandboxing-sandbox-section)
+- [robot_lab-sandbox](https://github.com/MadBomber/robot_lab-sandbox) — the optional confinement gem
 - [Robot: Skills](core/robot.md#skills) — template skills, the other meaning
 - [Tool](core/tool.md) — `Tool.create`, which `ScriptTool` builds on

data/docs/api/support.md

@@ -842,5 +842,5 @@ Thread-safe monotonic counter for event ordering.
 
 - [Core Classes](core/index.md) — `Robot`, `Network`, `Memory`, `Tool`, `RobotResult`
 - [Hooks API](hooks.md) — the extension seam these classes are wired into
-- [Skills API](skills.md) — `AgentSkill`, `Capabilities`, `ScriptTool`, `Sandbox`
+- [Skills API](skills.md) — `AgentSkill`, `Capabilities`, `ScriptTool` (confinement lives in the optional `robot_lab-sandbox` gem)
 - [Errors](errors.md) — including `Errors.retryable?` and `Errors.retryable_classes`

data/docs/architecture/index.md

@@ -62,7 +62,7 @@ graph TB
         H[MCP Client]
         I[Tools < RubyLLM::Tool]
         J[Templates / prompt_manager]
-        SK[AgentSkills + Sandbox]
+        SK[AgentSkills<br/>+ optional Sandbox]
     end
 
     subgraph "Execution Layer"
@@ -138,8 +138,9 @@ graph LR
     AS --> CAT[AgentSkillCatalog]
     AS --> CAP[Capabilities]
     AS --> ST[ScriptTool]
-    CAP --> SB[Sandbox<br/>Seatbelt or Null]
-    ST --> SB
+    ST --> EX{ScriptTool.executor}
+    EX -. "installed by<br/>robot_lab-sandbox" .-> SB[Sandbox<br/>Seatbelt or Null]
+    CAP -. "used if installed" .-> SB
 
     HC --> TA[TextAnalysis<br/>TF / TF-IDF]
     HS --> TA
@@ -165,7 +166,7 @@ dependency.
 | **Config** | MywayConfig-based global configuration with env var and file support | [Configuration](#configuration) |
 | **Hook** | Handler base class for the seven hook families — the framework's extension seam | [Hooks API](../api/hooks.md) |
 | **AgentSkill** | A `SKILL.md` bundle whose instructions and `scripts/` become prompt text and tools | [Skills API](../api/skills.md) |
-| **Sandbox** | Opt-in OS-level confinement (macOS Seatbelt) for skill scripts, derived from `Capabilities` | [Skills API](../api/skills.md) |
+| **Sandbox** | Opt-in OS-level confinement (macOS Seatbelt) for skill scripts, derived from `Capabilities`; ships in the optional `robot_lab-sandbox` gem, not core | [Skills API](../api/skills.md) |
 | **RobotMessage** | Immutable envelope for TypedBus inter-robot messaging, serialized per robot by `BusPoller` | [Support API](../api/support.md) |
 | **Budget::Ledger** | Thread-safe reserve/reconcile ledger behind `token_budget` / `cost_budget` | [Support API](../api/support.md) |
 

data/docs/getting-started/configuration.md

@@ -278,7 +278,10 @@ robot = RobotLab.build(
 
 ### Skill-Script Sandboxing (`sandbox:` section)
 
-Opt-in confinement for the scripts a [skill bundle](../guides/using-tools.md#skill-scripts-and-sandboxing) exposes as tools. Disabled by default — scripts run exactly as before until you turn it on:
+Core declares this config schema but has no sandboxing behavior of its own — enforcement
+lives in the optional [`robot_lab-sandbox`](https://github.com/MadBomber/robot_lab-sandbox)
+gem. Without it, skill scripts always run unconfined regardless of these values; requiring
+it installs a `RobotLab::ScriptTool.executor` that honors them:
 
 | Key | Default | Description |
 |-----|---------|-------------|