@lotics/ui 14.3.0 → 15.0.0

package/AGENTS.md

@@ -1,31 +1,5 @@
 # @lotics/ui — the UI reference index
 
-> **Upgrading to v13 from 12.x.** `RadioPicker`'s **`direction`** prop was removed — the
-> picker is always the stacked column of full-width choices. A former `direction="row"`
-> usage just drops the prop. Additively, `DetailRow` and `FormField` gained a **`warning`**
-> field annotation (amber, the third tone between `description` and `error`).
-
-> **Upgrading to v12 from 11.x.** Two exports were removed: **`CommentComposer`** (compose
-> comments with THE kit `Composer` — attach via `actionsButton`/`files`; `CommentList` is
-> unchanged) and **`DetailRow.info`** (field annotations are explicit — use the new
-> **`DetailRow.description`** under the value and **`DetailRow.error`**, the `FormField`
-> vocabulary; heading/card `info` ⓘ props are untouched). Visual behavior changes:
-> `SubsectionStack` is SPACE-ONLY (32px beat, no hairlines — titles carry the grouping),
-> `Section` heading gap 12→16, `DetailTable` row gap 6→8, `DetailRow` rows top-align with
-> label/control/trailing centered on the first control line, `Timeline` grew to 32px
-> discs / 16px icons / 40px minimum rows, `TextInputField` paints a WHITE surface on any
-> background (it was transparent — identical on the white canvas, visible on tinted
-> panels), and the inline editors' resting chip gained 6px vertical padding (identical for
-> one-line values; multi-line resting content now breathes).
-
-> **Upgrading to v11 from ≤10.x — the type scale was re-slotted.** The display sizes gained the
-> missing `##` step: `xl` is now 22/24 (section title), `xxl` is 28/32 (page/record title — the
-> OLD `xl` look), and the new `xxxl` is 32/48 (hero numbers — the OLD `xxl` look). Migrate an
-> app with two renames IN THIS ORDER: first `size="xxl"` → `size="xxxl"`, then `size="xl"` →
-> `size="xxl"` — every existing usage keeps its exact look. Also: `SectionHeadingTitle` is now
-> ALWAYS `##` (22/24), and disabled `Button`s fade their label to the zinc-400 disabled ink on
-> every variant EXCEPT `primary`, which keeps inverted ink over its washed surface.
-
 The component kit for Lotics custom-code apps and the product frontend: React-Native-Web
 primitives (renders on web **and** native), data-entry patterns, AI surfaces, a composition
 grammar, and worked-example screens. It pairs with **`@lotics/app-sdk`** (data + RPC — read
@@ -33,7 +7,8 @@ grammar, and worked-example screens. It pairs with **`@lotics/app-sdk`** (data +
 
 This file is the index. The comprehensive references live in **`docs/`** — read the owning area
 doc before building any screen, **never from memory**. Exact props are the shipped sources
-(`src/<name>.tsx`); full worked screens are `examples/tpl_*.tsx`.
+(`src/<name>.tsx`); full worked screens are `examples/tpl_*.tsx`. Everything here describes the
+CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 
 ## The area references
 

package/MIGRATION.md

@@ -0,0 +1,44 @@
+# @lotics/ui — migration notes
+
+Breaking changes per major, newest first. The current contract lives in `AGENTS.md` + `docs/`;
+this file exists only to move an app from one major to the next.
+
+## v15 from 14.x
+
+`AgentRun`/`AgentProgress`'s **`labelForTool`** prop was replaced by **`labelForCall`** — the
+callback now receives the whole call (`AgentToolCall = { toolName, input, state }`) instead of
+just the name, so labels can vary by input and by the new **`awaiting`** step state (ai's
+`approval-requested`, rendered as an amber parked row). Additively: `renderToolOutput` (replace
+an expanded step's Output panel), `onRetry` (a retry button under the terminal error row), and
+the new `ApprovalPrompt` + `MessageActions` components with their locale slices.
+
+## v13 from 12.x
+
+`RadioPicker`'s **`direction`** prop was removed — the picker is always the stacked column of
+full-width choices. A former `direction="row"` usage just drops the prop. Additively, `DetailRow`
+and `FormField` gained a **`warning`** field annotation (amber, the third tone between
+`description` and `error`).
+
+## v12 from 11.x
+
+Two exports were removed: **`CommentComposer`** (compose comments with THE kit `Composer` —
+attach via `actionsButton`/`files`; `CommentList` is unchanged) and **`DetailRow.info`** (field
+annotations are explicit — use the new **`DetailRow.description`** under the value and
+**`DetailRow.error`**, the `FormField` vocabulary; heading/card `info` ⓘ props are untouched).
+Visual behavior changes: `SubsectionStack` is SPACE-ONLY (32px beat, no hairlines — titles carry
+the grouping), `Section` heading gap 12→16, `DetailTable` row gap 6→8, `DetailRow` rows top-align
+with label/control/trailing centered on the first control line, `Timeline` grew to 32px discs /
+16px icons / 40px minimum rows, `TextInputField` paints a WHITE surface on any background (it was
+transparent — identical on the white canvas, visible on tinted panels), and the inline editors'
+resting chip gained 6px vertical padding (identical for one-line values; multi-line resting
+content now breathes).
+
+## v11 from ≤10.x
+
+The type scale was re-slotted — the display sizes gained the missing `##` step: `xl` is now 22/24
+(section title), `xxl` is 28/32 (page/record title — the OLD `xl` look), and the new `xxxl` is
+32/48 (hero numbers — the OLD `xxl` look). Migrate an app with two renames IN THIS ORDER: first
+`size="xxl"` → `size="xxxl"`, then `size="xl"` → `size="xxl"` — every existing usage keeps its
+exact look. Also: `SectionHeadingTitle` is now ALWAYS `##` (22/24), and disabled `Button`s fade
+their label to the zinc-400 disabled ink on every variant EXCEPT `primary`, which keeps inverted
+ink over its washed surface.

package/docs/ai_patterns.md

@@ -111,7 +111,10 @@ text, NOT all text on top of a flat step list. Content parts with no feed repres
 tool part's `input`/`output` are hidden in the row and **expand in place** on press — auto-built
 Input / Output `JsonPanel`s roll out under the row (the same disclosure pattern as "Thinking",
 never a popover). A tool in an `output-error` state flows like any other call — the dot goes
-amber and its `errorText` shows in the expanded Error panel.
+amber and its `errorText` shows in the expanded Error panel. To render a tool's OUTPUT yourself
+(an image preview, a table) pass **`renderToolOutput`** — the ONLY render escape hatch: it fires
+when an output-carrying step is expanded, and a non-`undefined` return replaces the default
+Output panel; `undefined` keeps it. Input + error rendering are untouched.
 
 **Activity grouping.** Consecutive tool parts fold into ONE group. While the agent is mid-tools
 the tail group is a SINGLE pulsing row whose label swaps in place as each call fires (no growing
@@ -123,18 +126,24 @@ no global terminal node.
 
 **Tool labels.** A tool part carries the RAW tool name (`update_records` from `tool-update_records`,
 or a `dynamic-tool`'s `toolName`), resolved via a built-in map of the platform record/document
-tools + an optional `labelForTool` override (localize THERE — the kit stays English); unknown
-names fall back to a prettified form. `stepsLabel` localizes the "{n} steps" suffix. The tool
-`state` collapses ai's lifecycle to running / done / error (an approval-pending state reads as
-running — a read-only feed has no approval control). The whole-run `state` prop
-(`"streaming" | "done" | "error"`) defaults to `streaming` while any tool is running, else `done`.
+tools + an optional **`labelForCall`** override (localize THERE — the kit stays English). It gets
+the whole call — `{ toolName, input, state }` (`AgentToolCall`) — so a caller can phrase by what the
+call targets or by whether it's awaiting; return `undefined` to fall back. Unknown names fall back
+to a prettified form. `stepsLabel` localizes the "{n} steps" suffix. The tool `state` folds ai's
+7-state lifecycle to **running / awaiting / done / error**: `approval-requested` → `awaiting` (the
+call is parked on a human decision — an amber dot + an "awaiting" annotation, and it NEVER pulses,
+because it isn't working); `approval-responded` → running; `output-denied` → error carrying the
+denial reason. The whole-run `state` prop (`"streaming" | "done" | "error"`) defaults to `streaming`
+while any tool is running, else `done` (an awaiting call is not running, so it settles).
 
 **Errors — two kinds, both surfaced, neither shouting.** An INTERMEDIARY tool failure rides in
 that tool's `output-error` part and flows like a normal call — the amber dot marks it (a settled
 group's header goes amber too), the reason waits in the expanded Error panel; real runs retry and
 move on, so the feed doesn't dramatize it. A BREAKING error that terminates the whole run lives
 OUTSIDE `parts` (chat persists it in the message's `errors`; `useAgentRun().error` carries it) —
-pass it as the `error` prop and it renders as a terminal danger row under the transcript.
+pass it as the `error` prop and it renders as a terminal danger row under the transcript. Pass
+**`onRetry`** alongside it and a Retry action (a secondary `Button`) rides under that row so the
+operator can re-fire the run; omit it and the error row renders exactly as before.
 
 **In a bounded container, wrap it in `FollowScroll`.** An `AgentRun` streaming inside a dialog,
 drawer, or fixed-height panel grows BELOW the fold — a plain scroll container doesn't follow. Wrap
@@ -149,24 +158,39 @@ list is already inverted and doesn't need the wrapper.
 
 Fed natively by `@lotics/app-sdk`'s `useAgentRun().parts` (reasoning + per-tool I/O + state come
 for free — no hand-assembly): `<AgentRun parts={run.parts} state={…} error={run.error} />` — see
-[the SDK doc](../../app-sdk/docs/ai.md) for the hook. Requires `ai` as an optional (type-only) peer.
+[the SDK doc](../../app-sdk/docs/ai.md) for the hook. The `ai` package is a regular dependency of
+`@lotics/ui` — its part TYPES resolve transitively in any consumer's typecheck with nothing to
+install; the imports are type-only (purity-enforced), so no `ai` runtime ever enters a bundle.
 **Reasoning only shows when the model produces it** — the declared model must support thinking
 (Sonnet / Opus, not Haiku); the renderer shows every reasoning part it's handed.
 
-**Limitation:** the collapsed reasoning row's "Thinking" label and the expanded detail's
-"Input"/"Output"/"Error" panel titles are currently English-only (not on the locale provider and
-not prop-overridable); `labelForTool`/`stepsLabel` localize everything else in the feed.
+**Localization.** The feed's fixed chrome — the "Thinking" label, the "Input"/"Output"/"Error"
+panel titles, the "awaiting" annotation, and the "Retry" action — resolves through the
+`LoticsLocale` `agentRun` slice (translate once at the provider; a `vi` app gets them for free).
+It is provider-localized, not per-instance prop-overridable; `labelForCall`/`stepsLabel` localize
+the tool labels and the "{n} steps" suffix per call site.
+
+**Answering an awaiting call — `ApprovalPrompt`.** The `awaiting` row inside `AgentRun` is
+READ-ONLY — it only NAMES that a call is parked on a human decision. The surface that ANSWERS it
+is `ApprovalPrompt` (`@lotics/ui/approval_prompt`): a warning icon + `message` (per-instance
+override, else the `approvalPrompt` slice default) on a bordered card, with **Deny** (secondary)
++ **Approve** (primary) right-aligned and an optional `children` slot for an input summary between
+them — `onApprove`/`onDeny` fire the SDK's approve/deny (the ai-sdk approval vocabulary). Slot it
+where the composer normally sits while the run is parked, so the operator reads the parked row in
+the feed and answers it below; on decision the run resumes (`approval-responded` → running) or the
+call settles denied (`output-denied` → error). Its strings resolve prop → the `approvalPrompt`
+locale slice → English.
 
 ### `AgentProgress` — the floating pill
 
 On a canvas/composer app reach for `AgentProgress` (`@lotics/ui/agent_progress`) — `AgentRun`
 collapsed into a floating pill (an animated `WaveAvatar` + the current step's label) that EXPANDS
-on press to the full feed in a capped scroll panel. It takes the same `items`/`state`/
-`labelForTool`/`stepsLabel`, plus `label` (override the collapsed text — defaults to the running
-step's label, else "Working…" / "Done" / "Stopped"; pass it to localize — note it's one static
-string, so it no longer tracks the running step) and `defaultExpanded`. Its pill matches
-`Composer`'s compact geometry, so the composer morphs into it while running and reveals again
-when done.
+on press to the full feed in a capped scroll panel. It takes the same `parts`/`state`/`error`, and
+forwards `labelForCall`/`renderToolOutput`/`onRetry`/`stepsLabel` to the expanded feed, plus `label`
+(override the collapsed text — defaults to the running step's label, else "Working…" / "Done" /
+"Stopped"; pass it to localize — note it's one static string, so it no longer tracks the running
+step) and `defaultExpanded`. Its pill matches `Composer`'s compact geometry, so the composer morphs
+into it while running and reveals again when done.
 
 **Limitation:** the pill's expand/collapse accessibility labels ("Show the agent's steps" /
 "Hide the agent's steps") are currently hardcoded English.

package/docs/catalog.md

@@ -263,7 +263,14 @@ a plain `metric` prop remains for one-number findings. The children slot compose
 result — a compact `Table` for per-line detail (danger color on the offending cells),
 `ProgressBar` for consumption-toward-a-cliff (free time, credit), dot `Badge`s for a
 present/missing checklist, `Confidence` for judgment calls. Display-only — it informs the
-verdict the host records; `finding` locale slice).
+verdict the host records; `finding` locale slice). `ApprovalPrompt` (the surface that ANSWERS
+an agent's approval-gated action — the interactive counterpart to `AgentRun`'s read-only amber
+`awaiting` row: a warning icon + message on a bordered card, Deny/Approve right-aligned, an
+optional `children` input summary; slot it where the composer sits while the run is parked;
+`approvalPrompt` locale slice), `MessageActions` (THE single shared per-message chrome bar for a
+chat transcript — copy with owned copied-feedback, regenerate, edit, and the branch/version
+pager as an internal part; each action renders only when its handler is given, so the assistant
+bar and the user bar are one component with different handlers; `messageActions` locale slice).
 
 ---
 
@@ -986,20 +993,40 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`composer`** — `Composer`: the adaptive command/chat composer — a compact pill that
   expands for long text + attachments (`pills` + attachment slots, controlled or
   uncontrolled `value`, `onSend`/`onStop`, `sendDisabled` override).
-- **`agent_run`** — `AgentRun` + `resolveToolMeta`: the live streaming work feed. Its prop is the
-  agent message's ai-sdk `parts` (`UIMessagePart[]` — text, reasoning, and tool parts), fed straight
-  from `useAgentRun().parts`; renders prose, a collapsed "Thinking" disclosure, and grouped tool
-  steps whose I/O expands in place on press (no popover). A per-tool failure shows amber with the
-  reason in its expanded Error panel; a run-level
-  breaking `error` (outside `parts`) renders as a terminal danger row. Needs `ai` as an optional
-  type-only peer. AI work ONLY —
-  deterministic work (template fill, an export) shows a `loading` state on its trigger and delivers
-  at once; dressing it as an agent run is theater.
+- **`agent_run`** — `AgentRun` + `resolveToolMeta` + `AgentToolCall` + `AgentToolOutput` (the
+  `renderToolOutput` call shape — `{ toolName, input, output }`): the live streaming work feed.
+  Its prop is the agent message's ai-sdk `parts` (`UIMessagePart[]` — text, reasoning, and tool
+  parts), fed straight from `useAgentRun().parts`; renders prose, a collapsed "Thinking" disclosure,
+  and grouped tool steps whose I/O expands in place on press (no popover). A tool `state` folds ai's
+  7-state lifecycle to running / **awaiting** / done / error — an `awaiting` call (parked on a human
+  approval) wears an amber dot + an "awaiting" annotation and never pulses. `labelForCall(call)`
+  localizes/overrides a step's label from the whole call (`AgentToolCall` = `{ toolName, input,
+  state }`); `renderToolOutput(call)` replaces a step's default Output panel (the one render escape
+  hatch — input/error untouched). A per-tool failure shows amber with the reason in its expanded
+  Error panel; a run-level breaking `error` (outside `parts`) renders as a terminal danger row, with
+  an optional `onRetry` Button under it. Fixed chrome (Thinking / Input / Output / Error / awaiting /
+  Retry) localizes via the `agentRun` locale slice. Needs `ai` as an optional type-only peer. AI
+  work ONLY — deterministic work (template fill, an export) shows a `loading` state on its trigger
+  and delivers at once; dressing it as an agent run is theater.
 - **`agent_transform`** — internal (no component): the one place that folds an ai-sdk `UIMessage`'s
   `parts` into the render timeline (`AgentUIPart`, `toSegments`, `lastRunningStep`), shared by
   `AgentRun` and `AgentProgress`. The sole file permitted to `import type` from `ai`.
 - **`agent_progress`** — `AgentProgress`: `AgentRun`'s compact, floating, expandable form (same
   `parts` prop) — a composer's working state.
+- **`approval_prompt`** — `ApprovalPrompt`: the surface that ANSWERS an agent's approval-gated
+  action — the interactive counterpart to `AgentRun`'s read-only amber `awaiting` row. A warning
+  icon + `message` (per-instance override; else the slice default) on a bordered card, `onDeny`
+  (secondary) + `onApprove` (primary) right-aligned, an optional `children` slot for an input
+  summary between them. Approve/deny is the ai-sdk approval vocabulary. Slot it where the composer
+  sits while the run is parked; the `approvalPrompt` locale slice.
+- **`message_actions`** — `MessageActions` + `MessageActionsBranch`: THE single shared per-message
+  action bar for a chat transcript — `onCopy` (the bar OWNS the copied feedback: the icon flips to
+  a check + the tooltip to "Copied" for ~2s, timer cleared on unmount; the handler only does the
+  clipboard write), `onRegenerate`, `onEdit`, and `branch` (the sibling-version pager, absorbed as
+  an internal part — renders when `total > 1`). Each action renders ONLY when its handler is given,
+  so an assistant bar (copy + regenerate) and a user bar (copy + edit) are the same component with
+  a different handler set. The bar hugs its content — the parent aligns it (left under an assistant
+  turn, right under a user bubble); the `messageActions` locale slice.
 - **`follow_scroll`** — `FollowScroll`: a scroll container that FOLLOWS its growing content —
   the chat message list's inverted mechanism packaged as a wrapper (single-cell inverted list),
   so the follow happens at LAYOUT level: each growth paints already pinned (no flash), scrolling

package/examples/tpl_item_list.tsx

@@ -1111,6 +1111,10 @@ function EnterDataDialog({ onCreate, onCreateMany }: {
   const [fileNames, setFileNames] = useState<string[]>([]);
   const [variant, setVariant] = useState<ManualVariant>("export");
   const [grouping, setGrouping] = useState<"customer" | "order">("customer");
+  // Q2's answer is load-bearing too: it decides how the unknown customer lands
+  // on the drafted records (create + link, leave unlinked, or the user's own
+  // instruction via the custom slot).
+  const [customerPlan, setCustomerPlan] = useState("New customer created and linked");
   // review state — per-card verdicts + the one editable value (the fee)
   const [cardStatus, setCardStatus] = useState<Record<string, ChangeStatus>>({});
   const [fees, setFees] = useState<Record<string, string>>({});
@@ -1151,6 +1155,7 @@ function EnterDataDialog({ onCreate, onCreateMany }: {
     setFileNames([]);
     setCardStatus({});
     setFees({});
+    setCustomerPlan("New customer created and linked");
     setKhach("");
     setDienThoai("");
     setPhi(null);
@@ -1233,6 +1238,14 @@ function EnterDataDialog({ onCreate, onCreateMany }: {
               onCancel={() => setPhase("intake")}
               onSubmit={(answers: ClarifyWizardAnswer[]) => {
                 setGrouping(answers[0]?.value === "order" ? "order" : "customer");
+                const plan = answers[1];
+                setCustomerPlan(
+                  plan?.custom
+                    ? plan.value
+                    : plan?.value === "skip"
+                      ? "Left unassigned — link a customer later"
+                      : "New customer created and linked",
+                );
                 setPhase("running");
               }}
             />
@@ -1256,6 +1269,9 @@ function EnterDataDialog({ onCreate, onCreateMany }: {
                   onUndo={() => setCardStatus((s) => ({ ...s, [p.id]: "pending" }))}
                 >
                   <ChangeField label="Customer" value={p.khach} summary={p.khach} />
+                  {p.khach === "Blue Harbor Foods" ? (
+                    <ChangeField label="Customer link" value={customerPlan} summary={customerPlan} />
+                  ) : null}
                   {p.dienThoai ? <ChangeField label="Phone" value={p.dienThoai} summary={p.dienThoai} /> : null}
                   <ChangeField label="Service fee" value={fees[p.id] ?? String(p.phi)} summary={formatMoney(Number(fees[p.id] ?? p.phi) || 0)}>
                     <ChangeValueInput value={fees[p.id] ?? String(p.phi)} onChangeText={(v) => setFees((s) => ({ ...s, [p.id]: v }))} accessibilityLabel={`Service fee for ${p.khach}`} />
@@ -1316,7 +1332,7 @@ function EnterDataDialog({ onCreate, onCreateMany }: {
           </DialogFooter>
         ) : phase === "review" ? (
           <DialogFooter>
-            <ChangeReviewActions onDiscard={close} onApply={applyProposals} applyLabel={`Add ${keptCount} ${keptCount === 1 ? "record" : "records"}`} />
+            <ChangeReviewActions onDiscard={close} onApply={applyProposals} applyLabel={keptCount > 0 ? `Add ${keptCount} ${keptCount === 1 ? "record" : "records"}` : "Add records"} />
           </DialogFooter>
         ) : null}
       </Dialog>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "14.3.0",
+  "version": "15.0.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -80,6 +80,8 @@
     "./activity_indicator": "./src/activity_indicator.tsx",
     "./agent_run": "./src/agent_run.tsx",
     "./agent_progress": "./src/agent_progress.tsx",
+    "./approval_prompt": "./src/approval_prompt.tsx",
+    "./message_actions": "./src/message_actions.tsx",
     "./follow_scroll": "./src/follow_scroll.tsx",
     "./markdown": {
       "react-native": "./src/markdown.tsx",
@@ -234,6 +236,7 @@
     "src",
     "examples",
     "AGENTS.md",
+    "MIGRATION.md",
     "docs"
   ],
   "publishConfig": {
@@ -248,6 +251,7 @@
   "dependencies": {
     "@lotics/docx": "^0.1.0",
     "@lotics/xlsx": "^0.1.0",
+    "ai": "^7.0.30",
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-gfm-footnote": "^2.1.0",
     "mdast-util-gfm-strikethrough": "^2.0.0",
@@ -266,13 +270,9 @@
     "react-dom": "^19.2.0",
     "react-native": ">=0.85.0",
     "react-native-svg": ">=15.0.0",
-    "react-native-web": ">=0.20.0",
-    "ai": ">=7.0.0"
+    "react-native-web": ">=0.20.0"
   },
   "peerDependenciesMeta": {
-    "ai": {
-      "optional": true
-    },
     "expo-image": {
       "optional": true
     },

package/src/agent_progress.tsx

@@ -5,7 +5,7 @@ import { Text } from "./text";
 import { WaveAvatar } from "./wave_avatar";
 import { FollowScroll } from "./follow_scroll";
 import { PressableHighlight } from "./pressable_highlight";
-import { AgentRun, resolveToolMeta } from "./agent_run";
+import { AgentRun, resolveToolMeta, type AgentRunProps, type AgentToolCall } from "./agent_run";
 import { toSegments, lastRunningStep, type AgentUIPart } from "./agent_transform";
 
 export interface AgentProgressProps {
@@ -18,9 +18,13 @@ export interface AgentProgressProps {
   /** The collapsed-pill label. Defaults to the running step's label (or
    *  "Working…" / "Done"). */
   label?: string;
-  /** Localize / override a tool step's label by raw tool name — applied to both
-   *  the collapsed pill and the expanded feed. */
-  labelForTool?: (toolName: string) => string | undefined;
+  /** Localize / override a tool step's label from the CALL — applied to both the
+   *  collapsed pill and the expanded feed. */
+  labelForCall?: (call: AgentToolCall) => string | undefined;
+  /** Replace a tool step's default output panel in the expanded feed. */
+  renderToolOutput?: AgentRunProps["renderToolOutput"];
+  /** Retry action under the expanded feed's terminal error row. */
+  onRetry?: () => void;
   /** Localized "{n} steps" suffix, forwarded to the expanded feed. */
   stepsLabel?: (n: number) => string;
   defaultExpanded?: boolean;
@@ -35,11 +39,11 @@ export interface AgentProgressProps {
  * label, so the surface stays calm until you ask to see the steps.
  */
 export function AgentProgress(props: AgentProgressProps) {
-  const { parts, state = "streaming", error, label, labelForTool, stepsLabel, defaultExpanded } = props;
+  const { parts, state = "streaming", error, label, labelForCall, renderToolOutput, onRetry, stepsLabel, defaultExpanded } = props;
   const [expanded, setExpanded] = useState(defaultExpanded ?? false);
 
   const running = lastRunningStep(toSegments(parts));
-  const runningLabel = running ? resolveToolMeta(running.toolName, labelForTool).label : undefined;
+  const runningLabel = running ? resolveToolMeta({ toolName: running.toolName, input: running.input, state: running.status }, labelForCall).label : undefined;
   const compact = label ?? runningLabel ?? (state === "done" ? "Done" : state === "error" ? "Stopped" : "Working…");
   const streaming = state === "streaming";
 
@@ -50,7 +54,7 @@ export function AgentProgress(props: AgentProgressProps) {
           {/* FollowScroll keeps the newest step in view as the run streams —
               a plain ScrollView would let new content grow below the fold. */}
           <FollowScroll style={{ maxHeight: 260 }} contentContainerStyle={{ padding: 16 }}>
-            <AgentRun parts={parts} state={state} error={error} labelForTool={labelForTool} stepsLabel={stepsLabel} />
+            <AgentRun parts={parts} state={state} error={error} labelForCall={labelForCall} renderToolOutput={renderToolOutput} onRetry={onRetry} stepsLabel={stepsLabel} />
           </FollowScroll>
         </View>
       ) : null}

package/src/agent_run.tsx

@@ -2,6 +2,7 @@ import { useState, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
 import { colors } from "./colors";
 import { Text } from "./text";
+import { Button } from "./button";
 import { Icon, type IconName } from "./icon";
 import { Markdown } from "./markdown";
 import { JsonPanel, stringifyData } from "./json_panel";
@@ -14,7 +15,24 @@ import { useLoticsLocale, type LoticsLocale } from "./locale";
 // The render model comes STRAIGHT from ai-sdk `UIMessage.parts` — no bespoke
 // transcript type. `agent_transform` is the one place that folds parts into the
 // timeline; this file is the renderer.
-import { toSegments, anyRunning, type AgentUIPart, type AgentStep } from "./agent_transform";
+import { toSegments, anyRunning, type AgentUIPart, type AgentStep, type AgentStepStatus } from "./agent_transform";
+
+/** A resolved tool call as a `labelForCall` sees it: the RAW tool name, the
+ *  input it was invoked with, and its settle state. Richer than a name-only map,
+ *  so a caller can phrase a call by what it targets or by whether it's awaiting. */
+export interface AgentToolCall {
+  toolName: string;
+  input: unknown;
+  state: AgentStepStatus;
+}
+
+/** A settled tool call as `renderToolOutput` sees it — the output stands in for
+ *  the state (only an output-carrying step reaches the renderer). */
+export interface AgentToolOutput {
+  toolName: string;
+  input: unknown;
+  output: unknown;
+}
 
 export interface AgentRunProps {
   /** The agent message's ai-sdk `parts` — the ordered transcript, rendered in
@@ -30,10 +48,20 @@ export interface AgentRunProps {
    *  it renders as a terminal danger row under the transcript. A per-tool failure
    *  is different — it rides in that tool's own `output-error` part. */
   error?: string;
-  /** Localize / override a TOOL step's display label by its raw tool name
-   *  (`update_records` → "Đang cập nhật dữ liệu"). Return `undefined` to fall
+  /** Localize / override a TOOL step's display label from the CALL — its raw
+   *  name, input, and state (`update_records` → "Đang cập nhật dữ liệu"; or a
+   *  distinct phrasing while `state === "awaiting"`). Return `undefined` to fall
    *  back to the built-in label. */
-  labelForTool?: (toolName: string) => string | undefined;
+  labelForCall?: (call: AgentToolCall) => string | undefined;
+  /** Replace the DEFAULT `JsonPanel` output rendering of an expanded tool step —
+   *  the only render escape hatch. Called only when a step carrying an output is
+   *  actually EXPANDED; a non-`undefined` return replaces the output panel (an
+   *  image preview, a table), while `undefined` keeps the default panel. Input +
+   *  error rendering are unaffected. */
+  renderToolOutput?: (call: AgentToolOutput) => ReactNode | undefined;
+  /** When the run ended on a terminal `error`, render a retry action under that
+   *  danger row. Omit it and the error row renders exactly as before. */
+  onRetry?: () => void;
   /** Localized "{n} steps" suffix on a collapsed activity group (the kit is
    *  locale-neutral). Default `"{n} steps"`. */
   stepsLabel?: (n: number) => string;
@@ -42,7 +70,7 @@ export interface AgentRunProps {
 
 // ── Tool → display meta ───────────────────────────────────────────────────────
 // The bounded set of platform tools an app agent can call. English by default
-// (the kit is locale-neutral; apps localize via `labelForTool`). A tool the map
+// (the kit is locale-neutral; apps localize via `labelForCall`). A tool the map
 // doesn't know falls back to a prettified name + a neutral icon.
 const TOOL_META: Record<string, { label: string; icon: IconName }> = {
   query_records: { label: "Searching records", icon: "search" },
@@ -65,23 +93,23 @@ function prettifyToolName(name: string): string {
  *  then the built-in map, then a prettified fallback. Exported so other agent
  *  surfaces (e.g. `AgentProgress`) render the same labels. */
 export function resolveToolMeta(
-  toolName: string,
-  labelForTool?: (toolName: string) => string | undefined,
+  call: AgentToolCall,
+  labelForCall?: (call: AgentToolCall) => string | undefined,
 ): { label: string; icon: IconName } {
   const def =
-    TOOL_META[toolName] ??
-    (toolName.startsWith("generate_") && toolName.endsWith("_from_template")
+    TOOL_META[call.toolName] ??
+    (call.toolName.startsWith("generate_") && call.toolName.endsWith("_from_template")
       ? { label: "Generating document", icon: "file-text" as IconName }
       : undefined);
   return {
-    label: labelForTool?.(toolName) ?? def?.label ?? prettifyToolName(toolName),
+    label: labelForCall?.(call) ?? def?.label ?? prettifyToolName(call.toolName),
     icon: def?.icon ?? "list",
   };
 }
 
-/** Resolve a tool step's display label from its raw tool name. */
-function stepLabel(s: AgentStep, labelForTool?: (toolName: string) => string | undefined): string {
-  return resolveToolMeta(s.toolName, labelForTool).label;
+/** Resolve a tool step's display label from its call. */
+function stepLabel(s: AgentStep, labelForCall?: (call: AgentToolCall) => string | undefined): string {
+  return resolveToolMeta({ toolName: s.toolName, input: s.input, state: s.status }, labelForCall).label;
 }
 
 const INK = colors.zinc[700];
@@ -96,7 +124,8 @@ const INK = colors.zinc[700];
  * Pair with `Composer` + `ChangeReview`.
  */
 export function AgentRun(props: AgentRunProps) {
-  const { parts, labelForTool, stepsLabel = (n) => `${n} steps`, accessibilityLabel } = props;
+  const { parts, labelForCall, renderToolOutput, onRetry, stepsLabel = (n) => `${n} steps`, accessibilityLabel } = props;
+  const locale = useLoticsLocale();
   const segments = toSegments(parts);
   const state = props.state ?? (anyRunning(segments) ? "streaming" : "done");
   const streaming = state === "streaming";
@@ -125,23 +154,32 @@ export function AgentRun(props: AgentRunProps) {
             active={streaming && i === lastIndex}
             expanded={!!expanded[seg.id]}
             onToggle={() => toggle(seg.id)}
-            labelForTool={labelForTool}
+            labelForCall={labelForCall}
+            renderToolOutput={renderToolOutput}
             stepsLabel={stepsLabel}
           />
         );
       })}
       {/* A run-level BREAKING error terminates the feed with a danger row. It lives
-          outside `parts` (the stream failed), so the caller passes it explicitly. */}
+          outside `parts` (the stream failed), so the caller passes it explicitly.
+          A retry action rides UNDER it when the caller can restart the run. */}
       {props.error ? (
-        <View style={styles.row}>
-          <View style={styles.dotCol}>
-            <Icon name="circle-alert" size={17} color={colors.red[500]} />
-          </View>
-          <View style={styles.rowBody}>
-            <Text size="sm" color="danger">
-              {props.error}
-            </Text>
+        <View style={{ gap: 8 }}>
+          <View style={styles.row}>
+            <View style={styles.dotCol}>
+              <Icon name="circle-alert" size={17} color={colors.red[500]} />
+            </View>
+            <View style={styles.rowBody}>
+              <Text size="sm" color="danger">
+                {props.error}
+              </Text>
+            </View>
           </View>
+          {onRetry ? (
+            <View style={styles.retry}>
+              <Button title={locale.agentRun.retry} color="secondary" icon="rotate-ccw" alignSelf="flex-start" onPress={onRetry} />
+            </View>
+          ) : null}
         </View>
       ) : null}
     </View>
@@ -179,24 +217,37 @@ function ActivityRow(props: {
   return <View style={styles.row}>{inner}</View>;
 }
 
-function StepBody({ label }: { label: string }) {
-  return <Text size="sm">{label}</Text>;
+// The step label, plus a muted "· {awaiting}" annotation when the call is parked
+// on a human decision (its amber dot already signals the state; the word names it).
+function StepBody({ label, awaiting }: { label: string; awaiting?: string }) {
+  return (
+    <Text size="sm">
+      {label}
+      {awaiting ? (
+        <Text size="sm" color="muted">
+          {"  ·  " + awaiting}
+        </Text>
+      ) : null}
+    </Text>
+  );
 }
 
 // The on-demand reveal for a tool step: Input / Output / Error panels auto-built
 // from the carried I/O; nothing if there's none. Raw I/O stays OUT of the row — only
-// shown here, on demand. Panel titles come from the locale.
-function stepDetail(s: AgentStep, labels: LoticsLocale["agentRun"]): ReactNode {
+// shown here, on demand. Panel titles come from the locale. A caller's
+// `renderToolOutput` replaces the OUTPUT panel (input + error stay auto-built).
+function stepDetail(s: AgentStep, labels: LoticsLocale["agentRun"], renderToolOutput?: AgentRunProps["renderToolOutput"]): ReactNode {
   const hasInput = s.input !== undefined;
   const hasOutput = s.output !== undefined;
   if (!hasInput && !hasOutput && !s.errorText) return null;
+  const customOutput = hasOutput && renderToolOutput ? renderToolOutput({ toolName: s.toolName, input: s.input, output: s.output }) : undefined;
   return (
     <View style={{ gap: 8 }}>
       {hasInput ? <JsonPanel title={labels.input} value={stringifyData(s.input)} /> : null}
       {s.errorText ? (
         <JsonPanel title={labels.error} value={s.errorText} />
       ) : hasOutput ? (
-        <JsonPanel title={labels.output} value={stringifyData(s.output)} />
+        customOutput !== undefined ? customOutput : <JsonPanel title={labels.output} value={stringifyData(s.output)} />
       ) : null}
     </View>
   );
@@ -205,24 +256,28 @@ function stepDetail(s: AgentStep, labels: LoticsLocale["agentRun"]): ReactNode {
 // A settled step row. When the step carries I/O (or an error) it EXPANDS IN PLACE on
 // press — the panels roll out under the row (same disclosure pattern as "Thinking"),
 // never a popover — so an errored call reads like any other step until you open it.
-function StepRow({ s, label }: { s: AgentStep; label: string }) {
+// An `awaiting` call wears the amber dot + an "awaiting" annotation, like an error.
+function StepRow({ s, label, renderToolOutput }: { s: AgentStep; label: string; renderToolOutput?: AgentRunProps["renderToolOutput"] }) {
   const locale = useLoticsLocale();
   const [open, setOpen] = useState(false);
-  const detail = stepDetail(s, locale.agentRun);
-  const marker: StepStatus = s.status === "error" ? "warning" : "done";
-  if (!detail) {
+  // Pressability is decided by a cheap carried-I/O check; the detail (and any
+  // caller `renderToolOutput`) is built only once the row is actually opened.
+  const hasDetail = s.input !== undefined || s.output !== undefined || !!s.errorText;
+  const marker: StepStatus = s.status === "error" || s.status === "awaiting" ? "warning" : "done";
+  const awaiting = s.status === "awaiting" ? locale.agentRun.awaiting : undefined;
+  if (!hasDetail) {
     return (
       <ActivityRow markerStatus={marker}>
-        <StepBody label={label} />
+        <StepBody label={label} awaiting={awaiting} />
       </ActivityRow>
     );
   }
   return (
     <View>
       <ActivityRow markerStatus={marker} onPress={() => setOpen((o) => !o)} accessibilityLabel={label} trailing={chevron(open ? "up" : "down")}>
-        <StepBody label={label} />
+        <StepBody label={label} awaiting={awaiting} />
       </ActivityRow>
-      {open ? <View style={styles.rowDetail}>{detail}</View> : null}
+      {open ? <View style={styles.rowDetail}>{stepDetail(s, locale.agentRun, renderToolOutput)}</View> : null}
     </View>
   );
 }
@@ -274,17 +329,29 @@ function ToolGroup(props: {
   active: boolean;
   expanded: boolean;
   onToggle: () => void;
-  labelForTool?: (toolName: string) => string | undefined;
+  labelForCall?: (call: AgentToolCall) => string | undefined;
+  renderToolOutput?: AgentRunProps["renderToolOutput"];
   stepsLabel: (n: number) => string;
 }) {
-  const { steps, active, expanded, onToggle, labelForTool, stepsLabel } = props;
-  const resolve = (s: AgentStep) => stepLabel(s, labelForTool);
+  const { steps, active, expanded, onToggle, labelForCall, renderToolOutput, stepsLabel } = props;
+  const locale = useLoticsLocale();
+  const resolve = (s: AgentStep) => stepLabel(s, labelForCall);
 
   // ACTIVE — one pulsing row whose label swaps in place as each call fires (the
   // label is keyed by the current step's id, so a new call rises + fades into the
-  // SAME row instead of stacking a new dot).
+  // SAME row instead of stacking a new dot). BUT a call parked on a human decision
+  // (`awaiting`) is NOT working — it settles to the amber, non-pulsing awaiting row.
   if (active) {
     const current = steps[steps.length - 1];
+    if (current.status === "awaiting") {
+      return (
+        <View style={styles.group}>
+          <ActivityRow markerStatus="warning">
+            <StepBody label={resolve(current)} awaiting={locale.agentRun.awaiting} />
+          </ActivityRow>
+        </View>
+      );
+    }
     return (
       <View style={styles.group}>
         <ActivityRow markerStatus="current" live>
@@ -297,6 +364,7 @@ function ToolGroup(props: {
   }
 
   const errored = steps.some((s) => s.status === "error");
+  const awaiting = steps.some((s) => s.status === "awaiting");
   const final = steps[steps.length - 1];
   const expandable = steps.length > 1;
 
@@ -304,7 +372,7 @@ function ToolGroup(props: {
   if (!expandable) {
     return (
       <View style={styles.group}>
-        <StepRow s={final} label={resolve(final)} />
+        <StepRow s={final} label={resolve(final)} renderToolOutput={renderToolOutput} />
       </View>
     );
   }
@@ -317,7 +385,7 @@ function ToolGroup(props: {
   return (
     <View style={styles.group}>
       <ActivityRow
-        markerStatus={errored ? "warning" : "complete"}
+        markerStatus={errored || awaiting ? "warning" : "complete"}
         onPress={onToggle}
         accessibilityLabel={`${resolve(final)} — ${stepsLabel(steps.length)}`}
         trailing={chevron(expanded ? "up" : "down")}
@@ -327,7 +395,7 @@ function ToolGroup(props: {
       {expanded
         ? steps.map((s) => (
             <AnimationFadeIn key={s.id} translateY={4}>
-              <StepRow s={s} label={resolve(s)} />
+              <StepRow s={s} label={resolve(s)} renderToolOutput={renderToolOutput} />
             </AnimationFadeIn>
           ))
         : null}
@@ -360,4 +428,7 @@ const styles = StyleSheet.create({
   reasoning: { paddingLeft: 28, paddingBottom: 4 },
   // A step's expanded I/O panels — same left edge as the reasoning body.
   rowDetail: { paddingLeft: 28, paddingBottom: 6, paddingTop: 2 },
+  // The retry action under the terminal error — aligned to the message body
+  // (past the dot column + its gap), so it reads as a response to that row.
+  retry: { paddingLeft: 28 },
 });

package/src/agent_transform.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import { toSegments, anyRunning, lastRunningStep, type AgentUIPart, type AgentSegment, type AgentStep } from "./agent_transform";
+
+// RN-free logic test for the parts → timeline fold. The renderer (agent_run.tsx)
+// is verified visually in the gallery; the mapping — ai's 7-state tool machine to
+// the feed's 4 states, plus grouping — is unit-tested here. Fixtures are the ai-sdk
+// `dynamic-tool` part shape (contextually typed as `AgentUIPart`, so each concrete
+// `state` discriminates to the right member — no casts).
+
+function groups(parts: AgentUIPart[]): Extract<AgentSegment, { kind: "group" }>[] {
+  return toSegments(parts).filter((s): s is Extract<AgentSegment, { kind: "group" }> => s.kind === "group");
+}
+
+function onlyStep(parts: AgentUIPart[]): AgentStep {
+  const [group, ...rest] = groups(parts);
+  expect(rest).toHaveLength(0);
+  expect(group.steps).toHaveLength(1);
+  return group.steps[0];
+}
+
+describe("agent_transform — tool state mapping", () => {
+  it("input-streaming → running", () => {
+    expect(onlyStep([{ type: "dynamic-tool", toolName: "update_records", toolCallId: "t", state: "input-streaming", input: {} }]).status).toBe("running");
+  });
+
+  it("input-available → running", () => {
+    expect(onlyStep([{ type: "dynamic-tool", toolName: "update_records", toolCallId: "t", state: "input-available", input: {} }]).status).toBe("running");
+  });
+
+  it("approval-requested → awaiting (parked on a human decision)", () => {
+    const step = onlyStep([{ type: "dynamic-tool", toolName: "delete_records", toolCallId: "t", state: "approval-requested", input: { table: "Containers" }, approval: { id: "a1" } }]);
+    expect(step.status).toBe("awaiting");
+    // The input still rides along for the on-demand peek.
+    expect(step.input).toEqual({ table: "Containers" });
+  });
+
+  it("approval-responded → running (the decision is in, work resumes)", () => {
+    expect(onlyStep([{ type: "dynamic-tool", toolName: "delete_records", toolCallId: "t", state: "approval-responded", input: {}, approval: { id: "a1", approved: true } }]).status).toBe("running");
+  });
+
+  it("output-available → done, carrying the output", () => {
+    const step = onlyStep([{ type: "dynamic-tool", toolName: "query_records", toolCallId: "t", state: "output-available", input: { q: 1 }, output: { rows: 3 } }]);
+    expect(step.status).toBe("done");
+    expect(step.output).toEqual({ rows: 3 });
+  });
+
+  it("output-error → error, carrying errorText", () => {
+    const step = onlyStep([{ type: "dynamic-tool", toolName: "query_records", toolCallId: "t", state: "output-error", input: {}, errorText: "Unknown field" }]);
+    expect(step.status).toBe("error");
+    expect(step.errorText).toBe("Unknown field");
+  });
+
+  it("output-denied → error, with the denial reason as the error text", () => {
+    const step = onlyStep([{ type: "dynamic-tool", toolName: "delete_records", toolCallId: "t", state: "output-denied", input: {}, approval: { id: "a1", approved: false, reason: "Delete not permitted" } }]);
+    expect(step.status).toBe("error");
+    expect(step.errorText).toBe("Delete not permitted");
+  });
+
+  it("output-denied without a reason → error with no error text", () => {
+    const step = onlyStep([{ type: "dynamic-tool", toolName: "delete_records", toolCallId: "t", state: "output-denied", input: {}, approval: { id: "a1", approved: false } }]);
+    expect(step.status).toBe("error");
+    expect(step.errorText).toBeUndefined();
+  });
+});
+
+describe("agent_transform — streaming signals", () => {
+  it("anyRunning is true while a call runs, false once every call has settled", () => {
+    const running = toSegments([{ type: "dynamic-tool", toolName: "query_records", toolCallId: "t", state: "input-available", input: {} }]);
+    expect(anyRunning(running)).toBe(true);
+
+    const settled = toSegments([{ type: "dynamic-tool", toolName: "query_records", toolCallId: "t", state: "output-available", input: {}, output: {} }]);
+    expect(anyRunning(settled)).toBe(false);
+  });
+
+  it("an awaiting call is NOT running — it's parked, so the feed never pulses it", () => {
+    const parked = toSegments([{ type: "dynamic-tool", toolName: "delete_records", toolCallId: "t", state: "approval-requested", input: {}, approval: { id: "a1" } }]);
+    expect(anyRunning(parked)).toBe(false);
+    expect(lastRunningStep(parked)).toBeUndefined();
+  });
+});
+
+describe("agent_transform — grouping", () => {
+  it("folds consecutive tool parts into ONE group, split by prose", () => {
+    const parts: AgentUIPart[] = [
+      { type: "text", text: "First" },
+      { type: "dynamic-tool", toolName: "query_records", toolCallId: "a", state: "output-available", input: {}, output: {} },
+      { type: "dynamic-tool", toolName: "query_records", toolCallId: "b", state: "output-available", input: {}, output: {} },
+      { type: "text", text: "Then" },
+      { type: "dynamic-tool", toolName: "delete_records", toolCallId: "c", state: "approval-requested", input: {}, approval: { id: "a1" } },
+    ];
+    expect(toSegments(parts).map((s) => s.kind)).toEqual(["text", "group", "text", "group"]);
+    const [first, second] = groups(parts);
+    expect(first.steps.map((s) => s.id)).toEqual(["a", "b"]);
+    expect(second.steps.map((s) => s.status)).toEqual(["awaiting"]);
+  });
+});

package/src/agent_transform.ts

@@ -10,8 +10,11 @@ import type { UIMessagePart, UIDataTypes, UITools } from "ai";
 /** An ai-sdk message part, tool-set-agnostic (we only read `type` + a few fields). */
 export type AgentUIPart = UIMessagePart<UIDataTypes, UITools>;
 
-/** A tool step's settle state, collapsed from ai's 7-state tool machine. */
-export type AgentStepStatus = "running" | "done" | "error";
+/** A tool step's settle state, folded from ai's 7-state tool machine.
+ *  `awaiting` = the call is parked on a human decision (`approval-requested`) —
+ *  first-class, distinct from `running` (working) so the feed never pulses a
+ *  parked call. */
+export type AgentStepStatus = "running" | "awaiting" | "done" | "error";
 
 /** One tool call, reduced to what the feed shows. `toolName` is the RAW name — the
  *  renderer maps it to a human label + icon (`resolveToolMeta`). */
@@ -38,11 +41,15 @@ function isToolPart(part: AgentUIPart): part is Extract<AgentUIPart, { toolCallI
   return part.type === "dynamic-tool" || part.type.startsWith("tool-");
 }
 
-// ai's tool state machine → the feed's 3 states. Approval-pending/responded read as
-// "running" (a read-only feed has no approval affordance); denied reads as an error.
+// ai's 7-state tool machine → the feed's 4 states. `approval-requested` is
+// first-class `awaiting` (the call sits parked on a human decision);
+// `approval-responded` reads `running` until the resolved output arrives —
+// `output-available` on approve, `output-denied` (an error carrying the denial
+// reason) on deny. `input-streaming`/`input-available` are `running`.
 function toStatus(state: string): AgentStepStatus {
   if (state === "output-available") return "done";
   if (state === "output-error" || state === "output-denied") return "error";
+  if (state === "approval-requested") return "awaiting";
   return "running";
 }
 
@@ -53,7 +60,12 @@ function toStep(part: Extract<AgentUIPart, { toolCallId: string }>): AgentStep {
     status: toStatus(part.state),
     input: part.input,
     output: part.state === "output-available" ? part.output : undefined,
-    errorText: part.state === "output-error" ? part.errorText : undefined,
+    errorText:
+      part.state === "output-error"
+        ? part.errorText
+        : part.state === "output-denied"
+          ? part.approval.reason
+          : undefined,
   };
 }
 

package/src/approval_prompt.tsx

@@ -0,0 +1,70 @@
+import { type ReactNode } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors } from "./colors";
+import { Text } from "./text";
+import { Button } from "./button";
+import { Icon } from "./icon";
+import { useLoticsLocale } from "./locale";
+
+export interface ApprovalPromptProps {
+  /** Confirm the gated action — the agent proceeds. */
+  onApprove: () => void;
+  /** Reject the gated action — the agent does not proceed. */
+  onDeny: () => void;
+  /** Per-instance override of the prompt line (e.g. a browser-specific
+   *  phrasing); defaults to the `approvalPrompt` locale slice's `message`. */
+  message?: string;
+  /** Optional detail rendered between the message and the actions — e.g. a
+   *  summary of the input the agent is asking to run. */
+  children?: ReactNode;
+}
+
+/**
+ * The prompt that ANSWERS an agent's approval-gated action — the interactive
+ * counterpart to `AgentRun`'s read-only amber `awaiting` row. A warning icon +
+ * message on a bordered card, with Deny (secondary) + Approve (primary)
+ * right-aligned; the `children` slot renders an input summary between the two.
+ * Every string resolves prop → the `approvalPrompt` locale slice → English.
+ * Typically slotted where the composer sits while the run is parked.
+ */
+export function ApprovalPrompt(props: ApprovalPromptProps) {
+  const { onApprove, onDeny, message, children } = props;
+  const labels = useLoticsLocale().approvalPrompt;
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.content}>
+        <Icon name="shield-alert" size={20} color={colors.orange[600]} />
+        <Text size="sm" style={{ flex: 1 }}>
+          {message ?? labels.message}
+        </Text>
+      </View>
+      {children}
+      <View style={styles.actions}>
+        <Button title={labels.deny} color="secondary" onPress={onDeny} />
+        <Button title={labels.approve} color="primary" onPress={onApprove} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 12,
+    borderRadius: 16,
+    borderWidth: 2,
+    borderColor: colors.border,
+    backgroundColor: colors.background,
+    gap: 12,
+  },
+  content: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+  },
+  actions: {
+    flexDirection: "row",
+    justifyContent: "flex-end",
+    gap: 8,
+  },
+});

package/src/locale.tsx

@@ -129,10 +129,19 @@ export interface LoticsLocale {
   scrollToBottom: { tooltip: string };
   /** `TextInputField`: the clear-button tooltip. */
   textInputField: { clear: string };
-  /** `AgentRun`: the reasoning disclosure's label (settled / streaming) and the
-   *  auto-built tool peek's Input / Error / Output panel titles. (Tool-step labels
-   *  and the "{n} steps" suffix stay prop-localized — `labelForTool` / `stepsLabel`.) */
-  agentRun: { thinking: string; thinkingStreaming: string; input: string; error: string; output: string };
+  /** `AgentRun`: the reasoning disclosure's label (settled / streaming), the
+   *  auto-built tool peek's Input / Error / Output panel titles, the `awaiting`
+   *  annotation on a call parked on a human decision, and the terminal error's
+   *  `retry` action. (Tool-step labels and the "{n} steps" suffix stay
+   *  prop-localized — `labelForCall` / `stepsLabel`.) */
+  agentRun: { thinking: string; thinkingStreaming: string; input: string; error: string; output: string; awaiting: string; retry: string };
+  /** `ApprovalPrompt`: the default prompt line (overridable per instance) and
+   *  the Approve / Deny button labels — the surface that ANSWERS `AgentRun`'s
+   *  read-only `awaiting` row (approve/deny = the ai-sdk approval vocabulary). */
+  approvalPrompt: { message: string; approve: string; deny: string };
+  /** `MessageActions`: the copy tooltip + its flipped "copied" confirmation, the
+   *  regenerate and edit tooltips, and the branch pager's prev/next names. */
+  messageActions: { copy: string; copied: string; regenerate: string; edit: string; previousVersion: string; nextVersion: string };
 }
 
 /** The platform default — English. Every component's hardcoded default lives
@@ -228,7 +237,9 @@ export const en: LoticsLocale = {
   matrix: { total: "Total", less: "Less", more: "More" },
   scrollToBottom: { tooltip: "Scroll to bottom" },
   textInputField: { clear: "Clear" },
-  agentRun: { thinking: "Thinking", thinkingStreaming: "Thinking…", input: "Input", error: "Error", output: "Output" },
+  agentRun: { thinking: "Thinking", thinkingStreaming: "Thinking…", input: "Input", error: "Error", output: "Output", awaiting: "Awaiting", retry: "Retry" },
+  approvalPrompt: { message: "The assistant wants to perform an action that needs your approval.", approve: "Approve", deny: "Deny" },
+  messageActions: { copy: "Copy", copied: "Copied", regenerate: "Regenerate", edit: "Edit", previousVersion: "Previous version", nextVersion: "Next version" },
 };
 
 /** Vietnamese. Maintained once here so every app (and the frontend) shares one
@@ -324,7 +335,9 @@ export const vi: LoticsLocale = {
   matrix: { total: "Tổng", less: "Ít", more: "Nhiều" },
   scrollToBottom: { tooltip: "Cuộn xuống cuối" },
   textInputField: { clear: "Xóa" },
-  agentRun: { thinking: "Suy nghĩ", thinkingStreaming: "Đang suy nghĩ…", input: "Đầu vào", error: "Lỗi", output: "Kết quả" },
+  agentRun: { thinking: "Suy nghĩ", thinkingStreaming: "Đang suy nghĩ…", input: "Đầu vào", error: "Lỗi", output: "Kết quả", awaiting: "Chờ duyệt", retry: "Thử lại" },
+  approvalPrompt: { message: "Trợ lý muốn thực hiện thao tác cần bạn duyệt.", approve: "Cho phép", deny: "Từ chối" },
+  messageActions: { copy: "Sao chép", copied: "Đã sao chép", regenerate: "Tạo lại", edit: "Chỉnh sửa", previousVersion: "Phiên bản trước", nextVersion: "Phiên bản sau" },
 };
 
 const LoticsLocaleContext = createContext<LoticsLocale>(en);

package/src/message_actions.tsx

@@ -0,0 +1,111 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { StyleSheet, View } from "react-native";
+import { Text } from "./text";
+import { IconButton } from "./icon_button";
+import { useLoticsLocale } from "./locale";
+
+/** The branch/version pager slot — the previous/next controls over a message's
+ *  sibling versions. Rendered only when `total > 1`. */
+export interface MessageActionsBranch {
+  current: number;
+  total: number;
+  onPrevious: () => void;
+  onNext: () => void;
+  disabled?: boolean;
+}
+
+export interface MessageActionsProps {
+  /** Copy the message. The bar OWNS the copied feedback — the icon flips to a
+   *  check and the tooltip flips to "Copied" for ~2s (the timer is cleared on
+   *  unmount). The handler only performs the clipboard write — it reads the
+   *  message content the bar cannot see. */
+  onCopy?: () => void | Promise<void>;
+  /** Regenerate the (assistant) message. */
+  onRegenerate?: () => void;
+  /** Edit the (user) message. */
+  onEdit?: () => void;
+  /** The sibling-version pager, absorbed as an internal part of the bar. */
+  branch?: MessageActionsBranch;
+}
+
+/**
+ * The single shared per-message action bar — the branch/version pager, copy
+ * (with the owned copied-feedback contract), regenerate, and edit. Each action
+ * renders ONLY when its handler is provided, so an assistant bar (copy +
+ * regenerate) and a user bar (copy + edit) are the same component with a
+ * different handler set; the pager renders when `branch.total > 1`. The bar
+ * hugs its content, so the parent controls the row's side (left for an
+ * assistant turn, right for a user bubble). Strings resolve through the
+ * `messageActions` locale slice.
+ */
+export function MessageActions(props: MessageActionsProps) {
+  const { onCopy, onRegenerate, onEdit, branch } = props;
+  const labels = useLoticsLocale().messageActions;
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  // The copied flag flips back after a beat; the timer is cleared on unmount so
+  // a bar that disappears (last message loses its actions) never sets state on
+  // an unmounted tree.
+  useEffect(() => {
+    return () => {
+      if (timer.current) clearTimeout(timer.current);
+    };
+  }, []);
+
+  const handleCopy = useCallback(async () => {
+    await onCopy?.();
+    setCopied(true);
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => setCopied(false), 2000);
+  }, [onCopy]);
+
+  return (
+    <View style={styles.bar}>
+      {branch ? <BranchPager branch={branch} previousLabel={labels.previousVersion} nextLabel={labels.nextVersion} /> : null}
+      {onCopy ? (
+        <IconButton
+          testID="copy-button"
+          onPress={handleCopy}
+          icon={copied ? "check" : "copy"}
+          tooltip={copied ? labels.copied : labels.copy}
+        />
+      ) : null}
+      {onRegenerate ? (
+        <IconButton testID="regenerate-button" onPress={onRegenerate} icon="refresh-cw" tooltip={labels.regenerate} />
+      ) : null}
+      {onEdit ? (
+        <IconButton testID="edit-button" onPress={onEdit} icon="pencil" tooltip={labels.edit} />
+      ) : null}
+    </View>
+  );
+}
+
+// The sibling-version pager: [‹] {current} / {total} [›]. A single version has
+// nothing to page, so it renders nothing.
+function BranchPager({ branch, previousLabel, nextLabel }: { branch: MessageActionsBranch; previousLabel: string; nextLabel: string }) {
+  const { current, total, onPrevious, onNext, disabled } = branch;
+  if (total <= 1) return null;
+  return (
+    <View testID="branch-pagination" style={styles.branch}>
+      <IconButton testID="branch-prev" icon="chevron-left" tooltip={previousLabel} onPress={onPrevious} disabled={disabled || current <= 1} />
+      <Text size="xs" color="muted">
+        {current} / {total}
+      </Text>
+      <IconButton testID="branch-next" icon="chevron-right" tooltip={nextLabel} onPress={onNext} disabled={disabled || current >= total} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  bar: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 4,
+  },
+  branch: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 2,
+  },
+});