feat(cli): add native drag-and-drop and Cmd+V clipboard image pasting

- Implement background clipboard image synchronizer to extract raw images from system clipboard and reframe their relative text paths back to the clipboard on macOS, Windows, and Linux.
- Update parsePastedPaths to support targetDir and convert absolute file paths to clean relative paths inside the workspace.
- Update text-buffer to pass targetDir and emit a transient status toast confirming dropped/pasted files.
- Add comprehensive unit tests for relative path resolution with targetDir.

Closes #27855

Author: pedrogoiania

package-lock.json

@@ -619,6 +619,7 @@ export const AppContainer = (props: AppContainerProps) => {
     stdin,
     setRawMode,
     escapePastedPaths: true,
+    targetDir: config.getTargetDir(),
     shellModeActive,
     getPreferredEditor,
   });

packages/cli/src/ui/AppContainer.tsx

@@ -67,6 +67,8 @@ import {
   clipboardHasImage,
   saveClipboardImage,
   cleanupOldClipboardImages,
+  readClipboardText,
+  writeClipboardText,
 } from '../utils/clipboardUtils.js';
 import {
   isAutoExecutableCommand,
@@ -263,6 +265,48 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
       windowMs: DOUBLE_TAB_CLEAN_UI_TOGGLE_WINDOW_MS,
     });
   const [showEscapePrompt, setShowEscapePrompt] = useState(false);
+
+  // Background clipboard image watcher to automatically convert copied raw images
+  // into temporary files and write their relative path back to the clipboard.
+  // This allows the user to paste raw images directly into the terminal with Cmd+V!
+  useEffect(() => {
+    if (!focus || shellModeActive) {
+      return;
+    }
+
+    const intervalId = setInterval(async () => {
+      try {
+        if (await clipboardHasImage()) {
+          const currentText = await readClipboardText();
+          // Only process if the clipboard text does not already reference a clipboard image or file path
+          if (
+            !currentText.startsWith('@') ||
+            !currentText.includes('clipboard-')
+          ) {
+            const imagePath = await saveClipboardImage(config.getTargetDir());
+            if (imagePath) {
+              // Clean up old clipboard images
+              cleanupOldClipboardImages(config.getTargetDir()).catch(() => {});
+
+              // Get relative path from current workspace
+              const relativePath = path.relative(
+                config.getTargetDir(),
+                imagePath,
+              );
+              const insertText = `@${relativePath} `;
+
+              // Write the text reference back to the clipboard!
+              await writeClipboardText(insertText);
+            }
+          }
+        }
+      } catch {
+        // Ignore clipboard watcher errors silently
+      }
+    }, 1000);
+
+    return () => clearInterval(intervalId);
+  }, [focus, shellModeActive, config]);
   const { handlePress: handleEscPress, resetCount: resetEscapeState } =
     useRepeatedKeyPress({
       windowMs: 500,

packages/cli/src/ui/components/InputPrompt.tsx

@@ -25,6 +25,11 @@ import {
   getCachedStringWidth,
 } from '../../utils/textUtils.js';
 import { parsePastedPaths } from '../../utils/clipboardUtils.js';
+import {
+  appEvents,
+  AppEvent,
+  TransientMessageType,
+} from '../../../utils/events.js';
 import type { Key } from '../../contexts/KeypressContext.js';
 import { Command } from '../../key/keyMatchers.js';
 import type { VimAction } from './vim-buffer-actions.js';
@@ -769,6 +774,7 @@ interface UseTextBufferProps {
   setRawMode?: (mode: boolean) => void; // For external editor
   onChange?: (text: string) => void; // Callback for when text changes
   escapePastedPaths?: boolean;
+  targetDir?: string;
   shellModeActive?: boolean; // Whether the text buffer is in shell mode
   inputFilter?: (text: string) => string; // Optional filter for input text
   singleLine?: boolean;
@@ -2837,6 +2843,7 @@ export function useTextBuffer({
   setRawMode,
   onChange,
   escapePastedPaths = false,
+  targetDir,
   shellModeActive = false,
   inputFilter,
   singleLine = false,
@@ -2958,9 +2965,24 @@ export function useTextBuffer({
         paste &&
         escapePastedPaths
       ) {
-        const processed = parsePastedPaths(ch.trim());
+        const processed = parsePastedPaths(ch.trim(), targetDir);
         if (processed) {
           textToInsert = processed;
+          // Emit transient toast message for dragging/pasting file
+          const files = (processed.match(/@("[^"]+"|[^ ]+)/g) || []).map((f) =>
+            f.slice(1).replace(/^["']|["']$/g, ''),
+          );
+          if (files.length > 0) {
+            const displayNames = files.map((f) => pathMod.basename(f));
+            const message =
+              displayNames.length === 1
+                ? `Added ${displayNames[0]} to prompt context`
+                : `Added ${displayNames.length} files to prompt context`;
+            appEvents.emit(AppEvent.TransientMessage, {
+              message,
+              type: TransientMessageType.Hint,
+            });
+          }
         }
       }
 
@@ -2980,7 +3002,7 @@ export function useTextBuffer({
         dispatch({ type: 'insert', payload: currentText, isPaste: paste });
       }
     },
-    [shellModeActive, escapePastedPaths],
+    [shellModeActive, escapePastedPaths, targetDir],
   );
 
   const newline = useCallback((): void => {

packages/cli/src/ui/components/shared/text-buffer.ts

@@ -47,6 +47,8 @@ vi.mock('@google/gemini-cli-core', async (importOriginal) => {
   return {
     ...actual,
     spawnAsync: vi.fn(),
+    resolveToRealPath: vi.fn((p) => p),
+    isSubpath: vi.fn((parent, child) => child.startsWith(parent)),
     debugLogger: {
       debug: vi.fn(),
       warn: vi.fn(),
@@ -597,5 +599,27 @@ describe('clipboardUtils', () => {
         expect(result).toBe('@\\\\server\\share\\file.txt ');
       });
     });
+
+    describe('with targetDir', () => {
+      it('should resolve path relative to targetDir if within it', () => {
+        const targetDir = '/mock/workspace';
+        const absolutePath = '/mock/workspace/src/image.png';
+        vi.mocked(existsSync).mockImplementation((p) => p === absolutePath);
+        vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
+
+        const result = parsePastedPaths(absolutePath, targetDir);
+        expect(result).toBe('@src/image.png ');
+      });
+
+      it('should keep absolute path if outside of targetDir', () => {
+        const targetDir = '/mock/workspace';
+        const absolutePath = '/mock/image.png';
+        vi.mocked(existsSync).mockImplementation((p) => p === absolutePath);
+        vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
+
+        const result = parsePastedPaths(absolutePath, targetDir);
+        expect(result).toBe('@/mock/image.png ');
+      });
+    });
   });
 });