feat: 评估并设计 Claude backend 兼容层（normal mode only）

[kxn]

背景

#185 已完成接入方向调研，当前进入 PoC 方案阶段。

本次明确采用“实例级兼容”路线：

• 系统支持 Codex / Claude backend 并存；
• 与 Codex 实例交互时，不触发 Claude 分支；
• 与 Claude 实例交互时，对暂不支持能力允许显式报错；
• 重点是 provider/capability 路由正确，不是做两套割裂系统。

目标

1. 形成可执行的 Claude normal-mode PoC 方案，并落地为仓库文档基线。
2. 在不回归 Codex 现有行为的前提下，补齐 provider-aware 能力调度基座。
3. 为后续实现提供清晰分阶段边界与验收口径。

范围

• provider/capability 模型进入 daemon/orchestrator 派发决策。
• wrapper/provider 入口与 adapter 分层（Codex 与 Claude 并行）。
• normal mode 下 Claude 的最小主链路（prompt/interrupt/request/resume/list）。
• 不支持命令的显式拒绝与用户提示策略。

非目标

• 本 issue 不实现 Claude 的 vscode mode / follow-local / focus 语义。
• 本 issue 第一阶段不追求 turn.steer 与 Codex 精确同语义。
• 本 issue 第一阶段不做全仓 thread -> session 字段重命名。

相关文档

• 统一实施基线：docs/inprogress/claude-backend-integration-plan.md
• 历史归档（不再作为实施依据）：docs/obsoleted/claude-normal-mode-poc-design.md
• 历史归档（不再作为实施依据）：docs/obsoleted/claude-provider-protocol-mapping.md
• 历史归档（不再作为实施依据）：docs/obsoleted/claude-feidex-reassessment.md
• docs/general/architecture.md
• docs/general/relay-protocol-spec.md
• docs/general/remote-surface-state-machine.md

涉及文件

