Built-in 3-Channel Tool Suite, 5 ToolExposure Modes, and Deferred tool_search Registry (Step 8).
3-Channel Tool Results (Decision 06)
Every tool execution returns a normalized map with:
"output"— Concise string sent to the LLM context (pi.messageroletool)."structured_output"— Typed JSON map for programmatic consumers and Codemode scripts."details"— Rich metadata (diff,line_count,spilled_path,duration_ms) for UI inspectors."control"(optional) — Control directives (%{"add_tools" => [...]},%{"handoff" => ...},%{"terminate" => true}).
5 ToolExposure Modes
:direct— Exposed in the active LLM tool declarations and callable from Codemode.:model_only— Exposed in the LLM tool declarations only (e.g.,tool_search).:codemode— Callable inside Codemode scripts only; omitted from top-level LLM declarations to save tokens.:deferred— Omitted from initial LLM declarations; discovered and activated dynamically viatool_search.:hidden— Internal/disabled tool.
Summary
Functions
Returns all tools that should be declared in the initial LLM request (:direct and :model_only).
The effect vocabulary: read, fs_write, exec, net_read, net_write, state_write.
Effects of a tool: what a call changes or reaches.
Executes one of the 7 built-in tools (read, write, edit, bash, grep, find, ls) or tool_search.
Supports common tool name aliases and argument variations with defensive parameter extraction.
Builds the error result for a tool that is registered but has no implementation.
Registers a tool specification in the ETS catalog with one of the 5 ToolExposure modes.
The catalog form of a tool spec: one "parameters" key for the schema, whatever the source called it.
Searches :deferred (and :direct) tools by keyword query (tool_search) and returns matching
tool schemas along with a control: %{"add_tools" => matches} directive that activates them
in pi.agent (Decision 06).
Types
Functions
Returns all tools that should be declared in the initial LLM request (:direct and :model_only).
@spec effect_vocabulary() :: [String.t()]
The effect vocabulary: read, fs_write, exec, net_read, net_write, state_write.
Effects of a tool: what a call changes or reaches.
| Effect | Meaning |
|---|---|
read | Reads the workspace or answers from existing state. Changes nothing. |
fs_write | Writes workspace files. |
exec | Runs a command. |
net_read | Reads from the network (a GET). |
net_write | Sends data out or changes a remote system. |
state_write | Changes Super-Pi state (artifacts, todos, memory, schedules), not the workspace. |
A tool states its effects in an "effects" list on its spec. The lookup order is: the spec in
agent_cfg["tools"] (plugin tools live there), the catalog, then the table for built-in tools.
nil means the tool is unknown, which every policy treats as the most dangerous kind.
Executes one of the 7 built-in tools (read, write, edit, bash, grep, find, ls) or tool_search.
Supports common tool name aliases and argument variations with defensive parameter extraction.
Builds the error result for a tool that is registered but has no implementation.
A tool that cannot do its job must report an error. It must never report success.
Registers a tool specification in the ETS catalog with one of the 5 ToolExposure modes.
The catalog form of a tool spec: one "parameters" key for the schema, whatever the source called it.
Searches :deferred (and :direct) tools by keyword query (tool_search) and returns matching
tool schemas along with a control: %{"add_tools" => matches} directive that activates them
in pi.agent (Decision 06).