@lotics/ui 20.0.2 → 20.2.0

package/AGENTS.md

@@ -16,7 +16,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 |---|---|
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` for a custom-code app's `vite.config.ts`). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (incl. the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
-| [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split (modify → review-before-apply; create → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md). |
+| [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split (modify → review-before-apply; create → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md)., the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer) |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude, banded cards, register vs inset rows, master-detail `Drawer`, view controls, color discipline, typography, whitespace. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget). |
 

package/docs/ai_patterns.md

@@ -157,9 +157,10 @@ PUT and rolls the calls out BELOW it on press. The run ALWAYS ends on the agent'
 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 **`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
+or a `dynamic-tool`'s `toolName`), resolved through the active locale's **`agentRun.tools`** map —
+so a `vi` provider renders Vietnamese tool rows with no per-app wiring, the same way the rest of the
+feed's chrome already resolved. An optional **`labelForCall`** override still wins, for phrasing a
+call by what it TARGETS rather than by which tool ran. 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
@@ -206,8 +207,12 @@ feed**; the starting row IS the placeholder, consistent and localized.
 **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.
+— **and so are the tool labels** (`agentRun.tools`, keyed by raw tool name). Translating a tool
+row is no longer each app's job: an English row under a Vietnamese "Đang suy nghĩ…" was the kit
+contradicting itself. The "{n} steps" suffix is locale-backed too (`agentRun.steps`). `labelForCall`
+and `stepsLabel` remain as per-call-site OVERRIDES — for phrasing a row by what
+it targets — not as the only route to a translation. A tool name in neither the locale map nor
+`labelForCall` falls back to its prettified form.
 
 **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
@@ -360,6 +365,44 @@ drives the footer bar (same verbs, same answered-gating). Worked example:
 [`tpl_item_list`](../examples/tpl_item_list.tsx)'s intake fork (the wizard between the analyze
 and import runs, its actions in the footer).
 
+## The whole run in a dialog — `AgentRunScope` / `AgentRunPane` / `AgentRunActions`
+
+`@lotics/ui/agent_run_pane` is the two sections above already composed: the transcript while the
+agent works, the question IN ITS PLACE when it asks, and the wizard's verbs pinned in the footer.
+Reach for it whenever an agent run happens inside a dialog — which is nearly always. Three lines:
+
+```tsx
+const run = useAgentRun("intake");            // @lotics/app-sdk
+<AgentRunScope>                                {/* wraps the Dialog, like ClarifyWizardScope */}
+  <Dialog …>
+    <AgentRunPane run={run} onCancel={…} />                        {/* content */}
+    <DialogFooter><AgentRunActions run={run} /></DialogFooter>     {/* actions */}
+  </Dialog>
+</AgentRunScope>
+```
+
+**The parked question REPLACES the feed — that is the contract, not a style.** The run is blocked
+on the answer, so the question is the only thing to act on; it gets the dialog's own scroller and
+its actions sit outside it. Stacked under the transcript in an unscrollable box — the arrangement
+every app reached for first — a multi-question ask runs past the dialog's height and clips its own
+Submit, leaving a live `awaiting_input` run readable and unanswerable until it expires. The pane
+also swaps `FollowScroll` for `DialogScrollArea` on the park, so the question opens at the top
+rather than wherever the feed was scrolled to.
+
+**`run` is a SHAPE, not an import** (`AgentRunLike`: `status`, `parts`, `pendingChoice`,
+`answerChoice`, `error`; `AgentRunQuestion` names what `pendingChoice` carries, so a template or
+test declares one directly — an option is a label + description and the answer's value IS the
+label, which is the `ask_user_choice` wire shape, so nothing maps between two question types). `useAgentRun()` satisfies it structurally — `@lotics/ui` never depends on
+`@lotics/app-sdk` — which also means a template or test can hand it a plain object and exercise the
+whole pane with no backend ([`tpl_item_list`](../examples/tpl_item_list.tsx) does exactly that).
+
+**Customize through the seams, or drop to the primitives.** `labelForCall` / `renderToolOutput`
+pass through to `AgentRun`; the `run` object is the data seam. There is deliberately NO
+empty-state slot — `AgentRun` renders its own localized "Starting…" row on zero parts, and the law
+above forbids hand-rolling a placeholder. An app that wants a different ARRANGEMENT does not fight
+the pane: `AgentRun`, `ClarifyWizard`, `ClarifyWizardScope`/`Actions`, `FollowScroll` and
+`DialogScrollArea` all remain exported, and composing them is what this pane itself does.
+
 ## Provenance — `Sources`
 
 `Sources` (`@lotics/ui/sources`): openable chips saying where the output came FROM, under any

