终答前检查 todos 未完成项并注回提醒

[Tony-ooo]

多步任务中模型常在 todos 还有 pending/in_progress 时以纯文本收尾交棒，用户只能手动“继续”；期望终答前自动检查并提醒继续。

验收与细节

• 验收条件：turn 即将以 completed 关闭前（agent/turn-stopping 边界），若本会话 todos 投影还有 pending/in_progress，harness 注回一条提醒并让同 turn 多跑一步；以下情况行为不变、直接关闭：无残留（全 completed）、从未建清单（null）、组合未挂载 tool-todo（key 缺席）。
• 用户或模型可见变化：模型在活没干完时不再“误报完工”式收尾；提醒每 agent 每 turn 最多一次，第二次到达关闭边界即放行，避免刷屏和卡死。
• “用户明确说结束/遇阻交棒时不拦截”只能近似实现：提醒文案给出明确逃生通道（继续干活 / 把 todos 置为 completed / 说出不再继续的原因），模型坚持结束时 guard 不再阻拦（原因见备选 A 的第 2 点）。
• 测试证据：构造 pending 残留的终答场景，断言请求数 1→2 且第二次请求包含提醒；全 completed / null / 未挂载 tool-todo 三个对照组断言请求数仍为 1 且无注入；同 turn 第二次到达关闭边界不断言再提醒。

实现建议（已按当前源码核验修正）

• 备选 A（推荐）：新 guard 包（如 todo-unfinished-reminder），监听 agent/turn-stopping（serial，无 next，payload 只有 {agent, turn, signal}），读 ctx.sessionProjections.stateOf(agent.session, 'todos')（tool-todo/src/index.ts:apply 已注册该 key；key 缺席时 stateOf 返回 undefined，按无残留放行）。有残留且本 turn 未提醒过，则 agent.steer(...) 注回提醒，每 agent 每 turn 最多一次。零侵入 agent-loop、可随组合开关，符合“Plugins, not loop changes”。只进 base 组合，不进 sdk-minimal（后者无 tool-todo）。
• 与 repeat-tool-reminder 形态的两处差异（不可照搬）：
  1. 没有 prependContext：turn-stopping 是 serial void，没有可改写的 decision 对象；正确做法是 agent.steer(reminder)（hooks-claude-code 的 Stop 桥与 loop.spec 的 /loop 模式已有先例；经 inbox splice → user/message 落盘，满足“Model-visible ⟺ logged”，无需新 session 事件）。
  2. 照抄不了 source.kind:'user' 复位：turn-stopping payload 无 messages 可扫；防刷屏改为按 turn 去重（WeakMap<Agent, lastRemindedTurn>），同 turn 只提醒一次。
• 备选 B：改 packages/core/agent-loop/src/agent.ts 的终答判定内联检查——侵入核心，需同步改 docs/architecture.md，重，不推荐。

落地时别漏的边界

• todos 是 standing-plan 语义（turn/start 清零）：guard 只覆盖“同 turn 虎头蛇尾”；跨新 turn 后投影自然为 null，按现有语义不算残留。
• 带 concludesTurn 的工具结果同样经过 turn-stopping：guard 会提醒一次；想提前结束的工具调用前先把 todos 收尾，guard README 需写明。
• 消息来源必须标注 {kind:'plugin', plugin:'todo-unfinished-reminder', form:'notice', summary} 且 summary 不超过 120 字符（CONTEXT_SUMMARY_MAX_CHARS），否则在派生历史里渲染异常。
• 无需 Config（“有残留即提醒”是固定规则，无证据不加可调量）；inject = ['sessionProjections'] 硬依赖注册表，对 todos key 软处理（缺席即放行，覆盖 HMR 卸载场景）。
• 提醒是建议性（advisory），不是 veto：最坏代价是同 turn 多一次模型请求；文案必须同时给三条出路，否则会诱发模型空转刷状态。

[argszero]

Solid proposal, and I agree with the direction of 备选 A (a new guard package, no core-loop change). When I traced the actual loop-control point, though, I found a concrete blocker that affects both options and is worth pinning down before writing the guard.

The terminal point is not a pluggable "before finish" hook — it's a loop-local decision that can't be un-ended from outside.

In packages/core/agent-loop/src/agent.ts (the step method, ~line 305-309):

if (turnEnds && this.inbox.nextStep.length === 0) {
  await this.dispatch.serial('agent/turn-stopping', { turn, signal })
  signal.throwIfAborted()
}
if (turnEnds && this.inbox.nextStep.length === 0) break

The "终答判定" is the combination of turnEnds (a loop-local variable, set to { kind: 'completed' } at line 284 when toolCalls.length === 0) plus inbox.nextStep.length === 0. agent/turn-stopping is dispatched after turn/start/step/end are already appended and the assistant message is already in the log. It is a serial fire-and-forget event:

• The loop reads turnEnds (loop-local) to decide break — a guard cannot reach that variable through a serial event.
• The loop does not re-check inbox.nextStep after the turn-stopping dispatch. So if a guard were to splice a new next-step message during turn-stopping, the loop still breaks — the splice is ignored.

So "让循环多跑一步" cannot be achieved purely from a guard at turn-stopping. The reminder-and-continue semantics require either (a) telling the loop to not end, which means reaching turnEnds (core change — your 备选 B), or (b) splicing into next-step before the break check and before turnEnds is forced — which is what executeToolCalls itself does at line 434 (inbox.splice('next-step', ..., context => ...)) but only because it holds the concluded flag.

The clean middleware-shaped place is actually the same one executeToolCalls uses: the tool-call-return path. When toolCalls.length === 0 (the finished-pure-text case at line 431), the loop returns { kind: 'completed' } directly — that's the moment the todos should be consulted. A guard hooking tools/post-execute (like repeat-tool-reminder does) rides the tool path, but the pure-text terminal case has no tool execution, so that hook also misses it.

My read on what's actually needed:

• If you want the pure text final answer (no tool call) case covered — which is precisely the "误报完工" the report describes — there is no non-invasive hook today: the only signal that a turn is ending with no tool call is the loop-local turnEnds/break, which is not exposed. That leans toward 备选 B, or exposing a small "turn may end" callback from the loop.
• If you scope to the tool-call-driven case (last tool call's result arrives, model could still act), tools/post-execute + reading the todos projection is workable and matches repeat-tool-reminder — but it doesn't cover the no-tool final answer.

Worth checking before committing: does the todos projection get refreshed at the point you'd read it in post-execute? It's folded from todo/write events (tool-todo/src/index.ts:139), so it's current as of the last todo/write. And the all-prompts/terminal "no tool call" case — the model's closing text — is the one users actually hit when todos are left pending, which is the hard one.

I'd be happy to help prototype the guard for the tool-driven path (non-invasive, repeat-tool-reminder shape) and separately capture the loop-level "turn may end with no tool call" gap for the core. The two are different surfaces.