docs(rfd): propose a prompt_suggestions session update

[nikita-ashihmin]

Elevator pitch

Agents increasingly predict a plausible next prompt at the end of a turn — the transcript is already in context and the prediction rides the same prompt cache — and editors already have the surface for it: the empty composer that shows grayed-out text, completes on Tab, and drops it on Escape or the first keystroke. ACP has no event for that value, so every Agent–Client pair invents its own channel.

This RFD proposes a prompt_suggestions variant of SessionUpdate for v1 and v2:

{
  "sessionUpdate": "prompt_suggestions",
  "suggestions": [{ "text": "Run the test suite and fix what breaks" }]
}

• An ordered list, most likely first; each update replaces the set whole.
• An empty list withdraws the offer. The Client may also drop it locally, and must never offer a suggestion from before the most recent prompt it sent.
• Accepting a suggestion fills the composer and must not send it — the user stays the author of every prompt in the transcript.
• Not conversation history: it should not appear in replay or session/load.
• A turn that ends with no suggestion is normal (first turn, API error, rate limit), so a Client must not wait for one.

In v1 a ClientSessionCapabilities.promptSuggestions capability gates the event. Unlike notices, there is no fallback channel behind it — the capability exists so an Agent knows whether asking the model for a prediction is worth anything at all. V2 relies on its unknown-update fallback.

Why now

The shape is not hypothetical: it already runs in production as session_info_update._meta.promptSuggestions between the JetBrains AIR Client and the Claude Agent adapter (claude-agent-acp#1356) — with a deliberately vendor-neutral key, which is a fair sign it wants to be protocol — and Codex has an open request for the same feature (openai/codex#42587). Standardizing it now avoids a second incompatible implementation of the same idea.

The FAQ covers why this is not a field on session_info_update (it must stay aligned with SessionInfo, and a prediction has no place in a session listing), why it is a list, why there is no "the Agent is still deciding" state, and why acceptance is not reported back.

Docs only: the RFD plus its navigation entry. Prettier and spellcheck are clean.

Generated with Claude Code
via Happy