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.

Complete tool listing

WorkItem plane

Task control plane

Agent plane

Workspace plane

Memory plane

Web plane

Tool definition contract

Each tool is defined by a BuiltinToolDefinition:

BuiltinToolDefinition {
    family: ToolCapabilityFamily,
    spec: ToolSpec { name, description, parameters },
}

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.

Input/result separation

Holon strictly separates tool startup input from result metadata:

• Startup input: cmd, workdir, shell, login, tty, 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, initial_output_preview, task_handle (when promoted to command_task).

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.