little_ghost 0.4.0 → 0.6.0

data/docs/guides/production.md

@@ -39,7 +39,9 @@ end
 
 Provider connections and model roles can also live in YAML files under `config/little_ghost`, or in files you select explicitly. Values set in Ruby take priority. An explicitly selected file comes next, followed by conventional files and environment defaults. See `LittleGhost::Configuration` when you need every supported source and override.
 
-Prompts, caller input and history, tool results, and attachments may leave the application for the selected external provider. Select providers from trusted configuration and account for their retention and data-residency policies.
+Prompts, caller input and history, Tool results, and attachments may go to the
+selected provider. Choose configured providers that are appropriate for that
+data and its retention or residency needs.
 
 ## Configure once, call from anywhere
 
@@ -73,6 +75,103 @@ The controller supplies identity and account access from authenticated applicati
 
 Configure LittleGhost before the first Agent or Assembly call. Once application services start successfully, the configuration is locked so every request sees one stable setup.
 
+## Use an existing fiber scheduler
+
+If your application already runs inside a Ruby Fiber scheduler, LittleGhost
+uses it for parallel Tool calls, Workflow and Graph branches, subagent turns,
+background Executions, and nested code-mode Tool calls. LittleGhost does not
+install or run a scheduler. Your scheduler must support `Fiber.schedule`. The
+optional `async` gem used below does.
+
+For example, an application using the optional `async` gem can let several
+requests make progress on one thread while each request waits for network I/O.
+Add `gem "async"` to the application's bundle, then start the calls inside an
+Async task:
+
+```ruby
+require "async"
+
+questions = [
+  "How long do refunds take?",
+  "Can I update my delivery address?"
+]
+
+answers = Async do |task|
+  questions.map do |question|
+    task.async { CustomerSupportAgent.ask(question).response }
+  end.map(&:wait)
+end.wait
+```
+
+The default `:auto` setting uses fibers when a call begins inside a scheduled
+fiber and worker threads everywhere else. Set `concurrency_backend` to `:fiber`
+when calling outside a scheduled fiber should be an application error.
+LittleGhost then raises `LittleGhost::ConfigurationError` instead of quietly
+starting a thread.
+
+### Keep one blocking call from pausing other fibers
+
+Fiber scheduling helps while work waits for I/O; it does not make CPU-heavy
+Ruby code run in parallel. Whether an I/O call lets other fibers run depends on
+the Ruby version, scheduler, and library. Call libraries normally at first. If
+documentation or measurement shows that one call pauses the other fibers—and
+the work can continue on another Ruby thread—wrap that call:
+
+```ruby
+article = LittleGhost.offload_blocking do
+  HelpCenterSearch.lookup(question)
+end
+```
+
+Outside a scheduled fiber, `offload_blocking` runs the block inline. Inside one,
+it uses LittleGhost's shared pool of reusable threads so the other fibers can
+continue. If the caller is cancelled after the pool accepts the block,
+LittleGhost waits for the block to finish before reporting the cancellation.
+The helper does not add a timeout or cancellation mechanism to the underlying
+call, so use the library's controls when available.
+
+If most of your Tool or extension code prevents other fibers from running, use
+worker threads for all LittleGhost concurrency instead:
+
+```ruby
+LittleGhost.configure do |config|
+  config.concurrency_backend = :thread
+end
+```
+
+LittleGhost also keeps a few jobs on threads so it can finish or clean them up
+reliably. Provider and subprocess streams may use dedicated threads. Inside a
+scheduled fiber, certificate generation and Filesystem SessionStore
+transactions use the same shared pool as `offload_blocking`. A Run may
+therefore still create or use threads when its concurrency backend is `:fiber`.
+
+The blocking pool allows two operations at a time by default. Applications
+that observe calls waiting for a pool worker can increase its process-wide
+capacity during startup, before any call can start the pool:
+
+```ruby
+LittleGhost.configure do |config|
+  config.blocking_pool_capacity 4
+end
+```
+
+Increasing this value permits more operating-system threads. It does not
+change Tool, Workflow, Graph, or subagent concurrency. The value is
+process-wide; every `Configuration` reads and writes the same setting.
+
+### Protect state shared by concurrent calls
+
+LittleGhost may call a shared Tool, provider, SessionStore, hook, or callback
+from different threads. Fibers can also take turns entering the same object on
+one thread. Protect shared mutable state, keep lock scope narrow, and do not
+call application callbacks while holding a lock.
+
+Pass request-specific values through the Invocation context or another explicit
+argument. Do not use `thread_variable_set` for request state because every
+fiber on the thread shares those values. `Thread.current[:key]` is fiber-local,
+but LittleGhost does not copy application-defined entries into each worker
+task.
+
 ## Preserve conversation with Sessions
 
 A **Session** lets one request continue an earlier conversation. Pass the same session ID and trusted actor ID with each related call:
@@ -104,7 +203,8 @@ Every Run has a session ID so LittleGhost can checkpoint its progress. If you do
 
 ## Stream or supervise long-running work
 
-`.stream_ask` runs on the caller's thread and yields `StreamEvent` values as the answer arrives:
+`.stream_ask` runs on the caller's fiber or thread and yields `StreamEvent`
+values as the answer arrives:
 
 ```ruby
 stream = CustomerSupportAgent.stream_ask(question)
@@ -116,6 +216,14 @@ end
 record_outcome(run.outcome, error_type: run.error&.class&.name)
 ```
 
+Composite assembly streams include intermediate and nested Agent work as `:agent_stream` events. This default also applies to the event consumer passed to `start_execution`. Pass `include_agent_events: false` when only the ordinary public stream is needed.
+
+> **Safety note:** Contextual events can include inputs, reasoning, Tool
+> arguments and results, errors, and output from every participant. Check that
+> the destination may see the complete Run, or filter the events before sending
+> or storing them. LittleGhost's AG-UI adapter ignores these events unless the
+> application translates them explicitly.
+
 Use `start_execution` when the caller must stay free for other work, or when you want to deliver an interjection to an active response:
 
 ```ruby
@@ -128,13 +236,24 @@ execution.wait(deadline: Time.now + 30)
 execution.run.completed?
 ```
 
-The event block runs on the worker thread, so keep it quick. Cancellation, deadlines, and `close` ask the work to stop; they cannot forcibly end arbitrary provider or tool code. They also cannot undo actions that already happened.
+The event block runs on the same fiber or thread as the Execution. With `:auto`,
+`start_execution` uses a fiber when its caller is already in a scheduled fiber;
+otherwise, it uses a worker thread. Keep the block quick because it slows event
+delivery while it runs. Cancellation, deadlines, and `close` ask the work to
+stop; they cannot forcibly end arbitrary provider or Tool code or undo actions
+that already happened. Keep the application's scheduler running until an
+Execution using it finishes or closes.
 
-## Treat tools as application boundaries
+## Keep Tool permission checks in application code
 
-A tool schema checks the shape of model-supplied input. Your application still owns permission checks, safe retries, rate limits, tenant boundaries, and auditing.
+A Tool schema checks the shape of model-supplied input. Your application still
+owns permission checks, safe retries, rate limits, and auditing. An ordinary
+Tool runs in the Ruby process; a Sandbox contains only file or child-process
+work that deliberately passes through it.
 
-Use the Tool binding's `run` to read current, application-established values from `run.invocation.context`. Do not make permission decisions from model arguments.
+Use the Tool binding's `run` to read current, application-established values
+from `run.invocation.context`. Don't rely on model arguments for identity or
+account membership.
 
 Treat `RunContext#state` as mutable working and Session state. Revalidate anything restored from an earlier request. Synchronize access when parallel Tools share mutable state, or mark every Tool that reads or changes it as `exclusive true`.
 
