Claude Code 2.1.235 CLI、SDK 与输出协议¶

版本边界： 本文只解释仓库中 Claude Code CLI 2.1.235 的 CLI 帮助、bundle schema、可读化 JavaScript、生成清单与已有精确二进制 Probe。当前官网没有被用来补写本版行为。

先回答读者真正会遇到的问题¶

读者问题： 为什么同一个 Claude Code，直接运行时是 TUI，-p 时可以只打印一段文本，SDK 却能边收消息、边审批工具、边切模型，而且 stream-json 里的 success、agent.message、control_response 看起来像三套不同协议？

一句话模型： 2.1.235 把同一个 Agent Loop 包在三种入口外面：TUI 持有本地交互，--print 把一轮结果投影为 text/json/NDJSON，SDK 再在 NDJSON 上叠加带 request_id 的双向控制 RPC；消息流负责“观察发生了什么”，控制流负责“请求另一端改变或补充状态”。

图的结论：result 是一轮结束信号，不是整个输出协议；control_response 是某个 RPC 的答复，不是模型回答；SDK host 与 CLI worker 可以同时成为 request 的发起方。

60 秒模型¶

贯穿场景：一个自动化程序恢复已有会话，要求 Claude 检查仓库；模型先输出文字，再请求 Read。SDK host 收到 can_use_tool，批准后 CLI 执行工具并继续模型轮次，最终产出符合 JSON Schema 的对象。

三个协议面不能混在一起¶

analysis/source-inventory/output-protocol-event-identifiers.txt 的 44 项属于第三行的远端事件词汇。它们不是本地 --output-format=stream-json 的 44 种 stdout frame。把两者合并会导致错误的 parser、错误的重连语义和错误的状态归属。

入口与格式矩阵¶

交互模式与 --print¶

• 默认入口是交互 TUI；-p/--print 打印响应后退出。
• 该版帮助明确说明：非交互入口会跳过 workspace trust 对话；无效 settings 在该模式下没有对话框，可能被静默忽略。因此 --print 是自动化入口，不等于更严格的信任入口。
• SDK 不是第二套 Agent Loop。TypeScript SDK 启动同一个 CLI，并固定添加 --output-format stream-json --verbose --input-format stream-json。

input-format 与 output-format¶

进一步约束：

• --replay-user-messages 需要 input/output 都是 stream-json。
• --include-partial-messages、--forward-subagent-text 需要 --print + stream-json；仅由内部条件隐式打开而用户没有显式传 flag 时，非法组合会被关闭而不是总是报错。
• --prompt-suggestions 只在 --print + stream-json 输出。
• --sdk-url 同时要求输入和输出为 stream-json，并有保留给 Remote Control worker 的 host 校验。
• stream-json 还要求 --verbose，否则在加载会话后、进入主循环前 exit 1。

三种输出的终态差异¶

text 只保留人类可读投影：成功打印 result，四类错误分别打印固定短句。json 保留 result 字段。stream-json 不再额外打印终态，因为 result 本身已经是一条 NDJSON frame。

不要只看 subtype：subtype: "success" 仍可能同时有 is_error: true，表示 API error 文本被装进 result。该版最终退出规则是 result.is_error 或永久 transport close 为 exit 1，否则 exit 0。

本地 stdout/stdin 的真实 envelope¶

stdout¶

schema 把 stdout 定义为“一行一个 JSON object”，主要成员是：

另外还有 auth_status、tool_use_summary、rate_limit_event、prompt_suggestion、conversation_reset、command_lifecycle、transcript_mirror、active_goal、autocompact_state。这再次证明“89 subtype 清单”不是完整 stdout 类型表。

stdin¶

stdin schema允许 user message、内部 bash_command、双向 control frames、update_environment_variables、queued_notification 和 session_notice。initialize 通常是第一条，但不是强制；第一条 user message 可以用默认值完成初始化。后到的 initialize 会返回当前状态，标题、SDK MCP server 与进度摘要仍可处理，但 system prompt/hooks/agents/skills 等一次性配置不会再次应用。

输入流关闭的语义是“让 CLI 完成当前 turn 后退出”，不是立即 kill。SDK 在存在双向回调需求时会等到首个 result，再关闭子进程 stdin。

Partial messages：实时预览不是简单透传¶

打开 --include-partial-messages 后，CLI 把底层 message_start、content_block_*、message_delta、message_stop 包成 type: stream_event。完整 assistant message仍是权威记录。

