[FEATURE] Auto-embed images when MCP tools return image file paths

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When MCP tools return image file paths (e.g., /tmp/xxx.png), Claude cannot directly view the image content. The current workflow is problematic:

1. return_path=false - Tool returns Image object directly embedded → Context explodes due to large image data
2. return_path=true - Tool returns file path string → Claude cannot see the image, user must manually copy-paste the image for Claude to view it

This creates an awkward workflow where:

• Claude says "Image saved to /tmp/xxx.png"
• User has to manually copy-paste the image back to Claude
• Only then can Claude actually analyze the image

This is especially frustrating when working with MCP tools that fetch images from remote services.

Proposed Solution

When a tool returns a file path that points to an image file, the CLI should:

1. Automatically detect that the returned string is an image file path (e.g., ends with .png, .jpg, .jpeg, .gif, .webp, etc.)
2. Automatically embed the image data into the next API request, similar to how user-pasted images are handled
3. Optionally resize/compress the image to prevent context explosion

This would make the workflow seamless:

• MCP tool returns /tmp/xxx.png
• CLI automatically embeds the image
• Claude can immediately analyze it without user intervention

The same mechanism that handles user-pasted images should be applied to tool-returned image paths.

Alternative Solutions

Current workarounds are all suboptimal:

1. Use return_path=false - Embeds image directly but causes context to explode with large images
2. Use Read tool - Claude can use the Read tool to read the image file, but this adds an extra round-trip
3. Manual copy-paste - User manually copies and pastes the image back to Claude (current painful workaround)

None of these provide the seamless experience that user-pasted images have.

Priority

Medium - Would be very helpful

Feature Category

MCP server integration

Use Case Example

Real-world scenario:

1. I'm using an MCP tool that fetches images from a remote service (e.g., issue tracking system with screenshots)
2. I call the MCP tool: issue_get_file_content(file_id="xxx", return_path=true)
3. Tool returns: /tmp/tmpABC123.png
4. Current behavior: Claude says "Image saved to /tmp/tmpABC123.png" but cannot see it. I have to manually copy-paste the image.
5. Expected behavior: CLI automatically detects this is an image path, embeds it, and Claude can immediately analyze the image content.

This happens frequently when working with:

• Issue tracking systems (Jira, GitHub issues with screenshots)
• Design tools (Figma exports)
• Any MCP tool that downloads/generates images

Additional Context

_No response_