BUG: classifyHandoffIfNeeded is not defined - SubagentStop hook failure

same here

Same here also

Same here

same here

Additional report: Critical workflow blocker

Environment

• Version: 2.1.27
• OS: Ubuntu Linux (root)
• Date: 2026-02-02

Impact: HIGH — All Task tool agents affected

Today I experienced this error on 6 consecutive Task tool invocations:

| Agent ID | Task Description | Result |
|----------|------------------|--------|
| a702c75 | Check ACS monitoring | ❌ Failed |
| aa6b342 | Check Conductor conflicts | ❌ Failed |
| a6e55df | Remove budget config | ❌ Failed |
| a29ab83 | Create parse-agent-tokens.sh | ❌ Failed |
| ad51a9e | Create parse-agent-worktime.sh | ❌ Failed |
| a15254f | Create agent-metrics-report.sh | ❌ Failed |

Critical observation

The agents complete their work successfully — files are created, Redis data is written, code executes properly — but then fail on the handoff/completion step with:

classifyHandoffIfNeeded is not defined

This suggests the error occurs in the agent termination phase, not during execution.

Workaround (partial)

Since agents complete their tasks before failing:

1. Check if output files were created
2. Test functionality manually
3. Ignore the failure notification

However, this is not sustainable — we cannot rely on background agents for any workflow automation.

Request

This bug is blocking production workflows that depend on multi-agent orchestration.

Questions:

1. Is there a timeline for the fix?
2. Is there a specific version we should downgrade to?
3. Are there any configuration flags to work around this?

Thank you for investigating.

Same Issue here

same

Came here to report this issue. Experiencing on MacOS.

Bug Report: Oracle Agent Dependency Assumptions

### Problem
The oracle agent assumes external Perplexity research scripts exist and fails with JavaScript errors when they don't.

### Expected Behavior

• Oracle should detect available tools and adapt accordingly
• Should gracefully fallback to WebSearch/WebFetch when custom scripts aren't available
• Should not assume project-specific external dependencies exist

### Actual Behavior

1. Oracle agent attempts to run non-existent scripts/perplexity_ask.py
2. Fails with ModuleNotFoundError: No module named 'runtime'
3. Later fails with classifyHandoffIfNeeded is not defined JavaScript error
4. Agent terminates without completing research

### Steps to Reproduce

1. Spawn oracle agent for external research: `Task(subagent_type="oracle", prompt="Research messaging

architecture...")`

1. Project has no custom Perplexity integration scripts
2. Agent fails trying to use uv run python -m runtime.harness scripts/perplexity_ask.py

### Environment

• Claude Code version: 2.1.31
• Platform: macOS (Darwin 25.1.0)
• Working directory: Rails project with no Python dependencies
• GitHub user: @fullmetalengineer

### Error Log
Agent attempted:
uv run python -m runtime.harness scripts/perplexity_ask.py --query "..."

Error: ModuleNotFoundError: No module named 'runtime'
Final error: classifyHandoffIfNeeded is not defined

Agent ID: a82119e

### Suggested Fix

• Oracle should check for tool availability before attempting to use them
• Should prefer built-in WebSearch/WebFetch over external scripts
• Should have graceful fallback when external dependencies are missing
• Fix the classifyHandoffIfNeeded undefined JavaScript error

### Workaround
Use WebSearch/WebFetch directly or general-purpose agents instead of oracle agent.

### Impact

• Blocks users from using oracle agent for research
• Creates confusion about required setup
• WebSearch/WebFetch work perfectly and should be preferred

I am getting this issue on MacOS.

Root Cause Analysis (v2.1.31)

I had Claude trace through the minified source to understand exactly when this error occurs.
In the following, all line numbers are relative to the cli.js file after being run through prettier.

The Bug

The function classifyHandoffIfNeeded is called but never defined in the codebase:

// Line 421994 - only reference in entire codebase
E1 = await classifyHandoffIfNeeded({
  agentMessages: q1,
  toolPermissionContext: S1.toolPermissionContext,
  abortSignal: D1.abortController.signal,
  isNonInteractiveSession: J.options.isNonInteractiveSession,
  subagentType: q,
  totalToolUseCount: h1.totalToolUseCount,
});

The function appears to have been intended for classifying/tagging agent output when completion happens in background (perhaps to determine if a "handoff" notification to user is needed), but the implementation was never added.

When This Code Path Executes

The call is inside the "moved-to-background" completion handler (lines 421966-422035). Based on my code trace, this path is entered when:

1. Agent started without run_in_background: true (synchronous start)
2. backgroundSignal promise resolves (line 421963)
3. isBackgrounded flag is true (line 421968)

The backgroundSignal is created by q54() and stored in a Map (w$6). It's resolved by K54(), which is called by $$6(), which is triggered by the task:background keybinding (ctrl+b).

Control Flow

q54() → creates backgroundSignal promise, stores resolver in w$6 Map
                    ↓
