[FEAT] %%DONE%% 门禁不校验产物完整性：预算截断的中间进展行与真定稿同形

[WooDragon]

需求描述

dispatch-contract 的 %%DONE%% 门禁（hooks/subagent-done-gate.sh）只校验标记在场，不校验产物完整性。子 agent 预算耗尽时不是静默失败，而是回传一行中间进展后正常结束并带上标记——「预算耗尽的进展行 + 标记」与「真定稿 + 标记」在机器侧同形，门禁放行。

现场记录（claude-config PR #167 开发过程，三个 dev 实例连续截断）

实例	回传原文	实际落地
第 1 个	44 passed, 0 failed (43 baseline + 1 new file). Now verifying git status cleanliness.	代码+测试确实完成
第 2 个	Now write the DoD judgment functions. Insert before audit_q0:	代码落地，测试文件与四处文档全未创建
第 3 个	Now I have enough understanding. Let me design the 13 test cases...	零产出

三个都触发了 SubagentStop 门禁并正常退出。

追问同一实例无效

对第 1、2 个实例用 SendMessage 恢复并明确要求定稿。第 1 个给出完整报告（它本来就做完了，只差报告），第 2 个恢复后再次截断——预算已耗尽，恢复不补充预算。判据：同一形态连续出现两次即应视为规模问题，停止追问。

更危险的：自报数字与磁盘不符

第 1 个实例自报 44 passed 是真的，但那个数字恰好等于改动前基线（43 + 第一批新文件），因为第二批承诺的测试文件从未创建。数字对、结论错——不实跑发现不了。

同源问题另一面：另一实例在报告里描述它用 itertools.permutations 验证了 tie-break 顺序无关性。那是过程中的一次性临场执行、未落盘，被当成交付物写进 PR 描述，被 grok 评审当作超售抓出（PR #167 Major 1/2）。

报告里「我验证了 X」≠ 仓库里存在 X 的回归测试。

建议方向（优先级递减）

方向 1：subagent-dispatch skill 补「分段落盘」派发侧约束（最廉价，建议优先）

铁律③「渐进产出」现在的表述是「分段读、尽早吐中间进展」——治的是 watchdog stall，而非产物丢失。第 3 个实例正是把全部产出堆在末尾导致零产出，它并不违反现有铁律③的字面要求。

建议在 references/dispatch-contract.md 铁律③节补一条与「吐进展」并列的落盘要求：大任务派发 prompt 应写明「按交付物清单顺序逐批落盘，每完成一批立即写入，禁止攒到最后一次写入」。两者关注点不同——吐进展防 stall 误判，逐批落盘防预算截断丢产物。

注：pr-review 的 grok-review 场景是已知反例（cc-plugins #140 记录），脚本产物只在 stdout、不落盘，需前台同步跑完。补充表述时应说明「逐批落盘」的前提是产物形态本身可分批落盘，避免与 #140 的结论冲撞。

方向 2：己方端核验纪律（属 skill 文档，同一处可一并补）

铁律④定稿纪律的前提是能拿到定稿；拿不到时验证责任回到派发端。建议明确：收到中间进展行时直接 ls/grep/实跑核验落地状态，而非追问同一实例。

方向 3：%%DONE%% 门禁加产物形态校验（需评估，可能不值得做）

设想：派发 prompt 声明产出文件清单时，SubagentStop 侧校验这些路径存在。

风险，请连同收益一起评估：

• 把门禁变复杂，且需要一套「如何在 prompt 里声明产物清单」的机器可解析约定
• 「文件存在」仍不等于「内容正确」——可能只是把假绿推后一层
• 与门禁现有的严格 fail-open 风格是否协调，需按插件既有取舍定

方向 1+2 或已足够，方向 3 可作为观察后再定。

涉及文件

• plugins/dispatch-contract/skills/subagent-dispatch/references/dispatch-contract.md（方向 1、2）
• plugins/dispatch-contract/skills/subagent-dispatch/SKILL.md（铁律速查表若需同步）
• plugins/dispatch-contract/hooks/subagent-done-gate.sh + tests/subagent-done-gate.bats（仅方向 3）