• internal/core/agentproto/wire.go
• internal/core/state/types.go
• internal/app/daemon/app_ingress.go
• internal/app/wrapper/entry.go
• internal/app/wrapper/app.go
• internal/core/orchestrator/service_helpers_threads.go
• internal/core/orchestrator/service_surface_actions.go
• internal/adapter/claude/**（新增）

方案阶段（PoC）

阶段 A：兼容性护栏

• hello capabilities 接入实例状态。
• onHello 改为 capability-aware 初始化（不再无条件 threads.refresh）。
• startup refresh pending 仅统计已派发 refresh 的实例。

阶段 B：Claude live transport

• 以 claude -p --input-format stream-json --output-format stream-json 作为当前实现基线。
• 固化长生命周期 child + stdin/stdout NDJSON 的 live turn transport。
• 打通 prompt.send / turn.interrupt / request.respond 主链路。
• request.respond 按 can_use_tool / elicitation 两类分开处理。
• 错误统一为 machine-readable code/message/retryable。

阶段 C：session catalog / history plane

• 把 threads.refresh / thread.history.read 从 live child 分离。
• 基于 provider-local session catalog / transcript metadata 回填会话目录与历史。
• threadId 在 v1 继续承载 Claude session_id，但持久键按 backend + instance_id + session_id 收口。
• resume(session_id + cwd) 成功/失败路径收口。

阶段 D：normal mode 命令闭环与显式降级

• /new、/use、/list 在 Claude 实例下闭环。
• turn.steer 明确 reject/problem + notice，不做 fake steer。
• threads.refresh 不再作为所有 backend 的默认能力假设。
• provider-specific config translation 先覆盖 model / reasoning / access。

阶段 E：稳定化收口

• Codex+Claude 混合场景回归。
• usage/context 口径与 UI 展示收口。
• 状态机与用户文档同步更新。

风险与回退

• 风险：能力门控遗漏造成错误下发。
• 风险：startup 恢复被错误 pending 条件阻塞。
• 风险：拒绝路径只报 ack 未投影 notice，形成“看似卡死”。

回退策略：

• provider-aware 分支保持 Codex 默认路径优先。
• Claude 实例异常时可直接禁用 Claude 实例，不影响 Codex 运行。

完成标准

1. PoC 方案文档可作为实现基线，且已在 docs 索引可检索。
2. Codex-only 回归不退化。
3. Codex+Claude 并存场景无命令串扰。
4. Claude 不支持命令显式可见失败，无 silent failure。
5. 拒绝/失败后 queue 与 request 状态机可继续工作，不出现死状态。

2026-04-23 同步更新（文档合并与 UI 语义基座）

1. Claude 接入设计文档已合并为单一实施基线：docs/inprogress/claude-backend-integration-plan.md。
2. 历史三份文档改为 docs/obsoleted/*，保留历史上下文但不再作为执行入口。
3. 统一基线已新增“基座九：UI/交互语义归一化与 projector 边界固化”，明确：
   • Claude 事件先归一化为 canonical eventcontract payload，再进入 orchestrator/projector
   • 不回退到上游拼 markdown 的旧路径
   • 补齐中间过程语义模型与 quiet/normal/verbose 可见性策略，同时保持 Codex 渲染边界零回归

2026-04-23 二次深调研结论（基于 feidex 最新实现）

本轮基于 https://github.com/yuhuan417/feidex 最新 main（ff0c522）重新复核，结论是：#185 当前不应保持 implementable-now，应回到 needs-investigation 继续收口。

关键证据（feidex）：

1. “不本地处理”命令默认不是 reject，而是 passthrough 到 backend（internal/app/commands.go、docs/capabilities.md）。
2. Claude 下 /compact 是显式 passthrough（internal/app/backend_runtime_helpers.go）。
3. Claude 的“回复继续”不是 Codex same-turn turn/steer，而是排队新 submission 的近似语义（internal/app/steer.go）。
4. /session fork 在 session_id 尚未 materialize 时允许进入 pending 过渡态，等待下一条消息物化（internal/app/conversation_backend_facade.go、internal/app/commands_test.go）。
5. AskUserQuestion / ExitPlanMode 被映射到本地 pending card/request 流程，且 reply 走 backend-specific adapter（internal/app/claude_runtime.go、internal/app/backend_server_request_adapter.go）。
6. Claude 动态工具被分类并做了独立渲染与 quiet 进度策略（internal/app/claude_dynamic_tool_rendering.go）。

对本仓库的直接影响：

1. 除“九项基座”外，还缺一层明确的命令策略矩阵（native / approximation / passthrough / reject）与产品承诺边界。
2. Claude continuation（reply-chain、/append、进行中输入）的语义合同尚未定稿。
3. pending fork / session materialization 的状态机与 UI 合同尚未定稿。
4. AskUserQuestion / ExitPlanMode 到 canonical request 的映射合同尚未定稿（尤其计划反馈语义）。
5. Claude 过程可见性策略（quiet/normal/verbose）与默认展示面尚未定稿。

与当前代码基线的结构缺口（仍未补齐）：

1. agentproto.Capabilities 仍只有 ThreadsRefresh。
2. wrapper 入口仍是 codex-only（app-server）。
3. daemon onHello() 仍无条件发送 threads.refresh。
4. /mode 仍仅 normal|vscode。
5. 状态层尚无 backend 维度分区（instance/surface/workspace defaults/thread key）。

结论：当前阶段应保持 needs-investigation，先完成语义与策略收口，再进入实现。

建议范围

1. #185 不再继续作为未拆分调查单；从现在起按 A2 pre-MVP 路线只承担调度与回卷。
2. 当前 pre-MVP worker 已扩成 6 张：#492 -> #493 -> #494 -> #495 -> #497 -> #498。
3. #496 继续作为明确的 MVP 决策门提前建好，但在这 6 张 pre-MVP 单都稳定关闭前不进入实现。

拆分结构

1. A. backend identity / capability gate
   • #463
   • 已完成并解除最早的 hello / refresh blocker
2. B. backend-aware state partition 与 /mode 语义
   • #492
   • 已完成并关闭
3. C. catalog seam repair（消费 #185 seam，回卷到 #369）
   • #493
   • 已完成并关闭，并已双回卷到 #185 / #369
4. D. Claude 命令策略 / request bridge
   • #494
   • 已完成并关闭
5. E. backend runtime host pre-MVP seam
   • #495
   • 已重评回 needs-plan；当前只保留 seam-only + lifecycle/reconciliation 闭包
6. F. Claude live transport semantic mapper
   • #497
   • 新增；负责 stream-json -> canonical turn/item/request 与 structured progress
7. G. Claude session catalog/history plane
   • #498
   • 新增；负责 threads.refresh / thread.history.read / resume-session semantics
8. H. Claude normal-mode dev MVP
   • #496
   • 当前只作为产品决策门，不进入实现

推荐顺序

1. #492
2. #493
3. #494
4. #495
5. #497
6. #498
7. 停在 #496 讨论 MVP 功能与展现方式，再决定是否开工

可并行组

• 理论上 #497 与 #498 在 #495 seam-only 稳定后可以局部并行。
• 当前默认仍按串行研究与串行推进：#492 -> #493 -> #494 -> #495 -> #497 -> #498 -> #496。
• 原因：这轮目标是先把 pre-MVP closure 调研稳，不抢实现速度。

当前风险

1. 若 #492 未先收口，后续 catalog / request / runtime 都会继续建立在旧的 backend 单维假设上。
2. 若跳过 #493 直接做 visible Claude，最近审计出的 ProductMode / FamilyID / family.default 固化点会重新变成真实回归面。
3. 若 #494 未先写清 strategy matrix 与 request contract，runtime host 很容易把临时近似写进主链。
4. 若 #495 未先吸收 host seam 与 lifecycle/reconciliation，Claude runtime 仍会和 Codex child 管理主骨架缠在一起。
5. 若 #497 不单独落 semantic mapper，MVP 很容易退化成 raw protocol 泄漏、伪 Codex 语义或上游预拼 markdown。
6. 若 #498 不单独落 session/catalog/history plane，threads.refresh / thread.history.read / resume 语义会继续被塞回 MVP，形成半死闭包。

总调度表

单元	类型	当前状态	依赖	当前闭包等级	下一步建议	结果回卷	verifier 状态	当前结论	备注
A. backend identity 与 capability gate	child(#463)	closed	无	已完成实现	已完成	已回卷	pass	done	已解除最早的 hello / refresh blocker
B. backend-aware state partition 与 /mode 语义	child(#492)	closed	A	已完成实现	已完成	已回卷	pass	done	state seam 与 /mode 语义已完成
C. catalog seam repair	sibling child(#493) under #369	closed	B	已完成实现	已完成	已双回卷到 #185 / #369	pass	done	A2 路线里的 pre-MVP catalog seam repair 已完成
D. Claude 命令策略 / request bridge	child(#494)	closed	C	已完成实现	已完成	已回卷	pass	done	命令策略矩阵、request bridge 与 final-output 合同已落地（cceeebcc）
E. backend runtime host pre-MVP seam	child(#495)	needs-plan	D	closure 待重写	先收紧 seam-only 范围，再决定实现顺序	待回卷	需要	rescope	不再把 semantic mapper / session plane 混进本单
F. Claude live transport semantic mapper	child(#497)	needs-investigation	D,E	research closure	先做 native -> canonical mapping matrix	待回卷	需要	new	stream-json / request / progress / final-output adapter
G. Claude session catalog/history plane	child(#498)	needs-investigation	B,E	research closure	先做 catalog/history/resume contract matrix	待回卷	需要	new	transcript / metadata / session-id plane
H. Claude normal-mode dev MVP	child(#496)	needs-clarification	B,C,D,E,F,G	产品决策闭包	在 E/F/G 后停下讨论	待回卷	未开始	decision-gate	不在本轮开工

执行决策

• 是否拆分：是；#185 现在只承担调度、依赖顺序与结果回卷，不再作为单 worker 直做 Claude 母单。
• 当前执行单元：没有 implementable-now worker；当前先继续深调研 #497 / #498，并把 #495 的 seam-only closure 写稳。
• verifier 决策：#495/#497/#498 默认都需要独立 verifier；#496 在进入实现后再决定是否追加 verifier 拆分。

当前阶段

• needs-investigation

当前执行点

• research-497-498-before-mvp

已完成

• Claude 统一实施基线已刷新到 docs/inprogress/claude-backend-integration-plan.md，catalog 设计草案已刷新到 docs/draft/backend-aware-command-catalog-design.md。
• #463 已完成 hello/backend/capability gate，并解除最早 blocker。
• 本轮已把 A2 路线正式拆成 7 张子单：#492、#493、#494、#495、#497、#498、#496。
• #496 已作为“真正开始 MVP 前停下讨论”的统一决策门建立。
• #492 已完成并关闭：backend-aware state partition、workspace defaults backend 分区、surface resume backend 持久化与 /mode codex|claude|vscode 底层语义已落地。
• #493 已完成并关闭：catalog seam 已收口到 CatalogContext + contextual variant 主路径，并已回卷到 #185 / #369。
• #494 已完成并关闭：Claude 命令策略矩阵、request bridge canonical contract 与 final-output 终态合同已落地，并已以 cceeebcc 回卷到本母单。
• #495 已完成重评并回退到 status:needs-plan；确认 runtime host seam 不能继续与 Claude semantic mapper / session plane 混做一张单。
• #497 / #498 已创建，用于把 live transport semantic mapper 与 session catalog/history plane 分开研究与收口。

当前 blocker

1. 当前没有 implementable-now worker：#495 仍需 seam-only 重写，#497/#498 仍需进一步技术调研。
2. #496 必须等待 #495/#497/#498 的 closure 稳定后，才有资格进入 MVP 功能与展现方式讨论。

下一步

1. 继续深调研 #497：把 Claude native stream-json 到 canonical turn/item/request/progress 的映射矩阵写稳。
2. 继续深调研 #498：把 session catalog/history/resume plane 的 contract matrix 写稳。
3. 在这两张 research worker 收口后，再回头把 #495 的 seam-only 执行边界彻底写定，并决定第一个真正可实现的 worker。

恢复步骤

1. 先读取本 issue 的 总调度表，确认当前没有 ready worker，当前执行点是 research-497-498-before-mvp。
2. 再读取 #495 的 2026-04-28 重评结论 与 #497/#498 的当前 blocker，确认这轮继续做的是 closure 调研而不是实现。
3. 只有当 #495/#497/#498 至少有一张重新进入 implementable-now，才恢复真正编码；否则继续研究和拆单，不要提前进入 #496。

实现参考

• 当前实现依据以 docs/inprogress/claude-backend-integration-plan.md 为准；其中第 6 节九项基座（尤其 6.9）定义了 Claude provider 映射、UI 语义归一化与非回归约束。
• v1 首选接入面固定为 claude -p --input-format stream-json --output-format stream-json；不要按 ACP 落地，remote-control 也不是本地 provider 主链路。
• provider 必须拆成两条面：
  • live turn transport：prompt.send / turn.interrupt / request.respond
  • session catalog/history plane：threads.refresh / thread.history.read
• request.respond 必须按 subtype 分开处理：
  • can_use_tool
  • elicitation
• turn.steer 在 Claude v1 明确不支持；只允许 reject/problem + notice，不允许用 interrupt + prompt.send 伪装成 steer。
• v1 可以继续让 canonical threadId 承载 session_id，但持久状态与缓存键必须带 backend + instance_id + session_id。

检查参考

• 复核 hello capability gate 是否真正进入 daemon/orchestrator 派发决策，且不再对 Claude 实例无条件发送 threads.refresh。
• 复核 startup refresh pending 只统计真正派发了 refresh 的实例，避免拖住其他 surface 的恢复门控。
• 复核 threads.refresh / thread.history.read 是否已经与 live child 解耦，在没有运行中 child 时也能工作。
• 复核 request.respond 是否没有把 permission 与 elicitation 混成同一条回写路径。
• 复核 turn.steer 在 Claude provider 下是显式 rejected/problem，而不是 silent failure 或伪装成其他命令。
• 复核 get_context_usage / usage 汇总不落到 tick，api_retry 之类的可重试过程信号不被上升成 fatal runtime error。
• 复核 Codex+Claude 混合场景下不存在跨 provider 的 thread/session 选中、恢复或请求串扰。

收尾参考

• 若 Claude 基座、映射关系、阶段边界、/mode 语义或降级策略变化，统一回写：docs/inprogress/claude-backend-integration-plan.md。
• 旧文档 docs/obsoleted/claude-*.md 仅保留历史归档，不再承载新的实施结论。
• 若 canonical command/event 语义变化，回写：docs/general/relay-protocol-spec.md。
• 若 remote surface 状态流、attach/use/follow/new 约束变化，回写：docs/general/remote-surface-state-machine.md。
• 若 request/card 导航、旧卡片失效或 inline replace 规则变化，回写：docs/general/feishu-card-ui-state-machine.md。
• 若这次实现沉淀出新的通用 issue workflow / rebase / provider 接入 guardrail，再决定是否同步到 AGENTS.md 或 repo skill。

历史调研归档（保留）

说明：以下内容保留 2026-04-12 ~ 2026-04-13 的调研过程、备选路线和阶段判断，作为历史上下文；当前执行口径以上文“方案阶段（PoC）”为准。

展开历史调研与备选方案

背景

当前仓库的 relay / wrapper / orchestrator 大边界本身允许接入多种 agent backend，但产品层和状态层仍明显偏向 Codex app-server 语义。

在重新收窄边界后，本 issue 的前提调整为：

• Claude backend 只覆盖 normal mode
• 不兼容 vscode mode，不复用 VS Code 焦点、follow-local、ObservedFocusedThreadID 等语义
• 优先复用现有 canonical turn/item/request 事件模型，而不是先做全仓 thread -> session 名词重写
• 不合入 PR feat: add Claude CLI agent support alongside Codex #64；PR feat: add Claude CLI agent support alongside Codex #64 只作为调研材料

和上一版判断相比，这个约束变化很重要：

• 一旦去掉 vscode mode，很多此前“不 fit”的点其实不再构成 blocker
• 真正剩下的核心问题，不再是产品语义本身，而是 Go 仓库要通过哪条官方支持度足够高的 Claude 接入路径来落地这些能力

目标

设计并实现一条可演进的 Claude compatibility path，使仓库未来可以在当前架构上同时支持 Codex 与 Claude backend，并满足以下原则：

1. Claude backend 在产品层只匹配 normal mode 语义，不引入伪装的 VS Code mode
2. wrapper / canonical protocol / orchestrator 之间的边界对 agent capability 显式建模，而不是继续默认所有 backend 都具备 Codex thread 能力
3. 优先基于 Claude 官方公开能力实现：session / resume / streaming input / approvals / usage / CLI print mode，而不是直接绑定 PR feat: add Claude CLI agent support alongside Codex #64 里未正式收敛的 raw protocol 细节
4. normal mode 下 /list / /use / /new / request prompt / token usage / resume 等核心体验要能在能力降级前提下自洽，而不是形成半死流程

范围

本 issue 聚焦：

• 评估并抽象多-agent compatibility 所需的 capability model
• 明确 canonical threadID 在 Claude backend 下如何映射到 official session handle
• 收敛 normal mode 下需要保留的核心产品语义
• 确认 Go 侧的 Claude 接入路径
• 在确认接入路径后，分阶段落地 Claude normal-mode MVP

非目标

• 不合入 PR feat: add Claude CLI agent support alongside Codex #64
• 不支持 Claude backend 的 vscode mode
• 不要求第一阶段实现与 Codex 完全对等的 /follow、VS Code focus、same-turn steer 语义
• 不在第一阶段先做全仓 thread -> session 的命名迁移

相关文档

仓库内：

• docs/general/architecture.md
• docs/general/relay-protocol-spec.md
• docs/general/codex-mcp-app-server-protocol.md
• docs/general/remote-surface-state-machine.md

Claude 官方文档：

• https://code.claude.com/docs/en/agent-sdk/overview
• https://code.claude.com/docs/en/agent-sdk/sessions
• https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode
• https://code.claude.com/docs/en/agent-sdk/user-input
• https://code.claude.com/docs/en/agent-sdk/streaming-output
• https://code.claude.com/docs/en/agent-sdk/cost-tracking
• https://code.claude.com/docs/en/headless
• https://code.claude.com/docs/en/cli-usage

涉及文件

• internal/app/wrapper/app.go
• internal/core/agentproto/types.go
• internal/core/agentproto/wire.go
• internal/core/state/types.go
• internal/core/orchestrator/service.go
• internal/core/orchestrator/service_surface_actions.go
• internal/core/orchestrator/service_surface_attach.go
• internal/core/orchestrator/service_surface_thread_selection.go
• internal/core/orchestrator/service_thread_global.go
• internal/core/orchestrator/service_token_usage.go
• internal/app/daemon/surface_resume_state.go

建议范围

建议按阶段推进：

阶段 0：接入路径定型

接入路径已定型为：

1. 主路径：Direct SDK bridge（wrapper 通过轻量桥接进程调用官方 @anthropic-ai/claude-agent-sdk，走流式 query() + canUseTool 回调）
2. 非主路径：不以 claude -p --stream-json 作为生产主链路，只保留为诊断/回归对照手段
3. 边界原则：桥接层只做协议翻译与能力归一化；normal-mode 产品语义仍由 orchestrator 决策

阶段 0 的目标从“选型”改为“桥接契约固化 + PoC 验证”：

• 固化 Go wrapper <-> bridge 的 stdio/NDJSON 契约、错误码和重连语义
• 验证 approval / AskUserQuestion / resume / interrupt / usage 这些关键能力在桥接链路可稳定承接
• 明确可降级能力（尤其 turn.steer）的 command matrix 与 UI 提示策略

阶段 1：能力基座与 normal-mode 边界收敛

• 在 wrapper hello / runtime 中引入更完整的 capability matrix，而不是只有 ThreadsRefresh
• 明确 canonical conversation handle 的语义；第一阶段允许继续沿用 threadID 字段承载 Claude session ID
• 将 orchestrator 中 hard-coded Codex 假设改为 capability-aware 分支
• 显式禁止 Claude backend 进入 vscode-only 路径

阶段 2：Claude adapter MVP（normal mode only）

• 支持最小可用路径：
  • 发送 prompt
  • turn/item 流式输出
  • approval / user input 请求
  • interrupt
  • token usage 标准化
  • resume 已知 session
• 明确不支持或降级的能力：turn.steer、VS Code follow、VS Code focus

阶段 3：normal mode 产品闭环

• 让 /list / /use / /new / status / resume 在 Claude backend 下形成自洽体验
• 按 capability 对 Feishu UI 做禁用、提示和降级，而不是 silent failure
• 补齐状态机文档与测试

完成标准

满足以下条件后可关闭：

1. 已确认并记录 Go 侧的 Claude 接入路径，且该路径与官方公开能力边界一致
2. 仓库中存在明确的 capability model，wrapper 与 orchestrator 不再把 Codex thread 语义默认成公共事实
3. Claude backend 被正式收敛为 normal-mode-only，不会误入 vscode mode 或 follow-local 路径
4. Claude backend 至少支持 normal mode 下的一条完整主路径：attach/list/use/new 中的合理子集 + prompt + output + approvals + resume
5. 所有不支持的能力都有显式降级策略和 UI 提示，不存在静默坏状态
6. 对应文档与测试完成更新

重新调研结论（仅看 normal mode）

结论摘要

在只保留 normal mode 的前提下，Claude 与当前产品模型的匹配度明显高于上一版判断。

新的判断是：

• normal-mode 语义整体可做
• 接入路径已定型为 Direct SDK bridge，主要工作转为桥接细节与状态一致性收敛
• 只要 session / approval / streaming 这些能力按官方支持路径接入，当前 canonical turn/item/request 模型无需大改就能承接 Claude

高匹配能力

1. Session / resume / fork / enumerate

   • 官方明确支持 session 持久化、continue、resume by ID、fork
   • 官方还提供 listSessions() / getSessionMessages() / getSessionInfo() / renameSession() / tagSession()
   • 这意味着 current threadID 可以先直接承载 Claude session_id

2. 流式输出与 turn/item 映射

   • 官方明确支持 stream-json、StreamEvent、AssistantMessage、ResultMessage
   • message_start / content_block_start|delta|stop / message_delta / message_stop 这些事件与当前 turn.started、item.started/delta/completed、turn.completed 的 canonical 结构基本可对齐

3. approval / AskUserQuestion

   • 官方明确说明 tool approval 和 clarifying question 都走 canUseTool
   • AskUserQuestion 直接提供问题与选项结构
   • 这与当前飞书 request prompt / request.started / request.respond 的产品抽象高度一致

4. streaming input / interrupt / queued messages

   • 官方明确支持长会话、interrupt、追加上下文、构建 chat interface
   • 这意味着虽然不一定能 1:1 复刻 Codex 的 turn.steer，但“执行中继续补充信息/打断重定向”并非做不到

5. usage / cost

   • 官方明确提供 assistant message 级 usage、result 级 cumulative usage、total_cost_usd、modelUsage
   • 当前 final summary / token usage 面板可以承接这类数据，只是聚合口径需要重新定义

中等匹配能力

1. /new

   • 当前 normal-mode /new 的基础要求很低：只要有 workspace key / cwd 就能开始新会话
   • 这一点与 Claude 天然契合，是高可行路径

2. /use

   • 只要 session catalog 可得，并且支持 resume by ID，/use 就能成立
   • 真正需要补的是 catalog 进入 orchestrator 的方式，而不是产品语义本身

3. /list / /useall

   • 单 workspace 下列出现有会话问题不大
   • 真正复杂的是 current product 还有“跨 workspace recent sessions”视图；Claude 官方 session 能力存在，但我们还需要决定是自己维护全局 recent index，还是扫描 / 同步本地 session 存储

4. surface resume / reconnect

   • 官方明确支持 resume=session_id
   • 但官方也明确写了两个约束：session 文件是本机本地文件，并且 cwd 必须匹配
   • 对本仓库的本地 daemon + 本地 workspace 场景来说这不是 blocker，但需要在恢复链路里显式建模，而不是像 Codex 那样假设“只要 threadID 在就一定可恢复”

5. token usage 汇总

   • 官方能给 per-step 与 per-call usage
   • 但没有天然的“session-level total across all query() calls”总账
   • 如果我们还想保留 current thread.token_usage.updated 的“总上下文量”语义，需要自己聚合或降级展示

低匹配或应明确降级的能力

1. vscode mode / follow-local / focus-retarget

   • 在本 issue 约束下全部排除，不应尝试兼容

2. 精确等价的 turn.steer

   • Claude 的 streaming input 能支持执行中继续追加消息与 interrupt
   • 但这不等于 current Codex turn.steer(expectedTurnId) 的精确同语义
   • 这项能力更适合 capability-gate + 产品降级，而不是强行伪装成完全一致

深入调研（接入细节与可行性）

A. 已确认的实现方向（针对本仓库）

1. wrapper 仍保持 Go 主进程；新增 Claude adapter 采用“外部 bridge 进程 + stdio 协议”而不是重写 orchestrator。
2. bridge 内部直接调用官方 Agent SDK：
   • prompt 输入通过 query({ prompt: AsyncIterable, options })
   • tool approval / question 通过 canUseTool
   • 会话续接通过 resume: session_id
3. canonical 协议层继续沿用 threadId 字段承载会话句柄（阶段 1 不做全仓字段改名），并在 metadata 显式标记 provider=claude 与 cwd 绑定信息。

B. 与当前代码现状的差距（已定位）

1. internal/app/wrapper/entry.go 当前硬编码只支持 codex app-server 入口，需要扩成 provider-aware wrapper 入口。
2. internal/app/wrapper/app.go 当前实例 hello 只上报 ThreadsRefresh 单能力，无法表达 turn.steer、request 交互、session catalog 等 capability 差异。
3. internal/adapter/ 当前只有 codex translator；Claude 需要新增并行 adapter，而不是在 codex translator 上堆分支。
4. internal/app/daemon/app_ingress.go 在 hello 后默认发送 threads.refresh，需要改为 capability-aware（不支持时走降级路径）。

C. 可行性判断（normal mode only）

1. 高可行：prompt -> turn/item stream -> turn completed 主链路、approval/question roundtrip、interrupt、resume（同 cwd）。
2. 中可行：/list / /use / /useall，需要先定义 session catalog 来源（SDK API + 本地会话文件扫描策略）与刷新时机。
3. 需要显式降级：turn.steer(expectedTurnId) 强一致语义；第一版应 capability-gate 并给出用户可见提示。
4. 可控风险：token usage 口径差异（per-call vs session cumulative）通过“口径标注 + 聚合策略”可控。

D. 阶段 0 PoC 验收口径（新增）

1. 单 surface 能完成：首条 prompt、流式输出、turn 完成、usage 上报。
2. 能触发并完成：一次 approval、一次 AskUserQuestion 回答回传。
3. 能验证：同 session_id + cwd resume 成功；故意更换 cwd 时返回可识别错误并给出提示。
4. interrupt 后可继续在同会话发送下一条 prompt，且不会污染 request 状态机。
5. turn.steer 在 Claude provider 下返回明确“能力不支持/已降级”而非 silent failure。

E. 建议的 capability matrix（阶段 1 草案）

建议把 hello capabilities 从“单布尔位”扩成可枚举能力集，至少包含：

1. supports_threads_refresh
2. supports_turn_steer
3. supports_request_respond
4. supports_session_catalog
5. supports_resume_by_thread_id
6. requires_cwd_for_resume
7. supports_vscode_mode

Claude normal-mode 目标默认值建议：

• supports_threads_refresh = false（改走 session catalog 刷新命令）
• supports_turn_steer = false（显式降级）
• supports_request_respond = true
• supports_session_catalog = true
• supports_resume_by_thread_id = true
• requires_cwd_for_resume = true
• supports_vscode_mode = false

F. bridge 协议最小草图（阶段 0 输出物）

为避免一次性改动过大，建议先定义最小双向消息集：

1. daemon/wrapper -> bridge commands
   • session.start_or_resume
   • prompt.send
   • turn.interrupt
   • request.respond
   • session.list
2. bridge -> daemon/wrapper events
   • session.bound
   • turn.started / item.started / item.delta / item.completed / turn.completed|failed
   • request.started / request.resolved
   • usage.updated
   • sessions.snapshot
   • problem.reported
3. 错误与恢复要求
   • 所有命令具备 request_id
   • 错误返回 machine-readable code + message + retryable
   • bridge 重启后可凭 session_id + cwd 尝试恢复，失败时上报明确失败原因

当前 blocker

接入路径已定型后，当前 blocker 变为 桥接细节与状态一致性尚未验证完成：

1. bridge 协议契约尚未落地（事件顺序、错误码、重启与幂等语义）
2. session catalog 进入 orchestrator 的策略尚未固化（刷新源、分页、recent 聚合）
3. Claude provider 下 command matrix 未完全 capability-gate（尤其 turn.steer、threads.refresh）
4. token usage 的聚合口径与 UI 呈现规则尚未最终确认

因此本 issue 仍保持 needs-investigation，但 investigation 的目标已收敛为“实现前的桥接 PoC 与降级策略定稿”，不再是接入路径选型本身。

重新估算工作量

在只做 normal mode 的前提下，工作量低于上一版：

• 阶段 0（bridge 契约 + PoC）：约 3~5 天
• Claude normal-mode MVP：约 1.5~2 周
• 做到 /list / /use / /new / resume / request / usage 较自洽：约 2~4 周

2026-04-13 复核结论（历史结论，已被 2026-04-23 二次深调研替代）

以下结论为历史记录，不再作为当前执行判定。

结论更新为：可以开始阶段 0。

原因不是“所有细节都已经完全确定”，而是当前剩余问题已经从“是否存在可靠接入路径”收缩为“按既定路径完成桥接契约与 capability 基座实现”。这两类问题适合通过阶段 0 的实现与测试来收敛，不再构成继续停留在 needs-investigation 的理由。

为什么现在可以开工

1. 官方能力边界已经足够清楚：session / resume、canUseTool、AskUserQuestion、partial streaming、usage 都有明确承接面；其中 resume 受 cwd 约束、session 文件本地化，这些限制已经可直接转成产品/状态约束，而不是未知风险。
2. 当前仓库的主要结构缺口已能精确落点到实现位点，而不是停留在抽象层：
   • wrapper 入口目前仍是 codex-only
   • hello capability 目前只有 ThreadsRefresh
   • daemon hello 后仍强制发送 threads.refresh
   • orchestrator 的 request.respond 链路本身已较 provider-agnostic，可直接复用
   • turn.steer 已有 ack/reject 回路，可改成 capability-gate + 显式降级，而不是另起一套状态模型
3. 命令矩阵已经能先定义出一版稳定降级：
   • prompt.send、turn.interrupt、request.respond、resume：阶段 0/1 可直接做
   • threads.refresh：改成 provider-aware，不再默认要求所有 backend 实现
   • turn.steer：第一版明确不支持，走 rejected/problem + UI 提示
4. 阶段 0 的验收口径已经足够具体，可以直接驱动实现与测试，不需要再额外做一轮选型调查。

阶段 0 最小实现合同（建议直接按此开工）

1. 协议与实例能力

   • 扩展 agentproto.Capabilities，至少覆盖：
     • threadsRefresh
     • turnSteer
     • requestRespond
     • sessionCatalog
     • resumeByThreadID
     • requiresCWDForResume
     • vscodeMode
   • daemon 在 instance state 中持久化 hello capabilities，后续命令派发都基于实例能力判断。

2. daemon hello 启动分支

   • onHello() 不再无条件发送 threads.refresh
   • 有 threadsRefresh 能力时走现有刷新路径
   • 无该能力但有 sessionCatalog 时改走新 catalog 刷新命令/路径
   • 两者都没有时，normal mode 也必须留下明确可见的“当前 backend 不支持会话目录刷新”提示，不能默默缺失

3. wrapper/provider 入口

   • wrapper 入口改成 provider-aware
   • codex 与 claude adapter 分离，避免在 codex translator 内堆 provider 分支
   • Claude 侧按 Direct SDK bridge 落一条最小 stdio/NDJSON 契约：session.start_or_resume、prompt.send、turn.interrupt、request.respond、session.list

4. command matrix 与降级规则

   • request.respond：保持 canonical 结构，不做 provider-special case
   • turn.steer：阶段 0 明确 capability-gate；在 Claude provider 下应走 command reject / problem，并把 notice 文案做成“当前 backend 暂不支持执行中追加输入，请等待当前轮结束后再发送下一条”这一类显式提示
   • threads.refresh：不能再作为系统级默认能力写死在协议假设里

5. 阶段 0 非目标

   • 不做全仓 thread -> session 字段重命名
   • 不做 vscode mode / follow-local 兼容
   • 不做与 Codex 完全等价的 turn.steer
   • 不在阶段 0 解决跨 workspace recent index 的最终形态；先支持 provider-local session catalog 即可
   • token usage 先按 turn/query 级口径打通，session 总账可后置

阶段 0 建议首批涉及文件

• internal/core/agentproto/wire.go
• internal/core/state/types.go
• internal/app/daemon/app_ingress.go
• internal/app/wrapper/entry.go
• internal/app/wrapper/app.go
• internal/core/orchestrator/service_helpers_threads.go
• internal/core/orchestrator/service_surface_actions.go
• internal/core/orchestrator/service_snapshot_runtime.go
• internal/adapter/claude/**（新增）

阶段 0 必测点

1. hello capability 分支：Codex 仍保持现状，Claude 不再被错误要求 threads.refresh
2. Claude provider 下首条 prompt -> 流式输出 -> turn completed
3. approval 与 AskUserQuestion 能经 request.started / request.respond 闭环返回
4. session_id + cwd resume 成功；故意错 cwd 时得到 machine-readable 错误，并投影成用户可见提示
5. turn.steer 在 Claude provider 下不会 silent failure，会稳定 rejected 并恢复 queue / notice 状态
6. interrupt 后同 session 再次发送 prompt 不会污染 request/queue 状态

当前状态更新

因此本 issue 从 2026-04-13 起不再继续维持 status:needs-investigation。后续默认按“阶段 0 可开工”处理；如果实现中发现 bridge 契约或官方 SDK 行为与当前结论不符，再单独回退状态。

2026-04-13 补充调研：PoC 不干扰现有功能的隔离方案

目标是：Claude PoC 上线前，现有 Codex 路径行为保持不变。基于当前代码复核，结论是可以做到，但要先加“强隔离护栏”。

关键风险（本次新增）

1. 目前 onHello() 会对所有实例无条件发送 threads.refresh，并把实例计入 startup refresh pending。
2. initialThreadsRefreshRoundComplete 是全局门控；若某个 PoC 实例长期不产出 threads.snapshot，可能影响其他 surface 的恢复判定。
3. 当前 Hello.Capabilities 还没进入 daemon/orchestrator 的调度决策，默认行为仍是“按 Codex 能力假设发送命令”。

隔离原则（必须同时满足）

1. 默认关闭：不显式开启 PoC 时，二进制与运行时行为等价于当前 master。
2. 路径隔离：Codex adapter 与 Claude adapter 分离，不在 codex translator 里混分支。
3. 实例隔离：PoC 实例必须显式 source=claude（或等价专用 source），禁止复用 vscode/headless 语义。
4. 能力隔离：所有可能不兼容命令必须先 capability-gate，再决定是否派发。
5. 回退简单：关闭 PoC 开关即可回到纯 Codex 路径，不需要数据迁移。

阶段 0 需要先落地的“防干扰护栏”

1. wrapper/provider 入口：
   • 保持现有 wrapper app-server Codex 路径不改语义；
   • Claude 仅走独立入口（例如显式 provider 参数或独立子命令），避免默认路径误入。
2. hello capability 生效：
   • daemon 必须持久化实例能力并在发命令前检查；
   • threads.refresh 仅对 supports_threads_refresh=true 实例发送。
3. startup refresh 门控修正：
   • 仅在确实发送了 threads.refresh 时标记 pending；
   • 对不支持该能力的实例，不进入 pending（或立即 settled），避免拖住全局恢复门控。
4. command matrix 显式降级：
   • turn.steer、threads.refresh 等不支持能力返回明确 rejected/problem + 用户可见提示；
   • 禁止 silent failure。
5. 发布隔离：
   • shipping 默认不启用 Claude PoC；
   • PoC 先限定在 dev/beta 实例验证，不影响 stable 实例。

新增完成标准（不干扰验收）

在原有完成标准基础上，新增以下硬验收：

1. 未开启 PoC 开关时，Codex 回归用例全通过且关键日志行为一致（hello 后仍正常 threads.refresh）。
2. 同机并存 Codex + Claude 实例时，Claude 实例不会阻塞 Codex 的 surface resume/headless restore 判定。
3. Claude 不支持命令的失败是显式、可见、可恢复的，不会污染 queue/request 状态。
4. 关闭 PoC 开关后，无需清理状态即可恢复纯 Codex 运行。

2026-04-13 需求澄清（以本节为准）

你最新确认的方向是：双后端兼容优先，而不是激进隔离优先。

具体落地口径：

1. 架构上允许 Codex / Claude 在同一系统并存，通过实例能力与 provider 路由区分，而不是做两套割裂流程。
2. 与 Codex 实例交互时，不应触发 Claude 侧逻辑或降级分支；Codex 行为保持当前语义。
3. 与 Claude 实例交互时，若某能力暂不支持（如 turn.steer），允许直接返回显式错误/拒绝，并给用户可见提示。
4. 不要求为了 PoC 先做“全局禁用式隔离”；重点是实例级不串扰和可预期失败。

对应实现策略更新：

• 把“防干扰”从全局强开关，收敛为实例级 capability-gate + provider-aware dispatch。
• daemon/orchestrator 的命令派发必须先看目标实例能力，再决定发送或拒绝。
• unsupported command 的标准结果是 command_rejected/problem + UI notice，而不是沉默或跨实例 fallback。

对应验收补充：

1. 混合场景（同机 Codex + Claude）下，Codex 常用路径不回归。
2. Claude 不支持命令能稳定给出显式错误，并且不污染其他实例状态。
3. 同一 surface 切换到不同 provider 实例时，行为由实例能力决定，不出现跨 provider 误触发。

2026-04-13 补充约束：backend 数据分区与并行语义

新增硬约束：

1. workspace 可跨 backend 共享（Codex/Claude 可同时操作同一目录）。
2. thread/session 数据必须按 backend 隔离，不能在 /list 和 /use 中混用。
3. /list 默认只看当前 attached instance 的 backend 视图；若有汇总视图也必须按 backend 分组。
4. /use 仅在当前 backend 解析会话 ID；跨 backend ID 必须显式报错，不做隐式跳转。
5. surface resume 必须携带 backend 维度，避免把 A backend 的会话误恢复到 B backend。

该约束已同步到方案文档：

• docs/inprogress/claude-normal-mode-poc-design.md（5.4、6.1、阶段与验收条目）

2026-04-13 补充约束：/mode 作为 backend 产品入口

新增产品决策：

1. /mode codex = 当前 normal 语义；/mode normal 兼容为 codex 别名。
2. /mode vscode 保持现有语义。
3. /mode claude 切到 Claude normal 语义。

切换 codex <-> claude 的状态处理：

• 保留：workspace 信息。
• 清空：除 workspace 外的当前 surface 会话态（instance/thread/queue/pending request/active turn/暂存输入与图片/会话恢复目标的 thread 部分）。
• 读取：目标 backend 的 workspace 参数命名空间（model/reasoning/access 按 backend 隔离）。

目标是让用户始终知道“当前正在和哪个 backend 交互”，并避免 backend 会话态串扰。

该决策已同步到方案文档：

• docs/inprogress/claude-normal-mode-poc-design.md（5.5、6.2、阶段与验收条目）

2026-04-13 补充约束：旧版本数据升级

实现时必须显式考虑旧版本持久化数据的兼容/升级。

原则：

1. 旧数据缺失 backend 维度时，默认按 codex 解释。
2. 升级后不能因为缺少 backend 字段导致 surface resume、workspace 默认配置或旧 normal 用户路径失效。
3. 能 lazy 兼容的优先 lazy 兼容；仅在结构冲突明显时再做显式迁移。
4. 若某状态不能安全迁移，必须采用“可恢复的默认行为 + 明确说明”，不能 silent break。

重点数据面：

• surface resume state
• workspace defaults / prompt override
• instance/thread 相关持久状态
• 任何把 thread id 当全局唯一键使用的缓存

该约束已同步到方案文档：

• docs/inprogress/claude-normal-mode-poc-design.md（5.6、阶段 A、验收与风险）

2026-04-13 深化设计补充（主方案继续细化）

本轮继续深化了主方案，不新增子 issue，重点补齐了下面几类此前仍偏抽象的点：

1. 状态结构职责

• 建议显式区分 Backend 与 Source：
  • Backend 表达会话协议面（codex / claude）
  • Source 表达实例来源（vscode / headless / claude）
• 避免继续把“来源”和“后端”混用在同一个字段里。

2. 命令派发顺序

• 固定为：surface -> attached instance -> backend/capabilities -> mode gate -> command gate -> dispatch/reject
• 禁止当前实例不支持时 silent fallback 到别的 backend/实例。

3. /mode codex|claude|vscode 切换契约

• codex <-> claude 切换前若仍有 active turn / pending request / dispatching queue，默认拒绝切换。
• 切换成功后，除 workspace 外的 surface 会话态全部清空，并重建目标 backend 的命令视图。

4. 阶段交付物更具体

• 阶段 A 现在不仅是护栏，还要求落下 backend-aware 基础状态结构草图。
• 阶段 C 明确要求补 /mode 状态清理测试，以及 backend-aware workspace 参数读写闭环。

已同步到方案文档：

• docs/inprogress/claude-normal-mode-poc-design.md（5.7、6.0、6.2 深化内容，以及阶段/验收更新）

2026-04-26 最新复核（当前仓库代码 + 最新 feidex）

本轮按当前 master 代码与 yuhuan417/feidex 最新 main 重新复核，结论更新如下：

1. #185 继续作为“Claude backend 基座 / provider seam”母单保留，暂不新开新的 Claude backend 母单。
2. 当前仓库的核心结构缺口仍然存在，且比前一轮更明确：
   • agentproto.Capabilities 仍只有 ThreadsRefresh
   • wrapper 入口仍只支持 app-server
   • wrapper runtime 仍直接持有 *codex.Translator
   • daemon onHello() 仍无条件发送 threads.refresh
   • InstanceRecord / WorkspaceDefaults 仍无 backend 维度
   • surface resume 持久层仍无 backend 分区
   • daemon 启动时挂接的 persisted thread catalog 仍然是 Codex-only
   • /mode parser 仍只有 normal|vscode
3. 最新 upstream Claude 兼容细节需要直接吸收进本仓库设计护栏：
   • abddb95: Claude runtime 退出时需要 completed reconciliation，不能假设一定收到单一 completed 事件
   • 6d05ba7 + b454943: plan approve/reject 这类卡片交互应优先走 callback response inline replace，而不是异步 patch
   • 8c895e9: quiet/progress 文件聚合必须按稳定全路径去重，不能只按显示文件名
   • ff0c522 + docs/capabilities.md: “Claude 缺很多本地产品能力”的旧判断已经失效；backend-aware help/menu filter、/history、/model、/effort、/session permissions、/session fork、/compact passthrough 都已被 upstream 证明可落地
4. 结论不变：本 issue 仍应保持 status:needs-investigation，但 investigation 的重点已经进一步收口为：
   • provider identity / capability seam
   • backend-aware state partition
   • completed reconciliation
   • request/card 交互收口
   • 命令策略矩阵（native / approximation / passthrough / reject）
5. 同步动作：主设计文档已刷新到 docs/inprogress/claude-backend-integration-plan.md（Updated: 2026-04-26）。

2026-04-26 与 #369 的 ownership 切分

为避免 backend seam 与 catalog seam 继续重叠，本 issue 明确拥有：

1. protocol / runtime seam
   • agentproto.Capabilities
   • wrapper/provider runtime 分层
   • hello / onHello() capability gate
2. backend-aware state partition
   • InstanceRecord.Backend
   • backend-aware WorkspaceDefaults
   • surface resume backend persistence
   • thread/session 持久键分区
3. backend 切换的产品语义约束
   • /mode codex|claude|vscode 的真实状态切换语义
   • 切换时的状态清理、恢复、安全门控

本 issue 不拥有：

1. family / variant / resolver 抽象
2. help/menu 的 backend-aware display
3. slash/menu parse
4. callback payload provenance
5. variant-specific page / owner-flow 接线

上述内容归 #369 持有；#369 的首张子 issue #462 只应消费本 issue 已提供的 seam，不应回头再拥有协议字段或状态 schema 设计。

当前依赖关系：

• #462 已因 #463 落地完成 unblock 判定；后续由 #369 继续消费这段 seam。

2026-04-27 状态重判（workflow）

按当前代码、文档与依赖关系重新判定后，#185 已不再适合继续维持为未拆分调查单。

结论：

1. 技术调查已经足够支撑拆分，不再只是“继续广泛摸底”。
2. 当前真正缺的是稳定执行计划和子 issue ownership，而不是继续把所有 seam 问题堆在母单里。
3. 因此本 issue 从 status:needs-investigation 收口到 status:needs-plan。
4. 最近动作已完成：#463 已实现 hello/backend/capability gate，并解除 #462 的最近 blocker。

2026-04-29 #500 拆分落地

1. #500 已从母单草图落成 4 张真实子单：#501、#502、#503、#504。
2. 当前 next ready unit 是 #501（Claude profile schema + launch contract）。
3. #500 继续保持 status:needs-plan，只承担母 issue 调度；后续执行顺序为 #501 -> #502 -> #503 -> #504。

2026-04-29 Claude MVP refresh delta follow-up

1. 2026-04-29 新产品决议已同步进文档基线：docs/inprogress/claude-backend-integration-plan.md 第 7.6 / 12.1 节为当前 Claude MVP 定义 source of truth。
2. 已关闭的 #496 代表上一轮 dev-visible Claude MVP 闭包；它的完成标准与当前新决议已经不一致，不再作为这轮 delta 的继续执行单。
3. 已新建 #510 作为本轮执行入口：它只承担“重审当前实现偏移 + 生成执行拆分”，不直接承担生产补丁。
4. 当前 next ready unit 改为 #510；在它产出稳定的偏移清单与执行闭包前，不要直接重开 #496 或口头驱动零散补丁。

2026-04-29 #510 审计收口与 next ready unit 更新

1. #510 已完成当前主线的事实审计与执行拆分，不再直接承担生产补丁。
2. #510 现已正式拆出两张实现子单：#512、#513。
   • #512：Claude 命令面刷新 + backend-only target filtering
   • #513：workspace-preserving backend switch + new-thread-ready + bad-state escape 收口
3. #511 继续保持 parked follow-up，只承接 resume headless 必要性 / 产品语义 / 残留清理 contract 的后续重审，不阻塞当前主线。
4. 当前 next ready unit 更新为 #512；恢复时不要再回到 #496，也不要停留在 #510 做补丁式直改。

2026-04-29 #512 完成后 next ready unit 更新

1. #512 已完成实现、验证、push 与关单。
2. #510 继续作为 Claude MVP refresh delta 的调度母单保留。
3. 当前 next ready unit 更新为 #513。
4. #511 继续保持 parked follow-up，不阻塞当前主线。

2026-04-29 #513 完成后 #510 close-out ready

1. 子 issue #510 已完成并关闭，结果回卷如下：
   • #510 已完成本轮 Claude MVP refresh delta 的事实审计、执行拆分与子单调度。
   • 主线子单 #512 / #513 已全部完成：
     • #512 收口了 Claude 命令面刷新与 backend-only target filtering。
     • #513 收口了 Claude <-> Codex normal 的 workspace-preserving backend switch、new_thread_ready 默认落点，以及 workspace-level normal-surface fresh-start recovery。
   • docs/inprogress/claude-backend-integration-plan.md 与 docs/general/remote-surface-state-machine.md 已与当前 live behavior 对齐。
   • #511 继续保持 parked follow-up，不阻塞本轮 #510 关单。
2. 当前 next ready unit 从 #513 更新为 #510 close-out；完成母单 close-out 后，不自动把 #511 提升为主线执行单。
3. 若后续需要继续重审 resume headless 的产品语义与残留清理 contract，再单独恢复 #511。

[kxn]

基于“Claude backend 只覆盖 normal mode、不兼容 vscode mode”的新约束，重新调研后已更新 issue body。

当前结论：

• normal-mode 语义的匹配度明显高于上一版，/new、/use、/list、approval / AskUserQuestion、resume、streaming output 都存在较清晰的官方能力对位
• 当前最大 blocker 已从“产品模型不 fit”收缩为“Go 侧接入路径尚未定型”
• 在 transport / bridge 选型明确前，不建议直接进入实现阶段

因此本 issue 先切到 status:needs-investigation，等待把 Claude 的接入路径收敛清楚后再开工。

[kxn]

已按当前决策把本 issue 更新为 Direct SDK bridge 路线，并继续补了实现细节调研。补充结论如下：

1. 当前仓库需要先补 provider-aware 基座，再接 Claude bridge：

• wrapper 入口目前只接受 codex app-server，要先放开 provider 分支；
• hello 能力目前只上报 ThreadsRefresh，还不足以表达 Claude 下的能力降级；
• daemon 在 hello 后默认发 threads.refresh，需要改成 capability-aware 分支。

2. normal-mode 主链路可行性较高：

• prompt -> streaming turn/item -> completed
• approval / AskUserQuestion 回路
• interrupt + resume(session_id)

3. 需要先明确并落地的风险点：

• bridge 协议契约（事件顺序、错误码、重连幂等）
• session catalog 进入 orchestrator 的刷新策略
• turn.steer 的显式降级（不能 silent failure）
• token usage 聚合口径

4. 建议按“阶段 0 PoC 验收口径”推进：

• 跑通主链路、approval/question、resume(cwd 匹配)、interrupt 后续发言
• 验证 cwd 不匹配恢复失败时有明确错误提示
• 验证 Claude provider 下 turn.steer 的 capability-gate 与用户可见提示

如果你确认，我下一步就按这个口径直接做阶段 0 的最小 PoC 设计和接口草图（先不改业务语义，只固化 bridge contract 与 capability matrix）。

[kxn]

复核到 2026-04-13，当前结论更新为：这个 issue 已经足够开始阶段 0，不再需要继续停留在 status:needs-investigation。

这次补充确认了几件关键事：

• 官方能力边界已经足够落到实现：session/resume、canUseTool、AskUserQuestion、partial streaming、usage 都有清晰承接面；resume 的 cwd 约束也已经是可建模约束，不是未知风险。
• 当前仓库的缺口已能精确落到代码位点：wrapper codex-only 入口、hello capability 过窄、daemon hello 后强制 threads.refresh，以及 turn.steer 需要 capability-gate。
• request.respond 链路本身已经较通用，第一阶段不需要因为 Claude 单独重做 request 状态机；主要是把 provider 能力显式化，把不支持的命令改成显式拒绝而不是 silent failure。

我已把 body 补成“阶段 0 最小实现合同 + 首批涉及文件 + 必测点”，建议后续就按这个边界直接开工。