ctrl+b pressed → $$6() → K54() → sets isBackgrounded=true, resolves signal
                    ↓
Main loop Promise.race detects signal resolution (line 421960-421965)
                    ↓
Enters background completion handler (line 421966+)
                    ↓
classifyHandoffIfNeeded() called → ReferenceError

Discrepancy with Reports

The analysis suggests the bug requires explicit ctrl+b to background an agent mid-execution. However, many reports (including this thread) describe it happening on routine Task tool usage without mentioning ctrl+b.

Possible explanations:

1. Accidental ctrl+b - especially in tmux where ctrl+b is the prefix key (code has tmux-aware handling at line 549035)
2. Keybinding conflicts - something else triggering the background action

Key Code Locations (v2.1.31)

| Function | Line | Purpose |
|----------|------|---------|
| classifyHandoffIfNeeded | 421994 | Called but undefined (the bug) |
| q54 | 296212 | Creates task with backgroundSignal promise |
| K54 | 296245 | Backgrounds agent: sets flag + resolves signal |
| $$6 | 296704 | Backgrounds all eligible agents (ctrl+b handler) |
| w$6 | 296272 | Map storing background signal resolvers |

Version History

| Version | References to classifyHandoff |
|---------|--------------------------------|
| v2.1.25 | 0 |
| v2.1.26 | 1 (introduced) |
| v2.1.27+ | 1 (persists) |

What Changed in v2.1.26

Comparing the background completion handler between versions:

v2.1.25 (working) - lines 426810-426816:

let fA = eS6(YA, VA, B),
    LA = fA.content.filter(...).map(...).join(`\n`);
rqA(VA, q, "completed", void 0, $.setAppState, LA);

v2.1.26 (broken) - same location:

let fA = ...,
    RA = await $.getAppState(),
    hA = await classifyHandoffIfNeeded({...});  // ← ADDED
if (hA)
  fA = `${hA}\n\n${fA}`;  // ← PREPEND RESULT
rqA(..., fA, ...);

The function call was added to prepend classification text to the agent output, but the function implementation was never included. This is a classic incomplete refactoring bug.

Suggested Fix

Either:

1. Define the function if it's meant to exist (look at v2.1.26 commit history for the intended implementation)
2. Remove the call - revert to v2.1.25 behavior which worked fine
3. Add a guard:

``javascript
const E1 = typeof classifyHandoffIfNeeded === 'function'
? await classifyHandoffIfNeeded({...})
: null;
``

Workaround

Downgrade to v2.1.25 if you frequently use ctrl+b to background agents:

npm install -g @anthropic-ai/claude-code@2.1.25

Or avoid pressing ctrl+b while agents are running.

---

Question for anyone hitting this bug

Are you using tmux?

The code shows ctrl+b triggers backgrounding, and in tmux, ctrl+b is the prefix key. If you're running Claude Code inside tmux and press ctrl+b (even for tmux commands), it might inadvertently trigger the background action.

The code has tmux awareness (line 549035: xA.terminal === "tmux" && D === "ctrl+b"), but there may be edge cases.

Please reply if you can confirm:

1. Were you using tmux when this happened?
2. Did you press ctrl+b at any point during the agent's execution?
3. What terminal emulator are you using?

This would help the team identify whether the trigger is always ctrl+b or if there's another code path.

I see platform:linux in the labels, but I want to add a note that I am also seeing on windows.

It happens when I interrupt a tool cool to add more info (Interrupted · What should Claude do instead?), meaning replying 'No' and add some comments

Update: Still broken on v2.1.34 (2026-02-07)

5 days since our last report. Bug persists across 3 more versions (2.1.27 → 2.1.34).

Today's failures (2026-02-07)

| Agent ID | Task | Result |
|----------|------|--------|
| a46b3b0 | Analyze all hook scripts | ❌ classifyHandoffIfNeeded |
| a250101 | Audit scripts and hooks integrity | ❌ classifyHandoffIfNeeded |
| a959426 | Audit MD docs and references | ❌ classifyHandoffIfNeeded |
| aac2607 | Check session startup and role switching | ❌ classifyHandoffIfNeeded |

Total affected agents across our sessions: 10+

Observation

The CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 flag is set. All Task tool invocations with subagent_type: Explore fail at completion. The agents do their work, collect data, then crash on the handoff step.

Impact

We cannot use multi-agent workflows reliably. Every Task tool call results in a "failed" status despite successful execution, which:

• Wastes context window (error messages)
• Breaks automated pipelines
• Forces manual verification of every agent result

Priority request

This issue has 17 thumbs-up, 11 comments from different users, zero response from Anthropic. Could a team member please acknowledge and provide an ETA?

Environment: Claude Code 2.1.34, Linux, Ubuntu

Additional Data Point: 100% Reproduction with Explore Agents (v2.1.37)

Environment

