[Bug] exit_plan_mode presents a plan while the background subagents it depends on are still running — plan finalization must wait for all delegations

[LuckyPro-X]

Summary

Plan 模式下，父 Agent 可以在它依赖的后台委派（subagent，默认 run_in_background: true）仍在运行时，就调用 exit_plan_mode 提交计划，于是进入评审的计划是基于不完整输入产出的。这个计划可能直接被批准；委派落定之后又必须重新提交一版（v2）。

问题不只是"缺少提示"：计划本身是全部已委派调查结果的汇总产物，只要还有委派未落定，这份计划在定义上就是不完整的，不应该进入评审。plan-mode policy 文本、exit_plan_mode 的契约与返回值、计划评审界面，都不包含任何"仍有在途委派"的信号；随包发布的 dsh-base profile 也没有面向模型的 join/wait 原语，模型没有可靠手段等到"全部回复"。

Reproduction

1. 会话处于 plan mode，standard preset（另挂了 MCP server；工具目录里没有任何等待 agent 的工具）。
2. 在同一条 assistant 消息里用 subagent 起两个只读调研子 Agent（默认后台运行），两者都是计划必须覆盖的调查。
3. list_agents 持续返回 [running]：本次 trace 中父 Agent 轮询了 8 次（step 63 / 73 / 103 / 111 / 127 / 130 / 133 / 138），step 138 的结果是两行 … [running] — <label>。
4. step 139：父 Agent 调用 exit_plan_mode 提交计划；其 reasoning 明说会在实施阶段再把"这些子 Agent 的发现并进来"。此时两个子 Agent 都还在运行，两份调查报告都还没产出。
5. 用户 dismissed 了这次评审；随后子 Agent 报告落定，父 Agent 立即提交 v2"（已并入两份调查报告）"并被批准。也就是说 v1 那次评审对用户是纯粹的干扰，而它本可以被批准。

Current behavior

• exit_plan_mode 只校验四件事：调用者 agent 存在、plan mode 处于 active、计划以 # 标题开头、存在用户提问通道。它不读取调用者的子 Agent/后台任务状态，因此在依赖的委派未落定时也会照常进入评审。
• 默认 plan-mode policy（packages/bundle/base/cordis.patch.yml 的 section）说明了如何探索、计划要写到什么程度，但完全没有提到在途委派，也没有"计划必须覆盖全部已委派调查"这条要求。
• 我使用的桌面版 0.2.0-rc.2 里，委派指引只有 Start independent subagent delegations together in one assistant message and continue useful work while they run.，没有"只剩等待时该怎么办"；而 list_agents 的说明是 "there is no need to keep checking its status"。两者叠加后，模型手上只剩"轮询"和"按现有信息先交计划"两条路——本次它两条都走了（轮询 8 次后仍然提前提交）。（master 的 7a881e944 已补上 When only waiting for their results remains, end your turn instead of sleeping or polling; the next result starts a new turn.，这条通用规则本身很好，但它仍没有把"计划定稿"与"委派是否全部落定"绑在一起。）
• 随包 profile 没有面向模型的 join：waitForChildren(parent) 是 service API（文档明确写 "Programmatic result waiting belongs to the subagent service"），wait_agent 只存在于实验性 agent-team 包，而 dsh-base 默认禁用该包。所以"等全部 subagent 回复"目前只能靠模型自觉结束本轮。

相关观察（master 已由 18a4bc409 处理）：在 0.2.0-rc.2 中，dismissed 评审是以 tool error 返回的——The user dismissed the plan review to speak instead; stay in plan mode, stop here, and wait for their message.——但这个 turn 并没有结束：4 条已排队的 inbox 条目（2 份子 Agent 报告 + 2 条 settlement 通知）在同一条 turn 里直接开启了下一个 step，于是计划在用户没有发任何消息的情况下被重新提交并获得批准。用户"收回这一轮"的意图被子 Agent 的落定消息覆盖了。

Expected behavior

计划是全部调查结果的汇总产物，因此"全部委派落定"必须是 exit_plan_mode 的硬前置条件，而不是提示项：

1. 硬性门禁（核心）：exit_plan_mode 读取调用者的 live descendants；只要仍有处于 running 的委派，调用即失败，例如 2 delegations are still running: <id> — <label>, <id> — <label>; wait for all of them to settle before presenting the plan。计划不进入评审界面，用户也就没有任何机会批准一份建立在部分输入上的计划。
2. 等待方式必须可用且明确：plan-mode policy 写明"计划必须覆盖全部已委派的调查；有在途委派时先等它们全部落定，不要调用 exit_plan_mode"，并明确"结束本轮"是 plan mode 下受支持的等待方式（落定消息开启新一轮，届时再提交完整计划）。否则模型只能在轮询与提前交计划之间二选一。
3. 仅告警/仅在评审界面列出在途委派不够：本次 trace 中父 Agent 在 list_agents 返回 [running] 之后仍然提交了计划，说明"提示"挡不住 stale plan 进入评审；把决定权交回用户也只是把"要不要用不完整输入定稿"这个系统性问题变成了人工兜底。
4. 委派全部落定后，提交的计划应当是完整聚合版本（本次即 v2 的内容），无需用户先 dismiss 一次、再等一版重新提交。

