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 families (`ToolCapabilityFamily`)

Tools are grouped by capability family for authority gating:

Family	Tools	Authority
`CoreAgent`	`WaitFor`, `AgentGet`, `Enqueue`, WorkItem tools, `MemorySearch`, `MemoryGet`	All agent profiles
`LocalEnvironment`	`ExecCommand`, `ExecCommandBatch`, `ApplyPatch`, `GetWorkspaceState`, `SwitchWorkspace`, `CreateWorktree`	All profiles
`AuthorityExpanding`	`AttachWorkspace`, `DetachWorkspace`, `RemoveWorktree`	Public named agents
`Web`	`WebFetch`, `WebSearch`	All profiles
`AgentCreation`	`SpawnAgent`	All profiles

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

Tool	Purpose
`CreateWorkItem`	Create a new open WorkItem
`UpdateWorkItem`	Mutate objective, plan_status, todo_list
`PickWorkItem`	Set current focus
`GetWorkItem`	Read single WorkItem with plan preview
`ListWorkItems`	Query with filters
`CompleteWorkItem`	Mark complete; promote same-round assistant text as the terminal completion report
`WaitFor`	Record task, external, or operator waiting state and yield

Task control plane

Tool	Purpose
`ExecCommand`	Start a shell command
`ExecCommandBatch`	Run bounded sequential command batch
`ListTasks`	Compact active-task digest with bounded output
`TaskStatus`	Single-task lifecycle snapshot
`TaskOutput`	Bounded output preview with optional blocking
`TaskInput`	Send input to interactive task
`TaskStop`	Stop a running task

Agent plane

Tool	Purpose
`AgentGet`	Read current agent-plane summary
`WaitFor`	Signal turn-end after recording explicit wait state
`Enqueue`	Schedule self-follow-up message
`SpawnAgent`	Delegate work to a child agent

Workspace plane

Tool	Purpose
`GetWorkspaceState`	Read bindings, active projection, worktrees, and occupancy
`AttachWorkspace`	Attach a workspace binding without switching
`DetachWorkspace`	Detach a binding; active targets fall back to agent home
`SwitchWorkspace`	Activate an existing workspace or execution root
`CreateWorktree`	Create or safely reuse a linked worktree
`RemoveWorktree`	Safely remove a registered clean worktree
`ApplyPatch`	Apply unified diff patch to files

Memory plane

Tool	Purpose
`MemorySearch`	Search agent memory sources
`MemoryGet`	Fetch exact memory content by source_ref

Web plane

Tool	Purpose
`WebFetch`	Fetch HTTP/HTTPS URL
`WebSearch`	Web search

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.