[Feature]: Human-in-the-loop interrupt/resume support in Claude Agent SDK integration

[Sri01728]

Pre-flight Checklist

• I have searched existing issues and this hasn't been requested yet.

Problem or Motivation

The AG-UI protocol (ag-ui-protocol 0.1.19) defines the interrupt/resume contract: RunFinishedInterruptOutcome, Interrupt, ResumeEntry, and RunAgentInput.resume. However, the Claude Agent SDK integration (ag-ui-claude-sdk, latest 0.1.5, and main) never emits or consumes these types. The only interrupt in adapter.py/session.py is interrupt(thread_id), which cancels the running query. There is no way to pause a Claude run on a tool call, surface a response schema to the client, and resume the same loop with a client-supplied payload.

This blocks the canonical human-in-the-loop use case — tool-approval gating — where the model proposes a mutating tool call and a human must approve (or edit args) before it executes. Today integrators have to build bespoke enforcement (e.g. PreToolUse deny + an out-of-band approval surface + a durable ledger + arg replay) instead of using the protocol's first-class interrupt outcome.

Proposed Solution

Wire the existing protocol types into the Claude adapter:

1. When a run needs human input (e.g. a PreToolUse/tool-gate signal), pause the underlying Claude query and emit RunFinishedEvent with RunFinishedInterruptOutcome containing one Interrupt per pending item (carrying toolCallId and a responseSchema).
2. On the next RunAgentInput, read resume: List[ResumeEntry], match each interrupt_id, and re-enter the paused loop — applying the resume payload (approve / reject / edited args) to the corresponding tool call.
3. Emit the tool result against the original toolCallId so the audit trail spans proposal -> resume -> result.

Alternatives Considered

• Building enforcement below the SDK via PreToolUse deny + retry with updatedInput, plus an out-of-band approval UI. This works, but is non-standard, doesn't produce protocol-level interrupt events, and accumulates edge-case complexity (cross-surface arg replay, at-most-once semantics) that a first-class interrupt/resume loop would obviate.
• Upgrading ag-ui-protocol to 0.1.19 alone — insufficient, since the adapter doesn't use the new types.

Additional Context

• Protocol support present as of ag-ui-protocol 0.1.19 (ag_ui/core/events.py, ag_ui/core/types.py).
• Adapter gap confirmed on main: integrations/claude-agent-sdk/python/ag_ui_claude_sdk/{adapter,session,handlers}.py — no resume / outcome / RunFinishedInterruptOutcome references.
• Happy to contribute a PR if the maintainers agree on the shape.

[Sri01728]

One thing worth surfacing before anyone writes code here: the Claude adapter on main already contains a de-facto interrupt/resume mechanism — it just isn't typed as AG-UI interrupts yet.

The existing halt path

When the model calls a frontend tool, _stream_claude_sdk sets halt_event_stream = True, breaks the SDK message loop, and the run finishes. The client is then expected to execute that tool and return its result on the next RunAgentInput (via a tool-result message). See ag_ui_claude_sdk/adapter.py:

• frontend_tool_names detection + halt on the streaming path (is_frontend_tool -> halt_event_stream = True)
• the same halt on the non-streaming block path (block_display_name in frontend_tool_names -> halt_event_stream = True; break)
• the loop guard at the top of _stream_claude_sdk that breaks when halt_event_stream is set

That is structurally the same "pause the run, hand control to the client, resume on the next input" flow that RunFinishedInterruptOutcome / RunAgentInput.resume describe in ag-ui-protocol 0.1.19. Today it's expressed as an untyped frontend-tool convention rather than a first-class interrupt outcome.

Why that matters for this feature

The gap for human-in-the-loop (e.g. tool-approval gating) isn't "add a pause primitive from scratch" — it's mostly a typing/semantics question on top of the halt path that already exists:

1. Is a HITL interrupt just a frontend tool that carries a responseSchema, or a distinct concept? The existing halt seam could plausibly emit RunFinishedInterruptOutcome with one Interrupt per pending tool call (carrying toolCallId + responseSchema) instead of a plain RunFinishedEvent.
2. How should RunAgentInput.resume coexist with the current tool-result-message replay? On resume there's no resume[] parsing today; the client replays via a tool-result message. Adding resume handling means deciding whether it supersedes or complements that path.
3. Concurrency invariants. run() has run-admission serialization, per-run result keying, and refcounted workers with several "defense-in-depth / unreachable" branches. Any new run-terminal outcome has to thread every finally/except path so serialization isn't silently broken.

Proposal

Rather than a speculative diff, it'd be great to get maintainer direction on (1) and (2) first. If the preferred shape is "interrupt = halt path + typed outcome + resume[] parsing," I'm happy to put up a PR building on the existing halt_event_stream seam (behind a flag, with tests). Wanted to align on semantics before writing it, since the concurrency-sensitive parts make the design the expensive bit, not the code.

[Sri01728]

Opened #2181 (draft) implementing this — bridges the Claude SDK defer primitive to the AG-UI interrupt/resume contract, following LangGraph's translation pattern. Gated behind an opt-in emit_interrupt_outcome flag for back-compat.

[hegu-1]

The protocol types are already close to the right abstraction. The missing contract is that an interrupt is durable workflow state, not only a UI pause.

For tool approval I would make the lifecycle explicit:

proposed -> pending_judgment -> approved/rejected/expired -> executing -> executed/failed

Each Interrupt should bind the original toolCallId, canonical argument digest, run/checkpoint id, policy version, expiry, and required approver scope. Each ResumeEntry should carry a decision id and operation id. The adapter must reject duplicate, expired, mismatched, or already-consumed resumes.

Two invariants matter:

1. Resume never changes the proposed action silently. Edited arguments create a new proposal/digest.
2. An approved resume is at-most-once. After a crash, the adapter reconciles the operation id before retrying execution.

The client presents the decision surface; the server-side runtime remains the authority that validates and consumes the grant. The resulting decision and tool outcome should share one audit correlation id.

This workflow contract maps closely to the durable orchestration and governance templates here: https://github.com/hegu-1/enterprise-ai-os-architecture/tree/main/layers/06-orchestration

[Sri01728]

Really like this framing, and agree an interrupt is durable workflow state, not just a UI pause. Since this affects every adapter, not just Claude, I'd rather build to the right contract than guess.

Two scopes I see:

• Adapter bridge (this PR, feat(claude-agent-sdk): bridge defer to AG-UI interrupt/resume #2181): translate the Claude defer/DeferredToolUse halt into RunFinishedInterruptOutcome + consume resume[], with frozen args (a resume can't silently change the proposed action; edited args would have to be a new proposal).
• Governance contract (protocol + runtime): the richer lifecycle and binding metadata (canonical arg digest, policy version, approver scope, operation/decision ids, expiry, reject-on-duplicate/expired/consumed) plus at-most-once reconciliation. These are fields on Interrupt/ResumeEntry and runtime-side enforcement shared across every adapter, so an adapter can't add them unilaterally.

@jpr5 @mme how would you like to sequence this? Land the minimal adapter bridge first and layer the governance contract at the protocol level, or define the fuller Interrupt/ResumeEntry shape now so adapters implement against it from the start? Happy to do the Claude adapter work either way and keep it compatible with a fuller contract.

cc @Sri01728