# Tool Calls

> The list of what an agent does, one line per step. Reads fold into a summary, edits and errors stay in view, and approvals ask before a tool runs.

Canonical: https://hextaui.com/blocks/tool-calls
Last updated: 2026-10-29

## Overview

Agents can take dozens of small steps before they answer. Showing every one buries the answer, and hiding them makes the agent feel like a black box. Tool Calls gives each step one quiet line that reads like a sentence, such as “Read components/search.tsx” or “Searched for useResults, 3 results”.

Reads, searches and lookups that run back to back fold into a single summary like “Explored 6 files”. Anything that changes something, needs a decision or fails stays on its own line, with a live timer while it runs. Open any step to see the real work: the file, the diff, the terminal or the results.

Every AI SDK tool state has its own look and wording, including approvals. Approving offers Allow, Deny, Always allow and “Tell it what to do instead”, which sends your words back as the reason, with ⌘↵ and ⌘⌫ from the keyboard. getToolPartStatus maps tool parts for you, and ready-made views cover search results, file lists, multiple-choice questions and raw JSON.

## Installation

### Step 1: Get HextaUI Pro

One payment unlocks every block, including future ones. [See pricing](https://hextaui.com/pricing).

### Step 2: Add the Pro registry to components.json

```json title="components.json"
{
  "registries": {
    "@hextaui-pro": {
      "url": "https://hextaui.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${HEXTAUI_PRO_TOKEN}"
      }
    }
  }
}
```

### Step 3: Add your token

Create a token on your [account page](https://hextaui.com/account) and put it in `.env.local` as `HEXTAUI_PRO_TOKEN`.

### Step 4: Add the block

```bash
npx shadcn@latest add @hextaui-pro/tool-calls
```

## Usage

### With the AI SDK

Turn tool parts into steps with getToolPartStatus and pick a kind and view per tool. Pass stopped once the chat stops streaming, so a call cut off midway reads Cancelled instead of spinning forever.

```tsx
"use client"

import type * as React from "react"
import { useChat } from "@ai-sdk/react"
import {
  getToolName,
  isToolUIPart,
  lastAssistantMessageIsCompleteWithApprovalResponses,
  type DynamicToolUIPart,
  type ToolUIPart,
  type UIMessage,
} from "ai"

import { CodeBlock } from "../code-block/code-block"
import { CodeTerminal } from "../code-block/code-terminal"
import type { ToolCallProps } from "@/components/blocks/tool-calls/tool-call"
import { ToolCalls } from "@/components/blocks/tool-calls/tool-group"
import {
  getToolPartApproval,
  getToolPartStatus,
} from "@/components/blocks/tool-calls/tool-part"
import { ToolJson } from "@/components/blocks/tool-calls/tool-views"

type ToolPart = ToolUIPart | DynamicToolUIPart
type Fields = Record<string, string | number | undefined>

function describe(part: ToolPart): Partial<ToolCallProps> {
  const input = (part.input ?? {}) as Fields
  const output = (part.state === "output-available" ? part.output : {}) as Fields
  const done = part.state === "output-available"

  switch (getToolName(part)) {
    case "readFile":
      return {
        kind: "read",
        subject: String(input.path ?? ""),
        content: done ? (
          <CodeBlock
            code={String(output.content)}
            filename={String(input.path)}
            lineNumbers
          />
        ) : undefined,
      }
    case "editFile":
      return {
        kind: "edit",
        subject: String(input.path ?? ""),
        content: input.diff ? (
          <CodeBlock
            code={String(input.diff)}
            filename={String(input.path)}
            streaming={part.state === "input-streaming"}
            diff
          />
        ) : undefined,
      }
    case "runCommand":
      return {
        kind: "run",
        subject: String(input.command ?? ""),
        exitCode: done ? Number(output.exitCode) : undefined,
        content: (
          <CodeTerminal
            command={String(input.command ?? "")}
            output={String(output.stdout ?? "")}
            running={!done && part.state !== "approval-requested"}
            exitCode={done ? Number(output.exitCode) : undefined}
          />
        ),
      }
    default:
      return {
        kind: "other",
        name: getToolName(part),
        content: (
          <ToolJson
            input={part.input}
            output={done ? part.output : undefined}
            streaming={part.state === "input-streaming"}
          />
        ),
      }
  }
}

function AssistantMessage({
  message,
  streaming,
  onApproval,
}: {
  message: UIMessage
  streaming: boolean
  onApproval: (id: string, approved: boolean, reason?: string) => void
}) {
  const blocks: (React.ReactNode | ToolCallProps[])[] = []

  message.parts.forEach((part, index) => {
    if (isToolUIPart(part)) {
      const call: ToolCallProps = {
        id: part.toolCallId,
        title: part.title,
        status: getToolPartStatus(part, { stopped: !streaming }),
        approval: getToolPartApproval(part),
        error: part.state === "output-error" ? part.errorText : undefined,
        onApprove: () => part.approval && onApproval(part.approval.id, true),
        onDeny: (reason) =>
          part.approval && onApproval(part.approval.id, false, reason),
        ...describe(part),
      }
      const last = blocks.at(-1)
      if (Array.isArray(last)) last.push(call)
      else blocks.push([call])
    } else if (part.type === "text") {
      blocks.push(<p key={index}>{part.text}</p>)
    }
  })

  return (
    <div className="flex flex-col gap-4">
      {blocks.map((block, index) =>
        Array.isArray(block) ? (
          <ToolCalls key={block[0].id} calls={block} />
        ) : (
          <div key={index}>{block}</div>
        )
      )}
    </div>
  )
}

export function Chat() {
  const { messages, status, addToolApprovalResponse } = useChat({
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
  })
  const busy = status === "submitted" || status === "streaming"

  return messages.map((message, index) =>
    message.role === "assistant" ? (
      <AssistantMessage
        key={message.id}
        message={message}
        streaming={busy && index === messages.length - 1}
        onApproval={(id, approved, reason) =>
          addToolApprovalResponse({ id, approved, reason })
        }
      />
    ) : null
  )
}
```

### Approving commands

Mark a tool with needsApproval on the server and answer with addToolApprovalResponse. Always allow remembers the program, and a denial can carry what to do instead as its reason. ⌘↵ and ⌘⌫ work while the step has focus.

```tsx
"use client"

import * as React from "react"
import { useChat } from "@ai-sdk/react"
import {
  isToolUIPart,
  lastAssistantMessageIsCompleteWithApprovalResponses,
} from "ai"

import { CodeTerminal } from "../code-block/code-terminal"
import { ToolCall } from "@/components/blocks/tool-calls/tool-call"
import { getToolPartApproval, getToolPartStatus } from "@/components/blocks/tool-calls/tool-part"

function program(command: string) {
  return command.trim().split(/\s+/)[0] ?? ""
}

export function Chat() {
  const [allowed, setAllowed] = React.useState<string[]>([])
  const { messages, status, addToolApprovalResponse } = useChat({
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
  })
  const streaming = status === "submitted" || status === "streaming"

  React.useEffect(() => {
    for (const part of messages.at(-1)?.parts ?? []) {
      if (part.type !== "tool-runCommand") continue
      if (part.state !== "approval-requested") continue
      const command = String((part.input as { command?: string }).command)
      if (allowed.includes(program(command))) {
        addToolApprovalResponse({ id: part.approval.id, approved: true })
      }
    }
  }, [messages, allowed, addToolApprovalResponse])

  return messages.flatMap((message) =>
    message.parts.map((part) => {
      if (!isToolUIPart(part) || part.type !== "tool-runCommand") return null
      const command = String((part.input as { command?: string })?.command ?? "")
      const output = part.state === "output-available"
        ? (part.output as { stdout: string; exitCode: number })
        : undefined

      return (
        <ToolCall
          key={part.toolCallId}
          id={part.toolCallId}
          kind="run"
          subject={command}
          status={getToolPartStatus(part, { stopped: !streaming })}
          exitCode={output?.exitCode}
          approval={{
            ...getToolPartApproval(part),
            alwaysLabel: `Always allow ${program(command)}`,
          }}
          onApprove={({ always }) => {
            if (!part.approval) return
            if (always) setAllowed((list) => [...list, program(command)])
            addToolApprovalResponse({ id: part.approval.id, approved: true })
          }}
          onDeny={(reason) => {
            if (!part.approval) return
            addToolApprovalResponse({
              id: part.approval.id,
              approved: false,
              reason,
            })
          }}
          content={
            <CodeTerminal
              command={command}
              output={output?.stdout}
              exitCode={output?.exitCode}
              running={part.state === "approval-responded"}
            />
          }
        />
      )
    })
  )
}
```

### Asking the user

A client tool with no execute function waits for an answer. Show the choices with AskUser and send the pick back with addToolOutput.

```tsx
"use client"

import { useChat } from "@ai-sdk/react"
import { lastAssistantMessageIsCompleteWithToolCalls } from "ai"

import { ToolCall } from "@/components/blocks/tool-calls/tool-call"
import { getToolPartStatus } from "@/components/blocks/tool-calls/tool-part"
import { AskUser, type AskOption } from "@/components/blocks/tool-calls/tool-views"

export function Chat() {
  const { messages, addToolOutput } = useChat({
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
  })

  return messages.flatMap((message) =>
    message.parts.map((part) => {
      if (part.type !== "tool-askUser") return null
      const input = (part.input ?? {}) as {
        question?: string
        options?: AskOption[]
      }

      return (
        <ToolCall
          key={part.toolCallId}
          id={part.toolCallId}
          kind="ask"
          subject={input.question}
          status={getToolPartStatus(part, { waiting: true })}
          content={
            <AskUser
              question={input.question ?? ""}
              options={input.options ?? []}
              answer={
                part.state === "output-available"
                  ? String(part.output)
                  : undefined
              }
              onAnswer={(value) =>
                addToolOutput({
                  tool: "askUser",
                  toolCallId: part.toolCallId,
                  output: value,
                })
              }
            />
          }
        />
      )
    })
  )
}
```

## Anatomy

The parts you compose, from the outside in.

| Part | Description |
| --- | --- |
| `ToolCalls` | The list. Groups quiet runs and shares timing between steps. |
| `ToolCall` | One step: icon, sentence, meta, timer, and its content when opened. |
| `ToolGroup` | A folded run of quiet steps with a summary line. |
| `ToolApproval` | The approve, deny and redirect card, shown inside a step waiting for approval. |
| `SearchResults, FileList, AskUser, ToolJson` | Views to pass as a step’s content. |

## API reference

### ToolCalls

Also accepts every ol prop except children.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `calls` | `ToolCallProps[]` | – | Steps in the order they ran. |
| `group` | `boolean` | `true` | Fold runs of quiet steps. Set false to show every step. |

### ToolCall

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | – | Stable id, usually the toolCallId. Timing is kept per id. |
| `status` | `ToolStatus` | – | streaming, running, waiting, approval, done, error, denied or cancelled. |
| `kind` | `ToolKind` | `"other"` | read, search, list, edit, write, run, web, fetch, ask or other. Picks the icon and verb. |
| `subject` | `string` | – | What it acted on: a path, query, URL or command. |
| `name` | `string` | – | Tool name, used for the sentence when kind is other. |
| `title` | `string` | – | Replaces the generated sentence entirely. |
| `meta` | `ReactNode` | – | Short result after the sentence, such as “3 results” or “+12 −3”. |
| `content` | `ReactNode` | – | Shown when the step is opened. |
| `exitCode` | `number` | – | For run steps. Non-zero marks the step failed and opens it. |
| `error` | `string` | – | Message shown for the error status. |
| `duration` | `number` | – | Stored duration in seconds, for history. |
| `approval` | `ToolCallApproval` | – | Reason, outcome and always-allow label for approvals. |
| `defaultOpen` | `boolean` | – | Override whether the step starts open. |
| `onApprove` | `(options: { always: boolean }) => void` | – | Called from Allow or Always allow. |
| `onDeny` | `(reason?: string) => void` | – | Called from Deny, or with text from “Tell it what to do instead”. |

### ToolCallApproval

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `reason` | `string` | – | Why approval is needed, shown above the buttons. |
| `approved` | `boolean` | – | The answer, once given. |
| `automatic` | `boolean` | – | Approved by a rule, so no card is shown. |
| `denialReason` | `string` | – | What the person asked for instead, shown on denied steps. |
| `alwaysLabel` | `string` | – | Shows “Always allow …” with this label, for example the program name. |

### getToolPartStatus(part, options)

Maps an AI SDK tool part to a ToolStatus.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `part` | `ToolUIPart \| DynamicToolUIPart` | – | The part from message.parts. |
| `options.stopped` | `boolean` | `false` | The chat stopped, so unfinished calls read Cancelled instead of spinning. |
| `options.waiting` | `boolean` | `false` | A client tool is waiting for the person, for example AskUser. |

### AskUser

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `question` | `string` | – | The question. |
| `options` | `{ value, label, description? }[]` | – | The choices. |
| `answer` | `string` | – | The chosen value, once answered. |
| `onAnswer` | `(value: string) => void` | – | Send it back with addToolOutput. |

### SearchResults

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | `string` | – | Highlighted inside each match. |
| `matches` | `{ path, line, text }[]` | – | The matches. |
| `limit` | `number` | `6` | Shown before “Show all”. |

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` | Opens or closes a step or a folded group. |
| `⌘` `↵` | Allows a step waiting for approval while focus is inside it. |
| `⌘` `⌫` | Denies a step waiting for approval while focus is inside it. |
| `Esc` | Leaves “Tell it what to do instead” without sending. |

## Accessibility

- Steps are an ordered list, so screen readers announce how many steps there are and where each one sits.
- Steps that need the person are announced through a polite live region, such as “Approval needed: Run pnpm test”, along with questions and errors. Routine steps stay quiet so screen readers aren’t flooded.
- Status is never color alone: each state has its own icon and wording.
- Approval shortcuts are ignored while typing in a field, and the redirect field focuses itself when opened and returns focus when closed.

## Built with

The free HextaUI components Tool Calls is made from. Each one installs on its own.

- [Button](https://hextaui.com/docs/button) - Buttons in every variant and size, with a built-in loading, success and error flow that skips the spinner for fast requests.
- [Card](https://hextaui.com/docs/card) - A surface for grouping content, with three variants, edge-to-edge media, concentric radii and whole-card links.
- [Collapsible](https://hextaui.com/docs/collapsible) - A panel that shows and hides with height motion you can reverse mid-way, without jumping the layout.
- [Kbd](https://hextaui.com/docs/kbd) - Key caps for shortcuts that show the right symbols on every platform, read them out properly and press down with the real keys.
- [Questionnaire](https://hextaui.com/docs/questionnaire) - A step-by-step form that moves between questions with a sense of direction, shows real progress and answers from the keyboard.
- [Spinner](https://hextaui.com/docs/spinner) - A loading indicator with Apple-style ticks or a breathing ring that can wait before showing and stay long enough not to flicker.
- [Textarea](https://hextaui.com/docs/textarea) - Multi-line text that grows smoothly with what you write between a minimum and maximum number of rows, with counters, validation and a submit shortcut.
- [Tree](https://hextaui.com/docs/tree) - Nested, expandable rows for files and hierarchies, with indent guides, connector lines, cascading checkboxes, typeahead and full keyboard support.

## Code

9 files, added to components/blocks/tool-calls.
