For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Confirmation

Ask the user to approve a tool call before the agent runs it.

confirmation-demo.tsx
"use client";

import { useChat } from "@ai-sdk/react";
import {
  lastAssistantMessageIsCompleteWithApprovalResponses,
  type UIDataTypes,
  type UIMessage,
} from "ai";
import { CircleCheckIcon, LoaderCircleIcon, TerminalIcon } from "lucide-react";
import { motion, useReducedMotion } from "motion/react";
import * as React from "react";
import { Button } from "@/components/ui/button";
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@/components/ui/item";
import {
  Bubble,
  BubbleContent,
  Message,
  MessageContent,
} from "@/components/ui/message";
import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
import { messageAnimations } from "@/lib/message-animations";

type ChatMessage = UIMessage<
  unknown,
  UIDataTypes,
  {
    runCommand: {
      input: { command: string };
      output: { stdout: string };
    };
  }
>;

const chat = createChat<ChatMessage>()
  .user("Clean up the build folder.")
  .sleep(600)
  .assistant(({ writer }) => {
    writer.reasoning(
      "The build output lives in dist. Deleting it cannot be undone, so I should ask before I run the command."
    );
    writer.sleep(400);
    writer.tool("runCommand", {
      input: { command: "rm -rf dist" },
      needsApproval: true,
      output: { stdout: "" },
    });
  })
  .assistant(({ writer, toolCall }) => {
    writer.sleep(600);
    writer.text(
      toolCall?.approved
        ? "Removed the dist folder."
        : "Okay, I left the dist folder in place."
    );
  });

const initialMessages = chat.get(0);
const transport = chat.transport({ delayMs: 20 });

export function ConfirmationDemo() {
  const {
    messages,
    sendMessage,
    setMessages,
    status,
    addToolApprovalResponse,
  } = useChat<ChatMessage>({
    messages: initialMessages,
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
    transport,
  });
  const shouldReduceMotion = useReducedMotion();
  const nextMessage = chat.next(messages);
  const busy = status === "submitted" || status === "streaming";

  return (
    <div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      {messages.map((message) => {
        if (message.role === "user") {
          return (
            <motion.div
              animate={shouldReduceMotion ? undefined : "animate"}
              initial={shouldReduceMotion ? undefined : "initial"}
              key={message.id}
              variants={messageAnimations["slide-up"].variants}
            >
              <Message align="end">
                <MessageContent>
                  <Bubble align="end" variant="muted">
                    <BubbleContent>{getMessageText(message)}</BubbleContent>
                  </Bubble>
                </MessageContent>
              </Message>
            </motion.div>
          );
        }

        return (
          <motion.div
            animate={shouldReduceMotion ? undefined : "animate"}
            initial={shouldReduceMotion ? undefined : "initial"}
            key={message.id}
            variants={messageAnimations.fade.variants}
          >
            <Message>
              <MessageContent className="gap-4">
                {message.parts.map((part, index) => {
                  if (part.type === "text") {
                    return <p key={index}>{part.text}</p>;
                  }

                  if (part.type === "reasoning") {
                    return (
                      <Trace key={index}>
                        <ReasoningRow
                          running={part.state === "streaming"}
                          text={part.text}
                        />
                      </Trace>
                    );
                  }

                  if (part.type !== "tool-runCommand") {
                    return null;
                  }

                  if (part.state === "approval-requested") {
                    return (
                      <motion.div
                        animate={shouldReduceMotion ? undefined : "animate"}
                        initial={shouldReduceMotion ? undefined : "initial"}
                        key={part.toolCallId}
                        variants={messageAnimations["slide-up"].variants}
                      >
                        <Item variant="outline">
                          <ItemMedia>
                            <TerminalIcon />
                          </ItemMedia>
                          <ItemContent>
                            <ItemTitle>Run {part.input.command}?</ItemTitle>
                            <ItemDescription>
                              The command runs in this project.
                            </ItemDescription>
                          </ItemContent>
                          <ItemActions>
                            <Button
                              onClick={() =>
                                addToolApprovalResponse({
                                  approved: false,
                                  id: part.approval.id,
                                })
                              }
                              size="sm"
                              variant="outline"
                            >
                              Deny
                            </Button>
                            <Button
                              onClick={() =>
                                addToolApprovalResponse({
                                  approved: true,
                                  id: part.approval.id,
                                })
                              }
                              size="sm"
                            >
                              Approve
                            </Button>
                          </ItemActions>
                        </Item>
                      </motion.div>
                    );
                  }

                  const denied =
                    part.state === "output-denied" ||
                    (part.state === "approval-responded" &&
                      !part.approval.approved);

                  return (
                    <React.Fragment key={part.toolCallId}>
                      <Trace>
                        <TraceLine
                          status={
                            !denied && part.state !== "output-available"
                              ? "running"
                              : undefined
                          }
                        >
                          <TraceIcon>
                            <TerminalIcon />
                          </TraceIcon>
                          <TraceTitle>
                            {denied
                              ? "Denied"
                              : part.state === "output-available"
                                ? "Ran"
                                : "Running"}
                            {part.input?.command}
                          </TraceTitle>
                        </TraceLine>
                      </Trace>
                    </React.Fragment>
                  );
                })}
              </MessageContent>
            </Message>
          </motion.div>
        );
      })}
      {!busy && (
        <Button
          className="mt-auto self-start"
          onClick={() =>
            nextMessage
              ? sendMessage(nextMessage)
              : setMessages(initialMessages)
          }
          size="sm"
          variant="outline"
        >
          {nextMessage ? "Send message" : "Reset"}
        </Button>
      )}
    </div>
  );
}