package/docs/catalog.md

@@ -1224,6 +1224,18 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   with **`ClarifyWizardScope`** and put **`ClarifyWizardActions`** in the `DialogFooter` — the
   wizard suppresses the inline row and drives the footer bar (same verbs, same gating), per the
   dialog grammar's footer-owns-actions law (worked example: `tpl_item_list`'s clarify phase).
+- **`agent_run_pane`** — `AgentRunScope` + `AgentRunPane` + `AgentRunActions` (+ `AgentRunLike`/`AgentRunQuestion`/`AgentRunOption`):
+  a whole agent run inside a dialog, in three lines. The pane streams `AgentRun` while the agent
+  works and, the moment it asks, renders the question IN PLACE OF the feed — in the dialog's own
+  scroller, with the wizard's verbs pinned in the `DialogFooter` via `AgentRunActions`. Replacing
+  rather than stacking is the CONTRACT: stacked under the transcript a multi-question ask clips
+  its own Submit and strands a live `awaiting_input` run. `run` is a structural shape
+  (`AgentRunLike`), so `useAgentRun()` satisfies it with no `@lotics/app-sdk` dependency and a
+  mock satisfies it with no backend — `AgentRunQuestion` names the question shape so a template
+  or test DECLARES one rather than mapping from `ClarifyWizardQuestion` (an option is a label +
+  description; the answer's value IS the label, the `ask_user_choice` wire shape). Seams:
+  `labelForCall` / `renderToolOutput`; no empty-state slot by design (`AgentRun` owns the
+  localized "Starting…" row). Worked example: `tpl_item_list`'s intake dialog.
 - **`choice_list`** — `ChoiceList` + `ChoiceOption`: selectable answer options as
   divider-separated rows (no bordered cards) with a per-row focus ring + hover wash; the
   agent's quick-reply surface. `allowCustom` appends an always-visible borderless multiline field whose

package/examples/tpl_item_list.tsx

@@ -52,15 +52,12 @@ import { FileGalleryModal } from "@lotics/ui/file_gallery_modal";
 import { Ledger, LedgerGroup, LedgerRow, LedgerTotal } from "@lotics/ui/ledger";
 import { ProgressBar } from "@lotics/ui/progress_bar";
 import { Dialog, DialogFooter, DialogHeader, DialogHeaderTitle, DialogScrollArea } from "@lotics/ui/dialog";
-import { AgentRun } from "@lotics/ui/agent_run";
-import { FollowScroll } from "@lotics/ui/follow_scroll";
-import { ClarifyWizard, ClarifyWizardActions, ClarifyWizardScope, type ClarifyWizardAnswer, type ClarifyWizardQuestion } from "@lotics/ui/clarify_wizard";
+import { AgentRunScope, AgentRunPane, AgentRunActions, type AgentRunLike, type AgentRunQuestion } from "@lotics/ui/agent_run_pane";
 import { ResultHeader } from "@lotics/ui/result_header";
 import { Confidence } from "@lotics/ui/confidence";
 import { CardSelectItem } from "@lotics/ui/card_select_item";
 import { FileDropzone } from "@lotics/ui/file_dropzone";
 import { FileDropTarget } from "@lotics/ui/file_drop_target";
-import { useScreenSize } from "@lotics/ui/use_screen_size";
 import { MemberSelect } from "@lotics/ui/member_select";
 import { Callout, CalloutText } from "@lotics/ui/callout";
 import { Timeline, type TimelineItem } from "@lotics/ui/timeline";
@@ -1052,8 +1049,8 @@ function LinkedRecordScreen({ ma }: { ma: string }) {
 
 // ─── Enter data — the INTAKE fork ────────────────────────────────────────────
 // AI FIRST, form as fallback. The one "Enter data" CTA opens a phased dialog:
-// drop files (the hero) → a short ANALYZE stream reads them → `ClarifyWizard`
-// asks the genuine ambiguities the analysis surfaced → the IMPORT stream
+// drop files (the hero) → a short ANALYZE stream reads them → the run asks the
+// genuine ambiguities the analysis surfaced → the IMPORT stream
 // CREATES the records and the dialog ends on the RESULT LIST — one row per
 // record with its key figures. This is the one law's creation branch: no
 // review gate on a create (nothing to diff — the register IS the review);
@@ -1064,7 +1061,8 @@ function LinkedRecordScreen({ ma }: { ma: string }) {
 // create-then-refine gate). The mock plays the clarify step as two phases; a
 // real app can run it as ONE agent run — every app agent carries
 // `ask_user_choice`, so the run parks on the agent's own question and
-// `useAgentRun().pendingChoice`/`answerChoice` drive this same wizard.
+// `AgentRunPane` renders it from `useAgentRun()` with no change to this file's
+// shape: the mock below satisfies the same `AgentRunLike` the hook does.
 
 type Part = UIMessagePart<UIDataTypes, UITools>;
 type IntakePhase = "intake" | "analyze" | "clarify" | "running" | "done" | "form";
@@ -1085,20 +1083,23 @@ const PROPOSED_BY_ORDER: Proposal[] = PROPOSED_BY_CUSTOMER.flatMap((c) =>
 
 // The wizard's questions come FROM the analysis (a real app renders them off the
 // analyze run's structured output) — informed, described, one custom-answer slot.
-const INTAKE_QUESTIONS: ClarifyWizardQuestion[] = [
+// Declared in the shape `pendingChoice` actually carries, so this reads like a
+// real run: an option is a LABEL plus its description, and the answer's value IS
+// that label (the `ask_user_choice` wire shape — there is no separate code).
+const INTAKE_QUESTIONS: AgentRunQuestion[] = [
   {
     question: "6 orders across 3 customers. How should they become records?",
-    answers: [
-      { value: "customer", label: "One record per customer", description: "3 records — each customer's orders grouped into one workspace and checklist." },
-      { value: "order", label: "One record per order", description: "6 records — every order tracked on its own; more rows, finer-grained status." },
+    options: [
+      { label: "One record per customer", description: "3 records — each customer's orders grouped into one workspace and checklist." },
+      { label: "One record per order", description: "6 records — every order tracked on its own; more rows, finer-grained status." },
     ],
   },
   {
     question: "Blue Harbor Foods isn't in the customer book yet. What should happen?",
-    allowCustom: true,
-    answers: [
-      { value: "create", label: "Create the customer", description: "A new customer record is added and linked as the records land." },
-      { value: "skip", label: "Leave unassigned", description: "The records are created without a customer — link one later from each record." },
+    allow_custom: true,
+    options: [
+      { label: "Create the customer", description: "A new customer record is added and linked as the records land." },
+      { label: "Leave unassigned", description: "The records are created without a customer — link one later from each record." },
     ],
   },
 ];
@@ -1137,7 +1138,6 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
   /** The import's save — rows land in the register as the stream finishes. */
   onCreateMany: (records: { khach: string; dienThoai: string; phi: number }[]) => void;
 }) {
-  const { small } = useScreenSize();
   const [phase, setPhase] = useState<IntakePhase>("intake");
   const [docs, setDocs] = useState<DisplayFile[]>([]);
   const [variant, setVariant] = useState<ManualVariant>("export");
@@ -1172,6 +1172,32 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
   const docNames = docs.map((d) => d.filename);
   const [revealed, setRevealed] = useState(0);
   const script = phase === "analyze" ? analyzeScript(docNames) : phase === "running" ? importScript(grouping) : [];
+
+  // What a real app hands the pane: `const run = useAgentRun("intake")`. The
+  // template has no backend, so it satisfies the same shape from its script —
+  // which is the point, the pane never knows the difference.
+  const run: AgentRunLike = {
+    status: phase === "clarify" ? "awaiting_input" : revealed >= script.length ? "completed" : "streaming",
+    parts: script.slice(0, revealed),
+    error: null,
+    pendingChoice:
+      phase === "clarify"
+        ? { questions: INTAKE_QUESTIONS }
+        : null,
+    answerChoice: async (answers) => {
+      // The answer's value is the LABEL the human picked — match on it.
+      setGrouping(answers[0]?.value === "One record per order" ? "order" : "customer");
+      const plan = answers[1];
+      setCustomerPlan(
+        plan?.custom
+          ? plan.value
+          : plan?.value === "Leave unassigned"
+            ? "Left unassigned — link a customer later"
+            : "New customer created and linked",
+      );
+      setPhase("running");
+    },
+  };
   useEffect(() => {
     if (phase !== "analyze" && phase !== "running") return;
     setRevealed(0);
@@ -1244,14 +1270,14 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
     : "Import from files";
 
   return (
-    <ClarifyWizardScope>
+    <AgentRunScope>
       {/* the file/stream phases (intake/analyze/clarify/running/done) run
-          WIDE — room for the thumbnail hero + the AgentRun/ClarifyWizard/result
+          WIDE — room for the thumbnail hero + the AgentRunPane/result
           panes; only the manual `form` stays a narrow single-column pane.
           760 sits just under the kit Dialog's default 786 maxWidth cap.
-          ClarifyWizardScope wraps the Dialog from OUTSIDE so the wizard's
-          Cancel/Back/Next/Submit render in the DialogFooter — the dialog
-          grammar's home for action bars — via ClarifyWizardActions. */}
+          AgentRunScope wraps the Dialog from OUTSIDE so the run's own action
+          bar renders in the DialogFooter — the dialog grammar's home for
+          action bars — via AgentRunActions. */}
       <Dialog width={phase === "form" ? 480 : 760} open={open} onOpenChange={(o) => { if (!o) close(); }}>
         <DialogHeader>
           <DialogHeaderTitle>{title}</DialogHeaderTitle>
@@ -1324,33 +1350,12 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
           </FileDropTarget>
         ) : null}
 
-        {phase === "analyze" || phase === "running" ? (
-          // Streams follow in a FollowScroll (padding mirrors DialogScrollArea);
-          // the phase flip swaps the scroller out, so the next pane opens at the top.
-          <FollowScroll contentContainerStyle={{ paddingBottom: 24, paddingHorizontal: small ? 16 : 24 }}>
-            <AgentRun parts={script.slice(0, revealed)} state={revealed >= script.length ? "done" : "streaming"} />
-          </FollowScroll>
-        ) : null}
-
-        {phase === "clarify" ? (
-          <View style={{ paddingHorizontal: 24, paddingBottom: 20 }}>
-            <ClarifyWizard
-              questions={INTAKE_QUESTIONS}
-              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");
-              }}
-            />
-          </View>
+        {phase === "analyze" || phase === "running" || phase === "clarify" ? (
+          // ONE pane for the whole run. It streams the transcript, and when the
+          // agent asks, the question REPLACES the feed — scrolled, with its
+          // actions in the footer. A real app passes `useAgentRun(alias)`
+          // straight in; this mock is the same shape.
+          <AgentRunPane run={run} onCancel={() => setPhase("intake")} />
         ) : null}
 
         {phase === "done" ? (
@@ -1462,7 +1467,7 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
           </DialogFooter>
         ) : phase === "clarify" ? (
           <DialogFooter>
-            <ClarifyWizardActions />
+            <AgentRunActions run={run} />
           </DialogFooter>
         ) : phase === "done" ? (
           <DialogFooter>
@@ -1471,7 +1476,7 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
           </DialogFooter>
         ) : null}
       </Dialog>
-    </ClarifyWizardScope>
+    </AgentRunScope>
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "20.0.2",
+  "version": "20.2.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -102,6 +102,7 @@
     "./finding": "./src/finding.tsx",
     "./clarify": "./src/clarify.tsx",
     "./clarify_wizard": "./src/clarify_wizard.tsx",
+    "./agent_run_pane": "./src/agent_run_pane.tsx",
     "./result_header": "./src/result_header.tsx",
     "./choice_list": "./src/choice_list.tsx",
     "./sources": "./src/sources.tsx",

package/src/agent_progress.tsx

@@ -6,6 +6,7 @@ import { WaveAvatar } from "./wave_avatar";
 import { FollowScroll } from "./follow_scroll";
 import { PressableHighlight } from "./pressable_highlight";
 import { AgentRun, resolveToolMeta, type AgentRunProps, type AgentToolCall } from "./agent_run";
+import { useLoticsLocale } from "./locale";
 import { toSegments, lastRunningStep, type AgentUIPart } from "./agent_transform";
 
 export interface AgentProgressProps {
@@ -43,7 +44,14 @@ export function AgentProgress(props: AgentProgressProps) {
   const [expanded, setExpanded] = useState(defaultExpanded ?? false);
 
   const running = lastRunningStep(toSegments(parts));
-  const runningLabel = running ? resolveToolMeta({ toolName: running.toolName, input: running.input, state: running.status }, labelForCall).label : undefined;
+  const locale = useLoticsLocale();
+  const runningLabel = running
+    ? resolveToolMeta(
+        { toolName: running.toolName, input: running.input, state: running.status },
+        labelForCall,
+        locale.agentRun.tools,
+      ).label
+    : undefined;
   const compact = label ?? runningLabel ?? (state === "done" ? "Done" : state === "error" ? "Stopped" : "Working…");
   const streaming = state === "streaming";
 

package/src/agent_run.tsx

@@ -69,19 +69,28 @@ 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 `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" },
-  get_record: { label: "Reading a record", icon: "file-text" },
-  get_records: { label: "Reading records", icon: "file-text" },
-  create_records: { label: "Creating records", icon: "plus" },
-  update_records: { label: "Updating records", icon: "square-pen" },
-  delete_records: { label: "Removing records", icon: "trash" },
-  generate_pdf_from_template: { label: "Generating PDF", icon: "file-down" },
-  generate_excel_from_template: { label: "Generating spreadsheet", icon: "file-spreadsheet" },
-  generate_docx_from_template: { label: "Generating document", icon: "file-text" },
+// The ICON per platform tool. The LABEL lives in the locale (`agentRun.tools`)
+// because it is language, and this component already renders localized chrome
+// around these rows — an English tool row under a Vietnamese "Đang suy nghĩ…"
+// was the kit contradicting itself. An icon is not language, so it stays here.
+// A tool neither map knows falls back to a prettified name + a neutral icon.
+const TOOL_ICONS: Record<string, IconName> = {
+  query_records: "search",
+  get_record: "file-text",
+  get_records: "file-text",
+  create_records: "plus",
+  update_records: "square-pen",
+  delete_records: "trash",
+  run_app_query: "search",
+  run_app_workflow: "play",
+  grep_knowledge: "search",
+  read_knowledge: "book-open",
+  list_knowledge: "list",
+  view_files: "file-text",
+  ask_user_choice: "message-circle-question-mark",
+  generate_pdf_from_template: "file-down",
+  generate_excel_from_template: "file-spreadsheet",
+  generate_docx_from_template: "file-text",
 };
 
 function prettifyToolName(name: string): string {
@@ -90,26 +99,37 @@ function prettifyToolName(name: string): string {
 }
 
 /** Resolve a tool's display label + icon: a caller override wins on the label,
- *  then the built-in map, then a prettified fallback. Exported so other agent
- *  surfaces (e.g. `AgentProgress`) render the same labels. */
+ *  then the active locale's `agentRun.tools`, then a prettified fallback.
+ *  Exported so other agent surfaces (e.g. `AgentProgress`) render the same
+ *  labels; `toolLabels` is optional so an existing external caller keeps
+ *  working (it just falls back to the prettified name). */
 export function resolveToolMeta(
   call: AgentToolCall,
   labelForCall?: (call: AgentToolCall) => string | undefined,
+  toolLabels?: Record<string, string>,
 ): { label: string; icon: IconName } {
-  const def =
-    TOOL_META[call.toolName] ??
-    (call.toolName.startsWith("generate_") && call.toolName.endsWith("_from_template")
-      ? { label: "Generating document", icon: "file-text" as IconName }
-      : undefined);
+  const generated =
+    call.toolName.startsWith("generate_") && call.toolName.endsWith("_from_template");
+  const label =
+    toolLabels?.[call.toolName] ??
+    (generated ? toolLabels?.generate_docx_from_template : undefined);
   return {
-    label: labelForCall?.(call) ?? def?.label ?? prettifyToolName(call.toolName),
-    icon: def?.icon ?? "list",
+    label: labelForCall?.(call) ?? label ?? prettifyToolName(call.toolName),
+    icon: TOOL_ICONS[call.toolName] ?? (generated ? "file-text" : "list"),
   };
 }
 
 /** 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;
+function stepLabel(
+  s: AgentStep,
+  labelForCall?: (call: AgentToolCall) => string | undefined,
+  toolLabels?: Record<string, string>,
+): string {
+  return resolveToolMeta(
+    { toolName: s.toolName, input: s.input, state: s.status },
+    labelForCall,
+    toolLabels,
+  ).label;
 }
 
 const INK = colors.zinc[700];
@@ -124,7 +144,7 @@ const INK = colors.zinc[700];
  * Pair with `Composer` + `ChangeReview`.
  */
 export function AgentRun(props: AgentRunProps) {
-  const { parts, labelForCall, renderToolOutput, onRetry, stepsLabel = (n) => `${n} steps`, accessibilityLabel } = props;
+  const { parts, labelForCall, renderToolOutput, onRetry, stepsLabel, accessibilityLabel } = props;
   const locale = useLoticsLocale();
   const segments = toSegments(parts);
   const state = props.state ?? (anyRunning(segments) ? "streaming" : "done");
@@ -163,7 +183,7 @@ export function AgentRun(props: AgentRunProps) {
             onToggle={() => toggle(seg.id)}
             labelForCall={labelForCall}
             renderToolOutput={renderToolOutput}
-            stepsLabel={stepsLabel}
+            stepsLabel={stepsLabel ?? locale.agentRun.steps}
           />
         );
       })}
@@ -369,7 +389,7 @@ function ToolGroup(props: {
 }) {
   const { steps, active, expanded, onToggle, labelForCall, renderToolOutput, stepsLabel } = props;
   const locale = useLoticsLocale();
-  const resolve = (s: AgentStep) => stepLabel(s, labelForCall);
+  const resolve = (s: AgentStep) => stepLabel(s, labelForCall, locale.agentRun.tools);
 
   // 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

package/src/agent_run_pane.tsx

@@ -0,0 +1,134 @@
+import { useCallback, useMemo, type ReactNode } from "react";
+import { View } from "react-native";
+import { AgentRun, type AgentRunProps } from "./agent_run";
+import type { AgentUIPart } from "./agent_transform";
+import { ClarifyWizard, ClarifyWizardActions, ClarifyWizardScope, type ClarifyWizardAnswer } from "./clarify_wizard";
+import { DialogScrollArea } from "./dialog";
+import { FollowScroll } from "./follow_scroll";
+import { useScreenSize } from "@lotics/ui/use_screen_size";
+
+/**
+ * What this pair needs from a run — structurally the shape `useAgentRun()`
+ * returns, declared here rather than imported so `@lotics/ui` keeps its one-way
+ * boundary and never depends on `@lotics/app-sdk`. Nothing enforces the match at
+ * build time; the app is where the two meet, so its typecheck is the detector.
+ */
+/** One option the agent offered. The answer's `value` IS the label — that is the
+ *  `ask_user_choice` wire shape, not a convenience. */
+export interface AgentRunOption {
+  label: string;
+  description?: string;
+}
+
+/** One question the agent asked, exactly as `pendingChoice` carries it. Named so
+ *  a consumer can DECLARE one — a template or test builds these directly, and
+ *  without a name it would borrow `ClarifyWizardQuestion` and map between two
+ *  shapes that a real run never maps between. */
+export interface AgentRunQuestion {
+  question: string;
+  options: AgentRunOption[];
+  allow_custom?: boolean;
+}
+
+export interface AgentRunLike {
+  status: "idle" | "streaming" | "awaiting_input" | "completed" | "error";
+  parts: readonly AgentUIPart[];
+  /** Non-null exactly while parked. */
+  pendingChoice: { questions: AgentRunQuestion[] } | null;
+  answerChoice: (answers: { value: string; custom: boolean }[]) => Promise<unknown>;
+  error: string | null;
+}
+
+export function AgentRunScope({ children }: { children: ReactNode }) {
+  return <ClarifyWizardScope>{children}</ClarifyWizardScope>;
+}
+
+export interface AgentRunPaneProps {
+  run: AgentRunLike;
+  labelForCall?: AgentRunProps["labelForCall"];
+  renderToolOutput?: AgentRunProps["renderToolOutput"];
+  /** Abandon a parked question — the run is left for the operator to retry. */
+  onCancel: () => void;
+}
+
+/**
+ * The run's content: the streaming transcript, or — once the agent asks — the
+ * question IN ITS PLACE.
+ *
+ * The question REPLACES the feed rather than stacking under it. The run is
+ * blocked on the answer, so the question is the only thing to act on; and
+ * stacking is what broke it in production — the wizard sat below the scroller in
+ * a container that could not scroll, so a multi-question ask ran past the
+ * dialog's height and clipped its own Submit. Every app rebuilt this arrangement
+ * by hand and it only had to be got wrong once.
+ */
+export function AgentRunPane(props: AgentRunPaneProps) {
+  const { run, labelForCall, renderToolOutput, onCancel } = props;
+  const { small } = useScreenSize();
+  const pending = run.pendingChoice;
+
+  // Mapped once per question set, not per render: the wizard keys its per-step
+  // draft off identity, and a fresh array every render is a new identity.
+  const questions = useMemo(
+    () =>
+      (pending?.questions ?? []).map((q) => ({
+        question: q.question,
+        answers: q.options.map((o) => ({ value: o.label, label: o.label, description: o.description ?? "" })),
+        allowCustom: q.allow_custom === true,
+      })),
+    [pending],
+  );
+  const submit = useCallback(
+    (answers: ClarifyWizardAnswer[]) => {
+      void run.answerChoice(answers.map((a) => ({ value: a.value, custom: a.custom })));
+    },
+    [run],
+  );
+
+  if (pending) {
+    return (
+      <DialogScrollArea>
+        <View style={{ paddingVertical: 4 }}>
+          <ClarifyWizard questions={questions} onSubmit={submit} onCancel={onCancel} />
+        </View>
+      </DialogScrollArea>
+    );
+  }
+
+  // FollowScroll, not DialogScrollArea: the transcript grows from the bottom and
+  // the newest step has to stay in view. Swapping the scroller on the park is
+  // deliberate — remounting opens the question at the top rather than wherever
+  // the feed happened to be scrolled to.
+  return (
+    <FollowScroll contentContainerStyle={{ paddingBottom: 24, paddingHorizontal: small ? 16 : 24 }}>
+      {/* No empty-state slot on purpose. `AgentRun` renders its own breathing
+          "Starting…" row while streaming with zero parts, localized through the
+          `agentRun` locale slice — and ai_patterns states the law outright:
+          never hand-roll a placeholder in front of the feed. A slot here would
+          invite exactly that, and every app would localize it again. */}
+      <AgentRun
+        parts={run.parts}
+        state={run.status === "error" ? "error" : run.status === "streaming" ? "streaming" : "done"}
+        error={run.error ?? undefined}
+        labelForCall={labelForCall}
+        renderToolOutput={renderToolOutput}
+      />
+    </FollowScroll>
+  );
+}
+
+/**
+ * The run's action bar, for a `DialogFooter`. Renders the wizard's
+ * Cancel/Back/Next/Submit while a question is up and NOTHING otherwise, so the
+ * host can mount it unconditionally and let the run decide.
+ *
+ * Pinned outside the scroller is the point: no length of question can push
+ * Submit out of reach.
+ */
+export function AgentRunActions({ run }: { run: AgentRunLike }) {
+  // Reads the SAME run the pane reads, rather than state the pane publishes: two
+  // components deriving from one source cannot disagree, and nothing has to set
+  // a parent's state during a child's render to keep them in step.
+  if (run.pendingChoice == null) return null;
+  return <ClarifyWizardActions />;
+}

package/src/locale.tsx

@@ -132,9 +132,27 @@ export interface LoticsLocale {
   /** `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: { starting: string; thinking: string; thinkingStreaming: string; input: string; error: string; output: string; awaiting: string; retry: string };
+   *  `retry` action, the per-tool labels (`tools`) and the "{n} steps" suffix
+   *  (`steps`). `labelForCall` / `stepsLabel` remain as per-call-site
+   *  OVERRIDES, not as the only way to get a translation. */
+  /** `AgentRun` / `AgentProgress` chrome, plus `tools` — the display label per
+   *  PLATFORM tool name. The tool set is bounded and kit-known, so localizing it
+   *  here means every app inherits it; leaving it to each call site's
+   *  `labelForCall` made a Vietnamese surface render Vietnamese chrome around
+   *  English tool rows. A name absent from the map still falls back to its
+   *  prettified form, and `labelForCall` still overrides per call. */
+  agentRun: {
+    starting: string;
+    thinking: string;
+    thinkingStreaming: string;
+    input: string;
+    error: string;
+    output: string;
+    awaiting: string;
+    retry: string;
+    tools: Record<string, string>;
+    steps: (n: number) => 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). */
@@ -237,7 +255,35 @@ export const en: LoticsLocale = {
   matrix: { total: "Total", less: "Less", more: "More" },
   scrollToBottom: { tooltip: "Scroll to bottom" },
   textInputField: { clear: "Clear" },
-  agentRun: { starting: "Starting…", thinking: "Thinking", thinkingStreaming: "Thinking…", input: "Input", error: "Error", output: "Output", awaiting: "Awaiting", retry: "Retry" },
+  agentRun: {
+    starting: "Starting…",
+    thinking: "Thinking",
+    thinkingStreaming: "Thinking…",
+    input: "Input",
+    error: "Error",
+    output: "Output",
+    awaiting: "Awaiting",
+    retry: "Retry",
+    tools: {
+      query_records: "Searching records",
+      get_record: "Reading a record",
+      get_records: "Reading records",
+      create_records: "Creating records",
+      update_records: "Updating records",
+      delete_records: "Removing records",
+      run_app_query: "Reading data",
+      run_app_workflow: "Running an action",
+      grep_knowledge: "Searching reference material",
+      read_knowledge: "Reading reference material",
+      list_knowledge: "Listing reference material",
+      view_files: "Reading files",
+      ask_user_choice: "Asking a question",
+      generate_pdf_from_template: "Generating PDF",
+      generate_excel_from_template: "Generating spreadsheet",
+      generate_docx_from_template: "Generating document",
+    },
+    steps: (n) => `${n} steps`,
+  },
   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" },
 };
@@ -335,7 +381,35 @@ 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: { starting: "Đang bắt đầu…", 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" },
+  agentRun: {
+    starting: "Đang bắt đầu…",
+    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",
+    tools: {
+      query_records: "Đang tìm dữ liệu",
+      get_record: "Đang đọc một bản ghi",
+      get_records: "Đang đọc dữ liệu",
+      create_records: "Đang tạo dữ liệu",
+      update_records: "Đang cập nhật dữ liệu",
+      delete_records: "Đang xoá dữ liệu",
+      run_app_query: "Đang đọc dữ liệu",
+      run_app_workflow: "Đang chạy tác vụ",
+      grep_knowledge: "Đang tra tài liệu",
+      read_knowledge: "Đang đọc tài liệu",
+      list_knowledge: "Đang liệt kê tài liệu",
+      view_files: "Đang đọc tệp",
+      ask_user_choice: "Đang hỏi thêm",
+      generate_pdf_from_template: "Đang tạo PDF",
+      generate_excel_from_template: "Đang tạo bảng tính",
+      generate_docx_from_template: "Đang tạo văn bản",
+    },
+    steps: (n) => `${n} bước`,
+  },
   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" },
 };