pref(runtime):重构完成验收链路，将正确性验证从 Accept Gate 下沉到 Hook

[phantom5099]

closes: #634

背景问题

当前完成验收链路里，Accept Gate 同时承担了两类职责：

1. 系统级预检
   例如是否有可见输出、todo 是否进入合理状态。
2. 任务正确性验证
   例如是否发生 workspace 写入、是否执行过命令、文件是否存在、内容是否匹配等。

这导致了几类问题：

• Accept Gate 通过查询 RuntimeFacts 判定“任务是否做对”，但 facts 只能说明“发生过什么”，不能证明“结果是否正确”。
• Plan.Verify 由模型自己生成，系统再按模型生成的条件验收，存在“模型自己出题、自己答题”的闭环偏差。
• Hook 审查层缺失，用户无法在模型声称完成时插入真实验证逻辑，例如重新执行测试、构建、lint。
• 验收失败后只有 Accepted / Failed 两个终态，模型没有机会根据失败原因继续修复。
• before_completion_decision 这类仅观测、不影响 loop 的 hook point 缺少明确价值，容易扩大无效 API 面。
• RuntimeFacts 还承载了部分与验收无关的聚合数据，例如 SubAgentSnapshot，导致职责混杂。

解决方案

本次改动将完成验收链路调整为：

模型无 tool calls
  -> 如本 run 有 workspace 变更，先触发 accept_gate hook
      -> hook block：注入原因，继续 loop
      -> hook pass：继续
  -> Accept Gate 仅执行系统级预检
      -> 可恢复问题：继续 loop
      -> 不可恢复问题：终止
      -> 通过：完成

核心决策：

• Hook 先于 Accept Gate

  • 正确性验证优先交给用户 Hook。
  • accept_gate 支持 block，用户可以通过脚本真正决定“是否放行”。

• Accept Gate 收缩为系统预检

  • 只保留：
    • 是否有可见输出
    • required todo 是否失败
    • required todo 是否仍未收敛
  • 不再承担 workspace、命令、文件、内容等正确性判断。

• 新增 Continue 路径

  • Hook block、空输出、required todo 未收敛都可以回到 loop。
  • 通过注入 hint 让模型继续修复，而不是直接把 run 杀掉。
  • 设置 continue 次数上限，防止无限循环。

• 删除 Plan.Verify

  • 去掉模型自定义验收条件的整套类型和渲染链路。
  • 旧 plan JSON 中的 verify 字段由反序列化自然忽略。

• 删除 RuntimeFacts 验收体系

  • 移除 facts collector 及其与 Accept Gate 的耦合。
  • 保留确实有产品价值的能力时，改为独立机制实现。

• 恢复独立的 SubAgentSnapshot

  • 不再依附 RuntimeFacts。
  • 由 runState 独立维护子代理聚合计数，并继续向 Gateway / TUI 暴露。

具体修改范围

1. Accept Gate 重构

涉及：

• internal/runtime/acceptgate/
• internal/runtime/acceptgate_runtime.go
• internal/runtime/controlplane/stop_reason.go

主要改动：

• 删除旧的 5 类内容正确性检查。
• 新增 OutcomeContinue 与 ContinueHint。
• 将 required todo 未收敛从直接失败改为可继续修复。
• 保留“无可见输出”预检，避免 run 空白结束。

2. Hook 系统增强

涉及：

• internal/runtime/hooks/
• internal/runtime/user_hooks.go
• internal/runtime/repo_hooks.go
• internal/config/runtime_hooks.go

主要改动：

• 新增 HookPointAcceptGate。
• 支持 command hook。
• accept_gate 支持 block。
• Hook metadata 补充 workspace 变更、todo 摘要、工具摘要等上下文。

3. Run Loop 调整

涉及：

• internal/runtime/run.go
• internal/runtime/acceptance_continue.go
• internal/runtime/state.go

主要改动：

• 完成链路改为 Hook -> Accept Gate。
• 新增 acceptance continue 计数。
• Hook block 后注入 reason，继续 loop。
• 纯问答场景在无 workspace 变更时跳过 Hook。
• continue 次数耗尽后给出专门 stop reason。

4. 删除 Plan.Verify

涉及：

• internal/session/plan.go
• internal/runtime/planning.go
• internal/context/source_plan_mode.go
• 相关测试

主要改动：

• 删除 AcceptCheck 类型体系。
• 删除 PlanSpec.Verify、SummaryView.Verify。
• 删除 plan prompt / render 中的 verify section。
• 同步清理所有依赖测试。

5. 删除 RuntimeFacts 验收链路

涉及：

