Typed interrupt/resume contract: should Interrupt/ResumeEntry carry durable-workflow-state, and what resume seam do adapters implement against?

[contextablemark]

Background

The protocol already defines the interrupt/resume types (RunFinishedInterruptOutcome, Interrupt, ResumeEntry, RunAgentInput.resume) as of ag-ui-protocol 0.1.19. Today Interrupt carries id, reason, message, tool_call_id, response_schema, expires_at, metadata; ResumeEntry carries interrupt_id, status (resolved | cancelled), payload.

Two things prompted this:

• [Feature]: Human-in-the-loop interrupt/resume support in Claude Agent SDK integration #2180 / feat(claude-agent-sdk): bridge defer to AG-UI interrupt/resume #2181 — an effort to bridge the Claude Agent SDK defer primitive into this contract, which surfaced that adapters currently have no shared guidance on how to express a resume verdict, so each would invent its own convention.
• @hegu-1's framing in [Feature]: Human-in-the-loop interrupt/resume support in Claude Agent SDK integration #2180 — that an interrupt is durable workflow state, not just a UI pause, and should bind enough metadata to be governed safely.

Because Interrupt/ResumeEntry are shared across every SDK (Python, TypeScript, .NET + protobuf, Go, Kotlin, Ruby) and every adapter, this is a protocol-contract decision, not something an adapter can settle unilaterally. Hence a Discussion rather than a PR.

Question 1 — Should the contract carry durable-state / governance fields?

@hegu-1 proposed a lifecycle (proposed → pending_judgment → approved/rejected/expired → executing → executed/failed) with each Interrupt binding: original tool_call_id (exists), canonical argument digest, run/checkpoint id, policy version, expiry (expires_at exists), required approver scope; and each ResumeEntry carrying a decision id and operation id — plus runtime invariants:

1. Resume never silently changes the proposed action (edited args ⇒ a new proposal/digest).
2. An approved resume is at-most-once (crash reconciliation via operation id before retrying execution).
3. The decision and the tool outcome share one audit-correlation id.

These would be additive/optional fields, so they're wire-backward-compatible whenever they land. The real question is governance: do we want these to be first-class, spec'd fields with defined enforcement semantics — so adapters implement uniformly from the start — or do we keep the minimal shape and let it evolve per-need? What's the smallest set worth committing to now?

Question 2 — What is the standard resume seam adapters implement against?

Independent of the fields: when a client sends a ResumeEntry, how should an adapter apply the verdict to the paused run? Frameworks differ (LangGraph resumes from persisted checkpoint state; the Claude SDK's defer replays a frozen tool call through a hook on --resume; the .NET runtime has yet another model). We should define the contract the client sees (how an interrupt id maps to a resume, what payload may/may not do — e.g. can it edit args, or does an edit require a new proposal) so behavior is consistent across adapters and clients don't have to special-case each backend.

Constraints / non-goals

• Keep additions optional and wire-backward-compatible.
• Don't standardize an accidental convention: e.g. deriving an interrupt id as interrupt_<tool_call_id>, or requiring a client's tool hook to query adapter-private state — these emerged in the Claude bridge exploration and shouldn't become de-facto standard without intent.
• This is orthogonal to Deferred tool resume executes pending tool without re-running Python SDK callback PreToolUse hook anthropics/claude-agent-sdk-python#993 (an upstream bug where a resumed in-process PreToolUse callback doesn't re-fire), which independently blocks the Claude defer-based approach regardless of what we decide here.

Ask

Maintainer direction on Q1 and Q2, and input from adapter authors on how each framework's native halt/resume would map to the chosen contract. Once there's a shape, the Claude bridge (#2181) and any other adapter can implement against it.

[uesleilima]

Thanks for framing this as a protocol-level contract question — we've hit both seams while integrating LangGraph with AG-UI, so sharing what worked (and where we currently diverge from the typed interrupt/resume surface).

Resume seam (Q2) — LangGraph adapter experience

On LangGraph, the durable halt is the checkpoint + interrupt(); the resume seam is Command(resume=…). In our adapter we treat that as the authority, then project into AG-UI events for the client.

Practical lessons that we'd want any shared contract to accommodate:

1. Resume must not be inferred solely from message-count / ID heuristics. When an interrupt is active, the checkpoint often contains AI/tool-call messages the frontend never rendered. Diff-based prepare_stream logic can mis-classify that as a regenerate/time-travel and destroy interrupt state. We short-circuit to the Command(resume=…) path when an interrupt is parked and a resume value is present.
2. Clients do not always send a formal resume. For frontend tools, some UIs submit results as ToolMessages in messages[] rather than a typed resume payload. We currently detect that case and synthesize a resume so the graph unblocks — useful, but it is application behavior, not something the protocol should leave unspecified.
3. Identity correlation matters. Prefer carrying the original tool_call_id on the interrupt value so the client can round-trip it. When streaming emits a different id than the checkpoint (we've seen this around text→tool_call transitions), matching by tool name alone becomes a fragile fallback.

Durable / governance fields (Q1)

Optional additive fields for at-most-once / audit correlation would help. From production use, the minimum that felt load-bearing was:

• stable interrupt id (not derived ad hoc as interrupt_<tool_call_id> without saying so)
• tool_call_id binding
• expiry / cancellation semantics
• a resume verdict that cannot silently rewrite proposed args (edit ⇒ new proposal)

We're less sure the full judgment lifecycle needs to be first-class on day one; adapters can carry richer policy metadata in optional metadata if the core stays small.

Explicit divergence from the current typed contract

Today our wire path still largely follows the older LangGraph AG-UI convention:

• interrupt surfacing via CUSTOM / on_interrupt (then converted to TOOL_CALL_* for frontend tools), and
• resume via forwardedProps.command.resume

rather than exclusively through the newer first-class Interrupt / ResumeEntry / RunAgentInput.resume shapes from ag-ui-protocol ≥ 0.1.19.

That is a conscious interim divergence, not a recommendation. Once adapters have a shared resume seam and field set, we'd prefer to migrate onto the typed types and treat forwardedProps as escape-hatch only.

Happy to refine this against a concrete proposed schema if useful.