# Code Mode

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/code_mode.html

Code mode lets an Agent solve a multi-step Tool task in one small program. The
model can gather independent results, filter them, and combine them before it
returns to the conversation. Your Ruby Tools keep their usual permission
checks.

Start by adding code mode to an Agent that already has a Tool:

```ruby
class HelpCenterLookupTool < LittleGhost::Tool
  tool_name "help_center_lookup"
  description "Find a support answer by topic."
  input_schema(
    type: "object",
    properties: {query: {type: "string"}},
    required: ["query"],
    additionalProperties: false
  )

  def call(input)
    entries = {
      "refund policy" => "Refunds are available within 30 days.",
      "shipping policy" => "Standard shipping takes three to five days."
    }
    entries.fetch(input.fetch("query"), "No matching entry.")
  end
end

class ResearchAgent < LittleGhost::Agent
  tools HelpCenterLookupTool
  code_mode
end
```

The language adapter that runs the program is called an engine. By default,
LittleGhost uses its Ruby engine and the native Sandbox for the host operating
system. It fails closed when that Sandbox is unavailable.

Code mode adds three control Tools to the conversation. `exec` starts a
program, `wait` checks on a program that is still working, and `stop` ends work
that is no longer needed. The model can now send Ruby like this to `exec`:

```ruby
results = tools.parallel(
  -> { tools.help_center_lookup(query: "refund policy") },
  -> { tools.help_center_lookup(query: "shipping policy") }
)

text(results.join("\n"))
```

LittleGhost turns the Agent's Tool schemas into Ruby method signatures. The
model sees those signatures and the available Tool names in its instructions.
Those names, descriptions, and signatures form the code-mode Tool catalog. The
model can compose the results with ordinary Ruby values instead of guessing
how to call each Tool.

## See what runs where

The program runs in a child interpreter. The Tools do not.

```text
model
  │ writes a program
  ▼
exec ──> sandboxed Ruby process
             │ tools.help_center_lookup(...)
             ▼
          Tool broker in the parent Ruby process
             │ normal Tool execution
             ▼
          HelpCenterLookupTool#call
```

The Tool broker receives interpreter calls in the parent Ruby process. It
accepts only Tools registered on the Agent, then sends each call through the
same validation, permission checks, limits, callbacks, events, and tracing used by
a direct Tool call.

Public streams show the brokered Tools by name. They omit the `exec`, `wait`,
and `stop` bookkeeping. Traces still record the control operation around its
nested Tool calls, so you can follow the complete execution.

Code mode does not change what a Tool can do. A Tool still runs as application
code, while the generated program runs in the configured Sandbox. Read
[Tools](tools.md) for Tool permission checks and [Workspaces and
Sandboxes](sandboxing.md) before giving generated programs file or process
access.

## Compose Tool calls with Ruby

Each `exec` starts a fresh Ruby process. Local variables, constants, and globals
do not carry into a later `exec`. Within one program, the model can use:

- Named methods such as `tools.help_center_lookup(query: "refund policy")`.
- `tools.call(name, arguments)` when the Tool name is dynamic.
- `tools.parallel` for independent calls whose results should preserve input
  order.
- `ALL_TOOLS` to inspect the complete runtime catalog.
- `text(value)` to add user-visible output.
- Ordinary Ruby output from `puts`, `print`, `printf`, and `p`, which is
  captured as user-visible output and combined into bounded chunks.
- The program's final expression as the completed value returned by `exec` or
  a later `wait`.
- `finish(value)` to complete early.

The dynamic form accepts either the catalog name (`"help_center_lookup"`) or
the matching method name (`"tools.help_center_lookup"`).

JSON Tool results arrive as ordinary Ruby hashes, arrays, strings, numbers,
booleans, or `nil`. When a Tool returns `Tool::Result`, code mode uses its
Ruby `value`. Artifact bytes are not copied into program variables; the
artifacts return to the model once with the surrounding `exec` or `wait`
result. Stored references appear only when native media delivery exceeds its
limit. A Tool failure raises inside the program so its Ruby code can handle the
failure or return an error.

Fresh processes keep interpreter state from leaking across programs. Each Ruby
program also gets a temporary Workspace. LittleGhost removes it when the
program ends, so files created directly by the interpreter do not carry into a
later `exec`.

A brokered filesystem Tool uses the Agent Run's separate Workspace. Files
written through that Tool follow the Run Workspace's cleanup rules and may
persist.

## Check on work that takes longer

Most programs finish while `exec` is watching them, so their result is ready in
the same Tool call. If a program is still active after one minute, `exec`
returns `still_working`. The program keeps running. The model can call `wait`
to watch for up to another minute or `stop` when it no longer needs the result.

Both `exec` and `wait` return as soon as the program finishes. The one-minute
window is a maximum observation time, not a delay added to every call.

`wait` does not resume, restart, or extend the program. It returns only output
produced since the previous `exec` or `wait`. The returned status tells the
model what to do next:

- `still_working` means the program is active. Call `wait` again when its result
  is still needed, or call `stop` to end it.
- `completed`, `error`, and `terminated` are final. There is no program to wait
  for after one of these statuses.

