# Class LittleGhost::Harnesses::Tool

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Harnesses/Tool.html

Lets an Agent delegate a coding task to an external coding-agent tool.

The application chooses which harnesses are available, where each executable
lives, where its home directory is created, and placeholder settings. The
model supplies only the task, the harness name, an optional session to resume,
and a budget and timeout within the configured bounds.

    class DelegateCodingTask < LittleGhost::Harnesses::Tool
      tool_name "delegate_coding_task"
      harnesses claude_code: {
        executable: "/opt/harnesses/bin/claude",
        home_root: :scratch,
        defaults: {base_url: "http://127.0.0.1:3130"}
      }
      budget default: 2, maximum: 10
      timeout default: 900, maximum: 3600
    end

    class SupportEngineerAgent < LittleGhost::Agent
      tools DelegateCodingTask
    end

The tool runs the harness in the Run's Sandbox, or on the host in
`:native_guards` mode when the Tool has no Sandbox, and publishes
each `:harness` StreamEvent to the Run while the harness works; by
default tool-call inputs and tool outputs are left out (see
#harness_event_data). The harness's tool calls also become `:tool`
Instrumentation operations beneath this call, so traces show the harness's
work step by step. It returns a JSON object with the Result's status, final
text (shortened to 16,000 characters), session, cost, turns, and usage, plus
the end of standard error when the task did not complete. Calls are exclusive,
so two harnesses never edit the same workspace at once.

Each harness gets one private home directory per Run, created on first use
beneath a Workspace path the Sandbox lets processes write and removed when the
Run closes. The model may resume only sessions that an earlier call in the
same Run started.

#serve_tools lets the harness call tools of the application's own while it
works, through a ToolServer that lives only for that call.

Override #build_harness to choose settings per run, and #build_request to add
instructions, a working directory, or a turn limit.

## Inheritance

`LittleGhost::Harnesses::Tool < LittleGhost::Tool`

## Class methods

<a id="method-c-budget"></a>
### `.budget`

```ruby
budget(default:, maximum:) -> Numeric
```

Lets the model choose `budget_usd` up to `maximum` US dollars; omitted, null,
or zero values use `default`. Without a budget, the harness runs without a
spending limit.

<a id="method-c-harness_settings"></a>
### `.harness_settings`

```ruby
.harness_settings(name)
```

Settings declared for harness `name`.

<a id="method-c-harnesses"></a>
### `.harnesses`

```ruby
harnesses()                      -> Array of Symbol
harnesses(*names, **settings)    -> Array of Symbol
```

Declares the available harnesses. Each name must be registered with
Harnesses.register. `settings` maps a name to a Hash with
`:executable`, `:home_root`, `:defaults`, and
`:mode` for Base.new; a bare name uses the harness's default
executable and the first writable runtime path for its home.
`:home` opts in to a persistent home shared by every Run, as
described in Base.new.

<a id="method-c-serve_tools"></a>
### `.serve_tools`

```ruby
serve_tools(*tools, socket:, url:, name: "tools") -> Hash
```

Serves `tools` to the harness during each call. Entries are Tool classes, Tool
instances, or provider classes, as for Agent.tools, bound to this Tool's
binding; override #served_tools to choose them per run. The ToolServer listens
on `socket`, an absolute host path, and the harness connects to `url` as MCP
server `name`, so the application relays `url` to `socket` inside the Sandbox.
Every tool served this way runs with the Run's credentials, without Agent
callbacks such as `:before_tool`; see ToolServer. Concurrent Runs
need separate sockets: a call fails while another serves `socket`.

<a id="method-c-timeout"></a>
### `.timeout`

```ruby
timeout(default:, maximum:) -> Integer
```

Lets the model choose `timeout_seconds` up to `maximum`; omitted, null, or
zero values use `default`. The default is 600 seconds.

## Instance methods

<a id="method-i-call"></a>
### `#call`

```ruby
#call(input)
```

Runs the selected harness and returns its result as a Hash.
