[Bug] Terminated sub-agent output is unrecoverable: no closing message, no registry entry, no read-back path

[CodingRookie98]

Summary

When a sub-agent dispatched through the subagent tool terminates instead of settling normally, the parent agent receives a settlement notice that carries no closing message, the finished child disappears from list_agents, and send_message to it fails. There is no tool in the parent's toolset that can read the child's output afterwards.

For any workflow whose entire value is the child's report, one early termination therefore destroys the deliverable silently — and the parent cannot even tell what was lost, or whether anything was produced at all.

Environment

dsh	0.2.0-rc.2 (local build; worktree at commit a360dd5da7, tag dsh-v0.2.0-rc.2 merged on branch local-build-and-deploy)
Node	v24.21.0
OS	Ubuntu 24.04 on WSL2 (kernel 6.18.40.1-microsoft-standard-WSL2)
Dispatch form	subagent({ run_in_background: true }) → returns { kind: "continuable", subagentId }
Session	Agent Teams session; no spawn_teammate teammates were created (relevant to E2 below)

What happened (parent-side observation)

Six sub-agent dispatches in one session. Two terminated before settling and their output was unrecoverable:

#	Dispatch	Outcome
1	subagent (review round 1)	terminated, no closing message → output lost
2	subagent (review round 2)	terminated, no closing message → output lost
3–6	subagent with a "write your report to a file first" instruction in the prompt	all settled normally; output delivered and durable on disk

The user could see the two lost reports in the UI, which is how we know content existed. The parent agent had no way to read them. (Dispatches 3–6 are also the workaround — see the end.)

Evidence

E1 — settlement notice without a closing message

Terminated child:

Background subagent <id> finished and will do no further work unless you send it more.

Normally settled child, same session, same tool:

Background subagent <id> finished and will do no further work unless you send it more.
Its closing message: <full report text>

The absence of the Its closing message: block is the only signal — the notice does not say why there is none.

E2 — a finished child is not addressable

list_agents()                          → [ { target: "lead", status: "running" } ]
list_agents({ scope: "children" })     → same
list_agents({ scope: "descendants" })  → same

send_message("a580a858")                                  → ToolCallError: active teammate "a580a858" not found
send_message("4edea57e-aef3-48d4-a0d6-16a5522f70a3")      → same   (full UUID, not a truncation artifact)

packages/subagent/tool-subagent-control/src/list-agents.ts accepts a scope: 'children' | 'descendants' request, but neither scope surfaces a child that has already finished. The error text says "teammate", and in this session no teammates existed — so the lookup appears to be against the live agent registry, from which a settled child is gone.

E3 — no read-back in the tool surface

The parent's sub-agent controls are subagent, subagent_fork, send_message, list_agents, interrupt_agent, list_subagent_models. None reads a child's transcript or output. job_output is documented for background jobs (shell), not sub-agents.

Contradiction with the documented design

The source reads as though termination should preserve output:

• packages/subagent/subagent/src/assistant-output.ts — "select the last non-empty assistant message … Selection is independent of the run's stop reason."
• packages/subagent/subagent/src/lifecycle.ts:35 — readonly output?: readonly ContentBlock[]; "The epoch's final assistant content, absent when it produced none or failed."
• packages/subagent/subagent/src/continuation-messages.ts:139-148 — the settlement notice builds summary from settlementSummary(childId, terminal.stopReason) and closingText from terminal.output.
• Termination paths do collect output: out-of-process.ts:196,200 → { output: parts.collectOutput(), stopReason: 'aborted' }; subagent-dsh-sdk/src/run.ts:326 → the same for turn === 'cancelled'.
• packages/subagent/tool-subagent/src/index.ts:386 — "returns a subagent id you can continue with send_message".

So exactly one of two things is true, and the parent cannot distinguish them:

