little_ghost 0.4.0 → 0.5.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
 
@@ -116,6 +118,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
@@ -130,11 +140,16 @@ 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.
 
-## 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 +157,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 +236,17 @@ 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. 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 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.
 

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`.

data/docs/guides/skills.md

@@ -0,0 +1,141 @@
+# Give Agents Skills
+
+A Skill is a reusable instruction package that an Agent can discover by name
+and load when a task needs it. Skills keep specialized procedures out of the
+Agent's main prompt.
+
+## Write one focused skill
+
+Create `app/skills/refund_guide/SKILL.md`:
+
+```markdown
+---
+name: refund_guide
+description: Determine which refund guidance applies to a customer request.
+allowed-tools:
+  - help_center_lookup
+compatibility: Requires the refunds help-center collection.
+---
+
+# Apply the refund guidance
+
+1. Load the current refund entry with `help_center_lookup`.
+2. Compare the purchase date and item category with the returned guidance.
+3. State which facts support the decision and which facts are still missing.
+4. Return the analysis to the application instead of issuing a refund.
+```
+
+Each immediate child of a configured skill root may contain one `SKILL.md`.
+Front matter requires a single-line `name` and `description`. Names contain
+only letters, numbers, underscores, and hyphens. `allowed-tools` and
+`compatibility` are optional information shown to the model.
+
+A Skill may also include supporting files in `references/`, `scripts/`, or
+`assets/`. Keep the main instructions short and point to a resource only when
+the task needs it.
+
+## Let an Agent discover skills
+
+The conventional root is `app/skills`:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  system_prompt "Use an available skill when a request needs a documented procedure."
+  tools HelpCenterLookupTool
+  skills
+end
+```
+
+At runtime, the Agent receives a short catalog of skill names, descriptions,
+and locations. The generated `skills` Tool loads the full instructions when
+the model selects one. An empty catalog adds nothing to the prompt and no Tool.
+
+You can use another application-owned directory or expose only selected
+skills:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  skills paths: [File.expand_path("../../support_skills", __dir__)],
+    only: %w[refund_guide]
+end
+```
+
+Paths may also come from a callable resolved for each Run. Build the path from
+application configuration, not from a path supplied by the model or request.
+
+## Pair instructions with Tools
+
+`allowed-tools` tells the model which Tools a Skill expects. It doesn't add or
+enable those Tools. The Agent's `tools` declaration remains the source of what
+the model can call, and each Tool applies its normal application checks.
+
+This separation makes Skills safe to use as guidance: changing a Markdown file
+can change what the Agent tries, but it can't grant a new Tool, provider,
+filesystem path, or credential.
+
+> **Safety note:** Keep configured skill directories under application control
+> and review Skill changes as prompt changes. A Skill can contain mistaken or
+> outdated instructions, so application code should continue to check any
+> operation that has side effects.
+
+## Make resources available to code mode
+
+Ordinary Skill loading needs no Workspace configuration. If model-authored code
+also needs to read Skill resources, give those resources a stable model-visible
+location:
+
+```ruby
+require "fileutils"
+require "tmpdir"
+
+skill_root = File.expand_path("../../app/skills", __dir__)
+
+LittleGhost.configure do |config|
+  config.skill_paths = [skill_root]
+  config.skill_resource_root = "workspace://skills"
+
+  config.workspace = lambda do |**|
+    root = Dir.mktmpdir("little-ghost-skills-")
+    LittleGhost::Workspace.new(
+      root:,
+      paths: {skills: skill_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, skills: :read_only},
+    root_filesystem: :isolated,
+    network: :none
+  }
+end
+```
+
+The named Workspace path maps the configured Skill directory, and the Sandbox
+makes it readable without allowing model-authored code to change it. The model
+can then ask the Filesystem Tool for a path such as
+`workspace://skills/refund_guide/references/example.md` without learning the
+host's directory layout. [Workspaces and Sandboxes](sandboxing.md) explains how
+to adapt the temporary root, backend, and other grants for your application.
+
+## Write instructions that stand on their own
+
+A useful Skill tells the Agent:
+
+- When the procedure applies.
+- Which information it needs before deciding.
+- Which named Tools or resources help.
+- What result the caller expects.
+- Which action remains with the application.
+- What to do when information is missing or conflicts.
+
+Use direct instructions and stable domain language. Avoid repeating the
+Agent's general prompt or relying on Tool behavior that the Tool description
+doesn't promise.
+
+Continue with [Workspaces and Sandboxes](sandboxing.md) when model-authored code
+needs Skill resources. See [Tools](tools.md) for Tool validation, bindings, and
+side effects.