[DOCS] CLI `--output-format stream-json` lacks event type reference

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/headless

Section/Topic

"Run Claude Code programmatically" page > "Stream responses" section.

Current Documentation

The current streaming section shows one example:

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

And states: "Each line is a JSON object representing an event."

The section also includes a cross-link:

For programmatic streaming with callbacks and message objects, see Stream responses in real-time in the Agent SDK documentation.

What's Wrong or Missing?

The documentation shows how to filter for text_delta events but doesn't document what event types exist. A developer trying to build a streaming consumer needs to know:

1. What message types can appear? The jq example mentions .type == "stream_event" but what other top-level types are there? (e.g., system, assistant, result, user)
2. What stream_event subtypes exist? The example shows content_block_delta with text_delta, but what about message_start, content_block_start, content_block_stop, message_delta, message_stop, input_json_delta?
3. What's the message flow? In what order do events appear during a typical response?
4. How are tool calls represented? Do they stream as input_json_delta events? How do you know when a tool starts and finishes?

The Agent SDK documentation has a thorough StreamEvent reference (platform.claude.com/docs/en/agent-sdk/streaming-output) with an event type table, message flow diagram, and examples for streaming both text and tool calls. The CLI docs should either provide equivalent coverage or explicitly link to the SDK streaming docs.

Suggested Improvement

Option A (preferred): Add an "Event types" subsection to the CLI streaming section with:

• A table of event types (system, stream_event, assistant, result)
• A table of stream_event subtypes (message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop)
• The message flow order (same diagram from the SDK streaming-output.md page)
• An example of streaming tool calls via CLI

Option B (partially implemented): The headless page now links to the Agent SDK streaming-output page. However, the link text says "For programmatic streaming with callbacks and message objects" which doesn't signal that it contains the event type reference. A more explicit cross-link would help, e.g., "For the complete event type reference, see Stream responses in real-time."

Impact

Medium - Makes feature difficult to understand

Additional Context

The Agent SDK streaming-output.md page already has excellent documentation for this, including a StreamEvent reference table, message flow diagram, and examples for text streaming, tool call streaming, and building a streaming UI. The CLI docs just need to either replicate or link to this content.

Note: This issue overlaps with issue 0012 (document all message types emitted by stream-json). This issue focuses on the stream_event subtypes (which the SDK docs already cover), while issue 0012 covers all top-level message types (system, assistant, stream_event, result) which are not documented anywhere. Consider whether both should be submitted or if 0012 subsumes this one, especially since the cross-link to SDK streaming docs partially addresses this issue's minimal fix.