Resumed sessions with many large images become permanently broken (400 error)

Bug Description

When a session accumulates many images (e.g., iPhone screenshots at 1170x2532), resuming the session with claude --resume <id> fails with a permanent, unrecoverable 400 error:

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.21.content.91.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels"}}

The session becomes completely unusable — every subsequent message triggers the same error because the historical images are always included in the context.

Root Cause

The Anthropic API has a stricter image dimension limit (2000px max per dimension) when a request contains many images. Claude Code stores images at their original resolution in the session JSONL file and does not downscale them before sending to the API. This means:

1. User pastes several high-res screenshots during a session (e.g., 1170x2532 iPhone screenshots)
2. While individual requests may work initially (fewer images per context window), as the conversation grows and more images accumulate in context, the API starts enforcing the many-image dimension limit
3. Once triggered, the session is permanently broken — there is no way to resume it without manually editing the JSONL session file

Impact

• Session is permanently lost — the user cannot continue their work
• No user-facing workaround — the only fix is to manually locate and edit the binary session file (~/.claude/projects/<project>/<session-id>.jsonl), decode base64 image data, identify oversized images, and remove or resize them
• Silent failure path — Claude Code happily accepts large images during the session, giving no warning that the session may become unresumable later
• Context-dependent breakage — the session works fine until enough images accumulate in the context window, making this a confusing intermittent-then-permanent failure

Reproduction Steps

1. Start a Claude Code session
2. Paste/attach ~10+ high-resolution screenshots (e.g., iPhone screenshots at 1170x2532, or any image with a dimension > 2000px)
3. Have a long enough conversation that many images end up in the context
4. Exit and resume the session with claude --resume <session-id>
5. Any message will fail with the 400 error above

Expected Behavior

At minimum, one of:

1. Downscale images to fit within API limits before storing in the session file (preferred — this also reduces session file size and token usage)
2. Warn the user when an image exceeds the many-image dimension limit
3. Gracefully handle the error on resume by automatically downscaling or dropping oversized images from historical context
4. Provide a repair command like claude --repair <session-id> to fix corrupted sessions

Environment

• Claude Code version: 2.1.33
• Model: claude-opus-4-6
• OS: macOS (Darwin 24.5.0)
• Session file: 25MB JSONL with 3,439 lines, 21 images (14 exceeding 2000px)
• Image source: iPhone screenshots (1170x2532 — 3x retina resolution)

Workaround

The only current workaround is to manually edit the session JSONL file to remove or replace the base64 image data for oversized images. This is not something users should have to do.