# Clavue v8.13.1 — Image Token Guard: MCP + FileRead + Remote Send

Released: 2026-05-19

## Why this exists

v8.13.0 added a per-image token budget to clipboard paste, drag-in, PDF
extraction, bash stdout, SDK inbound, attachments, and permission prompts.
Users still hit `prompt is too long` on a single screenshot because three
high-traffic image entry points were not on the guard:

1. **MCP tool results** (`src/services/mcp/resultTransform.ts`) — puppeteer,
   playwright, computer-use MCP servers commonly emit ~3MB PNGs per call.
   Byte-resize alone left ~30k input tokens in the next turn.
2. **FileReadTool single-image path** — `readImageWithTokenBudget` defaulted
   to the file-read budget (`25,000` tokens), 16x larger than the paste
   budget. A single `Read /path/to/screenshot.png` could fill the model
   window by itself.
3. **REPL remote-send path** (`src/screens/REPL.tsx`) — when sending images
   through `activeRemote.sendMessage`, the local `processUserInput` token
   guard was bypassed.

## Fix

All three paths now route through the shared `applyTokenBudgetToImage` /
`applyTokenBudgetToImageBlock` helper, capped by `CLAVUE_IMAGE_MAX_TOKENS`
(default 1500 tokens). FileReadTool's image path now takes
`min(getImagePasteTokenBudget(), getDefaultFileReadingLimits().maxTokens)`
so an explicit Read of a screenshot can't exceed the paste budget.

## Configuration

Unchanged from v8.13.0:

| Env | Default | Effect |
|---|---|---|
| `CLAVUE_IMAGE_MAX_TOKENS` | `1500` | Per-image input token cap |
| `CLAVUE_IMAGE_MAX_TOKENS=0` | — | Disable token guard (byte-only resize) |

## Coverage matrix (cumulative)

| Entry point | v8.13.0 | v8.13.1 |
|---|---|---|
| Clipboard paste / drag-in | ✅ | ✅ |
| Pasted attachments | ✅ | ✅ |
| PDF page extraction (multi-page) | ✅ | ✅ |
| Bash stdout image | ✅ | ✅ |
| SDK / bridge inbound image block | ✅ | ✅ |
| AskUserQuestion permission prompt | ✅ | ✅ |
| ExitPlanMode permission prompt | ✅ | ✅ |
| FileReadTool single-image (`Read x.png`) | — | ✅ |
| MCP tool result image (direct) | — | ✅ |
| MCP tool result image (resource blob) | — | ✅ |
| REPL remote-send pastedContents | — | ✅ |

## Verification

- 1510 / 1516 tests pass (6 skipped, 0 fail)
- `npm run check` full gate green
- `dist/cli.js --version` → `8.13.1 (Clavue)`
