qsssrg/subagent-completion-check-skill

/subagent-completion-check-skill — Silent Subagent Failure Detector

You are a diagnostic assistant for a specific, confirmed Claude Code bug: background subagents launched via the Agent tool (non-fork, async) can stop executing the instant they call a tool, before the tool's result is ever delivered back to them — and the harness still reports the task as status: completed, with no error surfaced anywhere. From the dispatching session's point of view this is indistinguishable from a subagent that finished successfully and simply had nothing more to say.

This is not a hypothetical. It's tracked upstream at anthropics/claude-code#47936, where users report it occurring in roughly 14-30% of tool-using background dispatches. See references/background.md for a full writeup, including an independent reproduction (control experiments isolating tool type, tool latency, and prompt size as non-factors) and a retrospective audit of 201 historical subagent transcripts.

Trigger

Invoke /subagent-completion-check-skill after dispatching any subagent that uses tools, whenever you want to confirm it actually did its job:

/subagent-completion-check-skill check /path/to/agent-<id>.jsonl
/subagent-completion-check-skill did my reviewer subagent actually run?
/subagent-completion-check-skill verify this background task completed for real

You can also invoke it naturally without the prefix — e.g. "check if that subagent actually finished" or "this agent said it was done but the file it was supposed to write isn't there."

What to do

1. Locate the subagent's transcript. When a background Agent tool call completes, the task-notification you receive includes an output_file path (usually a symlink to the real transcript, e.g. .../subagents/agent-<id>.jsonl). That path is what this skill checks. Do not Read/cat that file directly into your own context — it can be a large, full conversation transcript. Let the script inspect it instead.

2. Run the checker:

   python3 scripts/check_subagent_completion.py <output_file_or_transcript_path>
   

   It prints exactly one line and exits with a matching code:

   • OK: ... (exit 0) — either the subagent never needed a tool, or its last tool call got a result back. Trust the completion (but still apply ordinary skepticism to what the subagent claims it did — this check only rules out the specific silent-stop failure mode).
   • SILENT_FAILURE: ... (exit 1) — the exact bug signature: the last tool_use in the transcript has no matching tool_result anywhere after it. The subagent produced nothing real, no matter what the orchestrator told you.
   • ERROR: ... (exit 2) — the transcript couldn't be read (missing, empty, unreadable). Treat this the same as SILENT_FAILURE — a check that couldn't run is not a check that passed.

3. Act on the result:

   • SILENT_FAILURE or ERROR → don't trust the subagent's output. Re-dispatch the same task once (this failure is intermittent, not deterministic — see references/background.md for the measured rate). If it fails a second time, stop retrying and either do the work yourself or tell the user/orchestrator plainly that the delegated task could not be completed. Never silently substitute a partial or fabricated result.
   • OK → proceed normally, but remember this check only rules out the silent-stop bug — it says nothing about whether the subagent's actual output is correct or complete.

4. If you're designing a new delegation pattern from scratch, consider the complementary mitigation described in references/background.md: subagents that need zero tool calls (because all required context was embedded as plain text in the prompt, and the actual side effect — a post, a file write — is performed by the caller instead of the subagent) are structurally immune to this bug. That's not always practical (a code reviewer's whole job is to use tools), which is exactly why this detection-based approach exists as the general-purpose fallback.

Reference

File	Contents
references/background.md	Full bug writeup, reproduction methodology, historical data, and the two complementary mitigation strategies (tool-free subagent design vs. post-hoc detection)

Notes

• This is a diagnostic/detection tool, not a fix. The underlying bug lives in Claude Code's subagent execution runtime and can't be patched from user-space; see the linked GitHub issue for the authoritative status.
• The detection logic is intentionally simple and mechanical (inspect the last tool_use block and everything after it) rather than heuristic (e.g. "duration was suspiciously short") — every reproduced failure case during development matched this exact structural signature, and it has no false positives against 181 known-good historical transcripts.