[DOCS] Headless stream-json input does not document blank-line handling for Windows SDK hosts

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The “Get structured output” and “Stream responses” sections covering stream-json, especially bidirectional print-mode use with --input-format stream-json.

Current Documentation

The headless guide describes the output format as:

stream-json: newline-delimited JSON for real-time streaming

It also says:

Use --output-format stream-json with --verbose and --include-partial-messages to receive tokens as they're generated. Each line is a JSON object representing an event

The CLI reference lists the input option only as:

--input-format | Specify input format for print mode (options: text, stream-json)

What's Wrong or Missing?

The documentation explains how to receive newline-delimited JSON output, but it does not document the corresponding stdin contract for --input-format stream-json. In particular, it does not say whether blank lines, whitespace-only lines, or Windows-style CRLF line endings are valid between JSON messages.

Claude Code v2.1.208 fixed stream-json input killing the session when a Windows-style SDK host sent a blank CRLF line or a whitespace-only line. This is a compatibility guarantee for SDK and other programmatic hosts, not merely an implementation detail: hosts commonly emit line separators independently of message serialization, and a harmless empty line should not terminate the session.

Without this guidance, developers do not know whether they must suppress empty lines themselves, whether CRLF is supported, or whether a session ending after such a line indicates malformed JSON, an unsupported transport, or a Claude Code defect.

Suggested Improvement

Add an input-stream subsection or note that documents the --input-format stream-json wire contract alongside the existing output-stream guidance. It should:

1. Show the JSON message shape expected on stdin, with one complete JSON message per line.
2. State that both LF and Windows CRLF line endings are accepted.
3. State that blank and whitespace-only lines are ignored and do not terminate or kill the session, as of v2.1.208.
4. Clarify how malformed non-empty JSON lines are handled and what a host should do after an input error.
5. Include a short Windows/PowerShell or SDK-host example that writes JSON messages without requiring callers to strip harmless blank lines.

Cross-link the input guidance from the --input-format row in the CLI reference and distinguish the input protocol from --output-format stream-json, which the current page documents in detail.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/headless | Primary stream-json output and programmatic CLI guidance; input-stream semantics are absent |
| https://code.claude.com/docs/en/cli-reference | --input-format row lists stream-json without its stdin message and line-handling contract |
| https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode | SDK streaming-input examples use an async message generator but do not connect the SDK transport to the CLI's line-delimited input behavior |
| https://code.claude.com/docs/en/agent-sdk/python | Transport reference says write(data) sends “JSON + newline” but does not document CRLF or blank-line handling |

Total scope: 4 pages affected

The behavior change was released in Claude Code v2.1.208. The existing streaming-output guidance should remain intact while adding the missing input-side contract.