@assistant-ui/core 0.2.7 → 0.2.9

package/src/react/model-context/define-toolkit.ts

@@ -0,0 +1,23 @@
+import type { Toolkit, ToolkitDeclaration } from "./toolbox";
+
+/**
+ * Authoring helper for a `"use generative"` toolkit. Accepts the permissive
+ * {@link ToolkitDeclaration} (a `backend` tool may carry its server `execute`)
+ * and types the result as the canonical {@link Toolkit}.
+ *
+ * It has **no runtime implementation**. A `"use generative"` compiler (e.g.
+ * `@assistant-ui/next` or `@assistant-ui/vite`) strips the `defineToolkit(...)`
+ * wrapper (and its import) per build, so a correctly compiled
+ * `export default defineToolkit({...})` never calls this. If it *does* run, the
+ * module was not compiled by a use-generative loader — e.g. `defineToolkit` used
+ * outside a `"use generative"` file — which would ship a backend `execute` to the
+ * client. So it throws instead of silently leaking.
+ */
+export function defineToolkit(_declaration: ToolkitDeclaration): Toolkit {
+  throw new Error(
+    "[assistant-ui] defineToolkit() has no runtime implementation — it is " +
+      "stripped at build time by the use-generative compiler. Reaching it means " +
+      'this module was not compiled (e.g. defineToolkit used outside a "use ' +
+      'generative" file). Add the directive, or do not use defineToolkit here.',
+  );
+}

package/src/react/model-context/hitl.ts

@@ -0,0 +1,22 @@
+/**
+ * Marks a tool as **human-in-the-loop**: the agent pauses and the UI (`render`)
+ * supplies the result instead of code. Use it as the tool's `execute`:
+ *
+ * ```tsx
+ * confirm: { execute: hitl(), render: (props) => <Confirm {...props} /> }
+ * ```
+ *
+ * Like {@link defineToolkit}, it has **no runtime implementation**: a
+ * `"use generative"` compiler (e.g. `@assistant-ui/next` or `@assistant-ui/vite`)
+ * detects `execute: hitl()`, drops it, and stamps the tool `type: "human"`.
+ * Reaching it at runtime means the module wasn't compiled (used outside a
+ * `"use generative"` file), so it throws.
+ */
+export function hitl(): never {
+  throw new Error(
+    "[assistant-ui] hitl() has no runtime implementation — it marks a " +
+      "human-in-the-loop tool and is stripped at build time by the " +
+      "use-generative compiler. Reaching it means this module was not compiled " +
+      '(e.g. hitl() used outside a "use generative" file).',
+  );
+}

package/src/react/model-context/toolbox.ts

@@ -1,6 +1,22 @@
-import type { Tool } from "assistant-stream";
+import type { Tool, ToolDeclaration } from "assistant-stream";
 import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
 
+/**
+ * Resolves whether a tool's UI should be presented standalone (outside the
+ * chain-of-thought grouping), applying the type-based defaults.
+ *
+ * An explicit `display` wins. Otherwise `human` tools default to standalone
+ * (they prompt the user), and every other tool defaults to inline (a trace of
+ * what the model is doing). MCP-app tool calls are detected separately from
+ * the part itself and are not resolved here.
+ */
+export const isStandaloneToolDisplay = (
+  tool: Pick<Tool<any, any>, "type" | "display">,
+): boolean => {
+  if (tool.display !== undefined) return tool.display === "standalone";
+  return tool.type === "human";
+};
+
 type WithRender<T, TArgs extends Record<string, unknown>, TResult> = T extends {
   type: "frontend" | "human";
 }
@@ -43,6 +59,35 @@ export type ToolDefinition<
  */
 export type Toolkit = Record<string, ToolDefinition<any, any>>;
 