该版还维护 message id 与当前 block index。在 fallback、refusal 或 tombstone 回撤已经预览的内容时，它会合成缺失的 content_block_stop、message_delta 和 message_stop，把消费者看到的流闭合，再开始新的 message。否则 UI 会永久停留在“block 未结束”状态，或把被撤回的文字当成最终回答。

代价是 stdout 字节数、解析次数和 UI 状态复杂度增加；普通批处理应只读完整 assistant/result，需要低延迟预览时再打开 partial。

Structured output：不是在最后做一次 JSON.parse¶

1. --json-schema 先解析为 JSON object；字符串、数组或无效 schema 在启动阶段失败。
2. CLI 用 AJV 校验 schema，本版拒绝过大的 schema，并尝试派生 strict schema，失败时回落非 strict。
3. CLI 创建名为 StructuredOutput 的内置工具，把用户 schema 作为 tool input schema，并提示模型必须在结尾调用一次。
4. 工具调用输入通过 schema 校验后，返回 structured_output attachment 且 endsTurn: true。
5. 最终 result.structured_output 取最后一个仍存活的 attachment；若 model fallback tombstone 回撤了对应 tool call，该 attachment 也被移除。
6. 默认最多允许 5 次结构化输出尝试；MAX_STRUCTURED_OUTPUT_RETRIES 可覆盖。耗尽后返回 error_max_structured_output_retries。

因此结构化输出会占用工具 schema、至少一次 tool call，并可能增加模型轮次、token、时延和费用。它保证的是工具输入通过本地 schema 校验，不证明业务语义正确。

Session、resume 与 fork¶

不存在或含糊的 resume 目标会 exit 1，不会静默变成新会话。fork 在恢复消息后改写 session 身份，并保留逻辑历史。已有精确二进制 Probe 已证明 resume 会注入旧 prompt/result，fork 会产生不同 session ID 并继承 compact summary；详见 运行探针索引。

Control request/response 生命周期¶

普通成功路径¶

1. 发起端生成在当前 in-flight 集合中唯一的 request_id。
2. 它先登记 pending resolver，再写出 control_request。
3. 接收端按 subtype 处理；需要长操作时可发 control_request_progress。
4. 接收端写一条 control_response，其中 response.request_id 必须相同，verdict 为 success 或 error。
5. 发起端移除 pending，成功时按 subtype response schema 校验 payload，失败时 reject。

配对、重复与乱序¶

• SDK host 允许 response 比 waiter 更早到达：先放入 unmatched map，稍后 awaitControlResponse 再领取。
• unmatched map 上限为 1024，超限淘汰最老项，防止错误/恶意 peer 无限占用内存。
• worker 对未知 request ID 不会错误地完成另一个 request；can_use_tool 还校验 response 的 tool name。
• 已解决 toolUseID 的重复 response 会忽略。
• request_user_dialog 的 error response 不被当作用户选择，dialog 保持 parked；只有 completed/cancelled 语义的成功 response 才结算。

cancel、abort 与关闭¶

发起者 abort 时删除 pending 并发送 control_cancel_request。cancel 没有自己的 response；接收端可中止工作，也可能来不及中止并仍发回晚到 response。发起者已经停止等待，晚到 response 不应改变已结束状态。

关闭 transport 会 reject 所有 pending control/MCP promise，并终止或清理 callback。它只能恢复协议一致性，不能撤销已执行的文件写入、命令、网络请求或反馈上传。

initialize 的特殊重连语义¶

initialize response 除普通 payload 外可带 pending_permission_requests 与 pending_user_dialog_requests。新 host 加入已经运行的 session 时据此重新挂载未完成对话；同一 request 还可能作为 live/replay frame 到达，消费者必须按 request_id 去重。

request 的完整状态机，而不是“发一行等一行”¶

NEW
  -> PENDING(request_id 已登记，再写 control_request)
     -> PROGRESS*                 control_request_progress，只续期/展示，不结算
     -> SUCCEEDED                 control_response.success，同 request_id
     -> FAILED                    control_response.error，同 request_id
     -> CANCELLED                 发起端停止等待并发 control_cancel_request
     -> TRANSPORT_CLOSED          所有 pending 被 reject
     -> TIMED_OUT                 仅有超时策略的 transport；本地 Query 没有通用 RPC 超时

这里有六个容易写错的实现细节：

