[DOCS] Headless stream-json docs omit input format and UTF-8 text handling

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The stream-json sections for programmatic claude -p usage, especially bidirectional stdin/stdout pipelines using --input-format stream-json, --output-format stream-json, and --replay-user-messages

Current Documentation

The headless docs currently say:

Use --output-format to control how responses are returned: text (default): plain text output json: structured JSON with result, session ID, and metadata * stream-json: newline-delimited JSON for real-time streaming 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 currently says:

--input-format — Specify input format for print mode (options: text, stream-json) --replay-user-messages — Re-emit user messages from stdin back on stdout for acknowledgment. Requires --input-format stream-json and --output-format stream-json

The common workflows page also says:

This outputs a series of JSON objects in real-time as Claude processes the request. Each message is a valid JSON object, but the entire output is not valid JSON if concatenated.

What's Wrong or Missing?

Changelog v2.1.94 says:

Fixed CJK and other multibyte text being corrupted with U+FFFD in stream-json input/output when chunk boundaries split a UTF-8 sequence

That entry confirms stream-json is a real bidirectional integration surface, but the current docs only explain output streaming and a flag list.

A. The input side is still undocumented

The headless page explains --output-format stream-json, but it does not explain how --input-format stream-json works, what shape of newline-delimited JSON stdin should contain, or how --replay-user-messages fits into a bidirectional pipeline.

B. The text/encoding contract is not documented

Current docs never state that stream-json uses UTF-8 newline-delimited JSON or that Unicode text such as CJK, emoji, and other multibyte content is intended to round-trip correctly through stream-json stdin/stdout pipelines. Users only learn that from a bug-fix changelog entry.

Suggested Improvement

Add a short subsection to https://code.claude.com/docs/en/headless for bidirectional stream-json usage that:

1. documents the expected input line shape for --input-format stream-json,
2. includes a minimal example using --input-format stream-json, --output-format stream-json, and --replay-user-messages, and
3. states that stream-json is UTF-8 newline-delimited JSON and that Unicode text (including CJK and emoji) is supported in both input and output.

Also add a cross-reference from the --input-format and --replay-user-messages entries in https://code.claude.com/docs/en/cli-reference to that headless subsection.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/headless | Primary claude -p guide documents stream-json output but not bidirectional input/output usage or Unicode handling |
| https://code.claude.com/docs/en/cli-reference | Lists --input-format and --replay-user-messages without explaining the stream-json input contract |
| https://code.claude.com/docs/en/common-workflows | Recommends --output-format stream-json for real-time integrations, but does not point to fuller I/O guidance |
| https://code.claude.com/docs/en/best-practices | Recommends stream-json for scripts and automation, but does not link to input/encoding guidance |

Total scope: 4 pages affected

Source: Changelog v2.1.94

Exact changelog entry:

Fixed CJK and other multibyte text being corrupted with U+FFFD in stream-json input/output when chunk boundaries split a UTF-8 sequence