The built-in engines give each program a total lifetime of one hour by default.
That deadline begins at `exec` and does not reset when the model calls `wait`.
The engine ends and cleans up an expired program even if the model never checks
on it again. Applications can configure a shorter total lifetime with
`wall_seconds`; the one-minute observation window remains fixed.

A code-mode session owns the engine's active child process and related
resources. It accepts only one `exec`, `wait`, or `stop` operation at a time.
The Agent closes the session when its current call ends, including after a
failure or cancellation. Cleanup failures raise because LittleGhost cannot
claim that the child process and its resources ended cleanly.

## Keep a Tool in the conversation

With code mode enabled, ordinary Agent Tools move into the program catalog. The
model-facing controls become `exec`, `wait`, and `stop`. Use `except` when an
application Tool should remain available to the conversational model instead
of moving into the program:

```ruby
class ResearchAgent < LittleGhost::Agent
  tools HelpCenterLookupTool, ConfirmTool
  code_mode except: ["confirm_tool"]
end
```

Exclude a Tool when the conversational model should call it as a distinct
decision—for example, a final confirmation that must remain visible as its own
step. `except` uses each Tool's model-visible name; `ConfirmTool` defaults to
`confirm_tool`. Calls made inside and outside code mode share the Agent's
Tool-call limit. The `exec`, `wait`, and `stop` controls manage execution. They
do not count toward that application Tool limit themselves.

Subagent controls also stay in the conversation. They are orchestration choices
for the parent model, not functions available inside a code-mode program.
Code-mode `wait` watches an interpreter program; `wait_for_subagents` checks on
delegated Agents. [Core Concepts](core_concepts.md#subagents-bring-in-a-specialist)
explains model-directed delegation.

## Set limits for the work you expect

The Ruby engine sets limits for source and output size, memory, total and CPU
time, file size, the number of programs, Tool calls, concurrency, and cleanup.
Override only the limits your workload needs to change:

```ruby
LittleGhost.configure do |config|
  config.code_mode = {
    engine: :ruby,
    sandbox: :native,
    limits: {
      programs: 16,
      wall_seconds: 900,
      cleanup_seconds: 5
    }
  }
end
```

Bubblewrap owns the program's process tree but does not cap its process or thread
count. Use an outer cgroup or container supervisor when generated code needs a
hard task-count limit.

Application defaults apply to every Agent that declares `code_mode`. An Agent
can override the engine, Sandbox, limits, or excluded Tools in its own
declaration.

The operating-system Sandbox contains the interpreter. The parent Ruby process
starts it, brokers Tool calls, and cleans it up. Language restrictions alone
cannot contain native extensions, interpreter bugs, files, subprocesses, or
sockets.

Use an enforcing Sandbox backend for model-written code. Before production,
test the deployed backend against the files, child processes, networking, and
resource pressure your application expects. Also test cancellation and cleanup
on the deployed host.

## Opt into JavaScript when it fits

The JavaScript engine is optional. It uses MiniRacer and gives each program its
own V8 global state. The core gem does not require or load MiniRacer:

```ruby
# Gemfile
gem "mini_racer", "~> 0.21"

# application setup
require "little_ghost/code_mode/javascript_engine"

LittleGhost.configure do |config|
  config.code_mode = {engine: :javascript, sandbox: :native}
end
```

The JavaScript program has no Node.js APIs, filesystem, network, console,
WebAssembly, or process-spawning API. Tool methods return Promises, and the
generated instructions include TypeScript declarations derived from each Tool
schema. Use `await` or `Promise.all`, `text(value)` for output, and `exit()` to
complete early. Call `text(value)` first when the value should become
user-visible output.

MiniRacer's language-level restrictions are useful, but the operating-system
Sandbox still contains the program. The Ruby parent owns the Tool catalog,
permission checks, Tool-call limits, events, tracing, and resource cleanup.

## Build a custom engine

Applications can register another `CodeMode::Engine`. An engine names its
language, writes the instructions shown to the model, and opens a
`CodeMode::Session`. The session implements `#execute`, `#wait`, `#stop`, and
`#close`. The first three operations return a `CodeMode::ProgramResult`.

LittleGhost gives the engine a Tool broker and a Sandbox factory. The broker
stays in the parent Ruby process. The factory creates the Sandbox that
contains model-written code. An engine may request named runtime paths for its
interpreter libraries. Those paths are visible to the child process, but they
never become filesystem grants available through Tools.

The session owns every Workspace, Sandbox, child process, background task, and
communication channel it creates. It closes those resources in reverse order.
One registered engine can open several sessions concurrently on threads or
fibers. Keep each program's mutable state inside the returned session, and
synchronize any state the engine shares across sessions.

A sandboxed engine must use a backend that owns the complete child process tree
or can prevent child processes. An explicitly unrestricted backend may run an
engine, but the generated program then has the same host access as the parent.

See `LittleGhost::CodeMode::Engine`, `LittleGhost::CodeMode::Session`, and
`LittleGhost::CodeMode::ProgramResult` for the extension contract. Continue
with [Integrations](integrations.md) to connect Runs to MCP tools, AG-UI, and
OpenTelemetry.