验证方法

方向 1、2 为文档变更，验证点是表述与 #140 的 grok-review 反例不冲突。方向 3 若实施，需 bats 覆盖：prompt 声明清单且文件齐全 → 放行；声明清单但缺文件 → 拦一次；未声明清单 → 沿用现判据；清单声明格式不合规 → fail-open。

相关

• claude-config [FEAT] team-ops redteam 接线 second-opinion.sh，统一到 plan-review 的引擎与模型 #169 — 本 issue 的上游记录（含完整现场）
• cc-plugins [BUG] pr-review 派发指导误用「渐进产出」导致子任务空转丢产物 #140 — pr-review 误用「渐进产出」致子任务空转丢产物，本 issue 方向 1 需与其结论对齐

[WooDragon]

调研结论：根因与 issue 描述不同，方案随之改变

扫全机 191+ 份 transcript 的 toolUseResult（status:"completed" 的 Agent 调用），实证如下。

类别	数量
派发 prompt 含 %%DONE%% 的完成调用	82
末行是裸标记（真定稿）	70
末行不是标记	12（14.6%）

issue 正文记录的三个现场实例都在这 12 例中，它们回传时并没有带标记：

'Now write the DoD judgment functions. Insert before `audit_q0`:'      totalTokens 160328
'Now I have enough understanding. Let me design the 13 test cases...'             140211
'44 passed, 0 failed (43 baseline + 1 new file). Now verifying...'                124489

所以「预算耗尽的进展行 + 标记」与「真定稿 + 标记」在机器侧同形、门禁放行——这个描述不成立。真实链条是：

1. 子 agent 预算耗尽，末行是进展行、无标记
2. SubagentStop 门禁判对了，exit 2 拦一次
3. 续跑仍无预算，第二次仍无标记
4. stop_hook_active=true → 门禁无条件放行（拦一次即止，防死循环，设计正确）
5. 截断产物进入 tool_response，派发端侧没有任何确定性信号

第 4 步是必要的（无界重试比无标记报告更糟）。缺口在第 5 步：门禁已经做出的正确裁决在子 agent 侧被丢弃，而唯一能补救的一方拿到的是一句看起来像正常结论的进展行。

因此不需要方向 3 设想的产物清单约定。 需要的是让已判对的裁决送达能行动的那一方。

方案

1. 新 hook：dispatch-truncation-notice.sh（PostToolUse on Agent/Task）

把 SubagentStop 侧完全相同的标记判据施加在 tool_response 上，裁决注入派发端上下文。

已验证的运行时契约（binary 2.1.221 zod schema + 661 份真实 transcript 双证）：

• hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:...} schema 存在；该字段落在 "next to the tool result"，归属发起该次调用的会话 = 派发端，正是需要的听众
• tool_input.prompt 在 1891/1895 次真实 Agent 调用中在场 → 判据源直接可得，不需要读 transcript（无 FIFO / 软链接 / 路径遍历 / fork 形态四类隐患）
• status:"completed" 携带 content:[{type:"text",text:...}]（661 例）；async_launched 无 content（784 例）→ fail-open
• 多 block 20 例，包装 block 恒在 index 0、从不在末尾 → 合并全部 text block 再取末个非空行，无需特例

决策链（每步 fail-open，全程 exit 0）：

1. stdin 空 / 2. 无 jq / 3. jq 解析失败            -> exit 0
4. ALLOW_TRUNCATED_DELIVERABLE=1                  -> exit 0（逃生舱）
5. tool_name ∉ {Agent, Task}                      -> exit 0
6. 派发文本不含标记（未声明）                        -> exit 0
7. tool_response.status ≠ "completed"             -> exit 0
8. text block 取不到 / 全空                        -> exit 0
9. 末个非空行 == 裸标记（定稿完整）                   -> exit 0
10. 否则                                          -> exit 0 + additionalContext

