[FEATURE] Document all message types emitted by `claude -p --output-format stream-json`

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When using claude -p --output-format stream-json, the CLI emits NDJSON messages with various .type values. The documentation shows one filtering example (stream_event with text_delta) but doesn't document the complete set of message types, their schemas, or when they appear.

Developers building automation on top of claude -p need to know what messages to expect so they can:

• Build robust parsers that handle all message types
• Track session state (init, streaming, tool calls, results)
• Display progress information (token counts, cost, tool execution)
• Handle errors and edge cases

Without a schema reference, developers must either trial-and-error their way through the output or read the Agent SDK TypeScript type definitions.

Proposed Solution

Add a reference page or section documenting all message types emitted by claude -p --output-format stream-json. For each type, document:

1. The .type value (e.g., system, assistant, stream_event, result)
2. The .subtype value if applicable (e.g., init, compact_boundary)
3. The JSON schema / key fields
4. When it appears in the message flow
5. Example JSON

The Agent SDK's streaming-output.md already documents StreamEvent types thoroughly. The CLI docs need equivalent coverage for the full set of top-level message types (which includes types beyond just StreamEvent).

Alternative Solutions

• Publish a JSON Schema file: Machine-readable schema at a stable URL. Developers can use it for code generation and validation.
• Link to Agent SDK TypeScript types: Point developers to the SDK's .d.ts files as the source of truth. Less accessible but accurate.
• OpenAPI/AsyncAPI spec: For developers building HTTP wrappers around the CLI, a formal spec would enable code generation.

Priority

• [ ] Critical - Blocking my work
• [x] High - Significant impact on productivity
• [ ] Medium - Would be very helpful
• [ ] Low - Nice to have

Feature Category

• [x] CLI commands and flags
• [ ] Interactive mode (TUI)
• [ ] File operations
• [ ] API and model interactions
• [ ] MCP server integration
• [ ] Performance and speed
• [ ] Configuration and settings
• [x] Developer tools/SDK
• [x] Documentation
• [ ] Other

Use Case Example

A CI/CD pipeline runs claude -p --output-format stream-json and needs to:

1. Parse the system message with subtype: init to get the session_id
2. Monitor stream_event messages for progress
3. Detect tool calls and log them
4. Extract the final result message for the pipeline output
5. Track token usage from message_delta events

Currently, the developer has to guess which message types exist and what fields they contain. A reference would let them write a correct parser upfront.

Additional Context

The Vibe Companion project's session-types.ts file (232 lines) is essentially a community-authored type reference for these message types, reverse-engineered from the CLI output. This demonstrates both the demand for this documentation and the feasibility of providing it -- the types are stable enough to document.

The Agent SDK's TypeScript SDK reference (platform.claude.com/docs/en/agent-sdk/typescript) documents some of these types but in the context of the SDK library, not the CLI output format.