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
  └─ execution loop ──▶ [ToolInvocation₀, ToolInvocation₁, ...] (⑥)
                         │
                         ├─ updates io_footprint (paths read/written)
                         ├─ supports PatchSet generation (⑦)
                         └─ feeds Evidence (⑧)

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.

How Libra should use this object

• Create one ToolInvocation per tool call.
• Populate arguments, I/O footprint, status, summaries, and artifacts before persistence.
• Reconstruct the per-run action log by querying all tool invocations for the same run_id, typically ordered by header.created_at.
• Keep current orchestration state such as “next tool to run” in Libra rather than in this object.

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.