read tool should reliably deliver image files to the model as vision input — claude is multimodal, let it see

preflight checklist

• [x] I have searched existing issues and this is a consolidated re-request
• [x] This is a single feature request

problem statement

claude is a multimodal model. it can see, interpret, and reason about images. the read tool's own description says:

"this tool allows claude code to read images (eg PNG, JPG, etc). when reading an image file the contents are presented visually as claude code is a multimodal LLM."

but in practice, this is unreliable to broken depending on the platform and provider. the read tool base64-encodes the image and sends it, but:

• on bedrock, the image content doesn't reach the model at all (#18588 — claude reports success but can't describe what it sees)
• mime type detection uses file extensions, not magic bytes — a png saved as .jpg (or vice versa) triggers api 400 errors (#35234, #31444, #30124, #13396, #12009)
• no image validation before sending — corrupt/malformed files get base64-encoded blindly, the api rejects them, and the bad payload persists in conversation history, permanently breaking the session (#29527, #24387)
• large or transparent images crash terminals (#27546, #11560)
• no deduplication — reading the same image multiple times balloons token usage, eventually causing permanent rate-limit lockout (#30542)

meanwhile, clipboard paste works perfectly. same image, same model, same api — but the delivery path is different and it works. the read tool path is the broken one.

why this matters — real use case

i have a folder of 200 screenshots that need to be renamed based on their visual content. claude can look at an image and say "this is a login page" or "this is a dashboard with a pie chart" — it doesn't need OCR, it has native vision.

the workflow should be:

> look at all png files in ./screenshots/ and rename each one based on what you see in the image.
>   eg: "login-page-dark-mode.png", "dashboard-metrics-chart.png", "error-404-page.png"

claude should read each image, see it, reason about it, and rename it. today this doesn't work reliably — claude reads the file, gets base64 noise or nothing, and either hallucinates a name or errors out.

this isn't a niche request. any workflow that involves visual reasoning over files on disk is blocked:

• reviewing ui screenshots for bugs
• categorizing design assets
• analyzing charts/graphs in reports
• reading handwritten notes or whiteboard photos
• comparing before/after screenshots

proposed fix

the read tool needs a reliable image pipeline:

1. detect mime type from magic bytes, not file extension — the first few bytes of any image file identify its format unambiguously
2. validate image before sending — check dimensions (< 8000px), file size (< 5MB), format support (png/jpg/gif/webp), and decodability. if validation fails, return a clear error instead of poisoning the conversation
3. deduplicate — if the same image (by path + mtime) has already been sent in this conversation, reference the existing content block instead of re-sending
4. handle provider differences — if bedrock handles image content blocks differently, adapt the payload format accordingly
5. add recovery — if an image block causes an api 400, strip it from the conversation history and retry, instead of permanently corrupting the session

existing issues (this consolidates all of them)

core problem — read tool can't reliably show images to claude:

• #618 — image analysis capability limitation (mar 2025, closed)
• #18588 — read tool can't interpret image content on bedrock (closed not planned)
• #20822 — read tool returns empty result for images (closed)
• #30925 — let the agent read image files with vision (open, most detailed)
• #30546 — context-aware pdf/image handling (open)

mime type detection broken:

• #35234 — jpeg sent as image/png (open)
• #31444 — jpeg silently converted to png (duplicate)
• #30124 — mime detected from extension not content (duplicate)
• #13396 — should use magic bytes (duplicate)
• #12009 — api 400 from mime mismatch (open)

session corruption from bad images:

• #29527 — malformed image permanently breaks session (open)
• #24387 — corrupted image in context permanently breaks session (open)
• #11560 — transparent pngs crash session (closed)
• #27546 — high-res images crash terminal (closed)
• #30542 — accumulated image reads permanently kill conversations (open)

clipboard/paste works but file read doesn't:

• #12644, #23984, #32005, #26001 — all requesting paste/drag-drop support, which proves the underlying api supports images fine — the read tool delivery path is what's broken

that's 20+ issues spanning 12 months, all describing different facets of the same fundamental problem: claude code's read tool doesn't reliably deliver images to the multimodal model.

priority

high — this is a core capability gap. claude is multimodal. claude code should let it see.

feature category

tools

additional context

the read tool description already promises this works. it should actually work — consistently, across all providers, without crashing sessions or corrupting conversation state. the model is capable; the plumbing is what needs fixing.