@stigmer/react 2.0.0 → 3.0.0

package/src/execution/__tests__/subagent-thread-item.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import {
+  ExecutionPhase,
+  MessageType,
+  SubAgentStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { buildThreadItems } from "../MessageThread";
+
+/**
+ * Guards the correlation that makes a delegated sub-agent appear in the live
+ * thread: a parent MESSAGE_AI carrying a "task" tool call becomes a "sub-agent"
+ * thread item only when a SubAgentExecution with the same id is present in
+ * status.sub_agent_executions.
+ *
+ * This is the UI side of the cursor mid-stream visibility fix. Before the fix,
+ * the runner streamed an empty sub_agent_executions list while the parent ran,
+ * so the task tool call had no match — it was hidden AND no card rendered (the
+ * "idle screen"). Persisting the IN_PROGRESS sub-agent mid-stream makes the
+ * match succeed, so the card renders live.
+ */
+
+function makeAiWithTaskCall(taskCallId: string): ReturnType<typeof create<typeof AgentMessageSchema>> {
+  const msg = create(AgentMessageSchema);
+  msg.type = MessageType.MESSAGE_AI;
+  msg.content = "Delegating to the researcher.";
+  const tc = create(ToolCallSchema);
+  tc.id = taskCallId;
+  tc.name = "task";
+  msg.toolCalls = [tc];
+  return msg;
+}
+
+function makeSubAgent(id: string, status: SubAgentStatus): ReturnType<typeof create<typeof SubAgentExecutionSchema>> {
+  const sa = create(SubAgentExecutionSchema);
+  sa.id = id;
+  sa.name = "Research renewable energy";
+  sa.subject = "Research renewable energy";
+  sa.status = status;
+  return sa;
+}
+
+function makeExecution(opts: {
+  id: string;
+  phase: ExecutionPhase;
+  messages: ReturnType<typeof create<typeof AgentMessageSchema>>[];
+  subAgents?: ReturnType<typeof create<typeof SubAgentExecutionSchema>>[];
+}): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+
+  const meta = create(ApiResourceMetadataSchema);
+  meta.id = opts.id;
+  exec.metadata = meta;
+
+  const spec = create(AgentExecutionSpecSchema);
+  spec.message = "Please delegate to the researcher.";
+  exec.spec = spec;
+
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = opts.phase;
+  status.messages = opts.messages;
+  if (opts.subAgents) {
+    status.subAgentExecutions = opts.subAgents;
+  }
+  exec.status = status;
+
+  return exec;
+}
+
+describe("buildThreadItems sub-agent correlation", () => {
+  it("renders an IN_PROGRESS sub-agent as a sub-agent item while the parent is still running", () => {
+    const taskId = "tool_live_1";
+    const exec = makeExecution({
+      id: "exec-live",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: [makeAiWithTaskCall(taskId)],
+      subAgents: [makeSubAgent(taskId, SubAgentStatus.SUB_AGENT_IN_PROGRESS)],
+    });
+
+    const items = buildThreadItems([exec], exec, null, false, undefined);
+
+    const subItem = items.find((i) => i.kind === "sub-agent");
+    expect(subItem).toBeDefined();
+    if (subItem?.kind !== "sub-agent") throw new Error("expected sub-agent item");
+    expect(subItem.subAgentExecution.id).toBe(taskId);
+    expect(subItem.subAgentExecution.status).toBe(
+      SubAgentStatus.SUB_AGENT_IN_PROGRESS,
+    );
+    expect(subItem.key).toBe(`sa-${taskId}`);
+
+    // The "task" tool call must never surface as a normal tool row — it is
+    // represented by the sub-agent card.
+    const toolGroups = items.filter((i) => i.kind === "tool-group");
+    for (const g of toolGroups) {
+      if (g.kind !== "tool-group") continue;
+      expect(g.toolCalls.some((tc) => tc.name === "task")).toBe(false);
+    }
+  });
+
+  it("renders a COMPLETED sub-agent as a sub-agent item", () => {
+    const taskId = "tool_done_1";
+    const exec = makeExecution({
+      id: "exec-done",
+      phase: ExecutionPhase.EXECUTION_COMPLETED,
+      messages: [makeAiWithTaskCall(taskId)],
+      subAgents: [makeSubAgent(taskId, SubAgentStatus.SUB_AGENT_COMPLETED)],
+    });
+
+    const items = buildThreadItems([exec], null, null, false, undefined);
+
+    const subItem = items.find((i) => i.kind === "sub-agent");
+    expect(subItem).toBeDefined();
+    if (subItem?.kind !== "sub-agent") throw new Error("expected sub-agent item");
+    expect(subItem.subAgentExecution.status).toBe(
+      SubAgentStatus.SUB_AGENT_COMPLETED,
+    );
+  });
+
+  it("documents the pre-fix invisible state: a task call with no matching sub-agent produces neither a card nor a tool row", () => {
+    // This is exactly the buggy cursor mid-stream state the runner fix
+    // eliminates: the task tool call exists in messages, but
+    // sub_agent_executions is still empty, so no sub-agent card renders and
+    // the task tool call is suppressed — the "nothing is happening" screen.
+    const taskId = "tool_orphan_1";
+    const exec = makeExecution({
+      id: "exec-orphan",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: [makeAiWithTaskCall(taskId)],
+      subAgents: [],
+    });
+
+    const items = buildThreadItems([exec], exec, null, false, undefined);
+
+    expect(items.some((i) => i.kind === "sub-agent")).toBe(false);
+    const toolGroups = items.filter((i) => i.kind === "tool-group");
+    for (const g of toolGroups) {
+      if (g.kind !== "tool-group") continue;
+      expect(g.toolCalls.some((tc) => tc.name === "task")).toBe(false);
+    }
+  });
+});

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

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import { ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ToolKind } from "@stigmer/sdk";
+import { useToolPresentation, registerToolPresenter } from "../tool-presenter";
+
+function makeToolCall(opts: {
+  name: string;
+  args?: Record<string, unknown>;
+  result?: string;
+  mcpServerSlug?: string;
+  status?: ToolCallStatus;
+}) {
+  return create(ToolCallSchema, {
+    id: opts.name,
+    name: opts.name,
+    args: (opts.args ?? {}) as JsonObject,
+    result: opts.result ?? "",
+    mcpServerSlug: opts.mcpServerSlug ?? "",
+    status: opts.status ?? ToolCallStatus.TOOL_CALL_COMPLETED,
+  });
+}
+
+describe("useToolPresentation", () => {
+  it("classifies a Cursor PascalCase edit tool (the bug this fixes)", () => {
+    const tc = makeToolCall({
+      name: "StrReplace",
+      args: { path: "/x.ts", old_string: "a", new_string: "b" },
+      result: '{"status":"success","value":{"linesAdded":1,"linesRemoved":1}}',
+    });
+    const { result } = renderHook(() => useToolPresentation(tc));
+
+    expect(result.current.kind).toBe(ToolKind.FILE_EDIT);
+    expect(result.current.category).toBe("edit");
+    expect(result.current.label).toBe("Edit");
+    expect(result.current.result.type).toBe("diff");
+    expect(result.current.resultSummary).toBe("+1 -1");
+  });
+
+  it("summarizes a failed shell exit code", () => {
+    const tc = makeToolCall({
+      name: "Shell",
+      args: { command: "false" },
+      result: "oops\n[Command failed with exit code 3]",
+    });
+    const { result } = renderHook(() => useToolPresentation(tc));
+
+    expect(result.current.kind).toBe(ToolKind.SHELL);
+    expect(result.current.result.type).toBe("terminal");
+    expect(result.current.resultSummary).toBe("exit 3");
+  });
+
+  it("extracts the primary argument", () => {
+    const tc = makeToolCall({ name: "Shell", args: { command: "ls -la" } });
+    const { result } = renderHook(() => useToolPresentation(tc));
+    expect(result.current.primaryArg).toBe("ls -la");
+  });
+
+  it("honors a registered custom presenter override and restores on dispose", () => {
+    const dispose = registerToolPresenter(ToolKind.SHELL, {
+      label: () => "Run command",
+    });
+    try {
+      const tc = makeToolCall({ name: "Shell", args: { command: "ls" } });
+      const { result } = renderHook(() => useToolPresentation(tc));
+      expect(result.current.label).toBe("Run command");
+    } finally {
+      dispose();
+    }
+
+    // After dispose, the default label is restored — no global leakage.
+    const tc = makeToolCall({ name: "Shell", args: { command: "ls" } });
+    const { result } = renderHook(() => useToolPresentation(tc));
+    expect(result.current.label).toBe("Shell");
+  });
+});

