@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/hooks/use-tool-result-recovery.ts

@@ -1,41 +1,55 @@
-import { useEffect, useRef, useState } from "react"
-import { parseToolResult } from "../lib/parse-tool-result.js"
+import { useEffect, useState, useSyncExternalStore } from "react"
+import { installToolResultObserver, type ToolResultObserver } from "../lib/tool-result-observer.js"
+import {
+  createRecoveryController,
+  type RecoveryPolicy,
+  type ToolResultRecoveryState,
+} from "./tool-result-recovery-model.js"
+
+export { decodeRecoveredResult } from "./tool-result-recovery-model.js"
+export type {
+  RecoveryBlockReason,
+  RecoveryPolicy,
+  ToolResultRecoveryState,
+  ToolSafety,
+} from "./tool-result-recovery-model.js"
 
 /**
  * Recovery for hosts that deliver the `ui/notifications/tool-result`
  * notification without `structuredContent` (observed on claude.ai and Claude
- * Desktop, which forward only the model-facing `content` blocks). Since
- * mcp-use 2.x such a result is not even observable: the `useToolContext`
- * latch ignores content-only successes, so the tool status stays `"pending"`
- * forever and the shell would idle on its loading skeleton.
+ * Desktop, which forward only the model-facing `content` blocks). mcp-use
+ * 2.x's `useToolContext` latch ignores such a content-only result, so its
+ * status stays `"pending"` forever and the shell would idle on its skeleton.
  *
- * Because the stripped notification is invisible, readiness is inferred two
- * ways: the hard `resultReady` signal (the latch fired but the payload is
- * invalid), or a grace timer — once the originating tool is known and no
- * result has latched within
- * {@link ToolResultRecoveryOptions.assumeStrippedAfterMs}, the result is
- * assumed delivered-but-stripped. Either way the hook re-executes the
- * originating tool once via the host bridge's official `callTool` — tool-call
- * RESPONSES carry `structuredContent` intact on those hosts — and exposes the
- * decoded payload. Spec-conforming hosts (e.g. the mcp-use inspector) deliver
- * a valid payload up front, so the recovery never fires there.
+ * The hook re-executes the originating tool once via the host bridge's
+ * `callTool` — tool-call RESPONSES carry `structuredContent` intact on those
+ * hosts — and exposes the decoded payload. When it does so (toolkit#176):
  *
- * A call the host cancelled is never recovered: since mcp-use 2.7.1 the
- * cancellation latches as `status: "error"` (a `ToolCancelledError`), which
- * would otherwise count as a ready-but-invalid result — re-executing it would
- * override the user's decision to stop the call.
+ * - **Only when the host stripped the result.** A passive observer of the
+ *   host's lifecycle notifications (`installToolResultObserver`) sees the
+ *   content-only result itself, so the recovery fires as it arrives, and a
+ *   slow tool on a compliant host is never re-run (K13): no result has
+ *   arrived because none was sent. Where the observer cannot vouch for that
+ *   (no browser frame, or installed after the handshake), the 2.x grace timer
+ *   ({@link ToolResultRecoveryOptions.assumeStrippedAfterMs}) still infers a
+ *   stripped result, once the call's arguments arrived.
+ * - **With the call's complete arguments** (N21): the observer's complete
+ *   `tool-input`, never a partial stream; an equal re-delivery is the same run.
+ * - **Never for a cancelled or failed call:** re-running repeats the failure
+ *   or overrides the user's stop; the shell renders that state and offers an
+ *   explicit retry.
+ * - **Only for a tool the policy allows** ({@link ToolResultRecoveryOptions.policy}):
+ *   by default never one the host reports as writing (`readOnlyHint: false`
+ *   or `destructiveHint: true` in `hostContext.toolInfo.tool.annotations`).
+ *   A blocked recovery is reported (`blocked`) so the view can show its error.
  *
- * Assumes the originating tool is a read-only render pipeline (true for all
- * toolkit `render-view`/`show_*` tools) — the re-execution must be safe to
- * repeat, and may rarely run concurrently with the original invocation when
- * the grace timer beats a slow but conforming host.
+ * The decision and its timer live in `createRecoveryController`; this hook
+ * only binds it to React.
  */
 
 /**
- * Default grace period before a silent latch counts as a stripped result.
- * Long enough for a conforming host to latch a typical render tool first,
- * short enough that users on stripping hosts are not left staring at the
- * skeleton noticeably.
+ * Default grace period before a silent latch counts as a stripped result —
+ * used only where the transport observer cannot vouch that nothing arrived.
  */
 export const DEFAULT_ASSUME_STRIPPED_AFTER_MS = 2500
 