• internal/runtime/facts/
• internal/runtime/toolexec.go
• internal/runtime/runtime_snapshot.go
• Gateway / CLI / TUI 相关桥接层

主要改动：

• 删除 facts collector 与 facts snapshot。
• 删除 facts_updated 相关事件与桥接。
• 清理 Accept Gate 对 facts 的依赖。

6. 独立恢复 SubAgentSnapshot

涉及：

• internal/runtime/subagent_snapshot.go
• internal/runtime/runtime_snapshot.go
• internal/runtime/toolexec.go
• internal/gateway/contracts.go
• internal/cli/gateway_runtime_bridge.go
• internal/tui/services/...
• internal/tui/core/app/update.go

主要改动：

• 在 runState 内独立维护 subagent 聚合计数。
• spawn_subagent 结果回灌后更新 snapshot。
• 恢复 subagent_snapshot_updated 与 RuntimeSnapshot.SubAgents。
• 不再依赖 RuntimeFacts。

预期收益

1. 验收职责更清晰

• 系统负责系统级约束。
• 用户负责业务正确性验证。
• 不再用“发生过什么”冒充“结果正确”。

2. 真实验证能力增强

• 用户可以通过 Hook 执行真实校验逻辑：
  • go test
  • go build
  • lint
  • 项目内自定义脚本
• 验收逻辑从被动查表升级为主动验证。

3. 模型可自我修复

• 验证失败不再直接终止。
• 失败原因会回灌给模型，允许继续修改。
• 对“测试失败但模型误判完成”的场景更友好。

4. 纯问答体验更自然

• 无 workspace 变更时不触发 Hook。
• 不会因为 plan 或旧 verify 误杀分析类任务。

5. 架构更干净

• 删除 Plan.Verify 和 RuntimeFacts 后，完成链路更短、更直接。
• SubAgentSnapshot 从 facts 中解耦，职责边界更清楚。
• 观测能力和控制能力分开，不再混在同一层。

测试覆盖

本次补充和更新了以下场景：

• 纯问答跳过 Hook
• 有 workspace 变更时触发 Hook
• Hook block 后注入 reason 并继续 loop
• 空输出触发 Continue
• required todo failed 终止
• required todo 未收敛继续 loop
• continue 次数耗尽
• 旧 plan JSON 含 verify 字段时仍可正常读取
• 独立 SubAgentSnapshot 聚合、事件发射、Gateway / TUI 恢复链路

后续建议

• 删除已失去运行时意义的 before_completion_decision hook point，避免保留无效 API 面。
• 如果后续还要扩展“完成前”能力，应继续坚持：
  • 会影响 loop 的能力进入控制链路
  • 纯展示型能力不要伪装成控制点

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[fennoai]

Found 2 noteworthy issues after the code quality, performance, security, and documentation-accuracy passes.

[fennoai]

I found a few regressions in the new acceptance-hook flow that are worth fixing before merge.

[phantom5099]

@xgopilot 替我修复编译错误：--- FAIL: TestBuildGitHeadBlobSpecWindowsBackslash (0.00s)
git_blob_test.go:174: expected forward slashes, got "HEAD:internal\tools\bash\tool.go"
FAIL
coverage: 80.2% of statements提交PR到fork仓库

[fennoai]

结果

已修复 TestBuildGitHeadBlobSpecWindowsBackslash 失败。

• 调整 internal/repository/git_diff.go，在构造 HEAD:<path> 前先把 \ 统一规范成 /，避免 filepath.ToSlash 在非 Windows 平台下遗漏反斜杠路径。
• 已执行 go test ./internal/repository，结果通过。
• 已提交并推送到当前工作分支：d78c3ed7 fix(repository): normalize backslashes in git HEAD blob spec。
• 按 fork 流程补建了分叉仓库 PR：fix(repository): normalize backslashes in git HEAD blob spec phantom5099/neo-code#77

View job run

[codecov]

Codecov Report

❌ Patch coverage is 70.03484% with 86 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/runtime/user_hooks.go	2.56%	38 Missing ⚠️
internal/runtime/acceptance_continue.go	78.78%	7 Missing and 7 partials ⚠️
internal/tui/core/app/update.go	51.85%	13 Missing ⚠️
internal/runtime/subagent_snapshot.go	80.00%	4 Missing and 4 partials ⚠️
internal/runtime/run.go	79.31%	5 Missing and 1 partial ⚠️
internal/tui/core/app/view.go	0.00%	1 Missing and 2 partials ⚠️
internal/config/runtime_hooks.go	71.42%	1 Missing and 1 partial ⚠️
internal/runtime/toolexec.go	81.81%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!