Module tool 

Tool surface.

AgentTool is the only contract the loop knows about. Tools own their parameter schema, validation, and execution. The loop dispatches and emits events.

Termination is a tool decision: a tool result with terminate: true ends the run if every tool in the batch agrees (unanimous). One tool wanting to stop does not stop the batch.

Re-exports

pub use crate::types::ToolResultBlock;

Structs

ToolCall

A tool call request emitted by the model.

ToolHistoryPolicy

Tool-authored context-retention hints for history transforms.

ToolRegistry

Registry of available tools, keyed by name.

ToolResult

Result of a tool execution.

Enums

ExecutionMode

Loop-wide tool dispatch mode. Per-tool sequential dispatch is requested via AgentTool::requires_exclusive_sandbox; this enum is for pinning the whole loop (e.g. deterministic eval harness).

Constants

ARG_PARSE_ERROR_MARKER

Reserved object key used to mark an argument value that the provider stream layer could not parse as JSON. Tool args are always meant to be JSON objects; when the model emits malformed JSON (e.g. trailing comma, missing value) the provider wraps the failure in a sentinel object carrying this key plus the raw payload, so the loop can emit a structured “your JSON was malformed” error instead of the cryptic “invalid type: string, expected struct …” that comes from serde_json::from_value running over a Value::String fallback.

ARG_PARSE_RAW_MARKER

Companion to ARG_PARSE_ERROR_MARKER: holds the raw JSON-ish payload the model sent, so the model can see exactly what it produced and fix the syntax in its next turn.

Traits

AgentTool

A tool the agent can call.

TypedAgentTool

Implement this for tools whose argument shape is a typed Rust struct/enum. The blanket AgentTool impl below derives parameters_schema from Args via schemars and centralizes the Value → Args parse path. New tools should implement TypedAgentTool, not AgentTool directly; existing tools are migrated incrementally.

Functions

arg_parse_error_value

Build a Value that carries an argument-parse error for the loop to surface. Use from any provider stream layer that decoded a tool call whose arguments string was not valid JSON.

detect_arg_parse_error

If args was produced by arg_parse_error_value, return (error, raw). Otherwise return None.

Type Aliases

ToolUpdateSink

Sink the tool can use to publish partial progress while running.