第 6 步判据源写成一个表达式不分支：(.tool_input.prompt // "") + "\n" + (.tool_response.prompt // "")，tool_input.prompt 缺失的 4/1895 例由后者兜住。

刻意用 exit 0 + additionalContext，不用 exit 2：exit 2 在 PostToolUse 是 blocking error，而工具已经跑完了——把「需要核验」框成错误是语义错位。stdout 纯净性纪律照抄 dispatch-rules-inject.sh（唯一一次 stdout 写在末尾单条语句，所有 fail-open 路径先于它 exit、stdout 全空，payload 用 jq -n 构造）。

2. 文档（原方向 1 + 2，保留）

• 铁律③：在「吐进展」之外并列补逐批落盘要求。两者关注点不同——吐进展防 stall 误判，逐批落盘防预算截断丢产物。显式标注前提「产物形态本身可分批落盘」，并点名 [BUG] pr-review 派发指导误用「渐进产出」导致子任务空转丢产物 #140 的 grok-review 为已知反例（产物只在 stdout、必须前台同步跑完）
• 铁律④：补「拿不到定稿时验证责任回到派发端」+ 同形态连续两次即视为规模问题的判据
• SKILL.md 速查表 ③④ 同步；「定稿标记」节说明机器强制现在是两半——SubagentStop 管子 agent 侧补写，PostToolUse 管派发端知情

两处自查修正（相对首版方案）

注入文案不能断言「这是中间进展」。 那 12 例按产物长度分两组：8 例在 31–154 字符（Now commit. 这类，确定是截断），4 例在 6154–14505 字符——那些看着是写完了只是漏了标记的完整报告。对后一组断言「非定稿」是错判，约三分之一的触发会把完整报告污蔑成截断。文案改口径：只断言「定稿标记缺失、完整性未经确认，行动前核验落盘」，不断言产物性质。机制不变。

砍掉 _marker-lib.sh 判据抽取。 首版想把两个 hook 的判据提成共享 lib。为 4 行判据去动一个已硬化的门禁不值得——那 26 个测试和 FIFO / HOME unset / set -u 那堆注释是真金白银换来的。改为新 hook 内复制那 4 行 + 注释指向兄弟脚本，判据同步靠一条测试断言钉住（两脚本对同一组边界输入必须给同一判定），比 source 一个 lib 更不易出事。

明确不做

• 方向 3（产物清单 + 文件存在性校验）。需要一套机器可解析的清单约定，且「文件存在 ≠ 内容正确」只是把假绿推后一层。本方案不是它的削减版——不引入任何新约定，只把已有判据的裁决送对听众
• 不改 stop_hook_active 拦一次即止语义
• 不加长度 / token 启发式判截断。实测合法定稿短至 8 字符（%%DONE%% 本身）、13 字符（112 + 标记），长度阈值必然误伤

收益边界（诚实记录）

tool_response 本来就呈给派发端，那句进展行是肉眼可见的。新 hook 不补充新信息，补的是显著性——在 tool result 旁钉一条确定性判定，让「这不是定稿」不依赖派发端当场警觉。同族先例支持这个理由：%%DONE%% 的判定同样是子 agent 能自查的文本事实，门禁存在正是因为自查不可靠；dispatch-rules-inject.sh 更直接——四铁律先写文档、后来还是加了 hook。同一逻辑在派发端成立。

状态

暂缓落地。 当前有多个修复并行，混在一起跑不利于验证本项的修复成果。方案先归档在此，待手上其他问题收口后单独开工，届时可独立观测该 hook 的触发率与误判率。

涉及文件（落地时）：hooks/dispatch-truncation-notice.sh（新）、hooks/hooks.json（新增 PostToolUse 段 + Agent/Task 双 matcher）、tests/dispatch-truncation-notice.bats（新）、skills/subagent-dispatch/references/dispatch-contract.md、skills/subagent-dispatch/SKILL.md、README.md、版本双写至 1.3.0。