Image paste silently fails when wl-paste is present but non-functional (X11 session, no Wayland compositor)

Summary

On Linux X11-only sessions (no Wayland compositor running), image clipboard paste fails silently if wl-paste (from the wl-clipboard package) is installed but non-functional. Claude Code appears to prefer wl-paste when it's present in PATH, without checking whether a Wayland session is actually active, and does not fall back to xclip when wl-paste fails.

Environment

• OS: Kubuntu (KDE Plasma), X11 session (XDG_SESSION_TYPE=x11, WAYLAND_DISPLAY unset)
• Claude Code version: 2.1.224 (also reproduced on 2.1.221 before upgrading)
• Terminals tested: PyCharm integrated terminal (JetBrains "Reworked Terminal" engine) and kitty — both affected identically, ruling out a terminal-specific cause
• Clipboard tools installed: both wl-paste (wl-clipboard package) and xclip

Steps to reproduce

1. On a Linux machine running X11 only (no Wayland compositor), install both wl-clipboard and xclip.
2. Copy a screenshot/image to the clipboard (e.g. via Flameshot).
3. In Claude Code CLI, attempt to paste the image (Ctrl+V or Alt+V).

Expected behavior

The image should attach to the prompt, since xclip can successfully read the image from the clipboard.

Actual behavior

Image paste fails silently: no error message, no attachment, no feedback of any kind.

Root cause (diagnosed locally)

$ wl-paste -t image/png
Failed to connect to a Wayland server: No such file or directory
Note: WAYLAND_DISPLAY is unset (falling back to wayland-0)

$ xclip -selection clipboard -t image/png -o | wc -c
17160   # succeeds, correct PNG bytes

wl-paste fails immediately because no Wayland server is running, while xclip succeeds and returns the correct data. Claude Code's clipboard-reading logic seems to pick wl-paste whenever it exists in PATH, regardless of session type, and doesn't fall back to xclip on failure.

Workaround

Placing a shim script named wl-paste earlier in PATH (e.g. ~/.local/bin/wl-paste) that forwards to xclip when no Wayland socket is detected, and to the real wl-paste binary otherwise, fixes the issue completely. Confirmed working identically in both the PyCharm terminal and kitty after the shim was installed.

Suggested fix

Before invoking wl-paste, check for an active Wayland session ($WAYLAND_DISPLAY set and its socket present under $XDG_RUNTIME_DIR), and/or fall back to xclip when running under XDG_SESSION_TYPE=x11 or when wl-paste exits non-zero / produces no output.