Proposal: session/inject for mid-turn queue + steer

[kennethsinder]

TL;DR: Two adjacent inputs — queue (buffer for next turn) and steer (deliver mid-turn at next break-point) — have converged across most public coding-agent UIs, but ACP has no surface for either. Filing here per the RFD process before drafting a PR. Looking for a champion who'd like to co-design this as a follow-on to the v2 prompt lifecycle.

What converged

• Queue: Cursor (FIFO since 1.2, forum thread), VS Code's Claude agents, Claude Code (with known issues — flushes at every LLM pause, not true end-of-turn).
• Steer: Codex CLI's Enter-steer (opt-in via /experimental) is the most fleshed-out implementation. The Codex codebase has its own pending-steers queue, requeue-on-turn-complete, pause-on-usage-limits, and a separate stop-reason / replay edge-case surface — see PRs #12569, #15235, #22226, #22879 and issues #19975, #22815.
• The split itself is also discussed cross-ecosystem (langchain-ai/deepagents#1390 "Disambiguate steer/queue", anomalyco/opencode#21388, NousResearch/hermes-agent#6898, anthropics/claude-code#30492, #50246).

ACP today

session/cancel + a fresh session/prompt is the only mid-turn lever, and it discards in-flight context. stopReason has no value for steer-interrupted turns.

The v2 prompt lifecycle RFD already calls out queueing as future work: "Queueing messages (still an ongoing discussion) would also fit much nicer in this pattern... potentially the agent could decide whether it cancels the current turn and inserts it immediately, or inserts it at the next convenient break point." The substrate this needs — short-lived session/prompt, user_message echo notification, state_change running/idle/requires_action — is the v2 prompt lifecycle. So this is intended as a v2 follow-on, not a v1 patch.

Adjacent RFDs in motion that this composes with: message-id (handle for ack and revocation), multi-client attach #533 (who's allowed to inject), session rewind #1214 (destructive-history sibling), turn-complete signal #644 (queue-flush barrier).

Sketch

One method, two modes:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "session/inject",
  "params": {
    "sessionId": "sess_abc",
    "mode": "steer",
    "content": [{ "type": "text", "text": "stop using the legacy auth path, see auth_v2.go" }]
  }
}

Response carries the messageId per the v2 prompt lifecycle pattern. Capability:

{ "agentCapabilities": { "session": { "inject": { "modes": ["queue", "steer"] } } } }

Agent advertises which modes it supports. Streaming-only agent: ["queue"]. Tool-loop agent that can break safely: ["queue", "steer"].

Semantics

• steer: delivered as the next user message at the earliest safe break-point. Mid-tool-call: complete the call, then deliver. Mid-stream with no tool call in flight: agent-defined — interrupt and re-prompt, or finish the stream and deliver.
• queue: buffered, delivered as the next user message after state_change: idle. FIFO.
• Both fire-and-forget; response returns on accept, not on model-process.
• Both echo via user_message notification at the moment of delivery, so multi-client observers see consistent history and session/load replays in order.

Open questions for the discussion

• Revocation: cancel queued message via $/cancel_request on the inject request keyed by messageId? Steered messages once handed to the LLM are not revocable.
• session/cancel interaction: cancel-during-steer ordering — Codex #22815 is a real bug surface if left implicit.
• session/request_permission interaction: while blocked on permission, queue accumulates; steer rejected or queued (agent-defined, capability bit).
• Elicitation interaction: inject is a side-band, not the elicitation answer — orthogonal channels.
• Ordering: FIFO from one client; FIFO by arrival from multi-client attach.
• Sub-agents: inject lands on root session; parent decides whether to pass down. Keeps the protocol out of the sub-agent topology.
• stopReason: existing cancelled for steer-interrupted LLM calls — no new reason needed.
• Content types: full ContentBlock array, same shape as session/prompt.params.prompt.
• Persistence: injected messages part of session history, ordered by acceptance time, replayed by session/load.
• Usage limits: hold pending steers during pause, resume on recovery (Codex PR #22226 is the reference shape).

Looking for

A core-team champion willing to co-design this as a v2 follow-on. Happy to draft the RFD PR once direction is agreed — or rework if a different framing (e.g. two separate methods, or rolling queue into the v2 prompt lifecycle RFD itself) is preferred.

---

Process note: I workshopped this draft with a coding agent for structure and prior-art digging — happy to take feedback on framing, or to hop on Zulip / a call if a maintainer wants to talk it through live.

[benbrandt]

Hi Kenneth! This is a great start! I think you've encapsulated the problem nicely here and I think this is generally going in the right direction (or by right i mean, it matches my gut feeling, having not tried to implement it in ACP yet 😄 )

I'm trying to work out some kinks for the plumbing of v2 so we can start experimenting with the new prompt lifecycle and stuff like this, but if you want to open an RFD I'd be happy to put it in the v2 bucket!

Also happy to hop on a call to say hi and also talk more if you like

[kennethsinder]

Drafted as PR #1261 (docs/rfds/v2/session-inject.mdx). Would love your eyes when you have time, @benbrandt — happy to keep iterating on framing or factoring in the PR thread.

[point-source]

Use-case from Kandev (an ACP client running multiple agents)

+1 on session/inject, and especially on agents advertising session.inject.modes so clients can gate their UI per agent instead of hardcoding assumptions.

The queue vs steer split lines up with what each agent exposes on its programmatic surface today: Codex already offers a non-interrupting mid-turn steer, so it fits steer mode; the Claude Agent SDK doesn't expose one yet — mid-turn input is queued and delivered after the turn, with only a hard interrupt available — so over ACP it fits queue mode for now. Having agents advertise which they support is exactly what we need: without it, a client can't honestly tell an operator whether a typed message will steer the live turn or just wait for it to end.

One adjacent gap: a turn that's idle but held open only by background work (a subagent, a background shell) currently looks the same as an actively-generating turn. A signal for "foreground idle, only background work left" would let clients stop reporting those sessions as busy (see also claude-agent-acp#603).

Happy to test an implementation against Kandev when it lands.

[ofekron]

One implementation detail worth making explicit in the RFD is that acceptance, delivery, and application are three different states.

For queue, an accepted response should mean the agent has durably recorded the input, not that the model has seen it. For steer, delivery means the input crossed a declared safe breakpoint; application means the replacement/continuation turn actually incorporated it. I would model this as a small lifecycle keyed by messageId: accepted → delivered → applied, with terminal cancelled/rejected states. A reconnecting client can then reconcile by messageId instead of guessing from state_change or user_message echoes.

Two edge cases fall out of that model:

• Repeating session/inject after a transport timeout needs an idempotency key, otherwise durable queueing creates duplicates.
• session/cancel should cancel the active turn without silently deleting accepted queue entries; revoking a not-yet-delivered item should be a separate operation with an explicit outcome.

The same distinction has been useful in Better Agent, a local workspace supervising native Claude, Codex, and Gemini sessions: queued operator input is backend-owned and survives UI/backend reconnects, while the UI only reflects acknowledgement and delivery state. The implementation is source-available and free for non-commercial use; commercial use requires separate permission: https://github.com/ofekron/better-agent

AI-assistance disclosure: this comment was drafted by Codex under the maintainer’s authorization and reviewed in Better Agent.