Docs: prompt-turn page lists 5 SessionUpdate variants, schema v1 defines 11

[azuriru3]

What happened

I built an ACP client for Grok Build (grok agent stdio) working from the
prose docs at agentclientprotocol.com. The prompt-turn page presents these
sessionUpdate values for session/update notifications:

plan, agent_message_chunk, tool_call, tool_call_update, usage_update

I treated that list as exhaustive. The first real session immediately
delivered two more:

• user_message_chunk (echo of the submitted prompt, with _meta: {modelId, promptIndex})
• available_commands_update (fired twice after session/new)

I initially logged these as vendor deviations. They are not: both are
defined in schema/v1/schema.json, which has 11 variants in the
SessionUpdate union:

user_message_chunk, agent_message_chunk, agent_thought_chunk,
tool_call, tool_call_update, plan, available_commands_update,
current_mode_update, config_option_update, session_info_update,
usage_update

So a client author following the prose page implements 5 of 11 and then
misdiagnoses spec-conformant traffic as off-spec behavior. Captured
traffic and notes: https://github.com/azuriru3/grok-build-vscode/blob/main/docs/ACP-NOTES.md

Suggested fix

1. List all schema-defined variants on the prompt-turn page, or add a
   pointer that the page shows a common subset and the schema is the
   authority.
2. Add one sentence advising clients to treat the variant set as open for
   forward compatibility. The extensibility page covers unknown methods and
   notifications, but not unknown variants inside session/update, and
   that is where a closed switch bites in practice.

Secondary question, happy to split into its own issue

What is the intended way for an agent to report an upstream provider
failure mid-turn? StopReason has no failure value, which suggests a
JSON-RPC error on session/prompt. That is what Grok Build does:

{"jsonrpc":"2.0","id":3,"error":{"code":-32603,"message":"Internal error","data":{"message":"API error (status 403 Forbidden): permission-denied: ...","http_status":403}}}

If a JSON-RPC error is the intended mechanism, a sentence saying so in the
prompt-turn page's stop-reason section would remove the ambiguity.