# `LedgerUI.Components.Tool`
[🔗](https://github.com/devaction-labs/ledger_ui/blob/v0.2.0/lib/ledger_ui/components/tool.ex#L1)

A tool call an agent makes (running a command, reading a file), from input to output, as a line
of a `LedgerUI.Components.Trace.trace/1`: a plain line while it runs, a step that opens on its
output once it has one, red when it fails. A call that waits for the user is a
`tool_approval/1` card with Deny and Approve.

    <.trace>
      <.tool id="t1" state="running" subject="pnpm install" />
      <.tool id="t2" state="done" subject="node --version" output="v24.18.0" />
      <.tool id="t3" state="error" subject="pnpm lint" output={@stderr} />
    </.trace>

## States

| `state`   | line                | title (en / pt_BR)                  |
|-----------|---------------------|-------------------------------------|
| `running` | `running` (spinner) | Running ... / Rodando ...           |
| `waiting` | `pending` (faded)   | Waiting to run ... / Aguardando ... |
| `done`    | plain               | Ran ... / Rodou ...                 |
| `error`   | `error` (red)       | Failed to run ... / Falhou ao rodar ... |
| `denied`  | plain               | Denied ... / Negado ...             |

`verbs` overrides them per state (`verbs={%{done: "Read", running: "Reading"}}`) and `title`
replaces the whole title. `subject` is drawn as code.

`variant="panel"` draws the call as a panel (tool icon, title, state badge or spinner) instead
of a line of a trace; `input` / `output` are only shown by the `line` variant.

# `tool`

One tool call, as a line of a `trace/1` (or a panel).
## Attributes

* `id` (`:string`) (required) - Names the output block.
* `state` (`:string`) - Defaults to `"done"`. Must be one of `"running"`, `"waiting"`, `"done"`, `"error"`, or `"denied"`.
* `subject` (`:string`) - What the tool acted on, drawn as code. Defaults to `nil`.
* `title` (`:string`) - The whole title, in place of verb and subject. Defaults to `nil`.
* `verbs` (`:map`) - Verbs per state (atom keys), over the `locale` ones. Defaults to `%{}`.
* `locale` (`:string`) - Defaults to `"en"`. Must be one of `"en"`, or `"pt_BR"`.
* `icon` (`:string`) - Defaults to `"terminal"`.
* `description` (`:any`) - Defaults to `nil`.
* `input` (`:string`) - Defaults to `nil`.
* `output` (`:string`) - Defaults to `nil`.
* `open` (`:boolean`) - Defaults to `false`.
* `variant` (`:string`) - Defaults to `"line"`. Must be one of `"line"`, or `"panel"`.
* `indicator` (`:string`) - `panel` only: the state badge, or a spinner while `running`. Defaults to `"badge"`. Must be one of `"badge"`, or `"ring"`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `tool_approval`

A tool call that waits for the user: the question, the input and Deny / Approve.
## Attributes

* `id` (`:string`) (required)
* `subject` (`:string`) - What would run, drawn as code in the question. Defaults to `nil`.
* `title` (`:string`) - The question, in place of "Run `subject`?". Defaults to `nil`.
* `description` (`:string`) - Defaults to `nil`.
* `input` (`:string`) - Defaults to `nil`.
* `icon` (`:string`) - Defaults to `"terminal"`.
* `value` (`:any`) - Sent with both events. Defaults to `nil`.
* `on_approve` (`:any`) - Defaults to `nil`.
* `on_deny` (`:any`) - Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `approve_label` (`:string`) - Defaults to `nil`.
* `deny_label` (`:string`) - Defaults to `nil`.
* `locale` (`:string`) - Defaults to `"en"`. Must be one of `"en"`, or `"pt_BR"`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