1. pending 必须先登记再写出。 否则极快的 response 可能在 waiter 建立前到达。SDK Query 仍额外保留 unmatchedControlResponses，允许 response 先于 awaitControlResponse()；最多 1024 条，超限淘汰最老项。
2. request_id 只做关联，不做授权。 本地 Agent SDK 用随机 base36 字符串，Remote Control transport 使用 UUID；schema 只要求在本端 in-flight 集合中唯一。任何能写入可信 control transport 的 peer 已经在更高的信任边界内。
3. 成功 verdict 不等于业务成功。 control_response.response.subtype: success 表示 handler 正常结算；mcp_set_servers.response.errors、submit_feedback.failure_reason、rewind_files.canRewind:false 等仍可能表达部分成功或业务不可用。
4. 取消只撤销等待和仍可中止的 handler。 本地 Query 收到 cancel 后 abort 对应 callback controller；worker 只会 abort 登记在异步控制表中的任务。已完成的文件写入、命令、MCP 调用、反馈上传或设置落盘不会被撤回。
5. 本地 Agent SDK 没有统一 wall-clock timeout。 Query.request() 只响应调用方 AbortSignal、response 或 transport close。Remote Control manager 是另一层 host：普通 request 为 75s，side_question 为 600s，每条 control_request_progress 会重置同样的计时器；不能把这组数写成所有 SDK transport 的默认值。
6. 重复只在当前 in-flight 窗口内去重。 SDK host 对正在处理的同一 request_id 跳过重复 delivery；结算后不会永久保存所有 request ID。需要跨重连幂等时，必须依赖 initialize 的 pending redelivery、已见 response 集合或业务对象自身的幂等键。

本地 Agent SDK 的典型线序¶

SDK host                         CLI worker                         Agent Loop
   | initialize(request_id=A)       |                                  |
   |------------------------------->| apply once-only config            |
   |<-------------------------------| success(A, capabilities)          |
   |                                |                                  |
   | user message                   |                                  |
   |------------------------------->|-------------------------------> model
   |<-------------------------------| assistant / stream_event          |
   |<-------------------------------| can_use_tool(request_id=B)        |
   | render permission UI           | parked tool                       |
   | success(B, allow/deny)          |                                  |
   |------------------------------->| permission -> tool -> tool_result |
   |<-------------------------------| system/task/hook observations     |
   |<-------------------------------| result                            |

result 只结束当前 query turn。若 stdin 仍保持开放，下一条 user frame 可以启动下一轮；单轮 Query 在首个 result 后关闭 stdin。反过来，control_response 只结束一个 RPC，既不代表 turn 完成，也不应触发进程退出。

cancel 与晚到 response¶

host: PENDING(C) -> AbortSignal -> 删除 waiter -> 发 control_cancel_request(C)
worker: 收到 cancel -> abort 仍登记的 handler
worker: handler 已完成或不可撤销 -> 仍可能写回 response(C)
host: C 已不在 pending -> 缓存为 unmatched 或记录后忽略，不能恢复已取消调用

因此客户端必须把 CANCELLED 视为本端终态，而不是等待一个“取消确认”。协议明确规定 cancel 自身没有 response。

89 个 subtype 清单到底是什么¶

生成器的规则是扫描所有 subtype: literal("...") schema。结果精确为 89 个唯一字符串，但它混合了：

• 42 个 schema 化 control request subtype；
• success/error 两个 control response verdict，其中 success 同时也是 result subtype；
• 46 个观察型 system/result subtype。

所以数学关系是 42 + 2 + 46 - 1(success 重叠) = 89。清单名是历史命名，不能据此宣称“SDK 有 89 个 RPC”。

42 个 schema 化 control request¶

方向中的 client 指 SDK/远端 host -> CLI loop，agent 指 CLI loop -> host，both 指双向。注册表精确分成 35 个 client、6 个 agent、1 个 both。下面的“返回”都是 control_response.response 内部 payload；null 表示只需 success/error verdict，不表示整条 control_response 可以省略。

42 项的 response、所有权和结算语义¶

注册表只定义协议合同，不等于所有 transport 都实现所有项。静态 dispatch 审计的可执行结论是：主 print worker 处理 client 方向的注册请求并对未知 subtype 返回 error；set_color 只在专用 bridge 分支可见。agent 方向 6 项由 SDK Query.processControlRequest() 消费，mcp_message 同时走两端。feature flag、provider、登录态和 host callback 仍决定实际可达性。

