preview_snapshot includeImage embeds full-res base64 PNGs into tool history; providers that reject inline images brick the session permanently

Problem

t3-code_preview_snapshot with includeImage:true embeds full-resolution base64 PNG data: URLs directly into the MCP tool result (state.attachments). Those bytes persist in agent session history and are replayed to the model provider on every subsequent request.

Some providers reject inline image uploads. Observed case: opencode.ai zen gateway → upstream Console, model muse-spark-1.3-contributor-free, returns non-retryable 400 invalid_request_error: Invalid upload request on all later requests — including trivial text-only prompts. The session is permanently bricked; only surgery on the session store (deleting the attachments) recovers it.

Concrete numbers from the incident: two snapshots produced ~1.35MB + ~50KB base64 attachments (1280×800 PNGs), taking session tool history to ~2MB.

Requests

1. Downscale/compress screenshots before attaching (e.g. max-width + JPEG quality params on the snapshot tools), so the common case stays small.
2. Prefer returning a file path / saved-file reference plus text over inline base64, letting the agent re-read the image only when vision is actually needed.
3. Default includeImage to false (or document text-first usage) so agents don't attach images unless the task needs them.

Related upstream tracker (provider-side rejection): https://github.com/anomalyco/opencode/issues/47237 — this issue is the T3-side mitigation for it.

Built from a real incident diagnosed via Muse Spark through T3 Code.

Start at the t3-code_preview_snapshot tool and trace how includeImage populates state.attachments and persists into agent session history. Reproduce the large base64 data URLs described in the incident, then compare the available mitigation requests: resizing or compressing images, returning saved-file references, and changing the includeImage default. Done means later text-only requests no longer inherit provider-rejected inline images.