fix: @image.png mentions hallucinate; image tool_result stringified

[ericleepi314]

Summary

User reported wildly wrong output when asking about an @-mentioned image. Same provider + model:

• Python (before): "The screenshot shows a Google search results page for the query 'how to use claude code'."
• TypeScript: "The image shows an aerial view of a white research or expedition-style ship..."

Two independent bugs both contribute. The recently merged PR #154 (image-handling parity) fixed the Read tool's image pipeline but missed both of these paths.

Bug A — @image.png reads PNG as UTF-8 text and floods system-reminder with mojibake

src/command_system/input_processing.py:expand_at_mentions was opening every @-mentioned file with open(path, "r", encoding="utf-8", errors="replace"). For a PNG that produces utf-8 replacement chars over the binary bytes — and format_at_mention_attachments wrapped the garbage in <system-reminder>Contents of foo.png:\n\``\n\n```\n` and prepended it to the user message. The model latched onto ASCII fragments (PNG XMP "Screenshot" metadata, type tags) and hallucinated the rest.

Fix: detect image extensions (png/jpg/jpeg/gif/webp, aligned with the Read tool's IMAGE_EXTENSIONS) BEFORE the text-mode open(). Image files go through the same pipeline the Read tool uses (post-#154): bounded byte read → magic-byte format sniff → maybe_resize_image → compress_image_to_token_budget fallback when still over the 5 MB base64 API ceiling. Return a kind="image" attachment carrying base64 + media_type. The REPL builds a mixed [TextBlock, ImageBlock, ...] user message via new helper build_image_content_blocks so the API receives a real multimodal payload — matching TS's auto-Read-on-@image behaviour.

Bug B — _dispatch_single_tool JSON-stringifies list content, destroying image blocks

src/query/query.py:_dispatch_single_tool was running json.dumps on any non-string tool_result content, turning Read's properly-shaped [{"type": "image", "source": {...}}] into a text JSON blob. The Anthropic API then received an image tool_result whose content was text JSON; the model literally could not see the image and would continue hallucinating even after explicitly calling Read. PR #154's regression test only checked for the synthetic-error placeholder so this slipped through.

Fix: preserve list shape end-to-end. ToolResultBlock.content already accepts str | list[Any]; maybe_persist_large_tool_result already short-circuits image lists via _has_image_block; content_block_to_dict already serializes per-element. The dispatcher just needed to stop coercing.

Collateral fix — Anthropic image blocks didn't translate for OpenAI-compatible providers

_convert_anthropic_messages_to_openai was passing Anthropic image blocks through unchanged — OpenAI/GLM/Minimax/DeepSeek/OpenRouter either rejected the request or silently dropped the image. This was pre-existing (Read tool images had the same problem post-#154) but my @image.png work would have widened the attack surface, so addressed it here.

• New _anthropic_image_block_to_openai translates {"type": "image", "source": {"type": "base64", ...}} → {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}.
• For tool_result content with images: emits role=tool (text body, with a placeholder when image-only) followed by a synthetic role=user carrying the image_url blocks. Unavoidable split since OpenAI's role=tool doesn't accept multimodal content. Comment in-place documents the model-perception risk.
• Empty-data guard returns None rather than producing data:image/png;base64, (which OpenAI rejects with a confusing error).

Signature widening

• Conversation.add_user_message(content: str | list[ContentBlock])
• QueryEngine.submit_message(prompt: str | list[ContentBlock])

Both bodies already supported list content via _normalize_message_content / MessageContent; only the annotations changed, so existing string-callers (TUI, headless) are unaffected.

REPL UX

Image @-mentions skip the direct-stream short-circuit (it can only carry plain text) and print Read image <path> instead of Listed file <path>.

Test plan

• 29 new tests across tests/test_at_mention_images.py (17), tests/test_openai_compat_image_translation.py (13), and tests/parity/test_e2e_file_read.py (+2 covering Bug B dispatcher list-preservation and the aggregate-budget pressure path).
• Bug A coverage: single + multi-image + mixed text+image @-mentions; magic-byte detection beats extension (misnamed .png with JPEG bytes); empty/undecodable images dropped silently; oversize-image compression brings base64 under API limit (real 4000×4000 random-noise PNG); doubly-oversize image dropped (monkeypatched); end-to-end through normalize_messages_for_api.
• Bug B coverage: dispatcher returns list content with {"type": "image", ...}; full pipeline through normalize_messages_for_api yields proper image block in API payload; aggregate-pressure path (image still survives at tool_result_chars_so_far = MAX - 1, counter NOT bumped by image bytes).
• OpenAI translation coverage: valid/invalid block translation; JPEG/PNG/missing-media-type defaults; empty-data guard; tool_result image-only + image+text + text-only-no-regression paths.
• Wider suite: 4984 pass, 0 new failures. 9 pre-existing failures (mcp/zhipuai import issues + workspace-path tests) unchanged.
• Manual REPL smoke: critic-agent verified the BLOCKER fix against a real 48 MB random-noise PNG (compresses to 1.16 MB base64, doubly-oversize drops). Final manual REPL test with a real screenshot still recommended before declaring shipped.
• Critic review loop: APPROVE after three rounds.

🤖 Generated with Claude Code