feat(interrupt): implement interrupt system for human-in-the-loop workflows

[zastrowm]

Motivation

Agents executing tools often need to pause for human approval or input before proceeding with sensitive operations like financial transactions, data modifications, or external API calls. Without a built-in interrupt mechanism, developers must implement custom solutions to handle these human-in-the-loop workflows.

This implementation adds a comprehensive interrupt system that allows agents to:

• Pause execution at specific points (before individual tool calls, before batch tool execution, or within tool callbacks)
• Return interrupt details to the caller for user interaction
• Resume execution with user responses

Resolves #479

Public API Changes

New interrupt() method on hook events and tool context

Tools can now call interrupt() to pause execution:

const tool = new FunctionTool({
  name: 'transfer_money',
  description: 'Transfer money between accounts',
  callback: async (input, context) => {
    if (input.amount > 1000) {
      context.interrupt({
        name: 'confirm_transfer',
        reason: `Confirm transfer of $${input.amount}?`
      })
    }
    return { success: true }
  },
})

Hooks can also trigger interrupts:

agent.addHook(BeforeToolCallEvent, (event) => {
  if (event.toolUse.name === 'dangerous_operation') {
    event.interrupt({
      name: 'safety_approval',
      reason: 'This operation requires approval'
    })
  }
})

New stopReason: 'interrupt' and interrupts array on AgentResult

When an interrupt is triggered, the agent returns immediately:

const result = await agent.invoke('Transfer $5000')
if (result.stopReason === 'interrupt') {
  console.log(result.interrupts) // [{ name: 'confirm_transfer', reason: '...' }]
}

Use Cases

• Financial transactions: Require approval before processing large transfers
• Data modifications: Confirm destructive operations before execution
• External integrations: Validate API calls to third-party services
• Security-sensitive operations: Add human verification for privileged actions

[github-actions]

Encapsulation Refactor Complete

Addressed the second feedback item in commit 070b5de.

Change

Moved the pending execution reconstruction logic into InterruptState.getPendingExecution() method:

// New method signature
getPendingExecution(): { 
  assistantMessage: Message
  completedToolResults: Map<string, ToolResultBlock> 
} | undefined

Result

The agent code is now cleaner and the reconstruction logic is encapsulated in the InterruptState class where it belongs.

All 1862 tests pass.

[github-actions]

Review Summary - Follow-up Review

Assessment: Approve

All previous feedback has been addressed. The implementation is now complete with proper exports, comprehensive resume flow tests, and the maintainer-requested improvements for skipping model re-invocation on resume.

Changes Since Previous Review

Addressed Issues:

• ✅ Exports: Interrupt, InterruptError, InterruptState, and related types now exported from src/index.ts
• ✅ Resume Tests: Comprehensive E2E tests added covering interrupt → response → continue flow, including partial execution resume
• ✅ Code Duplication: _createInterruptResult() helper method consolidates interrupt result creation
• ✅ Maintainer Feedback: Resume without model re-invocation implemented with getPendingExecution() encapsulation

Documentation Note

This feature adds significant public API surface. Consider a follow-up documentation PR covering:

• interrupt() method on tool context and hook events
• stopReason: 'interrupt' and interrupts array on AgentResult
• Resume flow with InterruptResponseContent

Well-designed interrupt system that aligns with SDK tenets—simple API entry points, extensible through hooks, and composable with existing patterns.

[github-actions]

Review Summary - Third Review

Assessment: Approve (No changes needed)

The changes since my last review are all improvements - test consolidation following guidelines, better encapsulation (_interruptState now private), generic interrupt<T>() for type safety, and the new isInterruptResponseContent type guard.

All previous feedback remains addressed. Ready to merge.

[zastrowm]

Moved over to #784