Tool fallback

Thread already renders this for every tool call that doesn't have its own UI.

case "tool-call":
  return part.toolUI ?? <ToolFallbackComponent {...part} />;

<Thread components={{ ToolFallback: MyToolCard }} />

<div> {/* ToolFallbackRoot, a Collapsible */}
  <button aria-expanded={/* open */}>
    {/* status icon: spinner / check / X-circle / alert */}
    <span>{/* "Running tool: <name>", "Waiting on tool: <name>", "Failed tool: <name>", "Cancelled tool: <name>", or "Used tool: <name>" */}</span>
    <span>{/* elapsed duration, while known */}</span>
    {/* chevron, rotates open */}
  </button>
  <div> {/* ToolFallbackContent */}
    {/* error, only while status is "incomplete" and carries one */}
    {/* args, only when argsText is non-empty */}
    {/* approval controls while requires-action, then a receipt of the decision */}
    {/* result, only when result is defined */}
  </div>
</div>

The row opens by default whenever the tool call's status is "requires-action", and stays as the user left it otherwise. Duration only shows once the call has a recorded start; it keeps counting up once per second while the call is running, and freezes at the recorded total once it completes.

Approval without declared options

With no approval and no interrupt on the part, a plain Allow / Deny pair calls addResult directly with a fixed approved or denied string. With interrupt set, the same pair instead calls resume({ approved }) to unpause the paused frontend tool execution.

<ToolFallback {...part} />

Approval with declared options

When part.approval.options is set, one button renders per option instead of a plain pair: allow-kind options first (the first one styled as primary), then any custom kind, then reject-kind options. An option can opt into a confirmation step before it resolves.

approval: {
  id: "call-1",
  options: [
    { id: "once", kind: "allow-once", label: "Allow" },
    { id: "always", kind: "allow-always", label: "Always allow", confirm: true },
    { id: "deny", kind: "reject-once", label: "Deny" },
  ],
}

Choosing "Always allow" here shows a confirm/back step before it calls respondToApproval({ optionId: "always" }); the other two resolve immediately. In a thread that cannot answer tool calls, where s.thread.capabilities.answerToolCall is false as in a sub-agent transcript, the block shows only the prompt.

On the web and React Native, changing approval.id starts a fresh request in both the default renderer and the composed approval component, clearing the previous request's input, confirmation, error, and submission state.

Receipt of a settled request

Once approval.approved or approval.resolution is set, the controls give way to a receipt, so scrolling back never shows a live button for a decision already made. The receipt keeps the prompt and states what happened in the past tense: "Allowed" or "Denied" for a decision, "Answered" or "Dismissed" for a question, and "Cancelled before a decision" or "Expired before a decision" for a request that closed unanswered. The chosen option's label follows the verb, a typed text and a host reason follow on their own lines, and isAutomatic appends "automatically" when a policy decided instead of the user.

On the web, when the controls are replaced while they hold keyboard focus, focus moves to the receipt without scrolling. A decision that settles after focus moves elsewhere leaves that focus in place; historical receipts do not take focus when they mount.

In the web renderer, an explicit approval record keeps the component mounted across run-status updates, including when an external-store adapter updates the run status before the approval. Controls appear only while the request requires action, or while a submitted decision is still running and awaiting its receipt; submitted controls stay locked. If the run ends without settling the approval, the controls disappear. An unanswered approval in a running or finished message does not expose new actions.

approval: {
  id: "call-1",
  approved: true,
  optionId: "always",
  options: [{ id: "always", kind: "allow-always" }],
}
// renders: Allowed · Always allow

Question that accepts a dismissal

A request with display: "select" or "text" is a question, so no Deny renders for it: the kit never fabricates a refusal the host did not ask for. A host that records a dismissal declares dismissible: true, and the question gains a Dismiss control that calls respondToApproval({ approved: false }) with no answer attached, beside the options of a select or beside Send on a text field.

approval: {
  id: "call-2",
  prompt: "Custom summarization instructions",
  display: "text",
  dismissible: true,
}

Send submits the text as typed, an empty answer included; a host that cannot record one rejects the response, and the controls come back with its error.

Several questions at once

A display: "questions" request renders each of its questions with its options as toggle buttons (several stay pressed when the question allows multiple) and a text field where the question accepts a typed answer. One Send stays disabled until every question has an answer, then calls respondToApproval({ answers }) keyed by question id; Dismiss appears only when the request is dismissible. Once settled, the receipt lists each question beside its answer.

approval: {
  id: "call-3",
  display: "questions",
  questions: [
    {
      id: "scope",
      header: "Scope",
      prompt: "Which folders should change?",
      options: [
        { id: "src", label: "src" },
        { id: "tests", label: "tests" },
      ],
      multiple: true,
    },
    { id: "note", prompt: "Anything I should avoid?" },
  ],
}

Restyle a part

Every piece is a named export you can recompose, and each carries its own data-slot for targeted styling.

import { ToolFallbackTrigger, ToolFallbackContent } from "@/components/assistant-ui/elements/tool-fallback.aui";

<ToolFallbackTrigger toolName={part.toolName} status={part.status} className="text-sm" />

Parts

Tool-call part fields

ToolFallback (and each part above) receives the current tool call as ToolCallMessagePartProps, the full ToolCallMessagePart plus three callbacks:

Callbacks

Composition