@@ -43,8 +57,7 @@ export interface ToolResultRecoveryOptions {
   /**
    * The latch fired (`useToolContext().status !== "pending"`) — a structured
    * result, a tool error, or a host cancellation arrived. On hosts that strip
-   * `structuredContent` this never turns true; the grace timer below covers
-   * that case.
+   * `structuredContent` this never turns true.
    */
   resultReady: boolean
   /**
@@ -53,12 +66,17 @@ export interface ToolResultRecoveryOptions {
    * attempt already in flight is dropped. Defaults to `false`.
    */
   cancelled?: boolean
-  /** The payload the host delivered (`useToolContext().toolOutput`). */
-  props: unknown
   /**
-   * Validates a candidate payload. MUST be referentially stable (module-level
-   * function or memoised) — it is an effect dependency.
+   * The originating call latched a tool error (`useToolContext().status ===
+   * "error"` without a cancellation): an `isError` result or a failed call.
+   * Suppresses the recovery exactly like {@link cancelled} — the shell shows
+   * the error instead of silently re-running a call that just failed
+   * (toolkit#176). Defaults to `false`.
    */
+  errored?: boolean
+  /** The payload the host delivered (`useToolContext().toolOutput`). */
+  props: unknown
+  /** Validates a candidate payload. */
   isValid: (value: unknown) => boolean
   /** The tool arguments from `ui/notifications/tool-input` (`useToolContext().toolInput`). */
   toolInput: Record<string, unknown> | null | undefined
@@ -68,23 +86,21 @@ export interface ToolResultRecoveryOptions {
   callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>
   /**
    * Grace period in ms after which a silent latch counts as a stripped
-   * result. Armed once the originating tool is known while `resultReady` is
-   * still false; re-armed on every `toolInput` update, because streaming
-   * arguments mean the invocation may not have finished yet. Defaults to
+   * result. Applies only where the transport observer cannot vouch that no
+   * result arrived (see above); restarts for new arguments. Defaults to
    * {@link DEFAULT_ASSUME_STRIPPED_AFTER_MS}.
    */
   assumeStrippedAfterMs?: number
+  /** Which tools may be re-executed on their own. Default `"auto"`. */
+  policy?: RecoveryPolicy
+  /**
+   * The transport observer. Defaults to the document's
+   * (`installToolResultObserver()`); `null` disables it, leaving the grace
+   * timer to decide alone (the 2.x behaviour).
+   */
+  observer?: ToolResultObserver | null
 }
 
-export interface ToolResultRecoveryState<T> {
-  /** The recovered payload, `null` until the re-execution resolved (or when it failed). */
-  data: T | null
-  /** `true` when the single recovery attempt failed — the shell keeps its skeleton, no retry loop. */
-  failed: boolean
-}
-
-const IDLE: ToolResultRecoveryState<never> = { data: null, failed: false }
-
 /**
  * Resolves the originating tool name from the host context's `toolInfo`.
  * Reads the SEP-1865 shape first (`toolInfo.tool.name`), then the flattened
@@ -108,20 +124,19 @@ export function resolveRecoveryToolName(hostContext: unknown): string | undefine
 }
 
 /**
- * Decodes a re-executed tool result and validates it. Exposed for tests;
- * the hook uses it on the `callTool` response.
+ * Whether a latched or assumed-stripped result may be recovered at all: the
+ * call was neither cancelled nor failed. Kept for existing imports; the full
+ * rule (observer, policy, arguments) is `decideRecovery`.
+ * @deprecated Use `decideRecovery` from the recovery model.
  */
-export function decodeRecoveredResult<T>(
-  result: unknown,
-  isValid: (value: unknown) => boolean,
-): T | null {
-  let decoded: unknown
-  try {
-    decoded = parseToolResult<unknown>(result)
-  } catch {
-    return null
-  }
-  return decoded !== null && isValid(decoded) ? (decoded as T) : null
+export function isRecoveryReady(state: {
+  resultReady: boolean
+  assumedReady: boolean
+  cancelled: boolean
+  errored: boolean
+}): boolean {
+  if (state.cancelled || state.errored) return false
+  return state.resultReady || state.assumedReady
 }
 
 export function useToolResultRecovery<T>(
@@ -130,86 +145,41 @@ export function useToolResultRecovery<T>(
   const {
     resultReady,
     cancelled = false,
+    errored = false,
     props,
     isValid,
     toolInput,
     hostContext,
     callTool,
     assumeStrippedAfterMs = DEFAULT_ASSUME_STRIPPED_AFTER_MS,
+    policy = "auto",
+    observer,
   } = options
-  const [state, setState] = useState<ToolResultRecoveryState<T>>(IDLE)
-  // Single-flight: the promise ref survives StrictMode's dev-mode
-  // effect re-run (cleanup + setup on the same instance), so the re-run
-  // re-subscribes to the SAME in-flight call instead of firing a second one.
-  const flightRef = useRef<Promise<ToolResultRecoveryState<T>> | null>(null)
-  const flightInputRef = useRef<unknown>(null)
-
-  const toolName = resolveRecoveryToolName(hostContext)
-
-  // A stripped result is unobservable (the 2.x latch ignores content-only
-  // results), so infer it: once a recovery could fire but the latch has been
-  // silent for the grace period, treat the result as delivered-but-stripped.
-  // Re-armed on every toolInput identity change — streaming arguments mean
-  // the invocation may still be running, so the grace period starts over.
-  // The re-arm is a render-phase reset (not an effect) so the cascading-
-  // render lint stays satisfied; the timer effect below restarts anyway
-  // because toolInput is one of its dependencies.
-  const [assumedReady, setAssumedReady] = useState(false)
-  const [prevTimerInput, setPrevTimerInput] = useState<unknown>(toolInput)
-  if (prevTimerInput !== toolInput) {
-    setPrevTimerInput(toolInput)
-    if (assumedReady) setAssumedReady(false)
-  }
+  // One controller per mount; it survives StrictMode's effect re-run, so an
+  // in-flight call is never fired twice.
+  const [controller] = useState(() =>
+    createRecoveryController<T>({
+      observer: observer === undefined ? installToolResultObserver() : observer,
+    }),
+  )
   useEffect(() => {
-    if (resultReady || cancelled || toolName === undefined) return
-    const timer = setTimeout(() => setAssumedReady(true), assumeStrippedAfterMs)
-    return () => clearTimeout(timer)
-  }, [resultReady, cancelled, toolName, toolInput, assumeStrippedAfterMs])
-
-  // A cancelled call never counts as ready, so the effect below invalidates
-  // any in-flight attempt the same way it does for a superseded run.
-  const ready = !cancelled && (resultReady || assumedReady)
-
+    controller.start()
+    return () => controller.stop()
+  }, [controller])
   useEffect(() => {
-    // A new tool run (result no longer ready, or fresh tool-input identity)
-    // invalidates any previous recovery attempt and re-arms the single-flight.
-    if (flightRef.current && (!ready || flightInputRef.current !== toolInput)) {
-      flightRef.current = null
-      setState((prev) => (prev.data === null && !prev.failed ? prev : IDLE))
-    }
-    // Never fire on conforming hosts (valid payload) or before the
-    // originating tool is known.
-    if (!ready || isValid(props) || toolName === undefined) return
-
-    if (!flightRef.current) {
-      flightInputRef.current = toolInput
-      flightRef.current = (async (): Promise<ToolResultRecoveryState<T>> => {
-        try {
-          const result = await callTool(toolName, toolInput ?? {})
-          const data = decodeRecoveredResult<T>(result, isValid)
-          if (data !== null) return { data, failed: false }
-          console.warn(
-            `[mcp-toolkit] tool-result recovery: re-executing "${toolName}" returned no usable payload`,
-          )
-          return { data: null, failed: true }
-        } catch (err) {
-          console.warn(`[mcp-toolkit] tool-result recovery for "${toolName}" failed:`, err)
-          return { data: null, failed: true }
-        }
-      })()
-    }
-
-    const flight = flightRef.current
-    let stale = false
-    void flight.then((outcome) => {
-      // Drop the outcome when this subscription was superseded or the flight
-      // was invalidated by a newer tool run.
-      if (!stale && flightRef.current === flight) setState(outcome)
+    controller.update({
+      resultReady,
+      cancelled,
+      errored,
+      props,
+      isValid,
+      toolInput,
+      hostContext,
+      callTool,
+      policy,
+      graceMs: assumeStrippedAfterMs,
+      resolveToolName: resolveRecoveryToolName,
     })
-    return () => {
-      stale = true
-    }
-  }, [ready, props, isValid, toolName, toolInput, callTool])
-
-  return state
+  })
+  return useSyncExternalStore(controller.subscribe, controller.getState, controller.getState)
 }

package/src/hooks/use-view-data.test.tsx

@@ -0,0 +1,169 @@
+import { QueryClient } from "@tanstack/react-query"
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it, vi } from "vitest"
+import { toolQueryKey } from "../lib/tool-query.js"
+import { AppQueryProvider } from "../providers/query-provider.js"
+import { useViewData, type UseViewDataOptions, type ViewDataResult } from "./use-view-data.js"
+
+type Demo = { n: number }
+type CallTool = (name: string, args: object) => Promise<unknown>
+
+const KEY = ["use-view-data.test"] as const
+const ARGS = { id: 1 }
+
+/** Renders a probe once (SSR, the house path) and hands back the hook's result. */
+function probe(
+  initialData: Demo | null,
+  ready: boolean,
+  callTool: CallTool,
+  key: string,
+  options?: UseViewDataOptions<Demo> & { client?: QueryClient; toolNameInQueryKey?: boolean },
+): ViewDataResult<Demo> {
+  let result: ViewDataResult<Demo> | undefined
+  const { client, toolNameInQueryKey, ...hookOptions } = options ?? {}
+  function Probe() {
+    result = useViewData<Demo>(initialData, [...KEY, key], "demo_data", ARGS, ready, hookOptions)
+    return null
+  }
+  renderToStaticMarkup(
+    <AppQueryProvider callTool={callTool} client={client} toolNameInQueryKey={toolNameInQueryKey}>
+      <Probe />
+    </AppQueryProvider>,
+  )
+  if (!result) throw new Error("probe did not render")
+  return result
+}
+
+describe("useViewData", () => {
+  it("returns host-pushed data verbatim without fetching", () => {
+    const callTool = vi.fn<CallTool>(() => Promise.resolve({}))
+    const result = probe({ n: 1 }, true, callTool, "pushed")
+    expect(result.data).toEqual({ n: 1 })
+    expect(result.loading).toBe(false)
+    expect(result.error).toBeNull()
+    expect(callTool).not.toHaveBeenCalled()
+  })
+
+  it("is not loading before it is ready", () => {
+    const result = probe(null, false, vi.fn<CallTool>(), "not-ready")
+    expect(result).toMatchObject({ data: null, loading: false, error: null })
+  })
+
+  it("exposes the query's progress: failureCount, failureReason, isFetching, isPlaceholderData", () => {
+    const result = probe(null, false, vi.fn<CallTool>(), "progress")
+    expect(result).toMatchObject({
+      failureCount: 0,
+      failureReason: null,
+      isFetching: false,
+      isPlaceholderData: false,
+    })
+  })
+
+  it("refetch calls the tool again: the retry an error state offers", async () => {
+    const callTool = vi.fn<CallTool>(() => Promise.resolve({ structuredContent: { n: 2 } }))
+    const result = probe(null, false, callTool, "refetch")
+    expect(callTool).not.toHaveBeenCalled()
+    result.refetch()
+    await vi.waitFor(() => {
+      expect(callTool).toHaveBeenCalledWith("demo_data", { id: 1 })
+    })
+  })
+
+  it("enabled: false gates the feed next to ready; a ready feed without data is loading", () => {
+    const client = new QueryClient()
+    expect(probe(null, true, vi.fn<CallTool>(), "gated", { client, enabled: false }).loading).toBe(
+      false,
+    )
+    expect(probe(null, true, vi.fn<CallTool>(), "open", { client }).loading).toBe(true)
+  })
+
+  it("a function gate that says no idles like enabled: false, never an endless skeleton", () => {
+    const client = new QueryClient()
+    const closed = probe(null, true, vi.fn<CallTool>(), "fn-closed", {
+      client,
+      enabled: () => false,
+    })
+    expect(closed).toMatchObject({ data: null, loading: false, error: null })
+    const open = probe(null, true, vi.fn<CallTool>(), "fn-open", { client, enabled: () => true })
+    expect(open.loading).toBe(true)
+    // Not ready keeps it off whatever the gate says.
+    expect(
+      probe(null, false, vi.fn<CallTool>(), "fn-not-ready", { client, enabled: () => true })
+        .loading,
+    ).toBe(false)
+  })
+
+  it("passes TanStack's options through: initialData-free placeholderData shows meanwhile", () => {
+    const client = new QueryClient()
+    const result = probe(null, true, vi.fn<CallTool>(), "placeholder", {
+      client,
+      placeholderData: { n: 0 },
+    })
+    expect(result).toMatchObject({ data: { n: 0 }, isPlaceholderData: true, loading: false })
+  })
+})
+
+describe('useViewData initialDataMode: "seed" (the live standalone view)', () => {
+  const cacheKey = (key: string) => toolQueryKey([...KEY, key], "demo_data", ARGS)
+
+  it("seeds the feed's cache entry with the host's payload and returns it", () => {
+    const client = new QueryClient()
+    const result = probe({ n: 1 }, true, vi.fn<CallTool>(), "seeded", {
+      client,
+      initialDataMode: "seed",
+      initialDataUpdatedAt: 1234,
+    })
+    expect(result).toMatchObject({ data: { n: 1 }, loading: false })
+    expect(client.getQueryData(cacheKey("seeded"))).toEqual({ n: 1 })
+    expect(client.getQueryState(cacheKey("seeded"))?.dataUpdatedAt).toBe(1234)
+  })
+
+  it("with toolNameInQueryKey the seed lands under the key carrying the tool name", () => {
+    const client = new QueryClient()
+    const result = probe({ n: 1 }, true, vi.fn<CallTool>(), "tool-key", {
+      client,
+      initialDataMode: "seed",
+      toolNameInQueryKey: true,
+    })
+    expect(result.data).toEqual({ n: 1 })
+    expect(client.getQueryData([...KEY, "tool-key", "demo_data", ARGS])).toEqual({ n: 1 })
+    expect(client.getQueryData(cacheKey("tool-key")), "never the 2.x key").toBeUndefined()
+  })
+
+  it("static mode never writes the cache", () => {
+    const client = new QueryClient()
+    probe({ n: 1 }, true, vi.fn<CallTool>(), "static", { client })
+    expect(client.getQueryData(cacheKey("static"))).toBeUndefined()
+  })
+
+  it("the cached answer wins over the seed it came from once the feed answered anew", () => {
+    const client = new QueryClient()
+    probe({ n: 1 }, true, vi.fn<CallTool>(), "refetched", { client, initialDataMode: "seed" })
+    client.setQueryData(cacheKey("refetched"), { n: 2 })
+    const remounted = probe({ n: 1 }, true, vi.fn<CallTool>(), "refetched", {
+      client,
+      initialDataMode: "seed",
+      initialDataUpdatedAt: () => 99,
+    })
+    expect(remounted.data, "an old payload never rolls the answer back").toEqual({ n: 2 })
+    const delivered = probe({ n: 3 }, true, vi.fn<CallTool>(), "refetched", {
+      client,
+      initialDataMode: "seed",
+    })
+    expect(delivered.data, "a new delivery wins").toEqual({ n: 3 })
+  })
+
+  it("refetch over a seeded entry reads the feed again", async () => {
+    const client = new QueryClient()
+    const callTool = vi.fn<CallTool>(() => Promise.resolve({ structuredContent: { n: 2 } }))
+    const result = probe({ n: 1 }, true, callTool, "seed-refetch", {
+      client,
+      initialDataMode: "seed",
+    })
+    result.refetch()
+    await vi.waitFor(() => {
+      expect(client.getQueryData(cacheKey("seed-refetch"))).toEqual({ n: 2 })
+    })
+    expect(callTool).toHaveBeenCalledWith("demo_data", ARGS)
+  })
+})