@@ -142,27 +261,72 @@ A `ToolError` message is visible to the model, so keep it safe to share. LittleG
 
 When a step retries, its tool calls may happen again too. Prefer read-only work, idempotency keys, or operations that are safe to repeat.
 
+[Tools](tools.md) develops this pattern from the first application Tool through
+bindings, concurrency, sandbox delegation, and code mode.
+
 ## Choose workspace and sandbox behavior explicitly
 
-A Workspace gives one Run a place for files. A Sandbox decides how filesystem and process operations happen there.
+A **Workspace** names the host paths associated with a Run. A **Sandbox**
+controls filesystem operations and child processes deliberately sent through
+it. A custom Ruby Tool stays in the application process unless it delegates
+work to the bound Sandbox.
+
+The dependency-free default is an application-root Workspace with `LittleGhost::Sandboxes::Unrestricted`. It is not process or network isolation. Select an enforcing backend explicitly when a model can influence commands; LittleGhost raises when that backend is unavailable instead of silently falling back:
+
+```ruby
+require "fileutils"
+require "tmpdir"
+
+LittleGhost.configure do |config|
+  config.workspace = lambda do |**|
+    root = Dir.mktmpdir("little-ghost-support-")
+    LittleGhost::Workspace.new(
+      root:,
+      teardown: lambda do |workspace:, **|
+        FileUtils.remove_entry_secure(workspace.root) if File.exist?(workspace.root)
+      end
+    )
+  end
+  config.sandbox = {
+    provider: :native,
+    files: {root: :read_write},
+    root_filesystem: :isolated,
+    environment: {inherit: false, set: {"LANG" => "C.UTF-8"}},
+    network: :none
+  }
+end
+```
+
+The temporary Workspace above is useful when files should live for one Run. Use application-managed storage, with tenant isolation and concurrency control, when files must persist or several Runs share a root.
+
+The Run opens a Runtime-created Workspace before its Sandbox and closes them in reverse order after every outcome. Closing a Workspace invokes its configured teardown; it does not delete files by default. Cleanup failures raise because LittleGhost cannot confirm a clean shutdown of every owned resource. Existing instances passed by the application remain caller-owned.
 
-`LittleGhost::UnrestrictedSandbox` uses the host machine with the Ruby process's permissions. It does not contain untrusted code. Expose only the tools the model needs, and use a real isolation boundary when untrusted code must run.
+[Workspaces and Sandboxes](sandboxing.md) explains backend selection, logical
+Workspace paths, files, process-only runtime paths, Scopes, filtered
+networking, and deployment validation in depth.
 
-The Run closes workspaces and sandboxes that LittleGhost creates for it. If your application passes an existing instance instead, your application keeps ownership and must close it when its own lifecycle ends.
+[Code Mode](code_mode.md) applies that setup to model-authored Ruby or
+optional JavaScript that composes the Agent's existing Tools.
 
-## Instrument without leaking the application
+## Protect data in telemetry
 
 LittleGhost emits events as a request starts, calls a model or tool, moves between assembly steps, retries, and finishes. Instrumentation subscribers and OpenTelemetry exporters can send those events to your monitoring system.
 
-An external telemetry service may receive application identifiers and event data. Redact sensitive values before they leave your boundary. Avoid attributes with many unique values, such as raw order or request IDs. Replacing one identifier does not make the rest of the data anonymous.
+An external telemetry service may receive application identifiers and event
+data. Redact sensitive values before exporting them. Avoid attributes with many
+unique values, such as raw order or request IDs.
 
-A composite `RunResult` includes short step summaries and trajectory queries. Keep detailed provider errors and sensitive diagnostics in trusted monitoring channels, not in model or user responses.
+A composite `RunResult` includes short step summaries and trajectory queries.
+Keep detailed provider errors and sensitive diagnostics in your monitoring
+system, not in model or user responses.
 
