Subagent failure notices don't include the error reason — parent sees "Its closing message:" followed by nothing

[sijie-ni-0214]

Summary

When a background subagent fails mid-turn (e.g. a model API 429 rate-limit), the settlement notice injected into the parent conversation reads:

Background subagent <childId> failed before it finished.
Its closing message:

and then nothing. The actual failure reason never reaches the parent agent, so the failure looks "truncated" and cannot be self-diagnosed without manually digging through ~/.dsh/sessions/.../session.jsonl.zstd.

Version: @deepseek-ai/dsh-subagent@0.1.1-rc.2 (dsh CLI 0.1.1-rc.2).

Root cause (traced in code)

In packages/subagent/subagent/lib/index.js:

1. settlementSummary(childId, stopReason) maps stopReason to a fixed one-liner ("error" → "failed before it finished."). No error detail is forwarded.
2. notifySettlement() builds the notice as [summary text] + ["Its closing message:"] + terminal.output, where terminal.output is the last partial assistant output of the child. For a child that died mid-turn, that output is only reasoning + tool-call blocks (e.g. an in-flight bash/read call) — no final text message.
3. The tool-call blocks are dropped when the notice is rendered into the parent conversation (the parent cannot execute tool calls of a dead child), and reasoning blocks are hidden — so the visible notice ends right after "Its closing message:".
4. The real error — e.g. 429 RATE_LIMIT: Rate limit exceeded for api_key ... — is recorded in the child session turn/end record (reason.kind: "error", with the full API message), but notifySettlement() never reads it.

Related gap: observeRun() rejection path emits subagent/end with only { stopReason: "error" }, dropping lastAssistantMessage as well — so a plugin listening to the public subagent/end event also cannot see the details without reading the child session record itself.

Suggested improvement

1. In notifySettlement(), append a one-line error summary to the notice when the terminal carries error details (e.g. Failed with RATE_LIMIT: 429: <message>), so the parent agent can see why the child died.
2. Carry the error details (or at least keep lastAssistantMessage) in the subagent/end event payload rejection path, so community plugins can build diagnostics on top of it.

Impact

• Parent agents cannot self-diagnose child failures; the notice looks truncated.
• Observability tooling has no structured way to see why subagents fail without parsing session files.

The fix itself is small (a few lines in notifySettlement() / settlementSummary()); happy to submit a PR whenever the project accepts external contributions.

[argszero]

Verified all of this against rc.2 (HEAD b150a55). The trace is exact, and there is one thing you did not say that makes the fix even smaller: the error detail is already in scope at both call sites — it is discarded, not unavailable.

1. Every claim checks out

• settlementSummary maps error to the fixed one-liner "failed before it finished." at packages/subagent/subagent/src/continuation.ts:297-318 (the error arm is :310-311).
• notifySettlement builds the notice as summary + "Its closing message:" + terminal.output at continuation.ts:1467-1473.
• finalAssistantOutput selects the last non-empty assistant message (assistant-output.ts:32-39): a child that died mid-turn produced an assistant message whose content is reasoning + tool-call blocks with no text, so the notice really does end visually after "Its closing message:" once the parent renderer drops those blocks.
• The one-shot rejection path emits subagent/end with only stopReason: "error" — lifecycle.ts:156-158, and it ignores the rejection value entirely.

2. The missing layer: the error is in scope where it is dropped

Two sites, both of which have the failure in hand:

• Teardown/failure path: continuation.ts:1434 calls activation.observer.terminal(failure) with the SubagentError right there, and terminal() throws it away — lifecycle.ts:191-193 returns { stopReason: 'error' } with no message on failure. The 429 detail never survives the boundary.
• One-shot rejection path: lifecycle.ts:156-158 attaches a rejection handler () => { ... } that takes no argument. The handler signature is where the reason is lost; (reason) => { ... } would have errorChain(reason) in scope for free.

So the fix is not "go read the child session file" — it is "stop dropping the value you are already holding." That is the strongest argument for why this should be fixed in notifySettlement rather than in the child session record.

3. Concrete shape

• lifecycle.ts terminal(): carry the chain — on failure return { stopReason: 'error', error: errorChain(failure) } (errorChain is already imported at continuation.ts:33 and used throughout the file).
• notifySettlement (or settlementSummary): when the terminal carries error, append a single model-facing line after the summary, e.g. "It failed with: RATE_LIMIT: 429 Rate limit exceeded ..." — one line keeps the parent's attention budget; the full chain can go in a second line if present.
• lifecycle.ts:156-158 rejection handler: capture the reason and emit { ...identity, stopReason: 'error', error: errorChain(reason) } so the public subagent/end event gains the same detail for plugin consumers.
• Test gap: the existing settlement tests should pin that an error terminal produces a notice containing the failure text (and that subagent/end carries error on the rejection path). A regression in that shape would have caught this immediately.

4. One design note

The notice is intentionally model-facing and brief (the doc comment at continuation.ts:290-296 frames it as "one line ... in the parent's own task vocabulary"), so keeping the error to one summary line with an optional detail line respects that contract — the parent should get the cause without the notice turning into a log dump. stopReason stays the discriminator; the error text is context for it, not a new state.

This is a genuinely small, high-value fix — worth doing even before the issues/PRs channel reopens, since it is exactly the kind of observability gap that makes parent agents misdiagnose child failures as truncation.