[DOCS] Read tool docs omit text fallback for files with image extensions but non-image contents

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

Read tool behavior

Current Documentation

The docs currently say:

Read handles several file types beyond plain text: * Images: PNG, JPG, and other image formats are returned as visual content that Claude can see, not as raw bytes. Claude Code resizes and recompresses large images to fit the model's image size limits before sending them, so Claude may see a downscaled version of a large screenshot.

What's Wrong or Missing?

This section explains the normal image path, but it does not document the new v2.1.144 behavior for files whose extension looks like an image while the contents are actually text or other non-image data.

For example, if a file is named something.png but contains HTML, users now get a text fallback instead of an unrecoverable conversation. That behavior is useful and user-visible, but the docs do not explain it.

Without that note, users and SDK integrators can reasonably assume Claude Code decides solely from the filename extension and will always treat *.png as image input.

Suggested Improvement

Add a short note in the Read tool behavior section clarifying that Claude Code uses the file's actual contents when possible, not just the extension.

Suggested wording:

If a file has an image extension such as .png or .jpg but its contents are not a valid image, Claude Code falls back to returning text content when the file is readable as text, instead of treating it as image data.

The same clarification should also appear in the Agent SDK Read tool docs so SDK users know they must branch on the returned output type rather than assuming it from the path suffix alone.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/tools-reference | 252-255 | Read tool behavior explains image handling but not the mismatched-extension text fallback |
| https://code.claude.com/docs/en/agent-sdk/typescript | 1724, 2136-2152 | TypeScript SDK docs describe Read as handling text/images and show text vs image output shapes |
| https://code.claude.com/docs/en/agent-sdk/python | 2473-2489 | Python SDK docs split Read output into text vs image cases without noting content-based fallback |

Total scope: 3 pages affected

Relevant behavior changed in v2.1.144.