Environment

• DeepSeek Harness 桌面版 0.2.0-rc.2；@deepseek-ai/dsh-plan-mode 0.2.0-rc.2、@deepseek-ai/dsh-tool-subagent 0.2.0-rc.2。
• macOS（darwin）；plan mode 全程 active；standard preset，另挂 MCP server。
• 模型：通过自建 OpenAI 兼容 provider 接入的第三方模型。如需要，我可以提供脱敏后的 session log 片段（plan/mode、tool/call、agent/inbox/spliced 事件）。

[argszero]

Your reading holds up at source, and it is worth stating more strongly than the report does: this is not a race with a missing check — there is no check to race.

exit_plan_mode validates four things and none of them is a delegation. Its execute is packages/plan/plan-mode/src/index.ts:298, and it checks exactly: that a calling agent exists; that plan mode is logically active for that session (loggedActive); that the plan text starts with a # heading; and that a userQuestions channel is available. Then it asks. Nothing reads child agents, the delegation catalog, or the inbox. The tool definition (:277) declares one parameter, plan, and an output schema with a single approved boolean. So the plan is presented while delegations are in flight because the code that presents it never asks the question — the v1 review your trace shows is the tool working as written.

The shipped guidance is where the gap actually lives, and the model is obeying it. The plan:policy section in the dsh-base profile (packages/bundle/base/cordis.patch.yml:335-347) tells the model "Make the plan decision-complete…" and then "When ready, call exit_plan_mode with the complete plan markdown… Make exit_plan_mode the only and final tool call in that assistant response." It enumerates what a complete plan must contain — goal and success criteria, changes grouped by subsystem, public API and data-flow changes, edge cases, failure modes, tests, acceptance criteria, assumptions — and it never mentions delegations, running or otherwise. Your step 138 → 139 sequence is the policy executed literally: the last tool call before the submission was list_agents, and the policy's own instruction is that the submission be the only call in its response. A model cannot infer a precondition the text does not state, which is why I read your finding as a gap in the guidance as much as in the tool.

What the waiting surface really is, enumerated. The subagent tool's description says it "starts an independently managed subagent and immediately returns its id. The runtime notifies you when it finishes." That notice — injected when the child's turn ends — is the intended join primitive; there is no blocking one. The whole model-facing surface for delegations is three tools registered by tool-subagent-control: list_agents, send_message, interrupt_agent. Your trace's eight polls are the model constructing a wait loop out of the only primitive it has, and it is doing that correctly.

There is a blocking wait in the tree, but it cannot reach a delegation: job_output takes wait: true and blocks until the job settles or the timeout expires (packages/jobs/tool-jobs/src/index.ts:312). Jobs and delegations are separate surfaces — nothing under packages/subagent/ references ctx.jobs at all — so job_output cannot join a child agent, and job_list will not show one. That is the precise form of the statement in your report: not "the profile lacks a wait tool", but "the only blocking wait in the product belongs to a surface delegations are not registered on."

Two details that sharpen the fix. First, a gate built on list_agents would be blind to half the delegations: the model-facing projection in list-agents.ts returns nothing for a child whose mode !== 'continuable' — one-shot children are traversed for descendants but never listed. Your trace shows [running] rows, so your two investigations were continuable; a one-shot delegation is not merely un-waited, it is unlisted. Second, "running" is not a delegation-in-flight marker: it is the child agent's own turn status, derived as ctx.agents.get(id)?.status === 'running'. Any predicate you or a plugin writes on top of this should say that it means the child's turn is in flight, which is what you want here but is not the same proposition as "its report has not been delivered yet".

The signal you say is missing has a seam, and it is plugin-mountable. tools/pre-execute is a waterfall per call — (this: Scoped<ToolRuntime>, exec: ToolExecution, next: () => Promise<PreToolDecision>) — and its parameter is documented as "the pending call (name, parsed arguments, caller agent)", while the decision is one of allow / deny / cancel / ask. A plugin can therefore refuse by name: deny exit_plan_mode while the calling agent has a child whose turn is running, with a reason naming which delegations it is waiting on. That converts your "no signal at all" into a message the model reads at exactly the moment it needs it, and it does not require the tool to change. The seam is already used this way in-tree — the auto-review preset decides per call from exec.agent and exec.name and can answer denied(exec, reason) or { kind: 'cancel' } (packages/experimental/auto-review/src/index.ts:684), and packages/deliverables/workspace-changes/src/index.ts:174 uses the same seam to observe rather than to refuse.

