From 4072fd2baf4e91b6b9efcac5fafc1724d38270fb Mon Sep 17 00:00:00 2001
From: min-k-khant <102896221+min-hinthar@users.noreply.github.com>
Date: Sun, 8 Feb 2026 06:52:41 -0800
Subject: [PATCH] fix: add workaround for Claude Code classifyHandoffIfNeeded
 bug (#480)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude Code v2.1.27+ has a bug where all Task tool agents report
"failed" due to `classifyHandoffIfNeeded is not defined` — a function
called but never defined in the cli.js bundle. The error fires AFTER
all agent work completes, so actual work is always done.

This adds spot-check fallback logic to execute-phase, execute-plan,
and quick workflows: when an agent reports this specific failure,
verify artifacts on disk (SUMMARY.md exists, git commits present).
If spot-checks pass, treat as successful.

Tracked upstream: anthropics/claude-code#24181

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 get-shit-done/workflows/execute-phase.md | 7 ++++++-
 get-shit-done/workflows/execute-plan.md  | 6 ++++++
 get-shit-done/workflows/quick.md         | 2 ++
 3 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/get-shit-done/workflows/execute-phase.md b/get-shit-done/workflows/execute-phase.md
index 5118ac456..e6fefaa08 100644
--- a/get-shit-done/workflows/execute-phase.md
+++ b/get-shit-done/workflows/execute-phase.md
@@ -160,7 +160,11 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
    - Bad: "Wave 2 complete. Proceeding to Wave 3."
    - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
 
-5. **Handle failures:** Report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
+5. **Handle failures:**
+
+   **Known Claude Code bug (classifyHandoffIfNeeded):** If an agent reports "failed" with error containing `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a GSD or agent issue. The error fires in the completion handler AFTER all tool calls finish. In this case: run the same spot-checks as step 4 (SUMMARY.md exists, git commits present, no Self-Check: FAILED). If spot-checks PASS → treat as **successful**. If spot-checks FAIL → treat as real failure below.
+
+   For real failures: report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
 
 6. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
 
@@ -320,6 +324,7 @@ Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (Task bloc
 </context_efficiency>
 
 <failure_handling>
+- **classifyHandoffIfNeeded false failure:** Agent reports "failed" but error is `classifyHandoffIfNeeded is not defined` → Claude Code bug, not GSD. Spot-check (SUMMARY exists, commits present) → if pass, treat as success
 - **Agent fails mid-plan:** Missing SUMMARY.md → report, ask user how to proceed
 - **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents likely fail → user chooses attempt or skip
 - **All agents in wave fail:** Systemic issue → stop, report for investigation
diff --git a/get-shit-done/workflows/execute-plan.md b/get-shit-done/workflows/execute-plan.md
index 9a92a9e05..1c63ce085 100644
--- a/get-shit-done/workflows/execute-plan.md
+++ b/get-shit-done/workflows/execute-plan.md
@@ -111,6 +111,12 @@ Pattern B only (verify-only checkpoints). Skip for A/C.
    - Verify key-files.created exist on disk with `[ -f ]`
    - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
    - Append `## Self-Check: PASSED` or `## Self-Check: FAILED` to SUMMARY
+
+   **Known Claude Code bug (classifyHandoffIfNeeded):** If any segment agent reports "failed" with `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a real failure. Run spot-checks; if they pass, treat as successful.
+
+
+
+
 </step>
 
 <step name="load_prompt">
diff --git a/get-shit-done/workflows/quick.md b/get-shit-done/workflows/quick.md
index a93995058..14c859ae3 100644
--- a/get-shit-done/workflows/quick.md
+++ b/get-shit-done/workflows/quick.md
@@ -141,6 +141,8 @@ After executor returns:
 2. Extract commit hash from executor output
 3. Report completion status
 
+**Known Claude Code bug (classifyHandoffIfNeeded):** If executor reports "failed" with error `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a real failure. Check if summary file exists and git log shows commits. If so, treat as successful.
+
 If summary not found, error: "Executor failed to create ${next_num}-SUMMARY.md"
 
 Note: For quick tasks producing multiple plans (rare), spawn executors in parallel waves per execute-phase patterns.