dsh-wait-guard — a completion gate so an agent cannot answer before its subagents settle

[dn4hjtcr9s-del]

TL;DR — dsh-wait-guard keeps a delegating agent's turn open while any descendant subagent is still running. Host-only bundle: one agent/turn-stopping listener, no tools, no writes, no state.

The problem

Nothing in the default composition stops an agent from ending its turn before its subagents report. I went looking for a listener on agent/turn-stopping that checks for running children and found none — the only "must wait for teammates" wording ships inside the experimental Agent Teams bundle, as a prompt sentence rather than enforcement. In practice the model answers with 0 of N results and the settlement notices arrive afterwards as separate turns.

How it works

The gate hooks agent/turn-stopping — the serial event the loop awaits immediately before it re-reads the inbox and decides whether to close the turn (dsh-agent-loop) — and simply does not return while any descendant is running. Since the dispatch is awaited and its return value is discarded, the only lever available to a listener is the inbox: holding the event postpones the decision, and anything injected keeps the turn alive for one more step. Descendants are probed across the whole tree and filtered by the Agent registry's real status, so an intermediate agent that is idle between turns still holds the gate while its own children run.

Deactivation — two paths, both ending with the plugin out of the way

Path	Trigger	Behaviour
a message arrived	settlement notice · child relay · human message	stops waiting, injects nothing — that step belongs entirely to the model
the silence timer elapsed	firstWaitMs (default 60 s) of silence within one stop attempt	injects exactly one reminder, then leaves

Deactivation is always temporary: the next time the model tries to close the turn, the gate re-engages immediately. The plugin never rewrites the recorded turn/end reason — it only postpones the decision.

Install

dsh plugin --profile <your-profile> add github:dn4hjtcr9s-del/dsh-wait-guard#v0.1.0

Measured, not asserted

• 22 functional tests + 7 bundle-shape checks (npm test).
• Bundle install verified in an isolated profile (DSH_HOME=/tmp/...): the composed tree contains id: wait-guard / name: dsh-wait-guard.
• Live on a real profile: a deliberately premature answer was held 11–61 seconds until the last subagent settled, with turn/end count 0 and injected messages 0.
• Control run with the plugin unmounted: the same gesture closed the turn 2 seconds later while a child was still running, and that child's notice only arrived as a later turn.

Limits (deliberate)

The model can still emit intermediate prose — the gate governs the turn, not speech. It does not block interrupt_agent; that is the model's own judgement. A subagent that never settles means the agent waits (the timer notice gives the model a chance to interrupt it). Non-continuable one-shot subagents never send settlement notices and are invisible to it.

Repo: https://github.com/dn4hjtcr9s-del/dsh-wait-guard · MIT

中文摘要

纯 Host 插件，挂在 agent/turn-stopping 上：只要后代子代理还有 running，主 Agent 的 turn 就不允许结束。失效只有两条路径 —— 消息到达（立刻完全退场，一个字都不注入）或 时间到（注入恰好一条提醒后同样退场）；失效总是临时的，模型下次想收尾时闸门立刻重新生效。turn/end 的理由从不被篡改，只会被推迟。测试 22+7 全绿；实测「提前结论」被扣 11–61 秒、turn/end 全程为 0；对照实验（卸载插件）下同样的动作 2 秒后就收尾了。