A public way for any server tool to ask the user for input, typed by defineInterrupt

[kyleromines]

The gap

A common agent pattern is a tool the model calls to ask the user something: clarifying questions, a choice between options, a short form. The model calls ask_user({ questions }), the run pauses, the user answers, and the answer comes back to the model as that tool call's result.

TanStack AI has the right pieces nearby, but none of them fits this exactly:

• Tool approval (needsApproval) is a yes/no gate before a tool runs. It can't carry an arbitrary answer.
• Generic interrupts (defineInterrupt) are typed end to end, but they're raised from middleware and described as "a question that is not a tool call". onInterruptResolution can only return toolResume, so the answer can't become a tool result.
• Client tools put the answer in the tool result, but only the browser that holds the stream can answer. That doesn't work when the question should survive a reload, be answered later from somewhere else, or expire unanswered on a durable run.
• MCP input requests do exactly this: the tool pauses, chat() ends the run with an interrupt, the next run calls the tool again, and the tool reads ctx.inputResponse. But the only way for a non-MCP server tool to use it is to throw an object shaped like MCPInputRequiredError, which chat() recognizes by its name:

const askUser = toolDefinition({
  name: 'ask_user',
  inputSchema: z.object({ questions: z.array(questionSchema) }),
}).server(async ({ questions }, ctx) => {
  if (ctx.inputResponse?.status === 'resolved') {
    return { answers: ctx.inputResponse.payload }
  }
  // Pretend to be an MCP server so chat() pauses the run.
  throw Object.assign(new Error('Input required'), {
    name: 'MCPInputRequiredError',
    kind: 'form',
    request: { questions },
  })
})

That works today, but the shape isn't exported or documented as public API (isMcpInputRequired and McpInputRequiredThrow aren't in the package exports). The client sees an mcp_input interrupt whose payload is unknown, and an upgrade could change the check without notice.

Proposal

A documented way for any server tool to request input, typed by a defineInterrupt definition, with the answer delivered back to the same tool call. For example:

const askUserInterrupt = defineInterrupt({
  id: 'ask-user',
  payloadSchema: z.object({ questions: z.array(questionSchema) }),
  responseSchema: z.object({ answers: z.array(answerSchema) }),
})

const askUser = toolDefinition({
  name: 'ask_user',
  inputSchema: z.object({ questions: z.array(questionSchema) }),
}).server(async ({ questions }, ctx) => {
  const answer = ctx.requestInput(askUserInterrupt, { questions })
  // First call: pauses the run with a typed generic interrupt bound to this tool call.
  // Next run: returns the validated response, or throws if the user cancelled.
  return answer
})

On the client, the same definition types the payload and resolveInterrupt, as with generic interrupts today:

const { interrupts } = useChat({ connection, interrupts: [askUserInterrupt] })

interrupts.map((interrupt) =>
  interrupt.kind === 'generic' && interrupt.definitionId === askUserInterrupt.id ? (
    <QuestionForm
      questions={interrupt.payload.questions}
      onSubmit={(answers) => interrupt.resolveInterrupt({ answers })}
      onCancel={() => interrupt.cancel()}
    />
  ) : null,
)

What it would need

• A public, non-MCP way for a server tool to raise a typed input request bound to its tool call (the mcp_input path, generalized).
• The response checked against responseSchema and handed to the tool on the continuation, including on durable resumes through withPersistence, which today don't fill ctx.inputResponse (Durable resume through withPersistence never fills ctx.inputResponse for mcp_input interrupts #1885).
• A cancelled or expired request reaching the tool as a distinct outcome, so it can tell the model nobody answered instead of asking again.

The MCP input path could then be built on the same primitive.