• Claude Code version: 2.1.37
• Platform: macOS (Darwin 25.2.0)
• Configuration: opusplan (Opus for planning, Sonnet for execution)
• Session ID: dc8d7924-fba2-472c-bcdf-c94d4f45425e

Test Case

Testing sub-agent model selection with Explore agent type across 3 different model configurations.

Results: 100% Failure Rate (3/3 agents)

| Agent ID | Model Requested | Model Used | Duration | Error |
|----------|----------------|------------|----------|-------|
| a8f510b | haiku | claude-haiku-4-5-20251001 ✅ | ~50s | classifyHandoffIfNeeded is not defined |
| a93cf41 | sonnet | claude-haiku-4-5-20251001 | ~45s | classifyHandoffIfNeeded is not defined |
| ad59a46 | opus | claude-haiku-4-5-20251001 | ~50s | classifyHandoffIfNeeded is not defined |

Note: Explore agents ignore the model parameter and always use Haiku (appears intentional for optimization).

Key Observations

1. All agents performed successfully for 40-50 seconds before crashing
2. Agents completed multiple tool calls (Glob, Grep, Read operations)
3. Crash occurred at completion/handoff phase (consistent with function name)
4. Even correctly-configured Haiku agent failed (not a model mismatch issue)

Error Pattern

• Error occurs after substantial execution time (not immediate)
• Consistent across all agent types tested (only tested Explore)
• Timing suggests issue is in completion/result-handoff logic
• Error name classifyHandoffIfNeeded matches the pattern described in earlier comments

No Hooks Configured

• No SubagentStop hooks in .claude/settings.json
• No PreToolUse hooks configured
• Clean installation with default configuration
• Only custom config: opusplan model setting in CLAUDE.md

Impact

• Sub-agent system completely unusable
• Cannot parallelize codebase exploration tasks
• Blocking multi-agent workflows for 40+ microservice architecture (CampX project)

Session Artifacts

Session transcripts available showing:

• Model usage verification
• Tool execution sequence
• Error timing and context

Confirms Earlier Findings

This data point confirms:

• Bug persists through v2.1.37 (from v2.1.31+)
• Affects default Explore agents (not just custom agents)
• Not related to hook configuration
• Consistent crash timing (~40-50s execution)

---

Workaround Status: Avoiding all sub-agents until fix is released.

Would be helpful to know:

1. Is there a target version for the fix?
2. Should we downgrade to a specific earlier version?
3. Is there an alternative API for parallel task execution?

Still a problem, still wasting my time, tokens, and patience. Anthropic, please fix this. Also, could you please do a little bit of testing at your end in the future, or charge less money to the paying customers you're using as beta testers? I spend more time and money fighting your bugs than I spend doing my actual work or fighting my own bugs... every day this feels more and more like obstacles with a fee.

The workaround I'm using is explicitly telling the subagents to write their final output/handoff message to a file before attempting the actual handoff... still wastes tokens, but not as many as having to redo the entire subagent session.

Just had 20+ sub-agents fail because of this 2.1.39...

Anthropic, you're really digging your own grave with stuff like this. Go on Hacker News, on Reddit - developers that used to love your product are starting to turn away due to a never-ending stream of bugs in Claude Code. Unless you fundamentally change something, you're going to loose your momentum to the competition.

same here Agent "Create AQA test scenarios" failed: classifyHandoffIfNeeded is not defined 2.1.39

Claude Code itself says: "Wait for the Claude Code fix. The error is cosmetic — agents complete their work successfully, they're just marked "failed." You can live with it."

oh wow I'm not alone here, can this get fixed it's annoying to say the least

Still failing in 2.1.41 (with Sonnet 4.5 subagents, does not happen in Opus subagents)

Hi, I reviewed 'BUG: classifyHandoffIfNeeded is not defined - SubagentStop hook failure' and can start immediately. I can deliver a first usable version quickly and iterate based on your feedback. If this scope still matches your priority, I can proceed right away.

Yes, please

On Fri, Feb 13, 2026, 5:43 AM michaellinhq @.***> wrote:

michaellinhq left a comment (anthropics/claude-code#22087) <https://github.com/anthropics/claude-code/issues/22087#issuecomment-3896742981> Hi, I reviewed 'BUG: classifyHandoffIfNeeded is not defined - SubagentStop hook failure' and can start immediately. I can deliver a first usable version quickly and iterate based on your feedback. If this scope still matches your priority, I can proceed right away. — Reply to this email directly, view it on GitHub <https://github.com/anthropics/claude-code/issues/22087#issuecomment-3896742981>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AYZJYAXSN6P3YCIXYZENU2L4LW2HNAVCNFSM6AAAAACTQD53PCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQOJWG42DEOJYGE> . You are receiving this because you commented.Message ID: @.***>

fail

Fix coming in next release

i already blocked plan mode tools forever, and i guess i am done with built-in subagents now.

All dispatched subagents sooner or later error with classifyHandoffIfNeeded is not defined for me.

Claude Code 2.1.44

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.