[Bug] Main thread can stall after background task completion when Read on output file exceeds token limit

Summary

In a long tool-enabled claude -p run, the main thread can stall after a background review completes if it tries to Read the full background task output file and hits the built-in token limit.

In my case:

• the workflow reached STEP 6 of an ai-collab pipeline
• the main thread launched 2 background reviewers (Codex + Claude)
• the first background task completed successfully and emitted a task notification with an output file path
• the main thread then tried to Read the entire output file
• Read failed with:
• File content (12047 tokens) exceeds maximum allowed tokens (10000)
• after that, the main thread never recovered:
• no partial read fallback
• no summary extraction from the task notification
• no explicit failure/closure
• no progress to the next pipeline steps

A second background reviewer also completed successfully, but the main thread still did not continue.

This is different from the separate empty stdout / empty JSON result symptom. Here the issue is orchestration recovery after a completed background task + oversized output-file read.

Environment

• Claude Code CLI: 2.1.84
• Model: claude-opus-4-6
• OS: Linux / WSL2 Ubuntu
• Date observed: March 26, 2026
• Run mode: claude -p --verbose --output-format stream-json

Observed Workflow

I used a long claude -p prompt that activated an ai-collab workflow in a real repository and eventually launched:

• 1 background Codex review
• 1 background Claude review

The main thread progressed normally up to the review stage.

Then:

1. Background task completed.
2. Claude received a task notification with an output file path.
3. Claude attempted a full Read of that output file.
4. Read returned:

• File content (12047 tokens) exceeds maximum allowed tokens (10000)

1. The main thread stopped making forward progress and stayed running until I interrupted it manually.

Meanwhile, the second background reviewer completed and wrote its verdict successfully.

Expected

If a background task output file is too large for a single Read, Claude should recover by doing one of the following:

• partial read with offset/limit
• grep/search-based extraction
• consume the summary from the task notification when sufficient
• fail explicitly and close the workflow clearly

It should not remain in a silent in-between state after background tasks already completed.

Actual

• background tasks complete successfully
• output file exists
• main thread attempts full Read
• Read hits token limit
• main thread does not recover and does not close the workflow
• operator has to salvage the pipeline manually

Why This Matters

This can break long-running orchestration flows even when the actual work succeeded.

In my case it left the project in a half-finished state:

• code changes were useful and valid
• review artifacts existed
• the main workflow never reached final closure
• I had to manually review, run the quality gates, update docs, commit, push, and reset the local ai-collab status to idle

Repro Characteristics

I do not have a minimal 1-line repro yet.

What I do have is a confirmed repro pattern:

• long tool-enabled claude -p run
• background tasks used for code review
• one completed background task writes a large output file
• main thread tries to Read the entire file
• token-limit error occurs
• no recovery afterward

Evidence

• Main session id:
• 2a79de6e-d230-4f91-849c-89f59d9abb56
• Session log:
• local session JSONL captured the task notification, the oversized Read error, and the lack of follow-up recovery
• Background Claude reviewer completed and wrote its verdict successfully
• The project package had to be salvaged manually and was eventually shipped as:
• commit 133da3e

Related Issues

Possibly related, but not the same symptom:

• #32252 background tasks report completed but output files are missing or empty
• #22711 background task output file not accessible
• #30014 explore agent hang condition

This case is narrower:

• the output file existed
• the background task completed
• the failure happened in main-thread recovery after an oversized Read

Workaround

No reliable automatic workaround found.

Manual operator workaround:

• inspect the session JSONL / streamed events
• inspect the background task output files manually
• salvage the workflow outside Claude

Suggested Fix Direction

When a Read on a background task output file fails because the file exceeds tool token limits, Claude should automatically switch to a bounded recovery path instead of stalling:

• partial Read with offset + limit
• targeted Grep
• or use task-notification summary first and only fetch more detail if needed