class LittleGhost::Harnesses::Tool
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.
Public Class Methods
# File lib/little_ghost/harnesses/tool.rb, line 99 def budget(default:, maximum:) default = positive_number(default, "budget default") maximum = positive_number(maximum, "budget maximum") raise ArgumentError, "budget default must not exceed budget maximum" if default > maximum self.budget_maximum_value = maximum self.budget_default_value = default end
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.
Source
# File lib/little_ghost/harnesses/tool.rb, line 91 def harness_settings(name) = harness_settings_value.fetch(name.to_sym, {})
Settings declared for harness name.
# File lib/little_ghost/harnesses/tool.rb, line 74 def harnesses(*names, **settings) return harness_settings_value.keys if names.empty? && settings.empty? values = names.flatten.to_h { |name| [name.to_sym, {}] } settings.each do |name, options| options = options.to_h.transform_keys(&:to_sym) unknown = options.keys - SETTINGS raise ArgumentError, "unknown harness settings: #{unknown.join(", ")}" unless unknown.empty? values[name.to_sym] = options.freeze end values.each_key { |name| Harnesses.resolve(name) } self.harness_settings_value = values.freeze harnesses end
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.
# File lib/little_ghost/harnesses/tool.rb, line 135 def serve_tools(*tools, socket:, url:, name: "tools") raise ArgumentError, "serve_tools socket must be an absolute path" unless String(socket).start_with?("/") Request.new(prompt: "check", mcp_servers: {name => url}) self.tool_server_value = {tools: tools.flatten.freeze, socket: String(socket).freeze, url: String(url).freeze, name: String(name).freeze}.freeze end
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.
# File lib/little_ghost/harnesses/tool.rb, line 113 def timeout(default:, maximum:) unless [default, maximum].all? { |value| value.is_a?(Integer) && value.positive? } raise ArgumentError, "timeout default and maximum must be positive integers" end raise ArgumentError, "timeout default must not exceed timeout maximum" if default > maximum self.timeout_maximum_value = maximum self.timeout_default_value = default end
Lets the model choose timeout_seconds up to maximum; omitted, null, or zero values use default. The default is 600 seconds.
Public Instance Methods
Source
# File lib/little_ghost/harnesses/tool.rb, line 205 def call(input) name = selected_harness(input) request = begin build_request(input, harness: name) rescue ArgumentError => error raise ToolError, error.message end if request.session_id && !session_ledger.include?(name, request.session_id) raise ToolError, "Only sessions started earlier in this run can be resumed." end harness = build_harness(name) trace = Trace.new(harness: name, parent_operation_id: trace_parent_operation_id) result = with_tool_server(request) do |served_request| harness.run(served_request, context:) do |event| trace.record(event) data = harness_event_data(event) run&.publish(:harness, **data) if data end end session_ledger.record(name, result.session_id) result_value(result) ensure trace&.close end
Runs the selected harness and returns its result as a Hash.
Private Instance Methods
Source
# File lib/little_ghost/harnesses/tool.rb, line 239 def build_harness(name) # :doc: settings = self.class.harness_settings(name) harness_class = Harnesses.resolve(name) options = { sandbox:, executable: settings.fetch(:executable, harness_class.default_executable), home_root: settings[:home_root], defaults: settings.fetch(:defaults, {}), mode: settings[:mode] } harness = harness_class.new(**options) home = settings[:home] || run_home(name, harness) home ? harness_class.new(**options, home:) : harness end
Builds the Harnesses::Base for name from the declared settings and the bound Sandbox. Override to choose settings per run.
# File lib/little_ghost/harnesses/tool.rb, line 275 def build_request(input, harness:) # :doc: Request.new( prompt: input.fetch("task"), session_id: input["session_id"], budget_usd: budget_for(input), timeout: timeout_for(input) ) end
Builds the Harnesses::Request for validated model input. Override to add trusted values such as cwd, instructions, or max_turns. An ArgumentError becomes a model-visible tool error.
Source
# File lib/little_ghost/harnesses/tool.rb, line 263 def harness_event_data(event) # :doc: activity = event.data.fetch(:event) case activity[:kind] when :tool_call then event.data.merge(event: activity.slice(:kind, :id, :name)) when :tool_result then event.data.merge(event: activity.slice(:kind, :id, :error)) else event.data end end
Returns the data published to the Run for one :harness StreamEvent, or nil to skip it. The default publishes tool calls with only their identifier and name, and tool results with only their identifier and error flag, because tool inputs and outputs can contain repository content and credentials. Override to publish more or to redact text.
Source
# File lib/little_ghost/harnesses/tool.rb, line 292 def result_value(result) # :doc: value = result.to_h.except(:stderr_tail) if result.text && result.text.length > RESULT_TEXT_LIMIT value[:text] = "#{result.text[0, RESULT_TEXT_LIMIT]}…" value[:text_truncated] = true end value[:stderr_tail] = result.stderr_tail unless result.completed? || result.stderr_tail.empty? value end
Converts a Harnesses::Result into the value returned to the model.
Source
# File lib/little_ghost/harnesses/tool.rb, line 287 def served_tools # :doc: self.class.tool_server_value&.fetch(:tools) || [] end
Returns the tool declarations served to the harness for this call. Override to choose them per run; the default is the list given to ::serve_tools.