[Bug] Read Tool: Irreversible Session Corruption with Large Files

Bug Description

Claude Code Bug Report: Large File Handling Issue

Summary

Claude Code allows the Read tool to load files larger than the Claude API's 5MB limit, which causes irreversible session corruption and makes projects unusable.

Recent Regression (Critical)

This is a recent regression introduced 2-3 days ago with cloud context retrieval changes.

Previous Behavior (Working)

• claude -c used latest local session file
• Deleting large entries from local files solved the issue
• Local-file-based session management

Current Behavior (Broken)

• claude -c automatically retrieves past context from Anthropic's cloud
• Deleting entries from local files has no effect - data restored from cloud
• Cloud-based session management

Problem Description

Current Broken Flow

1. User executes Read tool on a large file (e.g., 8.5MB image)
2. Claude Code successfully reads and stores the file in session data
3. Session data is uploaded to Anthropic's cloud servers
4. When creating new sessions, Claude Code automatically retrieves past context from cloud
5. API request fails with: "image exceeds 5 MB maximum: 8956768 bytes > 5242880 bytes"
6. All new sessions in the project become unusable

Root Cause Analysis

• Local file deletion doesn't help - data persists in Anthropic's cloud
• Cache clearing doesn't help - data persists across app restarts and system reboots
• The issue is server-side - Claude Code retrieves corrupted context from Anthropic servers
• New session files are continuously generated with the same oversized data

Reproduction Steps

1. Create a large image file (>5MB) in a project directory
2. Use Claude Code's Read tool to read the large file
3. Exit Claude Code completely
4. Restart Claude Code and try to continue the session
5. Observe API error: messages.X.content.0.tool_result.content.0.image.source.base64: image exceeds 5 MB maximum

Expected vs Actual Behavior

Expected Behavior

The Read tool should reject files larger than 5MB with a clear error message:

Error: File size (8.5MB) exceeds Claude API limit (5MB). Please compress or split the file.

Actual Behavior

• File is read successfully
• Session becomes permanently corrupted
• All subsequent sessions inherit the corrupted data
• Project becomes unusable until manual intervention

Impact

• High severity: Complete project unusability
• User confusion: No clear indication of the root cause
• Data loss risk: Users may abandon projects with valuable conversation history
• Poor user experience: Technical users must manually edit JSON files to recover

Evidence

Our investigation revealed:

• Original session file: 16.3MB → reduced to 3.2MB after removing large entries
• New session files continued to be generated at 27MB each after app restarts
• Problem persisted even after system reboot (confirming server-side storage)
• Using -r <session-id> with a cleaned session works correctly

Proposed Solution

Immediate Fix (Client-side)

Add size validation to the Read tool:

// Pseudo-code
if (fileSize > MAX_API_SIZE) {
    throw new Error(`File size (${formatSize(fileSize)}) exceeds Claude API limit (${formatSize(MAX_API_SIZE)})`);
}

Additional Improvements

1. Server-side validation: Prevent upload of oversized content
2. Automatic compression: Offer to compress large images
3. File splitting: Support reading large files in chunks
4. Session recovery: Provide built-in tools to clean corrupted sessions
5. Better error messages: Clear guidance when API limits are exceeded

Environment

• OS: macOS Darwin 24.6.0
• Claude Code Version: 1.0.93
• Date: August 29, 2025
• Project Type: JavaScript/Node.js project with screenshots

Workarounds

1. Use claude -r <session-id> to specify a clean session
2. Manually edit session JSON files to remove large entries
3. Delete large files before reading them with Claude Code

Regression Impact

This regression eliminates the previously available workaround for large file issues. The underlying problem (lack of size validation in Read tool) existed before, but users could recover by deleting large entries from local session files.

The regression particularly affects:

• Users who relied on manual session file editing as a workaround
• Recovery workflows that previously worked (delete large entries → problem solved)
• Professional workflows where large file reading was manageable with local file cleanup

Business Impact

This bug affects professional users who work with screenshots, design files, or other media in their development workflow. The complete project corruption creates significant productivity loss and user frustration.

The timing is particularly problematic as it removes the user's ability to recover from large file issues, turning a manageable problem into an unrecoverable one.

---
Priority: Critical - Recent regression that breaks previously working functionality and causes complete feature breakdown requiring manual technical intervention to resolve.

Environment Info

• Platform: darwin
• Terminal: Apple_Terminal
• Version: 1.0.96
• Feedback ID: bd98157f-208c-43d8-bd90-7795aa8e53ac

Errors

Note: Error logs were truncated.