schema 清单之外的 16 个 worker 分支¶

实际 worker handler 还识别下列 string-only subtype：

add_directory, channel_enable, claude_authenticate, claude_oauth_callback, claude_oauth_wait_for_completion, end_session, generate_session_title, mcp_authenticate, mcp_clear_auth, mcp_oauth_callback_url, poll_event, remote_control, rewind_conversation, side_question, stage_file, ultrareview_launch。

它们证明“89 清单”甚至不是全部 control handler 表面。反过来，schema 中 set_color 没有出现在这条主 worker dispatch；因此本文不把 schema 存在升级为已执行证明。2.1.235 的静态事实是：schema 定义 42 个、主 worker 分支识别 51 个、两者并集 58 个；不同 transport/capability 仍决定可达性。

46 个观察型 subtype¶

error 是 control response verdict，不是观察事件。四个 result error subtype 使用一个 enum，因此没有进入这份 89 字符串清单：error_during_execution、error_max_turns、error_max_budget_usd、error_max_structured_output_retries。

46 个观察 subtype 的逐项协议语义¶

这 46 项精确由 45 个 system subtype + 1 个 result.success 构成。它们都不需要 control_response；只有 control_request_progress.request_id 会关联某个 RPC，但它仍不是结算帧。

success 之外的四个 result error subtype 不在 89 清单，却同样是 turn 终态。可靠 consumer 必须先按 type: result 分流，再读取 subtype 和 is_error；不能用“是否出现在 89 个字符串里”决定是否终止。

44 个 Managed Agents event identifier¶

这 44 项由宽词法规则从 bundle 恢复。逐项追到 parser、SessionToolRunner 和随包文档后，真实构成不是“44 种 output frame”，而是：

也就是说，36 + 6 + 1 + 1 = 44。这项审计修正了“44 项都由 SSE parser 接收”的旧说法。44 清单必须继续保留用于跨版本词法比较，但人类文档必须把 runtime、webhook、文档偏差和误报分开。

bundle 中另一套 SessionsV2Client 读取的是 /v1/code/sessions/... 的 Remote Control client_event/ephemeral_event，承载本地 CLI wire frame；这里的 44 项来自 bundled beta.sessions.events Managed Agents SDK。两者 host、重连游标、事件 ID 和终态完全不同。

共同字段以远端 persisted event record 为中心，通常包含 type、event id 和 processed_at。client-posted event 首次出现时 processed_at 可为 null；user.define_outcome、user.custom_tool_result、user.tool_result 在接收时处理，首次 echo 已可能非 null。下表只列 parser、SessionToolRunner 或随包文档能证明的字段；没有 runtime field validator 的项目继续标 Boundary。

远端流还有 event_start/event_delta 预览帧，但不进入这 44 个 {domain}.{action} 标识；随包文档明确它们只在 SSE preview 中出现，不在普通 event list 中。这个差异与本地 stream_event 仍然是两套协议。

Managed Agents 的关联键与终态¶

远端“结束”必须按状态对象判断：

• session.status_idle 是条件终态：end_turn 表示当前工作完成但 session 可继续；requires_action 表示还欠 tool confirmation/result；budget_reached 表示暂停，只有修改/移除 budget 才会恢复。
• session.status_terminated 是 session 的不可逆终态，成功完成和错误结束都会出现；不能把它当 error-only。
• session.deleted 同样终止 SessionToolRunner，因为资源已不存在。
• session.error、session.status_rescheduled、span.model_request_end.is_error 都不是充分终态；服务可能重排后继续。
• session.thread_status_terminated 只结束一个 thread，不结束整个 session。

典型 Managed Agents custom-tool 线序¶

host POST user.message
  -> echo user.message(processed_at may be null, then populated)
  -> session.status_running
  -> span.model_request_start
  -> agent.custom_tool_use(id=T, name, input)
  -> session.status_idle(stop_reason=requires_action, event_ids=[T])
host executes its own tool
host POST user.custom_tool_result(custom_tool_use_id=T, content, is_error)
  -> echo user.custom_tool_result(processed_at populated)
  -> session.status_running
  -> ... more model/tool events ...
  -> session.status_idle(end_turn) OR session.status_terminated

这条链没有 control_request/control_response，也没有本地 Agent SDK 的 request_id。把 agent.custom_tool_use 误当成本地 can_use_tool，会导致 approval/result 字段、重连策略和终态全部错误。

