diff --git a/.changeset/ag-ui-interrupts.md b/.changeset/ag-ui-interrupts.md
new file mode 100644
index 000000000..af939a21e
--- /dev/null
+++ b/.changeset/ag-ui-interrupts.md
@@ -0,0 +1,24 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-client': minor
+'@tanstack/ai-react': minor
+'@tanstack/ai-preact': minor
+'@tanstack/ai-solid': minor
+'@tanstack/ai-vue': minor
+'@tanstack/ai-svelte': minor
+'@tanstack/ai-angular': minor
+'@tanstack/ai-persistence': patch
+'@tanstack/ai-persistence-drizzle': patch
+'@tanstack/ai-persistence-prisma': patch
+'@tanstack/ai-persistence-cloudflare': patch
+---
+
+Adopt the AG-UI interrupt lifecycle for tool approvals, generic responses, and
+client-tool execution, with typed bound resolvers, atomic batches, structured
+errors, persistence-backed recovery, and exact continuation replay.
+
+This changes native approval and client-tool streams from legacy custom events
+to snapshot-plus-`RUN_FINISHED` interrupt outcomes. Deprecated
+`pendingInterrupts`, `addToolApprovalResponse`, raw `resumeInterrupts`, and
+legacy event readers remain as limited compatibility surfaces for migration;
+`addToolResult` remains supported.
diff --git a/docs/architecture/approval-flow-processing.md b/docs/architecture/approval-flow-processing.md
index 7838c9b14..58be2f7d4 100644
--- a/docs/architecture/approval-flow-processing.md
+++ b/docs/architecture/approval-flow-processing.md
@@ -16,7 +16,7 @@ Tool approval is an interrupt-and-resume protocol. A run that needs user input
 ends with one canonical event:
 
 ```ts
-{
+const interruptTerminal = {
   type: 'RUN_FINISHED',
   runId: 'run-1',
   threadId: 'thread-1',
@@ -26,17 +26,29 @@ ends with one canonical event:
     interrupts: [
       {
         id: 'approval-1',
-        reason: 'approval_required',
-        metadata: { kind: 'approval' },
+        reason: 'tool_call',
+        toolCallId: 'call-1',
+        responseSchema: {
+          oneOf: [
+            { type: 'object', properties: { approved: { const: true } } },
+            { type: 'object', properties: { approved: { const: false } } },
+          ],
+        },
       },
     ],
   },
 }
 ```
 
-The canonical event stream is the only approval event stream. Server state
-persistence stores the interrupt record; SSE delivery durability separately
-assigns opaque resume offsets to delivered events.
+The canonical event stream is the only native approval event stream. It works
+ephemerally without persistence. When server state persistence is configured,
+it stores the complete descriptor/binding batch before the terminal is exposed;
+SSE delivery durability separately assigns opaque resume offsets to delivered
+events. Native paths do not emit `approval-requested` or
+`tool-input-available` custom events.
+
+See [Interrupts](../interrupts/overview) for the public server/client guide and
+[Migrate to AG-UI interrupts](../interrupts/migration) for deprecated readers.
 
 ## Responsibilities
 
@@ -44,27 +56,65 @@ assigns opaque resume offsets to delivered events.
 | --- | --- |
 | Tool definition | Declares `needsApproval: true` for a sensitive operation. |
 | Chat engine | Stops before tool execution and emits the interrupt outcome. |
-| Chat persistence middleware | Creates pending interrupt records, marks the run interrupted, and snapshots messages. |
-| Chat client | Exposes `pendingInterrupts`, preserves `resumeState`, and sends typed resume entries. |
-| Application UI | Explains the operation and resolves or cancels each interrupt. |
+| Chat persistence middleware | Optionally opens the descriptor/binding batch atomically, marks the run interrupted, and snapshots authoritative messages. |
+| Chat client | Binds descriptors to typed methods, stages drafts, and submits one exact resume batch. |
+| Application UI | Explains the operation and uses `resolveInterrupt`, `cancel`, or root batch controls. |
 | Delivery adapter | Optionally replays SSE events by opaque adapter-owned offsets. |
 
+## Descriptor to continuation pipeline
+
+The base invariant is **descriptor → validate all → continuation → history**.
+Durable mode inserts **open batch → compare-and-swap → receipt** around that
+flow:
+
+1. The engine builds public descriptors and bindings. Output includes
+   `MESSAGES_SNAPSHOT`, optional `STATE_SNAPSHOT`, and the interrupt
+   `RUN_FINISHED` terminal. When persistence is configured, it first opens the
+   entire batch atomically and assigns its generation.
+2. The client binds only descriptors whose reason, tool identity, call ID,
+   schema hashes, interrupted run, and generation match its tool registry.
+   Anything untrusted degrades to `generic` rather than gaining a typed tool
+   resolver.
+3. Item methods validate and stage local drafts. The submit boundary contains
+   every pending interrupt ID exactly once.
+4. The client submits a fresh run with the full current message history, the
+   interrupted `parentRunId`, and the complete resume batch.
+5. The server validates **all** payloads, edited inputs, outputs, hashes, and
+   correlation before executing anything. Ephemeral mode reconstructs the
+   expected batch from client-provided history and current tool definitions.
+   Durable mode instead uses stored authoritative state and also validates
+   expiry and generation.
+6. Durable mode uses one transaction to compare the current interrupted run and
+   generation, store the canonical resolution fingerprint, and record the
+   continuation receipt. Ephemeral mode proceeds directly after validation.
+7. Resumed tool calls emit results only; they do not replay synthetic tool-call
+   start/argument events. Successful history belongs to the continuation run.
+
+With persistence, an exact retry returns the recorded continuation and a stale
+or different submission returns authoritative recovery state. Ephemeral mode
+does not provide replay, exactly-once, restart, or cross-instance guarantees;
+its message history is validated but remains client-provided input.
+
 ## Server setup
 
-Define the tool and add state persistence before handling requests:
+Define the tool normally. The following route opts into state persistence for
+durable recovery and concurrency guarantees; omit the persistence imports,
+store, and middleware for the zero-configuration ephemeral flow:
 
 ```ts
 // tools.ts
 import { toolDefinition } from '@tanstack/ai'
 import { z } from 'zod'
 
-export const deleteProject = toolDefinition({
+export const deleteProjectDefinition = toolDefinition({
   name: 'delete_project',
   description: 'Delete a project permanently',
   inputSchema: z.object({ projectId: z.string() }),
   outputSchema: z.object({ deleted: z.boolean() }),
   needsApproval: true,
-}).server(async ({ projectId }) => {
+})
+
+export const deleteProject = deleteProjectDefinition.server(async ({ projectId }) => {
   await deleteProjectFromDatabase(projectId)
   return { deleted: true }
 })
@@ -96,6 +146,7 @@ export async function POST(request: Request) {
     messages: params.messages,
     threadId: params.threadId,
     runId: params.runId,
+    parentRunId: params.parentRunId,
     ...(params.resume ? { resume: params.resume } : {}),
     tools: [deleteProject],
     middleware: [withChatPersistence(persistence)],
@@ -105,10 +156,11 @@ export async function POST(request: Request) {
 }
 ```
 
-There is no feature flag. Middleware behavior follows the stores present on the
-`AIPersistence` object. `interrupts` requires `runs`; invalid store
-combinations fail at compile time when statically known and at runtime for
-untyped JavaScript.
+Persistence is not required to emit or resolve interrupts. When middleware is
+present, behavior follows the stores on the `AIPersistence` object.
+`interrupts` requires `runs` within that optional durable configuration;
+invalid store combinations fail at compile time when statically known and at
+runtime for untyped JavaScript.
 
 ## Client state machine
 
@@ -117,60 +169,52 @@ A single approval follows this sequence:
 1. The model emits a tool call.
 2. The client tool-call part reaches `approval-requested`.
 3. The run ends with `RUN_FINISHED.outcome.type === 'interrupt'`.
-4. `useChat` exposes the descriptor in `pendingInterrupts` and retains
-   `{ threadId, runId }` in `resumeState`.
-5. The UI calls `resumeInterrupts(...)` with a resolution for every pending
-   interrupt.
-6. The next request carries those values in `RunAgentInput.resume`.
-7. Persistence validates and resolves the stored records before the engine
-   continues the tool call.
+4. `useChat` exposes a bound item in `interrupts`.
+5. The UI calls `resolveInterrupt(...)` or `cancel()`; a singleton
+   submits immediately, while a multi-item batch waits for every valid draft.
+6. The next request carries a fresh `runId`, the interrupted `parentRunId`, and
+   the exact AG-UI `resume` array.
+7. The server validates the full set before the engine continues the tool call.
+   With persistence, it also commits the set atomically against authoritative
+   state.
 
 Normal input is rejected at step 4. This prevents a second branch from being
 created while the existing run still waits for a decision.
 
-## Real React approval UI
+## React approval UI
 
-Use the values returned by `useChat`. Rendering the actual
-`pendingInterrupts` array keeps ids and types connected to the hook that owns
-the run.
+Use the bound values returned by `useChat`. Rendering `interrupts` keeps IDs,
+tool types, drafts, and errors connected to the hook that owns the run.
 
-```tsx
+```tsx group=approval-ui
+import type { ItemInterruptError } from '@tanstack/ai'
 import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { deleteProjectDefinition } from './tools'
 
 export function ApprovalQueue() {
   const chat = useChat({
     id: 'project-chat',
     threadId: 'project-thread',
     connection: fetchServerSentEvents('/api/chat'),
+    tools: [deleteProjectDefinition] as const,
   })
 
   return (
     <section>
-      {chat.pendingInterrupts.map((interrupt) => (
+      {chat.interrupts.map((interrupt) => (
         <article key={interrupt.id}>
           <p>Approval required: {interrupt.reason}</p>
-          <button
-            onClick={() =>
-              void chat.resumeInterrupts([
-                {
-                  interruptId: interrupt.id,
-                  status: 'resolved',
-                  payload: { approved: true },
-                },
-              ])
-            }
-          >
-            Approve
-          </button>
-          <button
-            onClick={() =>
-              void chat.resumeInterrupts([
-                { interruptId: interrupt.id, status: 'cancelled' },
-              ])
-            }
-          >
-            Deny
-          </button>
+          {interrupt.kind === 'tool-approval' ? (
+            <button onClick={() => interrupt.resolveInterrupt(true)}>
+              Approve
+            </button>
+          ) : null}
+          <button onClick={() => interrupt.cancel()}>Cancel</button>
+          {interrupt.errors.map((error: ItemInterruptError) => (
+            <p key={`${error.code}:${error.path?.join('.') ?? ''}`}>
+              {error.message}
+            </p>
+          ))}
         </article>
       ))}
     </section>
@@ -178,38 +222,30 @@ export function ApprovalQueue() {
 }
 ```
 
-For a batch, send one entry per pending interrupt in one call:
-
-```tsx
-import type { RunAgentResumeItem } from '@tanstack/ai/client'
-
-function resolveInterrupt(
-  interruptId: string,
-  approved: boolean,
-): RunAgentResumeItem {
-  return approved
-    ? {
-        interruptId,
-        status: 'resolved',
-        payload: { approved: true },
-      }
-    : { interruptId, status: 'cancelled' }
-}
+For a batch, stage every resolution in one synchronous root callback:
 
+```tsx group=approval-ui
 function ResolveAll({ approved }: { approved: boolean }) {
   const chat = useChat({
     threadId: 'project-thread',
     connection: fetchServerSentEvents('/api/chat'),
+    tools: [deleteProjectDefinition] as const,
   })
 
   return (
     <button
       onClick={() =>
-        void chat.resumeInterrupts(
-          chat.pendingInterrupts.map((interrupt) =>
-            resolveInterrupt(interrupt.id, approved),
-          ),
-        )
+        void chat.resolveInterrupts((interrupt) => {
+          if (interrupt.kind === 'tool-approval') {
+            if (approved) {
+              interrupt.resolveInterrupt(true)
+            } else {
+              interrupt.resolveInterrupt(false)
+            }
+            return
+          }
+          interrupt.cancel()
+        })
       }
     >
       Resolve all
@@ -218,21 +254,25 @@ function ResolveAll({ approved }: { approved: boolean }) {
 }
 ```
 
-## Persistence and concurrency
+## Optional persistence and concurrency
 
-`withChatPersistence` performs these state transitions:
+When configured, `withChatPersistence` performs these state transitions:
 
 | Run boundary | Run status | Other writes |
 | --- | --- | --- |
 | Start | `running` | Load and merge stored messages. |
-| Interrupt outcome | `interrupted` | Create pending interrupts and save messages. |
+| Interrupt outcome | `interrupted` | Atomically open the descriptor/binding batch and save messages before emission. |
+| Accepted resume | `running` continuation | Validate all entries, CAS the generation/current run, store the receipt, and link the new run to its parent. |
 | Successful finish | `completed` | Save messages and usage. |
 | Provider/server error | `failed` | Save the error. |
 | Abort | `interrupted` | Mark the run interrupted. |
 
-When multiple workers can resume the same thread, provide a `locks` store.
-Cloudflare Durable Objects can supply that store while D1 supplies messages,
-runs, and interrupts. See [Cloudflare Persistence](../persistence/cloudflare).
+Within durable mode, the interrupt store's compare-and-swap is required even
+when a `locks` store is present. Locks reduce contention; they do not replace
+idempotent receipts or database conflict detection. Cloudflare Durable Objects
+can supply locks while D1 supplies messages, runs, and interrupts. See
+[Cloudflare Persistence](../persistence/cloudflare) and
+[Custom stores](../persistence/custom-stores).
 
 ## State durability versus delivery durability
 
diff --git a/docs/chat/connection-adapters.md b/docs/chat/connection-adapters.md
index ed7bf9f9b..073246fa0 100644
--- a/docs/chat/connection-adapters.md
+++ b/docs/chat/connection-adapters.md
@@ -195,6 +195,9 @@ declare function callRpc(input: {
 
 const connection: ConnectConnectionAdapter = {
   connect(messages, _data, signal) {
+    if (!signal) {
+      throw new TypeError('An AbortSignal is required.')
+    }
     return callRpc({ messages, signal })
   },
 }
diff --git a/docs/chat/persistence.md b/docs/chat/persistence.md
index dfa146104..511dff624 100644
--- a/docs/chat/persistence.md
+++ b/docs/chat/persistence.md
@@ -18,14 +18,15 @@ keywords:
 `useChat` can persist two browser-side values independently:
 
 - `persistence.client` stores the rendered `UIMessage[]` under the chat `id`.
-- `persistence.server` stores the latest `ChatResumeSnapshot` under the
-  `threadId`. The snapshot contains the run identity and any pending
-  interrupts needed after a reload.
+- `persistence.server` stores the latest `ChatResumeSnapshotV2` under the
+  `threadId`. The snapshot contains run identity, authoritative recovery
+  correlation, and raw JSON-safe interrupt drafts.
 
 This is client hydration, not server state durability. Persist authoritative
 messages, runs, and interrupts with `withChatPersistence(...)`; make an
 in-flight response replayable with SSE delivery durability. See
-[Chat Persistence](../persistence/chat-persistence) for the complete flow.
+[Chat Persistence](../persistence/chat-persistence) for the complete flow and
+[Interrupts](../interrupts/overview) for resolution and recovery semantics.
 
 ## Use IndexedDB for chat messages
 
@@ -121,10 +122,12 @@ const messages = localStoragePersistence<Array<UIMessage>>({
   serialize: serializeJson,
   deserialize(value) {
     const stored: Array<StoredMessage> = JSON.parse(value)
-    return stored.map((message) => ({
-      ...message,
-      ...(message.createdAt
-        ? { createdAt: new Date(message.createdAt) }
+    return stored.map(({ id, role, parts, createdAt }) => ({
+      id,
+      role,
+      parts,
+      ...(createdAt
+        ? { createdAt: new Date(createdAt) }
         : {}),
     }))
   },
@@ -153,57 +156,85 @@ export function PersistentChat() {
 `localStorage` survives browser restarts. `sessionStorage` is scoped to the
 current tab. Both adapters default to the key prefix `tanstack-ai:`.
 
-## Resume pending interrupts after reload
+## Recover interrupts before rebinding drafts
 
-The hook exposes the persisted interrupt state directly. Render
-`pendingInterrupts` and call the returned `resumeInterrupts` function; do not
-manufacture a hook return type outside a component.
+The browser stores raw V2 drafts, not hydrated bound items. It never serializes
+`resolveInterrupt`, validators, configured tools, discriminated `kind`, or
+hydrated error objects. On reload, authoritative server recovery must confirm
+the thread, interrupted run, generation, exact IDs, schema hashes, expiry, and
+commit state before the client rebinds descriptors or restores a draft.
+
+Render `interrupts` and use their bound methods. `pendingInterrupts` and raw
+`resumeInterrupts` remain deprecated compatibility surfaces.
 
 ```tsx
+import { toolDefinition } from '@tanstack/ai'
 import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
 
+const approvalTool = toolDefinition({
+  name: 'sensitive_action',
+  description: 'Perform a sensitive action',
+  needsApproval: true,
+})
+
 export function Interrupts() {
-  const { pendingInterrupts, resumeInterrupts } = useChat({
+  const { interrupts, interruptErrors, retryInterrupts } = useChat({
     threadId: 'thread-1',
     connection: fetchServerSentEvents('/api/chat'),
+    tools: [approvalTool] as const,
   })
 
   return (
     <ul>
-      {pendingInterrupts.map((interrupt) => (
+      {interrupts.map((interrupt) => (
         <li key={interrupt.id}>
           <span>{interrupt.reason}</span>
-          <button
-            onClick={() =>
-              void resumeInterrupts([
-                {
-                  interruptId: interrupt.id,
-                  status: 'resolved',
-                  payload: { approved: true },
-                },
-              ])
-            }
-          >
-            Continue
-          </button>
-          <button
-            onClick={() =>
-              void resumeInterrupts([
-                { interruptId: interrupt.id, status: 'cancelled' },
-              ])
-            }
-          >
-            Cancel
-          </button>
+          {interrupt.kind === 'tool-approval' ? (
+            <button onClick={() => interrupt.resolveInterrupt(true)}>
+              Approve
+            </button>
+          ) : null}
+          <button onClick={() => interrupt.cancel()}>Cancel</button>
         </li>
       ))}
+      {interruptErrors.map((error) => (
+        <li key={`${error.code}:${error.generation}`}>{error.message}</li>
+      ))}
+      <li>
+        <button onClick={() => void retryInterrupts()}>Retry</button>
+      </li>
     </ul>
   )
 }
 ```
 
-The server still validates that every resume entry matches a pending
-interrupt. Normal new input is rejected while interrupts remain unresolved.
+The server still validates every entry and commits the exact batch atomically.
+Normal new input is rejected while interrupts remain unresolved.
+
+Recovery is opt-in. Configure explicit application-owned recovery and winning
+continuation URLs; connection adapters never infer them from the chat URL:
+
+```ts
+import {
+  createInterruptContinuationLoader,
+  createInterruptStateFetcher,
+  fetchServerSentEvents,
+} from '@tanstack/ai-client'
+
+export const connection = fetchServerSentEvents('/api/chat', {
+  interruptStateFetcher: createInterruptStateFetcher(
+    '/api/interrupts/recovery',
+  ),
+  continuationLoader: createInterruptContinuationLoader(
+    '/api/interrupts/continuation',
+  ),
+})
+```
+
+Exact retries use the stored fingerprint and join the winning continuation.
+Stale tabs recover the authoritative generation instead of executing a second
+continuation. See [Migrate to AG-UI interrupts](../interrupts/migration) for V1
+compatibility and rollout steps.
 
 ## SSR and custom adapters
 
diff --git a/docs/config.json b/docs/config.json
index b6427d169..3c5b66e35 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -102,13 +102,13 @@
           "label": "Client Tools",
           "to": "tools/client-tools",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-08"
+          "updatedAt": "2026-07-14"
         },
         {
           "label": "Tool Approval Flow",
           "to": "tools/tool-approval",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-09"
+          "updatedAt": "2026-07-14"
         },
         {
           "label": "Lazy Tool Discovery",
@@ -178,7 +178,43 @@
           "label": "Persistence",
           "to": "chat/persistence",
           "addedAt": "2026-06-02",
-          "updatedAt": "2026-07-10"
+          "updatedAt": "2026-07-14"
+        }
+      ]
+    },
+    {
+      "label": "Interrupts",
+      "children": [
+        {
+          "label": "Overview",
+          "to": "interrupts/overview",
+          "addedAt": "2026-07-16"
+        },
+        {
+          "label": "Tool Approval",
+          "to": "interrupts/tool-approval",
+          "addedAt": "2026-07-16"
+        },
+        {
+          "label": "Multiple Interrupts",
+          "to": "interrupts/multiple",
+          "addedAt": "2026-07-16"
+        },
+        {
+          "label": "Generic Interrupts",
+          "to": "interrupts/generic",
+          "addedAt": "2026-07-16"
+        },
+        {
+          "label": "Persistence & Recovery",
+          "to": "interrupts/persistence",
+          "addedAt": "2026-07-16"
+        },
+        {
+          "label": "Migration",
+          "to": "interrupts/migration",
+          "addedAt": "2026-07-14",
+          "updatedAt": "2026-07-16"
         }
       ]
     },
@@ -417,7 +453,7 @@
           "label": "Delivery Durability",
           "to": "persistence/delivery-durability",
           "addedAt": "2026-07-09",
-          "updatedAt": "2026-07-10"
+          "updatedAt": "2026-07-14"
         },
         {
           "label": "Persistence Controls",
@@ -483,7 +519,7 @@
           "label": "Custom Stores",
           "to": "persistence/custom-stores",
           "addedAt": "2026-07-03",
-          "updatedAt": "2026-07-10"
+          "updatedAt": "2026-07-14"
         },
         {
           "label": "Persistence Internals",
@@ -536,6 +572,12 @@
           "label": "Typed Pre-Configured Options",
           "to": "advanced/typed-options",
           "addedAt": "2026-05-25"
+        },
+        {
+          "label": "Approval Flow Processing",
+          "to": "architecture/approval-flow-processing",
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-07-15"
         }
       ]
     },
@@ -901,7 +943,8 @@
         {
           "label": "toolDefinition",
           "to": "reference/functions/toolDefinition",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-07-14"
         },
         {
           "label": "uiMessageToModelMessages",
diff --git a/docs/interrupts/generic.md b/docs/interrupts/generic.md
new file mode 100644
index 000000000..4989d0381
--- /dev/null
+++ b/docs/interrupts/generic.md
@@ -0,0 +1,104 @@
+---
+title: Generic Interrupts
+id: interrupts-generic
+order: 4
+description: "Resolve a schema-driven application pause by validating the wire responseSchema at runtime before submitting."
+keywords:
+  - tanstack ai
+  - generic interrupt
+  - responseSchema
+  - fromJSONSchema
+  - resolveInterrupt
+---
+
+# Generic Interrupts
+
+A generic interrupt is any application pause that isn't tied to a tool. It may
+carry a Draft 2020-12 `responseSchema`. Because that schema arrives over the
+wire, its payload is `unknown` at compile time — so you validate it at runtime
+before resolving. You have a schema-bearing `generic` item; you want a form that
+only submits valid input.
+
+## Render a validating form
+
+Convert the received schema to a validator with `z.fromJSONSchema`, parse the
+editor value as `unknown`, and resolve only on success:
+
+```tsx
+// app/generic-interrupt.tsx
+import { useState } from 'react'
+import type { GenericAGUIInterrupt } from '@tanstack/ai-client'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { z } from 'zod'
+
+// A generic item owns its own editor state, so give each one its own component.
+function GenericInterruptForm({
+  interrupt,
+}: {
+  interrupt: GenericAGUIInterrupt
+}) {
+  const [value, setValue] = useState('')
+  const [errors, setErrors] = useState<ReadonlyArray<string>>([])
+
+  const submit = () => {
+    if (!interrupt.responseSchema) {
+      setErrors(['This interrupt has no response schema.'])
+      return
+    }
+    let candidate: unknown
+    try {
+      candidate = JSON.parse(value)
+    } catch {
+      setErrors(['Enter valid JSON.'])
+      return
+    }
+    const result = z.fromJSONSchema(interrupt.responseSchema).safeParse(candidate)
+    if (!result.success) {
+      setErrors(result.error.issues.map((issue) => issue.message))
+      return
+    }
+    interrupt.resolveInterrupt(result.data)
+    setErrors([])
+  }
+
+  return (
+    <article>
+      <p>{interrupt.message ?? interrupt.reason}</p>
+      <textarea value={value} onChange={(event) => setValue(event.target.value)} />
+      <button disabled={!interrupt.canResolve} onClick={submit}>
+        Submit
+      </button>
+      {errors.map((message) => (
+        <p key={message}>{message}</p>
+      ))}
+    </article>
+  )
+}
+
+export function GenericInterrupts() {
+  const { interrupts } = useChat({
+    threadId: 'workflow-7',
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+
+  return (
+    <>
+      {interrupts.map((interrupt) =>
+        interrupt.kind === 'generic' ? (
+          <GenericInterruptForm key={interrupt.id} interrupt={interrupt} />
+        ) : null,
+      )}
+    </>
+  )
+}
+```
+
+The conversion gives you a runtime validator, not a trustworthy static type.
+TanStack AI still runs canonical Draft 2020-12 validation in the client, and
+server validation stays authoritative — an invalid or unsupported wire schema
+surfaces an `invalid-response-schema` error instead of slipping through.
+
+Applications that emit generic descriptors must send JSON-compatible Draft
+2020-12 schemas and validate the resume batch server-side. Prefer a shared
+`approvalSchema` for tool approvals instead — it adds compile-time branch
+inference on top of runtime validation. See [Tool Approval](./tool-approval).
diff --git a/docs/interrupts/migration.md b/docs/interrupts/migration.md
new file mode 100644
index 000000000..c7bba9e42
--- /dev/null
+++ b/docs/interrupts/migration.md
@@ -0,0 +1,175 @@
+---
+title: Migration
+id: interrupts-migration
+order: 6
+description: "Migrate approval and resume code from legacy custom events and raw resume APIs to typed, atomic AG-UI interrupts."
+keywords:
+  - tanstack ai migration
+  - ag-ui interrupts
+  - addToolApprovalResponse
+  - pendingInterrupts
+  - resumeInterrupts
+---
+
+# Migration
+
+TanStack AI now models approvals, generic pauses, and client-tool execution as
+AG-UI interrupt descriptors. Native runs end with
+`RUN_FINISHED.outcome.type === 'interrupt'`, and the continuation is a new run
+whose `parentRunId` is the interrupted run.
+
+There's no codemod — migrate the server lifecycle, client rendering, and (if
+used) persistence schema together. Legacy readers stay temporarily for old
+streams but can't provide the full native contract. Start from
+[Overview](./overview).
+
+## API mapping
+
+| Deprecated / legacy | Current |
+| --- | --- |
+| `pendingInterrupts` | `interrupts` (`pendingInterrupts` is a deprecated alias of the same array) |
+| `ChatClient.getPendingInterrupts()` | `ChatClient.getInterrupts()` |
+| `addToolApprovalResponse({ id, approved })` | Find the bound `tool-approval` item, call `interrupt.resolveInterrupt(approved)` |
+| Raw `resumeInterrupts(entries, state)` | Bound item methods or root `resolveInterrupts(...)`; reserve `resumeInterruptsUnsafe` for validated recovery tooling |
+| `approval-requested` custom event | `RUN_FINISHED` interrupt descriptor, reason `tool_call` |
+| `tool-input-available` custom event | `RUN_FINISHED` interrupt descriptor, reason `tanstack:client_tool_execution` |
+| Boolean denial treated as cancellation | `resolveInterrupt(false)` for denial; `cancel()` for payloadless cancellation |
+
+`addToolResult` is **not** removed — it still handles client-tool results and
+delegates to a matching native item. `needsApproval` remains the tool-definition
+switch for approvals.
+
+## Single approval
+
+```ts ignore
+// Before
+await addToolApprovalResponse({ id: approval.id, approved: true })
+
+// After
+const interrupt = interrupts.find(
+  (item) => item.kind === 'tool-approval' && item.toolName === 'transfer',
+)
+if (interrupt?.kind === 'tool-approval' && interrupt.toolName === 'transfer') {
+  interrupt.resolveInterrupt(true)
+}
+```
+
+A valid singleton submits automatically. For the full render/resolve component
+see [Tool Approval](./tool-approval).
+
+## Branch payloads and edits
+
+Legacy boolean approvals couldn't carry typed data. Add `approvalSchema` and
+resolve the selected branch with data under `payload`:
+
+```ts ignore
+interrupt.resolveInterrupt(true, {
+  editedArgs: { amount: 12, recipient: 'Ada' }, // optional, approval-only, full replacement
+  payload: { note: 'Reviewed' },
+})
+interrupt.resolveInterrupt(false, { payload: { reason: 'Policy limit' } })
+```
+
+Rejection never accepts edits; top-level custom fields are invalid. A single
+`approvalSchema` (not `{ approve, reject }`) applies to the selected decision;
+with no schema the boolean shorthand stays valid.
+
+## Denial vs cancellation
+
+`resolveInterrupt(false, ...)` continues the model with an explicit rejected
+decision. `cancel()` emits AG-UI `status: 'cancelled'` and never validates or
+selects the reject branch. Deprecated `addToolApprovalResponse({ approved: false })`
+maps to denial, not cancellation.
+
+## Batches
+
+Native batches are all-or-nothing — replace approval-ID loops with staged items
+(the last valid item auto-submits) or one synchronous root callback:
+
+```ts ignore
+await resolveInterrupts((interrupt) => {
+  if (interrupt.kind === 'tool-approval') {
+    interrupt.resolveInterrupt(true, { payload: { note: 'Batch review' } })
+    return
+  }
+  interrupt.cancel()
+})
+```
+
+`resolveInterrupts(true|false)` is shorthand only for all-approval batches with
+no payload/edits. Use `cancelInterrupts()` for payloadless all-items cancel,
+`clearResolution()` to drop one draft, `retryInterrupts()` only when every item
+is still validly staged and the root error is retryable. See
+[Multiple Interrupts](./multiple).
+
+## Generic responses
+
+Don't derive a static type from a received `responseSchema` — parse as
+`unknown`, convert with `z.fromJSONSchema`, then resolve the validated value.
+Full form example in [Generic Interrupts](./generic).
+
+## Server events and persistence
+
+A native server emits, in order: `MESSAGES_SNAPSHOT` → optional
+`STATE_SNAPSHOT` → `RUN_FINISHED` with a nonempty interrupt outcome.
+Continuations use a fresh `runId`, the same `threadId`, and the interrupted run
+as `parentRunId`, with every pending ID present exactly once.
+
+Persistence is optional. Without it, the batch is reconstructed and validated
+from the submitted history (client-provided input — no authoritative recovery,
+exactly-once, replay protection, restart recovery, or CAS). With it, stored
+schema hashes, expiry, and generation are validated before one compare-and-swap
+commit, and exact retries attach to the winning continuation. Upgrade your
+persistence schema (batch/binding/generation/fingerprint/continuation/tombstone
+storage and run correlation) before deploying — see
+[Persistence & Recovery](./persistence),
+[Persistence migrations](../persistence/migrations), and
+[Custom stores](../persistence/custom-stores).
+
+## Explicit recovery
+
+Browser persistence writes a V2 envelope of raw JSON-safe drafts only; after
+reload the client fetches authoritative recovery before rebinding descriptors.
+Configure application-owned URLs — none is inferred from `/api/chat`:
+
+```ts
+import {
+  createInterruptContinuationLoader,
+  createInterruptStateFetcher,
+  fetchServerSentEvents,
+} from '@tanstack/ai-client'
+
+const connection = fetchServerSentEvents('/api/chat', {
+  interruptStateFetcher: createInterruptStateFetcher('/api/interrupts/recovery'),
+  continuationLoader: createInterruptContinuationLoader(
+    '/api/interrupts/continuation',
+  ),
+})
+```
+
+`resumeInterruptsUnsafe` is only for low-level recovery integrations with
+validated raw resume entries — not the normal target for approval UI.
+
+## Legacy limits
+
+Deprecated readers recognize well-formed historical `approval-requested` and
+`tool-input-available` events and convert a fully-covered legacy batch into one
+cloned-history follow-up. They do **not** support edited arguments, custom
+approval payloads, generic responses, payloadless cancellation, expiry/
+schema-hash reconciliation, generation conflicts, or native recovery — those
+fail with `legacy-unsupported`. Native and legacy items can't mix in one batch;
+a failed legacy transport keeps staged decisions and reports `legacy-submit-failed`.
+
+## Checklist
+
+1. Deploy persistence schema changes for every configured backend.
+2. Add `withChatPersistence(...)` to interrupt-producing routes.
+3. Replace native custom-event writers with the interrupt terminal.
+4. Render bound `interrupts` instead of `pendingInterrupts`.
+5. Replace boolean approval helpers with `resolveInterrupt` + explicit
+   denial/cancellation.
+6. Replace approval loops with atomic batch staging or root `resolveInterrupts`.
+7. Add explicit recovery/continuation endpoints before enabling V2 draft restore.
+8. Keep `addToolResult` for client-tool results where useful.
+9. Test reloads, exact retries, two-tab conflicts, expired items, and failed
+   transport recovery before removing legacy support.
diff --git a/docs/interrupts/multiple.md b/docs/interrupts/multiple.md
new file mode 100644
index 000000000..acf393190
--- /dev/null
+++ b/docs/interrupts/multiple.md
@@ -0,0 +1,119 @@
+---
+title: Multiple Interrupts
+id: interrupts-multiple
+order: 3
+description: "Render a queue of pending interrupts and resolve them item-by-item or as one atomic batch."
+keywords:
+  - tanstack ai
+  - ag-ui interrupts
+  - resolveInterrupts
+  - batch approval
+  - cancelInterrupts
+---
+
+# Multiple Interrupts
+
+A single run can pause on several interrupts at once. You have a list of pending
+decisions; you want to render each one and submit them together.
+
+## How a batch submits
+
+Item methods (`resolveInterrupt`, `cancel`, `clearResolution`) return `void` —
+they stage local state. Each staged item is held until the batch is complete;
+the **last valid item auto-submits the whole batch**, and the server accepts all
+resolutions atomically or none. There is no per-item network call.
+
+## Render the queue
+
+Map over `interrupts` and switch on `kind`. Each item carries `canResolve` and
+its own `errors`:
+
+```tsx
+// app/interrupt-queue.tsx
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { transferTool } from '../tools/transfer'
+
+export function InterruptQueue() {
+  const { interrupts, resolveInterrupts, cancelInterrupts, resuming } = useChat({
+    threadId: 'account-42',
+    connection: fetchServerSentEvents('/api/chat'),
+    tools: [transferTool] as const,
+  })
+
+  if (interrupts.length === 0) return null
+
+  return (
+    <section>
+      <p>{interrupts.length} decision(s) needed</p>
+
+      {interrupts.map((interrupt) => {
+        if (
+          interrupt.kind === 'tool-approval' &&
+          interrupt.toolName === 'transfer'
+        ) {
+          return (
+            <article key={interrupt.id}>
+              <p>
+                {interrupt.originalArgs.amount} → {interrupt.originalArgs.recipient}
+              </p>
+              <button
+                disabled={!interrupt.canResolve || resuming}
+                onClick={() =>
+                  interrupt.resolveInterrupt(true, { payload: { note: 'ok' } })
+                }
+              >
+                Approve
+              </button>
+              <button
+                disabled={!interrupt.canResolve || resuming}
+                onClick={() =>
+                  interrupt.resolveInterrupt(false, { payload: { reason: 'no' } })
+                }
+              >
+                Reject
+              </button>
+            </article>
+          )
+        }
+        return <article key={interrupt.id}>Unsupported: {interrupt.kind}</article>
+      })}
+
+      <button onClick={() => void cancelInterrupts()}>Cancel all</button>
+    </section>
+  )
+}
+```
+
+## Resolve the whole batch in one transaction
+
+`resolveInterrupts(callback)` runs your callback against every item inside one
+synchronous transaction. It must resolve or cancel each item and cannot be
+async — if it throws or leaves an item unresolved, nothing submits:
+
+```ts ignore
+await resolveInterrupts((interrupt) => {
+  if (interrupt.kind === 'tool-approval') {
+    interrupt.resolveInterrupt(true, { payload: { note: 'Batch review' } })
+    return
+  }
+  interrupt.cancel()
+})
+```
+
+The boolean shorthand `resolveInterrupts(true)` / `resolveInterrupts(false)` is
+valid **only** when every item is a tool approval whose branch needs no payload
+or edits. It's rejected for generic items, client-tool outputs, mixed batches,
+or required branch payloads. `cancelInterrupts()` is the payloadless all-items
+cancel.
+
+## Errors and retry
+
+Each item exposes `errors` (payload, edited-args, output, expiry, binding).
+Root `interruptErrors` reports batch, transport, persistence, stale-generation,
+conflict, and recovery failures. `canResolve` is `false` when an item is
+expired, submitting, or quarantined for recovery.
+
+A failed candidate doesn't erase the last valid staged response — fix the form
+and call `resolveInterrupt` again, `clearResolution()` to start that item over,
+or `retryInterrupts()` after a *retryable* submission failure. Stale and
+conflict errors are non-retryable and need [authoritative recovery](./persistence).
diff --git a/docs/interrupts/overview.md b/docs/interrupts/overview.md
new file mode 100644
index 000000000..31c3b9bbf
--- /dev/null
+++ b/docs/interrupts/overview.md
@@ -0,0 +1,70 @@
+---
+title: Overview
+id: interrupts-overview
+order: 1
+description: "Pause an agent run for a decision, then resume it — tool approvals and generic application pauses over the AG-UI interrupt lifecycle."
+keywords:
+  - tanstack ai
+  - ag-ui interrupts
+  - human in the loop
+  - tool approval
+  - resolveInterrupt
+---
+
+# Interrupts
+
+An interrupt pauses a run so an application or a person can supply a decision
+before the agent continues. TanStack AI binds each AG-UI interrupt to typed
+methods that validate, stage, and atomically submit its resolution.
+
+## Lifecycle
+
+1. The server snapshots messages (and optional state).
+2. It emits `RUN_FINISHED` with `outcome.type === 'interrupt'` and one or more descriptors.
+3. The client exposes bound items as `interrupts`.
+4. Your app resolves or cancels every item.
+5. The client starts a continuation run — new `runId`, same `threadId`,
+   `parentRunId` set to the interrupted run — carrying the AG-UI `resume` array
+   and the current message history.
+
+This works **without persistence**. In the default ephemeral mode the server
+reconstructs and validates the expected batch from the submitted history and its
+current tool definitions. Persistence is an optional durability layer — see
+[Persistence & Recovery](./persistence).
+
+## Kinds you resolve
+
+The bound `interrupts` array holds the pauses your app resolves:
+
+| `kind` | Meaning | Guide |
+| --- | --- | --- |
+| `tool-approval` | Approve or reject a tool call, optionally editing its args | [Tool Approval](./tool-approval) |
+| `generic` | Any application pause with a wire `responseSchema` | [Generic Interrupts](./generic) |
+
+**Client tools are not on this list.** Running a tool in the browser and
+returning its result is not something you resolve by hand — a tool with a
+`.client()` implementation runs automatically and reports its own result. See
+[Client Tools](../tools/client-tools). Approval is a separate axis: add
+`needsApproval: true` to any tool (server or client) and it pauses on a
+`tool-approval` interrupt first; a client tool then runs automatically once
+approved.
+
+| Tool | What you handle |
+| --- | --- |
+| Server tool | nothing (runs on the server); a `tool-approval` interrupt first if `needsApproval` |
+| Client tool (`.client()` impl) | nothing (runs automatically); a `tool-approval` interrupt first if `needsApproval` |
+
+## Where to go next
+
+| You want to… | Page |
+| --- | --- |
+| Approve/reject a single tool call and render it | [Tool Approval](./tool-approval) |
+| Render and resolve several pending interrupts at once | [Multiple Interrupts](./multiple) |
+| Validate a schema-driven application pause | [Generic Interrupts](./generic) |
+| Run a tool in the browser and return its result | [Client Tools](../tools/client-tools) |
+| Survive reloads, retries, and multi-tab conflicts | [Persistence & Recovery](./persistence) |
+| Move off legacy `approval-requested` events | [Migration](./migration) |
+
+> This replaced the native `approval-requested` and `tool-input-available`
+> custom events. Native servers no longer emit them; deprecated readers remain
+> for old streams during [migration](./migration).
diff --git a/docs/interrupts/persistence.md b/docs/interrupts/persistence.md
new file mode 100644
index 000000000..2160b837b
--- /dev/null
+++ b/docs/interrupts/persistence.md
@@ -0,0 +1,79 @@
+---
+title: Persistence & Recovery
+id: interrupts-persistence
+order: 5
+description: "Choose ephemeral resume or durable persistence for interrupts, and wire explicit recovery and continuation endpoints."
+keywords:
+  - tanstack ai
+  - interrupt persistence
+  - withChatPersistence
+  - interrupt recovery
+  - continuation loader
+---
+
+# Persistence & Recovery
+
+Interrupts resume without any database by default. Add persistence when
+approvals guard operations that need durable audit and concurrency guarantees.
+
+## Ephemeral vs durable
+
+**Ephemeral (default):** interrupts are request-scoped. The client resends the
+full message history; the server validates it against the current tool
+definitions and response schemas. It **cannot** prove the client didn't drop or
+rewrite earlier history, and gives you no authoritative reload recovery,
+exactly-once execution, replay protection, restart recovery, or cross-tab/
+cross-instance coordination. Use it when those guarantees aren't required.
+
+**Durable (`withChatPersistence`):** server state and browser drafts have
+different authority:
+
+- The store atomically opens the descriptor/binding batch and commits the exact
+  resolution set with compare-and-swap semantics.
+- The browser's `ChatResumeSnapshotV2` holds raw JSON-safe drafts only — never
+  bound methods, validators, tool implementations, or hydrated errors.
+- On reload, authoritative recovery runs **before** descriptors are rebound and
+  a draft is restored.
+- Submission fingerprints make an exact retry idempotent — the same accepted
+  batch replays or joins the winning continuation instead of re-executing tools.
+- A second tab with a stale generation loses the compare-and-swap and adopts
+  recovery state; it never starts a second execution.
+
+Add `withChatPersistence(persistence)` to the route's `middleware` array after
+configuring a store. `migrate: true` is for local SQLite dev — generate, review,
+and deploy your backend's native migration for production. See
+[Persistence migrations](../persistence/migrations).
+
+## Wire recovery endpoints
+
+Recovery is opt-in and explicit — TanStack AI never infers a recovery or
+continuation URL from the chat URL. Configure application-owned endpoints:
+
+```ts
+import {
+  createInterruptContinuationLoader,
+  createInterruptStateFetcher,
+  fetchServerSentEvents,
+} from '@tanstack/ai-client'
+
+const connection = fetchServerSentEvents('/api/chat', {
+  interruptStateFetcher: createInterruptStateFetcher('/api/interrupts/recovery'),
+  continuationLoader: createInterruptContinuationLoader(
+    '/api/interrupts/continuation',
+  ),
+})
+```
+
+The recovery endpoint must authenticate the caller, authorize the requested
+thread, and return the store's authoritative recovery DTO. The continuation
+endpoint is a read-only GET of the winning run. See
+[Chat persistence](../persistence/chat-persistence),
+[Custom stores](../persistence/custom-stores), and
+[Delivery durability](../persistence/delivery-durability).
+
+`resumeInterruptsUnsafe` remains a low-level escape hatch for already-validated
+raw AG-UI resume entries and recovery tooling — not a replacement for normal
+approval UI. Prefer [bound item methods](./multiple).
+
+> Deeper internals — validate-all, CAS, continuation, and replay processing —
+> are in [Approval flow architecture](../architecture/approval-flow-processing).
diff --git a/docs/interrupts/tool-approval.md b/docs/interrupts/tool-approval.md
new file mode 100644
index 000000000..ce6ffe674
--- /dev/null
+++ b/docs/interrupts/tool-approval.md
@@ -0,0 +1,186 @@
+---
+title: Tool Approval
+id: interrupts-tool-approval
+order: 2
+description: "Gate a tool call behind a typed approve/reject decision, then render and resolve that single interrupt in the UI."
+keywords:
+  - tanstack ai
+  - tool approval
+  - needsApproval
+  - approvalSchema
+  - resolveInterrupt
+---
+
+# Tool Approval
+
+You have a tool that shouldn't run until a person says yes. By the end you'll
+have a typed approval interrupt and a component that renders it and resolves the
+decision.
+
+## Define the tool
+
+`needsApproval: true` turns the call into an approval interrupt. An optional
+`approvalSchema` attaches typed data to the decision — one schema for both
+branches, or a `{ approve, reject }` map for different payloads. Share the
+definition so server and client infer the same types:
+
+```ts
+// tools/transfer.ts
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+export const transferTool = toolDefinition({
+  name: 'transfer',
+  description: 'Transfer funds to a recipient',
+  needsApproval: true,
+  inputSchema: z.object({
+    amount: z.number().positive(),
+    recipient: z.string().min(1),
+  }),
+  outputSchema: z.object({ receiptId: z.string() }),
+  approvalSchema: {
+    approve: z.object({ note: z.string().min(1) }),
+    reject: z.object({ reason: z.string().min(1) }),
+  },
+})
+```
+
+## Serve it
+
+The server executes the tool only after the batch is accepted. No persistence is
+required — the client sends the full history, so a stateless route can rebuild
+the interrupted call and validate the batch before running anything.
+
+```ts
+// app/api/chat/route.ts
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { transferTool } from '../../../tools/transfer'
+
+const transfer = transferTool.server(
+  async (input: { amount: number; recipient: string }) => ({
+    receiptId: `${input.recipient}-${input.amount}-${crypto.randomUUID()}`,
+  }),
+)
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    parentRunId: params.parentRunId,
+    ...(params.resume ? { resume: params.resume } : {}),
+    tools: [transfer],
+  })
+  return toServerSentEventsResponse(stream)
+}
+```
+
+## Render and resolve it
+
+Pass the shared definition to `useChat` so `toolName`, `originalArgs`, edits, and
+branch payloads are inferred. Loop the pending `interrupts`, narrow on `kind`,
+and render each `transfer` approval — the same shape scales to a mixed queue
+(see [Multiple Interrupts](./multiple)):
+
+```tsx
+// app/transfer-approval.tsx
+import type { ItemInterruptError } from '@tanstack/ai'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { transferTool } from '../tools/transfer'
+
+export function TransferApprovals() {
+  const { interrupts, resuming } = useChat({
+    threadId: 'account-42',
+    connection: fetchServerSentEvents('/api/chat'),
+    tools: [transferTool] as const,
+  })
+
+  return (
+    <>
+      {interrupts.map((interrupt) => {
+        // Render only the transfer approvals; ignore other kinds/tools here.
+        if (
+          interrupt.kind !== 'tool-approval' ||
+          interrupt.toolName !== 'transfer'
+        ) {
+          return null
+        }
+        return (
+          <article key={interrupt.id}>
+            <p>
+              Transfer {interrupt.originalArgs.amount} to{' '}
+              {interrupt.originalArgs.recipient}?
+            </p>
+            <button
+              disabled={!interrupt.canResolve || resuming}
+              onClick={() =>
+                interrupt.resolveInterrupt(true, { payload: { note: 'Reviewed' } })
+              }
+            >
+              Approve
+            </button>
+            <button
+              disabled={!interrupt.canResolve || resuming}
+              onClick={() =>
+                interrupt.resolveInterrupt(false, {
+                  payload: { reason: 'Too large' },
+                })
+              }
+            >
+              Reject
+            </button>
+            {interrupt.errors.map((error: ItemInterruptError) => (
+              <p key={`${error.code}:${error.path?.join('.') ?? ''}`}>
+                {error.message}
+              </p>
+            ))}
+          </article>
+        )
+      })}
+    </>
+  )
+}
+```
+
+A valid resolution for a single-item batch submits automatically — no extra
+"submit" call.
+
+## Approve, edit, reject
+
+```ts ignore
+// Approve as-is.
+interrupt.resolveInterrupt(true, { payload: { note: 'Reviewed' } })
+
+// Approve with edited arguments — a validated FULL replacement, not a merge.
+interrupt.resolveInterrupt(true, {
+  editedArgs: { amount: 12, recipient: 'Ada' },
+  payload: { note: 'Capped to policy' },
+})
+
+// Reject — the reject branch schema validates its own payload.
+interrupt.resolveInterrupt(false, { payload: { reason: 'Policy limit' } })
+```
+
+Only approval accepts `editedArgs`; rejection never does. Branch data always
+goes under `payload`. Without an `approvalSchema`, the boolean shorthand
+`resolveInterrupt(true)` / `resolveInterrupt(false)` is valid on its own. The
+server re-validates the whole envelope before executing.
+
+## Rejection is not cancellation
+
+`resolveInterrupt(false, ...)` is a *resolved denial*: the continuation receives
+the denial (and any reject payload) so the model can respond to it.
+`cancel()` produces AG-UI `status: 'cancelled'`, carries no payload, and does not
+select the reject branch. Deny when the user answered "no"; cancel when the
+workflow is abandoned without an answer.
+
+> Resolving several approvals together? See [Multiple Interrupts](./multiple).
+> Defining approval on the tool side is covered in
+> [Tool Approval Flow](../tools/tool-approval).
diff --git a/docs/persistence/chat-persistence.md b/docs/persistence/chat-persistence.md
index bffcf6061..865a286bf 100644
--- a/docs/persistence/chat-persistence.md
+++ b/docs/persistence/chat-persistence.md
@@ -155,7 +155,7 @@ handled. This prevents accidental conversation forks.
 To reconnect to an in-flight SSE response, add a `StreamDurability` adapter to
 the response:
 
-```ts
+```ts ignore
 import { durableStream } from '@tanstack/ai-durable-stream'
 
 declare function getDurableStreamsToken(): Promise<string>
diff --git a/docs/persistence/cloudflare.md b/docs/persistence/cloudflare.md
index 02564e7d8..68fa9471a 100644
--- a/docs/persistence/cloudflare.md
+++ b/docs/persistence/cloudflare.md
@@ -66,13 +66,14 @@ export { CloudflareLockDurableObject } from '@tanstack/ai-persistence-cloudflare
 
 ## Create persistence
 
-```ts
+```ts group=cloudflare-persistence
 import { cloudflarePersistence } from '@tanstack/ai-persistence-cloudflare'
+import type { CloudflarePersistenceOptions } from '@tanstack/ai-persistence-cloudflare'
 
 interface Env {
-  AI_STATE: D1Database
-  AI_MEDIA: R2Bucket
-  AI_LOCKS: DurableObjectNamespace
+  AI_STATE: NonNullable<CloudflarePersistenceOptions['d1']>
+  AI_MEDIA: NonNullable<CloudflarePersistenceOptions['r2']>
+  AI_LOCKS: NonNullable<CloudflarePersistenceOptions['durableObjects']>
 }
 
 export function createPersistence(env: Env) {
@@ -96,7 +97,7 @@ serializes owners and uses leases/alarms for recovery.
 
 ## Use it with chat
 
-```ts
+```ts group=cloudflare-persistence
 import {
   chat,
   chatParamsFromRequest,
@@ -157,12 +158,13 @@ for (const migration of d1Migrations) {
 
 Use Cloudflare as the base and replace only application-owned stores:
 
-```ts
+```ts group=cloudflare-persistence
 import { composePersistence } from '@tanstack/ai-persistence'
 import type { InterruptStore, RunStore } from '@tanstack/ai-persistence'
 
 declare const customInterrupts: InterruptStore
 declare const customRuns: RunStore
+declare const env: Env
 
 const persistence = composePersistence(createPersistence(env), {
   overrides: {
diff --git a/docs/persistence/controls.md b/docs/persistence/controls.md
index 201acb625..68f5a79e2 100644
--- a/docs/persistence/controls.md
+++ b/docs/persistence/controls.md
@@ -32,21 +32,22 @@ the complete capability selection mechanism.
 `composePersistence` takes the base backend first and a configuration object
 second:
 
-```ts
+```ts group=persistence-controls
 import {
   composePersistence,
   defineAIPersistence,
 } from '@tanstack/ai-persistence'
 import { cloudflarePersistence } from '@tanstack/ai-persistence-cloudflare'
+import type { CloudflarePersistenceOptions } from '@tanstack/ai-persistence-cloudflare'
 import type {
   InterruptStore,
   RunStore,
 } from '@tanstack/ai-persistence'
 
 declare const env: {
-  AI_STATE: D1Database
-  AI_MEDIA: R2Bucket
-  AI_LOCKS: DurableObjectNamespace
+  AI_STATE: NonNullable<CloudflarePersistenceOptions['d1']>
+  AI_MEDIA: NonNullable<CloudflarePersistenceOptions['r2']>
+  AI_LOCKS: NonNullable<CloudflarePersistenceOptions['durableObjects']>
 }
 declare const interrupts: InterruptStore
 declare const runs: RunStore
@@ -76,7 +77,7 @@ Each override is independent:
 | a store object | Replace that store only. |
 | `false` | Remove that store. |
 
-```ts
+```ts group=persistence-controls
 const withoutGeneratedMedia = composePersistence(base, {
   overrides: {
     artifacts: false,
@@ -101,7 +102,7 @@ Some capabilities require related stores:
 Known-invalid static compositions fail to type-check at the middleware call.
 Runtime validation covers dynamically typed inputs.
 
-```ts
+```ts group=persistence-controls
 import { withGenerationPersistence } from '@tanstack/ai-persistence'
 
 // Valid: both stores remain present.
diff --git a/docs/persistence/custom-stores.md b/docs/persistence/custom-stores.md
index 22889ce0d..500d7a3da 100644
--- a/docs/persistence/custom-stores.md
+++ b/docs/persistence/custom-stores.md
@@ -14,15 +14,17 @@ database.
 ```ts
 import { defineAIPersistence } from '@tanstack/ai-persistence'
 import type {
+  InterruptStore,
   MessageStore,
   RunStore,
 } from '@tanstack/ai-persistence'
 
 declare const messages: MessageStore
 declare const runs: RunStore
+declare const interrupts: InterruptStore
 
 export const persistence = defineAIPersistence({
-  stores: { messages, runs },
+  stores: { messages, runs, interrupts },
 })
 ```
 
@@ -74,22 +76,73 @@ Implement `createOrResume` idempotently. Retries may repeat the same run id.
 
 ### Interrupts
 
+Interrupt persistence is an atomic capability, not a collection of sequential
+`create`, `resolve`, and `cancel` calls. Opening a batch must store all
+descriptors and protected bindings together. Committing a response must compare
+the expected generation and exact ID set, then resolve every item and create
+the continuation receipt in the same transaction.
+
 ```ts
-import type { InterruptRecord } from '@tanstack/ai-persistence'
+import type {
+  CommitInterruptResolutionsInput,
+  InterruptCommitResult,
+  InterruptRecoveryQuery,
+  InterruptRecoveryStateV1,
+  OpenInterruptBatchInput,
+} from '@tanstack/ai'
 
 interface InterruptStore {
-  create(record: Omit<InterruptRecord, 'resolvedAt'>): Promise<void>
-  resolve(interruptId: string, response?: unknown): Promise<void>
-  cancel(interruptId: string): Promise<void>
-  get(interruptId: string): Promise<InterruptRecord | null>
-  list(threadId: string): Promise<Array<InterruptRecord>>
-  listPending(threadId: string): Promise<Array<InterruptRecord>>
-  listByRun(runId: string): Promise<Array<InterruptRecord>>
-  listPendingByRun(runId: string): Promise<Array<InterruptRecord>>
+  openInterruptBatch(input: OpenInterruptBatchInput): Promise<{
+    generation: number
+    descriptors: OpenInterruptBatchInput['descriptors']
+  }>
+  commitInterruptResolutions(
+    input: CommitInterruptResolutionsInput,
+  ): Promise<InterruptCommitResult>
+  getInterruptRecoveryState(
+    input: InterruptRecoveryQuery,
+  ): Promise<InterruptRecoveryStateV1>
 }
 ```
 
+The commit result is the durable receipt:
+
+- `committed` returns the newly accepted `continuationRunId`;
+- `replayed` returns the same winning continuation for an exact idempotent
+  retry;
+- `conflict` returns authoritative recovery state for a stale generation or a
+  different submission.
+
+Compute and compare the canonical submission fingerprint inside the same
+transaction as the current-run/parent-run compare-and-swap. Never rerun tools
+for `replayed`. Do not accept a subset or superset of the opened IDs.
+
 An `interrupts` store requires a `runs` store when used with chat persistence.
+`defineAIPersistence` rejects an adapter that advertises interrupts without the
+atomic methods. See [Interrupts](../interrupts/overview) for client semantics and
+[Delivery durability](./delivery-durability) for exact replay behavior.
+
+### Explicit recovery handler
+
+Expose recovery only on an application-owned route. The handler does not infer
+a URL and must authorize the caller and thread before reading state:
+
+```ts
+// app/api/interrupts/recovery/route.ts
+import { createInterruptRecoveryHandler } from '@tanstack/ai-persistence'
+import { persistence } from '../../../../persistence'
+import { authorizeInterruptRecovery } from '../../../../authorization'
+
+export const POST = createInterruptRecoveryHandler({
+  gateway: persistence.stores.interrupts,
+  authorize: authorizeInterruptRecovery,
+})
+```
+
+Treat the concrete authorization object as application policy: authenticate the
+request, authorize the requested thread, and redact protected bindings or
+responses that the caller must not receive. Configure the matching client URL
+explicitly with `createInterruptStateFetcher`.
 
 ### Metadata
 
@@ -159,7 +212,7 @@ transactions, conditional writes, or stable idempotency keys.
 
 ## Override selected packaged stores
 
-```ts
+```ts ignore
 /// <reference types="@cloudflare/workers-types" />
 
 import { composePersistence } from '@tanstack/ai-persistence'
diff --git a/docs/persistence/delivery-durability.md b/docs/persistence/delivery-durability.md
index 556b1c166..82f2aff61 100644
--- a/docs/persistence/delivery-durability.md
+++ b/docs/persistence/delivery-durability.md
@@ -9,6 +9,12 @@ Delivery durability records an ordered SSE stream so a dropped connection can
 replay chunks without invoking the provider again. It is separate from state
 persistence for messages, runs, interrupts, metadata, and artifacts.
 
+Interrupt submission has a second exact-replay rule. The persistence store
+canonicalizes the complete resolution set into an idempotency fingerprint and
+commits it with the continuation run ID. Repeating that exact set returns the
+same winning continuation; it never executes approved tools twice. A different
+set or stale generation is a conflict and returns authoritative recovery state.
+
 Two adapters ship:
 
 - `memoryStream(request)` stores a process-local log for development and tests.
@@ -115,13 +121,44 @@ declare const runId: string
 const connection = fetchServerSentEvents('/api/chat')
 
 for await (const chunk of connection.joinRun(runId)) {
-  console.log(chunk.type)
+  if ('type' in chunk) {
+    console.log(chunk.type)
+  }
 }
 ```
 
 `joinRun` performs a GET with `offset=-1` and `runId`. The endpoint must accept
 that GET, as shown above.
 
+For interrupt recovery, configure this winning-run loader explicitly with
+`createInterruptContinuationLoader`. TanStack AI never guesses a continuation
+or recovery route from the chat URL. See [Interrupts](../interrupts/overview) for
+the client setup.
+
+## Accepted tombstones and exact replay
+
+After a native batch is accepted, the browser first persists a V2
+`phase: 'accepted'` tombstone containing the winning continuation ID and no
+drafts, then attempts to remove the resume record. If removal fails, reload does
+not show stale pending UI. Authoritative committed recovery confirms the winner
+and retries cleanup.
+
+The layers cooperate without sharing identifiers:
+
+1. Interrupt persistence compares the generation, exact ID set, and canonical
+   resolution fingerprint.
+2. A first valid submission atomically stores the resolutions and winning
+   continuation receipt.
+3. An exact retry returns `replayed` with that continuation ID.
+4. The client joins the winning run through SSE durability or an explicit
+   continuation loader.
+5. SSE delivery resumes from the adapter-owned opaque offset and de-duplicates
+   the replayed prefix.
+
+The fingerprint is not an SSE offset. The accepted tombstone is not the
+authoritative server commit. Keep both state persistence and delivery
+durability when the workflow must survive request retries and connection loss.
+
 ## Offset ownership
 
 `StreamDurability<TOffset>` owns its offset format. Core only passes returned
@@ -172,3 +209,7 @@ Delivery logs replay chunks. They are not the queryable source of truth for
 thread messages, pending interrupts, generation artifacts, or retention
 policies. Add [Chat Persistence](./chat-persistence) or
 [Generation Persistence](./generation-persistence) for that state.
+
+For atomic interrupt store requirements and conflict receipts, see
+[Custom stores](./custom-stores). For the legacy-to-native transition, see
+[Migrate to AG-UI interrupts](../interrupts/migration).
diff --git a/docs/persistence/drizzle.md b/docs/persistence/drizzle.md
index 82128f64a..dd2ddbbf7 100644
--- a/docs/persistence/drizzle.md
+++ b/docs/persistence/drizzle.md
@@ -18,7 +18,7 @@ backend.
 
 ## Node SQLite
 
-```ts
+```ts group=drizzle-node
 import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
 
 export const persistence = sqlitePersistence({
@@ -34,25 +34,30 @@ deployment-time migrations in production.
 ## Bring your own SQLite Drizzle database
 
 ```ts
-import { drizzle } from 'drizzle-orm/d1'
+import type { CloudflarePersistenceOptions } from '@tanstack/ai-persistence-cloudflare'
 import {
   drizzlePersistence,
   schema,
 } from '@tanstack/ai-persistence-drizzle'
+import { drizzle } from 'drizzle-orm/d1'
 
-declare const env: { AI_STATE: D1Database }
+declare const env: {
+  AI_STATE: NonNullable<CloudflarePersistenceOptions['d1']>
+}
 
 const db = drizzle(env.AI_STATE, { schema })
-export const persistence = drizzlePersistence(db)
+export const persistence = drizzlePersistence(db, { interrupts: false })
 ```
 
 The root entry does not import Node built-ins and works with Cloudflare D1 and
 other SQLite-compatible Drizzle drivers. The application owns connection
-lifecycle and migration timing.
+lifecycle and migration timing. The low-level factory requires either an
+atomic `interrupts` transaction executor or `interrupts: false`; use the
+Cloudflare persistence adapter when you need interrupt recovery on D1.
 
 ## Use the middleware
 
-```ts
+```ts group=drizzle-node
 import {
   chat,
   chatParamsFromRequest,
@@ -104,10 +109,10 @@ normal SQLite, D1, or Drizzle deployment workflow.
 
 ## Schema ownership
 
-The exported `schema` contains `messages`, `runs`, `interrupts`, `metadata`,
-`artifacts`, and `blobs`. Artifact rows contain metadata; blob bodies are stored
-in the separate blob table. Application tables may live beside these tables in
-the same database.
+The exported `schema` contains `messages`, `runs`, `interrupts`,
+`interruptBatches`, `metadata`, `artifacts`, and `blobs`. Artifact rows contain
+metadata; blob bodies are stored in the separate blob table. Application tables
+may live beside these tables in the same database.
 
 ## Own the schema
 
@@ -142,8 +147,14 @@ Then pass the schema back so the runtime reads and writes through your copy:
 import { drizzlePersistence } from '@tanstack/ai-persistence-drizzle'
 import { schema } from './tanstack-ai-schema'
 import { db } from './db'
+import type { DrizzleTransactionExecutor } from '@tanstack/ai-persistence-drizzle'
+
+declare const transactionExecutor: DrizzleTransactionExecutor
 
-export const persistence = drizzlePersistence(db, { schema })
+export const persistence = drizzlePersistence(db, {
+  schema,
+  interrupts: transactionExecutor,
+})
 ```
 
 Because the runtime operates on the table objects you pass, the file is truly
diff --git a/docs/persistence/generation-persistence.md b/docs/persistence/generation-persistence.md
index 3f3651ed6..cade7cfb8 100644
--- a/docs/persistence/generation-persistence.md
+++ b/docs/persistence/generation-persistence.md
@@ -13,7 +13,7 @@ Generated bytes never belong in browser resume state.
 
 ## Create the server endpoint
 
-```ts
+```ts group=generation-persistence
 import {
   generateImage,
   generationParamsFromRequest,
@@ -122,7 +122,7 @@ restart or reconnect to provider work.
 Artifact metadata and blob bodies are separate. The default generated blob key
 is `artifacts/<runId>/<artifactId>`.
 
-```ts
+```ts group=generation-persistence
 export async function GET(
   _request: Request,
   context: { params: Promise<{ artifactId: string }> },
@@ -154,7 +154,7 @@ Built-in extraction handles input media, generated image/audio/video output,
 transcription input audio, and structured transcription results. Supply
 `extractArtifacts` to replace the built-in extraction for a run:
 
-```ts
+```ts group=generation-persistence
 const generationPersistence = withGenerationPersistence(persistence, {
   extractArtifacts({ result }) {
     return [
diff --git a/docs/persistence/migrations.md b/docs/persistence/migrations.md
index 9da62c376..8eb63acaf 100644
--- a/docs/persistence/migrations.md
+++ b/docs/persistence/migrations.md
@@ -8,6 +8,18 @@ id: migrations
 Migration ownership depends on the backend. Apply schema changes before
 deploying code that reads or writes the corresponding stores.
 
+AG-UI interrupts add atomic batch state. Every backend must persist the
+descriptor and protected binding set, generation, exact ID set, canonical
+submission fingerprint, committed resolutions, continuation run ID, and
+accepted/commit timestamps. Runs also need current/parent correlation for the
+compare-and-swap that creates a continuation. Add uniqueness for one generation
+of an interrupted run and indexes for pending recovery lookups.
+
+Do not approximate this with sequential interrupt rows. A partial write can
+expose an interrupt that cannot be resumed safely. See
+[Custom stores](./custom-stores) for the atomic capability and
+[Interrupts](../interrupts/overview) for the lifecycle.
+
 ## Drizzle SQLite
 
 The Drizzle package bundles ordered canonical SQLite migrations. Copy them into
@@ -27,6 +39,11 @@ The CLI preserves existing identical files and refuses to overwrite divergent
 files without `--force`. Apply the copied SQL using your normal SQLite,
 Drizzle, or D1 deployment process.
 
+Refresh the manifest to pick up the interrupt batch table/columns, generation
+and pending-recovery indexes, submission fingerprint uniqueness, continuation
+receipt, and parent-run correlation. Review the generated SQL before applying
+it to every SQLite environment.
+
 For local Node development, the `/sqlite` factory can apply the same manifest:
 
 ```ts
@@ -59,6 +76,11 @@ It also exports `d1Migrations` for programmatic tooling. R2 and Durable Object
 locks do not use the D1 table migration set; configure their bindings and
 Durable Object migration tags in Wrangler.
 
+The D1 migration set carries the same atomic interrupt fields and indexes as
+Drizzle SQLite. Apply it before deploying Workers that can emit native
+interrupts. A Durable Object lock can serialize workers, but it does not replace
+the D1 compare-and-swap or accepted receipt.
+
 ## Prisma
 
 Prisma ships a provider-neutral models fragment, then delegates SQL generation
@@ -75,12 +97,33 @@ The copied fragment contains no datasource or generator. Keep those in your
 application schema and commit the native migration Prisma creates for your
 provider.
 
+The updated fragment adds the models and fields needed for atomic interrupt
+batches, bindings, generations, fingerprints, accepted receipts, continuation
+runs, and parent/current-run correlation. The package does **not** ship SQL for
+your provider. Generate and deploy your own Prisma migration before using the
+new package version:
+
+```bash
+pnpm exec tanstack-ai-prisma-models --out prisma/schema
+pnpm prisma migrate dev --name add-ag-ui-interrupts
+pnpm prisma generate
+pnpm prisma migrate deploy
+```
+
+Inspect and commit the migration that Prisma generates. Do not deploy the
+runtime first or rely on `prisma db push` as a production migration.
+
 ## Custom stores
 
 Custom `AIPersistence` adapters own their schema and migrations entirely.
 Maintain compatibility with the public store records and method semantics;
 TanStack AI does not inspect your table layout.
 
+For this upgrade, add one transaction boundary spanning exact-set validation,
+generation compare-and-swap, resolution persistence, continuation receipt, and
+run-parent linkage. Preserve committed fingerprints long enough for exact retry
+replay and recovery after a browser accepted-tombstone cleanup failure.
+
 ## Upgrade discipline
 
 1. Read the package release notes for schema changes.
diff --git a/docs/persistence/overview.md b/docs/persistence/overview.md
index 12d44f98f..57a9acc91 100644
--- a/docs/persistence/overview.md
+++ b/docs/persistence/overview.md
@@ -79,12 +79,13 @@ the second argument:
 import { composePersistence } from '@tanstack/ai-persistence'
 import { cloudflarePersistence } from '@tanstack/ai-persistence-cloudflare'
 import { defineAIPersistence } from '@tanstack/ai-persistence'
+import type { CloudflarePersistenceOptions } from '@tanstack/ai-persistence-cloudflare'
 import type { AIPersistenceStores } from '@tanstack/ai-persistence'
 
 declare const env: {
-  AI_STATE: D1Database
-  AI_MEDIA: R2Bucket
-  AI_LOCKS: DurableObjectNamespace
+  AI_STATE: NonNullable<CloudflarePersistenceOptions['d1']>
+  AI_MEDIA: NonNullable<CloudflarePersistenceOptions['r2']>
+  AI_LOCKS: NonNullable<CloudflarePersistenceOptions['durableObjects']>
 }
 declare const myInterruptStore: NonNullable<
   AIPersistenceStores['interrupts']
diff --git a/docs/persistence/prisma.md b/docs/persistence/prisma.md
index a26133193..2d6d90e14 100644
--- a/docs/persistence/prisma.md
+++ b/docs/persistence/prisma.md
@@ -99,10 +99,12 @@ transaction across multiple backends.
 
 ## Model layout
 
-The fragment maps six persisted store contracts to `Message`, `Run`, `Interrupt`,
-`Metadata`, `Artifact`, and `Blob` models. Artifact rows contain metadata;
-binary bodies live on `Blob.body`. IDs and timestamps use portable Prisma
-types so the application can generate migrations for its chosen provider.
+The fragment maps six persisted store contracts to `Message`, `Run`,
+`Interrupt`, `InterruptBatch`, `Metadata`, `Artifact`, and `Blob` models. The
+interrupt store uses both interrupt models for atomic resolution. Artifact rows
+contain metadata; binary bodies live on `Blob.body`. IDs and timestamps use
+portable Prisma types so the application can generate migrations for its
+chosen provider.
 
 ## Rename the models
 
diff --git a/docs/persistence/sandbox-persistence.md b/docs/persistence/sandbox-persistence.md
index a74d34cae..997ffca17 100644
--- a/docs/persistence/sandbox-persistence.md
+++ b/docs/persistence/sandbox-persistence.md
@@ -129,14 +129,13 @@ product contract.
 Cloudflare can back all workspace checkpoint stores:
 
 ```ts
-/// <reference types="@cloudflare/workers-types" />
-
 import { cloudflarePersistence } from '@tanstack/ai-persistence-cloudflare'
+import type { CloudflarePersistenceOptions } from '@tanstack/ai-persistence-cloudflare'
 
 declare const env: {
-  AI_STATE: D1Database
-  AI_MEDIA: R2Bucket
-  AI_LOCKS: DurableObjectNamespace
+  AI_STATE: NonNullable<CloudflarePersistenceOptions['d1']>
+  AI_MEDIA: NonNullable<CloudflarePersistenceOptions['r2']>
+  AI_LOCKS: NonNullable<CloudflarePersistenceOptions['durableObjects']>
 }
 
 const persistence = cloudflarePersistence({
diff --git a/docs/persistence/sql-backends.md b/docs/persistence/sql-backends.md
index fbf85471f..875632c22 100644
--- a/docs/persistence/sql-backends.md
+++ b/docs/persistence/sql-backends.md
@@ -31,13 +31,14 @@ export const persistence = sqlitePersistence({
 ## Existing SQLite or D1 Drizzle database
 
 ```ts
+import type { CloudflarePersistenceOptions } from '@tanstack/ai-persistence-cloudflare'
 import {
   drizzlePersistence,
   schema,
 } from '@tanstack/ai-persistence-drizzle'
 import { drizzle } from 'drizzle-orm/d1'
 
-declare const stateDatabase: D1Database
+declare const stateDatabase: NonNullable<CloudflarePersistenceOptions['d1']>
 
 const db = drizzle(stateDatabase, { schema })
 export const persistence = drizzlePersistence(db)
@@ -47,7 +48,7 @@ The package root is edge-safe; `/sqlite` is Node-only.
 
 ## Prisma
 
-```ts
+```ts group=sql-backends
 import { PrismaClient } from '@prisma/client'
 import { prismaPersistence } from '@tanstack/ai-persistence-prisma'
 
@@ -64,7 +65,7 @@ Both adapters provide messages, runs, interrupts, metadata, artifacts, blobs,
 and an in-process lock store. Replace `locks` with a distributed store when
 multiple processes can mutate the same run:
 
-```ts
+```ts group=sql-backends
 import { composePersistence } from '@tanstack/ai-persistence'
 import type { LockStore } from '@tanstack/ai'
 
diff --git a/docs/reference/functions/toolDefinition.md b/docs/reference/functions/toolDefinition.md
index 66ce2837e..96a6da370 100644
--- a/docs/reference/functions/toolDefinition.md
+++ b/docs/reference/functions/toolDefinition.md
@@ -6,7 +6,19 @@ title: toolDefinition
 # Function: toolDefinition()
 
 ```ts
-function toolDefinition<TInput, TOutput, TName>(config): ToolDefinition<TInput, TOutput, TName>;
+function toolDefinition<
+  TInput,
+  TOutput,
+  TName,
+  TNeedsApproval,
+  TApprovalSchema,
+>(config): ToolDefinition<
+  TInput,
+  TOutput,
+  TName,
+  TNeedsApproval,
+  TApprovalSchema
+>
 ```
 
 Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:191](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L191)
@@ -21,6 +33,34 @@ The definition contains all tool metadata (name, description, schemas) and can b
 Supports any Standard JSON Schema compliant library (Zod v4+, ArkType, Valibot, etc.)
 or plain JSON Schema objects.
 
+## Conditional approval schema
+
+`approvalSchema` is available only when `needsApproval: true`. It accepts either
+one Standard Schema/JSON Schema for both decisions or a nonempty branch map:
+
+```ts
+type ApprovalSchemaConfig =
+  | SchemaInput
+  | { approve: SchemaInput; reject?: SchemaInput }
+  | { approve?: SchemaInput; reject: SchemaInput }
+```
+
+The schema generic is preserved by `.server()` and `.client()`. Client
+`tool-approval` interrupts infer the selected branch payload, require it when
+the schema requires it, and place it under `payload`. Approval may also carry an
+optional, fully validated `editedArgs` replacement when the tool has an input
+schema. Rejection never accepts edited arguments.
+
+Plain JSON Schema remains runtime-only and therefore produces `unknown` payload
+data. Standard Schema inputs such as Zod infer both runtime validation and the
+bound resolver overloads.
+
+At runtime, defining `approvalSchema` without `needsApproval: true` throws.
+TanStack AI converts the input, output, and selected approval branches to
+canonical JSON Schema, embeds their hashes in the protected interrupt binding,
+and validates again on resume. See [Interrupts](../../interrupts/overview) for the
+full lifecycle.
+
 ## Type Parameters
 
 ### TInput
@@ -35,6 +75,16 @@ or plain JSON Schema objects.
 
 `TName` *extends* `string` = `string`
 
+### TNeedsApproval
+
+`TNeedsApproval` *extends* `boolean` = `false`. The literal `true` enables the
+approval capability in mapped client interrupt types.
+
+### TApprovalSchema
+
+`TApprovalSchema` *extends* `ApprovalSchemaConfig | undefined` = `undefined`.
+This generic is conditionally permitted only when `TNeedsApproval` is `true`.
+
 ## Parameters
 
 ### config
@@ -65,6 +115,10 @@ const addToCartTool = toolDefinition({
     cartId: z.string(),
     totalItems: z.number(),
   }),
+  approvalSchema: {
+    approve: z.object({ note: z.string() }),
+    reject: z.object({ reason: z.string() }),
+  },
 });
 
 // Use directly in chat (server-side, no execute function)
@@ -89,3 +143,17 @@ const addToCartClient = addToCartTool.client(async (args) => {
   return { success: true, cartId: 'local', totalItems: 1 };
 });
 ```
+
+With `tools: [addToCartTool] as const`, the corresponding bound approval has
+branch-specific overloads:
+
+```ts
+interrupt.resolveInterrupt(true, {
+  editedArgs: { guitarId: 'guitar-2', quantity: 2 },
+  payload: { note: 'Reviewed' },
+})
+
+interrupt.resolveInterrupt(false, {
+  payload: { reason: 'Budget limit' },
+})
+```
diff --git a/docs/superpowers/plans/2026-07-13-ag-ui-interrupts.md b/docs/superpowers/plans/2026-07-13-ag-ui-interrupts.md
new file mode 100644
index 000000000..0ba63a140
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-13-ag-ui-interrupts.md
@@ -0,0 +1,5205 @@
+# AG-UI Interrupts Full-Spec Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement native AG-UI interrupts with typed bound resolution APIs, exhaustive validation, durable atomic batching, recovery, compatibility shims, and equivalent behavior in every supported framework.
+
+**Architecture:** Core owns the wire DTOs, Draft 2020-12 validation, tool approval type machinery, and a persistence capability interface so `@tanstack/ai` never imports a persistence package. Persistence implementations atomically open and compare-and-swap complete interrupt batches; the headless client owns hydration, staging, validation, retry, and draft durability, while framework packages expose thin reactive projections. Continuations use the same thread, a fresh `runId`, and the interrupted run as `parentRunId` and the CAS correlation key.
+
+**Tech Stack:** TypeScript 5.9, pnpm 11.9.0, Nx, Vitest 4, Ajv 8 Draft 2020-12, ajv-formats, Standard Schema, Drizzle/SQLite, Prisma, Cloudflare D1, React, Preact, Solid, Vue, Svelte, Angular, Playwright, TanStack Start
+
+---
+
+## Scope, file structure, and dependency order
+
+The user already approved this feature-wide scope even though it changes more than five files. Keep each task narrowly scoped where feasible, do not add a codemod, and do not expand into general checkpoint, message, or tool-result persistence beyond what the interrupt transaction requires.
+
+Implementation must proceed in dependency order:
+
+1. Core schema validation and tool-definition types establish one runtime/static contract.
+2. Core wire DTOs and the core-owned interrupt persistence capability remove package-cycle pressure.
+3. The persistence contract, memory reference implementation, and shared conformance suite define atomic semantics.
+4. Drizzle, Prisma, and Cloudflare D1 implement the same atomic contract before server resumption depends on it.
+5. Server middleware and the chat engine enforce authoritative validation, event ordering, and continuation semantics.
+6. The headless client implements bound interrupts and draft durability against the settled wire contract.
+7. Compatibility readers and framework wrappers delegate to that single headless state machine.
+8. Browser E2E, documentation, release metadata, review, and quality gates close the work.
+
+The planned file ownership is:
+
+| Unit | Files | Responsibility |
+| --- | --- | --- |
+| Core validation | `packages/ai/src/activities/chat/tools/json-schema-validator.ts`, `packages/ai/src/activities/chat/tools/approval-schema.ts` | Compile Draft 2020-12 schemas, normalize issues, distinguish approval schema forms, generate response envelopes and schema identities. |
+| Core public contract | `packages/ai/src/interrupts.ts`, `packages/ai/src/types.ts`, `packages/ai/src/activities/chat/tools/tool-definition.ts`, `packages/ai/src/activities/chat/middleware/types.ts` | Public interrupt errors/recovery DTOs, capability seam, conditional generics, continuation state. |
+| Persistence core | `packages/ai-persistence/src/types.ts`, `packages/ai-persistence/src/interrupts.ts`, `packages/ai-persistence/src/memory.ts`, `packages/ai-persistence/src/testkit/conformance.ts` | Exact-set CAS contract, canonical fingerprint, memory critical section, reusable adapter tests. |
+| Durable stores | `packages/ai-persistence-drizzle/**`, `packages/ai-persistence-prisma/**`, `packages/ai-persistence-cloudflare/**` | Transactional batches, migrations, packaged assets, API and migration tests. R2 remains unchanged. |
+| Server lifecycle | `packages/ai-persistence/src/middleware.ts`, `packages/ai/src/activities/chat/index.ts` | Rebind current schemas, validate every entry, commit once, emit one structured error, snapshot before terminal, result-only continuation. |
+| Headless client | `packages/ai-client/src/interrupt-manager.ts`, `packages/ai-client/src/chat-client.ts`, `packages/ai-client/src/chat-persistence-controller.ts`, `packages/ai-client/src/connection-adapters.ts`, `packages/ai-client/src/types.ts` | Bound union, staging transaction, recovery, raw V2 drafts, explicit recovery adapters, compatibility delegation. |
+| Framework adapters | `packages/ai-{react,preact,solid,vue,svelte,angular}/src/**` | Reactive projection and generic preservation only. |
+| Browser/docs/release | `testing/e2e/**`, `docs/**`, `.changeset/ag-ui-interrupts.md` | Approved scenarios, feature/migration guides, timestamps, breaking changeset. |
+
+## Spec coverage matrix
+
+| Approved requirement | Owning task(s) |
+| --- | --- |
+| Protocol wire types and structured item/root errors | 3, 8, 9 |
+| Canonical `tool_call` and `tanstack:client_tool_execution` reasons | 9 |
+| `MESSAGES_SNAPSHOT` / `STATE_SNAPSHOT` before interrupt terminal | 9, 16 |
+| New continuation `runId`, same thread, interrupted run as `parentRunId` | 8, 9, 12, 16 |
+| Result-only resumed tool events and mixed audit history | 9, 16 |
+| Conditional `approvalSchema`, Standard Schema inference, `.client()` / `.server()` preservation | 2, 10, 15 |
+| Tool approval, client-tool, and generic bound unions | 10 |
+| Singleton auto-submit; multi-item wait; replacement; clear; callback rollback/late-call protection | 11 |
+| Root boolean/callback/cancel/retry, statuses, errors, staged response, unsafe raw resume | 11, 12 |
+| Draft 2020-12 Ajv validation and deterministic paths | 1, 2, 8, 10 |
+| Versioned client draft persistence and recovery reconciliation | 13 |
+| Exhaustive authoritative server validation, one error event, no write on invalid | 8 |
+| Atomic CAS memory/Drizzle/Prisma/D1, exact replay, conflict, first writer, recovery | 4, 5, 6, 7 |
+| Core-owned persistence capability without package cycles | 3, 8 |
+| Validator rebind by registered tool name/schema hash; drift is stale | 8 |
+| Explicit recovery handler/fetcher, never a guessed URL | 8, 13 |
+| Generic continuation exposed to application middleware | 3, 8, 9 |
+| Deprecations, legacy reader, no native dual writer, retained `addToolResult` | 12 |
+| Sandbox legacy-event collision guard | 12 |
+| React/Preact/Solid/Vue/Svelte/Angular parity | 14, 15 |
+| Documentation timestamps, migration guide, breaking changeset, no codemod | 17 |
+| All approved unit/type/framework/E2E scenarios | 1-17 |
+
+### Task 0: Prepare the isolated Windows execution environment
+
+**Prerequisites:** None. Run every later command from `F:\projects\tanstack\ai-interrupts-full-spec-design` in native Windows PowerShell.
+
+**Files:**
+- Read: `AGENTS.md`
+- Read: `CLAUDE.md`
+- Read: `docs/superpowers/specs/2026-07-13-ag-ui-interrupts-design.md`
+- Read: `docs/superpowers/plans/2026-07-13-ag-ui-interrupts.md`
+
+- [ ] **Step 1: Verify branch and working tree ownership**
+
+Run:
+
+```powershell
+git status --short --branch
+git branch --show-current
+```
+
+Expected: branch `codex/interrupts-full-spec-design`; only intentional plan/spec history is present before implementation. Preserve unrelated user changes if any appear.
+
+- [ ] **Step 2: Install with the repository-enforced package manager**
+
+Run:
+
+```powershell
+corepack pnpm --version
+pnpm install
+```
+
+Expected: pnpm reports `11.9.0` and install completes successfully. PowerShell environment assignments are process-local, so every later command block that runs Vitest, Nx, or Playwright sets `$env:CI='true'` itself. Run `pnpm install` again after any merge from `main` before resuming work.
+
+- [ ] **Step 3: Establish execution-time quality peers**
+
+Use the `test-hygiene` skill for a peer review before modifying test helpers or fixtures. Use the `debugging-discipline` skill whenever a red test fails for a reason other than the named missing symbol/behavior, and retain the investigation ledger for Task 18. These are execution requirements, not optional final polish.
+
+- [ ] **Step 4: Enforce subprocess hygiene**
+
+Use one-shot commands only; never start watch mode, a development server, or a WSL shell. Await each pnpm/Nx/Vitest/Playwright process tree before starting the next memory-heavy command. Do not kill all Node processes and do not run `wsl --shutdown` while any command is active.
+
+### Task 1: Add one Draft 2020-12 validator for browser and server
+
+**Prerequisites:** Task 0.
+
+**Files:**
+- Create: `packages/ai/src/activities/chat/tools/json-schema-validator.ts`
+- Modify: `packages/ai/src/index.ts:43-52`
+- Modify: `packages/ai/src/client.ts:229-234,300-301`
+- Modify: `packages/ai/package.json:82-94`
+- Modify: `pnpm-lock.yaml`
+- Test: `packages/ai/tests/interrupts.test.ts`
+
+- [ ] **Step 1: Write focused failing validator tests**
+
+Append these tests; they prove Ajv issue order, local references, repeated object reuse, cycle rejection, canonical JSON input, format handling, mutation safety, and RFC 6901 paths:
+
+```ts
+import {
+  JsonSchemaCompilationError,
+  compileJsonSchema202012,
+} from '../src/activities/chat/tools/json-schema-validator'
+
+it('normalizes every Draft 2020-12 issue without mutating input', () => {
+  const validate = compileJsonSchema202012({
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    type: 'object',
+    properties: {
+      'a/b': { type: 'string', minLength: 3 },
+      email: { type: 'string', format: 'email' },
+    },
+    required: ['a/b', 'email'],
+    additionalProperties: false,
+  })
+  const input = { 'a/b': 'x', email: 'bad', extra: true }
+
+  expect(validate(input)).toEqual([
+    expect.objectContaining({ keyword: 'additionalProperties', path: ['extra'] }),
+    expect.objectContaining({ path: ['a/b'] }),
+    expect.objectContaining({ path: ['email'] }),
+  ])
+  expect(input).toEqual({ 'a/b': 'x', email: 'bad', extra: true })
+})
+
+it('accepts #, local $defs, and repeated acyclic object identities', () => {
+  const sharedProperty = { type: 'string', minLength: 2 } as const
+  const sharedObject = {
+    type: 'object',
+    properties: { label: sharedProperty },
+    required: ['label'],
+    additionalProperties: false,
+  } as const
+  const root = {
+    type: 'object',
+    $defs: { entry: sharedObject },
+    properties: {
+      selfCopy: { $ref: '#' },
+      first: { $ref: '#/$defs/entry' },
+      second: sharedObject,
+      third: sharedObject,
+    },
+    additionalProperties: false,
+  } as const
+  const validate = compileJsonSchema202012(root)
+
+  expect(validate({
+    first: { label: 'ok' },
+    second: { label: 'yes' },
+    third: { label: 'no' },
+  })).toEqual([])
+})
+
+it('rejects unresolved local references, true cycles, Date, and Map', () => {
+  expect(() => compileJsonSchema202012({ $ref: '#/$defs/missing' })).toThrow(
+    JsonSchemaCompilationError,
+  )
+
+  const cyclic: Record<string, unknown> = { type: 'object' }
+  cyclic['properties'] = { self: cyclic }
+  expect(() => compileJsonSchema202012(cyclic)).toThrow(/cycles/)
+  expect(() => compileJsonSchema202012(new Date())).toThrow(/plain JSON/)
+  expect(() => compileJsonSchema202012(new Map())).toThrow(/plain JSON/)
+})
+
+it('accepts canonical JSON primitives and rejects non-JSON values', () => {
+  const validate = compileJsonSchema202012({
+    type: 'array',
+    items: { type: ['string', 'number', 'boolean', 'null'] },
+  })
+  expect(validate(['text', 1, true, null])).toEqual([])
+  expect(() => compileJsonSchema202012({ const: undefined })).toThrow(
+    /JSON-compatible/,
+  )
+})
+
+it('rejects other dialects, remote references, and unknown formats', () => {
+  expect(() =>
+    compileJsonSchema202012({
+      $schema: 'http://json-schema.org/draft-07/schema#',
+      type: 'string',
+    }),
+  ).toThrow(JsonSchemaCompilationError)
+  expect(() =>
+    compileJsonSchema202012({ $ref: 'https://example.com/schema.json' }),
+  ).toThrow(/document-local/)
+  expect(() =>
+    compileJsonSchema202012({ type: 'string', format: 'private-id' }),
+  ).toThrow(JsonSchemaCompilationError)
+})
+```
+
+- [ ] **Step 2: Run the red test**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai test:lib -- --run tests/interrupts.test.ts
+```
+
+Expected: FAIL because `json-schema-validator.ts` and `compileJsonSchema202012` do not exist.
+
+- [ ] **Step 3: Add dependencies and the minimal shared compiler**
+
+Add runtime dependencies `"ajv": "^8.20.0"` and `"ajv-formats": "^3.0.1"`, run `pnpm install`, and implement this public shape:
+
+```ts
+import Ajv2020 from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import type { ErrorObject } from 'ajv'
+import type { JSONSchema } from '../../../types'
+
+export interface JsonSchemaValidationIssue {
+  keyword: string
+  message: string
+  path: readonly (string | number)[]
+}
+
+export class JsonSchemaCompilationError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'JsonSchemaCompilationError'
+  }
+}
+
+function decodePointer(pointer: string): Array<string> {
+  if (pointer === '') return []
+  return pointer
+    .slice(1)
+    .split('/')
+    .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+}
+
+function issuePath(error: ErrorObject): Array<string> {
+  const path = decodePointer(error.instancePath)
+  if (error.keyword === 'required') {
+    path.push(String(error.params['missingProperty']))
+  }
+  if (error.keyword === 'additionalProperties') {
+    path.push(String(error.params['additionalProperty']))
+  }
+  return path
+}
+
+const draft202012 = 'https://json-schema.org/draft/2020-12/schema'
+
+function assertSupportedSchemaTree(schema: unknown): asserts schema is JSONSchema {
+  const active = new WeakSet<object>()
+  const visit = (value: unknown): void => {
+    if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) {
+      return
+    }
+    if (typeof value !== 'object') {
+      throw new JsonSchemaCompilationError('Schema values must be JSON-compatible.')
+    }
+    if (
+      !Array.isArray(value) &&
+      Object.getPrototypeOf(value) !== Object.prototype &&
+      Object.getPrototypeOf(value) !== null
+    ) {
+      throw new JsonSchemaCompilationError('Schema nodes must be plain JSON objects.')
+    }
+    if (active.has(value)) {
+      throw new JsonSchemaCompilationError('Schema values must not contain cycles.')
+    }
+    active.add(value)
+    if (Array.isArray(value)) {
+      value.forEach(visit)
+      active.delete(value)
+      return
+    }
+    const record = value as Record<string, unknown>
+    if (
+      typeof record['$schema'] === 'string' &&
+      record['$schema'] !== draft202012
+    ) {
+      throw new JsonSchemaCompilationError('Only Draft 2020-12 is supported.')
+    }
+    if (
+      typeof record['$ref'] === 'string' &&
+      !record['$ref'].startsWith('#')
+    ) {
+      throw new JsonSchemaCompilationError('Only document-local $ref values are supported.')
+    }
+    Object.values(record).forEach(visit)
+    active.delete(value)
+  }
+  visit(schema)
+}
+
+export function compileJsonSchema202012(
+  schema: unknown,
+): (value: unknown) => readonly JsonSchemaValidationIssue[] {
+  assertSupportedSchemaTree(schema)
+  const ajv = new Ajv2020({
+    allErrors: true,
+    strict: true,
+    validateFormats: true,
+    coerceTypes: false,
+    useDefaults: false,
+    removeAdditional: false,
+  })
+  addFormats(ajv, { mode: 'full' })
+  let validate
+  try {
+    validate = ajv.compile(schema)
+  } catch (cause) {
+    throw new JsonSchemaCompilationError('Invalid Draft 2020-12 schema.', {
+      cause,
+    })
+  }
+  return (value) => {
+    if (validate(value)) return []
+    return (validate.errors ?? []).map((error) => ({
+      keyword: error.keyword,
+      message: error.message ?? 'Schema validation failed.',
+      path: issuePath(error),
+    }))
+  }
+}
+```
+
+The active recursion set is removed on unwind, so repeated acyclic object identities are legal while true cycles fail. Ajv owns local-reference resolution and issue evaluation order; do not sort `validate.errors`. Export the compiler and issue/error types from both core barrels; do not alter the provider-facing draft-07 conversion in `schema-converter.ts`.
+
+- [ ] **Step 4: Run the green test and type check**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai test:lib -- --run tests/interrupts.test.ts
+pnpm --filter @tanstack/ai test:types
+```
+
+Expected: both commands PASS; the test reports all three normalized paths in deterministic Ajv order.
+
+- [ ] **Step 5: Refactor without changing behavior**
+
+Extract pointer decoding and recursive `$ref` traversal into private pure functions, keep one Ajv option object, rerun both commands, and confirm no validator path mutates input or performs network/file resolution.
+
+### Task 2: Make `approvalSchema` conditional, branch-aware, and generic-preserving
+
+**Prerequisites:** Task 1.
+
+**Files:**
+- Create: `packages/ai/src/activities/chat/tools/approval-schema.ts`
+- Create: `packages/ai/src/interrupt-serialization.ts`
+- Modify: `packages/ai/src/activities/chat/tools/tool-definition.ts:12-227`
+- Modify: `packages/ai/src/types.ts:133-153,601-735`
+- Modify: `packages/ai/src/index.ts:43-52`
+- Modify: `packages/ai/src/client.ts:229-234,300-301`
+- Modify: `packages/ai/package.json:82-94`
+- Modify: `pnpm-lock.yaml`
+- Create: `packages/ai/tests/interrupts-types.test-d.ts`
+- Modify: `packages/ai/tests/interrupts.test.ts`
+
+- [ ] **Step 1: Write failing compile-time and runtime cases**
+
+Create type tests covering shared/branch schemas, omitted branches, input/output inference, and both transformations:
+
+```ts
+import { expectTypeOf } from 'vitest'
+import { z } from 'zod'
+import {
+  toolDefinition,
+  type ApprovalCapabilityOf,
+  type ApprovalSchemaOf,
+  type InferToolInput,
+  type InferToolOutput,
+  type InputSchemaOf,
+  type NoSchema,
+} from '../src'
+
+const transfer = toolDefinition({
+  name: 'transfer',
+  description: 'Transfer funds',
+  needsApproval: true,
+  inputSchema: z.object({ cents: z.number() }),
+  outputSchema: z.object({ receipt: z.string() }),
+  approvalSchema: {
+    approve: z.object({ note: z.string() }),
+    reject: z.object({ reason: z.string() }),
+  },
+})
+
+expectTypeOf<InferToolInput<typeof transfer>>().toEqualTypeOf<{
+  cents: number
+}>()
+expectTypeOf<InferToolOutput<ReturnType<typeof transfer.client>>>().toEqualTypeOf<{
+  receipt: string
+}>()
+expectTypeOf<ApprovalCapabilityOf<ReturnType<typeof transfer.server>>>().toEqualTypeOf<true>()
+expectTypeOf<ApprovalSchemaOf<ReturnType<typeof transfer.client>>>().toEqualTypeOf<typeof transfer.approvalSchema>()
+
+toolDefinition({
+  name: 'invalid',
+  description: 'Cannot declare an approval payload',
+  // @ts-expect-error approvalSchema requires needsApproval: true
+  approvalSchema: z.object({ note: z.string() }),
+})
+
+const noInputDefinition = toolDefinition({
+  name: 'noInput',
+  description: 'Approval without editable input',
+  needsApproval: true,
+})
+const noInputClient = noInputDefinition.client()
+const noInputServer = noInputDefinition.server(async () => ({ ok: true }))
+expectTypeOf(noInputClient.inputSchema).toEqualTypeOf<undefined>()
+expectTypeOf(noInputServer.inputSchema).toEqualTypeOf<undefined>()
+expectTypeOf<InputSchemaOf<typeof noInputDefinition>>().toEqualTypeOf<NoSchema>()
+expectTypeOf<InputSchemaOf<typeof noInputClient>>().toEqualTypeOf<NoSchema>()
+expectTypeOf<InputSchemaOf<typeof noInputServer>>().toEqualTypeOf<NoSchema>()
+```
+
+Add runtime assertions:
+
+```ts
+it('builds branch-aware approval envelopes and rejects malformed maps', () => {
+  const normalized = normalizeApprovalSchema({
+    approve: { type: 'object', required: ['note'] },
+  })
+  expect(normalized.responseSchema).toMatchObject({ oneOf: expect.any(Array) })
+  expect(normalized.branches.reject).toBeNull()
+  expect(() => normalizeApprovalSchema({})).toThrow(/approve or reject/)
+  expect(() =>
+    normalizeApprovalSchema({ approve: { unsupported: Symbol('bad') } }),
+  ).toThrow(/SchemaInput/)
+})
+```
+
+- [ ] **Step 2: Run the red targets**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai test:types
+pnpm --filter @tanstack/ai test:lib -- --run tests/interrupts.test.ts
+```
+
+Expected: type check FAILS because `approvalSchema`, `ApprovalCapabilityOf`, and `ApprovalSchemaOf` are missing; runtime test FAILS because `normalizeApprovalSchema` is missing.
+
+- [ ] **Step 3: Add the type marker and discriminated config**
+
+Replace the config interface with a discriminated intersection and add an approval generic to definition/client/server forms:
+
+```ts
+export declare const toolApprovalCapability: unique symbol
+
+export interface ToolApprovalCapabilityMarker<
+  TNeedsApproval extends boolean,
+  TApprovalSchema,
+> {
+  readonly [toolApprovalCapability]: {
+    needsApproval: TNeedsApproval
+    approvalSchema: TApprovalSchema
+  }
+}
+
+export type ApprovalSchemaConfig =
+  | SchemaInput
+  | { approve: SchemaInput; reject?: SchemaInput }
+  | { approve?: SchemaInput; reject: SchemaInput }
+
+type ApprovalConfig<
+  TNeedsApproval extends boolean,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined,
+> = TNeedsApproval extends true
+  ? { needsApproval: true; approvalSchema?: TApprovalSchema }
+  : { needsApproval?: false; approvalSchema?: never }
+
+export type ToolDefinitionConfig<
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
+  TName extends string = string,
+  TNeedsApproval extends boolean = false,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
+> = {
+  name: TName
+  description: string
+  inputSchema?: TInput
+  outputSchema?: TOutput
+  lazy?: boolean
+  metadata?: Record<string, unknown>
+} & ApprovalConfig<TNeedsApproval, TApprovalSchema>
+
+export type ApprovalCapabilityOf<TTool> =
+  TTool extends ToolApprovalCapabilityMarker<infer TNeeds, unknown>
+    ? TNeeds
+    : false
+
+export type ApprovalSchemaOf<TTool> =
+  TTool extends ToolApprovalCapabilityMarker<boolean, infer TSchema>
+    ? TSchema
+    : undefined
+
+export declare const noSchema: unique symbol
+export type NoSchema = typeof noSchema
+
+export type InputSchemaOf<TTool> =
+  TTool extends { inputSchema: infer TInput }
+    ? TInput extends undefined ? NoSchema : TInput
+    : NoSchema
+
+export type OutputSchemaOf<TTool> =
+  TTool extends { outputSchema: infer TOutput }
+    ? TOutput extends undefined ? NoSchema : TOutput
+    : NoSchema
+```
+
+Apply `TInput extends SchemaInput | undefined = undefined` and `TOutput extends SchemaInput | undefined = undefined` verbatim to `ToolDefinitionConfig`, `ToolDefinition`, `ToolDefinitionInstance`, `ClientTool`, `ServerTool`, `toolDefinition()`, `.client()`, and `.server()`. Every returned intersection carries the exact `TInput`, `TOutput`, `TNeedsApproval`, and `TApprovalSchema` parameters. The runtime `inputSchema` and `outputSchema` fields remain `undefined` when omitted, while `InputSchemaOf`/`OutputSchemaOf` map only that literal absence to `NoSchema`. `InferToolInput` and `InferToolOutput` return `unknown` for a present raw JSON Schema but never widen an omitted schema into a present schema. The compile failures above prove `editedArgs` cannot appear for an omitted input schema before any client-manager work begins.
+
+- [ ] **Step 4: Normalize schemas once and generate the wire envelope**
+
+Implement `normalizeApprovalSchema` with this returned contract:
+
+```ts
+export interface NormalizedApprovalSchema {
+  branches: {
+    approve: NormalizedSchemaInput | null
+    reject: NormalizedSchemaInput | null
+  }
+  responseSchema: JSONSchema
+  responseSchemaHash: string
+  approvalSchemaHash: string
+}
+
+export function normalizeApprovalSchema(
+  approvalSchema: ApprovalSchemaConfig | undefined,
+  inputSchema?: SchemaInput,
+): NormalizedApprovalSchema
+```
+
+Add `@noble/hashes` as a runtime dependency and implement `interrupt-serialization.ts` in core. This is the only canonicalization, digest, clone, and deep-freeze implementation used later by persistence and the client:
+
+```ts
+import { sha256 } from '@noble/hashes/sha2.js'
+import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js'
+
+function canonical(value: unknown, active: WeakSet<object>): string {
+  if (value === null) return 'null'
+  if (typeof value === 'string' || typeof value === 'boolean') {
+    return JSON.stringify(value)
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return JSON.stringify(value)
+  }
+  if (typeof value !== 'object') {
+    throw new TypeError('Interrupt values must be JSON-compatible.')
+  }
+  if (active.has(value)) throw new TypeError('Interrupt values must not cycle.')
+  if (
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) !== Object.prototype &&
+    Object.getPrototypeOf(value) !== null
+  ) {
+    throw new TypeError('Interrupt values must use plain JSON objects.')
+  }
+
+  active.add(value)
+  let encoded: string
+  if (Array.isArray(value)) {
+    encoded = `[${value.map((item) => canonical(item, active)).join(',')}]`
+  } else {
+    const record = value as Record<string, unknown>
+    encoded = `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonical(record[key], active)}`)
+      .join(',')}}`
+  }
+  active.delete(value)
+  return encoded
+}
+
+export function canonicalInterruptJson(value: unknown): string {
+  return canonical(value, new WeakSet<object>())
+}
+
+export function digestInterruptJson(canonicalJson: string): string {
+  return `sha256:${bytesToHex(sha256(utf8ToBytes(canonicalJson)))}`
+}
+
+function freezeTree(value: unknown): void {
+  if (value === null || typeof value !== 'object' || Object.isFrozen(value)) return
+  Object.values(value).forEach(freezeTree)
+  Object.freeze(value)
+}
+
+export function cloneAndDeepFreezeJson<T>(value: T): T {
+  const clone: T = JSON.parse(canonicalInterruptJson(value))
+  freezeTree(clone)
+  return clone
+}
+```
+
+Implement the approval normalizer with no undefined helper. `schemaToWire` checks Standard Schema first, retains its validator, uses its Standard JSON Schema export when present, and otherwise uses `{}` only for the nested wire payload while keeping the validator. Raw JSON Schema is recognized before a branch map by the keyword set:
+
+```ts
+const jsonSchemaKeywords = new Set([
+  '$schema', '$id', '$ref', '$defs', 'type', 'properties', 'required',
+  'additionalProperties', 'items', 'oneOf', 'anyOf', 'allOf', 'enum', 'const',
+  'format', 'minimum', 'maximum', 'minLength', 'maxLength', 'pattern',
+])
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isRawJsonSchema(value: unknown): value is JSONSchema {
+  return isPlainRecord(value) &&
+    Object.keys(value).some((key) => jsonSchemaKeywords.has(key))
+}
+
+function isApprovalBranchMap(
+  value: unknown,
+): value is { approve?: SchemaInput; reject?: SchemaInput } {
+  if (!isPlainRecord(value)) return false
+  const keys = Object.keys(value)
+  return (
+    keys.length > 0 &&
+    keys.every((key) => key === 'approve' || key === 'reject') &&
+    keys.every((key) => isSchemaInput(value[key]))
+  )
+}
+
+function schemaToWire(schema: SchemaInput): NormalizedSchemaInput {
+  if (isStandardSchema(schema)) {
+    const jsonSchema = isStandardJSONSchema(schema)
+      ? schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' })
+      : undefined
+    return { source: schema, validator: schema, jsonSchema }
+  }
+  if (isRawJsonSchema(schema)) {
+    compileJsonSchema202012(schema)
+    return { source: schema, jsonSchema: schema }
+  }
+  throw new TypeError('Expected a supported SchemaInput.')
+}
+
+function decisionEnvelope(input: {
+  approved: boolean
+  payload: NormalizedSchemaInput | null
+  inputSchema: NormalizedSchemaInput | null
+}): JSONSchema {
+  const properties: Record<string, JSONSchema> = {
+    approved: { const: input.approved },
+  }
+  const required = ['approved']
+  if (input.approved && input.inputSchema) {
+    properties['editedArgs'] = input.inputSchema.jsonSchema ?? {}
+  }
+  if (input.payload) {
+    properties['payload'] = input.payload.jsonSchema ?? {}
+    required.push('payload')
+  }
+  return {
+    type: 'object',
+    properties,
+    required,
+    additionalProperties: false,
+  }
+}
+
+export function normalizeApprovalSchema(
+  approvalSchema: ApprovalSchemaConfig | undefined,
+  inputSchema?: SchemaInput,
+): NormalizedApprovalSchema {
+  const normalizedInput = inputSchema ? schemaToWire(inputSchema) : null
+  let approve: NormalizedSchemaInput | null = null
+  let reject: NormalizedSchemaInput | null = null
+  if (approvalSchema !== undefined) {
+    if (isStandardSchema(approvalSchema) || isRawJsonSchema(approvalSchema)) {
+      approve = schemaToWire(approvalSchema)
+      reject = approve
+    } else if (isApprovalBranchMap(approvalSchema)) {
+      approve = approvalSchema.approve
+        ? schemaToWire(approvalSchema.approve)
+        : null
+      reject = approvalSchema.reject
+        ? schemaToWire(approvalSchema.reject)
+        : null
+    } else {
+      throw new TypeError('approvalSchema must be a SchemaInput or nonempty approve/reject map.')
+    }
+  }
+  const responseSchema: JSONSchema = {
+    oneOf: [
+      decisionEnvelope({ approved: true, payload: approve, inputSchema: normalizedInput }),
+      decisionEnvelope({ approved: false, payload: reject, inputSchema: null }),
+    ],
+  }
+  const responseCanonical = canonicalInterruptJson(responseSchema)
+  const approvalCanonical = canonicalInterruptJson({
+    approve: approve?.jsonSchema ?? null,
+    reject: reject?.jsonSchema ?? null,
+  })
+  return {
+    branches: { approve, reject },
+    responseSchema,
+    responseSchemaHash: digestInterruptJson(responseCanonical),
+    approvalSchemaHash: digestInterruptJson(approvalCanonical),
+  }
+}
+
+export function hashSchemaInput(schema: SchemaInput | undefined): string {
+  if (schema === undefined) return digestInterruptJson('undefined')
+  const normalized = schemaToWire(schema)
+  const identity = normalized.jsonSchema ?? { standardValidator: 'unserialized' }
+  return digestInterruptJson(canonicalInterruptJson(identity))
+}
+```
+
+Add the imported `isSchemaInput` guard to `schema-converter.ts` using the same Standard-first/raw-keyword checks, export it, and use it above. Add `NormalizedSchemaInput` with `source`, optional `validator`, and optional `jsonSchema`. Add runtime tests for every shared/branch/omitted form, malformed empty/unknown-key maps, Standard Schema with and without JSON export, raw schema compilation, response/approval hash stability, and rejection of function/Symbol/cyclic values. Never derive identity from function source text.
+
+- [ ] **Step 5: Run green type/runtime checks**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai test:types
+pnpm --filter @tanstack/ai test:lib -- --run tests/interrupts.test.ts
+```
+
+Expected: both PASS; `.client()` and `.server()` preserve `true`, input/output, and approval-schema generics; malformed branch objects throw synchronously.
+
+- [ ] **Step 6: Focused refactor and recheck**
+
+Make the type-level `ApproveSchema`/`RejectSchema` selectors read the same normalized forms used at runtime, name conditional helpers so diagnostics remain legible, and rerun both commands. Confirm no provider schema-converter code changed.
+
+### Task 3: Define core wire DTOs, recovery DTO, and persistence capability
+
+**Prerequisites:** Task 2.
+
+**Files:**
+- Create: `packages/ai/src/interrupts.ts`
+- Modify: `packages/ai/src/types.ts:1081-1124,1371-1400,1480-1550`
+- Modify: `packages/ai/src/activities/chat/middleware/types.ts:88-115,208-235`
+- Modify: `packages/ai/src/index.ts:111-172`
+- Modify: `packages/ai/src/client.ts:229-234,300-301`
+- Modify: `packages/ai/tests/interrupts.test.ts`
+- Modify: `packages/ai/tests/interrupts-types.test-d.ts`
+
+- [ ] **Step 1: Write failing DTO and capability tests**
+
+Add compile/runtime assertions for item/root errors, recovery correlation, generic continuation, and the core-owned capability:
+
+```ts
+import {
+  InterruptPersistenceCapability,
+  canonicalizeInterruptResolutions,
+  type InterruptRecoveryStateV1,
+  type InterruptSubmissionError,
+} from '../src/interrupts'
+
+it('correlates interrupt errors and recovery to the interrupted run', () => {
+  const recovery = {
+    schemaVersion: 1,
+    state: 'committed',
+    threadId: 'thread-1',
+    interruptedRunId: 'run-old',
+    generation: 2,
+    pendingInterrupts: [],
+    committed: {
+      fingerprint: 'v1:abc',
+      resolutions: [],
+      continuationRunId: 'run-new',
+      committedAt: '2026-07-13T10:00:00.000Z',
+    },
+  } satisfies InterruptRecoveryStateV1
+  const error: InterruptSubmissionError = {
+    scope: 'batch',
+    code: 'conflict',
+    message: 'Another response batch won.',
+    source: 'server',
+    retryable: false,
+    interruptIds: ['interrupt-1'],
+    threadId: 'thread-1',
+    interruptedRunId: 'run-old',
+    generation: 2,
+  }
+
+  expect(recovery.committed.continuationRunId).toBe('run-new')
+  expect(error.interruptedRunId).toBe('run-old')
+  expect(InterruptPersistenceCapability.capabilityName).toBe(
+    'interrupt-persistence',
+  )
+})
+
+it('canonicalizes and deeply freezes response batches in core', () => {
+  const left = canonicalizeInterruptResolutions([
+    { interruptId: 'b', status: 'cancelled' },
+    { interruptId: 'a', status: 'resolved', payload: { z: 1, a: 2 } },
+  ])
+  const right = canonicalizeInterruptResolutions([
+    { interruptId: 'a', status: 'resolved', payload: { a: 2, z: 1 } },
+    { interruptId: 'b', status: 'cancelled' },
+  ])
+  expect(left.canonicalResolutions).toBe(right.canonicalResolutions)
+  expect(left.fingerprint).toMatch(/^sha256:[0-9a-f]{64}$/)
+  expect(left.fingerprint).toBe(right.fingerprint)
+  expect(Object.isFrozen(left.resolutions)).toBe(true)
+  expect(Object.isFrozen(left.resolutions[0])).toBe(true)
+})
+```
+
+- [ ] **Step 2: Run the red targets**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai test:lib -- --run tests/interrupts.test.ts
+pnpm --filter @tanstack/ai test:types
+```
+
+Expected: FAIL because `interrupts.ts`, `InterruptRecoveryStateV1`, and `InterruptPersistenceCapability` do not exist.
+
+- [ ] **Step 3: Implement the core-owned seam and public DTOs**
+
+Define the complete error code unions from the approved spec, `InterruptCorrelation`, item/root errors, and recovery DTO. The atomic gateway contract must include opening descriptors atomically as well as committing responses:
+
+```ts
+export interface OpenInterruptBatchInput {
+  threadId: string
+  interruptedRunId: string
+  descriptors: readonly Interrupt[]
+  bindings: readonly UnopenedInterruptBinding[]
+}
+
+export interface CommitInterruptResolutionsInput {
+  threadId: string
+  interruptedRunId: string
+  continuationRunId: string
+  expectedGeneration: number
+  expectedInterruptIds: readonly string[]
+  resolutions: readonly RunAgentResumeItem[]
+  fingerprint: string
+  canonicalResolutions: string
+}
+
+export interface InterruptCorrelation {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  submissionId?: string
+  continuationRunId?: string
+}
+
+export type ItemInterruptErrorCode =
+  | 'invalid-payload'
+  | 'invalid-edited-args'
+  | 'invalid-tool-output'
+  | 'invalid-response-schema'
+  | 'unknown-interrupt'
+  | 'expired'
+  | 'stale'
+  | 'conflict'
+  | 'legacy-unsupported'
+
+export type BatchInterruptErrorCode =
+  | 'incomplete-batch'
+  | 'item-validation-failed'
+  | 'unsupported-bulk-operation'
+  | 'async-resolver'
+  | 'inactive-transaction'
+  | 'mixed-provenance'
+  | 'transport'
+  | 'server'
+  | 'protocol'
+  | 'invalid-response-schema'
+  | 'expired'
+  | 'stale'
+  | 'conflict'
+  | 'persistence-required'
+  | 'atomic-commit-unsupported'
+  | 'recovery-unavailable'
+  | 'legacy-submit-failed'
+
+export interface ItemInterruptError extends InterruptCorrelation {
+  scope: 'item'
+  interruptId: string
+  code: ItemInterruptErrorCode
+  message: string
+  path?: readonly (string | number)[]
+  source: 'client' | 'server'
+  retryable: boolean
+}
+
+export interface BatchInterruptError extends InterruptCorrelation {
+  scope: 'batch'
+  code: BatchInterruptErrorCode
+  message: string
+  source: 'client' | 'server' | 'transport'
+  retryable: boolean
+  interruptIds: readonly string[]
+}
+
+export type InterruptSubmissionError = ItemInterruptError | BatchInterruptError
+
+export type InterruptBinding =
+  | {
+      kind: 'tool-approval'
+      interruptId: string
+      interruptedRunId: string
+      generation: number
+      toolName: string
+      toolCallId: string
+      originalArgs: unknown
+      inputSchemaHash: string
+      approvalSchemaHash: string
+      responseSchemaHash: string
+      expiresAt?: string
+    }
+  | {
+      kind: 'client-tool-execution'
+      interruptId: string
+      interruptedRunId: string
+      generation: number
+      toolName: string
+      toolCallId: string
+      outputSchemaHash: string
+      responseSchemaHash: string
+      expiresAt?: string
+    }
+  | {
+      kind: 'generic'
+      interruptId: string
+      interruptedRunId: string
+      generation: number
+      responseSchemaHash: string
+      expiresAt?: string
+    }
+
+export type UnopenedInterruptBinding = InterruptBinding extends infer TBinding
+  ? TBinding extends InterruptBinding
+    ? Omit<TBinding, 'interruptedRunId' | 'generation'>
+    : never
+  : never
+
+export type InterruptCommitResult =
+  | { status: 'committed'; continuationRunId: string }
+  | { status: 'replayed'; continuationRunId: string }
+  | { status: 'conflict'; authoritativeState: InterruptRecoveryStateV1 }
+
+export interface InterruptRecoveryQuery {
+  threadId: string
+  interruptedRunId: string
+  knownGeneration: number
+}
+
+export interface InterruptRecoveryStateV1 extends InterruptCorrelation {
+  schemaVersion: 1
+  state: 'pending' | 'committed' | 'expired' | 'missing' | 'legacy-committed'
+  pendingInterrupts: readonly Interrupt[]
+  committed?: {
+    fingerprint: string
+    resolutions?: readonly RunAgentResumeItem[]
+    continuationRunId?: string
+    committedAt: string
+  }
+}
+
+export interface InterruptPersistenceGateway {
+  openInterruptBatch(
+    input: OpenInterruptBatchInput,
+  ): Promise<{ generation: number; descriptors: readonly Interrupt[] }>
+  commitInterruptResolutions(
+    input: CommitInterruptResolutionsInput,
+  ): Promise<InterruptCommitResult>
+  getInterruptRecoveryState(
+    input: InterruptRecoveryQuery,
+  ): Promise<InterruptRecoveryStateV1>
+}
+
+export const InterruptPersistenceCapability =
+  createCapability<InterruptPersistenceGateway>()('interrupt-persistence')
+
+export const [getInterruptPersistence, provideInterruptPersistence] =
+  InterruptPersistenceCapability
+```
+
+Add this core-owned response canonicalizer; persistence stores compare both the SHA-256 digest and canonical bytes on replay:
+
+```ts
+export function canonicalizeInterruptResolutions(
+  resolutions: readonly RunAgentResumeItem[],
+): {
+  resolutions: readonly RunAgentResumeItem[]
+  canonicalResolutions: string
+  fingerprint: string
+} {
+  const sorted = [...resolutions].sort((left, right) =>
+    left.interruptId.localeCompare(right.interruptId),
+  )
+  const frozen = cloneAndDeepFreezeJson(sorted)
+  const canonicalResolutions = canonicalInterruptJson(frozen)
+  return Object.freeze({
+    resolutions: frozen,
+    canonicalResolutions,
+    fingerprint: digestInterruptJson(canonicalResolutions),
+  })
+}
+```
+
+Extend `RunErrorEvent` with optional top-level fields:
+
+```ts
+export interface RunErrorEvent extends AGUIRunErrorEvent {
+  model?: string
+  'tanstack:interruptErrors'?: readonly InterruptSubmissionError[]
+  'tanstack:interruptRecovery'?: InterruptRecoveryStateV1
+  error?: { message: string; code?: string | undefined } | undefined
+}
+```
+
+Extend middleware context/config state without importing persistence:
+
+```ts
+export interface ChatMiddlewareContext<TContext = unknown> {
+  runId: string
+  parentRunId?: string
+  threadId: string
+}
+
+export type ChatResumeGenericResolution =
+  | { interruptId: string; status: 'resolved'; payload: unknown }
+  | { interruptId: string; status: 'cancelled'; payload?: never }
+
+export interface ChatResumeToolState {
+  approvals?: ReadonlyMap<string, ToolApprovalResolution>
+  clientToolResults?: ReadonlyMap<string, unknown>
+  genericInterrupts?: ReadonlyMap<string, ChatResumeGenericResolution>
+  deniedToolResults?: ReadonlyMap<string, unknown>
+  cancelledToolCallIds?: ReadonlySet<string>
+}
+```
+
+Add `parentRunId` when `TextEngine` constructs `middlewareCtx`. Deprecate `ApprovalRequestedEvent` and `ToolInputAvailableEvent` with removal-at-1.0 JSDoc, but keep them in `KnownCustomEvent` for compatibility. Export every new public DTO/capability from root and client barrels.
+
+- [ ] **Step 4: Run green tests**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai test:lib -- --run tests/interrupts.test.ts
+pnpm --filter @tanstack/ai test:types
+```
+
+Expected: both PASS; no dependency from `packages/ai` to any persistence package appears.
+
+- [ ] **Step 5: Refactor and verify the seam**
+
+Group wire-only types separately from capability methods in `interrupts.ts`, keep `parentRunId` optional for non-resume requests, and rerun the focused commands. Run `pnpm --filter @tanstack/ai test:lib -- --run tests/custom-events-integration.test.ts` and expect PASS to prove deprecated types remain readable.
+
+### Task 4: Replace sequential persistence with the atomic reference contract
+
+**Prerequisites:** Task 3.
+
+**Files:**
+- Modify: `packages/ai-persistence/src/types.ts:36-55,139,255-287`
+- Modify: `packages/ai-persistence/src/interrupts.ts`
+- Modify: `packages/ai-persistence/src/capabilities.ts`
+- Modify: `packages/ai-persistence/src/memory.ts:65-126,355`
+- Modify: `packages/ai-persistence/src/testkit/conformance.ts:114-184`
+- Modify: `packages/ai-persistence/src/index.ts`
+- Modify: `packages/ai-persistence/tests/interrupts.test.ts`
+- Modify: `packages/ai-persistence/tests/memory.conformance.test.ts`
+- Modify: `packages/ai-persistence/tests/with-persistence.test.ts`
+- Modify: `packages/ai-persistence/tests/persistence-validation.test.ts`
+- Modify: `packages/ai-persistence/tests/persistence-types.test-d.ts`
+
+- [ ] **Step 1: Rewrite the shared conformance tests to fail on sequential stores**
+
+Replace the interrupt conformance block with complete-batch cases. Use stable IDs per test so adapters can run the same suite:
+
+```ts
+it('commits all responses, replays exactly, and rejects a different writer', async () => {
+  const store = persistence.stores.interrupts
+  expect(store, 'interrupt conformance requires stores.interrupts').toBeDefined()
+  if (!store) throw new Error('interrupt store missing')
+  const opened = await store.openInterruptBatch({
+    threadId: 'thread-cas',
+    interruptedRunId: 'run-interrupted',
+    descriptors: [
+      { id: 'int-a', reason: 'confirmation' },
+      { id: 'int-b', reason: 'input_required' },
+    ],
+    bindings: [
+      { interruptId: 'int-a', kind: 'generic', responseSchemaHash: 'v1:a' },
+      { interruptId: 'int-b', kind: 'generic', responseSchemaHash: 'v1:b' },
+    ],
+  })
+  const resolutions = [
+    { interruptId: 'int-b', status: 'cancelled' },
+    { interruptId: 'int-a', status: 'resolved', payload: { ok: true } },
+  ] as const
+  const canonical = canonicalizeInterruptResolutions(resolutions)
+  const input = {
+    threadId: 'thread-cas',
+    interruptedRunId: 'run-interrupted',
+    continuationRunId: 'run-continuation-a',
+    expectedGeneration: opened.generation,
+    expectedInterruptIds: ['int-b', 'int-a'],
+    resolutions: canonical.resolutions,
+    fingerprint: canonical.fingerprint,
+    canonicalResolutions: canonical.canonicalResolutions,
+  }
+
+  await expect(store.commitInterruptResolutions(input)).resolves.toEqual({
+    status: 'committed',
+    continuationRunId: 'run-continuation-a',
+  })
+  await expect(
+    store.commitInterruptResolutions({
+      ...input,
+      continuationRunId: 'ignored-on-replay',
+    }),
+  ).resolves.toEqual({
+    status: 'replayed',
+    continuationRunId: 'run-continuation-a',
+  })
+  await expect(
+    store.commitInterruptResolutions({
+      ...input,
+      continuationRunId: 'run-continuation-b',
+      resolutions: [
+        { interruptId: 'int-a', status: 'cancelled' },
+        { interruptId: 'int-b', status: 'cancelled' },
+      ],
+      fingerprint: canonicalizeInterruptResolutions([
+        { interruptId: 'int-a', status: 'cancelled' },
+        { interruptId: 'int-b', status: 'cancelled' },
+      ]).fingerprint,
+      canonicalResolutions: canonicalizeInterruptResolutions([
+        { interruptId: 'int-a', status: 'cancelled' },
+        { interruptId: 'int-b', status: 'cancelled' },
+      ]).canonicalResolutions,
+    }),
+  ).resolves.toMatchObject({ status: 'conflict' })
+})
+```
+
+Define the testkit contract and fixtures in `src/testkit/conformance.ts`; the store is required and no case may return early:
+
+```ts
+export interface InterruptConformanceHarness {
+  getStore(): InterruptStore | undefined
+  advanceBy(milliseconds: number): void
+  inspect(interruptedRunId: string): Promise<{
+    statuses: readonly string[]
+    batchCount: number
+  }>
+  failTransitionOnce(interruptId: string): void
+  reopen?(): Promise<InterruptStore>
+}
+
+export async function openTwoInterrupts(store: InterruptStore) {
+  return store.openInterruptBatch({
+    threadId: 'thread-cas',
+    interruptedRunId: 'run-interrupted',
+    descriptors: [
+      { id: 'int-a', reason: 'confirmation' },
+      {
+        id: 'int-b',
+        reason: 'input_required',
+        expiresAt: '2026-07-13T10:01:00.000Z',
+      },
+    ],
+    bindings: [
+      { interruptId: 'int-a', kind: 'generic', responseSchemaHash: 'sha256:a' },
+      {
+        interruptId: 'int-b',
+        kind: 'generic',
+        responseSchemaHash: 'sha256:b',
+        expiresAt: '2026-07-13T10:01:00.000Z',
+      },
+    ],
+  })
+}
+
+export function validTwoItemCommit(
+  generation: number,
+  continuationRunId = 'run-continuation-a',
+): CommitInterruptResolutionsInput {
+  const candidate = canonicalizeInterruptResolutions([
+    { interruptId: 'int-b', status: 'cancelled' },
+    { interruptId: 'int-a', status: 'resolved', payload: { ok: true } },
+  ])
+  return {
+    threadId: 'thread-cas',
+    interruptedRunId: 'run-interrupted',
+    continuationRunId,
+    expectedGeneration: generation,
+    expectedInterruptIds: ['int-b', 'int-a'],
+    resolutions: candidate.resolutions,
+    fingerprint: candidate.fingerprint,
+    canonicalResolutions: candidate.canonicalResolutions,
+  }
+}
+
+export function runInterruptStoreConformance(
+  createHarness: () => Promise<InterruptConformanceHarness>,
+): void {
+  it('requires the atomic interrupt capability', async () => {
+    const harness = await createHarness()
+    expect(
+      harness.getStore(),
+      'interrupt conformance requires stores.interrupts',
+    ).toBeDefined()
+    if (!harness.getStore()) throw new Error('interrupt store missing')
+  })
+
+  it('keeps canonical order stable and rejects malformed exact sets', async () => {
+    const harness = await createHarness()
+    const store = harness.getStore()
+    if (!store) throw new Error('interrupt store missing')
+    const opened = await openTwoInterrupts(store)
+    const ordered = validTwoItemCommit(opened.generation)
+    const reordered = canonicalizeInterruptResolutions([
+      { interruptId: 'int-a', status: 'resolved', payload: { ok: true } },
+      { interruptId: 'int-b', status: 'cancelled' },
+    ])
+    expect(reordered.fingerprint).toBe(ordered.fingerprint)
+    expect(reordered.canonicalResolutions).toBe(ordered.canonicalResolutions)
+    for (const expectedInterruptIds of [
+      ['int-a'],
+      ['int-a', 'int-b', 'int-c'],
+      ['int-a', 'int-a'],
+    ]) {
+      await expect(store.commitInterruptResolutions({
+        ...ordered,
+        expectedInterruptIds,
+      })).resolves.toMatchObject({ status: 'conflict' })
+    }
+    await expect(store.commitInterruptResolutions({
+      ...ordered,
+      expectedGeneration: opened.generation + 1,
+    })).resolves.toMatchObject({ status: 'conflict' })
+  })
+
+  it('rolls back every row when a transition fails', async () => {
+    const harness = await createHarness()
+    const store = harness.getStore()
+    if (!store) throw new Error('interrupt store missing')
+    const opened = await openTwoInterrupts(store)
+    harness.failTransitionOnce('int-b')
+    await expect(
+      store.commitInterruptResolutions(validTwoItemCommit(opened.generation)),
+    ).rejects.toThrow()
+    await expect(harness.inspect('run-interrupted')).resolves.toEqual({
+      statuses: ['pending', 'pending'],
+      batchCount: 0,
+    })
+  })
+
+  it('projects pending, committed replay, restart, and one concurrent winner', async () => {
+    const harness = await createHarness()
+    const store = harness.getStore()
+    if (!store) throw new Error('interrupt store missing')
+    const opened = await openTwoInterrupts(store)
+    await expect(store.getInterruptRecoveryState({
+      threadId: 'thread-cas',
+      interruptedRunId: 'run-interrupted',
+      knownGeneration: opened.generation,
+    })).resolves.toMatchObject({
+      state: 'pending',
+      generation: opened.generation,
+    })
+
+    const first = validTwoItemCommit(opened.generation, 'run-continuation-a')
+    const secondCandidate = canonicalizeInterruptResolutions([
+      { interruptId: 'int-a', status: 'cancelled' },
+      { interruptId: 'int-b', status: 'cancelled' },
+    ])
+    const second = {
+      ...first,
+      continuationRunId: 'run-continuation-b',
+      resolutions: secondCandidate.resolutions,
+      fingerprint: secondCandidate.fingerprint,
+      canonicalResolutions: secondCandidate.canonicalResolutions,
+    }
+    const results = await Promise.all([
+      store.commitInterruptResolutions(first),
+      store.commitInterruptResolutions(second),
+    ])
+    expect(results.map((result) => result.status).sort()).toEqual([
+      'committed',
+      'conflict',
+    ])
+    const winningRunId = results.find(
+      (result) => result.status === 'committed',
+    )?.continuationRunId
+    expect(winningRunId).toBeDefined()
+    const replayInput = winningRunId === 'run-continuation-a' ? first : second
+    await expect(store.commitInterruptResolutions({
+      ...replayInput,
+      continuationRunId: 'ignored-replay-run',
+    })).resolves.toEqual({
+      status: 'replayed',
+      continuationRunId: winningRunId,
+    })
+
+    const recoveredStore = harness.reopen ? await harness.reopen() : store
+    await expect(recoveredStore.getInterruptRecoveryState({
+      threadId: 'thread-cas',
+      interruptedRunId: 'run-interrupted',
+      knownGeneration: opened.generation,
+    })).resolves.toMatchObject({
+      state: 'committed',
+      committed: { continuationRunId: winningRunId },
+    })
+  })
+
+  it('marks an uncommitted expired batch expired', async () => {
+    const harness = await createHarness()
+    const store = harness.getStore()
+    if (!store) throw new Error('interrupt store missing')
+    const opened = await openTwoInterrupts(store)
+    harness.advanceBy(60_001)
+    await expect(
+      store.commitInterruptResolutions(validTwoItemCommit(opened.generation)),
+    ).resolves.toMatchObject({
+      status: 'conflict',
+      authoritativeState: { state: 'expired' },
+    })
+  })
+}
+```
+
+Memory omits `reopen` to make process-local loss explicit. Drizzle, Prisma, and Cloudflare supply it and must recover the committed winner. Every harness supplies `failTransitionOnce`; it may wrap the store at the gateway boundary so production adapters do not expose a test-only option. No conformance case returns early.
+
+- [ ] **Step 2: Run the red persistence targets**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-persistence test:lib -- --run tests/interrupts.test.ts tests/memory.conformance.test.ts tests/with-persistence.test.ts tests/persistence-validation.test.ts
+pnpm --filter @tanstack/ai-persistence test:types
+```
+
+Expected: FAIL because `openInterruptBatch`, `commitInterruptResolutions`, recovery, generation, and `fingerprintInterruptResolutions` are missing.
+
+- [ ] **Step 3: Define the store records and capability alias**
+
+Make `InterruptStore` extend the core gateway and retain read methods only; remove sequential `resolve`/`cancel` as a middleware path:
+
+```ts
+export interface InterruptRecord {
+  interruptId: string
+  runId: string
+  threadId: string
+  generation: number
+  status: 'pending' | 'resolved' | 'cancelled'
+  requestedAt: number
+  resolvedAt?: number
+  payload: unknown
+  binding: InterruptBinding
+  response?: unknown
+}
+
+export interface InterruptBatchRecord {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  expectedInterruptIds: readonly string[]
+  fingerprint: string
+  canonicalResolutions: string
+  resolutions: readonly RunAgentResumeItem[]
+  continuationRunId: string
+  committedAt: number
+}
+
+export interface InterruptStore extends InterruptPersistenceGateway {
+  get(interruptId: string): Promise<InterruptRecord | null>
+  list(threadId: string): Promise<InterruptRecord[]>
+  listPending(threadId: string): Promise<InterruptRecord[]>
+  listByRun(runId: string): Promise<InterruptRecord[]>
+  listPendingByRun(runId: string): Promise<InterruptRecord[]>
+}
+```
+
+In `capabilities.ts`, stop constructing a second interrupt token. Re-export the core `InterruptPersistenceCapability`, `getInterruptPersistence`, and `provideInterruptPersistence`. Keep `InterruptsCapability`, `getInterrupts`, and `provideInterrupts` as deprecated aliases referencing those exact same values until 1.0.
+
+- [ ] **Step 4: Implement exact-set helpers and consume the core identity**
+
+Delete persistence-owned canonicalization and FNV. Import `canonicalizeInterruptResolutions` and `cloneAndDeepFreezeJson` from `@tanstack/ai`; persistence owns only exact-set checks:
+
+```ts
+export class InterruptStoreCorruptionError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'InterruptStoreCorruptionError'
+  }
+}
+
+export function hasExactInterruptIds(
+  expected: readonly string[],
+  actual: readonly string[],
+): boolean {
+  const left = [...new Set(expected)].sort()
+  const right = [...new Set(actual)].sort()
+  return left.length === expected.length &&
+    right.length === actual.length &&
+    left.length === right.length &&
+    left.every((id, index) => id === right[index])
+}
+
+export function projectInterruptRecovery(input: {
+  query: InterruptRecoveryQuery
+  rows: readonly InterruptRecord[]
+  batch: InterruptBatchRecord | null
+  now: number
+  includeResolutions: boolean
+}): InterruptRecoveryStateV1 {
+  const correlation = {
+    schemaVersion: 1 as const,
+    threadId: input.query.threadId,
+    interruptedRunId: input.query.interruptedRunId,
+    generation:
+      input.batch?.generation ??
+      input.rows[0]?.generation ??
+      input.query.knownGeneration,
+    pendingInterrupts: [] as readonly Interrupt[],
+  }
+  if (input.batch) {
+    return cloneAndDeepFreezeJson({
+      ...correlation,
+      state: 'committed',
+      committed: {
+        fingerprint: input.batch.fingerprint,
+        ...(input.includeResolutions && {
+          resolutions: input.batch.resolutions,
+        }),
+        continuationRunId: input.batch.continuationRunId,
+        committedAt: new Date(input.batch.committedAt).toISOString(),
+      },
+    })
+  }
+  if (input.rows.length === 0) {
+    return cloneAndDeepFreezeJson({ ...correlation, state: 'missing' })
+  }
+  const pending = input.rows.filter((row) => row.status === 'pending')
+  if (pending.length > 0) {
+    const expired = pending.some(
+      (row) =>
+        row.binding.expiresAt !== undefined &&
+        Date.parse(row.binding.expiresAt) <= input.now,
+    )
+    return cloneAndDeepFreezeJson({
+      ...correlation,
+      state: expired ? 'expired' : 'pending',
+      pendingInterrupts: expired
+        ? []
+        : pending.map((row) => row.payload as Interrupt),
+    })
+  }
+  return cloneAndDeepFreezeJson({
+    ...correlation,
+    state: 'legacy-committed',
+  })
+}
+```
+
+Before any store operation, recompute `canonicalizeInterruptResolutions(input.resolutions)` and require both its digest and canonical bytes to equal `input.fingerprint` and `input.canonicalResolutions`. Replay requires stored digest equality **and** stored canonical-byte equality, so a digest alone never proves identity. Memory and every durable adapter call `projectInterruptRecovery` from inside their run lock/transaction with rows and winner read from that same snapshot; its five branches are exercised by the shared conformance suite and the migrated-legacy tests.
+
+- [ ] **Step 5: Implement the memory critical section and immutable winner**
+
+Use maps keyed by `interruptedRunId` plus a per-key promise chain. `openInterruptBatch` writes every descriptor or none, stamps generation `1` and schema identity into returned descriptors, and returns an existing identical pending batch idempotently. `commitInterruptResolutions` executes inside the same critical section:
+
+```ts
+return this.withInterruptLock(input.interruptedRunId, async () => {
+  const candidate = canonicalizeInterruptResolutions(input.resolutions)
+  if (
+    candidate.fingerprint !== input.fingerprint ||
+    candidate.canonicalResolutions !== input.canonicalResolutions
+  ) {
+    throw new TypeError('Interrupt batch identity does not match its resolutions.')
+  }
+  const winner = this.batches.get(input.interruptedRunId)
+  if (winner) {
+    return winner.fingerprint === input.fingerprint &&
+      winner.canonicalResolutions === input.canonicalResolutions
+      ? { status: 'replayed', continuationRunId: winner.continuationRunId }
+      : {
+          status: 'conflict',
+          authoritativeState: this.recoveryFromWinner(winner),
+        }
+  }
+  const pending = this.pendingForRun(input.interruptedRunId)
+  if (
+    !hasExactInterruptIds(
+      input.expectedInterruptIds,
+      pending.map((record) => record.interruptId),
+    ) ||
+    pending.some((record) => record.generation !== input.expectedGeneration) ||
+    pending.some((record) =>
+      record.binding.expiresAt !== undefined &&
+      Date.parse(record.binding.expiresAt) <= this.clock(),
+    )
+  ) {
+    return {
+      status: 'conflict',
+      authoritativeState: this.recoveryForRun(input),
+    }
+  }
+  const committedAt = this.clock()
+  const nextInterrupts = new Map(this.interrupts)
+  for (const resolution of candidate.resolutions) {
+    const current = nextInterrupts.get(resolution.interruptId)
+    if (
+      !current ||
+      current.runId !== input.interruptedRunId ||
+      current.status !== 'pending' ||
+      current.generation !== input.expectedGeneration
+    ) {
+      throw new Error(`Pending interrupt changed: ${resolution.interruptId}`)
+    }
+    nextInterrupts.set(
+      resolution.interruptId,
+      cloneAndDeepFreezeJson({
+        ...current,
+        status: resolution.status === 'cancelled' ? 'cancelled' : 'resolved',
+        response: resolution,
+        resolvedAt: committedAt,
+      }),
+    )
+  }
+  const immutableWinner = cloneAndDeepFreezeJson({
+    ...input,
+    resolutions: candidate.resolutions,
+    canonicalResolutions: candidate.canonicalResolutions,
+    fingerprint: candidate.fingerprint,
+    committedAt,
+  })
+  const nextBatches = new Map(this.batches)
+  nextBatches.set(input.interruptedRunId, immutableWinner)
+
+  // Publish only after every row and winner has been validated and built.
+  this.interrupts = nextInterrupts
+  this.batches = nextBatches
+  return {
+    status: 'committed',
+    continuationRunId: input.continuationRunId,
+  }
+})
+```
+
+`openInterruptBatch` runs under the same per-run lock: verify descriptor/binding exact IDs and correlations, build a cloned next interrupt map and frozen descriptor snapshot, and publish the map only after every record is built. `getInterruptRecoveryState` reads one locked snapshot and returns `pending`, `committed`, `expired`, `missing`, or `legacy-committed` without exposing mutable store objects.
+
+- [ ] **Step 6: Reject non-atomic custom stores and export the new helpers**
+
+Update `defineAIPersistence` validation so an interrupt store lacking all three gateway methods throws `atomic-commit-unsupported`; do not adapt `resolve`/`cancel` sequentially. Re-export new types/helpers and update `createInterruptController` to expose `openInterruptBatch`, `commitInterruptResolutions`, `getInterruptRecoveryState`, and pending reads only.
+
+- [ ] **Step 7: Run green persistence checks and refactor**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-persistence test:lib -- --run tests/interrupts.test.ts tests/memory.conformance.test.ts tests/with-persistence.test.ts tests/persistence-validation.test.ts
+pnpm --filter @tanstack/ai-persistence test:types
+```
+
+Expected: PASS; the concurrency test has one winner, replay returns its continuation ID, and fault injection leaves every row pending. Refactor duplicated recovery construction into pure helpers and rerun both commands.
+
+### Task 5: Implement transactional CAS and migrations for Drizzle SQLite
+
+**Prerequisites:** Task 4.
+
+**Files:**
+- Modify: `packages/ai-persistence-drizzle/src/schema.ts:65-78,115-125`
+- Modify: `packages/ai-persistence-drizzle/src/stores.ts:1-38,196-286`
+- Modify: `packages/ai-persistence-drizzle/src/index.ts`
+- Modify: `packages/ai-persistence-drizzle/src/sqlite.ts`
+- Modify: `packages/ai-persistence-drizzle/src/migrations.ts`
+- Create: `packages/ai-persistence-drizzle/drizzle/0001_tanstack_ai_interrupt_batches.sql`
+- Create: `packages/ai-persistence-drizzle/drizzle/meta/0001_snapshot.json`
+- Modify: `packages/ai-persistence-drizzle/drizzle/meta/_journal.json`
+- Create: `packages/ai-persistence-drizzle/src/assets/0001_tanstack_ai_interrupt_batches.sql`
+- Modify: `packages/ai-persistence-drizzle/tests/drizzle.conformance.test.ts`
+- Modify: `packages/ai-persistence-drizzle/tests/migrations.test.ts`
+- Modify: `packages/ai-persistence-drizzle/tests/migration-cli.test.ts`
+- Modify: `packages/ai-persistence-drizzle/tests/api-types.test-d.ts`
+
+- [ ] **Step 1: Add failing adapter and nonempty-migration tests**
+
+Extend the shared conformance invocation and assert historical rows migrate deterministically:
+
+```ts
+it('backfills pending generation and identifies historical commits', () => {
+  const db = new DatabaseSync(':memory:')
+  applySqliteMigrations(db, [sqliteMigrations[0]])
+  const binding = {
+    kind: 'generic',
+    interruptId: 'pending',
+    interruptedRunId: 'run-p',
+    generation: 1,
+    responseSchemaHash: 'sha256:pending',
+  }
+  const descriptor = {
+    id: 'pending',
+    reason: 'confirmation',
+    responseSchema: { type: 'object', required: ['approved'] },
+  }
+  const insert = db.prepare(`INSERT INTO interrupts (
+    interrupt_id, run_id, thread_id, status, requested_at,
+    resolved_at, payload_json, response_json
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+  insert.run('pending', 'run-p', 'thread', 'pending', 1, null, JSON.stringify(descriptor), null)
+  insert.run('done', 'run-d', 'thread', 'resolved', 1, 2, '{}', '{}')
+  applySqliteMigrations(db, [sqliteMigrations[1]])
+
+  expect(db.prepare('SELECT generation FROM interrupts WHERE interrupt_id = ?').get('pending')).toEqual({ generation: 1 })
+  expect(db.prepare('SELECT generation FROM interrupts WHERE interrupt_id = ?').get('done')).toEqual({ generation: 0 })
+  expect(db.prepare('SELECT COUNT(*) AS count FROM interrupt_batches').get()).toEqual({ count: 0 })
+  const migrated = db.prepare(
+    'SELECT status, generation, binding_json FROM interrupts WHERE interrupt_id = ?',
+  ).get('pending')
+  expect(migrated).toMatchObject({ status: 'pending', generation: 1 })
+  expect(JSON.parse(String(migrated.binding_json))).toEqual({
+    ...binding,
+    responseSchemaHash: expect.stringMatching(/^legacy-json:/),
+  })
+  expect(
+    db.prepare(
+      'SELECT payload_json FROM interrupts WHERE interrupt_id = ? AND status = ?',
+    ).get('pending', 'pending'),
+  ).toEqual({ payload_json: JSON.stringify(descriptor) })
+})
+
+it('upgrades all legacy pending descriptors atomically', () => {
+  const db = new DatabaseSync(':memory:')
+  applySqliteMigrations(db, [sqliteMigrations[0]])
+  db.prepare(`INSERT INTO interrupts (
+    interrupt_id, run_id, thread_id, status, requested_at, payload_json
+  ) VALUES (?, ?, ?, ?, ?, ?)`)
+    .run(
+      'legacy-tool',
+      'run-legacy',
+      'thread',
+      'pending',
+      1,
+      JSON.stringify({
+        id: 'legacy-tool',
+        reason: 'approval_required',
+        toolCallId: 'call-legacy',
+        responseSchema: {
+          type: 'object',
+          properties: { approved: { type: 'boolean' } },
+          required: ['approved'],
+        },
+        metadata: { kind: 'approval', toolName: 'transfer', input: { cents: 5 } },
+      }),
+    )
+  expect(() => applySqliteMigrations(db, [sqliteMigrations[1]])).not.toThrow()
+  const rows = db.prepare(
+    'SELECT status, generation, binding_json FROM interrupts WHERE run_id = ?',
+  ).all('run-legacy')
+  expect(rows).toHaveLength(1)
+  expect(rows[0]).toMatchObject({ status: 'pending', generation: 1 })
+  expect(JSON.parse(String(rows[0]?.binding_json))).toMatchObject({
+    kind: 'generic',
+    interruptId: 'legacy-tool',
+    interruptedRunId: 'run-legacy',
+    generation: 1,
+  })
+})
+```
+
+- [ ] **Step 2: Run the red Drizzle targets**
+
+Run:
+
+```powershell
+pnpm --filter @tanstack/ai-persistence-drizzle test:lib -- --run tests/drizzle.conformance.test.ts tests/migrations.test.ts tests/migration-cli.test.ts
+pnpm --filter @tanstack/ai-persistence-drizzle test:types
+```
+
+Expected: FAIL because the schema lacks generation/binding/batch columns and the store lacks atomic gateway methods.
+
+- [ ] **Step 3: Add schema and an explicit transaction executor**
+
+Add `generation`, `bindingJson`, and `responseSchemaHash` to `interrupts`; add an `interruptBatches` table keyed by interrupted run with a unique continuation ID. Do not claim atomicity from the schema-agnostic `DrizzleDb` alone:
+
+```ts
+export interface DrizzleTransactionExecutor {
+  transaction<T>(work: (tx: DrizzleDb) => Promise<T>): Promise<T>
+}
+
+export function createInterruptStore(
+  db: DrizzleDb,
+  executor: DrizzleTransactionExecutor,
+): InterruptStore
+
+export function drizzlePersistence(
+  db: DrizzleDb,
+  options: { interruptTransactions: DrizzleTransactionExecutor },
+)
+```
+
+The Node factory must serialize asynchronous transaction callbacks per connection:
+
+```ts
+export function createSerializedSqliteExecutor(
+  database: DatabaseSync,
+  db: DrizzleDb,
+): DrizzleTransactionExecutor {
+  let tail: Promise<void> = Promise.resolve()
+  return {
+    transaction<T>(work: (tx: DrizzleDb) => Promise<T>): Promise<T> {
+      const run = tail.then(async () => {
+        database.exec('BEGIN IMMEDIATE')
+        try {
+          const value = await work(db)
+          database.exec('COMMIT')
+          return value
+        } catch (error) {
+          database.exec('ROLLBACK')
+          throw error
+        }
+      })
+      tail = run.then(() => undefined, () => undefined)
+      return run
+    },
+  }
+}
+```
+
+`sqlitePersistence` constructs exactly one executor per `DatabaseSync`. `drizzlePersistence` requires `interruptTransactions` whenever interrupts are enabled and throws `atomic-commit-unsupported` during construction if it is absent.
+
+- [ ] **Step 4: Implement the transaction and exact replay**
+
+Implement `openInterruptBatch`, `commitInterruptResolutions`, and `getInterruptRecoveryState` through this executor. The commit body is:
+
+```ts
+return executor.transaction(async (tx) => {
+  const existing = await tx.select().from(interruptBatches)
+    .where(eq(interruptBatches.interruptedRunId, input.interruptedRunId)).get()
+  if (existing) {
+    if (
+      existing.fingerprint === input.fingerprint &&
+      existing.resolutionsJson === input.canonicalResolutions
+    ) {
+      return { status: 'replayed', continuationRunId: existing.continuationRunId }
+    }
+    return { status: 'conflict', authoritativeState: recoveryFromBatch(existing) }
+  }
+  const pending = await tx.select().from(interrupts).where(and(
+    eq(interrupts.runId, input.interruptedRunId),
+    eq(interrupts.status, 'pending'),
+  )).all()
+  const now = clock()
+  if (
+    !hasExactInterruptIds(input.expectedInterruptIds, pending.map((row) => row.interruptId)) ||
+    pending.some((row) => row.generation !== input.expectedGeneration) ||
+    pending.some((row) => isExpiredBindingJson(row.bindingJson, now))
+  ) {
+    return { status: 'conflict', authoritativeState: recoveryFromRows(input, pending, now) }
+  }
+  await tx.insert(interruptBatches).values({
+    interruptedRunId: input.interruptedRunId,
+    threadId: input.threadId,
+    generation: input.expectedGeneration,
+    expectedInterruptIdsJson: JSON.stringify([...input.expectedInterruptIds].sort()),
+    fingerprint: input.fingerprint,
+    resolutionsJson: input.canonicalResolutions,
+    continuationRunId: input.continuationRunId,
+    committedAt: now,
+  }).run()
+  for (const resolution of input.resolutions) {
+    const result = await tx.update(interrupts).set({
+      status: resolution.status === 'cancelled' ? 'cancelled' : 'resolved',
+      responseJson: resolution,
+      resolvedAt: now,
+    }).where(and(
+      eq(interrupts.interruptId, resolution.interruptId),
+      eq(interrupts.runId, input.interruptedRunId),
+      eq(interrupts.status, 'pending'),
+      eq(interrupts.generation, input.expectedGeneration),
+    )).run()
+    if (result.changes !== 1) throw new Error('interrupt CAS row changed')
+  }
+  return { status: 'committed', continuationRunId: input.continuationRunId }
+})
+```
+
+`openInterruptBatch` and recovery use the same executor and the shared projection:
+
+```ts
+async function openInterruptBatch(
+  input: OpenInterruptBatchInput,
+): Promise<{ generation: number; descriptors: readonly Interrupt[] }> {
+  if (!hasExactInterruptIds(
+    input.descriptors.map((descriptor) => descriptor.id),
+    input.bindings.map((binding) => binding.interruptId),
+  )) {
+    throw new TypeError('Interrupt descriptors and bindings must have exact IDs.')
+  }
+  return executor.transaction(async (tx) => {
+    const existing = await tx.select().from(interrupts).where(
+      eq(interrupts.runId, input.interruptedRunId),
+    ).all()
+    if (existing.length > 0) {
+      const existingIds = existing.map((row) => row.interruptId)
+      if (!hasExactInterruptIds(existingIds, input.descriptors.map((item) => item.id))) {
+        throw new Error('Interrupt batch already opened with a different set.')
+      }
+      return {
+        generation: existing[0]?.generation ?? 1,
+        descriptors: cloneAndDeepFreezeJson(
+          existing.map((row) => JSON.parse(row.payloadJson) as Interrupt),
+        ),
+      }
+    }
+
+    const generation = 1
+    const bindings = new Map(input.bindings.map((binding) => [
+      binding.interruptId,
+      cloneAndDeepFreezeJson({
+        ...binding,
+        interruptedRunId: input.interruptedRunId,
+        generation,
+      } satisfies InterruptBinding),
+    ]))
+    const descriptors = input.descriptors.map((descriptor) => {
+      const binding = bindings.get(descriptor.id)
+      if (!binding) throw new Error(`Missing binding for ${descriptor.id}`)
+      return cloneAndDeepFreezeJson({
+        ...descriptor,
+        metadata: { ...descriptor.metadata, 'tanstack:binding': binding },
+      })
+    })
+    await tx.insert(interrupts).values(descriptors.map((descriptor) => {
+      const binding = bindings.get(descriptor.id)
+      if (!binding) throw new Error(`Missing binding for ${descriptor.id}`)
+      return {
+        interruptId: descriptor.id,
+        runId: input.interruptedRunId,
+        threadId: input.threadId,
+        generation,
+        status: 'pending',
+        requestedAt: clock(),
+        payloadJson: JSON.stringify(descriptor),
+        bindingJson: JSON.stringify(binding),
+        responseSchemaHash: binding.responseSchemaHash,
+      }
+    })).run()
+    return { generation, descriptors: cloneAndDeepFreezeJson(descriptors) }
+  })
+}
+
+async function getInterruptRecoveryState(
+  query: InterruptRecoveryQuery,
+): Promise<InterruptRecoveryStateV1> {
+  return executor.transaction(async (tx) => {
+    const batchRow = await tx.select().from(interruptBatches).where(
+      eq(interruptBatches.interruptedRunId, query.interruptedRunId),
+    ).get()
+    const rows = await tx.select().from(interrupts).where(
+      eq(interrupts.runId, query.interruptedRunId),
+    ).orderBy(interrupts.interruptId).all()
+    return projectInterruptRecovery({
+      query,
+      batch: batchRow ? decodeInterruptBatchRow(batchRow) : null,
+      rows: rows.map(decodeInterruptRow),
+      now: clock(),
+      includeResolutions: true,
+    })
+  })
+}
+```
+
+Define the decoders beside the store; these names are used by the preceding methods:
+
+```ts
+function parseJsonRecord(value: string, label: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(value)
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new TypeError(`${label} must contain a JSON object.`)
+    }
+    return parsed as Record<string, unknown>
+  } catch (cause) {
+    throw new InterruptStoreCorruptionError(`Invalid ${label}.`, { cause })
+  }
+}
+
+function decodeInterruptRow(
+  row: typeof interrupts.$inferSelect,
+): InterruptRecord {
+  const payload = parseJsonRecord(row.payloadJson, 'interrupt payload')
+  const binding = parseJsonRecord(row.bindingJson, 'interrupt binding')
+  if (
+    binding['interruptId'] !== row.interruptId ||
+    binding['interruptedRunId'] !== row.runId ||
+    binding['generation'] !== row.generation
+  ) {
+    throw new InterruptStoreCorruptionError('Interrupt binding correlation mismatch.')
+  }
+  return cloneAndDeepFreezeJson({
+    interruptId: row.interruptId,
+    runId: row.runId,
+    threadId: row.threadId,
+    generation: row.generation,
+    status: row.status,
+    requestedAt: row.requestedAt,
+    ...(row.resolvedAt !== null && { resolvedAt: row.resolvedAt }),
+    payload,
+    binding,
+    ...(row.responseJson !== null && {
+      response: JSON.parse(row.responseJson) as unknown,
+    }),
+  }) as InterruptRecord
+}
+
+function decodeInterruptBatchRow(
+  row: typeof interruptBatches.$inferSelect,
+): InterruptBatchRecord {
+  const expectedInterruptIds: unknown = JSON.parse(row.expectedInterruptIdsJson)
+  const resolutions: unknown = JSON.parse(row.resolutionsJson)
+  if (!Array.isArray(expectedInterruptIds) || !Array.isArray(resolutions)) {
+    throw new InterruptStoreCorruptionError('Invalid interrupt batch arrays.')
+  }
+  const resolutionIds = resolutions.map((entry) => {
+    if (!entry || typeof entry !== 'object' || !('interruptId' in entry)) {
+      throw new InterruptStoreCorruptionError('Invalid interrupt batch resolution.')
+    }
+    return String(entry.interruptId)
+  })
+  if (!hasExactInterruptIds(expectedInterruptIds.map(String), resolutionIds)) {
+    throw new InterruptStoreCorruptionError('Interrupt batch ID set mismatch.')
+  }
+  return cloneAndDeepFreezeJson({
+    threadId: row.threadId,
+    interruptedRunId: row.interruptedRunId,
+    generation: row.generation,
+    expectedInterruptIds: expectedInterruptIds.map(String),
+    fingerprint: row.fingerprint,
+    canonicalResolutions: row.resolutionsJson,
+    resolutions,
+    continuationRunId: row.continuationRunId,
+    committedAt: row.committedAt,
+  }) as InterruptBatchRecord
+}
+```
+
+Direct tests assert `pending`, `committed`, `expired`, `missing`, and resolved-without-batch `legacy-committed`; expiry is evaluated inside the executor transaction.
+
+- [ ] **Step 5: Generate and package the numbered migration**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-persistence-drizzle db:generate -- --name tanstack_ai_interrupt_batches
+```
+
+Expected: Drizzle creates the `0001` SQL/meta entries. Ensure the SQL represented by both the generated file and packaged asset contains:
+
+```sql
+ALTER TABLE `interrupts` ADD `generation` integer NOT NULL DEFAULT 1;
+ALTER TABLE `interrupts` ADD `binding_json` text;
+ALTER TABLE `interrupts` ADD `response_schema_hash` text NOT NULL DEFAULT '';
+UPDATE `interrupts`
+SET `binding_json` = json_object(
+      'kind', 'generic',
+      'interruptId', `interrupt_id`,
+      'interruptedRunId', `run_id`,
+      'generation', 1,
+      'responseSchemaHash',
+        'legacy-json:' || COALESCE(json(json_extract(`payload_json`, '$.responseSchema')), 'null'),
+      'expiresAt', json_extract(`payload_json`, '$.expiresAt')
+    ),
+    `response_schema_hash` =
+      'legacy-json:' || COALESCE(json(json_extract(`payload_json`, '$.responseSchema')), 'null')
+WHERE `status` = 'pending';
+UPDATE `interrupts` SET `generation` = 0 WHERE `status` <> 'pending';
+CREATE TABLE `interrupt_batches` (
+  `interrupted_run_id` text PRIMARY KEY NOT NULL,
+  `thread_id` text NOT NULL,
+  `generation` integer NOT NULL,
+  `expected_interrupt_ids_json` text NOT NULL,
+  `fingerprint` text NOT NULL,
+  `resolutions_json` text NOT NULL,
+  `continuation_run_id` text NOT NULL UNIQUE,
+  `committed_at` integer NOT NULL
+);
+CREATE INDEX `interrupts_run_status_generation_idx` ON `interrupts` (`run_id`,`status`,`generation`);
+CREATE INDEX `interrupts_thread_status_idx` ON `interrupts` (`thread_id`,`status`);
+```
+
+In `migrations.test.ts`, read the generated SQL, packaged asset, `_journal.json`, and snapshot. Assert: journal entry tag is `0001_tanstack_ai_interrupt_batches`; snapshot contains `interrupt_batches` and both indexes; packaged SQL bytes equal generated SQL bytes; and `sqliteMigrations[1]` has the same ID, filename, and SQL. In `migration-cli.test.ts`, assert the CLI writes `0000` then `0001` with those exact bytes. Do not rename only the SQL; regenerate journal and snapshot together.
+
+- [ ] **Step 6: Run green adapter checks and refactor**
+
+Run:
+
+```powershell
+pnpm --filter @tanstack/ai-persistence-drizzle test:lib -- --run tests/drizzle.conformance.test.ts tests/migrations.test.ts tests/migration-cli.test.ts
+pnpm --filter @tanstack/ai-persistence-drizzle test:types
+```
+
+Expected: PASS; migration reruns are idempotent, CLI copies both files, and the conformance race has one winner. Extract row-to-recovery mapping, rerun both commands, and confirm no transaction accepts a partial expected set.
+
+### Task 6: Implement Prisma CAS and keep all schema copies identical
+
+**Prerequisites:** Task 4. May run after Task 5 once shared types settle.
+
+**Files:**
+- Modify: `packages/ai-persistence-prisma/src/stores.ts:200-300`
+- Modify: `packages/ai-persistence-prisma/prisma/schema.prisma`
+- Modify: `packages/ai-persistence-prisma/prisma/tanstack-ai.prisma`
+- Modify: `packages/ai-persistence-prisma/src/assets/tanstack-ai.prisma`
+- Modify: `packages/ai-persistence-prisma/tests/prisma.conformance.test.ts`
+- Modify: `packages/ai-persistence-prisma/tests/models.test.ts`
+- Modify: `packages/ai-persistence-prisma/tests/models-cli.test.ts`
+- Modify: `packages/ai-persistence-prisma/tests/api-types.test-d.ts`
+
+- [ ] **Step 1: Add failing schema-copy and transaction tests**
+
+Add assertions that all model fragments contain the batch model and are byte-identical where they are intended to be copied:
+
+```ts
+expect(prismaModels).toContain('model InterruptBatch')
+expect(prismaModels).toContain('generation Int @default(1)')
+expect(prismaModels).toContain('continuationRunId        String @unique')
+expect(copiedModels).toBe(prismaModels)
+```
+
+Run shared conformance with two Prisma clients submitting different complete batches concurrently.
+
+- [ ] **Step 2: Run the red Prisma targets**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-persistence-prisma db:generate
+pnpm --filter @tanstack/ai-persistence-prisma test:lib -- --run tests/prisma.conformance.test.ts tests/models.test.ts tests/models-cli.test.ts
+pnpm --filter @tanstack/ai-persistence-prisma test:types
+```
+
+Expected: tests FAIL because `InterruptBatch`, generation, and gateway methods are absent.
+
+- [ ] **Step 3: Update the three Prisma schema sources**
+
+Add the same fields to `Interrupt` in all copies and this provider-neutral model:
+
+```prisma
+model InterruptBatch {
+  interruptedRunId        String @id @map("interrupted_run_id")
+  threadId                 String @map("thread_id")
+  generation               Int
+  expectedInterruptIdsJson String @map("expected_interrupt_ids_json")
+  fingerprint              String
+  resolutionsJson          String @map("resolutions_json")
+  continuationRunId        String @unique @map("continuation_run_id")
+  committedAt              BigInt @map("committed_at")
+
+  @@map("interrupt_batches")
+}
+```
+
+Add `generation Int @default(1)`, `bindingJson String?`, `responseSchemaHash String @default("")`, plus run/status/generation and thread/status indexes to `Interrupt`.
+
+- [ ] **Step 4: Implement `$transaction` CAS**
+
+Use an interactive transaction with the exact-set decision inside it:
+
+```ts
+return prisma.$transaction(async (tx) => {
+  const winner = await tx.interruptBatch.findUnique({
+    where: { interruptedRunId: input.interruptedRunId },
+  })
+  if (winner) {
+    if (
+      winner.fingerprint === input.fingerprint &&
+      winner.resolutionsJson === input.canonicalResolutions
+    ) {
+      return { status: 'replayed', continuationRunId: winner.continuationRunId }
+    }
+    return { status: 'conflict', authoritativeState: recoveryFromPrismaBatch(winner) }
+  }
+
+  const pending = await tx.interrupt.findMany({
+    where: {
+      runId: input.interruptedRunId,
+      status: 'pending',
+      generation: input.expectedGeneration,
+    },
+    orderBy: { interruptId: 'asc' },
+  })
+  const now = clock()
+  if (
+    !hasExactInterruptIds(input.expectedInterruptIds, pending.map((row) => row.interruptId)) ||
+    pending.some((row) => bindingExpired(row.bindingJson, now))
+  ) {
+    return { status: 'conflict', authoritativeState: recoveryFromPrismaRows(input, pending, now) }
+  }
+  await tx.interruptBatch.create({
+    data: {
+      interruptedRunId: input.interruptedRunId,
+      threadId: input.threadId,
+      generation: input.expectedGeneration,
+      expectedInterruptIdsJson: JSON.stringify([...input.expectedInterruptIds].sort()),
+      fingerprint: input.fingerprint,
+      resolutionsJson: input.canonicalResolutions,
+      continuationRunId: input.continuationRunId,
+      committedAt: BigInt(now),
+    },
+  })
+  for (const resolution of input.resolutions) {
+    const updated = await tx.interrupt.updateMany({
+      where: {
+        interruptId: resolution.interruptId,
+        runId: input.interruptedRunId,
+        status: 'pending',
+        generation: input.expectedGeneration,
+      },
+      data: {
+        status: resolution.status === 'cancelled' ? 'cancelled' : 'resolved',
+        responseJson: JSON.stringify(resolution),
+        resolvedAt: BigInt(now),
+      },
+    })
+    if (updated.count !== 1) throw new Error('interrupt CAS row changed')
+  }
+  return {
+    status: 'committed',
+    continuationRunId: input.continuationRunId,
+  }
+})
+```
+
+Add these two gateway methods beside the commit method:
+
+```ts
+async function openInterruptBatch(
+  input: OpenInterruptBatchInput,
+): Promise<{ generation: number; descriptors: readonly Interrupt[] }> {
+  if (!hasExactInterruptIds(
+    input.descriptors.map((descriptor) => descriptor.id),
+    input.bindings.map((binding) => binding.interruptId),
+  )) {
+    throw new TypeError('Interrupt descriptors and bindings must have exact IDs.')
+  }
+  return prisma.$transaction(async (tx) => {
+    const existing = await tx.interrupt.findMany({
+      where: { runId: input.interruptedRunId },
+      orderBy: { interruptId: 'asc' },
+    })
+    if (existing.length > 0) {
+      if (!hasExactInterruptIds(
+        existing.map((row) => row.interruptId),
+        input.descriptors.map((descriptor) => descriptor.id),
+      )) {
+        throw new Error('Interrupt batch already opened with a different set.')
+      }
+      return {
+        generation: existing[0]?.generation ?? 1,
+        descriptors: cloneAndDeepFreezeJson(
+          existing.map((row) => JSON.parse(row.payloadJson) as Interrupt),
+        ),
+      }
+    }
+
+    const generation = 1
+    const unopened = new Map(
+      input.bindings.map((binding) => [binding.interruptId, binding]),
+    )
+    const descriptors = input.descriptors.map((descriptor) => {
+      const binding = unopened.get(descriptor.id)
+      if (!binding) throw new Error(`Missing binding for ${descriptor.id}`)
+      const authoritativeBinding = {
+        ...binding,
+        interruptedRunId: input.interruptedRunId,
+        generation,
+      } satisfies InterruptBinding
+      return {
+        descriptor: cloneAndDeepFreezeJson({
+          ...descriptor,
+          metadata: {
+            ...descriptor.metadata,
+            'tanstack:binding': authoritativeBinding,
+          },
+        }),
+        binding: authoritativeBinding,
+      }
+    })
+    await tx.interrupt.createMany({
+      data: descriptors.map(({ descriptor, binding }) => ({
+        interruptId: descriptor.id,
+        runId: input.interruptedRunId,
+        threadId: input.threadId,
+        generation,
+        status: 'pending',
+        requestedAt: BigInt(clock()),
+        payloadJson: JSON.stringify(descriptor),
+        bindingJson: JSON.stringify(binding),
+        responseSchemaHash: binding.responseSchemaHash,
+      })),
+    })
+    return {
+      generation,
+      descriptors: cloneAndDeepFreezeJson(
+        descriptors.map(({ descriptor }) => descriptor),
+      ),
+    }
+  })
+}
+
+async function getInterruptRecoveryState(
+  query: InterruptRecoveryQuery,
+): Promise<InterruptRecoveryStateV1> {
+  return prisma.$transaction(async (tx) => {
+    const batch = await tx.interruptBatch.findUnique({
+      where: { interruptedRunId: query.interruptedRunId },
+    })
+    const rawRows = await tx.interrupt.findMany({
+      where: { runId: query.interruptedRunId },
+      orderBy: { interruptId: 'asc' },
+    })
+    const rows = []
+    for (const row of rawRows) {
+      if (row.status === 'pending' && row.bindingJson === null) {
+        const descriptor: Interrupt = JSON.parse(row.payloadJson)
+        const responseSchemaHash = `legacy-json:${canonicalInterruptJson(
+          descriptor.responseSchema ?? null,
+        )}`
+        const binding = cloneAndDeepFreezeJson({
+          kind: 'generic',
+          interruptId: row.interruptId,
+          interruptedRunId: row.runId,
+          generation: row.generation,
+          responseSchemaHash,
+          ...(descriptor.expiresAt !== undefined && {
+            expiresAt: descriptor.expiresAt,
+          }),
+        } satisfies InterruptBinding)
+        await tx.interrupt.update({
+          where: { interruptId: row.interruptId },
+          data: {
+            bindingJson: JSON.stringify(binding),
+            responseSchemaHash,
+          },
+        })
+        rows.push(decodePrismaInterruptRow({ ...row, bindingJson: JSON.stringify(binding) }))
+      } else {
+        rows.push(decodePrismaInterruptRow(row))
+      }
+    }
+    return projectInterruptRecovery({
+      query,
+      batch: batch ? decodePrismaBatchRow(batch) : null,
+      rows,
+      now: clock(),
+      includeResolutions: true,
+    })
+  })
+}
+```
+
+Define the Prisma decoders used above:
+
+```ts
+type PrismaInterruptRow = {
+  interruptId: string
+  runId: string
+  threadId: string
+  generation: number
+  status: string
+  requestedAt: bigint
+  resolvedAt: bigint | null
+  payloadJson: string
+  bindingJson: string | null
+  responseJson: string | null
+}
+
+function decodePrismaInterruptRow(row: PrismaInterruptRow): InterruptRecord {
+  if (row.bindingJson === null) {
+    throw new InterruptStoreCorruptionError('Pending interrupt has no binding.')
+  }
+  const payload: unknown = JSON.parse(row.payloadJson)
+  const binding: unknown = JSON.parse(row.bindingJson)
+  if (
+    !binding ||
+    typeof binding !== 'object' ||
+    !('interruptId' in binding) ||
+    binding.interruptId !== row.interruptId ||
+    !('interruptedRunId' in binding) ||
+    binding.interruptedRunId !== row.runId ||
+    !('generation' in binding) ||
+    binding.generation !== row.generation
+  ) {
+    throw new InterruptStoreCorruptionError('Interrupt binding correlation mismatch.')
+  }
+  if (
+    row.status !== 'pending' &&
+    row.status !== 'resolved' &&
+    row.status !== 'cancelled'
+  ) {
+    throw new InterruptStoreCorruptionError('Invalid interrupt status.')
+  }
+  return cloneAndDeepFreezeJson({
+    interruptId: row.interruptId,
+    runId: row.runId,
+    threadId: row.threadId,
+    generation: row.generation,
+    status: row.status,
+    requestedAt: Number(row.requestedAt),
+    ...(row.resolvedAt !== null && { resolvedAt: Number(row.resolvedAt) }),
+    payload,
+    binding,
+    ...(row.responseJson !== null && {
+      response: JSON.parse(row.responseJson) as unknown,
+    }),
+  }) as InterruptRecord
+}
+
+type PrismaInterruptBatchRow = {
+  interruptedRunId: string
+  threadId: string
+  generation: number
+  expectedInterruptIdsJson: string
+  fingerprint: string
+  resolutionsJson: string
+  continuationRunId: string
+  committedAt: bigint
+}
+
+function decodePrismaBatchRow(
+  row: PrismaInterruptBatchRow,
+): InterruptBatchRecord {
+  const expected: unknown = JSON.parse(row.expectedInterruptIdsJson)
+  const resolutions: unknown = JSON.parse(row.resolutionsJson)
+  if (!Array.isArray(expected) || !Array.isArray(resolutions)) {
+    throw new InterruptStoreCorruptionError('Invalid interrupt batch arrays.')
+  }
+  const resolutionIds = resolutions.map((entry) => {
+    if (!entry || typeof entry !== 'object' || !('interruptId' in entry)) {
+      throw new InterruptStoreCorruptionError('Invalid interrupt resolution.')
+    }
+    return String(entry.interruptId)
+  })
+  if (!hasExactInterruptIds(expected.map(String), resolutionIds)) {
+    throw new InterruptStoreCorruptionError('Interrupt batch ID set mismatch.')
+  }
+  return cloneAndDeepFreezeJson({
+    interruptedRunId: row.interruptedRunId,
+    threadId: row.threadId,
+    generation: row.generation,
+    expectedInterruptIds: expected.map(String),
+    fingerprint: row.fingerprint,
+    canonicalResolutions: row.resolutionsJson,
+    resolutions,
+    continuationRunId: row.continuationRunId,
+    committedAt: Number(row.committedAt),
+  }) as InterruptBatchRecord
+}
+```
+
+The in-transaction legacy branch is the Prisma data migration path: it reconstructs a safe generic authoritative binding from the stored descriptor and persists it before returning `pending`; it never guesses a current tool binding.
+
+Catch a `P2002` unique race outside the commit transaction, reload the authoritative batch, and compare both fingerprint and canonical `resolutionsJson`; replay always returns the stored continuation ID. Invoke the shared conformance kit with a controllable clock, a faulting gateway wrapper, and a `reopen` that constructs a new Prisma client. Add a direct test that inserts a pending row with `bindingJson: null`, calls recovery, asserts the row was atomically upgraded to `kind: 'generic'`, and can then commit; add expiry-inside-transaction and resolved-without-batch `legacy-committed` tests. All three Prisma schema copies use the field-level `String @unique @map("continuation_run_id")` form shown above; no test or copy uses `@@unique([continuationRunId])`.
+
+- [ ] **Step 5: Generate the client and run green checks**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-persistence-prisma db:generate
+pnpm --filter @tanstack/ai-persistence-prisma test:lib -- --run tests/prisma.conformance.test.ts tests/models.test.ts tests/models-cli.test.ts
+pnpm --filter @tanstack/ai-persistence-prisma test:types
+```
+
+Expected: PASS; copied model output contains the new model, and concurrent writers produce one commit and one conflict.
+
+- [ ] **Step 6: Refactor and recheck**
+
+Centralize JSON serialization/deserialization for IDs, resolutions, and bindings, rerun the same commands, and verify docs in Task 17 instruct applications to generate and deploy their own Prisma migration before using the new package.
+
+### Task 7: Implement an atomic Cloudflare D1 conditional batch
+
+**Prerequisites:** Tasks 4 and 5 for shared schema/migration shape.
+
+**Files:**
+- Modify: `packages/ai-persistence-cloudflare/src/d1.ts`
+- Modify: `packages/ai-persistence-cloudflare/src/migrations.ts`
+- Create: `packages/ai-persistence-cloudflare/migrations/0001_tanstack_ai_interrupt_batches.sql`
+- Create: `packages/ai-persistence-cloudflare/src/assets/0001_tanstack_ai_interrupt_batches.sql`
+- Modify: `packages/ai-persistence-cloudflare/tests/runtime.conformance.test.ts`
+- Modify: `packages/ai-persistence-cloudflare/tests/migrations.test.ts`
+- Modify: `packages/ai-persistence-cloudflare/tests/migration-cli.test.ts`
+- Modify: `packages/ai-persistence-cloudflare/tests/api-types.test-d.ts`
+
+- [ ] **Step 1: Add failing D1 race, rollback, and migration tests**
+
+Invoke `runInterruptStoreConformance` with `createD1Stores(database).interrupts`, an injected clock, and a reopen callback that reuses the Miniflare database through a new store instance. Add this D1-only rollback assertion:
+
+```ts
+const store = createD1Stores(database, {
+  interruptTestHook: { failStatementForInterruptId: 'int-b' },
+}).interrupts
+if (!store) throw new Error('interrupt store missing')
+await openTwoInterrupts(store)
+await expect(store.commitInterruptResolutions(validTwoItemCommit())).rejects.toThrow(
+  /forced D1 statement failure/,
+)
+expect(await database.prepare('SELECT COUNT(*) AS count FROM interrupt_batches').first()).toEqual({ count: 0 })
+expect(await database.prepare("SELECT COUNT(*) AS count FROM interrupts WHERE status = 'pending'").first()).toEqual({ count: 2 })
+```
+
+The fixture functions `openTwoInterrupts` and `validTwoItemCommit` are exported by the shared conformance testkit created in Task 4; they contain the literal two descriptors/bindings and core-canonicalized commit input. Migration tests assert `0001` is bundled and copied after `0000`.
+
+- [ ] **Step 2: Run the red Cloudflare targets**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-persistence-cloudflare test:lib -- --run tests/runtime.conformance.test.ts tests/migrations.test.ts tests/migration-cli.test.ts
+pnpm --filter @tanstack/ai-persistence-cloudflare test:types
+```
+
+Expected: FAIL because `createD1Stores` delegates interrupts to a Drizzle store without an atomic executor and migration `0001` is missing.
+
+- [ ] **Step 3: Add and register the D1 migration**
+
+Both D1 migration locations contain these statements, including the same authoritative generic binding reconstruction for PR-head pending descriptors:
+
+```sql
+ALTER TABLE `interrupts` ADD `generation` integer NOT NULL DEFAULT 1;
+ALTER TABLE `interrupts` ADD `binding_json` text;
+ALTER TABLE `interrupts` ADD `response_schema_hash` text NOT NULL DEFAULT '';
+UPDATE `interrupts`
+SET `binding_json` = json_object(
+      'kind', 'generic',
+      'interruptId', `interrupt_id`,
+      'interruptedRunId', `run_id`,
+      'generation', 1,
+      'responseSchemaHash',
+        'legacy-json:' || COALESCE(json(json_extract(`payload_json`, '$.responseSchema')), 'null'),
+      'expiresAt', json_extract(`payload_json`, '$.expiresAt')
+    ),
+    `response_schema_hash` =
+      'legacy-json:' || COALESCE(json(json_extract(`payload_json`, '$.responseSchema')), 'null')
+WHERE `status` = 'pending';
+UPDATE `interrupts` SET `generation` = 0 WHERE `status` <> 'pending';
+CREATE TABLE `interrupt_batches` (
+  `interrupted_run_id` text PRIMARY KEY NOT NULL,
+  `thread_id` text NOT NULL,
+  `generation` integer NOT NULL,
+  `expected_interrupt_ids_json` text NOT NULL,
+  `fingerprint` text NOT NULL,
+  `resolutions_json` text NOT NULL,
+  `continuation_run_id` text NOT NULL UNIQUE,
+  `committed_at` integer NOT NULL
+);
+CREATE INDEX `interrupts_run_status_generation_idx`
+  ON `interrupts` (`run_id`,`status`,`generation`);
+CREATE INDEX `interrupts_thread_status_idx`
+  ON `interrupts` (`thread_id`,`status`);
+```
+
+The D1 migration test first inserts PR-head `approval_required` and `client_tool_input` descriptors with no reserved binding, applies `0001`, and asserts both remain `pending` with generation `1`, a `kind: 'generic'` binding correlated to the stored row/run, and a `legacy-json:` response-schema identity. Apply the migration in one D1 migration transaction and assert the table, columns, indexes, and both upgraded rows appear together. Import the raw asset and append:
+
+```ts
+{
+  id: '0001_tanstack_ai_interrupt_batches',
+  filename: '0001_tanstack_ai_interrupt_batches.sql',
+  sql: interruptBatchesMigrationSql,
+}
+```
+
+Keep `src/r2.ts` and R2 migrations unchanged.
+
+- [ ] **Step 4: Override the D1 interrupt store with one conditional batch**
+
+Implement `createD1InterruptStore(d1, clock)` and return it from `createD1Stores`. The open and recovery methods are:
+
+```ts
+async function openInterruptBatch(
+  input: OpenInterruptBatchInput,
+): Promise<{ generation: number; descriptors: readonly Interrupt[] }> {
+  const descriptorIds = input.descriptors.map((descriptor) => descriptor.id)
+  const bindingIds = input.bindings.map((binding) => binding.interruptId)
+  if (!hasExactInterruptIds(descriptorIds, bindingIds)) {
+    throw new TypeError('Interrupt descriptors and bindings must have exact IDs.')
+  }
+  const existing = await d1.prepare(
+    'SELECT * FROM interrupts WHERE run_id = ? ORDER BY interrupt_id',
+  ).bind(input.interruptedRunId).all<D1InterruptRow>()
+  if (existing.results.length > 0) {
+    if (!hasExactInterruptIds(
+      existing.results.map((row) => row.interrupt_id),
+      descriptorIds,
+    )) {
+      throw new Error('Interrupt batch already opened with a different set.')
+    }
+    return {
+      generation: existing.results[0]?.generation ?? 1,
+      descriptors: cloneAndDeepFreezeJson(
+        existing.results.map((row) => JSON.parse(row.payload_json) as Interrupt),
+      ),
+    }
+  }
+
+  const generation = 1
+  const bindings = new Map(input.bindings.map((binding) => [
+    binding.interruptId,
+    cloneAndDeepFreezeJson({
+      ...binding,
+      interruptedRunId: input.interruptedRunId,
+      generation,
+    } satisfies InterruptBinding),
+  ]))
+  const descriptors = input.descriptors.map((descriptor) => {
+    const binding = bindings.get(descriptor.id)
+    if (!binding) throw new Error(`Missing binding for ${descriptor.id}`)
+    return cloneAndDeepFreezeJson({
+      ...descriptor,
+      metadata: { ...descriptor.metadata, 'tanstack:binding': binding },
+    })
+  })
+  const results = await d1.batch(descriptors.map((descriptor) => {
+    const binding = bindings.get(descriptor.id)
+    if (!binding) throw new Error(`Missing binding for ${descriptor.id}`)
+    return d1.prepare(`INSERT INTO interrupts (
+      interrupt_id, run_id, thread_id, generation, status, requested_at,
+      payload_json, binding_json, response_schema_hash
+    ) VALUES (?, ?, ?, ?, 'pending', ?, ?, ?, ?)`).bind(
+      descriptor.id,
+      input.interruptedRunId,
+      input.threadId,
+      generation,
+      clock(),
+      JSON.stringify(descriptor),
+      JSON.stringify(binding),
+      binding.responseSchemaHash,
+    )
+  }))
+  if (results.some((result) => result.meta.changes !== 1)) {
+    throw new Error('D1 did not open every interrupt row.')
+  }
+  return { generation, descriptors: cloneAndDeepFreezeJson(descriptors) }
+}
+
+async function getInterruptRecoveryState(
+  query: InterruptRecoveryQuery,
+): Promise<InterruptRecoveryStateV1> {
+  const [batchResult, rowsResult] = await d1.batch([
+    d1.prepare(
+      'SELECT * FROM interrupt_batches WHERE interrupted_run_id = ?',
+    ).bind(query.interruptedRunId),
+    d1.prepare(
+      'SELECT * FROM interrupts WHERE run_id = ? ORDER BY interrupt_id',
+    ).bind(query.interruptedRunId),
+  ])
+  const batchRow = batchResult.results[0] as D1InterruptBatchRow | undefined
+  const rows = rowsResult.results as D1InterruptRow[]
+  return projectInterruptRecovery({
+    query,
+    batch: batchRow ? decodeD1BatchRow(batchRow) : null,
+    rows: rows.map(decodeD1InterruptRow),
+    now: clock(),
+    includeResolutions: true,
+  })
+}
+```
+
+Add the row contracts and decoders used by those methods:
+
+```ts
+interface D1InterruptRow {
+  interrupt_id: string
+  run_id: string
+  thread_id: string
+  generation: number
+  status: 'pending' | 'resolved' | 'cancelled'
+  requested_at: number
+  resolved_at: number | null
+  payload_json: string
+  binding_json: string
+  response_json: string | null
+}
+
+interface D1InterruptBatchRow {
+  interrupted_run_id: string
+  thread_id: string
+  generation: number
+  expected_interrupt_ids_json: string
+  fingerprint: string
+  resolutions_json: string
+  continuation_run_id: string
+  committed_at: number
+}
+
+function decodeD1InterruptRow(row: D1InterruptRow): InterruptRecord {
+  const payload: unknown = JSON.parse(row.payload_json)
+  const binding: unknown = JSON.parse(row.binding_json)
+  if (
+    !binding ||
+    typeof binding !== 'object' ||
+    !('interruptId' in binding) ||
+    binding.interruptId !== row.interrupt_id ||
+    !('interruptedRunId' in binding) ||
+    binding.interruptedRunId !== row.run_id ||
+    !('generation' in binding) ||
+    binding.generation !== row.generation
+  ) {
+    throw new InterruptStoreCorruptionError('Interrupt binding correlation mismatch.')
+  }
+  return cloneAndDeepFreezeJson({
+    interruptId: row.interrupt_id,
+    runId: row.run_id,
+    threadId: row.thread_id,
+    generation: row.generation,
+    status: row.status,
+    requestedAt: row.requested_at,
+    ...(row.resolved_at !== null && { resolvedAt: row.resolved_at }),
+    payload,
+    binding,
+    ...(row.response_json !== null && {
+      response: JSON.parse(row.response_json) as unknown,
+    }),
+  }) as InterruptRecord
+}
+
+function decodeD1BatchRow(row: D1InterruptBatchRow): InterruptBatchRecord {
+  const expected: unknown = JSON.parse(row.expected_interrupt_ids_json)
+  const resolutions: unknown = JSON.parse(row.resolutions_json)
+  if (!Array.isArray(expected) || !Array.isArray(resolutions)) {
+    throw new InterruptStoreCorruptionError('Invalid interrupt batch arrays.')
+  }
+  const resolutionIds = resolutions.map((entry) => {
+    if (!entry || typeof entry !== 'object' || !('interruptId' in entry)) {
+      throw new InterruptStoreCorruptionError('Invalid interrupt resolution.')
+    }
+    return String(entry.interruptId)
+  })
+  if (!hasExactInterruptIds(expected.map(String), resolutionIds)) {
+    throw new InterruptStoreCorruptionError('Interrupt batch ID set mismatch.')
+  }
+  return cloneAndDeepFreezeJson({
+    interruptedRunId: row.interrupted_run_id,
+    threadId: row.thread_id,
+    generation: row.generation,
+    expectedInterruptIds: expected.map(String),
+    fingerprint: row.fingerprint,
+    canonicalResolutions: row.resolutions_json,
+    resolutions,
+    continuationRunId: row.continuation_run_id,
+    committedAt: row.committed_at,
+  }) as InterruptBatchRecord
+}
+```
+
+Recovery reads winner and rows in one D1 batch snapshot. Commit builds the dynamic `IN` list from the already unique expected IDs and submits this insert followed by one gated update per resolution:
+
+```sql
+INSERT INTO interrupt_batches (
+  interrupted_run_id, thread_id, generation,
+  expected_interrupt_ids_json, fingerprint, resolutions_json,
+  continuation_run_id, committed_at
+)
+SELECT ?, ?, ?, ?, ?, ?, ?, ?
+WHERE (
+  SELECT COUNT(*) FROM interrupts
+  WHERE run_id = ? AND status = 'pending' AND generation = ?
+) = ?
+AND NOT EXISTS (
+  SELECT 1 FROM interrupts
+  WHERE run_id = ? AND status = 'pending' AND generation = ?
+    AND interrupt_id NOT IN (?, ?)
+)
+AND NOT EXISTS (
+  SELECT 1 FROM interrupts
+  WHERE run_id = ? AND status = 'pending' AND generation = ?
+    AND json_extract(binding_json, '$.expiresAt') IS NOT NULL
+    AND unixepoch(json_extract(binding_json, '$.expiresAt')) * 1000 <= ?
+);
+```
+
+Each update includes `WHERE interrupt_id = ? AND run_id = ? AND status = 'pending' AND generation = ? AND EXISTS (SELECT 1 FROM interrupt_batches WHERE interrupted_run_id = ? AND fingerprint = ? AND resolutions_json = ? AND continuation_run_id = ?)`. Inspect every batch result: the insert and every expected update must report one change. Zero insert changes or a uniqueness race triggers an authoritative batch read; replay requires both fingerprint and canonical `resolutions_json`, otherwise conflict. Any other zero update or statement error throws, and D1 rolls the batch back. The shared conformance suite plus D1 migration tests cover open, commit, all five recovery projections, expiry in the SQL predicate, exact replay, conflict, forced rollback, restart, and migrated pending/resolved rows.
+
+- [ ] **Step 5: Run green D1 checks and refactor**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-persistence-cloudflare test:lib -- --run tests/runtime.conformance.test.ts tests/migrations.test.ts tests/migration-cli.test.ts
+pnpm --filter @tanstack/ai-persistence-cloudflare test:types
+```
+
+Expected: PASS; forced failure rolls back, exact replay returns the first continuation ID, and different writers observe one conflict. Extract D1 row decoding/recovery helpers and rerun both commands.
+
+### Task 8: Build the authoritative resume gateway and explicit recovery handler
+
+**Prerequisites:** Tasks 3-7. All built-in stores must satisfy conformance before server execution depends on them.
+
+**Files:**
+- Modify: `packages/ai-persistence/src/middleware.ts:93-214,675-711,764-911`
+- Modify: `packages/ai-persistence/src/capabilities.ts`
+- Create: `packages/ai-persistence/src/recovery.ts`
+- Modify: `packages/ai-persistence/src/index.ts`
+- Modify: `packages/ai-persistence/tests/interrupts.test.ts`
+- Modify: `packages/ai-persistence/tests/with-persistence.test.ts`
+- Modify: `packages/ai-persistence/tests/persistence-validation.test.ts`
+- Modify: `packages/ai/tests/interrupts.test.ts`
+
+- [ ] **Step 1: Write failing exhaustive-validation and recovery tests**
+
+Add one batch containing three independent invalid entries and prove all are reported while the store remains pending. Reuse the existing local `mockAdapter` and `collect` test utilities already defined at the top of `tests/interrupts.test.ts`. Define the tool and fixture in that file:
+
+```ts
+const transferInput = z.object({ cents: z.number().int().positive() })
+const transferApprove = z.object({ note: z.string().min(1) })
+const transferReject = z.object({ reason: z.string().min(1) })
+const transferTool = toolDefinition({
+  name: 'transfer',
+  description: 'Transfer funds',
+  needsApproval: true,
+  inputSchema: transferInput,
+  approvalSchema: {
+    approve: transferApprove,
+    reject: transferReject,
+  },
+}).server(async ({ cents }) => ({ receipt: `receipt-${cents}` }))
+
+async function openApprovalBatch(
+  persistence: AIPersistence,
+  interruptedRunId: string,
+): Promise<void> {
+  const store = persistence.stores.interrupts
+  if (!store) throw new Error('interrupt store missing')
+  const approval = normalizeApprovalSchema(
+    transferTool.approvalSchema,
+    transferTool.inputSchema,
+  )
+  await store.openInterruptBatch({
+    threadId: 'thread-1',
+    interruptedRunId,
+    descriptors: [
+      {
+        id: 'approve',
+        reason: 'tool_call',
+        toolCallId: 'call-approve',
+        responseSchema: approval.responseSchema,
+      },
+      {
+        id: 'deny',
+        reason: 'tool_call',
+        toolCallId: 'call-deny',
+        responseSchema: approval.responseSchema,
+      },
+      {
+        id: 'generic',
+        reason: 'input_required',
+        responseSchema: {
+          type: 'object',
+          properties: { email: { type: 'string', format: 'email' } },
+          required: ['email'],
+          additionalProperties: false,
+        },
+      },
+    ],
+    bindings: [
+      {
+        kind: 'tool-approval',
+        interruptId: 'approve',
+        toolName: 'transfer',
+        toolCallId: 'call-approve',
+        originalArgs: { cents: 1 },
+        inputSchemaHash: hashSchemaInput(transferTool.inputSchema),
+        approvalSchemaHash: approval.approvalSchemaHash,
+        responseSchemaHash: approval.responseSchemaHash,
+      },
+      {
+        kind: 'tool-approval',
+        interruptId: 'deny',
+        toolName: 'transfer',
+        toolCallId: 'call-deny',
+        originalArgs: { cents: 2 },
+        inputSchemaHash: hashSchemaInput(transferTool.inputSchema),
+        approvalSchemaHash: approval.approvalSchemaHash,
+        responseSchemaHash: approval.responseSchemaHash,
+      },
+      {
+        kind: 'generic',
+        interruptId: 'generic',
+        responseSchemaHash: digestInterruptJson(canonicalInterruptJson({
+          type: 'object',
+          properties: { email: { type: 'string', format: 'email' } },
+          required: ['email'],
+          additionalProperties: false,
+        })),
+      },
+    ],
+  })
+}
+```
+
+Obtain the no-execution adapter as `const { adapter: shouldNotRunAdapter, calls: adapterCalls } = mockAdapter([])` and assert `adapterCalls` rather than assuming `chatStream` is a spy:
+
+```ts
+it('reports every invalid response and commits nothing', async () => {
+  const persistence = memoryPersistence()
+  const {
+    adapter: shouldNotRunAdapter,
+    calls: adapterCalls,
+  } = mockAdapter([])
+  await openApprovalBatch(persistence, 'run-old')
+  const stream = chat({
+    adapter: shouldNotRunAdapter,
+    messages: [],
+    threadId: 'thread-1',
+    runId: 'run-new',
+    parentRunId: 'run-old',
+    resume: [
+      {
+        interruptId: 'approve',
+        status: 'resolved',
+        payload: { approved: true, editedArgs: { cents: 'wrong' } },
+      },
+      {
+        interruptId: 'deny',
+        status: 'resolved',
+        payload: { approved: false, editedArgs: { cents: 1 } },
+      },
+      {
+        interruptId: 'generic',
+        status: 'resolved',
+        payload: { email: 42 },
+      },
+    ],
+    tools: [transferTool],
+    middleware: [withChatPersistence(persistence)],
+  })
+  const chunks = await collect(stream)
+  const errors = chunks.filter((chunk) => chunk.type === 'RUN_ERROR')
+
+  expect(errors).toHaveLength(1)
+  expect(errors[0]?.['tanstack:interruptErrors']).toEqual([
+    expect.objectContaining({ interruptId: 'approve', code: 'invalid-edited-args' }),
+    expect.objectContaining({ interruptId: 'deny', code: 'invalid-edited-args' }),
+    expect.objectContaining({ interruptId: 'generic', code: 'invalid-payload' }),
+  ])
+  expect(await persistence.stores.interrupts?.listPendingByRun('run-old')).toHaveLength(3)
+  expect(adapterCalls).toHaveLength(0)
+})
+```
+
+Add the exact-set aggregate test:
+
+```ts
+it('returns item and batch exact-set errors together', async () => {
+  const persistence = memoryPersistence()
+  const store = persistence.stores.interrupts
+  if (!store) throw new Error('interrupt store missing')
+  const responseSchema = {
+    type: 'object',
+    properties: { value: { type: 'string' } },
+    required: ['value'],
+    additionalProperties: false,
+  } as const
+  await store.openInterruptBatch({
+    threadId: 'thread-1',
+    interruptedRunId: 'run-old',
+    descriptors: ['a', 'b', 'c'].map((id) => ({
+      id,
+      reason: 'input_required',
+      responseSchema,
+    })),
+    bindings: ['a', 'b', 'c'].map((interruptId) => ({
+      kind: 'generic' as const,
+      interruptId,
+      responseSchemaHash: digestInterruptJson(
+        canonicalInterruptJson(responseSchema),
+      ),
+    })),
+  })
+  const { adapter, calls } = mockAdapter([])
+  const chunks = await collect(chat({
+    adapter,
+    messages: [],
+    threadId: 'thread-1',
+    runId: 'run-new',
+    parentRunId: 'run-old',
+    resume: [
+      { interruptId: 'a', status: 'resolved', payload: { value: 1 } },
+      { interruptId: 'a', status: 'cancelled' },
+      { interruptId: 'x', status: 'resolved', payload: { value: 'extra' } },
+    ],
+    middleware: [withChatPersistence(persistence)],
+  }))
+  const runErrors = chunks.filter((chunk) => chunk.type === 'RUN_ERROR')
+  expect(runErrors).toHaveLength(1)
+  expect(runErrors[0]?.['tanstack:interruptErrors']).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        scope: 'item',
+        interruptId: 'a',
+        code: 'invalid-payload',
+      }),
+      expect.objectContaining({
+        scope: 'item',
+        interruptId: 'x',
+        code: 'unknown-interrupt',
+      }),
+      expect.objectContaining({
+        scope: 'batch',
+        code: 'protocol',
+        interruptIds: ['a'],
+      }),
+      expect.objectContaining({
+        scope: 'batch',
+        code: 'protocol',
+        interruptIds: ['x'],
+      }),
+      expect.objectContaining({
+        scope: 'batch',
+        code: 'incomplete-batch',
+        interruptIds: ['b', 'c'],
+      }),
+    ]),
+  )
+  expect(await store.listPendingByRun('run-old')).toHaveLength(3)
+  expect(calls).toHaveLength(0)
+})
+```
+
+Add a table whose setup functions are concrete closures in the same test file:
+
+```ts
+async function createInvalidGatewayFixture(interruptId: string) {
+  const persistence = memoryPersistence()
+  const store = persistence.stores.interrupts
+  if (!store) throw new Error('interrupt store missing')
+  const { adapter, calls: adapterCalls } = mockAdapter([])
+  const approval = normalizeApprovalSchema(
+    transferTool.approvalSchema,
+    transferTool.inputSchema,
+  )
+  const isTool = interruptId === 'tool' || interruptId === 'drift'
+  const descriptor: Interrupt = isTool
+    ? {
+        id: interruptId,
+        reason: 'tool_call',
+        toolCallId: `call-${interruptId}`,
+        responseSchema: approval.responseSchema,
+        ...(interruptId === 'expired' && {
+          expiresAt: '2026-07-13T09:59:00.000Z',
+        }),
+      }
+    : {
+        id: interruptId,
+        reason: 'confirmation',
+        responseSchema: { type: 'object' },
+        ...(interruptId === 'expired' && {
+          expiresAt: '2026-07-13T09:59:00.000Z',
+        }),
+      }
+  const binding: UnopenedInterruptBinding = isTool
+    ? {
+        kind: 'tool-approval',
+        interruptId,
+        toolName: interruptId === 'tool' ? 'removed-tool' : 'transfer',
+        toolCallId: `call-${interruptId}`,
+        originalArgs: { cents: 1 },
+        inputSchemaHash:
+          interruptId === 'drift'
+            ? 'sha256:deployed-different-schema'
+            : hashSchemaInput(transferTool.inputSchema),
+        approvalSchemaHash: approval.approvalSchemaHash,
+        responseSchemaHash: approval.responseSchemaHash,
+      }
+    : {
+        kind: 'generic',
+        interruptId,
+        responseSchemaHash: digestInterruptJson(
+          canonicalInterruptJson(descriptor.responseSchema ?? null),
+        ),
+        ...(descriptor.expiresAt !== undefined && {
+          expiresAt: descriptor.expiresAt,
+        }),
+      }
+  await store.openInterruptBatch({
+    threadId: 'thread-1',
+    interruptedRunId: 'run-old',
+    descriptors: [descriptor],
+    bindings: [binding],
+  })
+  return {
+    persistence,
+    store,
+    adapter,
+    adapterCalls,
+    threadId: 'thread-1',
+    interruptedRunId: 'run-old',
+    tools: interruptId === 'drift' ? [transferTool] : [],
+  }
+}
+
+it.each([
+  ['cancelled payload', { interruptId: 'a', status: 'cancelled', payload: {} }, 'protocol'],
+  ['expired', { interruptId: 'expired', status: 'cancelled' }, 'expired'],
+  ['unknown tool after deploy', { interruptId: 'tool', status: 'cancelled' }, 'stale'],
+  ['schema hash drift', { interruptId: 'drift', status: 'cancelled' }, 'stale'],
+] as const)('%s performs no write or execution', async (_name, resumeItem, code) => {
+  const fixture = await createInvalidGatewayFixture(resumeItem.interruptId)
+  const chunks = await collect(chat({
+    adapter: fixture.adapter,
+    messages: [],
+    threadId: fixture.threadId,
+    runId: 'run-new',
+    parentRunId: fixture.interruptedRunId,
+    resume: [resumeItem],
+    tools: fixture.tools,
+    middleware: [withChatPersistence(fixture.persistence)],
+  }))
+  expect(chunks).toContainEqual(
+    expect.objectContaining({
+      type: 'RUN_ERROR',
+      'tanstack:interruptErrors': expect.arrayContaining([
+        expect.objectContaining({ code }),
+      ]),
+    }),
+  )
+  expect(await fixture.store.listPendingByRun(fixture.interruptedRunId)).toHaveLength(1)
+  expect(fixture.adapterCalls).toHaveLength(0)
+})
+```
+
+Separate tests cover missing `parentRunId`, exact replay, a conflicting second batch, and a persistence object with no interrupt store, because those cases use different request/setup shapes. Each asserts one terminal, the named code, zero adapter calls, and unchanged pending rows. Recovery handler tests use the full/redacted authorization contract from Step 6.
+
+- [ ] **Step 2: Run the red gateway tests**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-persistence test:lib -- --run tests/interrupts.test.ts tests/with-persistence.test.ts tests/persistence-validation.test.ts
+```
+
+Expected: FAIL because middleware still uses fail-fast `validatePendingResumes`, sequential `applyPendingResumes`, and same-run lookup.
+
+- [ ] **Step 3: Provide the core capability and atomically open descriptors**
+
+In middleware `setup`, call `provideInterruptPersistence(ctx, persistence.stores.interrupts)` only after store validation proves all atomic methods exist. In `onChunk`, replace the per-descriptor `create` loop with one call:
+
+```ts
+if (
+  chunk.type === EventType.RUN_FINISHED &&
+  chunk.outcome?.type === 'interrupt'
+) {
+  const gateway = getInterruptPersistence(ctx)
+  const bindings = chunk.outcome.interrupts.map(readServerBinding)
+  const opened = await gateway.openInterruptBatch({
+    threadId: ctx.threadId,
+    interruptedRunId: ctx.runId,
+    descriptors: chunk.outcome.interrupts,
+    bindings,
+  })
+  await interruptRun(runs, ctx.runId)
+  return {
+    ...chunk,
+    outcome: { type: 'interrupt', interrupts: [...opened.descriptors] },
+  }
+}
+```
+
+`readServerBinding` accepts only the reserved server-produced metadata shape created in Task 9; missing/malformed bindings fail before this terminal chunk is yielded. `openInterruptBatch` is all-or-none, so an exception cannot leave a partial descriptor set.
+
+- [ ] **Step 4: Rebind configured tool validators and collect every error**
+
+Replace `validatePendingResumes` with an async exhaustive function. The authoritative lookup key is stored tool name plus schema hashes, never client metadata:
+
+```ts
+async function validateInterruptResumeBatch(input: {
+  pending: readonly InterruptRecord[]
+  resume: readonly RunAgentResumeItem[]
+  tools: readonly Tool[]
+  now: number
+  correlation: InterruptCorrelation
+}): Promise<ValidatedInterruptBatch> {
+  const itemErrors: ItemInterruptError[] = []
+  const batchErrors: BatchInterruptError[] = []
+  const pendingIds = new Set(input.pending.map((record) => record.interruptId))
+  const resumeById = new Map<string, RunAgentResumeItem>()
+  for (const entry of input.resume) {
+    if (resumeById.has(entry.interruptId)) {
+      batchErrors.push(batchError('protocol', [entry.interruptId], 'Duplicate response.', input.correlation))
+      continue
+    }
+    resumeById.set(entry.interruptId, entry)
+    if (!pendingIds.has(entry.interruptId)) {
+      itemErrors.push(itemError(entry.interruptId, 'unknown-interrupt', 'Unknown interrupt.', input.correlation))
+      batchErrors.push(batchError('protocol', [entry.interruptId], 'Extra response.', input.correlation))
+    }
+  }
+  const missing = [...pendingIds].filter((id) => !resumeById.has(id)).sort()
+  if (missing.length > 0) {
+    batchErrors.push(batchError('incomplete-batch', missing, 'Missing responses.', input.correlation))
+  }
+
+  for (const record of [...input.pending].sort((a, b) =>
+    a.interruptId.localeCompare(b.interruptId),
+  )) {
+    const entry = resumeById.get(record.interruptId)
+    if (!entry) continue
+    const rebound = rebindAuthoritativeValidator(record.binding, input.tools)
+    if (rebound.status === 'stale') {
+      itemErrors.push(staleSchemaError(record, input.correlation))
+      continue
+    }
+    itemErrors.push(...await validateOneResume(record, entry, rebound, input))
+  }
+  itemErrors.sort((left, right) => left.interruptId.localeCompare(right.interruptId))
+  return itemErrors.length > 0 || batchErrors.length > 0
+    ? { ok: false, itemErrors, batchErrors, errors: [...itemErrors, ...batchErrors] }
+    : { ok: true, state: buildResumeState(input.pending, resumeById) }
+}
+```
+
+`batchError` and `itemError` are constructors that copy the full correlation and set `source: 'server'`/`retryable: false`. `validateOneResume` is exhaustive: cancelled entries reject any payload; tool approval validates the response envelope, then edited arguments and selected nested payload; rejection forbids edits; client-tool execution validates output; generic validates the descriptor response schema. Standard Schema validators are awaited and their returned issue order is preserved. Only the outer `itemErrors` array is sorted by interrupt ID. Missing tool/hash drift returns one `stale` item error and never an unconstrained validator.
+
+- [ ] **Step 5: Commit once using `parentRunId` as the CAS key**
+
+In `onConfig`, reject `resume` without `ctx.parentRunId`; load only `listPendingByRun(ctx.parentRunId)`, validate every item, and compute the fingerprint only after validation. Commit exactly once with the candidate continuation `ctx.runId`:
+
+```ts
+const candidate = canonicalizeInterruptResolutions(config.resume)
+const committed = await store.commitInterruptResolutions({
+  threadId: ctx.threadId,
+  interruptedRunId: ctx.parentRunId,
+  continuationRunId: ctx.runId,
+  expectedGeneration: pending[0]?.generation ?? 0,
+  expectedInterruptIds: pending.map((record) => record.interruptId),
+  resolutions: candidate.resolutions,
+  fingerprint: candidate.fingerprint,
+  canonicalResolutions: candidate.canonicalResolutions,
+})
+```
+
+On `committed`, return `resumeToolState` containing approvals with edited arguments/custom payload, client results, denied results, cancelled tool-call IDs, and generic resolutions. Later application middleware can read `genericInterrupts` and continue its own workflow without a tool event. On `replayed`, throw an internal replay signal carrying the winning continuation ID; Task 9 converts it to an accepted terminal replay result without executing tools twice. On `conflict`, throw a serializable interrupt submission failure with authoritative recovery.
+
+- [ ] **Step 6: Create a direct and authenticated HTTP recovery helper**
+
+Implement both an in-process function and an explicit handler factory:
+
+```ts
+export async function getInterruptRecoveryState(
+  persistence: AIPersistence,
+  input: InterruptRecoveryQuery,
+): Promise<InterruptRecoveryStateV1> {
+  const store = persistence.stores.interrupts
+  if (!store) throw new Error('Interrupt persistence is not configured.')
+  return store.getInterruptRecoveryState(input)
+}
+
+export function createInterruptRecoveryHandler(options: {
+  persistence: AIPersistence
+  authorize: (
+    request: Request,
+    input: InterruptRecoveryQuery,
+  ) => RecoveryAuthorization | Promise<RecoveryAuthorization>
+}): (request: Request) => Promise<Response> {
+  return async (request) => {
+    const input = parseInterruptRecoveryQuery(await request.json())
+    const authorization = await options.authorize(request, input)
+    if (!authorization.allowed) {
+      return new Response('Forbidden', { status: 403 })
+    }
+    const state = await getInterruptRecoveryState(options.persistence, input)
+    return Response.json(projectRecoveryState(state, authorization))
+  }
+}
+
+export type RecoveryAuthorization =
+  | { allowed: false }
+  | { allowed: true; includeResolutions: boolean }
+
+function projectRecoveryState(
+  state: InterruptRecoveryStateV1,
+  authorization: Extract<RecoveryAuthorization, { allowed: true }>,
+): InterruptRecoveryStateV1 {
+  if (
+    authorization.includeResolutions ||
+    state.state !== 'committed' ||
+    !state.committed
+  ) {
+    return cloneAndDeepFreezeJson(state)
+  }
+  const { resolutions: _redacted, ...committed } = state.committed
+  return cloneAndDeepFreezeJson({ ...state, committed })
+}
+```
+
+Test `{ allowed: false }` → 403, `{ allowed: true, includeResolutions: false }` → committed DTO without `resolutions`, and `includeResolutions: true` → full frozen resolutions. The helper does not register a route or infer a URL.
+
+- [ ] **Step 7: Run green gateway checks and refactor**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-persistence test:lib -- --run tests/interrupts.test.ts tests/memory.conformance.test.ts tests/with-persistence.test.ts tests/persistence-validation.test.ts
+pnpm --filter @tanstack/ai-persistence test:types
+```
+
+Expected: PASS; three invalid entries arrive in one error, nothing writes or executes, and schema drift is stale. Split exact-set, validator-rebind, and resume-state builders into pure private helpers, rerun both commands, and confirm core still has no persistence-package import.
+
+### Task 9: Correct the AG-UI interrupt lifecycle and resumed tool audit
+
+**Prerequisites:** Task 8.
+
+**Files:**
+- Modify: `packages/ai/src/activities/chat/index.ts:504-980,1409-1640,1673-1888,2821-2860`
+- Modify: `packages/ai/src/activities/chat/tools/tool-calls.ts:425-448,681-890`
+- Modify: `packages/ai/src/types.ts:590-735,980-1010,1081-1124`
+- Modify: `packages/ai/src/utilities/chat-params.ts:45-104`
+- Modify: `packages/ai/tests/interrupts.test.ts`
+- Modify: `packages/ai/tests/chat.test.ts:423-870`
+- Modify: `packages/ai/tests/chat-params.test.ts`
+- Modify: `packages/ai/tests/stream-processor.test.ts:1197-1376,2177-2220`
+
+- [ ] **Step 1: Write failing wire-order and continuation-audit tests**
+
+Add a protocol test that records exact chunk order and a continuation test with approved, denied, and cancelled tool approvals:
+
+```ts
+expect(interruptedChunks.map((chunk) => chunk.type).slice(-3)).toEqual([
+  EventType.MESSAGES_SNAPSHOT,
+  EventType.STATE_SNAPSHOT,
+  EventType.RUN_FINISHED,
+])
+expect(interruptOutcome.interrupts).toEqual([
+  expect.objectContaining({ reason: 'tool_call' }),
+  expect.objectContaining({ reason: 'tanstack:client_tool_execution' }),
+])
+
+const resumedToolEvents = continuationChunks.filter((chunk) =>
+  chunk.type.startsWith('TOOL_CALL_'),
+)
+expect(resumedToolEvents.map((chunk) => chunk.type)).toEqual([
+  EventType.TOOL_CALL_RESULT,
+  EventType.TOOL_CALL_RESULT,
+])
+expect(resumedToolEvents.map((chunk) => chunk.toolCallId)).toEqual([
+  'approved-call',
+  'denied-call',
+])
+expect(continuationChunks).not.toContainEqual(
+  expect.objectContaining({ toolCallId: 'cancelled-call' }),
+)
+```
+
+Assert the continuation has a new run ID, its `parentRunId` equals the interrupted run, its thread is unchanged, approved edits replace rather than merge, denied history is `{ status: 'denied', payload }`, cancellation is persisted in the interrupt audit and marks the original call not-executed during provider-history reconstruction, generic continuation reaches application middleware, and `onError` runs once for interrupt submission failure. Add a run with an approval-producing tool but no interrupt persistence capability and assert one `RUN_ERROR` with `persistence-required`, no snapshots, and no interrupt `RUN_FINISHED`.
+
+- [ ] **Step 2: Run the red core lifecycle tests**
+
+Run:
+
+```powershell
+pnpm --filter @tanstack/ai test:lib -- --run tests/interrupts.test.ts tests/chat.test.ts tests/chat-params.test.ts
+```
+
+Expected: FAIL on old reasons `approval_required` / `client_tool_input`, replayed start/args/end events, missing snapshots, and missing structured error handling.
+
+- [ ] **Step 3: Build canonical descriptors and reserved bindings**
+
+Change `buildActionableInterrupts` to use normalized tool schemas and server-owned binding metadata:
+
+```ts
+const approvalSchema = normalizeApprovalSchema(
+  tool.approvalSchema,
+  tool.inputSchema,
+)
+interrupts.push({
+  id: approval.approvalId,
+  reason: 'tool_call',
+  message: `Approval required to run ${approval.toolName}`,
+  toolCallId: approval.toolCallId,
+  responseSchema: approvalSchema.responseSchema,
+  metadata: {
+    'tanstack:binding': {
+      kind: 'tool-approval',
+      toolName: approval.toolName,
+      toolCallId: approval.toolCallId,
+      originalArgs: approval.input,
+      responseSchemaHash: approvalSchema.responseSchemaHash,
+      inputSchemaHash: hashSchemaInput(tool.inputSchema),
+      approvalSchemaHash: approvalSchema.approvalSchemaHash,
+    },
+  },
+})
+```
+
+Client-tool descriptors use `tanstack:client_tool_execution`, the original call ID, and output/response schema identities. Generic reasons retain `input_required`, `confirmation`, or an unknown namespaced/custom reason. Invalid raw schemas fail before a descriptor is emitted.
+
+Before returning any nonempty actionable descriptor set, require the core-owned `InterruptPersistenceCapability` from Task 3. If the capability is absent, throw `InterruptSubmissionFailure` with batch code `persistence-required` before emitting snapshots or an interrupt terminal. This check lives in core lifecycle code; merely omitting `withChatPersistence` must never create an unresumable native interrupt.
+
+- [ ] **Step 4: Emit required snapshots immediately before the terminal**
+
+Add `state?: unknown` to chat text options and pass the parsed AG-UI state from `chatParamsFromRequestBody`. Before every interrupt terminal path, yield:
+
+```ts
+yield* this.pipeThroughMiddleware({
+  type: EventType.MESSAGES_SNAPSHOT,
+  messages: uiMessagesToWire(modelMessagesToUIMessages(this.messages)),
+  timestamp: Date.now(),
+})
+if (this.params.state !== undefined) {
+  yield* this.pipeThroughMiddleware({
+    type: EventType.STATE_SNAPSHOT,
+    snapshot: this.params.state,
+    timestamp: Date.now(),
+  })
+}
+yield* this.pipeThroughMiddleware(this.buildInterruptFinishedChunk(
+  finishEvent,
+  executionResult.needsApproval,
+  executionResult.needsClientExecution,
+))
+```
+
+Because middleware processes a chunk before the generator yields it, Task 8's atomic descriptor open must finish before `RUN_FINISHED` becomes observable. If it fails, snapshots may precede the single `RUN_ERROR`, but no interrupt terminal is emitted.
+
+- [ ] **Step 5: Carry rich approval decisions into tool execution**
+
+Change `executeToolCalls` from `Map<string, boolean>` to `ReadonlyMap<string, ToolApprovalResolution>`. Select the authoritative stored original input unless an approved decision contains `editedArgs`; use edits as a complete replacement and validate them before execution. A denial produces one synthetic result:
+
+```ts
+if (!decision.approved) {
+  results.push({
+    toolCallId: toolCall.id,
+    toolName,
+    result: {
+      status: 'denied',
+      ...(decision.payload !== undefined && { payload: decision.payload }),
+    },
+    state: 'output-available',
+  })
+  continue
+}
+input = decision.editedArgs === undefined ? input : decision.editedArgs
+```
+
+Filter `cancelledToolCallIds` before execution and result construction. Record those call IDs as not-executed in the interrupt audit/provider-history reconstruction path without producing a result chunk. Client-tool resolved output follows the existing result path; generic resolutions remain only in middleware continuation state and create no tool chunk.
+
+- [ ] **Step 6: Make resumed tool output result-only**
+
+Delete the `argsMap` branch that synthesizes `TOOL_CALL_START`, `TOOL_CALL_ARGS`, and `TOOL_CALL_END` in `buildToolResultChunks`. Always emit one `TOOL_CALL_RESULT` for actual approved/client results and synthetic denied results, correlated to the original `toolCallId`. Persist corresponding actual/denied history before the resumed model begins; cancelled calls remain in the interrupt audit record and are excluded from actionable provider history.
+
+- [ ] **Step 7: Emit exactly one structured terminal on gateway failures and replay**
+
+Introduce an internal `InterruptSubmissionFailure` carrying serialized errors/recovery and an `InterruptReplaySignal` carrying the winning continuation ID. In the `TextEngine.run()` catch, call middleware `onError` once, then yield one `RUN_ERROR` for submission failure and return without rethrowing or adding `RUN_FINISHED`:
+
+```ts
+if (error instanceof InterruptSubmissionFailure) {
+  await this.runInterruptOnErrorOnce(error)
+  yield {
+    type: EventType.RUN_ERROR,
+    threadId: this.middlewareCtx.threadId,
+    runId: this.middlewareCtx.runId,
+    timestamp: Date.now(),
+    message: error.message,
+    code: 'INTERRUPT_SUBMISSION_FAILED',
+    'tanstack:interruptErrors': error.errors,
+    ...(error.recovery && {
+      'tanstack:interruptRecovery': error.recovery,
+    }),
+  }
+  return
+}
+```
+
+For exact replay, emit a successful `RUN_FINISHED` whose standard `result` is canonical JSON `{ "type": "tanstack:interrupt-replay", "continuationRunId": "winning-run" }`; do not execute tools. The client recognizes this result and joins/reloads the winner. `runStreamingText` disposes MCP resources in `finally` but does not translate or duplicate these terminal signals.
+
+- [ ] **Step 8: Run green lifecycle checks and audit legacy emission**
+
+Run:
+
+```powershell
+pnpm --filter @tanstack/ai test:lib -- --run tests/interrupts.test.ts tests/chat.test.ts tests/chat-params.test.ts tests/stream-processor.test.ts
+pnpm --filter @tanstack/ai test:types
+```
+
+Expected: PASS; snapshots precede a nonempty interrupt outcome, continuations use a new run with `parentRunId`, and resumed tools emit results only. Confirm native server paths emit no `approval-requested` or `tool-input-available` custom event; deprecated readers remain tested for old streams.
+
+- [ ] **Step 9: Focused refactor and recheck**
+
+Extract descriptor/binding construction and terminal-error serialization into focused helpers, rerun the same commands, and verify every terminal path calls exactly one of `onFinish`, `onAbort`, or `onError`.
+
+### Task 10: Define and hydrate the typed bound interrupt union
+
+**Prerequisites:** Tasks 2, 3, and 9.
+
+**Files:**
+- Create: `packages/ai-client/src/interrupt-manager.ts`
+- Modify: `packages/ai-client/src/types.ts:1-110,397-585`
+- Modify: `packages/ai-client/src/index.ts`
+- Create: `packages/ai-client/tests/chat-client-interrupts.test.ts`
+- Create: `packages/ai-client/tests/interrupts-types.test-d.ts`
+
+- [ ] **Step 1: Write failing type and hydration tests before implementation**
+
+Define an approval tool with distinct branches and assert the exact resolver calls:
+
+```ts
+const transfer = toolDefinition({
+  name: 'transfer',
+  description: 'Transfer funds',
+  needsApproval: true,
+  inputSchema: z.object({ cents: z.number() }),
+  outputSchema: z.object({ receipt: z.string() }),
+  approvalSchema: {
+    approve: z.object({ note: z.string() }),
+    reject: z.object({ reason: z.string() }),
+  },
+}).client()
+
+declare const interrupt: Extract<
+  ChatInterrupt<readonly [typeof transfer]>,
+  { kind: 'tool-approval'; toolName: 'transfer' }
+>
+
+interrupt.resolveInterrupt(true, {
+  editedArgs: { cents: 500 },
+  payload: { note: 'Reviewed' },
+})
+interrupt.resolveInterrupt(false, { payload: { reason: 'Policy' } })
+// @ts-expect-error rejection never accepts editedArgs
+interrupt.resolveInterrupt(false, { editedArgs: { cents: 1 }, payload: { reason: 'Policy' } })
+// @ts-expect-error custom data belongs under payload
+interrupt.resolveInterrupt(true, { editedArgs: { cents: 1 }, note: 'Reviewed' })
+
+const noInput = toolDefinition({
+  name: 'noInput',
+  description: 'No editable input',
+  needsApproval: true,
+}).client()
+declare const noInputInterrupt: Extract<
+  ChatInterrupt<readonly [typeof noInput]>,
+  { kind: 'tool-approval'; toolName: 'noInput' }
+>
+noInputInterrupt.resolveInterrupt(true)
+// @ts-expect-error omitted inputSchema forbids editedArgs
+noInputInterrupt.resolveInterrupt(true, { editedArgs: {} })
+
+declare const generic: Extract<
+  ChatInterrupt<readonly [typeof transfer]>,
+  { kind: 'generic' }
+>
+generic.resolveInterrupt({ applicationValue: 'runtime-validated' })
+```
+
+In `chat-client-interrupts.test.ts`, construct the manager with the literal `transfer` tool and hydrate one descriptor whose metadata binding contains matching `toolCallId`, `interruptedRunId`, `generation`, tool name, and hashes. Clone the case while changing each field independently and assert only the fully matching case becomes `tool-approval`; every mismatch becomes `generic`. Add matching/mismatched client-tool, unknown reason, invalid generic schema, and expired descriptor cases before production code.
+
+- [ ] **Step 2: Run the red client type target**
+
+Run both suites red:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-client test:types
+pnpm --filter @tanstack/ai-client test:lib -- --run tests/chat-client-interrupts.test.ts
+```
+
+Expected: FAIL because `ChatInterrupt`, bound variants, `InterruptManager`, and hydration do not exist.
+
+- [ ] **Step 3: Add the public base and mapped union**
+
+Define the public surface in `types.ts` and keep behavior private to the manager:
+
+```ts
+export interface BoundInterruptBase<TDraft> {
+  id: string
+  reason: string
+  message?: string
+  toolCallId?: string
+  responseSchema?: JSONSchema
+  expiresAt?: string
+  metadata?: Record<string, unknown>
+  kind: 'tool-approval' | 'client-tool-execution' | 'generic'
+  status: 'pending' | 'validating' | 'staged' | 'submitting' | 'error'
+  provenance: 'native' | 'legacy'
+  generation: number
+  errors: readonly ItemInterruptError[]
+  stagedResponse?: TDraft
+  clearResolution(): void
+  cancelInterrupt(): void
+}
+
+export interface GenericAGUIInterrupt extends BoundInterruptBase<
+  | { status: 'resolved'; payload: unknown }
+  | { status: 'cancelled' }
+> {
+  kind: 'generic'
+  toolName?: never
+  resolveInterrupt(payload: unknown): void
+}
+
+export type BoundInterrupts<
+  TTools extends readonly AnyClientTool[],
+> = readonly ChatInterrupt<TTools>[]
+
+declare const noSchema: unique symbol
+type NoSchema = typeof noSchema
+type InputSchemaOf<TTool> = TTool extends { inputSchema?: infer TSchema }
+  ? TSchema extends undefined ? NoSchema : TSchema
+  : NoSchema
+type OutputSchemaOf<TTool> = TTool extends { outputSchema?: infer TSchema }
+  ? TSchema extends undefined ? NoSchema : TSchema
+  : NoSchema
+type ApproveSchemaOf<TTool> = ApprovalSchemaOf<TTool> extends {
+  approve?: infer TSchema
+} ? TSchema extends undefined ? NoSchema : TSchema
+  : ApprovalSchemaOf<TTool> extends undefined ? NoSchema
+  : ApprovalSchemaOf<TTool>
+type RejectSchemaOf<TTool> = ApprovalSchemaOf<TTool> extends {
+  reject?: infer TSchema
+} ? TSchema extends undefined ? NoSchema : TSchema
+  : ApprovalSchemaOf<TTool> extends undefined ? NoSchema
+  : ApprovalSchemaOf<TTool>
+type EditedArgsField<TSchema> = TSchema extends NoSchema
+  ? { editedArgs?: never }
+  : { editedArgs?: InferSchemaType<TSchema> }
+type PayloadField<TSchema> = TSchema extends NoSchema
+  ? { payload?: never }
+  : TSchema extends JSONSchema
+    ? { payload: unknown }
+    : undefined extends InferSchemaType<TSchema>
+      ? { payload?: InferSchemaType<TSchema> }
+      : { payload: InferSchemaType<TSchema> }
+type RequiredKeys<T> = {
+  [TKey in keyof T]-?: Record<string, never> extends Pick<T, TKey>
+    ? never
+    : TKey
+}[keyof T]
+type OptionsTuple<T> = [RequiredKeys<T>] extends [never]
+  ? [options?: T]
+  : [options: T]
+
+export interface ToolApprovalInterrupt<TTool extends AnyClientTool>
+  extends BoundInterruptBase<
+    | ({ status: 'resolved'; approved: true } &
+        EditedArgsField<InputSchemaOf<TTool>> &
+        PayloadField<ApproveSchemaOf<TTool>>)
+    | ({ status: 'resolved'; approved: false } &
+        PayloadField<RejectSchemaOf<TTool>>)
+    | { status: 'cancelled' }
+  > {
+  kind: 'tool-approval'
+  reason: 'tool_call'
+  toolName: TTool['name']
+  toolCallId: string
+  resolveInterrupt(
+    approved: true,
+    ...options: OptionsTuple<
+      EditedArgsField<InputSchemaOf<TTool>> & PayloadField<ApproveSchemaOf<TTool>>
+    >
+  ): void
+  resolveInterrupt(
+    approved: false,
+    ...options: OptionsTuple<PayloadField<RejectSchemaOf<TTool>>>
+  ): void
+}
+
+export interface ClientToolExecutionInterrupt<TTool extends AnyClientTool>
+  extends BoundInterruptBase<
+    | { status: 'resolved'; payload: InferSchemaType<OutputSchemaOf<TTool>> }
+    | { status: 'cancelled' }
+  > {
+  kind: 'client-tool-execution'
+  reason: 'tanstack:client_tool_execution'
+  toolName: TTool['name']
+  toolCallId: string
+  resolveInterrupt(output: InferSchemaType<OutputSchemaOf<TTool>>): void
+}
+
+type ToolByName<TTools extends readonly AnyClientTool[], TName extends string> =
+  Extract<TTools[number], { name: TName }>
+type ToolNames<TTools extends readonly AnyClientTool[]> = TTools[number]['name']
+type ApprovalNames<TTools extends readonly AnyClientTool[]> = {
+  [TName in ToolNames<TTools>]: ApprovalCapabilityOf<
+    ToolByName<TTools, TName>
+  > extends true ? TName : never
+}[ToolNames<TTools>]
+type ToolApprovalInterruptsFor<TTools extends readonly AnyClientTool[]> = {
+  [TName in ApprovalNames<TTools>]: ToolApprovalInterrupt<ToolByName<TTools, TName>>
+}[ApprovalNames<TTools>]
+type ClientToolExecutionInterruptsFor<TTools extends readonly AnyClientTool[]> = {
+  [TName in ToolNames<TTools>]: ClientToolExecutionInterrupt<ToolByName<TTools, TName>>
+}[ToolNames<TTools>]
+export type ChatInterrupt<TTools extends readonly AnyClientTool[]> =
+  | ToolApprovalInterruptsFor<TTools>
+  | ClientToolExecutionInterruptsFor<TTools>
+  | GenericAGUIInterrupt
+```
+
+Use this contiguous type block verbatim and add the shared/branch/omitted/raw/optional assertions named in Step 1. `OutputSchemaOf<NoSchema>` maps to `unknown` for client-tool execution rather than exposing the private sentinel.
+
+- [ ] **Step 4: Hydrate only trusted known-tool matches**
+
+Create `InterruptManager<TTools>` with injected tools, submit, recovery, state-change, and draft-persistence callbacks. Hydration follows this decision:
+
+```ts
+function classifyDescriptor<TTools extends readonly AnyClientTool[]>(
+  descriptor: Interrupt,
+  registry: ToolRegistry<TTools>,
+  correlation: {
+    interruptedRunId: string
+    generation: number
+  },
+): HydratedKind<TTools> {
+  const binding = readUntrustedDescriptorBinding(descriptor.metadata)
+  if (
+    descriptor.reason === 'tool_call' &&
+    descriptor.toolCallId &&
+    binding?.kind === 'tool-approval' &&
+    descriptor.toolCallId === binding.toolCallId &&
+    binding.interruptedRunId === correlation.interruptedRunId &&
+    binding.generation === correlation.generation
+  ) {
+    const tool = registry.approvalTools.get(binding.toolName)
+    if (tool && registry.matchesHashes(tool, binding)) {
+      return { kind: 'tool-approval', tool, binding }
+    }
+  }
+  if (
+    descriptor.reason === 'tanstack:client_tool_execution' &&
+    descriptor.toolCallId &&
+    binding?.kind === 'client-tool-execution' &&
+    descriptor.toolCallId === binding.toolCallId &&
+    binding.interruptedRunId === correlation.interruptedRunId &&
+    binding.generation === correlation.generation
+  ) {
+    const tool = registry.tools.get(binding.toolName)
+    if (tool && registry.matchesHashes(tool, binding)) {
+      return { kind: 'client-tool-execution', tool, binding }
+    }
+  }
+  return { kind: 'generic' }
+}
+```
+
+`InterruptManager.hydrate` passes its own authoritative correlation into this function; it never reads the expected run/generation from the descriptor alone. Bind methods to manager/item IDs, compile generic response schemas with Task 1, retain configured Standard Schema validators for known tools, and expose core-cloned/deep-frozen snapshots.
+
+- [ ] **Step 5: Run the already-red hydration tests green**
+
+Run the tests written in Step 1:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-client test:lib -- --run tests/chat-client-interrupts.test.ts
+```
+
+Expected: PASS; forged/mismatched descriptors are generic and an invalid generic schema can only be cancelled.
+
+- [ ] **Step 6: Run green type checks and refactor**
+
+Run:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-client test:types
+pnpm --filter @tanstack/ai-client test:lib -- --run tests/chat-client-interrupts.test.ts
+```
+
+Expected: PASS. Extract type helpers (`NoSchema`, branch selectors, required-key tuple) into one contiguous section and registry hashing into one private class; rerun both commands.
+
+### Task 11: Implement staging, callback transactions, bulk operations, and retry
+
+**Prerequisites:** Task 10.
+
+**Files:**
+- Modify: `packages/ai-client/src/interrupt-manager.ts`
+- Modify: `packages/ai-client/src/types.ts`
+- Modify: `packages/ai-client/tests/chat-client-interrupts.test.ts`
+
+- [ ] **Step 1: Add failing state-machine tests**
+
+Cover singleton resolve/cancel auto-submit; three-item wait; replacement; clear; async validator generations; invalid replacement preserving the previous valid draft; submitting mutation rejection; root boolean eligibility; callback visit-once/submit-once; throw/non-`undefined`/thenable/incomplete rollback; late post-await token use; transport frozen retry; mutation invalidating retry; server item/root errors; acceptance removal; and status/error notifications.
+
+Use a deferred async-callback regression:
+
+```ts
+function deferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise
+    reject = rejectPromise
+  })
+  return { promise, resolve, reject }
+}
+
+const testTools = [transferTool, auditTool, notificationTool] as const
+type TestTools = typeof testTools
+
+function createThreeInterruptManager(options: {
+  submit: InterruptManagerOptions<TestTools>['submit']
+}) {
+  const manager = new InterruptManager({
+    tools: testTools,
+    submit: options.submit,
+    onStateChange: vi.fn(),
+  })
+  manager.hydrate({
+    threadId: 'thread-1',
+    interruptedRunId: 'run-old',
+    generation: 1,
+    descriptors: threeApprovalDescriptors,
+  })
+  return manager
+}
+
+it('invalidates a callback token before a late async item call', async () => {
+  const gate = deferred<void>()
+  const submit = vi.fn()
+  const manager = createThreeInterruptManager({ submit })
+  let captured: ChatInterrupt<TestTools> | undefined
+
+  await expect(
+    manager.resolveInterrupts(((interrupt: ChatInterrupt<TestTools>) => {
+      captured = interrupt
+      return gate.promise.then(() => {
+        interrupt.cancelInterrupt()
+      })
+    }) as (interrupt: ChatInterrupt<TestTools>) => undefined),
+  ).rejects.toMatchObject({ code: 'async-resolver' })
+
+  gate.resolve()
+  await gate.promise
+  captured?.cancelInterrupt()
+  expect(submit).not.toHaveBeenCalled()
+  expect(manager.interruptErrors).toContainEqual(
+    expect.objectContaining({ code: 'inactive-transaction' }),
+  )
+})
+```
+
+Define `transferTool`, `auditTool`, and `notificationTool` immediately above this block with literal names and payload-less approval branches. Define `threeApprovalDescriptors` as three native `tool_call` descriptors whose reserved bindings and schema hashes match those tools. `InterruptManagerOptions`, `hydrate`, and `onStateChange` are the concrete public-to-package-private constructor seam established in Task 10; use these exact names in implementation and tests so the fixture does not depend on hidden maps.
+
+- [ ] **Step 2: Run the red state-machine test**
+
+Run:
+
+```powershell
+pnpm --filter @tanstack/ai-client test:lib -- --run tests/chat-client-interrupts.test.ts
+```
+
+Expected: FAIL because bound methods do not yet stage, gate, roll back, freeze, or retry.
+
+- [ ] **Step 3: Implement synchronous candidate staging with async validation generations**
+
+Item methods return `void`. Each candidate increments an item generation, sets `validating` when a Standard Schema result is thenable, and ignores a result whose captured generation is stale. A valid candidate replaces the draft; an invalid candidate keeps the last valid `stagedResponse`, sets item errors/status, and blocks submission. Cancellation is payloadless and needs no schema validation. `clearResolution` removes draft/errors and returns to pending. Replacement/clear/cancel while submitting throws a non-retryable protocol error.
+
+- [ ] **Step 4: Freeze and submit only a complete valid batch**
+
+Implement one submission gate:
+
+```ts
+private maybeSubmit(): void {
+  if (this.transaction || this.submission || this.items.size === 0) return
+  const items = [...this.items.values()]
+  if (items.some((item) => item.status === 'validating' || item.status === 'error')) return
+  if (items.some((item) => item.draft === undefined)) return
+  const entries = items
+    .map((item) => item.draft?.response)
+    .filter((entry): entry is RunAgentResumeItem => entry !== undefined)
+    .sort((a, b) => a.interruptId.localeCompare(b.interruptId))
+  const candidate = canonicalizeInterruptResolutions(entries)
+  const frozen = cloneAndDeepFreezeJson({
+    generation: this.batchGeneration,
+    entries: candidate.resolutions,
+    fingerprint: candidate.fingerprint,
+    canonicalResolutions: candidate.canonicalResolutions,
+  })
+  void this.submitFrozenBatch(frozen)
+}
+```
+
+A singleton reaches this gate after its first valid decision. Multiple items wait for complete coverage. During submission every item is `submitting`. Acceptance removes active descriptors/drafts. A retryable transport/availability failure restores `staged`, retains the exact frozen batch, and appends a root transport/server error.
+
+- [ ] **Step 5: Implement root boolean and synchronous callback transactions**
+
+The boolean overload first verifies every open item is a tool approval and the chosen branch has no required payload; only then stage all and submit once. For callbacks, capture one stable item snapshot, clone all drafts/errors/statuses, install a unique token, suppress auto-submit, and invoke once per item. Require literal runtime return `undefined`; reject thenables and other values. On throw, invalid return, or incomplete coverage, restore the clone, seal the token, increment generation, and start no request. Transaction-scoped item methods check the active token and generation; late calls add `inactive-transaction` without mutation.
+
+- [ ] **Step 6: Implement cancel-all, exact retry, and error mapping**
+
+`cancelInterrupts()` stages payloadless cancellation for the stable full set and submits once. `retryInterrupts()` is allowed only while an intact retryable frozen batch exists. Any edit/clear/cancel after failure increments batch generation, clears the frozen fingerprint and superseded transport error, and disables retry. Map item server errors by `interruptId`; map batch/transport errors only to `interruptErrors`. Expired/stale/conflict results invoke recovery instead of retry.
+
+- [ ] **Step 7: Run green state-machine tests and refactor**
+
+Run:
+
+```powershell
+pnpm --filter @tanstack/ai-client test:lib -- --run tests/chat-client-interrupts.test.ts
+pnpm --filter @tanstack/ai-client test:types
+```
+
+Expected: PASS; one interrupt submits immediately, three wait, callback failures roll back, and late async calls cannot submit. Refactor snapshots, token sealing, and status notifications into focused private helpers and rerun both commands.
+
+### Task 12: Integrate the manager into ChatClient and legacy compatibility
+
+**Prerequisites:** Task 11.
+
+**Files:**
+- Modify: `packages/ai-client/src/chat-client.ts:41-146,191-275,510-706,967-1070,1403-1585`
+- Modify: `packages/ai-client/src/connection-adapters.ts:353-450,1171-1205`
+- Modify: `packages/ai-client/src/types.ts:397-585`
+- Modify: `packages/ai-client/src/index.ts`
+- Modify: `packages/ai-client/tests/chat-client-interrupts.test.ts`
+- Modify: `packages/ai-client/tests/chat-client-resume.test.ts`
+- Modify: `packages/ai-client/tests/chat-client-client-tool-status.test.ts`
+- Modify: `packages/ai-client/tests/connection-adapters.test.ts`
+
+- [ ] **Step 1: Add failing transport/integration/compatibility tests**
+
+Prove that a native resume sends no messages, uses a fresh run ID with `parentRunId` equal to the interrupted run, parses item/root error extensions, recognizes the replay terminal, and blocks unrelated input. Add legacy approval/custom-tool events and assert one history request with no native resume. Add the sandbox collision case:
+
+```ts
+client.processChunk({
+  type: EventType.CUSTOM,
+  name: 'approval-requested',
+  value: { approvalId: 'sandbox-approval', operation: 'process.exec' },
+  timestamp: Date.now(),
+})
+expect(client.getInterrupts()).toEqual([])
+```
+
+Also assert `addToolApprovalResponse({ approved: false })` stages a resolved denial, `cancelInterrupt` emits `cancelled`, `addToolResult` delegates to a matching client-tool interrupt, mixed provenance stops, and native server events never cause a legacy follow-up.
+
+- [ ] **Step 2: Run the red integration tests**
+
+Run:
+
+```powershell
+pnpm --filter @tanstack/ai-client test:lib -- --run tests/chat-client-interrupts.test.ts tests/chat-client-resume.test.ts tests/chat-client-client-tool-status.test.ts tests/connection-adapters.test.ts
+```
+
+Expected: FAIL because ChatClient still owns raw `pendingInterrupts`, reuses the interrupted run ID, and sends compatibility responses directly.
+
+- [ ] **Step 3: Make InterruptManager the single normalized owner**
+
+Replace `private pendingInterrupts` and `pendingInterruptRunId` with one manager. `observeInterruptState` hydrates native outcomes with `{ threadId, interruptedRunId, generation }`; RUN_ERROR extensions flow to manager error/recovery handling. Expose:
+
+```ts
+getInterrupts(): BoundInterrupts<TTools>
+getInterruptErrors(): readonly InterruptSubmissionError[]
+getIsResuming(): boolean
+
+/** @deprecated Use getInterrupts(). Removed in 1.0. */
+getPendingInterrupts(): BoundInterrupts<TTools>
+
+resolveInterrupts(
+  decisionOrResolver: boolean | ((interrupt: ChatInterrupt<TTools>) => undefined),
+): Promise<void>
+
+cancelInterrupts(): Promise<void>
+retryInterrupts(): Promise<void>
+resumeInterruptsUnsafe(
+  entries: readonly RunAgentResumeItem[],
+  state?: ChatResumeState,
+): Promise<void>
+
+/** @deprecated Use resumeInterruptsUnsafe(). Removed in 1.0. */
+resumeInterrupts(
+  entries: readonly RunAgentResumeItem[],
+  state?: ChatResumeState,
+): Promise<boolean>
+```
+
+Add one immutable state notification so frameworks never compose three independently timed reads:
+
+```ts
+export interface ChatInterruptState<TTools extends readonly AnyClientTool[]> {
+  interrupts: BoundInterrupts<TTools>
+  interruptErrors: readonly InterruptSubmissionError[]
+  isResuming: boolean
+}
+
+onInterruptStateChange?: (
+  state: ChatInterruptState<TTools>,
+) => void
+```
+
+Emit it after every hydration, draft/error/status transition, submission start/end, recovery replacement, reset, and disposal. `getInterrupts`, `getInterruptErrors`, and `getIsResuming` return the exact current immutable snapshot fields.
+
+Create one fresh deeply frozen `BoundInterrupts<TTools>` array per notification. `getInterrupts()`, deprecated `getPendingInterrupts()`, hook `interrupts`, and hook `pendingInterrupts` all return that exact array object. Do not maintain a second raw descriptor store or project legacy DTOs into the deprecated alias.
+
+- [ ] **Step 4: Send continuations with new run correlation**
+
+When manager submits a native batch, generate a new run ID, keep the same thread, set `parentRunId` to the interrupted run, send the complete `resume` array, and send `[]` messages. `resumeInterruptsUnsafe` uses the same correlation/submission path but accepts raw entries. Keep expiry, exact set, server validation, and CAS enforced.
+
+- [ ] **Step 5: Handle replay and structured failures**
+
+Parse `tanstack:interruptErrors` and `tanstack:interruptRecovery` from RUN_ERROR. For a committed recovery DTO or canonical interrupt-replay result, attach only to the winning continuation:
+
+```ts
+private async attachWinningContinuation(
+  threadId: string,
+  continuationRunId: string,
+): Promise<void> {
+  const controller = new AbortController()
+  const chunks =
+    this.connection && 'joinRun' in this.connection
+      ? this.connection.joinRun(continuationRunId, controller.signal)
+      : this.options.continuationLoader
+        ? this.options.continuationLoader(
+            { threadId, continuationRunId },
+            { signal: controller.signal },
+          )
+        : undefined
+  if (!chunks) {
+    this.interruptManager.quarantineForRecovery({
+      code: 'recovery-unavailable',
+      message: 'The winning continuation cannot be joined by this client.',
+      continuationRunId,
+    })
+    return
+  }
+  await this.consumeReadOnlyContinuation(chunks, continuationRunId)
+}
+
+private processIncomingChunk(chunk: StreamChunk): void {
+  this.callbacksRef.current.onChunk(chunk)
+  this.devtoolsBridge.observeChunk(chunk)
+  this.processor.processChunk(chunk)
+  this.updateRunLifecycle(chunk)
+  this.observeInterruptState(chunk)
+}
+
+private async consumeReadOnlyContinuation(
+  chunks: AsyncIterable<StreamChunk>,
+  continuationRunId: string,
+): Promise<void> {
+  for await (const chunk of chunks) {
+    const chunkRunId = getChunkRunId(chunk)
+    if (chunkRunId !== undefined && chunkRunId !== continuationRunId) {
+      throw new Error('Continuation loader returned a different run.')
+    }
+    this.processIncomingChunk(chunk)
+  }
+}
+```
+
+Replace the duplicated incoming-chunk statements in the existing connect/subscription loops with `processIncomingChunk(chunk)`. The read-only loader never calls `connect`, `sendMessage`, `reload`, the model endpoint, or the interrupt recovery loader. Tests provide a non-resumable connection plus a spy `continuationLoader`, assert the loader receives the stored winning ID, and assert no new model run is scheduled. A client with neither `joinRun` nor `continuationLoader` remains quarantined with `recovery-unavailable`.
+
+- [ ] **Step 6: Normalize legacy readers without a dual writer**
+
+Recognize legacy `approval-requested` only when its value has `toolCallId`, `toolName`, and `approval: { id, needsApproval: true }`; recognize `tool-input-available` only with its full historical tool shape. This prevents sandbox's path-only approval event from colliding. Hydrate `provenance: 'legacy'` and reject edits, custom payloads, generic responses, native cancellation, expiry, and conflict recovery as `legacy-unsupported`.
+
+When all legacy items are covered, clone current message history, update every matching approval/result part in the clone, and send one follow-up history request with no `resume`. On construction failure, change no live message. On transport failure, keep staged responses and report `legacy-submit-failed`. Reject mixed native/legacy sets before any mutation.
+
+- [ ] **Step 7: Deprecate approval APIs and preserve client-tool results**
+
+Add removal-at-1.0 JSDoc to `addToolApprovalResponse`, `pendingInterrupts`/`getPendingInterrupts`, raw `resumeInterrupts`, and legacy custom-event reader types. Implement `addToolApprovalResponse` by finding the bound item and calling `resolveInterrupt(response.approved)`; false is denial, not cancellation. Implement old `resumeInterrupts` as a compatibility wrapper over `resumeInterruptsUnsafe` while retaining its historical return type. Keep `addToolResult` supported and delegate to `resolveInterrupt(output)` for a matching native client-tool item or the legacy history backend for an old event.
+
+- [ ] **Step 8: Run green integration checks and refactor**
+
+Run:
+
+```powershell
+pnpm --filter @tanstack/ai-client test:lib -- --run tests/chat-client-interrupts.test.ts tests/chat-client-resume.test.ts tests/chat-client-client-tool-status.test.ts tests/connection-adapters.test.ts
+pnpm --filter @tanstack/ai-client test:types
+```
+
+Expected: PASS; native continuation context has a new run ID/old parent, denial and cancellation differ, sandbox events do not hydrate, and `addToolResult` remains supported. Remove duplicated approval batching logic from ChatClient and rerun both commands.
+
+### Task 13: Persist raw V2 drafts and recover through explicit adapters
+
+**Prerequisites:** Tasks 11 and 12.
+
+**Files:**
+- Modify: `packages/ai-client/src/chat-persistence-controller.ts`
+- Modify: `packages/ai-client/src/connection-adapters.ts:353-450,574-700,1171-1205`
+- Modify: `packages/ai-client/src/types.ts:18-110,397-435`
+- Modify: `packages/ai-client/src/chat-client.ts:250-275,485-520,698-706,1393-1410`
+- Modify: `packages/ai-client/src/index.ts`
+- Modify: `packages/ai-client/tests/chat-persistence-controller.test.ts`
+- Modify: `packages/ai-client/tests/chat-client-resume.test.ts`
+- Modify: `packages/ai-client/tests/connection-adapters.test.ts`
+
+- [ ] **Step 1: Add failing V1/V2 reconciliation and recovery tests**
+
+Test a partial one-of-three draft reload, V1 migration, mismatched thread/run/generation/ID/schema hash, expiry, committed winner, accepted tombstone after failed removal, reset/dispose stale-write suppression, event-extension recovery, fallback fetch, unauthorized/newer generation checks, and no-loader quarantine.
+
+Use an assertion that persisted values contain no functions or hydrated fields:
+
+```ts
+const stored = JSON.parse(JSON.stringify(resumeAdapter.setItem.mock.calls.at(-1)?.[1]))
+expect(stored.schemaVersion).toBe(2)
+expect(stored.interruptState.drafts).toHaveLength(1)
+expect(JSON.stringify(stored)).not.toContain('resolveInterrupt')
+expect(JSON.stringify(stored)).not.toContain('errors')
+expect(JSON.stringify(stored)).not.toContain('kind')
+```
+
+- [ ] **Step 2: Run the red durability tests**
+
+Run:
+
+```powershell
+pnpm --filter @tanstack/ai-client test:lib -- --run tests/chat-client-resume.test.ts tests/chat-persistence-controller.test.ts tests/connection-adapters.test.ts
+```
+
+Expected: FAIL because snapshots are unversioned, store raw pending descriptors only, and no recovery loader exists.
+
+- [ ] **Step 3: Define the raw V2 snapshot and V1 migration**
+
+Add the exact JSON DTO:
+
+```ts
+export interface ChatResumeSnapshotV2 {
+  schemaVersion: 2
+  resumeState: ChatResumeState
+  interruptState?: {
+    provenance: 'native' | 'legacy'
+    phase: 'pending' | 'accepted'
+    interruptedRunId: string
+    generation: number
+    descriptorsHash: string
+    descriptors: readonly Interrupt[]
+    drafts: readonly {
+      interruptId: string
+      responseSchemaHash: string
+      response: RunAgentResumeItem
+      savedAt: string
+    }[]
+    continuationRunId?: string
+  }
+}
+```
+
+Treat the PR-head unversioned `{ resumeState, pendingInterrupts }` shape as V1. Convert it to V2 generation `0`, native descriptors, no drafts, and `requiresRecovery: true` internally. Remove invalid/unrelatable V1 storage and report a root protocol error. Never serialize methods, validators, configured tools, kind, or error objects.
+
+- [ ] **Step 4: Reconcile drafts only after authoritative recovery**
+
+On native hydration, call recovery before binding. Accept only matching `(threadId, interruptedRunId)` and a generation not older than local. For `pending`, bind returned descriptors against the current tool registry, then retain a draft only when generation, interrupt ID, canonical response-schema hash, and expiry all match. For `committed`, clear drafts and attach/join the winning continuation. For `expired`, `missing`, and `legacy-committed`, clear unsafe retry state and expose the specified non-retryable error. Without extension or loader, quarantine drafts, disable submission, and expose `recovery-unavailable`.
+
+- [ ] **Step 5: Add explicit connection and fetcher recovery contracts**
+
+Extend connection adapters with an optional method:
+
+```ts
+export interface InterruptRecoveryConnection {
+  loadInterruptState(
+    input: InterruptRecoveryQuery,
+    options: { signal: AbortSignal },
+  ): Promise<InterruptRecoveryStateV1>
+}
+
+export type InterruptContinuationLoader = (
+  input: {
+    threadId: string
+    continuationRunId: string
+  },
+  options: { signal: AbortSignal },
+) => AsyncIterable<StreamChunk>
+```
+
+Add `interruptStateFetcher?: InterruptStateFetcher` and `continuationLoader?: InterruptContinuationLoader` beside `fetcher` in fetcher mode. Provide explicit helpers that require caller-supplied URLs:
+
+```ts
+export function createInterruptStateFetcher(
+  url: string | (() => string),
+  options: FetchConnectionOptions = {},
+): InterruptStateFetcher {
+  return async (input, { signal }) => {
+    const response = await (options.fetchClient ?? fetch)(
+      typeof url === 'function' ? url() : url,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...mergeHeaders(options.headers) },
+        credentials: options.credentials ?? 'same-origin',
+        signal,
+        body: JSON.stringify(input),
+      },
+    )
+  if (!response.ok) throw new Error(`Interrupt recovery failed: ${response.status}`)
+  return parseInterruptRecoveryState(await response.json())
+  }
+}
+
+export function createInterruptContinuationLoader(
+  url: string | (() => string),
+  options: FetchConnectionOptions = {},
+): InterruptContinuationLoader {
+  return async function* loadContinuation(input, { signal }) {
+    const requestUrl = withSearchParams(
+      typeof url === 'function' ? url() : url,
+      {
+        runId: input.continuationRunId,
+        offset: '-1',
+      },
+    )
+    yield* resumableServerSentEvents(
+      options.fetchClient ?? fetch,
+      requestUrl,
+      {
+        method: 'GET',
+        headers: mergeHeaders(options.headers),
+        credentials: options.credentials ?? 'same-origin',
+      },
+      signal,
+    )
+  }
+}
+```
+
+Implement `parseInterruptRecoveryState(value: unknown)` beside the fetcher with explicit object, version, state, correlation, generation, descriptor, and committed-shape checks; it returns `InterruptRecoveryStateV1` only after narrowing and throws a protocol error otherwise. `mergeHeaders`, `withSearchParams`, and `resumableServerSentEvents` are existing functions in this module. `fetchServerSentEvents` already provides `joinRun`; raw-stream/fetcher adapters expose only explicitly supplied `loadInterruptState` and `continuationLoader`. They never derive either path from the chat URL, and continuation loading is always a read-only GET of the winning run.
+
+- [ ] **Step 6: Write accepted tombstones before cleanup**
+
+After acceptance, remove active descriptors/drafts, persist `{ phase: 'accepted', continuationRunId, drafts: [] }`, then queue `removeItem`. If removal fails, the tombstone prevents stale pending UI on reload and cleanup retries after authoritative committed recovery. Thread reset and controller disposal increment generations so old async reads/writes cannot restore state.
+
+- [ ] **Step 7: Run green durability checks and refactor**
+
+Run:
+
+```powershell
+pnpm --filter @tanstack/ai-client test:lib -- --run tests/chat-client-interrupts.test.ts tests/chat-client-resume.test.ts tests/chat-persistence-controller.test.ts tests/connection-adapters.test.ts
+pnpm --filter @tanstack/ai-client test:types
+```
+
+Expected: PASS; one draft survives a safe reload, drifted drafts are removed, committed state attaches to the winning run, and no URL is guessed. Extract V1 parsing, V2 cloning, and reconciliation predicates into pure functions and rerun both commands.
+
+### Task 14: Write every framework behavior and type contract red
+
+**Prerequisites:** Tasks 12 and 13. This task changes tests only; no framework source or public type is modified until every runtime and type suite has failed for the intended missing API.
+
+**Files:**
+
+- Modify: `packages/ai-react/tests/use-chat.test.ts`
+- Modify: `packages/ai-react/tests/use-chat-types.test.ts`
+- Modify: `packages/ai-preact/tests/use-chat.test.ts`
+- Modify: `packages/ai-preact/tests/use-chat-types.test.ts`
+- Modify: `packages/ai-solid/tests/use-chat.test.ts`
+- Modify: `packages/ai-solid/tests/use-chat-types.test.ts`
+- Modify: `packages/ai-vue/tests/use-chat.test.ts`
+- Modify: `packages/ai-vue/tests/use-chat-types.test.ts`
+- Modify: `packages/ai-svelte/tests/use-chat.test.ts`
+- Modify: `packages/ai-svelte/tests/create-chat-types.test.ts`
+- Modify: `packages/ai-angular/tests/inject-chat.test.ts`
+- Modify: `packages/ai-angular/tests/inject-chat-types.test.ts`
+
+- [ ] **Step 1: Write the bound-state behavior contract in all six runtime suites**
+
+In each framework test utility, capture the `ChatClientOptions.onInterruptStateChange` callback and return root spies for `resolveInterrupts`, `cancelInterrupts`, `retryInterrupts`, and `resumeInterruptsUnsafe`. The callback accepts one `ChatInterruptState<TTools>` object. Use two bound items so calling one synchronous item resolver cannot represent the singleton auto-submit case:
+
+```ts
+it('reactively projects immutable interrupt state and delegates root methods', async () => {
+  const { result } = renderHook(() => useChat({ tools: [transferTool] }))
+  const first = createBoundToolInterrupt({
+    id: 'approval-1',
+    status: 'staged',
+    stagedResponse: {
+      status: 'resolved',
+      approved: true,
+      editedArgs: { amount: 10 },
+    },
+  })
+  const second = createBoundToolInterrupt({
+    id: 'approval-2',
+    status: 'pending',
+  })
+  const staged: ChatInterruptState<readonly [typeof transferTool]> = {
+    interrupts: Object.freeze([first, second]),
+    interruptErrors: [],
+    isResuming: false,
+  }
+  act(() => chatClientCallbacks.onInterruptStateChange?.(staged))
+
+  expect(result.current.interrupts).toBe(staged.interrupts)
+  expect(result.current.pendingInterrupts).toBe(staged.interrupts)
+  expect(result.current.interrupts[0]?.resolveInterrupt(true)).toBeUndefined()
+  expect(first.resolveInterrupt).toHaveBeenCalledWith(true)
+
+  const invalid = createBoundToolInterrupt({
+    id: 'approval-1',
+    status: 'error',
+    stagedResponse: first.stagedResponse,
+    errors: [
+      itemError('approval-1', 'invalid-edited-args', ['amount']),
+    ],
+  })
+  const transport = batchError('transport', ['approval-1', 'approval-2'])
+  const failed: ChatInterruptState<readonly [typeof transferTool]> = {
+    interrupts: Object.freeze([invalid, second]),
+    interruptErrors: [transport],
+    isResuming: true,
+  }
+  act(() => chatClientCallbacks.onInterruptStateChange?.(failed))
+  expect(result.current.interrupts[0]?.status).toBe('error')
+  expect(result.current.interrupts[0]?.errors).toEqual(invalid.errors)
+  expect(result.current.interruptErrors).toEqual([transport])
+  expect(result.current.isResuming).toBe(true)
+
+  const resolver = (item: ChatInterrupt<readonly [typeof transferTool]>) => {
+    item.cancelInterrupt()
+    return undefined
+  }
+  await act(() => result.current.resolveInterrupts(resolver))
+  expect(chatClientRootSpies.resolveInterrupts).toHaveBeenCalledWith(resolver)
+  expect(resolver(second)).toBeUndefined()
+  await act(() => result.current.cancelInterrupts())
+  await act(() => result.current.retryInterrupts())
+  expect(chatClientRootSpies.cancelInterrupts).toHaveBeenCalledOnce()
+  expect(chatClientRootSpies.retryInterrupts).toHaveBeenCalledOnce()
+})
+```
+
+Define `transferTool` with `toolDefinition({ name: 'transfer', needsApproval: true, inputSchema: z.object({ amount: z.number() }) })`. The test-only `createBoundToolInterrupt`, `itemError`, and `batchError` functions return fully correlated frozen public DTOs; their bound methods are `vi.fn<() => void>()`. They live in each package's existing `tests/test-utils.ts`, not in production. React and Preact use the displayed `renderHook`/their imported `act`; Solid reads `result.current.interrupts()`; Vue reads `result.current.interrupts.value` after `flushPromises()`; Svelte reads `chat.interrupts` after `await tick()`; Angular reads `result.interrupts()` after `TestBed.flushEffects()`. Each file performs every displayed identity, status, error, draft, root-error, and root-spy assertion with that exact native accessor.
+
+- [ ] **Step 2: Add branch-aware type failures to all six type suites**
+
+In each type-test file define this local tool and run the assertions against that framework's public result:
+
+```ts
+const transferTool = toolDefinition({
+  name: 'transfer',
+  description: 'Transfer funds',
+  inputSchema: z.object({ amount: z.number(), recipient: z.string() }),
+  needsApproval: true,
+  approvalSchema: {
+    approve: z.object({ note: z.string() }),
+    reject: z.object({ reason: z.string() }),
+  },
+})
+const tools = [transferTool] as const
+
+function assertInterruptTypes(
+  interrupt: ChatInterrupt<readonly [typeof transferTool]> | undefined,
+): void {
+  if (!interrupt) return
+  if (interrupt.kind === 'tool-approval' && interrupt.toolName === 'transfer') {
+    interrupt.resolveInterrupt(true, {
+      editedArgs: { amount: 12, recipient: 'Ada' },
+      payload: { note: 'Reviewed' },
+    })
+    interrupt.resolveInterrupt(false, {
+      payload: { reason: 'Limit exceeded' },
+    })
+    // @ts-expect-error approval cannot use the rejection payload
+    interrupt.resolveInterrupt(true, { payload: { reason: 'wrong branch' } })
+    // @ts-expect-error editedArgs preserve the input schema
+    interrupt.resolveInterrupt(true, {
+      editedArgs: { amount: '12', recipient: 'Ada' },
+      payload: { note: 'Reviewed' },
+    })
+    // @ts-expect-error rejection never accepts editedArgs
+    interrupt.resolveInterrupt(false, {
+      editedArgs: { amount: 12, recipient: 'Ada' },
+      payload: { reason: 'No' },
+    })
+  }
+  if (interrupt.kind === 'generic') {
+    type GenericPayload = Parameters<typeof interrupt.resolveInterrupt>[0]
+    expectTypeOf<GenericPayload>().toEqualTypeOf<unknown>()
+    interrupt.resolveInterrupt({ applicationValue: 'runtime validated' })
+  }
+}
+```
+
+Call `assertInterruptTypes` with these exact public expressions: React `renderHook(() => useChat({ tools })).result.current.interrupts[0]`; Preact `renderHook(() => useChat({ tools })).result.current.interrupts[0]`; Solid `useChat({ tools }).interrupts()[0]` inside its existing root; Vue `useChat({ tools }).interrupts.value[0]` inside its effect scope; Svelte `createChat({ tools }).interrupts[0]` inside its rune fixture; Angular `injectChat({ tools }).interrupts()[0]` inside its injection context.
+
+- [ ] **Step 3: Run all twelve framework suites red**
+
+Run sequentially to cap native Windows memory use:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-react test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-react test:types
+pnpm --filter @tanstack/ai-preact test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-preact test:types
+pnpm --filter @tanstack/ai-solid test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-solid test:types
+pnpm --filter @tanstack/ai-vue test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-vue test:types
+pnpm --filter @tanstack/ai-svelte test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-svelte test:types
+pnpm --filter @tanstack/ai-angular test:lib -- --run tests/inject-chat.test.ts
+pnpm --filter @tanstack/ai-angular test:types
+```
+
+Expected: all runtime and type suites FAIL because `interrupts`, `resolveInterrupts`, `cancelInterrupts`, `retryInterrupts`, `interruptErrors`, `isResuming`, `resumeInterruptsUnsafe`, and branch-specific inference are not exposed. Save the failing command/output in the task transcript; do not modify framework source in Task 14.
+
+- [ ] **Step 4: Confirm the red commit boundary**
+
+Run `git diff --name-only` and confirm Task 14 changed only the twelve named runtime/type test files and the six existing test-utility files. Do not commit. Framework source and public type declarations remain untouched until Task 15, so every type-red assertion predates the implementation it drives.
+
+### Task 15: Implement reactive and typed framework parity
+
+**Prerequisites:** Task 14.
+
+**Files:**
+
+- Modify: `packages/ai-react/src/use-chat.ts:52,87-212,426-444`
+- Modify: `packages/ai-react/src/types.ts:102-173`
+- Modify: `packages/ai-preact/src/use-chat.ts:51,86-190,349-367`
+- Modify: `packages/ai-preact/src/types.ts:102-173`
+- Modify: `packages/ai-solid/src/use-chat.ts:60-70,83-166,323-344`
+- Modify: `packages/ai-solid/src/types.ts:8-76,138-159`
+- Modify: `packages/ai-vue/src/use-chat.ts:60-64,83-162,328-349`
+- Modify: `packages/ai-vue/src/types.ts:116-159`
+- Modify: `packages/ai-svelte/src/create-chat.svelte.ts:79-82,98-178,333-376`
+- Modify: `packages/ai-svelte/src/types.ts:116-161`
+- Modify: `packages/ai-angular/src/inject-chat.ts:57-65,75-114,250-268`
+- Modify: `packages/ai-angular/src/types.ts:98-141`
+
+- [ ] **Step 1: Add the public generic control fields**
+
+Import all interrupt types from `@tanstack/ai-client` and add this shape to each framework return type:
+
+```ts
+export interface InterruptControls<TTools extends readonly AnyClientTool[]> {
+  interrupts: BoundInterrupts<TTools>
+  /** @deprecated Use `interrupts`. Removed in 1.0. */
+  pendingInterrupts: BoundInterrupts<TTools>
+  resolveInterrupts: ResolveInterrupts<TTools>
+  cancelInterrupts(): Promise<void>
+  retryInterrupts(): Promise<void>
+  interruptErrors: readonly InterruptSubmissionError[]
+  isResuming: boolean
+  resumeInterruptsUnsafe(
+    entries: readonly RunAgentResumeItem[],
+    state?: ChatResumeState,
+  ): Promise<void>
+  /** @deprecated Use a bound resolver. Removed in 1.0. */
+  addToolApprovalResponse(response: {
+    id: string
+    approved: boolean
+  }): Promise<void>
+  /** @deprecated Use `resumeInterruptsUnsafe`. Removed in 1.0. */
+  resumeInterrupts(
+    entries: readonly RunAgentResumeItem[],
+    state?: ChatResumeState,
+  ): Promise<boolean>
+}
+```
+
+React/Preact expose the plain fields. Solid wraps `interrupts`, `pendingInterrupts`, `interruptErrors`, and `isResuming` in accessors. Vue uses readonly refs, Svelte uses getters, and Angular uses readonly signals. Root methods remain functions in every package. No framework declares its own interrupt conditional type.
+
+- [ ] **Step 2: Wire React in the existing instance-holder order**
+
+Place state before `useMemo`, put the callback inside the existing `new ChatClient` options after `getActiveInstance` exists, and synchronize after the instance is active:
+
+```ts
+const [interruptState, setInterruptState] = useState<
+  ChatInterruptState<TTools>
+>(() => ({
+  interrupts: Object.freeze([]),
+  interruptErrors: Object.freeze([]),
+  isResuming: false,
+}))
+
+const syncInterruptState = useCallback((target: ChatClient<TTools, TContext>) => {
+  setInterruptState(target.getInterruptState())
+}, [])
+
+// Inside the existing useMemo, immediately after getActiveInstance:
+const handleInterruptStateChange = (next: ChatInterruptState<TTools>) => {
+  if (!getActiveInstance()) return
+  setInterruptState(next)
+  optionsRef.current.onInterruptStateChange?.(next)
+}
+
+// Inside the existing new ChatClient options, beside onResumeStateChange:
+onInterruptStateChange: handleInterruptStateChange,
+
+useEffect(() => {
+  syncInterruptState(client)
+}, [client, syncInterruptState])
+
+const resolveInterrupts = useCallback<ResolveInterrupts<TTools>>(
+  (decisionOrResolver) => client.resolveInterrupts(decisionOrResolver),
+  [client],
+)
+const cancelInterrupts = useCallback(() => client.cancelInterrupts(), [client])
+const retryInterrupts = useCallback(() => client.retryInterrupts(), [client])
+const resumeInterruptsUnsafe = useCallback(
+  (entries: readonly RunAgentResumeItem[], state?: ChatResumeState) =>
+    client.resumeInterruptsUnsafe(entries, state),
+  [client],
+)
+```
+
+Keep the existing `instanceHolder.current = instance` and `activeClientRef.current = instance` assignments before the memo returns. Add `syncInterruptState` to the memo dependency list. Return `interrupts: interruptState.interrupts` and `pendingInterrupts: interruptState.interrupts`, preserving exact array identity.
+
+- [ ] **Step 3: Wire Preact, Solid, Vue, Svelte, and Angular with concrete native state**
+
+In Preact, add the callback to its existing constructor closure and set the initial snapshot in the existing post-construction effect:
+
+```ts
+const [interruptState, setInterruptState] = useState<ChatInterruptState<TTools>>({
+  interrupts: Object.freeze([]),
+  interruptErrors: Object.freeze([]),
+  isResuming: false,
+})
+// inside the existing new ChatClient options:
+onInterruptStateChange: (next) => {
+  if (activeClientRef.current !== instance) return
+  setInterruptState(next)
+  optionsRef.current.onInterruptStateChange?.(next)
+},
+// inside the existing useEffect([client]):
+setInterruptState(client.getInterruptState())
+```
+
+In Solid, add one signal before `createMemo`, update it in the constructor callback, and initialize it after `client()` exists:
+
+```ts
+const [interruptState, setInterruptState] =
+  createSignal<ChatInterruptState<TTools>>({
+    interrupts: Object.freeze([]),
+    interruptErrors: Object.freeze([]),
+    isResuming: false,
+  })
+// inside new ChatClient:
+onInterruptStateChange: (next) => {
+  setInterruptState(next)
+  options.onInterruptStateChange?.(next)
+},
+setInterruptState(client().getInterruptState())
+const resolveInterrupts: ResolveInterrupts<TTools> = (value) =>
+  client().resolveInterrupts(value)
+```
+
+In Vue, Svelte, and Angular use these exact declarations/callbacks:
+
+```ts
+// Vue
+const interruptState = shallowRef<ChatInterruptState<TTools>>({
+  interrupts: Object.freeze([]),
+  interruptErrors: Object.freeze([]),
+  isResuming: false,
+})
+// in new ChatClient:
+onInterruptStateChange: (next) => {
+  interruptState.value = next
+  options.onInterruptStateChange?.(next)
+},
+interruptState.value = client.getInterruptState()
+
+// Svelte
+let interruptState = $state<ChatInterruptState<TTools>>({
+  interrupts: Object.freeze([]),
+  interruptErrors: Object.freeze([]),
+  isResuming: false,
+})
+// in new ChatClient:
+onInterruptStateChange: (next) => {
+  interruptState = next
+  options.onInterruptStateChange?.(next)
+},
+interruptState = client.getInterruptState()
+
+// Angular
+const interruptState = signal<ChatInterruptState<TTools>>({
+  interrupts: Object.freeze([]),
+  interruptErrors: Object.freeze([]),
+  isResuming: false,
+})
+// in new ChatClient:
+onInterruptStateChange: (next) => {
+  interruptState.set(next)
+  options.onInterruptStateChange?.(next)
+},
+interruptState.set(client.getInterruptState())
+```
+
+For each constructor, add `onInterruptStateChange` beside the existing `onResumeStateChange`; preserve every existing callback. Delegate `resolveInterrupts`, `cancelInterrupts`, `retryInterrupts`, and `resumeInterruptsUnsafe` directly to that package's existing `client`/`client()`. Vue returns `readonly(interruptState)` projections, Svelte getters return fields from `interruptState`, and Angular uses `computed(() => interruptState().interrupts)`; deprecated `pendingInterrupts` reads the identical field in all cases.
+
+- [ ] **Step 4: Run all runtime and type suites green**
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-react test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-react test:types
+pnpm --filter @tanstack/ai-preact test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-preact test:types
+pnpm --filter @tanstack/ai-solid test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-solid test:types
+pnpm --filter @tanstack/ai-vue test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-vue test:types
+pnpm --filter @tanstack/ai-svelte test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-svelte test:types
+pnpm --filter @tanstack/ai-angular test:lib -- --run tests/inject-chat.test.ts
+pnpm --filter @tanstack/ai-angular test:types
+```
+
+Expected: every command PASS; each `@ts-expect-error` is consumed, generic payload is `unknown`, callbacks observe staged/error/replaced states, root callback side effects return `undefined`, and `pendingInterrupts === interrupts` in plain-value packages (or their unwrapped values are strictly equal in reactive packages).
+
+### Task 16: Exercise the full interrupt lifecycle in a deterministic browser fixture
+
+**Prerequisites:** Tasks 5-9 and 13-15.
+
+**Files:**
+
+- Create: `testing/e2e/src/lib/interrupts-v2-fixture.ts`
+- Create: `testing/e2e/src/routes/api.interrupts-v2.ts`
+- Create: `testing/e2e/src/routes/api.interrupts-v2.recovery.ts`
+- Create: `testing/e2e/src/routes/interrupts-v2.tsx`
+- Create: `testing/e2e/tests/interrupts.spec.ts`
+- Modify (generated by the router command): `testing/e2e/src/routeTree.gen.ts`
+
+- [ ] **Step 1: Write the browser scenarios against stable selectors**
+
+Create one serial `interrupts.spec.ts` describe block only where a test deliberately shares a thread; all unrelated tests retain Playwright's normal parallelism and use a unique ID:
+
+```ts
+import { expect, test } from '@playwright/test'
+
+function interruptUrl(testId: string, scenario: string): string {
+  const search = new URLSearchParams({ testId, scenario })
+  return `/interrupts-v2?${search.toString()}`
+}
+
+test('waits for all three cards before one atomic submission', async ({ page }) => {
+  const testId = `interrupts-v2-batch-${test.info().workerIndex}-${Date.now()}`
+  await page.goto(interruptUrl(testId, 'three-tool-approvals'))
+  await page.getByTestId('start-run').click()
+  await expect(page.getByTestId('interrupt-card')).toHaveCount(3)
+
+  await page.getByTestId('interrupt-card').nth(0).getByRole('button', { name: 'Approve' }).click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('0')
+  await page.getByTestId('interrupt-card').nth(1).getByRole('button', { name: 'Deny' }).click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('0')
+  await page.getByTestId('interrupt-card').nth(2).getByRole('button', { name: 'Cancel' }).click()
+
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+  await expect(page.getByTestId('submitted-decisions')).toHaveText(
+    'approve,deny,cancel',
+  )
+})
+```
+
+Add the singleton omitted/edit, mixed audit history, reload, race, and payloadless scenarios with selectors for decision, staged status, continuation count, result-only event names, and stored history. Add these four tests verbatim for the previously ambiguous cases:
+
+```ts
+test('root callback performs synchronous side effects and returns undefined', async ({ page }) => {
+  const testId = `interrupt-callback-${test.info().workerIndex}-${Date.now()}`
+  await page.goto(interruptUrl(testId, 'heterogeneous-callback'))
+  await page.getByTestId('start-run').click()
+  await expect(page.getByTestId('interrupt-card')).toHaveCount(3)
+  await page.getByTestId('resolve-callback').click()
+  await expect(page.getByTestId('callback-return-values')).toHaveText(
+    'undefined,undefined,undefined',
+  )
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+  await expect(page.getByTestId('submitted-decisions')).toHaveText(
+    'approve,deny,generic',
+  )
+})
+
+test('shows every item error and the root aggregate in one response', async ({ page }) => {
+  const testId = `interrupt-errors-${test.info().workerIndex}-${Date.now()}`
+  await page.goto(interruptUrl(testId, 'two-invalid'))
+  await page.getByTestId('start-run').click()
+  await page.getByTestId('invalid-first').click()
+  await page.getByTestId('invalid-second').click()
+  await expect(page.getByTestId('interrupt-error-first')).toContainText(
+    'invalid-edited-args',
+  )
+  await expect(page.getByTestId('interrupt-error-second')).toContainText(
+    'invalid-payload',
+  )
+  await expect(page.getByTestId('interrupt-errors-root')).toContainText(
+    'item-validation-failed',
+  )
+  await expect(page.getByTestId('interrupt-errors-root')).toContainText(
+    'approval-1,question-1',
+  )
+  await page.getByTestId('correct-first').click()
+  await expect(page.getByTestId('interrupt-error-first')).toHaveText('')
+  await expect(page.getByTestId('interrupt-error-second')).toContainText(
+    'invalid-payload',
+  )
+  await page.getByTestId('correct-second').click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+})
+
+test('joins the original continuation after a committed response is truncated', async ({
+  page,
+  request,
+}) => {
+  const testId = `interrupt-retry-${test.info().workerIndex}-${Date.now()}`
+  await page.goto(interruptUrl(testId, 'commit-then-truncate'))
+  await page.getByTestId('start-run').click()
+  await page.getByRole('button', { name: 'Approve' }).click()
+  await expect(page.getByTestId('retry-banner')).toBeVisible()
+  const committed = await request.get(
+    `/api/interrupts-v2?testId=${encodeURIComponent(testId)}&stats=1`,
+  )
+  expect(await committed.json()).toMatchObject({
+    continuationCount: 1,
+    continuationRunIds: [expect.any(String)],
+    truncatedResponses: 1,
+  })
+  await page.getByTestId('retry-interrupts').click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+  const replayed = await request.get(
+    `/api/interrupts-v2?testId=${encodeURIComponent(testId)}&stats=1`,
+  )
+  const replayStats = await replayed.json()
+  expect(replayStats).toMatchObject({
+    continuationCount: 1,
+    replayCount: 1,
+    truncatedResponses: 1,
+  })
+  expect(replayStats.joinedContinuationRunId).toBe(
+    replayStats.continuationRunIds[0],
+  )
+})
+
+test('keeps client-tool execution typed, visible, and resolvable by its bound method', async ({
+  page,
+}) => {
+  const testId = `interrupt-client-tool-${test.info().workerIndex}-${Date.now()}`
+  await page.goto(interruptUrl(testId, 'client-tool-and-approval'))
+  await page.getByTestId('start-run').click()
+  await expect(
+    page.getByTestId('interrupt-kind-client-tool-execution'),
+  ).toHaveCount(1)
+  await expect(page.getByTestId('interrupt-kind-tool-approval')).toHaveCount(1)
+  await page.getByTestId('resolve-client-tool-bound').click()
+  await expect(page.getByTestId('client-tool-status')).toHaveText('staged')
+  await page.getByTestId('approve-server-tool').click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+  await expect(page.getByTestId('client-tool-output')).toHaveText(
+    '{"browserValue":"done"}',
+  )
+})
+```
+
+The retry scenario does not abort the request before the server sees it. The route consumes the first resume through authoritative commit and continuation scheduling, then intentionally returns a truncated stream once. The second request is an exact replay and the client joins the stored continuation ID.
+
+- [ ] **Step 2: Run the focused E2E test red**
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai-e2e test:e2e -- tests/interrupts.spec.ts
+```
+
+Expected: FAIL because `/interrupts-v2`, its chat endpoint, its recovery endpoint, and all stable selectors do not exist.
+
+- [ ] **Step 3: Build a deterministic adapter and per-test authoritative store**
+
+In `interrupts-v2-fixture.ts`, create a synthetic `AnyTextAdapter` that emits exact AG-UI chunks rather than depending on a live provider or timing. Its first run emits the scenario descriptors; its resumed run records response order and emits one final text result. Key server state by `testId` so Playwright workers and aimock sequences cannot collide:
+
+```ts
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import type { AIPersistence } from '@tanstack/ai-persistence'
+
+type InterruptFixture = {
+  persistence: AIPersistence
+  continuationCount: number
+  continuationRunIds: string[]
+  decisions: string[]
+  truncateCommittedResponseOnce: boolean
+  truncatedResponses: number
+  replayCount: number
+  joinedContinuationRunId?: string
+}
+
+const fixtures = new Map<string, InterruptFixture>()
+
+export function getInterruptFixture(testId: string): InterruptFixture {
+  const existing = fixtures.get(testId)
+  if (existing) return existing
+  const created: InterruptFixture = {
+    persistence: memoryPersistence(),
+    continuationCount: 0,
+    continuationRunIds: [],
+    decisions: [],
+    truncateCommittedResponseOnce: true,
+    truncatedResponses: 0,
+    replayCount: 0,
+  }
+  fixtures.set(testId, created)
+  return created
+}
+```
+
+Define the fixture's server tools with real `toolDefinition` schemas: one shared approval schema, one `{ approve, reject }` branch schema, one editable input schema, and one client tool. Cancellation remains payloadless. Define a generic descriptor with its own Draft 2020-12 `responseSchema`. The synthetic stream must include stable `threadId`, `runId`, `interruptId`, `toolCallId`, `parentRunId`, and three distinct responses so the test asserts wire semantics rather than UI-only state.
+
+- [ ] **Step 4: Add separate chat and recovery endpoints**
+
+`api.interrupts-v2.ts` uses the real `AIPersistence` middleware and exposes POST chat, GET continuation replay, and GET test statistics:
+
+```ts
+import {
+  chat,
+  chatParamsFromRequestBody,
+  toServerSentEventsResponse,
+  type StreamChunk,
+} from '@tanstack/ai'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  createInterruptFixtureAdapter,
+  getInterruptFixture,
+  interruptFixtureTools,
+} from '../lib/interrupts-v2-fixture'
+
+async function collectChunks(
+  stream: AsyncIterable<StreamChunk>,
+): Promise<StreamChunk[]> {
+  const chunks: StreamChunk[] = []
+  for await (const chunk of stream) chunks.push(chunk)
+  return chunks
+}
+
+function replayChunks(chunks: readonly StreamChunk[]): AsyncIterable<StreamChunk> {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const chunk of chunks) yield chunk
+    },
+  }
+}
+
+function truncatedSseResponse(): Response {
+  const encoder = new TextEncoder()
+  return new Response(
+    new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(encoder.encode('event: RUN_STARTED\ndata: {'))
+        queueMicrotask(() => controller.error(new Error('fixture truncation')))
+      },
+    }),
+    { headers: { 'Content-Type': 'text/event-stream' } },
+  )
+}
+
+export const Route = createFileRoute('/api/interrupts-v2')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const url = new URL(request.url)
+        const testId = url.searchParams.get('testId')
+        if (!testId) return new Response('Missing testId', { status: 400 })
+        const fixture = getInterruptFixture(testId)
+        if (url.searchParams.get('stats') === '1') {
+          return Response.json({
+            continuationCount: fixture.continuationCount,
+            continuationRunIds: fixture.continuationRunIds,
+            truncatedResponses: fixture.truncatedResponses,
+            replayCount: fixture.replayCount,
+            joinedContinuationRunId: fixture.joinedContinuationRunId,
+          })
+        }
+        const runId = url.searchParams.get('runId')
+        if (!runId) return new Response('Missing runId', { status: 400 })
+        const chunks = fixture.continuationChunks.get(runId)
+        if (!chunks) return new Response('Unknown run', { status: 404 })
+        fixture.joinedContinuationRunId = runId
+        return toServerSentEventsResponse(replayChunks(chunks))
+      },
+      POST: async ({ request }) => {
+        const url = new URL(request.url)
+        const testId = url.searchParams.get('testId')
+        const scenario = url.searchParams.get('scenario')
+        if (!testId || !scenario) {
+          return new Response('Missing fixture correlation', { status: 400 })
+        }
+        const fixture = getInterruptFixture(testId)
+        const params = await chatParamsFromRequestBody(await request.json())
+        const stream = chat({
+          ...params,
+          adapter: createInterruptFixtureAdapter(scenario, fixture),
+          tools: interruptFixtureTools,
+          middleware: [withChatPersistence(fixture.persistence)],
+        }) as AsyncIterable<StreamChunk>
+
+        if (
+          scenario === 'commit-then-truncate' &&
+          params.resume &&
+          fixture.truncateCommittedResponseOnce
+        ) {
+          fixture.truncateCommittedResponseOnce = false
+          const chunks = await collectChunks(stream)
+          fixture.truncatedResponses += 1
+          fixture.continuationCount += 1
+          fixture.continuationRunIds.push(params.runId)
+          fixture.continuationChunks.set(params.runId, chunks)
+          return truncatedSseResponse()
+        }
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+When the authoritative gateway returns the replay terminal, `createInterruptFixtureAdapter` increments `replayCount` but does not increment `continuationCount` or append another continuation run. Add `continuationChunks: Map<string, readonly StreamChunk[]>` to `InterruptFixture`.
+
+`api.interrupts-v2.recovery.ts` accepts only `InterruptRecoveryQuery` and uses the fixture persistence selected by the explicit `testId` query:
+
+```ts
+import { createInterruptRecoveryHandler } from '@tanstack/ai-persistence'
+import { createFileRoute } from '@tanstack/react-router'
+import { getInterruptFixture } from '../lib/interrupts-v2-fixture'
+
+export const Route = createFileRoute('/api/interrupts-v2/recovery')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const testId = new URL(request.url).searchParams.get('testId')
+        if (!testId) return new Response('Missing testId', { status: 400 })
+        const fixture = getInterruptFixture(testId)
+        const handleRecovery = createInterruptRecoveryHandler({
+          persistence: fixture.persistence,
+          authorize: () => ({ allowed: true, includeResolutions: true }),
+        })
+        return handleRecovery(request)
+      },
+    },
+  },
+})
+```
+
+Never infer `/recovery` or a continuation replay URL from the chat URL in library code; the test page explicitly configures recovery and the SSE connection itself supplies `joinRun`.
+
+- [ ] **Step 5: Build the test page using only public APIs**
+
+Configure `useChat` with the fixture's typed tool tuple, `fetchServerSentEvents(() => `/api/interrupts-v2?testId=${encodeURIComponent(testId)}&scenario=${encodeURIComponent(scenario)}`)`, `createInterruptStateFetcher(() => `/api/interrupts-v2/recovery?testId=${encodeURIComponent(testId)}`)`, and a local draft store. Read `testId` and `scenario` from the page search params before constructing the adapters. This is an explicit caller-supplied chat/recovery correlation; `testId` is fixture routing data and is not added to `InterruptRecoveryQuery`. Because `fetchServerSentEvents` preserves existing query parameters when it appends `runId`, the same explicit connection also supplies `joinRun`. Render every `interrupts` item with its `kind`, `errors`, current staged response, edit fields, and per-item resolve/clear controls. Render root controls for callback resolution, retry, and approve/deny/cancel all. Use only public bound methods:
+
+```tsx
+{interrupts.map((interrupt) => (
+  <section data-testid="interrupt-card" key={interrupt.id}>
+    <output data-testid="interrupt-errors">
+      {interrupt.errors.map((issue) => issue.message).join('|')}
+    </output>
+    {interrupt.kind === 'tool-approval' ? (
+      <button onClick={() => interrupt.resolveInterrupt(true)}>Approve</button>
+    ) : (
+      <button
+        onClick={() =>
+          interrupt.resolveInterrupt({ approved: true, payload: genericDraft })
+        }
+      >
+        Approve
+      </button>
+    )}
+  </section>
+))}
+```
+
+Declare `genericDraft` as `unknown` from the page's JSON editor state and let the built-in validator surface errors. Resolve the server-emitted `client-tool-execution` item through its typed bound `resolveInterrupt(output)` method in the scenario above. Add one separate assertion that the retained `addToolResult` API delegates to the same staged item, rather than creating a duplicate interrupt or a second submission.
+
+- [ ] **Step 6: Regenerate the route tree and run E2E green**
+
+The E2E package has no standalone route-generator script; its one-shot Vite build invokes the configured TanStack Router plugin and refreshes `routeTree.gen.ts`. Run:
+
+```powershell
+pnpm --filter @tanstack/ai-e2e build
+pnpm --filter @tanstack/ai-e2e test:types
+$env:CI='true'
+pnpm --filter @tanstack/ai-e2e test:e2e -- tests/interrupts.spec.ts
+```
+
+Expected: the build exits 0 and changes only `routeTree.gen.ts` as generated route output; type checks and all 11 scenarios PASS with no retries required locally. As the focused refactor, remove only duplicated fixture builders, keep selectors and assertions explicit, and rerun all three commands.
+
+### Task 17: Publish the API, validation recipe, migration guide, and changesets
+
+**Prerequisites:** Tasks 1-16. Document only the settled and tested public surface.
+
+**Files:**
+
+- Create: `docs/chat/interrupts.md`
+- Create: `docs/migration/interrupts.md`
+- Modify: `docs/tools/tool-approval.md`
+- Modify: `docs/tools/client-tools.md`
+- Modify: `docs/chat/persistence.md`
+- Modify: `docs/persistence/custom-stores.md`
+- Modify: `docs/persistence/migrations.md`
+- Modify: `docs/persistence/delivery-durability.md`
+- Modify: `docs/architecture/approval-flow-processing.md`
+- Modify: `docs/reference/functions/toolDefinition.md`
+- Modify: `docs/config.json`
+- Create: `.changeset/ag-ui-interrupts.md`
+
+- [ ] **Step 1: Make the documentation link test fail for the planned pages**
+
+Add `chat/interrupts` and `migration/interrupts` to the appropriate `docs/config.json` groups before creating the files. Also add a canonical `/chat/interrupts` link to `docs/tools/tool-approval.md` and a `/migration/interrupts` link to `docs/chat/persistence.md`; do not create the destination files yet. Then run:
+
+```powershell
+pnpm test:docs
+```
+
+Expected: FAIL with missing-page/link errors for both new destinations. `scripts/verify-links.ts` validates Markdown links, not navigation-only `docs/config.json` entries, so the two deliberate links are required for this red step. Do not weaken the verifier.
+
+- [ ] **Step 2: Write the end-to-end interrupt guide with server and client halves**
+
+`docs/chat/interrupts.md` must cover:
+
+- AG-UI descriptor/result lifecycle and the PR-head breaking change;
+- tool versus generic interrupt discrimination;
+- `responseSchema` as the wire/runtime-validation foundation;
+- `approvalSchema`, `{ approve, reject }`, optional `editedArgs`, grouped `payload`, and payloadless cancellation;
+- one-item auto-submit, multi-item staging, root callback transactions, bulk operations, `clearResolution`, retry, and `interrupt.errors`/root `interruptErrors`;
+- native recovery, V2 raw-draft persistence, idempotency, and tab conflicts;
+- the separate client-tool `addToolResult` path.
+
+Use a current model only when a provider-backed server example is necessary:
+
+```ts
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  tools: [transferTool],
+  middleware: [withChatPersistence(persistence)],
+  threadId,
+})
+```
+
+The matching client example must show the inferred branch payload and no type casts:
+
+```ts
+const {
+  interrupts,
+  resolveInterrupts,
+  cancelInterrupts,
+  retryInterrupts,
+  interruptErrors,
+  isResuming,
+  resumeInterruptsUnsafe,
+} = useChat({ tools: [transferTool] as const })
+
+const interrupt = interrupts.find(
+  (item) => item.kind === 'tool-approval' && item.toolName === 'transfer',
+)
+if (
+  interrupt?.kind === 'tool-approval' &&
+  interrupt.toolName === 'transfer'
+) {
+  interrupt.resolveInterrupt(true, {
+    editedArgs: { amount: 12, recipient: 'Ada' },
+    payload: { note: 'Reviewed' },
+  })
+}
+```
+
+Keep `as const` (a const assertion) but use no `as SomeType` assertion in docs.
+
+- [ ] **Step 3: Document converting received JSON Schema before app-level validation**
+
+Generic payloads stay `unknown` statically. Show users how to turn the received Draft 2020-12 schema into their chosen runtime validator before resolving. Use a real Zod 4 conversion example and narrow the conversion result without a type assertion:
+
+```ts
+import { z } from 'zod'
+import type { GenericAGUIInterrupt } from '@tanstack/ai-client'
+
+function resolveGenericEditorValue(
+  interrupt: GenericAGUIInterrupt,
+  editorValue: string,
+): readonly string[] {
+  if (!interrupt.responseSchema) return ['This interrupt has no response schema.']
+
+  let candidateResponse: unknown
+  try {
+    candidateResponse = JSON.parse(editorValue)
+  } catch {
+    return ['Enter valid JSON.']
+  }
+
+  const responseValidator = z.fromJSONSchema(interrupt.responseSchema)
+  const parsed = responseValidator.safeParse(candidateResponse)
+  if (!parsed.success) {
+    return parsed.error.issues.map(
+      (issue) => `${issue.path.join('.')}: ${issue.message}`,
+    )
+  }
+  interrupt.resolveInterrupt(parsed.data)
+  return []
+}
+```
+
+Explain that the conversion library returns a runtime schema rather than a wire-derived static application type, the client still performs canonical built-in Draft 2020-12 validation, and server validation remains authoritative.
+
+- [ ] **Step 4: Write the migration and specialized pages**
+
+`docs/migration/interrupts.md` maps every deprecated surface to the new API:
+
+```ts
+// Deprecated
+await addToolApprovalResponse({ id: approval.id, approved: true })
+
+// Current
+interrupt.resolveInterrupt(true)
+```
+
+State explicitly that there is no codemod. Add recipes for batched staging, branch payloads, optional edits, generic unknown payloads, legacy persistence behavior, and opt-in native recovery.
+
+Update the specialized pages as follows:
+
+| Page | Required content |
+| --- | --- |
+| `tools/tool-approval.md` | shorthand, approve/reject payloads, and payloadless cancel examples |
+| `tools/client-tools.md` | approval interrupts and client execution are separate axes |
+| `chat/persistence.md` | raw drafts only, V2 envelope, recovery before rebinding |
+| `persistence/custom-stores.md` | atomic `acceptInterruptBatch` capability and receipt contract |
+| `persistence/migrations.md` | new table/columns/indexes for every adapter |
+| `persistence/delivery-durability.md` | idempotency key, accepted tombstone, replay rules |
+| `architecture/approval-flow-processing.md` | descriptor → validate-all → CAS → continuation → history |
+| `reference/functions/toolDefinition.md` | conditional `approvalSchema` signature and inferred overloads |
+
+- [ ] **Step 5: Update docs metadata exactly once**
+
+In `docs/config.json`:
+
+- give both new pages `addedAt: "2026-07-13"`;
+- set `updatedAt: "2026-07-13"` on each existing page receiving a content change while preserving its existing `addedAt`;
+- add the currently unlisted `architecture/approval-flow-processing` entry under the existing `Advanced` section with its repository creation date `addedAt: "2026-04-15"` and `updatedAt: "2026-07-13"`;
+- do not change timestamps for unrelated pages or factual-only fixes.
+
+- [ ] **Step 6: Add one release changeset and run docs green**
+
+Create `.changeset/ag-ui-interrupts.md` with minor bumps for `@tanstack/ai`, `@tanstack/ai-client`, `@tanstack/ai-react`, `@tanstack/ai-preact`, `@tanstack/ai-solid`, `@tanstack/ai-vue`, `@tanstack/ai-svelte`, and `@tanstack/ai-angular`; add patch bumps for `@tanstack/ai-persistence`, `@tanstack/ai-persistence-drizzle`, `@tanstack/ai-persistence-prisma`, and `@tanstack/ai-persistence-cloudflare`. Describe the breaking migration and deprecated compatibility surfaces. Do not edit existing changesets.
+
+Run:
+
+```powershell
+pnpm test:docs
+pnpm test:types
+```
+
+Expected: PASS; all links resolve, examples are syntactically valid under doc checks, timestamps are valid, and public declarations build. Refactor repeated explanation into links to `chat/interrupts` without removing the server/client halves from the main guide.
+
+### Task 18: Converge review to zero, run CI parity, and make the only implementation commit
+
+**Prerequisites:** Tasks 0-17 are green. Do not start this task while an implementation or test process is still active.
+
+**Files:**
+
+- Review: every file changed by Tasks 1-17
+- Modify: only files required to fix findings
+
+- [ ] **Step 1: Format the actual diff and inspect its shape**
+
+Use the repository formatter on changed supported files only, then inspect rather than blindly accepting bulk edits:
+
+```powershell
+$changed = git ls-files --modified --others --exclude-standard
+pnpm exec prettier --experimental-cli --ignore-unknown --write $changed
+git diff --check
+git status --short
+git diff --stat
+```
+
+Expected: Prettier succeeds, `git diff --check` is silent, and the status contains only the paths named in this plan plus generated lockfile, migration, and route-tree files. If PowerShell argument expansion exceeds its limit, format one package group at a time; do not switch shells.
+
+- [ ] **Step 2: Perform the focused self-review ledger**
+
+Review the diff against the approved spec and record a pass/fix entry for every row below in the task transcript; do not commit a report file:
+
+| Ledger item | Required evidence |
+| --- | --- |
+| Protocol | canonical reasons, descriptor/result/error DTOs, one structured failure event |
+| Types | conditional schema availability, three branches, optional edits, generic `unknown`, builder preservation |
+| Client | singleton auto-submit, batch wait, replacement/clear, callback rollback and late-call guard, retry statuses |
+| Validation | same Draft 2020-12 compiler client/server, all items validated, deterministic paths, no mutation |
+| Persistence | exact-set CAS, first writer wins, idempotent replay, committed recovery, migrations/assets |
+| Recovery | explicit handler/fetcher, current tool/schema rebinding, V2 draft quarantine and tombstones |
+| Continuation | same thread, new run, `parentRunId`, generic middleware seam, result-only history |
+| Compatibility | all three old APIs deprecated, legacy read only, no dual writer, sandbox guard, no codemod |
+| Frameworks | runtime and type parity across all six packages |
+| Documentation | server/client halves, schema conversion, no assertion casts, dates, current model, changeset |
+
+Search for omissions and accidental placeholders:
+
+```powershell
+rg -n "TO[D]O|FIXME|IMPLEMENT_ME|throw new Error\(['\"]Not implemented" packages testing/e2e docs
+rg -n "addToolApprovalResponse|pendingInterrupts|resumeInterrupts" packages/ai-client packages/ai-react packages/ai-preact packages/ai-solid packages/ai-vue packages/ai-svelte packages/ai-angular docs
+rg -n "responseSchema|approvalSchema|parentRunId|interruptErrors|clearResolution|retryInterrupts" packages testing/e2e docs
+```
+
+Expected: no implementation placeholders; every legacy hit has a deprecation/compatibility purpose; every required new symbol has implementation, test, and documentation hits. Also search touched docs/model examples for repository-disallowed model names and replace any such existing line being edited with `gpt-5.5`.
+
+- [ ] **Step 3: Run the execution-time test-hygiene and debugging audits**
+
+Ask a `test-hygiene` peer to review new/modified tests for reusable fixtures, type-safe mocks, semantic assertions, deterministic timing, and absence of sleep-based synchronization. Fix every actionable finding and rerun the narrow owning test.
+
+Ask a `debugging-discipline` peer to audit any unexpected-failure entries retained from Task 0 onward. Each entry must show reproduced symptom, repository prior-art search, root cause, smallest fix, and regression test. If there were no unexpected failures, record that fact in the task transcript; do not fabricate an investigation.
+
+- [ ] **Step 4: Run the unbiased code-review/fix loop to zero**
+
+Use the `cr-loop` skill after implementation and self-review. Give reviewers the approved spec, this plan, and the complete diff; require coverage across protocol, type inference, browser state, security/validation, transactional persistence, concurrency/replay, framework parity, tests, and docs. Use xhigh reasoning for investigation and review agents as required by repository instructions.
+
+Classify every finding with file/line evidence. Fix all actionable findings, rerun the smallest owning command after each fix batch, and repeat independent review until the convergence report has zero actionable findings. Do not dismiss a finding merely because an existing test passes.
+
+- [ ] **Step 5: Run the complete focused package matrix sequentially**
+
+Set CI once and run native PowerShell one-shot commands. Await each process before starting the next:
+
+```powershell
+$env:CI='true'
+pnpm --filter @tanstack/ai test:lib -- --run tests/interrupts.test.ts tests/tool-definition.test.ts tests/chat-resume-interrupts.test.ts tests/ag-ui-event-order.test.ts
+pnpm --filter @tanstack/ai test:types
+pnpm --filter @tanstack/ai-persistence test:lib -- --run tests/interrupts.test.ts tests/interrupt-conformance.test.ts tests/middleware.test.ts
+pnpm --filter @tanstack/ai-persistence test:types
+pnpm --filter @tanstack/ai-persistence-drizzle test:lib
+pnpm --filter @tanstack/ai-persistence-drizzle test:types
+pnpm --filter @tanstack/ai-persistence-prisma test:lib
+pnpm --filter @tanstack/ai-persistence-prisma test:types
+pnpm --filter @tanstack/ai-persistence-cloudflare test:lib
+pnpm --filter @tanstack/ai-persistence-cloudflare test:types
+pnpm --filter @tanstack/ai-client test:lib -- --run tests/interrupt-manager.test.ts tests/chat-client-interrupts.test.ts tests/chat-client-resume.test.ts tests/chat-persistence-controller.test.ts tests/connection-adapters.test.ts
+pnpm --filter @tanstack/ai-client test:types
+pnpm --filter @tanstack/ai-react test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-react test:types
+pnpm --filter @tanstack/ai-preact test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-preact test:types
+pnpm --filter @tanstack/ai-solid test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-solid test:types
+pnpm --filter @tanstack/ai-vue test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-vue test:types
+pnpm --filter @tanstack/ai-svelte test:lib -- --run tests/use-chat.test.ts
+pnpm --filter @tanstack/ai-svelte test:types
+pnpm --filter @tanstack/ai-angular test:lib -- --run tests/inject-chat.test.ts
+pnpm --filter @tanstack/ai-angular test:types
+pnpm test:docs
+pnpm --filter @tanstack/ai-e2e test:types
+pnpm --filter @tanstack/ai-e2e test:e2e -- tests/interrupts.spec.ts
+```
+
+Expected: every command exits 0. On any unexpected failure, stop the matrix, apply `debugging-discipline`, fix the root cause, rerun the owning command, then restart from the first command whose output could be affected.
+
+- [ ] **Step 6: Run the mandatory repository-wide pre-PR gates**
+
+These commands are mandatory even after the focused matrix:
+
+```powershell
+$env:CI='true'
+pnpm test:pr
+pnpm --filter @tanstack/ai-e2e test:e2e
+```
+
+Expected: both exit 0. `pnpm test:pr` is the canonical CI-equivalent Nx affected target set, and the full E2E command is mandatory for this behavior change. Do not commit, push, or rely on remote CI if either fails.
+
+- [ ] **Step 7: Complete the verification checklist and inspect process hygiene**
+
+Use the `completion-checklist` and `verification-before-completion` skills against fresh Step 5/6 output. Then, at quiescence only, inspect for task-owned processes:
+
+```powershell
+Get-Process node,esbuild,vitest -ErrorAction SilentlyContinue |
+  Select-Object Id, ProcessName, StartTime, Path
+git diff --check
+git status --short --branch
+```
+
+Expected: no task-owned orphan process remains, `git diff --check` is silent, and the branch is `codex/interrupts-full-spec-design`. Never blanket-kill `node.exe`; identify ownership and wait for active commands. Do not run `wsl --shutdown` as part of this task.
+
+- [ ] **Step 8: Stage and create the single final implementation commit**
+
+Only after every review and gate is green, stage the planned implementation scope and inspect the staged diff:
+
+```powershell
+$implementationFiles = git ls-files --modified --others --exclude-standard
+$implementationFiles
+git add -- $implementationFiles
+git diff --cached --check
+git diff --cached --stat
+git status --short
+git commit -m "feat: implement durable AG-UI interrupts"
+git status --short --branch
+```
+
+Before `git add`, compare the printed list with the reviewed Task 1-17 status and remove any preserved user-owned path from `$implementationFiles`. Expected: one final commit succeeds, no generated plan/review/report artifact is accidentally staged, and the working tree is clean except for any explicitly preserved user-owned file. Do not add a co-author trailer. Do not push and do not open a PR in this execution; hand the verified local branch and commit back to the user.
diff --git a/docs/superpowers/specs/2026-07-13-ag-ui-interrupts-design.md b/docs/superpowers/specs/2026-07-13-ag-ui-interrupts-design.md
new file mode 100644
index 000000000..37e17fc78
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-13-ag-ui-interrupts-design.md
@@ -0,0 +1,1036 @@
+# AG-UI Interrupts: Full-Spec, Typed, Durable Resolution
+
+Status: Approved design
+
+Date: 2026-07-13
+
+Implementation base: [TanStack AI PR #785](https://github.com/TanStack/ai/pull/785), commit `61026d52669fc261b7a051ba20ba4bd806ce84fd`
+
+## Summary
+
+TanStack AI will adopt AG-UI native interrupts as the only interrupt protocol emitted by new servers. The client API will expose bound interrupt objects whose methods stage typed responses, validate them, and submit a complete response batch only after every simultaneously open interrupt has been answered or cancelled.
+
+The selected design is staged bound interrupts with auto-submit:
+
+- A single interrupt auto-submits after `resolveInterrupt` or `cancelInterrupt`.
+- A batch waits until every open interrupt has a staged resolution or cancellation, then submits exactly once.
+- `resolveInterrupts(callback)` provides a synchronous root transaction for heterogeneous batches.
+- Tool approvals infer edited arguments from `inputSchema` and custom approval data from `approvalSchema`.
+- Generic AG-UI interrupts retain `unknown` payloads statically and validate them from `responseSchema` at runtime.
+- The server validates the entire batch, reports all validation errors together, and executes no tools when any entry is invalid.
+- Final response batches use a mandatory atomic compare-and-swap persistence operation. Exact replays are idempotent, conflicting responses are rejected, and the first valid writer wins.
+
+This is a breaking protocol and API transition relative to the pre-PR approval flow and parts of PR #785's current surface. Compatibility is handled by a pre-1.0 deprecation period, retained legacy readers in new clients, coordinated client and server upgrades, and a manual migration guide. There will be no codemod.
+
+## Normative basis and requirement labels
+
+This design separates protocol requirements from TanStack guarantees:
+
+| Label | Meaning |
+| --- | --- |
+| `[AG-UI]` | Required for AG-UI protocol conformance. The normative source is the interrupts document at immutable commit [`2ed25b2009ff900315ab686dc9f86147b48fe382`](https://github.com/ag-ui-protocol/ag-ui/blob/2ed25b2009ff900315ab686dc9f86147b48fe382/docs/concepts/interrupts.mdx). The PR-head type baseline is `@ag-ui/core@0.0.57`. |
+| `[TanStack]` | A stronger TanStack API, validation, safety, persistence, or durability guarantee. It is not claimed as an AG-UI protocol requirement. |
+| `[Compatibility]` | Temporary pre-1.0 behavior for old TanStack clients or servers. It is outside the native AG-UI interrupt protocol. |
+
+The AG-UI requirements used here are: an interrupted run terminates with a nonempty interrupt outcome; required message and state snapshots precede that terminal event; the continuation uses the same thread and a new run; one resume array covers every open interrupt; pending interrupts block unrelated input; `responseSchema` describes resolved payloads; exact replay is idempotent; expiry rejects stale resumes; denial is a resolved payload; cancellation has no payload; and a resumed tool emits only its result against the original `toolCallId`.
+
+TanStack additionally guarantees typed tool shorthands, client preflight validation, authoritative server validation, exhaustive batch errors, full-set atomic compare-and-swap persistence, first-writer conflict handling, local draft durability, recovery state, and cross-framework API parity. In particular, AG-UI describes validation against `responseSchema`, but this design's mandatory server-side validation of every entry, all-errors response, and no-write-on-any-invalid rule are explicit TanStack guarantees.
+
+## Evidence and breaking-change analysis
+
+The protocol requirements in this design follow the primary [AG-UI interrupts specification](https://docs.ag-ui.com/concepts/interrupts) and its [immutable source revision](https://github.com/ag-ui-protocol/ag-ui/blob/2ed25b2009ff900315ab686dc9f86147b48fe382/docs/concepts/interrupts.mdx). The installed `@ag-ui/core@0.0.57` types define an interrupt descriptor, `resolved` and `cancelled` resume statuses, a `resume` array on run input, and an interrupt outcome on `RUN_FINISHED`.
+
+Before PR #785, TanStack AI used approval-specific custom events and `addToolApprovalResponse`. The old server emitted `approval-requested` and `tool-input-available` custom events, as shown in the [pre-PR chat implementation](https://github.com/TanStack/ai/blob/5fcaf90dc82bc20b8c7a75faa3c129da04858af5/packages/ai/src/activities/chat/index.ts#L1719-L1772). That flow represented approval state in message parts and resumed through updated conversation history.
+
+PR #785 changes the lifecycle to native interrupt outcomes and resumable run state. That is a breaking protocol change for an old client connected to a new server: the old client depends on custom approval events that the new server will no longer emit. Emitting both paths is not safe because duplicate prompts, duplicate callbacks, and ordering ambiguity can cause two responses to the same logical decision. No capability negotiation exists to make dual emission reliable.
+
+PR #785 also has correctness gaps that this design closes:
+
+- [`addToolApprovalResponse`](https://github.com/TanStack/ai/blob/61026d52669fc261b7a051ba20ba4bd806ce84fd/packages/ai-client/src/chat-client.ts#L1514-L1534) currently maps denial to `cancelled`. AG-UI represents denial as a resolved response such as `{ "approved": false }`; cancellation abandons an interrupt and has no payload.
+- The [resume request path](https://github.com/TanStack/ai/blob/61026d52669fc261b7a051ba20ba4bd806ce84fd/packages/ai-client/src/chat-client.ts#L1054-L1067) reuses the interrupted run ID. AG-UI ends the interrupted run and resumes in a new run on the same thread.
+- The [interrupt construction path](https://github.com/TanStack/ai/blob/61026d52669fc261b7a051ba20ba4bd806ce84fd/packages/ai/src/activities/chat/index.ts#L1762-L1825) uses noncanonical reasons. Tool approvals must use `tool_call`; a TanStack-specific client-tool interruption must use a namespaced reason.
+- The [resumed tool path](https://github.com/TanStack/ai/blob/61026d52669fc261b7a051ba20ba4bd806ce84fd/packages/ai/src/activities/chat/index.ts#L1837-L1873) can replay tool call start, arguments, and end events. A resumed edited tool call emits only the result against the original `toolCallId`.
+- The [persistence middleware](https://github.com/TanStack/ai/blob/61026d52669fc261b7a051ba20ba4bd806ce84fd/packages/ai-persistence/src/middleware.ts#L93-L154) validates fail-fast and stores responses sequentially. A response batch needs exhaustive validation followed by one atomic commit.
+- The [interrupt store contract](https://github.com/TanStack/ai/blob/61026d52669fc261b7a051ba20ba4bd806ce84fd/packages/ai-persistence/src/types.ts#L47-L73) exposes per-item `resolve` and `cancel`, so it cannot guarantee all-or-none batch persistence or first-writer conflict handling.
+
+Because PR #785 has not established a stable released API for native interrupt resumption, its raw `resumeInterrupts` surface can be replaced by the safe bound API in this work. An explicitly unsafe raw escape hatch remains available.
+
+## Goals
+
+- Fully implement the AG-UI interrupt lifecycle, event ordering, resume batching, cancellation, expiry, and idempotency requirements.
+- Make tool approvals ergonomic and type-safe from definition through every framework hook.
+- Support edited tool arguments as an optional full replacement of the original arguments.
+- Support branch-specific typed custom approval and rejection payloads.
+- Support arbitrary AG-UI interrupt reasons and response schemas without pretending runtime JSON Schema creates static TypeScript types.
+- Make multiple simultaneous interrupts safe and easy to resolve individually or as a root transaction.
+- Validate every entry on the server and return all errors in one response.
+- Preserve client response drafts across reloads while keeping final response authority on the server.
+- Prevent partial response persistence, duplicate continuation scheduling, and last-writer overwrites.
+- Give React, Preact, Solid, Vue, Svelte, and Angular equivalent behavior through the headless client.
+- Provide a clear pre-1.0 deprecation and migration path.
+
+## Non-goals
+
+- A codemod for approval APIs.
+- Static type inference from an interrupt's runtime JSON Schema.
+- Protocol negotiation or dual emission of native and legacy approval events.
+- Partial submission of a batch while sibling interrupts remain unanswered.
+- Merging `editedArgs` into original arguments. Edited arguments are always a complete replacement.
+- Deprecating `addToolResult`; it remains the direct client-tool result API.
+- Combining client-tool execution and human tool approval into one interrupt type.
+- Exactly-once external side effects for arbitrary tools. Tool implementations still need idempotency where crash recovery can re-enter external work.
+- Changing general checkpoint, tool-result, or message persistence beyond the interrupt response transaction required here.
+
+## Considered architectures
+
+### 1. Staged bound interrupts with auto-submit, selected
+
+Every exposed interrupt carries methods bound to the owning chat client. Item methods stage a decision. Once all currently open interrupts are covered, the client submits one batch. A singleton is therefore both staged and submitted by one call.
+
+This design makes the common case concise, supports per-card user interfaces, and preserves the AG-UI all-open-interrupt batch invariant. It also provides a natural place for typed tool overloads, validation status, item errors, replacement, and clearing.
+
+### 2. Pure response builders plus explicit submit
+
+Item methods could return response objects and require a separate root submit call. This makes batching explicit but adds boilerplate to the singleton case, makes per-card code manage a second response collection, and does not match the requested binding behavior.
+
+### 3. Root-only reducer
+
+The hook could expose only `resolveInterrupts(interrupts => responses)`. This centralizes atomicity but makes independent interrupt components awkward, prevents direct item binding, and forces a heterogeneous response construction problem into every consumer.
+
+The selected architecture keeps atomic submission centralized internally while exposing both convenient item bindings and an explicit root transaction.
+
+## Public type model
+
+The examples below describe the public contract. Implementation helper types may use different internal names, but they must preserve these inference and assignability rules.
+
+### Common bound interrupt fields
+
+```ts
+type InterruptStatus =
+  | 'pending'
+  | 'validating'
+  | 'staged'
+  | 'submitting'
+  | 'error'
+
+interface InterruptCorrelation {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  submissionId?: string
+  continuationRunId?: string
+}
+
+type ItemInterruptErrorCode =
+  | 'invalid-payload'
+  | 'invalid-edited-args'
+  | 'invalid-tool-output'
+  | 'invalid-response-schema'
+  | 'unknown-interrupt'
+  | 'expired'
+  | 'stale'
+  | 'conflict'
+  | 'legacy-unsupported'
+
+interface ItemInterruptError extends InterruptCorrelation {
+  scope: 'item'
+  interruptId: string
+  code: ItemInterruptErrorCode
+  message: string
+  path?: readonly (string | number)[]
+  source: 'client' | 'server'
+  retryable: boolean
+}
+
+type BatchInterruptErrorCode =
+  | 'incomplete-batch'
+  | 'item-validation-failed'
+  | 'unsupported-bulk-operation'
+  | 'async-resolver'
+  | 'inactive-transaction'
+  | 'mixed-provenance'
+  | 'transport'
+  | 'server'
+  | 'protocol'
+  | 'invalid-response-schema'
+  | 'expired'
+  | 'stale'
+  | 'conflict'
+  | 'persistence-required'
+  | 'atomic-commit-unsupported'
+  | 'recovery-unavailable'
+  | 'legacy-submit-failed'
+
+interface BatchInterruptError extends InterruptCorrelation {
+  scope: 'batch'
+  code: BatchInterruptErrorCode
+  message: string
+  source: 'client' | 'server' | 'transport'
+  retryable: boolean
+  interruptIds: readonly string[]
+}
+
+type InterruptSubmissionError = ItemInterruptError | BatchInterruptError
+
+interface BoundInterruptBase<TStagedResponse> {
+  id: string
+  reason: string
+  message?: string
+  toolCallId?: string
+  responseSchema?: JSONSchema
+  expiresAt?: string
+  metadata?: Record<string, unknown>
+  status: InterruptStatus
+  provenance: 'native' | 'legacy'
+  generation: number
+  errors: readonly ItemInterruptError[]
+  stagedResponse?: TStagedResponse
+  clearResolution(): void
+  cancelInterrupt(): void
+}
+```
+
+The AG-UI fields retain the installed core package's actual exported types. A typed `JSONSchema` descriptor still does not create a static application payload type. `stagedResponse` is a read-only view of the local draft and never includes bound functions when persisted.
+
+Every public variant has a TanStack-owned `kind` discriminator. Known tool variants also carry the configured tool's literal `toolName`; neither field is read from untrusted resume metadata.
+
+```ts
+declare const toolApprovalCapability: unique symbol
+
+interface ToolApprovalCapabilityMarker<TNeedsApproval extends boolean> {
+  readonly [toolApprovalCapability]: TNeedsApproval
+}
+
+type ApprovalCapabilityOf<TTool> =
+  TTool extends ToolApprovalCapabilityMarker<infer TNeedsApproval>
+    ? TNeedsApproval
+    : false
+
+type ToolName<TTools extends readonly AnyClientTool[]> = TTools[number]['name']
+
+type ToolByName<
+  TTools extends readonly AnyClientTool[],
+  TName extends ToolName<TTools>,
+> = Extract<TTools[number], { name: TName }>
+
+type ApprovalToolName<TTools extends readonly AnyClientTool[]> = {
+  [TName in ToolName<TTools>]: ApprovalCapabilityOf<
+    ToolByName<TTools, TName>
+  > extends true
+    ? TName
+    : never
+}[ToolName<TTools>]
+
+type ToolApprovalInterruptsFor<
+  TTools extends readonly AnyClientTool[],
+> = {
+  [TName in ApprovalToolName<TTools>]: ToolApprovalInterrupt<
+    ToolByName<TTools, TName>
+  > & {
+    kind: 'tool-approval'
+    toolName: TName
+  }
+}[ApprovalToolName<TTools>]
+
+type ClientToolExecutionInterruptsFor<
+  TTools extends readonly AnyClientTool[],
+> = {
+  [TName in ToolName<TTools>]: ClientToolExecutionInterrupt<
+    ToolByName<TTools, TName>
+  > & {
+    kind: 'client-tool-execution'
+    toolName: TName
+  }
+}[ToolName<TTools>]
+
+type ChatInterrupt<TTools extends readonly AnyClientTool[]> =
+  | ToolApprovalInterruptsFor<TTools>
+  | ClientToolExecutionInterruptsFor<TTools>
+  | GenericAGUIInterrupt
+```
+
+A generic interrupt has `kind: 'generic'` and no `toolName`. A known tool interrupt narrows by `kind` and literal `toolName` to the configured tool's input, output, and approval payload types. `ToolApprovalInterruptsFor` contains only names whose preserved `TNeedsApproval` capability is the literal `true`; tools with literal `false`, absent approval capability, or a widened nonliteral capability cannot enter the approval variant. A native descriptor that cannot be matched safely remains generic even if it happens to contain a tool-like reason.
+
+At submission, the server looks up the authoritative original call by `(threadId, interruptedRunId, interruptId)` and obtains its stored `toolCallId`, `toolName`, original arguments, schema hashes, and generation. It never selects a tool or arguments from client-supplied `kind`, `toolName`, `toolCallId`, or metadata. Any conflicting client correlation field is ignored for binding and reported as `stale` or `protocol` when it indicates a mismatched descriptor.
+
+### Tool definition configuration
+
+`approvalSchema` is legal only when `needsApproval` is statically `true`.
+
+```ts
+const transferFunds = toolDefinition({
+  name: 'transferFunds',
+  inputSchema: transferInputSchema,
+  outputSchema: transferOutputSchema,
+  needsApproval: true,
+  approvalSchema: {
+    approve: approvalPayloadSchema,
+    reject: rejectionPayloadSchema,
+  },
+})
+```
+
+Supported forms are:
+
+```ts
+approvalSchema: sharedPayloadSchema
+
+approvalSchema: {
+  approve: approvalPayloadSchema,
+  reject: rejectionPayloadSchema,
+}
+```
+
+The branch object must contain at least one branch. A shared schema applies to both approval and rejection. In a branch object, an omitted branch forbids a custom payload for that decision. If `approvalSchema` is absent, both branches forbid a custom payload. `approvalSchema` by itself never enables approval; `needsApproval: true` is required.
+
+Each shared or branch schema accepts the full existing `SchemaInput` family: Standard JSON Schema, Standard Schema, or TanStack's raw `JSONSchema`. Standard JSON Schema and raw JSON Schema are serialized into the AG-UI `responseSchema`. A Standard Schema validator that also exports Standard JSON Schema uses that export. A Standard Schema validator without JSON Schema export remains supported: matching TanStack clients and the server use the configured validator, while the wire schema expresses the branch envelope with an unconstrained nested payload. Generic clients therefore keep that nested payload as `unknown`, and server validation remains authoritative.
+
+Schema inference rules are explicit:
+
+- A Standard Schema or Standard JSON Schema input contributes its declared input type.
+- A raw `JSONSchema` contributes `unknown`; TanStack does not infer a TypeScript type from JSON Schema syntax.
+- An absent `inputSchema` forbids `editedArgs` in types and at runtime. The original stored arguments are used unchanged.
+- A present raw `inputSchema` permits `editedArgs: unknown`, then validates the replacement at runtime.
+- An absent `outputSchema` makes client-tool output `unknown` and performs no output-schema validation.
+- A present raw `outputSchema` keeps output `unknown` and validates it at runtime.
+- An absent approval branch schema forbids nested `payload`.
+- A present raw approval schema requires `payload: unknown`; Standard Schema input that includes `undefined` makes the property optional, while other typed schema inputs require it.
+
+The branch-map form is recognized only when its own keys are a nonempty subset of `approve` and `reject` and its values are `SchemaInput` values. A Standard Schema object is recognized by its standard marker first, and an object containing JSON Schema keywords is a shared raw schema. Ambiguous or malformed configuration fails tool-definition construction.
+
+The tool-definition builder carries its `TNeedsApproval` generic through the non-runtime `ToolApprovalCapabilityMarker` and preserves that marker, the input schema, output schema, and approval schema generics through client and server tool transformations. The mapped union reads this type marker rather than the optional runtime `needsApproval` property. Configurations with `needsApproval: false` or without `needsApproval` reject `approvalSchema` at compile time and runtime.
+
+### Typed tool approval signatures
+
+A tool approval interrupt has this normative branch-aware public contract:
+
+```ts
+interface ToolApprovalInterrupt<
+  TTool extends AnyClientTool,
+> extends BoundInterruptBase<ToolApprovalDraft<
+    ToolInputSchema<TTool>,
+    ApproveSchema<TTool>,
+    RejectSchema<TTool>
+  >> {
+  kind: 'tool-approval'
+  reason: 'tool_call'
+  toolName: TTool['name']
+  toolCallId: string
+
+  resolveInterrupt(
+    approved: true,
+    ...options: OptionsTuple<ApprovalFields<
+      ToolInputSchema<TTool>,
+      ApproveSchema<TTool>
+    >>
+  ): void
+
+  resolveInterrupt(
+    approved: false,
+    ...options: OptionsTuple<RejectionFields<RejectSchema<TTool>>>
+  ): void
+}
+
+type EditedArgsField<TInputSchema> = TInputSchema extends NoSchema
+  ? { editedArgs?: never }
+  : { editedArgs?: InferSchemaInput<TInputSchema> }
+
+type PayloadField<TPayloadSchema> = TPayloadSchema extends NoSchema
+  ? { payload?: never }
+  : TPayloadSchema extends JSONSchema
+    ? { payload: unknown }
+    : undefined extends InferSchemaInput<TPayloadSchema>
+      ? { payload?: InferSchemaInput<TPayloadSchema> }
+      : { payload: InferSchemaInput<TPayloadSchema> }
+
+type ApprovalFields<TInputSchema, TPayloadSchema> =
+  EditedArgsField<TInputSchema> & PayloadField<TPayloadSchema>
+
+type RejectionFields<TPayloadSchema> = PayloadField<TPayloadSchema> & {
+  editedArgs?: never
+}
+
+declare const noSchema: unique symbol
+type NoSchema = typeof noSchema
+
+type RequiredKeys<T> = {
+  [TKey in keyof T]-?: {} extends Pick<T, TKey> ? never : TKey
+}[keyof T]
+
+type OptionsTuple<TFields> = [RequiredKeys<TFields>] extends [never]
+  ? [options?: TFields]
+  : [options: TFields]
+
+type ToolApprovalDraft<TInputSchema, TApproveSchema, TRejectSchema> =
+  | ({ status: 'resolved'; approved: true } & ApprovalFields<
+      TInputSchema,
+      TApproveSchema
+    >)
+  | ({ status: 'resolved'; approved: false } & RejectionFields<
+      TRejectSchema
+    >)
+  | {
+      status: 'cancelled'
+    }
+```
+
+`OptionsTuple<TFields>` makes the argument optional only when every property in `TFields` is optional; otherwise it requires exactly one options object. The resolver overloads and `ToolApprovalDraft` deliberately share `ApprovalFields` and `RejectionFields`, so `stagedResponse` cannot represent a payload that the resolver could not create.
+
+The conditional option tuple has these rules:
+
+- `editedArgs` is optional and exists only on the approval branch.
+- `editedArgs` is inferred from the tool's `inputSchema` and is forbidden when that schema is absent.
+- If an approval payload schema requires a value, the options object and its `payload` field are required.
+- If an approval payload is optional, the options object is optional unless `editedArgs` is supplied.
+- If a branch has no payload schema, that branch's options type has no `payload` field. Raw JSON Schema payloads are required but remain `unknown` statically.
+- The rejection branch has no `editedArgs` field.
+- Excess-property checks and runtime validation reject custom fields outside the nested `payload` object.
+
+The intended calls are:
+
+```ts
+interrupt.resolveInterrupt(true)
+
+interrupt.resolveInterrupt(true, {
+  editedArgs: updatedInput,
+  payload: { note: 'Reviewed' },
+})
+
+interrupt.resolveInterrupt(false, {
+  payload: { reason: 'Insufficient evidence' },
+})
+```
+
+The first argument always represents approval or denial. On the AG-UI wire, both are `resolved` entries. TanStack's response schema and resume payload use this envelope:
+
+```ts
+type ToolApprovalResumePayload =
+  | {
+      approved: true
+      editedArgs?: unknown
+      payload?: unknown
+    }
+  | {
+      approved: false
+      payload?: unknown
+    }
+```
+
+`approvalSchema` governs only the nested `payload`. The generated `responseSchema` is a JSON Schema union of the approval and rejection envelopes. The approval branch includes optional `editedArgs` governed by `inputSchema`; the rejection branch forbids `editedArgs`. Branches without an approval schema forbid `payload`.
+
+`editedArgs`, when present, fully replaces the original tool arguments. Neither client nor server performs a shallow or deep merge. The server validates the replacement against `inputSchema` before any response is committed or tool is executed.
+
+### Generic AG-UI interrupts
+
+An interrupt that is not a known tool approval or a known TanStack client-tool execution remains generic:
+
+```ts
+interface GenericAGUIInterrupt
+  extends BoundInterruptBase<
+    | { status: 'resolved'; payload: unknown }
+    | { status: 'cancelled' }
+  > {
+  kind: 'generic'
+  toolName?: never
+  resolveInterrupt(payload: unknown): void
+}
+```
+
+All standard descriptor fields are statically known. The response remains `unknown` because a JSON Schema received at runtime cannot safely produce a compile-time TypeScript type. The client validates against `responseSchema` as a preflight when a schema is present. The server repeats that validation authoritatively.
+
+The user documentation will show how to convert the received JSON Schema into a schema supported by the user's chosen validation library, validate the payload, and narrow the result before calling `resolveInterrupt`. It will also show a Standard Schema compatible validation path. Documentation examples must not claim static inference from the wire schema.
+
+### Client-tool execution interrupts
+
+A client-owned tool that is awaiting browser execution is separate from human approval:
+
+```ts
+interface ClientToolExecutionInterrupt<TTool extends AnyClientTool>
+  extends BoundInterruptBase<
+    | { status: 'resolved'; payload: InferToolOutput<TTool> }
+    | { status: 'cancelled' }
+  > {
+  kind: 'client-tool-execution'
+  reason: 'tanstack:client_tool_execution'
+  toolName: TTool['name']
+  toolCallId: string
+  resolveInterrupt(output: InferToolOutput<TTool>): void
+}
+```
+
+The output is inferred from the tool's `outputSchema` and is validated before submission and again on the server when that schema exists. With no output schema, output is `unknown` and no schema validation is attempted. A raw output schema also remains `unknown` statically but is validated at runtime. `addToolResult` remains supported and delegates to this machinery when it targets a pending client-tool interrupt. It is not deprecated.
+
+### Hook and headless-client surface
+
+Every framework hook exposes the same logical surface from the headless client:
+
+```ts
+const {
+  interrupts,
+  resolveInterrupts,
+  cancelInterrupts,
+  retryInterrupts,
+  interruptErrors,
+  isResuming,
+  resumeInterruptsUnsafe,
+} = useChat(options)
+```
+
+The root operations are:
+
+```ts
+resolveInterrupts(decision: boolean): Promise<void>
+
+resolveInterrupts(
+  resolve: (interrupt: ChatInterrupt<TTools>) => undefined,
+): Promise<void>
+
+cancelInterrupts(): Promise<void>
+
+retryInterrupts(): Promise<void>
+
+resumeInterruptsUnsafe(
+  entries: readonly RunAgentResumeItem[],
+  state?: ChatResumeState,
+): Promise<void>
+```
+
+The boolean overload is intentionally narrow. It is allowed only when every open interrupt is a tool approval and the selected decision branch requires no custom payload. It never edits arguments. The client rejects unsupported boolean bulk operations before staging anything. Heterogeneous batches and payload-bearing decisions use the callback overload.
+
+Root promises resolve only after the server accepts the atomic response batch. They reject with a `BatchInterruptError` when validation, transport, protocol, expiry, staleness, or conflict prevents acceptance. Bound item methods are synchronous and return `void`; they update local state and may start asynchronous submission internally.
+
+`resumeInterruptsUnsafe` is the raw protocol escape hatch. It bypasses the type-safe builder API but still passes through server validation, exact-set checks, expiry checks, and atomic persistence. Its name is deliberately explicit. Normal application code should use bound or root resolvers.
+
+## Client staging and submission state machine
+
+The client maintains one draft slot per open interrupt. A draft is a resolved response or a cancellation.
+
+```text
+pending -> staged -> submitting -> accepted
+   ^          |          |
+   |          |          +-> error
+   +----------+
+```
+
+The state machine follows these rules:
+
+1. `resolveInterrupt` constructs a candidate synchronously and starts client preflight. Synchronous validators finish in the call; an async Standard Schema validator sets status to `validating` and the submission gate waits for it.
+2. `cancelInterrupt` stages `status: 'cancelled'` with no payload and needs no response-schema validation.
+3. A valid candidate replaces the prior draft, clears superseded item errors, and sets status to `staged` while no submission is in flight.
+4. An invalid replacement does not destroy the last valid draft. It sets status to `error`, records errors for the attempted candidate, preserves the previous `stagedResponse` for display, and blocks submission until the user supplies a valid replacement or clears it.
+5. Async validation captures the item's draft generation. A result from an older candidate is discarded and cannot overwrite newer state.
+6. `clearResolution()` removes the draft and candidate errors, increments the draft generation, and returns the item to `pending` while no submission is in flight.
+7. With one open interrupt, a valid response or cancellation immediately starts submission after preflight completes.
+8. With multiple open interrupts, item calls do not submit until every interrupt has a valid draft and no item is validating or in `error`.
+9. When the final uncovered interrupt becomes valid, the client freezes the complete canonical batch, its draft generations, and fingerprint, then starts one submission.
+10. During `submitting`, item replacement and clearing are rejected to avoid mutating the in-flight fingerprint.
+11. A transport or retryable availability failure unfreezes interaction but retains the complete valid batch and its retry fingerprint. Items return to `staged`, root `interruptErrors` receives the failure, and `retryInterrupts()` is enabled.
+12. Editing, replacing, cancelling, or clearing any item after that failure increments the batch generation, discards the frozen retry fingerprint, and clears the superseded transport error. `retryInterrupts()` then rejects until a new complete batch is frozen.
+13. A server validation failure unfreezes the batch, maps every item error, and sets affected items to `error` without deleting their last candidate. A corrected valid candidate replaces it.
+14. Pending interrupts block unrelated new user input as required by AG-UI.
+15. After acceptance, the resolved descriptors and drafts leave the active `interrupts` collection and the continuation owns subsequent state.
+
+The callback overload is a synchronous transaction. Its return type is `undefined`, not `void`, because TypeScript permits an async function where a callback merely returns `void`:
+
+```ts
+await resolveInterrupts((interrupt) => {
+  if (interrupt.kind === 'tool-approval') {
+    if (interrupt.toolName === 'transferFunds') {
+      interrupt.resolveInterrupt(true, {
+        payload: { note: 'Reviewed' },
+      })
+      return
+    }
+
+    interrupt.cancelInterrupt()
+    return
+  }
+
+  if (interrupt.kind === 'client-tool-execution') {
+    interrupt.cancelInterrupt()
+    return
+  }
+
+  interrupt.resolveInterrupt(buildGenericResponse(interrupt))
+})
+```
+
+The client invokes the callback exactly once for each interrupt in a stable snapshot. It passes transaction-scoped bound wrappers carrying a unique transaction token and draft-generation number. Item auto-submission is suppressed during the callback. On normal `undefined` return, every snapshot item must be covered; the complete batch is submitted once and the token is sealed.
+
+If the callback throws, returns any non-`undefined` value, returns a promise or thenable, or leaves an interrupt uncovered, all staging changes made by that callback are rolled back, its token and generation are invalidated, and no network request starts. Every transaction-scoped item method checks that token before touching state. This prevents a bypassed async callback from returning a promise, awaiting, and then mutating live drafts after rollback. Such a late call is ignored, records a root `inactive-transaction` error, and never submits. The original non-transaction bound objects remain usable after the failed root operation.
+
+`cancelInterrupts()` stages cancellation for every open interrupt and submits one batch. A cancellation counts as coverage but is never rewritten as an approval denial.
+
+`retryInterrupts()` resubmits the same frozen complete batch only after a retryable transport or server availability failure. Expired, stale, and conflicting batches refresh authoritative state and cannot be retried blindly.
+
+## Validation and error propagation
+
+### JSON Schema contract
+
+`[TanStack]` All serialized `responseSchema`, raw input, raw output, and raw approval schemas use JSON Schema Draft 2020-12. An absent `$schema` is interpreted as Draft 2020-12. A different declared dialect is rejected rather than silently reinterpreted.
+
+Browser and server use Ajv 8's 2020 entry point plus `ajv-formats` in full mode with the same options: `allErrors: true`, strict schema checking, format validation enabled, type coercion disabled, defaults disabled, and data mutation disabled. Unknown formats are schema compilation errors. Only document-local references, including `#` and `#/$defs/...`, are supported. Network, file, and cross-document `$ref` resolution is disabled in both environments. Unresolved references and invalid schemas produce `invalid-response-schema`; a TanStack server rejects an invalid schema before emitting an interrupt descriptor.
+
+Ajv `instancePath` values are decoded using RFC 6901 escaping. Normalized public paths are arrays of decoded string segments; validators that natively report numeric array indexes may use numbers. For `required` and `additionalProperties` errors, the missing or extra property is appended to the instance path. Multiple Ajv errors remain multiple errors and retain deterministic Ajv evaluation order within an item; items are ordered by interrupt ID in the aggregate response.
+
+Standard Schema validators run through their own validation surface and their issue paths are normalized to the same public path form. Client preflight may await an async Standard Schema validator behind the synchronous staging API. Server validation may also await it before commit. The serialized envelope is additionally checked with the common Ajv configuration. Validation never coerces, fills defaults, strips properties, or mutates `editedArgs` or payloads.
+
+If a client receives an invalid generic schema from a non-TanStack source, resolved submission is disabled for that item and it receives `invalid-response-schema`; cancellation remains available because it has no payload. `resumeInterruptsUnsafe` cannot bypass authoritative schema compilation.
+
+Validation happens in two phases:
+
+- Client preflight gives immediate feedback and avoids known-invalid requests.
+- `[TanStack]` Server validation is mandatory and authoritative because clients, schemas, state, and expiry can be stale or bypassed. Exhaustive validation and no-write-on-any-invalid are stronger TanStack guarantees, not additional claims about the AG-UI base protocol.
+
+The server validates every entry in the proposed batch before persisting or executing anything. It collects all failures rather than stopping at the first failure. Checks include:
+
+- The response covers exactly the current open interrupt ID set.
+- Every ID belongs to the interrupted run and has not expired.
+- Each entry uses an allowed `resolved` or `cancelled` status.
+- A cancelled entry has no payload.
+- A resolved generic payload matches `responseSchema` when present.
+- A tool approval envelope selects a valid branch.
+- Approved `editedArgs`, when present, match `inputSchema` as a full replacement.
+- Rejection never includes `editedArgs`.
+- The nested custom payload matches the selected approval schema branch.
+- A client-tool output matches `outputSchema`.
+
+If any validation fails, the server performs no interrupt response write, schedules no continuation tools, and returns one AG-UI `RUN_ERROR`. It does not emit a second error event or a compensating `RUN_FINISHED`. Because `RUN_ERROR` is the protocol's error event and its schema permits extension fields, TanStack attaches a serialized `InterruptSubmissionError[]` at the top-level namespaced field `tanstack:interruptErrors`. Generic AG-UI consumers still receive the standard error message and code.
+
+`scope: 'item'` errors populate only the matching bound item's `errors`; `scope: 'batch'` errors populate only root `interruptErrors`. An unknown interrupt ID, missing item, or invalid exact-set check is a batch error unless the authoritative state can correlate the problem to one still-current item. Every error carries thread, interrupted-run, and generation correlation; submission and continuation IDs are included when known. The promise rejection is a `BatchInterruptError` with `item-validation-failed` when only item errors caused failure, and its `interruptIds` lists every affected item.
+
+Retryability is explicit, not inferred only from code. Transport and transient server availability errors are retryable when the frozen fingerprint remains intact. Client validation, invalid schema, incomplete batch, unsupported bulk, async resolver, inactive transaction, mixed provenance, persistence capability, expiry, staleness, and conflict errors are not retryable without a state or draft change. A server error may mark itself retryable only when it proves no commit occurred.
+
+`interruptErrors` is cleared or replaced by the next relevant operation. A transport failure keeps the complete valid draft batch staged and adds a retryable root error. Stale, expired, and conflict responses replace local descriptors and drafts with authoritative server state before exposing the non-retryable error.
+
+### Authoritative recovery state
+
+`[TanStack]` Stale, expired, replayed, and conflicting submissions use one versioned recovery DTO:
+
+```ts
+interface InterruptRecoveryStateV1 {
+  schemaVersion: 1
+  state: 'pending' | 'committed' | 'expired' | 'missing' | 'legacy-committed'
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  pendingInterrupts: readonly Interrupt[]
+  committed?: {
+    fingerprint: string
+    resolutions: readonly RunAgentResumeItem[]
+    continuationRunId?: string
+    committedAt: string
+  }
+}
+```
+
+For every newly committed batch, `state: 'committed'` requires `committed.continuationRunId`; that is the winning continuation ID. `resolutions` is included only for authorized callers and is redacted according to the same policy as interrupt payload persistence. `legacy-committed` exists only for migrated pre-batch records whose historical continuation ID cannot be reconstructed. `pendingInterrupts` is nonempty only in `pending`; expired, missing, and committed states return an empty set.
+
+The primary recovery wire path is the top-level `tanstack:interruptRecovery` field on the same `RUN_ERROR` that reports stale, expired, or conflict. The server obtains this DTO in the same persistence read or transaction that detects the condition, so its generation and winning commit are consistent with the error.
+
+If the stream ends before that event or a transport cannot carry extension fields, the client calls an explicit recovery fetch contract:
+
+```ts
+type InterruptStateFetcher = (
+  input: {
+    threadId: string
+    interruptedRunId: string
+    knownGeneration: number
+  },
+  options: { signal: AbortSignal },
+) => Promise<InterruptRecoveryStateV1>
+```
+
+Connection adapters expose the equivalent `loadInterruptState` method. Fetcher-mode clients receive `interruptStateFetcher` beside `fetcher`. Server integrations expose the matching authenticated `getInterruptRecoveryState` handler over their chosen transport; the HTTP helper returns the DTO as JSON. The standard fetch and connection bridges wire these contracts automatically. This is a TanStack recovery extension, not an AG-UI run request.
+
+The client accepts only a matching thread and interrupted-run ID and a generation at least as new as its current generation. `pending` replaces descriptors, rebinds methods from the configured tool registry, and reconciles drafts. `committed` clears drafts and attaches to or reloads the winning continuation. `expired` clears drafts and reports expiry. `missing` and `legacy-committed` clear unsafe retry state and report a non-retryable protocol or migration error. If neither the event extension nor a configured recovery fetcher is available, state is not guessed: drafts remain quarantined, submission is disabled, and root receives `recovery-unavailable`.
+
+## Client draft durability
+
+Draft decisions are client state, not final server responses. `ChatPersistenceController` owns serialization, hydration, generation invalidation, and cleanup. The configured `persistence.server` `ChatStorageAdapter` remains an opaque get/set/remove transport keyed by thread ID; it never creates bound objects or decides reconciliation.
+
+The stored DTO is versioned and contains raw JSON only:
+
+```ts
+interface ChatResumeSnapshotV2 {
+  schemaVersion: 2
+  resumeState: ChatResumeState
+  interruptState?: {
+    provenance: 'native' | 'legacy'
+    phase: 'pending' | 'accepted'
+    interruptedRunId: string
+    generation: number
+    descriptorsHash: string
+    descriptors: readonly Interrupt[]
+    drafts: readonly {
+      interruptId: string
+      responseSchemaHash: string
+      response: RunAgentResumeItem
+      savedAt: string
+    }[]
+    continuationRunId?: string
+  }
+}
+```
+
+The effective draft identity is `(threadId, interruptedRunId, generation, interruptId, responseSchemaHash)`. Functions, validators, tool implementations, `kind`, and hydrated error objects are never serialized. On hydration, the controller validates the DTO shape and version, obtains authoritative recovery state when native interrupts are present, then rebuilds bound variants from descriptors plus the configured tool registry. A draft survives only when the authoritative run, generation, exact interrupt ID, canonical response schema hash, and expiry match. Everything else is discarded.
+
+After acceptance, the client clears active in-memory descriptors and drafts immediately, writes an `accepted` tombstone containing the continuation ID and no drafts, then queues adapter removal. If removal fails, the tombstone prevents an old pending UI from reappearing; a later authoritative recovery confirms the commit and cleanup retries. Thread reset and disposal also invalidate pending writes by generation.
+
+The unversioned PR #785 snapshot shape is treated as version 1. Migration copies `resumeState` and raw `pendingInterrupts` into a version 2 native descriptor set with no drafts, generation `0`, and a mandatory recovery refresh before resolution. Invalid or uncorrelatable version 1 snapshots are removed and produce a root `protocol` error. Legacy CUSTOM-event state continues to hydrate from message history through the compatibility backend, not by pretending it is a native resume snapshot.
+
+`pendingInterrupts` is a deprecated getter alias over the same hydrated `interrupts` array. It does not read a second snapshot, does not persist functions, and does not return raw descriptor DTOs.
+
+This persistence allows a user to answer part of a multi-interrupt batch, reload, and continue. It does not make a partial response visible to the server. Only the final complete batch is committed server-side.
+
+## Atomic server persistence and concurrency
+
+Every persistence adapter must implement an atomic batch compare-and-swap operation. Sequential per-item `resolve` and `cancel` calls are not an acceptable fallback.
+
+The store contract adds this normative operation:
+
+```ts
+commitInterruptResolutions({
+  threadId,
+  interruptedRunId,
+  continuationRunId,
+  expectedGeneration,
+  expectedInterruptIds,
+  resolutions,
+  fingerprint,
+}): Promise<
+  | { status: 'committed'; continuationRunId: string }
+  | { status: 'replayed'; continuationRunId: string }
+  | { status: 'conflict'; authoritativeState: InterruptBatchState }
+>
+```
+
+The commit invariant is:
+
+```text
+All currently pending interrupt responses are persisted, or none are.
+```
+
+The server computes a stable canonical fingerprint over the sorted complete resolution set. Property ordering and interrupt input order do not affect it. The transaction compares the exact expected pending ID set, records the response batch and continuation run ID together, and transitions every item atomically.
+
+Concurrency semantics are:
+
+- The first valid complete batch commits and becomes authoritative.
+- An exact replay with the same fingerprint is accepted idempotently as `replayed` and returns the first continuation run ID.
+- A later different batch for the same interrupted run returns `conflict` and the authoritative state.
+- A replay attaches to or replays the existing continuation. It never schedules the tools a second time.
+- A missing, extra, expired, already-transitioned, or otherwise stale expected ID set cannot commit.
+
+Database adapters use a transaction with a uniqueness or version predicate. The memory adapter uses a per-interrupted-run critical section and versioned batch record. Custom persistence adapters must implement the atomic operation; servers reject safe interrupt resumption when the configured adapter cannot provide it.
+
+The atomic response record prevents duplicate continuation scheduling at the resume gateway. Existing run locks and checkpoints remain responsible for continuation recovery. Arbitrary external tools must still be idempotent when exactly-once side effects matter across process crashes.
+
+This operation applies only to final client interrupt responses. Client drafts, general messages, checkpoints, and tool-result persistence retain their existing ownership and contracts unless separately changed.
+
+### Persistence availability and adapter work
+
+`[TanStack]` Safe native interrupt resumption requires an `InterruptStore` with atomic batch capability. Without configured persistence, the server must not emit an interrupt outcome that it cannot later resolve safely. At the point an operation would interrupt, it emits `RUN_ERROR` with `persistence-required` instead. Development applications may configure the existing memory persistence explicitly; production and multi-process applications use a durable adapter. There is no hidden process-global fallback.
+
+Built-in work is mandatory:
+
+- Memory: update `packages/ai-persistence/src/memory.ts` with a per-interrupted-run critical section, generation counter, immutable batch record, canonical fingerprint, replay lookup, and recovery DTO projection. It is single-process and loses state on restart, which documentation must state.
+- Drizzle: update schema and stores in `packages/ai-persistence-drizzle`, add a numbered migration and packaged migration asset, and perform interrupt row transitions plus batch insert in one database transaction.
+- Prisma: update the packaged and development Prisma models in `packages/ai-persistence-prisma`, its stores and model CLI, and document the required user migration before deploying the new package.
+- Cloudflare: add the equivalent D1 migration and packaged asset in `packages/ai-persistence-cloudflare`, use a D1 transaction for the CAS, and leave R2 artifact storage unchanged.
+
+Durable schemas add an `interrupt_batches` record keyed by interrupted run ID with thread ID, generation, expected ID set, fingerprint, serialized resolutions, winning continuation run ID, and commit time. Interrupt rows gain a generation column. Indexes cover `(run_id, status, generation)`, `(thread_id, status)`, and unique continuation run ID. The CAS transaction checks generation and the exact pending set, transitions rows, and inserts the batch record together.
+
+Migration behavior is deterministic. Existing pending interrupt rows backfill to generation `1` and can enter the new CAS. Existing resolved or cancelled rows remain historical and are marked as legacy committed; because no reliable winning continuation ID can be inferred, recovery returns `legacy-committed` and never replays them. New writes always have a batch record. Migrations must be idempotent under the repository migration tooling and safe on nonempty databases.
+
+The shared persistence testkit gains interrupt batch conformance covering commit, rollback, replay, conflict, recovery, generation, and concurrent writers. Memory, Drizzle, Prisma, and Cloudflare must all run it. A custom adapter lacking the capability fails server construction when interrupt middleware is configured, or fails the first dynamically discovered interrupt with `atomic-commit-unsupported` before emitting an interrupt outcome. It never falls back to sequential writes.
+
+## AG-UI wire lifecycle
+
+### Interrupted run
+
+The server emits any required state before terminating the run:
+
+1. Emit `MESSAGES_SNAPSHOT` when continuation needs updated message state.
+2. Emit `STATE_SNAPSHOT` when continuation needs updated agent state.
+3. Emit one `RUN_FINISHED` whose outcome is `type: 'interrupt'` and whose interrupt list is nonempty.
+
+The interrupted run is terminal. Its interrupt descriptors contain globally unique IDs, canonical or namespaced reasons, optional `responseSchema`, optional expiry, and enough metadata to bind known tools without weakening generic fallback behavior.
+
+Tool approvals use reason `tool_call`. General requests use the canonical `input_required` or `confirmation` reason when their semantics match it. TanStack client-tool execution uses `tanstack:client_tool_execution`. Other TanStack-specific reasons use the `tanstack:` namespace. Unknown reasons remain generic.
+
+### Resume request
+
+The client starts a new continuation run on the same thread. It sends one `resume` array containing every open interrupt exactly once. No new user message is required.
+
+- Approval is `status: 'resolved'` with `{ approved: true, ... }`.
+- Denial is `status: 'resolved'` with `{ approved: false, ... }`.
+- Cancellation is `status: 'cancelled'` with no payload.
+- An approved edit is a complete `editedArgs` replacement in the resolved payload.
+
+The client checks `expiresAt` before sending. The server checks expiry authoritatively. An expired or stale resume ends with `RUN_ERROR`, refreshes authoritative state, and executes nothing.
+
+### Continuation run
+
+The continuation has a new run ID and the same thread ID. After the batch commits, a resumed server tool emits only `TOOL_CALL_RESULT` for the original `toolCallId`. It does not replay `TOOL_CALL_START`, `TOOL_CALL_ARGS`, or `TOOL_CALL_END`. Subsequent model output and tool calls proceed normally in the new run.
+
+Downstream behavior is defined per entry after the complete batch commits:
+
+- Approved tool approval: invoke the authoritative tool once with `editedArgs` when supplied, otherwise with the stored original arguments. Persist its actual tool-result history part and emit one `TOOL_CALL_RESULT` with the original `toolCallId`.
+- Denied tool approval: do not invoke the tool. Persist a terminal tool-result history part whose value is `{ status: 'denied', payload?: unknown }` and emit one result-only `TOOL_CALL_RESULT` whose string content is the canonical JSON serialization of that value. This gives the continued model a resolved tool outcome without confusing denial with cancellation.
+- Cancelled tool approval: do not invoke the tool and emit no `TOOL_CALL_RESULT`. Persist the cancellation in the interrupt batch audit record and mark the original call not-executed when reconstructing provider history. This follows the AG-UI parallel-interrupt example, which emits results for approved calls and treats the cancelled call as not-executed.
+- Client-tool execution: treat the resolved output as the actual result, persist one tool-result history part, and emit one result-only `TOOL_CALL_RESULT`. Cancellation is not-executed and emits no result.
+- Generic interrupt: pass the resolved payload or cancellation state to the continuation handler and emit no tool event unless the application itself creates a later tool call.
+
+A mixed batch may therefore produce actual approved results, synthetic denied results, and no event for cancelled entries. Denied synthetic results are available immediately after commit; approved tool results are emitted as executions finish, so cross-tool result order is not guaranteed. Correlation is solely by the original `toolCallId`, and every result-producing entry emits exactly once. The resumed model starts only after required terminal history records for the batch are available; cancelled calls are excluded from its actionable tool-call set.
+
+Snapshots and persisted resume state must make a refresh capable of reconstructing the pending interrupt set before response, and the authoritative resolution or continuation after response.
+
+## Compatibility, deprecation, and migration
+
+`[Compatibility]` New servers emit only native AG-UI interrupts. New clients temporarily retain legacy custom-event readers and a real legacy submission backend so they can consume an older server during migration. Old clients cannot consume the new native-only server approval flow, so the recommended deployment is a coordinated server and client upgrade.
+
+Every hydrated item has `provenance: 'native' | 'legacy'`. Native items submit an AG-UI `resume` batch. Legacy `approval-requested` and `tool-input-available` events normalize into bound objects with `provenance: 'legacy'`, but they submit through the old history protocol:
+
+1. Stage all current legacy approval decisions with the same singleton and all-items-covered gate used by native items.
+2. On completion, clone the current message history and update every matching approval part in one in-memory transaction.
+3. Send that complete updated history in one legacy follow-up request, using no native `resume` array.
+4. If history construction fails, change no live message. If transport fails, restore the staged batch and expose `legacy-submit-failed`.
+
+This legacy backend supports the behavior the old protocol can represent: boolean approve or deny and existing client-tool results. Edited arguments, custom approval payloads, generic interrupts, native cancellation, expiry, atomic server CAS, and native conflict recovery are rejected with `legacy-unsupported`; they are not silently dropped. Multiple legacy approvals received together are updated in one history transaction and one request. Native and legacy provenance cannot coexist in one batch; if malformed input creates such a set, submission stops with `mixed-provenance`.
+
+The following are deprecated immediately and scheduled for removal at 1.0:
+
+- `addToolApprovalResponse`
+- `pendingInterrupts`
+- Legacy approval custom-event types
+- Legacy approval custom-event readers
+
+`pendingInterrupts` remains a deprecated alias of the new bound `interrupts` collection during the transition. It does not expose a second state store. `addToolApprovalResponse` selects the native bound backend or legacy history backend from provenance and emits a deprecation notice in development. `addToolResult` similarly preserves the legacy history path for an old client-tool event and the typed native path for a native client-tool interrupt. Legacy readers never cause new servers to dual-emit.
+
+The raw PR #785 `resumeInterrupts` name is replaced by `resumeInterruptsUnsafe`. The normal API is `interrupts`, item resolvers, and root resolvers.
+
+There is no codemod. The migration guide will cover:
+
+1. Coordinated client and server package upgrades.
+2. Replacing `pendingInterrupts` reads with `interrupts`.
+3. Replacing `addToolApprovalResponse` with bound `resolveInterrupt` calls.
+4. The distinction between denial and cancellation.
+5. Adding `approvalSchema` only beside `needsApproval: true`.
+6. Moving custom response data under nested `payload`.
+7. Treating `editedArgs` as an optional full replacement.
+8. Resolving simultaneous interrupts individually or with the root callback.
+9. Validating generic `unknown` payloads from `responseSchema`.
+10. Upgrading custom persistence adapters to atomic batch commit.
+11. Using `resumeInterruptsUnsafe` only for raw protocol integration.
+
+The implementation will include a changeset that calls out the breaking protocol/API transition under the repository's pre-1.0 release convention.
+
+## Documentation Impact
+
+Implementation adds two user-facing pages:
+
+- `docs/chat/interrupts.md`: the native AG-UI lifecycle and complete client API, with server and client examples.
+- `docs/migration/interrupts.md`: the manual pre-1.0 migration from custom approval events and PR #785 raw resume APIs. There is no codemod.
+
+Implementation updates these existing pages:
+
+- `docs/tools/tool-approval.md`: `needsApproval`, shared and branch-specific `approvalSchema`, nested payloads, full-replacement edits, denial, and cancellation.
+- `docs/tools/client-tools.md`: separate client-tool execution interrupts and retained `addToolResult`.
+- `docs/chat/persistence.md`: version 2 client resume snapshots and draft hydration.
+- `docs/persistence/custom-stores.md`: mandatory atomic interrupt batch capability and conformance kit.
+- `docs/persistence/migrations.md`: Drizzle, Prisma, and Cloudflare schema migration steps.
+- `docs/persistence/delivery-durability.md`: replay, first-writer conflicts, process-memory limitations, and tool idempotency.
+- `docs/architecture/approval-flow-processing.md`: native event flow, new-run continuation, and legacy compatibility boundary.
+- `docs/reference/functions/toolDefinition.md`: the `approvalSchema` type surface and `SchemaInput` behavior.
+
+`docs/config.json` adds navigation entries and `addedAt: "2026-07-13"` for both new pages. It refreshes `updatedAt` to `2026-07-13` for every content-updated page listed above, leaving `addedAt` intact. The page examples show both server and client, avoid type-assertion casts, and demonstrate user-library conversion and validation of generic JSON Schema payloads. They distinguish `[AG-UI]` protocol rules from TanStack guarantees in prose rather than presenting CAS or exhaustive server validation as base-protocol requirements.
+
+This internal file, `docs/superpowers/specs/2026-07-13-ag-ui-interrupts-design.md`, stays ignored and is not added to `docs/config.json`.
+
+## Framework parity
+
+Interrupt state, staging, validation, persistence, batching, and submission live in `@tanstack/ai-client`. Framework packages only adapt reactivity and preserve generics.
+
+React, Preact, Solid, Vue, Svelte, and Angular must expose equivalent:
+
+- Bound `interrupts`
+- Deprecated `pendingInterrupts` alias
+- Item resolver, clearer, and canceller behavior
+- Root resolve, cancel, and retry functions
+- `interruptErrors`
+- `isResuming`
+- `resumeInterruptsUnsafe`
+- Tool and approval-schema inference
+
+Framework-specific tests must prove that updates to staged status, errors, and replacement are observable in the framework's native reactive model. Behavior must not be reimplemented independently in wrappers.
+
+## Implementation sequence
+
+1. Extend core tool-definition types to preserve approval schema generics and generate branch-aware response schemas.
+2. Add the atomic interrupt batch persistence contract and implement it in built-in adapters.
+3. Correct server interrupt reasons, run lifecycle, exhaustive validation, batch commit, continuation IDs, and result-only resumed tool events.
+4. Build the headless client's bound interrupt normalization, type mapping, staging transaction, validation, error mapping, draft persistence, and retry behavior.
+5. Add root operations, the unsafe escape hatch, and the `addToolResult` delegation path.
+6. Thread the headless surface and generics through all framework packages.
+7. Add legacy client readers and deprecation annotations without server dual emission.
+8. Add unit, integration, persistence, type, framework, and end-to-end coverage.
+9. Publish the dedicated interrupts documentation, manual migration guide, docs metadata updates, and changeset.
+
+Protocol and persistence foundations precede client convenience APIs so tests can exercise one authoritative wire contract. Compatibility shims are added after the new internal model exists, ensuring they delegate to one implementation.
+
+## Test Strategy
+
+Tests are layered so type construction and state-machine failures are found before persistence races and end-to-end transport runs. Existing suites are extended where they already own the behavior; new focused files are added only where mixing concerns would obscure failures.
+
+Suite ownership is exact:
+
+- Core protocol and execution: `packages/ai/tests/interrupts.test.ts` and new `packages/ai/tests/interrupts-types.test-d.ts`.
+- Headless API and state machine: new `packages/ai-client/tests/chat-client-interrupts.test.ts`, plus `packages/ai-client/tests/chat-client-resume.test.ts` and `packages/ai-client/tests/chat-persistence-controller.test.ts`.
+- Persistence middleware and memory: `packages/ai-persistence/tests/interrupts.test.ts`, `packages/ai-persistence/tests/memory.conformance.test.ts`, and interrupt coverage added to `packages/ai-persistence/src/testkit/conformance.ts`.
+- Durable adapters: `packages/ai-persistence-drizzle/tests/drizzle.conformance.test.ts`, `packages/ai-persistence-drizzle/tests/migrations.test.ts`, `packages/ai-persistence-prisma/tests/prisma.conformance.test.ts`, `packages/ai-persistence-prisma/tests/models.test.ts`, `packages/ai-persistence-cloudflare/tests/runtime.conformance.test.ts`, and `packages/ai-persistence-cloudflare/tests/migrations.test.ts`.
+- Framework behavior and types: `packages/ai-react/tests/use-chat.test.ts`, `packages/ai-react/tests/use-chat-types.test.ts`, the equivalent `use-chat` files in `ai-preact`, `ai-solid`, and `ai-vue`, `packages/ai-svelte/tests/use-chat.test.ts`, `packages/ai-svelte/tests/create-chat-types.test.ts`, `packages/ai-angular/tests/inject-chat.test.ts`, and `packages/ai-angular/tests/inject-chat-types.test.ts`.
+- Browser-to-server behavior: new `testing/e2e/tests/interrupts.spec.ts` with its route fixture under `testing/e2e/src/routes/`.
+- Documentation and links: the repository `test:docs` target after the pages and `docs/config.json` entries in Documentation Impact are changed.
+
+### Type tests
+
+- `approvalSchema` is accepted only with `needsApproval: true`.
+- A tool with preserved `TNeedsApproval: false` or no approval marker produces `never` when extracted by `{ kind: 'tool-approval'; toolName: thatName }`, while a literal-true tool appears in the mapped approval union.
+- Shared schema types both branches.
+- Branch schemas type approval and rejection independently.
+- An omitted branch forbids custom payload.
+- Required and optional payload schemas produce the correct options arity.
+- Approved resolution accepts optional full-replacement `editedArgs` inferred from `inputSchema`.
+- Rejection rejects `editedArgs`.
+- Custom fields are accepted only under nested `payload`.
+- Client-tool resolution infers `outputSchema`.
+- Generic interrupt resolution accepts `unknown` without unsafe inferred narrowing.
+- Generics survive definition, client tool, server tool, headless client, and every framework hook.
+
+### Client unit tests
+
+- Singleton resolve and cancel auto-submit.
+- Multi-item resolution waits for all items.
+- Staged responses can be replaced and cleared before submission.
+- Root callback visits each item once, suppresses intermediate submission, and submits once.
+- Root callback rollback covers throws, non-`undefined` returns, promises, and incomplete batches.
+- A deliberately cast async callback returns a promise, awaits a deferred gate, then calls an item method; token invalidation prevents the delayed post-await call from changing drafts or submitting.
+- Boolean bulk resolution accepts only the allowed homogeneous case.
+- Invalid replacement preserves the prior valid draft, sets item error state, and blocks submission until corrected or cleared.
+- Editing or clearing after transport failure invalidates the frozen retry fingerprint.
+- Transport failure retains a retryable frozen batch.
+- Stale, expired, and conflict responses refresh authoritative state.
+- Item and root errors map correctly and clear when superseded.
+- Drafts survive reload and invalid drafts are discarded during reconciliation.
+- Pending interrupts block unrelated new input.
+- `addToolResult` and deprecated compatibility entry points delegate without duplicate submission.
+
+### Server and protocol tests
+
+- Snapshots precede interrupt `RUN_FINISHED`.
+- Interrupted and continuation run IDs differ while thread ID remains stable.
+- Resume covers the exact open set.
+- Approval, denial, and cancellation produce distinct correct wire entries.
+- Canonical and namespaced reasons are used.
+- Edited arguments fully replace original arguments.
+- Resumed tools emit result only against the original `toolCallId`.
+- Generic payloads, tool envelopes, edited arguments, and client-tool outputs validate against their schemas.
+- All invalid items are returned in one `RUN_ERROR` and no tool executes.
+- Expired and stale resumes fail without writes or execution.
+- Stale, expired, and conflict failures carry a correlated recovery DTO; fallback recovery fetch applies only newer matching generations.
+- Invalid Draft 2020-12 schemas, remote references, unknown formats, and normalized paths behave identically in browser and server.
+
+### Persistence and concurrency tests
+
+- All responses commit or none do.
+- A failure in any validation leaves every interrupt pending.
+- Exact replay returns the original continuation run ID and does not schedule twice.
+- Two different concurrent batches produce one commit and one conflict.
+- Property and input ordering do not change the canonical fingerprint.
+- Missing, extra, stale, and expired ID sets cannot commit.
+- Built-in memory and durable adapters meet identical semantics.
+- A restart after commit reconnects to the authoritative continuation.
+- Custom adapters without atomic batch support fail loudly.
+- No configured persistence fails before an unresumable interrupt outcome can be emitted.
+- Nonempty-database migrations backfill pending generation state and mark historical commits as legacy.
+
+### Compatibility and framework tests
+
+- New clients translate legacy approval custom events into the new bound model.
+- New servers do not emit legacy approval events.
+- Deprecated aliases share state with the new APIs.
+- Every framework observes the same staging, error, replacement, resolve, cancel, and retry behavior.
+- Framework type tests preserve tool-specific approval payload inference.
+
+### End-to-end scenarios
+
+- One approval with and without edited arguments.
+- Three simultaneous approvals resolved one card at a time.
+- A heterogeneous batch resolved through the root callback.
+- Approve, deny, and cancel decisions in one batch.
+- In a mixed batch, approved and denied entries each emit one result-only event, cancelled entries emit none, no tool start/args/end event is replayed, and history contains the specified actual, denied, and not-executed audit states.
+- Generic runtime-schema validation failure followed by correction.
+- Multiple invalid entries returned together and corrected in one follow-up.
+- Reload after one of three local drafts, then complete the batch.
+- Network failure, explicit retry, and exact replay.
+- Two browser tabs submit different complete batches and observe first-writer conflict behavior.
+- Client-tool execution remains separate and type-safe.
+
+Validation runs narrow package and type tests first, then the repository's mandatory pre-PR gate:
+
+```text
+pnpm test:pr
+pnpm --filter @tanstack/ai-e2e test:e2e
+```
+
+The end-to-end suite is mandatory because this changes observable behavior.
+
+## Risks and mitigations
+
+### Type complexity leaks into user errors
+
+Branch-aware conditional types can produce unreadable diagnostics. Keep public helper aliases named, document the two schema forms, and add compile-failure tests for the most common mistakes.
+
+### Runtime and static schema behavior diverge
+
+Generate the response JSON Schema from the same normalized approval-schema representation used by TypeScript helper types. Test every shared, branch-specific, absent, required, and optional combination at both type and runtime levels.
+
+### Partial persistence or duplicate continuations
+
+Sequential writes and best-effort fallback are forbidden. Require atomic adapter support, fingerprint the complete batch, store the continuation run ID in the same transaction, and test races with deterministic barriers.
+
+### Duplicate external tool side effects after crashes
+
+The response gateway prevents duplicate scheduling for exact replays, while run locks and checkpoints govern recovery. Documentation must still require idempotency keys for tools whose external side effects cannot tolerate retry.
+
+### Stale client drafts overwrite authoritative responses
+
+Draft keys include the interrupted run and interrupt ID, and reload reconciliation checks the authoritative set, schema identity, and expiry. CAS rejects any different response after the first commit.
+
+### Compatibility shims create two sources of truth
+
+Legacy readers and deprecated methods normalize into the same bound model. New servers emit only native interrupts. There is one client state store and one submission pipeline.
+
+### Structured validation errors exceed the base protocol
+
+Use standard `RUN_ERROR` fields for generic clients and a namespaced TanStack extension for the exhaustive error array. Do not introduce a competing error event.
+
+### Framework behavior drifts
+
+Keep all behavioral state in the headless client and limit wrappers to reactive projection. Run shared contract tests against every framework adapter.
+
+## Acceptance criteria
+
+The work is complete when all of the following are true:
+
+- Native AG-UI interrupt runs, resumes, snapshots, expiry, cancellation, and result-only tool continuation conform to the primary specification.
+- The public bound and root APIs implement the exact staging and submission semantics in this design.
+- Tool approvals are branch-aware and type-safe from `inputSchema` and `approvalSchema` across all frameworks.
+- Generic interrupts remain runtime-validated with statically `unknown` payloads.
+- Every server validation error is returned together, with no write or execution on any invalid batch.
+- Final response persistence is atomic, exact replay is idempotent, conflicting replay is rejected, and the first valid writer wins.
+- Client drafts survive safe reload and never become partial server responses.
+- Legacy client readers and deprecated APIs delegate to the new model, while new servers emit no legacy approval events.
+- `addToolResult` remains supported and client-tool execution remains a separate typed interrupt.
+- The migration guide, feature documentation, changeset, type tests, protocol tests, framework tests, persistence tests, and end-to-end scenarios are complete.
+- The mandatory local quality gates pass before commit and review.
diff --git a/docs/tools/client-tools.md b/docs/tools/client-tools.md
index a6232d6f3..6ed793f48 100644
--- a/docs/tools/client-tools.md
+++ b/docs/tools/client-tools.md
@@ -27,7 +27,7 @@ sequenceDiagram
     
     Note over Server: No execute function<br/>= client tool
     
-    Server->>Browser: Forward tool-input-available<br/>chunk via SSE/HTTP
+    Server->>Browser: RUN_FINISHED client-tool<br/>interrupt via SSE/HTTP
     Browser->>Browser: Find registered<br/>client tool
     Browser->>ClientTool: execute(args)
     ClientTool->>ClientTool: Update UI,<br/>localStorage, etc.
@@ -53,12 +53,46 @@ sequenceDiagram
 
 1. **Tool Call from LLM**: LLM decides to call a client tool
 2. **Server Detection**: Server sees the tool has no `execute` function
-3. **Client Notification**: Server sends a `tool-input-available` chunk to the browser
+3. **Client Notification**: Server emits a `client-tool-execution` AG-UI interrupt
 4. **Client Execution**: The browser finds the registered `.client()` implementation by tool name and runs it with the parsed input
 5. **Result Return**: Client executes the tool and returns the result
 6. **Server Update**: Result is sent back to the server and added to the conversation
 7. **LLM Continuation**: LLM receives the result and continues the conversation
 
+Native client-tool execution uses the same atomic interrupt lifecycle as other
+waits. See [Interrupts](../interrupts/overview) for persistence, batches, recovery,
+and migration from the historical `tool-input-available` custom event.
+
+## Approval is a separate axis
+
+A client tool can also require approval, and approval is separate from the
+browser result. Add `needsApproval: true` and the tool pauses on a
+`tool-approval` interrupt first. You resolve **that decision only** — once
+approved, the client runs the `.client()` implementation automatically and
+returns its result:
+
+```ts ignore
+const approval = interrupts.find(
+  (interrupt) =>
+    interrupt.kind === 'tool-approval' &&
+    interrupt.toolName === 'delete_local_data',
+)
+
+if (
+  approval?.kind === 'tool-approval' &&
+  approval.toolName === 'delete_local_data'
+) {
+  approval.resolveInterrupt(true)
+}
+```
+
+You never resolve the execution by hand — that is what the `.client()`
+implementation is for. If you register a tool **without** a `.client()`
+implementation and want to supply the result yourself, use `addToolResult`
+(validated against the tool's output schema); it also preserves the historical
+path for legacy streams. See [Tool approval flow](./tool-approval) for approval
+forms and [Interrupts](../interrupts/overview) for the approval lifecycle.
+
 ## Defining Client Tools
 
 Client tools use the same `toolDefinition()` API but with the `.client()` method:
@@ -232,7 +266,7 @@ function MessageComponent({ message }: { message: ChatMessages[number] }) {
 Client tools are **automatically executed** when the model calls them. The flow is:
 
 1. LLM calls a client tool
-2. Server sends `tool-input-available` chunk to browser
+2. Server sends a `client-tool-execution` interrupt to the browser
 3. Client automatically executes the matching tool implementation
 4. Result is sent back to server
 5. Conversation continues with the result
diff --git a/docs/tools/tool-approval.md b/docs/tools/tool-approval.md
index 2ab21975d..6ec54cca7 100644
--- a/docs/tools/tool-approval.md
+++ b/docs/tools/tool-approval.md
@@ -15,6 +15,11 @@ keywords:
 
 The tool approval flow allows you to require user approval before executing sensitive tools, giving users control over actions like sending emails, making purchases, or deleting data. A tool call moves through the `ToolCallState` lifecycle:
 
+The current client API exposes approvals as bound AG-UI interrupts. For the
+complete server/client lifecycle, atomic batch controls, generic interrupts,
+and recovery, see [Interrupts](../interrupts/overview). For deprecated API mapping,
+see [Migrate to AG-UI interrupts](../interrupts/migration).
+
 1. **`awaiting-input`** — Tool call started, no arguments yet
 2. **`input-streaming`** — Arguments arriving incrementally
 3. **`input-complete`** — All arguments received
@@ -36,6 +41,69 @@ When a tool requires approval, the typical flow is:
 4. Tool executes (if approved) or is cancelled (if denied)
 5. Conversation continues with the result
 
+## Resolve an approval interrupt
+
+Without an `approvalSchema`, use the boolean shorthand. Approval uses the
+original tool input by default:
+
+```ts ignore
+const approval = interrupts.find(
+  (interrupt) => interrupt.kind === 'tool-approval',
+)
+
+if (approval?.kind === 'tool-approval') {
+  approval.resolveInterrupt(true)
+}
+```
+
+An `approvalSchema` can define separate application payloads for approval and
+rejection:
+
+```ts
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+const transferDefinition = toolDefinition({
+  name: 'transfer',
+  description: 'Transfer funds',
+  needsApproval: true,
+  inputSchema: z.object({
+    amount: z.number().positive(),
+    recipient: z.string(),
+  }),
+  approvalSchema: {
+    approve: z.object({ note: z.string() }),
+    reject: z.object({ reason: z.string() }),
+  },
+})
+```
+
+Keep branch data under `payload`. Approved arguments can optionally be replaced
+in full with `editedArgs`; rejection never accepts edits:
+
+```ts ignore
+approval.resolveInterrupt(true, {
+  editedArgs: { amount: 12, recipient: 'Ada' },
+  payload: { note: 'Reviewed' },
+})
+
+approval.resolveInterrupt(false, {
+  payload: { reason: 'Policy limit' },
+})
+```
+
+Denial and cancellation are different. `resolveInterrupt(false, ...)` records a
+resolved rejection for the continuation. `cancel()` is payloadless and
+does not select the reject schema:
+
+```ts ignore
+approval.cancel()
+```
+
+A singleton submits after its valid resolution. Multiple items stage until all
+are valid, then submit atomically. Use root `resolveInterrupts(...)` for one
+synchronous batch transaction. See [Multiple Interrupts](../interrupts/multiple).
+
 ## Enabling Approval
 
 Tools can be marked as requiring approval by setting `needsApproval: true` in the definition:
@@ -91,9 +159,11 @@ export async function POST(request: Request) {
 }
 ```
 
-## Client-Side Approval Handling
+## Deprecated approval response compatibility
 
-The client receives approval requests and can respond:
+`addToolApprovalResponse` remains temporarily available for old approval UIs,
+but new code should use the bound interrupt API above. A compatibility
+`approved: false` is a denial, not a cancellation.
 
 ```tsx
 import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
@@ -186,7 +256,7 @@ const listData = toolDefinition({
   name: 'list_data',
   description: 'List available keys',
   inputSchema: z.object({}),
-}).client(async () => ({ keys: [] as Array<string> }))
+}).client(async () => ({ keys: new Array<string>() }))
 
 function ApprovalHandler() {
   const { messages, addToolApprovalResponse } = useChat({
diff --git a/examples/ts-code-mode-web/src/routes/_database-demo/api.database-demo.ts b/examples/ts-code-mode-web/src/routes/_database-demo/api.database-demo.ts
index 8bcd7e15a..8d9fd0908 100644
--- a/examples/ts-code-mode-web/src/routes/_database-demo/api.database-demo.ts
+++ b/examples/ts-code-mode-web/src/routes/_database-demo/api.database-demo.ts
@@ -10,10 +10,10 @@ import {
   skillsToTools,
 } from '@tanstack/ai-code-mode-skills'
 import { createFileSkillStorage } from '@tanstack/ai-code-mode-skills/storage'
-import { anthropicText } from '@tanstack/ai-anthropic'
-import { openaiText } from '@tanstack/ai-openai'
-import { geminiText } from '@tanstack/ai-gemini'
-import type { AnyTextAdapter, ServerTool, StreamChunk } from '@tanstack/ai'
+import { ANTHROPIC_MODELS, anthropicText } from '@tanstack/ai-anthropic'
+import { OPENAI_CHAT_MODELS, openaiText } from '@tanstack/ai-openai'
+import { GEMINI_MODELS, geminiText } from '@tanstack/ai-gemini'
+import type { AnyServerTool, AnyTextAdapter, StreamChunk } from '@tanstack/ai'
 import type { IsolateDriver } from '@tanstack/ai-code-mode'
 
 import { databaseTools, getSchemaInfoTool } from '@/lib/tools/database-tools'
@@ -21,15 +21,25 @@ import { maxTokensModelOptions } from '@/lib/max-tokens-model-options'
 
 type Provider = 'anthropic' | 'openai' | 'gemini'
 
+function selectModel<TModel extends string>(
+  requested: string | undefined,
+  fallback: TModel,
+  available: ReadonlyArray<TModel>,
+): TModel {
+  return available.find((candidate) => candidate === requested) ?? fallback
+}
+
 function getAdapter(provider: Provider, model?: string): AnyTextAdapter {
   switch (provider) {
     case 'openai':
-      return openaiText((model || 'gpt-4o') as 'gpt-4o')
+      return openaiText(selectModel(model, 'gpt-5.5', OPENAI_CHAT_MODELS))
     case 'gemini':
-      return geminiText((model || 'gemini-2.5-flash') as 'gemini-2.5-flash')
+      return geminiText(selectModel(model, 'gemini-2.5-flash', GEMINI_MODELS))
     case 'anthropic':
     default:
-      return anthropicText((model || 'claude-haiku-4-5') as 'claude-haiku-4-5')
+      return anthropicText(
+        selectModel(model, 'claude-haiku-4-5', ANTHROPIC_MODELS),
+      )
   }
 }
 
@@ -115,7 +125,7 @@ Rules:
 This is not optional — skill registration is a core part of your workflow.`
 
 async function getSkillToolsAndPrompt(driver: IsolateDriver): Promise<{
-  skillTools: Array<ServerTool<any, any, any>>
+  skillTools: Array<AnyServerTool>
   skillsPrompt: string
 }> {
   const allSkills = await skillStorage.loadAll()
@@ -250,7 +260,7 @@ export const Route = createFileRoute(
         const { adapter: instrumentedAdapter } = instrumentAdapter(rawAdapter)
 
         try {
-          let tools: Array<ServerTool<any, any, any>>
+          let tools: Array<AnyServerTool>
           let systemPrompts: Array<string>
 
           if (useCodeMode) {
diff --git a/examples/ts-react-chat/README.md b/examples/ts-react-chat/README.md
index c4e7aa4ae..66c1f0900 100644
--- a/examples/ts-react-chat/README.md
+++ b/examples/ts-react-chat/README.md
@@ -40,6 +40,13 @@ OPENAI_API_KEY=your_openai_api_key
 SQLITE_CHAT_DB_URL=file:./sqlite-chat-persistence.db
 ```
 
+## Interrupt Lab
+
+Run `pnpm dev:interrupt-lab` before opening `/interrupts` or
+`/durable-interrupts`. Its lifecycle prebuild refreshes the workspace package
+distributions used by the lab, preventing Vite from serving stale interrupt
+runtime code. Add `?debug=true` to either route for client and server traces.
+
 ## SQLite Persistence Demo
 
 The `/sqlite-persistence` route demonstrates server state persistence with the
diff --git a/examples/ts-react-chat/package.json b/examples/ts-react-chat/package.json
index e13e03e6c..583cb6236 100644
--- a/examples/ts-react-chat/package.json
+++ b/examples/ts-react-chat/package.json
@@ -5,6 +5,8 @@
   "scripts": {
     "dev": "concurrently -k -n proxy,threejs,vite -c magenta,green,cyan \"node scripts/serve-sandbox.mjs\" \"npx -y @modelcontextprotocol/server-threejs\" \"vite dev --port 3000\"",
     "dev:vite": "vite dev --port 3000",
+    "predev:interrupt-lab": "pnpm --filter \"@tanstack/ai-react...\" --filter \"@tanstack/ai-openai...\" --filter \"@tanstack/ai-persistence-drizzle...\" build",
+    "dev:interrupt-lab": "vite dev --port 3000",
     "build": "vite build",
     "serve": "vite preview",
     "test": "exit 0",
diff --git a/examples/ts-react-chat/src/components/Header.tsx b/examples/ts-react-chat/src/components/Header.tsx
index f5ab05666..6bc199481 100644
--- a/examples/ts-react-chat/src/components/Header.tsx
+++ b/examples/ts-react-chat/src/components/Header.tsx
@@ -12,11 +12,12 @@ import {
   Guitar,
   Home,
   Image,
-  Menu,
   LayoutGrid,
-  Mic,
+  Menu,
   MessageSquare,
+  Mic,
   Music,
+  PawPrint,
   Plug,
   Server,
   Sparkles,
@@ -246,6 +247,32 @@ export default function Header() {
             <span className="font-medium">Persistent Chats</span>
           </Link>
 
+          <Link
+            to="/interrupts"
+            onClick={() => setIsOpen(false)}
+            className="flex items-center gap-3 p-3 rounded-lg hover:bg-gray-800 transition-colors mb-1"
+            activeProps={{
+              className:
+                'flex items-center gap-3 p-3 rounded-lg bg-emerald-700 hover:bg-emerald-800 transition-colors mb-1',
+            }}
+          >
+            <PawPrint size={20} />
+            <span className="font-medium">Interrupt Lab</span>
+          </Link>
+
+          <Link
+            to="/durable-interrupts"
+            onClick={() => setIsOpen(false)}
+            className="flex items-center gap-3 p-3 rounded-lg hover:bg-gray-800 transition-colors mb-2"
+            activeProps={{
+              className:
+                'flex items-center gap-3 p-3 rounded-lg bg-emerald-700 hover:bg-emerald-800 transition-colors mb-2',
+            }}
+          >
+            <Database size={20} />
+            <span className="font-medium">Durable Interrupt Lab</span>
+          </Link>
+
           <Link
             to="/sqlite-persistence"
             onClick={() => setIsOpen(false)}
diff --git a/examples/ts-react-chat/src/lib/interrupt-lab/InterruptLabPage.tsx b/examples/ts-react-chat/src/lib/interrupt-lab/InterruptLabPage.tsx
new file mode 100644
index 000000000..239ecc234
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/interrupt-lab/InterruptLabPage.tsx
@@ -0,0 +1,1462 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import {
+  createInterruptStateFetcher,
+  localStoragePersistence,
+} from '@tanstack/ai-client'
+import {
+  AlertTriangle,
+  Check,
+  Database,
+  ExternalLink,
+  Leaf,
+  Radio,
+  RefreshCw,
+  RotateCcw,
+  Send,
+  ShieldCheck,
+  X,
+} from 'lucide-react'
+import {
+  buildGenericResolution,
+  createDurableDraftEnvelope,
+  createInterruptLabDebugFetch,
+  createIncompleteBulkResolver,
+  describeInterruptErrors,
+  durableCapabilityStatuses,
+  durableDraftStorageKey,
+  durableOutcomeStatus,
+  interruptLabPageConfig,
+  interruptProgressLabel,
+  invalidAggregateResolutionArguments,
+  isNormalSendDisabled,
+  logInterruptLabClientDebug,
+  restoreDurableDrafts,
+  shouldShowOpenAiApiKeyGuidance,
+} from './client-ui'
+import {
+  approvalBasicTool,
+  approvalBranchPayloadTool,
+  approvalClientTool,
+  approvalEditArgsTool,
+  approvalSharedPayloadTool,
+  batchSecondTool,
+  batchThirdTool,
+  clientOutputTool,
+  interruptLabScenarios,
+} from './scenarios'
+import type {
+  ChatInterrupt,
+  ChatResumeSnapshot,
+  UIMessage,
+} from '@tanstack/ai-client'
+import type { InterruptEditorDraft } from './client-ui'
+import type {
+  InterruptLabMode,
+  InterruptLabScenarioCategory,
+  InterruptLabScenarioId,
+} from './scenarios'
+
+const clientTools = [
+  approvalBasicTool.client(),
+  approvalEditArgsTool.client(),
+  approvalSharedPayloadTool.client(),
+  approvalBranchPayloadTool.client(),
+  batchSecondTool.client(),
+  batchThirdTool.client(),
+  clientOutputTool.client(),
+  approvalClientTool.client(),
+] as const
+
+type LabInterrupt = ChatInterrupt<typeof clientTools>
+
+type InspectorEvent = { at: string; type: string; detail: string }
+
+const categoryMeta: Record<
+  InterruptLabScenarioCategory,
+  { habitat: string; accent: string }
+> = {
+  approval: { habitat: 'Canopy permits', accent: 'text-amber-900' },
+  'client-tool': { habitat: 'Field instruments', accent: 'text-sky-900' },
+  generic: { habitat: 'Open-range signals', accent: 'text-violet-900' },
+  batching: { habitat: 'Migration groups', accent: 'text-emerald-900' },
+  validation: { habitat: 'Triage enclosure', accent: 'text-rose-900' },
+}
+
+const scenarioCategories = [
+  'approval',
+  'client-tool',
+  'generic',
+  'batching',
+  'validation',
+] as const satisfies ReadonlyArray<InterruptLabScenarioCategory>
+
+const durableResumePersistence = localStoragePersistence<ChatResumeSnapshot>({
+  keyPrefix: 'tanstack-ai:interrupt-lab:resume:',
+  serialize(value) {
+    return JSON.stringify(value)
+  },
+  deserialize: JSON.parse,
+})
+
+function createThreadId(
+  mode: InterruptLabMode,
+  scenarioId: InterruptLabScenarioId,
+): string {
+  const { threadPrefix } = interruptLabPageConfig(mode)
+  const storageKey = `tanstack-ai:${threadPrefix}:${scenarioId}:thread`
+  if (mode === 'durable') {
+    const stored = window.localStorage.getItem(storageKey)
+    if (stored) return stored
+  }
+  const suffix = crypto.randomUUID()
+  const threadId = `${threadPrefix}:${scenarioId}:${suffix}`
+  if (mode === 'durable') window.localStorage.setItem(storageKey, threadId)
+  return threadId
+}
+
+function emptyDraft(interrupt: LabInterrupt): InterruptEditorDraft {
+  const originalArgs =
+    interrupt.kind === 'tool-approval'
+      ? JSON.stringify(interrupt.originalArgs, null, 2)
+      : ''
+  const toolName = interrupt.kind === 'generic' ? '' : interrupt.toolName
+  return {
+    editedArgs: originalArgs,
+    includeEditedArgs: false,
+    approvePayload:
+      toolName === 'interrupt_lab_shared_payload' ||
+      toolName === 'interrupt_lab_approval_client'
+        ? '{\n  "note": "Reviewed in the field journal"\n}'
+        : toolName === 'interrupt_lab_branch_payload'
+          ? '{\n  "note": "Approved after habitat review"\n}'
+          : '',
+    rejectPayload:
+      toolName === 'interrupt_lab_shared_payload' ||
+      toolName === 'interrupt_lab_approval_client'
+        ? '{\n  "note": "Rejected after field review"\n}'
+        : toolName === 'interrupt_lab_branch_payload'
+          ? '{\n  "reason": "Unsafe conditions"\n}'
+          : '',
+    output:
+      interrupt.kind === 'generic'
+        ? '{\n  "answer": "Field response recorded"\n}'
+        : '{\n  "browserValue": "sensor-reading-42"\n}',
+  }
+}
+
+function hasDecisionPayload(interrupt: LabInterrupt): boolean {
+  return (
+    interrupt.kind === 'tool-approval' &&
+    (interrupt.toolName === 'interrupt_lab_shared_payload' ||
+      interrupt.toolName === 'interrupt_lab_branch_payload' ||
+      interrupt.toolName === 'interrupt_lab_approval_client')
+  )
+}
+
+function canBooleanBulk(interrupts: ReadonlyArray<LabInterrupt>): boolean {
+  return (
+    interrupts.length > 0 &&
+    interrupts.every(
+      (interrupt) =>
+        interrupt.kind === 'tool-approval' && !hasDecisionPayload(interrupt),
+    )
+  )
+}
+
+function messageText(message: UIMessage<typeof clientTools>): string {
+  return message.parts
+    .map((part) => {
+      if (part.type === 'text' || part.type === 'thinking') return part.content
+      if (part.type === 'tool-call')
+        return `[tool · ${part.name} · ${part.state}]`
+      return ''
+    })
+    .filter(Boolean)
+    .join('\n')
+}
+
+export function InterruptLabPage({
+  mode,
+  debug = false,
+  scenarioId,
+  onScenarioChange,
+}: {
+  mode: InterruptLabMode
+  debug?: boolean
+  scenarioId: InterruptLabScenarioId
+  onScenarioChange: (scenarioId: InterruptLabScenarioId) => void
+}) {
+  const [thread, setThread] = useState<{
+    key: string
+    threadId: string
+  }>()
+  const [caseBusy, setCaseBusy] = useState(false)
+  const threadKey = `${mode}:${scenarioId}`
+
+  useEffect(() => {
+    setThread({ key: threadKey, threadId: createThreadId(mode, scenarioId) })
+  }, [mode, scenarioId, threadKey])
+
+  const threadId = thread?.key === threadKey ? thread.threadId : undefined
+
+  return (
+    <main className="min-h-[calc(100vh-72px)] bg-[#e8e0cc] text-[#17251d] [background-image:radial-gradient(circle_at_15%_10%,rgba(255,255,255,.75),transparent_30%),linear-gradient(115deg,rgba(73,95,65,.08)_1px,transparent_1px)] [background-size:auto,28px_28px]">
+      <div className="mx-auto max-w-[1500px] px-4 py-7 sm:px-6 lg:px-8">
+        <header className="relative overflow-hidden border border-[#283c2e] bg-[#23412f] px-6 py-7 text-[#f3eddc] shadow-[8px_8px_0_#9c8d65] sm:px-9">
+          <div className="absolute -right-10 -top-14 h-52 w-52 rounded-full border-[28px] border-[#8ba56e]/25" />
+          <div className="relative grid gap-6 lg:grid-cols-[1fr_auto] lg:items-end">
+            <div>
+              <p className="flex items-center gap-2 font-mono text-xs uppercase tracking-[0.28em] text-[#cbd9aa]">
+                <Leaf size={15} aria-hidden="true" /> Station 07 · Manual lab
+              </p>
+              <h1 className="mt-3 max-w-4xl [font-family:Georgia,serif] text-4xl font-bold leading-none sm:text-6xl">
+                Wildlife Interrupt Response Center
+              </h1>
+              <p className="mt-4 max-w-3xl text-sm leading-6 text-[#e0e5d3] sm:text-base">
+                A real-model field journal for approvals, edited tool inputs,
+                browser results, generic AG-UI responses, and atomic batches.
+              </p>
+            </div>
+            <div className="border border-[#d8dfbd]/40 bg-[#152c20]/70 p-4 font-mono text-xs">
+              <div className="flex items-center gap-2">
+                {mode === 'durable' ? (
+                  <Database size={17} />
+                ) : (
+                  <Radio size={17} />
+                )}
+                <strong className="uppercase tracking-widest">
+                  {mode === 'durable' ? 'Durable SQLite' : 'Ephemeral'}
+                </strong>
+                {debug && (
+                  <span className="border border-[#cbd9aa]/60 px-2 py-0.5 text-[10px] uppercase tracking-widest text-[#dce7c1]">
+                    Debug on
+                  </span>
+                )}
+              </div>
+              <p className="mt-2 max-w-xs text-[#cbd9c2]">
+                {mode === 'durable'
+                  ? 'Atomic server state + browser resume drafts.'
+                  : 'No persistence. Full-history continuation only.'}
+              </p>
+            </div>
+          </div>
+        </header>
+
+        <div className="mt-8 grid gap-7 xl:grid-cols-[340px_minmax(0,1fr)]">
+          <ScenarioIndex
+            mode={mode}
+            selected={scenarioId}
+            disabled={caseBusy}
+            onSelect={onScenarioChange}
+          />
+          {threadId ? (
+            <InterruptRunner
+              key={`${mode}:${scenarioId}:${threadId}`}
+              mode={mode}
+              debug={debug}
+              scenarioId={scenarioId}
+              threadId={threadId}
+              onBusyChange={setCaseBusy}
+            />
+          ) : (
+            <div className="border border-[#b9ad8f] bg-[#f8f3e5] p-10">
+              Preparing a field journal…
+            </div>
+          )}
+        </div>
+      </div>
+    </main>
+  )
+}
+
+function ScenarioIndex({
+  mode,
+  selected,
+  disabled,
+  onSelect,
+}: {
+  mode: InterruptLabMode
+  selected: InterruptLabScenarioId
+  disabled: boolean
+  onSelect: (id: InterruptLabScenarioId) => void
+}) {
+  return (
+    <aside className="self-start border border-[#867b5e] bg-[#f6efd9] p-4 shadow-[5px_5px_0_#b9ad8f] xl:sticky xl:top-4">
+      <p className="font-mono text-xs uppercase tracking-[0.22em] text-[#5b674d]">
+        Habitat index
+      </p>
+      <div className="mt-4 space-y-5">
+        {scenarioCategories.map((category) => {
+          const scenarios = Object.values(interruptLabScenarios).filter(
+            (scenario) =>
+              scenario.category === category && scenario.modes.includes(mode),
+          )
+          return (
+            <section key={category}>
+              <h2
+                className={`mb-2 [font-family:Georgia,serif] text-lg font-bold ${categoryMeta[category].accent}`}
+              >
+                {categoryMeta[category].habitat}
+              </h2>
+              <div className="space-y-2">
+                {scenarios.map((scenario) => (
+                  <button
+                    key={scenario.id}
+                    type="button"
+                    disabled={disabled}
+                    onClick={() => onSelect(scenario.id)}
+                    aria-pressed={selected === scenario.id}
+                    className="w-full border border-[#c9bea1] bg-[#fffaf0] p-3 text-left transition hover:-translate-y-0.5 hover:border-[#526a4b] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[#1e5a3a] disabled:cursor-not-allowed disabled:opacity-50 aria-pressed:border-[#294934] aria-pressed:bg-[#dfe8cc] motion-reduce:transform-none motion-reduce:transition-none"
+                  >
+                    <span className="block text-sm font-bold">
+                      {scenario.label}
+                    </span>
+                    <span className="mt-1 block text-xs leading-5 text-[#5b6257]">
+                      {scenario.description}
+                    </span>
+                  </button>
+                ))}
+              </div>
+            </section>
+          )
+        })}
+      </div>
+    </aside>
+  )
+}
+
+function InterruptRunner({
+  mode,
+  debug,
+  scenarioId,
+  threadId,
+  onBusyChange,
+}: {
+  mode: InterruptLabMode
+  debug: boolean
+  scenarioId: InterruptLabScenarioId
+  threadId: string
+  onBusyChange: (busy: boolean) => void
+}) {
+  const config = interruptLabPageConfig(mode)
+  const scenario = interruptLabScenarios[scenarioId]
+  const debugFetch = useMemo(
+    () => createInterruptLabDebugFetch({ enabled: debug }),
+    [debug],
+  )
+  const connection = useMemo(
+    () =>
+      fetchServerSentEvents(config.endpoint, {
+        fetchClient: debugFetch,
+        ...(mode === 'durable'
+          ? {
+              interruptStateFetcher: createInterruptStateFetcher(
+                config.endpoint,
+                { fetchClient: debugFetch },
+              ),
+            }
+          : {}),
+      }),
+    [config.endpoint, debugFetch, mode],
+  )
+  const [drafts, setDrafts] = useState<Record<string, InterruptEditorDraft>>({})
+  const [note, setNote] = useState('')
+  const [events, setEvents] = useState<Array<InspectorEvent>>([])
+  const [localNotice, setLocalNotice] = useState<string>()
+  const [failNextResume, setFailNextResume] = useState(false)
+  const durableDraftKeyRef = useRef<string | undefined>(undefined)
+
+  const chat = useChat({
+    id: threadId,
+    threadId,
+    connection,
+    forwardedProps: {
+      interruptScenario: scenarioId,
+      ...(debug ? { interruptLabDebug: true } : {}),
+      ...(mode === 'durable' && failNextResume
+        ? { interruptLabFailResumeOnce: true }
+        : {}),
+    },
+    tools: clientTools,
+    ...(mode === 'durable'
+      ? { persistence: { server: durableResumePersistence } }
+      : {}),
+    onChunk(chunk) {
+      logInterruptLabClientDebug(debug, { event: 'chunk', chunk })
+      const detail =
+        chunk.type === 'RUN_ERROR'
+          ? chunk.message
+          : chunk.type === 'RUN_FINISHED'
+            ? (chunk.outcome?.type ?? 'finished')
+            : 'stream event'
+      setEvents((current) =>
+        [
+          ...current,
+          { at: new Date().toLocaleTimeString(), type: chunk.type, detail },
+        ].slice(-80),
+      )
+    },
+  })
+
+  const staged = chat.interrupts.filter(
+    (interrupt) => interrupt.status === 'staged',
+  ).length
+  const pending = chat.interrupts.length > 0
+  const allItemErrors = chat.interrupts.flatMap((interrupt) => interrupt.errors)
+  const visibleErrors = describeInterruptErrors(
+    allItemErrors,
+    chat.interruptErrors,
+  )
+  const hasRetryableError = chat.interruptErrors.some(
+    (interruptError) => interruptError.retryable,
+  )
+  const interruptedRunId = chat.resumeState?.runId
+  const durabilityOutcome = durableOutcomeStatus(
+    allItemErrors,
+    chat.interruptErrors,
+  )
+  const capabilityStatuses = durableCapabilityStatuses(mode, {
+    retryable: hasRetryableError,
+    hasExpiresAt: chat.interrupts.some(
+      (interrupt) => interrupt.expiresAt !== undefined,
+    ),
+  })
+
+  useEffect(() => {
+    logInterruptLabClientDebug(debug, {
+      event: 'interrupt-state',
+      resumeState: chat.resumeState,
+      resuming: chat.resuming,
+      interrupts: chat.interrupts.map((interrupt) => ({
+        id: interrupt.id,
+        kind: interrupt.kind,
+        status: interrupt.status,
+        canResolve: interrupt.canResolve,
+        binding: interrupt.binding,
+        errors: interrupt.errors,
+      })),
+      interruptErrors: chat.interruptErrors,
+    })
+  }, [
+    chat.interruptErrors,
+    chat.interrupts,
+    chat.resumeState,
+    chat.resuming,
+    debug,
+  ])
+
+  useEffect(() => {
+    onBusyChange(pending || chat.isLoading || chat.resuming)
+    return () => onBusyChange(false)
+  }, [chat.isLoading, chat.resuming, onBusyChange, pending])
+
+  useEffect(() => {
+    if (mode !== 'durable') return
+    const previousKey = durableDraftKeyRef.current
+
+    if (interruptedRunId === undefined || chat.interrupts.length === 0) {
+      if (previousKey !== undefined) window.localStorage.removeItem(previousKey)
+      durableDraftKeyRef.current = undefined
+      return
+    }
+    const activeKey = durableDraftStorageKey(threadId, interruptedRunId)
+    if (previousKey !== undefined && previousKey !== activeKey) {
+      window.localStorage.removeItem(previousKey)
+    }
+    if (previousKey !== activeKey) {
+      durableDraftKeyRef.current = activeKey
+      const restored = restoreDurableDrafts({
+        mode,
+        threadId,
+        interruptedRunId,
+        activeInterruptIds: chat.interrupts.map((interrupt) => interrupt.id),
+        serialized: window.localStorage.getItem(activeKey),
+      })
+      setDrafts(restored)
+      return
+    }
+
+    const activeDrafts = Object.fromEntries(
+      chat.interrupts.map((interrupt) => [
+        interrupt.id,
+        drafts[interrupt.id] ?? emptyDraft(interrupt),
+      ]),
+    )
+    const envelope = createDurableDraftEnvelope({
+      mode,
+      threadId,
+      interruptedRunId,
+      drafts: activeDrafts,
+    })
+    if (envelope !== undefined) {
+      window.localStorage.setItem(activeKey, JSON.stringify(envelope))
+    }
+  }, [chat.interrupts, drafts, interruptedRunId, mode, threadId])
+
+  useEffect(() => {
+    if (failNextResume && (chat.error !== undefined || hasRetryableError)) {
+      setFailNextResume(false)
+    }
+  }, [chat.error, failNextResume, hasRetryableError])
+
+  function getDraft(interrupt: LabInterrupt): InterruptEditorDraft {
+    return drafts[interrupt.id] ?? emptyDraft(interrupt)
+  }
+
+  function patchDraft(
+    interrupt: LabInterrupt,
+    patch: Partial<InterruptEditorDraft>,
+  ) {
+    setDrafts((current) => ({
+      ...current,
+      [interrupt.id]: {
+        ...(current[interrupt.id] ?? emptyDraft(interrupt)),
+        ...patch,
+      },
+    }))
+  }
+
+  function parsedEdit<T>(
+    interrupt: LabInterrupt,
+    parse: (value: unknown) => T,
+  ): T | undefined {
+    const draft = getDraft(interrupt)
+    return draft.includeEditedArgs
+      ? parse(buildGenericResolution(draft.editedArgs))
+      : undefined
+  }
+
+  function resolveApproval(
+    interrupt: Extract<LabInterrupt, { kind: 'tool-approval' }>,
+    approved: boolean,
+  ) {
+    const draft = getDraft(interrupt)
+    switch (interrupt.toolName) {
+      case 'interrupt_lab_approval_basic': {
+        if (!approved) return interrupt.resolveInterrupt(false)
+        const editedArgs = parsedEdit(
+          interrupt,
+          approvalBasicTool.inputSchema.parse,
+        )
+        return editedArgs
+          ? interrupt.resolveInterrupt(true, { editedArgs })
+          : interrupt.resolveInterrupt(true)
+      }
+      case 'interrupt_lab_edit_order': {
+        if (!approved) return interrupt.resolveInterrupt(false)
+        const editedArgs = parsedEdit(
+          interrupt,
+          approvalEditArgsTool.inputSchema.parse,
+        )
+        return editedArgs
+          ? interrupt.resolveInterrupt(true, { editedArgs })
+          : interrupt.resolveInterrupt(true)
+      }
+      case 'interrupt_lab_batch_second': {
+        if (!approved) return interrupt.resolveInterrupt(false)
+        const editedArgs = parsedEdit(
+          interrupt,
+          batchSecondTool.inputSchema.parse,
+        )
+        return editedArgs
+          ? interrupt.resolveInterrupt(true, { editedArgs })
+          : interrupt.resolveInterrupt(true)
+      }
+      case 'interrupt_lab_batch_third': {
+        if (!approved) return interrupt.resolveInterrupt(false)
+        const editedArgs = parsedEdit(
+          interrupt,
+          batchThirdTool.inputSchema.parse,
+        )
+        return editedArgs
+          ? interrupt.resolveInterrupt(true, { editedArgs })
+          : interrupt.resolveInterrupt(true)
+      }
+      case 'interrupt_lab_shared_payload': {
+        const source = approved ? draft.approvePayload : draft.rejectPayload
+        const payload = approvalSharedPayloadTool.approvalSchema.parse(
+          buildGenericResolution(source),
+        )
+        if (!approved) return interrupt.resolveInterrupt(false, { payload })
+        const editedArgs = parsedEdit(
+          interrupt,
+          approvalSharedPayloadTool.inputSchema.parse,
+        )
+        return interrupt.resolveInterrupt(true, {
+          ...(editedArgs ? { editedArgs } : {}),
+          payload,
+        })
+      }
+      case 'interrupt_lab_branch_payload': {
+        if (!approved) {
+          const payload = approvalBranchPayloadTool.approvalSchema.reject.parse(
+            buildGenericResolution(draft.rejectPayload),
+          )
+          return interrupt.resolveInterrupt(false, { payload })
+        }
+        const payload = approvalBranchPayloadTool.approvalSchema.approve.parse(
+          buildGenericResolution(draft.approvePayload),
+        )
+        const editedArgs = parsedEdit(
+          interrupt,
+          approvalBranchPayloadTool.inputSchema.parse,
+        )
+        return interrupt.resolveInterrupt(true, {
+          ...(editedArgs ? { editedArgs } : {}),
+          payload,
+        })
+      }
+      case 'interrupt_lab_approval_client': {
+        const source = approved ? draft.approvePayload : draft.rejectPayload
+        const payload = approvalClientTool.approvalSchema.parse(
+          buildGenericResolution(source),
+        )
+        if (!approved) return interrupt.resolveInterrupt(false, { payload })
+        const editedArgs = parsedEdit(
+          interrupt,
+          approvalClientTool.inputSchema.parse,
+        )
+        return interrupt.resolveInterrupt(true, {
+          ...(editedArgs ? { editedArgs } : {}),
+          payload,
+        })
+      }
+    }
+  }
+
+  function resolveOne(interrupt: LabInterrupt, approved = true) {
+    setLocalNotice(undefined)
+    if (interrupt.kind === 'tool-approval') {
+      resolveApproval(interrupt, approved)
+      return
+    }
+    const output = buildGenericResolution(getDraft(interrupt).output)
+    if (interrupt.kind === 'generic') {
+      interrupt.resolveInterrupt(output)
+      return
+    }
+    switch (interrupt.toolName) {
+      case 'interrupt_lab_client_output':
+        interrupt.resolveInterrupt(clientOutputTool.outputSchema.parse(output))
+        return
+      case 'interrupt_lab_approval_client':
+        interrupt.resolveInterrupt(
+          approvalClientTool.outputSchema.parse(output),
+        )
+        return
+    }
+  }
+
+  function safely(action: () => void) {
+    try {
+      action()
+    } catch (error) {
+      setLocalNotice(error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  function deliberatelyInvalid(interrupt: LabInterrupt) {
+    const invalidPayload = invalidAggregateResolutionArguments(interrupt.kind)
+    Reflect.apply(interrupt.resolveInterrupt, undefined, invalidPayload)
+  }
+
+  function createAggregateValidationErrors() {
+    for (const interrupt of chat.interrupts) deliberatelyInvalid(interrupt)
+    chat.resolveInterrupts(createIncompleteBulkResolver())
+    setLocalNotice(
+      'Deliberate invalid runtime data produced correlated item errors plus an incomplete-batch root error. Clear each resolution, fix the JSON, and resolve again.',
+    )
+  }
+
+  async function runScenario() {
+    setLocalNotice(undefined)
+    setEvents([])
+    if (chat.messages.length > 0) chat.clear()
+    try {
+      await chat.sendMessage(config.promptFor(scenarioId))
+    } catch (error) {
+      setLocalNotice(error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  async function sendNote(event: React.FormEvent) {
+    event.preventDefault()
+    if (
+      isNormalSendDisabled(
+        note,
+        chat.isLoading,
+        chat.resuming,
+        chat.interrupts.length,
+      )
+    ) {
+      return
+    }
+    const value = note.trim()
+    setNote('')
+    try {
+      await chat.sendMessage(value)
+    } catch (error) {
+      setLocalNotice(error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  return (
+    <div className="space-y-7">
+      <section className="border border-[#867b5e] bg-[#fffaf0] p-5 shadow-[5px_5px_0_#c8bc9e] sm:p-7">
+        <div className="flex flex-wrap items-start justify-between gap-4">
+          <div>
+            <p className="font-mono text-xs uppercase tracking-[0.2em] text-[#657157]">
+              Active case · {scenario.category}
+            </p>
+            <h2 className="mt-2 [font-family:Georgia,serif] text-3xl font-bold">
+              {scenario.label}
+            </h2>
+            <p className="mt-2 max-w-3xl text-sm leading-6 text-[#596157]">
+              {scenario.description}
+            </p>
+            {scenario.category === 'generic' && (
+              <p className="mt-3 inline-block border border-[#71558a] bg-[#eee3f2] px-3 py-2 font-mono text-[11px] uppercase tracking-wider text-[#503963]">
+                Controlled external-style AG-UI boundary · appended after the
+                real model run
+              </p>
+            )}
+          </div>
+          <button
+            type="button"
+            disabled={chat.isLoading || chat.resuming || pending}
+            onClick={() => void runScenario()}
+            className="inline-flex items-center gap-2 border border-[#173d28] bg-[#2d5b3c] px-5 py-3 text-sm font-bold text-white shadow-[3px_3px_0_#9b8c66] transition hover:bg-[#244a32] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[#173d28] disabled:cursor-not-allowed disabled:opacity-45 motion-reduce:transition-none"
+          >
+            <Radio size={17} /> Run exact scenario prompt
+          </button>
+        </div>
+
+        <div className="mt-5 border-l-4 border-[#6e7b4e] bg-[#ece8d6] px-4 py-3 font-mono text-xs leading-5 text-[#394338]">
+          {scenario.prompt}
+        </div>
+        <div className="mt-4 flex flex-wrap gap-x-5 gap-y-2 font-mono text-xs text-[#596157]">
+          <span>endpoint · {config.endpoint}</span>
+          <span>thread · {threadId.slice(0, 34)}…</span>
+          <span>model · server-configured gpt-5.5</span>
+        </div>
+
+        <form
+          onSubmit={(event) => void sendNote(event)}
+          className="mt-5 flex gap-2"
+        >
+          <label className="sr-only" htmlFor="interrupt-lab-note">
+            Send a normal field note
+          </label>
+          <input
+            id="interrupt-lab-note"
+            value={note}
+            onChange={(event) => setNote(event.target.value)}
+            disabled={pending || chat.isLoading || chat.resuming}
+            placeholder={
+              pending
+                ? 'Resolve the active interrupts first'
+                : 'Optional normal field note'
+            }
+            className="min-w-0 flex-1 border border-[#a99d7e] bg-white px-4 py-3 text-sm focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[#2d5b3c] disabled:bg-[#e1dccd]"
+          />
+          <button
+            type="submit"
+            disabled={isNormalSendDisabled(
+              note,
+              chat.isLoading,
+              chat.resuming,
+              chat.interrupts.length,
+            )}
+            className="border border-[#2d5b3c] px-4 text-[#23412f] disabled:opacity-40"
+            aria-label="Send normal field note"
+          >
+            <Send size={18} />
+          </button>
+        </form>
+
+        {chat.error && (
+          <div
+            role="alert"
+            className="mt-4 border border-[#a44a39] bg-[#f7ddd4] p-4 text-sm text-[#6d281d]"
+          >
+            <strong>Server request failed.</strong> {chat.error.message}
+            {shouldShowOpenAiApiKeyGuidance(chat.error) && (
+              <span className="mt-1 block">
+                This lab requires <code>OPENAI_API_KEY</code> on the server.
+              </span>
+            )}
+          </div>
+        )}
+        {localNotice && (
+          <div
+            role="alert"
+            className="mt-4 border border-[#a96e2d] bg-[#f5e5c8] p-4 text-sm text-[#684416]"
+          >
+            <strong>Field lab notice.</strong> {localNotice}
+          </div>
+        )}
+      </section>
+
+      {pending && (
+        <section aria-labelledby="interrupt-heading" className="space-y-4">
+          <div className="flex flex-wrap items-end justify-between gap-3">
+            <div>
+              <p className="font-mono text-xs uppercase tracking-[0.2em] text-[#5b674d]">
+                Live response queue
+              </p>
+              <h2
+                id="interrupt-heading"
+                className="mt-1 [font-family:Georgia,serif] text-3xl font-bold"
+              >
+                {chat.interrupts.length} active interrupt
+                {chat.interrupts.length === 1 ? '' : 's'}
+              </h2>
+              <p className="mt-1 text-sm text-[#596157]">
+                {interruptProgressLabel(
+                  chat.interrupts.length,
+                  staged,
+                  chat.resuming,
+                )}
+              </p>
+            </div>
+            <span className="border border-[#69765a] bg-[#edf0df] px-3 py-2 font-mono text-xs uppercase tracking-wider">
+              {chat.resuming ? 'Submitting' : 'Awaiting decisions'}
+            </span>
+          </div>
+
+          <RootControls
+            interrupts={chat.interrupts}
+            canBooleanBulk={canBooleanBulk(chat.interrupts)}
+            disabled={chat.resuming}
+            retryable={hasRetryableError}
+            onApproveAll={() => chat.resolveInterrupts(true)}
+            onRejectAll={() => chat.resolveInterrupts(false)}
+            onCancelAll={chat.cancelInterrupts}
+            onValidCallback={() =>
+              chat.resolveInterrupts((interrupt) => {
+                resolveOne(interrupt, true)
+                return undefined
+              })
+            }
+            onInvalidPayload={createAggregateValidationErrors}
+            onInvalidReturn={() =>
+              Reflect.apply(chat.resolveInterrupts, undefined, [
+                () => 'invalid',
+              ])
+            }
+            onThrow={() =>
+              chat.resolveInterrupts(() => {
+                throw new Error('Deliberate field callback failure.')
+              })
+            }
+            onIncomplete={() =>
+              chat.resolveInterrupts(createIncompleteBulkResolver())
+            }
+            onRetry={chat.retryInterrupts}
+          />
+
+          <div className="grid gap-4 2xl:grid-cols-2">
+            {chat.interrupts.map((interrupt, index) => (
+              <InterruptCard
+                key={interrupt.id}
+                interrupt={interrupt}
+                index={index}
+                draft={getDraft(interrupt)}
+                disabled={chat.resuming}
+                onDraft={(patch) => patchDraft(interrupt, patch)}
+                onApprove={() => safely(() => resolveOne(interrupt, true))}
+                onReject={() => safely(() => resolveOne(interrupt, false))}
+                onResolve={() => safely(() => resolveOne(interrupt))}
+                onInvalidEdit={() => {
+                  patchDraft(interrupt, {
+                    editedArgs: '{\n  "destination": "",\n  "quantity": 0\n}',
+                    includeEditedArgs: true,
+                  })
+                  Reflect.apply(interrupt.resolveInterrupt, undefined, [
+                    true,
+                    { editedArgs: { destination: '', quantity: 0 } },
+                  ])
+                }}
+              />
+            ))}
+          </div>
+        </section>
+      )}
+
+      {mode === 'durable' && (
+        <DurabilityPanel
+          resumeState={chat.resumeState}
+          interrupts={chat.interrupts}
+          retryable={hasRetryableError}
+          onRetry={chat.retryInterrupts}
+          outcome={durabilityOutcome}
+          capabilities={capabilityStatuses}
+          failNextResume={failNextResume}
+          onFailNextResume={setFailNextResume}
+        />
+      )}
+
+      <Inspector
+        messages={chat.messages}
+        events={events}
+        errors={visibleErrors}
+        isLoading={chat.isLoading}
+      />
+    </div>
+  )
+}
+
+function RootControls({
+  canBooleanBulk: showBooleanBulk,
+  disabled,
+  retryable,
+  onApproveAll,
+  onRejectAll,
+  onCancelAll,
+  onValidCallback,
+  onInvalidPayload,
+  onInvalidReturn,
+  onThrow,
+  onIncomplete,
+  onRetry,
+}: {
+  interrupts: ReadonlyArray<LabInterrupt>
+  canBooleanBulk: boolean
+  disabled: boolean
+  retryable: boolean
+  onApproveAll: () => void
+  onRejectAll: () => void
+  onCancelAll: () => void
+  onValidCallback: () => void
+  onInvalidPayload: () => void
+  onInvalidReturn: () => void
+  onThrow: () => void
+  onIncomplete: () => void
+  onRetry: () => void
+}) {
+  const buttonClass =
+    'border border-[#6f745f] bg-[#f8f3e5] px-3 py-2 text-xs font-bold transition hover:bg-white focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[#2d5b3c] disabled:opacity-40'
+  return (
+    <div className="border border-[#8f866d] bg-[#dcd6c4] p-3">
+      <div className="flex flex-wrap gap-2">
+        {showBooleanBulk && (
+          <>
+            <button
+              type="button"
+              disabled={disabled}
+              onClick={onApproveAll}
+              className={buttonClass}
+            >
+              Approve all
+            </button>
+            <button
+              type="button"
+              disabled={disabled}
+              onClick={onRejectAll}
+              className={buttonClass}
+            >
+              Reject all
+            </button>
+          </>
+        )}
+        <button
+          type="button"
+          disabled={disabled}
+          onClick={onCancelAll}
+          className={buttonClass}
+        >
+          Cancel all
+        </button>
+        <button
+          type="button"
+          disabled={disabled}
+          onClick={onValidCallback}
+          className={buttonClass}
+        >
+          Resolve via callback
+        </button>
+        <button
+          type="button"
+          disabled={disabled}
+          onClick={onInvalidPayload}
+          className={buttonClass}
+        >
+          Create item + batch validation errors
+        </button>
+        <button
+          type="button"
+          disabled={disabled}
+          onClick={onInvalidReturn}
+          className={buttonClass}
+        >
+          Invalid return rollback
+        </button>
+        <button
+          type="button"
+          disabled={disabled}
+          onClick={onThrow}
+          className={buttonClass}
+        >
+          Thrown callback rollback
+        </button>
+        <button
+          type="button"
+          disabled={disabled}
+          onClick={onIncomplete}
+          className={buttonClass}
+        >
+          Incomplete callback rollback
+        </button>
+        <button
+          type="button"
+          disabled={disabled || !retryable}
+          onClick={onRetry}
+          className={buttonClass}
+        >
+          Retry submission
+        </button>
+      </div>
+    </div>
+  )
+}
+
+function InterruptCard({
+  interrupt,
+  index,
+  draft,
+  disabled,
+  onDraft,
+  onApprove,
+  onReject,
+  onResolve,
+  onInvalidEdit,
+}: {
+  interrupt: LabInterrupt
+  index: number
+  draft: InterruptEditorDraft
+  disabled: boolean
+  onDraft: (patch: Partial<InterruptEditorDraft>) => void
+  onApprove: () => void
+  onReject: () => void
+  onResolve: () => void
+  onInvalidEdit: () => void
+}) {
+  const showPayload = hasDecisionPayload(interrupt)
+  const textareaClass =
+    'mt-1 min-h-24 w-full border border-[#aaa083] bg-[#fffdf7] p-3 font-mono text-xs leading-5 focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[#2d5b3c] disabled:bg-[#e4dfd1]'
+  return (
+    <article className="border border-[#5e6e55] bg-[#f8f2df] p-5 shadow-[4px_4px_0_#a9a185]">
+      <div className="flex items-start justify-between gap-4">
+        <div>
+          <p className="font-mono text-[11px] uppercase tracking-[0.18em] text-[#6c745f]">
+            Case {String(index + 1).padStart(2, '0')} · {interrupt.kind}
+          </p>
+          <h3 className="mt-2 [font-family:Georgia,serif] text-xl font-bold">
+            {interrupt.kind === 'generic'
+              ? interrupt.reason
+              : interrupt.toolName}
+          </h3>
+          <p className="mt-1 text-sm text-[#596157]">{interrupt.message}</p>
+        </div>
+        <span className="border border-[#7c846c] px-2 py-1 font-mono text-[10px] uppercase">
+          {interrupt.status}
+        </span>
+      </div>
+
+      <details className="mt-4 border-y border-[#c9bea1] py-2 text-xs">
+        <summary className="cursor-pointer font-bold">
+          Binding & response schema
+        </summary>
+        <pre className="mt-2 max-h-48 overflow-auto whitespace-pre-wrap font-mono leading-5">
+          {JSON.stringify(
+            {
+              binding: interrupt.binding,
+              responseSchema: interrupt.responseSchema,
+            },
+            null,
+            2,
+          )}
+        </pre>
+      </details>
+
+      {interrupt.kind === 'tool-approval' ? (
+        <>
+          <label className="mt-4 flex items-center gap-2 text-xs font-bold">
+            <input
+              type="checkbox"
+              checked={draft.includeEditedArgs}
+              disabled={disabled}
+              onChange={(event) =>
+                onDraft({ includeEditedArgs: event.target.checked })
+              }
+            />
+            Submit optional full-replacement editedArgs
+          </label>
+          <label className="mt-3 block text-xs font-bold">
+            Edited arguments · JSON
+            <textarea
+              aria-label={`Edited arguments for ${interrupt.id}`}
+              disabled={disabled || !draft.includeEditedArgs}
+              value={draft.editedArgs}
+              onChange={(event) => onDraft({ editedArgs: event.target.value })}
+              className={textareaClass}
+            />
+          </label>
+          {showPayload && (
+            <div className="mt-3 grid gap-3 sm:grid-cols-2">
+              <label className="block text-xs font-bold">
+                Approve payload · JSON
+                <textarea
+                  aria-label={`Approve payload for ${interrupt.id}`}
+                  disabled={disabled}
+                  value={draft.approvePayload}
+                  onChange={(event) =>
+                    onDraft({ approvePayload: event.target.value })
+                  }
+                  className={textareaClass}
+                />
+              </label>
+              <label className="block text-xs font-bold">
+                Reject payload · JSON
+                <textarea
+                  aria-label={`Reject payload for ${interrupt.id}`}
+                  disabled={disabled}
+                  value={draft.rejectPayload}
+                  onChange={(event) =>
+                    onDraft({ rejectPayload: event.target.value })
+                  }
+                  className={textareaClass}
+                />
+              </label>
+            </div>
+          )}
+        </>
+      ) : (
+        <label className="mt-4 block text-xs font-bold">
+          {interrupt.kind === 'generic'
+            ? 'Generic response payload'
+            : 'Typed client tool output'}{' '}
+          · JSON
+          <textarea
+            aria-label={`Response for ${interrupt.id}`}
+            disabled={disabled}
+            value={draft.output}
+            onChange={(event) => onDraft({ output: event.target.value })}
+            className={textareaClass}
+          />
+        </label>
+      )}
+
+      {interrupt.errors.length > 0 && (
+        <ul
+          role="alert"
+          className="mt-4 space-y-1 border border-[#b9503d] bg-[#f6dcd2] p-3 text-xs text-[#722c20]"
+        >
+          {interrupt.errors.map((error, errorIndex) => (
+            <li key={`${error.code}:${errorIndex}`}>
+              {error.code} · {error.message}
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <div className="mt-4 flex flex-wrap gap-2">
+        {interrupt.kind === 'tool-approval' ? (
+          <>
+            <ActionButton
+              disabled={disabled || !interrupt.canResolve}
+              onClick={onApprove}
+              tone="approve"
+            >
+              <Check size={15} /> Approve
+            </ActionButton>
+            <ActionButton
+              disabled={disabled || !interrupt.canResolve}
+              onClick={onReject}
+              tone="reject"
+            >
+              <X size={15} /> Reject
+            </ActionButton>
+            {interrupt.toolName === 'interrupt_lab_edit_order' && (
+              <ActionButton disabled={disabled} onClick={onInvalidEdit}>
+                Invalid edit
+              </ActionButton>
+            )}
+          </>
+        ) : (
+          <ActionButton
+            disabled={disabled || !interrupt.canResolve}
+            onClick={onResolve}
+            tone="approve"
+          >
+            <Check size={15} /> Resolve{' '}
+            {interrupt.kind === 'generic'
+              ? 'generic response'
+              : 'client output'}
+          </ActionButton>
+        )}
+        <ActionButton
+          disabled={disabled}
+          onClick={interrupt.cancel}
+          tone="reject"
+        >
+          Cancel{interrupt.kind === 'generic' ? ' generic interrupt' : ''}
+        </ActionButton>
+        <ActionButton
+          disabled={disabled || interrupt.status === 'pending'}
+          onClick={interrupt.clearResolution}
+        >
+          <RotateCcw size={14} />{' '}
+          {interrupt.kind === 'generic'
+            ? 'Clear generic response'
+            : 'Clear resolution'}
+        </ActionButton>
+      </div>
+    </article>
+  )
+}
+
+function ActionButton({
+  children,
+  tone,
+  ...props
+}: React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  tone?: 'approve' | 'reject'
+}) {
+  return (
+    <button
+      type="button"
+      {...props}
+      className={`inline-flex items-center gap-1.5 border px-3 py-2 text-xs font-bold focus-visible:outline-2 focus-visible:outline-offset-2 disabled:opacity-40 ${tone === 'approve' ? 'border-[#2d5b3c] bg-[#dce8d2] text-[#173d28]' : tone === 'reject' ? 'border-[#8e493b] bg-[#f1d8cf] text-[#712f24]' : 'border-[#77715f] bg-[#eee8d8]'}`}
+    >
+      {children}
+    </button>
+  )
+}
+
+function DurabilityPanel({
+  resumeState,
+  interrupts,
+  retryable,
+  onRetry,
+  outcome,
+  capabilities,
+  failNextResume,
+  onFailNextResume,
+}: {
+  resumeState: { threadId: string; runId: string } | null
+  interrupts: ReadonlyArray<LabInterrupt>
+  retryable: boolean
+  onRetry: () => void
+  outcome: ReturnType<typeof durableOutcomeStatus>
+  capabilities: ReturnType<typeof durableCapabilityStatuses>
+  failNextResume: boolean
+  onFailNextResume: (enabled: boolean) => void
+}) {
+  const expiresAt = interrupts
+    .map((interrupt) => interrupt.expiresAt)
+    .find(Boolean)
+  return (
+    <section className="border border-[#315446] bg-[#dce8dc] p-5">
+      <div className="flex items-center gap-2">
+        <ShieldCheck size={20} />
+        <h2 className="[font-family:Georgia,serif] text-2xl font-bold">
+          Durability station
+        </h2>
+      </div>
+      <p className="mt-2 text-sm text-[#43564b]">
+        SQLite owns atomic batches. Browser storage owns the public resume
+        snapshot and staged drafts.
+      </p>
+      <div
+        className={`mt-4 border p-3 ${outcome.kind === 'conflict' || outcome.kind === 'stale' || outcome.kind === 'expired' ? 'border-[#9c4b3d] bg-[#f2d9d0]' : outcome.kind === 'retryable' ? 'border-[#a36c24] bg-[#f4e5c8]' : 'border-[#55745e] bg-[#edf3e5]'}`}
+      >
+        <strong className="font-mono text-xs uppercase tracking-wider">
+          {outcome.label}
+        </strong>
+        <p className="mt-1 text-xs leading-5">{outcome.detail}</p>
+      </div>
+      <div className="mt-4 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+        {capabilities.map((capability) => (
+          <Capability
+            key={capability.id}
+            label={capability.id.replaceAll('-', ' ')}
+            value={capability.detail}
+            availability={capability.availability}
+          />
+        ))}
+      </div>
+      {resumeState && (
+        <p className="mt-3 font-mono text-xs">
+          Saved draft namespace · run {resumeState.runId.slice(0, 16)}…
+        </p>
+      )}
+      {expiresAt && (
+        <p className="mt-2 font-mono text-xs">
+          Advertised expiresAt · {expiresAt}
+        </p>
+      )}
+      <div className="mt-4 flex flex-wrap gap-2">
+        <button
+          type="button"
+          onClick={() => window.location.reload()}
+          className="inline-flex items-center gap-2 border border-[#315446] bg-white px-3 py-2 text-xs font-bold"
+        >
+          <RefreshCw size={14} /> Reload & recover draft
+        </button>
+        <button
+          type="button"
+          onClick={() =>
+            window.open(window.location.href, '_blank', 'noopener')
+          }
+          className="inline-flex items-center gap-2 border border-[#315446] bg-white px-3 py-2 text-xs font-bold"
+        >
+          <ExternalLink size={14} /> Open second tab
+        </button>
+        <button
+          type="button"
+          disabled={!retryable}
+          onClick={onRetry}
+          className="border border-[#315446] bg-white px-3 py-2 text-xs font-bold disabled:opacity-40"
+        >
+          Replay failed submission with retryInterrupts()
+        </button>
+        <label className="flex items-center gap-2 border border-[#315446] bg-[#f5ead0] px-3 py-2 text-xs font-bold">
+          <input
+            type="checkbox"
+            checked={failNextResume}
+            disabled={retryable}
+            onChange={(event) => onFailNextResume(event.target.checked)}
+          />
+          Arm one safe 503 on the next resume
+        </label>
+      </div>
+      <p className="mt-3 text-xs leading-5 text-[#4e5c53]">
+        Retry replays the captured failed submission. It does not join or replay
+        a committed continuation run.
+      </p>
+    </section>
+  )
+}
+
+function Capability({
+  label,
+  value,
+  availability,
+}: {
+  label: string
+  value: string
+  availability?: 'available' | 'unavailable' | 'observable-only'
+}) {
+  return (
+    <div className="border border-[#779081] bg-[#f5f8ee] p-3">
+      <div className="flex items-start justify-between gap-2">
+        <strong className="block font-mono text-[11px] uppercase tracking-wider">
+          {label}
+        </strong>
+        {availability && (
+          <span className="border border-[#98a790] px-1.5 py-0.5 font-mono text-[9px] uppercase">
+            {availability}
+          </span>
+        )}
+      </div>
+      <span className="mt-1 block text-xs leading-5 text-[#4e5c53]">
+        {value}
+      </span>
+    </div>
+  )
+}
+
+function Inspector({
+  messages,
+  events,
+  errors,
+  isLoading,
+}: {
+  messages: Array<UIMessage<typeof clientTools>>
+  events: Array<InspectorEvent>
+  errors: Array<string>
+  isLoading: boolean
+}) {
+  return (
+    <section className="border border-[#283c2e] bg-[#17251d] p-5 text-[#e8eedf]">
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <h2 className="[font-family:Georgia,serif] text-2xl font-bold">
+          Live event & result inspector
+        </h2>
+        <span className="flex items-center gap-2 font-mono text-xs">
+          <span
+            className={`h-2.5 w-2.5 rounded-full motion-reduce:animate-none ${isLoading ? 'animate-pulse bg-[#d7d570]' : 'bg-[#7ca173]'}`}
+          />
+          {isLoading ? 'streaming' : 'quiet'}
+        </span>
+      </div>
+      {errors.length > 0 && (
+        <div
+          role="alert"
+          className="mt-4 border border-[#d87761] bg-[#4b251f] p-3"
+        >
+          <p className="flex items-center gap-2 font-bold">
+            <AlertTriangle size={17} /> Correlated errors
+          </p>
+          <ul className="mt-2 space-y-1 font-mono text-xs">
+            {errors.map((error, index) => (
+              <li key={`${error}:${index}`}>{error}</li>
+            ))}
+          </ul>
+        </div>
+      )}
+      <div className="mt-4 grid gap-4 lg:grid-cols-2">
+        <div>
+          <h3 className="font-mono text-xs uppercase tracking-widest text-[#aabf9f]">
+            Messages & results
+          </h3>
+          <div className="mt-2 max-h-80 space-y-2 overflow-auto">
+            {messages.length === 0 ? (
+              <p className="text-sm text-[#94a18f]">No observations yet.</p>
+            ) : (
+              messages.map((message) => (
+                <div
+                  key={message.id}
+                  className="border border-[#3e5545] bg-[#213329] p-3"
+                >
+                  <strong className="font-mono text-[11px] uppercase text-[#b7cdaa]">
+                    {message.role}
+                  </strong>
+                  <pre className="mt-1 whitespace-pre-wrap text-xs leading-5">
+                    {messageText(message)}
+                  </pre>
+                </div>
+              ))
+            )}
+          </div>
+        </div>
+        <div>
+          <h3 className="font-mono text-xs uppercase tracking-widest text-[#aabf9f]">
+            AG-UI event trail
+          </h3>
+          <div className="mt-2 max-h-80 overflow-auto border border-[#3e5545]">
+            {events.length === 0 ? (
+              <p className="p-3 text-sm text-[#94a18f]">
+                Run a case to begin the trail.
+              </p>
+            ) : (
+              events.map((event, index) => (
+                <div
+                  key={`${event.at}:${event.type}:${index}`}
+                  className="grid grid-cols-[70px_1fr] gap-2 border-b border-[#33483a] p-2 font-mono text-[11px]"
+                >
+                  <span className="text-[#91a58b]">{event.at}</span>
+                  <span>
+                    <b>{event.type}</b> · {event.detail}
+                  </span>
+                </div>
+              ))
+            )}
+          </div>
+        </div>
+      </div>
+    </section>
+  )
+}
diff --git a/examples/ts-react-chat/src/lib/interrupt-lab/client-ui.test.ts b/examples/ts-react-chat/src/lib/interrupt-lab/client-ui.test.ts
new file mode 100644
index 000000000..ec699e976
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/interrupt-lab/client-ui.test.ts
@@ -0,0 +1,320 @@
+import { describe, expect, it } from 'vitest'
+import { interruptLabScenarios } from './scenarios'
+import {
+  buildApprovalResolution,
+  buildGenericResolution,
+  createDurableDraftEnvelope,
+  createInterruptLabDebugFetch,
+  createIncompleteBulkResolver,
+  describeInterruptErrors,
+  durableCapabilityStatuses,
+  durableOutcomeStatus,
+  interruptLabPageConfig,
+  interruptLabSearchFromSearch,
+  interruptProgressLabel,
+  interruptLabDebugFromSearch,
+  invalidAggregateResolutionArguments,
+  isNormalSendDisabled,
+  restoreDurableDrafts,
+  shouldShowOpenAiApiKeyGuidance,
+  visibleDurableControls,
+} from './client-ui'
+
+describe('interrupt lab client interaction contract', () => {
+  it('enables debug logging only for an explicit public query flag', () => {
+    expect(interruptLabDebugFromSearch({})).toBe(false)
+    expect(interruptLabDebugFromSearch({ debug: false })).toBe(false)
+    expect(interruptLabDebugFromSearch({ debug: '0' })).toBe(false)
+    expect(interruptLabDebugFromSearch({ debug: true })).toBe(true)
+    expect(interruptLabDebugFromSearch({ debug: '1' })).toBe(true)
+    expect(interruptLabDebugFromSearch({ debug: 'true' })).toBe(true)
+  })
+
+  it('keeps a valid scenario case with the debug flag and rejects unknown cases', () => {
+    expect(
+      interruptLabSearchFromSearch(
+        { debug: '1', case: 'approval-edit-args' },
+        'durable',
+      ),
+    ).toEqual({ debug: true, case: 'approval-edit-args' })
+    expect(
+      interruptLabSearchFromSearch(
+        { debug: 'true', case: 'not-a-scenario' },
+        'durable',
+      ),
+    ).toEqual({ debug: true })
+  })
+
+  it('logs structured client requests and responses only when debug is enabled', async () => {
+    const entries: Array<unknown> = []
+    const fetchClient: typeof fetch = () => Promise.resolve(new Response('ok'))
+    const disabledFetch = createInterruptLabDebugFetch({
+      enabled: false,
+      fetchClient,
+      log: (entry) => entries.push(entry),
+    })
+    await disabledFetch('http://localhost/api/interrupts', {
+      method: 'POST',
+      body: JSON.stringify({ runId: 'run-disabled' }),
+    })
+    expect(entries).toEqual([])
+
+    const debugFetch = createInterruptLabDebugFetch({
+      enabled: true,
+      fetchClient,
+      log: (entry) => entries.push(entry),
+    })
+    await debugFetch('http://localhost/api/interrupts', {
+      method: 'POST',
+      headers: { authorization: 'never-log-this-secret' },
+      body: JSON.stringify({
+        threadId: 'thread-1',
+        runId: 'run-2',
+        parentRunId: 'run-1',
+        resume: [
+          {
+            interruptId: 'approval_fc_1',
+            status: 'resolved',
+            payload: { approved: true },
+          },
+        ],
+      }),
+    })
+
+    expect(entries).toEqual([
+      {
+        event: 'request',
+        url: 'http://localhost/api/interrupts',
+        method: 'POST',
+        body: {
+          threadId: 'thread-1',
+          runId: 'run-2',
+          parentRunId: 'run-1',
+          resume: [
+            {
+              interruptId: 'approval_fc_1',
+              status: 'resolved',
+              payload: { approved: true },
+            },
+          ],
+        },
+      },
+      {
+        event: 'response',
+        url: 'http://localhost/api/interrupts',
+        status: 200,
+        ok: true,
+      },
+    ])
+    expect(JSON.stringify(entries)).not.toContain('never-log-this-secret')
+  })
+
+  it('maps each mode to its own endpoint and stable thread namespace', () => {
+    expect(interruptLabPageConfig('ephemeral')).toMatchObject({
+      endpoint: '/api/interrupts',
+      threadPrefix: 'interrupt-lab-ephemeral',
+      durable: false,
+    })
+    expect(interruptLabPageConfig('durable')).toMatchObject({
+      endpoint: '/api/durable-interrupts',
+      threadPrefix: 'interrupt-lab-durable',
+      durable: true,
+    })
+  })
+
+  it('dispatches the registry prompt unchanged', () => {
+    const scenario = interruptLabScenarios['approval-edit-args']
+    expect(interruptLabPageConfig('ephemeral').promptFor(scenario.id)).toBe(
+      scenario.prompt,
+    )
+  })
+
+  it('distinguishes a staged item from the final auto-submitting item', () => {
+    expect(interruptProgressLabel(3, 1, false)).toContain('1 of 3 staged')
+    expect(interruptProgressLabel(3, 2, false)).toContain('final decision')
+    expect(interruptProgressLabel(3, 3, true)).toContain('Submitting')
+  })
+
+  it('keeps edited arguments and approval data under payload', () => {
+    expect(
+      buildApprovalResolution(true, '{"quantity":2}', '{"note":"ok"}'),
+    ).toEqual({
+      approved: true,
+      options: {
+        editedArgs: { quantity: 2 },
+        payload: { note: 'ok' },
+      },
+    })
+    expect(buildGenericResolution('{"answer":"yes"}')).toEqual({
+      answer: 'yes',
+    })
+  })
+
+  it('provides a deliberately incomplete callback for rollback demos', () => {
+    expect(
+      createIncompleteBulkResolver()({ id: 'interrupt-1' }),
+    ).toBeUndefined()
+  })
+
+  it('disables normal sends while any interrupt is pending', () => {
+    expect(isNormalSendDisabled('note', false, false, 1)).toBe(true)
+    expect(isNormalSendDisabled('note', false, false, 0)).toBe(false)
+    expect(isNormalSendDisabled('', false, false, 0)).toBe(true)
+  })
+
+  it('does not mislabel generic or interrupt failures as a missing API key', () => {
+    expect(
+      shouldShowOpenAiApiKeyGuidance({
+        message: 'Interrupt lab run failed.',
+      }),
+    ).toBe(false)
+    expect(
+      shouldShowOpenAiApiKeyGuidance({
+        code: 'unknown-interrupt',
+        message: 'Resume entry references unknown interrupt approval_fc_123.',
+      }),
+    ).toBe(false)
+    expect(
+      shouldShowOpenAiApiKeyGuidance({
+        message: 'The server returned an unexpected response.',
+      }),
+    ).toBe(false)
+  })
+
+  it('shows API-key guidance only for an explicit missing-key failure', () => {
+    expect(
+      shouldShowOpenAiApiKeyGuidance({
+        message:
+          'OPENAI_API_KEY is required for the interrupt lab. Set it and restart the dev server.',
+      }),
+    ).toBe(true)
+    expect(
+      shouldShowOpenAiApiKeyGuidance({
+        code: 'openai-api-key-required',
+        message: 'Server configuration is incomplete.',
+      }),
+    ).toBe(true)
+  })
+
+  it('only exposes recovery controls in durable mode', () => {
+    expect(visibleDurableControls('ephemeral')).toEqual([])
+    expect(visibleDurableControls('durable')).toEqual([
+      'saved-drafts',
+      'reload-recovery',
+      'retry-join-replay',
+      'cas-conflict',
+      'expiry',
+    ])
+  })
+
+  it('projects item and batch errors for the visible inspector', () => {
+    expect(
+      describeInterruptErrors(
+        [{ code: 'invalid-payload', message: 'note is required' }],
+        [{ code: 'incomplete-batch', message: 'resolve every item' }],
+      ),
+    ).toEqual([
+      'Item · invalid-payload · note is required',
+      'Batch · incomplete-batch · resolve every item',
+    ])
+  })
+
+  it('creates unsafe-runtime aggregate inputs for every interrupt kind', () => {
+    expect(invalidAggregateResolutionArguments('tool-approval')).toEqual([
+      true,
+      { editedArgs: {}, payload: {} },
+    ])
+    expect(invalidAggregateResolutionArguments('generic')).toEqual([{}])
+    expect(
+      invalidAggregateResolutionArguments('client-tool-execution'),
+    ).toEqual([{}])
+  })
+
+  it('round-trips only active durable editor drafts', () => {
+    const draft = {
+      editedArgs: '{"quantity":2}',
+      includeEditedArgs: true,
+      approvePayload: '{"note":"ok"}',
+      rejectPayload: '{"reason":"no"}',
+      output: '{"browserValue":"42"}',
+    }
+    const envelope = createDurableDraftEnvelope({
+      mode: 'durable',
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      drafts: { one: draft, stale: { ...draft, output: 'stale' } },
+    })
+
+    expect(
+      restoreDurableDrafts({
+        mode: 'durable',
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        activeInterruptIds: ['one'],
+        serialized: JSON.stringify(envelope),
+      }),
+    ).toEqual({ one: draft })
+    expect(
+      restoreDurableDrafts({
+        mode: 'ephemeral',
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        activeInterruptIds: ['one'],
+        serialized: JSON.stringify(envelope),
+      }),
+    ).toEqual({})
+  })
+
+  it('maps durable public outcomes and capabilities precisely', () => {
+    expect(
+      durableOutcomeStatus([{ code: 'conflict', retryable: false }]),
+    ).toMatchObject({ kind: 'conflict', label: 'CAS conflict' })
+    expect(
+      durableOutcomeStatus([{ code: 'stale', retryable: false }]),
+    ).toMatchObject({ kind: 'stale', label: 'Stale generation' })
+    expect(
+      durableOutcomeStatus([{ code: 'expired', retryable: false }]),
+    ).toMatchObject({ kind: 'expired', label: 'Expired' })
+    expect(
+      durableOutcomeStatus([{ code: 'transport', retryable: true }]),
+    ).toMatchObject({ kind: 'retryable', label: 'Retry available' })
+
+    expect(
+      durableCapabilityStatuses('durable', {
+        retryable: true,
+        hasExpiresAt: false,
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ id: 'retry', availability: 'available' }),
+        expect.objectContaining({
+          id: 'join-replay',
+          availability: 'unavailable',
+        }),
+        expect.objectContaining({
+          id: 'expiry',
+          availability: 'observable-only',
+        }),
+      ]),
+    )
+  })
+
+  it('prioritizes item-scoped expiry and stale errors with duplicate root errors', () => {
+    expect(
+      durableOutcomeStatus(
+        [{ code: 'stale', retryable: false, scope: 'item' }],
+        [
+          { code: 'conflict', retryable: false, scope: 'batch' },
+          { code: 'conflict', retryable: false, scope: 'batch' },
+        ],
+      ),
+    ).toMatchObject({ kind: 'conflict', label: 'CAS conflict' })
+
+    expect(
+      durableOutcomeStatus(
+        [{ code: 'expired', retryable: false, scope: 'item' }],
+        [{ code: 'stale', retryable: false, scope: 'batch' }],
+      ),
+    ).toMatchObject({ kind: 'expired', label: 'Expired' })
+  })
+})
diff --git a/examples/ts-react-chat/src/lib/interrupt-lab/client-ui.ts b/examples/ts-react-chat/src/lib/interrupt-lab/client-ui.ts
new file mode 100644
index 000000000..9fc8fbe24
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/interrupt-lab/client-ui.ts
@@ -0,0 +1,441 @@
+import { interruptLabScenarios, isInterruptLabScenarioId } from './scenarios'
+import type { InterruptLabMode, InterruptLabScenarioId } from './scenarios'
+
+export type DurableControl =
+  | 'saved-drafts'
+  | 'reload-recovery'
+  | 'retry-join-replay'
+  | 'cas-conflict'
+  | 'expiry'
+
+export interface InterruptLabPageConfig {
+  endpoint: '/api/interrupts' | '/api/durable-interrupts'
+  threadPrefix: 'interrupt-lab-ephemeral' | 'interrupt-lab-durable'
+  durable: boolean
+  promptFor: (scenarioId: InterruptLabScenarioId) => string
+}
+
+export interface InterruptErrorLike {
+  code: string
+  message: string
+}
+
+export interface ChatErrorLike {
+  code?: string
+  message: string
+}
+
+export interface InterruptLabClientDebugEntry {
+  event: 'request' | 'response' | 'chunk' | 'interrupt-state'
+  [key: string]: unknown
+}
+
+export type InterruptLabClientDebugLog = (
+  entry: InterruptLabClientDebugEntry,
+) => void
+
+export interface InterruptEditorDraft {
+  editedArgs: string
+  includeEditedArgs: boolean
+  approvePayload: string
+  rejectPayload: string
+  output: string
+}
+
+export interface DurableDraftEnvelope {
+  schemaVersion: 1
+  mode: 'durable'
+  threadId: string
+  interruptedRunId: string
+  drafts: Record<string, InterruptEditorDraft>
+}
+
+export type DurableOutcomeKind =
+  | 'protected'
+  | 'retryable'
+  | 'conflict'
+  | 'stale'
+  | 'expired'
+  | 'recovery-unavailable'
+
+export interface DurableCapabilityStatus {
+  id: DurableControl | 'retry' | 'join-replay'
+  availability: 'available' | 'unavailable' | 'observable-only'
+  detail: string
+}
+
+function parseOptionalJson(source: string): unknown | undefined {
+  const trimmed = source.trim()
+  return trimmed === '' ? undefined : JSON.parse(trimmed)
+}
+
+export function interruptLabDebugFromSearch(
+  search: Record<string, unknown>,
+): boolean {
+  return (
+    search.debug === true || search.debug === '1' || search.debug === 'true'
+  )
+}
+
+export function interruptLabSearchFromSearch(
+  search: Record<string, unknown>,
+  mode: InterruptLabMode,
+): { debug?: boolean; case?: InterruptLabScenarioId } {
+  const scenarioId = search.case
+  const validScenario =
+    isInterruptLabScenarioId(scenarioId) &&
+    interruptLabScenarios[scenarioId].modes.includes(mode)
+      ? scenarioId
+      : undefined
+  return {
+    ...(interruptLabDebugFromSearch(search) ? { debug: true } : {}),
+    ...(validScenario === undefined ? {} : { case: validScenario }),
+  }
+}
+
+export function logInterruptLabClientDebug(
+  enabled: boolean,
+  entry: InterruptLabClientDebugEntry,
+  log: InterruptLabClientDebugLog = (debugEntry) =>
+    console.debug('[interrupt-lab:client]', debugEntry),
+): void {
+  if (enabled) log(entry)
+}
+
+function debugRequestUrl(input: RequestInfo | URL): string {
+  if (typeof input === 'string') return input
+  if (input instanceof URL) return input.toString()
+  return input.url
+}
+
+function debugRequestBody(body: BodyInit | null | undefined): unknown {
+  if (typeof body !== 'string') return undefined
+  try {
+    return JSON.parse(body)
+  } catch {
+    return body
+  }
+}
+
+export function createInterruptLabDebugFetch({
+  enabled,
+  fetchClient = fetch,
+  log,
+}: {
+  enabled: boolean
+  fetchClient?: typeof fetch
+  log?: InterruptLabClientDebugLog
+}): typeof fetch {
+  return async (input, init) => {
+    const url = debugRequestUrl(input)
+    logInterruptLabClientDebug(
+      enabled,
+      {
+        event: 'request',
+        url,
+        method:
+          init?.method ?? (input instanceof Request ? input.method : 'GET'),
+        body: debugRequestBody(init?.body),
+      },
+      log,
+    )
+    const response = await fetchClient(input, init)
+    logInterruptLabClientDebug(
+      enabled,
+      {
+        event: 'response',
+        url,
+        status: response.status,
+        ok: response.ok,
+      },
+      log,
+    )
+    return response
+  }
+}
+
+export function interruptLabPageConfig(
+  mode: InterruptLabMode,
+): InterruptLabPageConfig {
+  return {
+    endpoint:
+      mode === 'durable' ? '/api/durable-interrupts' : '/api/interrupts',
+    threadPrefix:
+      mode === 'durable' ? 'interrupt-lab-durable' : 'interrupt-lab-ephemeral',
+    durable: mode === 'durable',
+    promptFor: (scenarioId) => interruptLabScenarios[scenarioId].prompt,
+  }
+}
+
+export function buildApprovalResolution(
+  approved: boolean,
+  editedArgsSource: string,
+  payloadSource: string,
+): {
+  approved: boolean
+  options?: { editedArgs?: unknown; payload?: unknown }
+} {
+  const editedArgs = approved ? parseOptionalJson(editedArgsSource) : undefined
+  const payload = parseOptionalJson(payloadSource)
+  if (editedArgs === undefined && payload === undefined) return { approved }
+  return {
+    approved,
+    options: {
+      ...(editedArgs !== undefined ? { editedArgs } : {}),
+      ...(payload !== undefined ? { payload } : {}),
+    },
+  }
+}
+
+export function buildGenericResolution(source: string): unknown {
+  return JSON.parse(source)
+}
+
+export function invalidAggregateResolutionArguments(
+  kind: 'tool-approval' | 'generic' | 'client-tool-execution',
+): Array<unknown> {
+  return kind === 'tool-approval'
+    ? [true, { editedArgs: {}, payload: {} }]
+    : [{}]
+}
+
+export function createIncompleteBulkResolver(): (interrupt: {
+  id: string
+}) => undefined {
+  return () => undefined
+}
+
+export function interruptProgressLabel(
+  total: number,
+  staged: number,
+  resuming: boolean,
+): string {
+  if (resuming) return `Submitting ${total} interrupt decisions…`
+  const remaining = total - staged
+  if (remaining === 1 && total > 1) {
+    return `${staged} of ${total} staged · the final decision auto-submits the batch`
+  }
+  return `${staged} of ${total} staged · ${remaining} remaining`
+}
+
+export function isNormalSendDisabled(
+  message: string,
+  isLoading: boolean,
+  resuming: boolean,
+  interruptCount: number,
+): boolean {
+  return message.trim() === '' || isLoading || resuming || interruptCount > 0
+}
+
+export function shouldShowOpenAiApiKeyGuidance(error: ChatErrorLike): boolean {
+  return (
+    error.code === 'openai-api-key-required' ||
+    error.message.includes('OPENAI_API_KEY')
+  )
+}
+
+export function visibleDurableControls(
+  mode: InterruptLabMode,
+): ReadonlyArray<DurableControl> {
+  return mode === 'durable'
+    ? [
+        'saved-drafts',
+        'reload-recovery',
+        'retry-join-replay',
+        'cas-conflict',
+        'expiry',
+      ]
+    : []
+}
+
+export function describeInterruptErrors(
+  itemErrors: ReadonlyArray<InterruptErrorLike>,
+  batchErrors: ReadonlyArray<InterruptErrorLike>,
+): Array<string> {
+  return [
+    ...itemErrors.map((error) => `Item · ${error.code} · ${error.message}`),
+    ...batchErrors.map((error) => `Batch · ${error.code} · ${error.message}`),
+  ]
+}
+
+export function createDurableDraftEnvelope({
+  mode,
+  threadId,
+  interruptedRunId,
+  drafts,
+}: {
+  mode: InterruptLabMode
+  threadId: string
+  interruptedRunId: string
+  drafts: Record<string, InterruptEditorDraft>
+}): DurableDraftEnvelope | undefined {
+  if (mode !== 'durable') return undefined
+  return {
+    schemaVersion: 1,
+    mode,
+    threadId,
+    interruptedRunId,
+    drafts,
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isInterruptEditorDraft(value: unknown): value is InterruptEditorDraft {
+  return (
+    isRecord(value) &&
+    typeof value.editedArgs === 'string' &&
+    typeof value.includeEditedArgs === 'boolean' &&
+    typeof value.approvePayload === 'string' &&
+    typeof value.rejectPayload === 'string' &&
+    typeof value.output === 'string'
+  )
+}
+
+export function restoreDurableDrafts({
+  mode,
+  threadId,
+  interruptedRunId,
+  activeInterruptIds,
+  serialized,
+}: {
+  mode: InterruptLabMode
+  threadId: string
+  interruptedRunId: string
+  activeInterruptIds: ReadonlyArray<string>
+  serialized: string | null
+}): Record<string, InterruptEditorDraft> {
+  if (mode !== 'durable' || serialized === null) return {}
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(serialized)
+  } catch {
+    return {}
+  }
+  if (
+    !isRecord(parsed) ||
+    parsed.schemaVersion !== 1 ||
+    parsed.mode !== 'durable' ||
+    parsed.threadId !== threadId ||
+    parsed.interruptedRunId !== interruptedRunId ||
+    !isRecord(parsed.drafts)
+  ) {
+    return {}
+  }
+
+  const restored: Record<string, InterruptEditorDraft> = {}
+  for (const interruptId of activeInterruptIds) {
+    const draft = parsed.drafts[interruptId]
+    if (isInterruptEditorDraft(draft)) restored[interruptId] = draft
+  }
+  return restored
+}
+
+export function durableDraftStorageKey(
+  threadId: string,
+  interruptedRunId: string,
+): string {
+  return `tanstack-ai:interrupt-lab:drafts:durable:${threadId}:${interruptedRunId}`
+}
+
+export function durableOutcomeStatus(
+  itemErrors: ReadonlyArray<{
+    code: string
+    retryable: boolean
+    scope?: string
+  }>,
+  rootErrors: ReadonlyArray<{
+    code: string
+    retryable: boolean
+    scope?: string
+  }> = [],
+): { kind: DurableOutcomeKind; label: string; detail: string } {
+  const seen = new Set<string>()
+  const errors = [...itemErrors, ...rootErrors].filter((error) => {
+    const key = `${error.code}:${error.retryable}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+  if (errors.some((error) => error.code === 'expired')) {
+    return {
+      kind: 'expired',
+      label: 'Expired',
+      detail: 'The authoritative interrupt batch is no longer resolvable.',
+    }
+  }
+  if (errors.some((error) => error.code === 'conflict')) {
+    return {
+      kind: 'conflict',
+      label: 'CAS conflict',
+      detail: 'Another client committed a decision first.',
+    }
+  }
+  if (errors.some((error) => error.code === 'stale')) {
+    return {
+      kind: 'stale',
+      label: 'Stale generation',
+      detail: 'This client submitted an outdated interrupt generation.',
+    }
+  }
+  if (errors.some((error) => error.code === 'recovery-unavailable')) {
+    return {
+      kind: 'recovery-unavailable',
+      label: 'Recovery unavailable',
+      detail: 'The configured connection cannot load authoritative state.',
+    }
+  }
+  if (errors.some((error) => error.retryable)) {
+    return {
+      kind: 'retryable',
+      label: 'Retry available',
+      detail: 'retryInterrupts() can replay the captured submission.',
+    }
+  }
+  return {
+    kind: 'protected',
+    label: 'Atomic state protected',
+    detail: 'No durable conflict, stale generation, or retryable failure.',
+  }
+}
+
+export function durableCapabilityStatuses(
+  mode: InterruptLabMode,
+  state: { retryable: boolean; hasExpiresAt: boolean },
+): ReadonlyArray<DurableCapabilityStatus> {
+  if (mode !== 'durable') return []
+  return [
+    {
+      id: 'saved-drafts',
+      availability: 'available',
+      detail: 'Editor drafts and the public resume snapshot survive reload.',
+    },
+    {
+      id: 'cas-conflict',
+      availability: 'available',
+      detail: 'Open the same case in two tabs to exercise first-writer CAS.',
+    },
+    {
+      id: 'retry',
+      availability: state.retryable ? 'available' : 'observable-only',
+      detail: state.retryable
+        ? 'A captured failed submission can be replayed with retryInterrupts().'
+        : 'Arm the one-shot resume failure before resolving a batch.',
+    },
+    {
+      id: 'join-replay',
+      availability: 'unavailable',
+      detail:
+        'The current lab endpoint is POST-only and exposes no GET join loader.',
+    },
+    {
+      id: 'expiry',
+      availability: 'observable-only',
+      detail: state.hasExpiresAt
+        ? 'The server advertised expiresAt; this UI only observes it.'
+        : 'The lab store exposes no public TTL configuration for a trigger.',
+    },
+  ]
+}
diff --git a/examples/ts-react-chat/src/lib/interrupt-lab/persistence.ts b/examples/ts-react-chat/src/lib/interrupt-lab/persistence.ts
new file mode 100644
index 000000000..76f8f839e
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/interrupt-lab/persistence.ts
@@ -0,0 +1,63 @@
+import { composePersistence } from '@tanstack/ai-persistence'
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+
+type InterruptLabPersistence = ReturnType<
+  typeof createInterruptLabPersistenceBackend
+>
+
+let persistence: InterruptLabPersistence | undefined
+
+function createInterruptLabPersistenceBackend(url: string) {
+  const sqlite = sqlitePersistence({
+    url,
+    migrate: true,
+  })
+  const composed = composePersistence(sqlite, {
+    overrides: {
+      metadata: false,
+      locks: false,
+      artifacts: false,
+      blobs: false,
+    },
+  })
+  return {
+    ...composed,
+    close: () => sqlite.close(),
+  }
+}
+
+function cacheInterruptLabPersistence(
+  instance: InterruptLabPersistence,
+): InterruptLabPersistence {
+  let closed = false
+  const cached: InterruptLabPersistence = {
+    ...instance,
+    close() {
+      if (closed) return
+      closed = true
+      try {
+        instance.close()
+      } finally {
+        if (persistence === cached) {
+          persistence = undefined
+        }
+      }
+    },
+  }
+  return cached
+}
+
+/** Dedicated durable-state namespace for the interrupt manual lab. */
+export function createInterruptLabPersistence(options?: {
+  url?: string
+}): InterruptLabPersistence {
+  if (options?.url !== undefined) {
+    return createInterruptLabPersistenceBackend(options.url)
+  }
+  persistence ??= cacheInterruptLabPersistence(
+    createInterruptLabPersistenceBackend(
+      process.env.INTERRUPT_LAB_DB_URL ?? 'file:./interrupt-lab-persistence.db',
+    ),
+  )
+  return persistence
+}
diff --git a/examples/ts-react-chat/src/lib/interrupt-lab/production-composition.test.ts b/examples/ts-react-chat/src/lib/interrupt-lab/production-composition.test.ts
new file mode 100644
index 000000000..54f2ef2f6
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/interrupt-lab/production-composition.test.ts
@@ -0,0 +1,276 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { canonicalInterruptJson, digestInterruptJson } from '@tanstack/ai'
+import { createInterruptLabPersistence } from './persistence'
+import type * as DurableRouteModule from '../../routes/api.durable-interrupts'
+import type * as EphemeralRouteModule from '../../routes/api.interrupts'
+
+const temporaryDirectories: Array<string> = []
+let previousDatabaseUrl: string | undefined
+let durableRoute: typeof DurableRouteModule
+let ephemeralRoute: typeof EphemeralRouteModule
+
+beforeAll(async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'tanstack-interrupt-route-'))
+  temporaryDirectories.push(directory)
+  previousDatabaseUrl = process.env.INTERRUPT_LAB_DB_URL
+  process.env.INTERRUPT_LAB_DB_URL = `file:${join(directory, 'production.sqlite')}`
+  ;[ephemeralRoute, durableRoute] = await Promise.all([
+    import('../../routes/api.interrupts'),
+    import('../../routes/api.durable-interrupts'),
+  ])
+})
+
+afterAll(async () => {
+  durableRoute.durableInterruptLabPersistence.close()
+  if (previousDatabaseUrl === undefined) {
+    delete process.env.INTERRUPT_LAB_DB_URL
+  } else {
+    process.env.INTERRUPT_LAB_DB_URL = previousDatabaseUrl
+  }
+  for (const directory of temporaryDirectories.splice(0)) {
+    await rm(directory, { recursive: true, force: true })
+  }
+})
+
+describe('interrupt lab production route composition', () => {
+  it('keeps the ephemeral endpoint entirely persistence-free', () => {
+    expect(ephemeralRoute.interruptLabRouteConfig).toEqual({
+      mode: 'ephemeral',
+    })
+    expect(
+      'persistenceMiddleware' in ephemeralRoute.interruptLabRouteConfig,
+    ).toBe(false)
+  })
+
+  it('wires the durable endpoint to the dedicated real SQLite composition', () => {
+    expect(durableRoute.durableInterruptLabRouteConfig).toMatchObject({
+      mode: 'durable',
+    })
+    expect(
+      durableRoute.durableInterruptLabRouteConfig.persistenceMiddleware,
+    ).toBe(durableRoute.durableInterruptLabMiddleware)
+    expect(
+      durableRoute.durableInterruptLabPersistence.stores.interrupts,
+    ).toBeDefined()
+    expect(
+      durableRoute.durableInterruptLabPersistence.stores.runs,
+    ).toBeDefined()
+    expect(
+      durableRoute.durableInterruptLabPersistence.stores.messages,
+    ).toBeDefined()
+  })
+
+  it('opens an atomic interrupt batch in an isolated SQLite database', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'tanstack-interrupt-lab-'))
+    temporaryDirectories.push(directory)
+    const databasePath = join(directory, 'interrupts.sqlite')
+    const persistence = createInterruptLabPersistence({
+      url: `file:${databasePath}`,
+    })
+
+    try {
+      const opened = await persistence.stores.interrupts.openInterruptBatch({
+        threadId: 'durable-lab:thread-1',
+        interruptedRunId: 'run-1',
+        descriptors: [
+          {
+            id: 'generic-1',
+            reason: 'interrupt_lab:generic_question',
+            responseSchema: { type: 'object' },
+          },
+        ],
+        bindings: [
+          {
+            kind: 'generic',
+            interruptId: 'generic-1',
+            responseSchemaHash: 'sha256:test',
+          },
+        ],
+      })
+
+      expect(opened).toMatchObject({
+        generation: 1,
+        descriptors: [{ id: 'generic-1' }],
+      })
+    } finally {
+      persistence.close()
+    }
+  })
+
+  it('returns authoritative interrupt recovery state from the durable route', async () => {
+    const threadId = 'durable-lab:recovery-thread'
+    const interruptedRunId = 'recovery-run'
+    await durableRoute.durableInterruptLabPersistence.stores.interrupts.openInterruptBatch(
+      {
+        threadId,
+        interruptedRunId,
+        descriptors: [
+          {
+            id: 'recovery-interrupt',
+            reason: 'interrupt_lab:recovery',
+            responseSchema: { type: 'boolean' },
+          },
+        ],
+        bindings: [
+          {
+            kind: 'generic',
+            interruptId: 'recovery-interrupt',
+            responseSchemaHash: 'sha256:recovery-test',
+          },
+        ],
+      },
+    )
+
+    const response = await durableRoute.durableInterruptLabRequest(
+      new Request(
+        `http://localhost/api/durable-interrupts?threadId=${threadId}&interruptedRunId=${interruptedRunId}&knownGeneration=1`,
+        { method: 'POST' },
+      ),
+    )
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toMatchObject({
+      schemaVersion: 1,
+      state: 'pending',
+      threadId,
+      interruptedRunId,
+      generation: 1,
+      pendingInterrupts: [
+        {
+          id: 'recovery-interrupt',
+          metadata: {
+            'tanstack:interruptBinding': {
+              kind: 'generic',
+              interruptId: 'recovery-interrupt',
+              interruptedRunId,
+              generation: 1,
+              responseSchemaHash: 'sha256:recovery-test',
+            },
+          },
+        },
+      ],
+    })
+  })
+
+  it('redacts committed interrupt resolutions from the durable recovery route', async () => {
+    const threadId = 'durable-lab:committed-recovery-thread'
+    const interruptedRunId = 'committed-recovery-run'
+    const continuationRunId = 'committed-continuation-run'
+    const interruptId = 'committed-recovery-interrupt'
+    const resolutions = [
+      {
+        interruptId,
+        status: 'resolved' as const,
+        payload: { secret: 'must-not-leave-the-server' },
+      },
+    ]
+    const canonicalResolutions = canonicalInterruptJson(resolutions)
+    const fingerprint = digestInterruptJson(canonicalResolutions)
+    await durableRoute.durableInterruptLabPersistence.stores.interrupts.openInterruptBatch(
+      {
+        threadId,
+        interruptedRunId,
+        descriptors: [
+          {
+            id: interruptId,
+            reason: 'interrupt_lab:committed-recovery',
+            responseSchema: { type: 'object' },
+          },
+        ],
+        bindings: [
+          {
+            kind: 'generic',
+            interruptId,
+            responseSchemaHash: 'sha256:committed-recovery-test',
+          },
+        ],
+      },
+    )
+    await durableRoute.durableInterruptLabPersistence.stores.interrupts.commitInterruptResolutions(
+      {
+        threadId,
+        interruptedRunId,
+        continuationRunId,
+        expectedGeneration: 1,
+        expectedInterruptIds: [interruptId],
+        resolutions,
+        canonicalResolutions,
+        fingerprint,
+      },
+    )
+
+    const response = await durableRoute.durableInterruptLabRequest(
+      new Request(
+        `http://localhost/api/durable-interrupts?threadId=${threadId}&interruptedRunId=${interruptedRunId}&knownGeneration=1`,
+        { method: 'POST' },
+      ),
+    )
+    const state = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(state).toMatchObject({
+      schemaVersion: 1,
+      state: 'committed',
+      threadId,
+      interruptedRunId,
+      generation: 1,
+      committed: {
+        fingerprint,
+        continuationRunId,
+      },
+    })
+    expect(state.committed).not.toHaveProperty('resolutions')
+    expect(JSON.stringify(state)).not.toContain('must-not-leave-the-server')
+  })
+
+  it.each([
+    '?threadId=thread-1&interruptedRunId=run-1',
+    '?threadId=thread-1&knownGeneration=1',
+    '?interruptedRunId=run-1&knownGeneration=1',
+    '?threadId=thread-1&interruptedRunId=run-1&knownGeneration=-1',
+  ])('rejects an invalid durable recovery query %s', async (search) => {
+    const response = await durableRoute.durableInterruptLabRequest(
+      new Request(`http://localhost/api/durable-interrupts${search}`, {
+        method: 'POST',
+      }),
+    )
+
+    expect(response.status).toBe(400)
+    await expect(response.json()).resolves.toEqual({
+      error: 'Invalid interrupt recovery query.',
+    })
+  })
+
+  it('returns a missing durable recovery state for unknown correlation', async () => {
+    const response = await durableRoute.durableInterruptLabRequest(
+      new Request(
+        'http://localhost/api/durable-interrupts?threadId=missing-thread&interruptedRunId=missing-run&knownGeneration=3',
+        { method: 'POST' },
+      ),
+    )
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toMatchObject({
+      schemaVersion: 1,
+      state: 'missing',
+      threadId: 'missing-thread',
+      interruptedRunId: 'missing-run',
+      generation: 3,
+      pendingInterrupts: [],
+    })
+  })
+
+  it('recreates the cached SQLite persistence after the singleton is closed', () => {
+    const first = durableRoute.durableInterruptLabPersistence
+
+    first.close()
+    const recreated = createInterruptLabPersistence()
+
+    expect(recreated).not.toBe(first)
+    expect(recreated.stores.interrupts).toBeDefined()
+    recreated.close()
+  })
+})
diff --git a/examples/ts-react-chat/src/lib/interrupt-lab/scenarios.ts b/examples/ts-react-chat/src/lib/interrupt-lab/scenarios.ts
new file mode 100644
index 000000000..ee5865c13
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/interrupt-lab/scenarios.ts
@@ -0,0 +1,278 @@
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+import type { AnyTool } from '@tanstack/ai'
+
+export const interruptLabModes = ['ephemeral', 'durable'] as const
+export type InterruptLabMode = (typeof interruptLabModes)[number]
+
+const successSchema = z.object({ ok: z.boolean(), message: z.string() })
+
+export const approvalBasicTool = toolDefinition({
+  name: 'interrupt_lab_approval_basic',
+  description: 'Perform one basic server action after the user approves it.',
+  inputSchema: z.object({ action: z.string() }),
+  outputSchema: successSchema,
+  needsApproval: true,
+})
+
+export const approvalEditArgsTool = toolDefinition({
+  name: 'interrupt_lab_edit_order',
+  description:
+    'Submit an order whose destination and quantity may be fully replaced during approval.',
+  inputSchema: z.object({
+    destination: z.string().min(1),
+    quantity: z.number().int().positive(),
+  }),
+  outputSchema: successSchema,
+  needsApproval: true,
+})
+
+export const approvalSharedPayloadTool = toolDefinition({
+  name: 'interrupt_lab_shared_payload',
+  description:
+    'Perform an action that requires a review note for either decision.',
+  inputSchema: z.object({ action: z.string() }),
+  outputSchema: successSchema,
+  needsApproval: true,
+  approvalSchema: z.object({ note: z.string().min(1) }),
+})
+
+export const approvalBranchPayloadTool = toolDefinition({
+  name: 'interrupt_lab_branch_payload',
+  description:
+    'Perform an action with different payloads for approval and rejection.',
+  inputSchema: z.object({ action: z.string() }),
+  outputSchema: successSchema,
+  needsApproval: true,
+  approvalSchema: {
+    approve: z.object({ note: z.string().min(1) }),
+    reject: z.object({ reason: z.string().min(1) }),
+  },
+})
+
+export const clientOutputTool = toolDefinition({
+  name: 'interrupt_lab_client_output',
+  description: 'Read a value in the browser and return it to the agent.',
+  inputSchema: z.object({ key: z.string() }),
+  outputSchema: z.object({ browserValue: z.string().min(1) }),
+})
+
+export const approvalClientTool = toolDefinition({
+  name: 'interrupt_lab_approval_client',
+  description:
+    'Ask for approval, then run in the browser and return a typed result.',
+  inputSchema: z.object({ operation: z.string() }),
+  outputSchema: z.object({ browserValue: z.string().min(1) }),
+  needsApproval: true,
+  approvalSchema: z.object({ note: z.string().min(1) }),
+})
+
+export const batchSecondTool = toolDefinition({
+  name: 'interrupt_lab_batch_second',
+  description: 'Perform the second independently approved batch action.',
+  inputSchema: z.object({ action: z.string() }),
+  outputSchema: successSchema,
+  needsApproval: true,
+})
+
+export const batchThirdTool = toolDefinition({
+  name: 'interrupt_lab_batch_third',
+  description: 'Perform the third independently approved batch action.',
+  inputSchema: z.object({ action: z.string() }),
+  outputSchema: successSchema,
+  needsApproval: true,
+})
+
+function serverResult(label: string) {
+  return Promise.resolve({ ok: true, message: `${label} completed` })
+}
+
+const serverTools = {
+  approvalBasic: approvalBasicTool.server(() => serverResult('basic action')),
+  approvalEditArgs: approvalEditArgsTool.server(() =>
+    serverResult('edited order'),
+  ),
+  approvalSharedPayload: approvalSharedPayloadTool.server(() =>
+    serverResult('shared-payload action'),
+  ),
+  approvalBranchPayload: approvalBranchPayloadTool.server(() =>
+    serverResult('branch-payload action'),
+  ),
+  batchSecond: batchSecondTool.server(() => serverResult('second action')),
+  batchThird: batchThirdTool.server(() => serverResult('third action')),
+} as const
+
+export type InterruptLabScenarioCategory =
+  | 'approval'
+  | 'client-tool'
+  | 'generic'
+  | 'batching'
+  | 'validation'
+
+export interface InterruptLabScenario {
+  id: string
+  label: string
+  description: string
+  prompt: string
+  category: InterruptLabScenarioCategory
+  modes: ReadonlyArray<InterruptLabMode>
+  systemPrompt: string
+  tools: ReadonlyArray<AnyTool>
+  genericResponseSchema?: {
+    $schema: string
+    type: 'object'
+    properties: { answer: { type: 'string'; minLength: number } }
+    required: Array<'answer'>
+    additionalProperties: false
+  }
+}
+
+const bothModes = interruptLabModes
+
+export const interruptLabScenarios = {
+  'approval-basic': {
+    id: 'approval-basic',
+    label: 'Basic approval',
+    description: 'Approve, reject, or cancel one server tool call.',
+    prompt:
+      'Call interrupt_lab_approval_basic exactly once with action "publish the draft". Do not answer with text.',
+    category: 'approval',
+    modes: bothModes,
+    systemPrompt:
+      'Call interrupt_lab_approval_basic exactly once. Supply action "publish the draft" and do not call any other tool.',
+    tools: [serverTools.approvalBasic],
+  },
+  'approval-edit-args': {
+    id: 'approval-edit-args',
+    label: 'Editable arguments',
+    description: 'Approve a full replacement of the original tool arguments.',
+    prompt:
+      'Call interrupt_lab_edit_order with destination "Original address" and quantity 1. Do not answer with text.',
+    category: 'approval',
+    modes: bothModes,
+    systemPrompt:
+      'Call interrupt_lab_edit_order exactly once with destination "Original address" and quantity 1.',
+    tools: [serverTools.approvalEditArgs],
+  },
+  'approval-shared-payload': {
+    id: 'approval-shared-payload',
+    label: 'Shared decision payload',
+    description: 'Use one approval payload schema for approve and reject.',
+    prompt:
+      'Call interrupt_lab_shared_payload exactly once with action "deploy preview". Do not answer with text.',
+    category: 'approval',
+    modes: bothModes,
+    systemPrompt:
+      'Call interrupt_lab_shared_payload exactly once with action "deploy preview".',
+    tools: [serverTools.approvalSharedPayload],
+  },
+  'approval-branch-payload': {
+    id: 'approval-branch-payload',
+    label: 'Branch decision payloads',
+    description: 'Use different payload schemas for approval and rejection.',
+    prompt:
+      'Call interrupt_lab_branch_payload exactly once with action "release package". Do not answer with text.',
+    category: 'approval',
+    modes: bothModes,
+    systemPrompt:
+      'Call interrupt_lab_branch_payload exactly once with action "release package".',
+    tools: [serverTools.approvalBranchPayload],
+  },
+  'client-output': {
+    id: 'client-output',
+    label: 'Client tool output',
+    description: 'Run a client-only tool and submit its typed output.',
+    prompt:
+      'Call interrupt_lab_client_output exactly once with key "manual-lab". Do not answer with text.',
+    category: 'client-tool',
+    modes: bothModes,
+    systemPrompt:
+      'Call interrupt_lab_client_output exactly once with key "manual-lab".',
+    tools: [clientOutputTool],
+  },
+  'client-approval': {
+    id: 'client-approval',
+    label: 'Approved client tool',
+    description: 'Approve first, then execute the typed client tool.',
+    prompt:
+      'Call interrupt_lab_approval_client exactly once with operation "read browser setting". Do not answer with text.',
+    category: 'client-tool',
+    modes: bothModes,
+    systemPrompt:
+      'Call interrupt_lab_approval_client exactly once with operation "read browser setting".',
+    tools: [approvalClientTool],
+  },
+  'generic-response-schema': {
+    id: 'generic-response-schema',
+    label: 'External-style generic boundary',
+    description:
+      'After the real model finishes, the lab boundary appends a controlled non-tool AG-UI interrupt with a JSON Schema payload.',
+    prompt:
+      'Reply with one short sentence acknowledging that the generic interrupt lab is ready.',
+    category: 'generic',
+    modes: bothModes,
+    systemPrompt:
+      'Reply with one short sentence. The route will follow the real model run with a generic AG-UI interrupt.',
+    tools: [],
+    genericResponseSchema: {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      properties: { answer: { type: 'string', minLength: 2 } },
+      required: ['answer'],
+      additionalProperties: false,
+    },
+  },
+  'batch-three': {
+    id: 'batch-three',
+    label: 'Three approvals',
+    description:
+      'Resolve three simultaneous approvals before one continuation.',
+    prompt:
+      'In one response call interrupt_lab_approval_basic, interrupt_lab_batch_second, and interrupt_lab_batch_third. Do not answer with text.',
+    category: 'batching',
+    modes: bothModes,
+    systemPrompt:
+      'In the same response call all three available tools exactly once. Do not wait between calls and do not answer with text.',
+    tools: [
+      serverTools.approvalBasic,
+      serverTools.batchSecond,
+      serverTools.batchThird,
+    ],
+  },
+  'batch-mixed': {
+    id: 'batch-mixed',
+    label: 'Mixed server and client batch',
+    description: 'Resolve approval and client execution items in one batch.',
+    prompt:
+      'In one response call interrupt_lab_approval_basic and interrupt_lab_client_output. Do not answer with text.',
+    category: 'batching',
+    modes: bothModes,
+    systemPrompt:
+      'In the same response call both available tools exactly once. Do not wait between calls and do not answer with text.',
+    tools: [serverTools.approvalBasic, clientOutputTool],
+  },
+  'invalid-aggregate-errors': {
+    id: 'invalid-aggregate-errors',
+    label: 'Aggregate validation errors',
+    description:
+      'Submit multiple invalid staged responses and inspect all errors.',
+    prompt:
+      'In one response call interrupt_lab_edit_order and interrupt_lab_branch_payload. Do not answer with text.',
+    category: 'validation',
+    modes: bothModes,
+    systemPrompt:
+      'In the same response call both available tools exactly once. Use destination "Original address", quantity 1, and action "release package".',
+    tools: [serverTools.approvalEditArgs, serverTools.approvalBranchPayload],
+  },
+} as const satisfies Record<string, InterruptLabScenario>
+
+export type InterruptLabScenarioId = keyof typeof interruptLabScenarios
+
+export function isInterruptLabScenarioId(
+  value: unknown,
+): value is InterruptLabScenarioId {
+  return (
+    typeof value === 'string' &&
+    Object.prototype.hasOwnProperty.call(interruptLabScenarios, value)
+  )
+}
diff --git a/examples/ts-react-chat/src/lib/interrupt-lab/server.test.ts b/examples/ts-react-chat/src/lib/interrupt-lab/server.test.ts
new file mode 100644
index 000000000..e219dd2bd
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/interrupt-lab/server.test.ts
@@ -0,0 +1,765 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { EventType, toServerSentEventsResponse } from '@tanstack/ai'
+import {
+  createGenericInterruptMiddleware,
+  createInterruptLabPost,
+} from './server'
+import {
+  approvalBasicTool,
+  approvalBranchPayloadTool,
+  approvalClientTool,
+  approvalEditArgsTool,
+  approvalSharedPayloadTool,
+  clientOutputTool,
+  interruptLabScenarios,
+  isInterruptLabScenarioId,
+} from './scenarios'
+import type {
+  AnyTextAdapter,
+  ChatMiddleware,
+  ChatMiddlewareContext,
+  StreamChunk,
+} from '@tanstack/ai'
+import type {
+  InterruptLabChatOptions,
+  InterruptLabRouteDependencies,
+} from './server'
+
+const stream: AsyncIterable<StreamChunk> = {
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => Promise.resolve({ done: true, value: undefined }),
+    }
+  },
+}
+
+const adapter = { name: 'mock-openai' } as AnyTextAdapter
+
+function request(
+  scenarioId: keyof typeof interruptLabScenarios,
+  overrides: Record<string, unknown> = {},
+): Request {
+  return new Request('http://localhost/api/interrupts', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      threadId: 'thread-1',
+      runId: 'run-2',
+      parentRunId: 'run-1',
+      state: { cart: 'open' },
+      messages: [{ id: 'm1', role: 'user', content: 'run the scenario' }],
+      tools: [],
+      context: [],
+      forwardedProps: { interruptScenario: scenarioId },
+      resume: [
+        {
+          interruptId: 'interrupt-1',
+          status: 'resolved',
+          payload: { approved: true },
+        },
+      ],
+      ...overrides,
+    }),
+  })
+}
+
+function dependencies() {
+  const runChat = vi.fn((_options: InterruptLabChatOptions) => stream)
+  const toResponse = vi.fn(
+    (_stream: AsyncIterable<StreamChunk>) => new Response('stream'),
+  )
+  const createAdapter = vi.fn(() => adapter)
+  return {
+    runChat,
+    toResponse,
+    createAdapter,
+    readApiKey: (): string | undefined => 'test-key',
+  } satisfies InterruptLabRouteDependencies
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('interrupt lab scenario registry', () => {
+  it('provides stable metadata for every approved manual-lab capability', () => {
+    expect(Object.keys(interruptLabScenarios)).toEqual([
+      'approval-basic',
+      'approval-edit-args',
+      'approval-shared-payload',
+      'approval-branch-payload',
+      'client-output',
+      'client-approval',
+      'generic-response-schema',
+      'batch-three',
+      'batch-mixed',
+      'invalid-aggregate-errors',
+    ])
+
+    for (const [id, scenario] of Object.entries(interruptLabScenarios)) {
+      expect(scenario.id).toBe(id)
+      expect(scenario.label.length).toBeGreaterThan(0)
+      expect(scenario.prompt.length).toBeGreaterThan(20)
+      expect(scenario.category.length).toBeGreaterThan(0)
+      expect(scenario.modes.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('encodes approval, edit, payload, and client-tool capabilities', () => {
+    expect(approvalBasicTool.needsApproval).toBe(true)
+
+    expect(
+      approvalEditArgsTool.inputSchema.safeParse({
+        destination: 'Updated address',
+        quantity: 2,
+      }).success,
+    ).toBe(true)
+    expect(
+      approvalEditArgsTool.inputSchema.safeParse({
+        destination: 'Missing quantity',
+      }).success,
+    ).toBe(false)
+    expect(approvalEditArgsTool.needsApproval).toBe(true)
+
+    expect(
+      approvalSharedPayloadTool.approvalSchema.safeParse({ note: 'Reviewed' })
+        .success,
+    ).toBe(true)
+    expect(approvalSharedPayloadTool.approvalSchema.safeParse({}).success).toBe(
+      false,
+    )
+
+    expect(
+      approvalBranchPayloadTool.approvalSchema.approve.safeParse({
+        note: 'Approved after review',
+      }).success,
+    ).toBe(true)
+    expect(
+      approvalBranchPayloadTool.approvalSchema.reject.safeParse({
+        reason: 'Unsafe operation',
+      }).success,
+    ).toBe(true)
+    expect(
+      approvalBranchPayloadTool.approvalSchema.reject.safeParse({
+        note: 'Wrong branch payload',
+      }).success,
+    ).toBe(false)
+
+    expect(clientOutputTool.needsApproval).not.toBe(true)
+    expect(clientOutputTool.execute).toBeUndefined()
+    expect(approvalClientTool.needsApproval).toBe(true)
+    expect(approvalClientTool.execute).toBeUndefined()
+  })
+
+  it('composes the required exact approval, mixed, and invalid batches', () => {
+    expect(
+      interruptLabScenarios['batch-three'].tools.map((tool) => ({
+        name: tool.name,
+        needsApproval: tool.needsApproval,
+        clientOnly: tool.execute === undefined,
+      })),
+    ).toEqual([
+      {
+        name: 'interrupt_lab_approval_basic',
+        needsApproval: true,
+        clientOnly: false,
+      },
+      {
+        name: 'interrupt_lab_batch_second',
+        needsApproval: true,
+        clientOnly: false,
+      },
+      {
+        name: 'interrupt_lab_batch_third',
+        needsApproval: true,
+        clientOnly: false,
+      },
+    ])
+    expect(
+      interruptLabScenarios['batch-mixed'].tools.map((tool) => ({
+        name: tool.name,
+        needsApproval: tool.needsApproval === true,
+        clientOnly: tool.execute === undefined,
+      })),
+    ).toEqual([
+      {
+        name: 'interrupt_lab_approval_basic',
+        needsApproval: true,
+        clientOnly: false,
+      },
+      {
+        name: 'interrupt_lab_client_output',
+        needsApproval: false,
+        clientOnly: true,
+      },
+    ])
+    expect(
+      interruptLabScenarios['invalid-aggregate-errors'].tools.map(
+        (tool) => tool.name,
+      ),
+    ).toEqual(['interrupt_lab_edit_order', 'interrupt_lab_branch_payload'])
+  })
+
+  it('rejects prototype keys as scenario IDs', () => {
+    expect(isInterruptLabScenarioId('constructor')).toBe(false)
+    expect(isInterruptLabScenarioId('toString')).toBe(false)
+  })
+})
+
+describe('interrupt lab API request correlation', () => {
+  it('forwards all AG-UI correlation fields without persistence in ephemeral mode', async () => {
+    const deps = dependencies()
+    const post = createInterruptLabPost({
+      mode: 'ephemeral',
+      dependencies: deps,
+    })
+
+    const response = await post(request('approval-basic'))
+
+    expect(response.status).toBe(200)
+    expect(deps.createAdapter).toHaveBeenCalledWith('gpt-5.5', 'test-key')
+    expect(deps.runChat).toHaveBeenCalledOnce()
+    expect(deps.runChat.mock.calls[0]?.[0]).toMatchObject({
+      adapter,
+      debug: false,
+      threadId: 'thread-1',
+      runId: 'run-2',
+      parentRunId: 'run-1',
+      state: { cart: 'open' },
+      messages: [{ id: 'm1', role: 'user', content: 'run the scenario' }],
+      resume: [
+        {
+          interruptId: 'interrupt-1',
+          status: 'resolved',
+          payload: { approved: true },
+        },
+      ],
+    })
+    expect(
+      deps.runChat.mock.calls[0]?.[0].middleware?.map(
+        (middleware) => middleware.name,
+      ),
+    ).toEqual(['interrupt-lab-error-sanitizer'])
+    expect(deps.toResponse).toHaveBeenCalledOnce()
+  })
+
+  it('enables the chat debug pipeline only for an explicit lab request flag', async () => {
+    const deps = dependencies()
+    const post = createInterruptLabPost({
+      mode: 'ephemeral',
+      dependencies: deps,
+    })
+
+    await post(
+      request('approval-basic', {
+        forwardedProps: {
+          interruptScenario: 'approval-basic',
+          interruptLabDebug: true,
+        },
+      }),
+    )
+
+    expect(deps.runChat.mock.calls[0]?.[0].debug).toBe(true)
+  })
+
+  it.each([false, 'true', 1] as const)(
+    'keeps the chat debug pipeline disabled for non-true forwarded value %s',
+    async (interruptLabDebug) => {
+      const deps = dependencies()
+      const post = createInterruptLabPost({
+        mode: 'ephemeral',
+        dependencies: deps,
+      })
+
+      await post(
+        request('approval-basic', {
+          forwardedProps: {
+            interruptScenario: 'approval-basic',
+            interruptLabDebug,
+          },
+        }),
+      )
+
+      expect(deps.runChat.mock.calls[0]?.[0].debug).toBe(false)
+    },
+  )
+
+  it('uses only the scenario registry tool definitions and ignores client-declared schemas', async () => {
+    const deps = dependencies()
+    const post = createInterruptLabPost({
+      mode: 'ephemeral',
+      dependencies: deps,
+    })
+
+    await post(
+      request('client-output', {
+        tools: [
+          {
+            name: 'interrupt_lab_client_output',
+            description: 'Untrusted replacement description',
+            parameters: {
+              type: 'object',
+              properties: { injected: { type: 'string' } },
+            },
+          },
+          {
+            name: 'interrupt_lab_unregistered',
+            description: 'Unregistered client tool',
+            parameters: { type: 'object', properties: {} },
+          },
+        ],
+      }),
+    )
+
+    const finalTools = deps.runChat.mock.calls[0]?.[0].tools
+    expect(finalTools).toEqual(interruptLabScenarios['client-output'].tools)
+    expect(finalTools).toEqual([clientOutputTool])
+  })
+
+  it('places the error sanitizer before persistence in durable mode', async () => {
+    const deps = dependencies()
+    const persistenceMiddleware = { name: 'interrupt-lab-persistence' }
+    const post = createInterruptLabPost({
+      mode: 'durable',
+      persistenceMiddleware,
+      dependencies: deps,
+    })
+
+    await post(request('batch-three'))
+
+    expect(deps.runChat.mock.calls[0]?.[0].middleware).toEqual([
+      expect.objectContaining({ name: 'interrupt-lab-error-sanitizer' }),
+      persistenceMiddleware,
+    ])
+  })
+
+  it('can fail one durable continuation once so retryInterrupts is testable', async () => {
+    const deps = dependencies()
+    const post = createInterruptLabPost({
+      mode: 'durable',
+      persistenceMiddleware: { name: 'interrupt-lab-persistence' },
+      dependencies: deps,
+    })
+    const retryableRequest = () =>
+      request('approval-basic', {
+        forwardedProps: {
+          interruptScenario: 'approval-basic',
+          interruptLabFailResumeOnce: true,
+        },
+      })
+
+    const failed = await post(retryableRequest())
+    expect(failed.status).toBe(503)
+    expect(await failed.json()).toEqual({
+      error: 'Deliberate interrupt lab resume failure. Retry is safe.',
+      retryable: true,
+    })
+    expect(deps.runChat).not.toHaveBeenCalled()
+
+    const retried = await post(retryableRequest())
+    expect(retried.status).toBe(200)
+    expect(deps.runChat).toHaveBeenCalledOnce()
+  })
+
+  it('places the generic boundary before durable persistence', async () => {
+    const deps = dependencies()
+    const persistenceMiddleware = { name: 'interrupt-lab-persistence' }
+    const post = createInterruptLabPost({
+      mode: 'durable',
+      persistenceMiddleware,
+      dependencies: deps,
+    })
+
+    await post(request('generic-response-schema', { resume: undefined }))
+
+    expect(
+      deps.runChat.mock.calls[0]?.[0].middleware?.map(
+        (middleware) => middleware.name,
+      ),
+    ).toEqual([
+      'interrupt-lab-error-sanitizer',
+      'interrupt-lab-generic-boundary',
+      'interrupt-lab-persistence',
+    ])
+  })
+
+  it('requires a real OpenAI key before constructing or invoking the model', async () => {
+    const deps = dependencies()
+    deps.readApiKey = () => undefined
+    const post = createInterruptLabPost({
+      mode: 'ephemeral',
+      dependencies: deps,
+    })
+
+    const response = await post(request('approval-basic'))
+
+    expect(response.status).toBe(500)
+    expect(await response.text()).toMatch(/OPENAI_API_KEY/)
+    expect(deps.createAdapter).not.toHaveBeenCalled()
+    expect(deps.runChat).not.toHaveBeenCalled()
+  })
+
+  it('rejects unknown scenarios and mode-incompatible scenarios', async () => {
+    const deps = dependencies()
+    const post = createInterruptLabPost({
+      mode: 'ephemeral',
+      dependencies: deps,
+    })
+
+    const unknown = await post(
+      request('approval-basic', {
+        forwardedProps: { interruptScenario: 'not-a-scenario' },
+      }),
+    )
+
+    expect(unknown.status).toBe(400)
+    expect(deps.runChat).not.toHaveBeenCalled()
+
+    const constructorKey = await post(
+      request('approval-basic', {
+        forwardedProps: { interruptScenario: 'constructor' },
+      }),
+    )
+    const toStringKey = await post(
+      request('approval-basic', {
+        forwardedProps: { interruptScenario: 'toString' },
+      }),
+    )
+    expect(constructorKey.status).toBe(400)
+    expect(toStringKey.status).toBe(400)
+  })
+
+  it('sanitizes a RUN_ERROR yielded after the response is constructed', async () => {
+    const secret = 'sentinel-secret-provider-key'
+    const deps = dependencies()
+    deps.runChat.mockImplementation(() => ({
+      [Symbol.asyncIterator]: async function* () {
+        await Promise.resolve()
+        yield {
+          type: EventType.RUN_STARTED,
+          threadId: 'thread-1',
+          runId: 'run-2',
+          timestamp: 1,
+        }
+        yield {
+          type: EventType.RUN_ERROR,
+          threadId: 'thread-1',
+          runId: 'run-2',
+          timestamp: 2,
+          message: `Provider failed with api_key=${secret}`,
+          code: secret,
+          error: { message: secret, code: secret },
+          rawEvent: { providerSecret: secret },
+        }
+      },
+    }))
+    deps.toResponse.mockImplementation((outgoingStream) =>
+      toServerSentEventsResponse(outgoingStream),
+    )
+    const logError = vi.fn()
+    const post = createInterruptLabPost({
+      mode: 'ephemeral',
+      dependencies: { ...deps, logError },
+    })
+
+    const response = await post(request('approval-basic'))
+    expect(logError).not.toHaveBeenCalled()
+    const body = await response.text()
+
+    expect(response.status).toBe(200)
+    expect(body).toContain('"type":"RUN_STARTED"')
+    expect(body).toContain('"message":"Interrupt lab run failed."')
+    expect(body).toContain('"code":"interrupt-lab-run-failed"')
+    expect(body.match(/"type":"RUN_ERROR"/g)).toHaveLength(1)
+    expect(body).not.toContain(secret)
+    expect(logError).toHaveBeenCalledWith({
+      event: 'interrupt-lab-run-failed',
+      mode: 'ephemeral',
+      scenarioId: 'approval-basic',
+    })
+    expect(JSON.stringify(logError.mock.calls)).not.toContain(secret)
+  })
+
+  it('sanitizes late iterator failures before durable persistence and public SSE', async () => {
+    const secret = 'sentinel-secret-late-provider-failure'
+    const storedErrors: Array<string> = []
+    const persistenceMiddleware: ChatMiddleware = {
+      name: 'interrupt-lab-persistence',
+      onError(_ctx, info) {
+        storedErrors.push(
+          info.error instanceof Error
+            ? info.error.message
+            : JSON.stringify(info.error),
+        )
+      },
+    }
+    const deps = dependencies()
+    deps.runChat.mockImplementation((options) => ({
+      [Symbol.asyncIterator]: async function* () {
+        await Promise.resolve()
+        yield {
+          type: EventType.RUN_STARTED,
+          threadId: 'thread-1',
+          runId: 'run-2',
+          timestamp: 1,
+        }
+        const errorInfo = {
+          error: new Error(`Provider failed with api_key=${secret}`),
+          duration: 1,
+        }
+        for (const middleware of options.middleware ?? []) {
+          await middleware.onError?.(
+            {
+              runId: 'run-2',
+              threadId: 'thread-1',
+            } as ChatMiddlewareContext,
+            errorInfo,
+          )
+        }
+        throw new Error(`Provider failed with api_key=${secret}`)
+      },
+    }))
+    deps.toResponse.mockImplementation((outgoingStream) =>
+      toServerSentEventsResponse(outgoingStream),
+    )
+    const logError = vi.fn()
+    const post = createInterruptLabPost({
+      mode: 'durable',
+      persistenceMiddleware,
+      dependencies: { ...deps, logError },
+    })
+
+    const response = await post(request('approval-basic'))
+    expect(logError).not.toHaveBeenCalled()
+    const body = await response.text()
+
+    expect(
+      deps.runChat.mock.calls[0]?.[0].middleware?.map(
+        (middleware) => middleware.name,
+      ),
+    ).toEqual(['interrupt-lab-error-sanitizer', 'interrupt-lab-persistence'])
+    expect(body).toContain('"type":"RUN_STARTED"')
+    expect(body).toContain('"message":"Interrupt lab run failed."')
+    expect(body).toContain('"code":"interrupt-lab-run-failed"')
+    expect(body.match(/"type":"RUN_ERROR"/g)).toHaveLength(1)
+    expect(body).not.toContain(secret)
+    expect(storedErrors).toEqual(['Interrupt lab run failed.'])
+    expect(JSON.stringify(storedErrors)).not.toContain(secret)
+    expect(JSON.stringify(logError.mock.calls)).not.toContain(secret)
+  })
+})
+
+describe('controlled generic AG-UI interrupt', () => {
+  const scenario = interruptLabScenarios['generic-response-schema']
+
+  it('replaces the real model success terminal with a bound generic terminal', async () => {
+    const middleware = createGenericInterruptMiddleware({
+      scenario,
+      mode: 'ephemeral',
+    })
+    const terminal: StreamChunk = {
+      type: EventType.RUN_FINISHED,
+      runId: 'run-1',
+      threadId: 'thread-1',
+      model: 'gpt-5.5',
+      finishReason: 'stop',
+      outcome: { type: 'success' },
+      timestamp: 1,
+    }
+
+    const transformed = await middleware.onChunk?.(
+      { runId: 'run-1' } as ChatMiddlewareContext,
+      terminal,
+    )
+
+    expect(transformed).toMatchObject({
+      type: EventType.RUN_FINISHED,
+      outcome: {
+        type: 'interrupt',
+        interrupts: [
+          {
+            id: 'interrupt_lab_generic_run-1',
+            reason: 'interrupt_lab:generic_question',
+            responseSchema: scenario.genericResponseSchema,
+            metadata: {
+              kind: 'generic',
+              'tanstack:interruptBinding': {
+                kind: 'generic',
+                interruptId: 'interrupt_lab_generic_run-1',
+                interruptedRunId: 'run-1',
+                generation: 0,
+              },
+            },
+          },
+        ],
+      },
+    })
+  })
+
+  it('replaces a provider success terminal that omits the optional outcome', async () => {
+    const middleware = createGenericInterruptMiddleware({
+      scenario,
+      mode: 'ephemeral',
+    })
+    const terminal: StreamChunk = {
+      type: EventType.RUN_FINISHED,
+      runId: 'provider-run-1',
+      threadId: 'thread-1',
+      model: 'gpt-5.5',
+      finishReason: 'stop',
+      timestamp: 1,
+    }
+
+    const transformed = await middleware.onChunk?.(
+      { runId: 'request-run-1' } as ChatMiddlewareContext,
+      terminal,
+    )
+
+    expect(transformed).toMatchObject({
+      type: EventType.RUN_FINISHED,
+      outcome: {
+        type: 'interrupt',
+        interrupts: [{ id: 'interrupt_lab_generic_request-run-1' }],
+      },
+    })
+  })
+
+  it('validates and consumes an ephemeral generic resolution without retriggering', async () => {
+    const middleware = createGenericInterruptMiddleware({
+      scenario,
+      mode: 'ephemeral',
+    })
+    const config = {
+      messages: [],
+      systemPrompts: [],
+      tools: [],
+      resume: [
+        {
+          interruptId: 'interrupt_lab_generic_run-1',
+          status: 'resolved' as const,
+          payload: { answer: 'continue' },
+        },
+      ],
+    }
+
+    const transformed = await middleware.onConfig?.(
+      {
+        runId: 'run-2',
+        parentRunId: 'run-1',
+        phase: 'init',
+      } as ChatMiddlewareContext,
+      config,
+    )
+
+    expect(transformed).toMatchObject({ resume: undefined })
+    expect(transformed?.messages).toHaveLength(1)
+
+    const terminal: StreamChunk = {
+      type: EventType.RUN_FINISHED,
+      runId: 'run-2',
+      threadId: 'thread-1',
+      model: 'gpt-5.5',
+      finishReason: 'stop',
+      outcome: { type: 'success' },
+      timestamp: 1,
+    }
+    expect(
+      middleware.onChunk?.(
+        { runId: 'run-2' } as ChatMiddlewareContext,
+        terminal,
+      ),
+    ).toBeUndefined()
+  })
+
+  it('keeps validated generic resolution payloads out of trusted system prompts', async () => {
+    const sentinel = 'IGNORE_TRUSTED_INSTRUCTIONS_SENTINEL'
+    const middleware = createGenericInterruptMiddleware({
+      scenario,
+      mode: 'ephemeral',
+    })
+
+    const transformed = await middleware.onConfig?.(
+      {
+        runId: 'run-2',
+        parentRunId: 'run-1',
+        phase: 'init',
+      } as ChatMiddlewareContext,
+      {
+        messages: [],
+        systemPrompts: ['Trusted lab prompt.'],
+        tools: [],
+        resume: [
+          {
+            interruptId: 'interrupt_lab_generic_run-1',
+            status: 'resolved',
+            payload: { answer: sentinel },
+          },
+        ],
+      },
+    )
+
+    expect(transformed && 'systemPrompts' in transformed).toBe(false)
+    expect(JSON.stringify(transformed?.systemPrompts ?? [])).not.toContain(
+      sentinel,
+    )
+    expect(transformed?.messages).toEqual([
+      {
+        role: 'user',
+        content: expect.stringContaining(JSON.stringify({ answer: sentinel })),
+      },
+    ])
+  })
+
+  it('rejects an invalid generic payload but accepts cancellation', () => {
+    const invalid = createGenericInterruptMiddleware({
+      scenario,
+      mode: 'ephemeral',
+    })
+    expect(() =>
+      invalid.onConfig?.(
+        {
+          runId: 'run-2',
+          parentRunId: 'run-1',
+          phase: 'init',
+        } as ChatMiddlewareContext,
+        {
+          messages: [],
+          systemPrompts: [],
+          tools: [],
+          resume: [
+            {
+              interruptId: 'interrupt_lab_generic_run-1',
+              status: 'resolved',
+              payload: { answer: 1 },
+            },
+          ],
+        },
+      ),
+    ).toThrow(/generic interrupt payload/i)
+
+    const cancelled = createGenericInterruptMiddleware({
+      scenario,
+      mode: 'ephemeral',
+    })
+    expect(
+      cancelled.onConfig?.(
+        {
+          runId: 'run-2',
+          parentRunId: 'run-1',
+          phase: 'init',
+        } as ChatMiddlewareContext,
+        {
+          messages: [],
+          systemPrompts: [],
+          tools: [],
+          resume: [
+            {
+              interruptId: 'interrupt_lab_generic_run-1',
+              status: 'cancelled',
+            },
+          ],
+        },
+      ),
+    ).toMatchObject({ resume: undefined })
+  })
+})
diff --git a/examples/ts-react-chat/src/lib/interrupt-lab/server.ts b/examples/ts-react-chat/src/lib/interrupt-lab/server.ts
new file mode 100644
index 000000000..bb35f4b82
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/interrupt-lab/server.ts
@@ -0,0 +1,457 @@
+import {
+  EventType,
+  canonicalInterruptJson,
+  chat,
+  chatParamsFromRequestBody,
+  compileJsonSchema202012,
+  digestInterruptJson,
+  maxIterations,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { createOpenaiChat } from '@tanstack/ai-openai'
+import { interruptLabScenarios, isInterruptLabScenarioId } from './scenarios'
+import type { AnyTextAdapter, ChatMiddleware, StreamChunk } from '@tanstack/ai'
+import type {
+  InterruptLabMode,
+  InterruptLabScenario,
+  InterruptLabScenarioId,
+} from './scenarios'
+
+export type InterruptLabChatOptions = Parameters<typeof chat>[0]
+
+export interface InterruptLabRouteDependencies {
+  runChat: (options: InterruptLabChatOptions) => AsyncIterable<StreamChunk>
+  toResponse: (stream: AsyncIterable<StreamChunk>) => Response
+  createAdapter: (model: 'gpt-5.5', apiKey: string) => AnyTextAdapter
+  readApiKey: () => string | undefined
+  logError?: (entry: InterruptLabSafeLogEntry) => void
+}
+
+export interface InterruptLabSafeLogEntry {
+  event: 'interrupt-lab-run-failed'
+  mode: InterruptLabMode
+  scenarioId: InterruptLabScenarioId
+}
+
+const INTERRUPT_LAB_ERROR_MESSAGE = 'Interrupt lab run failed.'
+const INTERRUPT_LAB_ERROR_CODE = 'interrupt-lab-run-failed'
+const deliberateResumeFailures = new Map<string, true>()
+const MAX_DELIBERATE_RESUME_FAILURES = 128
+
+export interface CreateInterruptLabPostOptions {
+  mode: InterruptLabMode
+  persistenceMiddleware?: ChatMiddleware
+  dependencies?: InterruptLabRouteDependencies
+}
+
+const SYSTEM_PROMPT = `You are operating a manual interrupt API lab.
+Follow the scenario instruction exactly. Never substitute a different tool,
+never skip a requested tool, and make simultaneous calls in one assistant turn
+when the scenario asks for a batch.`
+
+const defaultDependencies: InterruptLabRouteDependencies = {
+  runChat: (options) => chat(options) as AsyncIterable<StreamChunk>,
+  toResponse: (stream) => toServerSentEventsResponse(stream),
+  createAdapter: (model, apiKey) => createOpenaiChat(model, apiKey),
+  readApiKey: () => process.env.OPENAI_API_KEY,
+  logError: (entry) => console.error('[interrupt-lab] request failed', entry),
+}
+
+type GenericInterruptLabScenario = InterruptLabScenario & {
+  genericResponseSchema: NonNullable<
+    InterruptLabScenario['genericResponseSchema']
+  >
+}
+
+function genericInterruptId(interruptedRunId: string): string {
+  return `interrupt_lab_generic_${interruptedRunId}`
+}
+
+function safeInterruptLabError(): Error {
+  const error = new Error(INTERRUPT_LAB_ERROR_MESSAGE)
+  Object.defineProperty(error, 'code', {
+    value: INTERRUPT_LAB_ERROR_CODE,
+    enumerable: true,
+  })
+  return error
+}
+
+function safeInterruptLabRunError({
+  threadId,
+  runId,
+  source,
+}: {
+  threadId: string
+  runId: string
+  source?: Extract<StreamChunk, { type: 'RUN_ERROR' }>
+}): Extract<StreamChunk, { type: 'RUN_ERROR' }> {
+  return {
+    type: EventType.RUN_ERROR,
+    threadId,
+    runId,
+    timestamp: Date.now(),
+    message: INTERRUPT_LAB_ERROR_MESSAGE,
+    code: INTERRUPT_LAB_ERROR_CODE,
+    ...(source?.['tanstack:interruptErrors'] !== undefined
+      ? { 'tanstack:interruptErrors': source['tanstack:interruptErrors'] }
+      : {}),
+    ...(source?.['tanstack:interruptRecovery'] !== undefined
+      ? { 'tanstack:interruptRecovery': source['tanstack:interruptRecovery'] }
+      : {}),
+  }
+}
+
+function createInterruptLabErrorSanitizerMiddleware(): ChatMiddleware {
+  return {
+    name: 'interrupt-lab-error-sanitizer',
+    onChunk(ctx, chunk) {
+      if (chunk.type !== EventType.RUN_ERROR) return
+      return safeInterruptLabRunError({
+        threadId: ctx.threadId,
+        runId: ctx.runId,
+        source: chunk,
+      })
+    },
+    onError(_ctx, info) {
+      // Hooks run in array order and ErrorInfo is intentionally mutable. This
+      // replaces provider details before durable persistence observes them.
+      info.error = safeInterruptLabError()
+    },
+  }
+}
+
+function logInterruptLabFailure(
+  logError: InterruptLabRouteDependencies['logError'],
+  entry: InterruptLabSafeLogEntry,
+): void {
+  try {
+    logError?.(entry)
+  } catch {
+    // Observability must never alter stream termination or public responses.
+  }
+}
+
+function sanitizeInterruptLabStream({
+  stream,
+  threadId,
+  runId,
+  logError,
+  logEntry,
+}: {
+  stream: AsyncIterable<StreamChunk>
+  threadId: string
+  runId: string
+  logError: InterruptLabRouteDependencies['logError']
+  logEntry: InterruptLabSafeLogEntry
+}): AsyncIterable<StreamChunk> {
+  return {
+    async *[Symbol.asyncIterator]() {
+      try {
+        for await (const chunk of stream) {
+          if (chunk.type === EventType.RUN_ERROR) {
+            logInterruptLabFailure(logError, logEntry)
+            yield safeInterruptLabRunError({
+              threadId,
+              runId,
+              source: chunk,
+            })
+            return
+          }
+          yield chunk
+        }
+      } catch {
+        logInterruptLabFailure(logError, logEntry)
+        yield safeInterruptLabRunError({ threadId, runId })
+      }
+    },
+  }
+}
+
+/**
+ * Models an external AG-UI generic interrupt at the stream boundary.
+ *
+ * The OpenAI request still runs normally. Only its final success terminal is
+ * replaced, and only for the dedicated generic scenario. This is deliberately
+ * not represented as a TanStack tool interrupt.
+ */
+export function createGenericInterruptMiddleware({
+  scenario,
+  mode,
+}: {
+  scenario: GenericInterruptLabScenario
+  mode: InterruptLabMode
+}): ChatMiddleware {
+  const responseSchema = scenario.genericResponseSchema
+  const validateResponse = compileJsonSchema202012(responseSchema)
+  const responseSchemaHash = digestInterruptJson(
+    canonicalInterruptJson(responseSchema),
+  )
+  let isContinuation = false
+
+  return {
+    name: 'interrupt-lab-generic-boundary',
+    onConfig(ctx, config) {
+      if (ctx.phase !== 'init' || (config.resume?.length ?? 0) === 0) {
+        return
+      }
+
+      isContinuation = true
+      const interruptedRunId = ctx.parentRunId
+      if (!interruptedRunId) {
+        throw new Error(
+          'Generic interrupt continuation requires parentRunId correlation.',
+        )
+      }
+      const expectedId = genericInterruptId(interruptedRunId)
+      if (
+        config.resume?.length !== 1 ||
+        config.resume[0]?.interruptId !== expectedId
+      ) {
+        throw new Error(
+          `Generic interrupt continuation must resolve only ${expectedId}.`,
+        )
+      }
+
+      const resolution = config.resume[0]
+      let resolutionPrompt: string
+      if (resolution.status === 'cancelled') {
+        resolutionPrompt =
+          'The user cancelled the generic interrupt. Acknowledge the cancellation briefly.'
+      } else {
+        const issues = validateResponse(resolution.payload)
+        if (issues.length > 0) {
+          const issueSummary = issues
+            .map(
+              (issue) =>
+                `${issue.path.join('.') || '<root>'}: ${issue.message}`,
+            )
+            .join('; ')
+          throw new Error(`Invalid generic interrupt payload: ${issueSummary}`)
+        }
+        resolutionPrompt = `The user resolved the generic interrupt with this validated payload: ${JSON.stringify(resolution.payload)}. Acknowledge it briefly.`
+      }
+
+      return {
+        messages: [
+          ...config.messages,
+          {
+            role: 'user',
+            content: resolutionPrompt,
+          },
+        ],
+        ...(mode === 'ephemeral' ? { resume: undefined } : {}),
+      }
+    },
+    onChunk(ctx, chunk) {
+      if (
+        isContinuation ||
+        chunk.type !== EventType.RUN_FINISHED ||
+        (chunk.outcome !== undefined && chunk.outcome.type !== 'success')
+      ) {
+        return
+      }
+
+      const interruptId = genericInterruptId(ctx.runId)
+      return {
+        ...chunk,
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              id: interruptId,
+              reason: 'interrupt_lab:generic_question',
+              message: 'Provide a typed answer for the generic AG-UI question.',
+              responseSchema,
+              metadata: {
+                kind: 'generic',
+                'tanstack:interruptBinding': {
+                  kind: 'generic',
+                  interruptId,
+                  interruptedRunId: ctx.runId,
+                  generation: 0,
+                  responseSchemaHash,
+                },
+              },
+            },
+          ],
+        },
+      }
+    },
+  }
+}
+
+function jsonError(status: number, error: string): Response {
+  return new Response(JSON.stringify({ error }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+function maybeFailDurableResumeOnce({
+  mode,
+  threadId,
+  parentRunId,
+  resumeCount,
+  enabled,
+}: {
+  mode: InterruptLabMode
+  threadId: string
+  parentRunId?: string
+  resumeCount: number
+  enabled: boolean
+}): Response | undefined {
+  if (mode !== 'durable' || resumeCount === 0 || parentRunId === undefined) {
+    return undefined
+  }
+
+  const key = `${threadId}:${parentRunId}`
+  if (!enabled) {
+    deliberateResumeFailures.delete(key)
+    return undefined
+  }
+  if (deliberateResumeFailures.delete(key)) return undefined
+  deliberateResumeFailures.set(key, true)
+  while (deliberateResumeFailures.size > MAX_DELIBERATE_RESUME_FAILURES) {
+    const oldestKey = deliberateResumeFailures.keys().next().value
+    if (oldestKey === undefined) break
+    deliberateResumeFailures.delete(oldestKey)
+  }
+  return new Response(
+    JSON.stringify({
+      error: 'Deliberate interrupt lab resume failure. Retry is safe.',
+      retryable: true,
+    }),
+    {
+      status: 503,
+      headers: { 'content-type': 'application/json' },
+    },
+  )
+}
+
+export function createInterruptLabPost({
+  mode,
+  persistenceMiddleware,
+  dependencies = defaultDependencies,
+}: CreateInterruptLabPostOptions): (request: Request) => Promise<Response> {
+  if (mode === 'durable' && persistenceMiddleware === undefined) {
+    throw new TypeError(
+      'Durable interrupt lab requires persistence middleware.',
+    )
+  }
+
+  return async (request) => {
+    if (request.signal.aborted) return new Response(null, { status: 499 })
+
+    let params: Awaited<ReturnType<typeof chatParamsFromRequestBody>>
+    try {
+      params = await chatParamsFromRequestBody(await request.json())
+    } catch (error) {
+      return jsonError(
+        400,
+        error instanceof Error ? error.message : 'Invalid AG-UI request body.',
+      )
+    }
+
+    const scenarioId = params.forwardedProps.interruptScenario
+    if (!isInterruptLabScenarioId(scenarioId)) {
+      return jsonError(400, 'Unknown interrupt lab scenario.')
+    }
+    const scenario: InterruptLabScenario = interruptLabScenarios[scenarioId]
+    if (!scenario.modes.some((supportedMode) => supportedMode === mode)) {
+      return jsonError(
+        400,
+        `Scenario ${scenarioId} does not support ${mode} mode.`,
+      )
+    }
+
+    const apiKey = dependencies.readApiKey()
+    if (typeof apiKey !== 'string' || apiKey.trim() === '') {
+      return jsonError(
+        500,
+        'OPENAI_API_KEY is required for the interrupt lab. Set it and restart the dev server.',
+      )
+    }
+
+    const deliberateFailure = maybeFailDurableResumeOnce({
+      mode,
+      threadId: params.threadId,
+      ...(params.parentRunId !== undefined
+        ? { parentRunId: params.parentRunId }
+        : {}),
+      resumeCount: params.resume?.length ?? 0,
+      enabled: params.forwardedProps.interruptLabFailResumeOnce === true,
+    })
+    if (deliberateFailure !== undefined) return deliberateFailure
+
+    const abortController = new AbortController()
+    request.signal.addEventListener('abort', () => abortController.abort(), {
+      once: true,
+    })
+
+    try {
+      const middleware: Array<ChatMiddleware> = [
+        createInterruptLabErrorSanitizerMiddleware(),
+      ]
+      if (scenario.genericResponseSchema !== undefined) {
+        middleware.push(
+          createGenericInterruptMiddleware({
+            scenario: {
+              ...scenario,
+              genericResponseSchema: scenario.genericResponseSchema,
+            },
+            mode,
+          }),
+        )
+      }
+      if (persistenceMiddleware !== undefined) {
+        middleware.push(persistenceMiddleware)
+      }
+
+      const stream = dependencies.runChat({
+        adapter: dependencies.createAdapter('gpt-5.5', apiKey),
+        debug: params.forwardedProps.interruptLabDebug === true,
+        messages: params.messages,
+        tools: [...scenario.tools],
+        systemPrompts: [SYSTEM_PROMPT, scenario.systemPrompt],
+        agentLoopStrategy: maxIterations(8),
+        middleware,
+        metadata: {
+          interruptLabMode: mode,
+          interruptLabScenario: scenarioId,
+        },
+        threadId: params.threadId,
+        runId: params.runId,
+        parentRunId: params.parentRunId,
+        state: params.state,
+        resume: params.resume,
+        abortController,
+      })
+      return dependencies.toResponse(
+        sanitizeInterruptLabStream({
+          stream,
+          threadId: params.threadId,
+          runId: params.runId,
+          logError: dependencies.logError ?? defaultDependencies.logError,
+          logEntry: {
+            event: 'interrupt-lab-run-failed',
+            mode,
+            scenarioId,
+          },
+        }),
+      )
+    } catch {
+      if (abortController.signal.aborted) {
+        return new Response(null, { status: 499 })
+      }
+      logInterruptLabFailure(
+        dependencies.logError ?? defaultDependencies.logError,
+        {
+          event: 'interrupt-lab-run-failed',
+          mode,
+          scenarioId,
+        },
+      )
+      return jsonError(502, INTERRUPT_LAB_ERROR_MESSAGE)
+    }
+  }
+}
diff --git a/examples/ts-react-chat/src/routeTree.gen.ts b/examples/ts-react-chat/src/routeTree.gen.ts
index 2fa2f9029..4012d5d19 100644
--- a/examples/ts-react-chat/src/routeTree.gen.ts
+++ b/examples/ts-react-chat/src/routeTree.gen.ts
@@ -18,9 +18,11 @@ import { Route as RealtimeRouteImport } from './routes/realtime'
 import { Route as McpDemoRouteImport } from './routes/mcp-demo'
 import { Route as McpAppsRouteImport } from './routes/mcp-apps'
 import { Route as Issue176ToolResultRouteImport } from './routes/issue-176-tool-result'
+import { Route as InterruptsRouteImport } from './routes/interrupts'
 import { Route as ImageToolReproRouteImport } from './routes/image-tool-repro'
 import { Route as ImageGenRouteImport } from './routes/image-gen'
 import { Route as GenerationHooksRouteImport } from './routes/generation-hooks'
+import { Route as DurableInterruptsRouteImport } from './routes/durable-interrupts'
 import { Route as CapabilityDemoRouteImport } from './routes/capability-demo'
 import { Route as IndexRouteImport } from './routes/index'
 import { Route as GenerationsVideoRouteImport } from './routes/generations.video'
@@ -47,8 +49,10 @@ import { Route as ApiMcpAppsWeatherServerRouteImport } from './routes/api.mcp-ap
 import { Route as ApiMcpAppsShopServerRouteImport } from './routes/api.mcp-apps-shop-server'
 import { Route as ApiMcpAppsChatRouteImport } from './routes/api.mcp-apps-chat'
 import { Route as ApiMcpAppsCallRouteImport } from './routes/api.mcp-apps-call'
+import { Route as ApiInterruptsRouteImport } from './routes/api.interrupts'
 import { Route as ApiImageToolReproRouteImport } from './routes/api.image-tool-repro'
 import { Route as ApiImageGenRouteImport } from './routes/api.image-gen'
+import { Route as ApiDurableInterruptsRouteImport } from './routes/api.durable-interrupts'
 import { Route as ApiCapabilityDemoRouteImport } from './routes/api.capability-demo'
 import { Route as ExampleGuitarsIndexRouteImport } from './routes/example.guitars/index'
 import { Route as ExampleGuitarsGuitarIdRouteImport } from './routes/example.guitars/$guitarId'
@@ -102,6 +106,11 @@ const Issue176ToolResultRoute = Issue176ToolResultRouteImport.update({
   path: '/issue-176-tool-result',
   getParentRoute: () => rootRouteImport,
 } as any)
+const InterruptsRoute = InterruptsRouteImport.update({
+  id: '/interrupts',
+  path: '/interrupts',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ImageToolReproRoute = ImageToolReproRouteImport.update({
   id: '/image-tool-repro',
   path: '/image-tool-repro',
@@ -117,6 +126,11 @@ const GenerationHooksRoute = GenerationHooksRouteImport.update({
   path: '/generation-hooks',
   getParentRoute: () => rootRouteImport,
 } as any)
+const DurableInterruptsRoute = DurableInterruptsRouteImport.update({
+  id: '/durable-interrupts',
+  path: '/durable-interrupts',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const CapabilityDemoRoute = CapabilityDemoRouteImport.update({
   id: '/capability-demo',
   path: '/capability-demo',
@@ -250,6 +264,11 @@ const ApiMcpAppsCallRoute = ApiMcpAppsCallRouteImport.update({
   path: '/api/mcp-apps-call',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiInterruptsRoute = ApiInterruptsRouteImport.update({
+  id: '/api/interrupts',
+  path: '/api/interrupts',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiImageToolReproRoute = ApiImageToolReproRouteImport.update({
   id: '/api/image-tool-repro',
   path: '/api/image-tool-repro',
@@ -260,6 +279,11 @@ const ApiImageGenRoute = ApiImageGenRouteImport.update({
   path: '/api/image-gen',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiDurableInterruptsRoute = ApiDurableInterruptsRouteImport.update({
+  id: '/api/durable-interrupts',
+  path: '/api/durable-interrupts',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiCapabilityDemoRoute = ApiCapabilityDemoRouteImport.update({
   id: '/api/capability-demo',
   path: '/api/capability-demo',
@@ -299,9 +323,11 @@ const ApiGenerateAudioRoute = ApiGenerateAudioRouteImport.update({
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
   '/capability-demo': typeof CapabilityDemoRoute
+  '/durable-interrupts': typeof DurableInterruptsRoute
   '/generation-hooks': typeof GenerationHooksRoute
   '/image-gen': typeof ImageGenRoute
   '/image-tool-repro': typeof ImageToolReproRoute
+  '/interrupts': typeof InterruptsRoute
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/mcp-apps': typeof McpAppsRoute
   '/mcp-demo': typeof McpDemoRoute
@@ -312,8 +338,10 @@ export interface FileRoutesByFullPath {
   '/threads': typeof ThreadsRoute
   '/typesafe-tools': typeof TypesafeToolsRoute
   '/api/capability-demo': typeof ApiCapabilityDemoRoute
+  '/api/durable-interrupts': typeof ApiDurableInterruptsRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/image-tool-repro': typeof ApiImageToolReproRoute
+  '/api/interrupts': typeof ApiInterruptsRoute
   '/api/mcp-apps-call': typeof ApiMcpAppsCallRoute
   '/api/mcp-apps-chat': typeof ApiMcpAppsChatRoute
   '/api/mcp-apps-shop-server': typeof ApiMcpAppsShopServerRoute
@@ -348,9 +376,11 @@ export interface FileRoutesByFullPath {
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
   '/capability-demo': typeof CapabilityDemoRoute
+  '/durable-interrupts': typeof DurableInterruptsRoute
   '/generation-hooks': typeof GenerationHooksRoute
   '/image-gen': typeof ImageGenRoute
   '/image-tool-repro': typeof ImageToolReproRoute
+  '/interrupts': typeof InterruptsRoute
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/mcp-apps': typeof McpAppsRoute
   '/mcp-demo': typeof McpDemoRoute
@@ -361,8 +391,10 @@ export interface FileRoutesByTo {
   '/threads': typeof ThreadsRoute
   '/typesafe-tools': typeof TypesafeToolsRoute
   '/api/capability-demo': typeof ApiCapabilityDemoRoute
+  '/api/durable-interrupts': typeof ApiDurableInterruptsRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/image-tool-repro': typeof ApiImageToolReproRoute
+  '/api/interrupts': typeof ApiInterruptsRoute
   '/api/mcp-apps-call': typeof ApiMcpAppsCallRoute
   '/api/mcp-apps-chat': typeof ApiMcpAppsChatRoute
   '/api/mcp-apps-shop-server': typeof ApiMcpAppsShopServerRoute
@@ -398,9 +430,11 @@ export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
   '/capability-demo': typeof CapabilityDemoRoute
+  '/durable-interrupts': typeof DurableInterruptsRoute
   '/generation-hooks': typeof GenerationHooksRoute
   '/image-gen': typeof ImageGenRoute
   '/image-tool-repro': typeof ImageToolReproRoute
+  '/interrupts': typeof InterruptsRoute
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/mcp-apps': typeof McpAppsRoute
   '/mcp-demo': typeof McpDemoRoute
@@ -411,8 +445,10 @@ export interface FileRoutesById {
   '/threads': typeof ThreadsRoute
   '/typesafe-tools': typeof TypesafeToolsRoute
   '/api/capability-demo': typeof ApiCapabilityDemoRoute
+  '/api/durable-interrupts': typeof ApiDurableInterruptsRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/image-tool-repro': typeof ApiImageToolReproRoute
+  '/api/interrupts': typeof ApiInterruptsRoute
   '/api/mcp-apps-call': typeof ApiMcpAppsCallRoute
   '/api/mcp-apps-chat': typeof ApiMcpAppsChatRoute
   '/api/mcp-apps-shop-server': typeof ApiMcpAppsShopServerRoute
@@ -449,9 +485,11 @@ export interface FileRouteTypes {
   fullPaths:
     | '/'
     | '/capability-demo'
+    | '/durable-interrupts'
     | '/generation-hooks'
     | '/image-gen'
     | '/image-tool-repro'
+    | '/interrupts'
     | '/issue-176-tool-result'
     | '/mcp-apps'
     | '/mcp-demo'
@@ -462,8 +500,10 @@ export interface FileRouteTypes {
     | '/threads'
     | '/typesafe-tools'
     | '/api/capability-demo'
+    | '/api/durable-interrupts'
     | '/api/image-gen'
     | '/api/image-tool-repro'
+    | '/api/interrupts'
     | '/api/mcp-apps-call'
     | '/api/mcp-apps-chat'
     | '/api/mcp-apps-shop-server'
@@ -498,9 +538,11 @@ export interface FileRouteTypes {
   to:
     | '/'
     | '/capability-demo'
+    | '/durable-interrupts'
     | '/generation-hooks'
     | '/image-gen'
     | '/image-tool-repro'
+    | '/interrupts'
     | '/issue-176-tool-result'
     | '/mcp-apps'
     | '/mcp-demo'
@@ -511,8 +553,10 @@ export interface FileRouteTypes {
     | '/threads'
     | '/typesafe-tools'
     | '/api/capability-demo'
+    | '/api/durable-interrupts'
     | '/api/image-gen'
     | '/api/image-tool-repro'
+    | '/api/interrupts'
     | '/api/mcp-apps-call'
     | '/api/mcp-apps-chat'
     | '/api/mcp-apps-shop-server'
@@ -547,9 +591,11 @@ export interface FileRouteTypes {
     | '__root__'
     | '/'
     | '/capability-demo'
+    | '/durable-interrupts'
     | '/generation-hooks'
     | '/image-gen'
     | '/image-tool-repro'
+    | '/interrupts'
     | '/issue-176-tool-result'
     | '/mcp-apps'
     | '/mcp-demo'
@@ -560,8 +606,10 @@ export interface FileRouteTypes {
     | '/threads'
     | '/typesafe-tools'
     | '/api/capability-demo'
+    | '/api/durable-interrupts'
     | '/api/image-gen'
     | '/api/image-tool-repro'
+    | '/api/interrupts'
     | '/api/mcp-apps-call'
     | '/api/mcp-apps-chat'
     | '/api/mcp-apps-shop-server'
@@ -597,9 +645,11 @@ export interface FileRouteTypes {
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
   CapabilityDemoRoute: typeof CapabilityDemoRoute
+  DurableInterruptsRoute: typeof DurableInterruptsRoute
   GenerationHooksRoute: typeof GenerationHooksRoute
   ImageGenRoute: typeof ImageGenRoute
   ImageToolReproRoute: typeof ImageToolReproRoute
+  InterruptsRoute: typeof InterruptsRoute
   Issue176ToolResultRoute: typeof Issue176ToolResultRoute
   McpAppsRoute: typeof McpAppsRoute
   McpDemoRoute: typeof McpDemoRoute
@@ -610,8 +660,10 @@ export interface RootRouteChildren {
   ThreadsRoute: typeof ThreadsRoute
   TypesafeToolsRoute: typeof TypesafeToolsRoute
   ApiCapabilityDemoRoute: typeof ApiCapabilityDemoRoute
+  ApiDurableInterruptsRoute: typeof ApiDurableInterruptsRoute
   ApiImageGenRoute: typeof ApiImageGenRoute
   ApiImageToolReproRoute: typeof ApiImageToolReproRoute
+  ApiInterruptsRoute: typeof ApiInterruptsRoute
   ApiMcpAppsCallRoute: typeof ApiMcpAppsCallRoute
   ApiMcpAppsChatRoute: typeof ApiMcpAppsChatRoute
   ApiMcpAppsShopServerRoute: typeof ApiMcpAppsShopServerRoute
@@ -709,6 +761,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof Issue176ToolResultRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/interrupts': {
+      id: '/interrupts'
+      path: '/interrupts'
+      fullPath: '/interrupts'
+      preLoaderRoute: typeof InterruptsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/image-tool-repro': {
       id: '/image-tool-repro'
       path: '/image-tool-repro'
@@ -730,6 +789,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof GenerationHooksRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/durable-interrupts': {
+      id: '/durable-interrupts'
+      path: '/durable-interrupts'
+      fullPath: '/durable-interrupts'
+      preLoaderRoute: typeof DurableInterruptsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/capability-demo': {
       id: '/capability-demo'
       path: '/capability-demo'
@@ -912,6 +978,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiMcpAppsCallRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/interrupts': {
+      id: '/api/interrupts'
+      path: '/api/interrupts'
+      fullPath: '/api/interrupts'
+      preLoaderRoute: typeof ApiInterruptsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/image-tool-repro': {
       id: '/api/image-tool-repro'
       path: '/api/image-tool-repro'
@@ -926,6 +999,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiImageGenRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/durable-interrupts': {
+      id: '/api/durable-interrupts'
+      path: '/api/durable-interrupts'
+      fullPath: '/api/durable-interrupts'
+      preLoaderRoute: typeof ApiDurableInterruptsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/capability-demo': {
       id: '/api/capability-demo'
       path: '/api/capability-demo'
@@ -981,9 +1061,11 @@ declare module '@tanstack/react-router' {
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
   CapabilityDemoRoute: CapabilityDemoRoute,
+  DurableInterruptsRoute: DurableInterruptsRoute,
   GenerationHooksRoute: GenerationHooksRoute,
   ImageGenRoute: ImageGenRoute,
   ImageToolReproRoute: ImageToolReproRoute,
+  InterruptsRoute: InterruptsRoute,
   Issue176ToolResultRoute: Issue176ToolResultRoute,
   McpAppsRoute: McpAppsRoute,
   McpDemoRoute: McpDemoRoute,
@@ -994,8 +1076,10 @@ const rootRouteChildren: RootRouteChildren = {
   ThreadsRoute: ThreadsRoute,
   TypesafeToolsRoute: TypesafeToolsRoute,
   ApiCapabilityDemoRoute: ApiCapabilityDemoRoute,
+  ApiDurableInterruptsRoute: ApiDurableInterruptsRoute,
   ApiImageGenRoute: ApiImageGenRoute,
   ApiImageToolReproRoute: ApiImageToolReproRoute,
+  ApiInterruptsRoute: ApiInterruptsRoute,
   ApiMcpAppsCallRoute: ApiMcpAppsCallRoute,
   ApiMcpAppsChatRoute: ApiMcpAppsChatRoute,
   ApiMcpAppsShopServerRoute: ApiMcpAppsShopServerRoute,
diff --git a/examples/ts-react-chat/src/routes/api.durable-interrupts.ts b/examples/ts-react-chat/src/routes/api.durable-interrupts.ts
new file mode 100644
index 000000000..635f8c154
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/api.durable-interrupts.ts
@@ -0,0 +1,65 @@
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  getInterruptRecoveryState,
+  withChatPersistence,
+} from '@tanstack/ai-persistence'
+import { createInterruptLabPersistence } from '@/lib/interrupt-lab/persistence'
+import { createInterruptLabPost } from '@/lib/interrupt-lab/server'
+
+export const durableInterruptLabPersistence = createInterruptLabPersistence()
+export const durableInterruptLabMiddleware = withChatPersistence(
+  durableInterruptLabPersistence,
+)
+export const durableInterruptLabRouteConfig = {
+  mode: 'durable',
+  persistenceMiddleware: durableInterruptLabMiddleware,
+} as const
+export const durableInterruptLabPost = createInterruptLabPost(
+  durableInterruptLabRouteConfig,
+)
+
+export async function durableInterruptLabRequest(
+  request: Request,
+): Promise<Response> {
+  const url = new URL(request.url)
+  const threadId = url.searchParams.get('threadId')
+  const interruptedRunId = url.searchParams.get('interruptedRunId')
+  const knownGenerationText = url.searchParams.get('knownGeneration')
+  const isRecoveryRequest =
+    threadId !== null ||
+    interruptedRunId !== null ||
+    knownGenerationText !== null
+
+  if (!isRecoveryRequest) return durableInterruptLabPost(request)
+
+  const knownGeneration = Number(knownGenerationText)
+  if (
+    !threadId ||
+    !interruptedRunId ||
+    knownGenerationText === null ||
+    !Number.isSafeInteger(knownGeneration) ||
+    knownGeneration < 0
+  ) {
+    return new Response(
+      JSON.stringify({ error: 'Invalid interrupt recovery query.' }),
+      {
+        status: 400,
+        headers: { 'content-type': 'application/json' },
+      },
+    )
+  }
+
+  const state = await getInterruptRecoveryState(
+    durableInterruptLabPersistence.stores.interrupts,
+    { threadId, interruptedRunId, knownGeneration },
+  )
+  return Response.json(state)
+}
+
+export const Route = createFileRoute('/api/durable-interrupts')({
+  server: {
+    handlers: {
+      POST: ({ request }) => durableInterruptLabRequest(request),
+    },
+  },
+})
diff --git a/examples/ts-react-chat/src/routes/api.interrupts.ts b/examples/ts-react-chat/src/routes/api.interrupts.ts
new file mode 100644
index 000000000..950ebf8f4
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/api.interrupts.ts
@@ -0,0 +1,13 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { createInterruptLabPost } from '@/lib/interrupt-lab/server'
+
+export const interruptLabRouteConfig = { mode: 'ephemeral' } as const
+export const interruptLabPost = createInterruptLabPost(interruptLabRouteConfig)
+
+export const Route = createFileRoute('/api/interrupts')({
+  server: {
+    handlers: {
+      POST: ({ request }) => interruptLabPost(request),
+    },
+  },
+})
diff --git a/examples/ts-react-chat/src/routes/durable-interrupts.tsx b/examples/ts-react-chat/src/routes/durable-interrupts.tsx
new file mode 100644
index 000000000..bfdeaf6e0
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/durable-interrupts.tsx
@@ -0,0 +1,29 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { InterruptLabPage } from '@/lib/interrupt-lab/InterruptLabPage'
+import { interruptLabSearchFromSearch } from '@/lib/interrupt-lab/client-ui'
+
+export const Route = createFileRoute('/durable-interrupts')({
+  validateSearch: (search) => interruptLabSearchFromSearch(search, 'durable'),
+  component: DurableInterruptLabRoute,
+})
+
+function DurableInterruptLabRoute() {
+  const { debug, case: scenarioId = 'approval-basic' } = Route.useSearch()
+  const navigate = Route.useNavigate()
+  return (
+    <InterruptLabPage
+      mode="durable"
+      debug={debug ?? false}
+      scenarioId={scenarioId}
+      onScenarioChange={(nextScenarioId) => {
+        void navigate({
+          replace: true,
+          search: (previous) => ({
+            ...previous,
+            case: nextScenarioId,
+          }),
+        })
+      }}
+    />
+  )
+}
diff --git a/examples/ts-react-chat/src/routes/interrupts.tsx b/examples/ts-react-chat/src/routes/interrupts.tsx
new file mode 100644
index 000000000..4db7eaf85
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/interrupts.tsx
@@ -0,0 +1,29 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { InterruptLabPage } from '@/lib/interrupt-lab/InterruptLabPage'
+import { interruptLabSearchFromSearch } from '@/lib/interrupt-lab/client-ui'
+
+export const Route = createFileRoute('/interrupts')({
+  validateSearch: (search) => interruptLabSearchFromSearch(search, 'ephemeral'),
+  component: EphemeralInterruptLabRoute,
+})
+
+function EphemeralInterruptLabRoute() {
+  const { debug, case: scenarioId = 'approval-basic' } = Route.useSearch()
+  const navigate = Route.useNavigate()
+  return (
+    <InterruptLabPage
+      mode="ephemeral"
+      debug={debug ?? false}
+      scenarioId={scenarioId}
+      onScenarioChange={(nextScenarioId) => {
+        void navigate({
+          replace: true,
+          search: (previous) => ({
+            ...previous,
+            case: nextScenarioId,
+          }),
+        })
+      }}
+    />
+  )
+}
diff --git a/packages/ai-acp/tests/compatible.test.ts b/packages/ai-acp/tests/compatible.test.ts
index 3a47958bb..8b21528b7 100644
--- a/packages/ai-acp/tests/compatible.test.ts
+++ b/packages/ai-acp/tests/compatible.test.ts
@@ -68,7 +68,7 @@ const FAKE_ACP_AGENT = fakeAcpAgent()
 const baseDir = path.join(os.tmpdir(), `tanstack-ai-acp-test-${Date.now()}`)
 // No removeOnDestroy: destroying a sandbox right after killing its agent races
 // the OS releasing the dir (EBUSY on Windows). Clean the tree once at the end.
-const provider = localProcessSandbox({ baseDir })
+const provider = localProcessSandbox({ baseDir, removeOnDestroy: false })
 
 afterAll(async () => {
   await fsp.rm(baseDir, {
diff --git a/packages/ai-acp/tests/sandbox-provisioning.test.ts b/packages/ai-acp/tests/sandbox-provisioning.test.ts
index dac4f7768..4f13b0de0 100644
--- a/packages/ai-acp/tests/sandbox-provisioning.test.ts
+++ b/packages/ai-acp/tests/sandbox-provisioning.test.ts
@@ -112,7 +112,7 @@ const baseDir = path.join(os.tmpdir(), `tanstack-ai-acp-prov-${Date.now()}`)
 // No removeOnDestroy: destroying a sandbox right after killing its agent races
 // the OS releasing the dir (EBUSY on Windows). Clean the whole tree once at the
 // end instead, with retries for any lingering handle.
-const provider = localProcessSandbox({ baseDir })
+const provider = localProcessSandbox({ baseDir, removeOnDestroy: false })
 
 afterAll(async () => {
   await fsp.rm(baseDir, {
diff --git a/packages/ai-angular/src/inject-chat.ts b/packages/ai-angular/src/inject-chat.ts
index 186d5dee9..d67aa2332 100644
--- a/packages/ai-angular/src/inject-chat.ts
+++ b/packages/ai-angular/src/inject-chat.ts
@@ -15,11 +15,15 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
   StreamChunk,
 } from '@tanstack/ai'
 import type {
   ChatClientState,
+  ChatInterrupt,
+  ChatInterruptState,
+  ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
   StructuredOutputPart,
@@ -32,6 +36,9 @@ import type {
   UIMessage,
 } from './types'
 
+const EMPTY_INTERRUPTS = Object.freeze([])
+const EMPTY_INTERRUPT_ERRORS = Object.freeze([])
+
 let nextId = 0
 
 export function injectChat<
@@ -63,6 +70,12 @@ export function injectChat<
   const isSubscribed = signal(false)
   const connectionStatus = signal<ConnectionStatus>('disconnected')
   const sessionGenerating = signal(false)
+  const interruptState = signal<ChatInterruptState<TTools>>({
+    interrupts: EMPTY_INTERRUPTS,
+    pendingInterrupts: EMPTY_INTERRUPTS,
+    interruptErrors: EMPTY_INTERRUPT_ERRORS,
+    resuming: false,
+  })
 
   // Reactive option sources. Plain values become constant computeds.
   const bodySource =
@@ -112,6 +125,10 @@ export function injectChat<
     onResumeStateChange: (resumeState, pendingInterrupts) => {
       options.onResumeStateChange?.(resumeState, pendingInterrupts)
     },
+    onInterruptStateChange: (nextInterruptState) => {
+      interruptState.set(nextInterruptState)
+      options.onInterruptStateChange?.(nextInterruptState)
+    },
     tools: options.tools,
     onCustomEvent: (eventType, data, context) =>
       options.onCustomEvent?.(eventType, data, context),
@@ -128,6 +145,7 @@ export function injectChat<
   })
 
   messages.set(client.getMessages())
+  interruptState.set(client.getInterruptState())
 
   // Sync reactive body / forwardedProps / context to the client.
   if (bodySource || forwardedPropsSource || contextSource) {
@@ -245,6 +263,25 @@ export function injectChat<
   }) => {
     await client.addToolApprovalResponse(response)
   }
+  const interrupts = computed(() => interruptState().interrupts)
+  const pendingInterrupts = computed(() => interruptState().interrupts)
+  const interruptErrors = computed(() => interruptState().interruptErrors)
+  const resuming = computed(() => interruptState().resuming)
+  const resolveInterrupts = (
+    resolution: boolean | ((interrupt: ChatInterrupt<TTools>) => undefined),
+  ) => {
+    if (typeof resolution === 'boolean') {
+      client.resolveInterrupts(resolution)
+    } else {
+      client.resolveInterrupts(resolution)
+    }
+  }
+  const cancelInterrupts = () => client.cancelInterrupts()
+  const retryInterrupts = () => client.retryInterrupts()
+  const resumeInterruptsUnsafe = (
+    resumeItems: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => client.resumeInterruptsUnsafe(resumeItems, state)
 
   // eslint-disable-next-line no-restricted-syntax -- return shape diverges from conditional InjectChatResult<TTools, TSchema>; TS can't structurally narrow the TSchema-gated partial/final signals
   return {
@@ -263,6 +300,14 @@ export function injectChat<
     clear,
     addToolResult,
     addToolApprovalResponse,
+    interrupts,
+    pendingInterrupts,
+    interruptErrors,
+    resuming,
+    resolveInterrupts,
+    cancelInterrupts,
+    retryInterrupts,
+    resumeInterruptsUnsafe,
     partial,
     final,
   } as unknown as InjectChatResult<TTools, TSchema>
diff --git a/packages/ai-angular/src/types.ts b/packages/ai-angular/src/types.ts
index d6c369263..3f6ee4a54 100644
--- a/packages/ai-angular/src/types.ts
+++ b/packages/ai-angular/src/types.ts
@@ -2,13 +2,18 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
 } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
+  BoundInterrupts,
   ChatClientOptions,
   ChatClientState,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatRequestBody,
+  ChatResumeState,
   ClientContextOptionFromTools,
   ConnectionStatus,
   DistributedOmit,
@@ -118,6 +123,24 @@ interface BaseInjectChatResult<
     id: string
     approved: boolean
   }) => Promise<void>
+  /** Immutable bound interrupts for the current interrupted run. */
+  interrupts: Signal<BoundInterrupts<TTools>>
+  /** @deprecated Use `interrupts`. */
+  pendingInterrupts: Signal<BoundInterrupts<TTools>>
+  /** Batch-level interrupt errors. */
+  interruptErrors: Signal<ChatInterruptState<TTools>['interruptErrors']>
+  /** Whether the client is submitting an interrupt batch. */
+  resuming: Signal<boolean>
+  resolveInterrupts: {
+    (approved: boolean): void
+    (resolver: (interrupt: ChatInterrupt<TTools>) => undefined): void
+  }
+  cancelInterrupts: () => void
+  retryInterrupts: () => void
+  resumeInterruptsUnsafe: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
   /** Reload the last assistant message. */
   reload: () => Promise<void>
   /** Stop the current response generation. */
diff --git a/packages/ai-angular/tests/inject-chat-types.test.ts b/packages/ai-angular/tests/inject-chat-types.test.ts
index d56de87a9..d121b7a62 100644
--- a/packages/ai-angular/tests/inject-chat-types.test.ts
+++ b/packages/ai-angular/tests/inject-chat-types.test.ts
@@ -7,7 +7,8 @@
 import { describe, expectTypeOf, it } from 'vitest'
 import { z } from 'zod'
 import type { Signal } from '@angular/core'
-import type { AnyClientTool } from '@tanstack/ai'
+import { toolDefinition, type AnyClientTool } from '@tanstack/ai'
+import { clientTools } from '@tanstack/ai-client'
 import { injectChat } from '../src/inject-chat'
 import type { DeepPartial, InjectChatResult } from '../src/types'
 
@@ -75,3 +76,117 @@ describe('injectChat() return type (angular)', () => {
     })
   })
 })
+
+describe('injectChat() interrupt types', () => {
+  it('preserves approval, generic, and client-tool inference', () => {
+    const inputSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { cents: 0 },
+          output: { cents: 0 },
+        },
+        validate: (value: unknown) => ({
+          value:
+            value !== null &&
+            typeof value === 'object' &&
+            'cents' in value &&
+            typeof value.cents === 'number'
+              ? { cents: value.cents }
+              : { cents: 0 },
+        }),
+      },
+    }
+    const approveSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { note: '' },
+          output: { note: '' },
+        },
+        validate: () => ({ value: { note: '' } }),
+      },
+    }
+    const rejectSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { reason: '' },
+          output: { reason: '' },
+        },
+        validate: () => ({ value: { reason: '' } }),
+      },
+    }
+    const outputSchema = z.object({ accountId: z.string() })
+    const transfer = toolDefinition({
+      name: 'transfer',
+      description: 'Transfer funds',
+      needsApproval: true,
+      inputSchema,
+      approvalSchema: {
+        approve: approveSchema,
+        reject: rejectSchema,
+      },
+    }).client()
+    const confirm = toolDefinition({
+      name: 'confirm',
+      description: 'Confirm without schemas',
+      needsApproval: true,
+    }).client()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Lookup account',
+      outputSchema,
+    }).client(() => ({ accountId: 'account-1' }))
+    const tools = clientTools(transfer, confirm, lookup)
+    type Interrupt = ReturnType<
+      InjectChatResult<typeof tools>['interrupts']
+    >[number]
+    type Transfer = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'transfer' }
+    >
+    type Confirm = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'confirm' }
+    >
+    type Generic = Extract<Interrupt, { kind: 'generic' }>
+
+    const check = (
+      transferInterrupt: Transfer,
+      confirmInterrupt: Confirm,
+      genericInterrupt: Generic,
+    ) => {
+      transferInterrupt.resolveInterrupt(true, {
+        editedArgs: { cents: 100 },
+        payload: { note: 'approved' },
+      })
+      transferInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'declined' },
+      })
+      // @ts-expect-error rejected approvals cannot edit tool input
+      transferInterrupt.resolveInterrupt(false, { editedArgs: { cents: 1 } })
+      // @ts-expect-error approve payload uses the approve branch
+      transferInterrupt.resolveInterrupt(true, {
+        payload: { reason: 'wrong branch' },
+      })
+
+      confirmInterrupt.resolveInterrupt(true)
+      confirmInterrupt.resolveInterrupt(false)
+      // @ts-expect-error omitted input schema forbids edited input
+      confirmInterrupt.resolveInterrupt(true, { editedArgs: { cents: 1 } })
+      // @ts-expect-error omitted approval branches forbid payloads
+      confirmInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'no branch' },
+      })
+
+      expectTypeOf(genericInterrupt.resolveInterrupt)
+        .parameter(0)
+        .toEqualTypeOf<unknown>()
+    }
+    void check
+  })
+})
diff --git a/packages/ai-angular/tests/inject-chat.test.ts b/packages/ai-angular/tests/inject-chat.test.ts
index 6855074af..39f930637 100644
--- a/packages/ai-angular/tests/inject-chat.test.ts
+++ b/packages/ai-angular/tests/inject-chat.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
 import { EventType } from '@tanstack/ai/client'
 import { Component, signal } from '@angular/core'
@@ -7,13 +7,93 @@ import { ChatClient } from '@tanstack/ai-client'
 import { injectChat } from '../src/inject-chat'
 import {
   createMockConnectionAdapter,
+  createInterruptResumeSnapshot,
   createTextChunks,
   renderInjectChat,
 } from './test-utils'
 
 const tick = () => new Promise((r) => setTimeout(r, 0))
 
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
 describe('injectChat', () => {
+  describe('interrupt state', () => {
+    it('projects one immutable reactive snapshot with the deprecated pending alias', () => {
+      const onInterruptStateChange = vi.fn()
+      const { result, flush } = renderInjectChat({
+        connection: createMockConnectionAdapter(),
+        initialResumeSnapshot: createInterruptResumeSnapshot(),
+        onInterruptStateChange,
+      })
+
+      expect(Object.isFrozen(result.interrupts())).toBe(true)
+      expect(result.pendingInterrupts()).toBe(result.interrupts())
+      expect(result.interrupts()[0]).toMatchObject({
+        id: 'staged-interrupt',
+        status: 'staged',
+      })
+      expect(result.interrupts()[1]).toMatchObject({
+        id: 'invalid-interrupt',
+        status: 'error',
+        error: { code: 'invalid-payload' },
+      })
+      expect(result.interruptErrors()).toEqual([])
+      expect(result.resuming()).toBe(false)
+      expect(result.interrupts()[0]).toEqual(
+        expect.objectContaining({
+          resolveInterrupt: expect.any(Function),
+          cancel: expect.any(Function),
+          clearResolution: expect.any(Function),
+        }),
+      )
+
+      result.resolveInterrupts(false)
+      TestBed.flushEffects()
+      flush()
+      expect(result.interruptErrors()[0]?.code).toBe(
+        'unsupported-bulk-operation',
+      )
+      expect(onInterruptStateChange).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          interrupts: result.interrupts(),
+          interruptErrors: result.interruptErrors(),
+        }),
+      )
+    })
+
+    it('delegates every root interrupt control to ChatClient', async () => {
+      const resolve = vi
+        .spyOn(ChatClient.prototype, 'resolveInterrupts')
+        .mockImplementation(() => {})
+      const cancel = vi
+        .spyOn(ChatClient.prototype, 'cancelInterrupts')
+        .mockImplementation(() => {})
+      const retry = vi
+        .spyOn(ChatClient.prototype, 'retryInterrupts')
+        .mockImplementation(() => {})
+      const unsafe = vi
+        .spyOn(ChatClient.prototype, 'resumeInterruptsUnsafe')
+        .mockResolvedValue(true)
+      const { result } = renderInjectChat({
+        connection: createMockConnectionAdapter(),
+      })
+      const resolver = () => undefined
+      const resume = [{ interruptId: 'one', status: 'cancelled' as const }]
+
+      result.resolveInterrupts(resolver)
+      result.cancelInterrupts()
+      result.retryInterrupts()
+      await expect(result.resumeInterruptsUnsafe(resume)).resolves.toBe(true)
+
+      expect(resolve).toHaveBeenCalledWith(resolver)
+      expect(cancel).toHaveBeenCalledOnce()
+      expect(retry).toHaveBeenCalledOnce()
+      expect(unsafe).toHaveBeenCalledWith(resume, undefined)
+    })
+  })
+
   it('initializes with default state', () => {
     const adapter = createMockConnectionAdapter()
     const { result } = renderInjectChat({ connection: adapter })
diff --git a/packages/ai-angular/tests/test-utils.ts b/packages/ai-angular/tests/test-utils.ts
index 9e217a942..b27b72497 100644
--- a/packages/ai-angular/tests/test-utils.ts
+++ b/packages/ai-angular/tests/test-utils.ts
@@ -7,6 +7,7 @@ import {
 import { injectChat } from '../src/inject-chat'
 import type { InjectChatOptions } from '../src/types'
 import type { InjectChatResult } from '../src/types'
+import type { ChatResumeSnapshotV2 } from '@tanstack/ai-client'
 
 export {
   createMockConnectionAdapter,
@@ -14,6 +15,80 @@ export {
   createToolCallChunks,
 } from '../../ai-client/tests/test-utils'
 
+export function createInterruptResumeSnapshot(): ChatResumeSnapshotV2 {
+  const pendingInterrupts = [
+    {
+      id: 'staged-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'staged-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+    {
+      id: 'invalid-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'invalid-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+  ]
+
+  return {
+    schemaVersion: 2,
+    resumeState: { threadId: 'thread-1', runId: 'run-1' },
+    pendingInterrupts,
+    interruptState: {
+      recoveryState: {
+        schemaVersion: 1,
+        state: 'pending',
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+        pendingInterrupts,
+      },
+      drafts: [
+        {
+          interruptId: 'staged-interrupt',
+          response: {
+            interruptId: 'staged-interrupt',
+            status: 'resolved',
+            payload: { answer: 42 },
+          },
+          status: 'staged',
+        },
+        {
+          interruptId: 'invalid-interrupt',
+          response: null,
+          status: 'error',
+          error: {
+            scope: 'item',
+            interruptId: 'invalid-interrupt',
+            code: 'invalid-payload',
+            message: 'Invalid persisted response',
+            source: 'client',
+            retryable: false,
+            threadId: 'thread-1',
+            interruptedRunId: 'run-1',
+            generation: 1,
+          },
+        },
+      ],
+    },
+  }
+}
+
 // Ensure TestBed is initialized in this module's scope, regardless of whether
 // the setup file's initialization was in a different module context (possible
 // when the Angular plugin creates separate ESM module instances for compiled
diff --git a/packages/ai-anthropic/tests/anthropic-adapter.test.ts b/packages/ai-anthropic/tests/anthropic-adapter.test.ts
index 43d3ded61..dd8ae2a3a 100644
--- a/packages/ai-anthropic/tests/anthropic-adapter.test.ts
+++ b/packages/ai-anthropic/tests/anthropic-adapter.test.ts
@@ -1,8 +1,12 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest'
 import {
+  InterruptPersistenceCapability,
   chat,
+  defineChatMiddleware,
+  provideInterruptPersistence,
   StreamProcessor,
   type Tool,
+  type InterruptPersistenceGateway,
   type StreamChunk,
   type UIMessage,
 } from '@tanstack/ai'
@@ -55,6 +59,43 @@ const weatherTool: Tool = {
   }),
 }
 
+const testInterruptGateway: InterruptPersistenceGateway = {
+  openInterruptBatch: async (input) => ({
+    generation: 1,
+    descriptors: input.descriptors,
+  }),
+  commitInterruptResolutions: async (input) => ({
+    status: 'committed',
+    continuationRunId: input.continuationRunId,
+  }),
+  getInterruptRecoveryState: async (input) => ({
+    schemaVersion: 1,
+    state: 'missing',
+    threadId: input.threadId,
+    interruptedRunId: input.interruptedRunId,
+    generation: input.knownGeneration,
+    pendingInterrupts: [],
+  }),
+}
+
+const testInterruptPersistence = defineChatMiddleware({
+  name: 'anthropic-test-interrupt-persistence',
+  provides: [InterruptPersistenceCapability],
+  setup(ctx) {
+    provideInterruptPersistence(ctx, testInterruptGateway)
+  },
+  async onChunk(_ctx, chunk) {
+    if (chunk.type === 'RUN_FINISHED' && chunk.outcome?.type === 'interrupt') {
+      await testInterruptGateway.openInterruptBatch({
+        threadId: chunk.threadId,
+        interruptedRunId: chunk.runId,
+        descriptors: chunk.outcome.interrupts,
+        bindings: [],
+      })
+    }
+  },
+})
+
 function createTextStream(text: string) {
   return (async function* () {
     yield {
@@ -1715,6 +1756,7 @@ describe('Anthropic stream processing', () => {
       adapter,
       messages: [{ role: 'user', content: 'Weather in Berlin?' }],
       tools: [weatherTool],
+      middleware: [testInterruptPersistence],
     })) {
       chunks.push(chunk)
     }
diff --git a/packages/ai-client/src/chat-client.ts b/packages/ai-client/src/chat-client.ts
index fc3a078cf..991ac6d7c 100644
--- a/packages/ai-client/src/chat-client.ts
+++ b/packages/ai-client/src/chat-client.ts
@@ -11,12 +11,18 @@ import {
   fetcherToConnectionAdapter,
   getChunkRunId,
   normalizeConnectionAdapter,
+  parseInterruptRecoveryState,
 } from './connection-adapters'
 import { ChatPersistenceController } from './chat-persistence-controller'
 import { ClearedStreamTracker } from './cleared-stream-tracker'
+import { InterruptManager } from './interrupt-manager'
 import type {
   AnyClientTool,
   ContentPart,
+  InterruptCommitResult,
+  InterruptRecoveryQuery,
+  InterruptRecoveryStateV1,
+  InterruptSubmissionError,
   ModelMessage,
   RunAgentResumeItem,
   StreamChunk,
@@ -35,18 +41,24 @@ import type {
   ChatDevtoolsBridgeOptions,
 } from './devtools'
 import type {
+  BoundInterrupts,
   ChatClientOptions,
   ChatClientState,
+  ChatContinuationLoader,
   ChatFetcher,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatPendingInterrupt,
   ChatResumeSnapshot,
   ChatResumeState,
   ConnectionStatus,
   MessagePart,
   MultimodalContent,
+  PersistedInterruptDraft,
   ToolCallPart,
   UIMessage,
 } from './types'
+import type { InterruptManagerSubmission } from './interrupt-manager'
 
 type ChatClientUpdateOptionsWithoutContext<
   TTools extends ReadonlyArray<AnyClientTool>,
@@ -66,8 +78,9 @@ type ChatClientUpdateOptionsWithoutContext<
   onSessionGeneratingChange?: (isGenerating: boolean) => void
   onResumeStateChange?: (
     resumeState: ChatResumeState | null,
-    pendingInterrupts: Array<ChatPendingInterrupt>,
+    pendingInterrupts: BoundInterrupts<TTools>,
   ) => void
+  onInterruptStateChange?: (state: ChatInterruptState<TTools>) => void
   onCustomEvent?: (
     eventType: string,
     data: unknown,
@@ -98,6 +111,110 @@ function resolveTransport(transport: {
   throw new Error('ChatClient: either `connection` or `fetcher` is required.')
 }
 
+function replayContinuationRunId(chunk: StreamChunk): string | undefined {
+  if (chunk.type !== 'RUN_FINISHED' || !('result' in chunk)) return undefined
+  const result: unknown = chunk.result
+  if (result === null || typeof result !== 'object' || Array.isArray(result)) {
+    return undefined
+  }
+  if (!('replayed' in result) || result.replayed !== true) return undefined
+  return 'continuationRunId' in result &&
+    typeof result.continuationRunId === 'string'
+    ? result.continuationRunId
+    : undefined
+}
+
+interface ParsedPersistedInterruptState {
+  recoveryState: InterruptRecoveryStateV1
+  drafts: ReadonlyArray<PersistedInterruptDraft>
+}
+
+interface PersistedRecoveryRequest {
+  query: InterruptRecoveryQuery
+  drafts: ReadonlyArray<PersistedInterruptDraft>
+  expectedGeneration?: number
+  expectedInterruptIds: ReadonlyArray<string>
+}
+
+function readResumeState(
+  snapshot: ChatResumeSnapshot,
+): ChatResumeState | undefined {
+  const value: unknown = snapshot
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    !('resumeState' in value)
+  ) {
+    return undefined
+  }
+  const resumeState = value.resumeState
+  if (
+    resumeState === null ||
+    typeof resumeState !== 'object' ||
+    !('threadId' in resumeState) ||
+    typeof resumeState.threadId !== 'string' ||
+    resumeState.threadId.length === 0 ||
+    !('runId' in resumeState) ||
+    typeof resumeState.runId !== 'string' ||
+    resumeState.runId.length === 0
+  ) {
+    return undefined
+  }
+  return { threadId: resumeState.threadId, runId: resumeState.runId }
+}
+
+function readPersistedInterruptState(
+  snapshot: ChatResumeSnapshot,
+): ParsedPersistedInterruptState | undefined {
+  if (snapshot.schemaVersion !== 2) {
+    return undefined
+  }
+  const interruptStateValue: unknown = snapshot.interruptState
+  if (
+    interruptStateValue === undefined ||
+    interruptStateValue === null ||
+    typeof interruptStateValue !== 'object' ||
+    Array.isArray(interruptStateValue)
+  ) {
+    return undefined
+  }
+  const interruptState = interruptStateValue as Record<string, unknown>
+  let recoveryState: InterruptRecoveryStateV1
+  try {
+    recoveryState = parseInterruptRecoveryState(interruptState.recoveryState)
+  } catch {
+    return undefined
+  }
+  const drafts = interruptState.drafts
+  if (
+    recoveryState.threadId !== snapshot.resumeState.threadId ||
+    recoveryState.interruptedRunId !== snapshot.resumeState.runId ||
+    !Array.isArray(drafts)
+  ) {
+    return undefined
+  }
+  if (
+    !drafts.every(
+      (draft) =>
+        draft !== null &&
+        typeof draft === 'object' &&
+        typeof draft.interruptId === 'string' &&
+        ['pending', 'validating', 'staged', 'submitting', 'error'].includes(
+          draft.status,
+        ) &&
+        'response' in draft &&
+        (draft.error === undefined ||
+          (draft.error !== null && typeof draft.error === 'object')),
+    )
+  ) {
+    return undefined
+  }
+  return {
+    recoveryState,
+    drafts: drafts as ReadonlyArray<PersistedInterruptDraft>,
+  }
+}
+
 export class ChatClient<
   TTools extends ReadonlyArray<AnyClientTool> = any,
   TContext = unknown,
@@ -118,15 +235,23 @@ export class ChatClient<
   // run, so approvals/client-tool results can be sent back. Cleared when the
   // run terminates. This is STATE (interrupt) resume, not delivery/cursor.
   private lastResume: ChatResumeState | null = null
-  private pendingInterrupts: Array<ChatPendingInterrupt> = []
-  private pendingInterruptRunId: string | null = null
-  private readonly pendingInterruptResumeItems = new Map<
-    string,
-    RunAgentResumeItem
-  >()
+  private readonly interruptManager: InterruptManager<TTools>
+  private readonly continuationLoader: ChatContinuationLoader | undefined
+  private activeInterruptSubmission: InterruptManagerSubmission | undefined
+  private pendingInterruptReplayRunId: string | undefined
+  private interruptSubmissionFailure:
+    | {
+        errors: ReadonlyArray<InterruptSubmissionError>
+        recovery?: InterruptRecoveryStateV1
+      }
+    | undefined
+  private readonly joinedRunWaiters = new Map<string, () => void>()
+  private readonly recoveryReady: boolean
+  private pendingInitialRecovery: InterruptRecoveryStateV1 | undefined
+  private pendingPersistedRecovery: PersistedRecoveryRequest | undefined
   // When set, the next streamResponse() continues this interrupted run instead
   // of starting a fresh run (consumed once).
-  private pendingResumeRunId: string | null = null
+  private pendingResumeParentRunId: string | null = null
   private pendingResumeThreadId: string | null = null
   private pendingResumeItems: Array<RunAgentResumeItem> | null = null
   private activeResumeThreadId: string | null = null
@@ -190,8 +315,9 @@ export class ChatClient<
       onSessionGeneratingChange: (isGenerating: boolean) => void
       onResumeStateChange: (
         resumeState: ChatResumeState | null,
-        pendingInterrupts: Array<ChatPendingInterrupt>,
+        pendingInterrupts: BoundInterrupts<TTools>,
       ) => void
+      onInterruptStateChange: (state: ChatInterruptState<TTools>) => void
       onCustomEvent: (
         eventType: string,
         data: unknown,
@@ -243,10 +369,19 @@ export class ChatClient<
         onSessionGeneratingChange:
           options.onSessionGeneratingChange || (() => {}),
         onResumeStateChange: options.onResumeStateChange || (() => {}),
+        onInterruptStateChange: options.onInterruptStateChange || (() => {}),
         onCustomEvent: options.onCustomEvent || (() => {}),
       },
     }
 
+    this.interruptManager = new InterruptManager({
+      ...(options.tools !== undefined ? { tools: options.tools } : {}),
+      submit: (submission) => this.submitInterruptBatch(submission),
+      recover: (state) => this.recoverInterrupts(state),
+      onChange: () => this.notifyResumeStateChange(),
+    })
+    this.continuationLoader = options.continuationLoader
+
     this.persistenceController = new ChatPersistenceController({
       chatId: this.uniqueId,
       threadId: this.threadId,
@@ -486,6 +621,17 @@ export class ChatClient<
     if (!options.initialResumeSnapshot) {
       this.persistenceController.hydrateResumeSnapshot(storedResumeSnapshot)
     }
+    this.recoveryReady = true
+    if (this.pendingInitialRecovery !== undefined) {
+      const recovery = this.pendingInitialRecovery
+      this.pendingInitialRecovery = undefined
+      this.startInitialRecovery(recovery)
+    }
+    if (this.pendingPersistedRecovery !== undefined) {
+      const recovery = this.pendingPersistedRecovery
+      this.pendingPersistedRecovery = undefined
+      this.startPersistedRecovery(recovery)
+    }
   }
 
   /**
@@ -508,10 +654,80 @@ export class ChatClient<
   }
 
   private applyResumeSnapshot(snapshot: ChatResumeSnapshot): void {
-    this.lastResume = { ...snapshot.resumeState }
-    this.pendingInterrupts = [...(snapshot.pendingInterrupts ?? [])]
-    this.pendingInterruptRunId =
-      this.pendingInterrupts.length > 0 ? this.lastResume.runId : null
+    const resumeState = readResumeState(snapshot)
+    if (resumeState === undefined) {
+      this.interruptManager.reset()
+      return
+    }
+    this.lastResume = resumeState
+    const persistedState = readPersistedInterruptState(snapshot)
+    if (persistedState !== undefined) {
+      const { recoveryState, drafts } = persistedState
+      if (recoveryState.state === 'pending') {
+        this.interruptManager.hydrate({
+          threadId: recoveryState.threadId,
+          interruptedRunId: recoveryState.interruptedRunId,
+          generation: recoveryState.generation,
+          interrupts: recoveryState.pendingInterrupts,
+        })
+        this.interruptManager.restorePersistedDrafts(drafts)
+        this.schedulePersistedRecovery({
+          query: {
+            threadId: recoveryState.threadId,
+            interruptedRunId: recoveryState.interruptedRunId,
+            knownGeneration: recoveryState.generation,
+          },
+          drafts,
+          expectedGeneration: recoveryState.generation,
+          expectedInterruptIds: recoveryState.pendingInterrupts.map(
+            (interrupt) => interrupt.id,
+          ),
+        })
+        return
+      }
+      this.interruptManager.reset()
+      if (this.recoveryReady) {
+        this.startInitialRecovery(recoveryState)
+      } else {
+        this.pendingInitialRecovery = recoveryState
+      }
+      return
+    }
+    const pendingInterrupts = Array.isArray(snapshot.pendingInterrupts)
+      ? snapshot.pendingInterrupts
+      : []
+    if (pendingInterrupts.length === 0) {
+      this.interruptManager.reset()
+      return
+    }
+    const generation = this.interruptGeneration(pendingInterrupts)
+    this.interruptManager.hydrate({
+      threadId: resumeState.threadId,
+      interruptedRunId: resumeState.runId,
+      generation,
+      interrupts: pendingInterrupts,
+    })
+    this.schedulePersistedRecovery({
+      query: {
+        threadId: resumeState.threadId,
+        interruptedRunId: resumeState.runId,
+        knownGeneration: generation,
+      },
+      drafts: [],
+      expectedGeneration: generation,
+      expectedInterruptIds: pendingInterrupts.map((interrupt) => interrupt.id),
+    })
+  }
+
+  private schedulePersistedRecovery(request: PersistedRecoveryRequest): void {
+    if (this.connection.loadInterruptState === undefined) {
+      return
+    }
+    if (this.recoveryReady) {
+      this.startPersistedRecovery(request)
+    } else {
+      this.pendingPersistedRecovery = request
+    }
   }
 
   mountDevtools(): void {
@@ -585,6 +801,15 @@ export class ChatClient<
     if (chunk.type !== 'RUN_FINISHED' && chunk.type !== 'RUN_ERROR') {
       return
     }
+
+    if (this.activeInterruptSubmission) {
+      const continuationRunId = replayContinuationRunId(chunk)
+      if (continuationRunId !== undefined) {
+        this.pendingInterruptReplayRunId = continuationRunId
+        return
+      }
+      if (chunk.type === 'RUN_ERROR') return
+    }
     const runId = getChunkRunId(chunk)
     const threadId =
       'threadId' in chunk && typeof chunk.threadId === 'string'
@@ -600,10 +825,12 @@ export class ChatClient<
         threadId: threadId ?? this.threadId,
         runId: interruptedRunId,
       }
-      this.pendingInterruptRunId = interruptedRunId
-      this.pendingInterrupts = [...chunk.outcome.interrupts]
-      this.pendingInterruptResumeItems.clear()
-      this.notifyResumeStateChange()
+      this.interruptManager.hydrate({
+        threadId: this.lastResume.threadId,
+        interruptedRunId,
+        generation: this.interruptGeneration(chunk.outcome.interrupts),
+        interrupts: chunk.outcome.interrupts,
+      })
       return
     }
 
@@ -611,9 +838,6 @@ export class ChatClient<
     const isTrackedRunTerminal = Boolean(
       runId && this.lastResume?.runId === runId,
     )
-    const isPendingInterruptRunTerminal = Boolean(
-      runId && this.pendingInterruptRunId === runId,
-    )
     const isCurrentRunTerminal = Boolean(
       (runId && this.currentRunId === runId) ||
       (this.currentRunId && this.lastResume?.runId === this.currentRunId),
@@ -623,14 +847,12 @@ export class ChatClient<
     if (
       isRunlessSessionError ||
       isTrackedRunTerminal ||
-      isPendingInterruptRunTerminal ||
       isCurrentRunTerminal ||
       isCurrentStreamTerminal
     ) {
       this.lastResume = null
-      this.pendingInterrupts = []
-      this.pendingInterruptRunId = null
-      this.pendingInterruptResumeItems.clear()
+      this.interruptManager.reset()
+      return
     }
     this.notifyResumeStateChange()
   }
@@ -644,22 +866,343 @@ export class ChatClient<
     return this.lastResume ? { ...this.lastResume } : null
   }
 
-  getPendingInterrupts(): Array<ChatPendingInterrupt> {
-    return [...this.pendingInterrupts]
+  getInterruptState(): ChatInterruptState<TTools> {
+    return this.interruptManager.getState()
   }
 
-  resumeInterrupts(
+  getInterrupts(): BoundInterrupts<TTools> {
+    return this.interruptManager.getInterrupts()
+  }
+
+  /** @deprecated Use getInterrupts(). */
+  getPendingInterrupts(): BoundInterrupts<TTools> {
+    return this.interruptManager.getInterrupts()
+  }
+
+  resolveInterrupts(approved: boolean): void
+  resolveInterrupts(
+    resolver: (interrupt: ChatInterrupt<TTools>) => undefined,
+  ): void
+  resolveInterrupts(
+    resolution: boolean | ((interrupt: ChatInterrupt<TTools>) => undefined),
+  ): void {
+    if (typeof resolution === 'boolean') {
+      this.interruptManager.resolve(resolution)
+    } else {
+      this.interruptManager.resolve(resolution)
+    }
+  }
+
+  cancelInterrupts(): void {
+    this.interruptManager.cancel()
+  }
+
+  retryInterrupts(): void {
+    this.interruptManager.retry()
+  }
+
+  /** Unsafe low-level resume escape hatch. Prefer bound interrupt methods. */
+  resumeInterruptsUnsafe(
     resume: Array<RunAgentResumeItem>,
     state?: ChatResumeState,
   ): Promise<boolean> {
     const target = state ?? this.lastResume
     if (!target || this.isLoading) return Promise.resolve(false)
     this.pendingResumeThreadId = target.threadId
-    this.pendingResumeRunId = target.runId
+    this.pendingResumeParentRunId = target.runId
     this.pendingResumeItems = [...resume]
     return this.streamResponse()
   }
 
+  /** @deprecated Use bound interrupt methods or resumeInterruptsUnsafe(). */
+  resumeInterrupts(
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ): Promise<boolean> {
+    return this.resumeInterruptsUnsafe(resume, state)
+  }
+
+  private async submitInterruptBatch(
+    submission: InterruptManagerSubmission,
+  ): Promise<InterruptCommitResult | void> {
+    this.activeInterruptSubmission = submission
+    this.pendingInterruptReplayRunId = undefined
+    this.interruptSubmissionFailure = undefined
+    const resumed = await this.resumeInterruptsUnsafe(
+      [...submission.resolutions],
+      {
+        threadId: submission.threadId,
+        runId: submission.interruptedRunId,
+      },
+    ).finally(() => {
+      this.activeInterruptSubmission = undefined
+    })
+    const replayRunId = this.takeInterruptReplayRunId()
+    const failure = this.takeInterruptSubmissionFailure()
+    if (failure?.recovery !== undefined) {
+      return { status: 'conflict', authoritativeState: failure.recovery }
+    }
+    if (failure !== undefined) {
+      throw { errors: failure.errors }
+    }
+    if (replayRunId !== undefined) {
+      await this.joinContinuationRun(replayRunId, {
+        schemaVersion: 1,
+        state: 'committed',
+        threadId: submission.threadId,
+        interruptedRunId: submission.interruptedRunId,
+        generation: submission.generation,
+        pendingInterrupts: [],
+        committed: {
+          fingerprint: submission.fingerprint,
+          continuationRunId: replayRunId,
+          committedAt: new Date().toISOString(),
+        },
+      })
+      return { status: 'replayed', continuationRunId: replayRunId }
+    }
+    if (!resumed) {
+      throw new Error('Interrupt continuation could not be started.')
+    }
+  }
+
+  private takeInterruptSubmissionFailure():
+    | {
+        errors: ReadonlyArray<InterruptSubmissionError>
+        recovery?: InterruptRecoveryStateV1
+      }
+    | undefined {
+    const failure = this.interruptSubmissionFailure
+    this.interruptSubmissionFailure = undefined
+    return failure
+  }
+
+  private takeInterruptReplayRunId(): string | undefined {
+    const runId = this.pendingInterruptReplayRunId
+    this.pendingInterruptReplayRunId = undefined
+    return runId
+  }
+
+  private async recoverInterrupts(
+    authoritativeState?: InterruptRecoveryStateV1,
+  ): Promise<void> {
+    let state = authoritativeState
+    if (state === undefined) {
+      const current = this.interruptManager.getRecoveryState()
+      if (
+        current === undefined ||
+        this.connection.loadInterruptState === undefined
+      ) {
+        this.interruptManager.reportRecoveryError(
+          'recovery-unavailable',
+          'Authoritative interrupt recovery is unavailable for this connection.',
+          current,
+        )
+        return
+      }
+      try {
+        state = await this.connection.loadInterruptState({
+          threadId: current.threadId,
+          interruptedRunId: current.interruptedRunId,
+          knownGeneration: current.generation,
+        })
+      } catch {
+        this.interruptManager.reportRecoveryError(
+          'recovery-unavailable',
+          'Authoritative interrupt recovery failed.',
+          current,
+        )
+        return
+      }
+    }
+
+    if (state.state === 'pending') {
+      this.lastResume = {
+        threadId: state.threadId,
+        runId: state.interruptedRunId,
+      }
+      this.interruptManager.hydrate({
+        threadId: state.threadId,
+        interruptedRunId: state.interruptedRunId,
+        generation: state.generation,
+        interrupts: state.pendingInterrupts,
+      })
+      return
+    }
+
+    if (state.state === 'committed' || state.state === 'legacy-committed') {
+      const continuationRunId = state.committed?.continuationRunId
+      if (continuationRunId === undefined) {
+        this.interruptManager.reportRecoveryError(
+          'recovery-unavailable',
+          'The committed interrupt state has no continuation run to join.',
+          state,
+        )
+        return
+      }
+      await this.joinContinuationRun(continuationRunId, state, {
+        preserveRootErrors: this.interruptManager
+          .getInterruptErrors()
+          .some((error) => error.code === 'conflict'),
+      })
+      return
+    }
+
+    this.interruptManager.reportRecoveryError(
+      state.state === 'expired' ? 'expired' : 'stale',
+      state.state === 'expired'
+        ? 'The interrupt batch has expired.'
+        : 'The interrupt batch no longer exists.',
+      state,
+    )
+  }
+
+  private startInitialRecovery(recoveryState: InterruptRecoveryStateV1): void {
+    // Constructors cannot await replay. The structured manager error keeps an
+    // unexpected async failure observable without turning hydration into an
+    // unhandled promise rejection.
+    void this.recoverInterrupts(recoveryState).catch(() => {
+      this.interruptManager.reportRecoveryError(
+        'recovery-unavailable',
+        'Initial interrupt recovery failed.',
+        recoveryState,
+      )
+    })
+  }
+
+  private startPersistedRecovery(request: PersistedRecoveryRequest): void {
+    void this.recoverPersistedInterrupts(request).catch(() => {
+      this.interruptManager.reportRecoveryError(
+        'recovery-unavailable',
+        'Persisted interrupt recovery failed.',
+        this.persistedRecoveryErrorState(request.query),
+      )
+    })
+  }
+
+  private async recoverPersistedInterrupts(
+    request: PersistedRecoveryRequest,
+  ): Promise<void> {
+    if (this.connection.loadInterruptState === undefined) {
+      this.interruptManager.reportRecoveryError(
+        'recovery-unavailable',
+        'Authoritative interrupt recovery is unavailable for this connection.',
+        this.persistedRecoveryErrorState(request.query),
+      )
+      return
+    }
+
+    let state: InterruptRecoveryStateV1
+    try {
+      state = parseInterruptRecoveryState(
+        await this.connection.loadInterruptState(request.query),
+      )
+      if (
+        state.threadId !== request.query.threadId ||
+        state.interruptedRunId !== request.query.interruptedRunId
+      ) {
+        throw new TypeError('Interrupt recovery correlation did not match.')
+      }
+    } catch {
+      this.interruptManager.reportRecoveryError(
+        'recovery-unavailable',
+        'Authoritative interrupt recovery failed.',
+        this.persistedRecoveryErrorState(request.query),
+      )
+      return
+    }
+
+    await this.recoverInterrupts(state)
+    if (
+      state.state === 'pending' &&
+      request.expectedGeneration === state.generation &&
+      request.expectedInterruptIds.length === state.pendingInterrupts.length &&
+      request.expectedInterruptIds.every(
+        (id, index) => state.pendingInterrupts[index]?.id === id,
+      )
+    ) {
+      this.interruptManager.restorePersistedDrafts(request.drafts)
+    }
+  }
+
+  private persistedRecoveryErrorState(
+    query: InterruptRecoveryQuery,
+  ): InterruptRecoveryStateV1 {
+    return {
+      schemaVersion: 1,
+      state: 'missing',
+      threadId: query.threadId,
+      interruptedRunId: query.interruptedRunId,
+      generation: query.knownGeneration,
+      pendingInterrupts: [],
+    }
+  }
+
+  private async joinContinuationRun(
+    continuationRunId: string,
+    recoveryState: InterruptRecoveryStateV1,
+    options?: { preserveRootErrors?: boolean },
+  ): Promise<void> {
+    try {
+      if (this.connection.joinRun !== undefined) {
+        this.ensureSubscription()
+        const processed = new Promise<void>((resolve) => {
+          this.joinedRunWaiters.set(continuationRunId, resolve)
+        })
+        await this.connection.joinRun(continuationRunId)
+        await processed
+      } else if (this.continuationLoader !== undefined) {
+        for await (const chunk of this.continuationLoader(continuationRunId)) {
+          await this.processIncomingChunk(chunk)
+        }
+      } else {
+        this.interruptManager.reportRecoveryError(
+          'recovery-unavailable',
+          'A continuation loader or joinRun connection operation is required.',
+          recoveryState,
+        )
+        return
+      }
+    } catch {
+      this.joinedRunWaiters.delete(continuationRunId)
+      this.interruptManager.reportRecoveryError(
+        'recovery-unavailable',
+        'The committed continuation run could not be replayed.',
+        recoveryState,
+      )
+      return
+    }
+    this.lastResume = null
+    this.interruptManager.reset({
+      preserveRootErrors: options?.preserveRootErrors === true,
+    })
+  }
+
+  private interruptGeneration(
+    interrupts: ReadonlyArray<ChatPendingInterrupt>,
+  ): number {
+    let generation: number | undefined
+    for (const interrupt of interrupts) {
+      const candidate: unknown =
+        interrupt.metadata?.['tanstack:interruptBinding']
+      if (
+        candidate === null ||
+        typeof candidate !== 'object' ||
+        !('generation' in candidate) ||
+        typeof candidate.generation !== 'number' ||
+        !Number.isInteger(candidate.generation) ||
+        candidate.generation < 0
+      ) {
+        return 0
+      }
+      if (generation !== undefined && generation !== candidate.generation) {
+        return 0
+      }
+      generation = candidate.generation
+    }
+    return generation ?? 0
+  }
+
   private generateUniqueId(prefix: string): string {
     return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
   }
@@ -697,13 +1240,31 @@ export class ChatClient<
 
   private notifyResumeStateChange(): void {
     const resumeState = this.getResumeState()
-    const pendingInterrupts = this.getPendingInterrupts()
+    const pendingInterrupts = [...this.interruptManager.getDescriptors()]
+    const recoveryState = this.interruptManager.getRecoveryState()
     this.persistenceController.persistResumeSnapshot(
-      resumeState ? { resumeState, pendingInterrupts } : null,
+      resumeState
+        ? {
+            schemaVersion: 2,
+            resumeState,
+            pendingInterrupts,
+            ...(recoveryState !== undefined
+              ? {
+                  interruptState: {
+                    recoveryState,
+                    drafts: this.interruptManager.getPersistedDrafts(),
+                  },
+                }
+              : {}),
+          }
+        : null,
     )
     this.callbacksRef.current.onResumeStateChange(
       resumeState,
-      pendingInterrupts,
+      this.interruptManager.getInterrupts(),
+    )
+    this.callbacksRef.current.onInterruptStateChange(
+      this.interruptManager.getState(),
     )
   }
 
@@ -859,33 +1420,75 @@ export class ChatClient<
     const stream = this.connection.subscribe(signal)
     for await (const chunk of stream) {
       if (signal.aborted) break
-      if (this.connectionStatus === 'connecting') {
-        this.setConnectionStatus('connected')
+      await this.processIncomingChunk(chunk)
+    }
+  }
+
+  private async processIncomingChunk(chunk: StreamChunk): Promise<void> {
+    if (
+      chunk.type === 'RUN_ERROR' &&
+      this.isActiveInterruptSubmissionFailure(chunk)
+    ) {
+      this.interruptSubmissionFailure = {
+        errors: chunk['tanstack:interruptErrors'] ?? [],
+        ...(chunk['tanstack:interruptRecovery'] !== undefined
+          ? { recovery: chunk['tanstack:interruptRecovery'] }
+          : {}),
       }
-      const shouldIgnore = this.clearedStreamTracker.shouldIgnoreChunk(chunk)
-      if (shouldIgnore) {
-        if (chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR') {
-          if (getChunkRunId(chunk)) {
-            this.updateRunLifecycle(chunk, { resolveProcessing: false })
-          }
-          this.retireIgnoredClearedTerminalChunk(chunk)
+    }
+    if (this.connectionStatus === 'connecting') {
+      this.setConnectionStatus('connected')
+    }
+    const shouldIgnore = this.clearedStreamTracker.shouldIgnoreChunk(chunk)
+    if (shouldIgnore) {
+      if (chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR') {
+        if (getChunkRunId(chunk)) {
+          this.updateRunLifecycle(chunk, { resolveProcessing: false })
         }
-        continue
+        this.retireIgnoredClearedTerminalChunk(chunk)
+        this.resolveJoinedRun(chunk)
       }
-      this.callbacksRef.current.onChunk(chunk)
-      this.devtoolsBridge.observeChunk(chunk)
-      this.processor.processChunk(chunk)
-      // Run lifecycle (active-run tracking, session-generating state, and
-      // processing resolution for RUN_FINISHED / RUN_ERROR) is handled in a
-      // single place so the ignored-chunk path above and this path can't
-      // diverge. RUN_ERROR carries its runId via the AG-UI passthrough so a
-      // per-run error only clears that run, while a runId-less RUN_ERROR is
-      // treated as a session-level error that clears every active run.
-      this.updateRunLifecycle(chunk)
-      this.observeInterruptState(chunk)
-      // Yield control back to event loop for UI updates
-      await new Promise((resolve) => setTimeout(resolve, 0))
+      return
     }
+    this.callbacksRef.current.onChunk(chunk)
+    this.devtoolsBridge.observeChunk(chunk)
+    this.processor.processChunk(chunk)
+    this.updateRunLifecycle(chunk)
+    this.observeInterruptState(chunk)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    this.resolveJoinedRun(chunk)
+  }
+
+  private isActiveInterruptSubmissionFailure(
+    chunk: Extract<StreamChunk, { type: 'RUN_ERROR' }>,
+  ): boolean {
+    const submission = this.activeInterruptSubmission
+    const errors = chunk['tanstack:interruptErrors']
+    if (!submission || !errors || errors.length === 0) return false
+    const runId = getChunkRunId(chunk)
+    if (runId !== undefined && runId !== this.currentRunId) return false
+    if (
+      typeof chunk.threadId === 'string' &&
+      chunk.threadId !== submission.threadId
+    ) {
+      return false
+    }
+    return errors.every(
+      (error) =>
+        error.threadId === submission.threadId &&
+        error.interruptedRunId === submission.interruptedRunId &&
+        error.generation === submission.generation,
+    )
+  }
+
+  private resolveJoinedRun(chunk: StreamChunk): void {
+    if (chunk.type !== 'RUN_FINISHED' && chunk.type !== 'RUN_ERROR') return
+    const runId = getChunkRunId(chunk)
+    if (runId === undefined) return
+    const resolve = this.joinedRunWaiters.get(runId)
+    if (resolve === undefined) return
+    this.joinedRunWaiters.delete(runId)
+    resolve()
   }
 
   /**
@@ -964,7 +1567,7 @@ export class ChatClient<
     if (emptyMessage || this.isLoading) {
       return
     }
-    if (this.pendingInterrupts.length > 0 && this.lastResume) {
+    if (this.interruptManager.getInterrupts().length > 0 && this.lastResume) {
       throw new Error(
         'ChatClient: cannot send normal input while pending interrupts exist. Use resumeInterrupts() instead.',
       )
@@ -1004,7 +1607,7 @@ export class ChatClient<
    */
   async append(message: UIMessage | ModelMessage): Promise<void> {
     this.mountDevtools()
-    if (this.pendingInterrupts.length > 0 && this.lastResume) {
+    if (this.interruptManager.getInterrupts().length > 0 && this.lastResume) {
       throw new Error(
         'ChatClient: cannot append normal input while pending interrupts exist. Use resumeInterrupts() instead.',
       )
@@ -1051,20 +1654,15 @@ export class ChatClient<
 
     // Track generation so a superseded stream's cleanup doesn't clobber the new one
     const generation = ++this.streamGeneration
-    // Resuming an interrupt reuses the original runId so the server continues
-    // that run with the resume decisions.
+    // Native interrupt continuation is a fresh child run. The interrupted run
+    // is carried as parentRunId and the complete resolution batch as resume.
     const resumeThreadId = this.pendingResumeThreadId
-    const resumeRunId = this.pendingResumeRunId
+    const resumeParentRunId = this.pendingResumeParentRunId
     const resumeItems = this.pendingResumeItems
-    const isResumeRequest = Boolean(
-      resumeThreadId || resumeRunId || resumeItems,
-    )
     this.pendingResumeThreadId = null
-    this.pendingResumeRunId = null
+    this.pendingResumeParentRunId = null
     this.pendingResumeItems = null
-    const runId =
-      resumeRunId ??
-      `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
     this.currentRunId = runId
     this.activeResumeThreadId = resumeThreadId ?? this.threadId
     this.activeResumeRunId = runId
@@ -1086,7 +1684,7 @@ export class ChatClient<
 
     try {
       // Get UIMessages with parts (preserves approval state and client tool results)
-      const messages = isResumeRequest ? [] : this.processor.getMessages()
+      const messages = this.processor.getMessages()
       const clientTools = new Map(this.clientToolsRef.current)
       const runtimeContext = this.context
 
@@ -1149,6 +1747,9 @@ export class ChatClient<
       const runContext = {
         threadId: resumeThreadId ?? this.threadId,
         runId,
+        ...(resumeParentRunId !== null
+          ? { parentRunId: resumeParentRunId }
+          : {}),
         clientTools: Array.from(clientTools.values()).map((t) => ({
           name: t.name,
           description: t.description,
@@ -1400,13 +2001,10 @@ export class ChatClient<
     this.processor.clearMessages()
     this.persistenceController.removeMessages()
     this.lastResume = null
-    this.pendingInterrupts = []
-    this.pendingInterruptRunId = null
-    this.pendingInterruptResumeItems.clear()
+    this.interruptManager.reset()
     this.pendingResumeThreadId = null
-    this.pendingResumeRunId = null
+    this.pendingResumeParentRunId = null
     this.pendingResumeItems = null
-    this.notifyResumeStateChange()
     this.setError(undefined)
     this.events.messagesCleared()
   }
@@ -1424,6 +2022,17 @@ export class ChatClient<
     clientTool: AnyClientTool | undefined,
     context?: ChatClientRunEventContext,
   ): Promise<void> {
+    if (
+      this.interruptManager.resolveClientToolOutput(
+        result.toolCallId,
+        result.state === 'output-error'
+          ? { error: result.errorText || 'Tool execution failed' }
+          : result.output,
+      )
+    ) {
+      return
+    }
+
     if (clientTool && result.state !== 'output-error') {
       try {
         result = {
@@ -1459,35 +2068,6 @@ export class ChatClient<
         : undefined,
     )
 
-    const pendingInterrupt = this.pendingInterrupts.find(
-      (interrupt) =>
-        interrupt.toolCallId === result.toolCallId ||
-        interrupt.id === result.toolCallId,
-    )
-    if (pendingInterrupt && this.lastResume) {
-      const resumeItem: RunAgentResumeItem = {
-        interruptId: pendingInterrupt.id,
-        status: 'resolved',
-        payload:
-          result.state === 'output-error'
-            ? { error: result.errorText || 'Tool execution failed' }
-            : result.output,
-      }
-      const resumeItems = this.collectPendingInterruptResumeItems(resumeItem)
-      if (!resumeItems) {
-        return
-      }
-      if (this.isLoading) {
-        this.queuePostStreamAction(async () => {
-          await this.resumeInterrupts(resumeItems)
-        })
-        return
-      }
-
-      await this.resumeInterrupts(resumeItems)
-      return
-    }
-
     // If stream is in progress, queue continuation check for after it ends
     if (this.isLoading) {
       this.queuePostStreamAction(() => this.checkForContinuation())
@@ -1515,9 +2095,14 @@ export class ChatClient<
     id: string // approval.id, not toolCallId
     approved: boolean
   }): Promise<void> {
-    const pendingInterrupt = this.pendingInterrupts.find(
-      (interrupt) => interrupt.id === response.id,
-    )
+    if (
+      this.interruptManager.resolveToolApprovalDecision(
+        response.id,
+        response.approved,
+      )
+    ) {
+      return
+    }
     // Find the tool call ID from the approval ID
     const messages = this.processor.getMessages()
     let foundToolCallId: string | undefined
@@ -1545,25 +2130,6 @@ export class ChatClient<
     this.processor.addToolApprovalResponse(response.id, response.approved)
     this.devtoolsBridge.emitSnapshot()
 
-    if (pendingInterrupt && this.lastResume) {
-      const resumeItems = this.collectPendingInterruptResumeItems({
-        interruptId: response.id,
-        status: response.approved ? 'resolved' : 'cancelled',
-        payload: { approved: response.approved },
-      })
-      if (!resumeItems) {
-        return
-      }
-      if (this.isLoading) {
-        this.queuePostStreamAction(async () => {
-          await this.resumeInterrupts(resumeItems)
-        })
-        return
-      }
-      await this.resumeInterrupts(resumeItems)
-      return
-    }
-
     // If stream is in progress, queue continuation check for after it ends
     if (this.isLoading) {
       this.queuePostStreamAction(() => this.checkForContinuation())
@@ -1573,23 +2139,6 @@ export class ChatClient<
     await this.checkForContinuation()
   }
 
-  private collectPendingInterruptResumeItems(
-    resumeItem: RunAgentResumeItem,
-  ): Array<RunAgentResumeItem> | null {
-    this.pendingInterruptResumeItems.set(resumeItem.interruptId, resumeItem)
-    const resumeItems: Array<RunAgentResumeItem> = []
-    for (const interrupt of this.pendingInterrupts) {
-      const answeredInterrupt = this.pendingInterruptResumeItems.get(
-        interrupt.id,
-      )
-      if (!answeredInterrupt) {
-        return null
-      }
-      resumeItems.push(answeredInterrupt)
-    }
-    return resumeItems
-  }
-
   /**
    * Queue an action to be executed after the current stream ends
    */
@@ -1775,6 +2324,7 @@ export class ChatClient<
       this.context = options.context
     }
     if (options.tools !== undefined) {
+      this.interruptManager.updateTools(options.tools)
       this.clientToolsRef.current = new Map()
       for (const tool of options.tools) {
         this.clientToolsRef.current.set(tool.name, tool)
@@ -1810,6 +2360,10 @@ export class ChatClient<
       this.callbacksRef.current.onResumeStateChange =
         options.onResumeStateChange
     }
+    if (options.onInterruptStateChange !== undefined) {
+      this.callbacksRef.current.onInterruptStateChange =
+        options.onInterruptStateChange
+    }
     if (options.onCustomEvent !== undefined) {
       this.callbacksRef.current.onCustomEvent = options.onCustomEvent
     }
diff --git a/packages/ai-client/src/chat-persistence-controller.ts b/packages/ai-client/src/chat-persistence-controller.ts
index 91eabb3fe..847a9b85f 100644
--- a/packages/ai-client/src/chat-persistence-controller.ts
+++ b/packages/ai-client/src/chat-persistence-controller.ts
@@ -173,6 +173,21 @@ export class ChatPersistenceController<
     this.resumeGeneration++
     this.desiredResumeSnapshot = snapshot
       ? {
+          ...(snapshot.schemaVersion === 2
+            ? {
+                schemaVersion: 2 as const,
+                ...(snapshot.interruptState !== undefined
+                  ? {
+                      interruptState: {
+                        recoveryState: snapshot.interruptState.recoveryState,
+                        drafts: [...snapshot.interruptState.drafts],
+                      },
+                    }
+                  : {}),
+              }
+            : snapshot.schemaVersion === 1
+              ? { schemaVersion: 1 as const }
+              : {}),
           resumeState: { ...snapshot.resumeState },
           pendingInterrupts: [...(snapshot.pendingInterrupts ?? [])],
         }
diff --git a/packages/ai-client/src/connection-adapters.ts b/packages/ai-client/src/connection-adapters.ts
index 8f19d255b..a5de0824e 100644
--- a/packages/ai-client/src/connection-adapters.ts
+++ b/packages/ai-client/src/connection-adapters.ts
@@ -5,6 +5,9 @@ import {
 } from './response-stream'
 import { parseSseDataLine } from './sse-utils'
 import type {
+  Interrupt,
+  InterruptRecoveryQuery,
+  InterruptRecoveryStateV1,
   ModelMessage,
   RunAgentResumeItem,
   RunErrorEvent,
@@ -29,9 +32,13 @@ const chunkRunIds = new WeakMap<StreamChunk, string>()
  * run the connect wrapper stamped it with.
  */
 export function getChunkRunId(chunk: StreamChunk): string | undefined {
-  return 'runId' in chunk && typeof chunk.runId === 'string'
-    ? chunk.runId
-    : chunkRunIds.get(chunk)
+  const requestRunId = chunkRunIds.get(chunk)
+  return (
+    requestRunId ??
+    ('runId' in chunk && typeof chunk.runId === 'string'
+      ? chunk.runId
+      : undefined)
+  )
 }
 
 /**
@@ -376,6 +383,16 @@ export interface ConnectConnectionAdapter {
     abortSignal?: AbortSignal,
     runContext?: RunAgentInputContext,
   ) => AsyncIterable<StreamChunk>
+  /** Read-only replay of an existing continuation run. */
+  joinRun?: (
+    runId: string,
+    abortSignal?: AbortSignal,
+  ) => AsyncIterable<StreamChunk>
+  /** Explicit authoritative interrupt recovery operation. */
+  loadInterruptState?: (
+    query: InterruptRecoveryQuery,
+    abortSignal?: AbortSignal,
+  ) => Promise<InterruptRecoveryStateV1>
 }
 
 /**
@@ -408,6 +425,12 @@ export interface SubscribeConnectionAdapter {
     abortSignal?: AbortSignal,
     runContext?: RunAgentInputContext,
   ) => Promise<void>
+  /** Pumps a read-only continuation replay through subscribe(). */
+  joinRun?: (runId: string, abortSignal?: AbortSignal) => Promise<void>
+  loadInterruptState?: (
+    query: InterruptRecoveryQuery,
+    abortSignal?: AbortSignal,
+  ) => Promise<InterruptRecoveryStateV1>
 }
 
 /**
@@ -445,6 +468,14 @@ export function normalizeConnectionAdapter(
     return {
       subscribe: connection.subscribe.bind(connection),
       send: connection.send.bind(connection),
+      ...(connection.joinRun !== undefined
+        ? { joinRun: connection.joinRun.bind(connection) }
+        : {}),
+      ...(connection.loadInterruptState !== undefined
+        ? {
+            loadInterruptState: connection.loadInterruptState.bind(connection),
+          }
+        : {}),
     }
   }
 
@@ -541,7 +572,7 @@ export function normalizeConnectionAdapter(
             timestamp: Date.now(),
             finishReason: 'stop',
           }
-          push(synthetic)
+          push(synthetic, runContext?.runId)
         }
       } catch (err) {
         if (!abortSignal?.aborted && !hasTerminalEvent) {
@@ -560,11 +591,28 @@ export function normalizeConnectionAdapter(
             timestamp: Date.now(),
             message,
           }
-          push(synthetic)
+          push(synthetic, runContext?.runId)
         }
         throw err
       }
     },
+    ...(connection.joinRun !== undefined
+      ? {
+          async joinRun(runId: string, abortSignal?: AbortSignal) {
+            for await (const chunk of connection.joinRun?.(
+              runId,
+              abortSignal,
+            ) ?? []) {
+              push(chunk, runId)
+            }
+          },
+        }
+      : {}),
+    ...(connection.loadInterruptState !== undefined
+      ? {
+          loadInterruptState: connection.loadInterruptState.bind(connection),
+        }
+      : {}),
   }
 }
 
@@ -577,6 +625,195 @@ export interface FetchConnectionOptions {
   signal?: AbortSignal
   body?: Record<string, any>
   fetchClient?: typeof globalThis.fetch
+  /** Explicit authoritative interrupt recovery operation. */
+  interruptStateFetcher?: NonNullable<
+    ConnectConnectionAdapter['loadInterruptState']
+  >
+  /** Explicit read-only loader for a committed continuation run. */
+  continuationLoader?: NonNullable<ConnectConnectionAdapter['joinRun']>
+}
+
+export type InterruptStateFetcher = NonNullable<
+  ConnectConnectionAdapter['loadInterruptState']
+>
+
+export type InterruptContinuationLoader = NonNullable<
+  ConnectConnectionAdapter['joinRun']
+>
+
+export interface InterruptFetchOptions {
+  headers?: Record<string, string> | Headers
+  credentials?: RequestCredentials
+  signal?: AbortSignal
+  fetchClient?: typeof globalThis.fetch
+}
+
+function isUnknownRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isInterruptDescriptor(value: unknown): value is Interrupt {
+  if (!isUnknownRecord(value)) return false
+  if (typeof value.id !== 'string' || typeof value.reason !== 'string') {
+    return false
+  }
+  if (value.message !== undefined && typeof value.message !== 'string') {
+    return false
+  }
+  if (value.toolCallId !== undefined && typeof value.toolCallId !== 'string') {
+    return false
+  }
+  if (
+    value.responseSchema !== undefined &&
+    !isUnknownRecord(value.responseSchema)
+  ) {
+    return false
+  }
+  if (value.expiresAt !== undefined && typeof value.expiresAt !== 'string') {
+    return false
+  }
+  return value.metadata === undefined || isUnknownRecord(value.metadata)
+}
+
+function isResumeEntry(value: unknown): value is RunAgentResumeItem {
+  return (
+    isUnknownRecord(value) &&
+    typeof value.interruptId === 'string' &&
+    (value.status === 'resolved' || value.status === 'cancelled')
+  )
+}
+
+function isInterruptRecoveryStateName(
+  value: unknown,
+): value is InterruptRecoveryStateV1['state'] {
+  return (
+    typeof value === 'string' &&
+    ['pending', 'committed', 'expired', 'missing', 'legacy-committed'].includes(
+      value,
+    )
+  )
+}
+
+/** @internal Runtime boundary parser shared by persistence and fetch recovery. */
+export function parseInterruptRecoveryState(
+  value: unknown,
+): InterruptRecoveryStateV1 {
+  if (
+    !isUnknownRecord(value) ||
+    value.schemaVersion !== 1 ||
+    !isInterruptRecoveryStateName(value.state) ||
+    typeof value.threadId !== 'string' ||
+    value.threadId.length === 0 ||
+    typeof value.interruptedRunId !== 'string' ||
+    value.interruptedRunId.length === 0 ||
+    typeof value.generation !== 'number' ||
+    !Number.isSafeInteger(value.generation) ||
+    value.generation < 0 ||
+    !Array.isArray(value.pendingInterrupts) ||
+    !value.pendingInterrupts.every(isInterruptDescriptor)
+  ) {
+    throw new TypeError('Invalid interrupt recovery response.')
+  }
+  let committed: InterruptRecoveryStateV1['committed']
+  if (value.committed !== undefined) {
+    if (
+      !isUnknownRecord(value.committed) ||
+      typeof value.committed.fingerprint !== 'string' ||
+      typeof value.committed.committedAt !== 'string' ||
+      (value.committed.continuationRunId !== undefined &&
+        typeof value.committed.continuationRunId !== 'string') ||
+      (value.committed.resolutions !== undefined &&
+        (!Array.isArray(value.committed.resolutions) ||
+          !value.committed.resolutions.every(isResumeEntry)))
+    ) {
+      throw new TypeError('Invalid interrupt recovery response.')
+    }
+    committed = {
+      fingerprint: value.committed.fingerprint,
+      committedAt: value.committed.committedAt,
+      ...(value.committed.continuationRunId === undefined
+        ? {}
+        : { continuationRunId: value.committed.continuationRunId }),
+      ...(value.committed.resolutions === undefined
+        ? {}
+        : { resolutions: value.committed.resolutions }),
+    }
+  }
+  return {
+    schemaVersion: 1,
+    state: value.state,
+    threadId: value.threadId,
+    interruptedRunId: value.interruptedRunId,
+    generation: value.generation,
+    pendingInterrupts: value.pendingInterrupts,
+    ...(typeof value.submissionId === 'string'
+      ? { submissionId: value.submissionId }
+      : {}),
+    ...(typeof value.continuationRunId === 'string'
+      ? { continuationRunId: value.continuationRunId }
+      : {}),
+    ...(committed === undefined ? {} : { committed }),
+  }
+}
+
+/** Create an authoritative interrupt-state fetcher for an explicit endpoint. */
+export function createInterruptStateFetcher(
+  url: string | (() => string),
+  options: InterruptFetchOptions = {},
+): InterruptStateFetcher {
+  return async (query, abortSignal) => {
+    const resolvedUrl = typeof url === 'function' ? url() : url
+    const requestUrl = withSearchParams(resolvedUrl, {
+      threadId: query.threadId,
+      interruptedRunId: query.interruptedRunId,
+      knownGeneration: String(query.knownGeneration),
+    })
+    const response = await (options.fetchClient ?? fetch)(requestUrl, {
+      method: 'POST',
+      headers: mergeHeaders(options.headers),
+      credentials: options.credentials ?? 'same-origin',
+      ...((abortSignal ?? options.signal) === undefined
+        ? {}
+        : { signal: abortSignal ?? options.signal }),
+    })
+    if (!response.ok) {
+      throw new Error(
+        `Interrupt recovery request failed with status ${response.status}.`,
+      )
+    }
+    const state = parseInterruptRecoveryState(await response.json())
+    if (
+      state.threadId !== query.threadId ||
+      state.interruptedRunId !== query.interruptedRunId
+    ) {
+      throw new TypeError('Invalid interrupt recovery response correlation.')
+    }
+    return state
+  }
+}
+
+/** Create a read-only continuation loader for an explicit endpoint. */
+export function createInterruptContinuationLoader(
+  url: string | (() => string),
+  options: InterruptFetchOptions = {},
+): InterruptContinuationLoader {
+  return async function* (runId, abortSignal) {
+    const resolvedUrl = typeof url === 'function' ? url() : url
+    const requestUrl = withSearchParams(resolvedUrl, {
+      offset: '-1',
+      runId,
+    })
+    yield* resumableServerSentEvents(
+      options.fetchClient ?? fetch,
+      requestUrl,
+      {
+        method: 'GET',
+        headers: mergeHeaders(options.headers),
+        credentials: options.credentials ?? 'same-origin',
+      },
+      abortSignal ?? options.signal,
+    )
+  }
 }
 
 /**
@@ -726,6 +963,14 @@ export function fetchServerSentEvents(
       const resolvedOptions =
         typeof options === 'function' ? await options() : options
 
+      if (resolvedOptions.continuationLoader !== undefined) {
+        yield* resolvedOptions.continuationLoader(
+          runId,
+          abortSignal ?? resolvedOptions.signal,
+        )
+        return
+      }
+
       const joinUrl = withSearchParams(resolvedUrl, {
         offset: '-1',
         runId,
@@ -748,6 +993,19 @@ export function fetchServerSentEvents(
         signal,
       )
     },
+    async loadInterruptState(query, abortSignal) {
+      const resolvedOptions =
+        typeof options === 'function' ? await options() : options
+      if (resolvedOptions.interruptStateFetcher === undefined) {
+        throw new Error(
+          'Interrupt recovery requires an explicit interruptStateFetcher.',
+        )
+      }
+      return resolvedOptions.interruptStateFetcher(
+        query,
+        abortSignal ?? resolvedOptions.signal,
+      )
+    },
   }
 }
 
@@ -1197,6 +1455,9 @@ export function fetcherToConnectionAdapter(
           data,
           threadId: runContext.threadId,
           runId: runContext.runId,
+          ...(runContext.parentRunId !== undefined && {
+            parentRunId: runContext.parentRunId,
+          }),
           ...(runContext.resume !== undefined && { resume: runContext.resume }),
         },
         { signal: abortSignal },
diff --git a/packages/ai-client/src/index.ts b/packages/ai-client/src/index.ts
index bb8b7f7ae..e13c6f680 100644
--- a/packages/ai-client/src/index.ts
+++ b/packages/ai-client/src/index.ts
@@ -6,6 +6,12 @@ export type {
   InferAudioRecordingOutput,
 } from './audio-recorder'
 export { ChatClient } from './chat-client'
+export { InterruptManager } from './interrupt-manager'
+export type {
+  InterruptManagerHydration,
+  InterruptManagerOptions,
+  InterruptManagerSubmission,
+} from './interrupt-manager'
 export { createMcpAppBridge } from './mcp-app-bridge'
 export type { McpAppBridge, CreateMcpAppBridgeOptions } from './mcp-app-bridge'
 export { RealtimeClient } from './realtime-client'
@@ -27,9 +33,20 @@ export type {
   ChatPersistenceOptions,
   ChatClientOptions,
   ChatPendingInterrupt,
+  BoundInterruptBase,
+  BoundInterrupts,
+  ChatInterrupt,
+  ChatInterruptState,
+  GenericAGUIInterrupt,
+  InterruptItemStatus,
+  ToolApprovalInterrupt,
   ClientContextOptionFromTools,
   ChatResumeState,
   ChatResumeSnapshot,
+  ChatResumeSnapshotV1,
+  ChatResumeSnapshotV2,
+  ChatContinuationLoader,
+  PersistedInterruptDraft,
   ChatRequestBody,
   InferChatMessages,
   InferredClientContext,
@@ -120,6 +137,8 @@ export type {
   RealtimeStateChangeCallback,
 } from './realtime-types'
 export {
+  createInterruptContinuationLoader,
+  createInterruptStateFetcher,
   fetchServerSentEvents,
   fetchHttpStream,
   xhrServerSentEvents,
@@ -131,6 +150,9 @@ export {
   type ConnectConnectionAdapter,
   type ConnectionAdapter,
   type FetchConnectionOptions,
+  type InterruptContinuationLoader,
+  type InterruptFetchOptions,
+  type InterruptStateFetcher,
   type ResumableConnectConnectionAdapter,
   type RunAgentInputContext,
   type SubscribeConnectionAdapter,
diff --git a/packages/ai-client/src/interrupt-manager.ts b/packages/ai-client/src/interrupt-manager.ts
new file mode 100644
index 000000000..a89c29de0
--- /dev/null
+++ b/packages/ai-client/src/interrupt-manager.ts
@@ -0,0 +1,1494 @@
+import {
+  canonicalInterruptJson,
+  canonicalizeInterruptResolutions,
+  cloneAndDeepFreezeJson,
+  compileJsonSchema202012,
+  digestInterruptJson,
+  hashSchemaInput,
+  isStandardSchema,
+  normalizeApprovalSchema,
+} from '@tanstack/ai/client'
+import type {
+  AnyClientTool,
+  BatchInterruptError,
+  Interrupt,
+  InterruptBinding,
+  InterruptCommitResult,
+  InterruptRecoveryStateV1,
+  InterruptSubmissionError,
+  ItemInterruptError,
+  RunAgentResumeItem,
+} from '@tanstack/ai/client'
+import type {
+  BoundInterruptBase,
+  BoundInterrupts,
+  ChatInterrupt,
+  ChatInterruptState,
+  GenericAGUIInterrupt,
+  InterruptItemStatus,
+  PersistedInterruptDraft,
+} from './types'
+
+export interface InterruptManagerHydration {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  interrupts: ReadonlyArray<Interrupt>
+}
+
+export interface InterruptManagerSubmission {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  resolutions: ReadonlyArray<RunAgentResumeItem>
+  canonicalResolutions: string
+  fingerprint: string
+}
+
+export interface InterruptManagerOptions<
+  TTools extends ReadonlyArray<AnyClientTool>,
+> {
+  tools?: TTools
+  submit: (
+    submission: InterruptManagerSubmission,
+  ) => Promise<InterruptCommitResult | void>
+  recover?: (state?: InterruptRecoveryStateV1) => void | Promise<void>
+  onChange?: () => void
+}
+
+type UnknownObject = { [key: string]: unknown }
+
+type RuntimeKind = 'generic' | 'tool-approval' | 'client-tool-execution'
+
+interface RuntimeInterrupt {
+  descriptor: Interrupt
+  binding: InterruptBinding
+  kind: RuntimeKind
+  status: InterruptItemStatus
+  canResolve: boolean
+  error?: ItemInterruptError
+  resolution?: RunAgentResumeItem
+  tool?: AnyClientTool
+  validationGeneration: number
+}
+
+interface ValidationFailure {
+  code: ItemInterruptError['code']
+  message: string
+  path?: ReadonlyArray<string | number>
+}
+
+type ValidationResult = { valid: true; payload: unknown } | ValidationFailure
+
+interface TransactionToken {
+  active: boolean
+}
+
+interface RuntimeInterruptCheckpoint {
+  status: InterruptItemStatus
+  resolution?: RunAgentResumeItem
+  error?: ItemInterruptError
+  validationGeneration: number
+}
+
+const itemErrorCodes = new Set<ItemInterruptError['code']>([
+  'invalid-payload',
+  'invalid-edited-args',
+  'invalid-tool-output',
+  'invalid-response-schema',
+  'unknown-interrupt',
+  'expired',
+  'stale',
+  'conflict',
+  'legacy-unsupported',
+])
+
+const batchErrorCodes = new Set<BatchInterruptError['code']>([
+  'incomplete-batch',
+  'item-validation-failed',
+  'unsupported-bulk-operation',
+  'async-resolver',
+  'inactive-transaction',
+  'mixed-provenance',
+  'transport',
+  'server',
+  'protocol',
+  'invalid-response-schema',
+  'expired',
+  'stale',
+  'conflict',
+  'persistence-required',
+  'atomic-commit-unsupported',
+  'recovery-unavailable',
+  'legacy-submit-failed',
+])
+
+function isUnknownObject(value: unknown): value is UnknownObject {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isLegacyApprovalMetadata(value: unknown): boolean {
+  return (
+    isUnknownObject(value) &&
+    value['kind'] === 'approval' &&
+    typeof value['toolName'] === 'string' &&
+    'input' in value
+  )
+}
+
+function isLegacyClientToolMetadata(value: unknown): boolean {
+  return (
+    isUnknownObject(value) &&
+    value['kind'] === 'client_tool' &&
+    typeof value['toolName'] === 'string' &&
+    'input' in value
+  )
+}
+
+function isBindingBase(value: UnknownObject): boolean {
+  return (
+    typeof value['kind'] === 'string' &&
+    typeof value['interruptId'] === 'string' &&
+    typeof value['interruptedRunId'] === 'string' &&
+    typeof value['generation'] === 'number' &&
+    Number.isInteger(value['generation']) &&
+    value['generation'] >= 0 &&
+    typeof value['responseSchemaHash'] === 'string' &&
+    (value['expiresAt'] === undefined ||
+      (typeof value['expiresAt'] === 'string' &&
+        Number.isFinite(Date.parse(value['expiresAt']))))
+  )
+}
+
+function readBinding(value: unknown): InterruptBinding | undefined {
+  if (!isUnknownObject(value) || !isBindingBase(value)) return undefined
+  const expiresAt =
+    typeof value['expiresAt'] === 'string' ? value['expiresAt'] : undefined
+  if (value['kind'] === 'generic') {
+    return {
+      kind: 'generic',
+      interruptId: String(value['interruptId']),
+      interruptedRunId: String(value['interruptedRunId']),
+      generation: Number(value['generation']),
+      responseSchemaHash: String(value['responseSchemaHash']),
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+    }
+  }
+  if (
+    value['kind'] === 'client-tool-execution' &&
+    typeof value['toolName'] === 'string' &&
+    typeof value['toolCallId'] === 'string' &&
+    typeof value['outputSchemaHash'] === 'string'
+  ) {
+    return {
+      kind: 'client-tool-execution',
+      interruptId: String(value['interruptId']),
+      interruptedRunId: String(value['interruptedRunId']),
+      generation: Number(value['generation']),
+      toolName: value['toolName'],
+      toolCallId: value['toolCallId'],
+      outputSchemaHash: value['outputSchemaHash'],
+      responseSchemaHash: String(value['responseSchemaHash']),
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+    }
+  }
+  if (
+    value['kind'] === 'tool-approval' &&
+    typeof value['toolName'] === 'string' &&
+    typeof value['toolCallId'] === 'string' &&
+    typeof value['inputSchemaHash'] === 'string' &&
+    typeof value['approvalSchemaHash'] === 'string' &&
+    'originalArgs' in value
+  ) {
+    return {
+      kind: 'tool-approval',
+      interruptId: String(value['interruptId']),
+      interruptedRunId: String(value['interruptedRunId']),
+      generation: Number(value['generation']),
+      toolName: value['toolName'],
+      toolCallId: value['toolCallId'],
+      originalArgs: value['originalArgs'],
+      inputSchemaHash: value['inputSchemaHash'],
+      approvalSchemaHash: value['approvalSchemaHash'],
+      responseSchemaHash: String(value['responseSchemaHash']),
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+    }
+  }
+  return undefined
+}
+
+function getDescriptorBinding(
+  interrupt: Interrupt,
+): InterruptBinding | undefined {
+  const candidate: unknown = interrupt.metadata?.['tanstack:interruptBinding']
+  return readBinding(candidate)
+}
+
+function isToolApprovalReason(reason: string): boolean {
+  return reason === 'tool_call' || reason === 'approval_required'
+}
+
+function isClientToolExecutionReason(reason: string): boolean {
+  return (
+    reason === 'tanstack:client_tool_execution' ||
+    reason === 'client_tool_input'
+  )
+}
+
+function responseSchemaHash(interrupt: Interrupt): string | undefined {
+  if (interrupt.responseSchema === undefined) return undefined
+  try {
+    return digestInterruptJson(canonicalInterruptJson(interrupt.responseSchema))
+  } catch {
+    return undefined
+  }
+}
+
+function canValidateGeneric(interrupt: Interrupt): boolean {
+  if (interrupt.responseSchema === undefined) return true
+  try {
+    compileJsonSchema202012(interrupt.responseSchema)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value !== null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    'then' in value &&
+    typeof value.then === 'function'
+  )
+}
+
+function validateWithSchema(
+  schema: unknown,
+  value: unknown,
+  code: ItemInterruptError['code'],
+): ValidationResult | Promise<ValidationResult> {
+  if (schema === undefined) return { valid: true, payload: value }
+  if (isStandardSchema(schema)) {
+    const result = schema['~standard'].validate(value)
+    const normalize = (
+      validation: Awaited<typeof result>,
+    ): ValidationResult => {
+      if (!validation.issues) {
+        return { valid: true, payload: validation.value }
+      }
+      return {
+        code,
+        message: validation.issues[0]?.message ?? 'Schema validation failed.',
+      }
+    }
+    return isPromiseLike(result)
+      ? Promise.resolve(result).then(normalize)
+      : normalize(result)
+  }
+  try {
+    const issues = compileJsonSchema202012(schema)(value)
+    const issue = issues[0]
+    return issue
+      ? { code, message: issue.message, path: issue.path }
+      : { valid: true, payload: value }
+  } catch {
+    return {
+      code: 'invalid-response-schema',
+      message: 'The interrupt response schema is invalid.',
+    }
+  }
+}
+
+function isItemErrorCode(value: string): value is ItemInterruptError['code'] {
+  for (const code of itemErrorCodes) if (code === value) return true
+  return false
+}
+
+function isBatchErrorCode(value: string): value is BatchInterruptError['code'] {
+  for (const code of batchErrorCodes) if (code === value) return true
+  return false
+}
+
+function isSubmissionError(value: unknown): value is InterruptSubmissionError {
+  if (!isUnknownObject(value)) return false
+  const scope = value['scope']
+  const code = value['code']
+  const base =
+    typeof code === 'string' &&
+    typeof value['message'] === 'string' &&
+    typeof value['retryable'] === 'boolean' &&
+    typeof value['threadId'] === 'string' &&
+    typeof value['interruptedRunId'] === 'string' &&
+    typeof value['generation'] === 'number'
+  if (!base) return false
+  if (scope === 'item') {
+    return (
+      isItemErrorCode(code) &&
+      typeof value['interruptId'] === 'string' &&
+      (value['source'] === 'client' || value['source'] === 'server')
+    )
+  }
+  return (
+    scope === 'batch' &&
+    isBatchErrorCode(code) &&
+    Array.isArray(value['interruptIds']) &&
+    value['interruptIds'].every((id) => typeof id === 'string') &&
+    (value['source'] === 'client' ||
+      value['source'] === 'server' ||
+      value['source'] === 'transport')
+  )
+}
+
+function readSubmissionErrors(
+  error: unknown,
+): ReadonlyArray<InterruptSubmissionError> {
+  if (isSubmissionError(error)) return [error]
+  if (!isUnknownObject(error) || !Array.isArray(error['errors'])) return []
+  return error['errors'].every(isSubmissionError) ? error['errors'] : []
+}
+
+function haveSameInterruptIds(
+  left: ReadonlyArray<string>,
+  right: ReadonlyArray<string>,
+): boolean {
+  if (left.length !== right.length) return false
+  const sortedLeft = [...left].sort()
+  const sortedRight = [...right].sort()
+  return sortedLeft.every((id, index) => id === sortedRight[index])
+}
+
+function haveSameBatchCorrelation(
+  left: BatchInterruptError,
+  right: BatchInterruptError,
+): boolean {
+  return (
+    left.threadId === right.threadId &&
+    left.interruptedRunId === right.interruptedRunId &&
+    left.generation === right.generation &&
+    haveSameInterruptIds(left.interruptIds, right.interruptIds)
+  )
+}
+
+function mergeSubmissionBatchErrors(
+  current: ReadonlyArray<BatchInterruptError>,
+  previousSubmission: ReadonlyArray<BatchInterruptError>,
+  incoming: ReadonlyArray<BatchInterruptError>,
+): {
+  rootErrors: ReadonlyArray<BatchInterruptError>
+  submissionRootErrors: ReadonlyArray<BatchInterruptError>
+} {
+  const replaceableIncoming = incoming.filter(
+    (error) => error.source !== 'transport',
+  )
+  const isSuperseded = (candidate: BatchInterruptError): boolean =>
+    previousSubmission.includes(candidate) &&
+    replaceableIncoming.some((error) =>
+      haveSameBatchCorrelation(candidate, error),
+    )
+  const retainedRootErrors = current.filter(
+    (candidate) => !isSuperseded(candidate),
+  )
+  const retainedSubmissionRootErrors = previousSubmission.filter(
+    (candidate) =>
+      !replaceableIncoming.some((error) =>
+        haveSameBatchCorrelation(candidate, error),
+      ),
+  )
+  return Object.freeze({
+    rootErrors: Object.freeze([...retainedRootErrors, ...incoming]),
+    submissionRootErrors: Object.freeze([
+      ...retainedSubmissionRootErrors,
+      ...replaceableIncoming,
+    ]),
+  })
+}
+
+function submissionErrorMatchesActiveBatch(
+  error: InterruptSubmissionError,
+  submission: InterruptManagerSubmission,
+): boolean {
+  if (
+    error.threadId !== submission.threadId ||
+    error.interruptedRunId !== submission.interruptedRunId ||
+    error.generation !== submission.generation
+  ) {
+    return false
+  }
+  const interruptIds = submission.resolutions.map(
+    (resolution) => resolution.interruptId,
+  )
+  return error.scope === 'item'
+    ? interruptIds.includes(error.interruptId)
+    : haveSameInterruptIds(error.interruptIds, interruptIds)
+}
+
+function genericBinding(
+  interrupt: Interrupt,
+  hydration: InterruptManagerHydration,
+  candidate: InterruptBinding | undefined,
+): InterruptBinding {
+  return cloneAndDeepFreezeJson({
+    kind: 'generic',
+    interruptId: interrupt.id,
+    interruptedRunId: hydration.interruptedRunId,
+    generation: hydration.generation,
+    responseSchemaHash:
+      responseSchemaHash(interrupt) ??
+      candidate?.responseSchemaHash ??
+      'invalid',
+    ...(interrupt.expiresAt !== undefined
+      ? { expiresAt: interrupt.expiresAt }
+      : {}),
+  })
+}
+
+function baseSnapshot(
+  item: RuntimeInterrupt,
+  hydration: InterruptManagerHydration,
+  cancel: () => void,
+  clearResolution: () => void,
+): BoundInterruptBase {
+  const descriptor = cloneAndDeepFreezeJson(item.descriptor)
+  const binding = cloneAndDeepFreezeJson(item.binding)
+  const errors: ReadonlyArray<ItemInterruptError> =
+    item.error === undefined
+      ? Object.freeze([])
+      : Object.freeze([cloneAndDeepFreezeJson(item.error)])
+  const error = errors[0]
+  return {
+    id: descriptor.id,
+    interruptId: descriptor.id,
+    reason: descriptor.reason,
+    ...(descriptor.message !== undefined
+      ? { message: descriptor.message }
+      : {}),
+    ...(descriptor.responseSchema !== undefined
+      ? { responseSchema: descriptor.responseSchema }
+      : {}),
+    ...(descriptor.expiresAt !== undefined
+      ? { expiresAt: descriptor.expiresAt }
+      : {}),
+    ...(descriptor.metadata !== undefined
+      ? { metadata: descriptor.metadata }
+      : {}),
+    threadId: hydration.threadId,
+    interruptedRunId: hydration.interruptedRunId,
+    generation: hydration.generation,
+    status: item.status,
+    binding,
+    errors,
+    ...(error !== undefined ? { error } : {}),
+    canResolve: item.canResolve,
+    cancel,
+    clearResolution,
+  }
+}
+
+export class InterruptManager<
+  TTools extends ReadonlyArray<AnyClientTool> = ReadonlyArray<AnyClientTool>,
+> {
+  private hydration: InterruptManagerHydration | undefined
+  private items: Array<RuntimeInterrupt> = []
+  private snapshot: ReadonlyArray<ChatInterrupt<TTools>> = Object.freeze([])
+  private rootErrors: ReadonlyArray<BatchInterruptError> = Object.freeze([])
+  private submissionRootErrors: ReadonlyArray<BatchInterruptError> =
+    Object.freeze([])
+  private state: ChatInterruptState<TTools> = Object.freeze({
+    interrupts: this.snapshot,
+    pendingInterrupts: this.snapshot,
+    interruptErrors: this.rootErrors,
+    resuming: false,
+  })
+  private activeTransaction: TransactionToken | undefined
+  private retrySubmission: InterruptManagerSubmission | undefined
+  private resuming = false
+  private tools: TTools | undefined
+
+  constructor(private readonly options: InterruptManagerOptions<TTools>) {
+    this.tools = options.tools
+  }
+
+  updateTools(tools: TTools): void {
+    this.tools = tools
+  }
+
+  hydrate(hydration: InterruptManagerHydration): void {
+    this.hydration = {
+      threadId: hydration.threadId,
+      interruptedRunId: hydration.interruptedRunId,
+      generation: hydration.generation,
+      interrupts: cloneAndDeepFreezeJson(hydration.interrupts),
+    }
+    this.items = hydration.interrupts.map((interrupt) =>
+      this.hydrateInterrupt(interrupt, hydration),
+    )
+    this.rootErrors = Object.freeze([])
+    this.submissionRootErrors = Object.freeze([])
+    this.retrySubmission = undefined
+    this.resuming = false
+    this.publish()
+  }
+
+  getInterrupts(): BoundInterrupts<TTools> {
+    return this.snapshot
+  }
+
+  getState(): ChatInterruptState<TTools> {
+    return this.state
+  }
+
+  getDescriptors(): ReadonlyArray<Interrupt> {
+    return this.hydration?.interrupts ?? Object.freeze([])
+  }
+
+  getRecoveryState(): InterruptRecoveryStateV1 | undefined {
+    const hydration = this.hydration
+    if (!hydration) return undefined
+    return cloneAndDeepFreezeJson({
+      schemaVersion: 1,
+      state: 'pending',
+      threadId: hydration.threadId,
+      interruptedRunId: hydration.interruptedRunId,
+      generation: hydration.generation,
+      pendingInterrupts: hydration.interrupts,
+    })
+  }
+
+  getPersistedDrafts(): ReadonlyArray<PersistedInterruptDraft> {
+    return cloneAndDeepFreezeJson(
+      this.items.flatMap((item) => {
+        if (item.resolution === undefined && item.error === undefined) return []
+        return [
+          {
+            interruptId: item.descriptor.id,
+            response: item.resolution ?? null,
+            status: item.status,
+            ...(item.error !== undefined ? { error: item.error } : {}),
+          },
+        ]
+      }),
+    )
+  }
+
+  reportRecoveryError(
+    code: 'expired' | 'stale' | 'conflict' | 'recovery-unavailable',
+    message: string,
+    recoveryState?: InterruptRecoveryStateV1,
+  ): void {
+    if (!this.hydration && recoveryState !== undefined) {
+      this.hydration = {
+        threadId: recoveryState.threadId,
+        interruptedRunId: recoveryState.interruptedRunId,
+        generation: recoveryState.generation,
+        interrupts: cloneAndDeepFreezeJson(recoveryState.pendingInterrupts),
+      }
+      this.items = recoveryState.pendingInterrupts.map((interrupt) =>
+        this.hydrateInterrupt(interrupt, this.requireHydration()),
+      )
+    }
+    for (const item of this.items) {
+      if (item.status === 'submitting') item.status = 'error'
+    }
+    this.addRootError(code, message, false, 'server')
+    this.publish()
+  }
+
+  restorePersistedDrafts(drafts: ReadonlyArray<PersistedInterruptDraft>): void {
+    for (const draft of drafts) {
+      const item = this.items.find(
+        (candidate) => candidate.descriptor.id === draft.interruptId,
+      )
+      if (!item) continue
+      const response = draft.response
+      if (
+        isUnknownObject(response) &&
+        response['interruptId'] === item.descriptor.id &&
+        response['status'] === 'cancelled'
+      ) {
+        item.resolution = Object.freeze({
+          interruptId: item.descriptor.id,
+          status: 'cancelled',
+        })
+        item.status = draft.error === undefined ? 'staged' : 'error'
+        item.error = draft.error
+        continue
+      }
+      if (
+        isUnknownObject(response) &&
+        response['interruptId'] === item.descriptor.id &&
+        response['status'] === 'resolved'
+      ) {
+        const validationGeneration = ++item.validationGeneration
+        const validation = this.validateCandidate(item, response['payload'])
+        if (isPromiseLike(validation)) {
+          item.status = 'validating'
+          void Promise.resolve(validation)
+            .then((result) => {
+              if (validationGeneration !== item.validationGeneration) return
+              this.applyRestoredValidation(item, result, draft)
+            })
+            .catch((error: unknown) => {
+              if (validationGeneration !== item.validationGeneration) return
+              this.applyRestoredValidation(
+                item,
+                {
+                  code: this.validationCode(item),
+                  message:
+                    error instanceof Error ? error.message : String(error),
+                },
+                draft,
+              )
+            })
+        } else {
+          this.applyRestoredValidation(item, validation, draft, false)
+        }
+        continue
+      }
+      if (draft.error !== undefined) {
+        item.status = 'error'
+        item.error = cloneAndDeepFreezeJson(draft.error)
+      }
+    }
+    this.publish()
+  }
+
+  reset(options?: { preserveRootErrors?: boolean }): void {
+    this.hydration = undefined
+    this.items = []
+    this.snapshot = Object.freeze([])
+    if (options?.preserveRootErrors !== true) {
+      this.rootErrors = Object.freeze([])
+      this.submissionRootErrors = Object.freeze([])
+    }
+    this.retrySubmission = undefined
+    this.resuming = false
+    this.state = Object.freeze({
+      interrupts: this.snapshot,
+      pendingInterrupts: this.snapshot,
+      interruptErrors: this.rootErrors,
+      resuming: false,
+    })
+    this.options.onChange?.()
+  }
+
+  getInterruptErrors(): ReadonlyArray<BatchInterruptError> {
+    return this.rootErrors
+  }
+
+  getResuming(): boolean {
+    return this.resuming
+  }
+
+  resolve(approved: boolean): void
+  resolve(resolver: (interrupt: ChatInterrupt<TTools>) => undefined): void
+  resolve(
+    resolution: boolean | ((interrupt: ChatInterrupt<TTools>) => unknown),
+  ): void {
+    this.assertRootMutable()
+    if (typeof resolution === 'boolean') {
+      this.resolveBooleanBulk(resolution)
+      return
+    }
+    this.resolveTransaction(resolution)
+  }
+
+  cancel(): void {
+    this.assertRootMutable()
+    this.invalidateRetry()
+    for (const item of this.items) {
+      item.validationGeneration++
+      item.resolution = Object.freeze({
+        interruptId: item.descriptor.id,
+        status: 'cancelled',
+      })
+      item.status = 'staged'
+      item.error = undefined
+    }
+    this.publish()
+    this.maybeSubmit()
+  }
+
+  retry(): void {
+    if (this.resuming)
+      throw new Error('Interrupt submission is already active.')
+    const submission = this.retrySubmission
+    if (!submission) {
+      this.addRootError(
+        'transport',
+        'There is no retryable interrupt submission.',
+        false,
+      )
+      return
+    }
+    this.submitBatch(submission)
+  }
+
+  resolveClientToolOutput(toolCallId: string, output: unknown): boolean {
+    const item = this.items.find(
+      (candidate) =>
+        (candidate.kind === 'client-tool-execution' &&
+          candidate.binding.kind === 'client-tool-execution' &&
+          candidate.binding.toolCallId === toolCallId) ||
+        (candidate.kind === 'generic' &&
+          candidate.descriptor.reason === 'client_tool_input' &&
+          candidate.descriptor.toolCallId === toolCallId &&
+          isLegacyClientToolMetadata(candidate.descriptor.metadata)),
+    )
+    if (!item) return false
+    this.resolveItem(item.descriptor.id, output)
+    return true
+  }
+
+  resolveToolApprovalDecision(interruptId: string, approved: boolean): boolean {
+    const item = this.items.find(
+      (candidate) =>
+        candidate.descriptor.id === interruptId &&
+        (candidate.kind === 'tool-approval' ||
+          (candidate.kind === 'generic' &&
+            candidate.descriptor.reason === 'approval_required' &&
+            isLegacyApprovalMetadata(candidate.descriptor.metadata))),
+    )
+    if (!item) return false
+    this.resolveItem(item.descriptor.id, { approved })
+    return true
+  }
+
+  private hydrateInterrupt(
+    descriptor: Interrupt,
+    hydration: InterruptManagerHydration,
+  ): RuntimeInterrupt {
+    const interrupt = cloneAndDeepFreezeJson(descriptor)
+    const candidate = getDescriptorBinding(interrupt)
+    const correlated =
+      candidate !== undefined &&
+      candidate.interruptId === interrupt.id &&
+      candidate.interruptedRunId === hydration.interruptedRunId &&
+      candidate.generation === hydration.generation &&
+      candidate.responseSchemaHash ===
+        (responseSchemaHash(interrupt) ?? candidate.responseSchemaHash)
+
+    if (correlated && candidate.kind === 'tool-approval') {
+      const tool = this.tools?.find(
+        (configured) => configured.name === candidate.toolName,
+      )
+      if (
+        tool?.needsApproval === true &&
+        isToolApprovalReason(interrupt.reason) &&
+        interrupt.toolCallId === candidate.toolCallId
+      ) {
+        try {
+          const approval = normalizeApprovalSchema(
+            tool.approvalSchema,
+            tool.inputSchema,
+          )
+          if (
+            hashSchemaInput(tool.inputSchema) === candidate.inputSchemaHash &&
+            approval.approvalSchemaHash === candidate.approvalSchemaHash &&
+            approval.responseSchemaHash === candidate.responseSchemaHash
+          ) {
+            return {
+              descriptor: interrupt,
+              binding: cloneAndDeepFreezeJson(candidate),
+              kind: 'tool-approval',
+              status: 'pending',
+              canResolve: true,
+              tool,
+              validationGeneration: 0,
+            }
+          }
+        } catch {
+          // Invalid configured schemas cannot safely grant typed hydration.
+        }
+      }
+    }
+
+    if (correlated && candidate.kind === 'client-tool-execution') {
+      const tool = this.tools?.find(
+        (configured) => configured.name === candidate.toolName,
+      )
+      if (
+        tool !== undefined &&
+        isClientToolExecutionReason(interrupt.reason) &&
+        interrupt.toolCallId === candidate.toolCallId &&
+        hashSchemaInput(tool.outputSchema) === candidate.outputSchemaHash
+      ) {
+        return {
+          descriptor: interrupt,
+          binding: cloneAndDeepFreezeJson(candidate),
+          kind: 'client-tool-execution',
+          status: 'pending',
+          canResolve: true,
+          tool,
+          validationGeneration: 0,
+        }
+      }
+    }
+
+    return {
+      descriptor: interrupt,
+      binding: genericBinding(interrupt, hydration, candidate),
+      kind: 'generic',
+      status: 'pending',
+      canResolve: canValidateGeneric(interrupt),
+      validationGeneration: 0,
+    }
+  }
+
+  private buildSnapshot(
+    transaction?: TransactionToken,
+  ): BoundInterrupts<TTools> {
+    const hydration = this.requireHydration()
+    // `client-tool-execution` items stay in `this.items` (they gate batch
+    // submission and are resolved internally via auto-execution / addToolResult),
+    // but they are never surfaced as public bound interrupts.
+    const next = this.items
+      .filter((item) => item.kind !== 'client-tool-execution')
+      .map((item) => {
+        const base = baseSnapshot(
+          item,
+          hydration,
+          () => this.cancelItem(item.descriptor.id, transaction),
+          () => this.clearItem(item.descriptor.id, transaction),
+        )
+        if (
+          item.kind === 'tool-approval' &&
+          item.binding.kind === 'tool-approval'
+        ) {
+          const snapshot = {
+            ...base,
+            kind: 'tool-approval' as const,
+            toolName: item.binding.toolName,
+            toolCallId: item.binding.toolCallId,
+            originalArgs: cloneAndDeepFreezeJson(item.binding.originalArgs),
+            resolveInterrupt: (approved: boolean, options?: unknown) => {
+              const details = isUnknownObject(options) ? options : undefined
+              this.resolveItem(
+                item.descriptor.id,
+                {
+                  approved,
+                  ...(approved && details?.['editedArgs'] !== undefined
+                    ? { editedArgs: details['editedArgs'] }
+                    : {}),
+                  ...(details?.['payload'] !== undefined
+                    ? { payload: details['payload'] }
+                    : {}),
+                },
+                transaction,
+              )
+            },
+          }
+          return Object.freeze(snapshot)
+        }
+        const snapshot: GenericAGUIInterrupt = {
+          ...base,
+          kind: 'generic',
+          resolveInterrupt: (payload) =>
+            this.resolveItem(item.descriptor.id, payload, transaction),
+        }
+        return Object.freeze(snapshot)
+      })
+
+    // The runtime items are created only from the exact configured TTools entry
+    // selected by name. TypeScript cannot preserve that per-element lookup
+    // through Array.map, so this generic return boundary restores the proven
+    // distributive public union.
+    return Object.freeze(next) as BoundInterrupts<TTools>
+  }
+
+  private publish(): void {
+    if (!this.hydration) {
+      this.snapshot = Object.freeze([])
+      this.state = Object.freeze({
+        interrupts: this.snapshot,
+        pendingInterrupts: this.snapshot,
+        interruptErrors: this.rootErrors,
+        resuming: this.resuming,
+      })
+      this.options.onChange?.()
+      return
+    }
+    this.snapshot = this.buildSnapshot()
+    this.state = Object.freeze({
+      interrupts: this.snapshot,
+      pendingInterrupts: this.snapshot,
+      interruptErrors: this.rootErrors,
+      resuming: this.resuming,
+    })
+    this.options.onChange?.()
+  }
+
+  private resolveItem(
+    interruptId: string,
+    payload: unknown,
+    transaction?: TransactionToken,
+  ): void {
+    this.assertItemMutable(transaction)
+    const item = this.findItem(interruptId)
+    this.invalidateRetry()
+    if (!item.canResolve) {
+      item.status = 'error'
+      item.error = this.itemError(
+        interruptId,
+        'invalid-response-schema',
+        'The interrupt response schema is invalid and cannot be resolved.',
+      )
+      if (!transaction) this.publish()
+      return
+    }
+    const validationGeneration = ++item.validationGeneration
+    const validation = this.validateCandidate(item, payload)
+    if (isPromiseLike(validation)) {
+      item.status = 'validating'
+      item.error = undefined
+      if (!transaction) this.publish()
+      void Promise.resolve(validation)
+        .then((result) => {
+          if (validationGeneration !== item.validationGeneration) return
+          this.applyValidation(item, result, transaction)
+        })
+        .catch((error: unknown) => {
+          if (validationGeneration !== item.validationGeneration) return
+          this.applyValidation(
+            item,
+            {
+              code: this.validationCode(item),
+              message: error instanceof Error ? error.message : String(error),
+            },
+            transaction,
+          )
+        })
+      return
+    }
+    this.applyValidation(item, validation, transaction)
+  }
+
+  private cancelItem(
+    interruptId: string,
+    transaction?: TransactionToken,
+  ): void {
+    this.assertItemMutable(transaction)
+    const item = this.findItem(interruptId)
+    this.invalidateRetry()
+    item.validationGeneration++
+    item.resolution = Object.freeze({ interruptId, status: 'cancelled' })
+    item.status = 'staged'
+    item.error = undefined
+    if (!transaction) {
+      this.publish()
+      this.maybeSubmit()
+    }
+  }
+
+  private clearItem(interruptId: string, transaction?: TransactionToken): void {
+    this.assertItemMutable(transaction)
+    const item = this.findItem(interruptId)
+    this.invalidateRetry()
+    item.validationGeneration++
+    item.resolution = undefined
+    item.error = undefined
+    item.status = 'pending'
+    if (!transaction) this.publish()
+  }
+
+  private maybeSubmit(): void {
+    if (
+      this.items.length === 0 ||
+      this.items.some(
+        (item) => item.resolution === undefined || item.status !== 'staged',
+      )
+    ) {
+      return
+    }
+    const hydration = this.requireHydration()
+    const canonical = canonicalizeInterruptResolutions(
+      this.items
+        .map((item) => item.resolution)
+        .filter((item) => item !== undefined),
+    )
+    const submission = Object.freeze({
+      threadId: hydration.threadId,
+      interruptedRunId: hydration.interruptedRunId,
+      generation: hydration.generation,
+      resolutions: canonical.resolutions,
+      canonicalResolutions: canonical.canonicalResolutions,
+      fingerprint: canonical.fingerprint,
+    })
+    this.submitBatch(submission)
+  }
+
+  private applyValidation(
+    item: RuntimeInterrupt,
+    result: ValidationResult,
+    transaction?: TransactionToken,
+  ): void {
+    if (!('valid' in result)) {
+      item.status = 'error'
+      item.error = this.itemError(
+        item.descriptor.id,
+        result.code,
+        result.message,
+        result.path,
+      )
+      if (!transaction) this.publish()
+      return
+    }
+    item.resolution = cloneAndDeepFreezeJson({
+      interruptId: item.descriptor.id,
+      status: 'resolved',
+      payload: result.payload,
+    })
+    item.status = 'staged'
+    item.error = undefined
+    if (!transaction) {
+      this.publish()
+      this.maybeSubmit()
+    }
+  }
+
+  private applyRestoredValidation(
+    item: RuntimeInterrupt,
+    result: ValidationResult,
+    draft: PersistedInterruptDraft,
+    publish = true,
+  ): void {
+    if (!('valid' in result)) {
+      item.status = 'error'
+      item.error = this.itemError(
+        item.descriptor.id,
+        result.code,
+        result.message,
+        result.path,
+      )
+    } else {
+      item.resolution = cloneAndDeepFreezeJson({
+        interruptId: item.descriptor.id,
+        status: 'resolved',
+        payload: result.payload,
+      })
+      item.status = draft.error === undefined ? 'staged' : 'error'
+      item.error =
+        draft.error === undefined
+          ? undefined
+          : cloneAndDeepFreezeJson(draft.error)
+    }
+    if (publish) this.publish()
+  }
+
+  private validateCandidate(
+    item: RuntimeInterrupt,
+    payload: unknown,
+  ): ValidationResult | Promise<ValidationResult> {
+    if (item.kind === 'generic') {
+      return validateWithSchema(
+        item.descriptor.responseSchema,
+        payload,
+        'invalid-payload',
+      )
+    }
+    if (item.kind === 'client-tool-execution') {
+      return validateWithSchema(
+        item.tool?.outputSchema,
+        payload,
+        'invalid-tool-output',
+      )
+    }
+    return this.validateApprovalCandidate(item, payload)
+  }
+
+  private validateApprovalCandidate(
+    item: RuntimeInterrupt,
+    payload: unknown,
+  ): ValidationResult | Promise<ValidationResult> {
+    if (!isUnknownObject(payload) || typeof payload['approved'] !== 'boolean') {
+      return {
+        code: 'invalid-payload',
+        message: 'Tool approval resolutions require an approved boolean.',
+      }
+    }
+    const approved = payload['approved']
+    const editedArgs = payload['editedArgs']
+    if (!approved && editedArgs !== undefined) {
+      return {
+        code: 'invalid-edited-args',
+        message: 'Rejected tool approvals cannot edit tool arguments.',
+      }
+    }
+    if (approved && editedArgs !== undefined) {
+      const editedValidation = validateWithSchema(
+        item.tool?.inputSchema,
+        editedArgs,
+        'invalid-edited-args',
+      )
+      if (isPromiseLike(editedValidation)) {
+        return Promise.resolve(editedValidation).then((result) =>
+          'valid' in result
+            ? this.validateApprovalPayload(item, payload, result.payload)
+            : result,
+        )
+      }
+      if (!('valid' in editedValidation)) return editedValidation
+      return this.validateApprovalPayload(
+        item,
+        payload,
+        editedValidation.payload,
+      )
+    }
+    return this.validateApprovalPayload(item, payload, undefined)
+  }
+
+  private validateApprovalPayload(
+    item: RuntimeInterrupt,
+    envelope: UnknownObject,
+    validatedEditedArgs: unknown,
+  ): ValidationResult | Promise<ValidationResult> {
+    const approved = envelope['approved'] === true
+    const schema = this.approvalBranchSchema(item.tool, approved)
+    const branchPayload = envelope['payload']
+    if (schema === undefined && branchPayload !== undefined) {
+      return {
+        code: 'invalid-payload',
+        message: 'This approval branch does not accept a payload.',
+      }
+    }
+    if (schema !== undefined && branchPayload === undefined) {
+      return {
+        code: 'invalid-payload',
+        message: 'This approval branch requires a payload.',
+      }
+    }
+    const validation = validateWithSchema(
+      schema,
+      branchPayload,
+      'invalid-payload',
+    )
+    const buildEnvelope = (result: ValidationResult): ValidationResult => {
+      if (!('valid' in result)) return result
+      return {
+        valid: true,
+        payload: {
+          approved,
+          ...(validatedEditedArgs !== undefined
+            ? { editedArgs: validatedEditedArgs }
+            : {}),
+          ...(schema !== undefined ? { payload: result.payload } : {}),
+        },
+      }
+    }
+    return isPromiseLike(validation)
+      ? Promise.resolve(validation).then(buildEnvelope)
+      : buildEnvelope(validation)
+  }
+
+  private approvalBranchSchema(
+    tool: AnyClientTool | undefined,
+    approved: boolean,
+  ): unknown {
+    const approvalSchema: unknown = tool?.approvalSchema
+    if (!isUnknownObject(approvalSchema)) return approvalSchema
+    const hasBranches =
+      'approve' in approvalSchema || 'reject' in approvalSchema
+    if (!hasBranches) return approvalSchema
+    return approved ? approvalSchema['approve'] : approvalSchema['reject']
+  }
+
+  private validationCode(item: RuntimeInterrupt): ItemInterruptError['code'] {
+    return item.kind === 'client-tool-execution'
+      ? 'invalid-tool-output'
+      : 'invalid-payload'
+  }
+
+  private resolveBooleanBulk(approved: boolean): void {
+    // `client-tool-execution` items resolve out-of-band (auto execution /
+    // addToolResult); they are transparent to the boolean shorthand. Eligibility
+    // and resolution consider only the publicly resolvable items.
+    const resolvable = this.items.filter(
+      (item) => item.kind !== 'client-tool-execution',
+    )
+    const eligible = resolvable.every(
+      (item) =>
+        item.kind === 'tool-approval' &&
+        this.approvalBranchSchema(item.tool, approved) === undefined,
+    )
+    if (!eligible || resolvable.length === 0) {
+      this.addRootError(
+        'unsupported-bulk-operation',
+        'Boolean bulk resolution requires payloadless tool approvals.',
+        false,
+      )
+      return
+    }
+    this.invalidateRetry()
+    for (const item of resolvable) {
+      item.validationGeneration++
+      item.resolution = cloneAndDeepFreezeJson({
+        interruptId: item.descriptor.id,
+        status: 'resolved',
+        payload: { approved },
+      })
+      item.status = 'staged'
+      item.error = undefined
+    }
+    this.publish()
+    this.maybeSubmit()
+  }
+
+  private resolveTransaction(
+    resolver: (interrupt: ChatInterrupt<TTools>) => unknown,
+  ): void {
+    const checkpoints = this.items.map<RuntimeInterruptCheckpoint>((item) => ({
+      status: item.status,
+      ...(item.resolution !== undefined ? { resolution: item.resolution } : {}),
+      ...(item.error !== undefined ? { error: item.error } : {}),
+      validationGeneration: item.validationGeneration,
+    }))
+    const token: TransactionToken = { active: true }
+    this.activeTransaction = token
+    const stable = this.buildSnapshot(token)
+    let failure:
+      | { code: BatchInterruptError['code']; message: string }
+      | undefined
+    try {
+      for (const interrupt of stable) {
+        const result = resolver(interrupt)
+        if (result !== undefined) {
+          failure = {
+            code: isPromiseLike(result)
+              ? 'async-resolver'
+              : 'inactive-transaction',
+            message: isPromiseLike(result)
+              ? 'Interrupt transaction resolvers must be synchronous.'
+              : 'Interrupt transaction resolvers must return literal undefined.',
+          }
+          break
+        }
+      }
+      if (
+        failure === undefined &&
+        this.items.some(
+          (item) =>
+            // `client-tool-execution` items are resolved out-of-band (auto
+            // execution / addToolResult), not by this synchronous resolver, so
+            // they don't count against transaction completeness. `maybeSubmit`
+            // still gates the actual submission on them being resolved.
+            item.kind !== 'client-tool-execution' &&
+            (item.resolution === undefined || item.status !== 'staged'),
+        )
+      ) {
+        failure = {
+          code: 'incomplete-batch',
+          message: 'Interrupt transaction did not resolve every item.',
+        }
+      }
+    } catch (error) {
+      failure = {
+        code: 'item-validation-failed',
+        message: error instanceof Error ? error.message : String(error),
+      }
+    } finally {
+      token.active = false
+      this.activeTransaction = undefined
+    }
+
+    if (failure) {
+      this.restoreCheckpoints(checkpoints)
+      this.addRootError(failure.code, failure.message, false)
+      return
+    }
+    this.publish()
+    this.maybeSubmit()
+  }
+
+  private restoreCheckpoints(
+    checkpoints: ReadonlyArray<RuntimeInterruptCheckpoint>,
+  ): void {
+    this.items.forEach((item, index) => {
+      const checkpoint = checkpoints[index]
+      if (!checkpoint) return
+      item.status = checkpoint.status
+      item.resolution = checkpoint.resolution
+      item.error = checkpoint.error
+      item.validationGeneration = checkpoint.validationGeneration + 1
+    })
+    this.publish()
+  }
+
+  private assertItemMutable(transaction?: TransactionToken): void {
+    if (transaction && !transaction.active) {
+      throw new Error('Interrupt transaction is inactive.')
+    }
+    if (this.activeTransaction && transaction !== this.activeTransaction) {
+      throw new Error('Interrupt transaction is inactive.')
+    }
+    if (this.resuming) {
+      throw new Error('Interrupts cannot be mutated while submitting.')
+    }
+  }
+
+  private assertRootMutable(): void {
+    if (this.activeTransaction) {
+      throw new Error('Interrupt transaction is already active.')
+    }
+    if (this.resuming) {
+      throw new Error('Interrupts cannot be mutated while submitting.')
+    }
+  }
+
+  private invalidateRetry(): void {
+    this.retrySubmission = undefined
+  }
+
+  private submitBatch(submission: InterruptManagerSubmission): void {
+    this.resuming = true
+    this.retrySubmission = undefined
+    for (const item of this.items) item.status = 'submitting'
+    this.publish()
+    void this.performSubmission(submission)
+  }
+
+  private async performSubmission(
+    submission: InterruptManagerSubmission,
+  ): Promise<void> {
+    try {
+      const result = await this.options.submit(submission)
+      if (result?.status === 'conflict') {
+        this.addRootError(
+          'conflict',
+          'Interrupt submission conflicted with authoritative state.',
+          false,
+          'server',
+        )
+        await this.options.recover?.(result.authoritativeState)
+      }
+    } catch (error) {
+      await this.handleSubmissionFailure(error, submission)
+    } finally {
+      this.resuming = false
+      this.publish()
+    }
+  }
+
+  private async handleSubmissionFailure(
+    error: unknown,
+    submission: InterruptManagerSubmission,
+  ): Promise<void> {
+    const errors = readSubmissionErrors(error)
+    if (errors.length === 0) {
+      const message = error instanceof Error ? error.message : String(error)
+      this.addRootError('transport', message, true, 'transport')
+      this.retrySubmission = submission
+      for (const item of this.items) item.status = 'error'
+      return
+    }
+
+    const correlatedErrors = errors.filter((submissionError) =>
+      submissionErrorMatchesActiveBatch(submissionError, submission),
+    )
+    if (correlatedErrors.length !== errors.length) {
+      this.addRootError(
+        'protocol',
+        'Interrupt submission errors did not match the active batch.',
+        false,
+      )
+    }
+
+    let requiresRecovery = false
+    let retryable = false
+    const batchErrors: Array<BatchInterruptError> = []
+    for (const submissionError of correlatedErrors) {
+      if (
+        submissionError.code === 'stale' ||
+        submissionError.code === 'expired' ||
+        submissionError.code === 'conflict'
+      ) {
+        requiresRecovery = true
+      }
+      retryable ||= submissionError.retryable
+      if (submissionError.scope === 'item') {
+        const item = this.items.find(
+          (candidate) =>
+            candidate.descriptor.id === submissionError.interruptId,
+        )
+        if (item) {
+          item.status = 'error'
+          item.error = cloneAndDeepFreezeJson(submissionError)
+        }
+      } else {
+        batchErrors.push(cloneAndDeepFreezeJson(submissionError))
+      }
+    }
+    const mergedBatchErrors = mergeSubmissionBatchErrors(
+      this.rootErrors,
+      this.submissionRootErrors,
+      batchErrors,
+    )
+    this.rootErrors = mergedBatchErrors.rootErrors
+    this.submissionRootErrors = mergedBatchErrors.submissionRootErrors
+    for (const item of this.items) {
+      if (item.status === 'submitting') item.status = 'error'
+    }
+    this.retrySubmission =
+      retryable && !requiresRecovery ? submission : undefined
+    if (requiresRecovery) await this.options.recover?.()
+  }
+
+  private addRootError(
+    code: BatchInterruptError['code'],
+    message: string,
+    retryable: boolean,
+    source: BatchInterruptError['source'] = 'client',
+  ): void {
+    const hydration = this.requireHydration()
+    this.rootErrors = Object.freeze([
+      ...this.rootErrors,
+      Object.freeze({
+        scope: 'batch' as const,
+        code,
+        message,
+        source,
+        retryable,
+        interruptIds: Object.freeze(
+          this.items.map((item) => item.descriptor.id),
+        ),
+        threadId: hydration.threadId,
+        interruptedRunId: hydration.interruptedRunId,
+        generation: hydration.generation,
+      }),
+    ])
+    this.publish()
+  }
+
+  private findItem(interruptId: string): RuntimeInterrupt {
+    const item = this.items.find(
+      (candidate) => candidate.descriptor.id === interruptId,
+    )
+    if (!item) throw new Error(`Unknown interrupt: ${interruptId}`)
+    return item
+  }
+
+  private requireHydration(): InterruptManagerHydration {
+    if (!this.hydration) throw new Error('InterruptManager is not hydrated.')
+    return this.hydration
+  }
+
+  private itemError(
+    interruptId: string,
+    code: ItemInterruptError['code'],
+    message: string,
+    path?: ReadonlyArray<string | number>,
+  ): ItemInterruptError {
+    const hydration = this.requireHydration()
+    return Object.freeze({
+      scope: 'item',
+      interruptId,
+      code,
+      message,
+      ...(path !== undefined ? { path: Object.freeze([...path]) } : {}),
+      source: 'client',
+      retryable: false,
+      threadId: hydration.threadId,
+      interruptedRunId: hydration.interruptedRunId,
+      generation: hydration.generation,
+    })
+  }
+}
diff --git a/packages/ai-client/src/types.ts b/packages/ai-client/src/types.ts
index 5ed1b0076..efc39d030 100644
--- a/packages/ai-client/src/types.ts
+++ b/packages/ai-client/src/types.ts
@@ -1,15 +1,25 @@
 import type {
   AnyClientTool,
+  ApprovalCapabilityOf,
+  ApprovalSchemaOf,
   AudioPart,
+  BatchInterruptError,
   ChunkStrategy,
   ContentPart,
   DocumentPart,
   ImagePart,
+  InferSchemaType,
   InferToolInput,
   InferToolOutput,
+  InputSchemaOf,
   Interrupt,
+  InterruptBinding,
+  InterruptRecoveryStateV1,
+  ItemInterruptError,
   ModelMessage,
+  NoSchema,
   RunAgentResumeItem,
+  SchemaInput,
   StreamChunk,
   StructuredOutputPart,
   UIResourcePart,
@@ -28,11 +38,155 @@ export interface ChatResumeState {
 
 export type ChatPendingInterrupt = Interrupt
 
-export interface ChatResumeSnapshot {
+export interface ChatResumeSnapshotV1 {
+  schemaVersion?: 1
   resumeState: ChatResumeState
   pendingInterrupts?: Array<ChatPendingInterrupt>
 }
 
+/** JSON-safe client draft state. Authoritative interrupt state stays in recoveryState. */
+export interface PersistedInterruptDraft {
+  readonly interruptId: string
+  readonly response: unknown
+  readonly status: InterruptItemStatus
+  readonly error?: ItemInterruptError
+}
+
+export interface ChatResumeSnapshotV2 {
+  schemaVersion: 2
+  resumeState: ChatResumeState
+  pendingInterrupts?: Array<ChatPendingInterrupt>
+  interruptState?: {
+    recoveryState: InterruptRecoveryStateV1
+    drafts: ReadonlyArray<PersistedInterruptDraft>
+  }
+}
+
+export type ChatResumeSnapshot = ChatResumeSnapshotV1 | ChatResumeSnapshotV2
+
+export type ChatContinuationLoader = (
+  continuationRunId: string,
+  abortSignal?: AbortSignal,
+) => AsyncIterable<StreamChunk>
+
+export type InterruptItemStatus =
+  | 'pending'
+  | 'validating'
+  | 'staged'
+  | 'submitting'
+  | 'error'
+
+export interface BoundInterruptBase {
+  readonly id: string
+  readonly interruptId: string
+  readonly reason: string
+  readonly message?: string
+  readonly responseSchema?: Readonly<Record<string, unknown>>
+  readonly expiresAt?: string
+  readonly metadata?: Readonly<Record<string, unknown>>
+  readonly threadId: string
+  readonly interruptedRunId: string
+  readonly generation: number
+  readonly status: InterruptItemStatus
+  readonly binding: Readonly<InterruptBinding>
+  readonly errors: ReadonlyArray<ItemInterruptError>
+  /** @deprecated Use `errors[0]`. */
+  readonly error?: ItemInterruptError
+  readonly canResolve: boolean
+  cancel: () => void
+  clearResolution: () => void
+}
+
+export interface GenericAGUIInterrupt extends BoundInterruptBase {
+  readonly kind: 'generic'
+  resolveInterrupt: (payload: unknown) => void
+}
+
+type ApprovalBranchSchema<TTool, TBranch extends 'approve' | 'reject'> =
+  ApprovalSchemaOf<TTool> extends infer TApproval
+    ? TApproval extends { approve?: SchemaInput; reject?: SchemaInput }
+      ? Exclude<TApproval[TBranch], undefined>
+      : TApproval extends SchemaInput
+        ? TApproval
+        : never
+    : never
+
+type ApprovalEdits<TTool> =
+  InputSchemaOf<TTool> extends NoSchema
+    ? { editedArgs?: never }
+    : { editedArgs?: InferToolInput<TTool> }
+
+type ApprovalPayload<TSchema> = [TSchema] extends [never]
+  ? { payload?: never }
+  : TSchema extends SchemaInput
+    ? { payload: InferSchemaType<TSchema> }
+    : { payload?: never }
+
+type ApproveArguments<TTool> = [
+  ApprovalBranchSchema<TTool, 'approve'>,
+] extends [never]
+  ? InputSchemaOf<TTool> extends NoSchema
+    ? [options?: never]
+    : [options?: ApprovalEdits<TTool> & { payload?: never }]
+  : [
+      options: ApprovalEdits<TTool> &
+        ApprovalPayload<ApprovalBranchSchema<TTool, 'approve'>>,
+    ]
+
+type RejectArguments<TTool> = [ApprovalBranchSchema<TTool, 'reject'>] extends [
+  never,
+]
+  ? [options?: never]
+  : [
+      options: { editedArgs?: never } & ApprovalPayload<
+        ApprovalBranchSchema<TTool, 'reject'>
+      >,
+    ]
+
+export type ToolApprovalInterrupt<TTool extends AnyClientTool = AnyClientTool> =
+  TTool extends AnyClientTool
+    ? BoundInterruptBase & {
+        readonly kind: 'tool-approval'
+        readonly toolName: TTool['name']
+        readonly toolCallId: string
+        readonly originalArgs: InferToolInput<TTool>
+        resolveInterrupt: {
+          (approved: true, ...args: ApproveArguments<TTool>): void
+          (approved: false, ...args: RejectArguments<TTool>): void
+        }
+      }
+    : never
+
+type ApprovalInterrupts<TTools extends ReadonlyArray<AnyClientTool>> =
+  TTools[number] extends infer TTool
+    ? TTool extends AnyClientTool
+      ? ApprovalCapabilityOf<TTool> extends true
+        ? ToolApprovalInterrupt<TTool>
+        : never
+      : never
+    : never
+
+// Client tools resolve through their `.client()` implementation (auto-run) or
+// `addToolResult` — never as a bound interrupt. The `client-tool-execution`
+// pause is handled internally and is intentionally absent from this public
+// union.
+export type ChatInterrupt<
+  TTools extends ReadonlyArray<AnyClientTool> = ReadonlyArray<AnyClientTool>,
+> = GenericAGUIInterrupt | ApprovalInterrupts<TTools>
+
+export type BoundInterrupts<
+  TTools extends ReadonlyArray<AnyClientTool> = ReadonlyArray<AnyClientTool>,
+> = ReadonlyArray<ChatInterrupt<TTools>>
+
+export interface ChatInterruptState<
+  TTools extends ReadonlyArray<AnyClientTool> = ReadonlyArray<AnyClientTool>,
+> {
+  readonly interrupts: BoundInterrupts<TTools>
+  readonly pendingInterrupts: BoundInterrupts<TTools>
+  readonly interruptErrors: ReadonlyArray<BatchInterruptError>
+  readonly resuming: boolean
+}
+
 /**
  * `messages` is the full UIMessage history (not a delta). `data` is the
  * merged body — `ChatClientOptions.body` plus any per-call data passed to
@@ -45,6 +199,7 @@ export interface ChatFetcherInput {
   data?: Record<string, unknown>
   threadId: string
   runId: string
+  parentRunId?: string
   resume?: Array<RunAgentResumeItem>
 }
 
@@ -435,6 +590,9 @@ export interface ChatClientBaseOptions<
    */
   initialResumeSnapshot?: ChatResumeSnapshot
 
+  /** Explicit read-only loader for replaying a committed continuation run. */
+  continuationLoader?: ChatContinuationLoader
+
   /**
    * Arbitrary client-controlled JSON forwarded to the server in the
    * AG-UI `RunAgentInput.forwardedProps` field. Use this for per-session
@@ -527,9 +685,12 @@ export interface ChatClientBaseOptions<
    */
   onResumeStateChange?: (
     resumeState: ChatResumeState | null,
-    pendingInterrupts: Array<ChatPendingInterrupt>,
+    pendingInterrupts: BoundInterrupts<TTools>,
   ) => void
 
+  /** Callback when the immutable interrupt state snapshot changes. */
+  onInterruptStateChange?: (state: ChatInterruptState<TTools>) => void
+
   /**
    * Callback when a custom event is received from a server-side tool.
    * Custom events are emitted by tools using `context.emitCustomEvent()` during execution.
diff --git a/packages/ai-client/tests/chat-client-interrupt-correlation.test.ts b/packages/ai-client/tests/chat-client-interrupt-correlation.test.ts
new file mode 100644
index 000000000..941016dbe
--- /dev/null
+++ b/packages/ai-client/tests/chat-client-interrupt-correlation.test.ts
@@ -0,0 +1,189 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai/client'
+import { ChatClient } from '../src/chat-client'
+import type { Interrupt, StreamChunk } from '@tanstack/ai/client'
+import type {
+  RunAgentInputContext,
+  SubscribeConnectionAdapter,
+} from '../src/connection-adapters'
+
+function createNativeQueue() {
+  const chunks: Array<StreamChunk> = []
+  const contexts: Array<RunAgentInputContext | undefined> = []
+  let wake: (() => void) | undefined
+  const connection: SubscribeConnectionAdapter = {
+    async *subscribe(signal) {
+      while (!signal?.aborted) {
+        const chunk = chunks.shift()
+        if (chunk) {
+          yield chunk
+          continue
+        }
+        await new Promise<void>((resolve) => {
+          wake = resolve
+          signal?.addEventListener('abort', () => resolve(), { once: true })
+        })
+      }
+    },
+    send: (_messages, _data, _signal, context) => {
+      contexts.push(context)
+      return Promise.resolve()
+    },
+  }
+  return {
+    connection,
+    contexts,
+    publish(chunk: StreamChunk) {
+      chunks.push(chunk)
+      const resolve = wake
+      wake = undefined
+      resolve?.()
+    },
+  }
+}
+
+const interruptedRunId = 'interrupted-run'
+const pendingInterrupt: Interrupt = {
+  id: 'generic-1',
+  reason: 'confirmation',
+  metadata: {
+    'tanstack:interruptBinding': {
+      kind: 'generic',
+      interruptId: 'generic-1',
+      interruptedRunId,
+      generation: 1,
+      responseSchemaHash: 'none',
+    },
+  },
+}
+
+describe('ChatClient interrupt error correlation', () => {
+  it('does not apply a foreign shared RUN_ERROR to a local interrupt submission', async () => {
+    const { connection, contexts, publish } = createNativeQueue()
+    const onChunk = vi.fn()
+    const client = new ChatClient({
+      connection,
+      onChunk,
+      initialResumeSnapshot: {
+        schemaVersion: 2,
+        resumeState: { threadId: 'thread-1', runId: interruptedRunId },
+        pendingInterrupts: [pendingInterrupt],
+        interruptState: {
+          recoveryState: {
+            schemaVersion: 1,
+            state: 'pending',
+            threadId: 'thread-1',
+            interruptedRunId,
+            generation: 1,
+            pendingInterrupts: [pendingInterrupt],
+          },
+          drafts: [],
+        },
+      },
+    })
+    const interrupt = client.getInterrupts()[0]
+    if (interrupt?.kind !== 'generic') {
+      throw new Error('Expected a generic interrupt')
+    }
+
+    interrupt.resolveInterrupt({ answer: 'continue' })
+    await vi.waitFor(() => expect(contexts).toHaveLength(1))
+    publish({
+      type: EventType.RUN_ERROR,
+      threadId: 'foreign-thread',
+      runId: 'foreign-child-run',
+      timestamp: Date.now(),
+      message: 'foreign run failed',
+      'tanstack:interruptErrors': [
+        {
+          scope: 'item',
+          interruptId: 'generic-1',
+          code: 'invalid-payload',
+          message: 'foreign item error',
+          source: 'server',
+          retryable: false,
+          threadId: 'foreign-thread',
+          interruptedRunId: 'foreign-parent-run',
+          generation: 7,
+        },
+        {
+          scope: 'batch',
+          code: 'item-validation-failed',
+          message: 'foreign batch error',
+          source: 'server',
+          retryable: false,
+          interruptIds: ['generic-1'],
+          threadId: 'foreign-thread',
+          interruptedRunId: 'foreign-parent-run',
+          generation: 7,
+        },
+      ],
+    })
+
+    await vi.waitFor(() =>
+      expect(client.getInterruptState().resuming).toBe(false),
+    )
+    expect(onChunk).toHaveBeenCalledWith(
+      expect.objectContaining({ runId: 'foreign-child-run' }),
+    )
+    expect(client.getError()?.message).toBe('foreign run failed')
+    expect(client.getInterrupts()[0]?.errors).toEqual([])
+    expect(client.getInterruptState().interruptErrors).toEqual([
+      expect.objectContaining({ code: 'transport', source: 'transport' }),
+    ])
+
+    client.retryInterrupts()
+    await vi.waitFor(() => expect(contexts).toHaveLength(2))
+    const localRunId = contexts[1]?.runId
+    if (!localRunId) throw new Error('Expected a local continuation run ID')
+    publish({
+      type: EventType.RUN_ERROR,
+      threadId: 'thread-1',
+      runId: localRunId,
+      timestamp: Date.now(),
+      message: 'local validation failed',
+      'tanstack:interruptErrors': [
+        {
+          scope: 'item',
+          interruptId: 'generic-1',
+          code: 'invalid-payload',
+          message: 'local item error',
+          source: 'server',
+          retryable: false,
+          threadId: 'thread-1',
+          interruptedRunId,
+          generation: 1,
+        },
+        {
+          scope: 'batch',
+          code: 'item-validation-failed',
+          message: 'local batch error',
+          source: 'server',
+          retryable: false,
+          interruptIds: ['generic-1'],
+          threadId: 'thread-1',
+          interruptedRunId,
+          generation: 1,
+        },
+      ],
+    })
+
+    await vi.waitFor(() =>
+      expect(client.getInterrupts()[0]?.errors).toMatchObject([
+        { message: 'local item error', source: 'server' },
+      ]),
+    )
+    expect(client.getInterruptState().interruptErrors).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ code: 'transport', source: 'transport' }),
+        expect.objectContaining({
+          code: 'item-validation-failed',
+          message: 'local batch error',
+          source: 'server',
+        }),
+      ]),
+    )
+    expect(JSON.stringify(client.getInterruptState())).not.toContain('foreign')
+    client.dispose()
+  })
+})
diff --git a/packages/ai-client/tests/chat-client-interrupts.test.ts b/packages/ai-client/tests/chat-client-interrupts.test.ts
new file mode 100644
index 000000000..518e52542
--- /dev/null
+++ b/packages/ai-client/tests/chat-client-interrupts.test.ts
@@ -0,0 +1,1724 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  InterruptPersistenceCapability,
+  chat,
+  defineChatMiddleware,
+  provideInterruptPersistence,
+} from '@tanstack/ai'
+import {
+  EventType,
+  canonicalInterruptJson,
+  convertSchemaToJsonSchema,
+  digestInterruptJson,
+  hashSchemaInput,
+  normalizeApprovalSchema,
+  toolDefinition,
+} from '@tanstack/ai/client'
+import { z } from 'zod'
+import { InterruptManager } from '../src/interrupt-manager'
+import { ChatClient } from '../src/chat-client'
+import type {
+  AnyTextAdapter,
+  InterruptSubmissionError,
+  InterruptRecoveryStateV1,
+  InterruptPersistenceGateway,
+  StreamChunk,
+} from '@tanstack/ai'
+import type {
+  Interrupt,
+  InterruptBinding,
+  ModelMessage,
+} from '@tanstack/ai/client'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { InterruptManagerSubmission } from '../src/interrupt-manager'
+import type { ChatInterrupt } from '../src/types'
+import type {
+  ConnectConnectionAdapter,
+  RunAgentInputContext,
+} from '../src/connection-adapters'
+import type { UIMessage } from '../src/types'
+import type { ChatResumeSnapshotV2, ChatServerPersistence } from '../src/types'
+
+const transferDefinition = toolDefinition({
+  name: 'transfer',
+  description: 'Transfer funds',
+  needsApproval: true,
+  inputSchema: z.object({ cents: z.number() }),
+  outputSchema: z.object({ receipt: z.string() }),
+  approvalSchema: {
+    approve: z.object({ note: z.string() }),
+    reject: z.object({ reason: z.string() }),
+  },
+})
+
+const lookupDefinition = toolDefinition({
+  name: 'lookup',
+  description: 'Look up an account',
+  outputSchema: z.object({ accountId: z.string() }),
+})
+
+const tools = [transferDefinition.client(), lookupDefinition.client()] as const
+
+function descriptor(
+  binding: InterruptBinding,
+  overrides: Partial<Interrupt> = {},
+): Interrupt {
+  return {
+    id: binding.interruptId,
+    reason:
+      binding.kind === 'tool-approval'
+        ? 'tool_call'
+        : binding.kind === 'client-tool-execution'
+          ? 'tanstack:client_tool_execution'
+          : 'confirmation',
+    ...(binding.kind !== 'generic' && { toolCallId: binding.toolCallId }),
+    metadata: { 'tanstack:interruptBinding': binding },
+    ...overrides,
+  }
+}
+
+function createManager() {
+  const submit = vi.fn(async (_submission: InterruptManagerSubmission) => ({
+    status: 'committed' as const,
+    continuationRunId: 'continuation-1',
+  }))
+  const manager = new InterruptManager({ tools, submit })
+  return { manager, submit }
+}
+
+function genericDescriptor(id: string): Interrupt {
+  return descriptor({
+    kind: 'generic',
+    interruptId: id,
+    interruptedRunId: 'run-1',
+    generation: 1,
+    responseSchemaHash: 'none',
+  })
+}
+
+async function settle(): Promise<void> {
+  await Promise.resolve()
+  await Promise.resolve()
+}
+
+describe('InterruptManager hydration', () => {
+  it('hydrates correlated approval and client-tool bindings into frozen typed snapshots', () => {
+    const approval = normalizeApprovalSchema(
+      transferDefinition.approvalSchema,
+      transferDefinition.inputSchema,
+    )
+    const approvalBinding: InterruptBinding = {
+      kind: 'tool-approval',
+      interruptId: 'approval-1',
+      interruptedRunId: 'run-1',
+      generation: 3,
+      toolName: 'transfer',
+      toolCallId: 'call-1',
+      originalArgs: { cents: 100 },
+      inputSchemaHash: hashSchemaInput(transferDefinition.inputSchema),
+      approvalSchemaHash: approval.approvalSchemaHash,
+      responseSchemaHash: approval.responseSchemaHash,
+    }
+    const outputSchemaHash = hashSchemaInput(lookupDefinition.outputSchema)
+    const clientBinding: InterruptBinding = {
+      kind: 'client-tool-execution',
+      interruptId: 'client-1',
+      interruptedRunId: 'run-1',
+      generation: 3,
+      toolName: 'lookup',
+      toolCallId: 'call-2',
+      outputSchemaHash,
+      responseSchemaHash: outputSchemaHash,
+    }
+    const { manager } = createManager()
+
+    manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 3,
+      interrupts: [
+        descriptor(approvalBinding, {
+          responseSchema: approval.responseSchema,
+        }),
+        descriptor(clientBinding),
+      ],
+    })
+
+    // The client-tool-execution item is hydrated internally but never surfaced
+    // publicly — only the approval appears in the bound array.
+    const snapshot = manager.getInterrupts()
+    expect(snapshot.map((item) => item.kind)).toEqual(['tool-approval'])
+    expect(Object.isFrozen(snapshot)).toBe(true)
+    expect(Object.isFrozen(snapshot[0])).toBe(true)
+    expect(Object.isFrozen(snapshot[0]?.binding)).toBe(true)
+  })
+
+  it('hydrates a real core client-tool terminal with distinct schema identity hashes', async () => {
+    const coreChunks: Array<StreamChunk> = [
+      {
+        type: EventType.RUN_STARTED,
+        runId: 'core-run',
+        threadId: 'core-thread',
+        timestamp: 1,
+      },
+      {
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'core-call',
+        toolCallName: lookupDefinition.name,
+        toolName: lookupDefinition.name,
+        timestamp: 1,
+      },
+      {
+        type: EventType.TOOL_CALL_ARGS,
+        toolCallId: 'core-call',
+        delta: '{}',
+        timestamp: 1,
+      },
+      {
+        type: EventType.RUN_FINISHED,
+        runId: 'core-run',
+        threadId: 'core-thread',
+        finishReason: 'tool_calls',
+        timestamp: 1,
+      },
+    ]
+    const adapter: AnyTextAdapter = {
+      kind: 'text',
+      name: 'core-interrupt-test',
+      model: 'test-model',
+      '~types': {
+        providerOptions: {},
+        inputModalities: ['text'],
+        messageMetadataByModality: {
+          text: undefined,
+          image: undefined,
+          audio: undefined,
+          video: undefined,
+          document: undefined,
+        },
+        toolCapabilities: [],
+        toolCallMetadata: undefined,
+        systemPromptMetadata: undefined,
+      },
+      chatStream: () =>
+        (async function* () {
+          await Promise.resolve()
+          for (const chunk of coreChunks) yield chunk
+        })(),
+      structuredOutput: () => Promise.resolve({ data: {}, rawText: '{}' }),
+    }
+    const gateway: InterruptPersistenceGateway = {
+      openInterruptBatch: (input) =>
+        Promise.resolve({ generation: 1, descriptors: input.descriptors }),
+      commitInterruptResolutions: (input) =>
+        Promise.resolve({
+          status: 'committed',
+          continuationRunId: input.continuationRunId,
+        }),
+      getInterruptRecoveryState: (input) =>
+        Promise.resolve({
+          schemaVersion: 1,
+          state: 'missing',
+          threadId: input.threadId,
+          interruptedRunId: input.interruptedRunId,
+          generation: input.knownGeneration,
+          pendingInterrupts: [],
+        }),
+    }
+    const persistence = defineChatMiddleware({
+      name: 'core-interrupt-test-persistence',
+      provides: [InterruptPersistenceCapability],
+      setup(ctx) {
+        provideInterruptPersistence(ctx, gateway)
+      },
+      async onChunk(_ctx, chunk) {
+        if (
+          chunk.type !== EventType.RUN_FINISHED ||
+          chunk.outcome?.type !== 'interrupt'
+        ) {
+          return
+        }
+        const opened = await gateway.openInterruptBatch({
+          threadId: chunk.threadId,
+          interruptedRunId: chunk.runId,
+          descriptors: chunk.outcome.interrupts,
+          bindings: [],
+        })
+        return {
+          ...chunk,
+          outcome: {
+            ...chunk.outcome,
+            interrupts: chunk.outcome.interrupts.map((interrupt) => {
+              const raw = interrupt.metadata?.['tanstack:interruptBinding']
+              if (
+                raw === null ||
+                typeof raw !== 'object' ||
+                Array.isArray(raw)
+              ) {
+                throw new Error('Expected a core interrupt binding.')
+              }
+              return {
+                ...interrupt,
+                metadata: {
+                  ...interrupt.metadata,
+                  'tanstack:interruptBinding': {
+                    ...Object.fromEntries(Object.entries(raw)),
+                    interruptedRunId: chunk.runId,
+                    generation: opened.generation,
+                  },
+                },
+              }
+            }),
+          },
+        }
+      },
+    })
+    const emitted: Array<StreamChunk> = []
+    for await (const chunk of chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Look up an account' }],
+      tools: [tools[1]],
+      runId: 'core-run',
+      threadId: 'core-thread',
+      middleware: [persistence],
+    })) {
+      emitted.push(chunk)
+    }
+    const terminal = emitted.find(
+      (chunk) =>
+        chunk.type === EventType.RUN_FINISHED &&
+        chunk.outcome?.type === 'interrupt',
+    )
+    if (
+      terminal?.type !== EventType.RUN_FINISHED ||
+      terminal.outcome?.type !== 'interrupt'
+    ) {
+      throw new Error('Expected a real core interrupt terminal.')
+    }
+    const interrupt = terminal.outcome.interrupts[0]
+    if (!interrupt) throw new Error('Expected a client-tool interrupt.')
+    const rawBinding = interrupt.metadata?.['tanstack:interruptBinding']
+    if (
+      rawBinding === null ||
+      typeof rawBinding !== 'object' ||
+      Array.isArray(rawBinding)
+    ) {
+      throw new Error('Expected a public interrupt binding.')
+    }
+    const binding = Object.fromEntries(Object.entries(rawBinding))
+    const expectedOutputSchemaHash = hashSchemaInput(
+      lookupDefinition.outputSchema,
+    )
+    const expectedResponseSchema =
+      convertSchemaToJsonSchema(lookupDefinition.outputSchema) ?? {}
+    const expectedResponseSchemaHash = digestInterruptJson(
+      canonicalInterruptJson(expectedResponseSchema),
+    )
+    expect(binding.outputSchemaHash).toBe(expectedOutputSchemaHash)
+    expect(binding.responseSchemaHash).toBe(expectedResponseSchemaHash)
+    expect(binding.outputSchemaHash).not.toBe(binding.responseSchemaHash)
+
+    const { manager } = createManager()
+    manager.hydrate({
+      threadId: 'core-thread',
+      interruptedRunId: 'core-run',
+      generation: 1,
+      interrupts: terminal.outcome.interrupts,
+    })
+    // A correctly-correlated client-tool item is internal only — not public.
+    expect(manager.getInterrupts()).toHaveLength(0)
+
+    manager.hydrate({
+      threadId: 'core-thread',
+      interruptedRunId: 'core-run',
+      generation: 1,
+      interrupts: [
+        {
+          ...interrupt,
+          metadata: {
+            ...interrupt.metadata,
+            'tanstack:interruptBinding': {
+              ...binding,
+              outputSchemaHash: 'sha256:configured-schema-drift',
+            },
+          },
+        },
+      ],
+    })
+    expect(manager.getInterrupts()[0]?.kind).toBe('generic')
+  })
+
+  it('keeps deprecated approval and client-tool reason aliases compatible', () => {
+    const approval = normalizeApprovalSchema(
+      transferDefinition.approvalSchema,
+      transferDefinition.inputSchema,
+    )
+    const approvalBinding: InterruptBinding = {
+      kind: 'tool-approval',
+      interruptId: 'approval-legacy',
+      interruptedRunId: 'run-legacy',
+      generation: 1,
+      toolName: 'transfer',
+      toolCallId: 'call-approval-legacy',
+      originalArgs: { cents: 100 },
+      inputSchemaHash: hashSchemaInput(transferDefinition.inputSchema),
+      approvalSchemaHash: approval.approvalSchemaHash,
+      responseSchemaHash: approval.responseSchemaHash,
+    }
+    const outputSchemaHash = hashSchemaInput(lookupDefinition.outputSchema)
+    const clientBinding: InterruptBinding = {
+      kind: 'client-tool-execution',
+      interruptId: 'client-legacy',
+      interruptedRunId: 'run-legacy',
+      generation: 1,
+      toolName: 'lookup',
+      toolCallId: 'call-client-legacy',
+      outputSchemaHash,
+      responseSchemaHash: outputSchemaHash,
+    }
+    const { manager } = createManager()
+
+    manager.hydrate({
+      threadId: 'thread-legacy',
+      interruptedRunId: 'run-legacy',
+      generation: 1,
+      interrupts: [
+        descriptor(approvalBinding, {
+          reason: 'approval_required',
+          responseSchema: approval.responseSchema,
+        }),
+        descriptor(clientBinding, { reason: 'client_tool_input' }),
+      ],
+    })
+
+    // The legacy client-tool alias hydrates internally but stays out of the
+    // public bound array; only the approval is surfaced.
+    expect(manager.getInterrupts().map((interrupt) => interrupt.kind)).toEqual([
+      'tool-approval',
+    ])
+  })
+
+  it('degrades mismatched tool correlation to generic without trusting wire correlation', () => {
+    const outputSchemaHash = hashSchemaInput(lookupDefinition.outputSchema)
+    const binding: InterruptBinding = {
+      kind: 'client-tool-execution',
+      interruptId: 'client-1',
+      interruptedRunId: 'untrusted-run',
+      generation: 99,
+      toolName: 'lookup',
+      toolCallId: 'expected-call',
+      outputSchemaHash,
+      responseSchemaHash: outputSchemaHash,
+    }
+    const { manager } = createManager()
+
+    manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 3,
+      interrupts: [descriptor(binding, { toolCallId: 'other-call' })],
+    })
+
+    expect(manager.getInterrupts()[0]).toMatchObject({
+      kind: 'generic',
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 3,
+    })
+  })
+
+  it('keeps cancellation available when a generic response schema is invalid', () => {
+    const binding: InterruptBinding = {
+      kind: 'generic',
+      interruptId: 'generic-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      responseSchemaHash: 'invalid-schema',
+    }
+    const { manager } = createManager()
+    manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [
+        descriptor(binding, {
+          responseSchema: {
+            $schema: 'https://json-schema.org/draft/2019-09/schema',
+            type: 'object',
+          },
+        }),
+      ],
+    })
+
+    const item = manager.getInterrupts()[0]
+    expect(item?.kind).toBe('generic')
+    expect(item?.canResolve).toBe(false)
+    item?.cancel()
+    expect(manager.getInterrupts()[0]?.status).toBe('submitting')
+  })
+})
+
+describe('InterruptManager transactions', () => {
+  it('waits for a complete multi-item batch and submits a singleton immediately', async () => {
+    const multi = createManager()
+    multi.manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [genericDescriptor('one'), genericDescriptor('two')],
+    })
+
+    const first = multi.manager.getInterrupts()[0]
+    if (first?.kind !== 'generic') throw new Error('Expected generic interrupt')
+    first.resolveInterrupt('first')
+    expect(multi.submit).not.toHaveBeenCalled()
+    expect(multi.manager.getInterrupts()[0]?.status).toBe('staged')
+    multi.manager.getInterrupts()[1]?.cancel()
+    expect(multi.submit).toHaveBeenCalledTimes(1)
+
+    const single = createManager()
+    single.manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [genericDescriptor('only')],
+    })
+    const only = single.manager.getInterrupts()[0]
+    if (only?.kind !== 'generic') throw new Error('Expected generic interrupt')
+    only.resolveInterrupt('done')
+    expect(single.submit).toHaveBeenCalledTimes(1)
+    await settle()
+  })
+
+  it('validates async Standard Schema candidates and preserves a prior valid draft', async () => {
+    const asyncOutputSchema: StandardSchemaV1<unknown, { accountId: string }> =
+      {
+        '~standard': {
+          version: 1,
+          vendor: 'test',
+          validate: async (value) =>
+            isAccountOutput(value)
+              ? { value }
+              : { issues: [{ message: 'accountId is required' }] },
+        },
+      }
+    const asyncTool = toolDefinition({
+      name: 'asyncLookup',
+      description: 'Async validation',
+      outputSchema: asyncOutputSchema,
+    }).client()
+    const outputSchemaHash = hashSchemaInput(asyncOutputSchema)
+    const submit = vi.fn(
+      async (_submission: InterruptManagerSubmission) => undefined,
+    )
+    const manager = new InterruptManager({
+      tools: [asyncTool] as const,
+      submit,
+    })
+    const binding: InterruptBinding = {
+      kind: 'client-tool-execution',
+      interruptId: 'async-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      toolName: 'asyncLookup',
+      toolCallId: 'call-1',
+      outputSchemaHash,
+      responseSchemaHash: outputSchemaHash,
+    }
+    manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [descriptor(binding), genericDescriptor('other')],
+    })
+
+    // `client-tool-execution` is internal only: the public array surfaces just
+    // the generic item, never the client tool.
+    expect(manager.getInterrupts()).toHaveLength(1)
+    expect(manager.getInterrupts()[0]?.kind).toBe('generic')
+
+    // The client tool result resolves through the internal path (the same one
+    // `addToolResult` uses) and is validated against the tool's output schema.
+    expect(
+      manager.resolveClientToolOutput('call-1', { accountId: 'valid' }),
+    ).toBe(true)
+    await settle()
+
+    // The batch submits only once both the internal client-tool item and the
+    // public generic item are resolved.
+    expect(submit).not.toHaveBeenCalled()
+    const generic = manager.getInterrupts()[0]
+    if (generic?.kind !== 'generic') {
+      throw new Error('Expected generic interrupt')
+    }
+    generic.resolveInterrupt('done')
+    await settle()
+    expect(submit).toHaveBeenCalledTimes(1)
+  })
+
+  it('rolls callback transactions back on thrown, returned, thenable, or incomplete work', () => {
+    const { manager, submit } = createManager()
+    manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [genericDescriptor('one'), genericDescriptor('two')],
+    })
+
+    manager.resolve(() => {
+      throw new Error('transaction failed')
+    })
+    Reflect.apply(manager.resolve, manager, [
+      (item: ChatInterrupt<typeof tools>) => {
+        item.cancel()
+        return 'not undefined'
+      },
+    ])
+    Reflect.apply(manager.resolve, manager, [() => Promise.resolve()])
+    manager.resolve((item) => {
+      if (item.id === 'one') item.cancel()
+      return undefined
+    })
+
+    expect(submit).not.toHaveBeenCalled()
+    expect(
+      manager.getInterrupts().every((item) => item.status === 'pending'),
+    ).toBe(true)
+    expect(manager.getInterruptErrors()).toHaveLength(4)
+  })
+
+  it('seals transaction items, invokes the callback once per item, and submits atomically', () => {
+    const { manager, submit } = createManager()
+    manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [genericDescriptor('one'), genericDescriptor('two')],
+    })
+    const calls: Array<string> = []
+    let lateCancel: (() => void) | undefined
+
+    manager.resolve((item) => {
+      calls.push(item.id)
+      if (item.id === 'one') lateCancel = item.cancel
+      item.cancel()
+      return undefined
+    })
+
+    expect(calls).toEqual(['one', 'two'])
+    expect(submit).toHaveBeenCalledTimes(1)
+    expect(() => lateCancel?.()).toThrow('inactive')
+    expect(() => manager.getInterrupts()[0]?.clearResolution()).toThrow(
+      'submitting',
+    )
+  })
+
+  it('permits boolean bulk resolution only for payloadless tool approvals and cancels all payloadlessly', () => {
+    const approvalTool = toolDefinition({
+      name: 'confirmOnly',
+      description: 'Confirm only',
+      needsApproval: true,
+    }).client()
+    const approval = normalizeApprovalSchema(undefined, undefined)
+    const binding: InterruptBinding = {
+      kind: 'tool-approval',
+      interruptId: 'approval-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      toolName: 'confirmOnly',
+      toolCallId: 'call-1',
+      originalArgs: {},
+      inputSchemaHash: hashSchemaInput(undefined),
+      approvalSchemaHash: approval.approvalSchemaHash,
+      responseSchemaHash: approval.responseSchemaHash,
+    }
+    const submit = vi.fn(
+      async (_submission: InterruptManagerSubmission) => undefined,
+    )
+    const approvals = new InterruptManager({
+      tools: [approvalTool] as const,
+      submit,
+    })
+    approvals.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [
+        descriptor(binding, { responseSchema: approval.responseSchema }),
+      ],
+    })
+    approvals.resolve(true)
+    expect(submit.mock.calls[0]?.[0].resolutions).toEqual([
+      {
+        interruptId: 'approval-1',
+        status: 'resolved',
+        payload: { approved: true },
+      },
+    ])
+
+    const generic = createManager()
+    generic.manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [genericDescriptor('generic')],
+    })
+    generic.manager.resolve(false)
+    expect(generic.submit).not.toHaveBeenCalled()
+    expect(generic.manager.getInterruptErrors()[0]?.code).toBe(
+      'unsupported-bulk-operation',
+    )
+    generic.manager.cancel()
+    expect(generic.submit.mock.calls[0]?.[0].resolutions).toEqual([
+      { interruptId: 'generic', status: 'cancelled' },
+    ])
+  })
+
+  it('retries the exact frozen batch only for retryable failures and recovers conflicts', async () => {
+    const retryable = {
+      scope: 'batch' as const,
+      code: 'transport' as const,
+      message: 'offline',
+      source: 'transport' as const,
+      retryable: true,
+      interruptIds: ['generic'],
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+    }
+    const submit = vi
+      .fn(async (_submission: InterruptManagerSubmission) => undefined)
+      .mockRejectedValueOnce({ errors: [retryable] })
+      .mockResolvedValue(undefined)
+    const recover = vi.fn(async () => undefined)
+    const manager = new InterruptManager({ submit, recover })
+    manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [genericDescriptor('generic')],
+    })
+    const retryItem = manager.getInterrupts()[0]
+    if (retryItem?.kind !== 'generic') {
+      throw new Error('Expected generic interrupt')
+    }
+    retryItem.resolveInterrupt('answer')
+    await settle()
+
+    const firstSubmission = submit.mock.calls[0]?.[0]
+    manager.retry()
+    expect(submit.mock.calls[1]?.[0]).toBe(firstSubmission)
+    await settle()
+    manager.getInterrupts()[0]?.clearResolution()
+    manager.retry()
+    expect(submit).toHaveBeenCalledTimes(2)
+
+    const conflictSubmit = vi.fn(
+      async (_submission: InterruptManagerSubmission) => ({
+        status: 'conflict' as const,
+        authoritativeState: {
+          schemaVersion: 1 as const,
+          state: 'pending' as const,
+          threadId: 'thread-1',
+          interruptedRunId: 'run-1',
+          generation: 2,
+          pendingInterrupts: [],
+        },
+      }),
+    )
+    const conflictManager = new InterruptManager({
+      submit: conflictSubmit,
+      recover,
+    })
+    conflictManager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [genericDescriptor('generic')],
+    })
+    conflictManager.getInterrupts()[0]?.cancel()
+    await settle()
+    expect(recover).toHaveBeenCalled()
+  })
+
+  it('supersedes a server batch error set without dropping local client, transport, or item errors', async () => {
+    const firstErrors: ReadonlyArray<InterruptSubmissionError> = [
+      {
+        scope: 'batch',
+        code: 'incomplete-batch',
+        message: 'first incomplete batch',
+        source: 'client',
+        retryable: false,
+        interruptIds: ['generic'],
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+      },
+      {
+        scope: 'batch',
+        code: 'item-validation-failed',
+        message: 'first aggregate validation failure',
+        source: 'client',
+        retryable: false,
+        interruptIds: ['generic'],
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+      },
+      {
+        scope: 'item',
+        interruptId: 'generic',
+        code: 'unknown-interrupt',
+        message: 'first item failure',
+        source: 'client',
+        retryable: false,
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+      },
+      {
+        scope: 'batch',
+        code: 'transport',
+        message: 'transport failure remains locally actionable',
+        source: 'transport',
+        retryable: false,
+        interruptIds: ['generic'],
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+      },
+    ]
+    const secondErrors: ReadonlyArray<InterruptSubmissionError> = [
+      {
+        scope: 'batch',
+        code: 'incomplete-batch',
+        message: 'updated incomplete batch',
+        source: 'client',
+        retryable: false,
+        interruptIds: ['generic'],
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+      },
+      {
+        scope: 'batch',
+        code: 'server',
+        message: 'a distinct server failure',
+        source: 'client',
+        retryable: false,
+        interruptIds: ['generic'],
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+      },
+      {
+        scope: 'item',
+        interruptId: 'generic',
+        code: 'unknown-interrupt',
+        message: 'updated item failure',
+        source: 'client',
+        retryable: false,
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+      },
+    ]
+    const submit = vi
+      .fn(async (_submission: InterruptManagerSubmission) => undefined)
+      .mockRejectedValueOnce({ errors: firstErrors })
+      .mockRejectedValueOnce({ errors: secondErrors })
+    const manager = new InterruptManager({ submit })
+    manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [genericDescriptor('generic')],
+    })
+
+    manager.resolve(() => undefined)
+    const firstItem = manager.getInterrupts()[0]
+    if (firstItem?.kind !== 'generic') {
+      throw new Error('Expected generic interrupt')
+    }
+    firstItem.resolveInterrupt('first answer')
+    await settle()
+    manager.getInterrupts()[0]?.clearResolution()
+    const secondItem = manager.getInterrupts()[0]
+    if (secondItem?.kind !== 'generic') {
+      throw new Error('Expected generic interrupt')
+    }
+    secondItem.resolveInterrupt('second answer')
+    await settle()
+
+    expect(manager.getInterruptErrors()).toMatchObject([
+      {
+        code: 'incomplete-batch',
+        message: 'Interrupt transaction did not resolve every item.',
+        source: 'client',
+      },
+      {
+        code: 'transport',
+        message: 'transport failure remains locally actionable',
+        source: 'transport',
+      },
+      {
+        code: 'incomplete-batch',
+        message: 'updated incomplete batch',
+        source: 'client',
+      },
+      {
+        code: 'server',
+        message: 'a distinct server failure',
+        source: 'client',
+      },
+    ])
+    expect(manager.getInterrupts()[0]?.errors).toMatchObject([
+      {
+        code: 'unknown-interrupt',
+        message: 'updated item failure',
+        source: 'client',
+      },
+    ])
+  })
+
+  it('rejects submission errors that do not correlate to the active interrupt batch', async () => {
+    const foreignErrors: ReadonlyArray<InterruptSubmissionError> = [
+      {
+        scope: 'item',
+        interruptId: 'generic',
+        code: 'unknown-interrupt',
+        message: 'foreign thread',
+        source: 'server',
+        retryable: false,
+        threadId: 'other-thread',
+        interruptedRunId: 'run-1',
+        generation: 1,
+      },
+      {
+        scope: 'item',
+        interruptId: 'generic',
+        code: 'unknown-interrupt',
+        message: 'foreign run',
+        source: 'server',
+        retryable: false,
+        threadId: 'thread-1',
+        interruptedRunId: 'other-run',
+        generation: 1,
+      },
+      {
+        scope: 'item',
+        interruptId: 'generic',
+        code: 'unknown-interrupt',
+        message: 'foreign generation',
+        source: 'server',
+        retryable: false,
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 2,
+      },
+      {
+        scope: 'item',
+        interruptId: 'other-interrupt',
+        code: 'unknown-interrupt',
+        message: 'foreign item',
+        source: 'server',
+        retryable: false,
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+      },
+      {
+        scope: 'batch',
+        code: 'item-validation-failed',
+        message: 'foreign batch',
+        source: 'server',
+        retryable: false,
+        interruptIds: ['other-interrupt'],
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+      },
+    ]
+    const submit = vi
+      .fn(async (_submission: InterruptManagerSubmission) => undefined)
+      .mockRejectedValueOnce({ errors: foreignErrors })
+    const manager = new InterruptManager({ submit })
+    manager.hydrate({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      interrupts: [genericDescriptor('generic')],
+    })
+    const item = manager.getInterrupts()[0]
+    if (item?.kind !== 'generic') {
+      throw new Error('Expected generic interrupt')
+    }
+
+    item.resolveInterrupt('answer')
+    await settle()
+
+    expect(manager.getInterrupts()[0]?.errors).toEqual([])
+    expect(manager.getInterruptErrors()).toMatchObject([
+      {
+        code: 'protocol',
+        message: 'Interrupt submission errors did not match the active batch.',
+        source: 'client',
+        retryable: false,
+      },
+    ])
+  })
+})
+
+function isAccountOutput(value: unknown): value is { accountId: string } {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'accountId' in value &&
+    typeof value.accountId === 'string' &&
+    value.accountId.length > 0
+  )
+}
+
+describe('ChatClient native interrupts', () => {
+  it('publishes the shared immutable interrupt state callback', () => {
+    const onInterruptStateChange = vi.fn()
+    const interrupt = genericDescriptor('generic-1')
+
+    const client = new ChatClient({
+      connection: { async *connect() {} },
+      onInterruptStateChange,
+      initialResumeSnapshot: {
+        schemaVersion: 2,
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [interrupt],
+        interruptState: {
+          recoveryState: {
+            schemaVersion: 1,
+            state: 'pending',
+            threadId: 'thread-1',
+            interruptedRunId: 'run-1',
+            generation: 1,
+            pendingInterrupts: [interrupt],
+          },
+          drafts: [],
+        },
+      },
+    })
+
+    expect(onInterruptStateChange).toHaveBeenLastCalledWith(
+      client.getInterruptState(),
+    )
+    const state = onInterruptStateChange.mock.lastCall?.[0]
+    expect(state?.interrupts).toBe(state?.pendingInterrupts)
+  })
+
+  it('owns one immutable interrupt state and resumes with a fresh child run', async () => {
+    const contexts: Array<RunAgentInputContext | undefined> = []
+    const sentMessages: Array<Array<ModelMessage> | Array<UIMessage>> = []
+    const binding: InterruptBinding = {
+      kind: 'generic',
+      interruptId: 'generic-1',
+      interruptedRunId: 'placeholder',
+      generation: 4,
+      responseSchemaHash: 'none',
+    }
+    let call = 0
+    const connection: ConnectConnectionAdapter = {
+      async *connect(messages, _data, _signal, context) {
+        contexts.push(context)
+        sentMessages.push(messages)
+        call++
+        const runId = context?.runId ?? `run-${call}`
+        const threadId = context?.threadId ?? 'thread-1'
+        yield {
+          type: EventType.RUN_STARTED,
+          runId,
+          threadId,
+          timestamp: Date.now(),
+        }
+        if (call === 1) {
+          binding.interruptedRunId = runId
+          yield {
+            type: EventType.RUN_FINISHED,
+            runId,
+            threadId,
+            timestamp: Date.now(),
+            outcome: {
+              type: 'interrupt',
+              interrupts: [descriptor(binding)],
+            },
+          }
+          return
+        }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId,
+          threadId,
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        }
+      },
+    }
+    const client = new ChatClient({ connection, threadId: 'thread-1' })
+
+    await client.sendMessage('start')
+    const state = client.getInterruptState()
+    expect(Object.isFrozen(state)).toBe(true)
+    expect(state.interrupts).toBe(state.pendingInterrupts)
+    expect(client.getInterrupts()).toBe(state.interrupts)
+    expect(client.getPendingInterrupts()).toBe(state.interrupts)
+    const item = state.interrupts[0]
+    if (item?.kind !== 'generic') throw new Error('Expected generic interrupt')
+    item.resolveInterrupt({ answer: 42 })
+
+    await vi.waitFor(() => expect(contexts).toHaveLength(2))
+    expect(contexts[1]).toMatchObject({
+      threadId: 'thread-1',
+      parentRunId: contexts[0]?.runId,
+      resume: [
+        {
+          interruptId: 'generic-1',
+          status: 'resolved',
+          payload: { answer: 42 },
+        },
+      ],
+    })
+    expect(contexts[1]?.runId).not.toBe(contexts[0]?.runId)
+    expect(sentMessages[1]).not.toEqual([])
+    expect(sentMessages[1]).toEqual(sentMessages[0])
+  })
+
+  it('preserves the exact interrupt batch and joins a replay after a child transport failure', async () => {
+    const contexts: Array<RunAgentInputContext | undefined> = []
+    const joined: Array<string> = []
+    const binding: InterruptBinding = {
+      kind: 'generic',
+      interruptId: 'generic-1',
+      interruptedRunId: 'placeholder',
+      generation: 1,
+      responseSchemaHash: 'none',
+    }
+    let calls = 0
+    const connection: ConnectConnectionAdapter = {
+      async *connect(_messages, _data, _signal, context) {
+        contexts.push(context)
+        calls++
+        const runId = context?.runId ?? `run-${calls}`
+        if (calls === 1) {
+          binding.interruptedRunId = runId
+          yield {
+            type: EventType.RUN_FINISHED,
+            threadId: 'thread-1',
+            runId,
+            timestamp: Date.now(),
+            outcome: {
+              type: 'interrupt',
+              interrupts: [descriptor(binding)],
+            },
+          }
+          return
+        }
+        if (calls === 2) throw new Error('continuation transport failed')
+        yield {
+          type: EventType.RUN_FINISHED,
+          threadId: 'thread-1',
+          runId,
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+          result: {
+            replayed: true,
+            continuationRunId: 'winner-run',
+          },
+        }
+      },
+      async *joinRun(runId) {
+        joined.push(runId)
+        yield {
+          type: EventType.RUN_FINISHED,
+          threadId: 'thread-1',
+          runId,
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        }
+      },
+    }
+    const client = new ChatClient({ connection, threadId: 'thread-1' })
+
+    await client.sendMessage('start')
+    client.getInterrupts()[0]?.resolveInterrupt({ answer: 42 })
+
+    await vi.waitFor(() => expect(contexts).toHaveLength(2))
+    await vi.waitFor(() =>
+      expect(client.getInterrupts()[0]).toMatchObject({
+        id: 'generic-1',
+        status: 'error',
+      }),
+    )
+    expect(Object.isFrozen(client.getInterrupts())).toBe(true)
+    client.retryInterrupts()
+
+    await vi.waitFor(() => expect(contexts).toHaveLength(3))
+    expect(contexts[2]?.resume).toEqual(contexts[1]?.resume)
+    await vi.waitFor(() => expect(joined).toEqual(['winner-run']))
+  })
+
+  it('resumes a hydrated ephemeral batch with full history in a fresh child run', async () => {
+    const contexts: Array<RunAgentInputContext | undefined> = []
+    const sentMessages: Array<Array<ModelMessage> | Array<UIMessage>> = []
+    let calls = 0
+    const connection: ConnectConnectionAdapter = {
+      async *connect(messages, _data, _signal, context) {
+        contexts.push(context)
+        sentMessages.push(messages)
+        calls++
+        const runId = context?.runId ?? `run-${calls}`
+        if (calls === 1) {
+          yield {
+            type: EventType.RUN_FINISHED,
+            threadId: 'thread-1',
+            runId,
+            timestamp: Date.now(),
+            outcome: {
+              type: 'interrupt',
+              interrupts: [
+                descriptor({
+                  kind: 'generic',
+                  interruptId: 'first',
+                  interruptedRunId: runId,
+                  generation: 1,
+                  responseSchemaHash: 'none',
+                }),
+                descriptor({
+                  kind: 'generic',
+                  interruptId: 'second',
+                  interruptedRunId: runId,
+                  generation: 1,
+                  responseSchemaHash: 'none',
+                }),
+              ],
+            },
+          }
+          return
+        }
+        yield {
+          type: EventType.RUN_FINISHED,
+          threadId: 'thread-1',
+          runId,
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        }
+      },
+    }
+    const client = new ChatClient({ connection, threadId: 'thread-1' })
+
+    await client.sendMessage('start')
+    const visited: Array<string> = []
+    client.resolveInterrupts((interrupt) => {
+      visited.push(interrupt.id)
+      interrupt.cancel()
+      return undefined
+    })
+
+    await vi.waitFor(() => expect(contexts).toHaveLength(2))
+    expect(visited).toEqual(['first', 'second'])
+    expect(contexts[1]).toMatchObject({
+      threadId: 'thread-1',
+      parentRunId: contexts[0]?.runId,
+      resume: [
+        { interruptId: 'first', status: 'cancelled' },
+        { interruptId: 'second', status: 'cancelled' },
+      ],
+    })
+    expect(contexts[1]?.runId).not.toBe(contexts[0]?.runId)
+    expect(sentMessages[1]).not.toEqual([])
+    expect(sentMessages[1]).toEqual(sentMessages[0])
+  })
+
+  it('writes a raw V2 snapshot with authoritative recovery state', async () => {
+    const writes: Array<ChatResumeSnapshotV2> = []
+    const persistence: ChatServerPersistence = {
+      getItem: () => undefined,
+      setItem: (_id, value) => {
+        if (value.schemaVersion === 2) writes.push(value)
+      },
+      removeItem: () => undefined,
+    }
+    const binding: InterruptBinding = {
+      kind: 'generic',
+      interruptId: 'generic-1',
+      interruptedRunId: 'run-1',
+      generation: 4,
+      responseSchemaHash: 'none',
+    }
+    const connection: ConnectConnectionAdapter = {
+      async *connect(_messages, _data, _signal, context) {
+        binding.interruptedRunId = context?.runId ?? 'run-1'
+        yield {
+          type: EventType.RUN_FINISHED,
+          threadId: context?.threadId ?? 'thread-1',
+          runId: binding.interruptedRunId,
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [descriptor(binding)],
+          },
+        }
+      },
+    }
+    const client = new ChatClient({
+      connection,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+    })
+
+    await client.sendMessage('start')
+
+    expect(writes.at(-1)).toEqual({
+      schemaVersion: 2,
+      resumeState: {
+        threadId: 'thread-1',
+        runId: binding.interruptedRunId,
+      },
+      pendingInterrupts: [descriptor(binding)],
+      interruptState: {
+        recoveryState: {
+          schemaVersion: 1,
+          state: 'pending',
+          threadId: 'thread-1',
+          interruptedRunId: binding.interruptedRunId,
+          generation: 4,
+          pendingInterrupts: [descriptor(binding)],
+        },
+        drafts: [],
+      },
+    })
+    expect(JSON.parse(JSON.stringify(writes.at(-1)))).toEqual(writes.at(-1))
+  })
+
+  it('hydrates V2 drafts immediately before reconciling authoritative state', async () => {
+    const first = genericDescriptor('first')
+    const second = genericDescriptor('second')
+    const connect = vi.fn(async function* () {})
+    let releaseRecovery: ((state: InterruptRecoveryStateV1) => void) | undefined
+    const recovery = new Promise<InterruptRecoveryStateV1>((resolve) => {
+      releaseRecovery = resolve
+    })
+    const loadInterruptState = vi.fn(() => recovery)
+    const client = new ChatClient({
+      connection: { connect, loadInterruptState },
+      initialResumeSnapshot: {
+        schemaVersion: 2,
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [first, second],
+        interruptState: {
+          recoveryState: {
+            schemaVersion: 1,
+            state: 'pending',
+            threadId: 'thread-1',
+            interruptedRunId: 'run-1',
+            generation: 1,
+            pendingInterrupts: [first, second],
+          },
+          drafts: [
+            {
+              interruptId: 'first',
+              response: {
+                interruptId: 'first',
+                status: 'resolved',
+                payload: { answer: 42 },
+              },
+              status: 'staged',
+            },
+          ],
+        },
+      },
+    })
+
+    expect(client.getInterrupts().map((item) => item.status)).toEqual([
+      'staged',
+      'pending',
+    ])
+    releaseRecovery?.({
+      schemaVersion: 1,
+      state: 'pending',
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      pendingInterrupts: [first, second],
+    })
+    await settle()
+    await settle()
+    expect(client.getInterrupts()).toHaveLength(2)
+    expect(client.getInterrupts().map((item) => item.status)).toEqual([
+      'staged',
+      'pending',
+    ])
+    expect(loadInterruptState).toHaveBeenCalledWith({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      knownGeneration: 1,
+    })
+    expect(connect).not.toHaveBeenCalled()
+  })
+
+  it('hydrates V2 fallback descriptors when recovery is unavailable', () => {
+    const fallback = genericDescriptor('fallback')
+    const malformed = JSON.parse(
+      JSON.stringify({
+        schemaVersion: 2,
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [fallback],
+        interruptState: {
+          recoveryState: {
+            schemaVersion: 1,
+            state: 'pending',
+            threadId: 'other-thread',
+            interruptedRunId: 'run-1',
+            generation: 99,
+            pendingInterrupts: [],
+          },
+          drafts: [],
+        },
+      }),
+    )
+    const client = new ChatClient({
+      connection: { async *connect() {} },
+      initialResumeSnapshot: malformed,
+    })
+
+    expect(client.getResumeState()).toEqual({
+      threadId: 'thread-1',
+      runId: 'run-1',
+    })
+    expect(client.getInterrupts().map((item) => item.id)).toEqual(['fallback'])
+    expect(client.getInterruptState().interruptErrors).toEqual([])
+  })
+
+  it.each([
+    ['null recovery state', { recoveryState: null, drafts: [] }],
+    ['array recovery state', { recoveryState: [], drafts: [] }],
+    [
+      'invalid drafts',
+      {
+        recoveryState: {
+          schemaVersion: 1,
+          state: 'pending',
+          threadId: 'thread-1',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          pendingInterrupts: [],
+        },
+        drafts: { interruptId: 'not-an-array' },
+      },
+    ],
+  ])(
+    'hydrates fallback descriptors for malformed V2 %s without losing resume state',
+    (_label, interruptState) => {
+      const malformed = JSON.parse(
+        JSON.stringify({
+          schemaVersion: 2,
+          resumeState: { threadId: 'thread-1', runId: 'run-1' },
+          pendingInterrupts: [genericDescriptor('fallback')],
+          interruptState,
+        }),
+      )
+
+      let client: ChatClient | undefined
+      expect(() => {
+        client = new ChatClient({
+          connection: { async *connect() {} },
+          initialResumeSnapshot: malformed,
+        })
+      }).not.toThrow()
+      expect(client?.getResumeState()).toEqual({
+        threadId: 'thread-1',
+        runId: 'run-1',
+      })
+      expect(client?.getInterrupts().map((item) => item.id)).toEqual([
+        'fallback',
+      ])
+      expect(client?.getInterruptState().interruptErrors).toEqual([])
+    },
+  )
+
+  it('hydrates V1 descriptors before explicit recovery replaces them', async () => {
+    const persisted = genericDescriptor('persisted')
+    const authoritative = genericDescriptor('authoritative')
+    let releaseRecovery: ((state: InterruptRecoveryStateV1) => void) | undefined
+    const recovery = new Promise<InterruptRecoveryStateV1>((resolve) => {
+      releaseRecovery = resolve
+    })
+    const loadInterruptState = vi.fn(() => recovery)
+    const client = new ChatClient({
+      connection: { async *connect() {}, loadInterruptState },
+      initialResumeSnapshot: {
+        schemaVersion: 1,
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [persisted],
+      },
+    })
+
+    expect(client.getInterrupts().map((item) => item.id)).toEqual(['persisted'])
+    releaseRecovery?.({
+      schemaVersion: 1,
+      state: 'pending',
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      generation: 1,
+      pendingInterrupts: [authoritative],
+    })
+    await vi.waitFor(() =>
+      expect(client.getInterrupts()[0]?.id).toBe('authoritative'),
+    )
+    expect(loadInterruptState).toHaveBeenCalledWith({
+      threadId: 'thread-1',
+      interruptedRunId: 'run-1',
+      knownGeneration: 1,
+    })
+  })
+
+  it('recovers a committed winner by joining it read-only', async () => {
+    const contexts: Array<RunAgentInputContext | undefined> = []
+    const joined: Array<string> = []
+    const binding = genericDescriptor('generic-1')
+    let interruptedRunId = 'run-1'
+    let calls = 0
+    const connection: ConnectConnectionAdapter = {
+      async *connect(_messages, _data, _signal, context) {
+        contexts.push(context)
+        calls++
+        if (calls === 1) {
+          interruptedRunId = context?.runId ?? interruptedRunId
+          const metadata = binding.metadata?.['tanstack:interruptBinding']
+          if (metadata && typeof metadata === 'object') {
+            metadata.interruptedRunId = interruptedRunId
+          }
+          yield {
+            type: EventType.RUN_FINISHED,
+            threadId: 'thread-1',
+            runId: interruptedRunId,
+            timestamp: Date.now(),
+            outcome: { type: 'interrupt', interrupts: [binding] },
+          }
+          return
+        }
+        yield {
+          type: EventType.RUN_ERROR,
+          threadId: 'thread-1',
+          runId: context?.runId ?? 'loser-run',
+          timestamp: Date.now(),
+          message: 'conflict',
+          code: 'conflict',
+          'tanstack:interruptErrors': [
+            {
+              scope: 'batch',
+              code: 'conflict',
+              message: 'another continuation won',
+              source: 'server',
+              retryable: false,
+              interruptIds: ['generic-1'],
+              threadId: 'thread-1',
+              interruptedRunId,
+              generation: 1,
+            },
+          ],
+          'tanstack:interruptRecovery': {
+            schemaVersion: 1,
+            state: 'committed',
+            threadId: 'thread-1',
+            interruptedRunId,
+            generation: 1,
+            pendingInterrupts: [],
+            committed: {
+              fingerprint: 'winner',
+              continuationRunId: 'winner-run',
+              committedAt: '2026-07-13T00:00:00.000Z',
+            },
+          },
+        }
+      },
+      async *joinRun(runId) {
+        joined.push(runId)
+        yield {
+          type: EventType.RUN_FINISHED,
+          threadId: 'thread-1',
+          runId,
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        }
+      },
+    }
+    const client = new ChatClient({ connection, threadId: 'thread-1' })
+
+    await client.sendMessage('start')
+    client.getInterrupts()[0]?.cancel()
+
+    await vi.waitFor(() => expect(joined).toEqual(['winner-run']))
+    expect(contexts).toHaveLength(2)
+    expect(client.getInterrupts()).toHaveLength(0)
+    expect(client.getInterruptState().interruptErrors).toMatchObject([
+      { code: 'conflict', source: 'server' },
+    ])
+  })
+
+  it('replays a persisted committed winner through an explicit continuation loader', async () => {
+    const connect = vi.fn(async function* () {})
+    const continuationLoader = vi.fn(async function* (runId: string) {
+      yield {
+        type: EventType.RUN_FINISHED as const,
+        threadId: 'thread-1',
+        runId,
+        timestamp: Date.now(),
+        outcome: { type: 'success' as const },
+      }
+    })
+    const client = new ChatClient({
+      connection: { connect },
+      continuationLoader,
+      initialResumeSnapshot: {
+        schemaVersion: 2,
+        resumeState: { threadId: 'thread-1', runId: 'interrupted-run' },
+        pendingInterrupts: [],
+        interruptState: {
+          recoveryState: {
+            schemaVersion: 1,
+            state: 'committed',
+            threadId: 'thread-1',
+            interruptedRunId: 'interrupted-run',
+            generation: 1,
+            pendingInterrupts: [],
+            committed: {
+              fingerprint: 'winner',
+              continuationRunId: 'winner-run',
+              committedAt: '2026-07-13T00:00:00.000Z',
+            },
+          },
+          drafts: [],
+        },
+      },
+    })
+
+    await vi.waitFor(() =>
+      expect(continuationLoader).toHaveBeenCalledWith('winner-run'),
+    )
+    await vi.waitFor(() => expect(client.getResumeState()).toBeNull())
+    expect(connect).not.toHaveBeenCalled()
+  })
+
+  it('reports recovery-unavailable when a committed winner cannot be joined', async () => {
+    const client = new ChatClient({
+      connection: { async *connect() {} },
+      initialResumeSnapshot: {
+        schemaVersion: 2,
+        resumeState: { threadId: 'thread-1', runId: 'interrupted-run' },
+        pendingInterrupts: [],
+        interruptState: {
+          recoveryState: {
+            schemaVersion: 1,
+            state: 'committed',
+            threadId: 'thread-1',
+            interruptedRunId: 'interrupted-run',
+            generation: 1,
+            pendingInterrupts: [],
+            committed: {
+              fingerprint: 'winner',
+              continuationRunId: 'winner-run',
+              committedAt: '2026-07-13T00:00:00.000Z',
+            },
+          },
+          drafts: [],
+        },
+      },
+    })
+
+    await vi.waitFor(() =>
+      expect(client.getInterruptState().interruptErrors[0]?.code).toBe(
+        'recovery-unavailable',
+      ),
+    )
+  })
+
+  it('loads authoritative pending state only through the explicit recovery operation', async () => {
+    const original = genericDescriptor('generic-1')
+    const replacement = descriptor({
+      kind: 'generic',
+      interruptId: 'generic-2',
+      interruptedRunId: 'run-1',
+      generation: 2,
+      responseSchemaHash: 'none',
+    })
+    let interruptedRunId = 'run-1'
+    let calls = 0
+    const loadInterruptState = vi.fn(async () => ({
+      schemaVersion: 1 as const,
+      state: 'pending' as const,
+      threadId: 'thread-1',
+      interruptedRunId,
+      generation: 2,
+      pendingInterrupts: [replacement],
+    }))
+    const connection: ConnectConnectionAdapter = {
+      async *connect(_messages, _data, _signal, context) {
+        calls++
+        if (calls === 1) {
+          interruptedRunId = context?.runId ?? interruptedRunId
+          const metadata = original.metadata?.['tanstack:interruptBinding']
+          if (metadata && typeof metadata === 'object') {
+            metadata.interruptedRunId = interruptedRunId
+          }
+          const nextMetadata =
+            replacement.metadata?.['tanstack:interruptBinding']
+          if (nextMetadata && typeof nextMetadata === 'object') {
+            nextMetadata.interruptedRunId = interruptedRunId
+          }
+          yield {
+            type: EventType.RUN_FINISHED,
+            threadId: 'thread-1',
+            runId: interruptedRunId,
+            timestamp: Date.now(),
+            outcome: { type: 'interrupt', interrupts: [original] },
+          }
+          return
+        }
+        yield {
+          type: EventType.RUN_ERROR,
+          threadId: 'thread-1',
+          runId: context?.runId ?? 'loser-run',
+          timestamp: Date.now(),
+          message: 'stale',
+          code: 'stale',
+          'tanstack:interruptErrors': [
+            {
+              scope: 'batch',
+              code: 'stale',
+              message: 'stale generation',
+              source: 'server',
+              retryable: false,
+              interruptIds: ['generic-1'],
+              threadId: 'thread-1',
+              interruptedRunId,
+              generation: 1,
+            },
+          ],
+        }
+      },
+      loadInterruptState,
+    }
+    const client = new ChatClient({ connection, threadId: 'thread-1' })
+
+    await client.sendMessage('start')
+    client.getInterrupts()[0]?.cancel()
+
+    await vi.waitFor(() =>
+      expect(client.getInterrupts()[0]).toMatchObject({
+        id: 'generic-2',
+        generation: 2,
+      }),
+    )
+    expect(loadInterruptState).toHaveBeenCalledWith({
+      threadId: 'thread-1',
+      interruptedRunId,
+      knownGeneration: 1,
+    })
+  })
+})
diff --git a/packages/ai-client/tests/chat-client-resume.test.ts b/packages/ai-client/tests/chat-client-resume.test.ts
index f2e7e4839..fe06204bc 100644
--- a/packages/ai-client/tests/chat-client-resume.test.ts
+++ b/packages/ai-client/tests/chat-client-resume.test.ts
@@ -5,21 +5,35 @@ import type {
   ConnectConnectionAdapter,
   RunAgentInputContext,
 } from '../src/connection-adapters'
-import type { RunAgentResumeItem, StreamChunk } from '@tanstack/ai/client'
-import type { ChatResumeSnapshot, ChatServerPersistence } from '../src/types'
+import type {
+  ModelMessage,
+  RunAgentResumeItem,
+  StreamChunk,
+} from '@tanstack/ai/client'
+import type {
+  ChatResumeSnapshot,
+  ChatServerPersistence,
+  UIMessage,
+} from '../src/types'
 
 /**
  * Adapter that records each connect's runContext and yields scripted chunks.
  * A script can be a function of the live `runContext` (so a test can emit a
  * RUN_FINISHED carrying the same runId the client generated and passed in).
  */
+interface ThrowingScript {
+  chunks: Array<StreamChunk>
+  error: Error
+}
+
+type ScriptResult = Array<StreamChunk> | ThrowingScript
 type Script =
-  | Array<StreamChunk>
-  | ((ctx: RunAgentInputContext | undefined) => Array<StreamChunk>)
+  | ScriptResult
+  | ((ctx: RunAgentInputContext | undefined) => ScriptResult)
 
 function recordingAdapter(scripts: Array<Script>) {
   const contexts: Array<RunAgentInputContext | undefined> = []
-  const sentMessages: Array<Array<unknown>> = []
+  const sentMessages: Array<Array<ModelMessage> | Array<UIMessage>> = []
   let i = 0
   const adapter: ConnectConnectionAdapter = {
     // eslint-disable-next-line @typescript-eslint/require-await
@@ -28,14 +42,51 @@ function recordingAdapter(scripts: Array<Script>) {
       contexts.push(runContext)
       const script = scripts[i]
       i++
-      const chunks =
+      const result =
         typeof script === 'function' ? script(runContext) : (script ?? [])
+      const chunks = Array.isArray(result) ? result : result.chunks
       for (const c of chunks) yield c
+      if (!Array.isArray(result)) throw result.error
     },
   }
   return { adapter, contexts, sentMessages }
 }
 
+async function createInterruptedClient(continuation: Script) {
+  const { adapter } = recordingAdapter([
+    (ctx) => [
+      {
+        type: EventType.RUN_STARTED,
+        runId: ctx?.runId ?? 'interrupted-run',
+        threadId: ctx?.threadId ?? 'thread-1',
+        timestamp: Date.now(),
+      },
+      {
+        type: EventType.RUN_FINISHED,
+        runId: ctx?.runId ?? 'interrupted-run',
+        threadId: ctx?.threadId ?? 'thread-1',
+        timestamp: Date.now(),
+        outcome: {
+          type: 'interrupt',
+          interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+        },
+      },
+    ],
+    continuation,
+  ])
+  const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+  await client.sendMessage('hi')
+  return client
+}
+
+function resolveGenericInterrupt(client: ChatClient): void {
+  const interrupt = client.getInterrupts()[0]
+  if (interrupt?.kind !== 'generic') {
+    throw new Error('Expected a generic interrupt')
+  }
+  interrupt.resolveInterrupt({ answer: 'continue' })
+}
+
 const text = (delta: string): StreamChunk => ({
   type: EventType.TEXT_MESSAGE_CONTENT,
   messageId: 'm1',
@@ -210,13 +261,108 @@ describe('ChatClient resume', () => {
     await client.resumeInterrupts(resumeItems)
 
     expect(contexts[1]?.threadId).toBe(resumeState?.threadId)
-    expect(contexts[1]?.runId).toBe(resumeState?.runId)
+    expect(contexts[1]?.runId).not.toBe(resumeState?.runId)
+    expect(contexts[1]?.parentRunId).toBe(resumeState?.runId)
     expect(contexts[1]?.resume).toEqual(resumeItems)
     expect(client.getPendingInterrupts()).toEqual([])
     expect(client.getResumeState()).toBeNull()
   })
 
-  it('resumeInterrupts reconnects without re-sending message history', async () => {
+  it('clears interrupts when a resumed provider run has a different run id', async () => {
+    const resumeItems: Array<RunAgentResumeItem> = [
+      {
+        interruptId: 'interrupt-1',
+        status: 'resolved',
+        payload: { approved: true },
+      },
+    ]
+    const { adapter, contexts } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+      [
+        {
+          type: EventType.RUN_STARTED,
+          runId: 'provider-continuation-run',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+        },
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'provider-continuation-run',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        },
+      ],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+    expect(client.getPendingInterrupts()).toHaveLength(1)
+
+    await client.resumeInterrupts(resumeItems)
+
+    expect(contexts[1]?.runId).not.toBe('provider-continuation-run')
+    expect(client.getResumeState()).toBeNull()
+    expect(client.getPendingInterrupts()).toEqual([])
+  })
+
+  it('correlates a synthesized resume finish to the client request run', async () => {
+    const client = await createInterruptedClient([
+      {
+        type: EventType.RUN_STARTED,
+        runId: 'provider-continuation-run',
+        threadId: 'thread-1',
+        timestamp: Date.now(),
+      },
+    ])
+
+    resolveGenericInterrupt(client)
+
+    await vi.waitFor(() => expect(client.getInterrupts()).toEqual([]))
+    expect(client.getResumeState()).toBeNull()
+    expect(client.getSessionGenerating()).toBe(false)
+  })
+
+  it('correlates a synthesized resume error to the client request run', async () => {
+    const client = await createInterruptedClient({
+      chunks: [
+        {
+          type: EventType.RUN_STARTED,
+          runId: 'provider-continuation-run',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+        },
+      ],
+      error: new Error('continuation transport failed'),
+    })
+
+    resolveGenericInterrupt(client)
+
+    await vi.waitFor(() =>
+      expect(client.getInterrupts()[0]?.status).toBe('error'),
+    )
+    expect(client.getResumeState()).not.toBeNull()
+    expect(client.getSessionGenerating()).toBe(false)
+  })
+
+  it('resumeInterrupts reconnects with the full current message history', async () => {
     const resumeItems: Array<RunAgentResumeItem> = [
       {
         interruptId: 'interrupt-1',
@@ -254,7 +400,8 @@ describe('ChatClient resume', () => {
     await client.resumeInterrupts(resumeItems)
 
     expect(contexts[1]?.resume).toEqual(resumeItems)
-    expect(sentMessages[1]).toEqual([])
+    expect(sentMessages[1]).not.toEqual([])
+    expect(sentMessages[1]).toEqual(client.getMessages())
   })
 
   it('clears resume state and pending interrupts on a runless RUN_ERROR', async () => {
@@ -598,7 +745,11 @@ describe('ChatClient resume', () => {
                 id: 'approval-1',
                 reason: 'approval_required',
                 toolCallId: 'tool-1',
-                metadata: { kind: 'approval' },
+                metadata: {
+                  kind: 'approval',
+                  toolName: 'lookup',
+                  input: { query: 'first' },
+                },
               },
             ],
           },
@@ -650,13 +801,21 @@ describe('ChatClient resume', () => {
                 id: 'approval-1',
                 reason: 'approval_required',
                 toolCallId: 'tool-1',
-                metadata: { kind: 'approval' },
+                metadata: {
+                  kind: 'approval',
+                  toolName: 'lookup',
+                  input: { query: 'first' },
+                },
               },
               {
                 id: 'approval-2',
                 reason: 'approval_required',
                 toolCallId: 'tool-2',
-                metadata: { kind: 'approval' },
+                metadata: {
+                  kind: 'approval',
+                  toolName: 'lookup',
+                  input: { query: 'second' },
+                },
               },
             ],
           },
@@ -682,7 +841,7 @@ describe('ChatClient resume', () => {
       },
       {
         interruptId: 'approval-2',
-        status: 'cancelled',
+        status: 'resolved',
         payload: { approved: false },
       },
     ])
@@ -712,7 +871,11 @@ describe('ChatClient resume', () => {
             id: 'approval-1',
             reason: 'approval_required',
             toolCallId: 'tool-1',
-            metadata: { kind: 'approval' },
+            metadata: {
+              kind: 'approval',
+              toolName: 'lookup',
+              input: { query: 'restored' },
+            },
           },
         ],
       },
@@ -729,7 +892,8 @@ describe('ChatClient resume', () => {
     await client.addToolApprovalResponse({ id: 'approval-1', approved: true })
 
     expect(contexts[0]?.threadId).toBe('thread-1')
-    expect(contexts[0]?.runId).toBe('run-1')
+    expect(contexts[0]?.runId).not.toBe('run-1')
+    expect(contexts[0]?.parentRunId).toBe('run-1')
     expect(contexts[0]?.resume).toEqual([
       {
         interruptId: 'approval-1',
@@ -805,8 +969,30 @@ describe('ChatClient resume', () => {
     await client.sendMessage('hi')
 
     expect(persistence.setItem).toHaveBeenLastCalledWith('thread-1', {
+      schemaVersion: 2,
       resumeState: client.getResumeState(),
-      pendingInterrupts: client.getPendingInterrupts(),
+      pendingInterrupts: [
+        expect.objectContaining({
+          id: 'interrupt-1',
+          reason: 'client_tool_input',
+        }),
+      ],
+      interruptState: {
+        recoveryState: {
+          schemaVersion: 1,
+          state: 'pending',
+          threadId: 'thread-1',
+          interruptedRunId: client.getResumeState()?.runId,
+          generation: 0,
+          pendingInterrupts: [
+            expect.objectContaining({
+              id: 'interrupt-1',
+              reason: 'client_tool_input',
+            }),
+          ],
+        },
+        drafts: [],
+      },
     })
     expect(onResumeStateChange).toHaveBeenCalled()
   })
@@ -1300,6 +1486,11 @@ describe('ChatClient resume', () => {
                 id: 'interrupt-tool-1',
                 reason: 'client_tool_input',
                 toolCallId: 'tool-call-1',
+                metadata: {
+                  kind: 'client_tool',
+                  toolName: 'lookup',
+                  input: { query: 'first' },
+                },
               },
             ],
           },
@@ -1318,7 +1509,8 @@ describe('ChatClient resume', () => {
     })
 
     expect(contexts[1]?.threadId).toBe(resumeState?.threadId)
-    expect(contexts[1]?.runId).toBe(resumeState?.runId)
+    expect(contexts[1]?.runId).not.toBe(resumeState?.runId)
+    expect(contexts[1]?.parentRunId).toBe(resumeState?.runId)
     expect(contexts[1]?.resume).toEqual([
       {
         interruptId: 'interrupt-tool-1',
@@ -1350,11 +1542,21 @@ describe('ChatClient resume', () => {
                 id: 'interrupt-tool-1',
                 reason: 'client_tool_input',
                 toolCallId: 'tool-call-1',
+                metadata: {
+                  kind: 'client_tool',
+                  toolName: 'lookup',
+                  input: { query: 'first' },
+                },
               },
               {
                 id: 'interrupt-tool-2',
                 reason: 'client_tool_input',
                 toolCallId: 'tool-call-2',
+                metadata: {
+                  kind: 'client_tool',
+                  toolName: 'lookup',
+                  input: { query: 'second' },
+                },
               },
             ],
           },
diff --git a/packages/ai-client/tests/connection-adapters.test.ts b/packages/ai-client/tests/connection-adapters.test.ts
index 4c98d25d1..78b13a041 100644
--- a/packages/ai-client/tests/connection-adapters.test.ts
+++ b/packages/ai-client/tests/connection-adapters.test.ts
@@ -440,6 +440,7 @@ describe('connection-adapters', () => {
         {
           threadId: 'thread-1',
           runId: 'run-1',
+          parentRunId: 'interrupted-run',
           resume: [
             {
               interruptId: 'interrupt-1',
@@ -1230,6 +1231,60 @@ describe('connection-adapters', () => {
         expect(received[0].error?.message).toBe('already failed')
       }
     })
+
+    it('preserves read-only join and explicit interrupt recovery operations', async () => {
+      const recovery = {
+        schemaVersion: 1 as const,
+        state: 'pending' as const,
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 2,
+        pendingInterrupts: [],
+      }
+      const loadInterruptState = vi.fn(async () => recovery)
+      const base = {
+        async *connect() {
+          yield {
+            type: EventType.RUN_FINISHED,
+            threadId: 'thread-1',
+            runId: 'run-new',
+            timestamp: Date.now(),
+          } as const
+        },
+        async *joinRun(runId: string) {
+          yield {
+            type: EventType.RUN_FINISHED,
+            threadId: 'thread-1',
+            runId,
+            timestamp: Date.now(),
+          } as const
+        },
+        loadInterruptState,
+      }
+      const adapter = normalizeConnectionAdapter(base)
+      const abortController = new AbortController()
+      const received = (async () => {
+        for await (const chunk of adapter.subscribe(abortController.signal)) {
+          abortController.abort()
+          return chunk
+        }
+        return undefined
+      })()
+
+      await adapter.joinRun?.('winner-run')
+      expect(await received).toMatchObject({
+        type: EventType.RUN_FINISHED,
+        runId: 'winner-run',
+      })
+      await expect(
+        adapter.loadInterruptState?.({
+          threadId: 'thread-1',
+          interruptedRunId: 'run-1',
+          knownGeneration: 1,
+        }),
+      ).resolves.toBe(recovery)
+      expect(loadInterruptState).toHaveBeenCalledTimes(1)
+    })
   })
 
   describe('rpcStream', () => {
@@ -1354,6 +1409,7 @@ describe('connection-adapters', () => {
         {
           threadId: 'thread-1',
           runId: 'run-1',
+          parentRunId: 'interrupted-run',
           resume: [
             {
               interruptId: 'interrupt-1',
@@ -1374,6 +1430,7 @@ describe('connection-adapters', () => {
           payload: { approved: true },
         },
       ])
+      expect(input.parentRunId).toBe('interrupted-run')
     })
   })
 })
diff --git a/packages/ai-client/tests/interrupt-recovery-adapters.test.ts b/packages/ai-client/tests/interrupt-recovery-adapters.test.ts
new file mode 100644
index 000000000..3e5d846fc
--- /dev/null
+++ b/packages/ai-client/tests/interrupt-recovery-adapters.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai/client'
+import {
+  createInterruptContinuationLoader,
+  createInterruptStateFetcher,
+  fetchServerSentEvents,
+} from '../src/connection-adapters'
+import type { InterruptRecoveryStateV1 } from '@tanstack/ai/client'
+
+const recoveryState: InterruptRecoveryStateV1 = {
+  schemaVersion: 1,
+  state: 'pending',
+  threadId: 'thread-1',
+  interruptedRunId: 'run-1',
+  generation: 2,
+  pendingInterrupts: [],
+}
+
+function continuationResponse(): Response {
+  return new Response(
+    `data: ${JSON.stringify({
+      type: EventType.RUN_FINISHED,
+      threadId: 'thread-1',
+      runId: 'winner-run',
+      timestamp: 1,
+      outcome: { type: 'success' },
+    })}\n\n`,
+    { headers: { 'content-type': 'text/event-stream' } },
+  )
+}
+
+describe('interrupt recovery fetch adapters', () => {
+  it('fetches and strictly parses authoritative state from an explicit URL', async () => {
+    const fetchClient = vi.fn<typeof fetch>(async () =>
+      Response.json(recoveryState),
+    )
+    const fetchState = createInterruptStateFetcher('/api/recovery?tenant=one', {
+      fetchClient,
+      headers: { authorization: 'Bearer test' },
+    })
+
+    await expect(
+      fetchState({
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        knownGeneration: 2,
+      }),
+    ).resolves.toEqual(recoveryState)
+    const [url, init] = fetchClient.mock.calls[0] ?? []
+    expect(String(url)).toBe(
+      '/api/recovery?tenant=one&threadId=thread-1&interruptedRunId=run-1&knownGeneration=2',
+    )
+    expect(init?.method).toBe('POST')
+    expect(new Headers(init?.headers).get('authorization')).toBe('Bearer test')
+  })
+
+  it('rejects malformed recovery JSON instead of trusting the response shape', async () => {
+    const fetchState = createInterruptStateFetcher('/api/recovery', {
+      fetchClient: vi.fn<typeof fetch>(async () =>
+        Response.json({ ...recoveryState, pendingInterrupts: 'not-an-array' }),
+      ),
+    })
+
+    await expect(
+      fetchState({
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        knownGeneration: 2,
+      }),
+    ).rejects.toThrow('Invalid interrupt recovery response')
+  })
+
+  it('wires explicit recovery and continuation operations without posting a new run', async () => {
+    const recoveryFetch = vi.fn<typeof fetch>(async () =>
+      Response.json(recoveryState),
+    )
+    const continuationFetch = vi.fn<typeof fetch>(async () =>
+      continuationResponse(),
+    )
+    const chatFetch = vi.fn<typeof fetch>()
+    const interruptStateFetcher = createInterruptStateFetcher('/api/recovery', {
+      fetchClient: recoveryFetch,
+    })
+    const continuationLoader = createInterruptContinuationLoader(
+      '/api/continuation',
+      { fetchClient: continuationFetch },
+    )
+    const adapter = fetchServerSentEvents('/api/chat', {
+      fetchClient: chatFetch,
+      interruptStateFetcher,
+      continuationLoader,
+    })
+
+    await expect(
+      adapter.loadInterruptState?.({
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        knownGeneration: 2,
+      }),
+    ).resolves.toEqual(recoveryState)
+    const chunks = []
+    for await (const chunk of adapter.joinRun('winner-run')) chunks.push(chunk)
+
+    expect(chunks).toHaveLength(1)
+    expect(continuationFetch).toHaveBeenCalledWith(
+      '/api/continuation?offset=-1&runId=winner-run',
+      expect.objectContaining({ method: 'GET' }),
+    )
+    expect(chatFetch).not.toHaveBeenCalled()
+  })
+})
diff --git a/packages/ai-client/tests/interrupts-types.test-d.ts b/packages/ai-client/tests/interrupts-types.test-d.ts
new file mode 100644
index 000000000..31853c63a
--- /dev/null
+++ b/packages/ai-client/tests/interrupts-types.test-d.ts
@@ -0,0 +1,175 @@
+import { expectTypeOf } from 'vitest'
+import { toolDefinition } from '@tanstack/ai/client'
+import { z } from 'zod'
+import {
+  createInterruptContinuationLoader,
+  createInterruptStateFetcher,
+  fetchServerSentEvents,
+} from '../src/index'
+import type { JSONSchema, ServerTool } from '@tanstack/ai'
+import type {
+  ClientTool,
+  InterruptBinding,
+  Interrupt as WireInterrupt,
+  InputSchemaOf,
+  NoSchema,
+  OutputSchemaOf,
+} from '@tanstack/ai/client'
+import type {
+  BoundInterrupts,
+  ChatClient,
+  ChatInterrupt,
+  ToolApprovalInterrupt,
+} from '../src/index'
+
+const transfer = toolDefinition({
+  name: 'transfer',
+  description: 'Transfer funds',
+  needsApproval: true,
+  inputSchema: z.object({ cents: z.number() }),
+  outputSchema: z.object({ receipt: z.string() }),
+  approvalSchema: {
+    approve: z.object({ note: z.string() }),
+    reject: z.object({ reason: z.string() }),
+  },
+}).client()
+
+const confirm = toolDefinition({
+  name: 'confirm',
+  description: 'Approval without custom schemas',
+  needsApproval: true,
+}).client()
+
+const lookup = toolDefinition({
+  name: 'lookup',
+  description: 'Client lookup',
+  outputSchema: z.object({ accountId: z.string() }),
+}).client()
+
+const raw = toolDefinition({
+  name: 'raw',
+  description: 'Raw JSON Schema remains unknown',
+  outputSchema: { type: 'object' },
+}).client()
+
+type Tools = readonly [
+  typeof transfer,
+  typeof confirm,
+  typeof lookup,
+  typeof raw,
+]
+type Interrupt = ChatInterrupt<Tools>
+
+expectTypeOf<InputSchemaOf<ServerTool>>().toEqualTypeOf<NoSchema>()
+expectTypeOf<OutputSchemaOf<ServerTool>>().toEqualTypeOf<NoSchema>()
+expectTypeOf<InputSchemaOf<ClientTool>>().toEqualTypeOf<NoSchema>()
+expectTypeOf<OutputSchemaOf<ClientTool>>().toEqualTypeOf<NoSchema>()
+
+const manuallyAnnotatedClientTool: ClientTool = {
+  __toolSide: 'client',
+  name: 'manual',
+  description: 'Manually annotated schema-less tool',
+}
+expectTypeOf(manuallyAnnotatedClientTool.inputSchema).toEqualTypeOf<undefined>()
+
+const manualJsonSchema = {
+  type: 'object',
+  properties: {},
+} satisfies JSONSchema
+const manuallyAnnotatedServerTool: ServerTool<typeof manualJsonSchema> = {
+  __toolSide: 'server',
+  name: 'manual-server',
+  description: 'Manually annotated tool with an explicit schema generic',
+  inputSchema: manualJsonSchema,
+  execute: async () => undefined,
+}
+expectTypeOf(manuallyAnnotatedServerTool.inputSchema).toEqualTypeOf<
+  typeof manualJsonSchema | undefined
+>()
+
+const publicRecoveryConnection = fetchServerSentEvents('/api/chat', {
+  interruptStateFetcher: createInterruptStateFetcher('/api/recovery'),
+  continuationLoader: createInterruptContinuationLoader('/api/continuation'),
+})
+expectTypeOf(publicRecoveryConnection.loadInterruptState).not.toBeUndefined()
+
+declare const approvalBinding: Extract<
+  InterruptBinding,
+  { kind: 'tool-approval' }
+>
+const canonicalApprovalDescriptor = {
+  id: approvalBinding.interruptId,
+  reason: 'tool_call' as const,
+  toolCallId: approvalBinding.toolCallId,
+  metadata: { 'tanstack:interruptBinding': approvalBinding },
+} satisfies WireInterrupt
+expectTypeOf(canonicalApprovalDescriptor.reason).toEqualTypeOf<'tool_call'>()
+
+declare const clientToolBinding: Extract<
+  InterruptBinding,
+  { kind: 'client-tool-execution' }
+>
+const canonicalClientToolDescriptor = {
+  id: clientToolBinding.interruptId,
+  reason: 'tanstack:client_tool_execution' as const,
+  toolCallId: clientToolBinding.toolCallId,
+  metadata: { 'tanstack:interruptBinding': clientToolBinding },
+} satisfies WireInterrupt
+expectTypeOf(
+  canonicalClientToolDescriptor.reason,
+).toEqualTypeOf<'tanstack:client_tool_execution'>()
+
+declare const transferApproval: Extract<
+  Interrupt,
+  { kind: 'tool-approval'; toolName: 'transfer' }
+>
+transferApproval.resolveInterrupt(true, {
+  editedArgs: { cents: 100 },
+  payload: { note: 'approved' },
+})
+transferApproval.resolveInterrupt(false, { payload: { reason: 'declined' } })
+// @ts-expect-error rejection never permits edited arguments
+transferApproval.resolveInterrupt(false, { editedArgs: { cents: 1 } })
+// @ts-expect-error approve payload is inferred from the approve branch
+transferApproval.resolveInterrupt(true, { payload: { reason: 'wrong branch' } })
+
+declare const confirmation: Extract<
+  Interrupt,
+  { kind: 'tool-approval'; toolName: 'confirm' }
+>
+confirmation.resolveInterrupt(true)
+confirmation.resolveInterrupt(false)
+// @ts-expect-error omitted input schema forbids edits
+confirmation.resolveInterrupt(true, { editedArgs: { value: 1 } })
+// @ts-expect-error omitted approval branch forbids payload
+confirmation.resolveInterrupt(false, { payload: { reason: 'no schema' } })
+
+// `client-tool-execution` is intentionally NOT part of the public interrupt
+// union. Client tools resolve through their `.client()` implementation or
+// `addToolResult`, never as a bound interrupt.
+expectTypeOf<
+  Extract<Interrupt, { kind: 'client-tool-execution' }>
+>().toEqualTypeOf<never>()
+
+expectTypeOf<BoundInterrupts<Tools>>().toEqualTypeOf<
+  readonly ChatInterrupt<Tools>[]
+>()
+
+declare const client: ChatClient<Tools>
+client.updateOptions({
+  onInterruptStateChange: (state) => {
+    expectTypeOf(state.interrupts).toEqualTypeOf(state.pendingInterrupts)
+  },
+})
+client.resolveInterrupts((interrupt) => {
+  interrupt.cancel()
+  return undefined
+})
+client.resumeInterruptsUnsafe([
+  { interruptId: 'generic-1', status: 'cancelled' },
+])
+// @ts-expect-error the low-level recovery escape hatch uses the locked name
+client.unsafeResumeInterrupts([])
+expectTypeOf<Extract<Interrupt, { kind: 'tool-approval' }>>().toMatchTypeOf<
+  ToolApprovalInterrupt<Tools[number]>
+>()
diff --git a/packages/ai-durable-stream/src/durable-stream.ts b/packages/ai-durable-stream/src/durable-stream.ts
index 0c8621a78..087882bcb 100644
--- a/packages/ai-durable-stream/src/durable-stream.ts
+++ b/packages/ai-durable-stream/src/durable-stream.ts
@@ -152,25 +152,23 @@ async function* readLines(
   const reader = body.getReader()
   const decoder = new TextDecoder()
   let buffer = ''
-  let completed = false
-  let cancelled = false
-  let readFailed = false
+  let shouldCancelReader = true
   try {
     for (;;) {
       let result: ReadableStreamReadResult<Uint8Array> | typeof READ_ABORTED
       try {
         result = await readWithAbort(reader, signal)
       } catch (error) {
-        readFailed = true
+        shouldCancelReader = false
         throw new ResponseBodyReadFailure(error)
       }
       if (result === READ_ABORTED) {
-        cancelled = true
+        shouldCancelReader = false
         await reader.cancel(signal?.reason)
         return
       }
       if (result.done) {
-        completed = true
+        shouldCancelReader = false
         break
       }
       buffer += decoder.decode(result.value, { stream: true })
@@ -186,7 +184,7 @@ async function* readLines(
     }
   } finally {
     try {
-      if (!completed && !cancelled && !readFailed) await reader.cancel()
+      if (shouldCancelReader) await reader.cancel()
     } finally {
       reader.releaseLock()
     }
diff --git a/packages/ai-gemini/tests/text-interactions-adapter.test.ts b/packages/ai-gemini/tests/text-interactions-adapter.test.ts
index c043efb63..62d57f420 100644
--- a/packages/ai-gemini/tests/text-interactions-adapter.test.ts
+++ b/packages/ai-gemini/tests/text-interactions-adapter.test.ts
@@ -1,7 +1,16 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
-import { chat } from '@tanstack/ai'
-import type { StreamChunk, Tool } from '@tanstack/ai'
+import {
+  InterruptPersistenceCapability,
+  chat,
+  defineChatMiddleware,
+  provideInterruptPersistence,
+} from '@tanstack/ai'
+import type {
+  InterruptPersistenceGateway,
+  StreamChunk,
+  Tool,
+} from '@tanstack/ai'
 import { GeminiTextInteractionsAdapter } from '../src/experimental/text-interactions/adapter'
 import type { GeminiTextInteractionsProviderOptions } from '../src/experimental/text-interactions/adapter'
 import type {
@@ -53,6 +62,43 @@ const collectChunks = async (stream: AsyncIterable<StreamChunk>) => {
   return chunks
 }
 
+const testInterruptGateway: InterruptPersistenceGateway = {
+  openInterruptBatch: async (input) => ({
+    generation: 1,
+    descriptors: input.descriptors,
+  }),
+  commitInterruptResolutions: async (input) => ({
+    status: 'committed',
+    continuationRunId: input.continuationRunId,
+  }),
+  getInterruptRecoveryState: async (input) => ({
+    schemaVersion: 1,
+    state: 'missing',
+    threadId: input.threadId,
+    interruptedRunId: input.interruptedRunId,
+    generation: input.knownGeneration,
+    pendingInterrupts: [],
+  }),
+}
+
+const testInterruptPersistence = defineChatMiddleware({
+  name: 'gemini-test-interrupt-persistence',
+  provides: [InterruptPersistenceCapability],
+  setup(ctx) {
+    provideInterruptPersistence(ctx, testInterruptGateway)
+  },
+  async onChunk(_ctx, chunk) {
+    if (chunk.type === 'RUN_FINISHED' && chunk.outcome?.type === 'interrupt') {
+      await testInterruptGateway.openInterruptBatch({
+        threadId: chunk.threadId,
+        interruptedRunId: chunk.runId,
+        descriptors: chunk.outcome.interrupts,
+        bindings: [],
+      })
+    }
+  },
+})
+
 describe('GeminiTextInteractionsAdapter', () => {
   beforeEach(() => {
     // `mockReset()` (vs `clearAllMocks`) also clears `mockResolvedValue`
@@ -416,6 +462,7 @@ describe('GeminiTextInteractionsAdapter', () => {
         adapter,
         messages: [{ role: 'user', content: 'Weather in Madrid?' }],
         tools: [weatherTool],
+        middleware: [testInterruptPersistence],
       }),
     )
 
@@ -428,19 +475,20 @@ describe('GeminiTextInteractionsAdapter', () => {
       }),
     ])
 
-    const startEvent = chunks.find((c) => c.type === 'TOOL_CALL_START') as any
-    expect(startEvent).toBeDefined()
-    expect(startEvent.toolCallId).toBe('call_1')
-    expect(startEvent.toolName).toBe('lookup_weather')
+    const startEvent = chunks.find((c) => c.type === 'TOOL_CALL_START')
+    expect(startEvent).toMatchObject({
+      toolCallId: 'call_1',
+      toolName: 'lookup_weather',
+    })
 
-    const argsEvent = chunks.find((c) => c.type === 'TOOL_CALL_ARGS') as any
-    expect(argsEvent.args).toBe('{"location":"Madrid"}')
+    const argsEvent = chunks.find((c) => c.type === 'TOOL_CALL_ARGS')
+    expect(argsEvent).toMatchObject({ args: '{"location":"Madrid"}' })
 
-    const endEvent = chunks.find((c) => c.type === 'TOOL_CALL_END') as any
-    expect(endEvent.input).toEqual({ location: 'Madrid' })
+    const endEvent = chunks.find((c) => c.type === 'TOOL_CALL_END')
+    expect(endEvent).toMatchObject({ input: { location: 'Madrid' } })
 
-    const finished = chunks.find((c) => c.type === 'RUN_FINISHED') as any
-    expect(finished.finishReason).toBe('tool_calls')
+    const finished = chunks.find((c) => c.type === 'RUN_FINISHED')
+    expect(finished).toMatchObject({ finishReason: 'tool_calls' })
   })
 
   it('accumulates multi-fragment arguments_delta into the final tool input', async () => {
@@ -492,24 +540,27 @@ describe('GeminiTextInteractionsAdapter', () => {
         adapter,
         messages: [{ role: 'user', content: 'Weather in Berlin?' }],
         tools: [{ name: 'lookup_weather', description: 'Return the weather' }],
+        middleware: [testInterruptPersistence],
       }),
     )
 
-    const startEvent = chunks.find((c) => c.type === 'TOOL_CALL_START') as any
-    expect(startEvent.toolCallId).toBe('call_frag')
-    expect(startEvent.toolName).toBe('lookup_weather')
+    const startEvent = chunks.find((c) => c.type === 'TOOL_CALL_START')
+    expect(startEvent).toMatchObject({
+      toolCallId: 'call_frag',
+      toolName: 'lookup_weather',
+    })
 
     // The last TOOL_CALL_ARGS event carries the fully-accumulated buffer.
-    const argsEvents = chunks.filter(
-      (c) => c.type === 'TOOL_CALL_ARGS',
-    ) as Array<any>
+    const argsEvents = chunks.filter((c) => c.type === 'TOOL_CALL_ARGS')
     expect(argsEvents.length).toBeGreaterThan(1)
-    expect(argsEvents.at(-1)!.args).toBe(
-      '{"location":"Berlin","unit":"celsius"}',
-    )
+    expect(argsEvents.at(-1)).toMatchObject({
+      args: '{"location":"Berlin","unit":"celsius"}',
+    })
 
-    const endEvent = chunks.find((c) => c.type === 'TOOL_CALL_END') as any
-    expect(endEvent.input).toEqual({ location: 'Berlin', unit: 'celsius' })
+    const endEvent = chunks.find((c) => c.type === 'TOOL_CALL_END')
+    expect(endEvent).toMatchObject({
+      input: { location: 'Berlin', unit: 'celsius' },
+    })
   })
 
   it('preserves the last good args when the arguments stream truncates mid-fragment', async () => {
@@ -557,13 +608,14 @@ describe('GeminiTextInteractionsAdapter', () => {
         adapter,
         messages: [{ role: 'user', content: 'Weather in London?' }],
         tools: [{ name: 'lookup_weather', description: 'Return the weather' }],
+        middleware: [testInterruptPersistence],
       }),
     )
 
     // No parse-failure RUN_ERROR, and the completed key survives truncation.
     expect(chunks.find((c) => c.type === 'RUN_ERROR')).toBeUndefined()
-    const endEvent = chunks.find((c) => c.type === 'TOOL_CALL_END') as any
-    expect(endEvent.input).toEqual({ city: 'London' })
+    const endEvent = chunks.find((c) => c.type === 'TOOL_CALL_END')
+    expect(endEvent).toMatchObject({ input: { city: 'London' } })
   })
 
   it('translates thought_summary deltas into REASONING events', async () => {
diff --git a/packages/ai-openrouter/tests/openrouter-responses-adapter.test.ts b/packages/ai-openrouter/tests/openrouter-responses-adapter.test.ts
index 84c74522e..f6f458f15 100644
--- a/packages/ai-openrouter/tests/openrouter-responses-adapter.test.ts
+++ b/packages/ai-openrouter/tests/openrouter-responses-adapter.test.ts
@@ -1,11 +1,21 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { EventType, chat } from '@tanstack/ai'
+import {
+  EventType,
+  InterruptPersistenceCapability,
+  chat,
+  defineChatMiddleware,
+  provideInterruptPersistence,
+} from '@tanstack/ai'
 import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
 import { ResponsesRequest$outboundSchema } from '@openrouter/sdk/models'
 import { createOpenRouterResponsesText } from '../src/adapters/responses-text'
 import { webSearchTool } from '../src/tools/web-search-tool'
 import { webFetchTool } from '../src/tools/web-fetch-tool'
-import type { StreamChunk, Tool } from '@tanstack/ai'
+import type {
+  InterruptPersistenceGateway,
+  StreamChunk,
+  Tool,
+} from '@tanstack/ai'
 
 const testLogger = resolveDebugOption(false)
 let mockSend: any
@@ -34,6 +44,43 @@ const weatherTool: Tool = {
   description: 'Return the forecast for a location',
 }
 
+const testInterruptGateway: InterruptPersistenceGateway = {
+  openInterruptBatch: async (input) => ({
+    generation: 1,
+    descriptors: input.descriptors,
+  }),
+  commitInterruptResolutions: async (input) => ({
+    status: 'committed',
+    continuationRunId: input.continuationRunId,
+  }),
+  getInterruptRecoveryState: async (input) => ({
+    schemaVersion: 1,
+    state: 'missing',
+    threadId: input.threadId,
+    interruptedRunId: input.interruptedRunId,
+    generation: input.knownGeneration,
+    pendingInterrupts: [],
+  }),
+}
+
+const testInterruptPersistence = defineChatMiddleware({
+  name: 'openrouter-test-interrupt-persistence',
+  provides: [InterruptPersistenceCapability],
+  setup(ctx) {
+    provideInterruptPersistence(ctx, testInterruptGateway)
+  },
+  async onChunk(_ctx, chunk) {
+    if (chunk.type === 'RUN_FINISHED' && chunk.outcome?.type === 'interrupt') {
+      await testInterruptGateway.openInterruptBatch({
+        threadId: chunk.threadId,
+        interruptedRunId: chunk.runId,
+        descriptors: chunk.outcome.interrupts,
+        bindings: [],
+      })
+    }
+  },
+})
+
 function createAsyncIterable<T>(chunks: Array<T>): AsyncIterable<T> {
   return {
     [Symbol.asyncIterator]() {
@@ -691,26 +738,27 @@ describe('OpenRouter responses adapter — stream event bridge', () => {
       adapter,
       messages: [{ role: 'user', content: 'hi' }],
       tools: [weatherTool],
+      middleware: [testInterruptPersistence],
     })) {
       chunks.push(c)
     }
 
-    const start = chunks.find((c) => c.type === 'TOOL_CALL_START') as any
+    const start = chunks.find((c) => c.type === 'TOOL_CALL_START')
     expect(start).toMatchObject({
       type: 'TOOL_CALL_START',
       toolCallId: 'item_1',
       toolCallName: 'lookup_weather',
     })
 
-    const args = chunks.filter((c) => c.type === 'TOOL_CALL_ARGS') as any[]
+    const args = chunks.filter((c) => c.type === 'TOOL_CALL_ARGS')
     expect(args.length).toBe(1)
-    expect(args[0]!.delta).toBe('{"location":"Berlin"}')
+    expect(args[0]).toMatchObject({ delta: '{"location":"Berlin"}' })
 
-    const end = chunks.find((c) => c.type === 'TOOL_CALL_END') as any
-    expect(end.input).toEqual({ location: 'Berlin' })
+    const end = chunks.find((c) => c.type === 'TOOL_CALL_END')
+    expect(end).toMatchObject({ input: { location: 'Berlin' } })
 
-    const finished = chunks.find((c) => c.type === 'RUN_FINISHED') as any
-    expect(finished.finishReason).toBe('tool_calls')
+    const finished = chunks.find((c) => c.type === 'RUN_FINISHED')
+    expect(finished).toMatchObject({ finishReason: 'tool_calls' })
   })
 
   it('emits parentMessageId on tool-first tool calls matching the assistant message id', async () => {
diff --git a/packages/ai-persistence-cloudflare/migrations/0001_tanstack_ai_interrupt_batches.sql b/packages/ai-persistence-cloudflare/migrations/0001_tanstack_ai_interrupt_batches.sql
new file mode 100644
index 000000000..d81b74cee
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/migrations/0001_tanstack_ai_interrupt_batches.sql
@@ -0,0 +1,68 @@
+CREATE TABLE `interrupt_batches` (
+	`interrupted_run_id` text PRIMARY KEY NOT NULL,
+	`thread_id` text NOT NULL,
+	`generation` integer NOT NULL,
+	`expected_interrupt_ids_json` text NOT NULL,
+	`fingerprint` text NOT NULL,
+	`canonical_resolutions` text NOT NULL,
+	`resolutions_json` text NOT NULL,
+	`continuation_run_id` text NOT NULL,
+	`committed_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `interrupt_batches_continuation_run_id_unique` ON `interrupt_batches` (`continuation_run_id`);
+--> statement-breakpoint
+CREATE TABLE `__new_interrupts` (
+	`interrupt_id` text PRIMARY KEY NOT NULL,
+	`run_id` text NOT NULL,
+	`thread_id` text NOT NULL,
+	`generation` integer NOT NULL,
+	`status` text NOT NULL,
+	`requested_at` integer NOT NULL,
+	`resolved_at` integer,
+	`payload_json` text NOT NULL,
+	`binding_json` text NOT NULL,
+	`response_schema_hash` text NOT NULL,
+	`response_json` text
+);
+--> statement-breakpoint
+INSERT INTO `__new_interrupts` (
+	`interrupt_id`,
+	`run_id`,
+	`thread_id`,
+	`generation`,
+	`status`,
+	`requested_at`,
+	`resolved_at`,
+	`payload_json`,
+	`binding_json`,
+	`response_schema_hash`,
+	`response_json`
+)
+SELECT
+	`interrupt_id`,
+	`run_id`,
+	`thread_id`,
+	CASE WHEN `status` = 'pending' THEN 1 ELSE 0 END,
+	`status`,
+	`requested_at`,
+	`resolved_at`,
+	`payload_json`,
+	json_object(
+		'kind', 'generic',
+		'interruptId', `interrupt_id`,
+		'interruptedRunId', `run_id`,
+		'generation', CASE WHEN `status` = 'pending' THEN 1 ELSE 0 END,
+		'responseSchemaHash', 'legacy:unknown'
+	),
+	'legacy:unknown',
+	`response_json`
+FROM `interrupts`;
+--> statement-breakpoint
+DROP TABLE `interrupts`;
+--> statement-breakpoint
+ALTER TABLE `__new_interrupts` RENAME TO `interrupts`;
+--> statement-breakpoint
+CREATE INDEX `interrupts_thread_status_requested_at_idx` ON `interrupts` (`thread_id`,`status`,`requested_at`);
+--> statement-breakpoint
+CREATE INDEX `interrupts_run_status_requested_at_idx` ON `interrupts` (`run_id`,`status`,`requested_at`);
diff --git a/packages/ai-persistence-cloudflare/src/assets/0001_tanstack_ai_interrupt_batches.sql b/packages/ai-persistence-cloudflare/src/assets/0001_tanstack_ai_interrupt_batches.sql
new file mode 100644
index 000000000..d81b74cee
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/src/assets/0001_tanstack_ai_interrupt_batches.sql
@@ -0,0 +1,68 @@
+CREATE TABLE `interrupt_batches` (
+	`interrupted_run_id` text PRIMARY KEY NOT NULL,
+	`thread_id` text NOT NULL,
+	`generation` integer NOT NULL,
+	`expected_interrupt_ids_json` text NOT NULL,
+	`fingerprint` text NOT NULL,
+	`canonical_resolutions` text NOT NULL,
+	`resolutions_json` text NOT NULL,
+	`continuation_run_id` text NOT NULL,
+	`committed_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `interrupt_batches_continuation_run_id_unique` ON `interrupt_batches` (`continuation_run_id`);
+--> statement-breakpoint
+CREATE TABLE `__new_interrupts` (
+	`interrupt_id` text PRIMARY KEY NOT NULL,
+	`run_id` text NOT NULL,
+	`thread_id` text NOT NULL,
+	`generation` integer NOT NULL,
+	`status` text NOT NULL,
+	`requested_at` integer NOT NULL,
+	`resolved_at` integer,
+	`payload_json` text NOT NULL,
+	`binding_json` text NOT NULL,
+	`response_schema_hash` text NOT NULL,
+	`response_json` text
+);
+--> statement-breakpoint
+INSERT INTO `__new_interrupts` (
+	`interrupt_id`,
+	`run_id`,
+	`thread_id`,
+	`generation`,
+	`status`,
+	`requested_at`,
+	`resolved_at`,
+	`payload_json`,
+	`binding_json`,
+	`response_schema_hash`,
+	`response_json`
+)
+SELECT
+	`interrupt_id`,
+	`run_id`,
+	`thread_id`,
+	CASE WHEN `status` = 'pending' THEN 1 ELSE 0 END,
+	`status`,
+	`requested_at`,
+	`resolved_at`,
+	`payload_json`,
+	json_object(
+		'kind', 'generic',
+		'interruptId', `interrupt_id`,
+		'interruptedRunId', `run_id`,
+		'generation', CASE WHEN `status` = 'pending' THEN 1 ELSE 0 END,
+		'responseSchemaHash', 'legacy:unknown'
+	),
+	'legacy:unknown',
+	`response_json`
+FROM `interrupts`;
+--> statement-breakpoint
+DROP TABLE `interrupts`;
+--> statement-breakpoint
+ALTER TABLE `__new_interrupts` RENAME TO `interrupts`;
+--> statement-breakpoint
+CREATE INDEX `interrupts_thread_status_requested_at_idx` ON `interrupts` (`thread_id`,`status`,`requested_at`);
+--> statement-breakpoint
+CREATE INDEX `interrupts_run_status_requested_at_idx` ON `interrupts` (`run_id`,`status`,`requested_at`);
diff --git a/packages/ai-persistence-cloudflare/src/d1.ts b/packages/ai-persistence-cloudflare/src/d1.ts
index 011e70ce4..13a63d517 100644
--- a/packages/ai-persistence-cloudflare/src/d1.ts
+++ b/packages/ai-persistence-cloudflare/src/d1.ts
@@ -1,13 +1,1008 @@
+import {
+  canonicalInterruptJson,
+  canonicalizeInterruptResolutions,
+  cloneAndDeepFreezeJson,
+} from '@tanstack/ai'
 import { drizzle } from 'drizzle-orm/d1'
 import { drizzlePersistence, schema } from '@tanstack/ai-persistence-drizzle'
+import {
+  InterruptStoreCorruptionError,
+  hasExactInterruptIds,
+  projectInterruptRecovery,
+} from '@tanstack/ai-persistence'
+import type {
+  InterruptBinding,
+  InterruptRecoveryQuery,
+  RunAgentResumeItem,
+} from '@tanstack/ai'
+import type {
+  InterruptBatchRecord,
+  InterruptRecord,
+  InterruptStore,
+} from '@tanstack/ai-persistence'
+
+interface D1InterruptRow {
+  interrupt_id: string
+  run_id: string
+  thread_id: string
+  generation: number
+  status: string
+  requested_at: number
+  resolved_at: number | null
+  payload_json: string
+  binding_json: string
+  response_schema_hash: string
+  response_json: string | null
+}
+
+interface D1InterruptBatchRow {
+  interrupted_run_id: string
+  thread_id: string
+  generation: number
+  expected_interrupt_ids_json: string
+  fingerprint: string
+  canonical_resolutions: string
+  resolutions_json: string
+  continuation_run_id: string
+  committed_at: number
+}
+
+type D1RecoveryRow = D1InterruptRow | D1InterruptBatchRow
+
+export interface D1InterruptStoreOptions {
+  /** Override wall-clock time, primarily for deterministic runtimes/tests. */
+  clock?: () => number
+}
+
+function corrupt(message: string, options?: ErrorOptions): never {
+  throw new InterruptStoreCorruptionError(message, options)
+}
+
+function parseJson(value: string, field: string): unknown {
+  try {
+    const parsed: unknown = JSON.parse(value)
+    return parsed
+  } catch (error) {
+    return corrupt(`Stored ${field} is not valid JSON.`, { cause: error })
+  }
+}
+
+function decodeBinding(
+  value: unknown,
+  correlation: {
+    interruptId: string
+    interruptedRunId: string
+    generation: number
+    responseSchemaHash: string
+  },
+): InterruptBinding {
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    !('kind' in value) ||
+    !('interruptId' in value) ||
+    !('interruptedRunId' in value) ||
+    !('generation' in value) ||
+    !('responseSchemaHash' in value) ||
+    typeof value.interruptId !== 'string' ||
+    typeof value.interruptedRunId !== 'string' ||
+    typeof value.generation !== 'number' ||
+    typeof value.responseSchemaHash !== 'string'
+  ) {
+    return corrupt('Stored interrupt binding is malformed.')
+  }
+  const expiresAt = 'expiresAt' in value ? value.expiresAt : undefined
+  if (
+    expiresAt !== undefined &&
+    (typeof expiresAt !== 'string' || !Number.isFinite(Date.parse(expiresAt)))
+  ) {
+    return corrupt('Stored interrupt expiry is malformed.')
+  }
+  if (
+    value.interruptId !== correlation.interruptId ||
+    value.interruptedRunId !== correlation.interruptedRunId ||
+    value.generation !== correlation.generation ||
+    value.responseSchemaHash !== correlation.responseSchemaHash
+  ) {
+    return corrupt('Stored interrupt binding correlation is inconsistent.')
+  }
+  if (value.kind === 'generic') {
+    return {
+      kind: 'generic',
+      interruptId: value.interruptId,
+      interruptedRunId: value.interruptedRunId,
+      generation: value.generation,
+      responseSchemaHash: value.responseSchemaHash,
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+    }
+  }
+  if (
+    value.kind === 'client-tool-execution' &&
+    'toolName' in value &&
+    'toolCallId' in value &&
+    'outputSchemaHash' in value &&
+    typeof value.toolName === 'string' &&
+    typeof value.toolCallId === 'string' &&
+    typeof value.outputSchemaHash === 'string'
+  ) {
+    return {
+      kind: 'client-tool-execution',
+      interruptId: value.interruptId,
+      interruptedRunId: value.interruptedRunId,
+      generation: value.generation,
+      toolName: value.toolName,
+      toolCallId: value.toolCallId,
+      outputSchemaHash: value.outputSchemaHash,
+      responseSchemaHash: value.responseSchemaHash,
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+    }
+  }
+  if (
+    value.kind === 'tool-approval' &&
+    'toolName' in value &&
+    'toolCallId' in value &&
+    'originalArgs' in value &&
+    'inputSchemaHash' in value &&
+    'approvalSchemaHash' in value &&
+    typeof value.toolName === 'string' &&
+    typeof value.toolCallId === 'string' &&
+    typeof value.inputSchemaHash === 'string' &&
+    typeof value.approvalSchemaHash === 'string'
+  ) {
+    return {
+      kind: 'tool-approval',
+      interruptId: value.interruptId,
+      interruptedRunId: value.interruptedRunId,
+      generation: value.generation,
+      toolName: value.toolName,
+      toolCallId: value.toolCallId,
+      originalArgs: value.originalArgs,
+      inputSchemaHash: value.inputSchemaHash,
+      approvalSchemaHash: value.approvalSchemaHash,
+      responseSchemaHash: value.responseSchemaHash,
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+    }
+  }
+  return corrupt('Stored interrupt binding kind is malformed.')
+}
+
+function validateDescriptor(value: unknown, interruptId: string): void {
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    !('id' in value) ||
+    !('reason' in value) ||
+    value.id !== interruptId ||
+    typeof value.reason !== 'string'
+  ) {
+    corrupt('Stored interrupt descriptor correlation is inconsistent.')
+  }
+}
+
+function decodeStatus(value: string): InterruptRecord['status'] {
+  if (value === 'pending' || value === 'resolved' || value === 'cancelled') {
+    return value
+  }
+  return corrupt('Stored interrupt status is malformed.')
+}
+
+function mapInterrupt(row: D1InterruptRow): InterruptRecord {
+  const payload = parseJson(row.payload_json, 'interrupt payload')
+  if (row.generation > 0) validateDescriptor(payload, row.interrupt_id)
+  const binding = decodeBinding(
+    parseJson(row.binding_json, 'interrupt binding'),
+    {
+      interruptId: row.interrupt_id,
+      interruptedRunId: row.run_id,
+      generation: row.generation,
+      responseSchemaHash: row.response_schema_hash,
+    },
+  )
+  return {
+    interruptId: row.interrupt_id,
+    runId: row.run_id,
+    threadId: row.thread_id,
+    generation: row.generation,
+    status: decodeStatus(row.status),
+    requestedAt: row.requested_at,
+    ...(row.resolved_at !== null ? { resolvedAt: row.resolved_at } : {}),
+    payload,
+    binding,
+    ...(row.response_json !== null
+      ? { response: parseJson(row.response_json, 'interrupt response') }
+      : {}),
+  }
+}
+
+function decodeStringArray(value: unknown, field: string): Array<string> {
+  if (!Array.isArray(value)) return corrupt(`Stored ${field} is malformed.`)
+  const strings: Array<string> = []
+  for (const item of value) {
+    if (typeof item !== 'string') {
+      return corrupt(`Stored ${field} is malformed.`)
+    }
+    strings.push(item)
+  }
+  if (!hasExactInterruptIds(strings, strings)) {
+    return corrupt(`Stored ${field} contains duplicate IDs.`)
+  }
+  return strings
+}
+
+function decodeResolution(value: unknown): RunAgentResumeItem {
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    !('interruptId' in value) ||
+    !('status' in value) ||
+    typeof value.interruptId !== 'string' ||
+    (value.status !== 'resolved' && value.status !== 'cancelled')
+  ) {
+    return corrupt('Stored interrupt resolution is malformed.')
+  }
+  return {
+    interruptId: value.interruptId,
+    status: value.status,
+    ...('payload' in value ? { payload: value.payload } : {}),
+  }
+}
+
+function decodeResolutions(value: unknown): Array<RunAgentResumeItem> {
+  if (!Array.isArray(value)) {
+    return corrupt('Stored interrupt resolutions are malformed.')
+  }
+  return value.map(decodeResolution)
+}
+
+function mapBatch(row: D1InterruptBatchRow): InterruptBatchRecord {
+  const expectedInterruptIds = decodeStringArray(
+    parseJson(row.expected_interrupt_ids_json, 'expected interrupt IDs'),
+    'expected interrupt IDs',
+  )
+  const resolutions = decodeResolutions(
+    parseJson(row.resolutions_json, 'interrupt resolutions'),
+  )
+  const candidate = canonicalizeInterruptResolutions(resolutions)
+  if (
+    !hasExactInterruptIds(
+      expectedInterruptIds,
+      resolutions.map((resolution) => resolution.interruptId),
+    ) ||
+    candidate.fingerprint !== row.fingerprint ||
+    candidate.canonicalResolutions !== row.canonical_resolutions
+  ) {
+    return corrupt('Stored interrupt batch identity is inconsistent.')
+  }
+  return {
+    threadId: row.thread_id,
+    interruptedRunId: row.interrupted_run_id,
+    generation: row.generation,
+    expectedInterruptIds,
+    fingerprint: row.fingerprint,
+    canonicalResolutions: row.canonical_resolutions,
+    resolutions,
+    continuationRunId: row.continuation_run_id,
+    committedAt: row.committed_at,
+  }
+}
+
+function isInterruptRow(row: D1RecoveryRow): row is D1InterruptRow {
+  return 'interrupt_id' in row
+}
+
+function isBatchRow(row: D1RecoveryRow): row is D1InterruptBatchRow {
+  return 'interrupted_run_id' in row
+}
+
+function inspectResults<T>(
+  results: Array<D1Result<T>>,
+  expectedCount: number,
+): void {
+  if (results.length !== expectedCount) {
+    corrupt(
+      `D1 batch returned ${results.length} results for ${expectedCount} statements.`,
+    )
+  }
+  for (const result of results) {
+    if (
+      !Array.isArray(result.results) ||
+      typeof result.meta.changes !== 'number'
+    ) {
+      corrupt('D1 batch returned a malformed statement result.')
+    }
+  }
+}
+
+function mutationChanges(result: D1Result<unknown>, label: string): number {
+  if (typeof result.meta.changes !== 'number') {
+    return corrupt(`D1 ${label} returned malformed change metadata.`)
+  }
+  return result.meta.changes
+}
+
+function requireResult<T>(
+  results: Array<D1Result<T>>,
+  index: number,
+  label: string,
+): D1Result<T> {
+  const result = results[index]
+  return result ?? corrupt(`D1 ${label} result is missing.`)
+}
+
+function bind(
+  d1: D1Database,
+  sql: string,
+  values: ReadonlyArray<unknown>,
+): D1PreparedStatement {
+  return d1.prepare(sql).bind(...values)
+}
+
+/** Direct, atomic D1 interrupt store. */
+export function createD1InterruptStore(
+  d1: D1Database,
+  options: D1InterruptStoreOptions = {},
+): InterruptStore {
+  const clock = options.clock ?? Date.now
+
+  const readBatchAndRows = async (interruptedRunId: string) => {
+    const statements = [
+      bind(d1, 'SELECT * FROM interrupt_batches WHERE interrupted_run_id = ?', [
+        interruptedRunId,
+      ]),
+      bind(
+        d1,
+        'SELECT * FROM interrupts WHERE run_id = ? ORDER BY requested_at, interrupt_id',
+        [interruptedRunId],
+      ),
+    ]
+    const results = await d1.batch<D1RecoveryRow>(statements)
+    inspectResults(results, statements.length)
+    const batchRows = results[0]?.results ?? []
+    const interruptRows = results[1]?.results ?? []
+    if (batchRows.length > 1) {
+      return corrupt('D1 returned malformed interrupt batch rows.')
+    }
+    let batch: InterruptBatchRecord | null = null
+    if (batchRows[0]) {
+      if (!isBatchRow(batchRows[0])) {
+        return corrupt('D1 returned malformed interrupt batch rows.')
+      }
+      batch = mapBatch(batchRows[0])
+    }
+    const rows: Array<InterruptRecord> = []
+    for (const row of interruptRows) {
+      if (!isInterruptRow(row)) {
+        return corrupt('D1 returned malformed interrupt rows.')
+      }
+      rows.push(mapInterrupt(row))
+    }
+    return {
+      batch,
+      rows,
+    }
+  }
+
+  const readRecovery = async (input: InterruptRecoveryQuery) => {
+    const snapshot = await readBatchAndRows(input.interruptedRunId)
+    const rows = snapshot.rows.filter((row) => row.threadId === input.threadId)
+    const batch =
+      snapshot.batch?.threadId === input.threadId ? snapshot.batch : null
+    const generations = new Set(rows.map((row) => row.generation))
+    if (generations.size > 1) {
+      return corrupt('Stored interrupt rows mix generations.')
+    }
+    if (
+      batch &&
+      (rows.length === 0 ||
+        rows.some((row) => row.generation !== batch.generation) ||
+        !hasExactInterruptIds(
+          batch.expectedInterruptIds,
+          rows.map((row) => row.interruptId),
+        ))
+    ) {
+      return corrupt('Stored interrupt batch correlation is inconsistent.')
+    }
+    return projectInterruptRecovery({
+      query: input,
+      rows,
+      batch,
+      now: clock(),
+      includeResolutions: true,
+    })
+  }
+
+  const store: InterruptStore = {
+    async create(record) {
+      const generation = record.generation ?? 0
+      const binding = decodeBinding(
+        cloneAndDeepFreezeJson(
+          record.binding ?? {
+            kind: 'generic',
+            interruptId: record.interruptId,
+            interruptedRunId: record.runId,
+            generation,
+            responseSchemaHash: 'legacy:unknown',
+          },
+        ),
+        {
+          interruptId: record.interruptId,
+          interruptedRunId: record.runId,
+          generation,
+          responseSchemaHash:
+            record.binding?.responseSchemaHash ?? 'legacy:unknown',
+        },
+      )
+      const result = await bind(
+        d1,
+        `INSERT INTO interrupts (
+          interrupt_id, run_id, thread_id, generation, status, requested_at,
+          resolved_at, payload_json, binding_json, response_schema_hash,
+          response_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(interrupt_id) DO NOTHING`,
+        [
+          record.interruptId,
+          record.runId,
+          record.threadId,
+          generation,
+          record.status,
+          record.requestedAt,
+          null,
+          canonicalInterruptJson(record.payload),
+          canonicalInterruptJson(binding),
+          binding.responseSchemaHash,
+          record.response === undefined
+            ? null
+            : canonicalInterruptJson(record.response),
+        ],
+      ).run()
+      const changes = mutationChanges(result, 'legacy interrupt insert')
+      if (changes !== 0 && changes !== 1) {
+        corrupt('D1 legacy interrupt insert changed an unexpected row count.')
+      }
+    },
+    async resolve(interruptId, response) {
+      const hasResponse = response !== undefined
+      const result = await bind(
+        d1,
+        `UPDATE interrupts SET
+          status = 'resolved', resolved_at = ?
+          ${hasResponse ? ', response_json = ?' : ''}
+        WHERE interrupt_id = ?`,
+        [
+          clock(),
+          ...(hasResponse ? [canonicalInterruptJson(response)] : []),
+          interruptId,
+        ],
+      ).run()
+      const changes = mutationChanges(result, 'legacy interrupt resolve')
+      if (changes !== 0 && changes !== 1) {
+        corrupt('D1 legacy interrupt resolve changed an unexpected row count.')
+      }
+    },
+    async cancel(interruptId) {
+      const result = await bind(
+        d1,
+        `UPDATE interrupts SET status = 'cancelled', resolved_at = ?
+         WHERE interrupt_id = ?`,
+        [clock(), interruptId],
+      ).run()
+      const changes = mutationChanges(result, 'legacy interrupt cancellation')
+      if (changes !== 0 && changes !== 1) {
+        corrupt(
+          'D1 legacy interrupt cancellation changed an unexpected row count.',
+        )
+      }
+    },
+    async get(interruptId) {
+      const result = await bind(
+        d1,
+        'SELECT * FROM interrupts WHERE interrupt_id = ?',
+        [interruptId],
+      ).all<D1InterruptRow>()
+      inspectResults([result], 1)
+      if (result.results.length > 1) {
+        return corrupt('D1 returned duplicate interrupt IDs.')
+      }
+      return result.results[0] ? mapInterrupt(result.results[0]) : null
+    },
+    async list(threadId) {
+      const result = await bind(
+        d1,
+        'SELECT * FROM interrupts WHERE thread_id = ? ORDER BY requested_at, interrupt_id',
+        [threadId],
+      ).all<D1InterruptRow>()
+      inspectResults([result], 1)
+      return result.results.map(mapInterrupt)
+    },
+    async listPending(threadId) {
+      const result = await bind(
+        d1,
+        `SELECT * FROM interrupts
+         WHERE thread_id = ? AND status = 'pending'
+         ORDER BY requested_at, interrupt_id`,
+        [threadId],
+      ).all<D1InterruptRow>()
+      inspectResults([result], 1)
+      return result.results.map(mapInterrupt)
+    },
+    async listByRun(runId) {
+      const snapshot = await readBatchAndRows(runId)
+      return snapshot.rows
+    },
+    async listPendingByRun(runId) {
+      const result = await bind(
+        d1,
+        `SELECT * FROM interrupts
+         WHERE run_id = ? AND status = 'pending'
+         ORDER BY requested_at, interrupt_id`,
+        [runId],
+      ).all<D1InterruptRow>()
+      inspectResults([result], 1)
+      return result.results.map(mapInterrupt)
+    },
+    async openInterruptBatch(input) {
+      const descriptors = cloneAndDeepFreezeJson(input.descriptors)
+      const unopenedBindings = cloneAndDeepFreezeJson(input.bindings)
+      const descriptorIds = descriptors.map((descriptor) => descriptor.id)
+      if (
+        descriptorIds.length === 0 ||
+        !hasExactInterruptIds(
+          descriptorIds,
+          unopenedBindings.map((binding) => binding.interruptId),
+        )
+      ) {
+        throw new TypeError(
+          'Interrupt descriptors and bindings must contain the same exact nonempty IDs.',
+        )
+      }
+      for (const descriptor of descriptors) {
+        validateDescriptor(descriptor, descriptor.id)
+      }
+
+      const snapshot = await readBatchAndRows(input.interruptedRunId)
+      if (snapshot.batch) {
+        throw new Error('Cannot reopen a committed interrupt batch.')
+      }
+      if (snapshot.rows.length > 0) {
+        const generation = snapshot.rows[0]?.generation
+        const requestedBindings = unopenedBindings
+          .map((binding) => ({
+            ...binding,
+            interruptedRunId: input.interruptedRunId,
+            generation,
+          }))
+          .sort((left, right) =>
+            left.interruptId.localeCompare(right.interruptId),
+          )
+        const existingBindings = snapshot.rows
+          .map((row) => row.binding)
+          .sort((left, right) =>
+            left.interruptId.localeCompare(right.interruptId),
+          )
+        const existingDescriptors = snapshot.rows
+          .map((row) => row.payload)
+          .sort((left, right) => {
+            if (
+              left !== null &&
+              typeof left === 'object' &&
+              'id' in left &&
+              typeof left.id === 'string' &&
+              right !== null &&
+              typeof right === 'object' &&
+              'id' in right &&
+              typeof right.id === 'string'
+            ) {
+              return left.id.localeCompare(right.id)
+            }
+            return 0
+          })
+        const requestedDescriptors = [...descriptors].sort((left, right) =>
+          left.id.localeCompare(right.id),
+        )
+        if (
+          generation !== undefined &&
+          snapshot.rows.every(
+            (row) =>
+              row.threadId === input.threadId &&
+              row.generation === generation &&
+              row.status === 'pending',
+          ) &&
+          hasExactInterruptIds(
+            descriptorIds,
+            snapshot.rows.map((row) => row.interruptId),
+          ) &&
+          canonicalInterruptJson(existingDescriptors) ===
+            canonicalInterruptJson(requestedDescriptors) &&
+          canonicalInterruptJson(existingBindings) ===
+            canonicalInterruptJson(requestedBindings)
+        ) {
+          return { generation, descriptors }
+        }
+        throw new Error('An incompatible interrupt batch is already open.')
+      }
+
+      const generation = 1
+      const bindingById = new Map(
+        unopenedBindings.map((binding) => [binding.interruptId, binding]),
+      )
+      const requestedAt = clock()
+      const encoded = descriptors.map((descriptor) => {
+        const unopened = bindingById.get(descriptor.id)
+        if (!unopened) {
+          throw new Error(`Missing binding for interrupt: ${descriptor.id}`)
+        }
+        const proposedBinding = cloneAndDeepFreezeJson({
+          ...unopened,
+          interruptedRunId: input.interruptedRunId,
+          generation,
+        })
+        const binding = decodeBinding(proposedBinding, {
+          interruptId: descriptor.id,
+          interruptedRunId: input.interruptedRunId,
+          generation,
+          responseSchemaHash: proposedBinding.responseSchemaHash,
+        })
+        return {
+          descriptor,
+          binding,
+          payloadJson: canonicalInterruptJson(descriptor),
+          bindingJson: canonicalInterruptJson(binding),
+        }
+      })
+      const insertStatements = encoded.map((item) =>
+        bind(
+          d1,
+          `INSERT INTO interrupts (
+            interrupt_id, run_id, thread_id, generation, status, requested_at,
+            payload_json, binding_json, response_schema_hash
+          ) VALUES (?, ?, ?, ?, 'pending', ?, ?, ?, ?)
+          ON CONFLICT(interrupt_id) DO NOTHING`,
+          [
+            item.descriptor.id,
+            input.interruptedRunId,
+            input.threadId,
+            generation,
+            requestedAt,
+            item.payloadJson,
+            item.bindingJson,
+            item.binding.responseSchemaHash,
+          ],
+        ),
+      )
+      const exactClauses = encoded
+        .map(
+          () =>
+            '(interrupt_id = ? AND payload_json = ? AND binding_json = ? AND response_schema_hash = ?)',
+        )
+        .join(' OR ')
+      const assertionValues: Array<unknown> = [
+        input.interruptedRunId,
+        input.interruptedRunId,
+        encoded.length,
+        input.interruptedRunId,
+        input.threadId,
+        generation,
+      ]
+      for (const item of encoded) {
+        assertionValues.push(
+          item.descriptor.id,
+          item.payloadJson,
+          item.bindingJson,
+          item.binding.responseSchemaHash,
+        )
+      }
+      assertionValues.push(encoded.length)
+      const assertion = bind(
+        d1,
+        `INSERT INTO interrupts (
+          interrupt_id, run_id, thread_id, generation, status, requested_at,
+          payload_json, binding_json, response_schema_hash
+        )
+        SELECT NULL, '', '', 0, 'pending', 0, '{}', '{}', ''
+        WHERE NOT (
+          NOT EXISTS (
+            SELECT 1 FROM interrupt_batches WHERE interrupted_run_id = ?
+          )
+          AND (SELECT COUNT(*) FROM interrupts WHERE run_id = ?) = ?
+          AND (
+            SELECT COUNT(*) FROM interrupts
+            WHERE run_id = ? AND thread_id = ? AND generation = ?
+              AND status = 'pending' AND (${exactClauses})
+          ) = ?
+        )`,
+        assertionValues,
+      )
+      const statements = [...insertStatements, assertion]
+      const results = await d1.batch(statements)
+      inspectResults(results, statements.length)
+      for (const result of results.slice(0, -1)) {
+        const changes = mutationChanges(result, 'interrupt open insert')
+        if (changes !== 0 && changes !== 1) {
+          corrupt('D1 interrupt open changed an unexpected row count.')
+        }
+      }
+      const openAssertionResult = requireResult(
+        results,
+        results.length - 1,
+        'interrupt open assertion',
+      )
+      if (
+        mutationChanges(openAssertionResult, 'interrupt open assertion') !== 0
+      ) {
+        corrupt('D1 interrupt open assertion unexpectedly changed a row.')
+      }
+      const opened = await readBatchAndRows(input.interruptedRunId)
+      if (
+        opened.batch ||
+        !hasExactInterruptIds(
+          descriptorIds,
+          opened.rows.map((row) => row.interruptId),
+        )
+      ) {
+        return corrupt('D1 interrupt open did not persist the exact batch.')
+      }
+      return { generation, descriptors }
+    },
+    async commitInterruptResolutions(input) {
+      const candidate = canonicalizeInterruptResolutions(input.resolutions)
+      if (
+        candidate.fingerprint !== input.fingerprint ||
+        candidate.canonicalResolutions !== input.canonicalResolutions
+      ) {
+        throw new TypeError(
+          'Interrupt batch identity does not match its resolutions.',
+        )
+      }
+      const resolutionIds = candidate.resolutions.map(
+        (resolution) => resolution.interruptId,
+      )
+      if (!hasExactInterruptIds(input.expectedInterruptIds, resolutionIds)) {
+        return {
+          status: 'conflict',
+          authoritativeState: await readRecovery({
+            threadId: input.threadId,
+            interruptedRunId: input.interruptedRunId,
+            knownGeneration: input.expectedGeneration,
+          }),
+        }
+      }
+
+      const snapshot = await readBatchAndRows(input.interruptedRunId)
+      if (snapshot.batch) {
+        return snapshot.batch.threadId === input.threadId &&
+          snapshot.batch.fingerprint === candidate.fingerprint &&
+          snapshot.batch.canonicalResolutions === candidate.canonicalResolutions
+          ? {
+              status: 'replayed',
+              continuationRunId: snapshot.batch.continuationRunId,
+            }
+          : {
+              status: 'conflict',
+              authoritativeState: await readRecovery({
+                threadId: input.threadId,
+                interruptedRunId: input.interruptedRunId,
+                knownGeneration: input.expectedGeneration,
+              }),
+            }
+      }
+      const pending = snapshot.rows.filter((row) => row.status === 'pending')
+      if (
+        !hasExactInterruptIds(
+          input.expectedInterruptIds,
+          pending.map((row) => row.interruptId),
+        ) ||
+        pending.some(
+          (row) =>
+            row.threadId !== input.threadId ||
+            row.generation !== input.expectedGeneration ||
+            (row.binding.expiresAt !== undefined &&
+              Date.parse(row.binding.expiresAt) <= clock()),
+        )
+      ) {
+        return {
+          status: 'conflict',
+          authoritativeState: await readRecovery({
+            threadId: input.threadId,
+            interruptedRunId: input.interruptedRunId,
+            knownGeneration: input.expectedGeneration,
+          }),
+        }
+      }
+
+      const committedAt = clock()
+      const idPlaceholders = input.expectedInterruptIds.map(() => '?').join(',')
+      const winnerInsert = bind(
+        d1,
+        `INSERT INTO interrupt_batches (
+          interrupted_run_id, thread_id, generation,
+          expected_interrupt_ids_json, fingerprint, canonical_resolutions,
+          resolutions_json, continuation_run_id, committed_at
+        )
+        SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?
+        WHERE NOT EXISTS (
+          SELECT 1 FROM interrupt_batches WHERE interrupted_run_id = ?
+        )
+        AND (
+          SELECT COUNT(*) FROM interrupts
+          WHERE run_id = ? AND status = 'pending'
+        ) = ?
+        AND (
+          SELECT COUNT(*) FROM interrupts
+          WHERE run_id = ? AND thread_id = ? AND generation = ?
+            AND status = 'pending'
+            AND interrupt_id IN (${idPlaceholders})
+            AND (
+              json_extract(binding_json, '$.expiresAt') IS NULL
+              OR json_extract(binding_json, '$.expiresAt') > ?
+            )
+        ) = ?
+        ON CONFLICT(interrupted_run_id) DO NOTHING`,
+        [
+          input.interruptedRunId,
+          input.threadId,
+          input.expectedGeneration,
+          canonicalInterruptJson(input.expectedInterruptIds),
+          candidate.fingerprint,
+          candidate.canonicalResolutions,
+          candidate.canonicalResolutions,
+          input.continuationRunId,
+          committedAt,
+          input.interruptedRunId,
+          input.interruptedRunId,
+          input.expectedInterruptIds.length,
+          input.interruptedRunId,
+          input.threadId,
+          input.expectedGeneration,
+          ...input.expectedInterruptIds,
+          new Date(committedAt).toISOString(),
+          input.expectedInterruptIds.length,
+        ],
+      )
+      const transitionStatements = candidate.resolutions.map((resolution) => {
+        const status =
+          resolution.status === 'cancelled' ? 'cancelled' : 'resolved'
+        return bind(
+          d1,
+          `UPDATE interrupts
+           SET status = ?, resolved_at = ?, response_json = ?
+           WHERE interrupt_id = ? AND run_id = ? AND thread_id = ?
+             AND generation = ? AND status = 'pending'
+             AND EXISTS (
+               SELECT 1 FROM interrupt_batches
+               WHERE interrupted_run_id = ? AND thread_id = ?
+                 AND generation = ? AND fingerprint = ?
+                 AND canonical_resolutions = ? AND continuation_run_id = ?
+             )`,
+          [
+            status,
+            committedAt,
+            canonicalInterruptJson(resolution),
+            resolution.interruptId,
+            input.interruptedRunId,
+            input.threadId,
+            input.expectedGeneration,
+            input.interruptedRunId,
+            input.threadId,
+            input.expectedGeneration,
+            candidate.fingerprint,
+            candidate.canonicalResolutions,
+            input.continuationRunId,
+          ],
+        )
+      })
+      const finalClauses = candidate.resolutions
+        .map(
+          () =>
+            '(interrupt_id = ? AND status = ? AND resolved_at = ? AND response_json = ?)',
+        )
+        .join(' OR ')
+      const assertionValues: Array<unknown> = [
+        input.interruptedRunId,
+        input.threadId,
+        input.expectedGeneration,
+        candidate.fingerprint,
+        candidate.canonicalResolutions,
+        input.continuationRunId,
+        input.interruptedRunId,
+      ]
+      for (const resolution of candidate.resolutions) {
+        assertionValues.push(
+          resolution.interruptId,
+          resolution.status === 'cancelled' ? 'cancelled' : 'resolved',
+          committedAt,
+          canonicalInterruptJson(resolution),
+        )
+      }
+      assertionValues.push(candidate.resolutions.length)
+      const assertion = bind(
+        d1,
+        `INSERT INTO interrupts (
+          interrupt_id, run_id, thread_id, generation, status, requested_at,
+          payload_json, binding_json, response_schema_hash
+        )
+        SELECT NULL, '', '', 0, 'pending', 0, '{}', '{}', ''
+        WHERE EXISTS (
+          SELECT 1 FROM interrupt_batches
+          WHERE interrupted_run_id = ? AND thread_id = ? AND generation = ?
+            AND fingerprint = ? AND canonical_resolutions = ?
+            AND continuation_run_id = ?
+        )
+        AND (
+          SELECT COUNT(*) FROM interrupts
+          WHERE run_id = ? AND (${finalClauses})
+        ) <> ?`,
+        assertionValues,
+      )
+      const statements = [winnerInsert, ...transitionStatements, assertion]
+      const results = await d1.batch(statements)
+      inspectResults(results, statements.length)
+      const insertChanges = mutationChanges(
+        requireResult(results, 0, 'winner insert'),
+        'winner insert',
+      )
+      if (insertChanges === 0) {
+        const authoritative = await readBatchAndRows(input.interruptedRunId)
+        if (
+          authoritative.batch?.threadId === input.threadId &&
+          authoritative.batch.fingerprint === candidate.fingerprint &&
+          authoritative.batch.canonicalResolutions ===
+            candidate.canonicalResolutions
+        ) {
+          return {
+            status: 'replayed',
+            continuationRunId: authoritative.batch.continuationRunId,
+          }
+        }
+        return {
+          status: 'conflict',
+          authoritativeState: await readRecovery({
+            threadId: input.threadId,
+            interruptedRunId: input.interruptedRunId,
+            knownGeneration: input.expectedGeneration,
+          }),
+        }
+      }
+      if (insertChanges !== 1) {
+        return corrupt('D1 winner insert changed an unexpected row count.')
+      }
+      for (const result of results.slice(1, -1)) {
+        if (mutationChanges(result, 'interrupt transition') !== 1) {
+          throw new Error('A D1 interrupt transition changed no rows.')
+        }
+      }
+      const commitAssertionResult = requireResult(
+        results,
+        results.length - 1,
+        'commit assertion',
+      )
+      if (mutationChanges(commitAssertionResult, 'commit assertion') !== 0) {
+        return corrupt('D1 commit assertion unexpectedly changed a row.')
+      }
+      return {
+        status: 'committed',
+        continuationRunId: input.continuationRunId,
+      }
+    },
+    getInterruptRecoveryState(input) {
+      return readRecovery(input)
+    },
+  }
+  return store
+}
 
 /** Create the structured stores owned by a migrated Cloudflare D1 binding. */
-export function createD1Stores(d1: D1Database) {
-  const persistence = drizzlePersistence(drizzle(d1, { schema }))
+export function createD1Stores(
+  d1: D1Database,
+  interruptOptions?: D1InterruptStoreOptions,
+) {
+  const persistence = drizzlePersistence(drizzle(d1, { schema }), {
+    interrupts: false,
+  })
   return {
     messages: persistence.stores.messages,
     runs: persistence.stores.runs,
-    interrupts: persistence.stores.interrupts,
+    interrupts: createD1InterruptStore(d1, interruptOptions),
     metadata: persistence.stores.metadata,
   }
 }
diff --git a/packages/ai-persistence-cloudflare/src/index.ts b/packages/ai-persistence-cloudflare/src/index.ts
index 76e31cc7f..d95c501c1 100644
--- a/packages/ai-persistence-cloudflare/src/index.ts
+++ b/packages/ai-persistence-cloudflare/src/index.ts
@@ -15,7 +15,8 @@ import type { LockStore } from '@tanstack/ai'
 import type { R2BucketBinding } from './bindings'
 import type { DurableObjectLockStoreOptions } from './locks'
 
-export { createD1Stores } from './d1'
+export { createD1InterruptStore, createD1Stores } from './d1'
+export type { D1InterruptStoreOptions } from './d1'
 export {
   CloudflareLockDurableObject,
   createDurableObjectLockStore,
diff --git a/packages/ai-persistence-cloudflare/src/migrations.ts b/packages/ai-persistence-cloudflare/src/migrations.ts
index 2399a8c10..5f3a2f948 100644
--- a/packages/ai-persistence-cloudflare/src/migrations.ts
+++ b/packages/ai-persistence-cloudflare/src/migrations.ts
@@ -1,4 +1,5 @@
 import initialMigrationSql from './assets/0000_tanstack_ai_initial.sql?raw'
+import interruptBatchesMigrationSql from './assets/0001_tanstack_ai_interrupt_batches.sql?raw'
 
 export interface D1Migration {
   id: string
@@ -13,4 +14,9 @@ export const d1Migrations: ReadonlyArray<D1Migration> = [
     filename: '0000_tanstack_ai_initial.sql',
     sql: initialMigrationSql,
   },
+  {
+    id: '0001_tanstack_ai_interrupt_batches',
+    filename: '0001_tanstack_ai_interrupt_batches.sql',
+    sql: interruptBatchesMigrationSql,
+  },
 ]
diff --git a/packages/ai-persistence-cloudflare/tests/api-types.test-d.ts b/packages/ai-persistence-cloudflare/tests/api-types.test-d.ts
index 4bc9c92f6..62d99c09b 100644
--- a/packages/ai-persistence-cloudflare/tests/api-types.test-d.ts
+++ b/packages/ai-persistence-cloudflare/tests/api-types.test-d.ts
@@ -4,6 +4,8 @@ import { composePersistence } from '@tanstack/ai-persistence'
 import {
   CloudflareLockDurableObject,
   cloudflarePersistence,
+  createD1InterruptStore,
+  createD1Stores,
 } from '../src/index'
 import type {
   ArtifactStore,
@@ -14,6 +16,7 @@ import type {
   RunStore,
 } from '@tanstack/ai-persistence'
 import type { LockStore } from '@tanstack/ai'
+import type { D1InterruptStoreOptions } from '../src/index'
 
 declare const d1: D1Database
 declare const r2: R2Bucket
@@ -22,6 +25,12 @@ declare const durableObjectState: DurableObjectState
 
 new CloudflareLockDurableObject(durableObjectState)
 
+declare const d1InterruptOptions: D1InterruptStoreOptions
+expectTypeOf(
+  createD1InterruptStore(d1, d1InterruptOptions),
+).toEqualTypeOf<InterruptStore>()
+expectTypeOf(createD1Stores(d1).interrupts).toEqualTypeOf<InterruptStore>()
+
 expectTypeOf(cloudflarePersistence({}).stores).toEqualTypeOf<{}>()
 expectTypeOf(cloudflarePersistence({ d1 }).stores).toEqualTypeOf<{
   messages: MessageStore
diff --git a/packages/ai-persistence-cloudflare/tests/migration-cli.test.ts b/packages/ai-persistence-cloudflare/tests/migration-cli.test.ts
index 5e5fd529b..b88f285db 100644
--- a/packages/ai-persistence-cloudflare/tests/migration-cli.test.ts
+++ b/packages/ai-persistence-cloudflare/tests/migration-cli.test.ts
@@ -30,19 +30,25 @@ describe('Cloudflare D1 migrations CLI', () => {
       },
     })
 
-    expect(output).toBe(`${d1Migrations[0]?.sql.trimEnd()}\n`)
+    expect(output).toBe(
+      `${d1Migrations.map((migration) => migration.sql.trimEnd()).join('\n\n')}\n`,
+    )
   })
 
   it('copies migrations without overwriting divergent files by default', async () => {
     const directory = await createTemporaryDirectory()
     await runCloudflareMigrationsCli(['--out', directory])
 
-    const migration = d1Migrations[0]
+    for (const migration of d1Migrations) {
+      expect(await readFile(join(directory, migration.filename), 'utf8')).toBe(
+        migration.sql,
+      )
+    }
+
+    const migration = d1Migrations[1]
     expect(migration).toBeDefined()
     if (!migration) return
     const destination = join(directory, migration.filename)
-    expect(await readFile(destination, 'utf8')).toBe(migration.sql)
-
     await writeFile(destination, 'user-owned contents', 'utf8')
     await expect(
       runCloudflareMigrationsCli(['--out', directory]),
diff --git a/packages/ai-persistence-cloudflare/tests/migrations.test.ts b/packages/ai-persistence-cloudflare/tests/migrations.test.ts
index 666e303fd..43a62e210 100644
--- a/packages/ai-persistence-cloudflare/tests/migrations.test.ts
+++ b/packages/ai-persistence-cloudflare/tests/migrations.test.ts
@@ -1,11 +1,32 @@
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
+import { Miniflare } from 'miniflare'
 import { d1Migrations } from '../src/index'
 
+interface MigrationBindings {
+  AI_DB: D1Database
+}
+
+function statementsFor(sql: string): Array<string> {
+  return sql
+    .split('--> statement-breakpoint')
+    .map((statement) => statement.trim())
+    .filter((statement) => statement.length > 0)
+}
+
+async function applyMigration(
+  d1: D1Database,
+  migration: (typeof d1Migrations)[number],
+): Promise<void> {
+  await d1.batch(
+    statementsFor(migration.sql).map((statement) => d1.prepare(statement)),
+  )
+}
+
 describe('D1 migrations', () => {
   it('exports the canonical structured-state migration', () => {
-    expect(d1Migrations).toHaveLength(1)
+    expect(d1Migrations).toHaveLength(2)
     expect(d1Migrations[0]).toMatchObject({
       id: '0000_tanstack_ai_initial',
       filename: '0000_tanstack_ai_initial.sql',
@@ -16,7 +37,12 @@ describe('D1 migrations', () => {
     expect(sql).toMatch(/CREATE TABLE [`"]interrupts[`"]/)
     expect(sql).toMatch(/CREATE TABLE [`"]metadata[`"]/)
     expect(sql).not.toMatch(/CREATE TABLE [`"]artifacts[`"]/)
-    expect(sql).not.toMatch(/CREATE TABLE [`"]blobs[`"]/)
+    expect(sql).not.toContain('CREATE TABLE `blobs`')
+    expect(d1Migrations[1]).toMatchObject({
+      id: '0001_tanstack_ai_interrupt_batches',
+      filename: '0001_tanstack_ai_interrupt_batches.sql',
+    })
+    expect(d1Migrations[1]?.sql).toContain('CREATE TABLE `interrupt_batches`')
   })
 
   it('keeps the published migration equal to the embedded asset', async () => {
@@ -34,5 +60,111 @@ describe('D1 migrations', () => {
     )
     expect(published).toBe(embedded)
     expect(d1Migrations[0]?.sql).toBe(embedded)
+
+    const interruptEmbedded = await readFile(
+      fileURLToPath(
+        new URL(
+          '../src/assets/0001_tanstack_ai_interrupt_batches.sql',
+          import.meta.url,
+        ),
+      ),
+      'utf8',
+    )
+    const interruptPublished = await readFile(
+      fileURLToPath(
+        new URL(
+          '../migrations/0001_tanstack_ai_interrupt_batches.sql',
+          import.meta.url,
+        ),
+      ),
+      'utf8',
+    )
+    const drizzlePublished = await readFile(
+      fileURLToPath(
+        new URL(
+          '../../ai-persistence-drizzle/drizzle/0001_tanstack_ai_interrupt_batches.sql',
+          import.meta.url,
+        ),
+      ),
+      'utf8',
+    )
+    expect(interruptPublished).not.toBe('')
+    expect(interruptPublished).toBe(interruptEmbedded)
+    expect(interruptPublished).toBe(drizzlePublished)
+    expect(d1Migrations[1]?.sql).toBe(interruptEmbedded)
   })
+
+  it('backfills safe legacy identity for pending and completed rows', async () => {
+    const miniflare = new Miniflare({
+      compatibilityDate: '2026-06-24',
+      d1Databases: ['AI_DB'],
+      modules: true,
+      script: 'export default { fetch() { return new Response("ok") } }',
+    })
+    try {
+      const bindings = await miniflare.getBindings<MigrationBindings>()
+      const initial = d1Migrations[0]
+      const interruptBatches = d1Migrations[1]
+      expect(initial).toBeDefined()
+      expect(interruptBatches).toBeDefined()
+      if (!initial || !interruptBatches) return
+      await applyMigration(bindings.AI_DB, initial)
+      await bindings.AI_DB.batch([
+        bindings.AI_DB.prepare(
+          `INSERT INTO interrupts
+            (interrupt_id, run_id, thread_id, status, requested_at, payload_json)
+           VALUES (?, ?, ?, ?, ?, ?)`,
+        ).bind(
+          'pending-int',
+          'pending-run',
+          'thread-legacy',
+          'pending',
+          1,
+          '{"id":"pending-int","reason":"confirmation"}',
+        ),
+        bindings.AI_DB.prepare(
+          `INSERT INTO interrupts
+            (interrupt_id, run_id, thread_id, status, requested_at, payload_json)
+           VALUES (?, ?, ?, ?, ?, ?)`,
+        ).bind(
+          'resolved-int',
+          'resolved-run',
+          'thread-legacy',
+          'resolved',
+          2,
+          '{"id":"resolved-int","reason":"confirmation"}',
+        ),
+      ])
+
+      await applyMigration(bindings.AI_DB, interruptBatches)
+
+      const rows = await bindings.AI_DB.prepare(
+        `SELECT interrupt_id, generation, binding_json, response_schema_hash
+         FROM interrupts ORDER BY interrupt_id`,
+      ).all<{
+        interrupt_id: string
+        generation: number
+        binding_json: string
+        response_schema_hash: string
+      }>()
+      expect(rows.results).toEqual([
+        {
+          interrupt_id: 'pending-int',
+          generation: 1,
+          binding_json:
+            '{"kind":"generic","interruptId":"pending-int","interruptedRunId":"pending-run","generation":1,"responseSchemaHash":"legacy:unknown"}',
+          response_schema_hash: 'legacy:unknown',
+        },
+        {
+          interrupt_id: 'resolved-int',
+          generation: 0,
+          binding_json:
+            '{"kind":"generic","interruptId":"resolved-int","interruptedRunId":"resolved-run","generation":0,"responseSchemaHash":"legacy:unknown"}',
+          response_schema_hash: 'legacy:unknown',
+        },
+      ])
+    } finally {
+      await miniflare.dispose()
+    }
+  }, 30_000)
 })
diff --git a/packages/ai-persistence-cloudflare/tests/runtime.conformance.test.ts b/packages/ai-persistence-cloudflare/tests/runtime.conformance.test.ts
index 9f9101250..5834b5716 100644
--- a/packages/ai-persistence-cloudflare/tests/runtime.conformance.test.ts
+++ b/packages/ai-persistence-cloudflare/tests/runtime.conformance.test.ts
@@ -1,19 +1,42 @@
 /// <reference types="@cloudflare/workers-types" />
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 import { Miniflare } from 'miniflare'
-import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
-import { cloudflarePersistence, d1Migrations } from '../src/index'
+import {
+  runInterruptStoreConformance,
+  runPersistenceConformance,
+} from '@tanstack/ai-persistence/testkit'
 import { composePersistence } from '@tanstack/ai-persistence'
+import { cloudflarePersistence, d1Migrations } from '../src/index'
+import { createD1InterruptStore } from '../src/d1'
 import type { AIPersistence, InterruptStore } from '@tanstack/ai-persistence'
+import type { InterruptConformanceHarness } from '@tanstack/ai-persistence/testkit'
 
 interface RuntimeBindings {
   AI_DB: D1Database
   AI_BUCKET: R2Bucket
 }
 
+function migrationStatements(sql: string): Array<string> {
+  return sql
+    .split('--> statement-breakpoint')
+    .map((statement) => statement.trim())
+    .filter((statement) => statement.length > 0)
+}
+
+async function applyMigrations(d1: D1Database): Promise<void> {
+  for (const migration of d1Migrations) {
+    await d1.batch(
+      migrationStatements(migration.sql).map((statement) =>
+        d1.prepare(statement),
+      ),
+    )
+  }
+}
+
 describe('Cloudflare persistence on Miniflare bindings', () => {
   let miniflare: Miniflare
   let persistence: AIPersistence
+  let d1: D1Database
 
   beforeAll(async () => {
     miniflare = new Miniflare({
@@ -24,20 +47,13 @@ describe('Cloudflare persistence on Miniflare bindings', () => {
       script: 'export default { fetch() { return new Response("ok") } }',
     })
     const bindings = await miniflare.getBindings<RuntimeBindings>()
-    for (const migration of d1Migrations) {
-      const statements = migration.sql
-        .split('--> statement-breakpoint')
-        .map((statement) => statement.trim())
-        .filter((statement) => statement.length > 0)
-      await bindings.AI_DB.batch(
-        statements.map((statement) => bindings.AI_DB.prepare(statement)),
-      )
-    }
+    d1 = bindings.AI_DB
+    await applyMigrations(d1)
     persistence = cloudflarePersistence({
       d1: bindings.AI_DB,
       r2: bindings.AI_BUCKET,
     })
-  })
+  }, 30_000)
 
   afterAll(async () => {
     await miniflare.dispose()
@@ -45,16 +61,88 @@ describe('Cloudflare persistence on Miniflare bindings', () => {
 
   runPersistenceConformance('cloudflare-d1-r2', () => persistence)
 
+  runInterruptStoreConformance(
+    async (): Promise<InterruptConformanceHarness> => {
+      await d1.exec('DROP TRIGGER IF EXISTS fail_interrupt_transition')
+      await d1.batch([
+        d1.prepare('DELETE FROM interrupt_batches'),
+        d1.prepare('DELETE FROM interrupts'),
+      ])
+      let now = Date.parse('2026-07-13T10:00:00.000Z')
+      let pendingFailureSetup: Promise<D1ExecResult> | undefined
+      const createBase = () =>
+        createD1InterruptStore(d1, {
+          clock: () => now,
+        })
+      const base = createBase()
+      const store: InterruptStore = {
+        create: (record) => base.create(record),
+        resolve: (interruptId, response) => base.resolve(interruptId, response),
+        cancel: (interruptId) => base.cancel(interruptId),
+        get: (interruptId) => base.get(interruptId),
+        list: (threadId) => base.list(threadId),
+        listPending: (threadId) => base.listPending(threadId),
+        listByRun: (runId) => base.listByRun(runId),
+        listPendingByRun: (runId) => base.listPendingByRun(runId),
+        openInterruptBatch: (input) => base.openInterruptBatch(input),
+        async commitInterruptResolutions(input) {
+          if (pendingFailureSetup) {
+            await pendingFailureSetup
+            pendingFailureSetup = undefined
+          }
+          return base.commitInterruptResolutions(input)
+        },
+        getInterruptRecoveryState: (input) =>
+          base.getInterruptRecoveryState(input),
+      }
+
+      return {
+        getStore: () => store,
+        advanceBy(milliseconds) {
+          now += milliseconds
+        },
+        async inspect(interruptedRunId) {
+          const [rows, batch] = await Promise.all([
+            d1
+              .prepare(
+                'SELECT status FROM interrupts WHERE run_id = ? ORDER BY interrupt_id',
+              )
+              .bind(interruptedRunId)
+              .all<{ status: string }>(),
+            d1
+              .prepare(
+                'SELECT COUNT(*) AS count FROM interrupt_batches WHERE interrupted_run_id = ?',
+              )
+              .bind(interruptedRunId)
+              .first<number>('count'),
+          ])
+          return {
+            statuses: rows.results.map((row) => row.status),
+            batchCount: batch ?? -1,
+          }
+        },
+        failTransitionOnce(interruptId) {
+          const escapedInterruptId = interruptId.replaceAll("'", "''")
+          pendingFailureSetup = d1.exec(`
+            CREATE TRIGGER fail_interrupt_transition
+            BEFORE UPDATE OF status ON interrupts
+            WHEN OLD.interrupt_id = '${escapedInterruptId}'
+              AND NEW.status <> OLD.status
+            BEGIN
+              SELECT RAISE(ABORT, 'injected interrupt transition failure');
+            END;
+          `)
+        },
+        reopen: () => Promise.resolve(createBase()),
+      }
+    },
+  )
+
   it('composes a custom interrupt store while retaining D1 runs', () => {
+    const baseInterrupts = persistence.stores.interrupts
+    if (!baseInterrupts) throw new Error('D1 interrupt store missing')
     const customInterrupts: InterruptStore = {
-      create: () => Promise.resolve(),
-      resolve: () => Promise.resolve(),
-      cancel: () => Promise.resolve(),
-      get: () => Promise.resolve(null),
-      list: () => Promise.resolve([]),
-      listPending: () => Promise.resolve([]),
-      listByRun: () => Promise.resolve([]),
-      listPendingByRun: () => Promise.resolve([]),
+      ...baseInterrupts,
     }
     const composed = composePersistence(persistence, {
       overrides: { interrupts: customInterrupts },
diff --git a/packages/ai-persistence-drizzle/drizzle/0001_tanstack_ai_interrupt_batches.sql b/packages/ai-persistence-drizzle/drizzle/0001_tanstack_ai_interrupt_batches.sql
new file mode 100644
index 000000000..d81b74cee
--- /dev/null
+++ b/packages/ai-persistence-drizzle/drizzle/0001_tanstack_ai_interrupt_batches.sql
@@ -0,0 +1,68 @@
+CREATE TABLE `interrupt_batches` (
+	`interrupted_run_id` text PRIMARY KEY NOT NULL,
+	`thread_id` text NOT NULL,
+	`generation` integer NOT NULL,
+	`expected_interrupt_ids_json` text NOT NULL,
+	`fingerprint` text NOT NULL,
+	`canonical_resolutions` text NOT NULL,
+	`resolutions_json` text NOT NULL,
+	`continuation_run_id` text NOT NULL,
+	`committed_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `interrupt_batches_continuation_run_id_unique` ON `interrupt_batches` (`continuation_run_id`);
+--> statement-breakpoint
+CREATE TABLE `__new_interrupts` (
+	`interrupt_id` text PRIMARY KEY NOT NULL,
+	`run_id` text NOT NULL,
+	`thread_id` text NOT NULL,
+	`generation` integer NOT NULL,
+	`status` text NOT NULL,
+	`requested_at` integer NOT NULL,
+	`resolved_at` integer,
+	`payload_json` text NOT NULL,
+	`binding_json` text NOT NULL,
+	`response_schema_hash` text NOT NULL,
+	`response_json` text
+);
+--> statement-breakpoint
+INSERT INTO `__new_interrupts` (
+	`interrupt_id`,
+	`run_id`,
+	`thread_id`,
+	`generation`,
+	`status`,
+	`requested_at`,
+	`resolved_at`,
+	`payload_json`,
+	`binding_json`,
+	`response_schema_hash`,
+	`response_json`
+)
+SELECT
+	`interrupt_id`,
+	`run_id`,
+	`thread_id`,
+	CASE WHEN `status` = 'pending' THEN 1 ELSE 0 END,
+	`status`,
+	`requested_at`,
+	`resolved_at`,
+	`payload_json`,
+	json_object(
+		'kind', 'generic',
+		'interruptId', `interrupt_id`,
+		'interruptedRunId', `run_id`,
+		'generation', CASE WHEN `status` = 'pending' THEN 1 ELSE 0 END,
+		'responseSchemaHash', 'legacy:unknown'
+	),
+	'legacy:unknown',
+	`response_json`
+FROM `interrupts`;
+--> statement-breakpoint
+DROP TABLE `interrupts`;
+--> statement-breakpoint
+ALTER TABLE `__new_interrupts` RENAME TO `interrupts`;
+--> statement-breakpoint
+CREATE INDEX `interrupts_thread_status_requested_at_idx` ON `interrupts` (`thread_id`,`status`,`requested_at`);
+--> statement-breakpoint
+CREATE INDEX `interrupts_run_status_requested_at_idx` ON `interrupts` (`run_id`,`status`,`requested_at`);
diff --git a/packages/ai-persistence-drizzle/drizzle/meta/0001_snapshot.json b/packages/ai-persistence-drizzle/drizzle/meta/0001_snapshot.json
new file mode 100644
index 000000000..24a99472d
--- /dev/null
+++ b/packages/ai-persistence-drizzle/drizzle/meta/0001_snapshot.json
@@ -0,0 +1,446 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "a87024ed-c5cd-41f2-aefd-fa31b9664b8d",
+  "prevId": "5e224922-d0ca-4cac-bf7b-5813ad6f6d5d",
+  "tables": {
+    "artifacts": {
+      "name": "artifacts",
+      "columns": {
+        "artifact_id": {
+          "name": "artifact_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mime_type": {
+          "name": "mime_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "size": {
+          "name": "size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_url": {
+          "name": "external_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "blobs": {
+      "name": "blobs",
+      "columns": {
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "content_type": {
+          "name": "content_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "size": {
+          "name": "size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "etag": {
+          "name": "etag",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "custom_metadata_json": {
+          "name": "custom_metadata_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "body": {
+          "name": "body",
+          "type": "blob",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "interrupt_batches": {
+      "name": "interrupt_batches",
+      "columns": {
+        "interrupted_run_id": {
+          "name": "interrupted_run_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "generation": {
+          "name": "generation",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "expected_interrupt_ids_json": {
+          "name": "expected_interrupt_ids_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "fingerprint": {
+          "name": "fingerprint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "canonical_resolutions": {
+          "name": "canonical_resolutions",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "resolutions_json": {
+          "name": "resolutions_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "continuation_run_id": {
+          "name": "continuation_run_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "committed_at": {
+          "name": "committed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "interrupt_batches_continuation_run_id_unique": {
+          "name": "interrupt_batches_continuation_run_id_unique",
+          "columns": ["continuation_run_id"],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "interrupts": {
+      "name": "interrupts",
+      "columns": {
+        "interrupt_id": {
+          "name": "interrupt_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "generation": {
+          "name": "generation",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "requested_at": {
+          "name": "requested_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "resolved_at": {
+          "name": "resolved_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "payload_json": {
+          "name": "payload_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "binding_json": {
+          "name": "binding_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "response_schema_hash": {
+          "name": "response_schema_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "response_json": {
+          "name": "response_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "interrupts_thread_status_requested_at_idx": {
+          "name": "interrupts_thread_status_requested_at_idx",
+          "columns": ["thread_id", "status", "requested_at"],
+          "isUnique": false
+        },
+        "interrupts_run_status_requested_at_idx": {
+          "name": "interrupts_run_status_requested_at_idx",
+          "columns": ["run_id", "status", "requested_at"],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "messages": {
+      "name": "messages",
+      "columns": {
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "messages_json": {
+          "name": "messages_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "metadata": {
+      "name": "metadata",
+      "columns": {
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "value_json": {
+          "name": "value_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {
+        "metadata_scope_key_pk": {
+          "columns": ["scope", "key"],
+          "name": "metadata_scope_key_pk"
+        }
+      },
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "runs": {
+      "name": "runs",
+      "columns": {
+        "run_id": {
+          "name": "run_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "finished_at": {
+          "name": "finished_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "error": {
+          "name": "error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "usage_json": {
+          "name": "usage_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
diff --git a/packages/ai-persistence-drizzle/drizzle/meta/_journal.json b/packages/ai-persistence-drizzle/drizzle/meta/_journal.json
index 7083785c2..da27e9e0f 100644
--- a/packages/ai-persistence-drizzle/drizzle/meta/_journal.json
+++ b/packages/ai-persistence-drizzle/drizzle/meta/_journal.json
@@ -8,6 +8,13 @@
       "when": 1783594836281,
       "tag": "0000_tanstack_ai_initial",
       "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1783960294769,
+      "tag": "0001_tanstack_ai_interrupt_batches",
+      "breakpoints": true
     }
   ]
 }
diff --git a/packages/ai-persistence-drizzle/src/assets/0001_tanstack_ai_interrupt_batches.sql b/packages/ai-persistence-drizzle/src/assets/0001_tanstack_ai_interrupt_batches.sql
new file mode 100644
index 000000000..d81b74cee
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/assets/0001_tanstack_ai_interrupt_batches.sql
@@ -0,0 +1,68 @@
+CREATE TABLE `interrupt_batches` (
+	`interrupted_run_id` text PRIMARY KEY NOT NULL,
+	`thread_id` text NOT NULL,
+	`generation` integer NOT NULL,
+	`expected_interrupt_ids_json` text NOT NULL,
+	`fingerprint` text NOT NULL,
+	`canonical_resolutions` text NOT NULL,
+	`resolutions_json` text NOT NULL,
+	`continuation_run_id` text NOT NULL,
+	`committed_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `interrupt_batches_continuation_run_id_unique` ON `interrupt_batches` (`continuation_run_id`);
+--> statement-breakpoint
+CREATE TABLE `__new_interrupts` (
+	`interrupt_id` text PRIMARY KEY NOT NULL,
+	`run_id` text NOT NULL,
+	`thread_id` text NOT NULL,
+	`generation` integer NOT NULL,
+	`status` text NOT NULL,
+	`requested_at` integer NOT NULL,
+	`resolved_at` integer,
+	`payload_json` text NOT NULL,
+	`binding_json` text NOT NULL,
+	`response_schema_hash` text NOT NULL,
+	`response_json` text
+);
+--> statement-breakpoint
+INSERT INTO `__new_interrupts` (
+	`interrupt_id`,
+	`run_id`,
+	`thread_id`,
+	`generation`,
+	`status`,
+	`requested_at`,
+	`resolved_at`,
+	`payload_json`,
+	`binding_json`,
+	`response_schema_hash`,
+	`response_json`
+)
+SELECT
+	`interrupt_id`,
+	`run_id`,
+	`thread_id`,
+	CASE WHEN `status` = 'pending' THEN 1 ELSE 0 END,
+	`status`,
+	`requested_at`,
+	`resolved_at`,
+	`payload_json`,
+	json_object(
+		'kind', 'generic',
+		'interruptId', `interrupt_id`,
+		'interruptedRunId', `run_id`,
+		'generation', CASE WHEN `status` = 'pending' THEN 1 ELSE 0 END,
+		'responseSchemaHash', 'legacy:unknown'
+	),
+	'legacy:unknown',
+	`response_json`
+FROM `interrupts`;
+--> statement-breakpoint
+DROP TABLE `interrupts`;
+--> statement-breakpoint
+ALTER TABLE `__new_interrupts` RENAME TO `interrupts`;
+--> statement-breakpoint
+CREATE INDEX `interrupts_thread_status_requested_at_idx` ON `interrupts` (`thread_id`,`status`,`requested_at`);
+--> statement-breakpoint
+CREATE INDEX `interrupts_run_status_requested_at_idx` ON `interrupts` (`run_id`,`status`,`requested_at`);
diff --git a/packages/ai-persistence-drizzle/src/assets/tanstack-ai-schema.ts b/packages/ai-persistence-drizzle/src/assets/tanstack-ai-schema.ts
index 7fcfbec8c..5a349797d 100644
--- a/packages/ai-persistence-drizzle/src/assets/tanstack-ai-schema.ts
+++ b/packages/ai-persistence-drizzle/src/assets/tanstack-ai-schema.ts
@@ -6,9 +6,14 @@
  *
  * ```ts
  * import { drizzlePersistence } from '@tanstack/ai-persistence-drizzle'
+ * import type { DrizzleTransactionExecutor } from '@tanstack/ai-persistence-drizzle'
  * import { schema } from './tanstack-ai-schema'
  *
- * const persistence = drizzlePersistence(db, { schema })
+ * declare const transactionExecutor: DrizzleTransactionExecutor
+ * const persistence = drizzlePersistence(db, {
+ *   schema,
+ *   interrupts: transactionExecutor,
+ * })
  * ```
  *
  * You may rename tables and columns (or drop the explicit column names below
@@ -18,13 +23,19 @@
  */
 import {
   customType,
+  index,
   integer,
   primaryKey,
   sqliteTable,
   text,
+  uniqueIndex,
 } from 'drizzle-orm/sqlite-core'
-import type { InterruptRecord, RunStatus } from '@tanstack/ai-persistence'
-import type { ModelMessage, TokenUsage } from '@tanstack/ai'
+import type {
+  InterruptBatchRecord,
+  InterruptRecord,
+  RunStatus,
+} from '@tanstack/ai-persistence'
+import type { InterruptBinding, ModelMessage, TokenUsage } from '@tanstack/ai'
 
 const bytes = customType<{
   data: Uint8Array<ArrayBuffer>
@@ -64,18 +75,65 @@ export const runs = sqliteTable('runs', {
 })
 
 /** Interrupt / approval records (`InterruptStore`). */
-export const interrupts = sqliteTable('interrupts', {
-  interruptId: text('interrupt_id').primaryKey(),
-  runId: text('run_id').notNull(),
-  threadId: text('thread_id').notNull(),
-  status: text('status').$type<InterruptRecord['status']>().notNull(),
-  requestedAt: integer('requested_at').notNull(),
-  resolvedAt: integer('resolved_at'),
-  payloadJson: text('payload_json', { mode: 'json' })
-    .$type<Record<string, unknown>>()
-    .notNull(),
-  responseJson: text('response_json', { mode: 'json' }).$type<unknown>(),
-})
+export const interrupts = sqliteTable(
+  'interrupts',
+  {
+    interruptId: text('interrupt_id').primaryKey(),
+    runId: text('run_id').notNull(),
+    threadId: text('thread_id').notNull(),
+    generation: integer('generation').notNull(),
+    status: text('status').$type<InterruptRecord['status']>().notNull(),
+    requestedAt: integer('requested_at').notNull(),
+    resolvedAt: integer('resolved_at'),
+    payloadJson: text('payload_json', { mode: 'json' })
+      .$type<InterruptRecord['payload']>()
+      .notNull(),
+    bindingJson: text('binding_json', { mode: 'json' })
+      .$type<InterruptBinding>()
+      .notNull(),
+    responseSchemaHash: text('response_schema_hash').notNull(),
+    responseJson: text('response_json', { mode: 'json' }).$type<unknown>(),
+  },
+  (table) => [
+    index('interrupts_thread_status_requested_at_idx').on(
+      table.threadId,
+      table.status,
+      table.requestedAt,
+    ),
+    index('interrupts_run_status_requested_at_idx').on(
+      table.runId,
+      table.status,
+      table.requestedAt,
+    ),
+  ],
+)
+
+/** Durable winner records for atomic interrupt resolution batches. */
+export const interruptBatches = sqliteTable(
+  'interrupt_batches',
+  {
+    interruptedRunId: text('interrupted_run_id').primaryKey(),
+    threadId: text('thread_id').notNull(),
+    generation: integer('generation').notNull(),
+    expectedInterruptIdsJson: text('expected_interrupt_ids_json', {
+      mode: 'json',
+    })
+      .$type<InterruptBatchRecord['expectedInterruptIds']>()
+      .notNull(),
+    fingerprint: text('fingerprint').notNull(),
+    canonicalResolutions: text('canonical_resolutions').notNull(),
+    resolutionsJson: text('resolutions_json', { mode: 'json' })
+      .$type<InterruptBatchRecord['resolutions']>()
+      .notNull(),
+    continuationRunId: text('continuation_run_id').notNull(),
+    committedAt: integer('committed_at').notNull(),
+  },
+  (table) => [
+    uniqueIndex('interrupt_batches_continuation_run_id_unique').on(
+      table.continuationRunId,
+    ),
+  ],
+)
 
 /** Scoped key/value metadata (`MetadataStore`). */
 export const metadata = sqliteTable(
@@ -114,11 +172,12 @@ export const blobs = sqliteTable('blobs', {
   body: bytes('body'),
 })
 
-/** The full state schema, for `drizzlePersistence(db, { schema })` and drizzle-kit. */
+/** The full state schema for `drizzlePersistence` and drizzle-kit. */
 export const schema = {
   messages,
   runs,
   interrupts,
+  interruptBatches,
   metadata,
   artifacts,
   blobs,
diff --git a/packages/ai-persistence-drizzle/src/index.ts b/packages/ai-persistence-drizzle/src/index.ts
index 99600cafa..0681c7c5f 100644
--- a/packages/ai-persistence-drizzle/src/index.ts
+++ b/packages/ai-persistence-drizzle/src/index.ts
@@ -19,7 +19,11 @@ import {
 } from './stores'
 import type { TanstackAiSchema } from './schema-contract'
 import type { LockStore } from '@tanstack/ai'
-import type { DrizzleDb, TanstackAiTables } from './stores'
+import type {
+  DrizzleDb,
+  DrizzleTransactionExecutor,
+  TanstackAiTables,
+} from './stores'
 
 export { schema } from './schema'
 export { sqliteMigrations } from './migrations'
@@ -27,7 +31,7 @@ export { drizzleSchemaFilename, drizzleSchemaSource } from './schema-source'
 export { DrizzleSchemaError } from './schema-contract'
 export type { TanstackAiSchema } from './schema-contract'
 export type { SqliteMigration } from './migrations'
-export type { DrizzleDb } from './stores'
+export type { DrizzleDb, DrizzleTransactionExecutor } from './stores'
 
 export interface DrizzlePersistenceOptions {
   /**
@@ -41,22 +45,68 @@ export interface DrizzlePersistenceOptions {
   schema?: TanstackAiSchema
 }
 
+export interface DrizzlePersistenceInterruptOptions extends DrizzlePersistenceOptions {
+  /** Atomic transaction boundary required by the interrupt store. */
+  interrupts: DrizzleTransactionExecutor
+  /** Override wall-clock time, primarily for deterministic runtimes/tests. */
+  clock?: () => number
+}
+
+export interface DrizzlePersistenceWithoutInterruptsOptions extends DrizzlePersistenceOptions {
+  /** Explicitly omit interrupts while retaining all other Drizzle stores. */
+  interrupts: false
+}
+
+function createBaseStores(db: DrizzleDb, tables: TanstackAiTables) {
+  const locks: LockStore = new InMemoryLockStore()
+  return {
+    messages: createMessageStore(db, tables),
+    runs: createRunStore(db, tables),
+    metadata: createMetadataStore(db, tables),
+    artifacts: createArtifactStore(db, tables),
+    blobs: createBlobStore(db, tables),
+    locks,
+  }
+}
+
+type DrizzleBaseStores = ReturnType<typeof createBaseStores>
+type DrizzleStoresWithInterrupts = DrizzleBaseStores & {
+  interrupts: ReturnType<typeof createInterruptStore>
+}
+
 /** Wire TanStack AI persistence stores over a migrated Drizzle SQLite database. */
 export function drizzlePersistence(
   db: DrizzleDb,
-  options?: DrizzlePersistenceOptions,
-) {
-  const tables = resolveTables(options?.schema)
-  const locks: LockStore = new InMemoryLockStore()
+  options: DrizzlePersistenceInterruptOptions,
+): { stores: DrizzleStoresWithInterrupts }
+export function drizzlePersistence(
+  db: DrizzleDb,
+  options: DrizzlePersistenceWithoutInterruptsOptions,
+): { stores: DrizzleBaseStores }
+export function drizzlePersistence(db: DrizzleDb): never
+export function drizzlePersistence(
+  db: DrizzleDb,
+  options?:
+    | DrizzlePersistenceInterruptOptions
+    | DrizzlePersistenceWithoutInterruptsOptions,
+): { stores: DrizzleBaseStores | DrizzleStoresWithInterrupts } {
+  if (!options) {
+    throw new Error(
+      'Drizzle interrupts require an explicit transaction executor. Pass { interrupts: executor } or explicitly disable them with { interrupts: false }.',
+    )
+  }
+  const tables = resolveTables(options.schema)
+  const stores = createBaseStores(db, tables)
+  if (options.interrupts === false) return { stores }
   return {
     stores: {
-      messages: createMessageStore(db, tables),
-      runs: createRunStore(db, tables),
-      interrupts: createInterruptStore(db, tables),
-      metadata: createMetadataStore(db, tables),
-      artifacts: createArtifactStore(db, tables),
-      blobs: createBlobStore(db, tables),
-      locks,
+      ...stores,
+      interrupts: createInterruptStore(
+        db,
+        tables,
+        options.interrupts,
+        options.clock,
+      ),
     },
   }
 }
diff --git a/packages/ai-persistence-drizzle/src/migrations.ts b/packages/ai-persistence-drizzle/src/migrations.ts
index 889f6426f..1df3a525c 100644
--- a/packages/ai-persistence-drizzle/src/migrations.ts
+++ b/packages/ai-persistence-drizzle/src/migrations.ts
@@ -1,4 +1,5 @@
 import initialMigrationSql from './assets/0000_tanstack_ai_initial.sql?raw'
+import interruptBatchesMigrationSql from './assets/0001_tanstack_ai_interrupt_batches.sql?raw'
 
 /** A canonical SQLite migration bundled with the adapter. */
 export interface SqliteMigration {
@@ -17,4 +18,9 @@ export const sqliteMigrations: ReadonlyArray<SqliteMigration> = [
     filename: '0000_tanstack_ai_initial.sql',
     sql: initialMigrationSql,
   },
+  {
+    id: '0001_tanstack_ai_interrupt_batches',
+    filename: '0001_tanstack_ai_interrupt_batches.sql',
+    sql: interruptBatchesMigrationSql,
+  },
 ]
diff --git a/packages/ai-persistence-drizzle/src/schema-contract.ts b/packages/ai-persistence-drizzle/src/schema-contract.ts
index 568e7fbe1..bf23a90cc 100644
--- a/packages/ai-persistence-drizzle/src/schema-contract.ts
+++ b/packages/ai-persistence-drizzle/src/schema-contract.ts
@@ -14,8 +14,12 @@
 import { Column, is } from 'drizzle-orm'
 import { SQLiteTable } from 'drizzle-orm/sqlite-core'
 import type { AnySQLiteColumn } from 'drizzle-orm/sqlite-core'
-import type { InterruptRecord, RunStatus } from '@tanstack/ai-persistence'
-import type { ModelMessage, TokenUsage } from '@tanstack/ai'
+import type {
+  InterruptBatchRecord,
+  InterruptRecord,
+  RunStatus,
+} from '@tanstack/ai-persistence'
+import type { InterruptBinding, ModelMessage, TokenUsage } from '@tanstack/ai'
 
 /**
  * A column whose decoded (`data`) type is `TData`. Name, table name, and
@@ -48,12 +52,28 @@ export interface TanstackAiSchema {
     interruptId: AiColumn<string>
     runId: AiColumn<string>
     threadId: AiColumn<string>
+    generation: AiColumn<number>
     status: AiColumn<InterruptRecord['status']>
     requestedAt: AiColumn<number>
     resolvedAt: AiColumn<number>
-    payloadJson: AiColumn<Record<string, unknown>>
+    payloadJson: AiColumn<InterruptRecord['payload']>
+    bindingJson: AiColumn<InterruptBinding>
+    responseSchemaHash: AiColumn<string>
     responseJson: AiColumn<unknown>
   }>
+  interruptBatches: AiTable<{
+    interruptedRunId: AiColumn<string>
+    threadId: AiColumn<string>
+    generation: AiColumn<number>
+    expectedInterruptIdsJson: AiColumn<
+      InterruptBatchRecord['expectedInterruptIds']
+    >
+    fingerprint: AiColumn<string>
+    canonicalResolutions: AiColumn<string>
+    resolutionsJson: AiColumn<InterruptBatchRecord['resolutions']>
+    continuationRunId: AiColumn<string>
+    committedAt: AiColumn<number>
+  }>
   metadata: AiTable<{
     scope: AiColumn<string>
     key: AiColumn<string>
@@ -98,12 +118,26 @@ const requiredColumns: {
     'interruptId',
     'runId',
     'threadId',
+    'generation',
     'status',
     'requestedAt',
     'resolvedAt',
     'payloadJson',
+    'bindingJson',
+    'responseSchemaHash',
     'responseJson',
   ],
+  interruptBatches: [
+    'interruptedRunId',
+    'threadId',
+    'generation',
+    'expectedInterruptIdsJson',
+    'fingerprint',
+    'canonicalResolutions',
+    'resolutionsJson',
+    'continuationRunId',
+    'committedAt',
+  ],
   metadata: ['scope', 'key', 'valueJson'],
   artifacts: [
     'artifactId',
diff --git a/packages/ai-persistence-drizzle/src/schema.ts b/packages/ai-persistence-drizzle/src/schema.ts
index b9cae92c7..ca9b02d99 100644
--- a/packages/ai-persistence-drizzle/src/schema.ts
+++ b/packages/ai-persistence-drizzle/src/schema.ts
@@ -16,13 +16,19 @@
  */
 import {
   customType,
+  index,
   integer,
   primaryKey,
   sqliteTable,
   text,
+  uniqueIndex,
 } from 'drizzle-orm/sqlite-core'
-import type { InterruptRecord, RunStatus } from '@tanstack/ai-persistence'
-import type { ModelMessage, TokenUsage } from '@tanstack/ai'
+import type {
+  InterruptBatchRecord,
+  InterruptRecord,
+  RunStatus,
+} from '@tanstack/ai-persistence'
+import type { InterruptBinding, ModelMessage, TokenUsage } from '@tanstack/ai'
 
 const bytes = customType<{
   data: Uint8Array<ArrayBuffer>
@@ -62,18 +68,65 @@ export const runs = sqliteTable('runs', {
 })
 
 /** Interrupt / approval records (`InterruptStore`). */
-export const interrupts = sqliteTable('interrupts', {
-  interruptId: text('interrupt_id').primaryKey(),
-  runId: text('run_id').notNull(),
-  threadId: text('thread_id').notNull(),
-  status: text('status').$type<InterruptRecord['status']>().notNull(),
-  requestedAt: integer('requested_at').notNull(),
-  resolvedAt: integer('resolved_at'),
-  payloadJson: text('payload_json', { mode: 'json' })
-    .$type<Record<string, unknown>>()
-    .notNull(),
-  responseJson: text('response_json', { mode: 'json' }).$type<unknown>(),
-})
+export const interrupts = sqliteTable(
+  'interrupts',
+  {
+    interruptId: text('interrupt_id').primaryKey(),
+    runId: text('run_id').notNull(),
+    threadId: text('thread_id').notNull(),
+    generation: integer('generation').notNull(),
+    status: text('status').$type<InterruptRecord['status']>().notNull(),
+    requestedAt: integer('requested_at').notNull(),
+    resolvedAt: integer('resolved_at'),
+    payloadJson: text('payload_json', { mode: 'json' })
+      .$type<InterruptRecord['payload']>()
+      .notNull(),
+    bindingJson: text('binding_json', { mode: 'json' })
+      .$type<InterruptBinding>()
+      .notNull(),
+    responseSchemaHash: text('response_schema_hash').notNull(),
+    responseJson: text('response_json', { mode: 'json' }).$type<unknown>(),
+  },
+  (table) => [
+    index('interrupts_thread_status_requested_at_idx').on(
+      table.threadId,
+      table.status,
+      table.requestedAt,
+    ),
+    index('interrupts_run_status_requested_at_idx').on(
+      table.runId,
+      table.status,
+      table.requestedAt,
+    ),
+  ],
+)
+
+/** Durable winner records for atomic interrupt resolution batches. */
+export const interruptBatches = sqliteTable(
+  'interrupt_batches',
+  {
+    interruptedRunId: text('interrupted_run_id').primaryKey(),
+    threadId: text('thread_id').notNull(),
+    generation: integer('generation').notNull(),
+    expectedInterruptIdsJson: text('expected_interrupt_ids_json', {
+      mode: 'json',
+    })
+      .$type<InterruptBatchRecord['expectedInterruptIds']>()
+      .notNull(),
+    fingerprint: text('fingerprint').notNull(),
+    canonicalResolutions: text('canonical_resolutions').notNull(),
+    resolutionsJson: text('resolutions_json', { mode: 'json' })
+      .$type<InterruptBatchRecord['resolutions']>()
+      .notNull(),
+    continuationRunId: text('continuation_run_id').notNull(),
+    committedAt: integer('committed_at').notNull(),
+  },
+  (table) => [
+    uniqueIndex('interrupt_batches_continuation_run_id_unique').on(
+      table.continuationRunId,
+    ),
+  ],
+)
 
 /** Scoped key/value metadata (`MetadataStore`). */
 export const metadata = sqliteTable(
@@ -117,6 +170,7 @@ export const schema = {
   messages,
   runs,
   interrupts,
+  interruptBatches,
   metadata,
   artifacts,
   blobs,
diff --git a/packages/ai-persistence-drizzle/src/sqlite.ts b/packages/ai-persistence-drizzle/src/sqlite.ts
index 0774c3ff0..3a7c87bc0 100644
--- a/packages/ai-persistence-drizzle/src/sqlite.ts
+++ b/packages/ai-persistence-drizzle/src/sqlite.ts
@@ -7,6 +7,7 @@ import { drizzle } from 'drizzle-orm/sqlite-proxy'
 import { sqliteMigrations } from './migrations'
 import { applySqliteMigrations } from './sqlite-migrations'
 import { drizzlePersistence } from './index'
+import type { DrizzleTransactionExecutor } from './index'
 
 export { SqliteMigrationError } from './sqlite-migrations'
 
@@ -15,6 +16,41 @@ export interface SqlitePersistenceOptions {
   url: string
   /** Apply the bundled TanStack AI migrations before creating stores. */
   migrate?: boolean
+  /** Override wall-clock time, primarily for deterministic runtimes/tests. */
+  clock?: () => number
+}
+
+function createSqliteTransactionExecutor(
+  database: DatabaseSync,
+): DrizzleTransactionExecutor {
+  let tail = Promise.resolve()
+  return {
+    transaction(work) {
+      const result = tail.then(async () => {
+        database.exec('BEGIN IMMEDIATE')
+        try {
+          const value = await work()
+          database.exec('COMMIT')
+          return value
+        } catch (error) {
+          try {
+            database.exec('ROLLBACK')
+          } catch (rollbackError) {
+            throw new AggregateError(
+              [error, rollbackError],
+              'Interrupt transaction failed and could not be rolled back.',
+            )
+          }
+          throw error
+        }
+      })
+      tail = result.then(
+        () => undefined,
+        () => undefined,
+      )
+      return result
+    },
+  }
 }
 
 /** Build persistence over Node's built-in SQLite driver. */
@@ -43,7 +79,11 @@ export function sqlitePersistence(options: SqlitePersistenceOptions) {
     return Promise.resolve({ rows: rows.map((row) => Object.values(row)) })
   })
 
-  const persistence = drizzlePersistence(db)
+  const transactionExecutor = createSqliteTransactionExecutor(sqlite)
+  const persistence = drizzlePersistence(db, {
+    interrupts: transactionExecutor,
+    ...(options.clock !== undefined ? { clock: options.clock } : {}),
+  })
   let closed = false
   return {
     ...persistence,
diff --git a/packages/ai-persistence-drizzle/src/stores.ts b/packages/ai-persistence-drizzle/src/stores.ts
index 8e5920c7b..dfa6f12ea 100644
--- a/packages/ai-persistence-drizzle/src/stores.ts
+++ b/packages/ai-persistence-drizzle/src/stores.ts
@@ -5,11 +5,33 @@
  * (`@tanstack/ai-persistence`'s `memory.ts`). JSON columns are handled by
  * Drizzle's `text({ mode: 'json' })`; blob bytes by `blob({ mode: 'buffer' })`.
  */
+import {
+  canonicalInterruptJson,
+  canonicalizeInterruptResolutions,
+  cloneAndDeepFreezeJson,
+} from '@tanstack/ai'
 import { and, asc, eq, gt, gte, lt } from 'drizzle-orm'
-import type { artifacts, blobs, interrupts, runs, schema } from './schema'
+import {
+  InterruptStoreCorruptionError,
+  hasExactInterruptIds,
+  projectInterruptRecovery,
+} from '@tanstack/ai-persistence'
+import type {
+  artifacts,
+  blobs,
+  interruptBatches,
+  interrupts,
+  runs,
+  schema,
+} from './schema'
 import type { SQL } from 'drizzle-orm'
 import type { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core'
-import type { ModelMessage } from '@tanstack/ai'
+import type {
+  InterruptBinding,
+  InterruptRecoveryQuery,
+  ModelMessage,
+  RunAgentResumeItem,
+} from '@tanstack/ai'
 import type {
   ArtifactRecord,
   ArtifactStore,
@@ -19,6 +41,7 @@ import type {
   BlobObject,
   BlobRecord,
   BlobStore,
+  InterruptBatchRecord,
   InterruptRecord,
   InterruptStore,
   MessageStore,
@@ -39,6 +62,11 @@ export type DrizzleDb = Pick<
   'select' | 'insert' | 'update' | 'delete'
 >
 
+/** Required atomic transaction boundary for Drizzle interrupt operations. */
+export interface DrizzleTransactionExecutor {
+  transaction: <T>(work: () => Promise<T>) => Promise<T>
+}
+
 /**
  * The concrete table set the stores are written against. A user-supplied
  * {@link TanstackAiSchema} is validated by `assertTanstackAiSchema` and then
@@ -202,52 +230,330 @@ export function createRunStore(
   return store
 }
 
+function corrupt(message: string): never {
+  throw new InterruptStoreCorruptionError(message)
+}
+
+function decodeBinding(
+  value: unknown,
+  correlation: {
+    interruptId: string
+    interruptedRunId: string
+    generation: number
+    responseSchemaHash: string
+  },
+): InterruptBinding {
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    !('kind' in value) ||
+    !('interruptId' in value) ||
+    !('interruptedRunId' in value) ||
+    !('generation' in value) ||
+    !('responseSchemaHash' in value) ||
+    typeof value.interruptId !== 'string' ||
+    typeof value.interruptedRunId !== 'string' ||
+    typeof value.generation !== 'number' ||
+    typeof value.responseSchemaHash !== 'string'
+  ) {
+    return corrupt('Stored interrupt binding is malformed.')
+  }
+  const expiresAt = 'expiresAt' in value ? value.expiresAt : undefined
+  if (
+    expiresAt !== undefined &&
+    (typeof expiresAt !== 'string' || !Number.isFinite(Date.parse(expiresAt)))
+  ) {
+    return corrupt('Stored interrupt expiry is malformed.')
+  }
+  if (
+    value.interruptId !== correlation.interruptId ||
+    value.interruptedRunId !== correlation.interruptedRunId ||
+    value.generation !== correlation.generation ||
+    value.responseSchemaHash !== correlation.responseSchemaHash
+  ) {
+    return corrupt('Stored interrupt binding correlation is inconsistent.')
+  }
+
+  if (value.kind === 'generic') {
+    return {
+      kind: 'generic',
+      interruptId: value.interruptId,
+      interruptedRunId: value.interruptedRunId,
+      generation: value.generation,
+      responseSchemaHash: value.responseSchemaHash,
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+    }
+  }
+  if (
+    value.kind === 'client-tool-execution' &&
+    'toolName' in value &&
+    'toolCallId' in value &&
+    'outputSchemaHash' in value &&
+    typeof value.toolName === 'string' &&
+    typeof value.toolCallId === 'string' &&
+    typeof value.outputSchemaHash === 'string'
+  ) {
+    return {
+      kind: 'client-tool-execution',
+      interruptId: value.interruptId,
+      interruptedRunId: value.interruptedRunId,
+      generation: value.generation,
+      toolName: value.toolName,
+      toolCallId: value.toolCallId,
+      outputSchemaHash: value.outputSchemaHash,
+      responseSchemaHash: value.responseSchemaHash,
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+    }
+  }
+  if (
+    value.kind === 'tool-approval' &&
+    'toolName' in value &&
+    'toolCallId' in value &&
+    'originalArgs' in value &&
+    'inputSchemaHash' in value &&
+    'approvalSchemaHash' in value &&
+    typeof value.toolName === 'string' &&
+    typeof value.toolCallId === 'string' &&
+    typeof value.inputSchemaHash === 'string' &&
+    typeof value.approvalSchemaHash === 'string'
+  ) {
+    return {
+      kind: 'tool-approval',
+      interruptId: value.interruptId,
+      interruptedRunId: value.interruptedRunId,
+      generation: value.generation,
+      toolName: value.toolName,
+      toolCallId: value.toolCallId,
+      originalArgs: value.originalArgs,
+      inputSchemaHash: value.inputSchemaHash,
+      approvalSchemaHash: value.approvalSchemaHash,
+      responseSchemaHash: value.responseSchemaHash,
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+    }
+  }
+  return corrupt('Stored interrupt binding kind is malformed.')
+}
+
+function validateNativeDescriptor(value: unknown, interruptId: string): void {
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    !('id' in value) ||
+    !('reason' in value) ||
+    value.id !== interruptId ||
+    typeof value.reason !== 'string'
+  ) {
+    corrupt('Stored interrupt descriptor correlation is inconsistent.')
+  }
+}
+
 function mapInterrupt(row: typeof interrupts.$inferSelect): InterruptRecord {
+  const binding = decodeBinding(row.bindingJson, {
+    interruptId: row.interruptId,
+    interruptedRunId: row.runId,
+    generation: row.generation,
+    responseSchemaHash: row.responseSchemaHash,
+  })
+  if (row.generation > 0) {
+    validateNativeDescriptor(row.payloadJson, row.interruptId)
+  }
   return {
     interruptId: row.interruptId,
     runId: row.runId,
     threadId: row.threadId,
+    generation: row.generation,
     status: row.status,
     requestedAt: row.requestedAt,
     ...(row.resolvedAt != null ? { resolvedAt: row.resolvedAt } : {}),
     payload: row.payloadJson,
+    binding,
     ...(row.responseJson != null ? { response: row.responseJson } : {}),
   }
 }
 
+function decodeStringArray(value: unknown, field: string): Array<string> {
+  if (!Array.isArray(value)) return corrupt(`Stored ${field} is malformed.`)
+  const strings: Array<string> = []
+  for (const item of value) {
+    if (typeof item !== 'string') {
+      return corrupt(`Stored ${field} is malformed.`)
+    }
+    strings.push(item)
+  }
+  if (!hasExactInterruptIds(strings, strings)) {
+    return corrupt(`Stored ${field} contains duplicate IDs.`)
+  }
+  return strings
+}
+
+function decodeResolution(value: unknown): RunAgentResumeItem {
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    !('interruptId' in value) ||
+    !('status' in value) ||
+    typeof value.interruptId !== 'string' ||
+    (value.status !== 'resolved' && value.status !== 'cancelled')
+  ) {
+    return corrupt('Stored interrupt resolution is malformed.')
+  }
+  return {
+    interruptId: value.interruptId,
+    status: value.status,
+    ...('payload' in value ? { payload: value.payload } : {}),
+  }
+}
+
+function decodeResolutions(value: unknown): Array<RunAgentResumeItem> {
+  if (!Array.isArray(value)) {
+    return corrupt('Stored interrupt resolutions are malformed.')
+  }
+  return value.map(decodeResolution)
+}
+
+function mapInterruptBatch(
+  row: typeof interruptBatches.$inferSelect,
+): InterruptBatchRecord {
+  const expectedInterruptIds = decodeStringArray(
+    row.expectedInterruptIdsJson,
+    'expected interrupt IDs',
+  )
+  const resolutions = decodeResolutions(row.resolutionsJson)
+  const candidate = canonicalizeInterruptResolutions(resolutions)
+  if (
+    !hasExactInterruptIds(
+      expectedInterruptIds,
+      resolutions.map((resolution) => resolution.interruptId),
+    ) ||
+    candidate.fingerprint !== row.fingerprint ||
+    candidate.canonicalResolutions !== row.canonicalResolutions
+  ) {
+    return corrupt('Stored interrupt batch identity is inconsistent.')
+  }
+  return {
+    threadId: row.threadId,
+    interruptedRunId: row.interruptedRunId,
+    generation: row.generation,
+    expectedInterruptIds,
+    fingerprint: row.fingerprint,
+    canonicalResolutions: row.canonicalResolutions,
+    resolutions,
+    continuationRunId: row.continuationRunId,
+    committedAt: row.committedAt,
+  }
+}
+
 export function createInterruptStore(
   db: DrizzleDb,
-  { interrupts }: TanstackAiTables,
+  { interruptBatches, interrupts }: TanstackAiTables,
+  transactionExecutor: DrizzleTransactionExecutor,
+  clock: () => number = Date.now,
 ): InterruptStore {
-  return {
+  const rowsForRun = async (runId: string) =>
+    (
+      await db
+        .select()
+        .from(interrupts)
+        .where(eq(interrupts.runId, runId))
+        .orderBy(asc(interrupts.requestedAt), asc(interrupts.interruptId))
+    ).map(mapInterrupt)
+
+  const readBatch = async (
+    interruptedRunId: string,
+  ): Promise<InterruptBatchRecord | null> => {
+    const rows = await db
+      .select()
+      .from(interruptBatches)
+      .where(eq(interruptBatches.interruptedRunId, interruptedRunId))
+    return rows[0] ? mapInterruptBatch(rows[0]) : null
+  }
+
+  const recovery = async (input: InterruptRecoveryQuery) => {
+    const rows = (await rowsForRun(input.interruptedRunId)).filter(
+      (row) => row.threadId === input.threadId,
+    )
+    const batch = await readBatch(input.interruptedRunId)
+    const correlatedBatch = batch?.threadId === input.threadId ? batch : null
+    const generations = new Set(rows.map((row) => row.generation))
+    if (generations.size > 1) {
+      return corrupt('Stored interrupt rows mix generations.')
+    }
+    if (
+      correlatedBatch &&
+      (rows.length === 0 ||
+        rows.some(
+          (row) =>
+            row.generation !== correlatedBatch.generation ||
+            row.runId !== correlatedBatch.interruptedRunId,
+        ) ||
+        !hasExactInterruptIds(
+          correlatedBatch.expectedInterruptIds,
+          rows.map((row) => row.interruptId),
+        ))
+    ) {
+      return corrupt('Stored interrupt batch correlation is inconsistent.')
+    }
+    return projectInterruptRecovery({
+      query: input,
+      rows,
+      batch: correlatedBatch,
+      now: clock(),
+      includeResolutions: true,
+    })
+  }
+
+  const store: InterruptStore = {
     async create(record) {
+      const generation = record.generation ?? 0
+      const binding = decodeBinding(
+        cloneAndDeepFreezeJson(
+          record.binding ?? {
+            kind: 'generic',
+            interruptId: record.interruptId,
+            interruptedRunId: record.runId,
+            generation,
+            responseSchemaHash: 'legacy:unknown',
+          },
+        ),
+        {
+          interruptId: record.interruptId,
+          interruptedRunId: record.runId,
+          generation,
+          responseSchemaHash:
+            record.binding?.responseSchemaHash ?? 'legacy:unknown',
+        },
+      )
       await db
         .insert(interrupts)
         .values({
           interruptId: record.interruptId,
           runId: record.runId,
           threadId: record.threadId,
+          generation,
           status: record.status,
           requestedAt: record.requestedAt,
-          payloadJson: record.payload,
+          payloadJson: cloneAndDeepFreezeJson(record.payload),
+          bindingJson: binding,
+          responseSchemaHash: binding.responseSchemaHash,
           responseJson: record.response ?? null,
         })
         .onConflictDoNothing({ target: interrupts.interruptId })
     },
     async resolve(interruptId, response) {
+      const set: Partial<typeof interrupts.$inferInsert> = {
+        status: 'resolved',
+        resolvedAt: clock(),
+      }
+      if (response !== undefined) set.responseJson = response
       await db
         .update(interrupts)
-        .set({
-          status: 'resolved',
-          resolvedAt: Date.now(),
-          responseJson: response ?? null,
-        })
+        .set(set)
         .where(eq(interrupts.interruptId, interruptId))
     },
     async cancel(interruptId) {
       await db
         .update(interrupts)
-        .set({ status: 'cancelled', resolvedAt: Date.now() })
+        .set({ status: 'cancelled', resolvedAt: clock() })
         .where(eq(interrupts.interruptId, interruptId))
     },
     async get(interruptId) {
@@ -280,12 +586,7 @@ export function createInterruptStore(
       return rows.map(mapInterrupt)
     },
     async listByRun(runId) {
-      const rows = await db
-        .select()
-        .from(interrupts)
-        .where(eq(interrupts.runId, runId))
-        .orderBy(asc(interrupts.requestedAt))
-      return rows.map(mapInterrupt)
+      return rowsForRun(runId)
     },
     async listPendingByRun(runId) {
       const rows = await db
@@ -297,7 +598,286 @@ export function createInterruptStore(
         .orderBy(asc(interrupts.requestedAt))
       return rows.map(mapInterrupt)
     },
+    async openInterruptBatch(input) {
+      const descriptors = cloneAndDeepFreezeJson(input.descriptors)
+      const unopenedBindings = cloneAndDeepFreezeJson(input.bindings)
+      const descriptorIds = descriptors.map((descriptor) => descriptor.id)
+      const bindingIds = unopenedBindings.map((binding) => binding.interruptId)
+      if (
+        descriptorIds.length === 0 ||
+        !hasExactInterruptIds(descriptorIds, bindingIds)
+      ) {
+        throw new TypeError(
+          'Interrupt descriptors and bindings must contain the same exact nonempty IDs.',
+        )
+      }
+      for (const descriptor of descriptors) {
+        validateNativeDescriptor(descriptor, descriptor.id)
+      }
+
+      return transactionExecutor.transaction(async () => {
+        if (await readBatch(input.interruptedRunId)) {
+          throw new Error('Cannot reopen a committed interrupt batch.')
+        }
+        const existing = await rowsForRun(input.interruptedRunId)
+        if (existing.length > 0) {
+          const generation = existing[0]?.generation
+          const requestedBindings = unopenedBindings
+            .map((binding) => ({
+              ...binding,
+              interruptedRunId: input.interruptedRunId,
+              generation,
+            }))
+            .sort((left, right) =>
+              left.interruptId.localeCompare(right.interruptId),
+            )
+          const existingBindings = existing
+            .map((row) => row.binding)
+            .sort((left, right) =>
+              left.interruptId.localeCompare(right.interruptId),
+            )
+          const existingDescriptors = existing
+            .map((row) => row.payload)
+            .sort((left, right) => {
+              if (
+                left !== null &&
+                typeof left === 'object' &&
+                'id' in left &&
+                typeof left.id === 'string' &&
+                right !== null &&
+                typeof right === 'object' &&
+                'id' in right &&
+                typeof right.id === 'string'
+              ) {
+                return left.id.localeCompare(right.id)
+              }
+              return 0
+            })
+          const requestedDescriptors = [...descriptors].sort((left, right) =>
+            left.id.localeCompare(right.id),
+          )
+          if (
+            generation !== undefined &&
+            existing.every(
+              (row) =>
+                row.threadId === input.threadId &&
+                row.generation === generation &&
+                row.status === 'pending',
+            ) &&
+            hasExactInterruptIds(
+              descriptorIds,
+              existing.map((row) => row.interruptId),
+            ) &&
+            canonicalInterruptJson(existingDescriptors) ===
+              canonicalInterruptJson(requestedDescriptors) &&
+            canonicalInterruptJson(existingBindings) ===
+              canonicalInterruptJson(requestedBindings)
+          ) {
+            return { generation, descriptors }
+          }
+          throw new Error('An incompatible interrupt batch is already open.')
+        }
+
+        const generation = 1
+        const byId = new Map(
+          unopenedBindings.map((binding) => [binding.interruptId, binding]),
+        )
+        const requestedAt = clock()
+        const values: Array<typeof interrupts.$inferInsert> = []
+        for (const descriptor of descriptors) {
+          const unopened = byId.get(descriptor.id)
+          if (!unopened) {
+            throw new Error(`Missing binding for interrupt: ${descriptor.id}`)
+          }
+          const proposedBinding = cloneAndDeepFreezeJson({
+            ...unopened,
+            interruptedRunId: input.interruptedRunId,
+            generation,
+          })
+          const binding = decodeBinding(proposedBinding, {
+            interruptId: descriptor.id,
+            interruptedRunId: input.interruptedRunId,
+            generation,
+            responseSchemaHash: proposedBinding.responseSchemaHash,
+          })
+          values.push({
+            interruptId: descriptor.id,
+            runId: input.interruptedRunId,
+            threadId: input.threadId,
+            generation,
+            status: 'pending',
+            requestedAt,
+            payloadJson: descriptor,
+            bindingJson: binding,
+            responseSchemaHash: binding.responseSchemaHash,
+          })
+        }
+        await db.insert(interrupts).values(values).onConflictDoNothing()
+        const inserted = await rowsForRun(input.interruptedRunId)
+        if (
+          !hasExactInterruptIds(
+            descriptorIds,
+            inserted.map((row) => row.interruptId),
+          ) ||
+          inserted.some(
+            (row) =>
+              row.threadId !== input.threadId ||
+              row.generation !== generation ||
+              row.status !== 'pending',
+          )
+        ) {
+          throw new Error('Interrupt IDs conflict with an existing batch.')
+        }
+        return { generation, descriptors }
+      })
+    },
+    async commitInterruptResolutions(input) {
+      return transactionExecutor.transaction(async () => {
+        const candidate = canonicalizeInterruptResolutions(input.resolutions)
+        if (
+          candidate.fingerprint !== input.fingerprint ||
+          candidate.canonicalResolutions !== input.canonicalResolutions
+        ) {
+          throw new TypeError(
+            'Interrupt batch identity does not match its resolutions.',
+          )
+        }
+
+        const existingWinner = await readBatch(input.interruptedRunId)
+        if (existingWinner) {
+          return existingWinner.threadId === input.threadId &&
+            existingWinner.fingerprint === input.fingerprint &&
+            existingWinner.canonicalResolutions === input.canonicalResolutions
+            ? {
+                status: 'replayed',
+                continuationRunId: existingWinner.continuationRunId,
+              }
+            : {
+                status: 'conflict',
+                authoritativeState: await recovery({
+                  threadId: input.threadId,
+                  interruptedRunId: input.interruptedRunId,
+                  knownGeneration: input.expectedGeneration,
+                }),
+              }
+        }
+
+        const pending = (await rowsForRun(input.interruptedRunId)).filter(
+          (row) => row.status === 'pending',
+        )
+        const resolutionIds = candidate.resolutions.map(
+          (resolution) => resolution.interruptId,
+        )
+        if (
+          !hasExactInterruptIds(
+            input.expectedInterruptIds,
+            pending.map((row) => row.interruptId),
+          ) ||
+          !hasExactInterruptIds(input.expectedInterruptIds, resolutionIds) ||
+          pending.some(
+            (row) =>
+              row.threadId !== input.threadId ||
+              row.generation !== input.expectedGeneration ||
+              (row.binding.expiresAt !== undefined &&
+                Date.parse(row.binding.expiresAt) <= clock()),
+          )
+        ) {
+          return {
+            status: 'conflict',
+            authoritativeState: await recovery({
+              threadId: input.threadId,
+              interruptedRunId: input.interruptedRunId,
+              knownGeneration: input.expectedGeneration,
+            }),
+          }
+        }
+
+        const committedAt = clock()
+        await db
+          .insert(interruptBatches)
+          .values({
+            interruptedRunId: input.interruptedRunId,
+            threadId: input.threadId,
+            generation: input.expectedGeneration,
+            expectedInterruptIdsJson: cloneAndDeepFreezeJson(
+              input.expectedInterruptIds,
+            ),
+            fingerprint: candidate.fingerprint,
+            canonicalResolutions: candidate.canonicalResolutions,
+            resolutionsJson: candidate.resolutions,
+            continuationRunId: input.continuationRunId,
+            committedAt,
+          })
+          .onConflictDoNothing({ target: interruptBatches.interruptedRunId })
+
+        const winner = await readBatch(input.interruptedRunId)
+        if (!winner) {
+          return corrupt('Interrupt winner insert did not persist a row.')
+        }
+        if (
+          winner.threadId !== input.threadId ||
+          winner.fingerprint !== input.fingerprint ||
+          winner.canonicalResolutions !== input.canonicalResolutions
+        ) {
+          return {
+            status: 'conflict',
+            authoritativeState: await recovery({
+              threadId: input.threadId,
+              interruptedRunId: input.interruptedRunId,
+              knownGeneration: input.expectedGeneration,
+            }),
+          }
+        }
+        if (winner.continuationRunId !== input.continuationRunId) {
+          return {
+            status: 'replayed',
+            continuationRunId: winner.continuationRunId,
+          }
+        }
+
+        for (const resolution of candidate.resolutions) {
+          const status =
+            resolution.status === 'cancelled' ? 'cancelled' : 'resolved'
+          await db
+            .update(interrupts)
+            .set({
+              status,
+              resolvedAt: committedAt,
+              responseJson: resolution,
+            })
+            .where(
+              and(
+                eq(interrupts.interruptId, resolution.interruptId),
+                eq(interrupts.runId, input.interruptedRunId),
+                eq(interrupts.threadId, input.threadId),
+                eq(interrupts.generation, input.expectedGeneration),
+                eq(interrupts.status, 'pending'),
+              ),
+            )
+          const transitioned = await store.get(resolution.interruptId)
+          if (
+            !transitioned ||
+            transitioned.status !== status ||
+            transitioned.resolvedAt !== committedAt ||
+            canonicalInterruptJson(transitioned.response) !==
+              canonicalInterruptJson(resolution)
+          ) {
+            throw new Error(
+              `Pending interrupt changed: ${resolution.interruptId}`,
+            )
+          }
+        }
+        return {
+          status: 'committed',
+          continuationRunId: input.continuationRunId,
+        }
+      })
+    },
+    async getInterruptRecoveryState(input) {
+      return transactionExecutor.transaction(() => recovery(input))
+    },
   }
+  return store
 }
 
 export function createMetadataStore(
diff --git a/packages/ai-persistence-drizzle/tests/api-types.test-d.ts b/packages/ai-persistence-drizzle/tests/api-types.test-d.ts
index 1b89b1437..ce9a23df7 100644
--- a/packages/ai-persistence-drizzle/tests/api-types.test-d.ts
+++ b/packages/ai-persistence-drizzle/tests/api-types.test-d.ts
@@ -1,4 +1,6 @@
 import { expectTypeOf } from 'vitest'
+import { drizzlePersistence } from '../src/index'
+import { sqlitePersistence } from '../src/sqlite'
 import type { DrizzleD1Database } from 'drizzle-orm/d1'
 import type {
   ArtifactStore,
@@ -9,24 +11,38 @@ import type {
   RunStore,
 } from '@tanstack/ai-persistence'
 import type { LockStore } from '@tanstack/ai'
-import { drizzlePersistence, schema } from '../src/index'
-import { sqlitePersistence } from '../src/sqlite'
 import { schema as emittedSchema } from '../src/assets/tanstack-ai-schema'
 import { variantSchema } from './variant-schema'
-import type { TanstackAiSchema } from '../src/index'
+import { schema } from '../src/index'
+import type { DrizzleTransactionExecutor, TanstackAiSchema } from '../src/index'
 
 declare const d1Database: DrizzleD1Database
-const d1Persistence = drizzlePersistence(d1Database)
-expectTypeOf(d1Persistence.stores.messages).toEqualTypeOf<MessageStore>()
-expectTypeOf(d1Persistence.stores.runs).toEqualTypeOf<RunStore>()
-expectTypeOf(d1Persistence.stores.interrupts).toEqualTypeOf<InterruptStore>()
-expectTypeOf(d1Persistence.stores.metadata).toEqualTypeOf<MetadataStore>()
-expectTypeOf(d1Persistence.stores.artifacts).toEqualTypeOf<ArtifactStore>()
-expectTypeOf(d1Persistence.stores.blobs).toEqualTypeOf<BlobStore>()
-expectTypeOf(d1Persistence.stores.locks).toEqualTypeOf<LockStore>()
+declare const transactionExecutor: DrizzleTransactionExecutor
+const genericPersistence = drizzlePersistence(d1Database, {
+  interrupts: transactionExecutor,
+})
+expectTypeOf(genericPersistence.stores.messages).toEqualTypeOf<MessageStore>()
+expectTypeOf(genericPersistence.stores.runs).toEqualTypeOf<RunStore>()
+expectTypeOf(
+  genericPersistence.stores.interrupts,
+).toEqualTypeOf<InterruptStore>()
+expectTypeOf(genericPersistence.stores.metadata).toEqualTypeOf<MetadataStore>()
+expectTypeOf(genericPersistence.stores.artifacts).toEqualTypeOf<ArtifactStore>()
+expectTypeOf(genericPersistence.stores.blobs).toEqualTypeOf<BlobStore>()
+expectTypeOf(genericPersistence.stores.locks).toEqualTypeOf<LockStore>()
+
+const nonInterruptPersistence = drizzlePersistence(d1Database, {
+  interrupts: false,
+})
+expectTypeOf(nonInterruptPersistence.stores.runs).toEqualTypeOf<RunStore>()
+// @ts-expect-error an explicit non-interrupt factory has no interrupt store
+nonInterruptPersistence.stores.interrupts
+
+const missingExecutor = drizzlePersistence(d1Database)
+expectTypeOf(missingExecutor).toEqualTypeOf<never>()
 
 const sqlite = sqlitePersistence({ url: ':memory:', migrate: true })
-expectTypeOf(sqlite.stores).toEqualTypeOf<typeof d1Persistence.stores>()
+expectTypeOf(sqlite.stores).toEqualTypeOf<typeof genericPersistence.stores>()
 expectTypeOf(sqlite.close).toEqualTypeOf<() => void>()
 
 // The bundled schema, the emitted schema asset, and a renamed/extended variant
@@ -37,7 +53,8 @@ expectTypeOf(variantSchema).toExtend<TanstackAiSchema>()
 
 const customPersistence = drizzlePersistence(d1Database, {
   schema: variantSchema,
+  interrupts: transactionExecutor,
 })
 expectTypeOf(customPersistence.stores).toEqualTypeOf<
-  typeof d1Persistence.stores
+  typeof genericPersistence.stores
 >()
diff --git a/packages/ai-persistence-drizzle/tests/custom-schema.test.ts b/packages/ai-persistence-drizzle/tests/custom-schema.test.ts
index 734c97017..7ca731a8b 100644
--- a/packages/ai-persistence-drizzle/tests/custom-schema.test.ts
+++ b/packages/ai-persistence-drizzle/tests/custom-schema.test.ts
@@ -7,9 +7,39 @@ import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
 import { DrizzleSchemaError, drizzlePersistence, schema } from '../src/index'
 import { variantDdl, variantSchema } from './variant-schema'
 import type { TanstackAiSchema } from '../src/index'
-import type { DrizzleDb } from '../src/index'
+import type { DrizzleDb, DrizzleTransactionExecutor } from '../src/index'
 
-function createVariantDb(): { db: DrizzleDb; sqlite: DatabaseSync } {
+function createTransactionExecutor(
+  sqlite: DatabaseSync,
+): DrizzleTransactionExecutor {
+  let tail = Promise.resolve()
+  return {
+    transaction(work) {
+      const result = tail.then(async () => {
+        sqlite.exec('BEGIN IMMEDIATE')
+        try {
+          const value = await work()
+          sqlite.exec('COMMIT')
+          return value
+        } catch (error) {
+          sqlite.exec('ROLLBACK')
+          throw error
+        }
+      })
+      tail = result.then(
+        () => undefined,
+        () => undefined,
+      )
+      return result
+    },
+  }
+}
+
+function createVariantDb(): {
+  db: DrizzleDb
+  sqlite: DatabaseSync
+  interrupts: DrizzleTransactionExecutor
+} {
   const sqlite = new DatabaseSync(':memory:')
   for (const statement of variantDdl) sqlite.exec(statement)
   const db = drizzle((sql, params, method) => {
@@ -25,19 +55,23 @@ function createVariantDb(): { db: DrizzleDb; sqlite: DatabaseSync } {
     const rows = statement.all(...params)
     return Promise.resolve({ rows: rows.map((row) => Object.values(row)) })
   })
-  return { db, sqlite }
+  return { db, sqlite, interrupts: createTransactionExecutor(sqlite) }
 }
 
 // The full store contract must hold when the runtime operates over a schema
 // whose table and column database names all differ from the bundled ones.
-runPersistenceConformance('drizzle-sqlite (injected variant schema)', () =>
-  drizzlePersistence(createVariantDb().db, { schema: variantSchema }),
-)
+runPersistenceConformance('drizzle-sqlite (injected variant schema)', () => {
+  const { db, interrupts } = createVariantDb()
+  return drizzlePersistence(db, { schema: variantSchema, interrupts })
+})
 
 describe('drizzlePersistence with an injected schema', () => {
   it('writes through the injected table and column names', async () => {
-    const { db, sqlite } = createVariantDb()
-    const persistence = drizzlePersistence(db, { schema: variantSchema })
+    const { db, interrupts, sqlite } = createVariantDb()
+    const persistence = drizzlePersistence(db, {
+      schema: variantSchema,
+      interrupts,
+    })
 
     await persistence.stores.messages.saveThread('thread-1', [
       { role: 'user', content: 'hello' },
@@ -53,8 +87,11 @@ describe('drizzlePersistence with an injected schema', () => {
   })
 
   it('coexists with app-owned columns on the same tables', async () => {
-    const { db, sqlite } = createVariantDb()
-    const persistence = drizzlePersistence(db, { schema: variantSchema })
+    const { db, interrupts, sqlite } = createVariantDb()
+    const persistence = drizzlePersistence(db, {
+      schema: variantSchema,
+      interrupts,
+    })
 
     await persistence.stores.messages.saveThread('thread-owned', [
       { role: 'user', content: 'mine' },
@@ -87,11 +124,13 @@ describe('drizzlePersistence with an injected schema', () => {
     expect(() =>
       drizzlePersistence(db, {
         schema: withoutBlobs as unknown as TanstackAiSchema,
+        interrupts: false,
       }),
     ).toThrow(DrizzleSchemaError)
     expect(() =>
       drizzlePersistence(db, {
         schema: withoutBlobs as unknown as TanstackAiSchema,
+        interrupts: false,
       }),
     ).toThrow(/`blobs` is not a Drizzle SQLite table/)
 
@@ -104,6 +143,7 @@ describe('drizzlePersistence with an injected schema', () => {
           ...schema,
           messages: incompleteMessages,
         } as unknown as TanstackAiSchema,
+        interrupts: false,
       }),
     ).toThrow(/`messages\.messagesJson` is missing/)
   })
diff --git a/packages/ai-persistence-drizzle/tests/drizzle.conformance.test.ts b/packages/ai-persistence-drizzle/tests/drizzle.conformance.test.ts
index caaef2ee3..ed9e77a9a 100644
--- a/packages/ai-persistence-drizzle/tests/drizzle.conformance.test.ts
+++ b/packages/ai-persistence-drizzle/tests/drizzle.conformance.test.ts
@@ -1,6 +1,132 @@
-import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { afterAll, describe, expect, it } from 'vitest'
+import { drizzle } from 'drizzle-orm/sqlite-proxy'
+import {
+  runInterruptStoreConformance,
+  runPersistenceConformance,
+} from '@tanstack/ai-persistence/testkit'
+import { drizzlePersistence } from '../src/index'
 import { sqlitePersistence } from '../src/sqlite'
+import type { InterruptConformanceHarness } from '@tanstack/ai-persistence/testkit'
+
+const cleanup: Array<() => void> = []
+
+function createNativeDrizzleDatabase(database: DatabaseSync) {
+  return drizzle((sql, params, method) => {
+    const statement = database.prepare(sql)
+    if (method === 'run') {
+      statement.run(...params)
+      return Promise.resolve({ rows: [] })
+    }
+    if (method === 'get') {
+      const row = statement.get(...params)
+      return Promise.resolve({ rows: row ? Object.values(row) : [] })
+    }
+    const rows = statement.all(...params)
+    return Promise.resolve({ rows: rows.map((row) => Object.values(row)) })
+  })
+}
+
+function createSqliteHarness(): Promise<InterruptConformanceHarness> {
+  const directory = mkdtempSync(join(tmpdir(), 'tanstack-ai-drizzle-cas-'))
+  const filename = join(directory, 'state.sqlite')
+  let now = Date.parse('2026-07-13T10:00:00.000Z')
+  const openConnections: Array<ReturnType<typeof sqlitePersistence>> = []
+
+  const open = () => {
+    const persistence = sqlitePersistence({
+      url: filename,
+      migrate: true,
+      clock: () => now,
+    })
+    openConnections.push(persistence)
+    return persistence
+  }
+  const persistence = open()
+
+  cleanup.push(() => {
+    for (const connection of openConnections.splice(0)) connection.close()
+    rmSync(directory, { recursive: true, force: true })
+  })
+
+  return Promise.resolve({
+    getStore: () => persistence.stores.interrupts,
+    advanceBy(milliseconds) {
+      now += milliseconds
+    },
+    async inspect(interruptedRunId) {
+      const statuses = (
+        await persistence.stores.interrupts.listByRun(interruptedRunId)
+      ).map((row) => row.status)
+      const database = new DatabaseSync(filename)
+      try {
+        const batch = database
+          .prepare(
+            'SELECT COUNT(*) AS count FROM interrupt_batches WHERE interrupted_run_id = ?',
+          )
+          .get(interruptedRunId)
+        return {
+          statuses,
+          batchCount: typeof batch?.count === 'number' ? batch.count : -1,
+        }
+      } finally {
+        database.close()
+      }
+    },
+    failTransitionOnce(interruptId) {
+      const database = new DatabaseSync(filename)
+      try {
+        database.exec(`
+          CREATE TRIGGER fail_interrupt_transition
+          BEFORE UPDATE OF status ON interrupts
+          WHEN OLD.interrupt_id = '${interruptId}' AND NEW.status <> OLD.status
+          BEGIN
+            SELECT RAISE(ABORT, 'injected interrupt transition failure');
+          END;
+        `)
+      } finally {
+        database.close()
+      }
+    },
+    reopen: () => Promise.resolve(open().stores.interrupts),
+  })
+}
 
 runPersistenceConformance('drizzle-sqlite', () =>
   sqlitePersistence({ url: ':memory:', migrate: true }),
 )
+
+runInterruptStoreConformance(createSqliteHarness)
+
+describe('drizzlePersistence interrupt transactions', () => {
+  it('rejects an implicit non-atomic interrupt store', () => {
+    const database = new DatabaseSync(':memory:')
+    cleanup.push(() => database.close())
+
+    expect(() =>
+      drizzlePersistence(createNativeDrizzleDatabase(database)),
+    ).toThrow(/interrupt.*transaction executor/i)
+  })
+
+  it('allows callers to explicitly omit interrupts', () => {
+    const database = new DatabaseSync(':memory:')
+    cleanup.push(() => database.close())
+
+    const persistence = drizzlePersistence(
+      createNativeDrizzleDatabase(database),
+      {
+        interrupts: false,
+      },
+    )
+
+    expect('interrupts' in persistence.stores).toBe(false)
+    expect(persistence.stores.runs).toBeDefined()
+  })
+})
+
+afterAll(() => {
+  for (const dispose of cleanup.splice(0).reverse()) dispose()
+})
diff --git a/packages/ai-persistence-drizzle/tests/migration-cli.test.ts b/packages/ai-persistence-drizzle/tests/migration-cli.test.ts
index 2743a2cbb..e79dcb5ed 100644
--- a/packages/ai-persistence-drizzle/tests/migration-cli.test.ts
+++ b/packages/ai-persistence-drizzle/tests/migration-cli.test.ts
@@ -30,18 +30,25 @@ describe('drizzle migrations CLI', () => {
       },
     })
 
-    expect(output).toBe(`${sqliteMigrations[0]?.sql.trimEnd()}\n`)
+    expect(output).toBe(
+      `${sqliteMigrations.map((migration) => migration.sql.trimEnd()).join('\n\n')}\n`,
+    )
   })
 
   it('copies migrations without overwriting divergent files by default', async () => {
     const directory = await createTemporaryDirectory()
     await runDrizzleMigrationsCli(['--out', directory])
 
-    const migration = sqliteMigrations[0]
+    for (const migration of sqliteMigrations) {
+      expect(await readFile(join(directory, migration.filename), 'utf8')).toBe(
+        migration.sql,
+      )
+    }
+
+    const migration = sqliteMigrations[1]
     expect(migration).toBeDefined()
     if (!migration) return
     const destination = join(directory, migration.filename)
-    expect(await readFile(destination, 'utf8')).toBe(migration.sql)
 
     await writeFile(destination, 'user-owned contents', 'utf8')
     await expect(runDrizzleMigrationsCli(['--out', directory])).rejects.toThrow(
diff --git a/packages/ai-persistence-drizzle/tests/migrations.test.ts b/packages/ai-persistence-drizzle/tests/migrations.test.ts
index 0e9d92945..d96e7ac7c 100644
--- a/packages/ai-persistence-drizzle/tests/migrations.test.ts
+++ b/packages/ai-persistence-drizzle/tests/migrations.test.ts
@@ -1,4 +1,5 @@
 import { DatabaseSync } from 'node:sqlite'
+import { readFileSync } from 'node:fs'
 import { afterEach, describe, expect, it } from 'vitest'
 import { sqliteMigrations } from '../src/migrations'
 import { applySqliteMigrations } from '../src/sqlite-migrations'
@@ -19,6 +20,7 @@ describe('sqlite migrations', () => {
   it('exposes an ordered canonical manifest and applies it idempotently', () => {
     expect(sqliteMigrations.map((migration) => migration.id)).toEqual([
       '0000_tanstack_ai_initial',
+      '0001_tanstack_ai_interrupt_batches',
     ])
 
     const database = createDatabase()
@@ -37,6 +39,7 @@ describe('sqlite migrations', () => {
         'artifacts',
         'blobs',
         'interrupts',
+        'interrupt_batches',
         'messages',
         'metadata',
         'runs',
@@ -46,7 +49,100 @@ describe('sqlite migrations', () => {
       database
         .prepare('SELECT migration_id FROM __tanstack_ai_migrations')
         .all(),
-    ).toEqual([{ migration_id: '0000_tanstack_ai_initial' }])
+    ).toEqual([
+      { migration_id: '0000_tanstack_ai_initial' },
+      { migration_id: '0001_tanstack_ai_interrupt_batches' },
+    ])
+  })
+
+  it('ships byte-identical nonempty generated and runtime migration assets', () => {
+    const migration = sqliteMigrations[1]
+    expect(migration?.sql.trim()).not.toBe('')
+    expect(migration?.sql).toBe(
+      readFileSync(
+        new URL(
+          '../drizzle/0001_tanstack_ai_interrupt_batches.sql',
+          import.meta.url,
+        ),
+        'utf8',
+      ),
+    )
+  })
+
+  it('backfills safe legacy interrupt identity and creates durable indexes', () => {
+    const database = createDatabase()
+    const initialMigration = sqliteMigrations[0]
+    expect(initialMigration).toBeDefined()
+    if (!initialMigration) return
+    applySqliteMigrations(database, [initialMigration])
+    database
+      .prepare(
+        `INSERT INTO interrupts
+          (interrupt_id, run_id, thread_id, status, requested_at, payload_json)
+         VALUES (?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        'pending-int',
+        'pending-run',
+        'thread-legacy',
+        'pending',
+        1,
+        '{"id":"pending-int","reason":"confirmation"}',
+      )
+    database
+      .prepare(
+        `INSERT INTO interrupts
+          (interrupt_id, run_id, thread_id, status, requested_at, payload_json)
+         VALUES (?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        'resolved-int',
+        'resolved-run',
+        'thread-legacy',
+        'resolved',
+        2,
+        '{"id":"resolved-int","reason":"confirmation"}',
+      )
+
+    applySqliteMigrations(database, sqliteMigrations)
+
+    expect(
+      database
+        .prepare(
+          `SELECT interrupt_id, generation, binding_json, response_schema_hash
+           FROM interrupts ORDER BY interrupt_id`,
+        )
+        .all(),
+    ).toEqual([
+      {
+        interrupt_id: 'pending-int',
+        generation: 1,
+        binding_json:
+          '{"kind":"generic","interruptId":"pending-int","interruptedRunId":"pending-run","generation":1,"responseSchemaHash":"legacy:unknown"}',
+        response_schema_hash: 'legacy:unknown',
+      },
+      {
+        interrupt_id: 'resolved-int',
+        generation: 0,
+        binding_json:
+          '{"kind":"generic","interruptId":"resolved-int","interruptedRunId":"resolved-run","generation":0,"responseSchemaHash":"legacy:unknown"}',
+        response_schema_hash: 'legacy:unknown',
+      },
+    ])
+
+    const indexes = database
+      .prepare(
+        "SELECT name FROM sqlite_master WHERE type = 'index' AND tbl_name IN ('interrupts', 'interrupt_batches') ORDER BY name",
+      )
+      .all()
+      .map((row) => row.name)
+    expect(indexes).toEqual(
+      expect.arrayContaining([
+        'interrupt_batches_continuation_run_id_unique',
+        'interrupts_run_status_requested_at_idx',
+        'interrupts_thread_status_requested_at_idx',
+      ]),
+    )
   })
 
   it('rolls back migration SQL and bookkeeping together, then permits retry', () => {
diff --git a/packages/ai-persistence-drizzle/tests/schema-cli.test.ts b/packages/ai-persistence-drizzle/tests/schema-cli.test.ts
index c24afee87..e73f425f1 100644
--- a/packages/ai-persistence-drizzle/tests/schema-cli.test.ts
+++ b/packages/ai-persistence-drizzle/tests/schema-cli.test.ts
@@ -31,7 +31,7 @@ describe('Drizzle schema CLI', () => {
     })
     expect(output).toBe(`${drizzleSchemaSource.trimEnd()}\n`)
     expect(output).toContain('sqliteTable')
-    expect(output).toContain('drizzlePersistence(db, { schema })')
+    expect(output).toContain('interrupts: transactionExecutor')
   })
 
   it('copies the schema without overwriting divergent files by default', async () => {
diff --git a/packages/ai-persistence-drizzle/tests/variant-schema.ts b/packages/ai-persistence-drizzle/tests/variant-schema.ts
index fd9606695..db6f6870c 100644
--- a/packages/ai-persistence-drizzle/tests/variant-schema.ts
+++ b/packages/ai-persistence-drizzle/tests/variant-schema.ts
@@ -7,13 +7,19 @@
  */
 import {
   customType,
+  index,
   integer,
   primaryKey,
   sqliteTable,
   text,
+  uniqueIndex,
 } from 'drizzle-orm/sqlite-core'
-import type { InterruptRecord, RunStatus } from '@tanstack/ai-persistence'
-import type { ModelMessage, TokenUsage } from '@tanstack/ai'
+import type {
+  InterruptBatchRecord,
+  InterruptRecord,
+  RunStatus,
+} from '@tanstack/ai-persistence'
+import type { InterruptBinding, ModelMessage, TokenUsage } from '@tanstack/ai'
 
 const bytes = customType<{
   data: Uint8Array<ArrayBuffer>
@@ -52,18 +58,64 @@ const runs = sqliteTable('app_ai_runs', {
   usageJson: text('usageJson', { mode: 'json' }).$type<TokenUsage>(),
 })
 
-const interrupts = sqliteTable('app_ai_interrupts', {
-  interruptId: text('interruptId').primaryKey(),
-  runId: text('runId').notNull(),
-  threadId: text('threadId').notNull(),
-  status: text('status').$type<InterruptRecord['status']>().notNull(),
-  requestedAt: integer('requestedAt').notNull(),
-  resolvedAt: integer('resolvedAt'),
-  payloadJson: text('payloadJson', { mode: 'json' })
-    .$type<Record<string, unknown>>()
-    .notNull(),
-  responseJson: text('responseJson', { mode: 'json' }).$type<unknown>(),
-})
+const interrupts = sqliteTable(
+  'app_ai_interrupts',
+  {
+    interruptId: text('interruptId').primaryKey(),
+    runId: text('runId').notNull(),
+    threadId: text('threadId').notNull(),
+    generation: integer('generation').notNull(),
+    status: text('status').$type<InterruptRecord['status']>().notNull(),
+    requestedAt: integer('requestedAt').notNull(),
+    resolvedAt: integer('resolvedAt'),
+    payloadJson: text('payloadJson', { mode: 'json' })
+      .$type<InterruptRecord['payload']>()
+      .notNull(),
+    bindingJson: text('bindingJson', { mode: 'json' })
+      .$type<InterruptBinding>()
+      .notNull(),
+    responseSchemaHash: text('responseSchemaHash').notNull(),
+    responseJson: text('responseJson', { mode: 'json' }).$type<unknown>(),
+  },
+  (table) => [
+    index('app_ai_interrupts_thread_status_requested_at_idx').on(
+      table.threadId,
+      table.status,
+      table.requestedAt,
+    ),
+    index('app_ai_interrupts_run_status_requested_at_idx').on(
+      table.runId,
+      table.status,
+      table.requestedAt,
+    ),
+  ],
+)
+
+const interruptBatches = sqliteTable(
+  'app_ai_interrupt_batches',
+  {
+    interruptedRunId: text('interruptedRunId').primaryKey(),
+    threadId: text('threadId').notNull(),
+    generation: integer('generation').notNull(),
+    expectedInterruptIdsJson: text('expectedInterruptIdsJson', {
+      mode: 'json',
+    })
+      .$type<InterruptBatchRecord['expectedInterruptIds']>()
+      .notNull(),
+    fingerprint: text('fingerprint').notNull(),
+    canonicalResolutions: text('canonicalResolutions').notNull(),
+    resolutionsJson: text('resolutionsJson', { mode: 'json' })
+      .$type<InterruptBatchRecord['resolutions']>()
+      .notNull(),
+    continuationRunId: text('continuationRunId').notNull(),
+    committedAt: integer('committedAt').notNull(),
+  },
+  (table) => [
+    uniqueIndex('app_ai_interrupt_batches_continuation_run_id_unique').on(
+      table.continuationRunId,
+    ),
+  ],
+)
 
 const metadata = sqliteTable(
   'app_ai_metadata',
@@ -103,6 +155,7 @@ export const variantSchema = {
   messages,
   runs,
   interrupts,
+  interruptBatches,
   metadata,
   artifacts,
   blobs,
@@ -128,12 +181,26 @@ export const variantDdl: ReadonlyArray<string> = [
     interruptId text PRIMARY KEY NOT NULL,
     runId text NOT NULL,
     threadId text NOT NULL,
+    generation integer NOT NULL,
     status text NOT NULL,
     requestedAt integer NOT NULL,
     resolvedAt integer,
     payloadJson text NOT NULL,
+    bindingJson text NOT NULL,
+    responseSchemaHash text NOT NULL,
     responseJson text
   );`,
+  `CREATE TABLE app_ai_interrupt_batches (
+    interruptedRunId text PRIMARY KEY NOT NULL,
+    threadId text NOT NULL,
+    generation integer NOT NULL,
+    expectedInterruptIdsJson text NOT NULL,
+    fingerprint text NOT NULL,
+    canonicalResolutions text NOT NULL,
+    resolutionsJson text NOT NULL,
+    continuationRunId text NOT NULL UNIQUE,
+    committedAt integer NOT NULL
+  );`,
   `CREATE TABLE app_ai_metadata (
     scopeName text NOT NULL,
     keyName text NOT NULL,
diff --git a/packages/ai-persistence-drizzle/vite.config.ts b/packages/ai-persistence-drizzle/vite.config.ts
index 05551030c..7ce379cfa 100644
--- a/packages/ai-persistence-drizzle/vite.config.ts
+++ b/packages/ai-persistence-drizzle/vite.config.ts
@@ -7,6 +7,7 @@ const config = defineConfig({
     name: packageJson.name,
     dir: './',
     watch: false,
+    testTimeout: 30_000,
 
     globals: true,
     environment: 'node',
diff --git a/packages/ai-persistence-prisma/prisma/tanstack-ai.prisma b/packages/ai-persistence-prisma/prisma/tanstack-ai.prisma
index 382893ed3..c0d9ebfef 100644
--- a/packages/ai-persistence-prisma/prisma/tanstack-ai.prisma
+++ b/packages/ai-persistence-prisma/prisma/tanstack-ai.prisma
@@ -30,15 +30,36 @@ model Interrupt {
   interruptId  String  @id @map("interrupt_id")
   runId        String  @map("run_id")
   threadId     String  @map("thread_id")
+  generation   Int     @default(0)
   status       String
   requestedAt  BigInt  @map("requested_at")
   resolvedAt   BigInt? @map("resolved_at")
   payloadJson  String  @map("payload_json")
+  bindingJson  String? @map("binding_json")
+  schemaHash   String? @map("schema_hash")
   responseJson String? @map("response_json")
 
+  @@index([threadId, status])
+  @@index([runId, generation, status])
   @@map("interrupts")
 }
 
+/// Immutable winner for an atomically committed interrupt batch.
+model InterruptBatch {
+  interruptedRunId        String @id @map("interrupted_run_id")
+  threadId                String @map("thread_id")
+  generation              Int
+  expectedInterruptIdsJson String @map("expected_interrupt_ids_json")
+  fingerprint             String
+  canonicalResolutions    String @map("canonical_resolutions")
+  resolutionsJson         String @map("resolutions_json")
+  continuationRunId       String @map("continuation_run_id")
+  committedAt             BigInt @map("committed_at")
+
+  @@index([threadId])
+  @@map("interrupt_batches")
+}
+
 /// Scoped key/value metadata (`MetadataStore`).
 model Metadata {
   scope     String
diff --git a/packages/ai-persistence-prisma/src/assets/tanstack-ai.prisma b/packages/ai-persistence-prisma/src/assets/tanstack-ai.prisma
index 382893ed3..c0d9ebfef 100644
--- a/packages/ai-persistence-prisma/src/assets/tanstack-ai.prisma
+++ b/packages/ai-persistence-prisma/src/assets/tanstack-ai.prisma
@@ -30,15 +30,36 @@ model Interrupt {
   interruptId  String  @id @map("interrupt_id")
   runId        String  @map("run_id")
   threadId     String  @map("thread_id")
+  generation   Int     @default(0)
   status       String
   requestedAt  BigInt  @map("requested_at")
   resolvedAt   BigInt? @map("resolved_at")
   payloadJson  String  @map("payload_json")
+  bindingJson  String? @map("binding_json")
+  schemaHash   String? @map("schema_hash")
   responseJson String? @map("response_json")
 
+  @@index([threadId, status])
+  @@index([runId, generation, status])
   @@map("interrupts")
 }
 
+/// Immutable winner for an atomically committed interrupt batch.
+model InterruptBatch {
+  interruptedRunId        String @id @map("interrupted_run_id")
+  threadId                String @map("thread_id")
+  generation              Int
+  expectedInterruptIdsJson String @map("expected_interrupt_ids_json")
+  fingerprint             String
+  canonicalResolutions    String @map("canonical_resolutions")
+  resolutionsJson         String @map("resolutions_json")
+  continuationRunId       String @map("continuation_run_id")
+  committedAt             BigInt @map("committed_at")
+
+  @@index([threadId])
+  @@map("interrupt_batches")
+}
+
 /// Scoped key/value metadata (`MetadataStore`).
 model Metadata {
   scope     String
diff --git a/packages/ai-persistence-prisma/src/index.ts b/packages/ai-persistence-prisma/src/index.ts
index f73496041..94dca339d 100644
--- a/packages/ai-persistence-prisma/src/index.ts
+++ b/packages/ai-persistence-prisma/src/index.ts
@@ -16,6 +16,7 @@ import {
   createRunStore,
 } from './stores'
 import type { PrismaModelMap } from './model-contract'
+import type { RunInterruptTransaction } from './stores'
 import type { LockStore } from '@tanstack/ai'
 import type { PrismaClient } from '@prisma/client'
 
@@ -41,12 +42,16 @@ export function prismaPersistence(
   options?: PrismaPersistenceOptions,
 ) {
   const delegates = resolveDelegates(prisma, options?.models)
+  const runInterruptTransaction: RunInterruptTransaction = (operation) =>
+    prisma.$transaction((transaction) =>
+      operation(resolveDelegates(transaction, options?.models)),
+    )
   const locks: LockStore = new InMemoryLockStore()
   return {
     stores: {
       messages: createMessageStore(delegates),
       runs: createRunStore(delegates),
-      interrupts: createInterruptStore(delegates),
+      interrupts: createInterruptStore(delegates, runInterruptTransaction),
       metadata: createMetadataStore(delegates),
       artifacts: createArtifactStore(delegates),
       blobs: createBlobStore(delegates),
diff --git a/packages/ai-persistence-prisma/src/model-contract.ts b/packages/ai-persistence-prisma/src/model-contract.ts
index 6a898b24a..4c95d5fdd 100644
--- a/packages/ai-persistence-prisma/src/model-contract.ts
+++ b/packages/ai-persistence-prisma/src/model-contract.ts
@@ -37,13 +37,28 @@ export interface InterruptRow {
   interruptId: string
   runId: string
   threadId: string
+  generation: number
   status: string
   requestedAt: bigint
   resolvedAt: bigint | null
   payloadJson: string
+  bindingJson: string | null
+  schemaHash: string | null
   responseJson: string | null
 }
 
+export interface InterruptBatchRow {
+  interruptedRunId: string
+  threadId: string
+  generation: number
+  expectedInterruptIdsJson: string
+  fingerprint: string
+  canonicalResolutions: string
+  resolutionsJson: string
+  continuationRunId: string
+  committedAt: bigint
+}
+
 export interface MetadataRow {
   scope: string
   key: string
@@ -111,8 +126,15 @@ export interface InterruptDelegate {
     where: { interruptId: string }
   }) => Promise<InterruptRow | null>
   findMany: (args: {
-    where: { threadId?: string; runId?: string; status?: string }
-    orderBy: { requestedAt: 'asc' }
+    where: {
+      interruptId?: string
+      runId?: string
+      threadId?: string
+      generation?: number
+      status?: string
+      bindingJson?: string | null
+    }
+    orderBy: Array<{ requestedAt: 'asc' } | { interruptId: 'asc' }>
   }) => Promise<Array<InterruptRow>>
   upsert: (args: {
     where: { interruptId: string }
@@ -120,16 +142,64 @@ export interface InterruptDelegate {
       interruptId: string
       runId: string
       threadId: string
+      generation: number
       status: string
       requestedAt: bigint
       payloadJson: string
+      bindingJson: string
+      schemaHash: string
       responseJson: string | null
     }
     update: Record<string, never>
   }) => Promise<unknown>
   updateMany: (args: {
-    where: { interruptId: string }
-    data: { status: string; resolvedAt: bigint; responseJson?: string | null }
+    where: {
+      interruptId?: string
+      runId?: string
+      threadId?: string
+      generation?: number
+      status?: string
+      bindingJson?: string | null
+    }
+    data: {
+      status?: string
+      resolvedAt?: bigint
+      responseJson?: string | null
+      bindingJson?: string
+      schemaHash?: string
+    }
+  }) => Promise<{ count: number }>
+  create: (args: {
+    data: {
+      interruptId: string
+      runId: string
+      threadId: string
+      generation: number
+      status: string
+      requestedAt: bigint
+      payloadJson: string
+      bindingJson: string
+      schemaHash: string
+    }
+  }) => Promise<unknown>
+}
+
+export interface InterruptBatchDelegate {
+  findUnique: (args: {
+    where: { interruptedRunId: string }
+  }) => Promise<InterruptBatchRow | null>
+  create: (args: {
+    data: {
+      interruptedRunId: string
+      threadId: string
+      generation: number
+      expectedInterruptIdsJson: string
+      fingerprint: string
+      canonicalResolutions: string
+      resolutionsJson: string
+      continuationRunId: string
+      committedAt: bigint
+    }
   }) => Promise<unknown>
 }
 
@@ -214,6 +284,7 @@ export interface TanstackAiDelegates {
   message: MessageDelegate
   run: RunDelegate
   interrupt: InterruptDelegate
+  interruptBatch: InterruptBatchDelegate
   metadata: MetadataDelegate
   artifact: ArtifactDelegate
   blob: BlobDelegate
@@ -228,6 +299,7 @@ export interface PrismaModelMap {
   messages?: string
   runs?: string
   interrupts?: string
+  interruptBatches?: string
   metadata?: string
   artifacts?: string
   blobs?: string
@@ -237,6 +309,7 @@ const defaultModelNames: Required<PrismaModelMap> = {
   messages: 'message',
   runs: 'run',
   interrupts: 'interrupt',
+  interruptBatches: 'interruptBatch',
   metadata: 'metadata',
   artifacts: 'artifact',
   blobs: 'blob',
@@ -252,6 +325,7 @@ const delegateKeyByStoreKey: {
   messages: 'message',
   runs: 'run',
   interrupts: 'interrupt',
+  interruptBatches: 'interruptBatch',
   metadata: 'metadata',
   artifacts: 'artifact',
   blobs: 'blob',
@@ -279,7 +353,7 @@ function isDelegate(value: unknown): boolean {
 }
 
 /**
- * Resolve the six store delegates off the client, applying any model-name
+ * Resolve the seven model delegates off the client, applying any model-name
  * overrides and verifying each resolved delegate looks like a Prisma model
  * delegate. Field shapes are enforced at compile time by the delegate
  * interfaces and are not re-checked here.
diff --git a/packages/ai-persistence-prisma/src/stores.ts b/packages/ai-persistence-prisma/src/stores.ts
index e5803fe44..edcad52aa 100644
--- a/packages/ai-persistence-prisma/src/stores.ts
+++ b/packages/ai-persistence-prisma/src/stores.ts
@@ -7,14 +7,33 @@
  * provider-neutral Prisma `String` fields, so they are serialized with
  * `JSON.stringify`/`JSON.parse` here; blob bytes use Prisma's `Bytes`.
  */
+import {
+  canonicalInterruptJson,
+  canonicalizeInterruptResolutions,
+  cloneAndDeepFreezeJson,
+} from '@tanstack/ai'
+import {
+  InterruptStoreCorruptionError,
+  hasExactInterruptIds,
+  projectInterruptRecovery,
+} from '@tanstack/ai-persistence'
 import type {
   ArtifactRow,
   BlobRow,
+  InterruptBatchRow,
   InterruptRow,
   RunRow,
   TanstackAiDelegates,
 } from './model-contract'
-import type { ModelMessage } from '@tanstack/ai'
+import type {
+  CommitInterruptResolutionsInput,
+  InterruptBinding,
+  InterruptCommitResult,
+  InterruptRecoveryQuery,
+  InterruptRecoveryStateV1,
+  ModelMessage,
+  RunAgentResumeItem,
+} from '@tanstack/ai'
 import type {
   ArtifactRecord,
   ArtifactStore,
@@ -24,6 +43,7 @@ import type {
   BlobObject,
   BlobRecord,
   BlobStore,
+  InterruptBatchRecord,
   InterruptRecord,
   InterruptStore,
   MessageStore,
@@ -36,6 +56,15 @@ import type {
 const textEncoder = new TextEncoder()
 const textDecoder = new TextDecoder()
 
+type InterruptTransactionDelegates = Pick<
+  TanstackAiDelegates,
+  'interrupt' | 'interruptBatch'
+>
+
+export type RunInterruptTransaction = <T>(
+  operation: (delegates: InterruptTransactionDelegates) => Promise<T>,
+) => Promise<T>
+
 /**
  * Smallest string strictly greater than every string that starts with `prefix`,
  * used as the exclusive upper bound of a literal prefix range scan. Increments
@@ -191,37 +220,454 @@ export function createRunStore({ run }: TanstackAiDelegates): RunStore {
   return store
 }
 
+function parseStoredJson(value: string, label: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch (error) {
+    throw new InterruptStoreCorruptionError(
+      `Stored ${label} is not valid JSON.`,
+      { cause: error },
+    )
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function hasOptionalString(
+  value: Record<string, unknown>,
+  key: string,
+): boolean {
+  return value[key] === undefined || typeof value[key] === 'string'
+}
+
+function isInterruptBinding(value: unknown): value is InterruptBinding {
+  if (
+    !isRecord(value) ||
+    typeof value.kind !== 'string' ||
+    typeof value.interruptId !== 'string' ||
+    typeof value.interruptedRunId !== 'string' ||
+    typeof value.generation !== 'number' ||
+    !Number.isInteger(value.generation) ||
+    typeof value.responseSchemaHash !== 'string' ||
+    !hasOptionalString(value, 'expiresAt')
+  ) {
+    return false
+  }
+  if (value.kind === 'generic') return true
+  if (value.kind === 'client-tool-execution') {
+    return (
+      typeof value.toolName === 'string' &&
+      typeof value.toolCallId === 'string' &&
+      typeof value.outputSchemaHash === 'string'
+    )
+  }
+  if (value.kind === 'tool-approval') {
+    return (
+      typeof value.toolName === 'string' &&
+      typeof value.toolCallId === 'string' &&
+      'originalArgs' in value &&
+      typeof value.inputSchemaHash === 'string' &&
+      typeof value.approvalSchemaHash === 'string'
+    )
+  }
+  return false
+}
+
+function decodeBinding(row: InterruptRow): InterruptBinding {
+  const fallback: InterruptBinding = {
+    kind: 'generic',
+    interruptId: row.interruptId,
+    interruptedRunId: row.runId,
+    generation: row.generation,
+    responseSchemaHash: row.schemaHash ?? 'legacy:unknown',
+  }
+  const parsed =
+    row.bindingJson === null
+      ? fallback
+      : parseStoredJson(row.bindingJson, `binding for ${row.interruptId}`)
+  if (!isInterruptBinding(parsed)) {
+    throw new InterruptStoreCorruptionError(
+      `Stored binding for interrupt ${row.interruptId} is malformed.`,
+    )
+  }
+  if (
+    parsed.interruptId !== row.interruptId ||
+    parsed.interruptedRunId !== row.runId ||
+    parsed.generation !== row.generation
+  ) {
+    throw new InterruptStoreCorruptionError(
+      `Stored binding correlation does not match interrupt ${row.interruptId}.`,
+    )
+  }
+  if (row.schemaHash !== null && parsed.responseSchemaHash !== row.schemaHash) {
+    throw new InterruptStoreCorruptionError(
+      `Stored schema hash does not match interrupt ${row.interruptId}.`,
+    )
+  }
+  return parsed
+}
+
+function decodeInterruptPayload(row: InterruptRow): unknown {
+  const payload = parseStoredJson(
+    row.payloadJson,
+    `payload for ${row.interruptId}`,
+  )
+  if (isRecord(payload) && 'id' in payload && payload.id !== row.interruptId) {
+    throw new InterruptStoreCorruptionError(
+      `Stored payload ID does not match interrupt ${row.interruptId}.`,
+    )
+  }
+  if (
+    row.generation > 0 &&
+    (!isRecord(payload) || payload.id !== row.interruptId)
+  ) {
+    throw new InterruptStoreCorruptionError(
+      `Stored native interrupt ${row.interruptId} has no matching payload ID.`,
+    )
+  }
+  return payload
+}
+
 function mapInterrupt(row: InterruptRow): InterruptRecord {
-  return {
+  if (
+    !Number.isInteger(row.generation) ||
+    row.generation < 0 ||
+    (row.status !== 'pending' &&
+      row.status !== 'resolved' &&
+      row.status !== 'cancelled')
+  ) {
+    throw new InterruptStoreCorruptionError(
+      `Stored interrupt ${row.interruptId} has invalid lifecycle fields.`,
+    )
+  }
+  const record: InterruptRecord = {
     interruptId: row.interruptId,
     runId: row.runId,
     threadId: row.threadId,
-    status: row.status as InterruptRecord['status'],
+    generation: row.generation,
+    status: row.status,
     requestedAt: Number(row.requestedAt),
     ...(row.resolvedAt != null ? { resolvedAt: Number(row.resolvedAt) } : {}),
-    payload: JSON.parse(row.payloadJson) as Record<string, unknown>,
+    payload: decodeInterruptPayload(row),
+    binding: decodeBinding(row),
     ...(row.responseJson != null
-      ? { response: JSON.parse(row.responseJson) as unknown }
+      ? {
+          response: parseStoredJson(
+            row.responseJson,
+            `response for ${row.interruptId}`,
+          ),
+        }
       : {}),
   }
+  return cloneAndDeepFreezeJson(record)
+}
+
+function isResumeItem(value: unknown): value is RunAgentResumeItem {
+  return (
+    isRecord(value) &&
+    typeof value.interruptId === 'string' &&
+    (value.status === 'resolved' || value.status === 'cancelled')
+  )
+}
+
+function decodeStringArray(
+  value: string,
+  label: string,
+): ReadonlyArray<string> {
+  const parsed = parseStoredJson(value, label)
+  if (
+    !Array.isArray(parsed) ||
+    !parsed.every((item): item is string => typeof item === 'string') ||
+    !hasExactInterruptIds(parsed, parsed)
+  ) {
+    throw new InterruptStoreCorruptionError(
+      `Stored ${label} is not an exact set of string IDs.`,
+    )
+  }
+  return cloneAndDeepFreezeJson(parsed)
 }
 
-export function createInterruptStore({
-  interrupt,
-}: TanstackAiDelegates): InterruptStore {
+function decodeInterruptBatch(
+  row: InterruptBatchRow,
+  expectedInterruptedRunId: string,
+): InterruptBatchRecord {
+  if (
+    row.interruptedRunId !== expectedInterruptedRunId ||
+    !Number.isInteger(row.generation) ||
+    row.generation < 0
+  ) {
+    throw new InterruptStoreCorruptionError(
+      `Stored interrupt batch correlation does not match ${expectedInterruptedRunId}.`,
+    )
+  }
+  const expectedInterruptIds = decodeStringArray(
+    row.expectedInterruptIdsJson,
+    `expected IDs for ${row.interruptedRunId}`,
+  )
+  const resolutions = parseStoredJson(
+    row.resolutionsJson,
+    `resolutions for ${row.interruptedRunId}`,
+  )
+  if (!Array.isArray(resolutions) || !resolutions.every(isResumeItem)) {
+    throw new InterruptStoreCorruptionError(
+      `Stored resolutions for ${row.interruptedRunId} are malformed.`,
+    )
+  }
+  const canonical = canonicalizeInterruptResolutions(resolutions)
+  if (
+    canonical.fingerprint !== row.fingerprint ||
+    canonical.canonicalResolutions !== row.canonicalResolutions ||
+    !hasExactInterruptIds(
+      expectedInterruptIds,
+      canonical.resolutions.map((resolution) => resolution.interruptId),
+    )
+  ) {
+    throw new InterruptStoreCorruptionError(
+      `Stored interrupt batch identity is corrupt for ${row.interruptedRunId}.`,
+    )
+  }
+  return cloneAndDeepFreezeJson({
+    threadId: row.threadId,
+    interruptedRunId: row.interruptedRunId,
+    generation: row.generation,
+    expectedInterruptIds,
+    fingerprint: row.fingerprint,
+    canonicalResolutions: row.canonicalResolutions,
+    resolutions: canonical.resolutions,
+    continuationRunId: row.continuationRunId,
+    committedAt: Number(row.committedAt),
+  })
+}
+
+function legacyBindingForRow(row: InterruptRow): InterruptBinding {
   return {
+    kind: 'generic',
+    interruptId: row.interruptId,
+    interruptedRunId: row.runId,
+    generation: row.generation,
+    responseSchemaHash: row.schemaHash ?? 'legacy:unknown',
+  }
+}
+
+async function upgradeLegacyPendingRows(
+  transaction: InterruptTransactionDelegates,
+  rows: ReadonlyArray<InterruptRow>,
+): Promise<ReadonlyArray<InterruptRow>> {
+  const upgraded: Array<InterruptRow> = []
+  for (const row of rows) {
+    if (row.status !== 'pending' || row.bindingJson !== null) {
+      upgraded.push(row)
+      continue
+    }
+    const binding = legacyBindingForRow(row)
+    const bindingJson = canonicalInterruptJson(binding)
+    const result = await transaction.interrupt.updateMany({
+      where: {
+        interruptId: row.interruptId,
+        runId: row.runId,
+        generation: row.generation,
+        status: 'pending',
+        bindingJson: null,
+      },
+      data: {
+        bindingJson,
+        schemaHash: binding.responseSchemaHash,
+      },
+    })
+    if (result.count !== 1) {
+      throw new Error(`Pending interrupt changed: ${row.interruptId}`)
+    }
+    upgraded.push({
+      ...row,
+      bindingJson,
+      schemaHash: binding.responseSchemaHash,
+    })
+  }
+  return upgraded
+}
+
+async function loadRowsForRun(
+  transaction: InterruptTransactionDelegates,
+  interruptedRunId: string,
+): Promise<ReadonlyArray<InterruptRecord>> {
+  const rows = await transaction.interrupt.findMany({
+    where: { runId: interruptedRunId },
+    orderBy: [{ requestedAt: 'asc' }, { interruptId: 'asc' }],
+  })
+  const upgraded = await upgradeLegacyPendingRows(transaction, rows)
+  return upgraded.map(mapInterrupt)
+}
+
+function validateBatchRowCorrelation(
+  batch: InterruptBatchRecord,
+  rows: ReadonlyArray<InterruptRecord>,
+): void {
+  if (
+    !hasExactInterruptIds(
+      batch.expectedInterruptIds,
+      rows.map((row) => row.interruptId),
+    ) ||
+    rows.some(
+      (row) =>
+        row.runId !== batch.interruptedRunId ||
+        row.threadId !== batch.threadId ||
+        row.generation !== batch.generation ||
+        row.status === 'pending',
+    )
+  ) {
+    throw new InterruptStoreCorruptionError(
+      `Stored interrupt batch correlation is corrupt for ${batch.interruptedRunId}.`,
+    )
+  }
+}
+
+async function recoveryInTransaction(
+  transaction: InterruptTransactionDelegates,
+  input: InterruptRecoveryQuery,
+  now: number,
+): Promise<InterruptRecoveryStateV1> {
+  const rows = await loadRowsForRun(transaction, input.interruptedRunId)
+  const batchRow = await transaction.interruptBatch.findUnique({
+    where: { interruptedRunId: input.interruptedRunId },
+  })
+  const batch = batchRow
+    ? decodeInterruptBatch(batchRow, input.interruptedRunId)
+    : null
+  if (batch?.threadId === input.threadId) {
+    validateBatchRowCorrelation(batch, rows)
+  }
+  return projectInterruptRecovery({
+    query: input,
+    rows: rows.filter((row) => row.threadId === input.threadId),
+    batch: batch?.threadId === input.threadId ? batch : null,
+    now,
+    includeResolutions: true,
+  })
+}
+
+async function winnerOutcome(
+  transaction: InterruptTransactionDelegates,
+  input: CommitInterruptResolutionsInput,
+  winner: InterruptBatchRecord,
+  now: number,
+): Promise<InterruptCommitResult> {
+  const authoritativeState = await recoveryInTransaction(
+    transaction,
+    {
+      threadId: input.threadId,
+      interruptedRunId: input.interruptedRunId,
+      knownGeneration: input.expectedGeneration,
+    },
+    now,
+  )
+  if (
+    winner.threadId === input.threadId &&
+    winner.generation === input.expectedGeneration &&
+    hasExactInterruptIds(
+      winner.expectedInterruptIds,
+      input.expectedInterruptIds,
+    ) &&
+    winner.fingerprint === input.fingerprint &&
+    winner.canonicalResolutions === input.canonicalResolutions
+  ) {
+    return {
+      status: 'replayed',
+      continuationRunId: winner.continuationRunId,
+    }
+  }
+  return {
+    status: 'conflict',
+    authoritativeState,
+  }
+}
+
+function errorCode(error: unknown): string | undefined {
+  return isRecord(error) && typeof error.code === 'string'
+    ? error.code
+    : undefined
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function isReloadableCommitRace(error: unknown): boolean {
+  if (errorCode(error) === 'P2002') return true
+  if (!['P1008', 'P2028', 'P2034', undefined].includes(errorCode(error))) {
+    return false
+  }
+  return /database is locked|database is busy|write conflict|deadlock|timed out|transaction.*closed/i.test(
+    errorMessage(error),
+  )
+}
+
+export function createInterruptStore(
+  { interrupt }: TanstackAiDelegates,
+  runTransaction: RunInterruptTransaction,
+  clock: () => number = Date.now,
+): InterruptStore {
+  async function readRows(where: {
+    threadId?: string
+    runId?: string
+    status?: string
+  }): Promise<Array<InterruptRecord>> {
+    return runTransaction(async (transaction) => {
+      const rows = await transaction.interrupt.findMany({
+        where,
+        orderBy: [{ requestedAt: 'asc' }, { interruptId: 'asc' }],
+      })
+      const upgraded = await upgradeLegacyPendingRows(transaction, rows)
+      return upgraded.map(mapInterrupt)
+    })
+  }
+
+  async function reloadWinner(
+    input: CommitInterruptResolutionsInput,
+  ): Promise<InterruptCommitResult | null> {
+    return runTransaction(async (transaction) => {
+      const row = await transaction.interruptBatch.findUnique({
+        where: { interruptedRunId: input.interruptedRunId },
+      })
+      if (!row) return null
+      return winnerOutcome(
+        transaction,
+        input,
+        decodeInterruptBatch(row, input.interruptedRunId),
+        clock(),
+      )
+    })
+  }
+
+  const store: InterruptStore = {
     async create(record) {
+      const generation = record.generation ?? 0
+      const binding =
+        record.binding ??
+        ({
+          kind: 'generic',
+          interruptId: record.interruptId,
+          interruptedRunId: record.runId,
+          generation,
+          responseSchemaHash: 'legacy:unknown',
+        } as const)
       await interrupt.upsert({
         where: { interruptId: record.interruptId },
         create: {
           interruptId: record.interruptId,
           runId: record.runId,
           threadId: record.threadId,
+          generation,
           status: record.status,
           requestedAt: BigInt(record.requestedAt),
-          payloadJson: JSON.stringify(record.payload),
+          payloadJson: canonicalInterruptJson(record.payload),
+          bindingJson: canonicalInterruptJson(binding),
+          schemaHash: binding.responseSchemaHash,
           responseJson:
-            record.response == null ? null : JSON.stringify(record.response),
+            record.response === undefined
+              ? null
+              : canonicalInterruptJson(record.response),
         },
         update: {},
       })
@@ -231,50 +677,274 @@ export function createInterruptStore({
         where: { interruptId },
         data: {
           status: 'resolved',
-          resolvedAt: BigInt(Date.now()),
-          responseJson: response == null ? null : JSON.stringify(response),
+          resolvedAt: BigInt(clock()),
+          ...(response === undefined
+            ? {}
+            : { responseJson: canonicalInterruptJson(response) }),
         },
       })
     },
     async cancel(interruptId) {
       await interrupt.updateMany({
         where: { interruptId },
-        data: { status: 'cancelled', resolvedAt: BigInt(Date.now()) },
+        data: { status: 'cancelled', resolvedAt: BigInt(clock()) },
       })
     },
     async get(interruptId) {
-      const row = await interrupt.findUnique({ where: { interruptId } })
-      return row ? mapInterrupt(row) : null
+      return runTransaction(async (transaction) => {
+        const row = await transaction.interrupt.findUnique({
+          where: { interruptId },
+        })
+        if (!row) return null
+        const [upgraded] = await upgradeLegacyPendingRows(transaction, [row])
+        return upgraded ? mapInterrupt(upgraded) : null
+      })
     },
     async list(threadId) {
-      const rows = await interrupt.findMany({
-        where: { threadId },
-        orderBy: { requestedAt: 'asc' },
-      })
-      return rows.map(mapInterrupt)
+      return readRows({ threadId })
     },
     async listPending(threadId) {
-      const rows = await interrupt.findMany({
-        where: { threadId, status: 'pending' },
-        orderBy: { requestedAt: 'asc' },
-      })
-      return rows.map(mapInterrupt)
+      return readRows({ threadId, status: 'pending' })
     },
     async listByRun(runId) {
-      const rows = await interrupt.findMany({
-        where: { runId },
-        orderBy: { requestedAt: 'asc' },
-      })
-      return rows.map(mapInterrupt)
+      return readRows({ runId })
     },
     async listPendingByRun(runId) {
-      const rows = await interrupt.findMany({
-        where: { runId, status: 'pending' },
-        orderBy: { requestedAt: 'asc' },
+      return readRows({ runId, status: 'pending' })
+    },
+    async openInterruptBatch(input) {
+      const descriptors = cloneAndDeepFreezeJson(input.descriptors)
+      const bindings = cloneAndDeepFreezeJson(input.bindings)
+      const descriptorIds = descriptors.map((descriptor) => descriptor.id)
+      const bindingIds = bindings.map((binding) => binding.interruptId)
+      if (
+        descriptorIds.length === 0 ||
+        !hasExactInterruptIds(descriptorIds, bindingIds)
+      ) {
+        throw new TypeError(
+          'Interrupt descriptors and bindings must contain the same exact nonempty IDs.',
+        )
+      }
+
+      return runTransaction(async (transaction) => {
+        const committed = await transaction.interruptBatch.findUnique({
+          where: { interruptedRunId: input.interruptedRunId },
+        })
+        if (committed) {
+          decodeInterruptBatch(committed, input.interruptedRunId)
+          throw new Error('Cannot reopen a committed interrupt batch.')
+        }
+
+        const existing = await loadRowsForRun(
+          transaction,
+          input.interruptedRunId,
+        )
+        if (existing.length > 0) {
+          const generation = existing[0]?.generation
+          const existingDescriptors = [...existing]
+            .sort((left, right) =>
+              left.interruptId.localeCompare(right.interruptId),
+            )
+            .map((record) => record.payload)
+          const requestedDescriptors = [...descriptors].sort((left, right) =>
+            left.id.localeCompare(right.id),
+          )
+          const existingBindings = [...existing]
+            .map((record) => record.binding)
+            .sort((left, right) =>
+              left.interruptId.localeCompare(right.interruptId),
+            )
+          const requestedBindings = bindings
+            .map((binding) => ({
+              ...binding,
+              interruptedRunId: input.interruptedRunId,
+              generation,
+            }))
+            .sort((left, right) =>
+              left.interruptId.localeCompare(right.interruptId),
+            )
+          if (
+            generation !== undefined &&
+            hasExactInterruptIds(
+              descriptorIds,
+              existing.map((record) => record.interruptId),
+            ) &&
+            canonicalInterruptJson(existingDescriptors) ===
+              canonicalInterruptJson(requestedDescriptors) &&
+            canonicalInterruptJson(existingBindings) ===
+              canonicalInterruptJson(requestedBindings) &&
+            existing.every(
+              (record) =>
+                record.status === 'pending' &&
+                record.threadId === input.threadId &&
+                record.generation === generation,
+            )
+          ) {
+            return { generation, descriptors }
+          }
+          throw new Error('An incompatible interrupt batch is already open.')
+        }
+
+        const generation = 1
+        const bindingsById = new Map(
+          bindings.map((binding) => [binding.interruptId, binding]),
+        )
+        const requestedAt = BigInt(clock())
+        for (const descriptor of descriptors) {
+          const unopened = bindingsById.get(descriptor.id)
+          if (!unopened) {
+            throw new Error(`Missing binding for interrupt: ${descriptor.id}`)
+          }
+          const binding = cloneAndDeepFreezeJson({
+            ...unopened,
+            interruptedRunId: input.interruptedRunId,
+            generation,
+          })
+          await transaction.interrupt.create({
+            data: {
+              interruptId: descriptor.id,
+              runId: input.interruptedRunId,
+              threadId: input.threadId,
+              generation,
+              status: 'pending',
+              requestedAt,
+              payloadJson: canonicalInterruptJson(descriptor),
+              bindingJson: canonicalInterruptJson(binding),
+              schemaHash: binding.responseSchemaHash,
+            },
+          })
+        }
+        return { generation, descriptors }
       })
-      return rows.map(mapInterrupt)
+    },
+    async commitInterruptResolutions(input) {
+      const candidate = canonicalizeInterruptResolutions(input.resolutions)
+      if (
+        candidate.fingerprint !== input.fingerprint ||
+        candidate.canonicalResolutions !== input.canonicalResolutions
+      ) {
+        throw new TypeError(
+          'Interrupt batch identity does not match its resolutions.',
+        )
+      }
+
+      try {
+        return await runTransaction(async (transaction) => {
+          const winnerRow = await transaction.interruptBatch.findUnique({
+            where: { interruptedRunId: input.interruptedRunId },
+          })
+          if (winnerRow) {
+            return winnerOutcome(
+              transaction,
+              input,
+              decodeInterruptBatch(winnerRow, input.interruptedRunId),
+              clock(),
+            )
+          }
+
+          const rows = await loadRowsForRun(transaction, input.interruptedRunId)
+          const pending = rows.filter((row) => row.status === 'pending')
+          const resolutionIds = candidate.resolutions.map(
+            (resolution) => resolution.interruptId,
+          )
+          const now = clock()
+          if (
+            !hasExactInterruptIds(
+              input.expectedInterruptIds,
+              pending.map((record) => record.interruptId),
+            ) ||
+            !hasExactInterruptIds(input.expectedInterruptIds, resolutionIds) ||
+            pending.some((record) => record.threadId !== input.threadId) ||
+            pending.some(
+              (record) => record.generation !== input.expectedGeneration,
+            ) ||
+            pending.some(
+              (record) =>
+                record.binding.expiresAt !== undefined &&
+                Date.parse(record.binding.expiresAt) <= now,
+            )
+          ) {
+            return {
+              status: 'conflict',
+              authoritativeState: await recoveryInTransaction(
+                transaction,
+                {
+                  threadId: input.threadId,
+                  interruptedRunId: input.interruptedRunId,
+                  knownGeneration: input.expectedGeneration,
+                },
+                now,
+              ),
+            }
+          }
+
+          await transaction.interruptBatch.create({
+            data: {
+              interruptedRunId: input.interruptedRunId,
+              threadId: input.threadId,
+              generation: input.expectedGeneration,
+              expectedInterruptIdsJson: canonicalInterruptJson(
+                [...input.expectedInterruptIds].sort(),
+              ),
+              fingerprint: candidate.fingerprint,
+              canonicalResolutions: candidate.canonicalResolutions,
+              resolutionsJson: candidate.canonicalResolutions,
+              continuationRunId: input.continuationRunId,
+              committedAt: BigInt(now),
+            },
+          })
+
+          for (const resolution of candidate.resolutions) {
+            const transitioned = await transaction.interrupt.updateMany({
+              where: {
+                interruptId: resolution.interruptId,
+                runId: input.interruptedRunId,
+                threadId: input.threadId,
+                generation: input.expectedGeneration,
+                status: 'pending',
+              },
+              data: {
+                status:
+                  resolution.status === 'cancelled' ? 'cancelled' : 'resolved',
+                responseJson: canonicalInterruptJson(resolution),
+                resolvedAt: BigInt(now),
+              },
+            })
+            if (transitioned.count !== 1) {
+              throw new Error(
+                `Pending interrupt changed: ${resolution.interruptId}`,
+              )
+            }
+          }
+
+          return {
+            status: 'committed',
+            continuationRunId: input.continuationRunId,
+          }
+        })
+      } catch (error) {
+        if (!isReloadableCommitRace(error)) throw error
+        for (let attempt = 0; attempt < 4; attempt++) {
+          try {
+            const winner = await reloadWinner(input)
+            if (winner) return winner
+          } catch (reloadError) {
+            if (!isReloadableCommitRace(reloadError)) throw reloadError
+          }
+          await new Promise<void>((resolve) => {
+            setTimeout(resolve, 10 * (attempt + 1))
+          })
+        }
+        throw error
+      }
+    },
+    async getInterruptRecoveryState(input) {
+      return runTransaction((transaction) =>
+        recoveryInTransaction(transaction, input, clock()),
+      )
     },
   }
+  return store
 }
 
 export function createMetadataStore({
diff --git a/packages/ai-persistence-prisma/tests/api-types.test-d.ts b/packages/ai-persistence-prisma/tests/api-types.test-d.ts
index d898ff4a8..fea67c918 100644
--- a/packages/ai-persistence-prisma/tests/api-types.test-d.ts
+++ b/packages/ai-persistence-prisma/tests/api-types.test-d.ts
@@ -13,6 +13,7 @@ import { prismaPersistence } from '../src/index'
 import type {
   ArtifactDelegate,
   BlobDelegate,
+  InterruptBatchDelegate,
   InterruptDelegate,
   MessageDelegate,
   MetadataDelegate,
@@ -28,6 +29,7 @@ const persistence = prismaPersistence(prisma)
 expectTypeOf(prisma.message).toExtend<MessageDelegate>()
 expectTypeOf(prisma.run).toExtend<RunDelegate>()
 expectTypeOf(prisma.interrupt).toExtend<InterruptDelegate>()
+expectTypeOf(prisma.interruptBatch).toExtend<InterruptBatchDelegate>()
 expectTypeOf(prisma.metadata).toExtend<MetadataDelegate>()
 expectTypeOf(prisma.artifact).toExtend<ArtifactDelegate>()
 expectTypeOf(prisma.blob).toExtend<BlobDelegate>()
@@ -40,6 +42,15 @@ expectTypeOf(mapped.stores).toEqualTypeOf<typeof persistence.stores>()
 expectTypeOf(persistence.stores.messages).toEqualTypeOf<MessageStore>()
 expectTypeOf(persistence.stores.runs).toEqualTypeOf<RunStore>()
 expectTypeOf(persistence.stores.interrupts).toEqualTypeOf<InterruptStore>()
+expectTypeOf(persistence.stores.interrupts.openInterruptBatch).toEqualTypeOf<
+  InterruptStore['openInterruptBatch']
+>()
+expectTypeOf(
+  persistence.stores.interrupts.commitInterruptResolutions,
+).toEqualTypeOf<InterruptStore['commitInterruptResolutions']>()
+expectTypeOf(
+  persistence.stores.interrupts.getInterruptRecoveryState,
+).toEqualTypeOf<InterruptStore['getInterruptRecoveryState']>()
 expectTypeOf(persistence.stores.metadata).toEqualTypeOf<MetadataStore>()
 expectTypeOf(persistence.stores.artifacts).toEqualTypeOf<ArtifactStore>()
 expectTypeOf(persistence.stores.blobs).toEqualTypeOf<BlobStore>()
diff --git a/packages/ai-persistence-prisma/tests/model-mapping.test.ts b/packages/ai-persistence-prisma/tests/model-mapping.test.ts
index a4b2fee02..3210bbc56 100644
--- a/packages/ai-persistence-prisma/tests/model-mapping.test.ts
+++ b/packages/ai-persistence-prisma/tests/model-mapping.test.ts
@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { DatabaseSync } from 'node:sqlite'
 import { afterAll, describe, expect, it } from 'vitest'
-import { PrismaClient } from '@prisma/client'
+import { PrismaClient, type Prisma } from '@prisma/client'
 import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
 import { PrismaModelError, prismaPersistence } from '../src/index'
 
@@ -29,12 +29,26 @@ const sqliteTestSchema = `
     interrupt_id TEXT NOT NULL PRIMARY KEY,
     run_id TEXT NOT NULL,
     thread_id TEXT NOT NULL,
+    generation INTEGER NOT NULL DEFAULT 0,
     status TEXT NOT NULL,
     requested_at BIGINT NOT NULL,
     resolved_at BIGINT,
     payload_json TEXT NOT NULL,
+    binding_json TEXT,
+    schema_hash TEXT,
     response_json TEXT
   );
+  CREATE TABLE interrupt_batches (
+    interrupted_run_id TEXT NOT NULL PRIMARY KEY,
+    thread_id TEXT NOT NULL,
+    generation INTEGER NOT NULL,
+    expected_interrupt_ids_json TEXT NOT NULL,
+    fingerprint TEXT NOT NULL,
+    canonical_resolutions TEXT NOT NULL,
+    resolutions_json TEXT NOT NULL,
+    continuation_run_id TEXT NOT NULL,
+    committed_at BIGINT NOT NULL
+  );
   CREATE TABLE metadata (
     scope TEXT NOT NULL,
     key TEXT NOT NULL,
@@ -88,13 +102,20 @@ async function makeTestClient(): Promise<PrismaClient> {
  */
 async function makeRenamedClient(): Promise<PrismaClient> {
   const prisma = await makeTestClient()
+  const aliases = (client: PrismaClient | Prisma.TransactionClient) => ({
+    chatMessage: client.message,
+    chatRun: client.run,
+    chatInterrupt: client.interrupt,
+    chatInterruptBatch: client.interruptBatch,
+    chatMetadata: client.metadata,
+    chatArtifact: client.artifact,
+    chatBlob: client.blob,
+  })
   const renamed = {
-    chatMessage: prisma.message,
-    chatRun: prisma.run,
-    chatInterrupt: prisma.interrupt,
-    chatMetadata: prisma.metadata,
-    chatArtifact: prisma.artifact,
-    chatBlob: prisma.blob,
+    ...aliases(prisma),
+    $transaction: <T>(
+      operation: (transaction: ReturnType<typeof aliases>) => Promise<T>,
+    ) => prisma.$transaction((transaction) => operation(aliases(transaction))),
   }
   return renamed as unknown as PrismaClient
 }
@@ -103,6 +124,7 @@ const renamedModels = {
   messages: 'chatMessage',
   runs: 'chatRun',
   interrupts: 'chatInterrupt',
+  interruptBatches: 'chatInterruptBatch',
   metadata: 'chatMetadata',
   artifacts: 'chatArtifact',
   blobs: 'chatBlob',
@@ -138,7 +160,7 @@ describe('prismaPersistence model mapping', () => {
     const prisma = await makeRenamedClient()
     // Default names resolve nothing on a fully renamed client.
     expect(() => prismaPersistence(prisma)).toThrow(
-      /messages[\s\S]*runs[\s\S]*interrupts[\s\S]*metadata[\s\S]*artifacts[\s\S]*blobs/,
+      /messages[\s\S]*runs[\s\S]*interrupts[\s\S]*interruptBatches[\s\S]*metadata[\s\S]*artifacts[\s\S]*blobs/,
     )
   })
 
diff --git a/packages/ai-persistence-prisma/tests/models-cli.test.ts b/packages/ai-persistence-prisma/tests/models-cli.test.ts
index 36a997568..ea07ebfb4 100644
--- a/packages/ai-persistence-prisma/tests/models-cli.test.ts
+++ b/packages/ai-persistence-prisma/tests/models-cli.test.ts
@@ -30,6 +30,8 @@ describe('Prisma models CLI', () => {
       },
     })
     expect(output).toBe(`${prismaModels.trimEnd()}\n`)
+    expect(output).toContain('model InterruptBatch')
+    expect(output).toContain('bindingJson')
   })
 
   it('copies the fragment without overwriting divergent files by default', async () => {
diff --git a/packages/ai-persistence-prisma/tests/models.test.ts b/packages/ai-persistence-prisma/tests/models.test.ts
index 06844786d..d81058e3b 100644
--- a/packages/ai-persistence-prisma/tests/models.test.ts
+++ b/packages/ai-persistence-prisma/tests/models.test.ts
@@ -29,7 +29,17 @@ describe('Prisma models asset', () => {
   it('is a models-only fragment with no provider or client generator', () => {
     expect(prismaModelsFilename).toBe('tanstack-ai.prisma')
     expect(prismaModels).toContain('model Message')
+    expect(prismaModels).toContain('model InterruptBatch')
     expect(prismaModels).toContain('model Blob')
+    expect(prismaModels).toMatch(/generation\s+Int\s+@default\(0\)/)
+    expect(prismaModels).toMatch(
+      /bindingJson\s+String\?\s+@map\("binding_json"\)/,
+    )
+    expect(prismaModels).toMatch(
+      /schemaHash\s+String\?\s+@map\("schema_hash"\)/,
+    )
+    expect(prismaModels).toContain('@@index([threadId, status])')
+    expect(prismaModels).toContain('@@index([runId, generation, status])')
     expect(prismaModels).not.toMatch(/\bgenerator\s+\w+\s*{/)
     expect(prismaModels).not.toMatch(/\bdatasource\s+\w+\s*{/)
   })
diff --git a/packages/ai-persistence-prisma/tests/prisma.conformance.test.ts b/packages/ai-persistence-prisma/tests/prisma.conformance.test.ts
index a73190329..3a6727f6e 100644
--- a/packages/ai-persistence-prisma/tests/prisma.conformance.test.ts
+++ b/packages/ai-persistence-prisma/tests/prisma.conformance.test.ts
@@ -3,10 +3,19 @@ import { mkdtempSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { DatabaseSync } from 'node:sqlite'
-import { afterAll } from 'vitest'
+import { afterAll, describe, expect, it } from 'vitest'
 import { PrismaClient } from '@prisma/client'
-import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { canonicalizeInterruptResolutions } from '@tanstack/ai'
+import {
+  runInterruptStoreConformance,
+  runPersistenceConformance,
+  type InterruptConformanceHarness,
+} from '@tanstack/ai-persistence/testkit'
 import { prismaPersistence } from '../src/index'
+import { resolveDelegates } from '../src/model-contract'
+import { createInterruptStore } from '../src/stores'
+import type { RunInterruptTransaction } from '../src/stores'
+import type { InterruptStore } from '@tanstack/ai-persistence'
 
 const clients: Array<PrismaClient> = []
 const temporaryDirectories: Array<string> = []
@@ -29,12 +38,32 @@ const sqliteTestSchema = `
     interrupt_id TEXT NOT NULL PRIMARY KEY,
     run_id TEXT NOT NULL,
     thread_id TEXT NOT NULL,
+    generation INTEGER NOT NULL DEFAULT 0,
     status TEXT NOT NULL,
     requested_at BIGINT NOT NULL,
     resolved_at BIGINT,
     payload_json TEXT NOT NULL,
+    binding_json TEXT,
+    schema_hash TEXT,
     response_json TEXT
   );
+  CREATE INDEX interrupts_thread_status_idx
+    ON interrupts(thread_id, status);
+  CREATE INDEX interrupts_run_generation_status_idx
+    ON interrupts(run_id, generation, status);
+  CREATE TABLE interrupt_batches (
+    interrupted_run_id TEXT NOT NULL PRIMARY KEY,
+    thread_id TEXT NOT NULL,
+    generation INTEGER NOT NULL,
+    expected_interrupt_ids_json TEXT NOT NULL,
+    fingerprint TEXT NOT NULL,
+    canonical_resolutions TEXT NOT NULL,
+    resolutions_json TEXT NOT NULL,
+    continuation_run_id TEXT NOT NULL,
+    committed_at BIGINT NOT NULL
+  );
+  CREATE INDEX interrupt_batches_thread_idx
+    ON interrupt_batches(thread_id);
   CREATE TABLE metadata (
     scope TEXT NOT NULL,
     key TEXT NOT NULL,
@@ -85,6 +114,52 @@ async function makeTestClient(): Promise<PrismaClient> {
   return prisma
 }
 
+async function makeSharedTestClients(): Promise<{
+  clients: readonly [PrismaClient, PrismaClient]
+  dbPath: string
+}> {
+  const dir = mkdtempSync(join(tmpdir(), 'tanstack-ai-prisma-interrupts-'))
+  temporaryDirectories.push(dir)
+  const dbPath = join(dir, 'state.db').replace(/\\/g, '/')
+  initializeSqliteTestDatabase(dbPath)
+  const first = new PrismaClient({
+    datasources: { db: { url: `file:${dbPath}` } },
+  })
+  const second = new PrismaClient({
+    datasources: { db: { url: `file:${dbPath}` } },
+  })
+  clients.push(first, second)
+  return { clients: [first, second], dbPath }
+}
+
+function createTestInterruptStore(
+  prisma: PrismaClient,
+  clock: () => number,
+): InterruptStore {
+  const delegates = resolveDelegates(prisma)
+  const runTransaction: RunInterruptTransaction = (operation) =>
+    prisma.$transaction((transaction) =>
+      operation(resolveDelegates(transaction)),
+    )
+  return createInterruptStore(delegates, runTransaction, clock)
+}
+
+function withTransitionFailure(dbPath: string, interruptId: string): void {
+  const database = new DatabaseSync(dbPath)
+  try {
+    database.exec(`
+      CREATE TRIGGER fail_next_interrupt_transition
+      BEFORE UPDATE ON interrupts
+      WHEN OLD.status = 'pending' AND NEW.interrupt_id = '${interruptId}'
+      BEGIN
+        SELECT RAISE(ABORT, 'Injected transition failure');
+      END;
+    `)
+  } finally {
+    database.close()
+  }
+}
+
 afterAll(async () => {
   await Promise.all(clients.map((client) => client.$disconnect()))
   await Promise.all(
@@ -97,3 +172,234 @@ afterAll(async () => {
 runPersistenceConformance('prisma', async () =>
   prismaPersistence(await makeTestClient()),
 )
+
+runInterruptStoreConformance(async (): Promise<InterruptConformanceHarness> => {
+  let now = Date.parse('2026-07-13T10:00:00.000Z')
+  const shared = await makeSharedTestClients()
+  const first = createTestInterruptStore(shared.clients[0], () => now)
+  const second = createTestInterruptStore(shared.clients[1], () => now)
+  let commitCount = 0
+  const store: InterruptStore = {
+    create: (record) => first.create(record),
+    resolve: (interruptId, response) => first.resolve(interruptId, response),
+    cancel: (interruptId) => first.cancel(interruptId),
+    get: (interruptId) => first.get(interruptId),
+    list: (threadId) => first.list(threadId),
+    listPending: (threadId) => first.listPending(threadId),
+    listByRun: (runId) => first.listByRun(runId),
+    listPendingByRun: (runId) => first.listPendingByRun(runId),
+    openInterruptBatch: (input) => first.openInterruptBatch(input),
+    commitInterruptResolutions: (input) => {
+      const target = commitCount++ % 2 === 0 ? first : second
+      return target.commitInterruptResolutions(input)
+    },
+    getInterruptRecoveryState: (input) =>
+      first.getInterruptRecoveryState(input),
+  }
+
+  return {
+    getStore: () => store,
+    advanceBy: (milliseconds) => {
+      now += milliseconds
+    },
+    inspect: async (interruptedRunId) => {
+      const database = new DatabaseSync(shared.dbPath, { readOnly: true })
+      try {
+        const statuses = database
+          .prepare(
+            'SELECT status FROM interrupts WHERE run_id = ? ORDER BY interrupt_id',
+          )
+          .all(interruptedRunId)
+          .map((row) => {
+            if (typeof row.status !== 'string') {
+              throw new TypeError('Expected a string interrupt status.')
+            }
+            return row.status
+          })
+        const batch = database
+          .prepare(
+            'SELECT COUNT(*) AS count FROM interrupt_batches WHERE interrupted_run_id = ?',
+          )
+          .get(interruptedRunId)
+        if (typeof batch?.count !== 'number') {
+          throw new TypeError('Expected a numeric interrupt batch count.')
+        }
+        return { statuses, batchCount: batch.count }
+      } finally {
+        database.close()
+      }
+    },
+    failTransitionOnce: (interruptId) => {
+      withTransitionFailure(shared.dbPath, interruptId)
+    },
+    reopen: async () => {
+      const reopened = new PrismaClient({
+        datasources: { db: { url: `file:${shared.dbPath}` } },
+      })
+      clients.push(reopened)
+      return createTestInterruptStore(reopened, () => now)
+    },
+  }
+})
+
+describe('Prisma interrupt persistence hardening', () => {
+  it('upgrades a pending legacy row to a safe generic binding', async () => {
+    const shared = await makeSharedTestClients()
+    const database = new DatabaseSync(shared.dbPath)
+    try {
+      database
+        .prepare(
+          `INSERT INTO interrupts (
+            interrupt_id, run_id, thread_id, generation, status, requested_at,
+            payload_json, binding_json, schema_hash
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL)`,
+        )
+        .run(
+          'legacy-pending',
+          'legacy-run',
+          'legacy-thread',
+          0,
+          'pending',
+          1,
+          JSON.stringify({
+            id: 'legacy-pending',
+            reason: 'confirmation',
+            toolName: 'must-not-be-guessed',
+          }),
+        )
+    } finally {
+      database.close()
+    }
+
+    const store = createTestInterruptStore(shared.clients[0], () => 2)
+    await expect(
+      store.getInterruptRecoveryState({
+        threadId: 'legacy-thread',
+        interruptedRunId: 'legacy-run',
+        knownGeneration: 0,
+      }),
+    ).resolves.toMatchObject({ state: 'pending' })
+
+    const verification = new DatabaseSync(shared.dbPath, { readOnly: true })
+    try {
+      const row = verification
+        .prepare(
+          'SELECT binding_json AS bindingJson, schema_hash AS schemaHash FROM interrupts WHERE interrupt_id = ?',
+        )
+        .get('legacy-pending')
+      expect(row?.schemaHash).toBe('legacy:unknown')
+      expect(JSON.parse(String(row?.bindingJson))).toEqual({
+        generation: 0,
+        interruptId: 'legacy-pending',
+        interruptedRunId: 'legacy-run',
+        kind: 'generic',
+        responseSchemaHash: 'legacy:unknown',
+      })
+    } finally {
+      verification.close()
+    }
+  })
+
+  it('rejects persisted rows whose payload ID does not match the row ID', async () => {
+    const shared = await makeSharedTestClients()
+    const store = createTestInterruptStore(shared.clients[0], () => 1)
+    await store.create({
+      interruptId: 'row-id',
+      runId: 'row-run',
+      threadId: 'row-thread',
+      status: 'pending',
+      requestedAt: 1,
+      payload: { id: 'different-id', reason: 'confirmation' },
+    })
+    await expect(store.get('row-id')).rejects.toThrow(/corrupt|match/i)
+  })
+
+  it('requires replay correlation to match the stored winner exactly', async () => {
+    const shared = await makeSharedTestClients()
+    const store = createTestInterruptStore(shared.clients[0], () => 1)
+    const opened = await store.openInterruptBatch({
+      threadId: 'replay-thread',
+      interruptedRunId: 'replay-run',
+      descriptors: [{ id: 'replay-int', reason: 'confirmation' }],
+      bindings: [
+        {
+          interruptId: 'replay-int',
+          kind: 'generic',
+          responseSchemaHash: 'sha256:replay',
+        },
+      ],
+    })
+    const candidate = canonicalizeInterruptResolutions([
+      { interruptId: 'replay-int', status: 'resolved', payload: true },
+    ])
+    const input = {
+      threadId: 'replay-thread',
+      interruptedRunId: 'replay-run',
+      continuationRunId: 'continuation-winner',
+      expectedGeneration: opened.generation,
+      expectedInterruptIds: ['replay-int'],
+      resolutions: candidate.resolutions,
+      fingerprint: candidate.fingerprint,
+      canonicalResolutions: candidate.canonicalResolutions,
+    }
+    await expect(
+      store.commitInterruptResolutions(input),
+    ).resolves.toMatchObject({ status: 'committed' })
+    await expect(
+      store.commitInterruptResolutions({
+        ...input,
+        continuationRunId: 'continuation-loser',
+        expectedGeneration: opened.generation + 1,
+      }),
+    ).resolves.toMatchObject({ status: 'conflict' })
+  })
+
+  it('rejects a stored batch whose generation diverges from its rows', async () => {
+    const shared = await makeSharedTestClients()
+    const store = createTestInterruptStore(shared.clients[0], () => 1)
+    const opened = await store.openInterruptBatch({
+      threadId: 'corrupt-thread',
+      interruptedRunId: 'corrupt-run',
+      descriptors: [{ id: 'corrupt-int', reason: 'confirmation' }],
+      bindings: [
+        {
+          interruptId: 'corrupt-int',
+          kind: 'generic',
+          responseSchemaHash: 'sha256:corrupt',
+        },
+      ],
+    })
+    const candidate = canonicalizeInterruptResolutions([
+      { interruptId: 'corrupt-int', status: 'cancelled' },
+    ])
+    await store.commitInterruptResolutions({
+      threadId: 'corrupt-thread',
+      interruptedRunId: 'corrupt-run',
+      continuationRunId: 'corrupt-continuation',
+      expectedGeneration: opened.generation,
+      expectedInterruptIds: ['corrupt-int'],
+      resolutions: candidate.resolutions,
+      fingerprint: candidate.fingerprint,
+      canonicalResolutions: candidate.canonicalResolutions,
+    })
+
+    const database = new DatabaseSync(shared.dbPath)
+    try {
+      database
+        .prepare(
+          'UPDATE interrupt_batches SET generation = ? WHERE interrupted_run_id = ?',
+        )
+        .run(opened.generation + 1, 'corrupt-run')
+    } finally {
+      database.close()
+    }
+
+    await expect(
+      store.getInterruptRecoveryState({
+        threadId: 'corrupt-thread',
+        interruptedRunId: 'corrupt-run',
+        knownGeneration: opened.generation,
+      }),
+    ).rejects.toThrow(/corrupt|correlation/i)
+  })
+})
diff --git a/packages/ai-persistence-prisma/vite.config.ts b/packages/ai-persistence-prisma/vite.config.ts
index f56314fed..63f7effc1 100644
--- a/packages/ai-persistence-prisma/vite.config.ts
+++ b/packages/ai-persistence-prisma/vite.config.ts
@@ -7,6 +7,7 @@ const config = defineConfig({
     name: packageJson.name,
     dir: './',
     watch: false,
+    testTimeout: 30_000,
 
     globals: true,
     environment: 'node',
diff --git a/packages/ai-persistence/src/capabilities.ts b/packages/ai-persistence/src/capabilities.ts
index b1673a4ab..324d63247 100644
--- a/packages/ai-persistence/src/capabilities.ts
+++ b/packages/ai-persistence/src/capabilities.ts
@@ -5,18 +5,42 @@
  * can read durable state. `LocksCapability` is re-exported from core
  * (`@tanstack/ai`) — a shared, single-owner token owned with the sandbox layer.
  */
-import { createCapability } from '@tanstack/ai'
-import type { AIPersistence, InterruptStore } from './types'
+import {
+  InterruptPersistenceCapability,
+  createCapability,
+  getInterruptPersistence,
+  provideInterruptPersistence,
+} from '@tanstack/ai'
+import { validatePersistenceStoreKeys } from './types'
+import type { CapabilityContext } from '@tanstack/ai'
+import type { AIPersistence } from './types'
 
 export const PersistenceCapability =
   createCapability<AIPersistence>()('persistence')
 
-export const InterruptsCapability = createCapability<InterruptStore>()(
-  'persistence.interrupts',
-)
+export const [getPersistence, providePersistenceUnchecked] =
+  PersistenceCapability
 
-export const [getPersistence, providePersistence] = PersistenceCapability
-export const [getInterrupts, provideInterrupts] = InterruptsCapability
+export function providePersistence(
+  ctx: CapabilityContext,
+  persistence: AIPersistence,
+): void {
+  validatePersistenceStoreKeys(persistence)
+  providePersistenceUnchecked(ctx, persistence)
+}
+
+export {
+  InterruptPersistenceCapability,
+  getInterruptPersistence,
+  provideInterruptPersistence,
+}
+
+/** @deprecated Use InterruptPersistenceCapability. Removed at 1.0. */
+export const InterruptsCapability = InterruptPersistenceCapability
+/** @deprecated Use getInterruptPersistence. Removed at 1.0. */
+export const getInterrupts = getInterruptPersistence
+/** @deprecated Use provideInterruptPersistence. Removed at 1.0. */
+export const provideInterrupts = provideInterruptPersistence
 
 // Shared, single-owner tokens live in core; re-export so consumers import
 // everything persistence-related from this package.
diff --git a/packages/ai-persistence/src/index.ts b/packages/ai-persistence/src/index.ts
index d8df76e68..7821a6899 100644
--- a/packages/ai-persistence/src/index.ts
+++ b/packages/ai-persistence/src/index.ts
@@ -6,7 +6,9 @@ export type {
   RunRecord,
   RunStore,
   InterruptRecord,
+  InterruptBatchRecord,
   InterruptStore,
+  LegacyInterruptRecordInput,
   MetadataStore,
   ArtifactRecord,
   ArtifactStore,
@@ -24,14 +26,33 @@ export type {
 } from './types'
 
 // Middleware
-export { withChatPersistence, withGenerationPersistence } from './middleware'
+export {
+  InterruptReplaySignal,
+  InterruptResumeValidationError,
+  validateInterruptResumeBatch,
+  withChatPersistence,
+  withGenerationPersistence,
+} from './middleware'
 export type {
   GenerationArtifactDescriptor,
   GenerationArtifactExtractionInput,
   GenerationArtifactNameInput,
+  ValidateInterruptResumeBatchInput,
+  ValidatedInterruptResumeBatch,
   WithPersistenceOptions,
 } from './middleware'
 
+// Authenticated recovery helpers (route registration remains application-owned)
+export {
+  createInterruptRecoveryHandler,
+  getInterruptRecoveryState,
+} from './recovery'
+export type {
+  GetInterruptRecoveryStateOptions,
+  InterruptRecoveryAuthorization,
+  InterruptRecoveryHandlerOptions,
+} from './recovery'
+
 export type {
   PersistedArtifactActivity,
   PersistedArtifactRef,
@@ -42,17 +63,25 @@ export type {
 export { memoryPersistence } from './memory'
 
 // Interrupt controller
-export { createInterruptController } from './interrupts'
+export {
+  createInterruptController,
+  hasExactInterruptIds,
+  InterruptStoreCorruptionError,
+  projectInterruptRecovery,
+} from './interrupts'
 export type { InterruptController } from './interrupts'
 
 // Capabilities (incl. re-exported core Locks token)
 export {
   PersistenceCapability,
   InterruptsCapability,
+  InterruptPersistenceCapability,
   getPersistence,
   providePersistence,
   getInterrupts,
   provideInterrupts,
+  getInterruptPersistence,
+  provideInterruptPersistence,
   LocksCapability,
   getLocks,
   provideLocks,
diff --git a/packages/ai-persistence/src/interrupts.ts b/packages/ai-persistence/src/interrupts.ts
index fdc39c084..9e63557fb 100644
--- a/packages/ai-persistence/src/interrupts.ts
+++ b/packages/ai-persistence/src/interrupts.ts
@@ -1,13 +1,113 @@
-import type { InterruptRecord, InterruptStore } from './types'
+import { cloneAndDeepFreezeJson } from '@tanstack/ai'
+import type {
+  CommitInterruptResolutionsInput,
+  Interrupt,
+  InterruptRecoveryQuery,
+  InterruptRecoveryStateV1,
+  OpenInterruptBatchInput,
+} from '@tanstack/ai'
+import type {
+  InterruptBatchRecord,
+  InterruptRecord,
+  InterruptStore,
+} from './types'
+
+export class InterruptStoreCorruptionError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'InterruptStoreCorruptionError'
+  }
+}
+
+const interruptBindingMetadataKey = 'tanstack:interruptBinding'
+
+function recoverableInterrupt(row: InterruptRecord): Interrupt {
+  const descriptor = row.payload as Interrupt
+  return {
+    ...descriptor,
+    metadata: {
+      ...descriptor.metadata,
+      [interruptBindingMetadataKey]: row.binding,
+    },
+  }
+}
+
+export function hasExactInterruptIds(
+  expected: ReadonlyArray<string>,
+  actual: ReadonlyArray<string>,
+): boolean {
+  const left = [...new Set(expected)].sort()
+  const right = [...new Set(actual)].sort()
+  return (
+    left.length === expected.length &&
+    right.length === actual.length &&
+    left.length === right.length &&
+    left.every((id, index) => id === right[index])
+  )
+}
+
+export function projectInterruptRecovery(input: {
+  query: InterruptRecoveryQuery
+  rows: ReadonlyArray<InterruptRecord>
+  batch: InterruptBatchRecord | null
+  now: number
+  includeResolutions: boolean
+}): InterruptRecoveryStateV1 {
+  const correlation = {
+    schemaVersion: 1 as const,
+    threadId: input.query.threadId,
+    interruptedRunId: input.query.interruptedRunId,
+    generation:
+      input.batch?.generation ??
+      input.rows[0]?.generation ??
+      input.query.knownGeneration,
+    pendingInterrupts: [] as ReadonlyArray<Interrupt>,
+  }
+
+  if (input.batch) {
+    return cloneAndDeepFreezeJson({
+      ...correlation,
+      state: 'committed',
+      committed: {
+        fingerprint: input.batch.fingerprint,
+        ...(input.includeResolutions && {
+          resolutions: input.batch.resolutions,
+        }),
+        continuationRunId: input.batch.continuationRunId,
+        committedAt: new Date(input.batch.committedAt).toISOString(),
+      },
+    })
+  }
+  if (input.rows.length === 0) {
+    return cloneAndDeepFreezeJson({ ...correlation, state: 'missing' })
+  }
+
+  const pending = input.rows.filter((row) => row.status === 'pending')
+  if (pending.length > 0) {
+    const expired = pending.some(
+      (row) =>
+        row.binding.expiresAt !== undefined &&
+        Date.parse(row.binding.expiresAt) <= input.now,
+    )
+    return cloneAndDeepFreezeJson({
+      ...correlation,
+      state: expired ? 'expired' : 'pending',
+      pendingInterrupts: expired ? [] : pending.map(recoverableInterrupt),
+    })
+  }
+
+  return cloneAndDeepFreezeJson({
+    ...correlation,
+    state: 'legacy-committed',
+  })
+}
 
 export interface InterruptController {
-  resolve: (interruptId: string, response?: unknown) => Promise<void>
-  cancel: (interruptId: string) => Promise<void>
-  request: (
-    record: Omit<InterruptRecord, 'status' | 'resolvedAt'>,
-  ) => Promise<void>
-  listPending: (threadId: string) => Promise<Array<InterruptRecord>>
-  listPendingByRun: (runId: string) => Promise<Array<InterruptRecord>>
+  openInterruptBatch: InterruptStore['openInterruptBatch']
+  commitInterruptResolutions: InterruptStore['commitInterruptResolutions']
+  getInterruptRecoveryState: InterruptStore['getInterruptRecoveryState']
+  listPending: InterruptStore['listPending']
+  listPendingByRun: InterruptStore['listPendingByRun']
 }
 
 export function createInterruptController(opts: {
@@ -15,13 +115,12 @@ export function createInterruptController(opts: {
 }): InterruptController {
   const { store } = opts
   return {
-    resolve: (interruptId, response) => store.resolve(interruptId, response),
-    cancel: (interruptId) => store.cancel(interruptId),
-    request: (record) =>
-      store.create({
-        ...record,
-        status: 'pending',
-      }),
+    openInterruptBatch: (input: OpenInterruptBatchInput) =>
+      store.openInterruptBatch(input),
+    commitInterruptResolutions: (input: CommitInterruptResolutionsInput) =>
+      store.commitInterruptResolutions(input),
+    getInterruptRecoveryState: (input: InterruptRecoveryQuery) =>
+      store.getInterruptRecoveryState(input),
     listPending: (threadId) => store.listPending(threadId),
     listPendingByRun: (runId) => store.listPendingByRun(runId),
   }
diff --git a/packages/ai-persistence/src/memory.ts b/packages/ai-persistence/src/memory.ts
index 3729c0983..e09d2965b 100644
--- a/packages/ai-persistence/src/memory.ts
+++ b/packages/ai-persistence/src/memory.ts
@@ -1,6 +1,20 @@
-import { InMemoryLockStore } from '@tanstack/ai'
+import {
+  InMemoryLockStore,
+  canonicalInterruptJson,
+  canonicalizeInterruptResolutions,
+  cloneAndDeepFreezeJson,
+} from '@tanstack/ai'
 import { defineAIPersistence } from './types'
-import type { LockStore, ModelMessage } from '@tanstack/ai'
+import { hasExactInterruptIds, projectInterruptRecovery } from './interrupts'
+import type {
+  CommitInterruptResolutionsInput,
+  InterruptCommitResult,
+  InterruptRecoveryQuery,
+  InterruptRecoveryStateV1,
+  LockStore,
+  ModelMessage,
+  OpenInterruptBatchInput,
+} from '@tanstack/ai'
 import type {
   ArtifactRecord,
   ArtifactStore,
@@ -9,8 +23,10 @@ import type {
   BlobObject,
   BlobRecord,
   BlobStore,
+  InterruptBatchRecord,
   InterruptRecord,
   InterruptStore,
+  LegacyInterruptRecordInput,
   MessageStore,
   MetadataStore,
   RunRecord,
@@ -63,34 +79,351 @@ class MemoryRunStore implements RunStore {
 }
 
 class MemoryInterruptStore implements InterruptStore {
-  private readonly interrupts = new Map<string, InterruptRecord>()
-  create(record: Omit<InterruptRecord, 'resolvedAt'>): Promise<void> {
-    this.interrupts.set(record.interruptId, { ...record })
+  private interrupts = new Map<string, InterruptRecord>()
+  private batches = new Map<string, InterruptBatchRecord>()
+  private readonly interruptLocks = new Map<string, Promise<void>>()
+
+  constructor(private readonly clock: () => number) {}
+
+  private async withInterruptLock<T>(
+    interruptedRunId: string,
+    operation: () => Promise<T> | T,
+  ): Promise<T> {
+    const previous =
+      this.interruptLocks.get(interruptedRunId) ?? Promise.resolve()
+    let release = (): void => undefined
+    const current = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    const queued = previous.then(() => current)
+    this.interruptLocks.set(interruptedRunId, queued)
+    await previous
+    try {
+      return await operation()
+    } finally {
+      release()
+      if (this.interruptLocks.get(interruptedRunId) === queued) {
+        this.interruptLocks.delete(interruptedRunId)
+      }
+    }
+  }
+
+  private rowsForRun(interruptedRunId: string): Array<InterruptRecord> {
+    return [...this.interrupts.values()].filter(
+      (record) => record.runId === interruptedRunId,
+    )
+  }
+
+  private recoveryForRun(input: {
+    threadId: string
+    interruptedRunId: string
+    expectedGeneration: number
+  }): InterruptRecoveryStateV1 {
+    const rows = this.rowsForRun(input.interruptedRunId).filter(
+      (record) => record.threadId === input.threadId,
+    )
+    const batch = this.batches.get(input.interruptedRunId)
+    return projectInterruptRecovery({
+      query: {
+        threadId: input.threadId,
+        interruptedRunId: input.interruptedRunId,
+        knownGeneration: input.expectedGeneration,
+      },
+      rows,
+      batch: batch?.threadId === input.threadId ? batch : null,
+      now: this.clock(),
+      includeResolutions: true,
+    })
+  }
+
+  create(record: LegacyInterruptRecordInput): Promise<void> {
+    const generation = record.generation ?? 0
+    const binding =
+      record.binding ??
+      ({
+        kind: 'generic',
+        interruptId: record.interruptId,
+        interruptedRunId: record.runId,
+        generation,
+        responseSchemaHash: 'legacy:unknown',
+      } as const)
+    this.interrupts.set(
+      record.interruptId,
+      cloneAndDeepFreezeJson({
+        ...record,
+        generation,
+        binding,
+      }),
+    )
     return Promise.resolve()
   }
+
   resolve(interruptId: string, response?: unknown): Promise<void> {
     const existing = this.interrupts.get(interruptId)
     if (existing) {
-      this.interrupts.set(interruptId, {
-        ...existing,
-        status: 'resolved',
-        resolvedAt: Date.now(),
-        response,
-      })
+      this.interrupts.set(
+        interruptId,
+        cloneAndDeepFreezeJson({
+          ...existing,
+          status: 'resolved',
+          resolvedAt: this.clock(),
+          ...(response !== undefined && { response }),
+        }),
+      )
     }
     return Promise.resolve()
   }
+
   cancel(interruptId: string): Promise<void> {
     const existing = this.interrupts.get(interruptId)
     if (existing) {
-      this.interrupts.set(interruptId, {
-        ...existing,
-        status: 'cancelled',
-        resolvedAt: Date.now(),
-      })
+      this.interrupts.set(
+        interruptId,
+        cloneAndDeepFreezeJson({
+          ...existing,
+          status: 'cancelled',
+          resolvedAt: this.clock(),
+        }),
+      )
     }
     return Promise.resolve()
   }
+
+  openInterruptBatch(input: OpenInterruptBatchInput): Promise<{
+    generation: number
+    descriptors: OpenInterruptBatchInput['descriptors']
+  }> {
+    return this.withInterruptLock(input.interruptedRunId, () => {
+      const descriptorIds = input.descriptors.map((descriptor) => descriptor.id)
+      const bindingIds = input.bindings.map((binding) => binding.interruptId)
+      if (
+        descriptorIds.length === 0 ||
+        !hasExactInterruptIds(descriptorIds, bindingIds)
+      ) {
+        throw new TypeError(
+          'Interrupt descriptors and bindings must contain the same exact nonempty IDs.',
+        )
+      }
+      if (this.batches.has(input.interruptedRunId)) {
+        throw new Error('Cannot reopen a committed interrupt batch.')
+      }
+
+      const existing = this.rowsForRun(input.interruptedRunId)
+      if (existing.length > 0) {
+        const generation = existing[0]?.generation
+        const existingDescriptors = [...existing]
+          .sort((left, right) =>
+            left.interruptId.localeCompare(right.interruptId),
+          )
+          .map((record) => record.payload)
+        const requestedDescriptors = [...input.descriptors].sort(
+          (left, right) => left.id.localeCompare(right.id),
+        )
+        const existingBindings = [...existing]
+          .map((record) => record.binding)
+          .sort((left, right) =>
+            left.interruptId.localeCompare(right.interruptId),
+          )
+        const requestedBindings = [...input.bindings]
+          .map((binding) => ({
+            ...binding,
+            interruptedRunId: input.interruptedRunId,
+            generation,
+          }))
+          .sort((left, right) =>
+            left.interruptId.localeCompare(right.interruptId),
+          )
+        const sameDescriptors =
+          hasExactInterruptIds(
+            descriptorIds,
+            existing.map((record) => record.interruptId),
+          ) &&
+          canonicalInterruptJson(existingDescriptors) ===
+            canonicalInterruptJson(requestedDescriptors)
+        const sameBindings =
+          canonicalInterruptJson(existingBindings) ===
+          canonicalInterruptJson(requestedBindings)
+        if (
+          sameDescriptors &&
+          sameBindings &&
+          generation !== undefined &&
+          existing.every(
+            (record) =>
+              record.status === 'pending' &&
+              record.threadId === input.threadId &&
+              record.generation === generation,
+          )
+        ) {
+          return {
+            generation,
+            descriptors: cloneAndDeepFreezeJson(input.descriptors),
+          }
+        }
+        throw new Error('An incompatible interrupt batch is already open.')
+      }
+
+      const generation = 1
+      const bindings = new Map(
+        input.bindings.map((binding) => [binding.interruptId, binding]),
+      )
+      const nextInterrupts = new Map(this.interrupts)
+      const descriptors = cloneAndDeepFreezeJson(input.descriptors)
+      for (const descriptor of descriptors) {
+        if (nextInterrupts.has(descriptor.id)) {
+          throw new Error(`Interrupt ID already exists: ${descriptor.id}`)
+        }
+        const unopened = bindings.get(descriptor.id)
+        if (!unopened) {
+          throw new Error(`Missing binding for interrupt: ${descriptor.id}`)
+        }
+        const binding = cloneAndDeepFreezeJson({
+          ...unopened,
+          interruptedRunId: input.interruptedRunId,
+          generation,
+        })
+        nextInterrupts.set(
+          descriptor.id,
+          cloneAndDeepFreezeJson({
+            interruptId: descriptor.id,
+            runId: input.interruptedRunId,
+            threadId: input.threadId,
+            generation,
+            status: 'pending',
+            requestedAt: this.clock(),
+            payload: descriptor,
+            binding,
+          }),
+        )
+      }
+      this.interrupts = nextInterrupts
+      return { generation, descriptors }
+    })
+  }
+
+  commitInterruptResolutions(
+    input: CommitInterruptResolutionsInput,
+  ): Promise<InterruptCommitResult> {
+    return this.withInterruptLock(input.interruptedRunId, () => {
+      const candidate = canonicalizeInterruptResolutions(input.resolutions)
+      if (
+        candidate.fingerprint !== input.fingerprint ||
+        candidate.canonicalResolutions !== input.canonicalResolutions
+      ) {
+        throw new TypeError(
+          'Interrupt batch identity does not match its resolutions.',
+        )
+      }
+
+      const winner = this.batches.get(input.interruptedRunId)
+      if (winner) {
+        return winner.threadId === input.threadId &&
+          winner.fingerprint === input.fingerprint &&
+          winner.canonicalResolutions === input.canonicalResolutions
+          ? {
+              status: 'replayed',
+              continuationRunId: winner.continuationRunId,
+            }
+          : {
+              status: 'conflict',
+              authoritativeState: this.recoveryForRun(input),
+            }
+      }
+
+      const pending = this.rowsForRun(input.interruptedRunId).filter(
+        (record) => record.status === 'pending',
+      )
+      const resolutionIds = candidate.resolutions.map(
+        (resolution) => resolution.interruptId,
+      )
+      if (
+        !hasExactInterruptIds(
+          input.expectedInterruptIds,
+          pending.map((record) => record.interruptId),
+        ) ||
+        !hasExactInterruptIds(input.expectedInterruptIds, resolutionIds) ||
+        pending.some((record) => record.threadId !== input.threadId) ||
+        pending.some(
+          (record) => record.generation !== input.expectedGeneration,
+        ) ||
+        pending.some(
+          (record) =>
+            record.binding.expiresAt !== undefined &&
+            Date.parse(record.binding.expiresAt) <= this.clock(),
+        )
+      ) {
+        return {
+          status: 'conflict',
+          authoritativeState: this.recoveryForRun(input),
+        }
+      }
+
+      const committedAt = this.clock()
+      const nextInterrupts = new Map(this.interrupts)
+      for (const resolution of candidate.resolutions) {
+        const current = nextInterrupts.get(resolution.interruptId)
+        if (
+          !current ||
+          current.runId !== input.interruptedRunId ||
+          current.status !== 'pending' ||
+          current.generation !== input.expectedGeneration
+        ) {
+          throw new Error(
+            `Pending interrupt changed: ${resolution.interruptId}`,
+          )
+        }
+        nextInterrupts.set(
+          resolution.interruptId,
+          cloneAndDeepFreezeJson({
+            ...current,
+            status:
+              resolution.status === 'cancelled' ? 'cancelled' : 'resolved',
+            response: resolution,
+            resolvedAt: committedAt,
+          }),
+        )
+      }
+
+      const immutableWinner = cloneAndDeepFreezeJson({
+        threadId: input.threadId,
+        interruptedRunId: input.interruptedRunId,
+        generation: input.expectedGeneration,
+        expectedInterruptIds: [...input.expectedInterruptIds],
+        fingerprint: candidate.fingerprint,
+        canonicalResolutions: candidate.canonicalResolutions,
+        resolutions: candidate.resolutions,
+        continuationRunId: input.continuationRunId,
+        committedAt,
+      })
+      const nextBatches = new Map(this.batches)
+      nextBatches.set(input.interruptedRunId, immutableWinner)
+
+      this.interrupts = nextInterrupts
+      this.batches = nextBatches
+      return {
+        status: 'committed',
+        continuationRunId: input.continuationRunId,
+      }
+    })
+  }
+
+  getInterruptRecoveryState(
+    input: InterruptRecoveryQuery,
+  ): Promise<InterruptRecoveryStateV1> {
+    return this.withInterruptLock(input.interruptedRunId, () => {
+      const rows = this.rowsForRun(input.interruptedRunId).filter(
+        (record) => record.threadId === input.threadId,
+      )
+      const batch = this.batches.get(input.interruptedRunId)
+      return projectInterruptRecovery({
+        query: input,
+        rows,
+        batch: batch?.threadId === input.threadId ? batch : null,
+        now: this.clock(),
+        includeResolutions: true,
+      })
+    })
+  }
+
   get(interruptId: string): Promise<InterruptRecord | null> {
     return Promise.resolve(this.interrupts.get(interruptId) ?? null)
   }
@@ -348,11 +681,11 @@ class MemoryBlobStore implements BlobStore {
   }
 }
 
-export function memoryPersistence() {
+export function memoryPersistence(options?: { clock?: () => number }) {
   const stores: MemoryPersistenceStores = {
     messages: new MemoryMessageStore(),
     runs: new MemoryRunStore(),
-    interrupts: new MemoryInterruptStore(),
+    interrupts: new MemoryInterruptStore(options?.clock ?? Date.now),
     metadata: new MemoryMetadataStore(),
     artifacts: new MemoryArtifactStore(),
     blobs: new MemoryBlobStore(),
diff --git a/packages/ai-persistence/src/middleware.ts b/packages/ai-persistence/src/middleware.ts
index b56efe27c..82ca4de3d 100644
--- a/packages/ai-persistence/src/middleware.ts
+++ b/packages/ai-persistence/src/middleware.ts
@@ -1,4 +1,7 @@
-import { defineChatMiddleware } from '@tanstack/ai'
+import {
+  defineChatMiddleware,
+  validateInterruptResumeBatch as validateCoreInterruptResumeBatch,
+} from '@tanstack/ai'
 import { base64ToUint8Array } from '@tanstack/ai-utils'
 import {
   InterruptsCapability,
@@ -25,12 +28,18 @@ import type {
   GenerationFinishInfo,
   GenerationMiddleware,
   GenerationMiddlewareContext,
+  Interrupt,
+  InterruptBinding,
+  InterruptRecoveryStateV1,
+  InterruptSubmissionError,
+  ItemInterruptErrorCode,
   PersistedArtifactActivity,
   PersistedArtifactRef,
   PersistedArtifactRole,
   RunAgentResumeItem,
   StreamChunk,
   TokenUsage,
+  UnopenedInterruptBinding,
 } from '@tanstack/ai'
 import type {
   AIPersistence,
@@ -88,69 +97,42 @@ const runState = new WeakMap<
   { merged: boolean; interrupted: boolean }
 >()
 
-const validResumeStatuses = new Set(['resolved', 'cancelled'])
+const interruptBindingMetadataKey = 'tanstack:interruptBinding'
 
-function validatePendingResumes(
-  pending: Array<InterruptRecord>,
-  resume: Array<RunAgentResumeItem> | undefined,
-): Map<string, RunAgentResumeItem> {
-  const pendingInterruptIds = new Set(
-    pending.map((interrupt) => interrupt.interruptId),
-  )
-  const resumeByInterruptId = new Map(
-    (resume ?? []).map((entry) => [entry.interruptId, entry]),
-  )
-  if (pending.length === 0) {
-    const staleEntry = resume?.[0]
-    if (staleEntry) {
-      throw new Error(
-        `Resume entry references non-pending interrupt ${staleEntry.interruptId}.`,
-      )
-    }
-    return resumeByInterruptId
-  }
-  if (!resume || resume.length === 0) {
-    throw new Error(
-      `Thread has pending interrupts; resume is required before accepting new input.`,
-    )
-  }
+export interface ValidateInterruptResumeBatchInput {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  pending: ReadonlyArray<InterruptRecord>
+  resume?: ReadonlyArray<RunAgentResumeItem>
+  tools: ChatMiddlewareConfig['tools']
+  now?: number
+}
 
-  for (const interrupt of pending) {
-    const entry = resumeByInterruptId.get(interrupt.interruptId)
-    if (!entry) {
-      throw new Error(
-        `Missing resume entry for pending interrupt ${interrupt.interruptId}.`,
-      )
-    }
-    if (!validResumeStatuses.has(entry.status)) {
-      throw new Error(
-        `Invalid resume status for pending interrupt ${interrupt.interruptId}: ${entry.status}.`,
-      )
-    }
-  }
-  for (const entry of resume) {
-    if (!pendingInterruptIds.has(entry.interruptId)) {
-      throw new Error(
-        `Resume entry references non-pending interrupt ${entry.interruptId}.`,
-      )
-    }
+export interface ValidatedInterruptResumeBatch {
+  errors: ReadonlyArray<InterruptSubmissionError>
+  resolutions?: ReadonlyArray<RunAgentResumeItem>
+  canonicalResolutions?: string
+  fingerprint?: string
+  resumeToolState?: ChatResumeToolState
+}
+
+export class InterruptResumeValidationError extends Error {
+  override readonly name = 'InterruptResumeValidationError'
+
+  constructor(
+    readonly errors: ReadonlyArray<InterruptSubmissionError>,
+    readonly recovery?: InterruptRecoveryStateV1,
+  ) {
+    super(errors.map((error) => error.message).join(' '))
   }
-  return resumeByInterruptId
 }
 
-async function applyPendingResumes(
-  pending: Array<InterruptRecord>,
-  resumeByInterruptId: Map<string, RunAgentResumeItem>,
-  interrupts: NonNullable<AIPersistence['stores']['interrupts']>,
-): Promise<void> {
-  for (const interrupt of pending) {
-    const entry = resumeByInterruptId.get(interrupt.interruptId)
-    if (!entry) continue
-    if (entry.status === 'resolved') {
-      await interrupts.resolve(interrupt.interruptId, entry.payload)
-    } else {
-      await interrupts.cancel(interrupt.interruptId)
-    }
+export class InterruptReplaySignal extends Error {
+  override readonly name = 'InterruptReplaySignal'
+
+  constructor(readonly continuationRunId: string) {
+    super(`Interrupt resolutions already committed by ${continuationRunId}.`)
   }
 }
 
@@ -167,54 +149,133 @@ function stringField(
   return typeof value[key] === 'string' ? value[key] : undefined
 }
 
-function interruptKind(interrupt: InterruptRecord): string | undefined {
-  const metadata = objectValue(interrupt.payload.metadata)
-  return metadata ? stringField(metadata, 'kind') : undefined
+function itemError(
+  input: ValidateInterruptResumeBatchInput,
+  interruptId: string,
+  code: ItemInterruptErrorCode,
+  message: string,
+  options?: {
+    path?: ReadonlyArray<string | number>
+    source?: 'client' | 'server'
+    retryable?: boolean
+  },
+): InterruptSubmissionError {
+  return {
+    scope: 'item',
+    threadId: input.threadId,
+    interruptedRunId: input.interruptedRunId,
+    generation: input.generation,
+    interruptId,
+    code,
+    message,
+    source: options?.source ?? 'client',
+    retryable: options?.retryable ?? false,
+    ...(options?.path ? { path: options.path } : {}),
+  }
 }
 
-function resolvedApprovalDecision(entry: RunAgentResumeItem): boolean {
-  if (entry.status === 'cancelled') return false
-  const payload = objectValue(entry.payload)
-  return typeof payload?.approved === 'boolean' ? payload.approved : true
+export async function validateInterruptResumeBatch(
+  input: ValidateInterruptResumeBatchInput,
+): Promise<ValidatedInterruptResumeBatch> {
+  // Keep the persistence package's public compatibility wrapper while making
+  // core the single runtime validator/translator for both durable and
+  // ephemeral resumes.
+  return validateCoreInterruptResumeBatch(input)
 }
 
-function resumeToolStateFromPending(
-  pending: Array<InterruptRecord>,
-  resumeByInterruptId: Map<string, RunAgentResumeItem>,
-): ChatResumeToolState | undefined {
-  const approvals = new Map<string, boolean>()
-  const clientToolResults = new Map<string, unknown>()
-
-  for (const interrupt of pending) {
-    const entry = resumeByInterruptId.get(interrupt.interruptId)
-    if (!entry) continue
-
-    const kind = interruptKind(interrupt)
-    const reason = stringField(interrupt.payload, 'reason')
-    const toolCallId = stringField(interrupt.payload, 'toolCallId')
-
-    if (kind === 'approval' || reason === 'approval_required') {
-      approvals.set(interrupt.interruptId, resolvedApprovalDecision(entry))
-      continue
+function readUnopenedInterruptBinding(
+  descriptor: Interrupt,
+): UnopenedInterruptBinding | undefined {
+  const metadata = objectValue(descriptor.metadata)
+  const raw = metadata
+    ? objectValue(metadata[interruptBindingMetadataKey])
+    : null
+  if (!raw || stringField(raw, 'interruptId') !== descriptor.id) {
+    return undefined
+  }
+  const kind = stringField(raw, 'kind')
+  const interruptId = stringField(raw, 'interruptId')
+  const responseSchemaHash = stringField(raw, 'responseSchemaHash')
+  const expiresAt = stringField(raw, 'expiresAt')
+  if (!interruptId || !responseSchemaHash) return undefined
+  if (kind === 'generic') {
+    return {
+      kind,
+      interruptId,
+      responseSchemaHash,
+      ...(expiresAt ? { expiresAt } : {}),
     }
-
-    if (
-      entry.status === 'resolved' &&
-      toolCallId &&
-      (kind === 'client_tool' || reason === 'client_tool_input')
-    ) {
-      clientToolResults.set(toolCallId, entry.payload)
+  }
+  const toolName = stringField(raw, 'toolName')
+  const toolCallId = stringField(raw, 'toolCallId')
+  if (!toolName || !toolCallId) return undefined
+  if (kind === 'client-tool-execution') {
+    const outputSchemaHash = stringField(raw, 'outputSchemaHash')
+    if (!outputSchemaHash) return undefined
+    return {
+      kind,
+      interruptId,
+      toolName,
+      toolCallId,
+      outputSchemaHash,
+      responseSchemaHash,
+      ...(expiresAt ? { expiresAt } : {}),
+    }
+  }
+  if (kind === 'tool-approval') {
+    const inputSchemaHash = stringField(raw, 'inputSchemaHash')
+    const approvalSchemaHash = stringField(raw, 'approvalSchemaHash')
+    if (!inputSchemaHash || !approvalSchemaHash) return undefined
+    return {
+      kind,
+      interruptId,
+      toolName,
+      toolCallId,
+      originalArgs: raw.originalArgs,
+      inputSchemaHash,
+      approvalSchemaHash,
+      responseSchemaHash,
+      ...(expiresAt ? { expiresAt } : {}),
     }
   }
+  return undefined
+}
 
-  if (approvals.size === 0 && clientToolResults.size === 0) return undefined
-  return { approvals, clientToolResults }
+function withoutInterruptBinding(descriptor: Interrupt): Interrupt {
+  const metadata = objectValue(descriptor.metadata)
+  if (!metadata || !(interruptBindingMetadataKey in metadata)) {
+    return descriptor
+  }
+  const publicMetadata = { ...metadata }
+  delete publicMetadata[interruptBindingMetadataKey]
+  return { ...descriptor, metadata: publicMetadata }
 }
 
-function interruptPayload(interrupt: unknown): Record<string, unknown> {
-  return interrupt && typeof interrupt === 'object'
-    ? { ...(interrupt as Record<string, unknown>) }
-    : { value: interrupt }
+function batchError(input: {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  interruptIds: ReadonlyArray<string>
+  code:
+    | 'stale'
+    | 'conflict'
+    | 'persistence-required'
+    | 'server'
+    | 'invalid-response-schema'
+  message: string
+  retryable?: boolean
+}): InterruptSubmissionError {
+  return {
+    scope: 'batch',
+    threadId: input.threadId,
+    interruptedRunId: input.interruptedRunId,
+    generation: input.generation,
+    interruptIds: input.interruptIds,
+    code: input.code,
+    message: input.message,
+    source: 'server',
+    retryable: input.retryable ?? false,
+  }
 }
 
 function isArtifactRef(value: unknown): value is PersistedArtifactRef {
@@ -779,7 +840,8 @@ async function interruptRun(
  * Chat-only persistence middleware. Provides durable **state** for `chat()`:
  * thread messages, run records, interrupts, and locks. Delivery durability
  * (replaying a disconnected/reloaded stream) lives on the transport layer via
- * `StreamDurability`, not here — this middleware never mutates the chunk stream.
+ * `StreamDurability`, not here. Interrupt terminals are enriched only with the
+ * store-issued run/generation correlation required by the public binding.
  */
 export function withChatPersistence<TStores extends AIPersistenceStores>(
   persistence: AIPersistence<TStores> & ValidChatPersistence<TStores>,
@@ -822,22 +884,89 @@ export function withChatPersistence(
       let resumeToolState: ChatResumeToolState | undefined
 
       if (wantsInterrupts && persistence.stores.interrupts) {
-        const pending = await persistence.stores.interrupts.listPending(
-          ctx.threadId,
-        )
-        const resumeByInterruptId = validatePendingResumes(
-          pending,
-          config.resume,
-        )
-        resumeToolState = resumeToolStateFromPending(
-          pending,
-          resumeByInterruptId,
-        )
-        await applyPendingResumes(
-          pending,
-          resumeByInterruptId,
-          persistence.stores.interrupts,
-        )
+        const pending = ctx.parentRunId
+          ? await persistence.stores.interrupts.listByRun(ctx.parentRunId)
+          : await persistence.stores.interrupts.listPending(ctx.threadId)
+        const interruptedRunId =
+          ctx.parentRunId ?? pending[0]?.runId ?? ctx.runId
+        const generation = pending[0]?.generation ?? 0
+        if (pending.length > 0 || (config.resume?.length ?? 0) > 0) {
+          if (!ctx.parentRunId) {
+            throw new InterruptResumeValidationError([
+              batchError({
+                threadId: ctx.threadId,
+                interruptedRunId,
+                generation,
+                interruptIds: pending.map((record) => record.interruptId),
+                code: 'stale',
+                message:
+                  'Interrupt continuation requires parentRunId to identify the interrupted run.',
+              }),
+            ])
+          }
+          const validated = await validateInterruptResumeBatch({
+            threadId: ctx.threadId,
+            interruptedRunId,
+            generation,
+            pending,
+            resume: config.resume,
+            tools: config.tools,
+          })
+          if (validated.errors.length > 0) {
+            throw new InterruptResumeValidationError(validated.errors)
+          }
+          if (
+            !validated.resolutions ||
+            validated.canonicalResolutions === undefined ||
+            validated.fingerprint === undefined
+          ) {
+            throw new InterruptResumeValidationError([
+              batchError({
+                threadId: ctx.threadId,
+                interruptedRunId,
+                generation,
+                interruptIds: pending.map((record) => record.interruptId),
+                code: 'server',
+                message:
+                  'Validated interrupt batch is missing canonical commit data.',
+              }),
+            ])
+          }
+          const expectedInterruptIds = pending
+            .map((record) => record.interruptId)
+            .sort((left, right) => left.localeCompare(right))
+          const commit =
+            await persistence.stores.interrupts.commitInterruptResolutions({
+              threadId: ctx.threadId,
+              interruptedRunId,
+              continuationRunId: ctx.runId,
+              expectedGeneration: generation,
+              expectedInterruptIds,
+              resolutions: validated.resolutions,
+              canonicalResolutions: validated.canonicalResolutions,
+              fingerprint: validated.fingerprint,
+            })
+          if (commit.status === 'replayed') {
+            throw new InterruptReplaySignal(commit.continuationRunId)
+          }
+          if (commit.status === 'conflict') {
+            throw new InterruptResumeValidationError(
+              [
+                batchError({
+                  threadId: ctx.threadId,
+                  interruptedRunId,
+                  generation,
+                  interruptIds: expectedInterruptIds,
+                  code: 'conflict',
+                  message:
+                    'Interrupt resolutions conflict with the authoritative committed batch.',
+                }),
+              ],
+              commit.authoritativeState,
+            )
+          }
+          resumeToolState = validated.resumeToolState
+        }
       }
 
       await createOrResumeRun(runs, ctx.runId, ctx.threadId)
@@ -852,7 +981,16 @@ export function withChatPersistence(
       if (state) state.merged = true
 
       const stored = await persistence.stores.messages.loadThread(ctx.threadId)
-      const merged = config.messages.length > 0 ? config.messages : stored
+      // Once an interrupt batch has been authoritatively validated and
+      // committed, its stored transcript is the execution source of truth.
+      // Client-supplied history may be useful for ephemeral continuation, but
+      // it must never replace persisted tool-call arguments on the durable
+      // path.
+      const merged = resumeToolState
+        ? stored
+        : config.messages.length > 0
+          ? config.messages
+          : stored
       return {
         messages: merged,
         ...(resumeToolState ? { resumeToolState } : {}),
@@ -860,9 +998,9 @@ export function withChatPersistence(
     },
 
     async onChunk(ctx: ChatMiddlewareContext, chunk: StreamChunk) {
-      // State-only: react to the interrupt boundary (create interrupt records,
-      // mark the run interrupted, snapshot thread messages). The chunk stream is
-      // never mutated — delivery durability is a transport-layer concern.
+      // Persist the interrupt boundary before returning it. The only stream
+      // projection added here is the store-issued run/generation correlation;
+      // delivery durability remains a transport-layer concern.
       if (
         chunk.type !== 'RUN_FINISHED' ||
         chunk.outcome?.type !== 'interrupt'
@@ -872,17 +1010,71 @@ export function withChatPersistence(
       const state = runState.get(ctx)
       if (!state) return
 
-      if (wantsInterrupts && persistence.stores.interrupts) {
-        for (const interrupt of chunk.outcome.interrupts) {
-          await persistence.stores.interrupts.create({
-            interruptId: interrupt.id,
-            runId: ctx.runId,
-            threadId: ctx.threadId,
-            status: 'pending',
-            requestedAt: Date.now(),
-            payload: interruptPayload(interrupt),
-          })
+      const interruptIds = chunk.outcome.interrupts.map(
+        (interrupt) => interrupt.id,
+      )
+      if (!wantsInterrupts || !persistence.stores.interrupts) {
+        await interruptRun(runs, ctx.runId)
+        if (wantsMessages && persistence.stores.messages) {
+          await persistence.stores.messages.saveThread(ctx.threadId, [
+            ...ctx.messages,
+          ])
+        }
+        state.interrupted = true
+        return
+      }
+      const bindings: Array<UnopenedInterruptBinding> = []
+      const descriptors: Array<Interrupt> = []
+      const bindingErrors: Array<InterruptSubmissionError> = []
+      for (const interrupt of chunk.outcome.interrupts) {
+        const binding = readUnopenedInterruptBinding(interrupt)
+        if (!binding) {
+          bindingErrors.push(
+            itemError(
+              {
+                threadId: ctx.threadId,
+                interruptedRunId: ctx.runId,
+                generation: 0,
+                pending: [],
+                tools: [],
+              },
+              interrupt.id,
+              'invalid-response-schema',
+              `Interrupt ${interrupt.id} is missing a valid server binding.`,
+              { source: 'server' },
+            ),
+          )
+          continue
         }
+        bindings.push(binding)
+        descriptors.push(withoutInterruptBinding(interrupt))
+      }
+      if (bindingErrors.length > 0) {
+        throw new InterruptResumeValidationError(bindingErrors)
+      }
+      let opened: Awaited<
+        ReturnType<typeof persistence.stores.interrupts.openInterruptBatch>
+      >
+      try {
+        opened = await persistence.stores.interrupts.openInterruptBatch({
+          threadId: ctx.threadId,
+          interruptedRunId: ctx.runId,
+          descriptors,
+          bindings,
+        })
+      } catch (error) {
+        if (error instanceof InterruptResumeValidationError) throw error
+        throw new InterruptResumeValidationError([
+          batchError({
+            threadId: ctx.threadId,
+            interruptedRunId: ctx.runId,
+            generation: 0,
+            interruptIds,
+            code: 'server',
+            message: `Failed to persist interrupt batch: ${error instanceof Error ? error.message : String(error)}`,
+            retryable: true,
+          }),
+        ])
       }
       await interruptRun(runs, ctx.runId)
       if (wantsMessages && persistence.stores.messages) {
@@ -891,6 +1083,34 @@ export function withChatPersistence(
         ])
       }
       state.interrupted = true
+      const openedBindings = new Map<string, InterruptBinding>(
+        bindings.map((binding) => [
+          binding.interruptId,
+          {
+            ...binding,
+            interruptedRunId: ctx.runId,
+            generation: opened.generation,
+          } satisfies InterruptBinding,
+        ]),
+      )
+      return {
+        ...chunk,
+        outcome: {
+          ...chunk.outcome,
+          interrupts: chunk.outcome.interrupts.map((interrupt) => {
+            const binding = openedBindings.get(interrupt.id)
+            return binding
+              ? {
+                  ...interrupt,
+                  metadata: {
+                    ...interrupt.metadata,
+                    [interruptBindingMetadataKey]: binding,
+                  },
+                }
+              : interrupt
+          }),
+        },
+      }
     },
 
     async onFinish(ctx: ChatMiddlewareContext, info: FinishInfo) {
diff --git a/packages/ai-persistence/src/recovery.ts b/packages/ai-persistence/src/recovery.ts
new file mode 100644
index 000000000..fdf085967
--- /dev/null
+++ b/packages/ai-persistence/src/recovery.ts
@@ -0,0 +1,179 @@
+import { cloneAndDeepFreezeJson } from '@tanstack/ai'
+import type {
+  InterruptPersistenceGateway,
+  InterruptRecoveryQuery,
+  InterruptRecoveryStateV1,
+  InterruptSubmissionError,
+} from '@tanstack/ai'
+
+export type InterruptRecoveryAuthorization =
+  | { authorized: false }
+  | { authorized: true; includeResolutions: boolean }
+
+export interface InterruptRecoveryHandlerOptions {
+  gateway: InterruptPersistenceGateway
+  authorize: (
+    request: Request,
+    input: InterruptRecoveryQuery,
+  ) => InterruptRecoveryAuthorization | Promise<InterruptRecoveryAuthorization>
+}
+
+export interface GetInterruptRecoveryStateOptions {
+  includeResolutions?: boolean
+}
+
+function redactCommittedResolutions(
+  state: InterruptRecoveryStateV1,
+): InterruptRecoveryStateV1 {
+  if (!state.committed || state.committed.resolutions === undefined) {
+    return state
+  }
+  return cloneAndDeepFreezeJson({
+    ...state,
+    committed: {
+      fingerprint: state.committed.fingerprint,
+      ...(state.committed.continuationRunId
+        ? { continuationRunId: state.committed.continuationRunId }
+        : {}),
+      committedAt: state.committed.committedAt,
+    },
+  })
+}
+
+export async function getInterruptRecoveryState(
+  gateway: InterruptPersistenceGateway,
+  query: InterruptRecoveryQuery,
+  options?: GetInterruptRecoveryStateOptions,
+): Promise<InterruptRecoveryStateV1> {
+  const state = await gateway.getInterruptRecoveryState(query)
+  return options?.includeResolutions === true
+    ? state
+    : redactCommittedResolutions(state)
+}
+
+function recoveryError(input: {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  code: 'recovery-unavailable' | 'protocol' | 'server'
+  message: string
+  source?: 'client' | 'server'
+  retryable?: boolean
+}): InterruptSubmissionError {
+  return {
+    scope: 'batch',
+    threadId: input.threadId,
+    interruptedRunId: input.interruptedRunId,
+    generation: input.generation,
+    interruptIds: [],
+    code: input.code,
+    message: input.message,
+    source: input.source ?? 'server',
+    retryable: input.retryable ?? false,
+  }
+}
+
+function jsonResponse(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+export function createInterruptRecoveryHandler(
+  options: InterruptRecoveryHandlerOptions,
+): (request: Request) => Promise<Response> {
+  return async (request) => {
+    const url = new URL(request.url)
+    const threadId = url.searchParams.get('threadId') ?? ''
+    const interruptedRunId = url.searchParams.get('interruptedRunId') ?? ''
+    const knownGenerationText = url.searchParams.get('knownGeneration')
+    const knownGeneration =
+      knownGenerationText === null ? Number.NaN : Number(knownGenerationText)
+    if (
+      !threadId ||
+      !interruptedRunId ||
+      !Number.isSafeInteger(knownGeneration) ||
+      knownGeneration < 0
+    ) {
+      return jsonResponse(
+        {
+          errors: [
+            recoveryError({
+              threadId,
+              interruptedRunId,
+              generation: Number.isSafeInteger(knownGeneration)
+                ? knownGeneration
+                : 0,
+              code: 'protocol',
+              message:
+                'Recovery requires threadId, interruptedRunId, and a non-negative integer knownGeneration.',
+              source: 'client',
+            }),
+          ],
+        },
+        400,
+      )
+    }
+    const input = { threadId, interruptedRunId, knownGeneration }
+    let authorization: InterruptRecoveryAuthorization
+    try {
+      authorization = await options.authorize(request, input)
+    } catch (error) {
+      return jsonResponse(
+        {
+          errors: [
+            recoveryError({
+              threadId: '',
+              interruptedRunId: '',
+              generation: 0,
+              code: 'server',
+              message: `Interrupt recovery authorization failed: ${error instanceof Error ? error.message : String(error)}`,
+              retryable: true,
+            }),
+          ],
+        },
+        500,
+      )
+    }
+    if (!authorization.authorized) {
+      return jsonResponse(
+        {
+          errors: [
+            recoveryError({
+              threadId: '',
+              interruptedRunId: '',
+              generation: 0,
+              code: 'recovery-unavailable',
+              message: 'Interrupt recovery is not authorized.',
+            }),
+          ],
+        },
+        401,
+      )
+    }
+
+    try {
+      const state = await getInterruptRecoveryState(options.gateway, input, {
+        includeResolutions: authorization.includeResolutions,
+      })
+      return jsonResponse(state, 200)
+    } catch (error) {
+      return jsonResponse(
+        {
+          errors: [
+            recoveryError({
+              threadId,
+              interruptedRunId,
+              generation: knownGeneration,
+              code: 'recovery-unavailable',
+              message: `Interrupt recovery failed: ${error instanceof Error ? error.message : String(error)}`,
+              retryable: true,
+            }),
+          ],
+        },
+        503,
+      )
+    }
+  }
+}
diff --git a/packages/ai-persistence/src/testkit/conformance.ts b/packages/ai-persistence/src/testkit/conformance.ts
index e2e80edfc..cb62aac97 100644
--- a/packages/ai-persistence/src/testkit/conformance.ts
+++ b/packages/ai-persistence/src/testkit/conformance.ts
@@ -11,7 +11,9 @@
  * hold identically for byte-storing (memory) and reference-only (SQL) backends.
  */
 import { beforeAll, describe, expect, it } from 'vitest'
-import type { AIPersistence } from '../types'
+import { canonicalizeInterruptResolutions } from '@tanstack/ai'
+import type { CommitInterruptResolutionsInput } from '@tanstack/ai'
+import type { AIPersistence, InterruptStore } from '../types'
 
 type MakePersistence = () => Promise<AIPersistence> | AIPersistence
 
@@ -352,3 +354,267 @@ export function runPersistenceConformance(
     })
   })
 }
+
+export interface InterruptConformanceHarness {
+  getStore: () => InterruptStore | undefined
+  advanceBy: (milliseconds: number) => void
+  inspect: (interruptedRunId: string) => Promise<{
+    statuses: ReadonlyArray<string>
+    batchCount: number
+  }>
+  failTransitionOnce: (interruptId: string) => void
+  reopen?: () => Promise<InterruptStore>
+}
+
+export async function openTwoInterrupts(store: InterruptStore) {
+  return store.openInterruptBatch({
+    threadId: 'thread-cas',
+    interruptedRunId: 'run-interrupted',
+    descriptors: [
+      { id: 'int-a', reason: 'confirmation' },
+      {
+        id: 'int-b',
+        reason: 'input_required',
+        expiresAt: '2026-07-13T10:01:00.000Z',
+      },
+    ],
+    bindings: [
+      {
+        interruptId: 'int-a',
+        kind: 'generic',
+        responseSchemaHash: 'sha256:a',
+      },
+      {
+        interruptId: 'int-b',
+        kind: 'generic',
+        responseSchemaHash: 'sha256:b',
+        expiresAt: '2026-07-13T10:01:00.000Z',
+      },
+    ],
+  })
+}
+
+export function validTwoItemCommit(
+  generation: number,
+  continuationRunId = 'run-continuation-a',
+): CommitInterruptResolutionsInput {
+  const candidate = canonicalizeInterruptResolutions([
+    { interruptId: 'int-b', status: 'cancelled' },
+    {
+      interruptId: 'int-a',
+      status: 'resolved',
+      payload: { ok: true },
+    },
+  ])
+  return {
+    threadId: 'thread-cas',
+    interruptedRunId: 'run-interrupted',
+    continuationRunId,
+    expectedGeneration: generation,
+    expectedInterruptIds: ['int-b', 'int-a'],
+    resolutions: candidate.resolutions,
+    fingerprint: candidate.fingerprint,
+    canonicalResolutions: candidate.canonicalResolutions,
+  }
+}
+
+export function runInterruptStoreConformance(
+  createHarness: () => Promise<InterruptConformanceHarness>,
+): void {
+  describe('atomic interrupt store conformance', () => {
+    it('requires the atomic interrupt capability', async () => {
+      const harness = await createHarness()
+      expect(
+        harness.getStore(),
+        'interrupt conformance requires stores.interrupts',
+      ).toBeDefined()
+      if (!harness.getStore()) throw new Error('interrupt store missing')
+    })
+
+    it('keeps canonical order stable and rejects malformed exact sets', async () => {
+      const harness = await createHarness()
+      const store = harness.getStore()
+      if (!store) throw new Error('interrupt store missing')
+      const opened = await openTwoInterrupts(store)
+      const ordered = validTwoItemCommit(opened.generation)
+      const reordered = canonicalizeInterruptResolutions([
+        {
+          interruptId: 'int-a',
+          status: 'resolved',
+          payload: { ok: true },
+        },
+        { interruptId: 'int-b', status: 'cancelled' },
+      ])
+      expect(reordered.fingerprint).toBe(ordered.fingerprint)
+      expect(reordered.canonicalResolutions).toBe(ordered.canonicalResolutions)
+
+      for (const expectedInterruptIds of [
+        ['int-a'],
+        ['int-a', 'int-b', 'int-c'],
+        ['int-a', 'int-a'],
+      ]) {
+        await expect(
+          store.commitInterruptResolutions({
+            ...ordered,
+            expectedInterruptIds,
+          }),
+        ).resolves.toMatchObject({ status: 'conflict' })
+      }
+      await expect(
+        store.commitInterruptResolutions({
+          ...ordered,
+          expectedGeneration: opened.generation + 1,
+        }),
+      ).resolves.toMatchObject({ status: 'conflict' })
+      await expect(
+        store.commitInterruptResolutions({
+          ...ordered,
+          threadId: 'thread-other',
+        }),
+      ).resolves.toMatchObject({
+        status: 'conflict',
+        authoritativeState: { state: 'missing' },
+      })
+    })
+
+    it('checks canonical bytes and digest before any transition', async () => {
+      const harness = await createHarness()
+      const store = harness.getStore()
+      if (!store) throw new Error('interrupt store missing')
+      const opened = await openTwoInterrupts(store)
+      const input = validTwoItemCommit(opened.generation)
+      await expect(
+        store.commitInterruptResolutions({
+          ...input,
+          canonicalResolutions: `${input.canonicalResolutions} `,
+        }),
+      ).rejects.toThrow(/identity/i)
+      await expect(harness.inspect('run-interrupted')).resolves.toEqual({
+        statuses: ['pending', 'pending'],
+        batchCount: 0,
+      })
+    })
+
+    it('rolls back every row when a transition fails', async () => {
+      const harness = await createHarness()
+      const store = harness.getStore()
+      if (!store) throw new Error('interrupt store missing')
+      const opened = await openTwoInterrupts(store)
+      harness.failTransitionOnce('int-b')
+      await expect(
+        store.commitInterruptResolutions(validTwoItemCommit(opened.generation)),
+      ).rejects.toThrow()
+      await expect(harness.inspect('run-interrupted')).resolves.toEqual({
+        statuses: ['pending', 'pending'],
+        batchCount: 0,
+      })
+    })
+
+    it('projects pending, committed replay, restart, and one concurrent winner', async () => {
+      const harness = await createHarness()
+      const store = harness.getStore()
+      if (!store) throw new Error('interrupt store missing')
+      const opened = await openTwoInterrupts(store)
+      await expect(
+        store.getInterruptRecoveryState({
+          threadId: 'thread-cas',
+          interruptedRunId: 'run-interrupted',
+          knownGeneration: opened.generation,
+        }),
+      ).resolves.toMatchObject({
+        state: 'pending',
+        generation: opened.generation,
+      })
+
+      const first = validTwoItemCommit(opened.generation, 'run-continuation-a')
+      const secondCandidate = canonicalizeInterruptResolutions([
+        { interruptId: 'int-a', status: 'cancelled' },
+        { interruptId: 'int-b', status: 'cancelled' },
+      ])
+      const second = {
+        ...first,
+        continuationRunId: 'run-continuation-b',
+        resolutions: secondCandidate.resolutions,
+        fingerprint: secondCandidate.fingerprint,
+        canonicalResolutions: secondCandidate.canonicalResolutions,
+      }
+      const results = await Promise.all([
+        store.commitInterruptResolutions(first),
+        store.commitInterruptResolutions(second),
+      ])
+      expect(results.map((result) => result.status).sort()).toEqual([
+        'committed',
+        'conflict',
+      ])
+      const winningRunId = results.find(
+        (result) => result.status === 'committed',
+      )?.continuationRunId
+      expect(winningRunId).toBeDefined()
+      const replayInput = winningRunId === 'run-continuation-a' ? first : second
+      await expect(
+        store.commitInterruptResolutions({
+          ...replayInput,
+          continuationRunId: 'ignored-replay-run',
+        }),
+      ).resolves.toEqual({
+        status: 'replayed',
+        continuationRunId: winningRunId,
+      })
+
+      const recoveredStore = harness.reopen ? await harness.reopen() : store
+      await expect(
+        recoveredStore.getInterruptRecoveryState({
+          threadId: 'thread-cas',
+          interruptedRunId: 'run-interrupted',
+          knownGeneration: opened.generation,
+        }),
+      ).resolves.toMatchObject({
+        state: 'committed',
+        committed: { continuationRunId: winningRunId },
+      })
+    })
+
+    it('projects missing and legacy-committed recovery states', async () => {
+      const harness = await createHarness()
+      const store = harness.getStore()
+      if (!store) throw new Error('interrupt store missing')
+      await expect(
+        store.getInterruptRecoveryState({
+          threadId: 'thread-cas',
+          interruptedRunId: 'run-missing',
+          knownGeneration: 3,
+        }),
+      ).resolves.toMatchObject({ state: 'missing', generation: 3 })
+
+      await store.create({
+        interruptId: 'legacy-int',
+        runId: 'legacy-run',
+        threadId: 'thread-cas',
+        status: 'resolved',
+        requestedAt: 1,
+        payload: { id: 'legacy-int', reason: 'confirmation' },
+      })
+      await expect(
+        store.getInterruptRecoveryState({
+          threadId: 'thread-cas',
+          interruptedRunId: 'legacy-run',
+          knownGeneration: 0,
+        }),
+      ).resolves.toMatchObject({ state: 'legacy-committed' })
+    })
+
+    it('marks an uncommitted expired batch expired', async () => {
+      const harness = await createHarness()
+      const store = harness.getStore()
+      if (!store) throw new Error('interrupt store missing')
+      const opened = await openTwoInterrupts(store)
+      harness.advanceBy(60_001)
+      await expect(
+        store.commitInterruptResolutions(validTwoItemCommit(opened.generation)),
+      ).resolves.toMatchObject({
+        status: 'conflict',
+        authoritativeState: { state: 'expired' },
+      })
+    })
+  })
+}
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
index bd3734da3..61a4c3071 100644
--- a/packages/ai-persistence/src/types.ts
+++ b/packages/ai-persistence/src/types.ts
@@ -1,4 +1,11 @@
-import type { LockStore, ModelMessage, TokenUsage } from '@tanstack/ai'
+import type {
+  InterruptBinding,
+  InterruptPersistenceGateway,
+  LockStore,
+  ModelMessage,
+  RunAgentResumeItem,
+  TokenUsage,
+} from '@tanstack/ai'
 
 export interface MessageStore {
   loadThread: (threadId: string) => Promise<Array<ModelMessage>>
@@ -37,16 +44,41 @@ export interface InterruptRecord {
   interruptId: string
   runId: string
   threadId: string
+  generation: number
   status: 'pending' | 'resolved' | 'cancelled'
   requestedAt: number
   resolvedAt?: number
-  payload: Record<string, unknown>
+  payload: unknown
+  binding: InterruptBinding
   response?: unknown
 }
 
-export interface InterruptStore {
-  create: (record: Omit<InterruptRecord, 'resolvedAt'>) => Promise<void>
+export interface InterruptBatchRecord {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  expectedInterruptIds: ReadonlyArray<string>
+  fingerprint: string
+  canonicalResolutions: string
+  resolutions: ReadonlyArray<RunAgentResumeItem>
+  continuationRunId: string
+  committedAt: number
+}
+
+export type LegacyInterruptRecordInput = Omit<
+  InterruptRecord,
+  'binding' | 'generation' | 'resolvedAt'
+> & {
+  binding?: InterruptBinding
+  generation?: number
+}
+
+export interface InterruptStore extends InterruptPersistenceGateway {
+  /** @deprecated Use openInterruptBatch for native interrupt writes. */
+  create: (record: LegacyInterruptRecordInput) => Promise<void>
+  /** @deprecated Use commitInterruptResolutions for native interrupt writes. */
   resolve: (interruptId: string, response?: unknown) => Promise<void>
+  /** @deprecated Use commitInterruptResolutions for native interrupt writes. */
   cancel: (interruptId: string) => Promise<void>
   get: (interruptId: string) => Promise<InterruptRecord | null>
   list: (threadId: string) => Promise<Array<InterruptRecord>>
@@ -271,6 +303,17 @@ function assertKnownStoreKeys(stores: object, location: string): void {
 
 export function validatePersistenceStoreKeys(persistence: AIPersistence): void {
   assertKnownStoreKeys(persistence.stores, 'store')
+  const interrupts = persistence.stores.interrupts
+  if (
+    interrupts !== undefined &&
+    (typeof interrupts.openInterruptBatch !== 'function' ||
+      typeof interrupts.commitInterruptResolutions !== 'function' ||
+      typeof interrupts.getInterruptRecoveryState !== 'function')
+  ) {
+    throw new Error(
+      'atomic-commit-unsupported: stores.interrupts must implement the atomic interrupt gateway.',
+    )
+  }
 }
 
 export function validateChatPersistenceStores(
diff --git a/packages/ai-persistence/tests/interrupts.test.ts b/packages/ai-persistence/tests/interrupts.test.ts
index f900b180d..17b9df248 100644
--- a/packages/ai-persistence/tests/interrupts.test.ts
+++ b/packages/ai-persistence/tests/interrupts.test.ts
@@ -1,610 +1,930 @@
 import { describe, expect, it, vi } from 'vitest'
-import { EventType, chat } from '@tanstack/ai'
-import type { AnyTextAdapter, StreamChunk, Tool } from '@tanstack/ai'
+import {
+  EventType,
+  canonicalInterruptJson,
+  digestInterruptJson,
+  chat,
+  hashSchemaInput,
+  normalizeApprovalSchema,
+  toolDefinition,
+} from '@tanstack/ai'
+import {
+  createInterruptRecoveryHandler,
+  getInterruptRecoveryState,
+} from '../src'
 import { memoryPersistence } from '../src/memory'
-import { withChatPersistence } from '../src/middleware'
+import {
+  validateInterruptResumeBatch,
+  withChatPersistence,
+} from '../src/middleware'
+import type {
+  AnyTextAdapter,
+  InterruptBinding,
+  SchemaInput,
+  StreamChunk,
+} from '@tanstack/ai'
+import type { InterruptRecord } from '../src'
+
+const bindingMetadataKey = 'tanstack:interruptBinding'
 
 function mockAdapter(iterations: Array<Array<StreamChunk>>) {
   const calls: Array<unknown> = []
-  let i = 0
-  const adapter = {
+  let index = 0
+  const adapter: AnyTextAdapter = {
     kind: 'text',
     name: 'mock',
     model: 'test-model',
-    '~types': {},
-    chatStream: (opts: unknown) => {
-      calls.push(opts)
-      const chunks = iterations[i] ?? []
-      i++
+    '~types': {
+      providerOptions: {},
+      inputModalities: ['text'],
+      messageMetadataByModality: {
+        text: undefined,
+        image: undefined,
+        audio: undefined,
+        video: undefined,
+        document: undefined,
+      },
+      toolCapabilities: [],
+      toolCallMetadata: undefined,
+      systemPromptMetadata: undefined,
+    },
+    chatStream: (options) => {
+      calls.push(options)
+      const chunks = iterations[index] ?? []
+      index++
       return (async function* () {
-        for (const c of chunks) yield c
+        for (const chunk of chunks) yield chunk
       })()
     },
     structuredOutput: async () => ({ data: {}, rawText: '{}' }),
-  } as unknown as AnyTextAdapter
+  }
   return { adapter, calls }
 }
 
 async function collect(stream: AsyncIterable<StreamChunk>) {
-  const out: Array<StreamChunk> = []
-  for await (const c of stream) out.push(c)
-  return out
+  const chunks: Array<StreamChunk> = []
+  for await (const chunk of stream) chunks.push(chunk)
+  return chunks
 }
 
-const interruptFinished = (): StreamChunk => ({
-  type: EventType.RUN_FINISHED,
-  runId: 'r1',
-  threadId: 't1',
-  finishReason: 'tool_calls',
-  timestamp: 1,
-  outcome: {
-    type: 'interrupt',
-    interrupts: [
-      {
-        id: 'interrupt-1',
-        reason: 'tool_call',
-        message: 'Approve the tool call?',
-        toolCallId: 'tool-call-1',
-      },
-    ],
-  },
-})
-
-const runStarted = (): StreamChunk => ({
-  type: EventType.RUN_STARTED,
-  runId: 'r1',
-  threadId: 't1',
-  timestamp: 1,
-})
-
-const toolStart = (): StreamChunk => ({
-  type: EventType.TOOL_CALL_START,
-  toolCallId: 'tool-call-1',
-  toolCallName: 'clientSearch',
-  toolName: 'clientSearch',
-  timestamp: 1,
-})
-
-const toolArgs = (): StreamChunk => ({
-  type: EventType.TOOL_CALL_ARGS,
-  toolCallId: 'tool-call-1',
-  delta: '{"query":"test"}',
-  timestamp: 1,
-})
+const responseSchema = {
+  type: 'object',
+  properties: { value: { type: 'number' } },
+  required: ['value'],
+  additionalProperties: false,
+}
 
-const text = (delta: string): StreamChunk => ({
-  type: EventType.TEXT_MESSAGE_CONTENT,
-  messageId: 'm1',
-  delta,
-  timestamp: 1,
-})
+function responseSchemaHash(): string {
+  return digestInterruptJson(canonicalInterruptJson(responseSchema))
+}
 
-const runFinished = (runId = 'r1'): StreamChunk => ({
-  type: EventType.RUN_FINISHED,
-  runId,
-  threadId: 't1',
-  finishReason: 'stop',
-  timestamp: 1,
-})
+function interruptFinished(options?: {
+  includeBinding?: boolean
+}): StreamChunk {
+  return {
+    type: EventType.RUN_FINISHED,
+    runId: 'interrupted-run',
+    threadId: 'thread-1',
+    finishReason: 'tool_calls',
+    timestamp: 1,
+    outcome: {
+      type: 'interrupt',
+      interrupts: [
+        {
+          id: 'interrupt-1',
+          reason: 'generic',
+          responseSchema,
+          ...(options?.includeBinding === false
+            ? {}
+            : {
+                metadata: {
+                  [bindingMetadataKey]: {
+                    kind: 'generic',
+                    interruptId: 'interrupt-1',
+                    responseSchemaHash: responseSchemaHash(),
+                  },
+                },
+              }),
+        },
+      ],
+    },
+  }
+}
 
-const clientTool = (name: string): Tool => ({
-  name,
-  description: `${name} client tool`,
-})
+function successfulRun(runId: string): Array<StreamChunk> {
+  return [
+    {
+      type: EventType.RUN_STARTED,
+      runId,
+      threadId: 'thread-1',
+      timestamp: 1,
+    },
+    {
+      type: EventType.RUN_FINISHED,
+      runId,
+      threadId: 'thread-1',
+      finishReason: 'stop',
+      timestamp: 2,
+    },
+  ]
+}
 
-const approvalClientTool = (name: string): Tool => ({
-  ...clientTool(name),
-  needsApproval: true,
-})
+function pendingRecord(input: {
+  interruptId: string
+  binding: InterruptBinding
+  payload?: unknown
+}): InterruptRecord {
+  return {
+    interruptId: input.interruptId,
+    runId: 'interrupted-run',
+    threadId: 'thread-1',
+    generation: 1,
+    status: 'pending',
+    requestedAt: 1,
+    payload:
+      input.payload ??
+      ({
+        id: input.interruptId,
+        reason: 'generic',
+        responseSchema,
+      } satisfies Record<string, unknown>),
+    binding: input.binding,
+  }
+}
 
-describe('interrupt persistence', () => {
-  it('persists RUN_FINISHED interrupt outcomes as pending interrupt records', async () => {
+describe('authoritative interrupt persistence', () => {
+  it('opens one atomic batch before exposing an interrupt terminal', async () => {
     const persistence = memoryPersistence()
-    const { adapter } = mockAdapter([[runStarted(), interruptFinished()]])
+    const open = vi.spyOn(persistence.stores.interrupts!, 'openInterruptBatch')
+    const legacyCreate = vi.spyOn(persistence.stores.interrupts!, 'create')
+    const { adapter } = mockAdapter([
+      [interruptFinished({ includeBinding: true })],
+    ])
 
     const chunks = await collect(
       chat({
         adapter,
-        messages: [{ role: 'user', content: 'hi' }],
-        runId: 'r1',
-        threadId: 't1',
+        messages: [{ role: 'user', content: 'pause' }],
+        runId: 'interrupted-run',
+        threadId: 'thread-1',
         middleware: [withChatPersistence(persistence)],
       }) as AsyncIterable<StreamChunk>,
     )
 
-    const pending = await persistence.stores.interrupts!.listPending('t1')
-    expect(pending).toHaveLength(1)
-    expect(pending[0]?.interruptId).toBe('interrupt-1')
-    expect((await persistence.stores.runs!.get('r1'))?.status).toBe(
-      'interrupted',
-    )
-    // Persistence is state-only: it never stamps delivery cursors on the stream.
-    expect(chunks.every((chunk) => !('cursor' in chunk))).toBe(true)
+    expect(open).toHaveBeenCalledTimes(1)
+    expect(open).toHaveBeenCalledWith({
+      threadId: 'thread-1',
+      interruptedRunId: 'interrupted-run',
+      descriptors: expect.arrayContaining([
+        expect.objectContaining({ id: 'interrupt-1' }),
+      ]),
+      bindings: [
+        {
+          kind: 'generic',
+          interruptId: 'interrupt-1',
+          responseSchemaHash: responseSchemaHash(),
+        },
+      ],
+    })
+    expect(legacyCreate).not.toHaveBeenCalled()
+    expect(chunks.at(-1)).toMatchObject({
+      type: EventType.RUN_FINISHED,
+      outcome: { type: 'interrupt' },
+    })
   })
 
-  it('saves thread messages when a messages-enabled run pauses on an interrupt', async () => {
+  it('reports a terminal with no reserved server binding before visibility', async () => {
     const persistence = memoryPersistence()
-    const { adapter } = mockAdapter([[runStarted(), interruptFinished()]])
+    const { adapter } = mockAdapter([
+      [interruptFinished({ includeBinding: false })],
+    ])
 
-    await collect(
+    const chunks = await collect(
       chat({
         adapter,
-        messages: [{ role: 'user', content: 'hi' }],
-        runId: 'r1',
-        threadId: 't1',
+        messages: [{ role: 'user', content: 'pause' }],
+        runId: 'interrupted-run',
+        threadId: 'thread-1',
         middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
+        stream: true,
+      }),
     )
 
-    expect(await persistence.stores.messages!.loadThread('t1')).toEqual([
-      { role: 'user', content: 'hi' },
+    expect(chunks).toEqual([
+      expect.objectContaining({
+        type: EventType.RUN_ERROR,
+        'tanstack:interruptErrors': expect.arrayContaining([
+          expect.objectContaining({
+            scope: 'item',
+            interruptId: 'interrupt-1',
+            code: 'invalid-response-schema',
+          }),
+        ]),
+      }),
     ])
+    expect(
+      await persistence.stores.interrupts!.listPendingByRun('interrupted-run'),
+    ).toEqual([])
   })
 
-  it('does not persist duplicate records before terminal interrupt outcome', async () => {
-    const persistence = memoryPersistence()
-    const create = vi.spyOn(persistence.stores.interrupts!, 'create')
-    const { adapter } = mockAdapter([
-      [
-        runStarted(),
-        toolStart(),
-        toolArgs(),
+  it('reports duplicate, extra, missing, expiry, and payload failures together', async () => {
+    const expiredBinding: InterruptBinding = {
+      kind: 'generic',
+      interruptId: 'interrupt-a',
+      interruptedRunId: 'interrupted-run',
+      generation: 1,
+      responseSchemaHash: responseSchemaHash(),
+      expiresAt: '2026-07-13T10:00:00.000Z',
+    }
+    const missingBinding: InterruptBinding = {
+      kind: 'generic',
+      interruptId: 'interrupt-b',
+      interruptedRunId: 'interrupted-run',
+      generation: 1,
+      responseSchemaHash: responseSchemaHash(),
+    }
+
+    const result = await validateInterruptResumeBatch({
+      threadId: 'thread-1',
+      interruptedRunId: 'interrupted-run',
+      generation: 1,
+      pending: [
+        pendingRecord({ interruptId: 'interrupt-a', binding: expiredBinding }),
+        pendingRecord({ interruptId: 'interrupt-b', binding: missingBinding }),
+      ],
+      resume: [
         {
-          type: EventType.RUN_FINISHED,
-          runId: 'r1',
-          threadId: 't1',
-          finishReason: 'tool_calls',
-          timestamp: 1,
+          interruptId: 'interrupt-a',
+          status: 'resolved',
+          payload: { value: 'not-a-number' },
         },
+        { interruptId: 'interrupt-a', status: 'cancelled', payload: true },
+        { interruptId: 'interrupt-extra', status: 'resolved' },
       ],
-    ])
-
-    await collect(
-      chat({
-        adapter,
-        messages: [{ role: 'user', content: 'hi' }],
-        tools: [approvalClientTool('clientSearch')],
-        runId: 'r1',
-        threadId: 't1',
-        middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
-    )
+      tools: [],
+      now: Date.parse('2026-07-13T10:00:00.001Z'),
+    })
 
-    expect(create).toHaveBeenCalledTimes(1)
-    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
-      1,
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          scope: 'item',
+          interruptId: 'interrupt-a',
+          code: 'conflict',
+        }),
+        expect.objectContaining({
+          scope: 'item',
+          interruptId: 'interrupt-a',
+          code: 'expired',
+        }),
+        expect.objectContaining({
+          scope: 'item',
+          interruptId: 'interrupt-a',
+          code: 'invalid-payload',
+        }),
+        expect.objectContaining({
+          scope: 'item',
+          interruptId: 'interrupt-b',
+          code: 'unknown-interrupt',
+        }),
+        expect.objectContaining({
+          scope: 'item',
+          interruptId: 'interrupt-extra',
+          code: 'unknown-interrupt',
+        }),
+        expect.objectContaining({
+          scope: 'batch',
+          code: 'incomplete-batch',
+        }),
+      ]),
     )
   })
 
-  it('blocks normal new input while a thread has pending interrupts', async () => {
-    const persistence = memoryPersistence()
-    await persistence.stores.interrupts!.create({
-      interruptId: 'interrupt-1',
-      runId: 'old-run',
-      threadId: 't1',
-      status: 'pending',
-      requestedAt: 1,
-      payload: {},
+  it('rejects cancelled tool interrupts after removal or schema drift', async () => {
+    const original = toolDefinition({
+      name: 'transfer',
+      description: 'Transfer funds',
+      needsApproval: true,
+      inputSchema: {
+        type: 'object',
+        properties: { cents: { type: 'number' } },
+        required: ['cents'],
+        additionalProperties: false,
+      },
+    })
+    const drifted = toolDefinition({
+      name: 'transfer',
+      description: 'Transfer funds',
+      needsApproval: true,
+      inputSchema: {
+        type: 'object',
+        properties: { amount: { type: 'number' } },
+        required: ['amount'],
+        additionalProperties: false,
+      },
+    })
+    const approval = normalizeApprovalSchema(
+      original.approvalSchema,
+      original.inputSchema,
+    )
+    const toolBinding = (
+      interruptId: string,
+      toolName: string,
+    ): InterruptBinding => ({
+      kind: 'tool-approval',
+      interruptId,
+      interruptedRunId: 'interrupted-run',
+      generation: 1,
+      toolName,
+      toolCallId: `call-${interruptId}`,
+      originalArgs: { cents: 1 },
+      inputSchemaHash: hashSchemaInput(original.inputSchema),
+      approvalSchemaHash: approval.approvalSchemaHash,
+      responseSchemaHash: approval.responseSchemaHash,
+    })
+    const result = await validateInterruptResumeBatch({
+      threadId: 'thread-1',
+      interruptedRunId: 'interrupted-run',
+      generation: 1,
+      pending: [
+        pendingRecord({
+          interruptId: 'removed',
+          binding: toolBinding('removed', 'removed-tool'),
+          payload: {
+            id: 'removed',
+            reason: 'tool_call',
+            responseSchema: approval.responseSchema,
+          },
+        }),
+        pendingRecord({
+          interruptId: 'drifted',
+          binding: toolBinding('drifted', 'transfer'),
+          payload: {
+            id: 'drifted',
+            reason: 'tool_call',
+            responseSchema: approval.responseSchema,
+          },
+        }),
+      ],
+      resume: [
+        { interruptId: 'removed', status: 'cancelled' },
+        { interruptId: 'drifted', status: 'cancelled' },
+      ],
+      tools: [drifted],
     })
-    const { adapter } = mockAdapter([[interruptFinished()]])
-
-    await expect(
-      collect(
-        chat({
-          adapter,
-          messages: [{ role: 'user', content: 'new input' }],
-          runId: 'r2',
-          threadId: 't1',
-          middleware: [withChatPersistence(persistence)],
-        }) as AsyncIterable<StreamChunk>,
-      ),
-    ).rejects.toThrow(/pending interrupt/i)
 
-    expect(await persistence.stores.runs!.get('r2')).toBeNull()
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ interruptId: 'removed', code: 'stale' }),
+        expect.objectContaining({ interruptId: 'drifted', code: 'stale' }),
+      ]),
+    )
+    expect(result.resolutions).toBeUndefined()
   })
 
-  it('treats resume entries as interrupt continuation on the same run', async () => {
-    const persistence = memoryPersistence()
-    const first = mockAdapter([[runStarted(), interruptFinished()]])
-    await collect(
-      chat({
-        adapter: first.adapter,
-        messages: [{ role: 'user', content: 'hi' }],
-        runId: 'r1',
-        threadId: 't1',
-        middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
-    )
-    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
-      1,
+  it('awaits async Standard Schema approval validation', async () => {
+    const asyncPayloadSchema = {
+      '~standard': {
+        version: 1,
+        vendor: 'interrupt-test',
+        validate: async (value: unknown) => {
+          await Promise.resolve()
+          if (
+            value !== null &&
+            typeof value === 'object' &&
+            'note' in value &&
+            typeof value.note === 'string'
+          ) {
+            return { value: { note: value.note } }
+          }
+          return {
+            issues: [{ message: 'Expected a note.', path: ['note'] }],
+          }
+        },
+      },
+    } satisfies SchemaInput
+    const tool = toolDefinition({
+      name: 'transfer',
+      description: 'Transfer funds',
+      needsApproval: true,
+      approvalSchema: { approve: asyncPayloadSchema },
+    })
+    const approval = normalizeApprovalSchema(
+      tool.approvalSchema,
+      tool.inputSchema,
     )
+    const binding: InterruptBinding = {
+      kind: 'tool-approval',
+      interruptId: 'approval',
+      interruptedRunId: 'interrupted-run',
+      generation: 1,
+      toolName: tool.name,
+      toolCallId: 'call-approval',
+      originalArgs: {},
+      inputSchemaHash: hashSchemaInput(tool.inputSchema),
+      approvalSchemaHash: approval.approvalSchemaHash,
+      responseSchemaHash: approval.responseSchemaHash,
+    }
+
+    const result = await validateInterruptResumeBatch({
+      threadId: 'thread-1',
+      interruptedRunId: 'interrupted-run',
+      generation: 1,
+      pending: [
+        pendingRecord({
+          interruptId: 'approval',
+          binding,
+          payload: {
+            id: 'approval',
+            reason: 'tool_call',
+            responseSchema: approval.responseSchema,
+          },
+        }),
+      ],
+      resume: [
+        {
+          interruptId: 'approval',
+          status: 'resolved',
+          payload: { approved: true, payload: {} },
+        },
+      ],
+      tools: [tool],
+    })
 
-    const continuation = mockAdapter([
-      [runStarted(), text('continued'), runFinished('r1')],
+    expect(result.errors).toEqual([
+      expect.objectContaining({
+        scope: 'item',
+        interruptId: 'approval',
+        code: 'invalid-payload',
+        path: ['note'],
+      }),
+      expect.objectContaining({
+        scope: 'batch',
+        code: 'item-validation-failed',
+      }),
     ])
-    const chunks = await collect(
-      chat({
-        adapter: continuation.adapter,
-        messages: [],
-        runId: 'r1',
-        threadId: 't1',
+  })
+
+  it.each([
+    ['approve', true],
+    ['reject', false],
+  ] as const)(
+    'rejects a boolean %s decision when that branch requires a payload',
+    async (_branch, approved) => {
+      const tool = toolDefinition({
+        name: 'transfer',
+        description: 'Transfer funds',
+        needsApproval: true,
+        approvalSchema: {
+          approve: {
+            type: 'object',
+            properties: { note: { type: 'string' } },
+            required: ['note'],
+            additionalProperties: false,
+          },
+          reject: {
+            type: 'object',
+            properties: { reason: { type: 'string' } },
+            required: ['reason'],
+            additionalProperties: false,
+          },
+        },
+      })
+      const approval = normalizeApprovalSchema(
+        tool.approvalSchema,
+        tool.inputSchema,
+      )
+      const binding: InterruptBinding = {
+        kind: 'tool-approval',
+        interruptId: 'approval',
+        interruptedRunId: 'interrupted-run',
+        generation: 1,
+        toolName: tool.name,
+        toolCallId: 'call-approval',
+        originalArgs: {},
+        inputSchemaHash: hashSchemaInput(tool.inputSchema),
+        approvalSchemaHash: approval.approvalSchemaHash,
+        responseSchemaHash: approval.responseSchemaHash,
+      }
+
+      const result = await validateInterruptResumeBatch({
+        threadId: 'thread-1',
+        interruptedRunId: 'interrupted-run',
+        generation: 1,
+        pending: [
+          pendingRecord({
+            interruptId: 'approval',
+            binding,
+            payload: {
+              id: 'approval',
+              reason: 'tool_call',
+              responseSchema: approval.responseSchema,
+            },
+          }),
+        ],
         resume: [
           {
-            interruptId: 'interrupt-1',
+            interruptId: 'approval',
             status: 'resolved',
-            payload: { approved: true },
+            payload: approved,
           },
         ],
-        middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
-    )
-
-    expect(continuation.calls).toHaveLength(1)
-    expect(chunks).toContainEqual(
-      expect.objectContaining({ delta: 'continued' }),
-    )
-    expect(await persistence.stores.interrupts!.listPending('t1')).toEqual([])
-    expect(
-      (await persistence.stores.interrupts!.get('interrupt-1'))?.status,
-    ).toBe('resolved')
-  })
+        tools: [tool],
+      })
+
+      expect(result.errors).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            scope: 'item',
+            interruptId: 'approval',
+            code: 'invalid-payload',
+          }),
+          expect.objectContaining({
+            scope: 'batch',
+            code: 'item-validation-failed',
+          }),
+        ]),
+      )
+    },
+  )
 
-  it('applies persisted approval and client-tool resume decisions with empty client messages', async () => {
+  it('commits one CAS batch with parent and continuation run correlation', async () => {
     const persistence = memoryPersistence()
-    const toolCallChunks = () => [
-      runStarted(),
-      toolStart(),
-      toolArgs(),
-      {
-        type: EventType.RUN_FINISHED,
-        runId: 'r1',
-        threadId: 't1',
-        finishReason: 'tool_calls',
-        timestamp: 1,
-      } as StreamChunk,
-    ]
-    const first = mockAdapter([toolCallChunks()])
-    await collect(
-      chat({
-        adapter: first.adapter,
-        messages: [{ role: 'user', content: 'hi' }],
-        tools: [approvalClientTool('clientSearch')],
-        runId: 'r1',
-        threadId: 't1',
-        middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
-    )
-
-    const approvalInterrupt = await persistence.stores.interrupts!.get(
-      'approval_tool-call-1',
+    await persistence.stores.interrupts!.openInterruptBatch({
+      threadId: 'thread-1',
+      interruptedRunId: 'interrupted-run',
+      descriptors: [{ id: 'interrupt-1', reason: 'generic', responseSchema }],
+      bindings: [
+        {
+          kind: 'generic',
+          interruptId: 'interrupt-1',
+          responseSchemaHash: responseSchemaHash(),
+        },
+      ],
+    })
+    const commit = vi.spyOn(
+      persistence.stores.interrupts!,
+      'commitInterruptResolutions',
     )
-    expect(approvalInterrupt?.status).toBe('pending')
+    const { adapter } = mockAdapter([successfulRun('continuation-run')])
 
-    const afterApproval = mockAdapter([toolCallChunks()])
-    const approvalChunks = await collect(
+    await collect(
       chat({
-        adapter: afterApproval.adapter,
+        adapter,
         messages: [],
-        tools: [approvalClientTool('clientSearch')],
-        runId: 'r1',
-        threadId: 't1',
+        runId: 'continuation-run',
+        parentRunId: 'interrupted-run',
+        threadId: 'thread-1',
         resume: [
           {
-            interruptId: 'approval_tool-call-1',
+            interruptId: 'interrupt-1',
             status: 'resolved',
-            payload: { approved: true },
+            payload: { value: 42 },
           },
         ],
         middleware: [withChatPersistence(persistence)],
       }) as AsyncIterable<StreamChunk>,
     )
 
-    expect(afterApproval.calls).toHaveLength(1)
-    expect(
-      (
-        afterApproval.calls[0] as { approvals?: ReadonlyMap<string, boolean> }
-      ).approvals?.get('approval_tool-call-1'),
-    ).toBe(true)
-    expect(
-      approvalChunks.find(
-        (chunk) =>
-          chunk.type === EventType.RUN_FINISHED &&
-          chunk.outcome?.type === 'interrupt',
-      ),
-    ).toMatchObject({
-      outcome: {
-        interrupts: [
+    expect(commit).toHaveBeenCalledTimes(1)
+    expect(commit).toHaveBeenCalledWith(
+      expect.objectContaining({
+        threadId: 'thread-1',
+        interruptedRunId: 'interrupted-run',
+        continuationRunId: 'continuation-run',
+        expectedGeneration: 1,
+        expectedInterruptIds: ['interrupt-1'],
+      }),
+    )
+  })
+
+  it('uses authoritative stored messages instead of tampered continuation arguments', async () => {
+    const persistence = memoryPersistence()
+    const execute = vi.fn().mockImplementation((input) => input)
+    const defined = toolDefinition({
+      name: 'transfer',
+      description: 'Transfer funds',
+      needsApproval: true,
+      inputSchema: {
+        type: 'object',
+        properties: { cents: { type: 'number' } },
+        required: ['cents'],
+        additionalProperties: false,
+      },
+    })
+    const tool = { ...defined, execute }
+    const approval = normalizeApprovalSchema(
+      defined.approvalSchema,
+      defined.inputSchema,
+    )
+    const storedMessages = [
+      { role: 'user' as const, content: 'Transfer one dollar' },
+      {
+        role: 'assistant' as const,
+        content: '',
+        toolCalls: [
           {
-            id: 'client_tool_tool-call-1',
-            reason: 'client_tool_input',
-            toolCallId: 'tool-call-1',
+            id: 'call-transfer',
+            type: 'function' as const,
+            function: {
+              name: 'transfer',
+              arguments: '{"cents":100}',
+            },
           },
         ],
       },
+    ]
+    await persistence.stores.messages!.saveThread('thread-1', storedMessages)
+    await persistence.stores.interrupts!.openInterruptBatch({
+      threadId: 'thread-1',
+      interruptedRunId: 'interrupted-run',
+      descriptors: [
+        {
+          id: 'approval_call-transfer',
+          reason: 'tool_call',
+          toolCallId: 'call-transfer',
+          responseSchema: approval.responseSchema,
+        },
+      ],
+      bindings: [
+        {
+          kind: 'tool-approval',
+          interruptId: 'approval_call-transfer',
+          toolName: 'transfer',
+          toolCallId: 'call-transfer',
+          originalArgs: { cents: 100 },
+          inputSchemaHash: hashSchemaInput(defined.inputSchema),
+          approvalSchemaHash: approval.approvalSchemaHash,
+          responseSchemaHash: approval.responseSchemaHash,
+        },
+      ],
     })
-    expect(
-      (await persistence.stores.interrupts!.get('approval_tool-call-1'))
-        ?.status,
-    ).toBe('resolved')
-    expect(
-      (await persistence.stores.interrupts!.get('client_tool_tool-call-1'))
-        ?.status,
-    ).toBe('pending')
+    const { adapter } = mockAdapter([successfulRun('continuation-run')])
 
-    const afterClientTool = mockAdapter([
-      toolCallChunks(),
-      [runStarted(), text('done'), runFinished('r1')],
-    ])
-    const finalChunks = await collect(
+    await collect(
       chat({
-        adapter: afterClientTool.adapter,
-        messages: [],
-        tools: [clientTool('clientSearch')],
-        runId: 'r1',
-        threadId: 't1',
+        adapter,
+        messages: [
+          { role: 'user', content: 'Transfer one dollar' },
+          {
+            role: 'assistant',
+            content: '',
+            toolCalls: [
+              {
+                id: 'call-transfer',
+                type: 'function',
+                function: {
+                  name: 'transfer',
+                  arguments: '{"cents":999999}',
+                },
+              },
+            ],
+          },
+        ],
+        tools: [tool],
+        runId: 'continuation-run',
+        parentRunId: 'interrupted-run',
+        threadId: 'thread-1',
         resume: [
           {
-            interruptId: 'client_tool_tool-call-1',
+            interruptId: 'approval_call-transfer',
             status: 'resolved',
-            payload: { answer: 42 },
+            payload: true,
           },
         ],
         middleware: [withChatPersistence(persistence)],
       }) as AsyncIterable<StreamChunk>,
     )
 
-    expect(afterClientTool.calls).toHaveLength(2)
-    expect(finalChunks).toContainEqual(
-      expect.objectContaining({
-        type: EventType.TOOL_CALL_RESULT,
-        toolCallId: 'tool-call-1',
-        content: JSON.stringify({ answer: 42 }),
-      }),
-    )
-    expect(finalChunks).toContainEqual(
-      expect.objectContaining({ delta: 'done' }),
-    )
-    expect(await persistence.stores.interrupts!.listPending('t1')).toEqual([])
+    expect(execute).toHaveBeenCalledWith({ cents: 100 }, expect.any(Object))
   })
 
-  it('rejects invalid resume entries against pending interrupts', async () => {
+  it('persists the complete native interrupt transcript for authoritative resume', async () => {
     const persistence = memoryPersistence()
-    const first = mockAdapter([[runStarted(), interruptFinished()]])
+    const { adapter } = mockAdapter([
+      [
+        {
+          type: EventType.RUN_STARTED,
+          runId: 'interrupted-run',
+          threadId: 'thread-1',
+          timestamp: 1,
+        },
+        {
+          type: EventType.TOOL_CALL_START,
+          toolCallId: 'call-transfer',
+          toolCallName: 'transfer',
+          toolName: 'transfer',
+          timestamp: 1,
+        },
+        {
+          type: EventType.TOOL_CALL_ARGS,
+          toolCallId: 'call-transfer',
+          delta: '{"cents":100}',
+          timestamp: 1,
+        },
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'interrupted-run',
+          threadId: 'thread-1',
+          finishReason: 'tool_calls',
+          timestamp: 2,
+        },
+      ],
+    ])
+
     await collect(
       chat({
-        adapter: first.adapter,
-        messages: [{ role: 'user', content: 'hi' }],
-        runId: 'r1',
-        threadId: 't1',
+        adapter,
+        messages: [{ role: 'user', content: 'Transfer one dollar' }],
+        tools: [
+          {
+            name: 'transfer',
+            description: 'Transfer funds',
+            needsApproval: true,
+            execute: (input: unknown) => input,
+          },
+        ],
+        runId: 'interrupted-run',
+        threadId: 'thread-1',
         middleware: [withChatPersistence(persistence)],
       }) as AsyncIterable<StreamChunk>,
     )
 
-    const continuation = mockAdapter([[text('SHOULD NOT RUN')]])
-    await expect(
-      collect(
-        chat({
-          adapter: continuation.adapter,
-          messages: [],
-          runId: 'r1',
-          threadId: 't1',
-          resume: [],
-          middleware: [withChatPersistence(persistence)],
-        }) as AsyncIterable<StreamChunk>,
-      ),
-    ).rejects.toThrow(/pending interrupts.*resume is required/i)
-
-    await expect(
-      collect(
-        chat({
-          adapter: continuation.adapter,
-          messages: [],
-          runId: 'r1',
-          threadId: 't1',
-          resume: [{ interruptId: 'stale-interrupt', status: 'resolved' }],
-          middleware: [withChatPersistence(persistence)],
-        }) as AsyncIterable<StreamChunk>,
-      ),
-    ).rejects.toThrow(/missing resume entry.*interrupt-1/i)
-
-    expect(continuation.calls).toHaveLength(0)
-    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
-      1,
+    expect(await persistence.stores.messages!.loadThread('thread-1')).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          role: 'assistant',
+          toolCalls: [
+            expect.objectContaining({
+              id: 'call-transfer',
+              function: expect.objectContaining({
+                name: 'transfer',
+                arguments: '{"cents":100}',
+              }),
+            }),
+          ],
+        }),
+      ]),
     )
   })
+})
 
-  it('rejects stale resume entries when a thread has no pending interrupts', async () => {
+describe('interrupt recovery', () => {
+  it('restores the trusted binding metadata for pending descriptors', async () => {
     const persistence = memoryPersistence()
-    const first = mockAdapter([[runStarted(), text('done'), runFinished()]])
-    await collect(
-      chat({
-        adapter: first.adapter,
-        messages: [{ role: 'user', content: 'hi' }],
-        runId: 'r1',
-        threadId: 't1',
-        middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
-    )
-    expect(await persistence.stores.interrupts!.listPending('t1')).toEqual([])
-
-    const continuation = mockAdapter([[text('SHOULD NOT RUN')]])
-    await expect(
-      collect(
-        chat({
-          adapter: continuation.adapter,
-          messages: [],
-          runId: 'r1',
-          threadId: 't1',
-          resume: [{ interruptId: 'stale-interrupt', status: 'resolved' }],
-          middleware: [withChatPersistence(persistence)],
-        }) as AsyncIterable<StreamChunk>,
-      ),
-    ).rejects.toThrow(/non-pending interrupt stale-interrupt/i)
+    await persistence.stores.interrupts!.openInterruptBatch({
+      threadId: 'thread-1',
+      interruptedRunId: 'interrupted-run',
+      descriptors: [{ id: 'interrupt-1', reason: 'generic', responseSchema }],
+      bindings: [
+        {
+          kind: 'generic',
+          interruptId: 'interrupt-1',
+          responseSchemaHash: responseSchemaHash(),
+        },
+      ],
+    })
+
+    const state =
+      await persistence.stores.interrupts!.getInterruptRecoveryState({
+        threadId: 'thread-1',
+        interruptedRunId: 'interrupted-run',
+        knownGeneration: 1,
+      })
 
-    expect(continuation.calls).toHaveLength(0)
+    expect(state.pendingInterrupts).toEqual([
+      expect.objectContaining({
+        id: 'interrupt-1',
+        metadata: {
+          [bindingMetadataKey]: {
+            kind: 'generic',
+            interruptId: 'interrupt-1',
+            interruptedRunId: 'interrupted-run',
+            generation: 1,
+            responseSchemaHash: responseSchemaHash(),
+          },
+        },
+      }),
+    ])
   })
 
-  it('accepts resume only when every pending interrupt has a valid matching entry', async () => {
+  it('requires authorization and can redact committed resolutions', async () => {
     const persistence = memoryPersistence()
-    await persistence.stores.interrupts!.create({
+    await persistence.stores.interrupts!.openInterruptBatch({
+      threadId: 'thread-1',
+      interruptedRunId: 'interrupted-run',
+      descriptors: [{ id: 'interrupt-1', reason: 'generic', responseSchema }],
+      bindings: [
+        {
+          kind: 'generic',
+          interruptId: 'interrupt-1',
+          responseSchemaHash: responseSchemaHash(),
+        },
+      ],
+    })
+    const resolution = {
       interruptId: 'interrupt-1',
-      runId: 'old-run',
-      threadId: 't1',
-      status: 'pending',
-      requestedAt: 1,
-      payload: {},
+      status: 'resolved' as const,
+      payload: { value: 42 },
+    }
+    const canonical = canonicalInterruptJson([resolution])
+    await persistence.stores.interrupts!.commitInterruptResolutions({
+      threadId: 'thread-1',
+      interruptedRunId: 'interrupted-run',
+      continuationRunId: 'continuation-run',
+      expectedGeneration: 1,
+      expectedInterruptIds: ['interrupt-1'],
+      resolutions: [resolution],
+      canonicalResolutions: canonical,
+      fingerprint: digestInterruptJson(canonical),
     })
-    const bad = mockAdapter([[runStarted(), interruptFinished()]])
-
-    await expect(
-      collect(
-        chat({
-          adapter: bad.adapter,
-          messages: [{ role: 'user', content: 'new input' }],
-          runId: 'r2',
-          threadId: 't1',
-          resume: [{ interruptId: 'different', status: 'resolved' }],
-          middleware: [withChatPersistence(persistence)],
-        }) as AsyncIterable<StreamChunk>,
-      ),
-    ).rejects.toThrow(/missing resume entry.*interrupt-1/i)
 
-    const good = mockAdapter([
-      [runStarted(), { ...interruptFinished(), runId: 'r2' }],
-    ])
-    await collect(
-      chat({
-        adapter: good.adapter,
-        messages: [{ role: 'user', content: 'new input' }],
-        runId: 'r2',
-        threadId: 't1',
-        resume: [{ interruptId: 'interrupt-1', status: 'resolved' }],
-        middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
+    const redacted = await getInterruptRecoveryState(
+      persistence.stores.interrupts!,
+      {
+        threadId: 'thread-1',
+        interruptedRunId: 'interrupted-run',
+        knownGeneration: 1,
+      },
     )
+    expect(redacted.committed).not.toHaveProperty('resolutions')
 
-    expect(good.calls).toHaveLength(1)
-  })
-
-  it('rejects extra stale resume entries when pending interrupts are satisfied', async () => {
-    const persistence = memoryPersistence()
-    await persistence.stores.interrupts!.create({
-      interruptId: 'interrupt-1',
-      runId: 'old-run',
-      threadId: 't1',
-      status: 'pending',
-      requestedAt: 1,
-      payload: {},
+    const handler = createInterruptRecoveryHandler({
+      gateway: persistence.stores.interrupts!,
+      authorize: async (_request, _input) => ({
+        authorized: true,
+        includeResolutions: false,
+      }),
     })
-    const run = mockAdapter([[text('SHOULD NOT RUN')]])
-
-    await expect(
-      collect(
-        chat({
-          adapter: run.adapter,
-          messages: [{ role: 'user', content: 'new input' }],
-          runId: 'r2',
-          threadId: 't1',
-          resume: [
-            { interruptId: 'interrupt-1', status: 'resolved' },
-            { interruptId: 'stale-interrupt', status: 'resolved' },
-          ],
-          middleware: [withChatPersistence(persistence)],
-        }) as AsyncIterable<StreamChunk>,
+    const response = await handler(
+      new Request(
+        'https://example.test/recovery?threadId=thread-1&interruptedRunId=interrupted-run&knownGeneration=1',
       ),
-    ).rejects.toThrow(/non-pending interrupt stale-interrupt/i)
-
-    expect(run.calls).toHaveLength(0)
-    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
-      1,
     )
+    expect(response.status).toBe(200)
+    expect(handler).toBeTypeOf('function')
+    expect(await response.json()).toMatchObject({
+      state: 'committed',
+      committed: { continuationRunId: 'continuation-run' },
+    })
   })
 
-  it('applies valid resume entries and allows later normal input', async () => {
+  it('validates the recovery query before resource authorization', async () => {
     const persistence = memoryPersistence()
-    await persistence.stores.interrupts!.create({
-      interruptId: 'resolve-me',
-      runId: 'old-run',
-      threadId: 't1',
-      status: 'pending',
-      requestedAt: 1,
-      payload: {},
-    })
-    await persistence.stores.interrupts!.create({
-      interruptId: 'cancel-me',
-      runId: 'old-run',
-      threadId: 't1',
-      status: 'pending',
-      requestedAt: 1,
-      payload: {},
+    const authorize = vi.fn(() => ({
+      authorized: true,
+      includeResolutions: false,
+    }))
+    const handler = createInterruptRecoveryHandler({
+      gateway: persistence.stores.interrupts!,
+      authorize,
     })
-
-    const resumeRun = mockAdapter([
-      [runStarted(), text('ok'), runFinished('r2')],
-    ])
-    await collect(
-      chat({
-        adapter: resumeRun.adapter,
-        messages: [{ role: 'user', content: 'resume' }],
-        runId: 'r2',
-        threadId: 't1',
-        resume: [
-          {
-            interruptId: 'resolve-me',
-            status: 'resolved',
-            payload: { approved: true },
-          },
-          { interruptId: 'cancel-me', status: 'cancelled' },
-        ],
-        middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
+    const request = new Request(
+      'https://example.test/recovery?threadId=thread-1&knownGeneration=1',
     )
 
-    expect(await persistence.stores.interrupts!.listPending('t1')).toEqual([])
-    expect(
-      (await persistence.stores.interrupts!.get('resolve-me'))?.status,
-    ).toBe('resolved')
-    expect(
-      (await persistence.stores.interrupts!.get('resolve-me'))?.response,
-    ).toEqual({ approved: true })
-    expect(
-      (await persistence.stores.interrupts!.get('cancel-me'))?.status,
-    ).toBe('cancelled')
+    const response = await handler(request)
 
-    const nextRun = mockAdapter([
-      [runStarted(), text('next'), runFinished('r3')],
-    ])
-    await collect(
-      chat({
-        adapter: nextRun.adapter,
-        messages: [{ role: 'user', content: 'next' }],
-        runId: 'r3',
-        threadId: 't1',
-        middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
-    )
-    expect(nextRun.calls).toHaveLength(1)
+    expect(response.status).toBe(400)
+    expect(authorize).not.toHaveBeenCalled()
   })
 
-  it('marks terminal interrupt outcomes as interrupted', async () => {
+  it('passes the validated resource identity to authorization', async () => {
     const persistence = memoryPersistence()
-    const { adapter } = mockAdapter([[runStarted(), interruptFinished()]])
-
-    await collect(
-      chat({
-        adapter,
-        messages: [{ role: 'user', content: 'hi' }],
-        runId: 'r1',
-        threadId: 't1',
-        middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
+    const authorize = vi.fn(() => ({ authorized: false }) as const)
+    const handler = createInterruptRecoveryHandler({
+      gateway: persistence.stores.interrupts!,
+      authorize,
+    })
+    const request = new Request(
+      'https://example.test/recovery?threadId=thread-1&interruptedRunId=interrupted-run&knownGeneration=2',
     )
 
-    expect((await persistence.stores.runs!.get('r1'))?.status).toBe(
-      'interrupted',
+    await handler(request)
+
+    expect(authorize).toHaveBeenCalledWith(request, {
+      threadId: 'thread-1',
+      interruptedRunId: 'interrupted-run',
+      knownGeneration: 2,
+    })
+  })
+
+  it('does not query recovery state when authorization is denied', async () => {
+    const persistence = memoryPersistence()
+    const recovery = vi.spyOn(
+      persistence.stores.interrupts!,
+      'getInterruptRecoveryState',
     )
-    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
-      1,
+    const handler = createInterruptRecoveryHandler({
+      gateway: persistence.stores.interrupts!,
+      authorize: () => ({ authorized: false }),
+    })
+    const response = await handler(
+      new Request(
+        'https://example.test/recovery?threadId=thread-1&interruptedRunId=interrupted-run&knownGeneration=1',
+      ),
     )
+    expect(response.status).toBe(401)
+    expect(recovery).not.toHaveBeenCalled()
   })
 })
diff --git a/packages/ai-persistence/tests/memory.conformance.test.ts b/packages/ai-persistence/tests/memory.conformance.test.ts
index 0b382b6a0..d2d2a0238 100644
--- a/packages/ai-persistence/tests/memory.conformance.test.ts
+++ b/packages/ai-persistence/tests/memory.conformance.test.ts
@@ -1,4 +1,57 @@
-import { runPersistenceConformance } from '../src/testkit/conformance'
+import {
+  runInterruptStoreConformance,
+  runPersistenceConformance,
+  type InterruptConformanceHarness,
+} from '../src/testkit/conformance'
 import { memoryPersistence } from '../src/memory'
+import type { InterruptStore } from '../src/types'
 
 runPersistenceConformance('memory', () => memoryPersistence())
+
+runInterruptStoreConformance(async (): Promise<InterruptConformanceHarness> => {
+  let now = Date.parse('2026-07-13T10:00:00.000Z')
+  let failNextTransition = false
+  const persistence = memoryPersistence({ clock: () => now })
+  const base = persistence.stores.interrupts
+  const store: InterruptStore = {
+    create: (record) => base.create(record),
+    resolve: (interruptId, response) => base.resolve(interruptId, response),
+    cancel: (interruptId) => base.cancel(interruptId),
+    get: (interruptId) => base.get(interruptId),
+    list: (threadId) => base.list(threadId),
+    listPending: (threadId) => base.listPending(threadId),
+    listByRun: (runId) => base.listByRun(runId),
+    listPendingByRun: (runId) => base.listPendingByRun(runId),
+    openInterruptBatch: (input) => base.openInterruptBatch(input),
+    commitInterruptResolutions: (input) => {
+      if (failNextTransition) {
+        failNextTransition = false
+        return Promise.reject(new Error('Injected transition failure'))
+      }
+      return base.commitInterruptResolutions(input)
+    },
+    getInterruptRecoveryState: (input) => base.getInterruptRecoveryState(input),
+  }
+
+  return {
+    getStore: () => store,
+    advanceBy: (milliseconds) => {
+      now += milliseconds
+    },
+    inspect: async (interruptedRunId) => {
+      const rows = await base.listByRun(interruptedRunId)
+      const recovery = await base.getInterruptRecoveryState({
+        threadId: rows[0]?.threadId ?? 'thread-cas',
+        interruptedRunId,
+        knownGeneration: rows[0]?.generation ?? 1,
+      })
+      return {
+        statuses: rows.map((row) => row.status).sort(),
+        batchCount: recovery.state === 'committed' ? 1 : 0,
+      }
+    },
+    failTransitionOnce: () => {
+      failNextTransition = true
+    },
+  }
+})
diff --git a/packages/ai-persistence/tests/persistence-fixtures.ts b/packages/ai-persistence/tests/persistence-fixtures.ts
index 84e2a8e16..d1ff82de6 100644
--- a/packages/ai-persistence/tests/persistence-fixtures.ts
+++ b/packages/ai-persistence/tests/persistence-fixtures.ts
@@ -46,6 +46,22 @@ export function createRunStore(): RunStore {
 
 export function createInterruptStore(): InterruptStore {
   return {
+    openInterruptBatch: (input) =>
+      Promise.resolve({ generation: 1, descriptors: input.descriptors }),
+    commitInterruptResolutions: (input) =>
+      Promise.resolve({
+        status: 'committed',
+        continuationRunId: input.continuationRunId,
+      }),
+    getInterruptRecoveryState: (input) =>
+      Promise.resolve({
+        schemaVersion: 1,
+        state: 'missing',
+        threadId: input.threadId,
+        interruptedRunId: input.interruptedRunId,
+        generation: input.knownGeneration,
+        pendingInterrupts: [],
+      }),
     create: () => Promise.resolve(),
     resolve: () => Promise.resolve(),
     cancel: () => Promise.resolve(),
diff --git a/packages/ai-persistence/tests/persistence-validation.test.ts b/packages/ai-persistence/tests/persistence-validation.test.ts
index 5f03fc201..1bc961611 100644
--- a/packages/ai-persistence/tests/persistence-validation.test.ts
+++ b/packages/ai-persistence/tests/persistence-validation.test.ts
@@ -4,6 +4,14 @@ import {
   withGenerationPersistence,
 } from '../src/middleware'
 import type { AIPersistence } from '../src'
+import {
+  InterruptPersistenceCapability,
+  InterruptsCapability,
+  getInterruptPersistence,
+  getInterrupts,
+  provideInterruptPersistence,
+  provideInterrupts,
+} from '../src'
 import {
   createArtifactStore,
   createBlobStore,
@@ -13,6 +21,11 @@ import {
 } from './persistence-fixtures'
 
 describe('persistence store dependency validation', () => {
+  it('keeps deprecated interrupt capability names as exact core aliases', () => {
+    expect(InterruptsCapability).toBe(InterruptPersistenceCapability)
+    expect(getInterrupts).toBe(getInterruptPersistence)
+    expect(provideInterrupts).toBe(provideInterruptPersistence)
+  })
   it('rejects a dynamic chat persistence with interrupts but no runs', () => {
     const persistence: AIPersistence = {
       stores: { interrupts: createInterruptStore() },
@@ -44,6 +57,18 @@ describe('persistence store dependency validation', () => {
     expect(() => withChatPersistence(persistence)).not.toThrow()
   })
 
+  it('rejects a sequential interrupt store without the atomic gateway', () => {
+    const interrupts = createInterruptStore()
+    Reflect.deleteProperty(interrupts, 'commitInterruptResolutions')
+    const persistence: AIPersistence = {
+      stores: { runs: createRunStore(), interrupts },
+    }
+
+    expect(() => withChatPersistence(persistence)).toThrow(
+      /atomic-commit-unsupported/,
+    )
+  })
+
   it.each([
     ['artifacts', { artifacts: createArtifactStore() }],
     ['blobs', { blobs: createBlobStore() }],
diff --git a/packages/ai-persistence/tests/with-persistence.test.ts b/packages/ai-persistence/tests/with-persistence.test.ts
index 3065ae8ba..579527b29 100644
--- a/packages/ai-persistence/tests/with-persistence.test.ts
+++ b/packages/ai-persistence/tests/with-persistence.test.ts
@@ -1,21 +1,40 @@
 import { describe, expect, it } from 'vitest'
-import { EventType, chat } from '@tanstack/ai'
-import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import {
+  EventType,
+  canonicalInterruptJson,
+  chat,
+  defineChatMiddleware,
+  digestInterruptJson,
+} from '@tanstack/ai'
 import { memoryPersistence } from '../src/memory'
 import { withChatPersistence } from '../src/middleware'
 import { defineAIPersistence } from '../src/types'
+import type { AnyTextAdapter, StreamChunk, Tool } from '@tanstack/ai'
 
 // --- minimal mock text adapter ---------------------------------------------
 
 function mockAdapter(iterations: Array<Array<StreamChunk>>) {
   const calls: Array<unknown> = []
   let i = 0
-  const adapter = {
+  const adapter: AnyTextAdapter = {
     kind: 'text',
     name: 'mock',
     model: 'test-model',
-    '~types': {},
-    chatStream: (opts: unknown) => {
+    '~types': {
+      providerOptions: {},
+      inputModalities: ['text'],
+      messageMetadataByModality: {
+        text: undefined,
+        image: undefined,
+        audio: undefined,
+        video: undefined,
+        document: undefined,
+      },
+      toolCapabilities: [],
+      toolCallMetadata: undefined,
+      systemPromptMetadata: undefined,
+    },
+    chatStream: (opts) => {
       calls.push(opts)
       const chunks = iterations[i] ?? []
       i++
@@ -24,7 +43,7 @@ function mockAdapter(iterations: Array<Array<StreamChunk>>) {
       })()
     },
     structuredOutput: async () => ({ data: {}, rawText: '{}' }),
-  } as unknown as AnyTextAdapter
+  }
   return { adapter, calls }
 }
 
@@ -52,16 +71,34 @@ const ev = {
     type: EventType.RUN_FINISHED,
     runId: 'r1',
     threadId: 't1',
-    finishReason: 'stop',
+    finishReason: 'tool_calls',
     timestamp: 1,
     outcome: {
       type: 'interrupt',
       interrupts: [
         {
           id: interruptId,
-          reason: 'approval_required',
-          toolCallId: 'tool-1',
-          metadata: { kind: 'approval' },
+          reason: 'generic',
+          responseSchema: {
+            type: 'object',
+            properties: { value: { type: 'number' } },
+            required: ['value'],
+            additionalProperties: false,
+          },
+          metadata: {
+            'tanstack:interruptBinding': {
+              kind: 'generic',
+              interruptId,
+              responseSchemaHash: digestInterruptJson(
+                canonicalInterruptJson({
+                  type: 'object',
+                  properties: { value: { type: 'number' } },
+                  required: ['value'],
+                  additionalProperties: false,
+                }),
+              ),
+            },
+          },
         },
       ],
     },
@@ -74,11 +111,17 @@ async function collect(stream: AsyncIterable<StreamChunk>) {
   return out
 }
 
-async function expectCollectRejects(
+async function expectCollectInterruptError(
   stream: AsyncIterable<StreamChunk>,
   pattern: RegExp,
 ) {
-  await expect(collect(stream)).rejects.toThrow(pattern)
+  expect(await collect(stream)).toEqual([
+    expect.objectContaining({
+      type: EventType.RUN_ERROR,
+      message: expect.stringMatching(pattern),
+      'tanstack:interruptErrors': expect.any(Array),
+    }),
+  ])
 }
 
 describe('withChatPersistence (state-only)', () => {
@@ -131,6 +174,196 @@ describe('withChatPersistence (state-only)', () => {
     )
   })
 
+  it('emits only safe correlated bindings while persisting descriptors separately', async () => {
+    const persistence = memoryPersistence()
+    const approvalTool: Tool = {
+      name: 'dangerousAction',
+      description: 'Perform a dangerous action',
+      needsApproval: true,
+      inputSchema: {
+        type: 'object',
+        properties: { action: { type: 'string' } },
+        required: ['action'],
+        additionalProperties: false,
+      },
+      execute: ({ action }) => ({ action }),
+    }
+    const browserTool: Tool = {
+      name: 'browserAction',
+      description: 'Perform an action in the browser',
+      outputSchema: {
+        type: 'object',
+        properties: { ok: { type: 'boolean' } },
+        required: ['ok'],
+        additionalProperties: false,
+      },
+    }
+    const addPrivateBindingFields = defineChatMiddleware({
+      name: 'add-private-binding-fields',
+      onChunk(_ctx, chunk) {
+        if (
+          chunk.type !== EventType.RUN_FINISHED ||
+          chunk.outcome?.type !== 'interrupt'
+        ) {
+          return
+        }
+        return {
+          ...chunk,
+          outcome: {
+            ...chunk.outcome,
+            interrupts: chunk.outcome.interrupts.map((interrupt) => ({
+              ...interrupt,
+              metadata: {
+                ...interrupt.metadata,
+                'tanstack:interruptBinding': {
+                  ...interrupt.metadata?.['tanstack:interruptBinding'],
+                  authorizationToken: 'must-not-leak',
+                  internal: { serverOnly: true },
+                },
+              },
+            })),
+          },
+        }
+      },
+    })
+
+    async function runInterrupt(input: {
+      runId: string
+      threadId: string
+      toolCallId: string
+      tool: Tool
+      args: string
+    }) {
+      const { adapter } = mockAdapter([
+        [
+          ev.runStarted(input.runId, input.threadId),
+          {
+            type: EventType.TOOL_CALL_START,
+            toolCallId: input.toolCallId,
+            toolCallName: input.tool.name,
+            toolName: input.tool.name,
+            timestamp: 1,
+          },
+          {
+            type: EventType.TOOL_CALL_ARGS,
+            toolCallId: input.toolCallId,
+            delta: input.args,
+            timestamp: 1,
+          },
+          {
+            type: EventType.RUN_FINISHED,
+            runId: input.runId,
+            threadId: input.threadId,
+            finishReason: 'tool_calls',
+            timestamp: 1,
+          },
+        ],
+      ])
+      const chunks = await collect(
+        chat({
+          adapter,
+          messages: [{ role: 'user', content: 'pause' }],
+          runId: input.runId,
+          threadId: input.threadId,
+          tools: [input.tool],
+          middleware: [
+            withChatPersistence(persistence),
+            addPrivateBindingFields,
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      )
+      const terminal = chunks.find(
+        (chunk) =>
+          chunk.type === EventType.RUN_FINISHED &&
+          chunk.outcome?.type === 'interrupt',
+      )
+      if (
+        terminal?.type !== EventType.RUN_FINISHED ||
+        terminal.outcome?.type !== 'interrupt'
+      ) {
+        throw new Error('Expected one public interrupt terminal.')
+      }
+      return terminal
+    }
+
+    const approvalTerminal = await runInterrupt({
+      runId: 'approval-run',
+      threadId: 'approval-thread',
+      toolCallId: 'approval-call-1',
+      tool: approvalTool,
+      args: '{"action":"delete"}',
+    })
+    const browserTerminal = await runInterrupt({
+      runId: 'client-run',
+      threadId: 'client-thread',
+      toolCallId: 'client-call-1',
+      tool: browserTool,
+      args: '{}',
+    })
+    expect(approvalTerminal).toMatchObject({
+      outcome: {
+        interrupts: [
+          {
+            id: 'approval_approval-call-1',
+            reason: 'tool_call',
+            toolCallId: 'approval-call-1',
+          },
+        ],
+      },
+    })
+    expect(browserTerminal).toMatchObject({
+      outcome: {
+        interrupts: [
+          {
+            id: 'client_tool_client-call-1',
+            reason: 'tanstack:client_tool_execution',
+            toolCallId: 'client-call-1',
+          },
+        ],
+      },
+    })
+
+    const stored = [
+      ...(await persistence.stores.interrupts.listPendingByRun('approval-run')),
+      ...(await persistence.stores.interrupts.listPendingByRun('client-run')),
+    ]
+    expect(stored).toHaveLength(2)
+    for (const record of stored) {
+      if (
+        record.payload === null ||
+        typeof record.payload !== 'object' ||
+        Array.isArray(record.payload)
+      ) {
+        throw new Error('Expected a persisted interrupt descriptor.')
+      }
+      const payload: Record<string, unknown> = Object.fromEntries(
+        Object.entries(record.payload),
+      )
+      expect(payload.metadata).not.toHaveProperty('tanstack:interruptBinding')
+      expect(record.binding).toMatchObject({
+        interruptId: record.interruptId,
+        interruptedRunId: record.runId,
+        generation: 1,
+      })
+      expect(record.binding).not.toHaveProperty('authorizationToken')
+      expect(record.binding).not.toHaveProperty('internal')
+    }
+
+    const publicBindings = [approvalTerminal, browserTerminal].flatMap(
+      (terminal) =>
+        terminal.outcome?.type === 'interrupt'
+          ? terminal.outcome.interrupts.map(
+              (interrupt) => interrupt.metadata?.['tanstack:interruptBinding'],
+            )
+          : [],
+    )
+    expect(publicBindings).toEqual(stored.map((record) => record.binding))
+    for (const binding of publicBindings) {
+      expect(binding).not.toHaveProperty('authorizationToken')
+      expect(binding).not.toHaveProperty('internal')
+    }
+  })
+
   it('blocks normal new input while a thread has pending interrupts', async () => {
     const persistence = memoryPersistence()
     const first = mockAdapter([[ev.runStarted(), ev.interrupted()]])
@@ -146,15 +379,16 @@ describe('withChatPersistence (state-only)', () => {
     )
 
     const next = mockAdapter([[ev.text('SHOULD NOT RUN')]])
-    await expectCollectRejects(
+    await expectCollectInterruptError(
       chat({
         adapter: next.adapter,
         messages: [{ role: 'user', content: 'new input' }],
         runId: 'r2',
         threadId: 't1',
         middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
-      /pending interrupts.*resume is required/i,
+        stream: true,
+      }),
+      /parentRunId/i,
     )
     expect(next.calls.length).toBe(0)
   })
@@ -174,16 +408,18 @@ describe('withChatPersistence (state-only)', () => {
     )
 
     const next = mockAdapter([[ev.text('SHOULD NOT RUN')]])
-    await expectCollectRejects(
+    await expectCollectInterruptError(
       chat({
         adapter: next.adapter,
         messages: [{ role: 'user', content: 'new input' }],
         runId: 'r2',
+        parentRunId: 'r1',
         threadId: 't1',
         resume: [{ interruptId: 'other-interrupt', status: 'resolved' }],
         middleware: [withChatPersistence(persistence)],
-      }) as AsyncIterable<StreamChunk>,
-      /missing resume entry for pending interrupt interrupt-1/i,
+        stream: true,
+      }),
+      /missing resume entry for interrupt interrupt-1/i,
     )
     expect(next.calls.length).toBe(0)
   })
@@ -208,12 +444,13 @@ describe('withChatPersistence (state-only)', () => {
         adapter: next.adapter,
         messages: [{ role: 'user', content: 'new input' }],
         runId: 'r2',
+        parentRunId: 'r1',
         threadId: 't1',
         resume: [
           {
             interruptId: 'interrupt-1',
             status: 'resolved',
-            payload: { approved: true },
+            payload: { value: 42 },
           },
         ],
         middleware: [withChatPersistence(persistence)],
@@ -251,6 +488,68 @@ describe('withChatPersistence (state-only)', () => {
     expect(await persistence.stores.messages!.loadThread('t1')).not.toEqual([])
   })
 
+  it('falls through to ephemeral native interrupts without an interrupt store', async () => {
+    const full = memoryPersistence()
+    const persistence = defineAIPersistence({
+      stores: { messages: full.stores.messages },
+    })
+    const { adapter } = mockAdapter([
+      [
+        ev.runStarted(),
+        {
+          type: EventType.TOOL_CALL_START,
+          toolCallId: 'call-client',
+          toolCallName: 'clientSearch',
+          toolName: 'clientSearch',
+          timestamp: 1,
+        },
+        {
+          type: EventType.TOOL_CALL_ARGS,
+          toolCallId: 'call-client',
+          delta: '{"query":"test"}',
+          timestamp: 1,
+        },
+        {
+          ...ev.runFinished(),
+          finishReason: 'tool_calls',
+        },
+      ],
+    ])
+
+    const chunks = await collect(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'search' }],
+        tools: [{ name: 'clientSearch', description: 'Search on the client' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(chunks.some((chunk) => chunk.type === EventType.RUN_ERROR)).toBe(
+      false,
+    )
+    expect(chunks.at(-1)).toMatchObject({
+      type: EventType.RUN_FINISHED,
+      outcome: {
+        type: 'interrupt',
+        interrupts: [
+          {
+            id: 'client_tool_call-client',
+            metadata: {
+              'tanstack:interruptBinding': {
+                interruptedRunId: 'r1',
+                generation: 0,
+              },
+            },
+          },
+        ],
+      },
+    })
+    expect(await persistence.stores.messages!.loadThread('t1')).not.toEqual([])
+  })
+
   it('is a no-op without the middleware: the stream is unchanged', async () => {
     const { adapter } = mockAdapter([
       [ev.runStarted(), ev.text('plain'), ev.runFinished()],
diff --git a/packages/ai-preact/src/types.ts b/packages/ai-preact/src/types.ts
index 91aee1804..dd59ef413 100644
--- a/packages/ai-preact/src/types.ts
+++ b/packages/ai-preact/src/types.ts
@@ -6,9 +6,11 @@ import type {
 } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
+  BoundInterrupts,
   ChatClientOptions,
   ChatClientState,
-  ChatPendingInterrupt,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatRequestBody,
   ChatResumeState,
   ClientContextOptionFromTools,
@@ -105,7 +107,22 @@ export interface UseChatReturn<
   }) => Promise<void>
 
   resumeState: ChatResumeState | null
-  pendingInterrupts: Array<ChatPendingInterrupt>
+  interrupts: BoundInterrupts<TTools>
+  /** @deprecated Use `interrupts`. */
+  pendingInterrupts: BoundInterrupts<TTools>
+  interruptErrors: ChatInterruptState<TTools>['interruptErrors']
+  resuming: boolean
+  resolveInterrupts: {
+    (approved: boolean): void
+    (resolver: (interrupt: ChatInterrupt<TTools>) => undefined): void
+  }
+  cancelInterrupts: () => void
+  retryInterrupts: () => void
+  resumeInterruptsUnsafe: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+  /** @deprecated Use bound interrupt methods or `resumeInterruptsUnsafe`. */
   resumeInterrupts: (
     resume: Array<RunAgentResumeItem>,
     state?: ChatResumeState,
diff --git a/packages/ai-preact/src/use-chat.ts b/packages/ai-preact/src/use-chat.ts
index 3f1cc1b08..3341d4277 100644
--- a/packages/ai-preact/src/use-chat.ts
+++ b/packages/ai-preact/src/use-chat.ts
@@ -10,7 +10,8 @@ import {
 } from 'preact/hooks'
 import type {
   ChatClientState,
-  ChatPendingInterrupt,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
@@ -28,6 +29,9 @@ import type {
   UseChatReturn,
 } from './types'
 
+const EMPTY_INTERRUPTS = Object.freeze([])
+const EMPTY_INTERRUPT_ERRORS = Object.freeze([])
+
 export function useChat<
   const TTools extends ReadonlyArray<AnyClientTool> = any,
   TContext = InferredClientContext<TTools>,
@@ -48,9 +52,14 @@ export function useChat<
   const [resumeState, setResumeState] = useState<ChatResumeState | null>(
     options.initialResumeSnapshot?.resumeState ?? null,
   )
-  const [pendingInterrupts, setPendingInterrupts] = useState<
-    Array<ChatPendingInterrupt>
-  >(options.initialResumeSnapshot?.pendingInterrupts ?? [])
+  const [interruptState, setInterruptState] = useState<
+    ChatInterruptState<TTools>
+  >(() => ({
+    interrupts: EMPTY_INTERRUPTS,
+    pendingInterrupts: EMPTY_INTERRUPTS,
+    interruptErrors: EMPTY_INTERRUPT_ERRORS,
+    resuming: false,
+  }))
 
   // Track current messages in a ref to preserve them when client is recreated
   const messagesRef = useRef<Array<UIMessage<TTools>>>(
@@ -72,7 +81,7 @@ export function useChat<
   const syncResumeState = useCallback((target: ChatClient | null) => {
     if (!target) return
     setResumeState(target.getResumeState())
-    setPendingInterrupts(target.getPendingInterrupts())
+    setInterruptState(target.getInterruptState())
   }, [])
 
   useEffect(() => {
@@ -92,6 +101,17 @@ export function useChat<
       ? { connection: initialOptions.connection }
       : { fetcher: initialOptions.fetcher }
 
+    const instanceHolder: {
+      current: ChatClient<TTools, TContext> | undefined
+    } = { current: undefined }
+    const getActiveInstance = () => {
+      const currentInstance = instanceHolder.current
+      if (!currentInstance || activeClientRef.current !== currentInstance) {
+        return undefined
+      }
+      return currentInstance
+    }
+    const pendingInitializationErrors: Array<Error> = []
     const instance = new ChatClient<TTools, TContext>({
       devtoolsBridgeFactory: createChatDevtoolsBridge,
       ...transport,
@@ -123,23 +143,28 @@ export function useChat<
       // Capturing the function reference directly would freeze it to whatever
       // the parent passed on the first render.
       onResponse: (response) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         return optionsRef.current.onResponse?.(response)
       },
       onChunk: (chunk) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         optionsRef.current.onChunk?.(chunk)
       },
       onFinish: (message) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         optionsRef.current.onFinish?.(message)
       },
       onError: (err) => {
-        if (activeClientRef.current !== instance) return
+        const currentInstance = instanceHolder.current
+        if (!currentInstance) {
+          pendingInitializationErrors.push(err)
+          return
+        }
+        if (activeClientRef.current !== currentInstance) return
         optionsRef.current.onError?.(err)
       },
       onCustomEvent: (eventType, data, context) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         optionsRef.current.onCustomEvent?.(eventType, data, context)
       },
       ...(initialOptions.tools !== undefined && {
@@ -149,41 +174,56 @@ export function useChat<
         streamProcessor: options.streamProcessor,
       }),
       onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setMessages(newMessages)
       },
       onLoadingChange: (newIsLoading: boolean) => {
-        if (activeClientRef.current !== instance) return
+        const currentInstance = getActiveInstance()
+        if (!currentInstance) return
         setIsLoading(newIsLoading)
-        syncResumeState(instance)
+        syncResumeState(currentInstance)
       },
       onStatusChange: (newStatus: ChatClientState) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setStatus(newStatus)
       },
       onErrorChange: (newError: Error | undefined) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setError(newError)
       },
       onSubscriptionChange: (nextIsSubscribed: boolean) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setIsSubscribed(nextIsSubscribed)
       },
       onConnectionStatusChange: (nextStatus: ConnectionStatus) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setConnectionStatus(nextStatus)
       },
       onSessionGeneratingChange: (isGenerating: boolean) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setSessionGenerating(isGenerating)
       },
       onResumeStateChange: (nextResumeState, nextPendingInterrupts) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setResumeState(nextResumeState)
-        setPendingInterrupts(nextPendingInterrupts)
+        setInterruptState((current) => ({
+          ...current,
+          interrupts: nextPendingInterrupts,
+          pendingInterrupts: nextPendingInterrupts,
+        }))
+      },
+      onInterruptStateChange: (nextInterruptState) => {
+        if (!getActiveInstance()) return
+        setInterruptState(nextInterruptState)
+        optionsRef.current.onInterruptStateChange?.(nextInterruptState)
       },
     })
+    instanceHolder.current = instance
     activeClientRef.current = instance
+    for (const initializationError of pendingInitializationErrors) {
+      if (activeClientRef.current !== instance) break
+      optionsRef.current.onError?.(initializationError)
+    }
     return instance
   }, [clientId, syncResumeState])
 
@@ -344,6 +384,33 @@ export function useChat<
     [client, syncResumeState],
   )
 
+  const resolveInterrupts = useCallback(
+    (
+      resolution: boolean | ((interrupt: ChatInterrupt<TTools>) => undefined),
+    ) => {
+      if (typeof resolution === 'boolean') {
+        client.resolveInterrupts(resolution)
+      } else {
+        client.resolveInterrupts(resolution)
+      }
+    },
+    [client],
+  )
+
+  const cancelInterrupts = useCallback(() => {
+    client.cancelInterrupts()
+  }, [client])
+
+  const retryInterrupts = useCallback(() => {
+    client.retryInterrupts()
+  }, [client])
+
+  const resumeInterruptsUnsafe = useCallback(
+    (resumeItems: Array<RunAgentResumeItem>, state?: ChatResumeState) =>
+      client.resumeInterruptsUnsafe(resumeItems, state),
+    [client],
+  )
+
   const renderedMessages = client.getMessages()
 
   return {
@@ -363,7 +430,14 @@ export function useChat<
     addToolResult,
     addToolApprovalResponse,
     resumeState,
-    pendingInterrupts,
+    interrupts: interruptState.interrupts,
+    pendingInterrupts: interruptState.pendingInterrupts,
+    interruptErrors: interruptState.interruptErrors,
+    resuming: interruptState.resuming,
+    resolveInterrupts,
+    cancelInterrupts,
+    retryInterrupts,
+    resumeInterruptsUnsafe,
     resumeInterrupts,
   }
 }
diff --git a/packages/ai-preact/tests/test-utils.ts b/packages/ai-preact/tests/test-utils.ts
index ac5d85676..ad6f25b6b 100644
--- a/packages/ai-preact/tests/test-utils.ts
+++ b/packages/ai-preact/tests/test-utils.ts
@@ -4,6 +4,81 @@ import { useChat } from '../src/use-chat'
 import type { RenderHookResult } from '@testing-library/preact'
 import type { UseChatOptions, UseChatReturn } from '../src/types'
 
+import type { ChatResumeSnapshotV2 } from '@tanstack/ai-client'
+
+export function createInterruptResumeSnapshot(): ChatResumeSnapshotV2 {
+  const pendingInterrupts = [
+    {
+      id: 'staged-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'staged-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+    {
+      id: 'invalid-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'invalid-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+  ]
+  return {
+    schemaVersion: 2,
+    resumeState: { threadId: 'thread-1', runId: 'run-1' },
+    pendingInterrupts,
+    interruptState: {
+      recoveryState: {
+        schemaVersion: 1,
+        state: 'pending',
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+        pendingInterrupts,
+      },
+      drafts: [
+        {
+          interruptId: 'staged-interrupt',
+          response: {
+            interruptId: 'staged-interrupt',
+            status: 'resolved',
+            payload: { answer: 42 },
+          },
+          status: 'staged',
+        },
+        {
+          interruptId: 'invalid-interrupt',
+          response: null,
+          status: 'error',
+          error: {
+            scope: 'item',
+            interruptId: 'invalid-interrupt',
+            code: 'invalid-payload',
+            message: 'Invalid persisted response',
+            source: 'client',
+            retryable: false,
+            threadId: 'thread-1',
+            interruptedRunId: 'run-1',
+            generation: 1,
+          },
+        },
+      ],
+    },
+  }
+}
+
 export {
   createMockConnectionAdapter,
   createTextChunks,
diff --git a/packages/ai-preact/tests/use-chat-types.test.ts b/packages/ai-preact/tests/use-chat-types.test.ts
index 5880305c6..942ea8479 100644
--- a/packages/ai-preact/tests/use-chat-types.test.ts
+++ b/packages/ai-preact/tests/use-chat-types.test.ts
@@ -7,7 +7,16 @@ import { describe, expectTypeOf, it } from 'vitest'
 import { toolDefinition } from '@tanstack/ai'
 import { clientTools } from '@tanstack/ai-client'
 import { useChat } from '../src/use-chat'
-import type { UseChatOptions } from '../src/types'
+import type { UseChatOptions, UseChatReturn } from '../src/types'
+
+type TestSchema<T> = {
+  readonly '~standard': {
+    readonly version: 1
+    readonly vendor: 'test'
+    readonly types: { readonly input: T; readonly output: T }
+    readonly validate: (value: unknown) => { readonly value: T }
+  }
+}
 
 describe('useChat() return type (preact)', () => {
   describe('with typed client tool context', () => {
@@ -70,3 +79,125 @@ describe('useChat() return type (preact)', () => {
     })
   })
 })
+
+describe('useChat() interrupt types', () => {
+  it('preserves approval, generic, and client-tool inference', () => {
+    const inputSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { cents: 0 },
+          output: { cents: 0 },
+        },
+        validate: (value: unknown) => ({
+          value:
+            value !== null &&
+            typeof value === 'object' &&
+            'cents' in value &&
+            typeof value.cents === 'number'
+              ? { cents: value.cents }
+              : { cents: 0 },
+        }),
+      },
+    }
+    const approveSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { note: '' },
+          output: { note: '' },
+        },
+        validate: () => ({ value: { note: '' } }),
+      },
+    }
+    const rejectSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { reason: '' },
+          output: { reason: '' },
+        },
+        validate: () => ({ value: { reason: '' } }),
+      },
+    }
+    const outputSchema: TestSchema<{ accountId: string }> = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { accountId: '' },
+          output: { accountId: '' },
+        },
+        validate: () => ({ value: { accountId: '' } }),
+      },
+    }
+    const transfer = toolDefinition({
+      name: 'transfer',
+      description: 'Transfer funds',
+      needsApproval: true,
+      inputSchema,
+      approvalSchema: {
+        approve: approveSchema,
+        reject: rejectSchema,
+      },
+    }).client()
+    const confirm = toolDefinition({
+      name: 'confirm',
+      description: 'Confirm without schemas',
+      needsApproval: true,
+    }).client()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Lookup account',
+      outputSchema,
+    }).client()
+    const tools = clientTools(transfer, confirm, lookup)
+    type Interrupt = UseChatReturn<typeof tools>['interrupts'][number]
+    type Transfer = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'transfer' }
+    >
+    type Confirm = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'confirm' }
+    >
+    type Generic = Extract<Interrupt, { kind: 'generic' }>
+
+    const check = (
+      transferInterrupt: Transfer,
+      confirmInterrupt: Confirm,
+      genericInterrupt: Generic,
+    ) => {
+      transferInterrupt.resolveInterrupt(true, {
+        editedArgs: { cents: 100 },
+        payload: { note: 'approved' },
+      })
+      transferInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'declined' },
+      })
+      // @ts-expect-error rejected approvals cannot edit tool input
+      transferInterrupt.resolveInterrupt(false, { editedArgs: { cents: 1 } })
+      // @ts-expect-error approve payload uses the approve branch
+      transferInterrupt.resolveInterrupt(true, {
+        payload: { reason: 'wrong branch' },
+      })
+
+      confirmInterrupt.resolveInterrupt(true)
+      confirmInterrupt.resolveInterrupt(false)
+      // @ts-expect-error omitted input schema forbids edited input
+      confirmInterrupt.resolveInterrupt(true, { editedArgs: { cents: 1 } })
+      // @ts-expect-error omitted approval branches forbid payloads
+      confirmInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'no branch' },
+      })
+
+      expectTypeOf(genericInterrupt.resolveInterrupt)
+        .parameter(0)
+        .toEqualTypeOf<unknown>()
+    }
+    void check
+  })
+})
diff --git a/packages/ai-preact/tests/use-chat.test.ts b/packages/ai-preact/tests/use-chat.test.ts
index f932b1ef2..9d7f4e02f 100644
--- a/packages/ai-preact/tests/use-chat.test.ts
+++ b/packages/ai-preact/tests/use-chat.test.ts
@@ -1,6 +1,9 @@
 import type { ModelMessage, StreamChunk } from '@tanstack/ai'
 import { EventType } from '@tanstack/ai'
-import type { SubscribeConnectionAdapter } from '@tanstack/ai-client'
+import {
+  ChatClient,
+  type SubscribeConnectionAdapter,
+} from '@tanstack/ai-client'
 import { act, renderHook, waitFor } from '@testing-library/preact'
 import { StrictMode } from 'preact/compat'
 import { useState } from 'preact/hooks'
@@ -9,6 +12,7 @@ import type { UIMessage } from '../src/types'
 import { useChat } from '../src/use-chat'
 import {
   createMockConnectionAdapter,
+  createInterruptResumeSnapshot,
   createTextChunks,
   createToolCallChunks,
   renderUseChat,
@@ -27,6 +31,85 @@ describe('useChat', () => {
     return { promise, resolve }
   }
 
+  describe('interrupt state', () => {
+    it('projects one immutable snapshot with the deprecated pending alias', async () => {
+      const onInterruptStateChange = vi.fn()
+      const { result } = renderUseChat({
+        connection: createMockConnectionAdapter(),
+        initialResumeSnapshot: createInterruptResumeSnapshot(),
+        onInterruptStateChange,
+      })
+
+      expect(Object.isFrozen(result.current.interrupts)).toBe(true)
+      expect(result.current.pendingInterrupts).toBe(result.current.interrupts)
+      expect(result.current.interrupts[0]).toMatchObject({
+        id: 'staged-interrupt',
+        status: 'staged',
+      })
+      expect(result.current.interrupts[1]).toMatchObject({
+        id: 'invalid-interrupt',
+        status: 'error',
+        error: { code: 'invalid-payload' },
+      })
+      expect(result.current.interruptErrors).toEqual([])
+      expect(result.current.resuming).toBe(false)
+      expect(result.current.interrupts[0]).toEqual(
+        expect.objectContaining({
+          resolveInterrupt: expect.any(Function),
+          cancel: expect.any(Function),
+          clearResolution: expect.any(Function),
+        }),
+      )
+
+      act(() => result.current.resolveInterrupts(false))
+      await waitFor(() => {
+        expect(result.current.interruptErrors[0]?.code).toBe(
+          'unsupported-bulk-operation',
+        )
+      })
+      expect(onInterruptStateChange).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          interrupts: result.current.interrupts,
+          interruptErrors: result.current.interruptErrors,
+        }),
+      )
+    })
+
+    it('delegates every root interrupt control to ChatClient', async () => {
+      const resolve = vi
+        .spyOn(ChatClient.prototype, 'resolveInterrupts')
+        .mockImplementation(() => {})
+      const cancel = vi
+        .spyOn(ChatClient.prototype, 'cancelInterrupts')
+        .mockImplementation(() => {})
+      const retry = vi
+        .spyOn(ChatClient.prototype, 'retryInterrupts')
+        .mockImplementation(() => {})
+      const unsafe = vi
+        .spyOn(ChatClient.prototype, 'resumeInterruptsUnsafe')
+        .mockResolvedValue(true)
+      const { result } = renderUseChat({
+        connection: createMockConnectionAdapter(),
+      })
+      const resolver = () => undefined
+      const resume = [{ interruptId: 'one', status: 'cancelled' as const }]
+
+      act(() => {
+        result.current.resolveInterrupts(resolver)
+        result.current.cancelInterrupts()
+        result.current.retryInterrupts()
+      })
+      await expect(result.current.resumeInterruptsUnsafe(resume)).resolves.toBe(
+        true,
+      )
+
+      expect(resolve).toHaveBeenCalledWith(resolver)
+      expect(cancel).toHaveBeenCalledOnce()
+      expect(retry).toHaveBeenCalledOnce()
+      expect(unsafe).toHaveBeenCalledWith(resume, undefined)
+    })
+  })
+
   describe('initialization', () => {
     it('should initialize with default state', () => {
       const adapter = createMockConnectionAdapter()
diff --git a/packages/ai-react/src/types.ts b/packages/ai-react/src/types.ts
index cf38b8a13..7f696c2f6 100644
--- a/packages/ai-react/src/types.ts
+++ b/packages/ai-react/src/types.ts
@@ -7,9 +7,11 @@ import type {
 } from '@tanstack/ai/client'
 import type {
   AIDevtoolsDisplayOptions,
+  BoundInterrupts,
   ChatClientOptions,
   ChatClientState,
-  ChatPendingInterrupt,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatRequestBody,
   ChatResumeState,
   ClientContextOptionFromTools,
@@ -166,7 +168,22 @@ interface BaseUseChatReturn<
   }) => Promise<void>
 
   resumeState: ChatResumeState | null
-  pendingInterrupts: Array<ChatPendingInterrupt>
+  interrupts: BoundInterrupts<TTools>
+  /** @deprecated Use `interrupts`. */
+  pendingInterrupts: BoundInterrupts<TTools>
+  interruptErrors: ChatInterruptState<TTools>['interruptErrors']
+  resuming: boolean
+  resolveInterrupts: {
+    (approved: boolean): void
+    (resolver: (interrupt: ChatInterrupt<TTools>) => undefined): void
+  }
+  cancelInterrupts: () => void
+  retryInterrupts: () => void
+  resumeInterruptsUnsafe: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+  /** @deprecated Use bound interrupt methods or `resumeInterruptsUnsafe`. */
   resumeInterrupts: (
     resume: Array<RunAgentResumeItem>,
     state?: ChatResumeState,
diff --git a/packages/ai-react/src/use-chat.ts b/packages/ai-react/src/use-chat.ts
index 30c9ff202..fb65ea808 100644
--- a/packages/ai-react/src/use-chat.ts
+++ b/packages/ai-react/src/use-chat.ts
@@ -11,7 +11,8 @@ import type {
 } from '@tanstack/ai/client'
 import type {
   ChatClientState,
-  ChatPendingInterrupt,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
@@ -26,6 +27,9 @@ import type {
   UseChatReturn,
 } from './types'
 
+const EMPTY_INTERRUPTS = Object.freeze([])
+const EMPTY_INTERRUPT_ERRORS = Object.freeze([])
+
 export function useChat<
   const TTools extends ReadonlyArray<AnyClientTool> = any,
   TSchema extends SchemaInput | undefined = undefined,
@@ -49,9 +53,14 @@ export function useChat<
   const [resumeState, setResumeState] = useState<ChatResumeState | null>(
     options.initialResumeSnapshot?.resumeState ?? null,
   )
-  const [pendingInterrupts, setPendingInterrupts] = useState<
-    Array<ChatPendingInterrupt>
-  >(options.initialResumeSnapshot?.pendingInterrupts ?? [])
+  const [interruptState, setInterruptState] = useState<
+    ChatInterruptState<TTools>
+  >(() => ({
+    interrupts: EMPTY_INTERRUPTS,
+    pendingInterrupts: EMPTY_INTERRUPTS,
+    interruptErrors: EMPTY_INTERRUPT_ERRORS,
+    resuming: false,
+  }))
 
   type Partial = DeepPartial<InferSchemaType<NonNullable<TSchema>>>
   type Final = InferSchemaType<NonNullable<TSchema>>
@@ -80,7 +89,7 @@ export function useChat<
   const syncResumeState = useCallback((target: ChatClient | null) => {
     if (!target) return
     setResumeState(target.getResumeState())
-    setPendingInterrupts(target.getPendingInterrupts())
+    setInterruptState(target.getInterruptState())
   }, [])
 
   // Create ChatClient instance with callbacks to sync state
@@ -199,7 +208,16 @@ export function useChat<
       onResumeStateChange: (nextResumeState, nextPendingInterrupts) => {
         if (!getActiveInstance()) return
         setResumeState(nextResumeState)
-        setPendingInterrupts(nextPendingInterrupts)
+        setInterruptState((current) => ({
+          ...current,
+          interrupts: nextPendingInterrupts,
+          pendingInterrupts: nextPendingInterrupts,
+        }))
+      },
+      onInterruptStateChange: (nextInterruptState) => {
+        if (!getActiveInstance()) return
+        setInterruptState(nextInterruptState)
+        optionsRef.current.onInterruptStateChange?.(nextInterruptState)
       },
     })
     instanceHolder.current = instance
@@ -374,6 +392,33 @@ export function useChat<
     [client, syncResumeState],
   )
 
+  const resolveInterrupts = useCallback(
+    (
+      resolution: boolean | ((interrupt: ChatInterrupt<TTools>) => undefined),
+    ) => {
+      if (typeof resolution === 'boolean') {
+        client.resolveInterrupts(resolution)
+      } else {
+        client.resolveInterrupts(resolution)
+      }
+    },
+    [client],
+  )
+
+  const cancelInterrupts = useCallback(() => {
+    client.cancelInterrupts()
+  }, [client])
+
+  const retryInterrupts = useCallback(() => {
+    client.retryInterrupts()
+  }, [client])
+
+  const resumeInterruptsUnsafe = useCallback(
+    (resumeItems: Array<RunAgentResumeItem>, state?: ChatResumeState) =>
+      client.resumeInterruptsUnsafe(resumeItems, state),
+    [client],
+  )
+
   // The "active" structured-output part is the one on the assistant message
   // that follows the latest user message. No such message exists between
   // sendMessage() and the first chunk, so partial/final naturally read as
@@ -440,7 +485,14 @@ export function useChat<
     addToolResult,
     addToolApprovalResponse,
     resumeState,
-    pendingInterrupts,
+    interrupts: interruptState.interrupts,
+    pendingInterrupts: interruptState.pendingInterrupts,
+    interruptErrors: interruptState.interruptErrors,
+    resuming: interruptState.resuming,
+    resolveInterrupts,
+    cancelInterrupts,
+    retryInterrupts,
+    resumeInterruptsUnsafe,
     resumeInterrupts,
     partial,
     final,
diff --git a/packages/ai-react/tests/test-utils.ts b/packages/ai-react/tests/test-utils.ts
index 40f0b2ac9..e9e7a6c36 100644
--- a/packages/ai-react/tests/test-utils.ts
+++ b/packages/ai-react/tests/test-utils.ts
@@ -8,6 +8,80 @@ export {
 import { renderHook, type RenderHookResult } from '@testing-library/react'
 import type { UseChatOptions, UseChatReturn } from '../src/types'
 import { useChat } from '../src/use-chat'
+import type { ChatResumeSnapshotV2 } from '@tanstack/ai-client'
+
+export function createInterruptResumeSnapshot(): ChatResumeSnapshotV2 {
+  const pendingInterrupts = [
+    {
+      id: 'staged-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'staged-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+    {
+      id: 'invalid-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'invalid-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+  ]
+  return {
+    schemaVersion: 2,
+    resumeState: { threadId: 'thread-1', runId: 'run-1' },
+    pendingInterrupts,
+    interruptState: {
+      recoveryState: {
+        schemaVersion: 1,
+        state: 'pending',
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+        pendingInterrupts,
+      },
+      drafts: [
+        {
+          interruptId: 'staged-interrupt',
+          response: {
+            interruptId: 'staged-interrupt',
+            status: 'resolved',
+            payload: { answer: 42 },
+          },
+          status: 'staged',
+        },
+        {
+          interruptId: 'invalid-interrupt',
+          response: null,
+          status: 'error',
+          error: {
+            scope: 'item',
+            interruptId: 'invalid-interrupt',
+            code: 'invalid-payload',
+            message: 'Invalid persisted response',
+            source: 'client',
+            retryable: false,
+            threadId: 'thread-1',
+            interruptedRunId: 'run-1',
+            generation: 1,
+          },
+        },
+      ],
+    },
+  }
+}
 
 /**
  * Render the useChat hook with testing utilities
diff --git a/packages/ai-react/tests/use-chat-types.test.ts b/packages/ai-react/tests/use-chat-types.test.ts
index 4edd539fb..5a652468d 100644
--- a/packages/ai-react/tests/use-chat-types.test.ts
+++ b/packages/ai-react/tests/use-chat-types.test.ts
@@ -16,6 +16,14 @@ import type { DeepPartial, UseChatOptions, UseChatReturn } from '../src/types'
 type Person = { name: string; age: number; email: string }
 type PersonSchema = StandardJSONSchemaV1<Person, Person>
 type NoTools = ReadonlyArray<AnyClientTool>
+type TestSchema<T> = {
+  readonly '~standard': {
+    readonly version: 1
+    readonly vendor: 'test'
+    readonly types: { readonly input: T; readonly output: T }
+    readonly validate: (value: unknown) => { readonly value: T }
+  }
+}
 
 describe('useChat() return type', () => {
   describe('with outputSchema', () => {
@@ -183,3 +191,125 @@ describe('useChat() return type', () => {
     })
   })
 })
+
+describe('useChat() interrupt types', () => {
+  it('preserves approval, generic, and client-tool inference', () => {
+    const inputSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { cents: 0 },
+          output: { cents: 0 },
+        },
+        validate: (value: unknown) => ({
+          value:
+            value !== null &&
+            typeof value === 'object' &&
+            'cents' in value &&
+            typeof value.cents === 'number'
+              ? { cents: value.cents }
+              : { cents: 0 },
+        }),
+      },
+    }
+    const approveSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { note: '' },
+          output: { note: '' },
+        },
+        validate: () => ({ value: { note: '' } }),
+      },
+    }
+    const rejectSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { reason: '' },
+          output: { reason: '' },
+        },
+        validate: () => ({ value: { reason: '' } }),
+      },
+    }
+    const outputSchema: TestSchema<{ accountId: string }> = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { accountId: '' },
+          output: { accountId: '' },
+        },
+        validate: () => ({ value: { accountId: '' } }),
+      },
+    }
+    const transfer = toolDefinition({
+      name: 'transfer',
+      description: 'Transfer funds',
+      needsApproval: true,
+      inputSchema,
+      approvalSchema: {
+        approve: approveSchema,
+        reject: rejectSchema,
+      },
+    }).client()
+    const confirm = toolDefinition({
+      name: 'confirm',
+      description: 'Confirm without schemas',
+      needsApproval: true,
+    }).client()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Lookup account',
+      outputSchema,
+    }).client()
+    const tools = clientTools(transfer, confirm, lookup)
+    type Interrupt = UseChatReturn<typeof tools>['interrupts'][number]
+    type Transfer = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'transfer' }
+    >
+    type Confirm = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'confirm' }
+    >
+    type Generic = Extract<Interrupt, { kind: 'generic' }>
+
+    const check = (
+      transferInterrupt: Transfer,
+      confirmInterrupt: Confirm,
+      genericInterrupt: Generic,
+    ) => {
+      transferInterrupt.resolveInterrupt(true, {
+        editedArgs: { cents: 100 },
+        payload: { note: 'approved' },
+      })
+      transferInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'declined' },
+      })
+      // @ts-expect-error rejected approvals cannot edit tool input
+      transferInterrupt.resolveInterrupt(false, { editedArgs: { cents: 1 } })
+      // @ts-expect-error approve payload uses the approve branch
+      transferInterrupt.resolveInterrupt(true, {
+        payload: { reason: 'wrong branch' },
+      })
+
+      confirmInterrupt.resolveInterrupt(true)
+      confirmInterrupt.resolveInterrupt(false)
+      // @ts-expect-error omitted input schema forbids edited input
+      confirmInterrupt.resolveInterrupt(true, { editedArgs: { cents: 1 } })
+      // @ts-expect-error omitted approval branches forbid payloads
+      confirmInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'no branch' },
+      })
+
+      expectTypeOf(genericInterrupt.resolveInterrupt)
+        .parameter(0)
+        .toEqualTypeOf<unknown>()
+    }
+    void check
+  })
+})
diff --git a/packages/ai-react/tests/use-chat.test.ts b/packages/ai-react/tests/use-chat.test.ts
index 7511c58fe..7e56780cc 100644
--- a/packages/ai-react/tests/use-chat.test.ts
+++ b/packages/ai-react/tests/use-chat.test.ts
@@ -1,6 +1,9 @@
 import type { ModelMessage, StreamChunk } from '@tanstack/ai'
 import { EventType } from '@tanstack/ai'
-import type { SubscribeConnectionAdapter } from '@tanstack/ai-client'
+import {
+  ChatClient,
+  type SubscribeConnectionAdapter,
+} from '@tanstack/ai-client'
 import { act, renderHook, waitFor } from '@testing-library/react'
 import { StrictMode, useState } from 'react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -8,6 +11,7 @@ import type { UIMessage, UseChatOptions } from '../src/types'
 import { useChat } from '../src/use-chat'
 import {
   createMockConnectionAdapter,
+  createInterruptResumeSnapshot,
   createTextChunks,
   createToolCallChunks,
   renderUseChat,
@@ -26,6 +30,85 @@ describe('useChat', () => {
     return { promise, resolve }
   }
 
+  describe('interrupt state', () => {
+    it('projects one immutable snapshot with the deprecated pending alias', async () => {
+      const onInterruptStateChange = vi.fn()
+      const { result } = renderUseChat({
+        connection: createMockConnectionAdapter(),
+        initialResumeSnapshot: createInterruptResumeSnapshot(),
+        onInterruptStateChange,
+      })
+
+      expect(Object.isFrozen(result.current.interrupts)).toBe(true)
+      expect(result.current.pendingInterrupts).toBe(result.current.interrupts)
+      expect(result.current.interrupts[0]).toMatchObject({
+        id: 'staged-interrupt',
+        status: 'staged',
+      })
+      expect(result.current.interrupts[1]).toMatchObject({
+        id: 'invalid-interrupt',
+        status: 'error',
+        error: { code: 'invalid-payload' },
+      })
+      expect(result.current.interruptErrors).toEqual([])
+      expect(result.current.resuming).toBe(false)
+      expect(result.current.interrupts[0]).toEqual(
+        expect.objectContaining({
+          resolveInterrupt: expect.any(Function),
+          cancel: expect.any(Function),
+          clearResolution: expect.any(Function),
+        }),
+      )
+
+      act(() => result.current.resolveInterrupts(false))
+      await waitFor(() => {
+        expect(result.current.interruptErrors[0]?.code).toBe(
+          'unsupported-bulk-operation',
+        )
+      })
+      expect(onInterruptStateChange).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          interrupts: result.current.interrupts,
+          interruptErrors: result.current.interruptErrors,
+        }),
+      )
+    })
+
+    it('delegates every root interrupt control to ChatClient', async () => {
+      const resolve = vi
+        .spyOn(ChatClient.prototype, 'resolveInterrupts')
+        .mockImplementation(() => {})
+      const cancel = vi
+        .spyOn(ChatClient.prototype, 'cancelInterrupts')
+        .mockImplementation(() => {})
+      const retry = vi
+        .spyOn(ChatClient.prototype, 'retryInterrupts')
+        .mockImplementation(() => {})
+      const unsafe = vi
+        .spyOn(ChatClient.prototype, 'resumeInterruptsUnsafe')
+        .mockResolvedValue(true)
+      const { result } = renderUseChat({
+        connection: createMockConnectionAdapter(),
+      })
+      const resolver = () => undefined
+      const resume = [{ interruptId: 'one', status: 'cancelled' as const }]
+
+      act(() => {
+        result.current.resolveInterrupts(resolver)
+        result.current.cancelInterrupts()
+        result.current.retryInterrupts()
+      })
+      await expect(result.current.resumeInterruptsUnsafe(resume)).resolves.toBe(
+        true,
+      )
+
+      expect(resolve).toHaveBeenCalledWith(resolver)
+      expect(cancel).toHaveBeenCalledOnce()
+      expect(retry).toHaveBeenCalledOnce()
+      expect(unsafe).toHaveBeenCalledWith(resume, undefined)
+    })
+  })
+
   describe('initialization', () => {
     it('should initialize with default state', () => {
       const adapter = createMockConnectionAdapter()
diff --git a/packages/ai-solid/src/types.ts b/packages/ai-solid/src/types.ts
index 580d0be1c..d1cf04aff 100644
--- a/packages/ai-solid/src/types.ts
+++ b/packages/ai-solid/src/types.ts
@@ -7,9 +7,11 @@ import type {
 } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
+  BoundInterrupts,
   ChatClientOptions,
   ChatClientState,
-  ChatPendingInterrupt,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatRequestBody,
   ChatResumeState,
   ClientContextOptionFromTools,
@@ -152,7 +154,22 @@ interface BaseUseChatReturn<
   }) => Promise<void>
 
   resumeState: Accessor<ChatResumeState | null>
-  pendingInterrupts: Accessor<Array<ChatPendingInterrupt>>
+  interrupts: Accessor<BoundInterrupts<TTools>>
+  /** @deprecated Use `interrupts`. */
+  pendingInterrupts: Accessor<BoundInterrupts<TTools>>
+  interruptErrors: Accessor<ChatInterruptState<TTools>['interruptErrors']>
+  resuming: Accessor<boolean>
+  resolveInterrupts: {
+    (approved: boolean): void
+    (resolver: (interrupt: ChatInterrupt<TTools>) => undefined): void
+  }
+  cancelInterrupts: () => void
+  retryInterrupts: () => void
+  resumeInterruptsUnsafe: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+  /** @deprecated Use bound interrupt methods or `resumeInterruptsUnsafe`. */
   resumeInterrupts: (
     resume: Array<RunAgentResumeItem>,
     state?: ChatResumeState,
diff --git a/packages/ai-solid/src/use-chat.ts b/packages/ai-solid/src/use-chat.ts
index 327058d37..f2aed2ce4 100644
--- a/packages/ai-solid/src/use-chat.ts
+++ b/packages/ai-solid/src/use-chat.ts
@@ -11,7 +11,8 @@ import { ChatClient } from '@tanstack/ai-client'
 import { createChatDevtoolsBridge } from '@tanstack/ai-client/devtools'
 import type {
   ChatClientState,
-  ChatPendingInterrupt,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
@@ -33,6 +34,9 @@ import type {
   UseChatReturn,
 } from './types'
 
+const EMPTY_INTERRUPTS = Object.freeze([])
+const EMPTY_INTERRUPT_ERRORS = Object.freeze([])
+
 export function useChat<
   const TTools extends ReadonlyArray<AnyClientTool> = any,
   TSchema extends SchemaInput | undefined = undefined,
@@ -60,13 +64,18 @@ export function useChat<
   const [resumeState, setResumeState] = createSignal<ChatResumeState | null>(
     options.initialResumeSnapshot?.resumeState ?? null,
   )
-  const [pendingInterrupts, setPendingInterrupts] = createSignal<
-    Array<ChatPendingInterrupt>
-  >(options.initialResumeSnapshot?.pendingInterrupts ?? [])
+  const [interruptState, setInterruptState] = createSignal<
+    ChatInterruptState<TTools>
+  >({
+    interrupts: EMPTY_INTERRUPTS,
+    pendingInterrupts: EMPTY_INTERRUPTS,
+    interruptErrors: EMPTY_INTERRUPT_ERRORS,
+    resuming: false,
+  })
 
   const syncResumeState = () => {
     setResumeState(client().getResumeState())
-    setPendingInterrupts(client().getPendingInterrupts())
+    setInterruptState(client().getInterruptState())
   }
 
   // Structured-output `partial` / `final` are derived from `messages` —
@@ -155,7 +164,15 @@ export function useChat<
       },
       onResumeStateChange: (nextResumeState, nextPendingInterrupts) => {
         setResumeState(nextResumeState)
-        setPendingInterrupts(nextPendingInterrupts)
+        setInterruptState((current) => ({
+          ...current,
+          interrupts: nextPendingInterrupts,
+          pendingInterrupts: nextPendingInterrupts,
+        }))
+      },
+      onInterruptStateChange: (nextInterruptState) => {
+        setInterruptState(nextInterruptState)
+        options.onInterruptStateChange?.(nextInterruptState)
       },
     })
     // Only recreate when clientId changes
@@ -163,6 +180,7 @@ export function useChat<
   }, [clientId])
 
   setMessages(client().getMessages())
+  syncResumeState()
 
   // Sync body / forwardedProps changes to the client.
   // Both populate the same wire payload; `forwardedProps` is preferred
@@ -279,6 +297,34 @@ export function useChat<
     return result
   }
 
+  const resolveInterrupts = (
+    resolution: boolean | ((interrupt: ChatInterrupt<TTools>) => undefined),
+  ) => {
+    if (typeof resolution === 'boolean') {
+      client().resolveInterrupts(resolution)
+    } else {
+      client().resolveInterrupts(resolution)
+    }
+  }
+
+  const cancelInterrupts = () => {
+    client().cancelInterrupts()
+  }
+
+  const retryInterrupts = () => {
+    client().retryInterrupts()
+  }
+
+  const resumeInterruptsUnsafe = (
+    resumeItems: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => client().resumeInterruptsUnsafe(resumeItems, state)
+
+  const interrupts = () => interruptState().interrupts
+  const pendingInterrupts = () => interruptState().pendingInterrupts
+  const interruptErrors = () => interruptState().interruptErrors
+  const resuming = () => interruptState().resuming
+
   // The "active" structured-output part is on the assistant message after
   // the latest user message. When no user message exists yet, return null
   // rather than scanning history — otherwise a stale `final` from
@@ -337,7 +383,14 @@ export function useChat<
     addToolResult,
     addToolApprovalResponse,
     resumeState,
+    interrupts,
     pendingInterrupts,
+    interruptErrors,
+    resuming,
+    resolveInterrupts,
+    cancelInterrupts,
+    retryInterrupts,
+    resumeInterruptsUnsafe,
     resumeInterrupts,
     partial,
     final,
diff --git a/packages/ai-solid/tests/test-utils.ts b/packages/ai-solid/tests/test-utils.ts
index 82bff2ad7..b45cce38f 100644
--- a/packages/ai-solid/tests/test-utils.ts
+++ b/packages/ai-solid/tests/test-utils.ts
@@ -10,6 +10,81 @@ import { renderHook } from '@solidjs/testing-library'
 import type { UseChatOptions } from '../src/types'
 import { useChat } from '../src/use-chat'
 
+import type { ChatResumeSnapshotV2 } from '@tanstack/ai-client'
+
+export function createInterruptResumeSnapshot(): ChatResumeSnapshotV2 {
+  const pendingInterrupts = [
+    {
+      id: 'staged-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'staged-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+    {
+      id: 'invalid-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'invalid-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+  ]
+  return {
+    schemaVersion: 2,
+    resumeState: { threadId: 'thread-1', runId: 'run-1' },
+    pendingInterrupts,
+    interruptState: {
+      recoveryState: {
+        schemaVersion: 1,
+        state: 'pending',
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+        pendingInterrupts,
+      },
+      drafts: [
+        {
+          interruptId: 'staged-interrupt',
+          response: {
+            interruptId: 'staged-interrupt',
+            status: 'resolved',
+            payload: { answer: 42 },
+          },
+          status: 'staged',
+        },
+        {
+          interruptId: 'invalid-interrupt',
+          response: null,
+          status: 'error',
+          error: {
+            scope: 'item',
+            interruptId: 'invalid-interrupt',
+            code: 'invalid-payload',
+            message: 'Invalid persisted response',
+            source: 'client',
+            retryable: false,
+            threadId: 'thread-1',
+            interruptedRunId: 'run-1',
+            generation: 1,
+          },
+        },
+      ],
+    },
+  }
+}
+
 /**
  * Render the useChat hook with testing utilities
  *
diff --git a/packages/ai-solid/tests/use-chat-types.test.ts b/packages/ai-solid/tests/use-chat-types.test.ts
index aa2e7c878..3b40461d1 100644
--- a/packages/ai-solid/tests/use-chat-types.test.ts
+++ b/packages/ai-solid/tests/use-chat-types.test.ts
@@ -14,6 +14,14 @@ import type { DeepPartial, UseChatOptions, UseChatReturn } from '../src/types'
 type Person = { name: string; age: number; email: string }
 type PersonSchema = StandardJSONSchemaV1<Person, Person>
 type NoTools = ReadonlyArray<AnyClientTool>
+type TestSchema<T> = {
+  readonly '~standard': {
+    readonly version: 1
+    readonly vendor: 'test'
+    readonly types: { readonly input: T; readonly output: T }
+    readonly validate: (value: unknown) => { readonly value: T }
+  }
+}
 
 describe('useChat() return type (solid)', () => {
   describe('with outputSchema', () => {
@@ -137,3 +145,127 @@ describe('useChat() return type (solid)', () => {
     })
   })
 })
+
+describe('useChat() interrupt types', () => {
+  it('preserves approval, generic, and client-tool inference', () => {
+    const inputSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { cents: 0 },
+          output: { cents: 0 },
+        },
+        validate: (value: unknown) => ({
+          value:
+            value !== null &&
+            typeof value === 'object' &&
+            'cents' in value &&
+            typeof value.cents === 'number'
+              ? { cents: value.cents }
+              : { cents: 0 },
+        }),
+      },
+    }
+    const approveSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { note: '' },
+          output: { note: '' },
+        },
+        validate: () => ({ value: { note: '' } }),
+      },
+    }
+    const rejectSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { reason: '' },
+          output: { reason: '' },
+        },
+        validate: () => ({ value: { reason: '' } }),
+      },
+    }
+    const outputSchema: TestSchema<{ accountId: string }> = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { accountId: '' },
+          output: { accountId: '' },
+        },
+        validate: () => ({ value: { accountId: '' } }),
+      },
+    }
+    const transfer = toolDefinition({
+      name: 'transfer',
+      description: 'Transfer funds',
+      needsApproval: true,
+      inputSchema,
+      approvalSchema: {
+        approve: approveSchema,
+        reject: rejectSchema,
+      },
+    }).client()
+    const confirm = toolDefinition({
+      name: 'confirm',
+      description: 'Confirm without schemas',
+      needsApproval: true,
+    }).client()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Lookup account',
+      outputSchema,
+    }).client()
+    const tools = clientTools(transfer, confirm, lookup)
+    type Interrupt = ReturnType<
+      UseChatReturn<typeof tools>['interrupts']
+    >[number]
+    type Transfer = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'transfer' }
+    >
+    type Confirm = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'confirm' }
+    >
+    type Generic = Extract<Interrupt, { kind: 'generic' }>
+
+    const check = (
+      transferInterrupt: Transfer,
+      confirmInterrupt: Confirm,
+      genericInterrupt: Generic,
+    ) => {
+      transferInterrupt.resolveInterrupt(true, {
+        editedArgs: { cents: 100 },
+        payload: { note: 'approved' },
+      })
+      transferInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'declined' },
+      })
+      // @ts-expect-error rejected approvals cannot edit tool input
+      transferInterrupt.resolveInterrupt(false, { editedArgs: { cents: 1 } })
+      // @ts-expect-error approve payload uses the approve branch
+      transferInterrupt.resolveInterrupt(true, {
+        payload: { reason: 'wrong branch' },
+      })
+
+      confirmInterrupt.resolveInterrupt(true)
+      confirmInterrupt.resolveInterrupt(false)
+      // @ts-expect-error omitted input schema forbids edited input
+      confirmInterrupt.resolveInterrupt(true, { editedArgs: { cents: 1 } })
+      // @ts-expect-error omitted approval branches forbid payloads
+      confirmInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'no branch' },
+      })
+
+      expectTypeOf(genericInterrupt.resolveInterrupt)
+        .parameter(0)
+        .toEqualTypeOf<unknown>()
+    }
+    void check
+  })
+})
diff --git a/packages/ai-solid/tests/use-chat.test.ts b/packages/ai-solid/tests/use-chat.test.ts
index f2c9c0524..23d25a806 100644
--- a/packages/ai-solid/tests/use-chat.test.ts
+++ b/packages/ai-solid/tests/use-chat.test.ts
@@ -1,15 +1,97 @@
-import { waitFor } from '@solidjs/testing-library'
+import { renderHook, waitFor } from '@solidjs/testing-library'
 import type { ModelMessage } from '@tanstack/ai'
+import { ChatClient } from '@tanstack/ai-client'
 import { describe, expect, it, vi } from 'vitest'
 import type { UIMessage } from '../src/types'
+import { useChat } from '../src/use-chat'
 import {
   createMockConnectionAdapter,
+  createInterruptResumeSnapshot,
   createTextChunks,
   createToolCallChunks,
   renderUseChat,
 } from './test-utils'
 
 describe('useChat', () => {
+  describe('interrupt state', () => {
+    it('projects one immutable reactive snapshot with the deprecated pending alias', async () => {
+      const onInterruptStateChange = vi.fn()
+      const rendered = renderHook(() =>
+        useChat({
+          connection: createMockConnectionAdapter(),
+          initialResumeSnapshot: createInterruptResumeSnapshot(),
+          onInterruptStateChange,
+        }),
+      )
+      const chat = rendered.result
+
+      expect(Object.isFrozen(chat.interrupts())).toBe(true)
+      expect(chat.pendingInterrupts()).toBe(chat.interrupts())
+      expect(chat.interrupts()[0]).toMatchObject({
+        id: 'staged-interrupt',
+        status: 'staged',
+      })
+      expect(chat.interrupts()[1]).toMatchObject({
+        id: 'invalid-interrupt',
+        status: 'error',
+        error: { code: 'invalid-payload' },
+      })
+      expect(chat.interruptErrors()).toEqual([])
+      expect(chat.resuming()).toBe(false)
+      expect(chat.interrupts()[0]).toEqual(
+        expect.objectContaining({
+          resolveInterrupt: expect.any(Function),
+          cancel: expect.any(Function),
+          clearResolution: expect.any(Function),
+        }),
+      )
+
+      chat.resolveInterrupts(false)
+      await waitFor(() => {
+        expect(chat.interruptErrors()[0]?.code).toBe(
+          'unsupported-bulk-operation',
+        )
+      })
+      expect(onInterruptStateChange).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          interrupts: chat.interrupts(),
+          interruptErrors: chat.interruptErrors(),
+        }),
+      )
+    })
+
+    it('delegates every root interrupt control to ChatClient', async () => {
+      const resolve = vi
+        .spyOn(ChatClient.prototype, 'resolveInterrupts')
+        .mockImplementation(() => {})
+      const cancel = vi
+        .spyOn(ChatClient.prototype, 'cancelInterrupts')
+        .mockImplementation(() => {})
+      const retry = vi
+        .spyOn(ChatClient.prototype, 'retryInterrupts')
+        .mockImplementation(() => {})
+      const unsafe = vi
+        .spyOn(ChatClient.prototype, 'resumeInterruptsUnsafe')
+        .mockResolvedValue(true)
+      const rendered = renderHook(() =>
+        useChat({ connection: createMockConnectionAdapter() }),
+      )
+      const chat = rendered.result
+      const resolver = () => undefined
+      const resume = [{ interruptId: 'one', status: 'cancelled' as const }]
+
+      chat.resolveInterrupts(resolver)
+      chat.cancelInterrupts()
+      chat.retryInterrupts()
+      await expect(chat.resumeInterruptsUnsafe(resume)).resolves.toBe(true)
+
+      expect(resolve).toHaveBeenCalledWith(resolver)
+      expect(cancel).toHaveBeenCalledOnce()
+      expect(retry).toHaveBeenCalledOnce()
+      expect(unsafe).toHaveBeenCalledWith(resume, undefined)
+    })
+  })
+
   describe('initialization', () => {
     it('should initialize with default state', () => {
       const adapter = createMockConnectionAdapter()
diff --git a/packages/ai-svelte/src/create-chat.svelte.ts b/packages/ai-svelte/src/create-chat.svelte.ts
index 91db27ceb..ed97a4d8c 100644
--- a/packages/ai-svelte/src/create-chat.svelte.ts
+++ b/packages/ai-svelte/src/create-chat.svelte.ts
@@ -3,7 +3,8 @@ import { createChatDevtoolsBridge } from '@tanstack/ai-client/devtools'
 import { onMount } from 'svelte'
 import type {
   ChatClientState,
-  ChatPendingInterrupt,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
@@ -25,6 +26,9 @@ import type {
   UIMessage,
 } from './types'
 
+const EMPTY_INTERRUPTS = Object.freeze([])
+const EMPTY_INTERRUPT_ERRORS = Object.freeze([])
+
 /**
  * Creates a reactive chat instance for Svelte 5.
  *
@@ -78,9 +82,12 @@ export function createChat<
   let resumeState = $state<ChatResumeState | null>(
     options.initialResumeSnapshot?.resumeState ?? null,
   )
-  let pendingInterrupts = $state<Array<ChatPendingInterrupt>>(
-    options.initialResumeSnapshot?.pendingInterrupts ?? [],
-  )
+  let interruptState = $state.raw<ChatInterruptState<TTools>>({
+    interrupts: EMPTY_INTERRUPTS,
+    pendingInterrupts: EMPTY_INTERRUPTS,
+    interruptErrors: EMPTY_INTERRUPT_ERRORS,
+    resuming: false,
+  })
 
   // Structured-output `partial` / `final` are derived from `messages` —
   // specifically from the structured-output part on the latest assistant
@@ -167,18 +174,22 @@ export function createChat<
     onSessionGeneratingChange: (isGenerating: boolean) => {
       sessionGenerating = isGenerating
     },
-    onResumeStateChange: (nextResumeState, nextPendingInterrupts) => {
+    onResumeStateChange: (nextResumeState) => {
       resumeState = nextResumeState
-      pendingInterrupts = nextPendingInterrupts
+    },
+    onInterruptStateChange: (nextInterruptState) => {
+      interruptState = nextInterruptState
+      options.onInterruptStateChange?.(nextInterruptState)
     },
   })
 
   function syncResumeState() {
     resumeState = client.getResumeState()
-    pendingInterrupts = client.getPendingInterrupts()
+    interruptState = client.getInterruptState()
   }
 
   messages = client.getMessages()
+  interruptState = client.getInterruptState()
 
   if (options.live) {
     client.subscribe()
@@ -273,6 +284,29 @@ export function createChat<
     return result
   }
 
+  const resolveInterrupts = (
+    resolution: boolean | ((interrupt: ChatInterrupt<TTools>) => undefined),
+  ) => {
+    if (typeof resolution === 'boolean') {
+      client.resolveInterrupts(resolution)
+    } else {
+      client.resolveInterrupts(resolution)
+    }
+  }
+
+  const cancelInterrupts = () => {
+    client.cancelInterrupts()
+  }
+
+  const retryInterrupts = () => {
+    client.retryInterrupts()
+  }
+
+  const resumeInterruptsUnsafe = (
+    resumeItems: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => client.resumeInterruptsUnsafe(resumeItems, state)
+
   /**
    * @deprecated Use `updateForwardedProps` instead.
    * Both populate the same wire payload.
@@ -355,8 +389,17 @@ export function createChat<
     get resumeState() {
       return resumeState
     },
+    get interrupts() {
+      return interruptState.interrupts
+    },
     get pendingInterrupts() {
-      return pendingInterrupts
+      return interruptState.interrupts
+    },
+    get interruptErrors() {
+      return interruptState.interruptErrors
+    },
+    get resuming() {
+      return interruptState.resuming
     },
     get partial() {
       return partial
@@ -373,6 +416,10 @@ export function createChat<
     clear,
     addToolResult,
     addToolApprovalResponse,
+    resolveInterrupts,
+    cancelInterrupts,
+    retryInterrupts,
+    resumeInterruptsUnsafe,
     resumeInterrupts,
     updateBody,
     updateForwardedProps,
diff --git a/packages/ai-svelte/src/types.ts b/packages/ai-svelte/src/types.ts
index e416fdb15..beb6371dc 100644
--- a/packages/ai-svelte/src/types.ts
+++ b/packages/ai-svelte/src/types.ts
@@ -7,9 +7,11 @@ import type {
 } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
+  BoundInterrupts,
   ChatClientOptions,
   ChatClientState,
-  ChatPendingInterrupt,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatRequestBody,
   ChatResumeState,
   ClientContextOptionFromTools,
@@ -157,7 +159,22 @@ interface BaseCreateChatReturn<
   }) => Promise<void>
 
   readonly resumeState: ChatResumeState | null
-  readonly pendingInterrupts: Array<ChatPendingInterrupt>
+  readonly interrupts: BoundInterrupts<TTools>
+  /** @deprecated Use `interrupts`. */
+  readonly pendingInterrupts: BoundInterrupts<TTools>
+  readonly interruptErrors: ChatInterruptState<TTools>['interruptErrors']
+  readonly resuming: boolean
+  resolveInterrupts: {
+    (approved: boolean): void
+    (resolver: (interrupt: ChatInterrupt<TTools>) => undefined): void
+  }
+  cancelInterrupts: () => void
+  retryInterrupts: () => void
+  resumeInterruptsUnsafe: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+  /** @deprecated Use bound interrupt methods or `resumeInterruptsUnsafe`. */
   resumeInterrupts: (
     resume: Array<RunAgentResumeItem>,
     state?: ChatResumeState,
diff --git a/packages/ai-svelte/tests/create-chat-types.test.ts b/packages/ai-svelte/tests/create-chat-types.test.ts
index b647e49b1..d55f136d4 100644
--- a/packages/ai-svelte/tests/create-chat-types.test.ts
+++ b/packages/ai-svelte/tests/create-chat-types.test.ts
@@ -4,7 +4,10 @@
  */
 
 import { describe, expectTypeOf, it } from 'vitest'
-import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from '@standard-schema/spec'
 import { toolDefinition, type AnyClientTool } from '@tanstack/ai'
 import { clientTools, type StructuredOutputPart } from '@tanstack/ai-client'
 import { createChat } from '../src/create-chat.svelte'
@@ -136,3 +139,128 @@ describe('createChat() return type (svelte)', () => {
     })
   })
 })
+
+describe('createChat() interrupt types', () => {
+  it('preserves approval, generic, and client-tool inference', () => {
+    const inputSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { cents: 0 },
+          output: { cents: 0 },
+        },
+        validate: (value: unknown) => ({
+          value:
+            value !== null &&
+            typeof value === 'object' &&
+            'cents' in value &&
+            typeof value.cents === 'number'
+              ? { cents: value.cents }
+              : { cents: 0 },
+        }),
+      },
+    }
+    const approveSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { note: '' },
+          output: { note: '' },
+        },
+        validate: () => ({ value: { note: '' } }),
+      },
+    }
+    const rejectSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { reason: '' },
+          output: { reason: '' },
+        },
+        validate: () => ({ value: { reason: '' } }),
+      },
+    }
+    const outputSchema: StandardSchemaV1<
+      { accountId: string },
+      { accountId: string }
+    > = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { accountId: '' },
+          output: { accountId: '' },
+        },
+        validate: () => ({ value: { accountId: '' } }),
+      },
+    }
+    const transfer = toolDefinition({
+      name: 'transfer',
+      description: 'Transfer funds',
+      needsApproval: true,
+      inputSchema,
+      approvalSchema: {
+        approve: approveSchema,
+        reject: rejectSchema,
+      },
+    }).client()
+    const confirm = toolDefinition({
+      name: 'confirm',
+      description: 'Confirm without schemas',
+      needsApproval: true,
+    }).client()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Lookup account',
+      outputSchema,
+    }).client(() => ({ accountId: 'account-1' }))
+    const tools = clientTools(transfer, confirm, lookup)
+    type Interrupt = CreateChatReturn<typeof tools>['interrupts'][number]
+    type Transfer = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'transfer' }
+    >
+    type Confirm = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'confirm' }
+    >
+    type Generic = Extract<Interrupt, { kind: 'generic' }>
+
+    const check = (
+      transferInterrupt: Transfer,
+      confirmInterrupt: Confirm,
+      genericInterrupt: Generic,
+    ) => {
+      transferInterrupt.resolveInterrupt(true, {
+        editedArgs: { cents: 100 },
+        payload: { note: 'approved' },
+      })
+      transferInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'declined' },
+      })
+      // @ts-expect-error rejected approvals cannot edit tool input
+      transferInterrupt.resolveInterrupt(false, { editedArgs: { cents: 1 } })
+      // @ts-expect-error approve payload uses the approve branch
+      transferInterrupt.resolveInterrupt(true, {
+        payload: { reason: 'wrong branch' },
+      })
+
+      confirmInterrupt.resolveInterrupt(true)
+      confirmInterrupt.resolveInterrupt(false)
+      // @ts-expect-error omitted input schema forbids edited input
+      confirmInterrupt.resolveInterrupt(true, { editedArgs: { cents: 1 } })
+      // @ts-expect-error omitted approval branches forbid payloads
+      confirmInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'no branch' },
+      })
+
+      expectTypeOf(genericInterrupt.resolveInterrupt)
+        .parameter(0)
+        .toEqualTypeOf<unknown>()
+    }
+    void check
+  })
+})
diff --git a/packages/ai-svelte/tests/test-utils.ts b/packages/ai-svelte/tests/test-utils.ts
index 2f6fe6e64..ae356b74d 100644
--- a/packages/ai-svelte/tests/test-utils.ts
+++ b/packages/ai-svelte/tests/test-utils.ts
@@ -4,3 +4,79 @@ export {
   createTextChunks,
   createToolCallChunks,
 } from '../../ai-client/tests/test-utils'
+
+import type { ChatResumeSnapshotV2 } from '@tanstack/ai-client'
+
+export function createInterruptResumeSnapshot(): ChatResumeSnapshotV2 {
+  const pendingInterrupts = [
+    {
+      id: 'staged-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'staged-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+    {
+      id: 'invalid-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'invalid-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+  ]
+
+  return {
+    schemaVersion: 2,
+    resumeState: { threadId: 'thread-1', runId: 'run-1' },
+    pendingInterrupts,
+    interruptState: {
+      recoveryState: {
+        schemaVersion: 1,
+        state: 'pending',
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+        pendingInterrupts,
+      },
+      drafts: [
+        {
+          interruptId: 'staged-interrupt',
+          response: {
+            interruptId: 'staged-interrupt',
+            status: 'resolved',
+            payload: { answer: 42 },
+          },
+          status: 'staged',
+        },
+        {
+          interruptId: 'invalid-interrupt',
+          response: null,
+          status: 'error',
+          error: {
+            scope: 'item',
+            interruptId: 'invalid-interrupt',
+            code: 'invalid-payload',
+            message: 'Invalid persisted response',
+            source: 'client',
+            retryable: false,
+            threadId: 'thread-1',
+            interruptedRunId: 'run-1',
+            generation: 1,
+          },
+        },
+      ],
+    },
+  }
+}
diff --git a/packages/ai-svelte/tests/use-chat.test.ts b/packages/ai-svelte/tests/use-chat.test.ts
index fd6fe11ef..38bf3f4e1 100644
--- a/packages/ai-svelte/tests/use-chat.test.ts
+++ b/packages/ai-svelte/tests/use-chat.test.ts
@@ -1,12 +1,92 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ChatClient } from '@tanstack/ai-client'
+import { tick } from 'svelte'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createChat } from '../src/create-chat.svelte'
-import { createMockConnectionAdapter, createTextChunks } from './test-utils'
+import {
+  createInterruptResumeSnapshot,
+  createMockConnectionAdapter,
+  createTextChunks,
+} from './test-utils'
 
 describe('createChat', () => {
   beforeEach(() => {
     vi.clearAllMocks()
   })
 
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('interrupt state', () => {
+    it('projects one immutable reactive snapshot with the deprecated pending alias', async () => {
+      const onInterruptStateChange = vi.fn()
+      const chat = createChat({
+        connection: createMockConnectionAdapter(),
+        initialResumeSnapshot: createInterruptResumeSnapshot(),
+        onInterruptStateChange,
+      })
+
+      expect(Object.isFrozen(chat.interrupts)).toBe(true)
+      expect(chat.pendingInterrupts).toBe(chat.interrupts)
+      expect(chat.interrupts[0]).toMatchObject({
+        id: 'staged-interrupt',
+        status: 'staged',
+      })
+      expect(chat.interrupts[1]).toMatchObject({
+        id: 'invalid-interrupt',
+        status: 'error',
+        error: { code: 'invalid-payload' },
+      })
+      expect(chat.interruptErrors).toEqual([])
+      expect(chat.resuming).toBe(false)
+      expect(chat.interrupts[0]).toEqual(
+        expect.objectContaining({
+          resolveInterrupt: expect.any(Function),
+          cancel: expect.any(Function),
+          clearResolution: expect.any(Function),
+        }),
+      )
+
+      chat.resolveInterrupts(false)
+      await tick()
+      expect(chat.interruptErrors[0]?.code).toBe('unsupported-bulk-operation')
+      expect(onInterruptStateChange).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          interrupts: chat.interrupts,
+          interruptErrors: chat.interruptErrors,
+        }),
+      )
+    })
+
+    it('delegates every root interrupt control to ChatClient', async () => {
+      const resolve = vi
+        .spyOn(ChatClient.prototype, 'resolveInterrupts')
+        .mockImplementation(() => {})
+      const cancel = vi
+        .spyOn(ChatClient.prototype, 'cancelInterrupts')
+        .mockImplementation(() => {})
+      const retry = vi
+        .spyOn(ChatClient.prototype, 'retryInterrupts')
+        .mockImplementation(() => {})
+      const unsafe = vi
+        .spyOn(ChatClient.prototype, 'resumeInterruptsUnsafe')
+        .mockResolvedValue(true)
+      const chat = createChat({ connection: createMockConnectionAdapter() })
+      const resolver = () => undefined
+      const resume = [{ interruptId: 'one', status: 'cancelled' as const }]
+
+      chat.resolveInterrupts(resolver)
+      chat.cancelInterrupts()
+      chat.retryInterrupts()
+      await expect(chat.resumeInterruptsUnsafe(resume)).resolves.toBe(true)
+
+      expect(resolve).toHaveBeenCalledWith(resolver)
+      expect(cancel).toHaveBeenCalledOnce()
+      expect(retry).toHaveBeenCalledOnce()
+      expect(unsafe).toHaveBeenCalledWith(resume, undefined)
+    })
+  })
+
   it('should initialize with empty messages', () => {
     const mockConnection = createMockConnectionAdapter({ chunks: [] })
 
diff --git a/packages/ai-vue/src/types.ts b/packages/ai-vue/src/types.ts
index 3c824e7df..38a56bc14 100644
--- a/packages/ai-vue/src/types.ts
+++ b/packages/ai-vue/src/types.ts
@@ -7,9 +7,11 @@ import type {
 } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
+  BoundInterrupts,
   ChatClientOptions,
   ChatClientState,
-  ChatPendingInterrupt,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatRequestBody,
   ChatResumeState,
   ClientContextOptionFromTools,
@@ -155,7 +157,24 @@ interface BaseUseChatReturn<
   }) => Promise<void>
 
   resumeState: DeepReadonly<ShallowRef<ChatResumeState | null>>
-  pendingInterrupts: DeepReadonly<ShallowRef<Array<ChatPendingInterrupt>>>
+  interrupts: DeepReadonly<ShallowRef<BoundInterrupts<TTools>>>
+  /** @deprecated Use `interrupts`. */
+  pendingInterrupts: DeepReadonly<ShallowRef<BoundInterrupts<TTools>>>
+  interruptErrors: DeepReadonly<
+    ShallowRef<ChatInterruptState<TTools>['interruptErrors']>
+  >
+  resuming: DeepReadonly<ShallowRef<boolean>>
+  resolveInterrupts: {
+    (approved: boolean): void
+    (resolver: (interrupt: ChatInterrupt<TTools>) => undefined): void
+  }
+  cancelInterrupts: () => void
+  retryInterrupts: () => void
+  resumeInterruptsUnsafe: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+  /** @deprecated Use bound interrupt methods or `resumeInterruptsUnsafe`. */
   resumeInterrupts: (
     resume: Array<RunAgentResumeItem>,
     state?: ChatResumeState,
diff --git a/packages/ai-vue/src/use-chat.ts b/packages/ai-vue/src/use-chat.ts
index e6bb219d9..ec6aef00f 100644
--- a/packages/ai-vue/src/use-chat.ts
+++ b/packages/ai-vue/src/use-chat.ts
@@ -19,7 +19,8 @@ import type {
 } from '@tanstack/ai'
 import type {
   ChatClientState,
-  ChatPendingInterrupt,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
@@ -33,6 +34,9 @@ import type {
   UseChatReturn,
 } from './types'
 
+const EMPTY_INTERRUPTS = Object.freeze([])
+const EMPTY_INTERRUPT_ERRORS = Object.freeze([])
+
 export function useChat<
   const TTools extends ReadonlyArray<AnyClientTool> = any,
   TSchema extends SchemaInput | undefined = undefined,
@@ -59,9 +63,12 @@ export function useChat<
   const resumeState = shallowRef<ChatResumeState | null>(
     options.initialResumeSnapshot?.resumeState ?? null,
   )
-  const pendingInterrupts = shallowRef<Array<ChatPendingInterrupt>>(
-    options.initialResumeSnapshot?.pendingInterrupts ?? [],
-  )
+  const interruptState = shallowRef<ChatInterruptState<TTools>>({
+    interrupts: EMPTY_INTERRUPTS,
+    pendingInterrupts: EMPTY_INTERRUPTS,
+    interruptErrors: EMPTY_INTERRUPT_ERRORS,
+    resuming: false,
+  })
 
   // Structured-output `partial` / `final` are derived from `messages` —
   // specifically from the structured-output part on the latest assistant
@@ -151,18 +158,22 @@ export function useChat<
     onSessionGeneratingChange: (isGenerating: boolean) => {
       sessionGenerating.value = isGenerating
     },
-    onResumeStateChange: (nextResumeState, nextPendingInterrupts) => {
+    onResumeStateChange: (nextResumeState) => {
       resumeState.value = nextResumeState
-      pendingInterrupts.value = nextPendingInterrupts
+    },
+    onInterruptStateChange: (nextInterruptState) => {
+      interruptState.value = nextInterruptState
+      options.onInterruptStateChange?.(nextInterruptState)
     },
   })
 
   function syncResumeState() {
     resumeState.value = client.getResumeState()
-    pendingInterrupts.value = client.getPendingInterrupts()
+    interruptState.value = client.getInterruptState()
   }
 
   messages.value = client.getMessages()
+  interruptState.value = client.getInterruptState()
 
   // Sync body / forwardedProps changes to the client.
   // Both populate the same wire payload; `forwardedProps` is preferred
@@ -280,6 +291,34 @@ export function useChat<
     return result
   }
 
+  const interrupts = computed(() => interruptState.value.interrupts)
+  const pendingInterrupts = computed(() => interruptState.value.interrupts)
+  const interruptErrors = computed(() => interruptState.value.interruptErrors)
+  const resuming = computed(() => interruptState.value.resuming)
+
+  const resolveInterrupts = (
+    resolution: boolean | ((interrupt: ChatInterrupt<TTools>) => undefined),
+  ) => {
+    if (typeof resolution === 'boolean') {
+      client.resolveInterrupts(resolution)
+    } else {
+      client.resolveInterrupts(resolution)
+    }
+  }
+
+  const cancelInterrupts = () => {
+    client.cancelInterrupts()
+  }
+
+  const retryInterrupts = () => {
+    client.retryInterrupts()
+  }
+
+  const resumeInterruptsUnsafe = (
+    resumeItems: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => client.resumeInterruptsUnsafe(resumeItems, state)
+
   // The "active" structured-output part is the one on the assistant message
   // that follows the latest user message. No such message exists between
   // sendMessage() and the first chunk, so partial/final naturally read as
@@ -342,7 +381,14 @@ export function useChat<
     addToolResult,
     addToolApprovalResponse,
     resumeState: readonly(resumeState),
+    interrupts: readonly(interrupts),
     pendingInterrupts: readonly(pendingInterrupts),
+    interruptErrors: readonly(interruptErrors),
+    resuming: readonly(resuming),
+    resolveInterrupts,
+    cancelInterrupts,
+    retryInterrupts,
+    resumeInterruptsUnsafe,
     resumeInterrupts,
     partial: readonly(partial),
     final: readonly(final),
diff --git a/packages/ai-vue/tests/test-utils.ts b/packages/ai-vue/tests/test-utils.ts
index 3f8c05c46..b0b68951c 100644
--- a/packages/ai-vue/tests/test-utils.ts
+++ b/packages/ai-vue/tests/test-utils.ts
@@ -1,4 +1,4 @@
-import type { UIMessage } from '@tanstack/ai-client'
+import type { ChatResumeSnapshotV2, UIMessage } from '@tanstack/ai-client'
 import { mount } from '@vue/test-utils'
 import { defineComponent } from 'vue'
 import type { UseChatOptions } from '../src/types'
@@ -11,6 +11,80 @@ export {
   createToolCallChunks,
 } from '../../ai-client/tests/test-utils'
 
+export function createInterruptResumeSnapshot(): ChatResumeSnapshotV2 {
+  const pendingInterrupts = [
+    {
+      id: 'staged-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'staged-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+    {
+      id: 'invalid-interrupt',
+      reason: 'confirmation',
+      metadata: {
+        'tanstack:interruptBinding': {
+          kind: 'generic' as const,
+          interruptId: 'invalid-interrupt',
+          interruptedRunId: 'run-1',
+          generation: 1,
+          responseSchemaHash: 'none',
+        },
+      },
+    },
+  ]
+
+  return {
+    schemaVersion: 2,
+    resumeState: { threadId: 'thread-1', runId: 'run-1' },
+    pendingInterrupts,
+    interruptState: {
+      recoveryState: {
+        schemaVersion: 1,
+        state: 'pending',
+        threadId: 'thread-1',
+        interruptedRunId: 'run-1',
+        generation: 1,
+        pendingInterrupts,
+      },
+      drafts: [
+        {
+          interruptId: 'staged-interrupt',
+          response: {
+            interruptId: 'staged-interrupt',
+            status: 'resolved',
+            payload: { answer: 42 },
+          },
+          status: 'staged',
+        },
+        {
+          interruptId: 'invalid-interrupt',
+          response: null,
+          status: 'error',
+          error: {
+            scope: 'item',
+            interruptId: 'invalid-interrupt',
+            code: 'invalid-payload',
+            message: 'Invalid persisted response',
+            source: 'client',
+            retryable: false,
+            threadId: 'thread-1',
+            interruptedRunId: 'run-1',
+            generation: 1,
+          },
+        },
+      ],
+    },
+  }
+}
+
 /**
  * Render the useChat hook with testing utilities
  *
@@ -54,6 +128,14 @@ export function renderUseChat(options?: UseChatOptions) {
       setMessages: hook.setMessages,
       addToolResult: hook.addToolResult,
       addToolApprovalResponse: hook.addToolApprovalResponse,
+      interrupts: hook.interrupts,
+      pendingInterrupts: hook.pendingInterrupts,
+      interruptErrors: hook.interruptErrors,
+      resuming: hook.resuming,
+      resolveInterrupts: hook.resolveInterrupts,
+      cancelInterrupts: hook.cancelInterrupts,
+      retryInterrupts: hook.retryInterrupts,
+      resumeInterruptsUnsafe: hook.resumeInterruptsUnsafe,
     }
   }
 
diff --git a/packages/ai-vue/tests/use-chat-types.test.ts b/packages/ai-vue/tests/use-chat-types.test.ts
index 518c47b02..88a89571d 100644
--- a/packages/ai-vue/tests/use-chat-types.test.ts
+++ b/packages/ai-vue/tests/use-chat-types.test.ts
@@ -4,7 +4,10 @@
  */
 
 import { describe, expectTypeOf, it } from 'vitest'
-import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from '@standard-schema/spec'
 import { toolDefinition, type AnyClientTool } from '@tanstack/ai'
 import { clientTools, type StructuredOutputPart } from '@tanstack/ai-client'
 import type { ShallowRef } from 'vue'
@@ -131,3 +134,128 @@ describe('useChat() return type (vue)', () => {
     })
   })
 })
+
+describe('useChat() interrupt types', () => {
+  it('preserves approval, generic, and client-tool inference', () => {
+    const inputSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { cents: 0 },
+          output: { cents: 0 },
+        },
+        validate: (value: unknown) => ({
+          value:
+            value !== null &&
+            typeof value === 'object' &&
+            'cents' in value &&
+            typeof value.cents === 'number'
+              ? { cents: value.cents }
+              : { cents: 0 },
+        }),
+      },
+    }
+    const approveSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { note: '' },
+          output: { note: '' },
+        },
+        validate: () => ({ value: { note: '' } }),
+      },
+    }
+    const rejectSchema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { reason: '' },
+          output: { reason: '' },
+        },
+        validate: () => ({ value: { reason: '' } }),
+      },
+    }
+    const outputSchema: StandardSchemaV1<
+      { accountId: string },
+      { accountId: string }
+    > = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        types: {
+          input: { accountId: '' },
+          output: { accountId: '' },
+        },
+        validate: () => ({ value: { accountId: '' } }),
+      },
+    }
+    const transfer = toolDefinition({
+      name: 'transfer',
+      description: 'Transfer funds',
+      needsApproval: true,
+      inputSchema,
+      approvalSchema: {
+        approve: approveSchema,
+        reject: rejectSchema,
+      },
+    }).client()
+    const confirm = toolDefinition({
+      name: 'confirm',
+      description: 'Confirm without schemas',
+      needsApproval: true,
+    }).client()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Lookup account',
+      outputSchema,
+    }).client(() => ({ accountId: 'account-1' }))
+    const tools = clientTools(transfer, confirm, lookup)
+    type Interrupt = UseChatReturn<typeof tools>['interrupts']['value'][number]
+    type Transfer = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'transfer' }
+    >
+    type Confirm = Extract<
+      Interrupt,
+      { kind: 'tool-approval'; toolName: 'confirm' }
+    >
+    type Generic = Extract<Interrupt, { kind: 'generic' }>
+
+    const check = (
+      transferInterrupt: Transfer,
+      confirmInterrupt: Confirm,
+      genericInterrupt: Generic,
+    ) => {
+      transferInterrupt.resolveInterrupt(true, {
+        editedArgs: { cents: 100 },
+        payload: { note: 'approved' },
+      })
+      transferInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'declined' },
+      })
+      // @ts-expect-error rejected approvals cannot edit tool input
+      transferInterrupt.resolveInterrupt(false, { editedArgs: { cents: 1 } })
+      // @ts-expect-error approve payload uses the approve branch
+      transferInterrupt.resolveInterrupt(true, {
+        payload: { reason: 'wrong branch' },
+      })
+
+      confirmInterrupt.resolveInterrupt(true)
+      confirmInterrupt.resolveInterrupt(false)
+      // @ts-expect-error omitted input schema forbids edited input
+      confirmInterrupt.resolveInterrupt(true, { editedArgs: { cents: 1 } })
+      // @ts-expect-error omitted approval branches forbid payloads
+      confirmInterrupt.resolveInterrupt(false, {
+        payload: { reason: 'no branch' },
+      })
+
+      expectTypeOf(genericInterrupt.resolveInterrupt)
+        .parameter(0)
+        .toEqualTypeOf<unknown>()
+    }
+    void check
+  })
+})
diff --git a/packages/ai-vue/tests/use-chat.test.ts b/packages/ai-vue/tests/use-chat.test.ts
index b513ef2c0..a334a392c 100644
--- a/packages/ai-vue/tests/use-chat.test.ts
+++ b/packages/ai-vue/tests/use-chat.test.ts
@@ -1,15 +1,97 @@
 import type { ModelMessage } from '@tanstack/ai'
+import { ChatClient } from '@tanstack/ai-client'
 import { flushPromises } from '@vue/test-utils'
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { UIMessage } from '../src/types'
 import {
   createMockConnectionAdapter,
+  createInterruptResumeSnapshot,
   createTextChunks,
   createToolCallChunks,
   renderUseChat,
 } from './test-utils'
 
 describe('useChat', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('interrupt state', () => {
+    it('projects one immutable reactive snapshot with the deprecated pending alias', async () => {
+      const onInterruptStateChange = vi.fn()
+      const { result } = renderUseChat({
+        connection: createMockConnectionAdapter(),
+        initialResumeSnapshot: createInterruptResumeSnapshot(),
+        onInterruptStateChange,
+      })
+
+      expect(Object.isFrozen(result.current.interrupts)).toBe(true)
+      expect(result.current.pendingInterrupts).toBe(result.current.interrupts)
+      expect(result.current.interrupts[0]).toMatchObject({
+        id: 'staged-interrupt',
+        status: 'staged',
+      })
+      expect(result.current.interrupts[1]).toMatchObject({
+        id: 'invalid-interrupt',
+        status: 'error',
+        error: { code: 'invalid-payload' },
+      })
+      expect(result.current.interruptErrors).toEqual([])
+      expect(result.current.resuming).toBe(false)
+      expect(result.current.interrupts[0]).toEqual(
+        expect.objectContaining({
+          resolveInterrupt: expect.any(Function),
+          cancel: expect.any(Function),
+          clearResolution: expect.any(Function),
+        }),
+      )
+
+      result.current.resolveInterrupts(false)
+      await flushPromises()
+      expect(result.current.interruptErrors[0]?.code).toBe(
+        'unsupported-bulk-operation',
+      )
+      expect(onInterruptStateChange).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          interrupts: result.current.interrupts,
+          interruptErrors: result.current.interruptErrors,
+        }),
+      )
+    })
+
+    it('delegates every root interrupt control to ChatClient', async () => {
+      const resolve = vi
+        .spyOn(ChatClient.prototype, 'resolveInterrupts')
+        .mockImplementation(() => {})
+      const cancel = vi
+        .spyOn(ChatClient.prototype, 'cancelInterrupts')
+        .mockImplementation(() => {})
+      const retry = vi
+        .spyOn(ChatClient.prototype, 'retryInterrupts')
+        .mockImplementation(() => {})
+      const unsafe = vi
+        .spyOn(ChatClient.prototype, 'resumeInterruptsUnsafe')
+        .mockResolvedValue(true)
+      const { result } = renderUseChat({
+        connection: createMockConnectionAdapter(),
+      })
+      const resolver = () => undefined
+      const resume = [{ interruptId: 'one', status: 'cancelled' as const }]
+
+      result.current.resolveInterrupts(resolver)
+      result.current.cancelInterrupts()
+      result.current.retryInterrupts()
+      await expect(result.current.resumeInterruptsUnsafe(resume)).resolves.toBe(
+        true,
+      )
+
+      expect(resolve).toHaveBeenCalledWith(resolver)
+      expect(cancel).toHaveBeenCalledOnce()
+      expect(retry).toHaveBeenCalledOnce()
+      expect(unsafe).toHaveBeenCalledWith(resume, undefined)
+    })
+  })
+
   describe('initialization', () => {
     it('should initialize with default state', () => {
       const adapter = createMockConnectionAdapter()
diff --git a/packages/ai/package.json b/packages/ai/package.json
index f88be6ae6..bc8c79a1e 100644
--- a/packages/ai/package.json
+++ b/packages/ai/package.json
@@ -86,9 +86,12 @@
   ],
   "dependencies": {
     "@ag-ui/core": "^0.0.57",
+    "@noble/hashes": "^2.0.1",
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/ai-event-client": "workspace:*",
     "@tanstack/ai-utils": "workspace:*",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "partial-json": "^0.1.7"
   },
   "peerDependencies": {
diff --git a/packages/ai/skills/ai-core/persistence/SKILL.md b/packages/ai/skills/ai-core/persistence/SKILL.md
index 1b57055ca..94674846b 100644
--- a/packages/ai/skills/ai-core/persistence/SKILL.md
+++ b/packages/ai/skills/ai-core/persistence/SKILL.md
@@ -155,8 +155,9 @@ and `blobs`.
 Projects that run their own drizzle-kit journal can own the schema instead of
 applying the bundled SQL: emit it with the `tanstack-ai-drizzle-schema` CLI
 (`--out <dir>` / `--stdout`), add the emitted file to the drizzle-kit `schema`
-paths, and pass it back via `drizzlePersistence(db, { schema })`. The runtime
-reads and writes through the injected table objects, so renamed tables/columns
+paths, and pass it back via
+`drizzlePersistence(db, { schema, interrupts: transactionExecutor })`. The
+runtime reads and writes through the injected table objects, so renamed tables/columns
 (including drizzle `casing` conventions) and extra app-owned columns (for
 example a nullable `userId` on `messages` for thread ownership) are supported;
 the `TanstackAiSchema` type pins the required column data shapes and
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index b8d9341ef..cc35a4fd6 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -11,6 +11,16 @@ import { stripToSpecMiddleware } from '../../strip-to-spec-middleware'
 import { streamToText } from '../../stream-to-response.js'
 import { resolveDebugOption } from '../../logger/resolve'
 import { EventType } from '../../types'
+import { getInterruptPersistence } from '../../interrupts'
+import {
+  InterruptResumeValidationError,
+  readUnopenedInterruptBinding,
+  validateInterruptResumeBatch,
+} from '../../interrupt-resume'
+import {
+  canonicalInterruptJson,
+  digestInterruptJson,
+} from '../../interrupt-serialization'
 import { normalizeToolResult } from '../../utilities/tool-result'
 import { isProviderExecutedToolCall } from '../../utilities/provider-executed'
 import { LazyToolManager } from './tools/lazy-tool-manager'
@@ -25,6 +35,10 @@ import {
   isStandardSchema,
   parseWithStandardSchema,
 } from './tools/schema-converter'
+import {
+  hashSchemaInput,
+  normalizeApprovalSchema,
+} from './tools/approval-schema'
 import { maxIterations as maxIterationsStrategy } from './agent-loop-strategies'
 import { convertMessagesToModelMessages, generateMessageId } from './messages'
 import { MiddlewareRunner } from './middleware/compose'
@@ -32,11 +46,18 @@ import { provideSandboxRuntime } from './middleware/sandbox-runtime'
 import { CapabilityRegistry } from './middleware/capabilities'
 import { validateCapabilities } from './middleware/validate'
 import { MCPManager } from './mcp/manager'
+import type {
+  InterruptBinding,
+  InterruptRecoveryStateV1,
+  InterruptSubmissionError,
+  ToolApprovalResolution,
+} from '../../interrupts'
 import type {
   ApprovalRequest,
   ClientToolRequest,
   ToolResult,
 } from './tools/tool-calls'
+import type { ApprovalSchemaConfig } from './tools/tool-definition'
 import type {
   AnyTextAdapter,
   StructuredOutputOptions,
@@ -52,6 +73,7 @@ import type {
   Interrupt,
   JSONSchema,
   LazyToolsConfig,
+  MessagesSnapshotEvent,
   ModelMessage,
   RunFinishedEvent,
   SchemaInput,
@@ -71,6 +93,7 @@ import type {
   ChatMiddleware,
   ChatMiddlewareConfig,
   ChatMiddlewareContext,
+  ChatResumeToolState,
   SandboxFileHookEvent,
   StructuredOutputMiddlewareConfig,
 } from './middleware/types'
@@ -96,6 +119,174 @@ import type { ChatMCPOptions } from './mcp/types'
 export const kind = 'text' as const
 
 type AnyRuntimeTool = AnyTool
+type RuntimeToolWithApproval = AnyRuntimeTool & {
+  approvalSchema?: ApprovalSchemaConfig
+}
+const interruptBindingMetadataKey = 'tanstack:interruptBinding'
+
+interface StructuralInterruptFailure {
+  error: Error
+  errors: ReadonlyArray<InterruptSubmissionError>
+  recovery?: InterruptRecoveryStateV1
+}
+
+function isInterruptSubmissionError(
+  value: unknown,
+): value is InterruptSubmissionError {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false
+  }
+  if (
+    !('scope' in value) ||
+    !('code' in value) ||
+    !('message' in value) ||
+    !('source' in value) ||
+    !('retryable' in value) ||
+    !('threadId' in value) ||
+    !('interruptedRunId' in value) ||
+    !('generation' in value) ||
+    typeof value.code !== 'string' ||
+    typeof value.message !== 'string' ||
+    typeof value.retryable !== 'boolean' ||
+    typeof value.threadId !== 'string' ||
+    typeof value.interruptedRunId !== 'string' ||
+    typeof value.generation !== 'number'
+  ) {
+    return false
+  }
+  if (value.scope === 'item') {
+    return (
+      'interruptId' in value &&
+      typeof value.interruptId === 'string' &&
+      (value.source === 'client' || value.source === 'server')
+    )
+  }
+  return (
+    value.scope === 'batch' &&
+    'interruptIds' in value &&
+    Array.isArray(value.interruptIds) &&
+    value.interruptIds.every((id) => typeof id === 'string') &&
+    (value.source === 'client' ||
+      value.source === 'server' ||
+      value.source === 'transport')
+  )
+}
+
+function isInterruptRecoveryState(
+  value: unknown,
+): value is InterruptRecoveryStateV1 {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    'schemaVersion' in value &&
+    value.schemaVersion === 1 &&
+    'state' in value &&
+    typeof value.state === 'string' &&
+    'threadId' in value &&
+    typeof value.threadId === 'string' &&
+    'interruptedRunId' in value &&
+    typeof value.interruptedRunId === 'string' &&
+    'generation' in value &&
+    typeof value.generation === 'number' &&
+    'pendingInterrupts' in value &&
+    Array.isArray(value.pendingInterrupts)
+  )
+}
+
+function structuralInterruptFailure(
+  error: unknown,
+): StructuralInterruptFailure | undefined {
+  if (
+    !(error instanceof Error) ||
+    error.name !== 'InterruptResumeValidationError' ||
+    !('errors' in error) ||
+    !Array.isArray(error.errors) ||
+    error.errors.length === 0 ||
+    !error.errors.every(isInterruptSubmissionError)
+  ) {
+    return undefined
+  }
+  const recovery =
+    'recovery' in error && isInterruptRecoveryState(error.recovery)
+      ? error.recovery
+      : undefined
+  return {
+    error,
+    errors: error.errors,
+    ...(recovery !== undefined ? { recovery } : {}),
+  }
+}
+
+function normalizePublicInterruptBinding(
+  value: unknown,
+  expectedInterruptId: string,
+): InterruptBinding | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined
+  }
+  const binding: Record<string, unknown> = Object.fromEntries(
+    Object.entries(value),
+  )
+  if (
+    binding.interruptId !== expectedInterruptId ||
+    typeof binding.interruptedRunId !== 'string' ||
+    typeof binding.generation !== 'number' ||
+    !Number.isInteger(binding.generation) ||
+    binding.generation < 0 ||
+    typeof binding.responseSchemaHash !== 'string' ||
+    (binding.expiresAt !== undefined && typeof binding.expiresAt !== 'string')
+  ) {
+    return undefined
+  }
+  const base = {
+    interruptId: binding.interruptId,
+    interruptedRunId: binding.interruptedRunId,
+    generation: binding.generation,
+    responseSchemaHash: binding.responseSchemaHash,
+    ...(typeof binding.expiresAt === 'string'
+      ? { expiresAt: binding.expiresAt }
+      : {}),
+  }
+  if (binding.kind === 'generic') {
+    return { kind: binding.kind, ...base }
+  }
+  if (
+    typeof binding.toolName !== 'string' ||
+    typeof binding.toolCallId !== 'string'
+  ) {
+    return undefined
+  }
+  if (
+    binding.kind === 'client-tool-execution' &&
+    typeof binding.outputSchemaHash === 'string'
+  ) {
+    return {
+      kind: binding.kind,
+      ...base,
+      toolName: binding.toolName,
+      toolCallId: binding.toolCallId,
+      outputSchemaHash: binding.outputSchemaHash,
+    }
+  }
+  if (
+    binding.kind === 'tool-approval' &&
+    Object.prototype.hasOwnProperty.call(binding, 'originalArgs') &&
+    typeof binding.inputSchemaHash === 'string' &&
+    typeof binding.approvalSchemaHash === 'string'
+  ) {
+    return {
+      kind: binding.kind,
+      ...base,
+      toolName: binding.toolName,
+      toolCallId: binding.toolCallId,
+      originalArgs: binding.originalArgs,
+      inputSchemaHash: binding.inputSchemaHash,
+      approvalSchemaHash: binding.approvalSchemaHash,
+    }
+  }
+  return undefined
+}
 
 // The leaf context-inference primitives (KnownContext, MergeContext,
 // UnionToIntersection, DefinedContext, ContextFromTool, ContextFromMiddleware)
@@ -255,6 +446,8 @@ export interface TextActivityOptions<
   runId?: TextOptions['runId']
   /** Parent run ID for AG-UI protocol nested run correlation. */
   parentRunId?: TextOptions['parentRunId']
+  /** Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. */
+  state?: TextOptions['state']
   /**
    * AG-UI interrupt resume responses. Persistence middleware validates these
    * before accepting new input on a thread with pending interrupts.
@@ -542,10 +735,12 @@ class TextEngine<
   private toolPhase: ToolPhaseResult = 'continue'
   private cyclePhase: CyclePhase = 'processText'
   // Client state extracted from initial messages (before conversion to ModelMessage)
-  private readonly initialApprovals: Map<string, boolean>
+  private readonly initialApprovals: Map<string, ToolApprovalResolution>
   private readonly initialClientToolResults: Map<string, any>
-  private readonly resumeApprovals = new Map<string, boolean>()
+  private readonly resumeApprovals = new Map<string, ToolApprovalResolution>()
   private readonly resumeClientToolResults = new Map<string, any>()
+  private readonly resumeDeniedToolResults = new Map<string, unknown>()
+  private readonly resumeCancelledToolCallIds = new Set<string>()
 
   // AG-UI protocol IDs
   private readonly threadId: string
@@ -669,6 +864,7 @@ class TextEngine<
       requestId: this.requestId,
       streamId: this.streamId,
       runId: this.runIdOverride ?? this.requestId,
+      parentRunId: this.parentRunIdOverride,
       threadId: this.threadId,
       // Legacy alias kept on the ctx so middleware that reads
       // `ctx.conversationId` keeps working. Always equals `threadId`.
@@ -806,6 +1002,7 @@ class TextEngine<
         initialConfig,
       )
       this.applyMiddlewareConfig(transformedConfig)
+      await this.applyEphemeralInterruptResume(transformedConfig)
 
       // Run onStart (devtools middleware emits text:request:started and initial messages here)
       await this.middlewareRunner.runOnStart(this.middlewareCtx)
@@ -926,6 +1123,41 @@ class TextEngine<
         }
       }
     } catch (error: unknown) {
+      if (
+        error instanceof Error &&
+        error.name === 'InterruptReplaySignal' &&
+        'continuationRunId' in error &&
+        typeof error.continuationRunId === 'string'
+      ) {
+        this.terminalHookCalled = true
+        yield {
+          type: EventType.RUN_FINISHED,
+          timestamp: Date.now(),
+          threadId: this.threadId,
+          runId: this.runIdOverride ?? this.requestId,
+          finishReason: 'stop',
+          outcome: { type: 'success' },
+          result: {
+            replayed: true,
+            continuationRunId: error.continuationRunId,
+          },
+        }
+        return
+      }
+      const interruptFailure = structuralInterruptFailure(error)
+      if (interruptFailure) {
+        this.terminalHookCalled = true
+        this.logger.errors('chat interrupt resume failed', {
+          error,
+          threadId: this.middlewareCtx.threadId,
+        })
+        await this.middlewareRunner.runOnError(this.middlewareCtx, {
+          error: interruptFailure.error,
+          duration: Date.now() - this.streamStartTime,
+        })
+        yield this.buildInterruptRunErrorChunk(error)
+        return
+      }
       if (!this.terminalHookCalled) {
         this.terminalHookCalled = true
         if (error instanceof MiddlewareAbortError) {
@@ -1061,6 +1293,13 @@ class TextEngine<
         : undefined
 
     const { approvals } = this.collectClientState()
+    const adapterApprovals = new Map<string, boolean>()
+    for (const [approvalId, resolution] of approvals) {
+      adapterApprovals.set(
+        approvalId,
+        typeof resolution === 'boolean' ? resolution : resolution.approved,
+      )
+    }
 
     for await (const chunk of this.adapter.chatStream({
       model: this.params.model,
@@ -1077,7 +1316,7 @@ class TextEngine<
       // Expose provided capabilities (e.g. sandbox) to harness adapters.
       capabilities: this.middlewareCtx,
       // Client approval decisions, for harness interactive-approval resolution.
-      approvals,
+      approvals: adapterApprovals,
       ...(combinedSchema ? { outputSchema: combinedSchema } : {}),
     })) {
       if (this.isCancelled()) {
@@ -1391,6 +1630,10 @@ class TextEngine<
       },
       this.middlewareCtx.context,
       this.toolAbortSignal,
+      {
+        deniedToolResults: this.resumeDeniedToolResults,
+        cancelledToolCallIds: this.resumeCancelledToolCallIds,
+      },
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -1410,13 +1653,6 @@ class TextEngine<
       needsClientExecution: executionResult.needsClientExecution,
     })
 
-    // Build args lookup so buildToolResultChunks can emit TOOL_CALL_START +
-    // TOOL_CALL_ARGS before TOOL_CALL_END during continuation re-executions.
-    const argsMap = new Map<string, string>()
-    for (const tc of pendingToolCalls) {
-      argsMap.set(tc.id, tc.function.arguments)
-    }
-
     if (
       executionResult.needsApproval.length > 0 ||
       executionResult.needsClientExecution.length > 0
@@ -1427,28 +1663,23 @@ class TextEngine<
         for (const chunk of this.buildToolResultChunks(
           executionResult.results,
           finishEvent,
-          argsMap,
         )) {
           yield* this.pipeThroughMiddleware(chunk)
         }
       }
 
-      yield* this.pipeThroughMiddleware(
-        this.buildInterruptFinishedChunk(
-          finishEvent,
-          executionResult.needsApproval,
-          executionResult.needsClientExecution,
-        ),
+      const emitted = yield* this.emitActionableInterruptBoundary(
+        finishEvent,
+        executionResult.needsApproval,
+        executionResult.needsClientExecution,
       )
-
-      this.setToolPhase('wait')
-      return 'wait'
+      this.setToolPhase(emitted ? 'wait' : 'stop')
+      return emitted ? 'wait' : 'stop'
     }
 
     const toolResultChunks = this.buildToolResultChunks(
       executionResult.results,
       finishEvent,
-      argsMap,
     )
 
     for (const chunk of toolResultChunks) {
@@ -1550,6 +1781,10 @@ class TextEngine<
       },
       this.middlewareCtx.context,
       this.toolAbortSignal,
+      {
+        deniedToolResults: this.resumeDeniedToolResults,
+        cancelledToolCallIds: this.resumeCancelledToolCallIds,
+      },
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -1584,15 +1819,12 @@ class TextEngine<
         }
       }
 
-      yield* this.pipeThroughMiddleware(
-        this.buildInterruptFinishedChunk(
-          finishEvent,
-          executionResult.needsApproval,
-          executionResult.needsClientExecution,
-        ),
+      const emitted = yield* this.emitActionableInterruptBoundary(
+        finishEvent,
+        executionResult.needsApproval,
+        executionResult.needsClientExecution,
       )
-
-      this.setToolPhase('wait')
+      this.setToolPhase(emitted ? 'wait' : 'stop')
       return
     }
 
@@ -1667,6 +1899,7 @@ class TextEngine<
         }),
       },
     ]
+    this.middlewareCtx.messages = this.messages
   }
 
   /**
@@ -1677,10 +1910,10 @@ class TextEngine<
   private extractClientStateFromOriginalMessages(
     originalMessages: Array<any>,
   ): {
-    approvals: Map<string, boolean>
+    approvals: Map<string, ToolApprovalResolution>
     clientToolResults: Map<string, any>
   } {
-    const approvals = new Map<string, boolean>()
+    const approvals = new Map<string, ToolApprovalResolution>()
     const clientToolResults = new Map<string, any>()
 
     for (const message of originalMessages) {
@@ -1709,7 +1942,7 @@ class TextEngine<
   }
 
   private collectClientState(): {
-    approvals: Map<string, boolean>
+    approvals: Map<string, ToolApprovalResolution>
     clientToolResults: Map<string, any>
   } {
     // Start with the initial client state extracted from original messages
@@ -1766,34 +1999,62 @@ class TextEngine<
     const interrupts: Array<Interrupt> = []
 
     for (const approval of approvals) {
+      const tool = this.tools.find(
+        (candidate) => candidate.name === approval.toolName,
+      ) as RuntimeToolWithApproval | undefined
+      const normalized = normalizeApprovalSchema(
+        tool?.approvalSchema,
+        tool?.inputSchema,
+      )
       interrupts.push({
         id: approval.approvalId,
-        reason: 'approval_required',
+        reason: 'tool_call',
         message: `Approval required to run ${approval.toolName}`,
         toolCallId: approval.toolCallId,
-        responseSchema: {
-          type: 'object',
-          properties: { approved: { type: 'boolean' } },
-          required: ['approved'],
-        },
+        responseSchema: normalized.responseSchema,
         metadata: {
           kind: 'approval',
           toolName: approval.toolName,
           input: approval.input,
+          [interruptBindingMetadataKey]: {
+            kind: 'tool-approval',
+            interruptId: approval.approvalId,
+            toolName: approval.toolName,
+            toolCallId: approval.toolCallId,
+            originalArgs: approval.input,
+            inputSchemaHash: hashSchemaInput(tool?.inputSchema),
+            approvalSchemaHash: normalized.approvalSchemaHash,
+            responseSchemaHash: normalized.responseSchemaHash,
+          },
         },
       })
     }
 
     for (const clientTool of clientRequests) {
+      const tool = this.tools.find(
+        (candidate) => candidate.name === clientTool.toolName,
+      )
+      const responseSchema = convertSchemaToJsonSchema(tool?.outputSchema) ?? {}
       interrupts.push({
         id: `client_tool_${clientTool.toolCallId}`,
-        reason: 'client_tool_input',
+        reason: 'tanstack:client_tool_execution',
         message: `Client tool ${clientTool.toolName} is ready to run`,
         toolCallId: clientTool.toolCallId,
+        responseSchema,
         metadata: {
           kind: 'client_tool',
           toolName: clientTool.toolName,
           input: clientTool.input,
+          [interruptBindingMetadataKey]: {
+            kind: 'client-tool-execution',
+            interruptId: `client_tool_${clientTool.toolCallId}`,
+            toolName: clientTool.toolName,
+            toolCallId: clientTool.toolCallId,
+            outputSchemaHash: hashSchemaInput(tool?.outputSchema),
+            responseSchemaHash: digestInterruptJson(
+              canonicalInterruptJson(responseSchema),
+            ),
+          },
         },
       })
     }
@@ -1816,10 +2077,228 @@ class TextEngine<
     }
   }
 
+  private buildMessagesSnapshotChunk(): StreamChunk {
+    const messages: MessagesSnapshotEvent['messages'] = this.messages.map(
+      (message, index) => {
+        const content =
+          typeof message.content === 'string'
+            ? message.content
+            : message.content === null
+              ? undefined
+              : JSON.stringify(message.content)
+        return {
+          id: `snapshot_${this.runIdOverride ?? this.requestId}_${index}`,
+          role: message.role,
+          ...(content !== undefined ? { content } : {}),
+          ...('toolCalls' in message && message.toolCalls
+            ? { toolCalls: message.toolCalls }
+            : {}),
+          ...('toolCallId' in message && message.toolCallId
+            ? { toolCallId: message.toolCallId }
+            : {}),
+        } as MessagesSnapshotEvent['messages'][number]
+      },
+    )
+    return {
+      type: EventType.MESSAGES_SNAPSHOT,
+      timestamp: Date.now(),
+      model: this.params.model,
+      messages,
+    }
+  }
+
+  private publicInterruptTerminal(chunk: StreamChunk): StreamChunk {
+    if (
+      chunk.type !== EventType.RUN_FINISHED ||
+      chunk.outcome?.type !== 'interrupt'
+    ) {
+      return chunk
+    }
+    return {
+      ...chunk,
+      outcome: {
+        ...chunk.outcome,
+        interrupts: chunk.outcome.interrupts.map((interrupt) => {
+          if (
+            !interrupt.metadata ||
+            typeof interrupt.metadata !== 'object' ||
+            Array.isArray(interrupt.metadata)
+          ) {
+            return interrupt
+          }
+          const metadata = { ...interrupt.metadata }
+          const binding = normalizePublicInterruptBinding(
+            metadata[interruptBindingMetadataKey],
+            interrupt.id,
+          )
+          if (binding) {
+            metadata[interruptBindingMetadataKey] = binding
+          } else {
+            delete metadata[interruptBindingMetadataKey]
+          }
+          return { ...interrupt, metadata }
+        }),
+      },
+    }
+  }
+
+  private interruptFailure(error: unknown): {
+    message: string
+    code: string
+    errors?: ReadonlyArray<InterruptSubmissionError>
+    recovery?: InterruptRecoveryStateV1
+  } {
+    const structured = structuralInterruptFailure(error)
+    if (structured) {
+      return {
+        message: structured.error.message,
+        code: structured.errors[0]?.code ?? 'server',
+        errors: structured.errors,
+        ...(structured.recovery !== undefined
+          ? { recovery: structured.recovery }
+          : {}),
+      }
+    }
+    if (error && typeof error === 'object' && 'errors' in error) {
+      const errors = error.errors
+      if (Array.isArray(errors)) {
+        const first = errors[0]
+        if (first && typeof first === 'object') {
+          const message =
+            'message' in first && typeof first.message === 'string'
+              ? first.message
+              : 'Interrupt persistence failed.'
+          const code =
+            'code' in first && typeof first.code === 'string'
+              ? first.code
+              : 'server'
+          return { message, code }
+        }
+      }
+    }
+    return {
+      message:
+        error instanceof Error
+          ? error.message
+          : 'Interrupt persistence failed.',
+      code: 'server',
+    }
+  }
+
+  private buildInterruptRunErrorChunk(error: unknown): StreamChunk {
+    const failure = this.interruptFailure(error)
+    return {
+      type: EventType.RUN_ERROR,
+      timestamp: Date.now(),
+      runId: this.runIdOverride ?? this.requestId,
+      threadId: this.threadId,
+      message: failure.message,
+      code: failure.code,
+      error: { message: failure.message, code: failure.code },
+      ...(failure.errors !== undefined
+        ? { 'tanstack:interruptErrors': failure.errors }
+        : {}),
+      ...(failure.recovery !== undefined
+        ? { 'tanstack:interruptRecovery': failure.recovery }
+        : {}),
+    }
+  }
+
+  private async *emitInterruptRunError(
+    error: unknown,
+  ): AsyncGenerator<StreamChunk, void, void> {
+    const failure = this.interruptFailure(error)
+    this.finalizationError = {
+      message: failure.message,
+      code: failure.code,
+      cause: error,
+    }
+    yield* this.pipeThroughMiddleware(this.buildInterruptRunErrorChunk(error))
+  }
+
+  private async *emitActionableInterruptBoundary(
+    finishEvent: RunFinishedEvent,
+    approvals: Array<ApprovalRequest>,
+    clientRequests: Array<ClientToolRequest>,
+  ): AsyncGenerator<StreamChunk, boolean, void> {
+    let terminal = this.buildInterruptFinishedChunk(
+      finishEvent,
+      approvals,
+      clientRequests,
+    )
+    if (!getInterruptPersistence(this.middlewareCtx, { optional: true })) {
+      terminal = this.completeEphemeralInterruptBindings(terminal)
+    }
+    let terminalOutputs: Array<StreamChunk>
+    try {
+      terminalOutputs = await this.middlewareRunner.runOnChunk(
+        this.middlewareCtx,
+        terminal,
+      )
+    } catch (error) {
+      yield* this.emitInterruptRunError(error)
+      return false
+    }
+
+    yield* this.pipeThroughMiddleware(this.buildMessagesSnapshotChunk())
+    if (this.params.state !== undefined) {
+      yield* this.pipeThroughMiddleware({
+        type: EventType.STATE_SNAPSHOT,
+        timestamp: Date.now(),
+        model: this.params.model,
+        snapshot: this.params.state,
+      })
+    }
+    for (const output of terminalOutputs) {
+      yield this.publicInterruptTerminal(output)
+      this.middlewareCtx.chunkIndex++
+    }
+    return true
+  }
+
+  private completeEphemeralInterruptBindings(chunk: StreamChunk): StreamChunk {
+    if (
+      chunk.type !== EventType.RUN_FINISHED ||
+      chunk.outcome?.type !== 'interrupt'
+    ) {
+      return chunk
+    }
+    const interruptedRunId = this.runIdOverride ?? this.requestId
+    return {
+      ...chunk,
+      outcome: {
+        ...chunk.outcome,
+        interrupts: chunk.outcome.interrupts.map((interrupt) => {
+          if (
+            !interrupt.metadata ||
+            typeof interrupt.metadata !== 'object' ||
+            Array.isArray(interrupt.metadata)
+          ) {
+            return interrupt
+          }
+          const metadata = { ...interrupt.metadata }
+          const unopened = metadata[interruptBindingMetadataKey]
+          if (
+            unopened === null ||
+            typeof unopened !== 'object' ||
+            Array.isArray(unopened)
+          ) {
+            return interrupt
+          }
+          metadata[interruptBindingMetadataKey] = {
+            ...unopened,
+            interruptedRunId,
+            generation: 0,
+          }
+          return { ...interrupt, metadata }
+        }),
+      },
+    }
+  }
+
   private buildToolResultChunks(
     results: Array<ToolResult>,
     finishEvent: RunFinishedEvent,
-    argsMap?: Map<string, string>,
   ): Array<StreamChunk> {
     const chunks: Array<StreamChunk> = []
 
@@ -1834,41 +2313,6 @@ class TextEngine<
       const wireContent =
         typeof content === 'string' ? content : JSON.stringify(content)
 
-      // argsMap is set only on continuation re-executions, where the adapter
-      // never streamed these calls. Otherwise it already emitted END, so a
-      // second one here would be an orphan that fails verifyEvents (#519).
-      if (argsMap) {
-        chunks.push({
-          type: 'TOOL_CALL_START',
-          timestamp: Date.now(),
-          model: finishEvent.model,
-          toolCallId: result.toolCallId,
-          toolCallName: result.toolName,
-          toolName: result.toolName,
-        } as StreamChunk)
-
-        const args = argsMap.get(result.toolCallId) ?? '{}'
-        chunks.push({
-          type: 'TOOL_CALL_ARGS',
-          timestamp: Date.now(),
-          model: finishEvent.model,
-          toolCallId: result.toolCallId,
-          delta: args,
-          args,
-        } as StreamChunk)
-
-        chunks.push({
-          type: 'TOOL_CALL_END',
-          timestamp: Date.now(),
-          model: finishEvent.model,
-          toolCallId: result.toolCallId,
-          toolCallName: result.toolName,
-          toolName: result.toolName,
-          result: wireContent,
-          ...(result.state !== undefined && { state: result.state }),
-        } as StreamChunk)
-      }
-
       // AG-UI spec TOOL_CALL_RESULT event (content is string-only per spec)
       chunks.push({
         type: 'TOOL_CALL_RESULT',
@@ -1914,6 +2358,7 @@ class TextEngine<
       } else {
         this.messages = [...this.messages, newToolMessage]
       }
+      this.middlewareCtx.messages = this.messages
     }
 
     return chunks
@@ -2564,24 +3009,178 @@ class TextEngine<
       resumeToolState: {
         approvals: this.resumeApprovals,
         clientToolResults: this.resumeClientToolResults,
+        deniedToolResults: this.resumeDeniedToolResults,
+        cancelledToolCallIds: this.resumeCancelledToolCallIds,
       },
       metadata: this.params.metadata,
       modelOptions: this.params.modelOptions,
     }
   }
 
-  private applyMiddlewareConfig(config: ChatMiddlewareConfig): void {
-    if (config.resumeToolState?.approvals) {
-      for (const [approvalId, approved] of config.resumeToolState.approvals) {
-        this.resumeApprovals.set(approvalId, approved)
+  private async applyEphemeralInterruptResume(
+    config: ChatMiddlewareConfig,
+  ): Promise<void> {
+    if (
+      (config.resume?.length ?? 0) === 0 ||
+      getInterruptPersistence(this.middlewareCtx, { optional: true })
+    ) {
+      return
+    }
+
+    const interruptedRunId = this.parentRunIdOverride
+    if (!interruptedRunId) {
+      throw new InterruptResumeValidationError([
+        {
+          scope: 'batch',
+          threadId: this.threadId,
+          interruptedRunId: this.runIdOverride ?? this.requestId,
+          generation: 0,
+          interruptIds: config.resume?.map((entry) => entry.interruptId) ?? [],
+          code: 'stale',
+          message:
+            'Interrupt continuation requires parentRunId to identify the interrupted run.',
+          source: 'server',
+          retryable: false,
+        },
+      ])
+    }
+
+    const approvalRequests: Array<ApprovalRequest> = []
+    const clientRequests: Array<ClientToolRequest> = []
+    const pendingToolCalls = this.getPendingToolCallsFromMessages()
+    const resumeInterruptIds = new Set(
+      config.resume?.map((entry) => entry.interruptId),
+    )
+    const toolInputs = new Map<string, unknown>()
+    const toolsByCallId = new Map<string, AnyRuntimeTool>()
+    const clientExecutionCallIds = new Set<string>()
+
+    for (const toolCall of pendingToolCalls) {
+      const tool = this.tools.find(
+        (candidate) => candidate.name === toolCall.function.name,
+      )
+      if (!tool) continue
+      toolsByCallId.set(toolCall.id, tool)
+      let input: unknown = {}
+      try {
+        const parsed = JSON.parse(toolCall.function.arguments.trim() || '{}')
+        input = parsed && typeof parsed === 'object' ? parsed : {}
+      } catch {
+        input = {}
+      }
+      toolInputs.set(toolCall.id, input)
+      if (
+        !tool.execute &&
+        resumeInterruptIds.has(`client_tool_${toolCall.id}`)
+      ) {
+        clientExecutionCallIds.add(toolCall.id)
       }
     }
-    if (config.resumeToolState?.clientToolResults) {
-      for (const [toolCallId, result] of config.resumeToolState
-        .clientToolResults) {
+
+    // Mirror executeToolCalls' scheduling boundary. Server execution remains
+    // gated while any approval is outstanding, but plain client tools are
+    // represented in the same interrupt batch because requesting their output
+    // does not execute a server-side effect.
+    for (const toolCall of pendingToolCalls) {
+      const tool = toolsByCallId.get(toolCall.id)
+      if (tool?.needsApproval && !clientExecutionCallIds.has(toolCall.id)) {
+        approvalRequests.push({
+          toolCallId: toolCall.id,
+          toolName: toolCall.function.name,
+          input: toolInputs.get(toolCall.id) ?? {},
+          approvalId: `approval_${toolCall.id}`,
+        })
+      }
+    }
+
+    for (const toolCall of pendingToolCalls) {
+      const tool = toolsByCallId.get(toolCall.id)
+      if (
+        tool !== undefined &&
+        !tool.execute &&
+        (!tool.needsApproval || clientExecutionCallIds.has(toolCall.id))
+      ) {
+        clientRequests.push({
+          toolCallId: toolCall.id,
+          toolName: toolCall.function.name,
+          input: toolInputs.get(toolCall.id) ?? {},
+        })
+      }
+    }
+
+    const pending = this.buildActionableInterrupts(
+      approvalRequests,
+      clientRequests,
+    ).flatMap((descriptor) => {
+      const unopened = readUnopenedInterruptBinding(descriptor)
+      return unopened
+        ? [
+            {
+              interruptId: descriptor.id,
+              payload: descriptor,
+              binding: {
+                ...unopened,
+                interruptedRunId,
+                generation: 0,
+              } satisfies InterruptBinding,
+            },
+          ]
+        : []
+    })
+    const validated = await validateInterruptResumeBatch({
+      threadId: this.threadId,
+      interruptedRunId,
+      generation: 0,
+      pending,
+      resume: config.resume,
+      tools: this.tools,
+    })
+    if (validated.errors.length > 0 || !validated.resumeToolState) {
+      throw new InterruptResumeValidationError(validated.errors)
+    }
+
+    // A client-tool execution interrupt can only be emitted after an
+    // approval-required client tool was approved in the preceding ephemeral
+    // run. Reconstruct that phase marker from the trusted `client_tool_*`
+    // continuation so executeToolCalls consumes the validated client output
+    // instead of asking for approval again.
+    const approvals = new Map(validated.resumeToolState.approvals)
+    for (const request of clientRequests) {
+      if (toolsByCallId.get(request.toolCallId)?.needsApproval) {
+        approvals.set(request.toolCallId, true)
+      }
+    }
+    this.applyResumeToolState({
+      ...validated.resumeToolState,
+      approvals,
+    })
+  }
+
+  private applyResumeToolState(state: ChatResumeToolState | undefined): void {
+    if (state?.approvals) {
+      for (const [approvalId, resolution] of state.approvals) {
+        this.resumeApprovals.set(approvalId, resolution)
+      }
+    }
+    if (state?.clientToolResults) {
+      for (const [toolCallId, result] of state.clientToolResults) {
         this.resumeClientToolResults.set(toolCallId, result)
       }
     }
+    if (state?.deniedToolResults) {
+      for (const [toolCallId, result] of state.deniedToolResults) {
+        this.resumeDeniedToolResults.set(toolCallId, result)
+      }
+    }
+    if (state?.cancelledToolCallIds) {
+      for (const toolCallId of state.cancelledToolCallIds) {
+        this.resumeCancelledToolCallIds.add(toolCallId)
+      }
+    }
+  }
+
+  private applyMiddlewareConfig(config: ChatMiddlewareConfig): void {
+    this.applyResumeToolState(config.resumeToolState)
     this.messages = config.messages
     this.systemPrompts = config.systemPrompts
     this.tools = config.tools
diff --git a/packages/ai/src/activities/chat/mcp/manager.ts b/packages/ai/src/activities/chat/mcp/manager.ts
index c52bff037..bac5e22ec 100644
--- a/packages/ai/src/activities/chat/mcp/manager.ts
+++ b/packages/ai/src/activities/chat/mcp/manager.ts
@@ -1,4 +1,4 @@
-import type { ServerTool } from '../tools/tool-definition'
+import type { AnyServerTool } from '../tools/tool-definition'
 import type { ChatMCPOptions, MCPToolSource } from './types'
 
 /**
@@ -18,7 +18,7 @@ import type { ChatMCPOptions, MCPToolSource } from './types'
  * drains. If discovery results were ever cached and reused across runs, this
  * would bind a closure over an already-closed source — bind onto a copy then.
  */
-function bindReadResource(tool: ServerTool, source: MCPToolSource): void {
+function bindReadResource(tool: AnyServerTool, source: MCPToolSource): void {
   if (!source.readResource) return
   const meta = (
     tool.metadata as { mcp?: { uiResourceUri?: string } } | undefined
@@ -71,13 +71,13 @@ export class MCPManager {
    * (no `onDiscoveryError`, or it re-threw) or a duplicate tool name; in that
    * case it first closes any connected sources when the policy is 'close'.
    */
-  async discover(): Promise<Array<ServerTool>> {
+  async discover(): Promise<Array<AnyServerTool>> {
     if (this.#sources.length === 0) return []
     try {
       const settled = await Promise.allSettled(
         this.#sources.map((s) => s.tools({ lazy: this.#lazyTools })),
       )
-      const tools: Array<ServerTool> = []
+      const tools: Array<AnyServerTool> = []
       const zipped = this.#sources.map(
         (source, i) => [source, settled[i]] as const,
       )
diff --git a/packages/ai/src/activities/chat/mcp/types.ts b/packages/ai/src/activities/chat/mcp/types.ts
index 6fe73d5ef..96c7911ca 100644
--- a/packages/ai/src/activities/chat/mcp/types.ts
+++ b/packages/ai/src/activities/chat/mcp/types.ts
@@ -1,4 +1,4 @@
-import type { ServerTool } from '../tools/tool-definition'
+import type { AnyServerTool } from '../tools/tool-definition'
 
 /**
  * The shape `readResource` resolves to — a structural subset of MCP's
@@ -26,7 +26,7 @@ export interface MCPToolSource {
   // Keep the options shape in sync with ai-mcp's `ToolsOptions` — extra
   // optional fields added there still match structurally, but chat() only
   // forwards what is declared here.
-  tools: (options?: { lazy?: boolean }) => Promise<Array<ServerTool>>
+  tools: (options?: { lazy?: boolean }) => Promise<Array<AnyServerTool>>
   close: () => Promise<void>
   /**
    * Reads an MCP resource by URI. Used by the chat manager to eagerly fetch
diff --git a/packages/ai/src/activities/chat/messages.ts b/packages/ai/src/activities/chat/messages.ts
index 8d47ba320..e83078842 100644
--- a/packages/ai/src/activities/chat/messages.ts
+++ b/packages/ai/src/activities/chat/messages.ts
@@ -211,6 +211,7 @@ function isToolCallIncluded(part: ToolCallPart): boolean {
   return (
     part.state === 'input-complete' ||
     part.state === 'complete' ||
+    part.state === 'approval-requested' ||
     part.state === 'approval-responded' ||
     part.state === 'error' ||
     part.output !== undefined
diff --git a/packages/ai/src/activities/chat/middleware/index.ts b/packages/ai/src/activities/chat/middleware/index.ts
index 6d231eedd..ad4fa9dad 100644
--- a/packages/ai/src/activities/chat/middleware/index.ts
+++ b/packages/ai/src/activities/chat/middleware/index.ts
@@ -4,6 +4,7 @@ export type {
   ChatMiddlewarePhase,
   ChatMiddlewareConfig,
   ChatResumeToolState,
+  ChatResumeGenericResolution,
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   BeforeToolCallDecision,
diff --git a/packages/ai/src/activities/chat/middleware/types.ts b/packages/ai/src/activities/chat/middleware/types.ts
index 741d2df45..06798374f 100644
--- a/packages/ai/src/activities/chat/middleware/types.ts
+++ b/packages/ai/src/activities/chat/middleware/types.ts
@@ -8,6 +8,7 @@ import type {
   ToolCall,
 } from '../../../types'
 import type { SystemPrompt } from '../../../system-prompts'
+import type { ToolApprovalResolution } from '../../../interrupts'
 import type {
   Capability,
   CapabilityHandle,
@@ -91,6 +92,8 @@ export interface ChatMiddlewareContext<TContext = unknown> {
   streamId: string
   /** AG-UI run identifier for correlating client and server events */
   runId: string
+  /** Interrupted or parent run correlated with this continuation. */
+  parentRunId?: string
   /**
    * AG-UI thread identifier — a stable per-conversation ID used to
    * correlate client and server devtools events. Resolves to the
@@ -221,10 +224,19 @@ export interface ChatMiddlewareConfig {
  * without relying on client message history.
  */
 export interface ChatResumeToolState {
-  approvals?: ReadonlyMap<string, boolean> | undefined
+  approvals?: ReadonlyMap<string, ToolApprovalResolution> | undefined
   clientToolResults?: ReadonlyMap<string, unknown> | undefined
+  genericInterrupts?:
+    | ReadonlyMap<string, ChatResumeGenericResolution>
+    | undefined
+  deniedToolResults?: ReadonlyMap<string, unknown> | undefined
+  cancelledToolCallIds?: ReadonlySet<string> | undefined
 }
 
+export type ChatResumeGenericResolution =
+  | { interruptId: string; status: 'resolved'; payload: unknown }
+  | { interruptId: string; status: 'cancelled'; payload?: never }
+
 /**
  * Config passed to onStructuredOutputConfig.
  *
diff --git a/packages/ai/src/activities/chat/tools/approval-schema.ts b/packages/ai/src/activities/chat/tools/approval-schema.ts
new file mode 100644
index 000000000..7cfb47103
--- /dev/null
+++ b/packages/ai/src/activities/chat/tools/approval-schema.ts
@@ -0,0 +1,205 @@
+import {
+  canonicalInterruptJson,
+  digestInterruptJson,
+} from '../../../interrupt-serialization'
+import { compileJsonSchema202012 } from './json-schema-validator'
+import { isStandardJSONSchema, isStandardSchema } from './schema-converter'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { JSONSchema, SchemaInput } from '../../../types'
+import type { ApprovalSchemaConfig } from './tool-definition'
+
+export interface NormalizedSchemaInput {
+  source: SchemaInput
+  validator?: StandardSchemaV1
+  jsonSchema?: JSONSchema
+}
+
+export interface NormalizedApprovalSchema {
+  branches: {
+    approve: NormalizedSchemaInput | null
+    reject: NormalizedSchemaInput | null
+  }
+  responseSchema: JSONSchema
+  responseSchemaHash: string
+  approvalSchemaHash: string
+}
+
+const jsonSchemaKeywords = new Set([
+  '$schema',
+  '$id',
+  '$ref',
+  '$defs',
+  'type',
+  'properties',
+  'required',
+  'additionalProperties',
+  'items',
+  'oneOf',
+  'anyOf',
+  'allOf',
+  'enum',
+  'const',
+  'format',
+  'minimum',
+  'maximum',
+  'minLength',
+  'maxLength',
+  'pattern',
+])
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    (Object.getPrototypeOf(value) === Object.prototype ||
+      Object.getPrototypeOf(value) === null)
+  )
+}
+
+function isRawJsonSchema(value: unknown): value is JSONSchema {
+  return (
+    isPlainRecord(value) &&
+    Object.keys(value).some((key) => jsonSchemaKeywords.has(key))
+  )
+}
+
+function isSchemaInput(value: unknown): value is SchemaInput {
+  return (
+    isStandardSchema(value) ||
+    isStandardJSONSchema(value) ||
+    isRawJsonSchema(value)
+  )
+}
+
+function isApprovalBranchMap(
+  value: unknown,
+): value is { approve?: SchemaInput; reject?: SchemaInput } {
+  if (!isPlainRecord(value)) return false
+  const keys = Object.keys(value)
+  return (
+    keys.length > 0 &&
+    keys.every((key) => key === 'approve' || key === 'reject') &&
+    keys.every((key) => isSchemaInput(value[key]))
+  )
+}
+
+function toJsonSchema(value: Record<string, unknown>): JSONSchema {
+  const result: JSONSchema = {}
+  for (const [key, item] of Object.entries(value)) {
+    result[key] = item
+  }
+  return result
+}
+
+function schemaToWire(schema: SchemaInput): NormalizedSchemaInput {
+  if (isStandardSchema(schema)) {
+    const jsonSchema = isStandardJSONSchema(schema)
+      ? toJsonSchema(
+          schema['~standard'].jsonSchema.input({
+            target: 'draft-2020-12',
+          }),
+        )
+      : undefined
+    return {
+      source: schema,
+      validator: schema,
+      ...(jsonSchema !== undefined && { jsonSchema }),
+    }
+  }
+  if (isRawJsonSchema(schema)) {
+    compileJsonSchema202012(schema)
+    return { source: schema, jsonSchema: schema }
+  }
+  throw new TypeError('Expected a supported SchemaInput.')
+}
+
+function decisionEnvelope(input: {
+  approved: boolean
+  payload: NormalizedSchemaInput | null
+  inputSchema: NormalizedSchemaInput | null
+}): JSONSchema {
+  const properties: Record<string, JSONSchema> = {
+    approved: { const: input.approved },
+  }
+  const required = ['approved']
+  if (input.approved && input.inputSchema) {
+    properties['editedArgs'] = input.inputSchema.jsonSchema ?? {}
+  }
+  if (input.payload) {
+    properties['payload'] = input.payload.jsonSchema ?? {}
+    required.push('payload')
+  }
+  return {
+    type: 'object',
+    properties,
+    required,
+    additionalProperties: false,
+  }
+}
+
+export function normalizeApprovalSchema(
+  approvalSchema: ApprovalSchemaConfig | undefined,
+  inputSchema?: SchemaInput,
+): NormalizedApprovalSchema {
+  const normalizedInput =
+    inputSchema === undefined ? null : schemaToWire(inputSchema)
+  let approve: NormalizedSchemaInput | null = null
+  let reject: NormalizedSchemaInput | null = null
+
+  if (approvalSchema !== undefined) {
+    if (isStandardSchema(approvalSchema) || isRawJsonSchema(approvalSchema)) {
+      approve = schemaToWire(approvalSchema)
+      reject = approve
+    } else if (isApprovalBranchMap(approvalSchema)) {
+      approve =
+        approvalSchema.approve === undefined
+          ? null
+          : schemaToWire(approvalSchema.approve)
+      reject =
+        approvalSchema.reject === undefined
+          ? null
+          : schemaToWire(approvalSchema.reject)
+    } else {
+      throw new TypeError(
+        'approvalSchema must be a SchemaInput or a nonempty map containing approve or reject.',
+      )
+    }
+  }
+
+  const responseSchema: JSONSchema = {
+    oneOf: [
+      decisionEnvelope({
+        approved: true,
+        payload: approve,
+        inputSchema: normalizedInput,
+      }),
+      decisionEnvelope({
+        approved: false,
+        payload: reject,
+        inputSchema: null,
+      }),
+    ],
+  }
+  const responseCanonical = canonicalInterruptJson(responseSchema)
+  const approvalCanonical = canonicalInterruptJson({
+    approve: approve?.jsonSchema ?? null,
+    reject: reject?.jsonSchema ?? null,
+  })
+
+  return {
+    branches: { approve, reject },
+    responseSchema,
+    responseSchemaHash: digestInterruptJson(responseCanonical),
+    approvalSchemaHash: digestInterruptJson(approvalCanonical),
+  }
+}
+
+export function hashSchemaInput(schema: SchemaInput | undefined): string {
+  if (schema === undefined) return digestInterruptJson('undefined')
+  const normalized = schemaToWire(schema)
+  const identity = normalized.jsonSchema ?? {
+    standardValidator: 'unserialized',
+  }
+  return digestInterruptJson(canonicalInterruptJson(identity))
+}
diff --git a/packages/ai/src/activities/chat/tools/json-schema-validator.ts b/packages/ai/src/activities/chat/tools/json-schema-validator.ts
new file mode 100644
index 000000000..753a89873
--- /dev/null
+++ b/packages/ai/src/activities/chat/tools/json-schema-validator.ts
@@ -0,0 +1,138 @@
+import Ajv2020 from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import type { ErrorObject } from 'ajv'
+import type { JSONSchema } from '../../../types'
+
+export interface JsonSchemaValidationIssue {
+  keyword: string
+  message: string
+  path: ReadonlyArray<string | number>
+}
+
+export class JsonSchemaCompilationError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'JsonSchemaCompilationError'
+  }
+}
+
+const draft202012 = 'https://json-schema.org/draft/2020-12/schema'
+
+function decodePointer(pointer: string): Array<string> {
+  if (pointer === '') return []
+  return pointer
+    .slice(1)
+    .split('/')
+    .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+}
+
+function issuePath(error: ErrorObject): Array<string> {
+  const path = decodePointer(error.instancePath)
+  if (error.keyword === 'required') {
+    path.push(String(error.params['missingProperty']))
+  }
+  if (error.keyword === 'additionalProperties') {
+    path.push(String(error.params['additionalProperty']))
+  }
+  return path
+}
+
+function assertSupportedSchemaTree(
+  schema: unknown,
+): asserts schema is JSONSchema {
+  const active = new WeakSet<object>()
+
+  const visit = (value: unknown): void => {
+    if (
+      value === null ||
+      typeof value === 'string' ||
+      typeof value === 'boolean'
+    ) {
+      return
+    }
+    if (typeof value === 'number') {
+      if (Number.isFinite(value)) return
+      throw new JsonSchemaCompilationError(
+        'Schema values must be JSON-compatible.',
+      )
+    }
+    if (typeof value !== 'object') {
+      throw new JsonSchemaCompilationError(
+        'Schema values must be JSON-compatible.',
+      )
+    }
+    if (
+      !Array.isArray(value) &&
+      Object.getPrototypeOf(value) !== Object.prototype &&
+      Object.getPrototypeOf(value) !== null
+    ) {
+      throw new JsonSchemaCompilationError(
+        'Schema nodes must be plain JSON objects.',
+      )
+    }
+    if (active.has(value)) {
+      throw new JsonSchemaCompilationError(
+        'Schema values must not contain cycles.',
+      )
+    }
+
+    active.add(value)
+    if (Array.isArray(value)) {
+      value.forEach(visit)
+      active.delete(value)
+      return
+    }
+
+    const record = value as Record<string, unknown>
+    if (
+      typeof record['$schema'] === 'string' &&
+      record['$schema'] !== draft202012
+    ) {
+      throw new JsonSchemaCompilationError('Only Draft 2020-12 is supported.')
+    }
+    if (typeof record['$ref'] === 'string' && !record['$ref'].startsWith('#')) {
+      throw new JsonSchemaCompilationError(
+        'Only document-local $ref values are supported.',
+      )
+    }
+    Object.values(record).forEach(visit)
+    active.delete(value)
+  }
+
+  visit(schema)
+}
+
+export function compileJsonSchema202012(
+  schema: unknown,
+): (value: unknown) => ReadonlyArray<JsonSchemaValidationIssue> {
+  assertSupportedSchemaTree(schema)
+  const ajv = new Ajv2020({
+    allErrors: true,
+    strict: true,
+    strictRequired: false,
+    allowUnionTypes: true,
+    validateFormats: true,
+    coerceTypes: false,
+    useDefaults: false,
+    removeAdditional: false,
+  })
+  addFormats(ajv, { mode: 'full' })
+
+  let validate
+  try {
+    validate = ajv.compile(schema)
+  } catch (cause) {
+    throw new JsonSchemaCompilationError('Invalid Draft 2020-12 schema.', {
+      cause,
+    })
+  }
+
+  return (value) => {
+    if (validate(value)) return []
+    return (validate.errors ?? []).map((error) => ({
+      keyword: error.keyword,
+      message: error.message ?? 'Schema validation failed.',
+      path: issuePath(error),
+    }))
+  }
+}
diff --git a/packages/ai/src/activities/chat/tools/tool-calls.ts b/packages/ai/src/activities/chat/tools/tool-calls.ts
index 5049c1de0..938700000 100644
--- a/packages/ai/src/activities/chat/tools/tool-calls.ts
+++ b/packages/ai/src/activities/chat/tools/tool-calls.ts
@@ -1,5 +1,6 @@
 import { normalizeToolResult } from '../../../utilities/tool-result'
 import { isStandardSchema, parseWithStandardSchema } from './schema-converter'
+import type { ToolApprovalResolution } from '../../../interrupts'
 import type {
   AnyTool,
   ContentPart,
@@ -435,6 +436,36 @@ export interface ClientToolRequest {
   input: any
 }
 
+export interface ToolResumeExecutionState {
+  deniedToolResults?: ReadonlyMap<string, unknown>
+  cancelledToolCallIds?: ReadonlySet<string>
+}
+
+function approvalResolution(
+  approvals: ReadonlyMap<string, ToolApprovalResolution>,
+  toolCallId: string,
+): ToolApprovalResolution | undefined {
+  return approvals.get(toolCallId) ?? approvals.get(`approval_${toolCallId}`)
+}
+
+function isApproved(resolution: ToolApprovalResolution): boolean {
+  return typeof resolution === 'boolean' ? resolution : resolution.approved
+}
+
+function editedApprovalArgs(
+  resolution: ToolApprovalResolution,
+): unknown | undefined {
+  return typeof resolution === 'object' && resolution.approved
+    ? resolution.editedArgs
+    : undefined
+}
+
+function deniedApprovalResult(resolution: ToolApprovalResolution): unknown {
+  return typeof resolution === 'object' && !resolution.approved
+    ? (resolution.payload ?? { error: 'User declined tool execution' })
+    : { error: 'User declined tool execution' }
+}
+
 interface ExecuteToolCallsResult {
   /** Tool results ready to send to LLM */
   results: Array<ToolResult>
@@ -685,7 +716,7 @@ function buildClientToolResult(
 export async function* executeToolCalls<TContext = unknown>(
   toolCalls: Array<ToolCall>,
   tools: ReadonlyArray<AnyTool>,
-  approvals: Map<string, boolean> = new Map(),
+  approvals: Map<string, ToolApprovalResolution> = new Map(),
   clientResults: Map<string, any> = new Map(),
   createCustomEventChunk?: (
     eventName: string,
@@ -694,6 +725,7 @@ export async function* executeToolCalls<TContext = unknown>(
   middlewareHooks?: ToolExecutionMiddlewareHooks,
   userContext?: TContext,
   abortSignal?: AbortSignal,
+  resumeState?: ToolResumeExecutionState,
 ): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
@@ -709,7 +741,11 @@ export async function* executeToolCalls<TContext = unknown>(
   // defer all execution so side effects don't happen before the user decides.
   const hasPendingApprovals = toolCalls.some((tc) => {
     const t = toolMap.get(tc.function.name)
-    return t?.needsApproval && !approvals.has(`approval_${tc.id}`)
+    return (
+      t?.needsApproval &&
+      approvalResolution(approvals, tc.id) === undefined &&
+      !resumeState?.cancelledToolCallIds?.has(tc.id)
+    )
   })
 
   for (const toolCall of toolCalls) {
@@ -729,11 +765,25 @@ export async function* executeToolCalls<TContext = unknown>(
 
     // Skip non-pending tools while approvals are outstanding
     if (hasPendingApprovals) {
-      if (!tool.needsApproval || approvals.has(`approval_${toolCall.id}`)) {
+      const isPendingApproval =
+        tool.needsApproval &&
+        approvalResolution(approvals, toolCall.id) === undefined
+      const isPlainClientRequest = !tool.needsApproval && !tool.execute
+      if (!isPendingApproval && !isPlainClientRequest) {
         continue
       }
     }
 
+    if (resumeState?.cancelledToolCallIds?.has(toolCall.id)) {
+      results.push({
+        toolCallId: toolCall.id,
+        toolName,
+        result: { error: 'Tool execution cancelled' },
+        state: 'output-error',
+      })
+      continue
+    }
+
     // Parse arguments, throwing error if invalid JSON
     let input: unknown = {}
     const argsStr = toolCall.function.arguments.trim() || '{}'
@@ -792,12 +842,14 @@ export async function* executeToolCalls<TContext = unknown>(
       // Check if tool needs approval
       if (tool.needsApproval) {
         const approvalId = `approval_${toolCall.id}`
+        const resolution = approvalResolution(approvals, toolCall.id)
 
         // Check if approval decision exists
-        if (approvals.has(approvalId)) {
-          const approved = approvals.get(approvalId)
+        if (resolution !== undefined) {
+          const approved = isApproved(resolution)
 
           if (approved) {
+            input = editedApprovalArgs(resolution) ?? input
             // Approved - check if client has executed
             if (clientResults.has(toolCall.id)) {
               results.push(
@@ -821,7 +873,9 @@ export async function* executeToolCalls<TContext = unknown>(
             results.push({
               toolCallId: toolCall.id,
               toolName,
-              result: { error: 'User declined tool execution' },
+              result:
+                resumeState?.deniedToolResults?.get(toolCall.id) ??
+                deniedApprovalResult(resolution),
               state: 'output-error',
             })
           }
@@ -860,12 +914,14 @@ export async function* executeToolCalls<TContext = unknown>(
     // CASE 2: Server tool with approval required
     if (tool.needsApproval) {
       const approvalId = `approval_${toolCall.id}`
+      const resolution = approvalResolution(approvals, toolCall.id)
 
       // Check if approval decision exists
-      if (approvals.has(approvalId)) {
-        const approved = approvals.get(approvalId)
+      if (resolution !== undefined) {
+        const approved = isApproved(resolution)
 
         if (approved) {
+          input = editedApprovalArgs(resolution) ?? input
           // Apply middleware before-hook for approved tools
           if (middlewareHooks) {
             const decision = await applyBeforeToolCallDecision(
@@ -895,7 +951,9 @@ export async function* executeToolCalls<TContext = unknown>(
           results.push({
             toolCallId: toolCall.id,
             toolName,
-            result: { error: 'User declined tool execution' },
+            result:
+              resumeState?.deniedToolResults?.get(toolCall.id) ??
+              deniedApprovalResult(resolution),
             state: 'output-error',
           })
         }
diff --git a/packages/ai/src/activities/chat/tools/tool-definition.ts b/packages/ai/src/activities/chat/tools/tool-definition.ts
index fe62bd4ac..2849661eb 100644
--- a/packages/ai/src/activities/chat/tools/tool-definition.ts
+++ b/packages/ai/src/activities/chat/tools/tool-definition.ts
@@ -1,36 +1,113 @@
-import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
 import type {
+  InferSchemaType,
   JSONSchema,
   SchemaInput,
   Tool,
   ToolExecuteFunction,
 } from '../../../types'
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from '@standard-schema/spec'
+
+export declare const toolApprovalCapability: unique symbol
+
+export interface ToolApprovalCapabilityMarker<
+  TNeedsApproval extends boolean,
+  TApprovalSchema,
+> {
+  readonly [toolApprovalCapability]?: {
+    needsApproval: TNeedsApproval
+    approvalSchema: TApprovalSchema
+  }
+}
+
+export type ApprovalSchemaConfig =
+  | SchemaInput
+  | { approve: SchemaInput; reject?: SchemaInput }
+  | { approve?: SchemaInput; reject: SchemaInput }
+
+type ApprovalConfig<
+  TNeedsApproval extends boolean,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined,
+> = TNeedsApproval extends true
+  ? { needsApproval: TNeedsApproval; approvalSchema?: TApprovalSchema }
+  : { needsApproval?: TNeedsApproval; approvalSchema?: never }
+
+export type ApprovalCapabilityOf<TTool> =
+  TTool extends ToolApprovalCapabilityMarker<infer TNeeds, unknown>
+    ? TNeeds
+    : false
+
+export type ApprovalSchemaOf<TTool> =
+  TTool extends ToolApprovalCapabilityMarker<boolean, infer TSchema>
+    ? TSchema
+    : undefined
+
+export declare const noSchema: unique symbol
+export type NoSchema = typeof noSchema
+
+export type InputSchemaOf<TTool> = TTool extends {
+  inputSchema: infer TInput
+}
+  ? TInput extends undefined
+    ? NoSchema
+    : TInput
+  : NoSchema
+
+export type OutputSchemaOf<TTool> = TTool extends {
+  outputSchema: infer TOutput
+}
+  ? TOutput extends undefined
+    ? NoSchema
+    : TOutput
+  : NoSchema
+
+type BuiltToolSchemaFields<
+  TInput extends SchemaInput | undefined,
+  TOutput extends SchemaInput | undefined,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined,
+> = {
+  inputSchema: TInput
+  outputSchema: TOutput
+  approvalSchema: TApprovalSchema
+}
 
 /**
  * Marker type for server-side tools
  */
 export interface ServerTool<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   TContext = unknown,
-> extends Tool<TInput, TOutput, TName, TContext> {
+  TNeedsApproval extends boolean = false,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
+>
+  extends
+    Tool<TInput, TOutput, TName, TContext>,
+    ToolApprovalCapabilityMarker<TNeedsApproval, TApprovalSchema> {
   __toolSide: 'server'
+  inputSchema?: TInput
+  outputSchema?: TOutput
+  needsApproval?: TNeedsApproval
+  approvalSchema?: TApprovalSchema
 }
 
 /**
  * Marker type for client-side tools
  */
 export interface ClientTool<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   TContext = unknown,
   // Captured as a literal (`true` / `false`) so downstream types — notably
   // the tool-call part's `approval` field — can be gated on it. Defaults to
   // `false` when the tool config omits `needsApproval`.
   TNeedsApproval extends boolean = false,
-> {
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
+> extends ToolApprovalCapabilityMarker<TNeedsApproval, TApprovalSchema> {
   __toolSide: 'client'
   name: TName
   description: string
@@ -42,35 +119,55 @@ export interface ClientTool<
   inputSchema?: TInput
   outputSchema?: TOutput
   needsApproval?: TNeedsApproval
+  approvalSchema?: TApprovalSchema
   lazy?: boolean
   metadata?: Record<string, unknown>
   execute?: ToolExecuteFunction<TInput, TOutput, TContext>
 }
 
+/** Broad server-tool shape for heterogeneous internal collections. */
+export type AnyServerTool = Omit<
+  ServerTool<any, any, string, any, boolean, any>,
+  'execute'
+> & {
+  execute?: ((args: any, context?: any) => any) | undefined
+}
+
 /**
  * Tool definition that can be used directly or instantiated for server/client
  */
 export interface ToolDefinitionInstance<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   TContext = unknown,
   TNeedsApproval extends boolean = false,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
 > extends Tool<TInput, TOutput, TName, TContext> {
   __toolSide: 'definition'
   // Narrow the base `needsApproval?: boolean` to the captured literal so it
   // survives into `ToolCallPartForTool`'s approval gate.
+  inputSchema: TInput
+  outputSchema: TOutput
   needsApproval?: TNeedsApproval
+  approvalSchema: TApprovalSchema
+  readonly [toolApprovalCapability]?: {
+    needsApproval: TNeedsApproval
+    approvalSchema: TApprovalSchema
+  }
 }
 
 /**
  * Union type for any kind of client-side tool (client tool or definition)
  */
 export type AnyClientTool =
-  | (Omit<ClientTool<any, any, string, any, boolean>, 'execute'> & {
+  | (Omit<ClientTool<any, any, string, any, boolean, any>, 'execute'> & {
       execute?: ((args: any, context?: any) => any) | undefined
     })
-  | (Omit<ToolDefinitionInstance<any, any, string, any, boolean>, 'execute'> & {
+  | (Omit<
+      ToolDefinitionInstance<any, any, string, any, boolean, any>,
+      'execute'
+    > & {
       execute?: ((args: any, context?: any) => any) | undefined
     })
 
@@ -83,63 +180,73 @@ export type InferToolName<T> = T extends { name: infer N } ? N : never
  * Extract the input type from a tool (inferred from Standard JSON Schema, or `unknown` for plain JSONSchema)
  */
 export type InferToolInput<T> = T extends { inputSchema?: infer TInput }
-  ? TInput extends StandardJSONSchemaV1<infer TInferred, unknown>
-    ? TInferred
-    : TInput extends JSONSchema
-      ? unknown
-      : unknown
+  ? TInput extends JSONSchema
+    ? unknown
+    : InferSchemaType<TInput>
   : unknown
 
 /**
  * Extract the output type from a tool (inferred from Standard JSON Schema, or `unknown` for plain JSONSchema)
  */
 export type InferToolOutput<T> = T extends { outputSchema?: infer TOutput }
-  ? TOutput extends StandardJSONSchemaV1<infer TInferred, unknown>
-    ? TInferred
-    : TOutput extends JSONSchema
-      ? unknown
-      : unknown
+  ? TOutput extends StandardJSONSchemaV1<any, any>
+    ? InferSchemaType<TOutput>
+    : TOutput extends StandardSchemaV1<any, any>
+      ? InferSchemaType<TOutput>
+      : TOutput extends JSONSchema
+        ? unknown
+        : InferSchemaType<TOutput>
   : unknown
 
 /**
  * Tool definition configuration
  */
-export interface ToolDefinitionConfig<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+export type ToolDefinitionConfig<
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   TNeedsApproval extends boolean = false,
-> {
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
+> = {
   name: TName
   description: string
   inputSchema?: TInput
   outputSchema?: TOutput
-  needsApproval?: TNeedsApproval
   lazy?: boolean
   metadata?: Record<string, unknown>
-}
+} & ApprovalConfig<TNeedsApproval, TApprovalSchema>
 
 /**
  * Tool definition builder that allows creating server or client tools from a shared definition
  */
 export interface ToolDefinition<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   TNeedsApproval extends boolean = false,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
 > extends ToolDefinitionInstance<
   TInput,
   TOutput,
   TName,
   unknown,
-  TNeedsApproval
+  TNeedsApproval,
+  TApprovalSchema
 > {
   /**
    * Create a server-side tool with execute function
    */
   server: <TContext = unknown>(
     execute: ToolExecuteFunction<TInput, TOutput, TContext>,
-  ) => ServerTool<TInput, TOutput, TName, TContext>
+  ) => ServerTool<
+    TInput,
+    TOutput,
+    TName,
+    TContext,
+    TNeedsApproval,
+    TApprovalSchema
+  > &
+    BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema>
 
   /**
    * Create a client-side tool with optional execute function.
@@ -148,7 +255,15 @@ export interface ToolDefinition<
    */
   client: <TContext = unknown>(
     execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
-  ) => ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval>
+  ) => ClientTool<
+    TInput,
+    TOutput,
+    TName,
+    TContext,
+    TNeedsApproval,
+    TApprovalSchema
+  > &
+    BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema>
 }
 
 /**
@@ -207,35 +322,84 @@ export interface ToolDefinition<
  * ```
  */
 export function toolDefinition<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = undefined,
+  TOutput extends SchemaInput | undefined = undefined,
   TName extends string = string,
   // `const` forces the literal (`true` / `false`) to be captured from the
   // config's optional `needsApproval` — without it TS widens to `boolean`,
   // which collapses the approval gate in `ToolCallPartForTool`.
   const TNeedsApproval extends boolean = false,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined = undefined,
 >(
-  config: ToolDefinitionConfig<TInput, TOutput, TName, TNeedsApproval>,
-): ToolDefinition<TInput, TOutput, TName, TNeedsApproval> {
-  const definition: ToolDefinition<TInput, TOutput, TName, TNeedsApproval> = {
+  config: ToolDefinitionConfig<
+    TInput,
+    TOutput,
+    TName,
+    TNeedsApproval,
+    TApprovalSchema
+  >,
+): ToolDefinition<TInput, TOutput, TName, TNeedsApproval, TApprovalSchema> {
+  if (config.approvalSchema !== undefined && config.needsApproval !== true) {
+    throw new TypeError('approvalSchema requires needsApproval: true.')
+  }
+  const inputSchema = config.inputSchema as TInput
+  const outputSchema = config.outputSchema as TOutput
+  const approvalSchema = config.approvalSchema as TApprovalSchema
+  const needsApproval = config.needsApproval as TNeedsApproval | undefined
+
+  const definition: ToolDefinition<
+    TInput,
+    TOutput,
+    TName,
+    TNeedsApproval,
+    TApprovalSchema
+  > = {
     __toolSide: 'definition',
     ...config,
+    inputSchema,
+    outputSchema,
+    approvalSchema,
+    needsApproval,
     server<TContext = unknown>(
       execute: ToolExecuteFunction<TInput, TOutput, TContext>,
-    ): ServerTool<TInput, TOutput, TName, TContext> {
+    ): ServerTool<
+      TInput,
+      TOutput,
+      TName,
+      TContext,
+      TNeedsApproval,
+      TApprovalSchema
+    > &
+      BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema> {
       return {
         __toolSide: 'server',
         ...config,
+        inputSchema,
+        outputSchema,
+        approvalSchema,
+        needsApproval,
         execute,
       }
     },
 
     client<TContext = unknown>(
       execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
-    ): ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval> {
+    ): ClientTool<
+      TInput,
+      TOutput,
+      TName,
+      TContext,
+      TNeedsApproval,
+      TApprovalSchema
+    > &
+      BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema> {
       return {
         __toolSide: 'client',
         ...config,
+        inputSchema,
+        outputSchema,
+        approvalSchema,
+        needsApproval,
         ...(execute !== undefined && { execute }),
       }
     },
diff --git a/packages/ai/src/client.ts b/packages/ai/src/client.ts
index 1a9d8e623..e9b84671f 100644
--- a/packages/ai/src/client.ts
+++ b/packages/ai/src/client.ts
@@ -232,17 +232,43 @@ export {
   type InferToolInput,
   type InferToolName,
   type InferToolOutput,
+  type ApprovalCapabilityOf,
+  type ApprovalSchemaConfig,
+  type ApprovalSchemaOf,
+  type InputSchemaOf,
+  type OutputSchemaOf,
+  type NoSchema,
   type ToolDefinition,
   type ToolDefinitionConfig,
   type ToolDefinitionInstance,
 } from './activities/chat/tools/tool-definition'
 
+export {
+  hashSchemaInput,
+  normalizeApprovalSchema,
+  type NormalizedApprovalSchema,
+  type NormalizedSchemaInput,
+} from './activities/chat/tools/approval-schema'
+
+export {
+  canonicalInterruptJson,
+  cloneAndDeepFreezeJson,
+  digestInterruptJson,
+} from './interrupt-serialization'
+
 export {
   convertSchemaToJsonSchema,
   isStandardSchema,
   parseWithStandardSchema,
+  validateWithStandardSchema,
 } from './activities/chat/tools/schema-converter'
 
+export {
+  JsonSchemaCompilationError,
+  compileJsonSchema202012,
+  type JsonSchemaValidationIssue,
+} from './activities/chat/tools/json-schema-validator'
+
 export {
   convertMessagesToModelMessages,
   generateMessageId,
@@ -316,6 +342,8 @@ export type {
   InferSchemaType,
 } from './types'
 
+export * from './interrupts'
+
 export type {
   AudioVisualization,
   RealtimeAdapter,
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index 5558029a2..4856093ee 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -45,12 +45,40 @@ export {
   type ToolDefinitionInstance,
   type ToolDefinitionConfig,
   type ServerTool,
+  type AnyServerTool,
   type ClientTool,
   type AnyClientTool,
   type InferToolName,
   type InferToolInput,
   type InferToolOutput,
+  type ApprovalCapabilityOf,
+  type ApprovalSchemaConfig,
+  type ApprovalSchemaOf,
+  type InputSchemaOf,
+  type OutputSchemaOf,
+  type NoSchema,
 } from './activities/chat/tools/tool-definition'
+export {
+  hashSchemaInput,
+  normalizeApprovalSchema,
+  type NormalizedApprovalSchema,
+  type NormalizedSchemaInput,
+} from './activities/chat/tools/approval-schema'
+export {
+  canonicalInterruptJson,
+  cloneAndDeepFreezeJson,
+  digestInterruptJson,
+} from './interrupt-serialization'
+export {
+  InterruptResumeValidationError,
+  interruptItemError,
+  readUnopenedInterruptBinding,
+  validateInterruptResumeBatch,
+  withoutInterruptBinding,
+  type PendingInterruptResumeRecord,
+  type ValidateInterruptResumeBatchInput,
+  type ValidatedInterruptResumeBatch,
+} from './interrupt-resume'
 
 // MCP chat option types
 export type {
@@ -67,8 +95,14 @@ export {
   convertSchemaToJsonSchema,
   isStandardSchema,
   parseWithStandardSchema,
+  validateWithStandardSchema,
   StandardSchemaValidationError,
 } from './activities/chat/tools/schema-converter'
+export {
+  JsonSchemaCompilationError,
+  compileJsonSchema202012,
+  type JsonSchemaValidationIssue,
+} from './activities/chat/tools/json-schema-validator'
 
 // Stream utilities
 export {
@@ -115,6 +149,7 @@ export type {
   ChatMiddlewarePhase,
   ChatMiddlewareConfig,
   ChatResumeToolState,
+  ChatResumeGenericResolution,
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   BeforeToolCallDecision,
@@ -130,6 +165,8 @@ export type {
   ChatSandboxHooks,
 } from './activities/chat/middleware/index'
 
+export * from './interrupts'
+
 // Base, activity-agnostic middleware. The observe-only superset that media
 // activities accept via their `middleware` option; `ChatMiddleware` adds the
 // chat-only hooks on top. Pure types only — the `otelMiddleware` value lives at
diff --git a/packages/ai/src/interrupt-resume.ts b/packages/ai/src/interrupt-resume.ts
new file mode 100644
index 000000000..0f6872b9a
--- /dev/null
+++ b/packages/ai/src/interrupt-resume.ts
@@ -0,0 +1,739 @@
+import { canonicalizeInterruptResolutions } from './interrupts'
+import {
+  canonicalInterruptJson,
+  digestInterruptJson,
+} from './interrupt-serialization'
+import {
+  hashSchemaInput,
+  normalizeApprovalSchema,
+} from './activities/chat/tools/approval-schema'
+import {
+  isStandardSchema,
+  validateWithStandardSchema,
+} from './activities/chat/tools/schema-converter'
+import { compileJsonSchema202012 } from './activities/chat/tools/json-schema-validator'
+import type {
+  InterruptBinding,
+  InterruptRecoveryStateV1,
+  InterruptSubmissionError,
+  ItemInterruptErrorCode,
+  ToolApprovalResolution,
+  UnopenedInterruptBinding,
+} from './interrupts'
+import type {
+  ChatMiddlewareConfig,
+  ChatResumeToolState,
+} from './activities/chat/middleware/types'
+import type { Interrupt, RunAgentResumeItem } from './types'
+
+const interruptBindingMetadataKey = 'tanstack:interruptBinding'
+
+/** The persistence-neutral shape required to validate an interrupt resume. */
+export interface PendingInterruptResumeRecord {
+  interruptId: string
+  payload: unknown
+  binding: InterruptBinding
+}
+
+export interface ValidateInterruptResumeBatchInput {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  pending: ReadonlyArray<PendingInterruptResumeRecord>
+  resume?: ReadonlyArray<RunAgentResumeItem>
+  tools: ChatMiddlewareConfig['tools']
+  now?: number
+}
+
+export interface ValidatedInterruptResumeBatch {
+  errors: ReadonlyArray<InterruptSubmissionError>
+  resolutions?: ReadonlyArray<RunAgentResumeItem>
+  canonicalResolutions?: string
+  fingerprint?: string
+  resumeToolState?: ChatResumeToolState
+}
+
+export class InterruptResumeValidationError extends Error {
+  override readonly name = 'InterruptResumeValidationError'
+
+  constructor(
+    readonly errors: ReadonlyArray<InterruptSubmissionError>,
+    readonly recovery?: InterruptRecoveryStateV1,
+  ) {
+    super(errors.map((error) => error.message).join(' '))
+  }
+}
+
+function objectValue(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object'
+    ? (value as Record<string, unknown>)
+    : null
+}
+
+function stringField(
+  value: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  return typeof value[key] === 'string' ? value[key] : undefined
+}
+
+function normalizeIssuePath(
+  path: ReadonlyArray<unknown> | undefined,
+): ReadonlyArray<string | number> | undefined {
+  if (!path) return undefined
+  return path.map((segment) => {
+    if (typeof segment === 'string' || typeof segment === 'number') {
+      return segment
+    }
+    const record = objectValue(segment)
+    const key = record?.key
+    return typeof key === 'number' ? key : String(key ?? segment)
+  })
+}
+
+export function interruptItemError(
+  input: Pick<
+    ValidateInterruptResumeBatchInput,
+    'threadId' | 'interruptedRunId' | 'generation'
+  >,
+  interruptId: string,
+  code: ItemInterruptErrorCode,
+  message: string,
+  options?: {
+    path?: ReadonlyArray<string | number>
+    source?: 'client' | 'server'
+    retryable?: boolean
+  },
+): InterruptSubmissionError {
+  return {
+    scope: 'item',
+    threadId: input.threadId,
+    interruptedRunId: input.interruptedRunId,
+    generation: input.generation,
+    interruptId,
+    code,
+    message,
+    source: options?.source ?? 'client',
+    retryable: options?.retryable ?? false,
+    ...(options?.path ? { path: options.path } : {}),
+  }
+}
+
+async function validateSchemaValue(input: {
+  schema: unknown
+  value: unknown
+  onIssue: (message: string, path?: ReadonlyArray<string | number>) => void
+}): Promise<void> {
+  if (isStandardSchema(input.schema)) {
+    const result = await validateWithStandardSchema<unknown>(
+      input.schema,
+      input.value,
+    )
+    if (!result.success) {
+      for (const issue of result.issues) {
+        input.onIssue(issue.message, normalizeIssuePath(issue.path))
+      }
+    }
+    return
+  }
+
+  const validate = compileJsonSchema202012(input.schema)
+  for (const issue of validate(input.value)) {
+    input.onIssue(issue.message, issue.path)
+  }
+}
+
+type RuntimeTool = ChatMiddlewareConfig['tools'][number] & {
+  approvalSchema?: Parameters<typeof normalizeApprovalSchema>[0]
+}
+
+function runtimeTool(
+  tools: ChatMiddlewareConfig['tools'],
+  name: string,
+): RuntimeTool | undefined {
+  return tools.find((tool) => tool.name === name) as RuntimeTool | undefined
+}
+
+function descriptorResponseSchema(
+  record: PendingInterruptResumeRecord,
+): unknown {
+  return objectValue(record.payload)?.responseSchema
+}
+
+function schemaHash(schema: unknown): string {
+  return digestInterruptJson(canonicalInterruptJson(schema))
+}
+
+async function pushSchemaIssues(input: {
+  request: ValidateInterruptResumeBatchInput
+  errors: Array<InterruptSubmissionError>
+  interruptId: string
+  schema: unknown
+  value: unknown
+  code: ItemInterruptErrorCode
+  label: string
+}): Promise<void> {
+  try {
+    await validateSchemaValue({
+      schema: input.schema,
+      value: input.value,
+      onIssue: (message, path) => {
+        input.errors.push(
+          interruptItemError(
+            input.request,
+            input.interruptId,
+            input.code,
+            `${input.label}: ${message}`,
+            { path },
+          ),
+        )
+      },
+    })
+  } catch (error) {
+    input.errors.push(
+      interruptItemError(
+        input.request,
+        input.interruptId,
+        'invalid-response-schema',
+        `${input.label} could not be validated: ${error instanceof Error ? error.message : String(error)}`,
+        { source: 'server' },
+      ),
+    )
+  }
+}
+
+function validateDescriptorSchema(
+  input: ValidateInterruptResumeBatchInput,
+  record: PendingInterruptResumeRecord,
+  binding: InterruptBinding,
+  errors: Array<InterruptSubmissionError>,
+): unknown {
+  const schema = descriptorResponseSchema(record)
+  if (
+    schema === undefined ||
+    schemaHash(schema) !== binding.responseSchemaHash
+  ) {
+    errors.push(
+      interruptItemError(
+        input,
+        record.interruptId,
+        'invalid-response-schema',
+        `Interrupt ${record.interruptId} response schema no longer matches its binding.`,
+        { source: 'server' },
+      ),
+    )
+  }
+  return schema
+}
+
+/**
+ * Validate and translate a complete interrupt batch before any tool executes.
+ * Both ephemeral chat resumes and durable persistence use this function.
+ */
+export async function validateInterruptResumeBatch(
+  input: ValidateInterruptResumeBatchInput,
+): Promise<ValidatedInterruptResumeBatch> {
+  const grouped = new Map<string, Array<InterruptSubmissionError>>()
+  const batchErrors: Array<InterruptSubmissionError> = []
+  const group = (interruptId: string): Array<InterruptSubmissionError> => {
+    const existing = grouped.get(interruptId)
+    if (existing) return existing
+    const created: Array<InterruptSubmissionError> = []
+    grouped.set(interruptId, created)
+    return created
+  }
+  const pendingById = new Map(
+    input.pending.map((record) => [record.interruptId, record]),
+  )
+  const resumeById = new Map<string, RunAgentResumeItem>()
+  const counts = new Map<string, number>()
+  for (const entry of input.resume ?? []) {
+    counts.set(entry.interruptId, (counts.get(entry.interruptId) ?? 0) + 1)
+    if (!resumeById.has(entry.interruptId))
+      resumeById.set(entry.interruptId, entry)
+  }
+
+  for (const [interruptId, count] of counts) {
+    if (count > 1) {
+      group(interruptId).push(
+        interruptItemError(
+          input,
+          interruptId,
+          'conflict',
+          `Interrupt ${interruptId} has duplicate resume entries.`,
+        ),
+      )
+    }
+  }
+
+  let incomplete = false
+  for (const record of input.pending) {
+    const errors = group(record.interruptId)
+    const entry = resumeById.get(record.interruptId)
+    const binding = record.binding
+    if (!entry) {
+      incomplete = true
+      errors.push(
+        interruptItemError(
+          input,
+          record.interruptId,
+          'unknown-interrupt',
+          `Missing resume entry for interrupt ${record.interruptId}.`,
+        ),
+      )
+    }
+    if (
+      binding.interruptedRunId !== input.interruptedRunId ||
+      binding.generation !== input.generation ||
+      binding.interruptId !== record.interruptId
+    ) {
+      errors.push(
+        interruptItemError(
+          input,
+          record.interruptId,
+          'stale',
+          `Interrupt ${record.interruptId} has stale correlation metadata.`,
+          { source: 'server' },
+        ),
+      )
+    }
+    if (
+      binding.expiresAt !== undefined &&
+      Date.parse(binding.expiresAt) <= (input.now ?? Date.now())
+    ) {
+      errors.push(
+        interruptItemError(
+          input,
+          record.interruptId,
+          'expired',
+          `Interrupt ${record.interruptId} has expired.`,
+          { source: 'server' },
+        ),
+      )
+    }
+
+    const responseSchema = validateDescriptorSchema(
+      input,
+      record,
+      binding,
+      errors,
+    )
+    if (!entry) continue
+    const entryStatus: unknown = entry.status
+    if (entryStatus !== 'resolved' && entryStatus !== 'cancelled') {
+      errors.push(
+        interruptItemError(
+          input,
+          record.interruptId,
+          'invalid-payload',
+          `Interrupt ${record.interruptId} has invalid status ${String(entryStatus)}.`,
+        ),
+      )
+      continue
+    }
+    if (binding.kind === 'generic') {
+      if (entry.status === 'cancelled') {
+        if (entry.payload !== undefined) {
+          errors.push(
+            interruptItemError(
+              input,
+              record.interruptId,
+              'invalid-payload',
+              `Cancelled interrupt ${record.interruptId} must not include a payload.`,
+            ),
+          )
+        }
+      } else if (responseSchema !== undefined) {
+        await pushSchemaIssues({
+          request: input,
+          errors,
+          interruptId: record.interruptId,
+          schema: responseSchema,
+          value: entry.payload,
+          code: 'invalid-payload',
+          label: `Interrupt ${record.interruptId} payload is invalid`,
+        })
+      }
+      continue
+    }
+
+    const tool = runtimeTool(input.tools, binding.toolName)
+    if (!tool) {
+      errors.push(
+        interruptItemError(
+          input,
+          record.interruptId,
+          'stale',
+          `Tool ${binding.toolName} is unavailable for interrupt ${record.interruptId}.`,
+          { source: 'server' },
+        ),
+      )
+      continue
+    }
+
+    let approval: ReturnType<typeof normalizeApprovalSchema> | undefined
+    let schemaDrifted = false
+    if (binding.kind === 'client-tool-execution') {
+      if (hashSchemaInput(tool.outputSchema) !== binding.outputSchemaHash) {
+        errors.push(
+          interruptItemError(
+            input,
+            record.interruptId,
+            'stale',
+            `Tool ${binding.toolName} output schema has changed.`,
+            { source: 'server' },
+          ),
+        )
+        schemaDrifted = true
+      }
+    } else {
+      try {
+        approval = normalizeApprovalSchema(
+          tool.approvalSchema,
+          tool.inputSchema,
+        )
+      } catch {
+        errors.push(
+          interruptItemError(
+            input,
+            record.interruptId,
+            'stale',
+            `Tool ${binding.toolName} approval schema is unavailable.`,
+            { source: 'server' },
+          ),
+        )
+        schemaDrifted = true
+      }
+      if (
+        approval !== undefined &&
+        (hashSchemaInput(tool.inputSchema) !== binding.inputSchemaHash ||
+          approval.approvalSchemaHash !== binding.approvalSchemaHash ||
+          approval.responseSchemaHash !== binding.responseSchemaHash)
+      ) {
+        errors.push(
+          interruptItemError(
+            input,
+            record.interruptId,
+            'stale',
+            `Tool ${binding.toolName} approval schema has changed.`,
+            { source: 'server' },
+          ),
+        )
+        schemaDrifted = true
+      }
+    }
+
+    if (entry.status === 'cancelled') {
+      if (entry.payload !== undefined) {
+        errors.push(
+          interruptItemError(
+            input,
+            record.interruptId,
+            'invalid-payload',
+            `Cancelled interrupt ${record.interruptId} must not include a payload.`,
+          ),
+        )
+      }
+      continue
+    }
+    if (schemaDrifted) continue
+
+    if (binding.kind === 'client-tool-execution') {
+      if (responseSchema !== undefined) {
+        await pushSchemaIssues({
+          request: input,
+          errors,
+          interruptId: record.interruptId,
+          schema: responseSchema,
+          value: entry.payload,
+          code: 'invalid-tool-output',
+          label: `Tool ${binding.toolName} output is invalid`,
+        })
+      }
+      if (tool.outputSchema !== undefined) {
+        await pushSchemaIssues({
+          request: input,
+          errors,
+          interruptId: record.interruptId,
+          schema: tool.outputSchema,
+          value: entry.payload,
+          code: 'invalid-tool-output',
+          label: `Tool ${binding.toolName} output is invalid`,
+        })
+      }
+      continue
+    }
+
+    if (approval === undefined) continue
+    const envelope = objectValue(entry.payload)
+    const approved =
+      typeof entry.payload === 'boolean'
+        ? entry.payload
+        : typeof envelope?.approved === 'boolean'
+          ? envelope.approved
+          : undefined
+    if (approved === undefined) {
+      errors.push(
+        interruptItemError(
+          input,
+          record.interruptId,
+          'invalid-payload',
+          `Approval ${record.interruptId} must be a boolean or decision envelope.`,
+        ),
+      )
+      continue
+    }
+    if (envelope) {
+      await pushSchemaIssues({
+        request: input,
+        errors,
+        interruptId: record.interruptId,
+        schema: approval.responseSchema,
+        value: entry.payload,
+        code: 'invalid-payload',
+        label: `Approval ${record.interruptId} envelope is invalid`,
+      })
+    }
+    if (approved && envelope?.editedArgs !== undefined) {
+      if (tool.inputSchema === undefined) {
+        errors.push(
+          interruptItemError(
+            input,
+            record.interruptId,
+            'invalid-edited-args',
+            `Approval ${record.interruptId} cannot edit arguments without an input schema.`,
+          ),
+        )
+      } else {
+        await pushSchemaIssues({
+          request: input,
+          errors,
+          interruptId: record.interruptId,
+          schema: tool.inputSchema,
+          value: envelope.editedArgs,
+          code: 'invalid-edited-args',
+          label: `Approval ${record.interruptId} edited arguments are invalid`,
+        })
+      }
+    }
+    const branch = approved
+      ? approval.branches.approve
+      : approval.branches.reject
+    if (branch) {
+      if (!envelope) {
+        errors.push(
+          interruptItemError(
+            input,
+            record.interruptId,
+            'invalid-payload',
+            `Approval ${record.interruptId} requires a payload for the ${approved ? 'approve' : 'reject'} decision.`,
+          ),
+        )
+      } else {
+        await pushSchemaIssues({
+          request: input,
+          errors,
+          interruptId: record.interruptId,
+          schema: branch.source,
+          value: envelope.payload,
+          code: 'invalid-payload',
+          label: `Approval ${record.interruptId} payload is invalid`,
+        })
+      }
+    }
+  }
+
+  for (const entry of input.resume ?? []) {
+    if (!pendingById.has(entry.interruptId)) {
+      incomplete = true
+      group(entry.interruptId).push(
+        interruptItemError(
+          input,
+          entry.interruptId,
+          'unknown-interrupt',
+          `Resume entry references unknown interrupt ${entry.interruptId}.`,
+        ),
+      )
+    }
+  }
+
+  if (incomplete) {
+    batchErrors.push({
+      scope: 'batch',
+      threadId: input.threadId,
+      interruptedRunId: input.interruptedRunId,
+      generation: input.generation,
+      code: 'incomplete-batch',
+      message:
+        'Resume entries must resolve or cancel the complete interrupt batch.',
+      source: 'client',
+      retryable: false,
+      interruptIds: input.pending.map((record) => record.interruptId),
+    })
+  }
+
+  const itemErrors = [...grouped.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .flatMap(([, errors]) => errors)
+  if (itemErrors.length > 0) {
+    batchErrors.push({
+      scope: 'batch',
+      threadId: input.threadId,
+      interruptedRunId: input.interruptedRunId,
+      generation: input.generation,
+      code: 'item-validation-failed',
+      message: 'One or more interrupt resolutions are invalid.',
+      source: 'client',
+      retryable: false,
+      interruptIds: input.pending.map((record) => record.interruptId),
+    })
+    return { errors: [...itemErrors, ...batchErrors] }
+  }
+
+  const canonical = canonicalizeInterruptResolutions(input.resume ?? [])
+  const approvals = new Map<string, ToolApprovalResolution>()
+  const clientToolResults = new Map<string, unknown>()
+  const genericInterrupts = new Map<
+    string,
+    | { interruptId: string; status: 'resolved'; payload: unknown }
+    | { interruptId: string; status: 'cancelled' }
+  >()
+  const deniedToolResults = new Map<string, unknown>()
+  const cancelledToolCallIds = new Set<string>()
+
+  for (const record of input.pending) {
+    const entry = resumeById.get(record.interruptId)
+    if (!entry) continue
+    const binding = record.binding
+    if (binding.kind === 'generic') {
+      genericInterrupts.set(
+        record.interruptId,
+        entry.status === 'resolved'
+          ? {
+              interruptId: record.interruptId,
+              status: 'resolved',
+              payload: entry.payload,
+            }
+          : { interruptId: record.interruptId, status: 'cancelled' },
+      )
+      continue
+    }
+    if (entry.status === 'cancelled') {
+      cancelledToolCallIds.add(binding.toolCallId)
+      continue
+    }
+    if (binding.kind === 'client-tool-execution') {
+      clientToolResults.set(binding.toolCallId, entry.payload)
+      continue
+    }
+    const envelope = objectValue(entry.payload)
+    const resolution: ToolApprovalResolution =
+      typeof entry.payload === 'boolean'
+        ? entry.payload
+        : envelope?.approved === true
+          ? {
+              approved: true,
+              ...(envelope.editedArgs !== undefined
+                ? { editedArgs: envelope.editedArgs }
+                : {}),
+              ...(envelope.payload !== undefined
+                ? { payload: envelope.payload }
+                : {}),
+            }
+          : {
+              approved: false,
+              ...(envelope?.payload !== undefined
+                ? { payload: envelope.payload }
+                : {}),
+            }
+    approvals.set(binding.toolCallId, resolution)
+    if (
+      resolution === false ||
+      (typeof resolution === 'object' && !resolution.approved)
+    ) {
+      deniedToolResults.set(
+        binding.toolCallId,
+        typeof resolution === 'object' ? resolution.payload : undefined,
+      )
+    }
+  }
+
+  return {
+    errors: [],
+    resolutions: canonical.resolutions,
+    canonicalResolutions: canonical.canonicalResolutions,
+    fingerprint: canonical.fingerprint,
+    resumeToolState: {
+      approvals,
+      clientToolResults,
+      genericInterrupts,
+      deniedToolResults,
+      cancelledToolCallIds,
+    },
+  }
+}
+
+export function readUnopenedInterruptBinding(
+  descriptor: Interrupt,
+): UnopenedInterruptBinding | undefined {
+  const metadata = objectValue(descriptor.metadata)
+  const raw = metadata
+    ? objectValue(metadata[interruptBindingMetadataKey])
+    : null
+  if (!raw || stringField(raw, 'interruptId') !== descriptor.id)
+    return undefined
+  const kind = stringField(raw, 'kind')
+  const interruptId = stringField(raw, 'interruptId')
+  const responseSchemaHash = stringField(raw, 'responseSchemaHash')
+  const expiresAt = stringField(raw, 'expiresAt')
+  if (!interruptId || !responseSchemaHash) return undefined
+  if (kind === 'generic') {
+    return {
+      kind,
+      interruptId,
+      responseSchemaHash,
+      ...(expiresAt ? { expiresAt } : {}),
+    }
+  }
+  const toolName = stringField(raw, 'toolName')
+  const toolCallId = stringField(raw, 'toolCallId')
+  if (!toolName || !toolCallId) return undefined
+  if (kind === 'client-tool-execution') {
+    const outputSchemaHash = stringField(raw, 'outputSchemaHash')
+    if (!outputSchemaHash) return undefined
+    return {
+      kind,
+      interruptId,
+      toolName,
+      toolCallId,
+      outputSchemaHash,
+      responseSchemaHash,
+      ...(expiresAt ? { expiresAt } : {}),
+    }
+  }
+  if (kind === 'tool-approval') {
+    const inputSchemaHash = stringField(raw, 'inputSchemaHash')
+    const approvalSchemaHash = stringField(raw, 'approvalSchemaHash')
+    if (!inputSchemaHash || !approvalSchemaHash) return undefined
+    return {
+      kind,
+      interruptId,
+      toolName,
+      toolCallId,
+      originalArgs: raw.originalArgs,
+      inputSchemaHash,
+      approvalSchemaHash,
+      responseSchemaHash,
+      ...(expiresAt ? { expiresAt } : {}),
+    }
+  }
+  return undefined
+}
+
+export function withoutInterruptBinding(descriptor: Interrupt): Interrupt {
+  const metadata = objectValue(descriptor.metadata)
+  if (!metadata || !(interruptBindingMetadataKey in metadata)) return descriptor
+  const publicMetadata = { ...metadata }
+  delete publicMetadata[interruptBindingMetadataKey]
+  return { ...descriptor, metadata: publicMetadata }
+}
diff --git a/packages/ai/src/interrupt-serialization.ts b/packages/ai/src/interrupt-serialization.ts
new file mode 100644
index 000000000..2441c2b6c
--- /dev/null
+++ b/packages/ai/src/interrupt-serialization.ts
@@ -0,0 +1,68 @@
+import { sha256 } from '@noble/hashes/sha2.js'
+import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js'
+
+function canonical(value: unknown, active: WeakSet<object>): string {
+  if (value === null) return 'null'
+  if (typeof value === 'string' || typeof value === 'boolean') {
+    return JSON.stringify(value)
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return JSON.stringify(value)
+  }
+  if (typeof value !== 'object') {
+    throw new TypeError('Interrupt values must be JSON-compatible.')
+  }
+  if (active.has(value)) {
+    throw new TypeError('Interrupt values must not cycle.')
+  }
+  if (
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) !== Object.prototype &&
+    Object.getPrototypeOf(value) !== null
+  ) {
+    throw new TypeError('Interrupt values must use plain JSON objects.')
+  }
+
+  active.add(value)
+  let encoded: string
+  if (Array.isArray(value)) {
+    const items: Array<string> = []
+    for (let index = 0; index < value.length; index++) {
+      items.push(canonical(value[index], active))
+    }
+    encoded = `[${items.join(',')}]`
+  } else {
+    const record = value as Record<string, unknown>
+    encoded = `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonical(record[key], active)}`)
+      .join(',')}}`
+  }
+  active.delete(value)
+  return encoded
+}
+
+export function canonicalInterruptJson(value: unknown): string {
+  return canonical(value, new WeakSet<object>())
+}
+
+export function digestInterruptJson(canonicalJson: string): string {
+  if (typeof canonicalJson !== 'string') {
+    throw new TypeError('Interrupt digests require canonical JSON text.')
+  }
+  return `sha256:${bytesToHex(sha256(utf8ToBytes(canonicalJson)))}`
+}
+
+function freezeTree(value: unknown): void {
+  if (value === null || typeof value !== 'object' || Object.isFrozen(value)) {
+    return
+  }
+  Object.values(value).forEach(freezeTree)
+  Object.freeze(value)
+}
+
+export function cloneAndDeepFreezeJson<T>(value: T): T {
+  const clone: T = JSON.parse(canonicalInterruptJson(value))
+  freezeTree(clone)
+  return clone
+}
diff --git a/packages/ai/src/interrupts.ts b/packages/ai/src/interrupts.ts
new file mode 100644
index 000000000..8768c1d3a
--- /dev/null
+++ b/packages/ai/src/interrupts.ts
@@ -0,0 +1,200 @@
+import { createCapability } from './activities/chat/middleware/capabilities'
+import {
+  canonicalInterruptJson,
+  cloneAndDeepFreezeJson,
+  digestInterruptJson,
+} from './interrupt-serialization'
+import type { Interrupt, RunAgentResumeItem } from './types'
+
+export interface OpenInterruptBatchInput {
+  threadId: string
+  interruptedRunId: string
+  descriptors: ReadonlyArray<Interrupt>
+  bindings: ReadonlyArray<UnopenedInterruptBinding>
+}
+
+export interface CommitInterruptResolutionsInput {
+  threadId: string
+  interruptedRunId: string
+  continuationRunId: string
+  expectedGeneration: number
+  expectedInterruptIds: ReadonlyArray<string>
+  resolutions: ReadonlyArray<RunAgentResumeItem>
+  fingerprint: string
+  canonicalResolutions: string
+}
+
+export interface InterruptCorrelation {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  submissionId?: string
+  continuationRunId?: string
+}
+
+export type ItemInterruptErrorCode =
+  | 'invalid-payload'
+  | 'invalid-edited-args'
+  | 'invalid-tool-output'
+  | 'invalid-response-schema'
+  | 'unknown-interrupt'
+  | 'expired'
+  | 'stale'
+  | 'conflict'
+  | 'legacy-unsupported'
+
+export type BatchInterruptErrorCode =
+  | 'incomplete-batch'
+  | 'item-validation-failed'
+  | 'unsupported-bulk-operation'
+  | 'async-resolver'
+  | 'inactive-transaction'
+  | 'mixed-provenance'
+  | 'transport'
+  | 'server'
+  | 'protocol'
+  | 'invalid-response-schema'
+  | 'expired'
+  | 'stale'
+  | 'conflict'
+  | 'persistence-required'
+  | 'atomic-commit-unsupported'
+  | 'recovery-unavailable'
+  | 'legacy-submit-failed'
+
+export interface ItemInterruptError extends InterruptCorrelation {
+  scope: 'item'
+  interruptId: string
+  code: ItemInterruptErrorCode
+  message: string
+  path?: ReadonlyArray<string | number>
+  source: 'client' | 'server'
+  retryable: boolean
+}
+
+export interface BatchInterruptError extends InterruptCorrelation {
+  scope: 'batch'
+  code: BatchInterruptErrorCode
+  message: string
+  source: 'client' | 'server' | 'transport'
+  retryable: boolean
+  interruptIds: ReadonlyArray<string>
+}
+
+export type InterruptSubmissionError = ItemInterruptError | BatchInterruptError
+
+export type InterruptBinding =
+  | {
+      kind: 'tool-approval'
+      interruptId: string
+      interruptedRunId: string
+      generation: number
+      toolName: string
+      toolCallId: string
+      originalArgs: unknown
+      inputSchemaHash: string
+      approvalSchemaHash: string
+      responseSchemaHash: string
+      expiresAt?: string
+    }
+  | {
+      kind: 'client-tool-execution'
+      interruptId: string
+      interruptedRunId: string
+      generation: number
+      toolName: string
+      toolCallId: string
+      outputSchemaHash: string
+      responseSchemaHash: string
+      expiresAt?: string
+    }
+  | {
+      kind: 'generic'
+      interruptId: string
+      interruptedRunId: string
+      generation: number
+      responseSchemaHash: string
+      expiresAt?: string
+    }
+
+export type UnopenedInterruptBinding = InterruptBinding extends infer TBinding
+  ? TBinding extends InterruptBinding
+    ? Omit<TBinding, 'interruptedRunId' | 'generation'>
+    : never
+  : never
+
+export type InterruptCommitResult =
+  | { status: 'committed'; continuationRunId: string }
+  | { status: 'replayed'; continuationRunId: string }
+  | {
+      status: 'conflict'
+      authoritativeState: InterruptRecoveryStateV1
+    }
+
+export interface InterruptRecoveryQuery {
+  threadId: string
+  interruptedRunId: string
+  knownGeneration: number
+}
+
+export interface InterruptRecoveryStateV1 extends InterruptCorrelation {
+  schemaVersion: 1
+  state: 'pending' | 'committed' | 'expired' | 'missing' | 'legacy-committed'
+  pendingInterrupts: ReadonlyArray<Interrupt>
+  committed?: {
+    fingerprint: string
+    resolutions?: ReadonlyArray<RunAgentResumeItem>
+    continuationRunId?: string
+    committedAt: string
+  }
+}
+
+export interface InterruptPersistenceGateway {
+  openInterruptBatch: (
+    input: OpenInterruptBatchInput,
+  ) => Promise<{ generation: number; descriptors: ReadonlyArray<Interrupt> }>
+  commitInterruptResolutions: (
+    input: CommitInterruptResolutionsInput,
+  ) => Promise<InterruptCommitResult>
+  getInterruptRecoveryState: (
+    input: InterruptRecoveryQuery,
+  ) => Promise<InterruptRecoveryStateV1>
+}
+
+export type ToolApprovalResolution =
+  | boolean
+  | {
+      approved: true
+      editedArgs?: unknown
+      payload?: unknown
+    }
+  | {
+      approved: false
+      payload?: unknown
+      editedArgs?: never
+    }
+
+export function canonicalizeInterruptResolutions(
+  resolutions: ReadonlyArray<RunAgentResumeItem>,
+): {
+  resolutions: ReadonlyArray<RunAgentResumeItem>
+  canonicalResolutions: string
+  fingerprint: string
+} {
+  const sorted = [...resolutions].sort((left, right) =>
+    left.interruptId.localeCompare(right.interruptId),
+  )
+  const frozen = cloneAndDeepFreezeJson(sorted)
+  const canonicalResolutions = canonicalInterruptJson(frozen)
+  return Object.freeze({
+    resolutions: frozen,
+    canonicalResolutions,
+    fingerprint: digestInterruptJson(canonicalResolutions),
+  })
+}
+
+export const InterruptPersistenceCapability =
+  createCapability<InterruptPersistenceGateway>()('interrupt-persistence')
+
+export const [getInterruptPersistence, provideInterruptPersistence] =
+  InterruptPersistenceCapability
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index a585cac23..7e3c0abd5 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -5,6 +5,10 @@ import type {
 import type { InternalLogger } from './logger/internal-logger'
 import type { SystemPrompt } from './system-prompts'
 import type { CapabilityContext } from './activities/chat/middleware/capabilities'
+import type {
+  InterruptRecoveryStateV1,
+  InterruptSubmissionError,
+} from './interrupts'
 // The canonical usage types live in the leaf `@tanstack/ai-event-client`
 // package (which `@tanstack/ai` already depends on) so there is a single source
 // of truth without a dependency cycle. They are re-exported below.
@@ -572,8 +576,8 @@ export type ToolExecutionContext<TContext = unknown> =
   }
 
 export type ToolExecuteFunction<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = SchemaInput,
+  TOutput extends SchemaInput | undefined = SchemaInput,
   TContext = unknown,
 > = undefined extends TContext
   ? (
@@ -599,8 +603,8 @@ export type ToolExecuteFunction<
  * @see https://standardschema.dev/json-schema
  */
 export interface Tool<
-  TInput extends SchemaInput = SchemaInput,
-  TOutput extends SchemaInput = SchemaInput,
+  TInput extends SchemaInput | undefined = SchemaInput,
+  TOutput extends SchemaInput | undefined = SchemaInput,
   TName extends string = string,
   TContext = unknown,
 > {
@@ -982,6 +986,9 @@ export interface TextOptions<
    */
   parentRunId?: string
 
+  /** Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. */
+  state?: unknown
+
   /**
    * AG-UI interrupt resume responses supplied by the client on a follow-up run.
    * Threaded through request parsing now so later runtime behavior can resolve
@@ -1108,6 +1115,10 @@ export interface RunFinishedEvent extends AGUIRunFinishedEvent {
 export interface RunErrorEvent extends AGUIRunErrorEvent {
   /** Model identifier for multi-model support */
   model?: string
+  /** Exhaustive TanStack interrupt submission failures for this run. */
+  'tanstack:interruptErrors'?: ReadonlyArray<InterruptSubmissionError>
+  /** Authoritative interrupt state returned with stale/conflicting submissions. */
+  'tanstack:interruptRecovery'?: InterruptRecoveryStateV1
   /**
    * @deprecated Use top-level `message` and `code` fields instead.
    * Kept for backward compatibility.
@@ -1368,6 +1379,10 @@ export interface StructuredOutputStartEvent extends CustomEvent {
  * (the agent-loop branch of `runStreamingStructuredOutputImpl` in
  * `activities/chat/index.ts` forwards CUSTOM events from `TextEngine.run()`).
  */
+/**
+ * @deprecated Native interrupts use RUN_FINISHED interrupt outcomes. This
+ * compatibility event remains readable until 1.0.
+ */
 export interface ApprovalRequestedEvent extends CustomEvent {
   name: 'approval-requested'
   value: {
@@ -1384,6 +1399,10 @@ export interface ApprovalRequestedEvent extends CustomEvent {
  * will not fire for that run. Shape fixed by the agent-loop forwarding in
  * `runStreamingStructuredOutputImpl` in `activities/chat/index.ts`.
  */
+/**
+ * @deprecated Native interrupts use RUN_FINISHED interrupt outcomes. This
+ * compatibility event remains readable until 1.0.
+ */
 export interface ToolInputAvailableEvent extends CustomEvent {
   name: 'tool-input-available'
   value: {
diff --git a/packages/ai/tests/chat-mcp-manager.test.ts b/packages/ai/tests/chat-mcp-manager.test.ts
index de8e982de..73f3c78a2 100644
--- a/packages/ai/tests/chat-mcp-manager.test.ts
+++ b/packages/ai/tests/chat-mcp-manager.test.ts
@@ -8,7 +8,7 @@ import {
   type ToolResult,
 } from '../src/activities/chat/tools/tool-calls'
 import { EventType } from '../src/types'
-import type { ServerTool } from '../src'
+import type { JSONSchema, ServerTool } from '../src'
 import type {
   CustomEvent,
   ToolCall,
@@ -41,11 +41,13 @@ interface ReadResourceResult {
 }
 
 /** A ui-linked ServerTool whose `metadata.mcp` is statically typed. */
-interface UiServerTool extends ServerTool {
+type TestServerTool = ServerTool<JSONSchema>
+
+interface UiServerTool extends TestServerTool {
   metadata: McpAppMetadata
 }
 
-function tool(name: string): ServerTool {
+function tool(name: string): TestServerTool {
   return {
     __toolSide: 'server',
     name,
@@ -55,7 +57,7 @@ function tool(name: string): ServerTool {
   }
 }
 
-function source(tools: Array<ServerTool>, opts: { fail?: boolean } = {}) {
+function source(tools: Array<TestServerTool>, opts: { fail?: boolean } = {}) {
   const s = {
     closed: false,
     tools: async (_o?: { lazy?: boolean }) => {
@@ -193,7 +195,7 @@ type EmittedEvent = { name: string; value: UIResourceEvent['value'] }
  * CUSTOM events emitted via the same `emitCustomEvent` closure chat() wires in.
  */
 async function runToolResult(
-  tool: ServerTool,
+  tool: TestServerTool,
   toolCallId: string,
   onEvent: (event: EmittedEvent) => void,
 ): Promise<Array<ToolResult>> {
diff --git a/packages/ai/tests/chat.test.ts b/packages/ai/tests/chat.test.ts
index c92169229..e3bba7f58 100644
--- a/packages/ai/tests/chat.test.ts
+++ b/packages/ai/tests/chat.test.ts
@@ -1,8 +1,15 @@
 import { describe, expect, it, vi } from 'vitest'
 import { chat, createChatOptions } from '../src/activities/chat/index'
+import { defineChatMiddleware } from '../src/activities/chat/middleware/define'
 import { DISCOVERY_TOOL_NAME } from '../src/activities/chat/tools/lazy-tool-manager'
+import {
+  InterruptPersistenceCapability,
+  provideInterruptPersistence,
+} from '../src/interrupts'
 import { EventType } from '../src/types'
-import type { StreamChunk, Tool } from '../src/types'
+import type { StreamChunk, Tool, UIMessage } from '../src/types'
+import type { InterruptPersistenceGateway } from '../src/interrupts'
+import type { ChatResumeToolState } from '../src/activities/chat/middleware/types'
 import {
   chunk,
   ev,
@@ -33,6 +40,60 @@ function expectSingleRunFinished(
   return terminals[0]!
 }
 
+function interruptPersistenceMiddleware(sequence?: string[]) {
+  const gateway: InterruptPersistenceGateway = {
+    openInterruptBatch: async (input) => {
+      sequence?.push('persist')
+      return { generation: 1, descriptors: input.descriptors }
+    },
+    commitInterruptResolutions: async (input) => ({
+      status: 'committed',
+      continuationRunId: input.continuationRunId,
+    }),
+    getInterruptRecoveryState: async (input) => ({
+      schemaVersion: 1,
+      state: 'missing',
+      threadId: input.threadId,
+      interruptedRunId: input.interruptedRunId,
+      generation: input.knownGeneration,
+      pendingInterrupts: [],
+    }),
+  }
+  return defineChatMiddleware({
+    name: 'test-interrupt-persistence',
+    provides: [InterruptPersistenceCapability],
+    setup(ctx) {
+      provideInterruptPersistence(ctx, gateway)
+    },
+    async onChunk(_ctx, value) {
+      if (
+        value.type === EventType.RUN_FINISHED &&
+        value.outcome?.type === 'interrupt'
+      ) {
+        await gateway.openInterruptBatch({
+          threadId: value.threadId,
+          interruptedRunId: value.runId,
+          descriptors: value.outcome.interrupts,
+          bindings: [],
+        })
+      } else if (value.type === EventType.MESSAGES_SNAPSHOT) {
+        sequence?.push('messages')
+      } else if (value.type === EventType.STATE_SNAPSHOT) {
+        sequence?.push('state')
+      }
+    },
+  })
+}
+
+function resumeStateMiddleware(resumeToolState: ChatResumeToolState) {
+  return defineChatMiddleware({
+    name: 'test-interrupt-resume-state',
+    onConfig() {
+      return { resumeToolState }
+    },
+  })
+}
+
 // ============================================================================
 // Tests
 // ============================================================================
@@ -42,6 +103,115 @@ describe('chat()', () => {
   // Streaming text (no tools)
   // ==========================================================================
   describe('streaming text (no tools)', () => {
+    it('turns an exact interrupt replay signal into a successful terminal', async () => {
+      const { adapter, calls } = createMockAdapter({
+        iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+      })
+      const replay = defineChatMiddleware({
+        name: 'test-interrupt-replay',
+        onConfig(ctx) {
+          if (ctx.phase !== 'init') return
+          const error = new Error('already committed')
+          error.name = 'InterruptReplaySignal'
+          Object.defineProperty(error, 'continuationRunId', {
+            value: 'committed-run',
+            enumerable: true,
+          })
+          throw error
+        },
+      })
+
+      const chunks = await collectChunks(
+        chat({
+          adapter,
+          messages: [],
+          threadId: 'thread-1',
+          runId: 'replay-run',
+          parentRunId: 'interrupted-run',
+          middleware: [replay],
+        }) as AsyncIterable<StreamChunk>,
+      )
+
+      expect(calls).toHaveLength(0)
+      expect(chunks).toEqual([
+        expect.objectContaining({
+          type: EventType.RUN_FINISHED,
+          threadId: 'thread-1',
+          runId: 'replay-run',
+          outcome: { type: 'success' },
+        }),
+      ])
+    })
+
+    it('turns interrupt validation failures into one structured error terminal', async () => {
+      const { adapter, calls } = createMockAdapter({
+        iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+      })
+      const onError = vi.fn()
+      const errors = [
+        {
+          scope: 'item',
+          interruptId: 'interrupt-1',
+          code: 'invalid-payload',
+          message: 'The interrupt payload is invalid.',
+          source: 'server',
+          retryable: false,
+          threadId: 'thread-1',
+          interruptedRunId: 'interrupted-run',
+          generation: 1,
+        },
+      ] as const
+      const recovery = {
+        schemaVersion: 1,
+        state: 'pending',
+        threadId: 'thread-1',
+        interruptedRunId: 'interrupted-run',
+        generation: 1,
+        pendingInterrupts: [],
+      } as const
+      const validation = defineChatMiddleware({
+        name: 'test-interrupt-validation-failure',
+        onConfig(ctx) {
+          if (ctx.phase !== 'init') return
+          const error = new Error(errors[0].message)
+          error.name = 'InterruptResumeValidationError'
+          Object.defineProperties(error, {
+            errors: { value: errors, enumerable: true },
+            recovery: { value: recovery, enumerable: true },
+          })
+          throw error
+        },
+        onError(_ctx, info) {
+          onError(info.error)
+        },
+      })
+
+      const chunks = await collectChunks(
+        chat({
+          adapter,
+          messages: [],
+          stream: true,
+          threadId: 'thread-1',
+          runId: 'continuation-run',
+          parentRunId: 'interrupted-run',
+          middleware: [validation],
+        }),
+      )
+
+      expect(calls).toHaveLength(0)
+      expect(onError).toHaveBeenCalledTimes(1)
+      expect(chunks).toEqual([
+        expect.objectContaining({
+          type: EventType.RUN_ERROR,
+          threadId: 'thread-1',
+          runId: 'continuation-run',
+          message: errors[0].message,
+          'tanstack:interruptErrors': errors,
+          'tanstack:interruptRecovery': recovery,
+        }),
+      ])
+    })
+
     it('should return an async iterable that yields all adapter chunks', async () => {
       const { adapter } = createMockAdapter({
         iterations: [
@@ -420,6 +590,96 @@ describe('chat()', () => {
   // Client tools (no execute)
   // ==========================================================================
   describe('client tools (no execute)', () => {
+    it('emits an actionable client-tool interrupt without persistence', async () => {
+      const { adapter } = createMockAdapter({
+        iterations: [
+          [
+            ev.runStarted(),
+            ev.toolStart('call_1', 'clientSearch'),
+            ev.toolArgs('call_1', '{"query":"test"}'),
+            ev.runFinished('tool_calls'),
+          ],
+        ],
+      })
+
+      const chunks = await collectChunks(
+        chat({
+          adapter,
+          messages: [{ role: 'user', content: 'Search' }],
+          tools: [clientTool('clientSearch')],
+          threadId: 'thread-1',
+          runId: 'interrupted-run',
+        }) as AsyncIterable<StreamChunk>,
+      )
+
+      expect(chunks.some((value) => value.type === EventType.RUN_ERROR)).toBe(
+        false,
+      )
+      expect(expectSingleRunFinished(chunks)).toMatchObject({
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              id: 'client_tool_call_1',
+              metadata: {
+                'tanstack:interruptBinding': {
+                  kind: 'client-tool-execution',
+                  interruptId: 'client_tool_call_1',
+                  interruptedRunId: 'interrupted-run',
+                  generation: 0,
+                },
+              },
+            },
+          ],
+        },
+      })
+    })
+
+    it('persists before ordered snapshots and emits canonical bound interrupts', async () => {
+      const sequence: string[] = []
+      const { adapter } = createMockAdapter({
+        iterations: [
+          [
+            ev.runStarted(),
+            ev.toolStart('call_1', 'clientSearch'),
+            ev.toolArgs('call_1', '{"query":"test"}'),
+            ev.runFinished('tool_calls'),
+          ],
+        ],
+      })
+
+      const chunks = await collectChunks(
+        chat({
+          adapter,
+          messages: [{ role: 'user', content: 'Search' }],
+          tools: [clientTool('clientSearch')],
+          state: { screen: 'search' },
+          middleware: [interruptPersistenceMiddleware(sequence)],
+        }) as AsyncIterable<StreamChunk>,
+      )
+
+      expect(sequence).toEqual(['persist', 'messages', 'state'])
+      expect(chunks.slice(-3).map((value) => value.type)).toEqual([
+        EventType.MESSAGES_SNAPSHOT,
+        EventType.STATE_SNAPSHOT,
+        EventType.RUN_FINISHED,
+      ])
+      const terminal = expectSingleRunFinished(chunks)
+      expect(terminal).toMatchObject({
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              id: 'client_tool_call_1',
+              reason: 'tanstack:client_tool_execution',
+              toolCallId: 'call_1',
+              responseSchema: {},
+            },
+          ],
+        },
+      })
+    })
+
     it('should yield an interrupt outcome for client tools', async () => {
       const { adapter } = createMockAdapter({
         iterations: [
@@ -436,6 +696,7 @@ describe('chat()', () => {
         adapter,
         messages: [{ role: 'user', content: 'Search for test' }],
         tools: [clientTool('clientSearch')],
+        middleware: [interruptPersistenceMiddleware()],
       })
 
       const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
@@ -449,7 +710,7 @@ describe('chat()', () => {
           interrupts: [
             {
               id: 'client_tool_call_1',
-              reason: 'client_tool_input',
+              reason: 'tanstack:client_tool_execution',
               toolCallId: 'call_1',
               metadata: {
                 kind: 'client_tool',
@@ -489,6 +750,7 @@ describe('chat()', () => {
           required: ['status'],
         },
         stream: true,
+        middleware: [interruptPersistenceMiddleware()],
       })
 
       const chunks = await collectChunks(
@@ -553,6 +815,7 @@ describe('chat()', () => {
           serverTool('searchTools', searchExecute),
           clientTool('showNotification'),
         ],
+        middleware: [interruptPersistenceMiddleware()],
       })
 
       const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
@@ -581,7 +844,7 @@ describe('chat()', () => {
           type: 'interrupt',
           interrupts: [
             {
-              reason: 'client_tool_input',
+              reason: 'tanstack:client_tool_execution',
               toolCallId: 'call_client',
               metadata: {
                 kind: 'client_tool',
@@ -641,6 +904,7 @@ describe('chat()', () => {
           serverTool('getWeather', weatherExecute),
           clientTool('showNotification'),
         ],
+        middleware: [interruptPersistenceMiddleware()],
       })
 
       const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
@@ -669,7 +933,7 @@ describe('chat()', () => {
           type: 'interrupt',
           interrupts: [
             {
-              reason: 'client_tool_input',
+              reason: 'tanstack:client_tool_execution',
               toolCallId: 'call_client',
               metadata: {
                 kind: 'client_tool',
@@ -696,7 +960,66 @@ describe('chat()', () => {
   // Approval flow
   // ==========================================================================
   describe('approval flow', () => {
-    it('should end with an interrupt outcome for tools with needsApproval', async () => {
+    it('applies approved argument edits and emits only a result for a resumed tool call', async () => {
+      const execute = vi.fn().mockImplementation((input) => input)
+      const { adapter } = createMockAdapter({
+        iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+      })
+      const stream = chat({
+        adapter,
+        messages: [
+          { role: 'user', content: 'Change it' },
+          {
+            role: 'assistant',
+            content: '',
+            toolCalls: [
+              {
+                id: 'call_1',
+                type: 'function',
+                function: {
+                  name: 'dangerousTool',
+                  arguments: '{"action":"original"}',
+                },
+              },
+            ],
+          },
+        ],
+        tools: [
+          {
+            ...serverTool('dangerousTool', execute),
+            needsApproval: true,
+            inputSchema: {
+              type: 'object',
+              properties: { action: { type: 'string' } },
+              required: ['action'],
+            },
+          },
+        ],
+        middleware: [
+          interruptPersistenceMiddleware(),
+          resumeStateMiddleware({
+            approvals: new Map([
+              ['call_1', { approved: true, editedArgs: { action: 'edited' } }],
+            ]),
+          }),
+        ],
+      })
+
+      const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
+      expect(execute).toHaveBeenCalledWith(
+        { action: 'edited' },
+        expect.any(Object),
+      )
+      expect(
+        chunks
+          .filter(
+            (value) => 'toolCallId' in value && value.toolCallId === 'call_1',
+          )
+          .map((value) => value.type),
+      ).toEqual([EventType.TOOL_CALL_RESULT])
+    })
+
+    it('should end with an interrupt outcome for tools with needsApproval without persistence', async () => {
       const { adapter } = createMockAdapter({
         iterations: [
           [
@@ -711,6 +1034,8 @@ describe('chat()', () => {
       const stream = chat({
         adapter,
         messages: [{ role: 'user', content: 'Delete something' }],
+        threadId: 'thread-1',
+        runId: 'interrupted-run',
         tools: [serverTool('dangerousTool', () => ({ ok: true }))].map((t) => ({
           ...t,
           needsApproval: true,
@@ -729,18 +1054,20 @@ describe('chat()', () => {
           interrupts: [
             {
               id: 'approval_call_1',
-              reason: 'approval_required',
+              reason: 'tool_call',
               message: 'Approval required to run dangerousTool',
               toolCallId: 'call_1',
-              responseSchema: {
-                type: 'object',
-                properties: { approved: { type: 'boolean' } },
-                required: ['approved'],
-              },
+              responseSchema: { oneOf: expect.any(Array) },
               metadata: {
                 kind: 'approval',
                 toolName: 'dangerousTool',
                 input: { action: 'delete' },
+                'tanstack:interruptBinding': {
+                  kind: 'tool-approval',
+                  interruptId: 'approval_call_1',
+                  interruptedRunId: 'interrupted-run',
+                  generation: 0,
+                },
               },
             },
           ],
@@ -755,6 +1082,725 @@ describe('chat()', () => {
       ).toBe(false)
     })
 
+    it('resumes an ephemeral approval from an approval-requested UIMessage tool call', async () => {
+      const execute = vi.fn().mockReturnValue({ ok: true })
+      const { adapter } = createMockAdapter({
+        iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+      })
+      const messages: Array<UIMessage> = [
+        {
+          id: 'user-1',
+          role: 'user',
+          parts: [{ type: 'text', content: 'Delete something' }],
+        },
+        {
+          id: 'assistant-1',
+          role: 'assistant',
+          parts: [
+            {
+              type: 'tool-call',
+              id: 'call_1',
+              name: 'dangerousTool',
+              arguments: '{"action":"delete"}',
+              input: { action: 'delete' },
+              state: 'approval-requested',
+              approval: {
+                id: 'approval_call_1',
+                needsApproval: true,
+              },
+            },
+          ],
+        },
+      ]
+
+      const chunks = await collectChunks(
+        chat({
+          adapter,
+          messages,
+          threadId: 'thread-1',
+          runId: 'continuation-run',
+          parentRunId: 'interrupted-run',
+          tools: [
+            {
+              ...serverTool('dangerousTool', execute),
+              needsApproval: true,
+              inputSchema: {
+                type: 'object',
+                properties: { action: { type: 'string' } },
+                required: ['action'],
+                additionalProperties: false,
+              },
+            },
+          ],
+          resume: [
+            {
+              interruptId: 'approval_call_1',
+              status: 'resolved',
+              payload: true,
+            },
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      )
+
+      expect(execute).toHaveBeenCalledWith(
+        { action: 'delete' },
+        expect.any(Object),
+      )
+      expect(chunks.some((chunk) => chunk.type === EventType.RUN_ERROR)).toBe(
+        false,
+      )
+      expect(expectSingleRunFinished(chunks).finishReason).toBe('stop')
+    })
+
+    it('validates an entire ephemeral batch before executing any tool', async () => {
+      const firstExecute = vi.fn().mockReturnValue({ ok: true })
+      const secondExecute = vi.fn().mockReturnValue({ ok: true })
+      const { adapter, calls } = createMockAdapter({
+        iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+      })
+      const inputSchema = {
+        type: 'object',
+        properties: { action: { type: 'string' } },
+        required: ['action'],
+        additionalProperties: false,
+      }
+
+      const chunks = await collectChunks(
+        chat({
+          adapter,
+          threadId: 'thread-1',
+          runId: 'continuation-run',
+          parentRunId: 'interrupted-run',
+          messages: [
+            { role: 'user', content: 'Do both' },
+            {
+              role: 'assistant',
+              content: '',
+              toolCalls: [
+                {
+                  id: 'call_1',
+                  type: 'function',
+                  function: {
+                    name: 'firstTool',
+                    arguments: '{"action":"one"}',
+                  },
+                },
+                {
+                  id: 'call_2',
+                  type: 'function',
+                  function: {
+                    name: 'secondTool',
+                    arguments: '{"action":"two"}',
+                  },
+                },
+              ],
+            },
+          ],
+          tools: [
+            {
+              ...serverTool('firstTool', firstExecute),
+              needsApproval: true,
+              inputSchema,
+            },
+            {
+              ...serverTool('secondTool', secondExecute),
+              needsApproval: true,
+              inputSchema,
+            },
+          ],
+          resume: [
+            {
+              interruptId: 'approval_call_1',
+              status: 'resolved',
+              payload: {
+                approved: true,
+                editedArgs: { action: 1 },
+              },
+            },
+            {
+              interruptId: 'approval_call_2',
+              status: 'resolved',
+              payload: {
+                approved: true,
+                editedArgs: { action: 2 },
+              },
+            },
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      )
+
+      expect(firstExecute).not.toHaveBeenCalled()
+      expect(secondExecute).not.toHaveBeenCalled()
+      expect(calls).toHaveLength(0)
+      expect(chunks).toEqual([
+        expect.objectContaining({
+          type: EventType.RUN_ERROR,
+          'tanstack:interruptErrors': expect.arrayContaining([
+            expect.objectContaining({
+              interruptId: 'approval_call_1',
+              code: 'invalid-edited-args',
+            }),
+            expect.objectContaining({
+              interruptId: 'approval_call_2',
+              code: 'invalid-edited-args',
+            }),
+            expect.objectContaining({
+              scope: 'batch',
+              code: 'item-validation-failed',
+            }),
+          ]),
+        }),
+      ])
+    })
+
+    it('translates ephemeral approve, reject, cancel, edits, and payloads before continuing', async () => {
+      const approvedExecute = vi.fn().mockImplementation((input) => input)
+      const rejectedExecute = vi.fn()
+      const cancelledExecute = vi.fn()
+      const { adapter } = createMockAdapter({
+        iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+      })
+      const inputSchema = {
+        type: 'object',
+        properties: { action: { type: 'string' } },
+        required: ['action'],
+        additionalProperties: false,
+      }
+      const approvalSchema = {
+        approve: {
+          type: 'object',
+          properties: { note: { type: 'string' } },
+          required: ['note'],
+          additionalProperties: false,
+        },
+        reject: {
+          type: 'object',
+          properties: { reason: { type: 'string' } },
+          required: ['reason'],
+          additionalProperties: false,
+        },
+      }
+
+      const chunks = await collectChunks(
+        chat({
+          adapter,
+          threadId: 'thread-1',
+          runId: 'continuation-run',
+          parentRunId: 'interrupted-run',
+          messages: [
+            { role: 'user', content: 'Do all' },
+            {
+              role: 'assistant',
+              content: '',
+              toolCalls: [
+                {
+                  id: 'call_approve',
+                  type: 'function',
+                  function: {
+                    name: 'approvedTool',
+                    arguments: '{"action":"original"}',
+                  },
+                },
+                {
+                  id: 'call_reject',
+                  type: 'function',
+                  function: {
+                    name: 'rejectedTool',
+                    arguments: '{"action":"reject"}',
+                  },
+                },
+                {
+                  id: 'call_cancel',
+                  type: 'function',
+                  function: {
+                    name: 'cancelledTool',
+                    arguments: '{"action":"cancel"}',
+                  },
+                },
+              ],
+            },
+          ],
+          tools: [
+            {
+              ...serverTool('approvedTool', approvedExecute),
+              needsApproval: true,
+              inputSchema,
+              approvalSchema,
+            },
+            {
+              ...serverTool('rejectedTool', rejectedExecute),
+              needsApproval: true,
+              inputSchema,
+              approvalSchema,
+            },
+            {
+              ...serverTool('cancelledTool', cancelledExecute),
+              needsApproval: true,
+              inputSchema,
+              approvalSchema,
+            },
+          ],
+          resume: [
+            {
+              interruptId: 'approval_call_approve',
+              status: 'resolved',
+              payload: {
+                approved: true,
+                editedArgs: { action: 'edited' },
+                payload: { note: 'reviewed' },
+              },
+            },
+            {
+              interruptId: 'approval_call_reject',
+              status: 'resolved',
+              payload: {
+                approved: false,
+                payload: { reason: 'unsafe' },
+              },
+            },
+            {
+              interruptId: 'approval_call_cancel',
+              status: 'cancelled',
+            },
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      )
+
+      expect(chunks.some((chunk) => chunk.type === EventType.RUN_ERROR)).toBe(
+        false,
+      )
+      expect(approvedExecute).toHaveBeenCalledWith(
+        { action: 'edited' },
+        expect.any(Object),
+      )
+      expect(rejectedExecute).not.toHaveBeenCalled()
+      expect(cancelledExecute).not.toHaveBeenCalled()
+      expect(chunks).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            type: EventType.TOOL_CALL_RESULT,
+            toolCallId: 'call_approve',
+            content: JSON.stringify({ action: 'edited' }),
+          }),
+          expect.objectContaining({
+            type: EventType.TOOL_CALL_RESULT,
+            toolCallId: 'call_reject',
+            content: JSON.stringify({ reason: 'unsafe' }),
+          }),
+          expect.objectContaining({
+            type: EventType.TOOL_CALL_RESULT,
+            toolCallId: 'call_cancel',
+          }),
+        ]),
+      )
+    })
+
+    it('translates a validated ephemeral client-tool output', async () => {
+      const { adapter, calls } = createMockAdapter({
+        iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+      })
+      const outputSchema = {
+        type: 'object',
+        properties: { result: { type: 'string' } },
+        required: ['result'],
+        additionalProperties: false,
+      }
+
+      const chunks = await collectChunks(
+        chat({
+          adapter,
+          threadId: 'thread-1',
+          runId: 'continuation-run',
+          parentRunId: 'interrupted-run',
+          messages: [
+            { role: 'user', content: 'Search' },
+            {
+              role: 'assistant',
+              content: '',
+              toolCalls: [
+                {
+                  id: 'call_search',
+                  type: 'function',
+                  function: {
+                    name: 'clientSearch',
+                    arguments: '{"query":"test"}',
+                  },
+                },
+              ],
+            },
+          ],
+          tools: [
+            {
+              ...clientTool('clientSearch'),
+              outputSchema,
+            },
+          ],
+          resume: [
+            {
+              interruptId: 'client_tool_call_search',
+              status: 'resolved',
+              payload: { result: 'found' },
+            },
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      )
+
+      expect(chunks.some((chunk) => chunk.type === EventType.RUN_ERROR)).toBe(
+        false,
+      )
+      expect(calls).toHaveLength(1)
+      expect(calls[0]!.messages).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            role: 'tool',
+            toolCallId: 'call_search',
+            content: JSON.stringify({ result: 'found' }),
+          }),
+        ]),
+      )
+    })
+
+    it('continues an approved client tool through its client-execution interrupt', async () => {
+      const tool = {
+        ...clientTool('clientDanger', { needsApproval: true }),
+        outputSchema: {
+          type: 'object',
+          properties: { result: { type: 'string' } },
+          required: ['result'],
+          additionalProperties: false,
+        },
+      }
+      const history = [
+        { role: 'user' as const, content: 'Run it' },
+        {
+          role: 'assistant' as const,
+          content: '',
+          toolCalls: [
+            {
+              id: 'call_client',
+              type: 'function' as const,
+              function: { name: 'clientDanger', arguments: '{}' },
+            },
+          ],
+        },
+      ]
+
+      const approvalAdapter = createMockAdapter({ iterations: [] })
+      const approvalChunks = await collectChunks(
+        chat({
+          adapter: approvalAdapter.adapter,
+          messages: history,
+          tools: [tool],
+          threadId: 'thread-1',
+          runId: 'approval-continuation',
+          parentRunId: 'approval-run',
+          resume: [
+            {
+              interruptId: 'approval_call_client',
+              status: 'resolved',
+              payload: true,
+            },
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      )
+      expect(expectSingleRunFinished(approvalChunks)).toMatchObject({
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              id: 'client_tool_call_client',
+              reason: 'tanstack:client_tool_execution',
+            },
+          ],
+        },
+      })
+
+      const outputAdapter = createMockAdapter({
+        iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+      })
+      const outputChunks = await collectChunks(
+        chat({
+          adapter: outputAdapter.adapter,
+          messages: history,
+          tools: [tool],
+          threadId: 'thread-1',
+          runId: 'output-continuation',
+          parentRunId: 'approval-continuation',
+          resume: [
+            {
+              interruptId: 'client_tool_call_client',
+              status: 'resolved',
+              payload: { result: 'done' },
+            },
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      )
+
+      expect(
+        outputChunks.some((chunk) => chunk.type === EventType.RUN_ERROR),
+      ).toBe(false)
+      expect(outputAdapter.calls).toHaveLength(1)
+      expect(outputAdapter.calls[0]!.messages).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            role: 'tool',
+            toolCallId: 'call_client',
+            content: JSON.stringify({ result: 'done' }),
+          }),
+        ]),
+      )
+    })
+
+    it('reconstructs a mixed approval and plain client-tool batch atomically', async () => {
+      const approvedExecute = vi.fn().mockReturnValue({ approved: true })
+      const history = [
+        { role: 'user' as const, content: 'Run both' },
+        {
+          role: 'assistant' as const,
+          content: '',
+          toolCalls: [
+            {
+              id: 'call_approval',
+              type: 'function' as const,
+              function: { name: 'approvedTool', arguments: '{}' },
+            },
+            {
+              id: 'call_client',
+              type: 'function' as const,
+              function: { name: 'plainClient', arguments: '{}' },
+            },
+          ],
+        },
+      ]
+      const { adapter, calls } = createMockAdapter({
+        iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+      })
+
+      const chunks = await collectChunks(
+        chat({
+          adapter,
+          messages: history,
+          tools: [
+            {
+              ...serverTool('approvedTool', approvedExecute),
+              needsApproval: true,
+            },
+            clientTool('plainClient'),
+          ],
+          threadId: 'thread-1',
+          runId: 'continuation-run',
+          parentRunId: 'interrupted-run',
+          resume: [
+            {
+              interruptId: 'approval_call_approval',
+              status: 'resolved',
+              payload: true,
+            },
+            {
+              interruptId: 'client_tool_call_client',
+              status: 'resolved',
+              payload: { result: 'done' },
+            },
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      )
+
+      expect(chunks.some((chunk) => chunk.type === EventType.RUN_ERROR)).toBe(
+        false,
+      )
+      expect(approvedExecute).toHaveBeenCalledTimes(1)
+      expect(calls).toHaveLength(1)
+      expect(calls[0]!.messages).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            role: 'tool',
+            toolCallId: 'call_approval',
+          }),
+          expect.objectContaining({
+            role: 'tool',
+            toolCallId: 'call_client',
+            content: JSON.stringify({ result: 'done' }),
+          }),
+        ]),
+      )
+    })
+
+    it('rejects an incomplete mixed approval and plain client-tool resume before execution', async () => {
+      const approvedExecute = vi.fn().mockReturnValue({ approved: true })
+      const { adapter, calls } = createMockAdapter({
+        iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+      })
+
+      const chunks = await collectChunks(
+        chat({
+          adapter,
+          messages: [
+            { role: 'user', content: 'Run both' },
+            {
+              role: 'assistant',
+              content: '',
+              toolCalls: [
+                {
+                  id: 'call_approval',
+                  type: 'function',
+                  function: { name: 'approvedTool', arguments: '{}' },
+                },
+                {
+                  id: 'call_client',
+                  type: 'function',
+                  function: { name: 'plainClient', arguments: '{}' },
+                },
+              ],
+            },
+          ],
+          tools: [
+            {
+              ...serverTool('approvedTool', approvedExecute),
+              needsApproval: true,
+            },
+            clientTool('plainClient'),
+          ],
+          threadId: 'thread-1',
+          runId: 'continuation-run',
+          parentRunId: 'interrupted-run',
+          resume: [
+            {
+              interruptId: 'approval_call_approval',
+              status: 'resolved',
+              payload: true,
+            },
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      )
+
+      expect(approvedExecute).not.toHaveBeenCalled()
+      expect(calls).toHaveLength(0)
+      expect(chunks).toEqual([
+        expect.objectContaining({
+          type: EventType.RUN_ERROR,
+          'tanstack:interruptErrors': expect.arrayContaining([
+            expect.objectContaining({
+              interruptId: 'client_tool_call_client',
+              code: 'unknown-interrupt',
+            }),
+            expect.objectContaining({
+              scope: 'batch',
+              code: 'incomplete-batch',
+              interruptIds: [
+                'approval_call_approval',
+                'client_tool_call_client',
+              ],
+            }),
+          ]),
+        }),
+      ])
+    })
+
+    it('keeps mixed interrupt identities and order stable during ephemeral reconstruction', async () => {
+      const approvedExecute = vi.fn().mockReturnValue({ approved: true })
+      const tools = [
+        clientTool('plainClient'),
+        {
+          ...serverTool('approvedTool', approvedExecute),
+          needsApproval: true,
+        },
+      ]
+      const history = [
+        { role: 'user' as const, content: 'Run both' },
+        {
+          role: 'assistant' as const,
+          content: '',
+          toolCalls: [
+            {
+              id: 'call_client',
+              type: 'function' as const,
+              function: { name: 'plainClient', arguments: '{}' },
+            },
+            {
+              id: 'call_approval',
+              type: 'function' as const,
+              function: { name: 'approvedTool', arguments: '{}' },
+            },
+          ],
+        },
+      ]
+      const initialAdapter = createMockAdapter({
+        iterations: [
+          [
+            ev.runStarted('interrupted-run'),
+            ev.toolStart('call_client', 'plainClient', 0),
+            ev.toolArgs('call_client', '{}'),
+            ev.toolStart('call_approval', 'approvedTool', 1),
+            ev.toolArgs('call_approval', '{}'),
+            ev.runFinished('tool_calls', 'interrupted-run'),
+          ],
+        ],
+      })
+
+      const initialChunks = await collectChunks(
+        chat({
+          adapter: initialAdapter.adapter,
+          messages: [{ role: 'user', content: 'Run both' }],
+          tools,
+          threadId: 'thread-1',
+          runId: 'interrupted-run',
+        }) as AsyncIterable<StreamChunk>,
+      )
+      const initialOutcome = expectSingleRunFinished(initialChunks).outcome
+      expect(initialOutcome?.type).toBe('interrupt')
+      if (initialOutcome?.type !== 'interrupt') {
+        throw new Error('Expected an interrupt outcome')
+      }
+      const initialInterruptIds = initialOutcome.interrupts.map(
+        (interrupt) => interrupt.id,
+      )
+      expect(initialInterruptIds).toEqual([
+        'approval_call_approval',
+        'client_tool_call_client',
+      ])
+
+      const continuationAdapter = createMockAdapter({
+        iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+      })
+      const continuationChunks = await collectChunks(
+        chat({
+          adapter: continuationAdapter.adapter,
+          messages: history,
+          tools,
+          threadId: 'thread-1',
+          runId: 'continuation-run',
+          parentRunId: 'interrupted-run',
+          resume: [
+            {
+              interruptId: 'approval_call_approval',
+              status: 'resolved',
+              payload: 'invalid-decision',
+            },
+            {
+              interruptId: 'client_tool_call_client',
+              status: 'resolved',
+              payload: { result: 'done' },
+            },
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      )
+
+      expect(approvedExecute).not.toHaveBeenCalled()
+      expect(continuationAdapter.calls).toHaveLength(0)
+      expect(continuationChunks).toEqual([
+        expect.objectContaining({
+          type: EventType.RUN_ERROR,
+          'tanstack:interruptErrors': expect.arrayContaining([
+            expect.objectContaining({
+              scope: 'batch',
+              code: 'item-validation-failed',
+              interruptIds: initialInterruptIds,
+            }),
+          ]),
+        }),
+      ])
+    })
+
     it('should end with an interrupt outcome for client tools with needsApproval', async () => {
       const { adapter } = createMockAdapter({
         iterations: [
@@ -771,6 +1817,7 @@ describe('chat()', () => {
         adapter,
         messages: [{ role: 'user', content: 'Do something' }],
         tools: [clientTool('clientDanger', { needsApproval: true })],
+        middleware: [interruptPersistenceMiddleware()],
       })
 
       const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
@@ -784,7 +1831,7 @@ describe('chat()', () => {
           interrupts: [
             {
               id: 'approval_call_1',
-              reason: 'approval_required',
+              reason: 'tool_call',
               toolCallId: 'call_1',
               metadata: {
                 kind: 'approval',
@@ -813,6 +1860,7 @@ describe('chat()', () => {
         adapter,
         messages: [{ role: 'user', content: 'Search for test' }],
         tools: [clientTool('clientSearch')],
+        middleware: [interruptPersistenceMiddleware()],
       })
 
       const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
@@ -826,7 +1874,7 @@ describe('chat()', () => {
           interrupts: [
             {
               id: 'client_tool_call_1',
-              reason: 'client_tool_input',
+              reason: 'tanstack:client_tool_execution',
               message: 'Client tool clientSearch is ready to run',
               toolCallId: 'call_1',
               metadata: {
@@ -973,7 +2021,7 @@ describe('chat()', () => {
       expect(calls).toHaveLength(1)
     })
 
-    it('should emit TOOL_CALL_START and TOOL_CALL_ARGS before TOOL_CALL_END for pending tool calls', async () => {
+    it('should emit only TOOL_CALL_RESULT for pending tool calls', async () => {
       const executeSpy = vi.fn().mockReturnValue({ temp: 72 })
 
       const { adapter } = createMockAdapter({
@@ -1014,42 +2062,14 @@ describe('chat()', () => {
       // Tool should have been executed
       expect(executeSpy).toHaveBeenCalledTimes(1)
 
-      // The continuation re-execution should emit the full chunk sequence:
-      // TOOL_CALL_START -> TOOL_CALL_ARGS -> TOOL_CALL_END
-      // Without the fix, only TOOL_CALL_END is emitted, causing the client
-      // to store the tool call with empty arguments {}.
-      const toolStartChunks = chunks.filter(
-        (c) =>
-          c.type === 'TOOL_CALL_START' && (c as any).toolCallId === 'call_1',
-      )
-      expect(toolStartChunks).toHaveLength(1)
-      // Both AG-UI spec field `toolCallName` and deprecated alias `toolName`
-      // must be set so consumers reading either get a valid name (issue #532).
-      expect((toolStartChunks[0] as any).toolCallName).toBe('getWeather')
-      expect((toolStartChunks[0] as any).toolName).toBe('getWeather')
-
-      const toolArgsChunks = chunks.filter(
-        (c) =>
-          c.type === 'TOOL_CALL_ARGS' && (c as any).toolCallId === 'call_1',
-      )
-      expect(toolArgsChunks).toHaveLength(1)
-      expect((toolArgsChunks[0] as any).delta).toBe('{"city":"NYC"}')
-      expect((toolArgsChunks[0] as any).args).toBe('{"city":"NYC"}')
-
-      const toolEndChunks = chunks.filter(
-        (c) => c.type === 'TOOL_CALL_END' && (c as any).toolCallId === 'call_1',
-      )
-      expect(toolEndChunks).toHaveLength(1)
-
-      // Verify ordering: START before ARGS before END
-      const startIdx = chunks.indexOf(toolStartChunks[0]!)
-      const argsIdx = chunks.indexOf(toolArgsChunks[0]!)
-      const endIdx = chunks.indexOf(toolEndChunks[0]!)
-      expect(startIdx).toBeLessThan(argsIdx)
-      expect(argsIdx).toBeLessThan(endIdx)
+      expect(
+        chunks
+          .filter((c) => 'toolCallId' in c && c.toolCallId === 'call_1')
+          .map((c) => c.type),
+      ).toEqual([EventType.TOOL_CALL_RESULT])
     })
 
-    it('should emit TOOL_CALL_START and TOOL_CALL_ARGS for each pending tool call in a batch', async () => {
+    it('should emit only TOOL_CALL_RESULT for each pending tool call in a batch', async () => {
       const weatherSpy = vi.fn().mockReturnValue({ temp: 72 })
       const timeSpy = vi.fn().mockReturnValue({ time: '3pm' })
 
@@ -1099,39 +2119,16 @@ describe('chat()', () => {
       expect(weatherSpy).toHaveBeenCalledTimes(1)
       expect(timeSpy).toHaveBeenCalledTimes(1)
 
-      // Each pending tool should get the full START -> ARGS -> END sequence
-      for (const { id, name, args } of [
-        { id: 'call_weather', name: 'getWeather', args: '{"city":"NYC"}' },
-        { id: 'call_time', name: 'getTime', args: '{"tz":"EST"}' },
-      ]) {
-        const starts = chunks.filter(
-          (c) => c.type === 'TOOL_CALL_START' && (c as any).toolCallId === id,
-        )
-        expect(starts).toHaveLength(1)
-        expect((starts[0] as any).toolCallName).toBe(name)
-        expect((starts[0] as any).toolName).toBe(name)
-
-        const argChunks = chunks.filter(
-          (c) => c.type === 'TOOL_CALL_ARGS' && (c as any).toolCallId === id,
-        )
-        expect(argChunks).toHaveLength(1)
-        expect((argChunks[0] as any).delta).toBe(args)
-
-        const ends = chunks.filter(
-          (c) => c.type === 'TOOL_CALL_END' && (c as any).toolCallId === id,
-        )
-        expect(ends).toHaveLength(1)
-
-        // Verify ordering
-        const startIdx = chunks.indexOf(starts[0]!)
-        const argsIdx = chunks.indexOf(argChunks[0]!)
-        const endIdx = chunks.indexOf(ends[0]!)
-        expect(startIdx).toBeLessThan(argsIdx)
-        expect(argsIdx).toBeLessThan(endIdx)
+      for (const id of ['call_weather', 'call_time']) {
+        expect(
+          chunks
+            .filter((c) => 'toolCallId' in c && c.toolCallId === id)
+            .map((c) => c.type),
+        ).toEqual([EventType.TOOL_CALL_RESULT])
       }
     })
 
-    it('should emit TOOL_CALL_START and TOOL_CALL_ARGS for the server tool in a mixed pending batch', async () => {
+    it('should emit only TOOL_CALL_RESULT for the server tool in a mixed pending batch', async () => {
       const weatherSpy = vi.fn().mockReturnValue({ temp: 72 })
 
       const { adapter } = createMockAdapter({ iterations: [] })
@@ -1165,6 +2162,7 @@ describe('chat()', () => {
           serverTool('getWeather', weatherSpy),
           clientTool('showNotification'),
         ],
+        middleware: [interruptPersistenceMiddleware()],
       })
 
       const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
@@ -1172,36 +2170,11 @@ describe('chat()', () => {
       // Server tool should have executed
       expect(weatherSpy).toHaveBeenCalledTimes(1)
 
-      // The executed server tool should get the full START -> ARGS -> END
-      const starts = chunks.filter(
-        (c) =>
-          c.type === 'TOOL_CALL_START' &&
-          (c as any).toolCallId === 'call_server',
-      )
-      expect(starts).toHaveLength(1)
-      expect((starts[0] as any).toolCallName).toBe('getWeather')
-      expect((starts[0] as any).toolName).toBe('getWeather')
-
-      const argChunks = chunks.filter(
-        (c) =>
-          c.type === 'TOOL_CALL_ARGS' &&
-          (c as any).toolCallId === 'call_server',
-      )
-      expect(argChunks).toHaveLength(1)
-      expect((argChunks[0] as any).delta).toBe('{"city":"NYC"}')
-
-      const ends = chunks.filter(
-        (c) =>
-          c.type === 'TOOL_CALL_END' && (c as any).toolCallId === 'call_server',
-      )
-      expect(ends).toHaveLength(1)
-
-      // Verify ordering
-      const startIdx = chunks.indexOf(starts[0]!)
-      const argsIdx = chunks.indexOf(argChunks[0]!)
-      const endIdx = chunks.indexOf(ends[0]!)
-      expect(startIdx).toBeLessThan(argsIdx)
-      expect(argsIdx).toBeLessThan(endIdx)
+      expect(
+        chunks
+          .filter((c) => 'toolCallId' in c && c.toolCallId === 'call_server')
+          .map((c) => c.type),
+      ).toEqual([EventType.TOOL_CALL_RESULT])
     })
 
     it('should replace pendingExecution placeholder with the real tool result and supply both toolCallName/toolName (issue #532)', async () => {
@@ -1261,19 +2234,11 @@ describe('chat()', () => {
       // it as pendingExecution.
       expect(executeSpy).toHaveBeenCalledTimes(1)
 
-      // Synthesized TOOL_CALL_START must include both `toolCallName` (AG-UI
-      // spec) and `toolName` (deprecated alias). Without `toolCallName` the
-      // chat-client's StreamProcessor would create a tool-call part with
-      // name=undefined and the next outbound request would fail at Anthropic
-      // with `tool_use.name: String should have at least 1 character`.
-      const toolStart = chunks.find(
-        (c) =>
-          c.type === 'TOOL_CALL_START' &&
-          (c as any).toolCallId === 'call_approval',
-      )
-      expect(toolStart).toBeDefined()
-      expect((toolStart as any).toolCallName).toBe('approvedTool')
-      expect((toolStart as any).toolName).toBe('approvedTool')
+      expect(
+        chunks
+          .filter((c) => 'toolCallId' in c && c.toolCallId === 'call_approval')
+          .map((c) => c.type),
+      ).toEqual([EventType.TOOL_CALL_RESULT])
 
       // The follow-up adapter call (after the tool ran) must see the real
       // tool result, not the placeholder. With the placeholder still in the
diff --git a/packages/ai/tests/interrupts-types.test-d.ts b/packages/ai/tests/interrupts-types.test-d.ts
new file mode 100644
index 000000000..99b501e2f
--- /dev/null
+++ b/packages/ai/tests/interrupts-types.test-d.ts
@@ -0,0 +1,74 @@
+import { expectTypeOf } from 'vitest'
+import { z } from 'zod'
+import {
+  toolDefinition,
+  type ApprovalCapabilityOf,
+  type ApprovalSchemaOf,
+  type InferToolInput,
+  type InferToolOutput,
+  type InputSchemaOf,
+  type NoSchema,
+  type RunErrorEvent,
+  type ChatMiddlewareContext,
+  type ChatResumeToolState,
+} from '../src'
+import type { InterruptSubmissionError } from '../src/interrupts'
+
+const transfer = toolDefinition({
+  name: 'transfer',
+  description: 'Transfer funds',
+  needsApproval: true,
+  inputSchema: z.object({ cents: z.number() }),
+  outputSchema: z.object({ receipt: z.string() }),
+  approvalSchema: {
+    approve: z.object({ note: z.string() }),
+    reject: z.object({ reason: z.string() }),
+  },
+})
+
+expectTypeOf<InferToolInput<typeof transfer>>().toEqualTypeOf<{
+  cents: number
+}>()
+expectTypeOf<
+  InferToolOutput<ReturnType<typeof transfer.client>>
+>().toEqualTypeOf<{
+  receipt: string
+}>()
+expectTypeOf<
+  ApprovalCapabilityOf<ReturnType<typeof transfer.server>>
+>().toEqualTypeOf<true>()
+expectTypeOf<
+  ApprovalSchemaOf<ReturnType<typeof transfer.client>>
+>().toEqualTypeOf<typeof transfer.approvalSchema>()
+
+toolDefinition({
+  name: 'invalid',
+  description: 'Cannot declare an approval payload',
+  // @ts-expect-error approvalSchema requires needsApproval: true
+  approvalSchema: z.object({ note: z.string() }),
+})
+
+const noInputDefinition = toolDefinition({
+  name: 'noInput',
+  description: 'Approval without editable input',
+  needsApproval: true,
+})
+const noInputClient = noInputDefinition.client()
+const noInputServer = noInputDefinition.server(async () => ({ ok: true }))
+expectTypeOf(noInputClient.inputSchema).toEqualTypeOf<undefined>()
+expectTypeOf(noInputServer.inputSchema).toEqualTypeOf<undefined>()
+expectTypeOf<
+  InputSchemaOf<typeof noInputDefinition>
+>().toEqualTypeOf<NoSchema>()
+expectTypeOf<InputSchemaOf<typeof noInputClient>>().toEqualTypeOf<NoSchema>()
+expectTypeOf<InputSchemaOf<typeof noInputServer>>().toEqualTypeOf<NoSchema>()
+
+expectTypeOf<RunErrorEvent['tanstack:interruptErrors']>().toEqualTypeOf<
+  readonly InterruptSubmissionError[] | undefined
+>()
+expectTypeOf<ChatMiddlewareContext['parentRunId']>().toEqualTypeOf<
+  string | undefined
+>()
+expectTypeOf<ChatResumeToolState['cancelledToolCallIds']>().toEqualTypeOf<
+  ReadonlySet<string> | undefined
+>()
diff --git a/packages/ai/tests/interrupts.test.ts b/packages/ai/tests/interrupts.test.ts
index 1c99e0ab5..a809c587b 100644
--- a/packages/ai/tests/interrupts.test.ts
+++ b/packages/ai/tests/interrupts.test.ts
@@ -1,5 +1,24 @@
 import { describe, expect, expectTypeOf, it } from 'vitest'
 import { EventType } from '@ag-ui/core'
+import {
+  JsonSchemaCompilationError,
+  compileJsonSchema202012,
+} from '../src/activities/chat/tools/json-schema-validator'
+import {
+  hashSchemaInput,
+  normalizeApprovalSchema,
+} from '../src/activities/chat/tools/approval-schema'
+import {
+  canonicalInterruptJson,
+  cloneAndDeepFreezeJson,
+  digestInterruptJson,
+} from '../src/interrupt-serialization'
+import {
+  InterruptPersistenceCapability,
+  canonicalizeInterruptResolutions,
+  type InterruptRecoveryStateV1,
+  type InterruptSubmissionError,
+} from '../src/interrupts'
 import type {
   Interrupt,
   RunAgentResumeItem,
@@ -81,3 +100,218 @@ describe('AG-UI interrupt protocol types', () => {
     >()
   })
 })
+
+describe('Draft 2020-12 interrupt schema validation', () => {
+  it('normalizes every Draft 2020-12 issue without mutating input', () => {
+    const validate = compileJsonSchema202012({
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      properties: {
+        'a/b': { type: 'string', minLength: 3 },
+        email: { type: 'string', format: 'email' },
+      },
+      required: ['a/b', 'email'],
+      additionalProperties: false,
+    })
+    const input = { 'a/b': 'x', email: 'bad', extra: true }
+
+    expect(validate(input)).toEqual([
+      expect.objectContaining({
+        keyword: 'additionalProperties',
+        path: ['extra'],
+      }),
+      expect.objectContaining({ path: ['a/b'] }),
+      expect.objectContaining({ path: ['email'] }),
+    ])
+    expect(input).toEqual({ 'a/b': 'x', email: 'bad', extra: true })
+  })
+
+  it('accepts #, local $defs, and repeated acyclic object identities', () => {
+    const sharedProperty = { type: 'string', minLength: 2 } as const
+    const sharedObject = {
+      type: 'object',
+      properties: { label: sharedProperty },
+      required: ['label'],
+      additionalProperties: false,
+    } as const
+    const root = {
+      type: 'object',
+      $defs: { entry: sharedObject },
+      properties: {
+        selfCopy: { $ref: '#' },
+        first: { $ref: '#/$defs/entry' },
+        second: sharedObject,
+        third: sharedObject,
+      },
+      additionalProperties: false,
+    } as const
+    const validate = compileJsonSchema202012(root)
+
+    expect(
+      validate({
+        first: { label: 'ok' },
+        second: { label: 'yes' },
+        third: { label: 'no' },
+      }),
+    ).toEqual([])
+  })
+
+  it('rejects unresolved local references, true cycles, Date, and Map', () => {
+    expect(() => compileJsonSchema202012({ $ref: '#/$defs/missing' })).toThrow(
+      JsonSchemaCompilationError,
+    )
+
+    const cyclic: Record<string, unknown> = { type: 'object' }
+    cyclic['properties'] = { self: cyclic }
+    expect(() => compileJsonSchema202012(cyclic)).toThrow(/cycles/)
+    expect(() => compileJsonSchema202012(new Date())).toThrow(/plain JSON/)
+    expect(() => compileJsonSchema202012(new Map())).toThrow(/plain JSON/)
+  })
+
+  it('accepts canonical JSON primitives and rejects non-JSON values', () => {
+    const validate = compileJsonSchema202012({
+      type: 'array',
+      items: { type: ['string', 'number', 'boolean', 'null'] },
+    })
+    expect(validate(['text', 1, true, null])).toEqual([])
+    expect(() => compileJsonSchema202012({ const: undefined })).toThrow(
+      /JSON-compatible/,
+    )
+  })
+
+  it('rejects other dialects, remote references, and unknown formats', () => {
+    expect(() =>
+      compileJsonSchema202012({
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        type: 'string',
+      }),
+    ).toThrow(JsonSchemaCompilationError)
+    expect(() =>
+      compileJsonSchema202012({
+        $ref: 'https://example.com/schema.json',
+      }),
+    ).toThrow(/document-local/)
+    expect(() =>
+      compileJsonSchema202012({ type: 'string', format: 'private-id' }),
+    ).toThrow(JsonSchemaCompilationError)
+  })
+})
+
+describe('approval schema normalization and interrupt serialization', () => {
+  it('builds branch-aware approval envelopes and rejects malformed maps', () => {
+    const normalized = normalizeApprovalSchema({
+      approve: { type: 'object', required: ['note'] },
+    })
+    expect(normalized.responseSchema).toMatchObject({
+      oneOf: expect.any(Array),
+    })
+    expect(normalized.branches.reject).toBeNull()
+    expect(() => normalizeApprovalSchema({})).toThrow(/approve or reject/)
+    expect(() =>
+      normalizeApprovalSchema({
+        approve: { unsupported: Symbol('bad') },
+      }),
+    ).toThrow(/SchemaInput/)
+  })
+
+  it('normalizes shared and omitted payload branches with stable hashes', () => {
+    const shared = { type: 'string', minLength: 1 }
+    const left = normalizeApprovalSchema(shared, {
+      type: 'object',
+      properties: { value: { type: 'number' } },
+    })
+    const right = normalizeApprovalSchema(
+      { minLength: 1, type: 'string' },
+      {
+        properties: { value: { type: 'number' } },
+        type: 'object',
+      },
+    )
+    const omitted = normalizeApprovalSchema(undefined)
+
+    expect(left.branches.approve?.jsonSchema).toBe(shared)
+    expect(left.branches.reject?.jsonSchema).toBe(shared)
+    expect(left.responseSchemaHash).toBe(right.responseSchemaHash)
+    expect(left.approvalSchemaHash).toBe(right.approvalSchemaHash)
+    expect(omitted.branches).toEqual({ approve: null, reject: null })
+    expect(hashSchemaInput(undefined)).toMatch(/^sha256:[0-9a-f]{64}$/)
+  })
+
+  it('canonicalizes JSON without hashing functions and deeply freezes clones', () => {
+    const canonical = canonicalInterruptJson({ z: 1, a: { value: true } })
+    expect(canonical).toBe('{"a":{"value":true},"z":1}')
+    expect(digestInterruptJson(canonical)).toMatch(/^sha256:[0-9a-f]{64}$/)
+
+    const frozen = cloneAndDeepFreezeJson({ nested: { ok: true } })
+    expect(Object.isFrozen(frozen)).toBe(true)
+    expect(Object.isFrozen(frozen.nested)).toBe(true)
+    expect(() => canonicalInterruptJson({ handler: () => undefined })).toThrow(
+      /JSON-compatible/,
+    )
+
+    const cyclic: Record<string, unknown> = {}
+    cyclic['self'] = cyclic
+    expect(() => canonicalInterruptJson(cyclic)).toThrow(/cycle/)
+  })
+})
+
+describe('core interrupt correlation and persistence seam', () => {
+  it('correlates interrupt errors and recovery to the interrupted run', () => {
+    const recovery = {
+      schemaVersion: 1,
+      state: 'committed',
+      threadId: 'thread-1',
+      interruptedRunId: 'run-old',
+      generation: 2,
+      pendingInterrupts: [],
+      committed: {
+        fingerprint: 'sha256:abc',
+        resolutions: [],
+        continuationRunId: 'run-new',
+        committedAt: '2026-07-13T10:00:00.000Z',
+      },
+    } satisfies InterruptRecoveryStateV1
+    const error: InterruptSubmissionError = {
+      scope: 'batch',
+      code: 'conflict',
+      message: 'Another response batch won.',
+      source: 'server',
+      retryable: false,
+      interruptIds: ['interrupt-1'],
+      threadId: 'thread-1',
+      interruptedRunId: 'run-old',
+      generation: 2,
+    }
+
+    expect(recovery.committed.continuationRunId).toBe('run-new')
+    expect(error.interruptedRunId).toBe('run-old')
+    expect(InterruptPersistenceCapability.capabilityName).toBe(
+      'interrupt-persistence',
+    )
+  })
+
+  it('canonicalizes and deeply freezes response batches in core', () => {
+    const left = canonicalizeInterruptResolutions([
+      { interruptId: 'b', status: 'cancelled' },
+      {
+        interruptId: 'a',
+        status: 'resolved',
+        payload: { z: 1, a: 2 },
+      },
+    ])
+    const right = canonicalizeInterruptResolutions([
+      {
+        interruptId: 'a',
+        status: 'resolved',
+        payload: { a: 2, z: 1 },
+      },
+      { interruptId: 'b', status: 'cancelled' },
+    ])
+
+    expect(left.canonicalResolutions).toBe(right.canonicalResolutions)
+    expect(left.fingerprint).toMatch(/^sha256:[0-9a-f]{64}$/)
+    expect(left.fingerprint).toBe(right.fingerprint)
+    expect(Object.isFrozen(left.resolutions)).toBe(true)
+    expect(Object.isFrozen(left.resolutions[0])).toBe(true)
+  })
+})
diff --git a/packages/ai/tests/messages.test.ts b/packages/ai/tests/messages.test.ts
index d6f5fe4d9..238daa0cb 100644
--- a/packages/ai/tests/messages.test.ts
+++ b/packages/ai/tests/messages.test.ts
@@ -138,6 +138,46 @@ describe('convertMessagesToModelMessages — AG-UI dedup pre-pass', () => {
     // Metadata round-trips so the adapter can replay the server tool blocks.
     expect(assistant?.toolCalls?.[0]?.metadata).toMatchObject(metadata)
   })
+
+  it('preserves approval-requested tool calls as assistant toolCalls', () => {
+    const messages: Array<UIMessage> = [
+      {
+        id: 'assistant-approval',
+        role: 'assistant',
+        parts: [
+          {
+            type: 'tool-call',
+            id: 'call_1',
+            name: 'dangerousTool',
+            arguments: '{"action":"delete"}',
+            input: { action: 'delete' },
+            state: 'approval-requested',
+            approval: {
+              id: 'approval_call_1',
+              needsApproval: true,
+            },
+          },
+        ],
+      },
+    ]
+
+    expect(convertMessagesToModelMessages(messages)).toEqual([
+      {
+        role: 'assistant',
+        content: null,
+        toolCalls: [
+          {
+            id: 'call_1',
+            type: 'function',
+            function: {
+              name: 'dangerousTool',
+              arguments: '{"action":"delete"}',
+            },
+          },
+        ],
+      },
+    ])
+  })
 })
 
 describe('convertMessagesToModelMessages — MCP Apps ui-resource exclusion', () => {
diff --git a/packages/ai/tests/stream-processor.test.ts b/packages/ai/tests/stream-processor.test.ts
index d9bb3827b..af2500026 100644
--- a/packages/ai/tests/stream-processor.test.ts
+++ b/packages/ai/tests/stream-processor.test.ts
@@ -4,6 +4,11 @@ import {
   createReplayStream,
 } from '../src/activities/chat/stream/processor'
 import { chat } from '../src/activities/chat/index'
+import { defineChatMiddleware } from '../src/activities/chat/middleware/define'
+import {
+  InterruptPersistenceCapability,
+  provideInterruptPersistence,
+} from '../src/interrupts'
 import { EventType } from '../src/types'
 import {
   createMockAdapter,
@@ -23,11 +28,39 @@ import type {
   UIMessage,
 } from '../src/types'
 import type { Message as AGUIMessage } from '@ag-ui/core'
+import type { InterruptPersistenceGateway } from '../src/interrupts'
 
 // ============================================================================
 // Helpers
 // ============================================================================
 
+const testInterruptGateway: InterruptPersistenceGateway = {
+  openInterruptBatch: async (input) => ({
+    generation: 1,
+    descriptors: input.descriptors,
+  }),
+  commitInterruptResolutions: async (input) => ({
+    status: 'committed',
+    continuationRunId: input.continuationRunId,
+  }),
+  getInterruptRecoveryState: async (input) => ({
+    schemaVersion: 1,
+    state: 'missing',
+    threadId: input.threadId,
+    interruptedRunId: input.interruptedRunId,
+    generation: input.knownGeneration,
+    pendingInterrupts: [],
+  }),
+}
+
+const testInterruptPersistence = defineChatMiddleware({
+  name: 'test-interrupt-persistence',
+  provides: [InterruptPersistenceCapability],
+  setup(ctx) {
+    provideInterruptPersistence(ctx, testInterruptGateway)
+  },
+})
+
 /** Create a typed StreamChunk by event type. Narrows the return to the
  *  matching variant via `Extract`. */
 function chunk<T extends StreamChunk['type']>(
@@ -1209,7 +1242,7 @@ describe('StreamProcessor', () => {
           interrupts: [
             {
               id: 'approval-1',
-              reason: 'approval_required',
+              reason: 'tool_call',
               toolCallId: 'tc-1',
               metadata: {
                 kind: 'approval',
@@ -1252,7 +1285,7 @@ describe('StreamProcessor', () => {
           interrupts: [
             {
               id: 'client_tool_tc-1',
-              reason: 'client_tool_input',
+              reason: 'tanstack:client_tool_execution',
               toolCallId: 'tc-1',
               metadata: {
                 kind: 'client_tool',
@@ -1302,6 +1335,7 @@ describe('StreamProcessor', () => {
           serverTool('searchTools', () => ({ results: ['a', 'b'] })),
           clientTool('showNotification'),
         ],
+        middleware: [testInterruptPersistence],
       })
       const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
 
@@ -1314,7 +1348,7 @@ describe('StreamProcessor', () => {
         toolName: 'showNotification',
         input: { message: 'done' },
       })
-      expect(order).toEqual(['tool-call', 'stream-end'])
+      expect(order).toEqual(['tool-call'])
     })
 
     it('addToolApprovalResponse should approve a tool call', () => {
diff --git a/packages/ai/tests/tool-call-manager.test.ts b/packages/ai/tests/tool-call-manager.test.ts
index b9d644e4d..262b3c44a 100644
--- a/packages/ai/tests/tool-call-manager.test.ts
+++ b/packages/ai/tests/tool-call-manager.test.ts
@@ -830,6 +830,39 @@ describe('executeToolCalls', () => {
   })
 
   describe('mixed approval batch gating', () => {
+    it('should batch plain client execution requests with pending approvals', async () => {
+      vi.mocked(serverToolWithApproval.execute!).mockClear()
+      const plainClientTool: Tool = {
+        name: 'show_notification',
+        description: 'Show a notification in the client',
+        inputSchema: z.object({ message: z.string() }),
+      }
+
+      const toolCalls = [
+        makeToolCall('call_1', 'delete_record', '{"id":"rec_123"}'),
+        makeToolCall('call_2', 'show_notification', '{"message":"done"}'),
+      ]
+
+      const result = await drainExecuteToolCalls(
+        toolCalls,
+        [serverToolWithApproval, plainClientTool],
+        new Map(),
+        new Map(),
+      )
+
+      expect(result.needsApproval).toHaveLength(1)
+      expect(result.needsApproval[0]?.toolCallId).toBe('call_1')
+      expect(result.needsClientExecution).toEqual([
+        {
+          toolCallId: 'call_2',
+          toolName: 'show_notification',
+          input: { message: 'done' },
+        },
+      ])
+      expect(result.results).toHaveLength(0)
+      expect(serverToolWithApproval.execute).not.toHaveBeenCalled()
+    })
+
     it('should not execute non-approval tools when the same batch contains unapproved tools', async () => {
       // Non-approval tools should wait until all approvals in the batch are resolved,
       // otherwise side effects happen before the user has a chance to deny.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9e775c9f1..0eeed9b50 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1320,6 +1320,9 @@ importers:
       '@ag-ui/core':
         specifier: ^0.0.57
         version: 0.0.57
+      '@noble/hashes':
+        specifier: ^2.0.1
+        version: 2.2.0
       '@standard-schema/spec':
         specifier: ^1.1.0
         version: 1.1.0
@@ -1329,6 +1332,12 @@ importers:
       '@tanstack/ai-utils':
         specifier: workspace:*
         version: link:../ai-utils
+      ajv:
+        specifier: ^8.20.0
+        version: 8.20.0
+      ajv-formats:
+        specifier: ^3.0.1
+        version: 3.0.1(ajv@8.20.0)
       partial-json:
         specifier: ^0.1.7
         version: 0.1.7
@@ -5845,6 +5854,10 @@ packages:
     resolution: {integrity: sha512-P06o9TpxrJbiRbHQkiwy/rUrlXRupc+Z8KT4MiJfmcdWxvIdzjCaJOdnNkcOTs6DMyzIOefG5tvk/HLdtjqr0g==}
     engines: {node: '>= 10'}
 
+  '@noble/hashes@2.2.0':
+    resolution: {integrity: sha512-IYqDGiTXab6FniAgnSdZwgWbomxpy9FtYvLKs7wCUs2a8RkITG+DFGO1DM9cr+E3/RgADRpFjrKVaJ1z6sjtEg==}
+    engines: {node: '>= 20.19.0'}
+
   '@nodelib/fs.scandir@2.1.5':
     resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==}
     engines: {node: '>= 8'}
@@ -18851,7 +18864,7 @@ snapshots:
 
   '@eslint/eslintrc@3.3.3':
     dependencies:
-      ajv: 6.12.6
+      ajv: 6.15.0
       debug: 4.4.3
       espree: 10.4.0
       globals: 14.0.0
@@ -19932,6 +19945,8 @@ snapshots:
       '@ngrok/ngrok-win32-ia32-msvc': 1.7.0
       '@ngrok/ngrok-win32-x64-msvc': 1.7.0
 
+  '@noble/hashes@2.2.0': {}
+
   '@nodelib/fs.scandir@2.1.5':
     dependencies:
       '@nodelib/fs.stat': 2.0.5
diff --git a/testing/e2e/src/lib/interrupts-v2-fixture.ts b/testing/e2e/src/lib/interrupts-v2-fixture.ts
new file mode 100644
index 000000000..b786a2ad7
--- /dev/null
+++ b/testing/e2e/src/lib/interrupts-v2-fixture.ts
@@ -0,0 +1,440 @@
+import {
+  EventType,
+  canonicalInterruptJson,
+  convertSchemaToJsonSchema,
+  digestInterruptJson,
+  hashSchemaInput,
+  normalizeApprovalSchema,
+  toolDefinition,
+} from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { z } from 'zod'
+import type {
+  AnyTextAdapter,
+  Interrupt,
+  InterruptBinding,
+  ModelMessage,
+  RunAgentResumeItem,
+  StreamChunk,
+} from '@tanstack/ai'
+
+const editableInputSchema = z.object({ action: z.string().min(1) })
+const sharedApprovalSchema = z.object({ note: z.string().optional() })
+const branchApprovalSchema = {
+  approve: z.object({ note: z.string() }),
+  reject: z.object({ reason: z.string() }),
+}
+const toolOutputSchema = z.object({ ok: z.boolean() })
+const clientToolOutputSchema = z.object({ browserValue: z.string() })
+
+const editableActionDefinition = toolDefinition({
+  name: 'editable_action',
+  description: 'Run an editable action after approval.',
+  inputSchema: editableInputSchema,
+  outputSchema: toolOutputSchema,
+  needsApproval: true,
+  approvalSchema: sharedApprovalSchema,
+})
+
+const branchActionDefinition = toolDefinition({
+  name: 'branch_action',
+  description: 'Run an action with branch-specific approval payloads.',
+  inputSchema: z.object({ action: z.string() }),
+  outputSchema: toolOutputSchema,
+  needsApproval: true,
+  approvalSchema: branchApprovalSchema,
+})
+
+const payloadlessActionDefinition = toolDefinition({
+  name: 'payloadless_action',
+  description: 'Run an action with a payloadless approval decision.',
+  outputSchema: toolOutputSchema,
+  needsApproval: true,
+})
+
+const browserActionDefinition = toolDefinition({
+  name: 'browser_action',
+  description: 'Resolve an action in the browser.',
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: clientToolOutputSchema,
+})
+
+export const interruptFixtureServerTools = [
+  editableActionDefinition.server(() => Promise.resolve({ ok: true })),
+  branchActionDefinition.server(() => Promise.resolve({ ok: true })),
+  payloadlessActionDefinition.server(() => Promise.resolve({ ok: true })),
+  browserActionDefinition,
+] as const
+
+export const interruptFixtureTools = [
+  editableActionDefinition.client(),
+  branchActionDefinition.client(),
+  payloadlessActionDefinition.client(),
+  browserActionDefinition.client(() =>
+    Promise.resolve({ browserValue: 'done' }),
+  ),
+] as const
+
+const genericResponseSchema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    answer: { type: 'string', minLength: 2 },
+  },
+  required: ['answer'],
+  additionalProperties: false,
+} as const
+
+const bindingKey = 'tanstack:interruptBinding'
+
+function approvalInterrupt(
+  interruptId: string,
+  tool:
+    | typeof editableActionDefinition
+    | typeof branchActionDefinition
+    | typeof payloadlessActionDefinition,
+  originalArgs: unknown,
+  interruptedRunId: string,
+  generation: number,
+): Interrupt {
+  const normalized = normalizeApprovalSchema(
+    tool.approvalSchema,
+    tool.inputSchema,
+  )
+  const binding = {
+    kind: 'tool-approval',
+    interruptId,
+    interruptedRunId,
+    generation,
+    toolName: tool.name,
+    toolCallId: `tool-call-${interruptId}`,
+    originalArgs,
+    inputSchemaHash: hashSchemaInput(tool.inputSchema),
+    approvalSchemaHash: normalized.approvalSchemaHash,
+    responseSchemaHash: normalized.responseSchemaHash,
+  } satisfies InterruptBinding
+
+  return {
+    id: interruptId,
+    reason: 'tool_call',
+    message: `Approval required for ${tool.name}`,
+    toolCallId: binding.toolCallId,
+    responseSchema: normalized.responseSchema,
+    metadata: {
+      kind: 'approval',
+      toolName: tool.name,
+      input: originalArgs,
+      [bindingKey]: binding,
+    },
+  }
+}
+
+function clientToolInterrupt(
+  interruptedRunId: string,
+  generation: number,
+): Interrupt {
+  const responseSchema =
+    convertSchemaToJsonSchema(browserActionDefinition.outputSchema) ?? {}
+  const binding = {
+    kind: 'client-tool-execution',
+    interruptId: 'client-tool-1',
+    interruptedRunId,
+    generation,
+    toolName: browserActionDefinition.name,
+    toolCallId: 'tool-call-client-tool-1',
+    outputSchemaHash: hashSchemaInput(browserActionDefinition.outputSchema),
+    responseSchemaHash: digestInterruptJson(
+      canonicalInterruptJson(responseSchema),
+    ),
+  } satisfies InterruptBinding
+
+  return {
+    id: binding.interruptId,
+    reason: 'tanstack:client_tool_execution',
+    message: 'Browser action is ready to run.',
+    toolCallId: binding.toolCallId,
+    responseSchema,
+    metadata: {
+      kind: 'client_tool',
+      toolName: binding.toolName,
+      input: { value: 'fixture' },
+      [bindingKey]: binding,
+    },
+  }
+}
+
+function genericInterrupt(
+  interruptedRunId: string,
+  generation: number,
+): Interrupt {
+  const binding = {
+    kind: 'generic',
+    interruptId: 'question-1',
+    interruptedRunId,
+    generation,
+    responseSchemaHash: digestInterruptJson(
+      canonicalInterruptJson(genericResponseSchema),
+    ),
+  } satisfies InterruptBinding
+  return {
+    id: binding.interruptId,
+    reason: 'fixture_question',
+    message: 'Answer the fixture question.',
+    responseSchema: genericResponseSchema,
+    metadata: {
+      kind: 'generic',
+      [bindingKey]: binding,
+    },
+  }
+}
+
+function scenarioInterrupts(
+  scenario: string,
+  interruptedRunId: string,
+  generation: number,
+): ReadonlyArray<Interrupt> {
+  const editable = () =>
+    approvalInterrupt(
+      'approval-1',
+      editableActionDefinition,
+      {
+        action: 'original-action',
+      },
+      interruptedRunId,
+      generation,
+    )
+  switch (scenario) {
+    case 'singleton-approval':
+    case 'commit-then-truncate':
+    case 'two-tab-conflict':
+      return [editable()]
+    case 'three-tool-approvals':
+      return [
+        editable(),
+        approvalInterrupt(
+          'approval-2',
+          branchActionDefinition,
+          {
+            action: 'branch-action',
+          },
+          interruptedRunId,
+          generation,
+        ),
+        approvalInterrupt(
+          'approval-3',
+          payloadlessActionDefinition,
+          {},
+          interruptedRunId,
+          generation,
+        ),
+      ]
+    case 'heterogeneous-callback':
+      return [
+        editable(),
+        approvalInterrupt(
+          'approval-2',
+          branchActionDefinition,
+          {
+            action: 'branch-action',
+          },
+          interruptedRunId,
+          generation,
+        ),
+        genericInterrupt(interruptedRunId, generation),
+      ]
+    case 'generic-validation':
+      return [genericInterrupt(interruptedRunId, generation)]
+    case 'two-invalid':
+    case 'partial-draft-reload':
+      return [editable(), genericInterrupt(interruptedRunId, generation)]
+    case 'client-tool-and-approval':
+      return [clientToolInterrupt(interruptedRunId, generation), editable()]
+    default:
+      return [editable()]
+  }
+}
+
+export interface InterruptFixture {
+  persistence: ReturnType<typeof memoryPersistence>
+  continuationCount: number
+  continuationRunIds: Array<string>
+  continuationChunks: Map<string, ReadonlyArray<StreamChunk>>
+  decisions: Array<string>
+  edits: Record<string, unknown>
+  auditHistory: Array<string>
+  resultEventNames: Array<string>
+  storedHistory: Array<string>
+  truncateCommittedResponseOnce: boolean
+  truncatedResponses: number
+  replayCount: number
+  joinedContinuationRunId?: string
+}
+
+const fixtures = new Map<string, InterruptFixture>()
+
+export function getInterruptFixture(testId: string): InterruptFixture {
+  const existing = fixtures.get(testId)
+  if (existing) return existing
+  const created: InterruptFixture = {
+    persistence: memoryPersistence(),
+    continuationCount: 0,
+    continuationRunIds: [],
+    continuationChunks: new Map(),
+    decisions: [],
+    edits: {},
+    auditHistory: [],
+    resultEventNames: [],
+    storedHistory: [],
+    truncateCommittedResponseOnce: true,
+    truncatedResponses: 0,
+    replayCount: 0,
+  }
+  fixtures.set(testId, created)
+  return created
+}
+
+export function createInterruptFixtureAdapter(
+  scenario: string,
+  resuming: boolean,
+): AnyTextAdapter {
+  return {
+    kind: 'text',
+    name: 'interrupts-v2-fixture',
+    model: 'interrupts-v2-fixture',
+    '~types': {
+      providerOptions: {},
+      inputModalities: ['text'],
+      messageMetadataByModality: {},
+      toolCapabilities: [],
+      toolCallMetadata: undefined,
+      systemPromptMetadata: undefined,
+    },
+    async *chatStream(options): AsyncGenerator<StreamChunk> {
+      await Promise.resolve()
+      const runId = options.runId ?? crypto.randomUUID()
+      const threadId = options.threadId ?? `thread-${runId}`
+      const model = 'interrupts-v2-fixture'
+      yield {
+        type: EventType.RUN_STARTED,
+        runId,
+        threadId,
+        model,
+        timestamp: Date.now(),
+      }
+
+      if (!resuming) {
+        if (scenario === 'core-mixed-client-approval') {
+          yield {
+            type: EventType.TOOL_CALL_START,
+            toolCallId: 'core-approval-call',
+            toolCallName: editableActionDefinition.name,
+            toolName: editableActionDefinition.name,
+            model,
+            timestamp: Date.now(),
+          }
+          yield {
+            type: EventType.TOOL_CALL_ARGS,
+            toolCallId: 'core-approval-call',
+            delta: JSON.stringify({ action: 'original-action' }),
+            model,
+            timestamp: Date.now(),
+          }
+          yield {
+            type: EventType.TOOL_CALL_START,
+            toolCallId: 'core-client-call',
+            toolCallName: browserActionDefinition.name,
+            toolName: browserActionDefinition.name,
+            model,
+            timestamp: Date.now(),
+          }
+          yield {
+            type: EventType.TOOL_CALL_ARGS,
+            toolCallId: 'core-client-call',
+            delta: JSON.stringify({ value: 'fixture' }),
+            model,
+            timestamp: Date.now(),
+          }
+          yield {
+            type: EventType.RUN_FINISHED,
+            runId,
+            threadId,
+            model,
+            finishReason: 'tool_calls',
+            timestamp: Date.now(),
+          }
+          return
+        }
+
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId,
+          threadId,
+          model,
+          finishReason: 'stop',
+          outcome: {
+            type: 'interrupt',
+            interrupts: [...scenarioInterrupts(scenario, runId, 1)],
+          },
+          timestamp: Date.now(),
+        }
+        return
+      }
+
+      yield {
+        type: EventType.RUN_FINISHED,
+        runId,
+        threadId,
+        model,
+        finishReason: 'stop',
+        outcome: { type: 'success' },
+        timestamp: Date.now(),
+      }
+    },
+    structuredOutput: () => Promise.resolve({ data: {}, rawText: '{}' }),
+  }
+}
+
+export function fixtureResumeMessages(
+  scenario: string,
+): Array<ModelMessage> | undefined {
+  if (scenario !== 'three-tool-approvals') return undefined
+  return [
+    {
+      role: 'assistant',
+      content: '',
+      toolCalls: [
+        {
+          id: 'tool-call-approval-1',
+          type: 'function',
+          function: {
+            name: editableActionDefinition.name,
+            arguments: JSON.stringify({ action: 'original-action' }),
+          },
+        },
+        {
+          id: 'tool-call-approval-2',
+          type: 'function',
+          function: {
+            name: branchActionDefinition.name,
+            arguments: JSON.stringify({ action: 'branch-action' }),
+          },
+        },
+      ],
+    },
+  ]
+}
+
+export function responseDecision(item: RunAgentResumeItem): string {
+  if (item.status === 'cancelled') return 'cancel'
+  const payload = item.payload
+  if (payload && typeof payload === 'object' && 'approved' in payload) {
+    return payload.approved === true ? 'approve' : 'deny'
+  }
+  if (
+    item.interruptId.startsWith('client-tool') ||
+    item.interruptId.startsWith('client_tool_')
+  ) {
+    return 'client-tool'
+  }
+  return 'generic'
+}
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index 8abc6f917..03d49d81d 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -12,6 +12,7 @@ import { Route as rootRouteImport } from './routes/__root'
 import { Route as ToolsTestRouteImport } from './routes/tools-test'
 import { Route as MiddlewareTestRouteImport } from './routes/middleware-test'
 import { Route as MarkdownCjkRouteImport } from './routes/markdown-cjk'
+import { Route as InterruptsV2RouteImport } from './routes/interrupts-v2'
 import { Route as DevtoolsToolsRouteImport } from './routes/devtools-tools'
 import { Route as DevtoolsStructuredRouteImport } from './routes/devtools-structured'
 import { Route as DevtoolsRouteBRouteImport } from './routes/devtools-route-b'
@@ -44,6 +45,7 @@ import { Route as ApiMcpAppsServerRouteImport } from './routes/api.mcp-apps-serv
 import { Route as ApiMcpAppsChatRouteImport } from './routes/api.mcp-apps-chat'
 import { Route as ApiMcpAppsCallRouteImport } from './routes/api.mcp-apps-call'
 import { Route as ApiLazyToolsWireRouteImport } from './routes/api.lazy-tools-wire'
+import { Route as ApiInterruptsV2RouteImport } from './routes/api.interrupts-v2'
 import { Route as ApiImageRouteImport } from './routes/api.image'
 import { Route as ApiDurableDeliveryRouteImport } from './routes/api.durable-delivery'
 import { Route as ApiChatRouteImport } from './routes/api.chat'
@@ -56,6 +58,7 @@ import { Route as ProviderFeatureRouteImport } from './routes/$provider/$feature
 import { Route as ApiVideoStreamRouteImport } from './routes/api.video.stream'
 import { Route as ApiTtsStreamRouteImport } from './routes/api.tts.stream'
 import { Route as ApiTranscriptionStreamRouteImport } from './routes/api.transcription.stream'
+import { Route as ApiInterruptsV2RecoveryRouteImport } from './routes/api.interrupts-v2.recovery'
 import { Route as ApiImageStreamRouteImport } from './routes/api.image.stream'
 import { Route as ApiAudioStreamRouteImport } from './routes/api.audio.stream'
 
@@ -74,6 +77,11 @@ const MarkdownCjkRoute = MarkdownCjkRouteImport.update({
   path: '/markdown-cjk',
   getParentRoute: () => rootRouteImport,
 } as any)
+const InterruptsV2Route = InterruptsV2RouteImport.update({
+  id: '/interrupts-v2',
+  path: '/interrupts-v2',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const DevtoolsToolsRoute = DevtoolsToolsRouteImport.update({
   id: '/devtools-tools',
   path: '/devtools-tools',
@@ -238,6 +246,11 @@ const ApiLazyToolsWireRoute = ApiLazyToolsWireRouteImport.update({
   path: '/api/lazy-tools-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiInterruptsV2Route = ApiInterruptsV2RouteImport.update({
+  id: '/api/interrupts-v2',
+  path: '/api/interrupts-v2',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiImageRoute = ApiImageRouteImport.update({
   id: '/api/image',
   path: '/api/image',
@@ -299,6 +312,11 @@ const ApiTranscriptionStreamRoute = ApiTranscriptionStreamRouteImport.update({
   path: '/stream',
   getParentRoute: () => ApiTranscriptionRoute,
 } as any)
+const ApiInterruptsV2RecoveryRoute = ApiInterruptsV2RecoveryRouteImport.update({
+  id: '/recovery',
+  path: '/recovery',
+  getParentRoute: () => ApiInterruptsV2Route,
+} as any)
 const ApiImageStreamRoute = ApiImageStreamRouteImport.update({
   id: '/stream',
   path: '/stream',
@@ -319,6 +337,7 @@ export interface FileRoutesByFullPath {
   '/devtools-route-b': typeof DevtoolsRouteBRoute
   '/devtools-structured': typeof DevtoolsStructuredRoute
   '/devtools-tools': typeof DevtoolsToolsRoute
+  '/interrupts-v2': typeof InterruptsV2Route
   '/markdown-cjk': typeof MarkdownCjkRoute
   '/middleware-test': typeof MiddlewareTestRoute
   '/tools-test': typeof ToolsTestRoute
@@ -331,6 +350,7 @@ export interface FileRoutesByFullPath {
   '/api/chat': typeof ApiChatRoute
   '/api/durable-delivery': typeof ApiDurableDeliveryRoute
   '/api/image': typeof ApiImageRouteWithChildren
+  '/api/interrupts-v2': typeof ApiInterruptsV2RouteWithChildren
   '/api/lazy-tools-wire': typeof ApiLazyToolsWireRoute
   '/api/mcp-apps-call': typeof ApiMcpAppsCallRoute
   '/api/mcp-apps-chat': typeof ApiMcpAppsChatRoute
@@ -357,6 +377,7 @@ export interface FileRoutesByFullPath {
   '/$provider/': typeof ProviderIndexRoute
   '/api/audio/stream': typeof ApiAudioStreamRoute
   '/api/image/stream': typeof ApiImageStreamRoute
+  '/api/interrupts-v2/recovery': typeof ApiInterruptsV2RecoveryRoute
   '/api/transcription/stream': typeof ApiTranscriptionStreamRoute
   '/api/tts/stream': typeof ApiTtsStreamRoute
   '/api/video/stream': typeof ApiVideoStreamRoute
@@ -370,6 +391,7 @@ export interface FileRoutesByTo {
   '/devtools-route-b': typeof DevtoolsRouteBRoute
   '/devtools-structured': typeof DevtoolsStructuredRoute
   '/devtools-tools': typeof DevtoolsToolsRoute
+  '/interrupts-v2': typeof InterruptsV2Route
   '/markdown-cjk': typeof MarkdownCjkRoute
   '/middleware-test': typeof MiddlewareTestRoute
   '/tools-test': typeof ToolsTestRoute
@@ -382,6 +404,7 @@ export interface FileRoutesByTo {
   '/api/chat': typeof ApiChatRoute
   '/api/durable-delivery': typeof ApiDurableDeliveryRoute
   '/api/image': typeof ApiImageRouteWithChildren
+  '/api/interrupts-v2': typeof ApiInterruptsV2RouteWithChildren
   '/api/lazy-tools-wire': typeof ApiLazyToolsWireRoute
   '/api/mcp-apps-call': typeof ApiMcpAppsCallRoute
   '/api/mcp-apps-chat': typeof ApiMcpAppsChatRoute
@@ -408,6 +431,7 @@ export interface FileRoutesByTo {
   '/$provider': typeof ProviderIndexRoute
   '/api/audio/stream': typeof ApiAudioStreamRoute
   '/api/image/stream': typeof ApiImageStreamRoute
+  '/api/interrupts-v2/recovery': typeof ApiInterruptsV2RecoveryRoute
   '/api/transcription/stream': typeof ApiTranscriptionStreamRoute
   '/api/tts/stream': typeof ApiTtsStreamRoute
   '/api/video/stream': typeof ApiVideoStreamRoute
@@ -422,6 +446,7 @@ export interface FileRoutesById {
   '/devtools-route-b': typeof DevtoolsRouteBRoute
   '/devtools-structured': typeof DevtoolsStructuredRoute
   '/devtools-tools': typeof DevtoolsToolsRoute
+  '/interrupts-v2': typeof InterruptsV2Route
   '/markdown-cjk': typeof MarkdownCjkRoute
   '/middleware-test': typeof MiddlewareTestRoute
   '/tools-test': typeof ToolsTestRoute
@@ -434,6 +459,7 @@ export interface FileRoutesById {
   '/api/chat': typeof ApiChatRoute
   '/api/durable-delivery': typeof ApiDurableDeliveryRoute
   '/api/image': typeof ApiImageRouteWithChildren
+  '/api/interrupts-v2': typeof ApiInterruptsV2RouteWithChildren
   '/api/lazy-tools-wire': typeof ApiLazyToolsWireRoute
   '/api/mcp-apps-call': typeof ApiMcpAppsCallRoute
   '/api/mcp-apps-chat': typeof ApiMcpAppsChatRoute
@@ -460,6 +486,7 @@ export interface FileRoutesById {
   '/$provider/': typeof ProviderIndexRoute
   '/api/audio/stream': typeof ApiAudioStreamRoute
   '/api/image/stream': typeof ApiImageStreamRoute
+  '/api/interrupts-v2/recovery': typeof ApiInterruptsV2RecoveryRoute
   '/api/transcription/stream': typeof ApiTranscriptionStreamRoute
   '/api/tts/stream': typeof ApiTtsStreamRoute
   '/api/video/stream': typeof ApiVideoStreamRoute
@@ -475,6 +502,7 @@ export interface FileRouteTypes {
     | '/devtools-route-b'
     | '/devtools-structured'
     | '/devtools-tools'
+    | '/interrupts-v2'
     | '/markdown-cjk'
     | '/middleware-test'
     | '/tools-test'
@@ -487,6 +515,7 @@ export interface FileRouteTypes {
     | '/api/chat'
     | '/api/durable-delivery'
     | '/api/image'
+    | '/api/interrupts-v2'
     | '/api/lazy-tools-wire'
     | '/api/mcp-apps-call'
     | '/api/mcp-apps-chat'
@@ -513,6 +542,7 @@ export interface FileRouteTypes {
     | '/$provider/'
     | '/api/audio/stream'
     | '/api/image/stream'
+    | '/api/interrupts-v2/recovery'
     | '/api/transcription/stream'
     | '/api/tts/stream'
     | '/api/video/stream'
@@ -526,6 +556,7 @@ export interface FileRouteTypes {
     | '/devtools-route-b'
     | '/devtools-structured'
     | '/devtools-tools'
+    | '/interrupts-v2'
     | '/markdown-cjk'
     | '/middleware-test'
     | '/tools-test'
@@ -538,6 +569,7 @@ export interface FileRouteTypes {
     | '/api/chat'
     | '/api/durable-delivery'
     | '/api/image'
+    | '/api/interrupts-v2'
     | '/api/lazy-tools-wire'
     | '/api/mcp-apps-call'
     | '/api/mcp-apps-chat'
@@ -564,6 +596,7 @@ export interface FileRouteTypes {
     | '/$provider'
     | '/api/audio/stream'
     | '/api/image/stream'
+    | '/api/interrupts-v2/recovery'
     | '/api/transcription/stream'
     | '/api/tts/stream'
     | '/api/video/stream'
@@ -577,6 +610,7 @@ export interface FileRouteTypes {
     | '/devtools-route-b'
     | '/devtools-structured'
     | '/devtools-tools'
+    | '/interrupts-v2'
     | '/markdown-cjk'
     | '/middleware-test'
     | '/tools-test'
@@ -589,6 +623,7 @@ export interface FileRouteTypes {
     | '/api/chat'
     | '/api/durable-delivery'
     | '/api/image'
+    | '/api/interrupts-v2'
     | '/api/lazy-tools-wire'
     | '/api/mcp-apps-call'
     | '/api/mcp-apps-chat'
@@ -615,6 +650,7 @@ export interface FileRouteTypes {
     | '/$provider/'
     | '/api/audio/stream'
     | '/api/image/stream'
+    | '/api/interrupts-v2/recovery'
     | '/api/transcription/stream'
     | '/api/tts/stream'
     | '/api/video/stream'
@@ -629,6 +665,7 @@ export interface RootRouteChildren {
   DevtoolsRouteBRoute: typeof DevtoolsRouteBRoute
   DevtoolsStructuredRoute: typeof DevtoolsStructuredRoute
   DevtoolsToolsRoute: typeof DevtoolsToolsRoute
+  InterruptsV2Route: typeof InterruptsV2Route
   MarkdownCjkRoute: typeof MarkdownCjkRoute
   MiddlewareTestRoute: typeof MiddlewareTestRoute
   ToolsTestRoute: typeof ToolsTestRoute
@@ -641,6 +678,7 @@ export interface RootRouteChildren {
   ApiChatRoute: typeof ApiChatRoute
   ApiDurableDeliveryRoute: typeof ApiDurableDeliveryRoute
   ApiImageRoute: typeof ApiImageRouteWithChildren
+  ApiInterruptsV2Route: typeof ApiInterruptsV2RouteWithChildren
   ApiLazyToolsWireRoute: typeof ApiLazyToolsWireRoute
   ApiMcpAppsCallRoute: typeof ApiMcpAppsCallRoute
   ApiMcpAppsChatRoute: typeof ApiMcpAppsChatRoute
@@ -690,6 +728,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof MarkdownCjkRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/interrupts-v2': {
+      id: '/interrupts-v2'
+      path: '/interrupts-v2'
+      fullPath: '/interrupts-v2'
+      preLoaderRoute: typeof InterruptsV2RouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/devtools-tools': {
       id: '/devtools-tools'
       path: '/devtools-tools'
@@ -914,6 +959,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiLazyToolsWireRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/interrupts-v2': {
+      id: '/api/interrupts-v2'
+      path: '/api/interrupts-v2'
+      fullPath: '/api/interrupts-v2'
+      preLoaderRoute: typeof ApiInterruptsV2RouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/image': {
       id: '/api/image'
       path: '/api/image'
@@ -998,6 +1050,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiTranscriptionStreamRouteImport
       parentRoute: typeof ApiTranscriptionRoute
     }
+    '/api/interrupts-v2/recovery': {
+      id: '/api/interrupts-v2/recovery'
+      path: '/recovery'
+      fullPath: '/api/interrupts-v2/recovery'
+      preLoaderRoute: typeof ApiInterruptsV2RecoveryRouteImport
+      parentRoute: typeof ApiInterruptsV2Route
+    }
     '/api/image/stream': {
       id: '/api/image/stream'
       path: '/stream'
@@ -1039,6 +1098,18 @@ const ApiImageRouteWithChildren = ApiImageRoute._addFileChildren(
   ApiImageRouteChildren,
 )
 
+interface ApiInterruptsV2RouteChildren {
+  ApiInterruptsV2RecoveryRoute: typeof ApiInterruptsV2RecoveryRoute
+}
+
+const ApiInterruptsV2RouteChildren: ApiInterruptsV2RouteChildren = {
+  ApiInterruptsV2RecoveryRoute: ApiInterruptsV2RecoveryRoute,
+}
+
+const ApiInterruptsV2RouteWithChildren = ApiInterruptsV2Route._addFileChildren(
+  ApiInterruptsV2RouteChildren,
+)
+
 interface ApiTranscriptionRouteChildren {
   ApiTranscriptionStreamRoute: typeof ApiTranscriptionStreamRoute
 }
@@ -1082,6 +1153,7 @@ const rootRouteChildren: RootRouteChildren = {
   DevtoolsRouteBRoute: DevtoolsRouteBRoute,
   DevtoolsStructuredRoute: DevtoolsStructuredRoute,
   DevtoolsToolsRoute: DevtoolsToolsRoute,
+  InterruptsV2Route: InterruptsV2Route,
   MarkdownCjkRoute: MarkdownCjkRoute,
   MiddlewareTestRoute: MiddlewareTestRoute,
   ToolsTestRoute: ToolsTestRoute,
@@ -1094,6 +1166,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiChatRoute: ApiChatRoute,
   ApiDurableDeliveryRoute: ApiDurableDeliveryRoute,
   ApiImageRoute: ApiImageRouteWithChildren,
+  ApiInterruptsV2Route: ApiInterruptsV2RouteWithChildren,
   ApiLazyToolsWireRoute: ApiLazyToolsWireRoute,
   ApiMcpAppsCallRoute: ApiMcpAppsCallRoute,
   ApiMcpAppsChatRoute: ApiMcpAppsChatRoute,
diff --git a/testing/e2e/src/routes/api.interrupts-v2.recovery.ts b/testing/e2e/src/routes/api.interrupts-v2.recovery.ts
new file mode 100644
index 000000000..f8e94d80f
--- /dev/null
+++ b/testing/e2e/src/routes/api.interrupts-v2.recovery.ts
@@ -0,0 +1,24 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { createInterruptRecoveryHandler } from '@tanstack/ai-persistence'
+import { getInterruptFixture } from '../lib/interrupts-v2-fixture'
+
+export const Route = createFileRoute('/api/interrupts-v2/recovery')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const testId = new URL(request.url).searchParams.get('testId')
+        if (!testId) return new Response('Missing testId', { status: 400 })
+        const fixture = getInterruptFixture(testId)
+        const handleRecovery = createInterruptRecoveryHandler({
+          gateway: fixture.persistence.stores.interrupts,
+          authorize: (recoveryRequest) => ({
+            authorized:
+              recoveryRequest.headers.get('x-interrupt-fixture') === testId,
+            includeResolutions: true,
+          }),
+        })
+        return handleRecovery(request)
+      },
+    },
+  },
+})
diff --git a/testing/e2e/src/routes/api.interrupts-v2.ts b/testing/e2e/src/routes/api.interrupts-v2.ts
new file mode 100644
index 000000000..f2355c7b5
--- /dev/null
+++ b/testing/e2e/src/routes/api.interrupts-v2.ts
@@ -0,0 +1,235 @@
+import {
+  EventType,
+  chat,
+  chatParamsFromRequestBody,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import {
+  InterruptResumeValidationError,
+  withChatPersistence,
+} from '@tanstack/ai-persistence'
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  createInterruptFixtureAdapter,
+  fixtureResumeMessages,
+  getInterruptFixture,
+  interruptFixtureServerTools,
+  responseDecision,
+} from '../lib/interrupts-v2-fixture'
+import type { RunAgentResumeItem, StreamChunk } from '@tanstack/ai'
+import type { InterruptFixture } from '../lib/interrupts-v2-fixture'
+
+async function collectChunks(
+  stream: AsyncIterable<StreamChunk>,
+): Promise<Array<StreamChunk>> {
+  const chunks: Array<StreamChunk> = []
+  for await (const chunk of stream) chunks.push(chunk)
+  return chunks
+}
+
+function replayChunks(
+  chunks: ReadonlyArray<StreamChunk>,
+): AsyncIterable<StreamChunk> {
+  return {
+    async *[Symbol.asyncIterator]() {
+      await Promise.resolve()
+      for (const chunk of chunks) yield chunk
+    },
+  }
+}
+
+function truncatedSseResponse(): Response {
+  const encoder = new TextEncoder()
+  return new Response(
+    new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(encoder.encode('event: RUN_STARTED\ndata: {'))
+        controller.close()
+      },
+    }),
+    { headers: { 'Content-Type': 'text/event-stream' } },
+  )
+}
+
+function errorStream(
+  error: InterruptResumeValidationError,
+  runId: string,
+): AsyncIterable<StreamChunk> {
+  return {
+    async *[Symbol.asyncIterator]() {
+      await Promise.resolve()
+      const base: StreamChunk = {
+        type: EventType.RUN_ERROR,
+        runId,
+        message: error.message,
+        code: 'INTERRUPT_RESUME_VALIDATION',
+        timestamp: Date.now(),
+      }
+      yield Object.assign(base, {
+        'tanstack:interruptErrors': error.errors,
+        ...(error.recovery === undefined
+          ? {}
+          : { 'tanstack:interruptRecovery': error.recovery }),
+      })
+    },
+  }
+}
+
+function objectValue(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value))
+    : undefined
+}
+
+function recordSubmission(
+  fixture: InterruptFixture,
+  resume: ReadonlyArray<RunAgentResumeItem>,
+  chunks: ReadonlyArray<StreamChunk>,
+  runId: string,
+): void {
+  fixture.continuationCount += 1
+  fixture.continuationRunIds.push(runId)
+  fixture.continuationChunks.set(runId, chunks)
+  fixture.decisions = resume.map(responseDecision)
+  fixture.auditHistory = resume.map(
+    (item) => `${item.interruptId}:${responseDecision(item)}`,
+  )
+  fixture.resultEventNames = chunks
+    .map((chunk) => chunk.type)
+    .filter(
+      (type) =>
+        type === EventType.RUN_STARTED ||
+        type === EventType.TOOL_CALL_RESULT ||
+        type === EventType.RUN_FINISHED,
+    )
+  fixture.storedHistory.push(fixture.decisions.join(','))
+
+  for (const item of resume) {
+    const payload = objectValue(item.payload)
+    const editedArgs = payload?.editedArgs
+    const edited = objectValue(editedArgs)
+    if (edited) fixture.edits = edited
+  }
+}
+
+function replayedContinuationId(
+  chunks: ReadonlyArray<StreamChunk>,
+): string | undefined {
+  for (const chunk of chunks) {
+    if (chunk.type !== EventType.RUN_FINISHED || !('result' in chunk)) continue
+    const result = objectValue(chunk.result)
+    if (result?.replayed !== true) continue
+    const continuationRunId = result.continuationRunId
+    if (typeof continuationRunId === 'string') return continuationRunId
+  }
+  return undefined
+}
+
+function hasInterruptFailure(chunks: ReadonlyArray<StreamChunk>): boolean {
+  return chunks.some(
+    (chunk) =>
+      chunk.type === EventType.RUN_ERROR &&
+      (chunk['tanstack:interruptErrors']?.length ?? 0) > 0,
+  )
+}
+
+export const Route = createFileRoute('/api/interrupts-v2')({
+  server: {
+    handlers: {
+      GET: ({ request }) => {
+        const url = new URL(request.url)
+        const testId = url.searchParams.get('testId')
+        if (!testId) return new Response('Missing testId', { status: 400 })
+        const fixture = getInterruptFixture(testId)
+
+        if (url.searchParams.get('stats') === '1') {
+          return Response.json({
+            continuationCount: fixture.continuationCount,
+            continuationRunIds: fixture.continuationRunIds,
+            decisions: fixture.decisions,
+            edits: fixture.edits,
+            auditHistory: fixture.auditHistory,
+            resultEventNames: fixture.resultEventNames,
+            storedHistory: fixture.storedHistory,
+            truncatedResponses: fixture.truncatedResponses,
+            replayCount: fixture.replayCount,
+            joinedContinuationRunId: fixture.joinedContinuationRunId,
+          })
+        }
+
+        const runId = url.searchParams.get('runId')
+        if (!runId) return new Response('Missing runId', { status: 400 })
+        const chunks = fixture.continuationChunks.get(runId)
+        if (!chunks) return new Response('Unknown run', { status: 404 })
+        fixture.replayCount += 1
+        fixture.joinedContinuationRunId = runId
+        return toServerSentEventsResponse(replayChunks(chunks))
+      },
+      POST: async ({ request }) => {
+        const url = new URL(request.url)
+        const testId = url.searchParams.get('testId')
+        const scenario = url.searchParams.get('scenario')
+        if (!testId || !scenario) {
+          return new Response('Missing fixture correlation', { status: 400 })
+        }
+
+        let params
+        try {
+          params = await chatParamsFromRequestBody(await request.json())
+        } catch (error) {
+          return new Response(
+            error instanceof Error ? error.message : 'Bad request',
+            { status: 400 },
+          )
+        }
+
+        const fixture = getInterruptFixture(testId)
+        const resumeMessages =
+          params.resume === undefined
+            ? undefined
+            : fixtureResumeMessages(scenario)
+        const stream = chat({
+          ...params,
+          ...(resumeMessages === undefined ? {} : { messages: resumeMessages }),
+          adapter: createInterruptFixtureAdapter(
+            scenario,
+            params.resume !== undefined,
+          ),
+          tools: [...interruptFixtureServerTools],
+          middleware: [withChatPersistence(fixture.persistence)],
+        })
+
+        let chunks: Array<StreamChunk>
+        try {
+          chunks = await collectChunks(stream)
+        } catch (error) {
+          if (error instanceof InterruptResumeValidationError) {
+            return toServerSentEventsResponse(errorStream(error, params.runId))
+          }
+          throw error
+        }
+
+        if (params.resume !== undefined) {
+          const replayedId = replayedContinuationId(chunks)
+          if (replayedId === undefined && !hasInterruptFailure(chunks)) {
+            recordSubmission(fixture, params.resume, chunks, params.runId)
+          } else {
+            fixture.joinedContinuationRunId = replayedId
+          }
+        }
+
+        if (
+          scenario === 'commit-then-truncate' &&
+          params.resume !== undefined &&
+          fixture.truncateCommittedResponseOnce
+        ) {
+          fixture.truncateCommittedResponseOnce = false
+          fixture.truncatedResponses += 1
+          return truncatedSseResponse()
+        }
+
+        return toServerSentEventsResponse(replayChunks(chunks))
+      },
+    },
+  },
+})
diff --git a/testing/e2e/src/routes/interrupts-v2.tsx b/testing/e2e/src/routes/interrupts-v2.tsx
new file mode 100644
index 000000000..666acaa41
--- /dev/null
+++ b/testing/e2e/src/routes/interrupts-v2.tsx
@@ -0,0 +1,709 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { EventType } from '@tanstack/ai'
+import {
+  fetchServerSentEvents,
+  localStoragePersistence,
+} from '@tanstack/ai-client'
+import { useChat } from '@tanstack/ai-react'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { interruptFixtureTools } from '../lib/interrupts-v2-fixture'
+import type {
+  Interrupt,
+  InterruptRecoveryQuery,
+  InterruptRecoveryStateV1,
+  StreamChunk,
+} from '@tanstack/ai'
+import type {
+  ChatResumeSnapshot,
+  ConnectConnectionAdapter,
+  RunAgentInputContext,
+  SubscribeConnectionAdapter,
+} from '@tanstack/ai-client'
+
+interface FixtureStats {
+  continuationCount: number
+  decisions: Array<string>
+  edits: Record<string, unknown>
+  auditHistory: Array<string>
+  resultEventNames: Array<string>
+  storedHistory: Array<string>
+}
+
+interface LocalDrafts {
+  action: string
+  generic: string
+  stagedFirst: string
+  clientOutput: string
+  addToolResultCount: number
+}
+
+const emptyStats: FixtureStats = {
+  continuationCount: 0,
+  decisions: [],
+  edits: {},
+  auditHistory: [],
+  resultEventNames: [],
+  storedHistory: [],
+}
+
+const emptyDrafts: LocalDrafts = {
+  action: '',
+  generic: '',
+  stagedFirst: '',
+  clientOutput: '',
+  addToolResultCount: 0,
+}
+
+const sharedErrorResponseSchema = {
+  type: 'object',
+  properties: { answer: { type: 'string' } },
+  required: ['answer'],
+  additionalProperties: false,
+} as const
+
+function sharedErrorInterrupt(
+  interruptedRunId: string,
+  generation: number,
+): Interrupt {
+  return {
+    id: 'shared-generic',
+    reason: 'confirmation',
+    message: 'Resolve the shared-stream fixture.',
+    responseSchema: sharedErrorResponseSchema,
+    metadata: {
+      kind: 'generic',
+      'tanstack:interruptBinding': {
+        kind: 'generic',
+        interruptId: 'shared-generic',
+        interruptedRunId,
+        generation,
+        responseSchemaHash: 'fixture:shared-generic',
+      },
+    },
+  }
+}
+
+function createSharedErrorFixture() {
+  const chunks: Array<StreamChunk> = []
+  let wake: (() => void) | undefined
+  let activeResume: RunAgentInputContext | undefined
+
+  const publish = (chunk: StreamChunk) => {
+    chunks.push(chunk)
+    const resolve = wake
+    wake = undefined
+    resolve?.()
+  }
+
+  const connection: SubscribeConnectionAdapter = {
+    async *subscribe(abortSignal) {
+      while (!abortSignal?.aborted) {
+        const chunk = chunks.shift()
+        if (chunk) {
+          yield chunk
+          continue
+        }
+        await new Promise<void>((resolve) => {
+          wake = resolve
+          abortSignal?.addEventListener('abort', () => resolve(), {
+            once: true,
+          })
+        })
+      }
+    },
+    send: (_messages, _data, _abortSignal, runContext) => {
+      if (!runContext) {
+        return Promise.reject(new Error('Missing shared fixture run context.'))
+      }
+      if (runContext.resume === undefined) {
+        publish({
+          type: EventType.RUN_STARTED,
+          threadId: runContext.threadId,
+          runId: runContext.runId,
+          timestamp: Date.now(),
+        })
+        publish({
+          type: EventType.RUN_FINISHED,
+          threadId: runContext.threadId,
+          runId: runContext.runId,
+          outcome: {
+            type: 'interrupt',
+            interrupts: [sharedErrorInterrupt(runContext.runId, 1)],
+          },
+          timestamp: Date.now(),
+        })
+      } else {
+        activeResume = runContext
+      }
+      return Promise.resolve()
+    },
+  }
+
+  return {
+    connection,
+    publishForeignError() {
+      publish({
+        type: EventType.RUN_ERROR,
+        threadId: 'foreign-thread',
+        runId: 'foreign-child-run',
+        timestamp: Date.now(),
+        message: 'foreign run failed',
+        'tanstack:interruptErrors': [
+          {
+            scope: 'item',
+            interruptId: 'shared-generic',
+            code: 'invalid-payload',
+            message: 'foreign item error',
+            source: 'server',
+            retryable: false,
+            threadId: 'foreign-thread',
+            interruptedRunId: 'foreign-parent-run',
+            generation: 7,
+          },
+          {
+            scope: 'batch',
+            code: 'item-validation-failed',
+            message: 'foreign batch error',
+            source: 'server',
+            retryable: false,
+            interruptIds: ['shared-generic'],
+            threadId: 'foreign-thread',
+            interruptedRunId: 'foreign-parent-run',
+            generation: 7,
+          },
+        ],
+      })
+    },
+    publishLocalError() {
+      if (!activeResume?.parentRunId) return
+      publish({
+        type: EventType.RUN_ERROR,
+        threadId: activeResume.threadId,
+        runId: activeResume.runId,
+        timestamp: Date.now(),
+        message: 'local validation failed',
+        'tanstack:interruptErrors': [
+          {
+            scope: 'item',
+            interruptId: 'shared-generic',
+            code: 'invalid-payload',
+            message: 'local item error',
+            source: 'server',
+            retryable: false,
+            threadId: activeResume.threadId,
+            interruptedRunId: activeResume.parentRunId,
+            generation: 1,
+          },
+          {
+            scope: 'batch',
+            code: 'item-validation-failed',
+            message: 'local batch error',
+            source: 'server',
+            retryable: false,
+            interruptIds: ['shared-generic'],
+            threadId: activeResume.threadId,
+            interruptedRunId: activeResume.parentRunId,
+            generation: 1,
+          },
+        ],
+      })
+    },
+  }
+}
+
+function createInterruptStateFetcher(
+  url: () => string,
+  authorization: string,
+): NonNullable<ConnectConnectionAdapter['loadInterruptState']> {
+  return async (
+    query: InterruptRecoveryQuery,
+    abortSignal?: AbortSignal,
+  ): Promise<InterruptRecoveryStateV1> => {
+    const recoveryUrl = new URL(url(), window.location.origin)
+    recoveryUrl.searchParams.set('threadId', query.threadId)
+    recoveryUrl.searchParams.set('interruptedRunId', query.interruptedRunId)
+    recoveryUrl.searchParams.set(
+      'knownGeneration',
+      String(query.knownGeneration),
+    )
+    const response = await fetch(recoveryUrl, {
+      method: 'POST',
+      headers: { 'x-interrupt-fixture': authorization },
+      ...(abortSignal === undefined ? {} : { signal: abortSignal }),
+    })
+    if (!response.ok) {
+      throw new Error(`Interrupt recovery failed with ${response.status}.`)
+    }
+    return response.json()
+  }
+}
+
+function readDrafts(key: string): LocalDrafts {
+  if (typeof window === 'undefined') return emptyDrafts
+  const value = window.localStorage.getItem(key)
+  if (!value) return emptyDrafts
+  try {
+    const parsed: unknown = JSON.parse(value)
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return emptyDrafts
+    }
+    const record = Object.fromEntries(Object.entries(parsed))
+    return {
+      action: typeof record.action === 'string' ? record.action : '',
+      generic: typeof record.generic === 'string' ? record.generic : '',
+      stagedFirst:
+        typeof record.stagedFirst === 'string' ? record.stagedFirst : '',
+      clientOutput:
+        typeof record.clientOutput === 'string' ? record.clientOutput : '',
+      addToolResultCount:
+        typeof record.addToolResultCount === 'number'
+          ? record.addToolResultCount
+          : 0,
+    }
+  } catch {
+    return emptyDrafts
+  }
+}
+
+function InterruptsV2Page() {
+  const { testId, scenario } = Route.useSearch()
+  const draftKey = `interrupts-v2:drafts:${testId}`
+  const [drafts, setDrafts] = useState<LocalDrafts>(() => readDrafts(draftKey))
+  const [stats, setStats] = useState<FixtureStats>(emptyStats)
+  const [callbackReturns, setCallbackReturns] = useState('')
+  const [retryVisible, setRetryVisible] = useState(false)
+  const [hydrated, setHydrated] = useState(false)
+  const sharedErrorFixture = useMemo(createSharedErrorFixture, [testId])
+
+  const updateDrafts = useCallback(
+    (update: Partial<LocalDrafts>) => {
+      setDrafts((current) => {
+        const next = { ...current, ...update }
+        if (typeof window !== 'undefined') {
+          window.localStorage.setItem(draftKey, JSON.stringify(next))
+        }
+        return next
+      })
+    },
+    [draftKey],
+  )
+
+  const refreshStats = useCallback(async () => {
+    if (typeof window === 'undefined') return
+    const response = await fetch(
+      new URL(
+        `/api/interrupts-v2?testId=${encodeURIComponent(testId)}&stats=1`,
+        window.location.origin,
+      ),
+    )
+    if (response.ok) setStats(await response.json())
+  }, [testId])
+
+  const connection = useMemo(() => {
+    if (scenario === 'shared-error-correlation') {
+      return sharedErrorFixture.connection
+    }
+    const chatUrl = () =>
+      `/api/interrupts-v2?testId=${encodeURIComponent(testId)}&scenario=${encodeURIComponent(scenario)}`
+    const recoveryUrl = () =>
+      `/api/interrupts-v2/recovery?testId=${encodeURIComponent(testId)}`
+    return {
+      ...fetchServerSentEvents(chatUrl),
+      loadInterruptState: createInterruptStateFetcher(recoveryUrl, testId),
+    }
+  }, [scenario, sharedErrorFixture, testId])
+
+  const resumePersistence = useMemo(
+    () =>
+      typeof window === 'undefined'
+        ? undefined
+        : localStoragePersistence<ChatResumeSnapshot>({
+            keyPrefix: 'tanstack-ai:interrupts-v2:',
+            serialize: (value) => JSON.stringify(value),
+            deserialize: (value) => JSON.parse(value),
+          }),
+    [],
+  )
+
+  const {
+    sendMessage,
+    interrupts,
+    interruptErrors,
+    error,
+    isLoading,
+    resuming,
+    resolveInterrupts,
+    retryInterrupts,
+  } = useChat({
+    id: `interrupts-v2-${testId}`,
+    threadId: `interrupts-v2-${testId}`,
+    connection,
+    tools: interruptFixtureTools,
+    ...(resumePersistence === undefined
+      ? {}
+      : { persistence: { server: resumePersistence } }),
+    onChunk: (chunk) => {
+      if (chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR') {
+        void refreshStats()
+      }
+    },
+    onError: () => {
+      setRetryVisible(true)
+      void refreshStats()
+    },
+  })
+
+  useEffect(() => {
+    void refreshStats()
+  }, [isLoading, refreshStats, resuming, interrupts.length])
+
+  useEffect(() => setHydrated(true), [])
+
+  const first =
+    interrupts.find((interrupt) => interrupt.interruptId === 'approval-1') ??
+    interrupts.find(
+      (interrupt) =>
+        interrupt.kind === 'tool-approval' &&
+        interrupt.toolName === 'editable_action',
+    )
+  const second = interrupts.find(
+    (interrupt) => interrupt.interruptId === 'question-1',
+  )
+  // `browser_action` is a client tool with a `.client()` implementation, so it
+  // executes automatically and never appears in the public `interrupts` array.
+  // Its resolution is observed via `submitted-decisions` once the batch resumes.
+  const invalidItemIds = interrupts
+    .filter((interrupt) => interrupt.error !== undefined)
+    .map((interrupt) => interrupt.interruptId)
+  const validationAggregate =
+    invalidItemIds.length === 0
+      ? ''
+      : `item-validation-failed:${invalidItemIds.join(',')}`
+
+  const approveFirst = useCallback(() => {
+    if (first?.kind !== 'tool-approval') return
+    const editedArgs = drafts.action
+      ? { editedArgs: { action: drafts.action } }
+      : {}
+    if (first.toolName === 'editable_action') {
+      first.resolveInterrupt(true, { payload: {}, ...editedArgs })
+      updateDrafts({
+        stagedFirst: JSON.stringify({ approved: true, ...editedArgs }),
+      })
+    }
+  }, [drafts.action, first, updateDrafts])
+
+  const parseGenericDraft = useCallback((): unknown => {
+    try {
+      return JSON.parse(drafts.generic)
+    } catch {
+      return drafts.generic
+    }
+  }, [drafts.generic])
+
+  return (
+    <main>
+      <h1>Interrupts v2 fixture</h1>
+      <button
+        data-testid="start-run"
+        disabled={!hydrated || isLoading || interrupts.length > 0}
+        onClick={() => void sendMessage('start fixture')}
+      >
+        Start run
+      </button>
+
+      <output data-testid="continuation-count">
+        {stats.continuationCount}
+      </output>
+      <output data-testid="submitted-decisions">
+        {stats.decisions.join(',')}
+      </output>
+      <output data-testid="submitted-edits">
+        {JSON.stringify(stats.edits)}
+      </output>
+      <output data-testid="audit-history">
+        {stats.auditHistory.join('|')}
+      </output>
+      <output data-testid="result-event-names">
+        {stats.resultEventNames.join(',')}
+      </output>
+      <output data-testid="stored-history">
+        {stats.storedHistory.join('|')}
+      </output>
+      <output data-testid="callback-return-values">{callbackReturns}</output>
+      <output data-testid="staged-response-first">{drafts.stagedFirst}</output>
+      <output data-testid="resume-status">
+        {resuming ? 'resuming' : 'idle'}
+      </output>
+      <output data-testid="interrupt-errors-items">
+        {interrupts
+          .flatMap((interrupt) =>
+            interrupt.errors.map(
+              (interruptError) =>
+                `${interruptError.code}:${interruptError.message}`,
+            ),
+          )
+          .join('|')}
+      </output>
+
+      <output data-testid="interrupt-error-first">
+        {first?.error ? `${first.error.code}:${first.error.message}` : ''}
+      </output>
+      <output data-testid="interrupt-error-second">
+        {second?.error ? `${second.error.code}:${second.error.message}` : ''}
+      </output>
+      <output data-testid="interrupt-error-generic">
+        {second?.error ? `${second.error.code}:${second.error.message}` : ''}
+      </output>
+      <output data-testid="interrupt-errors-root">
+        {interruptErrors
+          .map(
+            (submissionError) =>
+              `${submissionError.code}:${submissionError.interruptIds.join(',')}:${submissionError.message}`,
+          )
+          .join('|')}
+        {interruptErrors.length > 0 && validationAggregate ? '|' : ''}
+        {validationAggregate}
+      </output>
+      <output data-testid="chat-error">{error?.message ?? ''}</output>
+
+      {retryVisible ? (
+        <div data-testid="retry-banner">Retry available</div>
+      ) : null}
+      <button
+        data-testid="retry-interrupts"
+        disabled={resuming}
+        onClick={() => {
+          retryInterrupts()
+          void refreshStats()
+        }}
+      >
+        Retry interrupts
+      </button>
+      {scenario === 'shared-error-correlation' ? (
+        <>
+          <button
+            data-testid="publish-foreign-error"
+            onClick={sharedErrorFixture.publishForeignError}
+          >
+            Publish foreign error
+          </button>
+          <button
+            data-testid="publish-local-error"
+            onClick={sharedErrorFixture.publishLocalError}
+          >
+            Publish local error
+          </button>
+        </>
+      ) : null}
+
+      {interrupts.map((interrupt) => (
+        <section data-testid="interrupt-card" key={interrupt.id}>
+          <strong>{interrupt.interruptId}</strong>
+          <span data-testid={`interrupt-kind-${interrupt.kind}`}>
+            {interrupt.kind}
+          </span>
+          {interrupt.kind === 'tool-approval' ? (
+            <>
+              {interrupt.toolName === 'editable_action' ? (
+                <>
+                  <input
+                    data-testid="edited-action"
+                    value={drafts.action}
+                    onChange={(event) =>
+                      updateDrafts({ action: event.currentTarget.value })
+                    }
+                  />
+                  <button onClick={approveFirst}>
+                    {drafts.action ? 'Approve edited' : 'Approve'}
+                  </button>
+                  <button
+                    onClick={() =>
+                      interrupt.resolveInterrupt(false, { payload: {} })
+                    }
+                  >
+                    Deny
+                  </button>
+                </>
+              ) : interrupt.toolName === 'branch_action' ? (
+                <>
+                  <button
+                    onClick={() =>
+                      interrupt.resolveInterrupt(true, {
+                        payload: { note: 'approved' },
+                      })
+                    }
+                  >
+                    Approve
+                  </button>
+                  <button
+                    onClick={() =>
+                      interrupt.resolveInterrupt(false, {
+                        payload: { reason: 'denied' },
+                      })
+                    }
+                  >
+                    Deny
+                  </button>
+                </>
+              ) : (
+                <>
+                  <button onClick={() => interrupt.resolveInterrupt(true)}>
+                    Approve
+                  </button>
+                  <button onClick={() => interrupt.resolveInterrupt(false)}>
+                    Deny
+                  </button>
+                </>
+              )}
+              <button onClick={() => interrupt.cancel()}>Cancel</button>
+            </>
+          ) : null}
+          {interrupt.kind === 'generic' ? (
+            <>
+              <textarea
+                data-testid="generic-draft"
+                value={drafts.generic}
+                onChange={(event) =>
+                  updateDrafts({ generic: event.currentTarget.value })
+                }
+              />
+              <button
+                data-testid="resolve-generic"
+                onClick={() => interrupt.resolveInterrupt(parseGenericDraft())}
+              >
+                Resolve generic
+              </button>
+            </>
+          ) : null}
+        </section>
+      ))}
+
+      <button data-testid="approve-first" onClick={approveFirst}>
+        Resolve first
+      </button>
+      <button
+        data-testid="deny-second"
+        onClick={() => {
+          const interrupt = interrupts.find(
+            (candidate) => candidate.interruptId === 'approval-2',
+          )
+          if (
+            interrupt?.kind === 'tool-approval' &&
+            interrupt.toolName === 'branch_action'
+          ) {
+            interrupt.resolveInterrupt(false, {
+              payload: { reason: 'denied' },
+            })
+          }
+        }}
+      >
+        Deny second
+      </button>
+      <button
+        data-testid="cancel-third"
+        onClick={() =>
+          interrupts
+            .find((interrupt) => interrupt.interruptId === 'approval-3')
+            ?.cancel()
+        }
+      >
+        Cancel third
+      </button>
+      <button
+        data-testid="resolve-callback"
+        onClick={() => {
+          const returns: Array<string> = []
+          resolveInterrupts((interrupt) => {
+            let result: undefined
+            if (
+              interrupt.kind === 'tool-approval' &&
+              interrupt.toolName === 'editable_action'
+            ) {
+              interrupt.resolveInterrupt(true, { payload: {} })
+            } else if (
+              interrupt.kind === 'tool-approval' &&
+              interrupt.toolName === 'branch_action'
+            ) {
+              interrupt.resolveInterrupt(false, {
+                payload: { reason: 'callback' },
+              })
+            } else if (interrupt.kind === 'generic') {
+              interrupt.resolveInterrupt({ answer: 'callback' })
+            }
+            returns.push(String(result))
+            return undefined
+          })
+          setCallbackReturns(returns.join(','))
+        }}
+      >
+        Resolve callback
+      </button>
+
+      <button
+        data-testid="invalid-first"
+        onClick={() => {
+          if (
+            first?.kind === 'tool-approval' &&
+            first.toolName === 'editable_action'
+          ) {
+            first.resolveInterrupt(true, {
+              payload: {},
+              editedArgs: { action: '' },
+            })
+          }
+        }}
+      >
+        Invalid first
+      </button>
+      <button
+        data-testid="invalid-second"
+        onClick={() =>
+          second?.kind === 'generic' && second.resolveInterrupt({ answer: 1 })
+        }
+      >
+        Invalid second
+      </button>
+      <button
+        data-testid="correct-first"
+        onClick={() => {
+          if (
+            first?.kind === 'tool-approval' &&
+            first.toolName === 'editable_action'
+          ) {
+            first.resolveInterrupt(true, {
+              payload: {},
+              editedArgs: { action: 'correct' },
+            })
+          }
+        }}
+      >
+        Correct first
+      </button>
+      <button
+        data-testid="correct-second"
+        onClick={() =>
+          second?.kind === 'generic' &&
+          second.resolveInterrupt({ answer: 'correct' })
+        }
+      >
+        Correct second
+      </button>
+
+      <button data-testid="approve-server-tool" onClick={approveFirst}>
+        Resolve server tool
+      </button>
+    </main>
+  )
+}
+
+export const Route = createFileRoute('/interrupts-v2')({
+  validateSearch: (search) => ({
+    testId: typeof search.testId === 'string' ? search.testId : 'default',
+    scenario:
+      typeof search.scenario === 'string'
+        ? search.scenario
+        : 'singleton-approval',
+  }),
+  component: InterruptsV2Page,
+})
diff --git a/testing/e2e/tests/interrupts.spec.ts b/testing/e2e/tests/interrupts.spec.ts
new file mode 100644
index 000000000..7b2a4f611
--- /dev/null
+++ b/testing/e2e/tests/interrupts.spec.ts
@@ -0,0 +1,317 @@
+import { expect, test } from '@playwright/test'
+import type { APIRequestContext, Page } from '@playwright/test'
+
+function fixtureId(label: string): string {
+  const info = test.info()
+  return `${label}-${info.workerIndex}-${info.testId}`
+}
+
+function interruptUrl(testId: string, scenario: string): string {
+  const search = new URLSearchParams({ testId, scenario })
+  return `/interrupts-v2?${search.toString()}`
+}
+
+async function startScenario(
+  page: Page,
+  testId: string,
+  scenario: string,
+): Promise<void> {
+  await page.goto(interruptUrl(testId, scenario))
+  await page.getByTestId('start-run').click()
+}
+
+async function readStats(request: APIRequestContext, testId: string) {
+  const response = await request.get(
+    `/api/interrupts-v2?testId=${encodeURIComponent(testId)}&stats=1`,
+  )
+  expect(response.ok()).toBe(true)
+  return response.json()
+}
+
+test('submits a singleton approval unchanged or with an edited input', async ({
+  page,
+}) => {
+  const unchangedId = fixtureId('interrupt-singleton-unchanged')
+  await startScenario(page, unchangedId, 'singleton-approval')
+  await expect(page.getByTestId('interrupt-card')).toHaveCount(1)
+  await page.getByRole('button', { name: 'Approve', exact: true }).click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+  await expect(page.getByTestId('submitted-decisions')).toHaveText('approve')
+  await expect(page.getByTestId('submitted-edits')).toHaveText('{}')
+
+  const editedId = fixtureId('interrupt-singleton-edited')
+  await startScenario(page, editedId, 'singleton-approval')
+  await expect(page.getByTestId('interrupt-card')).toHaveCount(1)
+  await page.getByTestId('edited-action').fill('edited-action')
+  await page.getByRole('button', { name: 'Approve edited' }).click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+  await expect(page.getByTestId('submitted-edits')).toHaveText(
+    '{"action":"edited-action"}',
+  )
+})
+
+test('waits for all three cards before one atomic submission', async ({
+  page,
+}) => {
+  const testId = fixtureId('interrupts-v2-batch')
+  await startScenario(page, testId, 'three-tool-approvals')
+  await expect(page.getByTestId('interrupt-card')).toHaveCount(3)
+
+  await page
+    .getByTestId('interrupt-card')
+    .nth(0)
+    .getByRole('button', { name: 'Approve' })
+    .click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('0')
+  await page
+    .getByTestId('interrupt-card')
+    .nth(1)
+    .getByRole('button', { name: 'Deny' })
+    .click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('0')
+  await page
+    .getByTestId('interrupt-card')
+    .nth(2)
+    .getByRole('button', { name: 'Cancel' })
+    .click()
+
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+  await expect(page.getByTestId('submitted-decisions')).toHaveText(
+    'approve,deny,cancel',
+  )
+})
+
+test('root callback performs synchronous side effects and returns undefined', async ({
+  page,
+}) => {
+  const testId = fixtureId('interrupt-callback')
+  await startScenario(page, testId, 'heterogeneous-callback')
+  await expect(page.getByTestId('interrupt-card')).toHaveCount(3)
+  await page.getByTestId('resolve-callback').click()
+  await expect(page.getByTestId('callback-return-values')).toHaveText(
+    'undefined,undefined,undefined',
+  )
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+  await expect(page.getByTestId('submitted-decisions')).toHaveText(
+    'approve,deny,generic',
+  )
+})
+
+test('records approve, deny, and cancel decisions in audit and result history', async ({
+  page,
+}) => {
+  const testId = fixtureId('interrupt-audit')
+  await startScenario(page, testId, 'three-tool-approvals')
+  await expect(page.getByTestId('interrupt-card')).toHaveCount(3)
+  await page.getByTestId('approve-first').click()
+  await page.getByTestId('deny-second').click()
+  await page.getByTestId('cancel-third').click()
+
+  await expect(page.getByTestId('audit-history')).toHaveText(
+    'approval-1:approve|approval-2:deny|approval-3:cancel',
+  )
+  await expect(page.getByTestId('result-event-names')).toHaveText(
+    'TOOL_CALL_RESULT,TOOL_CALL_RESULT,RUN_STARTED,RUN_FINISHED',
+  )
+  await expect(page.getByTestId('stored-history')).toContainText(
+    'approve,deny,cancel',
+  )
+})
+
+test('keeps a generic interrupt staged until its payload validates', async ({
+  page,
+}) => {
+  const testId = fixtureId('interrupt-generic')
+  await startScenario(page, testId, 'generic-validation')
+  await expect(page.getByTestId('interrupt-kind-generic')).toHaveCount(1)
+  await page.getByTestId('generic-draft').fill('{"answer":1}')
+  await page.getByTestId('resolve-generic').click()
+  await expect(page.getByTestId('interrupt-error-generic')).toContainText(
+    'invalid-payload',
+  )
+  await expect(page.getByTestId('continuation-count')).toHaveText('0')
+
+  await page.getByTestId('generic-draft').fill('{"answer":"correct"}')
+  await page.getByTestId('resolve-generic').click()
+  await expect(page.getByTestId('interrupt-error-generic')).toHaveText('')
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+})
+
+test('shows every item error and the root aggregate in one response', async ({
+  page,
+}) => {
+  const testId = fixtureId('interrupt-errors')
+  await startScenario(page, testId, 'two-invalid')
+  await page.getByTestId('invalid-first').click()
+  await page.getByTestId('invalid-second').click()
+  await expect(page.getByTestId('interrupt-error-first')).toContainText(
+    'invalid-edited-args',
+  )
+  await expect(page.getByTestId('interrupt-error-second')).toContainText(
+    'invalid-payload',
+  )
+  await expect(page.getByTestId('interrupt-errors-root')).toContainText(
+    'item-validation-failed',
+  )
+  await expect(page.getByTestId('interrupt-errors-root')).toContainText(
+    'approval-1,question-1',
+  )
+  await page.getByTestId('correct-first').click()
+  await expect(page.getByTestId('interrupt-error-first')).toHaveText('')
+  await expect(page.getByTestId('interrupt-error-second')).toContainText(
+    'invalid-payload',
+  )
+  await page.getByTestId('correct-second').click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+})
+
+test('restores partial staged drafts after a full reload', async ({ page }) => {
+  const testId = fixtureId('interrupt-reload')
+  await startScenario(page, testId, 'partial-draft-reload')
+  await expect(page.getByTestId('interrupt-card')).toHaveCount(2)
+  await page.getByTestId('edited-action').fill('persisted-edit')
+  await page.getByTestId('approve-first').click()
+  await page.getByTestId('generic-draft').fill('{"answer":"persisted"}')
+
+  await page.reload()
+  await expect(page.getByTestId('interrupt-card')).toHaveCount(2)
+  await expect(page.getByTestId('staged-response-first')).toHaveText(
+    '{"approved":true,"editedArgs":{"action":"persisted-edit"}}',
+  )
+  await expect(page.getByTestId('generic-draft')).toHaveValue(
+    '{"answer":"persisted"}',
+  )
+  await expect(page.getByTestId('continuation-count')).toHaveText('0')
+})
+
+test('joins the original continuation after a committed response is truncated', async ({
+  page,
+  request,
+}) => {
+  const testId = fixtureId('interrupt-retry')
+  await startScenario(page, testId, 'commit-then-truncate')
+  await page.getByRole('button', { name: 'Approve', exact: true }).click()
+  await expect(page.getByTestId('retry-banner')).toBeVisible()
+  const committed = await readStats(request, testId)
+  expect(committed).toMatchObject({
+    continuationCount: 1,
+    continuationRunIds: [expect.any(String)],
+    truncatedResponses: 1,
+  })
+  await page.getByTestId('retry-interrupts').click()
+  await expect
+    .poll(async () => (await readStats(request, testId)).replayCount)
+    .toBe(1)
+  const replayStats = await readStats(request, testId)
+  expect(replayStats).toMatchObject({
+    continuationCount: 1,
+    replayCount: 1,
+    truncatedResponses: 1,
+  })
+  expect(replayStats.joinedContinuationRunId).toBe(
+    replayStats.continuationRunIds[0],
+  )
+})
+
+test('reports a two-tab loser as a conflict without a second continuation', async ({
+  context,
+  page,
+}) => {
+  const testId = fixtureId('interrupt-conflict')
+  const url = interruptUrl(testId, 'two-tab-conflict')
+  await page.goto(url)
+  await page.getByTestId('start-run').click()
+  await expect(page.getByTestId('interrupt-card')).toHaveCount(1)
+
+  const secondPage = await context.newPage()
+  await secondPage.goto(url)
+  await expect(secondPage.getByTestId('interrupt-card')).toHaveCount(1)
+  await page.getByRole('button', { name: 'Approve', exact: true }).click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+  await secondPage.getByRole('button', { name: 'Deny', exact: true }).click()
+  await expect(secondPage.getByTestId('interrupt-errors-root')).toContainText(
+    'conflict',
+  )
+  await expect(secondPage.getByTestId('continuation-count')).toHaveText('1')
+  await secondPage.close()
+})
+
+test('auto-executes the client tool internally and keeps it out of the public interrupts', async ({
+  page,
+}) => {
+  const testId = fixtureId('interrupt-client-tool')
+  await startScenario(page, testId, 'client-tool-and-approval')
+  // The client tool has a `.client()` implementation, so it executes
+  // automatically and never appears as a public interrupt — only the approval
+  // is surfaced.
+  await expect(
+    page.getByTestId('interrupt-kind-client-tool-execution'),
+  ).toHaveCount(0)
+  await expect(page.getByTestId('interrupt-kind-tool-approval')).toHaveCount(1)
+  // Resolving the public approval completes the batch (the client tool has
+  // already auto-resolved internally) and the run continues.
+  await page.getByTestId('approve-server-tool').click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+  await expect(page.getByTestId('submitted-decisions')).toContainText(
+    'client-tool',
+  )
+})
+
+test('schedules a mixed core batch and resumes only after every item resolves', async ({
+  page,
+}) => {
+  const testId = fixtureId('interrupt-core-mixed')
+  await startScenario(page, testId, 'core-mixed-client-approval')
+  // Only the approval is public; the client tool auto-executes internally.
+  await expect(page.getByTestId('interrupt-card')).toHaveCount(1)
+  await expect(
+    page.getByTestId('interrupt-kind-client-tool-execution'),
+  ).toHaveCount(0)
+  await expect(page.getByTestId('interrupt-kind-tool-approval')).toHaveCount(1)
+
+  // The batch resumes only after the public approval resolves; the client tool
+  // has already auto-resolved internally.
+  await expect(page.getByTestId('continuation-count')).toHaveText('0')
+  await page.getByTestId('approve-server-tool').click()
+  await expect(page.getByTestId('continuation-count')).toHaveText('1')
+  await expect(page.getByTestId('submitted-decisions')).toHaveText(
+    'approve,client-tool',
+  )
+  await expect(page.getByTestId('result-event-names')).toHaveText(
+    'TOOL_CALL_RESULT,TOOL_CALL_RESULT,RUN_STARTED,RUN_FINISHED',
+  )
+})
+
+test('ignores a foreign structured resume error and applies the correlated local failure', async ({
+  page,
+}) => {
+  const testId = fixtureId('interrupt-shared-error')
+  await startScenario(page, testId, 'shared-error-correlation')
+  await expect(page.getByTestId('interrupt-kind-generic')).toHaveCount(1)
+  await page.getByTestId('generic-draft').fill('{"answer":"ready"}')
+  await page.getByTestId('resolve-generic').click()
+  await expect(page.getByTestId('resume-status')).toHaveText('resuming')
+
+  await page.getByTestId('publish-foreign-error').click()
+  await expect(page.getByTestId('retry-banner')).toBeVisible()
+  await expect(page.getByTestId('interrupt-errors-items')).toHaveText('')
+  await expect(page.getByTestId('interrupt-errors-root')).toContainText(
+    'transport',
+  )
+  await expect(page.getByTestId('interrupt-errors-root')).not.toContainText(
+    'foreign',
+  )
+
+  await page.getByTestId('retry-interrupts').click()
+  await expect(page.getByTestId('resume-status')).toHaveText('resuming')
+  await page.getByTestId('publish-local-error').click()
+  await expect(page.getByTestId('interrupt-errors-items')).toContainText(
+    'local item error',
+  )
+  await expect(page.getByTestId('interrupt-errors-root')).toContainText(
+    'local batch error',
+  )
+  await expect(page.getByTestId('interrupt-errors-root')).not.toContainText(
+    'foreign',
+  )
+})