Lifecycle Boundaries

You know you need a generic interrupt. You do not know which phase to pause in. If you pause too early, the model has no draft to review. If you pause too late, a tool has already run.

By the end of this page you can pick one phase from INTERRUPT_BOUNDARY_PHASES and write the ctx.phase guard for it.

For the define, register, and resolve steps, see Generic Interrupts.

The four phases

onInterruptBoundary runs at each of these points in one agent iteration. Return { interrupts } to pause. Return nothing to let the run continue.

The engine combines every request from every middleware at the same phase into one interrupt batch. That batch ends the current run with one interrupt outcome.

import type { ChatMiddleware } from '@tanstack/ai'
import { reviewPlan } from './interrupts'

export const requestReview: ChatMiddleware<unknown, typeof reviewPlan> = {
  name: 'request-review',
  onInterruptBoundary(ctx) {
    if (ctx.phase !== 'beforeModel') return
    if (ctx.parentRunId) return
    if (ctx.iteration !== 0) return
    return {
      interrupts: [
        reviewPlan.interrupt({
          key: 'initial-plan',
          reason: 'review-required',
          message: 'Review the proposed plan.',
          payload: {
            title: 'Release plan',
            changes: ['Add search', 'Add tests'],
          },
        }),
      ],
    }
  },
}

onInterruptBoundary cannot change config. It can only pause. To change prompts, tools, or messages from the user answer, see Apply Answers.

Skip the pause on the continuation

The continuation is a new chat() call. Every boundary hook runs again.

If you return the same request, the run pauses again. If ctx.parentRunId is set, skip the emit. Use that skip when the pause belongs to the original request only.

onInterruptBoundary(ctx) {
  if (ctx.phase !== 'beforeModel') return
  if (ctx.parentRunId) return
  return {
    interrupts: [
      reviewPlan.interrupt({
        key: 'initial-plan',
        reason: 'review-required',
        message: 'Review the proposed plan.',
        payload: {
          title: 'Release plan',
          changes: ['Add search'],
        },
      }),
    ],
  }
}

What you can read at each phase

Every hook receives the same ChatMiddlewareContext. The contents change.

Useful fields on ctx:

• phase and iteration
• parentRunId (set on a continuation)
• messages (read-only view)
• systemPrompts, toolNames, hasTools, modelOptions
• accumulatedContent (assistant text for this model turn)
• model and provider (fixed for this request)
• context (your chat({ context }) value)
• abort(reason) and defer(promise)

Mutating ctx.messages does not change the engine config.

beforeModel

onConfig for this iteration has already run. Prompts, tools, messages, and modelOptions are the values after that merge.

• accumulatedContent is empty
• messages is the conversation so far

Use this phase when you need data before you pay for a model call.

afterModel

The model stream is complete.

• accumulatedContent has this turn's assistant text
• messages does not include this turn yet
• Proposed tool calls are not on ctx. They are not in messages yet

If you need tool names or args, wait for beforeTools, or watch onChunk during modelStream.

beforeTools

The engine has added the assistant message with toolCalls to messages. Tools have not run.

Use this phase to inspect the proposed calls before any side effect.

afterTools

Tools have run. Result messages with role: 'tool' are already in messages. onToolPhaseComplete has already run.

Use this phase to inspect results before the next model turn.

Real uses

beforeModel: collect a choice first

Ask for a plan, an audience, or a locale before the model writes.

Examples:

• "Which brand voice should this reply use?"
• "Which ticket should I work on?"
• "Is this request in scope for this agent?"

afterModel: review the draft

The model has written text. You want a human to accept it before tools run.

Examples:

• Review an email draft before sendEmail
• Review a SQL query before runQuery
• Review a support reply before it reaches the user

beforeTools: gate the side effects

The model asked for tools. Nothing has executed.

Examples:

• Confirm a bulk delete
• Confirm a payment
• Confirm a deploy

This is close to tool approval. Use a generic interrupt when the question is not a yes or no on one tool. Also use it when several tools must be judged as one batch.

afterTools: audit the results

The tools have already run. You want a human to see the output before the model uses it.

Examples:

• A search returned customer PII. Ask if it may stay in context
• A code run produced a diff. Ask if the next turn may apply it
• A lookup returned a low-confidence match. Ask which record to keep

Try it

The React chat example has a playground for all four phases.

1. Start examples/ts-react-chat.
2. Open /generic-interrupts.
3. Pick a phase and resolve both cards.

When you are ready to apply the answer to prompts or to stop the run, go to Apply Answers.