Two honest limits of that shape, since they decide whether it is worth building: a plugin can refuse and explain, but it cannot make the model wait or coalesce the notices — the release has to come from state (the children settling), never from a timer, or the guard turns a stale plan into a stuck one. And the state it reads (ctx.subagents.listChildren(), ctx.agents) makes the deny accurate for continuable children while inheriting the blindness above for one-shot ones — so the honest version of the guard denies only on the children it can prove are running, and says so in its own message.

If it is useful, I can build that as a small plugin (@argszero/dsh-plan-delegation-guard): a tools/pre-execute listener scoped to the calling agent that refuses exit_plan_mode while a child turn is in flight, released by the child's own settlement events rather than by a countdown. It would not replace the change this report argues for — a plan gate belongs in the plan tool or its policy text — but it is a shippable way to stop the v1 review today, for anyone on a released build.

[LuckyPro-X]

谢谢这份源码级复核，结论我们接受。你指出的两处锐化我们也同意，并已确认其准确性：

• list-agents.ts 里 if (entry.mode !== 'continuable') return undefined —— one-shot subagent 对 list_agents 确实不可见，所以任何建立在其之上的门禁都只覆盖一半委派；
• running 是 subagent 自身的 turn 状态（ctx.agents.get(id)?.status === 'running'），并不等于"报告尚未送达"，写守卫时需要说清这个命题。

先补三条事实，都是我们在刚发布的 0.2.1-rc.2（tag dsh-v0.2.1-rc.2，2026-10-17 切出）上逐项核对过的：

1. exit_plan_mode 仍然只校验 agent / loggedActive / # 标题 / userQuestions 四项（dsh-plan-mode/lib/index.js:254-257），没有任何委派读取；
2. plan:policy 仍然完全不提委派（packages/bundle/base/cordis.patch.yml:335-350），与 0.2.0-rc.2 相同；
3. 这一点对你的方案很关键：7a881e944（10-12）确实加入过 "When only waiting for their results remains, end your turn instead of sleeping or polling; the next result starts a new turn."，但 d6adc5d9b（"fix(prompts): restore compatible PTC guidance and SDK persona"，10-16）把它删了回去，而 packages/subagent/tool-subagent/README.md 仍在描述这句话。因此 0.2.1-rc.2 的委派指引只剩 "…continue useful work while they run."。

也就是说：结算通知在协议层确实是设计中的 join 原语，但当前发布版没有任何提示让模型停止轮询、结束本轮。

为什么我们坚持"硬门禁"而不是"提示"或"在评审界面展示"：这份计划不是独立文档，它是全部已委派调查结果的聚合产物。只要有委派未落定，计划在定义上就不完整，而 plan mode 的价值恰恰在于"被评审的是一份已被调查结果支撑过的计划"。本次 trace 里 list_agents 已经明确返回 [running]，父 Agent 仍然提交了计划 —— 这说明提示挡不住 stale plan 进入评审；把在途委派画到评审界面上也不够，那只是把"要不要用不完整输入定稿"降级成人工兜底。要的语义是：未落定 → 不能定稿。

关于插件：我们接受，也很期待 @argszero/dsh-plan-delegation-guard。实现上我们这边有几点想法，供你参考，最终以你的判断为准：

1. deny 的 reason 里如果能直接带上"结束本轮、等 settlement 通知到达后再提交计划"，就不必依赖 prompt 文本 —— 当前发布版已经没有这句；
2. 只对能被证明为 running 的 subagent 触发 deny，并在消息里说明 one-shot 委派不在这个守卫的可见范围内，这样读者不会误判覆盖面；
3. 释放如果能挂在 subagent 的 settlement 事件上，就比任何计时器都稳妥。

最后，想再强调一下我们理解的问题重点，供你和维护者参考（也正是我们报告里那条 Expected behavior 的来源）：

• 这个问题的要害不是"少了一个检查"，而是 subagent 的调研结论没有被完整吸纳进计划 —— 计划在委派落定前就进入了评审，plan mode 的效果因此大幅缩水；本次即 v1 被 dismiss、v2 才并入两份报告。
• 因此 harness 层面可强制的只有"顺序"：全部委派落定之前不得定稿；"计划是否真的理解了结论"属于模型行为，任何门禁都无法替代。
• 插件的价值在于挡住"提前批准"这个可观测症状（continuable 委派的情形下）；one-shot 委派与计划内容质量仍在守卫之外，所以核心修复仍需要一个 plan gate —— 落在 plan 工具或其 policy 文本里，并把"计划必须覆盖全部已委派调查"写进 plan:policy。