--- name: parallel-impl-agent-dies-mid-stream-verify-working-tree description: | A dispatched parallel implementation subagent can die mid-stream and leave ZERO durable output while the harness still reports the task "completed". Use when: (1) you fanned out 2+ foreground impl agents (Agent/Task tool) to edit code in one repo, (2) one returns `API Error: Response stalled mid-stream` / an empty or truncated final message, possibly alongside a background " completed (exit code 0)" notification, (3) you're about to integrate or commit their combined work. The "completed" status is a LIE here — the agent may have written nothing (target file untouched, no test created, its self-made todos all still pending). ALWAYS reconcile each agent's CLAIMED work against the actual working tree (`git status`, grep the target file for the expected change) before integrating; the healthy sibling's work is usually intact, so just finish the dead agent's task yourself. Sister to subagent-reports-complete-but-pr-unmerged (work done, integration skipped) and credit-stall-mid-orchestration-revive-collision (stalled then auto-revives and races). Pairs with shared-file-redesign-parallel-author-serial-integrate (the no-commit → serial path-scoped integrate pattern that makes this degrade gracefully). ALSO covers the INVERSE outcome — see "Variant: the agent died but the work SURVIVED" — where a long single-owner pipeline agent commits+pushes per stage, so a mid-stream death leaves finished stages already on the remote. There, redoing the task from scratch duplicates landed work: reconcile against `origin/` and open PRs BEFORE the working tree, re-dispatch only the missing stages, never `resumeFromRunId` (it re-runs everything downstream), and after the SAME stage dies 3 times do it in the main loop. AND the REVIEWER/ANALYST variant — see "Variant: the dead agent's product was its final MESSAGE" — where the right move is neither redo nor re-dispatch: the agent's transcript survives, the failure notification carries its partial result, and a SendMessage resume ("finalize from what you have; no advisor consults; no re-reading") recovers the complete deliverable in one cheap turn. author: Claude Code version: 1.3.0 date: 2026-07-23 disable-model-invocation: true --- # Parallel impl agent dies mid-stream — verify the working tree, not "completed" ## Problem You dispatch N foreground implementation agents in parallel (disjoint files). One comes back with `API Error: Response stalled mid-stream` (or an empty/truncated report), and the harness may even emit a background " completed (exit code 0)" line. If you trust that and integrate, you ship a hole: the agent wrote NOTHING — its target route is untouched, no test file exists, the todos it created for itself are all still `pending`. ## Context / Trigger Conditions - 2+ parallel `Agent`/`Task` impl agents editing code in one repo. - One returns a stall/timeout/empty final message; `subagent_tokens` ~0; a "completed" status. - You're about to run a combined `git add`/commit or a whole-repo check across both outputs. ## Solution 1. **Reconcile claimed-vs-actual before integrating.** For each agent: `git status --short` and grep its target for the expected change (e.g. `grep -n buildResponse handler.ts`). A missing edit + no new test file = the agent died; "completed (exit 0)" was the harness reporting the shell wrapper exited, NOT the work landing. 2. **Don't try to revive a dead foreground agent — finish its task yourself.** Unlike a credit-stall suspension, a mid-stream API death leaves no resumable state. You have full context; do it in the main loop (or redispatch a fresh agent with the same brief). 3. **It degrades gracefully because of the orchestration guardrails:** agents do NOT commit and do NOT run whole-repo type-check (avoids git-index races + cross-agent `tsc` false-positives on half-written files); the orchestrator does path-scoped `git add ` per unit + the full check at integration. So the survivor's work is clean and committable independent of the casualty. ## Variant: the agent died but the work SURVIVED (checkpointed pipelines) The headline case above is the *shared-file* orchestration, where agents deliberately don't commit — so a death means zero durable output. The **inverse** case is just as common and the recovery is completely different: a long, single-owner pipeline agent whose stages each `git commit && git push` before moving on. When that agent dies mid-stream, the finished stages are **already on the remote**. Treating it like the headline case — redoing the task from scratch — duplicates work and can clobber pushed commits. **So the reconcile step (Solution 1) has to look in the right place.** Working-tree-only checks lie here in the other direction: the agent's worktree may be gone or reset while its commits sit safely on `origin`. Check, in this order: ```sh git fetch origin git log --oneline origin/ # which stages actually landed? gh pr list --head --state all # did it get as far as opening a PR? git status --short # only NOW look at the tree ``` Then **re-dispatch only the missing stages**, with a brief that states what's already committed. **Do not use workflow resume.** `resumeFromRunId` re-runs everything downstream of the first changed call, not just the failed stage — for a checkpointed pipeline that means re-doing landed work. A targeted mini-workflow covering only the gap is correct. **The 3-strike escalation rule.** If the *same stage* dies three times, stop re-dispatching and do it in the main loop in small, individually-verified steps. Three failures on one stage is evidence the stage is too large for one agent context (oversized payload, long tool chains, big file rewrites), and a fourth dispatch will fail the same way. Breaking the stage into individually verified steps can recover progress without repeating the same oversized dispatch. **Design implication — pick the guardrail that matches the work.** Neither pattern is universally right: | Work shape | Guardrail | Failure mode it buys | |---|---|---| | N agents editing SHARED files in parallel | agents do NOT commit; orchestrator integrates path-scoped | death = no output, but no index races or half-written cross-checks | | ONE agent, long serial pipeline, stall-prone | agent commits + pushes per stage | death = partial-but-durable progress; resume by re-dispatching the gap | Choose per-stage commits whenever the work is long enough that a mid-stream death is likely and the agent owns its files exclusively. ## Verification `git status` + a grep of each target shows exactly the expected edits from the SURVIVING agents and nothing from the dead one; after you finish the dead one's task, the full suite + type-check pass before any commit. ## Variant: the dead agent's product was its final MESSAGE (reviewer/critic/analyst) — resume-finalize, don't redo When the stalled agent is a REVIEWER, CRITIC, or ANALYST — its deliverable is a structured final message, not file edits — the impl-agent playbook (verify tree, redo the task) wastes the whole review: there is no working tree to check, and re-dispatching re-pays the full read-and-reason cost. The recovery is different and nearly free: 1. **Read the failure notification's `` before deciding anything.** A mid-stream stall often lands AFTER the analysis is done and BEFORE the write-up — the partial result in the notification can already contain findings that matter to the result. 2. **SendMessage the SAME agent id** — it resumes from its full transcript — with a finalize-only prompt: "Your run stalled mid-stream. FINALIZE now from what you already have — do NOT consult any advisor, spawn subagents, or re-read files; write the findings list directly in the specified format." Closing the expensive paths matters: the stall often happened INSIDE one of them (an advisor consult), and an unconstrained resume can stall the same way again. 3. **Name the specific partial-result threads you want finalized** ("include your positions on X, Y, Z from your interrupted notes") so nothing silently drops between the partial and the final. Synthetic example: a reviewer finishes its analysis but stalls while writing its final report. A finalize-only message to the same resumable agent asks it to write from its existing notes. This recovers the deliverable without repeating its reading. This is distinct from `resumeFromRunId`, a workflow-level operation that can repeat downstream work. **Sub-variant — interrupted by a session or credit limit:** if the platform retains the agent transcript, it may be possible to resume after the limit resets. Inspect the partial result first. Use "finalize" when analysis is complete and "continue" when an identified computation or verification step remains. Specify the missing step and avoid unnecessary re-reading or additional delegation. If the branch or input artifacts changed during the interruption, state that delta in the resume message. Re-check affected conclusions against the changed inputs. Transcript recovery depends on platform support; when no resumable transcript exists, redispatch only the missing work from the recovered evidence. ## Notes - TRAP, surfaced reactively (`disable-model-invocation`): recall by grepping lessons/skills when a parallel agent returns a stall, or via the `/name` invocation. - The lie is specifically "completed (exit 0)" on the shell *wrapper*, not on the agent's work. Same family as subagent-reports-complete-but-pr-unmerged — different gap: there the code exists but the PR isn't merged; here the code was never written. ## References - See also: credit-stall-mid-orchestration-revive-collision, subagent-reports-complete-but-pr-unmerged, shared-file-redesign-parallel-author-serial-integrate.