1. By design: the child had produced no non-empty assistant message at termination time (lifecycle.ts:35's "produced none or failed"). Then the missing notice payload is expected — but the notice should still say so, and there should still be a way to inspect what happened.
2. A bug: the child had produced output, and it was not carried into the notice (e.g. not folded, or dropped on a particular teardown path).

The ambiguity is itself the defect: with no reason string and no read-back, a losing dispatch is indistinguishable from a child that never got started. It also means case 2 cannot be ruled out from the parent side.

Why it matters

• The child's output is usually the whole point of the dispatch; losing it silently is worse than a hard error, because the parent keeps going and may report success.
• Fail-silent: the parent cannot decide whether to re-dispatch, since it cannot tell "nothing was produced" from "something was produced and dropped".
• Asymmetry with background shell jobs — those have job_output and stay readable after settling. Sub-agents do not. The same harness gives you a read-back path for a shell command but not for a delegated agent.
• The documented send_message continuation implies an addressable history around a child; for finished children there is none.

Suggested directions

1. Say what happened in the notice. Distinguish normal settlement / abort / failure, and state whether output was captured. If output existed and was dropped, say so — this alone converts a silent loss into an actionable one.
2. Keep a readable transcript for finished children — at minimum the folded assistant output (AssistantOutputFold), bounded if necessary.
3. Expose a read-back path: e.g. a subagent_output(id) tool, or make list_agents(scope: 'descendants') include finished children with an output reference — mirroring what job_output already does for shell jobs.
4. Tighten the doc contract: "returns a subagent id you can continue with send_message" reads as indefinite; if continuation only works while the child is live, it would help to say so explicitly.

Workaround for anyone hitting this

Put "write your final report to <path> as your first action, then return a short closing message" in every dispatch prompt.

After adopting this, all four subsequent dispatches preserved their output regardless of how they ended, and the reports were on disk before the process settled — so the parent could recover them even from a failed notice. It costs one line of prompt and removes the single point of failure.

(The general lesson: treat a child's closing message as a best-effort channel and give the deliverable a durable address. But a harness should not require every user to discover that independently.)

[CodingRookie98]

Follow-up & Connection to #9056

I noticed #9056 was posted a day earlier with a very similar root-cause symptom. Connecting the two highlights a broader architectural gap in the subagent lifecycle:

1. Shared Root Cause (active teammate not found):

   • In [BUG] subagent 派出的子代理不可寻址：send_message / interrupt_agent 均报 active teammate not found，父 Agent 无法终止它 #9056, a running subagent's ID cannot be found by send_message or interrupt_agent.
   • In our case (Evidence E2), a terminated/settled subagent's ID also cannot be found by send_message.
   • Both confirm that subagent IDs are never wired into the teammate registry that send_message / interrupt_agent query against, directly contradicting the tool description: "returns a subagent id you can continue with send_message".

2. The Full Spectrum of the Issue:

   • In-flight ([BUG] subagent 派出的子代理不可寻址：send_message / interrupt_agent 均报 active teammate not found，父 Agent 无法终止它 #9056): The parent has no control channel to steer or interrupt running subagents.
   • Post-mortem ([Bug] Terminated sub-agent output is unrecoverable: no closing message, no registry entry, no read-back path #9124): The parent silently loses deliverables if the child aborts/terminates early, with zero read-back recourse (asymmetry with shell background job_output).

3. Current Mitigation Experience:
   As noted in the description, instructing the child to persist the report to disk as its first action completely worked around the data loss in our subsequent runs. However, native harness support (transparent stop reason in the settlement notice + post-mortem output recovery) remains crucial for reliable multi-agent workflows.

[slyyr]

I'd treat this as a task-lifecycle and output-durability problem, rather than relying entirely on the subagent's final message.

A useful design would separate the task's execution state from its produced output:

• Persist output incrementally: Give each subagent a durable result or transcript location, so a parent can recover useful work even if the child terminates unexpectedly.
• Record terminal state explicitly: Distinguish successful completion, cancellation, timeout, and failure. Also distinguish "no output was produced" from "output was produced but couldn't be delivered."
• Expose completed tasks: Keep a bounded record of finished subagents, including their IDs, terminal states, and output references, instead of removing all traces from the registry.
• Provide a read-back operation: A parent should be able to retrieve a completed subagent's final output by ID, even if sending additional messages is no longer possible.

As a practical workaround, asking each subagent to write its report to a file early is sensible. However, that should be a fallback rather than a requirement for every agent prompt.

I'd add tests for termination before any output, termination after partial output, cancellation after a complete report, and normal completion. Those cases should produce distinguishable results so the parent can decide whether to retry or recover the existing output.

The general principle is that task completion and result delivery are separate concerns. Making the result durable removes a fragile dependency on one final message.

Hope this helps! If this answers the issue, would you consider marking it as the accepted answer?

[CodingRookie98]

Thanks @slyyr for the insightful design breakdown! The distinction between task execution lifecycle and result delivery/durability gets right to the heart of the architectural challenge here.

A quick update on the latest release:
I checked the upstream codebase in dsh-v0.2.1-alpha.2 (released yesterday). Interestingly, the core bug reported in Evidence E1 was actually addressed under the chore "Unify subagent execution and completion notifications" (commit f52167746c):

• Previously, SubagentManager had an includeClosingText policy that suppressed the closing message in the settlement notice whenever the child agent had send_message in its toolset (assuming it would report back via tool calls instead).
• Commit f52167746c removed includeClosingText entirely and now unconditionally passes captured final text as Its closing message: (and explicitly outputs It left no closing message. if empty).
• This effectively resolves the silent output loss in settlement notices for the latest alpha release.

That said, the deeper points you and #9056 raised remain very relevant for the overall subagent architecture:

1. Tool Addressing & Steering ([BUG] subagent 派出的子代理不可寻址：send_message / interrupt_agent 均报 active teammate not found，父 Agent 无法终止它 #9056 / E2): send_message / interrupt_agent still target the teammate roster directly, so attempting to steer or interrupt a standalone subagent by ID continues to fail with active teammate not found.
2. Post-Mortem Read-Back (E3): There is still no standalone subagent_output(id) tool to retrieve or inspect settled outputs independently of the settlement notification (asymmetrical with background shell job_output).

Because the broader addressing and durable read-back capabilities are still open architectural questions for the harness, I'll keep this discussion open rather than marking an accepted answer, so the maintainers have a consolidated place to track these subagent lifecycle gaps. Thanks again for the valuable perspective!