feat: show pasted images as [Image #N] and make the chip un-attach them

[ericleepi314]

Follow-up to #761, from two user-reported gaps.

1. A pasted image left no trace in the input box

The composer now shows the reference's chip:

> what this image is about?
  [Image #2]

The chip is not decoration. The backend assigns the id, and at submit it drops any pending image whose [Image #N] is no longer in the text — so deleting the chip un-attaches the image. That's the reference's rule (handlePromptSubmit.ts:225), and it closes the gap #761 shipped with: previously the only way to undo an accidental attach was /clear, which destroys the conversation.

The chip text stays in the prompt the model sees — the reference leaves image refs inline and sends the bytes as separate blocks (history.ts:79).

_pending_images entries become (image_id, PastedImage, expects_placeholder) behind the existing _queue_image choke point, with a monotonic per-session _image_seq. Session-wide rather than per-prompt on purpose: ids are never reused and the drain is destructive, so a stale chip recalled from history or /resume matches nothing. A per-prompt reset would be worse than the reference — a recalled [Image #1] would keep a freshly-pasted image #1 alive after its real chip was deleted.

2. Cmd+V did nothing on macOS

A third unwired RPC: clipboard.paste. macOS terminals own Cmd+V and, with an image-only clipboard, deliver an empty bracketed paste — which lands in the composer's empty-paste branch, calls onClipboardPaste, and hit gatewayClient's "Unhandled RPC (Phase 2)" default. Resolved {}, silently, because that call passes quiet=true.

The keybinding was never the missing piece. I checked three references and they disagree:

project	Cmd+V bound?	how
hermes (clawcodex's ui-tui ancestor)	yes	isMac && isActionMod(k) && inp === 'v' in textInput.tsx; super+v reserved in platform.ts
openclaude	no — reserved, severity error	image paste is ctrl+v; ships a tip "use control+v (not cmd+v!)"
opencode	no	ctrl+v only (though it uses super+z/super+a), plus a re-dispatch on an empty bracketed paste

clawcodex already inherited hermes' binding, so Cmd+V works as a keypress wherever the terminal reports Cmd, and through the empty-paste route where it doesn't (Apple Terminal). Ctrl+V works everywhere.

⚠️ placeholder is a call-site property, not an RPC property

Whether an [Image #N] chip gets rendered depends on the caller, so the flag has to come from one. Six sites reach these four RPCs and only three render a chip. Hardcoding placeholder: true at the RPC layer made the backend drop the images of the other three — /image, the CLAWCODEX_TUI_IMAGE startup image, and typed-path submit — at submit time, after their UI had already printed "📎 Attached image". Both of those worked when #761 shipped.

Default false is fail-open, so headless -p and the VS Code bridge keep sending their images. If a new image entry point is added, it must opt in only if it renders a chip.

Testing

Tests pin the cross-layer invariant in both directions — that's what was missing when a green suite hid the above:

• RPC forwards true from a chip-rendering caller, defaults to false, and refuses a truthy-ish 'yes'.
• The real _do_clipboard_image / _do_detect_file_drop honour the flag and drop on a deleted chip (TestClipboardRouteHonorsPlaceholder).
• TestChipIsAuthoritative: kept chip sends, deleted chip drops, partial drop keeps the right image (distinguishable bytes, so it can actually tell), chip text stays inline, queue drained even when everything was un-attached, no-placeholder client unaffected.

Live: clipboard image → [Image #1] → claude-opus-5 read **PURPLE-ELEPHANT-42** (finish_reason: end_turn); with the chip deleted the prompt went out as plain text with the queue drained.

Python 9007 passed / 3 skipped / 0 failed. ui-tui 1545 passed, same 8 pre-existing baseline failures. tsc --noEmit clean; 0 lint errors.

One flake worth naming: an earlier full run failed test_sigterm_triggers_drain. It passes in isolation and 5/5 runs of its file, has zero overlap with anything here, and fires SIGTERM 200ms into a subprocess expecting the handler to be installed — load-sensitive. A clean re-run of identical code confirmed it.

Follow-ups (not in this change)

• Atomic chip — one backspace should delete the whole pill (Cursor.ts:346-370). Today it takes 10, and a partial [Image #1 silently un-attaches.
• Chip for /image — it currently prints a notice instead, which also leaves session.ts:162's remainder-replaces-composer behavior unaddressed.

🤖 Generated with Claude Code

[github-actions]

Test Results

    1 files      1 suites   7m 40s ⏱️
9 010 tests 9 004 ✅ 6 💤 0 ❌
9 256 runs  9 250 ✅ 6 💤 0 ❌

Results for commit 9f87c0f.

♻️ This comment has been updated with latest results.