Bug: in-process subagent failures drop the child's error diagnostic — delegating tool shows only "subagent run failed"

[LiveNathan]

Summary

When an in-process (spawn/fork) subagent child fails at the model-call level, the delegating tool result is only:

Error: subagent run failed

No diagnostic, no child session pointer. The actual failure (HTTP 429 billing cap, 400 invalid request, auth error, …) exists only in the child's own session log (~/.dsh/sessions/<workdir>/<childSessionId>/session.jsonl.zstd, the turn/end event's reason.error.message). This turns a 30-second diagnosis into a multi-day mystery: in our case a reviewer-seat subagent pinned to google/gemini-3.8-flash failed for days, looking like a harness spawn bug, when the real errors were 400: Thinking level MINIMAL is not supported for this model and later 429: project exceeded its monthly spending cap (see https://github.com/LiveNathan/showbook/issues/582).

Root cause (v0.1.2-rc.1)

@deepseek-ai/dsh-subagent-in-process-driver — readResult():

const recorded = toStopReason(lastEnd?.data.reason);   // "error" — error payload dropped here
return { output, stopReason };

toStopReason() flattens the turn/end reason { kind: "error", error: { message: … } } to the string "error" and discards the payload. The seam's result object already supports an optional diagnostic field (settleRunResult() in @deepseek-ai/dsh-subagent even has a collectDiagnostic sink — but only the out-of-process path feeds it), so the in-process driver is the gap:

• Out-of-process providers: attempt rejection → onError/collectDiagnostic → result.diagnostic → surfaced by the tool's withDiagnosticAndPartialText.
• In-process providers (spawn/fork): turn ends with reason.kind === "error" → readResult returns {output, stopReason} only → stopReasonError() renders "subagent run failed" with diagnostic === undefined.

Suggested fix

In readResult(), when the last consumed-work end carries reason.kind === "error", copy the error message (already available on the event) into the returned result as diagnostic. The tool layer already renders it (Diagnostic: …). One small change; out-of-process behavior is untouched.

Environment

• dsh 0.1.2-rc.1, web daemon, macOS
• Provider: llm-pi-ai route google/gemini-3.8-flash, in-process spawn subagents

[argszero]

@LiveNathan 你的诊断我在 d347e70390（v0.1.3-alpha.1, 当前 master）上逐项核实了, 完全成立。补充精确锚点 + 一个「Tool 层已就绪」的确认, 让这个修复变得非常小、可验证。

源级确认

TurnEndReasonMap.error = { kind: 'error'; error: LlmFailure }（packages/core/session/src/types.ts:203）。turn/end 的 data.reason 里确实带着 error.message。

但两条路径把它丢掉：

• packages/subagent/subagent-in-process-driver/src/index.ts:50 toStopReason(): case 'error': … return 'error' —— 只保留字符串, 丢弃 error payload。
• :211 readResult(): const recorded = toStopReason(lastEnd?.data.reason) → :235 return { output, stopReason } —— 从不填充 diagnostic。该文件全文无 diagnostic 引用。

Tool 层已就绪（关键——修复只要一份数据）

packages/subagent/tool-subagent/src/index.ts:183 withDiagnosticAndPartialText() 已经会渲染 result.diagnostic:

const diagnostic = result.diagnostic === undefined ? '' : `\nDiagnostic: ${result.diagnostic}`

SubagentResult.diagnostic（packages/subagent/subagent/src/types.ts:250）是可选的 string。所以 in-process 驱动只要把 turn/end 的 error.message 塞进 result.diagnostic, Tool 层会自动 \nDiagnostic: … 展示——不需要改 Tool。

参考 diff（仅 in-process 驱动, 一个函数 + 断言）

改动 readResult()（subagent-in-process-driver/src/index.ts:225），从 lastEnd?.data.reason 的 error payload 提取 message 作为 diagnostic（限定为非 completed 才带, 且建议经 limitSubagentDiagnostic 截断——4096 字节上限, 与 out-of-process 行为一致）：

@@ packages/subagent/subagent-in-process-driver/src/index.ts @@
   const lastEnd = foldConsumedWork(own).end
   const output: ContentBlock[] = finalAssistantOutput(own) ?? []
   const recorded = toStopReason(lastEnd?.data.reason)
+  // A failed turn carries the structured LlmFailure on the end reason.
+  // toStopReason() flattens it to the string "error"; surface the payload
+  // (e.g. a 429/400/401) as the seam's diagnostic so the delegating tool
+  // renders "Diagnostic: …" instead of a bare "subagent run failed".
+  const diagnostic = capturedDiagnostic(lastEnd)
   const stopReason: SubagentStopReason = cancelled && recorded !== 'completed' ? 'aborted' : recorded
   if (structured !== undefined) {
     if (structured.captured !== undefined) {
-      return { output, structured: structured.captured.value, stopReason }
+      return { output, structured: structured.captured.value, stopReason, ...(diagnostic === undefined ? {} : { diagnostic }) }
     }
     if (stopReason === 'completed') return { output, stopReason: cancelled ? 'aborted' : 'error' }
   }
-  return { output, stopReason }
+  return { output, stopReason, ...(diagnostic === undefined ? {} : { diagnostic }) }
 }

+function capturedDiagnostic(reason: TurnEndReason | undefined): string | undefined {
+  if (reason?.kind !== 'error') return undefined
+  const message = reason.error?.message
+  return message === undefined || message.length === 0 ? undefined : limitSubagentDiagnostic(message)
+}