-## Keep ownership and failure visible
+## Know what the Run closes and raises
 
 One top-level Run owns the workspace and sandbox that LittleGhost creates for it, plus application resources registered with `run.register`. It closes those resources after success, failure, a partial response, or cancellation. Existing workspace or sandbox instances passed by the application remain caller-owned.
 
-Ordinary execution failures appear on the Run and its final event. Cleanup, event delivery, or instrumentation can still raise an exception: once those boundaries fail, LittleGhost cannot promise a clean ending.
+Ordinary execution failures appear on the Run and its final event. Cleanup,
+event delivery, or instrumentation can still raise an exception when
+LittleGhost cannot promise a clean ending.
 
 ## Advanced: work with Runtime directly
 
@@ -176,11 +340,20 @@ runtime = LittleGhost::Runtime.new(configuration: configuration)
 agent = CustomerSupportAgent.new(runtime: runtime)
 ```
 
-An explicit Runtime is an independent configuration snapshot. It does not replace LittleGhost's shared default.
+An explicit Runtime has its own independent configuration. It does not replace
+LittleGhost's shared default.
 
-One Runtime can serve independent calls from several threads. Each call gets its own Run, participants, Tools, and Runtime-created workspace and sandbox. An Agent or Assembly already bound to an active Run must stay with that Run.
+One Runtime can serve independent calls from several threads and fibers. Each
+call gets its own Run, participants, Tools, and Runtime-created Workspace and
+Sandbox. An Agent or Assembly already bound to an active Run must stay with
+that Run.
 
-Within one SessionStore instance, LittleGhost serializes calls sharing a Session. Multi-process deployments need coordination from their store. Custom stores, identity and credential resolvers, model resolvers, hooks, instrumentation subscribers, providers, and resource factories may receive concurrent calls and must be thread-safe.
+Within one SessionStore instance, LittleGhost serializes calls sharing a
+Session. Multi-process deployments need coordination from their store. Custom
+stores and other shared extension objects may receive concurrent calls. Calls
+can overlap on different threads, or fibers can take turns entering the same
+object on one thread. Protect shared mutable state without relying on thread
+identity.
 
 Runtime has no shutdown step. Shared services supplied by the application keep their own lifecycle. Shut those services down with the rest of your application. If you installed process-wide instrumentation subscribers, flush or shut down `LittleGhost::Instrumentation` during application shutdown.
 

data/docs/guides/prompt_views.md

@@ -2,7 +2,7 @@
 
 A short prompt fits nicely inside an Agent class. As the instructions grow, move them into a **prompt view**: an ERB file that LittleGhost finds and renders for the Agent.
 
-This keeps the Agent easy to scan. It also gives shared instructions and application values a natural home.
+This keeps the Agent definition focused. It also gives shared instructions and application values a natural home.
 
 ## Start with the inline prompt
 
@@ -90,7 +90,7 @@ You are a customer support agent for <%= company_name %>.
 
 The underscore marks a partial. Its locals are explicit, so it does not quietly inherit everything available to the parent view.
 
-## Override the convention when it helps
+## Choose a different template path
 
 Most named Agents can rely on their conventional path. Use `system_template` when a class should read a differently named view:
 
@@ -106,15 +106,20 @@ LittleGhost chooses one prompt source in this order:
 2. An explicit `system_template`
 3. The Agent's conventional `system.erb` view
 
-Applications can add prompt lookup roots through `Configuration#prompt_paths`. Earlier roots win, which is useful when one trusted application layer overrides a shared prompt package.
+Applications can add prompt lookup roots through `Configuration#prompt_paths`.
+Earlier roots win, which lets application code override a shared prompt package.
 
 ## Treat views as application code
 
-Prompt views run as ERB inside the Ruby process. They can call Ruby, so keep every prompt directory application-controlled and non-user-writable. Never turn a request or model-supplied path into a prompt root.
+Prompt views run as ERB inside the Ruby process and can call Ruby. Keep prompt
+directories with the rest of your application code rather than letting a
+request choose one.
 
