[FEATURE] Native iTerm2 image attachment over SSH via RequestUpload

Preflight checklist

• [x] I searched existing requests.
• [x] This is a single feature request: native image attachment from macOS/iTerm2 to Claude Code running on a remote host over SSH.

Related: #5277 describes the user problem and workarounds. This request proposes a concrete terminal-protocol integration.

Problem statement

When Claude Code runs locally on macOS, an image can be pasted or dropped into the prompt. When it runs on a remote Linux/macOS host through SSH from iTerm2, the same action cannot attach the local image:

• Finder drag-and-drop inserts a local path such as /Users/me/Desktop/screenshot.png; that path does not exist on the remote host.
• Ctrl+V is handled by the remote Claude Code process, so it reads the remote clipboard, not the Mac clipboard.
• The current workarounds (scp, it2ul, iTerm2 Option-drag with Shell Integration, clipboard daemons, or SSH tunnels) require setup and interrupt the prompt workflow.

This is specifically about crossing the local/remote boundary. Claude's existing image attachment support works after the file exists on the remote host.

Proposed solution

Add an iTerm2-aware attachment flow for SSH sessions using iTerm2's upload protocol:

OSC 1337 ; RequestUpload=format=tgz ST

iTerm2 asks the user to choose one or more local files, then returns ok\n followed by a base64-encoded .tar.gz payload (or abort\n). Claude Code could:

1. Detect that it is running interactively over SSH (SSH_CONNECTION/SSH_TTY).
2. Detect iTerm2 upload capability using terminal capability reporting where available, with a conservative fallback/opt-in.
3. Expose an /attach command and/or keybinding in this environment.
4. Emit RequestUpload=format=tgz, read and validate the response, and extract accepted image files into a private temporary directory on the remote host.
5. Attach the extracted images using the existing Claude Code image-input path.
6. Delete temporary files at session end or after a documented retention period.

If capability detection is reliable, show the attachment action automatically; otherwise allow an explicit setting such as terminalUploadProtocol: "iterm2".

Drag-and-drop behavior

RequestUpload opens a picker; it does not itself receive Finder drag events. For true drag-and-drop, Claude Code could additionally integrate with or document iTerm2 Shell Integration:

• iTerm2 already supports uploading a dropped file to the current remote directory via SCP when Option is held.
• Once iTerm2 inserts/returns the remote path, Claude Code should recognize it as an attachment exactly as it does for a local image path.
• A fully automatic, modifier-free drop may require cooperation from iTerm2 because the terminal emulator, not the remote TUI, owns the macOS drag event.

The protocol-backed /attach flow would still provide a native, dependency-free solution without requiring users to install clipboard daemons or manually run scp.

Security and robustness requirements

• Require an interactive user action before accepting local files.
• Limit archive size, extracted size, file count, and supported image MIME types/extensions.
• Reject absolute paths, .. traversal, symlinks, hard links, devices, and other unsafe tar entries.
• Extract into a mode-0700 directory with non-predictable names.
• Avoid printing base64 payloads or local file contents into logs/transcripts.
• Handle abort, timeout, unsupported terminals, tmux/screen passthrough, and interrupted uploads without corrupting the TUI input stream.
• Do not silently enable the protocol solely from an untrusted environment variable.

Expected user experience

Mac Finder / screenshot
        ↓
iTerm2 → SSH → remote Claude Code
        ↓
[Image #1] attached to the current prompt

The user should not need a second SSH connection, an external daemon, or a manually copied remote path.

Environment

• Local client: macOS + iTerm2
• Transport: OpenSSH
• Remote: Linux or macOS
• Application: Claude Code CLI running on the remote host

References

• iTerm2 upload escape sequence: https://stage.iterm2.com/documentation-one-page.html (Uploads / RequestUpload)
• iTerm2 remote upload with Shell Integration: https://iterm2.com/documentation-shell-integration.html (Upload with scp)
• Existing user-problem discussion: #5277

Priority

Medium-high. This affects remote-development workflows where builds, repositories, and Claude Code run on servers but screenshots originate on the developer's Mac.