Tools

This page defines the current contract for Holon's model-facing tool surface: tool families, authority classification, schema/dispatch alignment, and result envelope conventions.

The machine-readable inventory for built-in model-facing tools is model-tool-schema-inventory.json; its versioning policy and refresh workflow are documented in the model tool schema inventory reference.

Last verified: 2026-05-27 against src/types.rs ToolCapabilityFamily, src/tool/tools/mod.rs builtin_tool_definitions(), src/tool/spec.rs, src/tool/dispatch.rs.

Source RFCs

• Tool Surface Layering
• Tool Contract Consistency
• Tool Result Envelope
• Task Surface Narrowing
• Command Tool Family
• Apply Patch Unified Diff Contract
• Exec Command Batch

Tool families (ToolCapabilityFamily)

Tools are grouped by capability family for authority gating:

Operator notification records, delivery callbacks, and UI rendering remain runtime-owned capabilities. They are not part of the model-facing tool inventory; NotifyOperator is intentionally absent from the built-in tool registry and machine-readable schema inventory. The ExternalTrigger tools follow the same pattern today: they are dispatchable in the registry but kept out of the model-facing surface.

Complete tool listing

WorkItem plane

Task control plane

Agent plane

Timer plane

Model plane

Image plane

Workspace plane

Memory plane

Web plane

Tool definition contract

Each tool is defined by a BuiltinToolDefinition:

BuiltinToolDefinition {
    family: ToolCapabilityFamily,
    spec: ToolSpec { name, description, input_schema, freeform_grammar },
}

Key contract:

• Tool schemas must match the runtime type used for argument parsing.
• serde(deny_unknown_fields) is enforced on tool argument structs.
• The description field in ToolSpec is the model-visible guidance text.
• Prompt-level tool guidance (in AGENTS.md or system prompt) must not contradict the tool's own description.

Command output safety

max_output_tokens controls only the model-visible projection of command output. Managed command tasks separately enforce a finite combined artifact retention limit, a higher emitted-byte execution quota, and a filesystem free-space waterline.

Retention overflow keeps a bounded raw-byte head and tail and continues draining stdout/stderr. Execution quota, low disk, and persistence failures are typed terminal failures. TaskStatus and TaskOutput expose the frozen policy, byte counters, dropped-byte evidence, and capture truncation through output_capture; TaskOutput.output_truncated remains the independent API preview-truncation flag.

See Command Task Output Safety.

Input/result separation

Holon strictly separates tool startup input from result metadata:

• Startup input: cmd, workdir, shell, login, tty, duplicate_policy, accepts_input, yield_time_ms, max_output_tokens.
• Result metadata (not valid in startup input): status, task_handle, disposition, exit_status, output_preview.

Key contract:

• Passing result fields as startup input is an error.
• The model must not confuse the two surfaces. Prompt guidance explicitly documents the distinction via valid/invalid startup examples.

Result envelope

Tool execution returns a ToolResult that may be serialized as JSON or rendered as a human-readable receipt:

• Canonical result: structured JSON with content (array of text/tool_use blocks) and optional artifacts.
• Human-readable receipt: rendered text shown to the model; may omit internal fields but must preserve semantically meaningful content.

ExecCommand results carry additional fields: disposition, exit_status, initial_output_preview, and task_handle (when promoted to command_task).

WaitFor delivery modes and wait ownership

WaitFor records explicit wait state and yields the turn. Every invocation must explicitly choose a delivery mode:

• delivery=final: The turn must publish a non-empty operator-facing assistant final brief before waiting. The runtime commits the wait condition, and the assistant responds with final text only without further tool calls.
• delivery=silent: No operator-facing brief is needed; the runtime settles the wait directly without an extra model round.

Key contracts:

• Required parameters: reason (non-empty explanation), wake (task_result, operator_input, external, timer, or system), and delivery (final or silent).
• Atomic settlement: The runtime commits the chosen delivery mode, wait registration, tool evidence, turn terminal, and queue terminal together in one atomic transaction. A stale task, execution binding, WorkItem revision, wake, or interjection cannot publish an obsolete waiting report.
• Task-result wait ownership: For wake=task_result, wait ownership resolves strictly from the task's captured owner. Switching WorkItem focus (via PickWorkItem or CreateWorkItem) never migrates a task or bypasses its captured ownership boundary.

Known gaps

• Tool description text is hand-maintained in Rust source; drift between description and actual behavior is possible without automated validation.
• ExecCommandBatch and individual ExecCommand calls share fields but have different valid field subsets; no structural schema prevents passing batch-only fields to single ExecCommand at the type level.