[FEATURE] Enhanced Streaming Interrupt Mechanism with Graceful Cleanup

Summary

Implement an enhanced interrupt mechanism for streaming agent responses that provides better control, cleanup handling, and user feedback during long-running operations.

Current Behavior

Based on the existing Claude Agent SDK:

• The interrupt() method exists and can stop active agent runs
• However, there's limited control over the interrupt process during streaming
• No hook exists to detect when a user manually interrupts the agent (related to #9516)
• Cleanup and state management after interruption is not well-defined

Proposed Enhancement

1. Graceful Interrupt with Cleanup Hooks

Add lifecycle hooks for interrupt events:

agent.onInterruptStart((context) => {
  // Called immediately when interrupt is requested
  console.log('Interrupting agent...');
});

agent.onInterruptComplete((context) => {
  // Called after interrupt is fully processed
  // Includes partial results if available
  console.log('Interrupt completed', context.partialResult);
});

2. Interrupt State Management

Provide clear state tracking during interrupt:

const status = await agent.getInterruptStatus();
// Returns: { isInterrupting: boolean, progress: number, canResume: boolean }

3. Partial Result Preservation

When an agent is interrupted during streaming, preserve partial results:

const result = await agent.interrupt({ preservePartialResults: true });
// Returns partial output, tool uses, and execution state

4. UI Integration Support

Provide built-in support for interrupt UI patterns:

// Hook for updating UI during interrupt
agent.onInterruptProgress((progress) => {
  updateProgressBar(progress.percentage);
});

Use Cases

1. Long-running analysis: User wants to stop a complex database query analysis midway
2. Streaming chat: User wants to stop a lengthy response to ask a clarification
3. Resource management: System needs to interrupt agent due to timeout or resource constraints
4. Error recovery: Gracefully handle interrupts during error states

Related Issues

• #9516 - User Interrupt Hook (this would extend that functionality)

Technical Considerations

• Ensure interrupt is atomic and doesn't leave agents in inconsistent state
• Support both Python and TypeScript SDKs
• Maintain backward compatibility with existing interrupt() method
• Consider impact on streaming modes vs single-shot mode

Benefits

• Better UX for long-running operations
• Cleaner state management
• Easier debugging and logging
• More control for developers building agent-based applications

Implementation Priority

Medium-High - This affects developer experience and application reliability in production scenarios.

---

References:

• Streaming Input Documentation
• Building agents with Claude Agent SDK
• Issue #44 - Streaming Text Deltas Pause