little_ghost 0.3.0 → 0.5.0

data/docs/guides/production.md

@@ -0,0 +1,253 @@
+# Running in Production
+
+The Agent or Assembly you ran in a script can move into a controller, job, CLI, or service without changing shape. A long-running application usually adds stable model names, shared services, conversation history, background execution, and observability.
+
+## Select models by application role
+
+A direct target keeps a small definition self-contained:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  model "openrouter:openai/gpt-5.6-luna"
+end
+```
+
+As an application grows, a **model role** gives that choice a stable application name:
+
+```ruby
+# config/initializers/little_ghost.rb
+LittleGhost.configure do |config|
+  config.providers = {
+    openrouter: {
+      adapter: :openrouter,
+      api_key: ENV.fetch("OPENROUTER_API_KEY")
+    }
+  }
+  config.models = {
+    customer_support: {
+      target: "openrouter:openai/gpt-5.6-luna",
+      settings: {temperature: 0.2}
+    }
+  }
+  config.default_model = :customer_support
+end
+
+class CustomerSupportAgent < LittleGhost::Agent
+  model :customer_support
+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 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
+
+The `LittleGhost.configure` block above is the entire initializer. Controllers and jobs can call your Agent and Assembly classes directly.
+
+Then call the Agent directly from a controller or job:
+
+```ruby
+class SupportQuestionsController < ApplicationController
+  def create
+    run = CustomerSupportAgent.ask(
+      params.require(:question),
+      actor_id: current_user.id,
+      context: {account_id: current_user.account_id}
+    )
+
+    if run.completed?
+      render json: {answer: run.response}
+    else
+      render json: {error: "Support request failed"}, status: :bad_gateway
+    end
+  end
+end
+```
+
+On the first class-level call, LittleGhost prepares model resolution, loading, prompt lookup, persistence, hooks, and factories. Later calls reuse those application services automatically.
+
+Each `.ask` creates a fresh top-level Run with fresh bound participants and Tools. Reusing application services does not create conversation history. Pass a stable `session_id` only when a later request should continue an earlier conversation.
+
+The controller supplies identity and account access from authenticated application state. The model cannot replace those values through its prompt or tool arguments. A background job uses the same direct calling style.
+
+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.
+
+## 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:
+
+```ruby
+run = CustomerSupportAgent.ask(
+  "What did we decide about my refund?",
+  session_id: "conversation-42",
+  actor_id: authenticated_user.id
+)
+```
+
+Take `actor_id` from authenticated application state. A session ID alone does not prove who the caller is, and a nil actor does not separate tenants. Built-in persistence drops system messages, temporary messages, and private reasoning. If you customize persistence, decide what else is safe to store.
+
+A session is checkpointed when its store write succeeds. The in-memory store lasts only as long as one process. Choose a durable `SessionStore` when conversations must survive a restart or continue on another process.
+
+{LittleGhost::SessionStores::Filesystem}[rdoc-ref:LittleGhost::SessionStores::Filesystem] is a built-in durable choice for a trusted local or shared filesystem. Set its root to the application-managed directory that holds session data:
+
+```ruby
+LittleGhost.configure do |config|
+  config.session_store = {
+    provider: LittleGhost::SessionStores::Filesystem,
+    root: "/var/lib/customer_support/sessions"
+  }
+end
+```
+
+Every Run has a session ID so LittleGhost can checkpoint its progress. If you do not supply one, LittleGhost generates a new ID for that call. Because your application does not reuse that generated ID, it does not create conversation continuity. A persistent SessionStore may still save working state under it before the Run finishes, so keep request context safe to store or filter sensitive fields in your store.
+
+## Stream or supervise long-running work
+
+`.stream_ask` runs on the caller's thread and yields `StreamEvent` values as the answer arrives:
+
+```ruby
+stream = CustomerSupportAgent.stream_ask(question)
+
+run = stream.each do |event|
+  publish(event) if event.type == :text_delta
+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
+execution = agent.start_execution(message: question) do |event|
+  event_buffer << event
+end
+
+execution.interject(message: "Include the latest ledger entry")
+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.
+
+## 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, 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`. 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`.
+
+A `ToolError` message is visible to the model, so keep it safe to share. LittleGhost hides unexpected exception messages from model-facing results.
+
+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** 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.
+
+[Workspaces and Sandboxes](sandboxing.md) explains backend selection, logical
+Workspace paths, files, process-only runtime paths, Scopes, filtered
+networking, and deployment validation in depth.
+
+[Code Mode](code_mode.md) applies that setup to model-authored Ruby or
+optional JavaScript that composes the Agent's existing Tools.
+
+## 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 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 your monitoring
+system, not in model or user responses.
+
+## 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 when
+LittleGhost cannot promise a clean ending.
+
+## Advanced: work with Runtime directly
+
+A Runtime is the internal home for shared model resolution, loading, persistence, hooks, and resource factories. Most applications never need to handle it: `LittleGhost.configure` and class-level `.ask` are enough.
+
+Use `LittleGhost.runtime` when an extension needs the shared object itself. Construct a separate Runtime only when one process deliberately hosts an isolated LittleGhost setup:
+
+```ruby
+configuration = LittleGhost::Configuration.new(root: isolated_root)
+runtime = LittleGhost::Runtime.new(configuration: configuration)
+agent = CustomerSupportAgent.new(runtime: runtime)
+```
+
+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.
+
+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 and
+must be thread-safe.
+
+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.
+
+For exact constructors, options, events, extension contracts, and error behavior, continue into the API reference for `LittleGhost::Configuration`, `LittleGhost::Runtime`, `LittleGhost::Run`, `LittleGhost::Execution`, `LittleGhost::Session`, `LittleGhost::Tool`, and `LittleGhost::StreamEvent`.

data/docs/guides/prompt_views.md

@@ -0,0 +1,139 @@
+# Prompts as Views
+
+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 definition focused. It also gives shared instructions and application values a natural home.
+
+## Start with the inline prompt
+
+The Agent from Getting Started keeps its first instruction close to the model:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  model "openrouter:openai/gpt-5.6-luna"
+  system_prompt "Answer customer questions clearly and concisely."
+end
+```
+
+Inline prompts are a good fit while the whole instruction is one thought.
+
+## Move a growing prompt into a view
+
+Remove `system_prompt` from the class:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  model "openrouter:openai/gpt-5.6-luna"
+  tools HelpCenterLookupTool, OrderStatusTool
+end
+```
+
+Then create `app/prompts/customer_support/system.erb`:
+
+```erb
+You help customers understand their orders and account.
+
+Answer clearly and concisely.
+Never invent company guidance. Check the help center when policy matters.
+Use the order status tool before making a claim about a private order.
+```
+
+That is enough. `CustomerSupportAgent` becomes `customer_support`, so LittleGhost looks for `customer_support/system.erb` under `app/prompts`.
+
+The prompt is still a system instruction sent to the selected model provider. Keeping it in a view improves organization; it does not keep the content inside your process.
+
+## Give the view application values
+
+Use `prompt_local` for a value the application owns:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  prompt_local :company_name, "Northstar"
+end
+```
+
+The local is available by name in the view:
+
+```erb
+You are a customer support agent for <%= company_name %>.
+Answer clearly and concisely.
+```
+
+A block can resolve a trusted value for each Agent instance. Add it to the Agent class too:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  prompt_local(:policy_version) { SupportPolicy.current_version }
+end
+```
+
+Prompt views also receive `invocation`, `run`, and `agent`. Reach for those when the instruction truly depends on the current request. Keep user wording in the caller message unless you deliberately want it inside the system instruction.
+
+Every rendered value may be sent to the model provider. Pass only data that belongs in the prompt.
+
+## Share a small partial
+
+Partials keep repeated instructions in one place. Create `app/prompts/shared/_voice.erb`:
+
+```erb
+Use a warm, direct voice for <%= company_name %>.
+Prefer one clear next step over a long list of possibilities.
+```
+
+Render it from the Agent's system view:
+
+```erb
+You are a customer support agent for <%= company_name %>.
+
+<%= partial "shared/voice", locals: {company_name: company_name} %>
+```
+
+The underscore marks a partial. Its locals are explicit, so it does not quietly inherit everything available to the parent view.
+
+## 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:
+
+```ruby
+class BillingSupportAgent < LittleGhost::Agent
+  system_template "customer_support/billing"
+end
+```
+
+LittleGhost chooses one prompt source in this order:
+
+1. An inline `system_prompt`
+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 lets application code override a shared prompt package.
+
+## Treat views as application code
+
+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` 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.
+
+## 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:
+
+```ruby
+invoke CustomerSupportAgent, input: <<~MESSAGE
+  #{input.text}
+
+  Verified research:
+  #{research}
+MESSAGE
+```
+
+The Workflow is composing this request. `CustomerSupportAgent` still receives its own system prompt view when it runs.
+
+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`.