function ReasoningRow({ text, running }: { text: string; running: boolean }) {
  const [open, setOpen] = React.useState<boolean>();

  return (
    <TraceCollapsible onOpenChange={setOpen} open={open ?? running}>
      <TraceCollapsibleTrigger>
        <TraceLine status={running ? "running" : undefined}>
          <TraceIcon>
            {running ? (
              <LoaderCircleIcon className="animate-spin" />
            ) : (
              <CircleCheckIcon />
            )}
          </TraceIcon>
          <TraceTitle>{running ? "Thinking" : "Thought"}</TraceTitle>
        </TraceLine>
      </TraceCollapsibleTrigger>
      <TraceCollapsibleContent className="whitespace-pre-wrap">
        {text}
      </TraceCollapsibleContent>
    </TraceCollapsible>
  );
}

Confirmation pauses a tool call and asks the user to approve or deny it before it runs. The pending tool renders as an Item card with Approve and Deny actions. Once the user responds, the card is replaced by a Trace line showing the outcome.

Confirmation is a composition — install the primitives, then wire the approval flow the same way the demo does.

Installation

Usage

Mark the tool call with needsApproval: true. The writer emits an approval-requested state instead of running the tool immediately.

chat.tsx
import { createChat } from "@frakment/ai";
import type { UIDataTypes, UIMessage } from "ai";
 
type ChatMessage = UIMessage<
  unknown,
  UIDataTypes,
  { runCommand: { input: { command: string }; output: { stdout: string } } }
>;
 
const chat = createChat<ChatMessage>()
  .user("Clean up the build folder.")
  .assistant(({ writer }) => {
    writer.tool("runCommand", {
      input: { command: "rm -rf dist" },
      needsApproval: true,
      output: { stdout: "" },
    });
  });

Wire the approval handler into useChat and let the SDK auto-send the follow-up turn.

chat.tsx
import { useChat } from "@ai-sdk/react";
import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
 
const { messages, addToolApprovalResponse } = useChat({
  messages: initialMessages,
  transport,
  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
});

Anatomy

A pending tool call renders as an Item card. Once approved or denied, it becomes a Trace line.

confirmation.tsx
{part.state === "approval-requested" ? (
  <Item variant="outline" size="sm">
    <ItemMedia variant="icon">
      <TerminalIcon />
    </ItemMedia>
    <ItemContent>
      <ItemTitle>Run {part.input.command}?</ItemTitle>
      <ItemDescription>The command runs in this project.</ItemDescription>
    </ItemContent>
    <ItemActions>
      <Button
        size="sm"
        variant="outline"
        onClick={() =>
          addToolApprovalResponse({ id: part.approval.id, approved: false })
        }
      >
        Deny
      </Button>
      <Button
        size="sm"
        onClick={() =>
          addToolApprovalResponse({ id: part.approval.id, approved: true })
        }
      >
        Approve
      </Button>
    </ItemActions>
  </Item>
) : (
  <Trace>
    <TraceLine status={!denied && part.state !== "output-available" ? "running" : undefined}>
      <TraceIcon><TerminalIcon /></TraceIcon>
      <TraceTitle>
        {denied ? "Denied" : part.state === "output-available" ? "Ran" : "Running"} 
        {part.input?.command}
      </TraceTitle>
    </TraceLine>
  </Trace>
)}
  • Item — the pending approval card with media, content, and actions.
  • Button — Approve (default) and Deny (outline).
  • Trace — the outcome row, shown after the user responds.
  • Message, Bubble — surrounding turn.

Approval states

The tool call moves through states:

StateRender
input-streaminghidden (input not yet available)
approval-requestedItem card with Approve / Deny
approval-respondedTrace line, running if approved
output-availableTrace line showing "Ran [command]"
output-deniedTrace line showing "Denied [command]"

Animation

User turns animate with the slide-up variant, assistant turns fade in, and the approval card slides up when it appears.

confirmation.tsx
import { MESSAGE_ANIMATIONS } from "@/lib/message-animations";
import { motion, useReducedMotion } from "motion/react";
 
const shouldReduceMotion = useReducedMotion();
 
<motion.div
  animate={shouldReduceMotion ? undefined : "animate"}
  initial={shouldReduceMotion ? undefined : "initial"}
  variants={MESSAGE_ANIMATIONS["slide-up"].variants}
>
  <Item variant="outline" size="sm">...</Item>
</motion.div>

Motion is skipped when the user prefers reduced motion.

Next

  • Chat — full streaming chat surface.
  • Checkpoint — restore points in a conversation.
  • Trace — collapsible reasoning and tool-call lines.
  • Item — card with media, content, and actions.

Accessibility

  • The approval card is an Item with role="group". Both buttons are focusable and labelled ("Approve", "Deny").
  • addToolApprovalResponse resolves on click and keyboard. The card unmounts and focus returns to the transcript.
  • The pending state is announced with aria-live="polite". Do not use assertive.
  • The resulting Trace line reports "Ran command" or "Denied command".

Best Practices

  • Ask only when needed. Set needsApproval: true for destructive or outbound actions.
  • Show the exact command. The user needs to see what will run.
  • Use clear verbs. "Approve" and "Deny" beat "Yes" and "No".
  • Resolve the tool immediately after approval. Emit output-available or output-denied.
  • Do not double-prompt. Once responded, hide the card and stream the outcome.