Background subagents stall when ending their turn on a pending background task

[jantimon]

What happens

Background subagents driving long tasks for this repo (e2e suites, record invocations, PR triage) repeatedly stop mid-task with a final message like "the e2e run will re-invoke me on completion" / "awaiting the monitor's completion event" — and the promised wake-up never comes. The coordinator receives a completed-notification while the OS process (the e2e suite, the recording) is still running. The work sits half-done for 10–40 minutes until a human or the coordinator resumes the agent, which then finds its command finished long ago.

Observed six times over 2026-07-24 → 2026-07-27, across unrelated agents (a dogfood run, a PR-feedback triage, a PR-merge task, and the headless-migration implementation — the last stalled twice, once straight through an explicit "poll directly, don't wait" instruction).

Root cause (investigated, mechanism confirmed on Claude Code 2.1.219)

The background-task re-invocation contract is honored only for a session that is still live:

• The top-level session idles between user turns, so it survives ending a turn with a run_in_background Bash task pending, and is re-invoked when that task exits.
• A subagent has no idle state. The moment it emits a final message with no in-flight foreground tool call, SubagentStop fires and the subagent is finalized — its result returns to the parent, and its still-running background task is orphaned. A background Bash task does not count as a "live background child" that defers finalization; only an in-flight child agent would, and background subagents have the Agent tool filtered out, so they can't create one.
• Positive control (the load-bearing measurement): the completion notification is delivered to a subagent that stays live and keeps working — verified directly with a 90s background task whose completion notification arrived at the next tool-step boundary. The wiring exists; turn-end finalization races ahead of it.

So every stall is the same one-line mistake: the agent ended its turn expecting to be woken, and turn-end is precisely the thing that makes waking impossible.

Mitigations in place

