Module tool 

AI Tool Invocation Definition

A ToolInvocation records a single action taken by an agent during a Run — reading a file, running a shell command, calling an API, etc. It is the finest-grained unit of agent activity, capturing what was done, with which arguments, and what happened.

Position in Lifecycle

Run ──patchsets──▶ [PatchSet₀, ...]
 │
 ├── evidence ──▶ [Evidence₀, ...]
 │
 └── tool invocations ──▶ [ToolInvocation₀, ToolInvocation₁, ...]
                                 │
                                 └── io_footprint (paths read/written)

ToolInvocations are produced throughout a Run, one per tool call. They form a chronological log of every action the agent performed. Unlike Evidence (which validates a PatchSet) or Decision (which concludes a Run), ToolInvocations are low-level operational records.

Purpose

• Audit Trail: Allows reconstructing exactly what the agent did step by step, including arguments and results.
• Dependency Tracking: io_footprint records which files were read or written, enabling incremental re-runs and cache invalidation.
• Debugging: When a Run produces unexpected results, reviewing the ToolInvocation sequence reveals the agent’s reasoning path.

Structs

IoFootprint

File-level I/O footprint of a tool invocation.

ToolInvocation

Record of a single tool call made by an agent during a Run.

Enums

ToolStatus

Tool invocation status.