SSE 断线后的恢复为什么要“list + reconcile”¶

bundled SessionToolRunner 的真实恢复路径是：stream 断开后以 500ms 起步、最高 10s 退避重连；重新连上先 list events，再从历史重建 seen tool-use、tool-result 与 confirmation 三组状态，然后只执行仍未结算且由当前 runner 拥有的工具。工具执行本身有 120s abort timeout，result POST 最多尝试 3 次，退避 1s/2s；退出时最多等待 30s drain。

这条 reconcile 避免断线后重复执行已收到 result 的 tool call，但边界仍然存在：

• host 工具已经产生副作用、result POST 却失败时，重连可能再次面对同一未结算 call；真正的外部工具必须用 tool_use_id 做业务幂等；
• runner 不拥有的 tool name 会保持 pending 并交给真正 owner，不会伪造 result；
• session.status_terminated 或 session.deleted 会停止 runner；普通 stream error 只触发重连；
• preview delta 不持久化、不可 replay，重连后只能用 buffered event 对账。

103 个 slash command 的协议归属¶

slash command 首先是 输入扩展/本地命令路由，不是 control subtype。命令可能：只改 TUI、本地读写 session/settings、生成 prompt 进入 Agent Loop，或在 remote mode 下转成 control request。不能从命令名推断网络协议。

这张表覆盖生成清单中的全部 103 个名字，但只说明入口归属。具体某个命令是 local/local-jsx/prompt、有哪些 feature gate、是否在 remote mode 改走 control channel，需要回到对应 command object 与 handler，不能由这份词法清单推出。

失败恢复与诊断顺序¶

安全、隐私与成本¶

• system/init 可包含 cwd、工具、MCP server、plugin/skill、账户 email/organization、模型和权限模式；assistant/user/tool result 还可包含源码、文件路径和命令输出。NDJSON 必须按会话数据处理，不能当普通 debug log 公开。
• submit_feedback 可以附带 transcript；schema 说明会运行 policy/redaction，但调用者仍要把 attach_transcript 当成显式数据外发决定。
• mcp_call 的 schema 说明 control channel 被视为可信，不走普通 model-turn permission check。任何能写入 stdin control frame 的进程都处在高信任边界。
• update_environment_variables 只应用 allowlist 键；非 allowlist 被拒绝。remote stdin 还会过滤 server-authored-only frame，防止伪造 ingress provenance。
• read_file 复用 Read 权限规则；set_cwd 复用目录校验和 trust，但 trust attestation 可能先持久化，随后因 busy/relocation 失败而 cwd 不变。
• result.total_cost_usd 与 modelUsage 是当前 query() 的累计估算；多轮 streaming input 应读取最新 result，不要把每轮累计值相加。resume 新 query 重新累计。
• partial events、hook events、replay、verbose JSON 数组会增加传输/内存成本。structured output 默认最多 5 次尝试，会增加模型调用成本。

可验证证据¶

仍然不能从本版证明的边界¶

• schema/handler 的存在不证明任意账户、provider、remote service 或 feature flag 下都可达。
• 44 个 Managed Agents 词法项中只有 36 个进入 named-event parser；6 个是 webhook-only，session.usage 只有 embedded-doc 合同，session.archived 是属性访问误报。没有登录态 service Probe，不能宣称远端实际发送了每一种 runtime event。
• named-event parser 对 36 项只做 JSON.parse，不运行逐 event 字段 validator；字段结论只能来自 SessionToolRunner 的真实读取或随包文档，不能凭名字补造。
• session.usage 的随包 event 文档与 named-event parser allowlist 不一致；它可能经 generic message SSE event 或更新的 service/SDK path 到达，但 2.1.235 bundle 不能证明所有表达都可被当前 parser 消费。
• output-protocol-event-identifiers.txt 是宽词法 inventory，不是一份 runtime discriminated union；它适合发现版本词汇，不适合直接生成生产 parser。
• set_color 有 schema 声明但主 worker dispatch 未见处理；16 个 string-only handler 又未进入 schema inventory。客户端必须做 capability/version negotiation，不能硬编码某一集合为永恒协议。
• 本地 Agent SDK Query 没有统一 RPC timeout，Remote Control manager 的 75s/600s 也不能外推到其他 transport；host 必须自己提供 AbortSignal 和业务 deadline。
• control cancel、resume、fork、rewind 都不能回滚已经完成的外部副作用。