[BUG] Task tool agents always report "failed" — classifyHandoffIfNeeded is not defined

🐛 Bug Report

Every single Task tool subagent reports "failed" even though all work completes successfully. This has been happening 100% of the time across multiple projects, sessions, agent types, and platforms since at least v2.1.27.

The error: classifyHandoffIfNeeded is not defined

This is a ReferenceError in Claude Code's internal completion handler — a function is called but never defined in the cli.js bundle.

Environment

• Claude Code version: 2.1.34 (also reproduced on 2.1.27, 2.1.29)
• OS: Windows 11 (MINGW64_NT-10.0-26300), also reported on macOS and Linux
• Model: claude-opus-4-6 (happens with all models)

Reproduction

1. Use the Task tool to spawn any subagent (custom or built-in)
2. Let the agent complete its work successfully (file edits, git commits, etc.)
3. Agent returns with status: failed and error classifyHandoffIfNeeded is not defined

Reproducibility: 100%. Every single Task tool invocation triggers this.

What happens

<task-notification>
  <task-id>a15d42a</task-id>
  <status>failed</status>
  <summary>Agent "Execute plan 04-01" failed: classifyHandoffIfNeeded is not defined</summary>
</task-notification>

The agent's actual work completes perfectly — files are written, git commits are made, everything is correct. But the completion handler crashes because classifyHandoffIfNeeded() is called but never defined, causing the Task tool to report "failed."

Impact

This breaks any workflow that checks agent completion status:

• Plugin orchestrators (like GSD's execute-phase) see "failed" and trigger failure handlers, asking users to retry work that already succeeded
• Parallel agent workflows are particularly affected — every wave reports failures, requiring manual "continue anyway" responses
• Background agents show "failed" in task notifications despite completing all work
• CI/automation pipelines that check Task tool exit status will incorrectly fail

Workaround

For orchestrator-style workflows that spawn subagents, we've added explicit spot-check logic to bypass the false failure:

When a Task tool agent reports "failed" with error containing
"classifyHandoffIfNeeded is not defined":

1. Run spot-checks:
   - Verify expected output files exist on disk
   - Check git log for expected commits
   - Look for any self-check failure markers

2. If spot-checks PASS → treat agent as successful, proceed normally
3. If spot-checks FAIL → treat as real failure

This works because the error occurs AFTER all agent tool calls complete — the actual work is always done by the time the completion handler crashes.

Root Cause Hypothesis

A function classifyHandoffIfNeeded is referenced in Claude Code's agent completion/handoff code path but was never defined or imported in the bundled cli.js. Likely a missing import or a function that was renamed/removed during a refactor but its call site was left behind.

Related Issues

• #22087
• #22098
• #22312
• #22544

Would love to see this fixed — it's the only thing keeping parallel agent workflows from being truly seamless! 🚀