@stigmer/react 3.12.1 → 3.12.3

package/src/execution/__tests__/message-thread-slots.test.tsx

@@ -28,9 +28,11 @@ import {
 import { MessageThread, type MessageThreadSlots } from "../MessageThread";
 import type { MessageEntryProps } from "../MessageEntry";
 import type { ApprovalCardProps } from "../ApprovalCard";
+import type { ExecutionErrorNoticeProps } from "../ExecutionErrorNotice";
 import type { TodoCardProps } from "../TodoCard";
 import type { TodoRowProps } from "../TodoList";
 import type { SetupProgressProps } from "../SetupProgress";
+import type { LivenessStatusLineProps } from "../LivenessStatusLine";
 import type { PlanCompletionCardProps } from "../PlanCompletionCard";
 import type { PlanArtifactCardProps } from "../PlanArtifactCard";
 import type { PlanStreamingCardProps } from "../PlanStreamingCard";
@@ -110,6 +112,7 @@ function makeExecution(opts: {
   todos?: Record<string, { content: string; status: TodoStatus }>;
   pendingApprovalToolCallId?: string;
   planArtifactName?: string;
+  error?: string;
 }): AgentExecution {
   const exec = create(AgentExecutionSchema);
 
@@ -128,6 +131,9 @@ function makeExecution(opts: {
 
   const status = create(AgentExecutionStatusSchema);
   status.phase = opts.phase ?? ExecutionPhase.EXECUTION_COMPLETED;
+  if (opts.error) {
+    status.error = opts.error;
+  }
 
   const aiMsg = create(AgentMessageSchema);
   aiMsg.type = MessageType.MESSAGE_AI;
@@ -312,6 +318,28 @@ describe("MessageThread slots", () => {
     expect(screen.getByTestId("custom-setup").textContent).toBe("waiting");
   });
 
+  it("renders the LivenessStatusLine slot while the execution is live between events", () => {
+    const CustomLiveness = ({ label }: LivenessStatusLineProps) => (
+      <div data-testid="custom-liveness">{label ?? "custom-live"}</div>
+    );
+
+    const exec = makeExecution({
+      id: "e-live",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      aiContent: "thinking about it",
+    });
+
+    render(
+      <MessageThread
+        executions={[]}
+        activeStreamExecution={exec}
+        slots={{ LivenessStatusLine: CustomLiveness }}
+      />,
+    );
+
+    expect(screen.getByTestId("custom-liveness").textContent).toBe("custom-live");
+  });
+
   it("renders the PlanCompletionCard slot for an artifact-less completed Plan turn", () => {
     const CustomCompletion = ({ onImplement }: PlanCompletionCardProps) => (
       <button type="button" data-testid="custom-completion" onClick={onImplement}>
@@ -390,6 +418,70 @@ describe("MessageThread slots", () => {
     );
   });
 
+  it("renders the ExecutionErrorNotice slot with the retry wiring intact", () => {
+    const onRetryExecution = vi.fn();
+    const CustomNotice = ({ error, retryMessage, onRetry }: ExecutionErrorNoticeProps) => (
+      <div data-testid="custom-error-notice">
+        <span>{error}</span>
+        {onRetry && retryMessage && (
+          <button type="button" onClick={() => onRetry(retryMessage)}>
+            switch engine and retry
+          </button>
+        )}
+      </div>
+    );
+
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e-failed",
+            specMessage: "prompt text",
+            phase: ExecutionPhase.EXECUTION_FAILED,
+            error: "model capacity exhausted",
+          }),
+        ]}
+        onRetryExecution={onRetryExecution}
+        slots={{ ExecutionErrorNotice: CustomNotice }}
+      />,
+    );
+
+    const notice = screen.getByTestId("custom-error-notice");
+    expect(notice.textContent).toContain("model capacity exhausted");
+    // The built-in's clamp toggle must not render alongside the override.
+    expect(screen.queryByRole("button", { name: "Show more" })).toBeNull();
+
+    // The slot's retry contract is identical to the built-in's: it resends
+    // the originating message.
+    fireEvent.click(screen.getByRole("button", { name: "switch engine and retry" }));
+    expect(onRetryExecution).toHaveBeenCalledWith("prompt text");
+  });
+
+  it("falls back to the built-in ExecutionErrorNotice when the slot is omitted", () => {
+    const onRetryExecution = vi.fn();
+
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e-failed",
+            specMessage: "prompt text",
+            phase: ExecutionPhase.EXECUTION_FAILED,
+            error: "model capacity exhausted",
+          }),
+        ]}
+        onRetryExecution={onRetryExecution}
+      />,
+    );
+
+    // The built-in renders as a destructive alert with clamp + Retry.
+    const alert = screen.getByRole("alert");
+    expect(alert.textContent).toContain("model capacity exhausted");
+    expect(screen.getByRole("button", { name: "Show more" })).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "Retry" }));
+    expect(onRetryExecution).toHaveBeenCalledWith("prompt text");
+  });
+
   // -------------------------------------------------------------------------
   // Backward compatibility and memo guarantees
   // -------------------------------------------------------------------------

