[kennethsinder]

Proposes a v2 RFD for sending a prompt while the Agent is still working, with the Client saying what should happen to it:

• steer: insert at the next safe point in the current turn, so the Agent changes course without starting over.
• queue: hold until the turn ends, then start a new turn with it.

Summary (v2 only):

• New optional delivery: "steer" | "queue" field on session/prompt.
• New session.prompt.delivery.{steer,queue} Agent capability.
• Everything else reuses the v2 prompt lifecycle: the response still means "inserted", $/cancel_request withdraws a pending message, and the response and user_message may arrive in either order.
• No new methods or error codes.

This revision replaces the earlier session/inject, session/revoke_inject, and session/replace_inject design. The v2 prompt lifecycle now covers acknowledgment, IDs, and cancellation, so a separate method would duplicate them. It adopts the session/prompt approach from #2255 and answers that RFD's open question (implicit vs. explicit intent) with an explicit field.

Rendered: docs/rfds/v2/prompt-delivery.mdx. Background: discussion #1220.

[SteffenDE]

Some comments from my side. Don't see me as authoritative here though. Happy to close the promptQueueing PR, as it makes more sense to wait for v2 to land.

[SteffenDE]

It doesn't address steer, doesn't define delivery semantics

I'd say this is not a correct representation of that PR.

promptQueueing was always meant to be steering. If you just want to queue for sending after the current turn, this is trivial to implement by ACP clients.

The early end_turn was the signal to the client when the new message was injected into the context.

[kennethsinder]

Fair pushback, that was a sloppier read than I should have given #484. Rewrote the paragraph to call your early-end_turn what it is: a steer-via-yield design where the agent yields and the client's parallel session/prompt becomes the next turn. The honest delta vs. this RFD is that yield-and-re-prompt forces a turn boundary at every steer, so a tool call mid-stream surfaces as completing a turn instead of being absorbed, and the client drives the re-prompt rather than handing the agent a payload. Both reach steer; the trade-offs differ.

[SteffenDE]

Just as a note: this won't work for the Claude Agent SDK, because it will only generate the id at the point of delivery. In practice, this means that ACP message IDs would be an adapter concern, requiring the ACP code to store its own state persistently somewhere in order to get the same IDs for later loads.

We already have similar problems for message IDs in streaming chunks, so at some point this is probably inevitable.

[kennethsinder]

Yeah, this is the part where I think the adapter has to pay the cost and we should just say so out loud. Added an FAQ explicitly addressing it: the wire ID has to come back synchronously, so any adapter bridging to an SDK that doesn't expose a pre-delivery ID needs to mint a wire ID at accept-time and remember the mapping until the underlying SDK delivers. Same shape as the streaming-chunk situation message-id already accepts. The two alternatives (client-provided ID, deferred ID-on-delivery) are worse for different reasons that the FAQ spells out.

[SteffenDE]

Maybe worth discussing if this needs to be part of ACP in the first place, as clients need to implement logic for displaying queued messages anyway, so adding the logic to buffer those client-side and do regular prompt on end_turn might be enough and keeps the protocol smaller. No strong opinions on my side there though.

[kennethsinder]

Good question and one I went back and forth on. Added a dedicated FAQ ("Does queue need to be in the protocol at all?") that tries to be honest about it: for one client driving one agent, you're right, client-side buffering covers the user-visible behavior and the protocol stays smaller. The cases I think justify the protocol-level queue are multi-client fan-out (with #533, the agent has to be the ordering authority because client-side queues can't agree on FIFO), session/load reconnect (a queue at the agent survives client restart), and headless agents serving multiple thin surfaces. Open to dropping it if the consensus is that those cases are too speculative for v2.

[SteffenDE]

This doesn't seem clear to be. Is revoke required or not? Can an agent omit pending and therefore signal that revoke is not supported?

[kennethsinder]

Good catch, the wording was vague. Tightened it: revoke is mandatory if you support session/inject at all. Any agent that can accept a pending inject can drop one before delivery; worst case is a tombstone flag plus skipping the user_message emit. Replace stays opt-in via pending.replace because content editing is genuinely harder than dropping (the content may already be partially serialized into a prompt envelope by the time the replace lands). The asymmetry is now spelled out instead of implied.

[SteffenDE]

or has irrevocably queued

I'd say an agent should always emit the user_message at the point where it belongs in the chat. If a message is only "irrevocably queued" meaning that is can't be edited any more, but belongs to a later point in history, I'd say that should be an error on revoke / replace.

