Feat: tRPC-Agent对齐Claude Code Plan Mod能力

[CongkeChen]

Feature:

• 参考claude code 的工具设计、提示词设计进行框架plan mod能力的设计与实现。
• 支持模型主动进入plan 模式 & 用户主动选择plan模式。
• 支持agui 解析 toolset能力

BugFix:

• 修复agui协议传递state数据无法有效更新问题。

Doc:

• 支持plan mod指引文档。
• 单独列出todowrite、task、goal的指引文档。

[CongkeChen]

AI Code Review

审查结论

不通过

审查范围：本次提交 e113610..526631f 为「tRPC-Agent 对齐 Claude Code Plan Mode 能力」特性，新增 trpc_agent_sdk/plan_mode 子包（状态机、HITL 长任务工具、写工具门禁、锁与存储）、AG-UI 侧嵌套 toolset 的长任务工具名抽取与会话回查补全、update_session_state 由 partial=True 改为 partial=False 以修复状态持久化，并配套示例与测试。计划符合性：整体对齐了进入/起草/审批/退出流程与只读门禁语义，partial=False 变更有专项测试覆盖。主要风险：发现 1 个高置信正确性缺陷——_ensure_forced_plan 在计划已 APPROVED 后仍会因 agent_mode 未清除而重新创建 EXPLORING 计划并重新激活写门禁，破坏审批后实现路径。测试充分性：状态机、HITL 标准化、锁释放、UI 自动进入等均有覆盖，但缺少「计划审批后继续会话」这一关键路径的回归测试，故缺陷未被捕获。门禁结论：存在 SEVERE 级正确性缺陷，不通过。

发现的问题

严重

trpc_agent_sdk/plan_mode/_controller.py:124-135

问题： _ensure_forced_plan 仅在已存在计划且 is_gate_active() 或状态为 PENDING_ENTER 时跳过自动进入；当已存在计划的状态为 APPROVED（gate 未激活）时，_should_force_enter 仍为真（会话 state 中 agent_mode 仍为 plan），apply_enter 因此创建一个全新的 EXPLORING 计划并覆盖既有已批准计划，重新激活写工具门禁。

触发条件： 在 AG-UI Plan Mode 流程中计划经 exit_plan_mode 获批进入 APPROVED 后，会话 state 的 agent_mode 未被任何代码清除（示例 buildRunState() 始终发送 agent_mode=plan）；用户随后发送一条普通实现指令（非 HITL 恢复），触发 before_model 中的 _ensure_forced_plan。

实际影响： 已批准计划被新 EXPLORING 计划覆盖，写工具（Write/Edit/Bash/task_create 等）再次被 before_tool 门禁拦截，导致计划通过审批后无法进入实现阶段——核心功能在 SDK 自带示例的默认流程下即可复现。

修正方向： 在 _ensure_forced_plan（或 apply_enter）中增加终态判断：当 existing.status == PlanStatus.APPROVED 时跳过自动进入（或要求先清理/归档旧计划）；或在审批通过时由 apply_approval_decision 清除 force_enter_plan_state_key 指定的会话信号，使自动进入不再重复触发。

[CongkeChen]

问题： _ensure_forced_plan 仅在已存在计划且 is_gate_active() 或状态为 PENDING_ENTER 时跳过自动进入；当已存在计划的状态为 APPROVED（gate 未激活）时，_should_force_enter 仍为真（会话 state 中 agent_mode 仍为 plan），apply_enter 因此创建一个全新的 EXPLORING 计划并覆盖既有已批准计划，重新激活写工具门禁。

触发条件： 在 AG-UI Plan Mode 流程中计划经 exit_plan_mode 获批进入 APPROVED 后，会话 state 的 agent_mode 未被任何代码清除（示例 buildRunState() 始终发送 agent_mode=plan）；用户随后发送一条普通实现指令（非 HITL 恢复），触发 before_model 中的 _ensure_forced_plan。

实际影响： 已批准计划被新 EXPLORING 计划覆盖，写工具（Write/Edit/Bash/task_create 等）再次被 before_tool 门禁拦截，导致计划通过审批后无法进入实现阶段——核心功能在 SDK 自带示例的默认流程下即可复现。

修正方向： 在 _ensure_forced_plan（或 apply_enter）中增加终态判断：当 existing.status == PlanStatus.APPROVED 时跳过自动进入（或要求先清理/归档旧计划）；或在审批通过时由 apply_approval_decision 清除 force_enter_plan_state_key 指定的会话信号，使自动进入不再重复触发。