limitSubagentDiagnostic 目前是 out-of-process.ts 的内部函数（:31, 未导出）。in-process 驱动要复用的话, 建议把它 export（但成对导出会影响 out-of-process.ts 的模块边界语义, 或者把 4096 上限提为共享常量）。更小的改动: in-process 驱动直接 message.slice(0, 4096) 即可（错误消息长度有限, 少一个函数导出更稳）。你选其一, 不影响正确性。

注入式断言（可加在 subagent-in-process-driver 既有 spec）

packages/subagent/subagent-in-process-driver/tests/ 已有 spec。仿既有「child fails at model-call」用例, 断言返回结果带 diagnostic === '400: Thinking level MINIMAL is not supported for this model'（你的 #582 真实 payload）。这正好把「读 turn/end 的 error → 冒泡到 result.diagnostic」钉死。

与 out-of-process 的一致性

out-of-process 驱动（acp/claude-code/codex）已通过 collectDiagnostic → result.diagnostic 喂给同一渲染 sink。in-process（spawn/fork）是唯一的空档, 你的定位精准。补上后三路行为一致, 都是「错误 headline + Diagnostic: … + 保留 partial output」。

一个点提醒 maintainer: readResult 里 structured 分支的 stopReason === 'completed' 回退（:233）不带 diagnostic——若 completed 但被 cancel, 现在 structured 分支也不抛 error, 无需改。真正要改的只有 error 分支。

插件可观测性关联（顺带）

这个「child 失败的 error 只留在子会话 log, 父只见 subagent run failed」的可观测性缺口, 与我的 @argszero/cordis-plugin-session-audit（会话日志完整性/错误诊断审计）是同一主题——session-audit 插件刻意做「诊断非修复」, 检测 error/turn 事件但从不吞掉父进程的可见性。这个小补丁是 in-tree 侧的正确修复; 若后续要「父级看板聚合子代理错误」, 那是插件演进方向。这条 thread 本身是 in-tree 修复, 不是插件面, 但值得 maintainer 看到 in-tree 侧先修 root cause。

[LiveNathan]

Thanks for the line-by-line verification against d347e70390 and for the exact anchors — that removes all the guesswork.

Confirming both key points:

1. Tool layer needs nothing. Since withDiagnosticAndPartialText() already renders result.diagnostic, the whole fix is just supplying the data. And yes — the out-of-process paths surfaced diagnostics fine, which is exactly why the bare subagent run failed was so maddening to track down (a multi-day mystery for us until the child's session log gave it up).

2. Taking the smaller change: inline message.slice(0, 4096) in the in-process driver. I'd rather not widen out-of-process.ts's module surface just to share a one-line truncation; if a shared constant is ever warranted, promoting it later is trivial.

Your reference diff is essentially the patch. The test suggestion is spot on too — asserting diagnostic === '400: Thinking level MINIMAL is not supported for this model' in the existing "child fails at model-call" spec pins the whole chain (turn/end error → result.diagnostic → tool rendering) with the real-world payload from our incident.

Happy to put up a PR (driver change + test) unless a maintainer would rather take it from here.

[chaoran]

Independently reproduced on a newer tree, so the gap is still open past your
build: master @ c291e796
(@deepseek-ai/dsh-subagent-in-process-driver 0.1.5-rc.2). readResult() still
returns { output, stopReason } with no diagnostic on any of its three return
paths.

I built the fix before finding this thread (I should have searched first — that
one is on me). Since you said you are happy to put up the driver change + test,
I don't want to duplicate it. I can either hand you the tested patch to fold
into your change, or leave it here as a reference — your call.

If it helps, three things in my version go slightly beyond the reference diff,
and two of them are exactly the points raised in #4666's review:

1. Carry code and status, not only message. [bug] Spawn-backed subagents drop reasoningEffort; endpoints that require thinking reject every delegation #4666's review asked to
   "carry the LlmFailure code alongside message so the parent can act on an
   endpoint-contract rejection but not treat an internal crash as actionable
   model feedback". Mine renders Insufficient Balance code=QUOTA status=402;
   forwarding error.message alone loses the machine-routable part.
2. Bound with a UTF-8-safe limiter, not message.slice(0, 4096). slice
   counts UTF-16 code units, so a CJK/emoji message can exceed the documented
   4096-byte cap and a cut can split a surrogate pair. The field contract is
   4096 UTF-8 bytes; the implementation encodes, cuts on a code-point boundary,
   and appends the existing \\n\[diagnostic truncated] marker so consumer text
   matches what the out-of-process path used to emit.
3. Local cancellation stays diagnostic-free. Only reason.kind === 'error'
   produces one, so a cancelled run keeps aborted without a diagnostic and
   runOutcome still maps it to killed (the Subagent failure notices don't include the error reason — parent sees "Its closing message:" followed by nothing #4334 seam). A test pins it.

Tests in the patch: driver — populated detail (message/QUOTA/402),
cancel → diagnostic === undefined, 4096-byte bound with suffix, and a
multibyte message cut with no replacement character; tool — the real in-process
spawn backend surfaces Diagnostic: Insufficient Balance code=QUOTA status=402
through dsh-tool-subagent. Changed source is 100% covered and the existing
suite is green. The patch also carries the repo-required Agent Note.

Patch: <link to your fork / gist / patch file>
Branch: <your-fork>:fix/subagent-in-process-diagnostic

Since issues and PRs are disabled upstream, I am happy for this to be carried
as a discussion artifact or folded into your branch.

Cross-links so the threads converge instead of diverging: #4666 (where the
diagnostic half was proposed and the code/status review ask came from) and
#4334 (the adjacent continuable-settlement / subagent/end seam, which this
driver change does not cover).