它到底是什么

--input-format 用于为打印模式（-p / --print）指定 stdin 输入的解析格式。

text 是普通的纯文本 stdin（即平时 cat file | claude -p "..." 那种管道输入）；stream-json 则让 CLI 把 stdin 当作换行分隔的 JSON 对象流（jsonl）来解析，从而支持程序化输入。

用法

官方给出的示例：

claude -p --output-format json --input-format stream-json

不带 -p/--print 时，--input-format 不会生效。

与其他 flag 的组合 / 互斥

• 必须搭配 -p/--print：这是官方文档给出的硬性要求，离开打印模式该 flag 没有意义。
• 常与 --output-format 搭配：输入和输出格式是两个独立的开关，可以自由组合，例如 --input-format stream-json --output-format json 或两端都用 stream-json。
• 与 --include-partial-messages、--include-hook-events：这两个 flag 控制的是 --output-format stream-json 输出端的事件粒度，和 --input-format 本身没有直接依赖关系，但在构建全双工流式管道时经常同框出现。

运行约束 / 限制

常见坑

• 官方文档对 stream-json 输入格式的说明非常简略：CLI flags 表里只有一行描述，headless（非交互模式）页面在编写本文时并未详细展开 stdin 端 stream-json 的具体消息结构、多轮对话怎么通过 stdin 追加消息、以及和权限提示交互的方式。这一文档缺口在 GitHub issue #24594 中被明确提出，内容涉及缺少消息类型说明、缺少双向流工作方式说明等。若要依赖 --input-format stream-json 做程序化对接，建议优先参考 Agent SDK 而非自行拼装 stdin 协议。
• 忘记加 -p/--print：只写 --input-format stream-json 而不带打印模式，该 flag 不会生效。

来源

• CLI reference（官方 CLI 参考)
• Run Claude Code programmatically（官方 headless / 非交互模式文档)
• [DOCS] --input-format stream-json usage is undocumented beyond the CLI flags table · Issue #24594