-`TrustedPath` exists for the uncommon case where trusted application code selects a request-specific root. It records a trust decision; it does not make an untrusted directory safe.
+`TrustedPath` is available for the uncommon case where application code selects
+a request-specific root. It marks that choice explicitly; it does not inspect
+or restrict the directory.
 
-## Keep request composition separate
+## Build request-specific input in a Workflow
 
 A prompt view defines reusable instructions for one Agent. A Workflow may still build request-specific input for that Agent:
 
@@ -129,4 +134,6 @@ MESSAGE
 
 The Workflow is composing this request. `CustomerSupportAgent` still receives its own system prompt view when it runs.
 
-Continue with [Running in Production](production.md) to configure model roles, preserve sessions, supervise execution, and connect observability.
+Continue with [Tools](tools.md) to give those Agents application capabilities
+while keeping model input, trusted context, and delegated sandbox operations
+distinct.

data/docs/guides/sandboxing.md

@@ -0,0 +1,282 @@
+# Workspaces and Sandboxes
+
+A Workspace gives one Run—one top-level Agent or Assembly execution—a stable
+set of host paths. A Sandbox decides which operations may reach those paths and
+how child processes are contained.
+
+Use them together when an Agent can read files, change files, or run programs:
+
+```ruby
+require "fileutils"
+require "tmpdir"
+
+LittleGhost.configure do |config|
+  config.workspace = lambda do |**|
+    root = Dir.mktmpdir("little-ghost-support-")
+    LittleGhost::Workspace.new(
+      root:,
+      teardown: lambda do |workspace:, **|
+        FileUtils.remove_entry_secure(workspace.root) if File.exist?(workspace.root)
+      end
+    )
+  end
+
+  config.sandbox = {
+    provider: :native,
+    files: {root: :read_write},
+    root_filesystem: :isolated,
+    environment: {inherit: false, set: {"LANG" => "C.UTF-8"}},
+    network: :none
+  }
+end
+```
+
+This example gives each Run a temporary writable root and removes it during
+teardown. The `:native` Sandbox backend selects Seatbelt on macOS or Bubblewrap on
+Linux. It raises instead of running without isolation when the native backend
+is unavailable.
+
+`LittleGhost::Tools::Filesystem` and `LittleGhost::Tools::Shell` use the Sandbox
+assigned to the current Run. Code-mode interpreters also run inside their own
+Sandbox. Ordinary application Tools, callbacks, and provider requests stay in
+the Ruby process unless they deliberately delegate an operation.
+
+The split looks like this:
+
+```text
+Ruby application process
+├── provider requests
+├── application Tool#call
+└── Sandbox
+    ├── bounded filesystem operations
+    ├── Shell child processes
+    └── code-mode interpreter processes
+```
+
+## Give files a stable home
+
+A Workspace names the files available during a Run and controls their setup and
+cleanup. Its `root` is the default working directory. Named paths give important
+directories logical identities:
+
+```ruby
+workspace = LittleGhost::Workspace.new(
+  root: "/var/lib/support/run-481",
+  paths: {
+    source: "/srv/support/source",
+    skills: "skills",
+    home: "runtime-home"
+  }
+)
+```
+
+Relative named paths live beneath the root and are created when the Workspace
+opens. Absolute named paths are references deliberately supplied by the
+application and must already exist. A setup callback can provision them when
+needed.
+
+Opening resolves real paths and records which physical directories they refer
+to. LittleGhost rejects two names that point to the same directory and later
+fails closed if a configured directory is replaced. Nested paths are allowed,
+and the most restrictive matching access wins.
+
+Workspace object lifetime and file lifetime are separate. Closing invokes the
+configured teardown callback, but does not delete files by default. Use a
+run-scoped temporary root for disposable work. Use application-managed storage,
+tenant isolation, and concurrency control when several Runs share files.
+
+## Give artifacts logical references
+
+Images and documents normally remain provider content. When filesystem Tools
+or code mode should read the same bytes, configure the conventional artifact
+path and enable artifact handling:
+
+```ruby
+LittleGhost.configure do |config|
+  config.workspace = {
+    provider: :directory,
+    root: "tmp/agent-runs",
+    paths: {artifacts: "artifacts"}
+  }
+  config.artifacts
+end
+```
+
+LittleGhost stores input images and documents after the Workspace and Sandbox
+open. The model receives the image or document in its normal input without a
+second text reference. Filesystem Tools can list `workspace://artifacts` when a
+later operation needs the stored copy. Messages added while the Run is active
+receive the same treatment.
+
+LittleGhost limits the number and size of files stored from each message and
+across the complete Run. Those limits also include Tool artifacts and oversized
+Tool results. A successful operation stores all of its files. If storage fails
+partway through, LittleGhost attempts to remove that operation's files and
+reports a cleanup error when it cannot. Stored files use private permissions,
+and the Workspace provider still owns final cleanup.
+
+Declaring the path does not grant model access. When the Agent should read it,
+grant the Sandbox access to `:artifacts` and include a filesystem Tool.
+
+## Pass logical paths, not host layout
+
+The Filesystem Tool accepts root-relative paths such as `notes/today.md`.
+Named paths use references such as
+`workspace://skills/refunds/SKILL.md`.
+
+Those references remain meaningful without exposing or translating the host
+layout. The Filesystem Tool rejects physical absolute paths. Child processes
+use the Workspace's real paths directly, start in its root, and receive
+`LITTLE_GHOST_WORKSPACE_ROOT` plus one
+`LITTLE_GHOST_WORKSPACE_<NAME>` variable for each named path.
+
+Workspace references give application code one stable path format. Each
+Sandbox backend applies the configured access using the filesystem controls
+available on its host.
+
+## Separate Tool-visible files from process support
+
+Sandbox configuration divides named paths into two groups:
+
+```ruby
+config.sandbox = {
+  provider: :native,
+  files: {
+    root: :read_write,
+    source: :read_only,
+    skills: :read_only
+  },
+  runtime_paths: {
+    home: :read_write
+  },
+  network: :none
+}
+```
+
+`files` are visible to both the Filesystem Tool and sandboxed processes.
+`runtime_paths` are process-only. Use runtime paths for interpreter libraries,
+homes, sockets, and service state that a model should not browse through a
+filesystem Tool.
+
+This is visibility, not secrecy from the process. A child with a runtime-path
+grant can use that path according to its access mode. The distinction prevents
+the Filesystem Tool from offering it as a model-visible file
+tree.
+
+## Narrow access with a Scope
+
+A `Sandbox::Scope` is a non-owning, reduced view of a Sandbox. It can remove
+paths, change writable access to read-only, remove capabilities (categories of
+allowed operations), or narrow networking. It cannot widen its parent:
+
+```ruby
+reviewer = run.sandbox.scope(
+  files: {source: :read_only},
+  runtime_paths: [],
+  capabilities: %i[filesystem_read filesystem_list],
+  network: false
+)
+```
+
+Scopes constrain only code that receives and uses the Scope. Code that keeps a
+reference to the parent Sandbox keeps the parent's authority. A Scope does not
+open or close its parent and owns no resources.
+
+## Choose how much of the host exists
+
+`root_filesystem` controls what a sandboxed process can see beyond declared
+Workspace paths:
+
+- `:isolated` exposes only declared paths and required runtime support. It is
+  the default and the right starting point for generated interpreters.
+- `:read_only` exposes the host filesystem for development commands while
+  confining writes to declared writable paths. It makes installed compilers,
+  package managers, profiles, and toolchains available, but the child can also
+  read host files unless the Ruby process already runs inside a container or VM
+  that prevents those reads.
+- `:read_write` grants the host filesystem directly. Treat it as unrestricted
+  host authority.
+
+On Seatbelt, host-visible modes permit subprocesses because development tools
+often need them. A Scope can remove `process_spawn` for a command that does not.
+
+## Choose an enforcement backend
+
+| Sandbox backend | Host | What it enforces |
+| --- | --- | --- |
+| `:native` | macOS or Linux | Selects Seatbelt on macOS and Bubblewrap on Linux; fails closed elsewhere |
+| `:seatbelt` | macOS | Deny-default Seatbelt profile over the configured physical paths |
+| `:bubblewrap` | Linux | Fresh user, PID, mount, IPC, UTS, and optional network namespaces |
+| `:unrestricted` | Ruby platforms | No containment; commands have the application process's host authority |
+
+`LittleGhost::Sandbox.probe(:native)` reports whether the platform backend is
+available. Selecting an enforcing backend never falls back to unrestricted
+execution.
+
+Bubblewrap owns descendants with a PID namespace and ends them when the
+supervising process dies. It cannot selectively deny fork inside that
+namespace, so a request for
+`allow_subprocesses: false` fails closed rather than claiming an unenforced
+restriction. Bubblewrap does not impose a task-count limit by itself. Use an
+outer cgroup or container supervisor when generated code needs a hard cap on
+the processes and threads it can create.
+
+Seatbelt can constrain spawned children, but macOS has no PID namespace. It
+terminates the command process group during cleanup; a child that deliberately
+detaches from that group may survive. Use an outer process or container
+supervisor when complete descendant ownership is required on macOS.
+
+> **Safety note:** `LittleGhost::Sandboxes::Unrestricted` is suitable for
+> application commands and tests that you would already run directly. It
+> validates paths and bounds output, but it does not isolate the command from
+> the host. Use `:native` for generated commands in production.
+
+## Keep process ownership explicit
+
+`Sandbox#start_program` returns a `Sandbox::ProcessSession` with bounded input
+and output, `alive?`, bounded `wait(timeout:)`, `terminate`, and `close`. The
+session starts the command in a process group so cleanup can stop it and its
+ordinary descendants together. It applies available CPU, memory, file, and
+output limits, requests termination, and then forces termination when needed.
+
+Callers that open a ProcessSession own it and must close it. LittleGhost fails
+closed when it cannot supervise a configured memory limit. The parent samples
+the visible process tree every 100 milliseconds, so it reacts only to memory
+present at a sample and may miss peaks between samples. On Linux, three
+consecutive failures to read the root process or the `/proc` snapshot end the
+process. Use an outer cgroup or container when memory must be enforced as a hard
+limit by the operating system.
+
+A Run closes the Workspace and Sandbox it creates after success, failure, a
+partial response, or cancellation. Application-supplied instances remain
+caller-owned.
+
+## Configure child-process networking separately
+
+Sandbox networking has three modes:
+
+- `:none` removes child networking.
+- `:inherit` permits the selected Sandbox backend's ordinary network access.
+- `:allowlist` requires an enforcing gateway: a supervised proxy that permits
+  only configured destinations.
+
+Proxy environment variables alone are not an allowlist. An external gateway
+uses named, process-only Workspace paths and verifies that they still point to
+the configured directories; it does not create a virtual path mapping.
+LittleGhost does not attest that an external proxy is ready or enforcing the
+declared destinations. The application must supervise and verify that
+gateway before giving a child network access.
+
+These settings reach only processes launched through the Sandbox. Providers,
+callbacks, and application Tool code still use the Ruby process's network
+access.
+
+Test the deployed kernel and filesystem, not only the configuration object.
+Exercise denied reads and writes, runtime paths, child creation, direct sockets,
+cancellation, limits, and cleanup before depending on the Sandbox to isolate
+generated code.
+
+Continue with [Code Mode](code_mode.md) to see how a model-authored interpreter
+uses this setup while every Tool call stays in the parent Ruby process. For
+exact setup, access, and cleanup behavior, see `LittleGhost::Workspace`,
+`LittleGhost::Sandbox`, and `LittleGhost::Sandbox::Scope`.