+/**
+ * A tool as authored, before the build splits it: like {@link ToolDefinition}
+ * but it may declare `description`, `parameters`, and a server-side `execute`
+ * alongside its `render`. The `type` field is **not** authored — the
+ * `"use generative"` compiler infers it (`execute: hitl()` → human; `execute`
+ * with a `"use client"` directive → frontend; otherwise backend) and writes it
+ * back — so declaring it here is a type error.
+ */
+export type ToolkitDeclarationDefinition<
+  TArgs extends Record<string, unknown>,
+  TResult,
+> = WithRender<
+  Omit<ToolDeclaration<TArgs, TResult>, "type">,
+  TArgs,
+  TResult
+> & {
+  type?: never;
+};
+
+/**
+ * The permissive, authoring-time counterpart to {@link Toolkit} — the input to
+ * {@link defineToolkit}. Backend entries may carry their server `execute` here;
+ * the canonical {@link Toolkit} keeps those fields `undefined`.
+ */
+export type ToolkitDeclaration = Record<
+  string,
+  ToolkitDeclarationDefinition<any, any>
+>;
+
 /** Configuration for the {@link Tools} resource. */
 export type ToolsConfig = {
   /** Tools to register with model context and, when provided, message renderers. */

package/src/react/model-context/useAssistantTool.ts

@@ -2,6 +2,7 @@ import { useEffect } from "react";
 import { useAui } from "@assistant-ui/store";
 import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
 import type { AssistantToolProps as CoreAssistantToolProps } from "../..";
+import { isStandaloneToolDisplay } from "./toolbox";
 
 /**
  * Props used to register a tool from React.
@@ -52,13 +53,17 @@ export const useAssistantTool = <
 ) => {
   const aui = useAui();
 
+  const standalone = isStandaloneToolDisplay(tool);
+
   useEffect(() => {
     if (!tool.render) return undefined;
-    return aui.tools().setToolUI(tool.toolName, tool.render);
-  }, [aui, tool.toolName, tool.render]);
+    return aui.tools().setToolUI(tool.toolName, tool.render, { standalone });
+  }, [aui, tool.toolName, tool.render, standalone]);
 
   useEffect(() => {
-    const { toolName, render, ...rest } = tool;
+    // `render` and `display` are client-only presentation concerns and never
+    // reach the model.
+    const { toolName, render, display, ...rest } = tool;
     const context = {
       tools: {
         [toolName]: rest,

package/src/react/model-context/useAssistantToolUI.ts

@@ -8,6 +8,12 @@ export type AssistantToolUIProps<TArgs, TResult> = {
   toolName: string;
   /** Component rendered for matching tool-call message parts. */
   render: ToolCallMessagePartComponent<TArgs, TResult>;
+  /**
+   * How the UI is presented relative to the chain-of-thought trace. Set
+   * `"standalone"` to surface it on its own (e.g. human-in-the-loop or
+   * generative UI for a backend/MCP tool). Defaults to `"inline"`.
+   */
+  display?: "standalone" | "inline";
 };
 
 /**
@@ -23,8 +29,9 @@ export const useAssistantToolUI = (
   tool: AssistantToolUIProps<any, any> | null,
 ) => {
   const aui = useAui();
+  const standalone = tool?.display === "standalone";
   useEffect(() => {
     if (!tool?.toolName || !tool?.render) return undefined;
-    return aui.tools().setToolUI(tool.toolName, tool.render);
-  }, [aui, tool?.toolName, tool?.render]);
+    return aui.tools().setToolUI(tool.toolName, tool.render, { standalone });
+  }, [aui, tool?.toolName, tool?.render, standalone]);
 };

package/src/react/model-context/useInlineRender.ts

@@ -17,7 +17,6 @@ export const useInlineRender = <TArgs, TResult>(
 
   return useCallback(
     function ToolUI(args) {
-      // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
       const store = useToolUIStore();
       return store.toolUI(args);
     },

package/src/react/primitives/message/MessageGroupedParts.tsx

@@ -11,6 +11,7 @@ import type {
 import {
   buildGroupTree,
   GROUPBY_MEMO_KEY,
+  type GroupByContext,
   type GroupNode,
 } from "../../utils/groupParts";
 import { MessagePartChildren, type EnrichedPartState } from "./MessageParts";
@@ -28,13 +29,40 @@ export namespace MessagePrimitiveGroupedParts {
     readonly indices: readonly number[];
   };
 
+  /**
+   * Synthetic trailing slot for a streaming/loading affordance (a
+   * "thinking…" dot, etc.). Surfaced through the same `{ part }` channel
+   * as groups and leaf parts so a single `switch (part.type)` renders it
+   * via `case "indicator"`.
+   *
+   * It is only ever emitted while the message is running, so its presence
+   * alone means "render your loading UI here" — there's no `status` to
+   * branch on.
+   */
+  export type IndicatorPart = {
+    readonly type: "indicator";
+  };
+
+  /**
+   * When to emit the synthetic {@link IndicatorPart}. It is **only** emitted
+   * while the message is running (streaming); the mode further restricts
+   * which running states qualify:
+   * - `"never"` — never.
+   * - `"empty"` — only when the message has no parts yet.
+   * - `"no-text"` (default) — when the last part isn't `text`/`reasoning`
+   *   (e.g. it ended on a tool call, so the assistant likely isn't done).
+   * - `"always"` — whenever the message is running, regardless of parts.
+   */
+  export type IndicatorMode = "never" | "empty" | "no-text" | "always";
+
   export type RenderInfo<TKey extends `group-${string}` = `group-${string}`> = {
     /**
      * Either a coalesced group ({@link GroupPart}, identified by a
-     * `group-…` `type`) or a single enriched part. Use one switch over
-     * `part.type` to handle both.
+     * `group-…` `type`), a single enriched leaf part, or the synthetic
+     * {@link IndicatorPart} (`type: "indicator"`). Use one switch over
+     * `part.type` to handle all three.
      */
-    readonly part: GroupPart<TKey> | EnrichedPartState;
+    readonly part: GroupPart<TKey> | EnrichedPartState | IndicatorPart;
     /**
      * For group nodes: the recursively-rendered subtree (subgroups +
      * leaf parts). For leaf parts: a sentinel that throws when rendered
@@ -59,6 +87,9 @@ export namespace MessagePrimitiveGroupedParts {
      * the helper isn't expressive enough (e.g. branching on
      * `part.toolName` or part metadata).
      *
+     * The second argument is a {@link GroupByContext} carrying the tool-UI
+     * registry, for grouping that depends on it (e.g. standalone tool calls).
+     *
      * @example
      * ```tsx
      * import { groupPartByType } from "@assistant-ui/react";
@@ -71,12 +102,27 @@ export namespace MessagePrimitiveGroupedParts {
      * >
      * ```
      */
-    readonly groupBy: (part: PartState) => readonly TKey[] | null;
+    readonly groupBy: (
+      part: PartState,
+      context: GroupByContext,
+    ) => readonly TKey[] | null;
 
     /**
-     * Render function called once per group node and once per leaf part.
-     * Switch on `part.type`: `"group-…"` cases wrap `children`; real
-     * part types (`"text"`, `"tool-call"`, …) render the part directly.
+     * Controls emission of the synthetic {@link IndicatorPart} — a
+     * trailing `{ part: { type: "indicator", status } }` render call you
+     * handle with `case "indicator"` to show loading/status UI.
+     *
+     * @default "no-text"
+     * @see IndicatorMode
+     */
+    readonly indicator?: IndicatorMode;
+
+    /**
+     * Render function called once per group node, once per leaf part, and
+     * (when the `indicator` condition is met) once for the trailing
+     * {@link IndicatorPart}. Switch on `part.type`: `"group-…"` cases wrap
+     * `children`; real part types (`"text"`, `"tool-call"`, …) render the
+     * part directly; `"indicator"` renders status/loading UI.
      *
      * Leaf parts receive the same {@link EnrichedPartState} that
      * `<MessagePrimitive.Parts>` would produce (`toolUI`, `addResult`,
@@ -88,6 +134,31 @@ export namespace MessagePrimitiveGroupedParts {
 
 const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
 
+const shouldShowIndicator = (
+  mode: MessagePrimitiveGroupedParts.IndicatorMode,
+  parts: readonly PartState[],
+  isRunning: boolean,
+): boolean => {
+  // The indicator is a streaming affordance — never show it on a settled
+  // message, whatever the mode.
+  if (!isRunning) return false;
+
+  switch (mode) {
+    case "never":
+      return false;
+    case "always":
+      return true;
+    case "empty":
+      return parts.length === 0;
+    case "no-text": {
+      const last = parts[parts.length - 1];
+      return (
+        last !== undefined && last.type !== "text" && last.type !== "reasoning"
+      );
+    }
+  }
+};
+
 /**
  * `children` placeholder passed for leaf-part renders. Leaf parts have no
  * inner subtree; rendering this sentinel signals the consumer wrote
@@ -161,6 +232,7 @@ const renderNode = <TKey extends `group-${string}`>(
  *       case "group-tool":      return <ToolStack>{children}</ToolStack>;
  *       case "text":            return <MarkdownText />;
  *       case "tool-call":       return part.toolUI ?? <ToolFallback {...part} />;
+ *       case "indicator":       return <LoadingDots />;
  *       default:                return null;
  *     }
  *   }}
@@ -169,9 +241,17 @@ const renderNode = <TKey extends `group-${string}`>(
  */
 export const MessagePrimitiveGroupedParts = <TKey extends `group-${string}`>({
   groupBy,
+  indicator = "no-text",
   children,
 }: MessagePrimitiveGroupedParts.Props<TKey>): ReactNode => {
   const parts = useAuiState(useShallow((s) => s.message.parts));
+  // Handed to `groupBy` as its `context` argument (see GroupByContext).
+  const toolUIs = useAuiState((s) => s.tools.toolUIs);
+  // Subscribe to a boolean, not the status object: the tree only needs to
+  // re-render when running-ness flips, and `"never"` opts out entirely.
+  const isRunning = useAuiState((s) =>
+    indicator === "never" ? false : s.message.status?.type === "running",
+  );
 
   // Helpers like `groupPartByType` tag the function with `GROUPBY_MEMO_KEY`
   // (a stable string fingerprint of the helper config). When present,
@@ -182,13 +262,22 @@ export const MessagePrimitiveGroupedParts = <TKey extends `group-${string}`>({
     GROUPBY_MEMO_KEY
   ];
   const memoDep = memoKey ?? groupBy;
-  const tree = useMemo(
-    () => buildGroupTree(parts.map((part) => groupBy(part) ?? [])),
+  const tree = useMemo(() => {
+    const context: GroupByContext = { toolUIs };
+    return buildGroupTree(parts.map((part) => groupBy(part, context) ?? []));
     // oxlint-disable-next-line tap-hooks/exhaustive-deps -- groupBy is captured via memoDep (either its identity or the helper's memoKey fingerprint); listing it directly would defeat the helper-tagged memo path
-    [parts, memoDep],
-  );
+  }, [parts, memoDep, toolUIs]);
 
-  return <>{tree.map((node) => renderNode(node, parts, children))}</>;
+  return (
+    <>
+      {tree.map((node) => renderNode(node, parts, children))}
+      {shouldShowIndicator(indicator, parts, isRunning) &&
+        children({
+          part: { type: "indicator" },
+          children: <PartChildrenSentinel />,
+        })}
+    </>
+  );
 };
 
 MessagePrimitiveGroupedParts.displayName = "MessagePrimitive.GroupedParts";

package/src/react/primitives/message/MessageParts.tsx

@@ -308,11 +308,9 @@ const ToolUIDisplay = ({
 }: {
   Fallback: ToolCallMessagePartComponent | undefined;
 } & ToolCallMessagePartProps) => {
-  const Render = useAuiState((s) => {
-    const Render = s.tools.tools[props.toolName] ?? Fallback;
-    if (Array.isArray(Render)) return Render[0] ?? Fallback;
-    return Render;
-  });
+  const Render = useAuiState(
+    (s) => s.tools.toolUIs[props.toolName]?.[0]?.render ?? Fallback,
+  );
   if (!Render) return null;
   return <Render {...props} />;
 };
@@ -574,8 +572,7 @@ function resolveToolRender(
   toolsState: ToolsState,
   part: Extract<PartState, { type: "tool-call" }>,
 ): ToolCallMessagePartComponent | null {
-  const entry = toolsState.tools[part.toolName];
-  const named = Array.isArray(entry) ? (entry[0] ?? null) : (entry ?? null);
+  const named = toolsState.toolUIs[part.toolName]?.[0]?.render ?? null;
   if (named) return named;
   if (isMcpAppUri(part.mcp?.app?.resourceUri) && toolsState.mcpApp) {
     return toolsState.mcpApp.render;

package/src/react/runtimes/RemoteThreadListThreadListRuntimeCore.tsx

@@ -62,7 +62,6 @@ export class RemoteThreadListThreadListRuntimeCore
               isLoading: true,
             };
           },
-          // biome-ignore lint/suspicious/noThenProperty: OptimisticState reducer pattern
           then: (state, l) => {
             if (generation !== this._loadGeneration) return state;
             const fresh = classifyThreads(l.threads, {
@@ -120,7 +119,6 @@ export class RemoteThreadListThreadListRuntimeCore
       .optimisticUpdate({
         execute: () => adapter.list({ after: cursor }),
         loading: (state) => ({ ...state, isLoadingMore: true }),
-        // biome-ignore lint/suspicious/noThenProperty: OptimisticState reducer pattern
         then: (state, l) => {
           if (generation !== this._loadGeneration) return state;
           if (adapter !== this._options.adapter) return state;
@@ -423,7 +421,6 @@ export class RemoteThreadListThreadListRuntimeCore
           },
         };
       },
-      // biome-ignore lint/suspicious/noThenProperty: OptimisticState reducer pattern
       then: (state, { remoteId, externalId }) => {
         const data = getThreadData(state, threadId);
         if (!data) return state;

package/src/react/runtimes/RuntimeAdapterProvider.tsx

@@ -1,4 +1,10 @@
-import { createContext, type FC, type ReactNode, useContext } from "react";
+import {
+  createContext,
+  type FC,
+  type ReactNode,
+  useContext,
+  useMemo,
+} from "react";
 import type { ThreadHistoryAdapter } from "../../adapters/thread-history";
 import type { AttachmentAdapter } from "../../adapters/attachment";
 import type { ModelContextProvider } from "../../model-context/types";
@@ -23,13 +29,12 @@ export const RuntimeAdapterProvider: FC<RuntimeAdapterProvider.Props> = ({
   children,
 }) => {
   const context = useContext(RuntimeAdaptersContext);
+  const value = useMemo(
+    () => ({ ...context, ...adapters }),
+    [context, adapters],
+  );
   return (
-    <RuntimeAdaptersContext.Provider
-      value={{
-        ...context,
-        ...adapters,
-      }}
-    >
+    <RuntimeAdaptersContext.Provider value={value}>
       {children}
     </RuntimeAdaptersContext.Provider>
   );

package/src/react/runtimes/cloud/useCloudThreadListAdapter.tsx

@@ -43,20 +43,17 @@ export const useCloudThreadListAdapter = (
 
   const unstable_Provider = useCallback<FC<PropsWithChildren>>(
     function Provider({ children }) {
-      // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
       const history = useAssistantCloudThreadHistoryAdapter({
         get current() {
           return adapterRef.current.cloud ?? autoCloud!;
         },
       });
       const cloudInstance = adapterRef.current.cloud ?? autoCloud!;
-      // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
       const attachments = useMemo(
         () => new CloudFileAttachmentAdapter(cloudInstance),
         [cloudInstance],
       );
 
-      // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
       const adapters = useMemo(
         () => ({
           history,

package/src/react/runtimes/external-message-converter.ts

@@ -198,6 +198,10 @@ const joinExternalMessages = (
                 assistantMessage.metadata.submittedFeedback =
                   output.metadata.submittedFeedback;
               }
+
+              if (output.metadata.isOptimistic) {
+                assistantMessage.metadata.isOptimistic = true;
+              }
             }
             // TODO keep this in sync
           }

package/src/react/runtimes/useExternalStoreSharedOptions.ts

@@ -0,0 +1,23 @@
+"use client";
+
+import { useMemo } from "react";
+import type { ExternalStoreSharedOptions } from "../../runtimes/external-store/external-store-shared-options";
+
+export const useExternalStoreSharedOptions = (
+  options: ExternalStoreSharedOptions,
+): ExternalStoreSharedOptions => {
+  const { isDisabled, isSendDisabled, unstable_capabilities, suggestions } =
+    options;
+  return useMemo(
+    () =>
+      ({
+        isDisabled,
+        isSendDisabled,
+        unstable_capabilities,
+        suggestions,
+      }) satisfies {
+        [K in keyof Required<ExternalStoreSharedOptions>]: ExternalStoreSharedOptions[K];
+      },
+    [isDisabled, isSendDisabled, unstable_capabilities, suggestions],
+  );
+};

package/src/react/runtimes/useLocalRuntime.ts

@@ -22,7 +22,6 @@ const useLocalThreadRuntime = (
   chatModel: ChatModelAdapter,
   { initialMessages, ...options }: LocalRuntimeOptions,
 ): AssistantRuntime => {
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const { modelContext, ...threadListAdapters } = useRuntimeAdapters() ?? {};
   const opt = {
     ...options,
@@ -33,41 +32,33 @@ const useLocalThreadRuntime = (
     },
   };
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const [runtime] = useState(() => new LocalRuntimeCore(opt, initialMessages));
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const threadIdRef = useRef<string | undefined>(undefined);
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   threadIdRef.current = useAuiState((s) => s.threadListItem.remoteId);
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   useEffect(() => {
     runtime.threads
       .getMainThreadRuntimeCore()
       .__internal_setGetThreadId(() => threadIdRef.current);
   }, [runtime]);
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   useEffect(() => {
     return () => {
       runtime.threads.getMainThreadRuntimeCore().detach();
     };
   }, [runtime]);
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   useEffect(() => {
     runtime.threads.getMainThreadRuntimeCore().__internal_setOptions(opt);
     runtime.threads.getMainThreadRuntimeCore().__internal_load();
   });
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   useEffect(() => {
     if (!modelContext) return undefined;
     return runtime.registerModelContextProvider(modelContext);
   }, [modelContext, runtime]);
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   return useMemo(() => new AssistantRuntimeImpl(runtime), [runtime]);
 };
 
@@ -102,7 +93,6 @@ export const useLocalRuntime = (
   const cloudAdapter = useCloudThreadListAdapter({ cloud });
   return useRemoteThreadListRuntime({
     runtimeHook: function RuntimeHook() {
-      // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
       return useLocalThreadRuntime(chatModel, options);
     },
     adapter: cloudAdapter,

package/src/react/runtimes/useRemoteThreadListRuntime.ts

@@ -29,15 +29,12 @@ class RemoteThreadListRuntimeCore
 const useRemoteThreadListRuntimeImpl = (
   options: RemoteThreadListOptions,
 ): AssistantRuntime => {
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const [runtime] = useState(() => new RemoteThreadListRuntimeCore(options));
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   useEffect(() => {
     runtime.threads.__internal_setOptions(options);
     runtime.threads.__internal_load();
   }, [runtime, options]);
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   return useMemo(() => new AssistantRuntimeImpl(runtime), [runtime]);
 };
 
@@ -80,12 +77,9 @@ export const useRemoteThreadListRuntime = (
     return stableRuntimeHook();
   }
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const runtime = useRemoteThreadListRuntimeImpl(stableOptions);
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const prevThreadIdRef = useRef(options.threadId);
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   useEffect(() => {
     if (options.threadId === prevThreadIdRef.current) return;
     prevThreadIdRef.current = options.threadId;

package/src/react/types/scopes/tools.ts

@@ -5,9 +5,27 @@ export type McpAppResourceOutput = {
   readonly render: ToolCallMessagePartComponent;
 };
 
+/**
+ * A single tool-UI registration: the renderer plus its presentation options.
+ * Stored as a per-tool-name list so the name stays registered while any
+ * registration of it is mounted.
+ */
+type ToolRegistration = {
+  readonly render: ToolCallMessagePartComponent;
+  /** Whether this UI renders standalone, outside the chain-of-thought trace. */
+  readonly standalone: boolean;
+};
+
 export type ToolsState = {
-  tools: Record<string, ToolCallMessagePartComponent[]>;
+  /** Registered tool UIs (renderer + presentation options) keyed by tool name. */
+  toolUIs: Record<string, readonly ToolRegistration[]>;
   mcpApp?: McpAppResourceOutput | undefined;
+  /**
+   * @deprecated Use {@link toolUIs} instead, whose entries carry the renderer
+   * alongside its presentation options. This component-only map is kept for
+   * back-compat and will be removed in v0.15.
+   */
+  tools: Record<string, ToolCallMessagePartComponent[]>;
 };
 
 export type ToolsMethods = {
@@ -15,6 +33,7 @@ export type ToolsMethods = {
   setToolUI(
     toolName: string,
     render: ToolCallMessagePartComponent,
+    options?: { standalone?: boolean },
   ): Unsubscribe;
 };