package/src/hooks/use-view-data.ts

@@ -1,22 +1,74 @@
-import { useToolQuery } from "./use-tool-query.js"
+import { useCallback, useState } from "react"
+import { hashKey, useQueryClient } from "@tanstack/react-query"
+import { seedToolQuery, type UseToolQueryOptions } from "../lib/tool-query.js"
+import { useToolQuery, useToolQueryKey } from "./use-tool-query.js"
 
 export interface ViewDataResult<T> {
   data: T | null
   /** True while self-fetching with no data yet — the first paint of a cockpit cell. */
   loading: boolean
   error: Error | null
+  /**
+   * Fetch `tool` again now: the retry of an error state
+   * (`<ErrorState onRetry={refetch} … />`) or a manual refresh — a new read
+   * even while a failed fetch still waits on its retry backoff. In `"static"`
+   * mode host-pushed data, when present, stays what `data` returns.
+   */
+  refetch: () => void
+  /** Failed attempts of the current fetch (0 once it succeeds). */
+  failureCount: number
+  /**
+   * The current fetch's last failed attempt — set from the first failure on,
+   * while the query still retries (`error` waits for the last retry).
+   */
+  failureReason: Error | null
+  /** A fetch is in flight (the first one or a refetch). */
+  isFetching: boolean
+  /**
+   * `data` is a placeholder (`placeholderData`, e.g. `keepPreviousData`):
+   * the previous args' answer while the current args' fetch runs or failed.
+   */
+  isPlaceholderData: boolean
+}
+
+/**
+ * How {@link useViewData} treats host-pushed `initialData`.
+ *
+ * - `"static"` (default): returned verbatim; the feed query stays off while
+ *   it is present.
+ * - `"seed"`: it becomes the feed query's cached answer, and the query stays
+ *   live (once `ready`): an invalidation after a write, a `refetch` or a
+ *   retry re-reads the feed. A fresh seed is not refetched on mount (it is
+ *   younger than `staleTime`); a payload delivered anew (content not seeded
+ *   for the key before) replaces the cached answer, while a re-rendered or
+ *   remounted old one never rolls a refetched answer back.
+ */
+export type ViewDataMode = "static" | "seed"
+
+/**
+ * Options of {@link useViewData}: TanStack's query options for the feed
+ * (`retry`, `retryDelay`, `staleTime`, `placeholderData` /
+ * `keepPreviousData`, `enabled` as an extra gate next to `ready`, …),
+ * plus how host data seeds it.
+ */
+export type UseViewDataOptions<T> = Omit<UseToolQueryOptions<T>, "initialData" | "select"> & {
+  initialDataMode?: ViewDataMode
 }
 
 /**
  * The seam that lets one widget component serve both modes without a duplicate UI.
  *
  * Standalone (a `*_show_*` widget) the agent's tool result is handed in via
- * `initialData` (from the view's stepData, e.g. through `adaptDataWidget`) and
- * returned verbatim. Embedded in a self-fetching cockpit only scope params are
- * passed, so the component fetches `tool` with `args` under `key` — disabled
- * unless data is absent AND `ready` (i.e. the required id/key is present).
- * Sibling widgets sharing `key` dedupe to a single call, so a composed view of
- * N widgets over one data feed fetches once.
+ * `initialData` (from the view's stepData, e.g. through `adaptDataWidget`).
+ * Embedded in a self-fetching cockpit only scope params are passed, so the
+ * component fetches `tool` with `args` under `key`, gated on `ready` (i.e.
+ * the required id/key is present). Sibling widgets sharing `key` and `args`
+ * dedupe to a single call, so a composed view of N widgets over one data
+ * feed fetches once.
+ *
+ * By default host data is returned verbatim and switches the query off;
+ * `initialDataMode: "seed"` keeps the query live over it instead (see
+ * {@link ViewDataMode}). `options` passes TanStack's query options through.
  */
 export function useViewData<T>(
   initialData: T | null | undefined,
@@ -24,8 +76,77 @@ export function useViewData<T>(
   tool: string,
   args: Record<string, unknown>,
   ready: boolean,
+  options?: UseViewDataOptions<T>,
 ): ViewDataResult<T> {
-  const query = useToolQuery<T>([...key], tool, args, { enabled: !initialData && ready })
-  const data = initialData ?? query.data ?? null
-  return { data, loading: !data && ready && !query.isError, error: query.error ?? null }
+  const { initialDataMode = "static", enabled, ...queryOptions } = options ?? {}
+  const seeding = initialDataMode === "seed"
+  const cacheKey = useStableKey(useToolQueryKey(key, tool, args))
+  useSeed(seeding ? initialData : null, cacheKey, queryOptions.initialDataUpdatedAt)
+
+  const active = ready && enabled !== false
+  const fetches = active && (seeding || !initialData)
+  const query = useToolQuery<T>([...key], tool, args, {
+    ...queryOptions,
+    enabled: typeof enabled === "function" ? (q) => fetches && enabled(q) : fetches,
+  })
+  const data = seeding ? (query.data ?? initialData) : (initialData ?? query.data)
+  const refetch = useFreshRefetch(cacheKey, query.refetch)
+  return {
+    data: data ?? null,
+    // The query's own verdict: a function `enabled` that returns false idles
+    // like `enabled: false`, never an endless skeleton.
+    loading: !data && query.isEnabled && !query.isError,
+    error: query.error,
+    refetch,
+    failureCount: query.failureCount,
+    failureReason: query.failureReason,
+    isFetching: query.isFetching,
+    isPlaceholderData: query.isPlaceholderData,
+  }
+}
+
+/** `key`, kept by content: callers build `key`/`args` anew every render. */
+function useStableKey(key: unknown[]): unknown[] {
+  const id = hashKey(key)
+  const [stable, setStable] = useState({ id, key })
+  if (stable.id !== id) setStable({ id, key })
+  return stable.id === id ? stable.key : key
+}
+
+/**
+ * `"seed"` mode: write the host's payload into the feed's cache entry in the
+ * render phase, before the query's observer reads the cache — what TanStack's
+ * own `initialData` does (see {@link seedToolQuery} for when it wins over a
+ * cached answer). The last processed seed skips the content check while the
+ * same object comes in render after render.
+ */
+function useSeed(
+  seed: unknown,
+  cacheKey: unknown[],
+  updatedAt: number | (() => number | undefined) | undefined,
+): void {
+  const client = useQueryClient()
+  const keyId = hashKey(cacheKey)
+  const [seen, setSeen] = useState<{ seed: unknown; keyId: string } | null>(null)
+  if (seed == null || (seen?.seed === seed && seen.keyId === keyId)) return
+  const at = typeof updatedAt === "function" ? updatedAt() : updatedAt
+  const written = seedToolQuery(client, cacheKey, seed, at)
+  // Only a real change re-renders: an equal new object per render must not loop.
+  if (written || seen?.keyId !== keyId) setSeen({ seed, keyId })
+}
+
+/**
+ * A refetch that reads anew at once. TanStack restarts an in-flight fetch only
+ * over data (`cancelRefetch`); a key without data joins the running retry
+ * chain and waits out its backoff. So cancel that chain first, then read.
+ */
+function useFreshRefetch(cacheKey: unknown[], refetchQuery: () => Promise<unknown>): () => void {
+  const client = useQueryClient()
+  return useCallback(() => {
+    if (client.getQueryData(cacheKey) !== undefined) {
+      void refetchQuery()
+      return
+    }
+    void client.cancelQueries({ queryKey: cacheKey, exact: true }).then(() => refetchQuery())
+  }, [client, cacheKey, refetchQuery])
 }