package/src/execution/__tests__/tool-presenter.test.tsx

@@ -78,8 +78,9 @@ describe("useToolPresentation", () => {
 
   describe("disclosure", () => {
     it("keeps known compact tools as summary", () => {
-      // Shell/edit/write are intentionally excluded — they are `preview`
-      // categories (output / diff is the information), asserted separately below.
+      // Shell/edit/write are intentionally excluded — shell is the `tail`
+      // category and edit/write are `preview` categories (output / diff is
+      // the information), asserted separately below.
       for (const name of ["Read", "Grep", "Glob"]) {
         const tc = makeToolCall({ name, args: { path: "/x", command: "ls", pattern: "p" } });
         const { result } = renderHook(() => useToolPresentation(tc));
@@ -98,11 +99,25 @@ describe("useToolPresentation", () => {
       }
     });
 
-    it("keeps a shell tool's output as a persistent preview", () => {
+    it("gives shell the tail disclosure (live preview, dimmed-tail settle)", () => {
       const tc = makeToolCall({ name: "Shell", args: { command: "ls" }, result: "files" });
       const { result } = renderHook(() => useToolPresentation(tc));
       expect(result.current.category).toBe("shell");
-      expect(result.current.disclosure).toBe("preview");
+      expect(result.current.disclosure).toBe("tail");
+    });
+
+    it("lets a host restore the always-expanded shell preview via the registry", () => {
+      // The one-line opt-out for hosts that prefer the pre-tail behaviour.
+      const dispose = registerToolPresenter(ToolKind.SHELL, {
+        disclosure: () => "preview",
+      });
+      try {
+        const tc = makeToolCall({ name: "Shell", args: { command: "ls" }, result: "files" });
+        const { result } = renderHook(() => useToolPresentation(tc));
+        expect(result.current.disclosure).toBe("preview");
+      } finally {
+        dispose();
+      }
     });
 
     it("foregrounds MCP tools as preview", () => {
@@ -140,6 +155,28 @@ describe("useToolPresentation", () => {
     });
   });
 
+  describe("chrome", () => {
+    it("quiets metadata-only categories and keeps content-bearing ones as cards", () => {
+      const quiet = makeToolCall({ name: "Read", args: { path: "/x" } });
+      const card = makeToolCall({ name: "Shell", args: { command: "ls" }, result: "files" });
+      expect(renderHook(() => useToolPresentation(quiet)).result.current.chrome).toBe("quiet");
+      expect(renderHook(() => useToolPresentation(card)).result.current.chrome).toBe("card");
+    });
+
+    it("lets a registered presenter restore the boxed look for a kind", () => {
+      const dispose = registerToolPresenter(ToolKind.FILE_READ, {
+        chrome: () => "card",
+      });
+      try {
+        const tc = makeToolCall({ name: "Read", args: { path: "/x" } });
+        const { result } = renderHook(() => useToolPresentation(tc));
+        expect(result.current.chrome).toBe("card");
+      } finally {
+        dispose();
+      }
+    });
+  });
+
   describe("runGroupable", () => {
     it("folds read-only repetitive categories", () => {
       for (const name of ["Read", "Grep", "Glob"]) {

package/src/execution/index.ts

@@ -127,6 +127,9 @@ export type { InteractionModeBadgeProps } from "./InteractionModeBadge.js";
 export { SetupProgress } from "./SetupProgress.js";
 export type { SetupProgressProps } from "./SetupProgress.js";
 
+export { LivenessStatusLine } from "./LivenessStatusLine.js";
+export type { LivenessStatusLineProps } from "./LivenessStatusLine.js";
+
 export { ToolCallGroup } from "./ToolCallGroup.js";
 export type { ToolCallGroupProps } from "./ToolCallGroup.js";
 
@@ -154,8 +157,8 @@ export type { ToolArgsViewProps } from "./ToolArgsView.js";
 export { ResultView, summarizeResultView } from "./ResultView.js";
 export type { ResultViewProps } from "./ResultView.js";
 
-export { TerminalSession } from "./TerminalSession.js";
-export type { TerminalSessionProps } from "./TerminalSession.js";
+export { TerminalSession, TerminalTail } from "./TerminalSession.js";
+export type { TerminalSessionProps, TerminalTailProps } from "./TerminalSession.js";
 
 export {
   useToolPresentation,
@@ -204,6 +207,9 @@ export type {
   ThreadContentColumn,
 } from "./MessageThread.js";
 
+export { ExecutionErrorNotice } from "./ExecutionErrorNotice.js";
+export type { ExecutionErrorNoticeProps } from "./ExecutionErrorNotice.js";
+
 export { ThreadSkeleton } from "./ThreadSkeleton.js";
 export type { ThreadSkeletonProps } from "./ThreadSkeleton.js";
 
@@ -334,6 +340,9 @@ export {
   toolKindToCategoryInfo,
   extractPrimaryArg,
   extractPrimaryArgFromPreview,
+  extractShellIntent,
+  extractShellIntentFromPreview,
+  SHELL_INTENT_ARG_FIELD,
   humanizeToolName,
   defaultDisclosureForCategory,
   isRunGroupableCategory,

package/src/execution/tool-categories.ts

@@ -36,16 +36,67 @@ export type ToolCategory =
  *   `Search … 2 matches`). The full detail is one click away.
  * - `"preview"` — the row renders its result body **always** (no card chevron),
  *   because the one-liner cannot convey what happened so the content itself IS
- *   the information (a shell command's output, an MCP result such as a
- *   screenshot, a fetched page, a web-search answer, or an unrecognised tool's
- *   output). The body's own in-place reveal expands it beyond the height budget.
+ *   the information (an MCP result such as a screenshot, a fetched page, a
+ *   web-search answer, or an unrecognised tool's output). The body's own
+ *   in-place reveal expands it beyond the height budget.
+ * - `"tail"` — live like `"preview"`, settled like a teaser: while the tool
+ *   runs (or awaits approval) the full body streams in view; once it settles
+ *   successfully the row collapses to a dimmed tail of its last output lines —
+ *   at-a-glance evidence that it ran and what it printed last — expanding on
+ *   demand via the header chevron. A settled *failure* stays open: error
+ *   output is content, not context. Shell is the canonical tail category — a
+ *   working session's compile/validate loops would otherwise dominate the
+ *   transcript at full contrast (Cursor's chat is the reference UX).
  *
  * This is the *disclosure* axis (how much of a result to show); it is
  * orthogonal to {@link isRunGroupableCategory} (whether consecutive same-kind
  * calls fold into one chip). A category can be result-rich but never folded
  * (`shell`), or foldable but never previewed (`read`).
  */
-export type ToolDisclosure = "summary" | "preview";
+export type ToolDisclosure = "summary" | "preview" | "tail";
+
+/**
+ * How much *chrome* a tool row carries in the thread — the density axis,
+ * orthogonal to {@link ToolDisclosure} (how much of the result to show).
+ *
+ * - `"card"` — a self-contained bordered card. For content-bearing rows
+ *   (shell, edit, fetch, MCP), where the body is real evidence worth a frame.
+ * - `"quiet"` — an unboxed single text line, no border, no card. For
+ *   metadata-only rows (read / list / search / think) whose label + argument
+ *   already tell the whole story: a 4 ms directory listing must not shout as
+ *   loudly as a 3-minute shell run (Cursor's chat is the reference UX — prose
+ *   with quiet evidence attached, not a stack of equally-loud widgets).
+ *
+ * This is the *settled default*. A row escalates to `"card"` regardless of
+ * category while it carries something the quiet line cannot: a pending
+ * approval gate (a decision surface) or a failure (error output is content).
+ * That escalation is owned by the component layer and is deliberately not
+ * override-able — a gate must never render without its frame.
+ */
+export type ToolChrome = "card" | "quiet";
+
+/**
+ * Categories whose settled summary row IS the complete information, rendered
+ * as quiet unboxed lines by default. Mirrors {@link RUN_GROUPABLE_CATEGORIES}
+ * plus `think` (a thought's row reads like narration, not evidence) — the
+ * same low-signal set, on the chrome axis instead of the folding axis.
+ */
+const QUIET_CATEGORIES: ReadonlySet<ToolCategory> = new Set<ToolCategory>([
+  "read",
+  "list",
+  "search",
+  "think",
+]);
+
+/**
+ * Returns the default {@link ToolChrome} for a presentation category.
+ * Consumers can override per {@link ToolKind} via {@link registerToolPresenter}
+ * (`chrome: () => "card"` to restore the boxed look for a kind), exactly like
+ * the disclosure axis.
+ */
+export function defaultChromeForCategory(category: ToolCategory): ToolChrome {
+  return QUIET_CATEGORIES.has(category) ? "quiet" : "card";
+}
 
 /**
  * Categories whose result is foregrounded as a persistent bounded preview by
@@ -60,7 +111,6 @@ export type ToolDisclosure = "summary" | "preview";
  * under control even in turns with many edits.
  */
 const PREVIEW_CATEGORIES: ReadonlySet<ToolCategory> = new Set<ToolCategory>([
-  "shell",
   "edit",
   "write",
   "mcp",
@@ -69,6 +119,18 @@ const PREVIEW_CATEGORIES: ReadonlySet<ToolCategory> = new Set<ToolCategory>([
   "unknown",
 ]);
 
+/**
+ * Categories that stream in full while live but settle to a dimmed tail of
+ * their last output lines (see the `"tail"` arm of {@link ToolDisclosure}).
+ * Today that is shell alone: its output is evidence worth keeping at a
+ * glance, but rarely worth reading line by line once the command succeeded.
+ * Consumers can restore the always-expanded preview per kind via
+ * {@link registerToolPresenter} (`disclosure: () => "preview"`).
+ */
+const TAIL_CATEGORIES: ReadonlySet<ToolCategory> = new Set<ToolCategory>([
+  "shell",
+]);
+
 /**
  * Low-signal categories whose consecutive runs fold into a single collapsible
  * "Read 5 files" chip in the thread. These are the read-only, repetitive
@@ -84,13 +146,15 @@ const RUN_GROUPABLE_CATEGORIES: ReadonlySet<ToolCategory> = new Set<ToolCategory
 
 /**
  * Returns the default inline {@link ToolDisclosure} for a presentation
- * category. This is the headless policy behind the thread's "keep a live
- * preview for shell/MCP/unknown, keep generic tools compact" behaviour;
- * consumers can override per {@link ToolKind} via {@link registerToolPresenter}.
+ * category. This is the headless policy behind the thread's "collapse settled
+ * shell to a dimmed tail, keep a live preview for MCP/unknown, keep generic
+ * tools compact" behaviour; consumers can override per {@link ToolKind} via
+ * {@link registerToolPresenter}.
  */
 export function defaultDisclosureForCategory(
   category: ToolCategory,
 ): ToolDisclosure {
+  if (TAIL_CATEGORIES.has(category)) return "tail";
   return PREVIEW_CATEGORIES.has(category) ? "preview" : "summary";
 }
 
@@ -128,6 +192,14 @@ export interface ToolCategoryInfo {
   readonly primaryArgField: string;
   /** Fallback argument keys tried when the primary key is absent. */
   readonly fallbackArgFields: readonly string[];
+  /**
+   * JSON argument key carrying a model-authored intent phrase for this kind
+   * (stigmer#276), or `undefined` for kinds without one. Shell is the only
+   * carrier today: both harnesses converge on `description` — the Cursor
+   * harness's built-in Shell tool ships it natively, and the native harness's
+   * tool-intent middleware adds it to the `execute` schema at bind time.
+   */
+  readonly intentArgField?: string;
 }
 
 interface KindDisplayEntry {
@@ -135,6 +207,7 @@ interface KindDisplayEntry {
   readonly label: string;
   readonly primaryField: string;
   readonly fallbackFields?: readonly string[];
+  readonly intentField?: string;
 }
 
 // Presentation metadata per ToolKind. Classification (name -> kind) is owned by
@@ -145,7 +218,7 @@ const KIND_DISPLAY: Partial<Record<ToolKind, KindDisplayEntry>> = {
   [ToolKind.FILE_WRITE]:  { category: "write",     label: "Write",     primaryField: "path", fallbackFields: ["file_path", "file", "filename"] },
   [ToolKind.FILE_EDIT]:   { category: "edit",      label: "Edit",      primaryField: "path", fallbackFields: ["file_path", "file", "filename"] },
   [ToolKind.FILE_DELETE]: { category: "delete",    label: "Delete",    primaryField: "path", fallbackFields: ["file_path", "file", "filename"] },
-  [ToolKind.SHELL]:       { category: "shell",     label: "Shell",     primaryField: "command" },
+  [ToolKind.SHELL]:       { category: "shell",     label: "Shell",     primaryField: "command", intentField: "description" },
   [ToolKind.SEARCH]:      { category: "search",    label: "Search",    primaryField: "pattern", fallbackFields: ["query", "q"] },
   [ToolKind.LIST]:        { category: "list",      label: "List",      primaryField: "path" },
   [ToolKind.FETCH]:       { category: "fetch",     label: "Fetch",     primaryField: "url", fallbackFields: ["uri"] },
@@ -200,6 +273,7 @@ export function toolKindToCategoryInfo(
       label: entry.label,
       primaryArgField: entry.primaryField,
       fallbackArgFields: entry.fallbackFields ?? [],
+      ...(entry.intentField ? { intentArgField: entry.intentField } : {}),
     };
   }
 
@@ -376,6 +450,118 @@ export function extractPrimaryArgFromPreview(
   }
 }
 
+/**
+ * Extracts the model-authored intent phrase from a tool call's args
+ * (stigmer#276), or `null` when the kind carries none / the model omitted it.
+ *
+ * The intent is presentation metadata authored by the model *for the user* —
+ * "Run unit tests for the parser" — rendered as the row title in place of the
+ * bare category label. Extraction is kind-scoped via
+ * {@link ToolCategoryInfo.intentArgField} (shell-only today) so a same-named
+ * REAL argument on another kind (e.g. the sub-agent task tool's
+ * `description`, which is its subject) is never misread as an intent.
+ */
+export function extractIntent(toolCall: ToolCall): string | null {
+  const info = resolveToolCategoryFromCall(toolCall);
+  if (!info.intentArgField || !toolCall.args) return null;
+  const value = toolCall.args[info.intentArgField];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * {@link extractIntent} for surfaces that carry a JSON `argsPreview` string
+ * instead of a full {@link ToolCall} — notably `PendingApproval`. Same
+ * kind-scoping; returns `null` on parse failure or when absent.
+ */
+export function extractIntentFromPreview(
+  toolName: string,
+  argsPreview: string,
+  mcpServerSlug?: string,
+  toolKind?: ToolKind,
+): string | null {
+  if (!argsPreview) return null;
+
+  const info =
+    toolKind !== undefined
+      ? resolveToolCategoryFromKind(toolKind, toolName, mcpServerSlug)
+      : resolveToolCategory(toolName, mcpServerSlug);
+  if (!info.intentArgField) return null;
+
+  try {
+    const parsed = JSON.parse(argsPreview);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const value = (parsed as Record<string, unknown>)[info.intentArgField];
+    return typeof value === "string" && value.length > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The tool-call argument that carries a model-authored intent phrase for
+ * SHELL tools (stigmer#276) — a short human description of what the command
+ * does and why, rendered as the row title with the command as secondary text.
+ *
+ * Two writers populate it, converged on one wire key by design: the native
+ * harness's tool-intent middleware (`backend/services/runner/src/middleware/
+ * tool-intent.ts`, `INTENT_ARG`) extends the shell tool's bind-time schema
+ * with it, and the Cursor harness's built-in Shell tool carries it natively.
+ * The shared, machine-checked contract is
+ * `test/fixtures/tool-view/intent-title.json` — keep all three in lockstep.
+ */
+export const SHELL_INTENT_ARG_FIELD = "description";
+
+/**
+ * The intent-title extraction core: SHELL-kind-scoped on purpose, because
+ * `description` means other things on other tools (a task tool's description
+ * is the sub-agent subject, never a row title). Blank and non-string values
+ * degrade to null — the caller falls back to the category label.
+ */
+function extractIntentFromArgs(kind: ToolKind, args: JsonObject | undefined): string | null {
+  if (kind !== ToolKind.SHELL || !args) return null;
+  const value = args[SHELL_INTENT_ARG_FIELD];
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Extracts the model-authored intent phrase from a SHELL tool call, or null
+ * when absent (legacy executions, models that skipped the optional arg, and
+ * every non-shell kind). See {@link SHELL_INTENT_ARG_FIELD}.
+ */
+export function extractShellIntent(toolCall: ToolCall): string | null {
+  return extractIntentFromArgs(resolveToolKind(toolCall), toolCall.args);
+}
+
+/**
+ * Preview-string twin of {@link extractShellIntent} for surfaces that carry a
+ * `PendingApproval` (JSON `argsPreview`) instead of a full {@link ToolCall} —
+ * mirrors {@link extractPrimaryArgFromPreview}'s kind resolution.
+ */
+export function extractShellIntentFromPreview(
+  toolName: string,
+  argsPreview: string,
+  mcpServerSlug?: string,
+  toolKind?: ToolKind,
+): string | null {
+  if (!argsPreview) return null;
+
+  const kind =
+    toolKind !== undefined && toolKind !== ToolKind.UNSPECIFIED
+      ? toolKind
+      : resolveToolKindByName(toolName, mcpServerSlug);
+  if (kind !== ToolKind.SHELL) return null;
+
+  try {
+    const parsed = JSON.parse(argsPreview);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    return extractIntentFromArgs(kind, parsed as JsonObject);
+  } catch {
+    return null;
+  }
+}
+
 const WRITE_CONTENT_FIELDS = [
   "contents",
   "content",

package/src/execution/tool-presenter.ts

@@ -19,10 +19,12 @@ import type { ToolResultView } from "@stigmer/sdk";
 import {
   resolveToolCategoryFromCall,
   extractPrimaryArg,
+  extractShellIntent,
+  defaultChromeForCategory,
   defaultDisclosureForCategory,
   isRunGroupableCategory,
 } from "./tool-categories.js";
-import type { ToolCategory, ToolDisclosure } from "./tool-categories.js";
+import type { ToolCategory, ToolChrome, ToolDisclosure } from "./tool-categories.js";
 import { summarizeResultView } from "./ResultView.js";
 
 /** Optional per-kind overrides for label, summary, disclosure, and run-grouping. */
@@ -37,6 +39,15 @@ export interface ToolPresenter {
    * (`() => "preview"`) without forking the components.
    */
   readonly disclosure?: (toolCall: ToolCall, result: ToolResultView) => ToolDisclosure;
+  /**
+   * Overrides the default chrome tier — quiet unboxed line vs bordered card
+   * (see {@link ToolChrome}). Use to restore the boxed look for a kind
+   * (`() => "card"`) or to quiet a chatty custom tool (`() => "quiet"`).
+   * A pending approval gate or a failure always escalates the row to a card
+   * regardless of this override — a decision surface and error output must
+   * never render frameless.
+   */
+  readonly chrome?: (toolCall: ToolCall, result: ToolResultView) => ToolChrome;
   /**
    * Overrides whether consecutive same-kind calls fold into one collapsible
    * "Read 5 files" chip. Use to fold a chatty custom tool (`() => true`) or to
@@ -114,6 +125,21 @@ export interface ToolPresentation {
   readonly category: ToolCategory;
   /** Display label, e.g. "Edit", "Shell". */
   readonly label: string;
+  /**
+   * The model-authored intent phrase for a SHELL call (stigmer#276), or null
+   * when absent (legacy executions, skipped optional arg, non-shell kinds).
+   * Raw extraction — precedence against overrides is resolved in
+   * {@link ToolPresentation.title}.
+   */
+  readonly intent: string | null;
+  /**
+   * The row title: a registered presenter's `label` override wins (a host's
+   * explicit wording is never displaced by model output), then the
+   * model-authored {@link intent}, then the category {@link label}. Renderers
+   * that title a row use this; {@link label} stays the short kind label for
+   * chips and badges.
+   */
+  readonly title: string;
   /** Primary argument (path, command, pattern...), or null. */
   readonly primaryArg: string | null;
   /** Normalized result view for rendering with {@link ResultView}. */
@@ -127,6 +153,13 @@ export interface ToolPresentation {
    * default.
    */
   readonly disclosure: ToolDisclosure;
+  /**
+   * Default chrome tier for this tool — `"quiet"` renders an unboxed line,
+   * `"card"` a bordered card (see {@link ToolChrome}). A pending gate or a
+   * failure escalates to `"card"` in the component layer; this is the
+   * *settled* default.
+   */
+  readonly chrome: ToolChrome;
   /**
    * Whether consecutive same-kind calls fold into one collapsible chip — the
    * run-grouping axis, orthogonal to {@link disclosure}. See
@@ -149,12 +182,18 @@ export function useToolPresentation(toolCall: ToolCall): ToolPresentation {
     const result = normalizeToolResult(toolCall);
     const override = registry.get(kind);
 
-    const label = override?.label?.(toolCall) ?? categoryInfo.label;
+    const overrideLabel = override?.label?.(toolCall);
+    const label = overrideLabel ?? categoryInfo.label;
+    const intent = extractShellIntent(toolCall);
+    const title = overrideLabel ?? intent ?? categoryInfo.label;
     const resultSummary =
       override?.summary?.(toolCall, result) ?? summarizeResultView(result);
     const disclosure =
       override?.disclosure?.(toolCall, result) ??
       defaultDisclosureForCategory(categoryInfo.category);
+    const chrome =
+      override?.chrome?.(toolCall, result) ??
+      defaultChromeForCategory(categoryInfo.category);
     const runGroupable =
       override?.runGroupable?.(toolCall) ??
       isRunGroupableCategory(categoryInfo.category);
@@ -163,10 +202,13 @@ export function useToolPresentation(toolCall: ToolCall): ToolPresentation {
       kind,
       category: categoryInfo.category,
       label,
+      intent,
+      title,
       primaryArg: extractPrimaryArg(toolCall),
       result,
       resultSummary,
       disclosure,
+      chrome,
       runGroupable,
     };
   }, [toolCall]);

package/src/execution/useArtifactInspection.ts

@@ -12,8 +12,7 @@ import {
   useApplyResource,
   type ApplyResourceResult,
 } from "../library/useApplyResource.js";
-
-const COPIED_FEEDBACK_MS = 2000;
+import { useCopyFeedback } from "../internal/useCopyFeedback.js";
 
 /** Options for {@link useArtifactInspection}. */
 export interface UseArtifactInspectionOptions {
@@ -198,14 +197,11 @@ export function useArtifactInspection(
 
   // --- Copy -----------------------------------------------------------------
 
-  const [copied, setCopied] = useState(false);
+  const { copy: copyToClipboard, copied } = useCopyFeedback();
   const copy = useCallback(() => {
     if (!content) return;
-    void navigator.clipboard.writeText(content).then(() => {
-      setCopied(true);
-      setTimeout(() => setCopied(false), COPIED_FEEDBACK_MS);
-    });
-  }, [content]);
+    void copyToClipboard(content);
+  }, [content, copyToClipboard]);
 
   return useMemo(
     () => ({

package/src/iam-policy/GrantAccessForm.tsx

@@ -12,6 +12,7 @@ import { getUserMessage, iamRoleToString } from "@stigmer/sdk";
 import { useCreateIamPolicy } from "./useCreateIamPolicy.js";
 import { RoleSelector } from "./RoleSelector.js";
 import { PrincipalPicker, type SelectedPrincipal } from "./PrincipalPicker.js";
+import { SpinnerIcon } from "../internal/SpinnerIcon.js";
 
 /** Props for {@link GrantAccessForm}. */
 export interface GrantAccessFormProps {
@@ -151,7 +152,7 @@ export function GrantAccessForm({
             "stg:disabled:pointer-events-none stg:disabled:opacity-40",
           )}
         >
-          {isCreating && <SpinnerIcon />}
+          {isCreating && <SpinnerIcon size={12} />}
           Grant access
         </button>
 
@@ -174,20 +175,3 @@ export function GrantAccessForm({
   );
 }
 
-function SpinnerIcon() {
-  return (
-    <svg
-      width="12"
-      height="12"
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth="2"
-      strokeLinecap="round"
-      className="stg:animate-spin"
-      aria-hidden="true"
-    >
-      <path d="M8 2a6 6 0 1 0 6 6" />
-    </svg>
-  );
-}