1. Brief discipline (works when followed): long commands run as ONE foreground Bash call with an explicit timeout (a ~90s e2e suite fits comfortably in timeout: 600000), or are driven to completion inside a single Bash call with a bounded poll:

   for attempt in $(seq 1 240); do [ -s out.txt ] && break; sleep 5; done; cat out.txt

   (-s so a half-written file isn't read; foreground sleep inside one call is allowed for subagents — verified.)
2. Mechanical guard (built and tested, NOT yet installed — see TODO): a SubagentStop hook in the main session's project settings that blocks a stall-shaped final message (re-invoke / will notify / awaiting … completion …) and sends back the poll instruction as the agent's next input. Loop-guarded via stop_hook_active (one nudge, then allow). Script logic fully tested against mock hook payloads; the hook runs in the main session, so it does not depend on subagents inheriting project hooks.

Human TODO

• Install the stall guard (agent self-installation of hook config is classifier-blocked, correctly):
  1. Copy subagent-stall-guard.sh into .claude/hooks/ and chmod +x it (the tested script is in the session scratchpad under stall-investigation/sandbox-project/.claude/hooks/; it is ~40 lines, pure bash, no dependencies — reproduced below for permanence).
  2. Add to .claude/settings.local.json:

     "hooks": { "SubagentStop": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/subagent-stall-guard.sh" } ] } ] }

• File the upstream issue on the Claude Code repository (draft below — the harness asymmetry is theirs to fix properly).
• Optional: decide whether the hook should be committed for all contributors (.claude/settings.json) once it has proven itself locally.

The hook script (for permanence)

#!/usr/bin/env bash
# SubagentStop guard: catch a subagent that ends its turn expecting to be
# re-invoked when a background task finishes, and force it to poll instead.
set -euo pipefail
input="$(cat)"
if printf '%s' "$input" | grep -qE '"stop_hook_active"[[:space:]]*:[[:space:]]*true'; then
  exit 0
fi
if printf '%s' "$input" | grep -qiE 're-?invoke|will notify|notify (me )?(on|upon) completion|awa(it|iting)|waiting (for|on) .*(background|task|run|monitor|completion|event)|monitor.?s? (completion|event)|(both|the).*(will )?notify'; then
  printf '%s\n' '{"decision":"block","reason":"A background task looks like it is still running and you ended your turn expecting to be re-invoked on its completion. Subagents are NOT re-invoked when a run_in_background Bash task finishes: you are finalized on turn-end and the task is orphaned. Do not wait. In ONE Bash tool call, poll the output file to completion, then act on it this turn, e.g.: for attempt in $(seq 1 240); do [ -s OUTFILE ] && break; sleep 5; done; cat OUTFILE"}'
  exit 0
fi
exit 0

Upstream issue draft (ready to file)

Title: A subagent with a live background Bash task is finalized on turn-end instead of re-invoked on task completion

Version: 2.1.219

Summary: A top-level session that starts a run_in_background Bash task and ends its turn is re-invoked when the task completes. A subagent doing the same is finalized: SubagentStop fires on turn-end, the result returns to the parent, and the still-running background task is orphaned. The completion notification never re-invokes the subagent.

Repro: (1) spawn a background subagent whose brief says to run a long command with run_in_background: true and then end its turn "to be re-invoked on completion"; (2) the coordinator receives the subagent-completion notification while the OS process demonstrably still runs; (3) resuming the subagent shows stopped (completed); it finds the command finished long ago and only then completes the work.

Expected: either hold the subagent pending like the top-level session and re-invoke it on task completion, or refuse to finalize a subagent with a live tracked background task.

Actual: finalized on turn-end; task orphaned; &-spawned "waiters" reaped only on a later resume.

Confirmed sub-facts: the completion notification IS delivered to a subagent that stays live (verified with a 90s background task); background subagents have the Agent tool filtered, so a foreground poll loop inside one tool call is their only wait primitive.

[jantimon]

Investigation complete — root cause found in the shipped bundle, repro confirmed on 2.1.220, and the mitigation is on branch claude/claude-code-bug-investigation-bjz6if (guard hook + full record under stall-investigation/). Two corrections to this issue's model, both measured:

• Headless (claude -p), the background task is killed at SubagentStop (status:"stopped" fires ~2–5s after start, before the subagent result even reaches the parent) — not orphaned. The survive-orphaned behavior observed here is the interactive/remote-session variant. Both modes lose the wake-up.
• Keeping the parent alive does not rescue the task: the completion notification is addressed to the finalized subagent's id, so a live parent never sees it. (Mechanism: the Bash completion notifier bypasses the owner-liveness router that agent/workflow notifications use, and the retire-time reclaim sweep filters on type === "local_agent", so a local_bash notification stranded by a dead owner is never re-addressed to main.)

Upstream tracking — do not file a new issue, this is a known cluster

Watch these on anthropics/claude-code to know when the bug is fixed (primary: #80834, the closest duplicate and best consolidation target):

Same mechanism (subagent finalized on turn-end, background Bash task lost):

• [BUG] Background Bash's "You will be notified when it completes" is false for a subagent that stops — the copy invites orphaning, while agent children correctly resume the parent anthropics/claude-code#80834 — subagent's "You will be notified when it completes" is false when the subagent stops (open, v2.1.218)
• Background Bash task completion never resumes in-process subagents — they idle forever while finished work sits on disk anthropics/claude-code#78782 — background Bash completion never resumes in-process subagents (open, bug)
• Background subagent never re-woken when its tracked background Bash child exits (child survives, wake event lost) anthropics/claude-code#77578 — background subagent never re-woken when its tracked background Bash child exits (open, bug has repro)
• Background tasks started by a non-root sub-agent become permanently orphaned once that sub-agent's turn ends anthropics/claude-code#77554 — tasks started by a sub-agent become permanently orphaned once its turn ends; untrackable from root (open, bug has repro)
• Background task notification enqueued but never delivered when the owning subagent already completed (SendMessage-resumed agent's orphaned Bash task) anthropics/claude-code#76681 — completion notification enqueued but never delivered when the owning subagent already completed (open, bug has repro)
• Worker fork / subagent is not woken by the completion of its LAST pending background task anthropics/claude-code#68749 — subagent not woken by its last pending background task (open; claims wake works only while another task is still pending)

Adjacent lifecycle/notification bugs (same family, different edge):

• Nested subagents: children spawned by a subagent are always async (regardless of run_in_background), completion notifications never reach the subagent parent, and TaskStop fails with ownership errors after resume anthropics/claude-code#75043 — nested subagents: children always async, completion notifications never reach the subagent parent
• [BUG] Agent teams: Monitor events and background-task notifications never wake an idle teammate — dropped, not queued (only SendMessage wakes it) anthropics/claude-code#77300 — agent teams: background-task notifications never wake an idle teammate (dropped, not queued)
• SendMessage-resumed nested subagent's completion notification routes to the top-level session, not the depth-1 parent that resumed it (first completion routes correctly) anthropics/claude-code#81438 — nested subagent completion routed to top level instead of its parent
• Nested background subagent: unresumed completion + stale idle_notifications + confident-wrong state claims turn a routine one-command deploy into a ~30-min ordeal (compounds #78782/#73647/#68922) anthropics/claude-code#80684 — nested background subagent: unresumed completion, stale idle notifications
• [BUG] Monitor tool's return message advises text-only end_turn — deterministically kills the watched task in headless (claude -p) mode anthropics/claude-code#81476 — Monitor tool copy invites text-only turn-end that kills the watched task in headless mode

Closed-as-stale precursors (pattern to be aware of — the cluster has been auto-staled twice): anthropics/claude-code#17764, anthropics/claude-code#50572, anthropics/claude-code#47936, anthropics/claude-code#23154.

No fix in the changelog through 2.1.222, and the docs document no subagent exception for run_in_background — so this is a bug, not documented intent.

How to verify a future fix

Run stall-investigation/repro/run-repro.sh B2 from the branch against the new version: fixed means the done-marker gets written and the parent receives the completion notification after the subagent stops. Once fixed upstream, the SubagentStop guard hook can be removed.

---

Generated by Claude Code