[FEATURE] Context-aware PDF/image handling in Read tool — replace-on-re-read, text-first mode, multimodal budget

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single feature request

Feature Description

The Read tool's handling of PDF (and image) files needs context-aware intelligence. Currently, every Read of a PDF inserts a full base64 document content block into the conversation that persists indefinitely and compounds with each subsequent read. There is no deduplication, no eviction, no budget, and no text-first fallback.

This creates a silent trap in any iterative document workflow (edit → render → verify → repeat) where the accumulated multimodal content eventually overwhelms the conversation. See bug report #30542 for a detailed forensic analysis of the failure mode.

This feature request proposes making the Read tool context-aware for multimodal content so that Claude (and users) can't accidentally poison their own conversations.

---

The Problem: A Common Workflow That Silently Self-Destructs

A completely normal document workflow in Claude Code:

User: "Edit the markdown"           → Edit tool (small, text)
User: "Regenerate the PDF"          → Bash tool (no output)
User: "Check if it fits on one page"→ Read tool (full PDF as base64 document block)
User: "Fix the margin"              → Edit tool (small, text)
User: "Regenerate and check again"  → Bash + Read (ANOTHER full PDF document block)
... repeat 3-5 times ...
💀 Conversation permanently rate-limited

Each iteration adds ~21KB of base64 / ~2,000 image tokens to the context. Since the entire conversation is resent on every API call, these compound. After 4-5 iterations, the conversation is dead.

The user did nothing wrong. Claude did nothing wrong. The tooling allowed a perfectly reasonable workflow to silently accumulate fatal context weight.

---

Proposed Changes

1. Replace-on-re-read (highest impact, simplest)

When the Read tool reads a file that already has a document block in context, replace the old block instead of adding a new one.

Before (current behavior):
  Context: [PDF v1] [text...] [PDF v2] [text...] [PDF v3] [text...] [PDF v4]
  → 4× document blocks, all sent on every API call

After (proposed):
  Context: [text...] [text...] [text...] [PDF v4]
  → Only the latest version retained

This single change would have prevented the bug in #30542 entirely.

2. Text-first mode for PDFs

Many PDF reads don't need visual rendering. When Claude reads a PDF to verify content (not layout), extracting text with pdftotext would cost a fraction of the tokens:

| Mode | Token Cost (1-page PDF) | When to Use |
|---|---|---|
| Full document block (current) | ~2,000 tokens | Layout/formatting verification |
| Text extraction | ~200-400 tokens | Content verification, proofreading |

This could be:

• Automatic: Use text extraction by default, full render only when Claude explicitly requests visual inspection
• Heuristic: If the PDF is text-only (no images, simple layout), prefer text extraction
• Parameter: Add a mode parameter to the Read tool: visual vs text

3. Multimodal content budget

Cap the number of active document/image blocks in context. When a new one is added and the cap is reached, evict the oldest.

Suggested defaults:

• Max document blocks: 3 (configurable)
• Eviction strategy: Oldest first, with a one-line summary replacing the evicted block (e.g., "[Previously read: report.pdf — evicted to save context]")

This provides a safety net even when reading different files.

4. Context weight visibility

Give Claude (and the user) visibility into how much context weight multimodal content is consuming:

Context Usage: 45% text | 38% documents (3 PDFs) | 17% system
⚠️ Document blocks are consuming 38% of context budget

This could live in the existing /status or context usage display, so users can make informed decisions about when to /compact.

---

Why This Matters

PDF and image reading is a core capability that Claude Code actively offers and uses. The Read tool's own documentation says:

"This tool allows Claude Code to read images (eg PNG, JPG, etc)." "This tool can read PDF files (.pdf)."

Users are encouraged to use this. But the current implementation has no guardrails for the most natural usage pattern: iterative reading. Every developer who uses Claude Code to review mockups, verify generated documents, or iterate on visual output will eventually hit this wall — most without understanding why.

The proposed changes aren't about limiting functionality — they're about making the existing functionality safe by default for the workflows it's designed to support.

---

Impact on Existing Behavior

| Change | Breaking? | Risk |
|---|---|---|
| Replace-on-re-read | No — old behavior was never useful | Low |
| Text-first mode | Mild — some visual checks might need explicit opt-in | Low |
| Multimodal budget | Possible — power users reading many distinct files | Low (configurable cap) |
| Context visibility | No — additive only | None |

---

Related Issues

| Issue | Relationship |
|---|---|
| #30542 | Bug report documenting the failure mode this feature would prevent |
| #25805 | Rate limit error messaging — context visibility would help here too |
| #4095 | Context/cache explosion from different cause — budget would help |