[DOCS] `--input-format stream-json` usage is undocumented beyond the CLI flags table

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/cli-reference
https://code.claude.com/docs/en/headless

Section/Topic

CLI reference > CLI flags table, and the "Run Claude Code programmatically" (headless) page.

Current Documentation

The CLI reference lists the flag in a single row:

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

The headless page does not mention --input-format at all. It only covers output streaming.

What's Wrong or Missing?

There is no documentation explaining how to use --input-format stream-json. Specifically:

1. What message format should be sent on stdin? What JSON structure does the CLI expect? What are the valid message types?
2. How do you send follow-up messages? Can you send multiple user messages to create a multi-turn conversation via stdin?
3. How does it interact with --output-format stream-json? When using both together, what's the expected bidirectional flow?
4. What happens when the CLI sends a permission request? How do you respond via stdin?

The Agent SDK docs have thorough coverage of streaming input (platform.claude.com/docs/en/agent-sdk/streaming-vs-single-mode), but this doesn't help users who want to use the CLI directly via claude -p with structured input.

This gap is significant because --input-format stream-json is the only CLI mechanism for programmatic bidirectional communication with Claude Code in print mode.

Suggested Improvement

Add a section to the headless page (or a new dedicated page) covering:

1. The NDJSON message format expected on stdin when using --input-format stream-json
2. Example of sending a user message and reading the response
3. Example of multi-turn conversation via stdin/stdout
4. How permission prompts work in this mode (or a pointer to --permission-prompt-tool)
5. A complete example showing bidirectional streaming (send input, read streaming output, send follow-up)

At minimum, link to the Agent SDK's streaming input documentation from the CLI reference flag description, noting the message format is the same.

Impact

High - Prevents users from using a feature

Additional Context

Third-party projects like The Vibe Companion have resorted to reverse-engineering the internal WebSocket NDJSON protocol because the documented CLI interface doesn't explain how to use bidirectional streaming. If --input-format stream-json were properly documented, developers could build programmatic integrations using the supported CLI interface instead of exploiting hidden flags.