[kennethsinder]

Agreed, that hedge created a state that doesn't actually exist on the wire. Tightened the definition: delivery is exactly the user_message emission. Before that, revoke succeeds. At or after that, revoke returns already_delivered. Any internal commit the agent does before emitting is purely for its own bookkeeping.

[SteffenDE]

Agents that prefer to drop steers during permission waits may do so, capability-advertised.

I'd drop that. If an Agent (SDK) can't handle this, the ACP adapter code should buffer rather than just dropping. But maybe I'm misunderstanding the point.

[kennethsinder]

Fair, that carve-out was a cop-out and pushed work onto agents that should sit in the adapter. Removed it. The spec is now uniform: pending steer is held during a permission wait and delivered at the next break-point after the decision resolves. If the underlying runtime can't hold it, the ACP adapter buffers. No capability flag for this.

[kennethsinder]

Thanks for the careful review, @SteffenDE! Replied to each thread inline. Quick summary of what changed in 48a629f + c3c9980:

• Reframed the comparison with docs(rfd): prompt queueing RFD #484 to acknowledge its early end_turn as a legitimate steer-via-yield design, and articulated the actual trade-off (forced turn boundary at every steer vs. absorb-into-running-turn).
• Made revoke mandatory; replace stays opt-in via pending.replace. Asymmetry explained.
• Dropped the "irrevocably queued" hedge. Delivery is now defined strictly as user_message emission; no phantom intermediate state.
• Dropped the agent-may-drop-steers-during-permission carve-out. Adapter buffers when the underlying runtime can't.
• New FAQ on the adapter burden for messageId (the Claude Agent SDK case): the wire ID has to come back synchronously, adapter mints + maps, same shape message-id already accepts for streaming chunks.
• New FAQ on why queue is in the protocol rather than client-side only: multi-client FIFO ordering authority, replay/reconnect, headless agents serving multiple thin surfaces.
• Prose pass: tightened em-dashes to colons where natural, eased back on rule-of-three flourishes, removed "not X. It is Y" constructions to match the tone of the v2 prompt lifecycle RFD.

Open to more rounds. The biggest open design question I think is the queue itself: whether the multi-client / replay / headless cases justify protocol-level standardization at v2 stabilization time, or whether it's cleaner to ship steer alone and let queue land later once #533 firms up.

[htahaozlu]

Thanks for the clean factoring here, @kennethsinder — the inject-vs-rewind split you drew in #1220 held up, so I leaned on it.

I've re-based the session-rewind proposal onto the v2 prompt lifecycle and filed it as the "Truncate/Edit support" item from the v2 overview's "RFDs to be Written" list: #1321 (docs/rfds/v2/session-rewind.mdx). It supersedes my earlier v1-substrate draft (#1214).

The two line up the way you framed them:

• inject = additive — adds a user_message, never touches prior history.
• rewind = destructive — session/rewind truncates the tail, session/edit_prompt rewinds + re-runs.

Both ride the same substrate (agent-owned messageId, user_message echo, state_change). Inject reuses user_message; rewind adds one symmetric notification, history_truncated, for the removal case so multi-client and session/load replay converge. Capabilities (session.inject vs session.rewind) and flags don't collide, and they compose — inject a correction mid-turn, or rewind to redo the turn.

@benbrandt — since the v2 overview already lists Truncate/Edit as a to-be-written RFD, happy to iterate framing in the rewind PR thread, and glad to align it with however the prompt-lifecycle unstable/_meta flagging shakes out.

[kennethsinder]

Rebased this onto the current main and resolved the docs/docs.json v2 RFD nav conflict.

Validation on the rebased branch:

node -e 'JSON.parse(require("fs").readFileSync("docs/docs.json","utf8")); console.log("docs.json ok")'\nnpx prettier --check docs/docs.json docs/rfds/v2/session-inject.mdx\n```

[xxchan]

Production feedback from Raft: this RFD is not a nice-to-have for us; the absence of steering is currently an adoption blocker for ACP.

Raft is a multi-agent collaboration platform. A core interaction is that a user can send a correction or additional context from another client/channel while an agent is still executing. Waiting until the current turn becomes idle is too late for a correction, while the only standard ACP fallback today, session/cancel followed by a new session/prompt, discards in-flight work and reports tool calls as cancelled. We need a capability-advertised way to deliver a user message at the next safe breakpoint without ending the running turn.

This is now blocking a concrete runtime integration. Grok's public programmatic surfaces are ACP over stdio and WebSocket. We tested the current Grok CLI (0.2.93): a concurrent session/prompt is queued until the active turn completes; session/cancel plus a new prompt only provides abort-and-redirect; and Grok's private TUI interjection path is not registered on either public ACP transport. As a result, we cannot offer the same live correction contract that we can offer through Codex app-server's turn/steer.

Because of this gap, we have stopped treating ACP as a sufficient canonical runtime abstraction for Raft, and we cannot ship a production-quality Grok runtime through ACP today without explicitly degrading steering to destructive cancellation. This is exactly the kind of fragmentation ACP should remove: the runtime supports interjection internally, but the shared protocol cannot express it.

Strong +1 from an implementer/operator for moving session/inject forward. Could a maintainer champion this RFD and clarify the v2 path/timeline? If protocol-level queue semantics are holding up consensus, our experience argues for landing a steer-only capability first (even as an unstable v2 extension) and allowing queue/revoke/replace semantics to follow. The minimum useful contract for us is steer acceptance, delivery at a safe breakpoint, capability negotiation, and an observable user-message/history event.

We are happy to provide our Grok/ACP probe results and implementation feedback against a narrowed proposal.

[ChrisAkre]

I found this proposal yesterday and I implemented a copilot sdk -> acp bridge that added session/inject capability and it is an utterly massive quality of life improvement.

On the slim chance this RFD is rejected, there is zero chance I'm ever going back to an ACP protocol without it.

(note my usecase is a ACP<->websocket bridge that supports multi-client fanout so you can control multiple harnesses on multiple devices concurrently)

[kennethsinder]

^ That is so cool, thanks everyone for sharing the love and helping shape this <3 cc @benbrandt let me know if I missed any comms from you or anything that I can provide to help smooth this proposal along, sorry for the radio silence the last few weeks!

[danielkov]

I implemented the RFD’s session/inject in our ACP-based harness: Kit and plumbed it through the protocol schema, Rust SDK:

• Protocol schema: feat(unstable-v2): add session injection schema #2043
• JSON-RPC response ordering: feat(jsonrpc): add tracked response receipts rust-sdk#338
• Rust SDK injection support: feat(unstable-v2): add session injection support rust-sdk#339
• agentkit implementation: feat(acp): add unstable v2 session injection danielkov/agentkit#13
• Kit integration: feat(acp): add v2 mid-turn steering speakeasy-api/kit#24

The implementation currently supports steer with finish behavior and revoke. Accepted messages are delivered FIFO after the current model stream or tool call finishes, and before the next model request.

One issue I ran into was ensuring the successful inject response is sent before the corresponding user_message delivery notification. In batched JSON-RPC responses, the full batch must be ready first. I added tracked response receipts in agentclientprotocol/rust-sdk#338 to provide that ordering.

Feedback appreciated!

[mintlify]

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit ee193af.

Approve preview

[kennethsinder]

I've rebuilt this RFD on the current v2 prompt lifecycle and rebased it onto main.

What changed. Since May, v2 made the session/prompt response mean "inserted" and defined cancelling a prompt before insertion. That covers most of what session/inject had to define on its own. So the proposal is now an optional delivery: "steer" | "queue" field on session/prompt, plus a capability. Withdrawing a pending message is $/cancel_request. There are no new methods or error codes. This follows the approach in @uzayer's #2255, with an explicit field instead of implicit steering, for the reason in the first FAQ.

@danielkov, thank you for implementing the earlier draft in Kit and for the ordering report. The RFD now follows the existing v2 rule: the response and the user_message update may arrive in either order, and Clients match them by messageId. Sending the response first is allowed, not required, so the receipt tracking in agentclientprotocol/rust-sdk#338 becomes optional. Moving Kit to the new shape should mostly mean reading delivery on session/prompt instead of a separate method, and handling $/cancel_request instead of session/revoke_inject.

@mkorun, thanks for the four-agent comparison. It matches the RFD's choices: the Agent picks the safe point, it may cut a streaming response short to insert sooner (the Codex behavior), and an adapter can mint its own messageId for SDKs that assign one only at delivery (the Claude Code case).

@benbrandt, this is now a small addition on top of the v2 prompt work: one request field and one capability. Would you be willing to champion it into Draft, or point me to who would be? I'm happy to merge it with #2255 into a single RFD if that's easier to review.