[Bug] classifyHandoffIfNeeded error affects BUILT-IN agents (Explore, Plan) - not just custom subagents

Summary

The classifyHandoffIfNeeded is not defined error affects built-in subagent types (e.g., Explore, Plan), not just custom subagents as previously reported. This significantly expands the scope of the bug.

Environment

| Property | Value |
|----------|-------|
| Claude Code Version | 2.1.31 |
| OS | macOS (Darwin 25.2.0) |
| Architecture | arm64 (Apple Silicon M3 Max) |
| Kernel | xnu-12377.61.12~1/RELEASE_ARM64_T6031 |

Bug Description

When using the Task tool with built-in subagent types like Explore or Plan, the agent successfully executes all tool calls (Glob, Grep, Read, etc.) but crashes during the completion/handoff phase with:

ReferenceError: classifyHandoffIfNeeded is not defined

Previous Understanding (Incorrect)

Prior issues (#22312, #22544, #22098) reported this only affected custom subagents registered via plugins or ~/.claude/agents/. Built-in agents were thought to be unaffected.

Actual Behavior

Built-in agents like Explore and Plan are also affected. This means the bug is in the core Task tool completion handler, not specific to custom agent loading.

Reproduction Steps

Method 1: Built-in Explore Agent

User: "Search the codebase for authentication patterns"

Claude invokes Task tool:
- subagent_type: "Explore"  
- prompt: "Find all files related to authentication"
- thoroughness: "medium"

Method 2: Built-in Plan Agent

User: Enters plan mode for a feature

Claude invokes Task tool:
- subagent_type: "Plan"
- prompt: "Design implementation plan for user authentication"

Expected Result

• Agent completes exploration/planning
• Returns summary to parent context
• Task marked as successful

Actual Result

1. ✅ Agent spawns successfully
2. ✅ Agent executes all tool calls (Glob, Grep, Read, Bash)
3. ✅ Agent produces all output (visible in terminal)
4. ❌ Agent crashes on completion with classifyHandoffIfNeeded is not defined
5. ❌ Task marked as "failed"
6. ❌ No summary returned to parent context

Error Details

Agent "Explore codebase" failed: classifyHandoffIfNeeded is not defined

The error is a JavaScript ReferenceError, indicating the function is being called but doesn't exist in scope.

Impact

| Severity | Critical |
|----------|----------|
| Affected Features | Task tool, all subagent types |
| User Impact | Cannot use subagent delegation effectively |
| Workaround | None - affects core built-in agents |

Affected Subagent Types (Confirmed)

• [x] Explore - built-in
• [x] Plan - built-in
• [x] Custom agents (via plugins) - previously reported
• [ ] Bash - untested
• [ ] general-purpose - untested

Root Cause Analysis

Based on the error pattern:

1. Function Missing in Scope: classifyHandoffIfNeeded is called but not imported/defined in the module handling subagent completion
2. Likely Location: Task tool's completion handler (src/tools/task/ or similar)
3. Why Built-ins Affected: The completion/handoff logic is shared between custom and built-in agents

Suggested Investigation

// The error suggests something like:
function handleSubagentCompletion(result) {
  // This function is called but not imported
  const handoffType = classifyHandoffIfNeeded(result); // ReferenceError!
  // ...
}

Check for:

• Missing import statement
• Function defined in different module but not exported
• Build/bundling issue excluding the function

Related Issues

This issue consolidates and expands on:

• #22312 - Task tool subagent fails (reported as custom agents only)
• #22544 - ReferenceError when Task agent completes
• #22098 - Task agents fail (duplicate)
• #22087 - SubagentStop hook failure
• #22722 - Subagent fails on completion
• #22933 - Agent failures with classifyHandoffIfNeeded

Key Difference: Those issues assumed built-in agents were unaffected. This issue confirms they are affected, making this a core framework bug rather than a plugin integration issue.

Suggested Fix Priority

P0 - Critical: This bug breaks a core feature (Task tool delegation) for all users, not just those using custom plugins.

Additional Context

• The actual agent work completes successfully (file reads, searches work)
• Only the result return/handoff fails
• This prevents effective use of multi-agent workflows
• No workaround exists since built-in agents are affected

---

Reporter: Walid Boudabbous (Dudoxx UG / Acceleate Consulting OU)