CLI freezes with "No messages returned" error - never recovers

When running Claude Code CLI in a long-running automated script, I occasionally encounter a "No messages returned" error that causes the CLI to freeze indefinitely. The process never completes or exits - it just hangs.

Context

I'm building an autonomous coding agent that uses Claude Code to implement features from a PRD (Product Requirements Document). I have a bash script (affectionately named "Ralph Wiggum") that iterates over user stories, having Claude implement them one at a time.

Command Being Run

cat "$SCRIPT_DIR/prompt.md" | claude --dangerously-skip-permissions --verbose --print 2>&1 | tee "$TEMP_OUTPUT"

The prompt file contains instructions for Claude to:

1. Read a JSON-based PRD with user stories
2. Pick the highest priority incomplete story
3. Implement it following existing codebase patterns
4. Run tests and linting
5. Commit the changes

Error Output

we didn't catch the error

This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason:
Error: No messages returned
    at GO9 (file:///opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js:5390:73)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)

Observed Behavior

1. Claude begins processing the prompt normally
2. At some point during execution, the error above is printed to stderr
3. The process does not exit - it hangs indefinitely
4. No further output is produced
5. Ctrl+C is required to terminate the process

Expected Behavior

• The CLI should either recover from this transient error and continue, or
• Exit with a non-zero status code so the calling script can retry

Workaround Attempted

I've implemented retry logic in my bash script that:

1. Captures output to a temp file
2. Greps for "No messages returned"
3. Retries up to 3 times with 5-second delays

However, this doesn't help because the CLI freezes - it doesn't exit, so the script can't detect completion and retry. The only option is to manually Ctrl+C.

Reproduction

This is intermittent and hard to reproduce on demand. It seems to occur:

• During long-running sessions with many tool calls
• More frequently when iterating over multiple tasks
• Possibly related to rate limiting or API timeouts?

Environment

| Component | Version |
|-----------|---------|
| Claude Code | 2.1.12 |
| macOS | 26.2 (Build 25C56) |
| Darwin Kernel | 25.2.0 (ARM64) |
| Node.js | v23.11.0 |
| npm | 10.9.2 |
| Architecture | Apple Silicon (arm64, M1) |

Minimal Reproduction Script

#!/bin/bash
# "Ralph Wiggum" - iterates over specs to implement features

MAX_ITERATIONS=10
TEMP_OUTPUT=$(mktemp)
trap "rm -f $TEMP_OUTPUT" EXIT

for i in $(seq 1 $MAX_ITERATIONS); do
  echo "Iteration $i"
  
  # This command occasionally triggers the freeze
  cat prompt.md | claude --dangerously-skip-permissions --verbose --print 2>&1 | tee "$TEMP_OUTPUT" || true
  
  # Check for completion (never reached when frozen)
  if grep -q "COMPLETE" "$TEMP_OUTPUT"; then
    echo "Done!"
    exit 0
  fi
done

Suggested Fix

The unhandled promise rejection at cli.js:5390 should be caught and either:

1. Retried with exponential backoff internally
2. Result in a clean exit with a specific error code (e.g., exit 2 for "retry recommended")
3. At minimum, not freeze the entire process

Additional Context

The error message "we didn't catch the error" suggests this is a known gap in error handling. The stack trace points to GO9 function in cli.js:5390 which is likely minified code, but the issue is clearly an unhandled async rejection.