package/src/execution/index.ts

@@ -32,6 +32,9 @@ export type { SummarizationCardProps } from "./SummarizationCard";
 export { PlanCompletionCard } from "./PlanCompletionCard";
 export type { PlanCompletionCardProps } from "./PlanCompletionCard";
 
+export { PlanArtifactCard } from "./PlanArtifactCard";
+export type { PlanArtifactCardProps } from "./PlanArtifactCard";
+
 export { useExecutionArtifacts } from "./useExecutionArtifacts";
 export type { UseExecutionArtifactsReturn } from "./useExecutionArtifacts";
 
@@ -79,6 +82,16 @@ export type {
 export { ToolArgsView } from "./ToolArgsView";
 export type { ToolArgsViewProps } from "./ToolArgsView";
 
+export { ResultView, summarizeResultView } from "./ResultView";
+export type { ResultViewProps } from "./ResultView";
+
+export {
+  useToolPresentation,
+  registerToolPresenter,
+  getToolPresenter,
+} from "./tool-presenter";
+export type { ToolPresentation, ToolPresenter } from "./tool-presenter";
+
 export {
   CollapsibleCode,
   CollapsiblePre,
@@ -150,6 +163,9 @@ export type { WriteBacksWidgetProps } from "./WriteBacksWidget";
 
 export {
   resolveToolCategory,
+  resolveToolCategoryFromCall,
+  resolveToolCategoryFromKind,
+  toolKindToCategoryInfo,
   extractPrimaryArg,
   extractPrimaryArgFromPreview,
   humanizeToolName,

package/src/execution/tool-categories.ts

@@ -1,15 +1,15 @@
 import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import type { JsonObject } from "@bufbuild/protobuf";
+import { ToolKind, resolveToolKind, resolveToolKindByName } from "@stigmer/sdk";
 
 /**
  * Discriminated tool categories for type-aware rendering.
  *
- * Mirrors the CLI's `toolDisplayMap` in
- * `client-apps/cli/pkg/toolrender/render.go`.
- *
- * `"mcp"` covers tools originating from an MCP server whose
- * names are dynamic and cannot be statically listed in
- * {@link TOOL_DISPLAY_MAP}.
+ * This is the presentation taxonomy. Classification (name -> kind) lives in
+ * `@stigmer/sdk`'s `resolveToolKind` (single source of truth, shared with the
+ * runner and Go CLI); this file maps each {@link ToolKind} to its presentation
+ * metadata (label, primary argument). `"mcp"` covers tools originating from an
+ * MCP server, whose names are dynamic.
  */
 export type ToolCategory =
   | "shell"
@@ -19,6 +19,8 @@ export type ToolCategory =
   | "delete"
   | "search"
   | "list"
+  | "fetch"
+  | "web-search"
   | "think"
   | "sub-agent"
   | "internal"
@@ -37,77 +39,45 @@ export interface ToolCategoryInfo {
   readonly fallbackArgFields: readonly string[];
 }
 
-interface ToolDisplayEntry {
+interface KindDisplayEntry {
   readonly category: ToolCategory;
   readonly label: string;
   readonly primaryField: string;
   readonly fallbackFields?: readonly string[];
 }
 
-const TOOL_DISPLAY_MAP: ReadonlyMap<string, ToolDisplayEntry> = new Map([
-  ["shell",           { category: "shell",     label: "Shell",     primaryField: "command" }],
-  ["bash",            { category: "shell",     label: "Shell",     primaryField: "command" }],
-  ["execute",         { category: "shell",     label: "Execute",   primaryField: "command" }],
-  ["execute_command", { category: "shell",     label: "Shell",     primaryField: "command" }],
-  ["run_command",     { category: "shell",     label: "Shell",     primaryField: "command" }],
-  ["terminal",        { category: "shell",     label: "Shell",     primaryField: "command" }],
-
-  ["read",            { category: "read",      label: "Read",      primaryField: "path",    fallbackFields: ["file_path", "file"] }],
-  ["read_file",       { category: "read",      label: "Read",      primaryField: "path",    fallbackFields: ["file_path", "file"] }],
-
-  ["write",           { category: "write",     label: "Write",     primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
-  ["write_file",      { category: "write",     label: "Write",     primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
-  ["create_file",     { category: "write",     label: "Create",    primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
-  ["overwrite_file",  { category: "write",     label: "Write",     primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
-
-  ["edit",            { category: "edit",      label: "Edit",      primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
-  ["edit_file",       { category: "edit",      label: "Edit",      primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
-
-  ["delete_file",     { category: "delete",    label: "Delete",    primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
-  ["remove_file",     { category: "delete",    label: "Delete",    primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
-
-  ["glob",            { category: "search",    label: "Find",      primaryField: "pattern" }],
-  ["grep",            { category: "search",    label: "Search",    primaryField: "pattern" }],
-
-  ["list_directory",  { category: "list",      label: "List",      primaryField: "path" }],
-  ["ls",              { category: "list",      label: "List",      primaryField: "path" }],
-
-  ["think",           { category: "think",     label: "Thinking",  primaryField: "thought" }],
-
-  ["task",            { category: "sub-agent", label: "Sub-agent", primaryField: "description", fallbackFields: ["prompt"] }],
-
-  ["updateTodos",     { category: "internal",  label: "Todos",     primaryField: "todos" }],
-  ["TodoWrite",       { category: "internal",  label: "Todos",     primaryField: "todos" }],
-  ["write_todos",     { category: "internal",  label: "Todos",     primaryField: "todos" }],
-]);
+// Presentation metadata per ToolKind. Classification (name -> kind) is owned by
+// @stigmer/sdk; this table only describes how each kind is shown. MCP and
+// unknown are resolved dynamically (label derived from the tool name).
+const KIND_DISPLAY: Partial<Record<ToolKind, KindDisplayEntry>> = {
+  [ToolKind.FILE_READ]:   { category: "read",      label: "Read",      primaryField: "path", fallbackFields: ["file_path", "file"] },
+  [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.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"] },
+  [ToolKind.WEB_SEARCH]:  { category: "web-search", label: "Web Search", primaryField: "query", fallbackFields: ["q", "search_term"] },
+  [ToolKind.THINK]:       { category: "think",     label: "Thinking",  primaryField: "thought" },
+  [ToolKind.SUBAGENT]:    { category: "sub-agent", label: "Sub-agent", primaryField: "description", fallbackFields: ["prompt"] },
+  [ToolKind.TODO]:        { category: "internal",  label: "Todos",     primaryField: "todos" },
+};
 
 /**
- * Resolves a tool name to its category metadata for type-aware
- * rendering.
- *
- * When `mcpServerSlug` is provided and the tool name is not a
- * known built-in, the tool is categorised as `"mcp"` with a
- * human-readable label derived from the raw tool name.
- *
- * Falls back to `"unknown"` only when the tool is neither
- * built-in nor MCP-originated.
- */
-/**
- * Returns true if the tool is an internal state management tool that
- * should not be displayed in the message thread. Internal tools are
- * rendered through dedicated UX surfaces (e.g. TodoList sidebar)
- * rather than as expandable tool call items.
+ * Returns true if the tool is an internal state-management tool that should not
+ * appear in the message thread (todos are rendered through a dedicated surface).
  */
 export function isInternalTool(toolName: string): boolean {
-  const entry = TOOL_DISPLAY_MAP.get(toolName);
-  return entry?.category === "internal";
+  return resolveToolKindByName(toolName) === ToolKind.TODO;
 }
 
-export function resolveToolCategory(
+/** Maps a {@link ToolKind} to its presentation metadata. */
+export function toolKindToCategoryInfo(
+  kind: ToolKind,
   toolName: string,
-  mcpServerSlug?: string,
 ): ToolCategoryInfo {
-  const entry = TOOL_DISPLAY_MAP.get(toolName);
+  const entry = KIND_DISPLAY[kind];
   if (entry) {
     return {
       category: entry.category,
@@ -117,7 +87,7 @@ export function resolveToolCategory(
     };
   }
 
-  if (mcpServerSlug) {
+  if (kind === ToolKind.MCP) {
     return {
       category: "mcp",
       label: humanizeToolName(toolName),
@@ -128,12 +98,56 @@ export function resolveToolCategory(
 
   return {
     category: "unknown",
-    label: toolName,
+    label: humanizeToolName(toolName),
     primaryArgField: "",
     fallbackArgFields: [],
   };
 }
 
+/**
+ * Resolves a tool's presentation category from its name + MCP slug.
+ *
+ * Classification is delegated to `@stigmer/sdk`'s name-based resolver (the same
+ * table the runner and Go CLI use), then mapped to presentation metadata. When
+ * the caller has the full {@link ToolCall}, prefer {@link resolveToolCategoryFromCall},
+ * which also honours the wire `tool_kind` for forward compatibility.
+ */
+export function resolveToolCategory(
+  toolName: string,
+  mcpServerSlug?: string,
+): ToolCategoryInfo {
+  return toolKindToCategoryInfo(
+    resolveToolKindByName(toolName, mcpServerSlug),
+    toolName,
+  );
+}
+
+/**
+ * Like {@link resolveToolCategory} but uses the wire `tool_kind` when present,
+ * falling back to name-based resolution for legacy executions.
+ */
+export function resolveToolCategoryFromCall(toolCall: ToolCall): ToolCategoryInfo {
+  return toolKindToCategoryInfo(resolveToolKind(toolCall), toolCall.name);
+}
+
+/**
+ * Resolves presentation metadata from an explicit wire {@link ToolKind} plus the
+ * tool name and MCP slug. Used by surfaces that carry a denormalized `tool_kind`
+ * but not a full {@link ToolCall} — notably `PendingApproval`. Falls back to
+ * name-based resolution when the kind is unset (legacy executions).
+ */
+export function resolveToolCategoryFromKind(
+  toolKind: ToolKind,
+  toolName: string,
+  mcpServerSlug?: string,
+): ToolCategoryInfo {
+  const kind =
+    toolKind !== ToolKind.UNSPECIFIED
+      ? toolKind
+      : resolveToolKindByName(toolName, mcpServerSlug);
+  return toolKindToCategoryInfo(kind, toolName);
+}
+
 /**
  * Converts a snake_case or camelCase tool name into a
  * human-readable title.
@@ -188,7 +202,7 @@ function extractArgValue(
  * Returns `null` when the tool has no recognised arguments.
  */
 export function extractPrimaryArg(toolCall: ToolCall): string | null {
-  const info = resolveToolCategory(toolCall.name, toolCall.mcpServerSlug);
+  const info = resolveToolCategoryFromCall(toolCall);
   const result = extractArgValue(
     toolCall.args,
     info.primaryArgField,

package/src/execution/tool-presenter.ts

@@ -0,0 +1,118 @@
+"use client";
+
+// Headless presentation layer for tool calls.
+//
+// useToolPresentation turns a ToolCall into everything a renderer needs — kind,
+// label, primary argument, a normalized result view, and a one-line summary —
+// without rendering anything. Styled components (ToolCallItem, ToolCallDetail)
+// consume it; platform builders can consume it to build their own tool UI.
+//
+// The registry lets a consumer override the label or summary for a ToolKind
+// (e.g. a product that wants "Run command" instead of "Shell") without forking
+// the components. Result interpretation stays in @stigmer/sdk; this is the React
+// presentation seam.
+
+import { useMemo } from "react";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { ToolKind, resolveToolKind, normalizeToolResult } from "@stigmer/sdk";
+import type { ToolResultView } from "@stigmer/sdk";
+import { resolveToolCategoryFromCall, extractPrimaryArg } from "./tool-categories";
+import type { ToolCategory } from "./tool-categories";
+import { summarizeResultView } from "./ResultView";
+
+/** Optional per-kind overrides for label and summary. */
+export interface ToolPresenter {
+  /** Overrides the display label (e.g. "Shell" -> "Run command"). */
+  readonly label?: (toolCall: ToolCall) => string;
+  /** Overrides the one-line result summary suffix. */
+  readonly summary?: (toolCall: ToolCall, result: ToolResultView) => string | null;
+}
+
+const registry = new Map<ToolKind, ToolPresenter>();
+
+/**
+ * Registers a custom presenter for a {@link ToolKind}, overriding the default
+ * label and/or summary. Call once at app startup. This is the extension point
+ * for platform builders embedding the execution UI who want product-specific
+ * wording without forking the components.
+ *
+ * Returns a disposer that unregisters the presenter, restoring the previous one
+ * for that kind (or the default). Most apps register once at startup and ignore
+ * it; tests and dynamic hosts use it to avoid leaking global state.
+ *
+ * @example
+ * ```ts
+ * import { registerToolPresenter, ToolKind } from "@stigmer/react";
+ *
+ * const dispose = registerToolPresenter(ToolKind.SHELL, {
+ *   label: () => "Run command",
+ *   summary: (_tc, result) =>
+ *     result.type === "terminal" && result.exitCode ? `failed (${result.exitCode})` : null,
+ * });
+ * // later: dispose();
+ * ```
+ */
+export function registerToolPresenter(
+  kind: ToolKind,
+  presenter: ToolPresenter,
+): () => void {
+  const previous = registry.get(kind);
+  registry.set(kind, presenter);
+  return () => {
+    if (previous === undefined) {
+      registry.delete(kind);
+    } else {
+      registry.set(kind, previous);
+    }
+  };
+}
+
+/** Returns the registered presenter for a kind, if any. */
+export function getToolPresenter(kind: ToolKind): ToolPresenter | undefined {
+  return registry.get(kind);
+}
+
+/** The fully-resolved presentation for a tool call, returned by {@link useToolPresentation}. */
+export interface ToolPresentation {
+  /** Harness-agnostic kind (wire field, with name fallback). */
+  readonly kind: ToolKind;
+  /** Presentation category (1:1 with kind). */
+  readonly category: ToolCategory;
+  /** Display label, e.g. "Edit", "Shell". */
+  readonly label: string;
+  /** Primary argument (path, command, pattern...), or null. */
+  readonly primaryArg: string | null;
+  /** Normalized result view for rendering with {@link ResultView}. */
+  readonly result: ToolResultView;
+  /** One-line result summary suffix for the collapsed row (e.g. "+40 -0"). */
+  readonly resultSummary: string | null;
+}
+
+/**
+ * Resolves the complete, render-ready presentation for a tool call.
+ *
+ * Headless and memoized: the returned object is referentially stable across
+ * renders for the same `toolCall`, so it is safe to depend on in `React.memo`
+ * leaves of the streaming thread.
+ */
+export function useToolPresentation(toolCall: ToolCall): ToolPresentation {
+  return useMemo(() => {
+    const kind = resolveToolKind(toolCall);
+    const categoryInfo = resolveToolCategoryFromCall(toolCall);
+    const result = normalizeToolResult(toolCall);
+    const override = registry.get(kind);
+
+    const label = override?.label?.(toolCall) ?? categoryInfo.label;
+    const resultSummary =
+      override?.summary?.(toolCall, result) ?? summarizeResultView(result);
+
+    return {
+      kind,
+      category: categoryInfo.category,
+      label,
+      primaryArg: extractPrimaryArg(toolCall),
+      result,
+      resultSummary,
+    };
+  }, [toolCall]);
+}

package/src/execution/useCreateAgentExecution.ts

@@ -59,6 +59,15 @@ export interface CreateAgentExecutionInput {
    * Maps to `ExecutionConfig.interaction_mode` in the proto.
    */
   readonly interactionMode?: "agent" | "plan";
+  /**
+   * Auto-approve every tool call for this execution.
+   *
+   * When `true`, the human-in-the-loop approval gate is bypassed and no tool
+   * waits for approval. When `false` (default), mutating/destructive tools
+   * require approval per the configured policies. Maps to
+   * `AgentExecutionSpec.auto_approve_all` in the proto.
+   */
+  readonly autoApproveAll?: boolean;
   /**
    * JSON Schema that the agent's final output must conform to.
    *
@@ -174,6 +183,7 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
           agentId: input.agentId,
           message: input.message,
           executionConfig,
+          autoApproveAll: input.autoApproveAll,
           runtimeEnv: input.runtimeEnv,
           attachments: input.attachments,
           workspaceFileRefs: input.workspaceFileRefs,