[BUG] Background task queue operations after completion signal cause session hang (stop_reason: null)
Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
What's Wrong?
Short Description
When a Bash command exceeds its timeout and converts to a background task, the internal queue operations can occur after Claude signals completion (regardless of method - StructuredOutput, XML tags, or normal end_turn), leaving the session permanently hung with stop_reason: null.
Full Explanation
#### Environment
- Claude Code version: 2.1.12
- Platform: macOS Darwin 25.0.0
- Mode: Pipe mode (
claude -p --output-format json) - Model: Opus 4.5
Root Cause Analysis
Timeline from failing session ea410998-d7ef-4963-adf0-7a1a640ff97a:
| Time (UTC) | Event |
|--------|--------|
| 05:58:32 | Bash called with timeout: 600000 for web mutation tests |
| 06:08:32 | Timeout exceeded → converted to background task ba36dce |
| 06:08:43 | TaskOutput called to wait for ba36dce |
| 06:09:39 | Background task completes → enqueue operation |
| 06:09:39 | TaskOutput returns result |
| 06:22:04 | Second mutation test times out → background task bf53eac |
| 06:22:16 | TaskOutput called for bf53eac |
| 06:29:44 | Background task completes → enqueue operation |
| 06:29:44 | TaskOutput returns result |
| 06:30:12 | StructuredOutput called (completion signal) |
| 06:30:16.814 | dequeue operation (4 sec AFTER completion) |
| 06:30:16.815 | dequeue operation |
| ∞ | Session hung - stop_reason: null |
The bug: Dequeue operations are processed after the completion signal. The session ends up with pending queue state that prevents proper termination.
Pattern Correlation
| Session ID | Background Tasks | Queue-ops | Hung? |
|--------|--------|--------|--------|
| d772cfa0 (success) | 0 | 1 | No |
| 5af2ef03 (fail) | 1 | 3 | Yes |
| ea410998 (fail) | 2 | 5 | Yes |
Sessions with timeout-converted background tasks accumulate queue operations and hang. Sessions without background tasks terminate cleanly.
Key Observations
- This is not related to
--json-schemaor StructuredOutput specifically - sessions with and without showed the same pattern - The issue only manifests when commands exceed their timeout and get converted mid-execution
- TaskOutput successfully retrieves results - the queue operations are an internal notification mechanism that desyncs
What Should Happen?
Session should stop properly after the dequeue or Claude should wait for the dequeue to return the completion signal
Error Messages/Logs
Steps to Reproduce
Reproduction Scenario
- Run Claude in pipe mode
- Have Claude execute a command with timeout that will be exceeded
- Command converts to background task
- Claude retrieves result via TaskOutput, continues, completes
- Session hangs - queue dequeue operations arrive after completion
Claude Model
Opus
Is this a regression?
I don't know
Last Working Version
_No response_
Claude Code Version
2.1.12 (Claude Code)
Platform
AWS Bedrock
Operating System
macOS
Terminal/Shell
Other
Additional Information
_No response_
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