Add interactive ValidationDialog for handling 403 VALIDATION_REQUIRED errors. (#16231)

packages/cli/src/ui/AppContainer.tsx

@@ -495,7 +495,12 @@ export const AppContainer = (props: AppContainerProps) => {
     }
   }, [authState, authContext, setAuthState]);
 
-  const { proQuotaRequest, handleProQuotaChoice } = useQuotaAndFallback({
+  const {
+    proQuotaRequest,
+    handleProQuotaChoice,
+    validationRequest,
+    handleValidationChoice,
+  } = useQuotaAndFallback({
     config,
     historyManager,
     userTier,
@@ -1471,6 +1476,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
     showPrivacyNotice ||
     showIdeRestartPrompt ||
     !!proQuotaRequest ||
+    !!validationRequest ||
     isSessionBrowserOpen ||
     isAuthDialogOpen ||
     authState === AuthState.AwaitingApiKeyInput;
@@ -1588,6 +1594,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       currentModel,
       userTier,
       proQuotaRequest,
+      validationRequest,
       contextFileNames,
       errorCount,
       availableTerminalHeight,
@@ -1678,6 +1685,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       showAutoAcceptIndicator,
       userTier,
       proQuotaRequest,
+      validationRequest,
       contextFileNames,
       errorCount,
       availableTerminalHeight,
@@ -1747,6 +1755,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       handleFinalSubmit,
       handleClearScreen,
       handleProQuotaChoice,
+      handleValidationChoice,
       openSessionBrowser,
       closeSessionBrowser,
       handleResumeSession,
@@ -1787,6 +1796,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       handleFinalSubmit,
       handleClearScreen,
       handleProQuotaChoice,
+      handleValidationChoice,
       openSessionBrowser,
       closeSessionBrowser,
       handleResumeSession,

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

@@ -17,6 +17,7 @@ import { ApiAuthDialog } from '../auth/ApiAuthDialog.js';
 import { EditorSettingsDialog } from './EditorSettingsDialog.js';
 import { PrivacyNotice } from '../privacy/PrivacyNotice.js';
 import { ProQuotaDialog } from './ProQuotaDialog.js';
+import { ValidationDialog } from './ValidationDialog.js';
 import { runExitCleanup } from '../../utils/cleanup.js';
 import { RELAUNCH_EXIT_CODE } from '../../utils/processUtils.js';
 import { SessionBrowser } from './SessionBrowser.js';
@@ -68,6 +69,16 @@ export const DialogManager = ({
       />
     );
   }
+  if (uiState.validationRequest) {
+    return (
+      <ValidationDialog
+        validationLink={uiState.validationRequest.validationLink}
+        validationDescription={uiState.validationRequest.validationDescription}
+        learnMoreUrl={uiState.validationRequest.learnMoreUrl}
+        onChoice={uiActions.handleValidationChoice}
+      />
+    );
+  }
   if (uiState.shouldShowIdePrompt) {
     return (
       <IdeIntegrationNudge

packages/cli/src/ui/components/ValidationDialog.test.tsx

@@ -0,0 +1,195 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { render } from '../../test-utils/render.js';
+import { act } from 'react';
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type Mock,
+} from 'vitest';
+import { ValidationDialog } from './ValidationDialog.js';
+import { RadioButtonSelect } from './shared/RadioButtonSelect.js';
+
+// Mock the child components and utilities
+vi.mock('./shared/RadioButtonSelect.js', () => ({
+  RadioButtonSelect: vi.fn(),
+}));
+
+vi.mock('./CliSpinner.js', () => ({
+  CliSpinner: vi.fn(() => null),
+}));
+
+const mockOpenBrowserSecurely = vi.fn();
+const mockShouldLaunchBrowser = vi.fn();
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    openBrowserSecurely: (...args: unknown[]) =>
+      mockOpenBrowserSecurely(...args),
+    shouldLaunchBrowser: () => mockShouldLaunchBrowser(),
+  };
+});
+
+vi.mock('../hooks/useKeypress.js', () => ({
+  useKeypress: vi.fn(),
+}));
+
+describe('ValidationDialog', () => {
+  const mockOnChoice = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockShouldLaunchBrowser.mockReturnValue(true);
+    mockOpenBrowserSecurely.mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('initial render (choosing state)', () => {
+    it('should render the main message and two options', () => {
+      const { lastFrame, unmount } = render(
+        <ValidationDialog onChoice={mockOnChoice} />,
+      );
+
+      expect(lastFrame()).toContain(
+        'Further action is required to use this service.',
+      );
+      expect(RadioButtonSelect).toHaveBeenCalledWith(
+        expect.objectContaining({
+          items: [
+            {
+              label: 'Verify your account',
+              value: 'verify',
+              key: 'verify',
+            },
+            {
+              label: 'Change authentication',
+              value: 'change_auth',
+              key: 'change_auth',
+            },
+          ],
+        }),
+        undefined,
+      );
+      unmount();
+    });
+
+    it('should render learn more URL when provided', () => {
+      const { lastFrame, unmount } = render(
+        <ValidationDialog
+          learnMoreUrl="https://example.com/help"
+          onChoice={mockOnChoice}
+        />,
+      );
+
+      expect(lastFrame()).toContain('Learn more:');
+      expect(lastFrame()).toContain('https://example.com/help');
+      unmount();
+    });
+  });
+
+  describe('onChoice handling', () => {
+    it('should call onChoice with change_auth when that option is selected', () => {
+      const { unmount } = render(<ValidationDialog onChoice={mockOnChoice} />);
+
+      const onSelect = (RadioButtonSelect as Mock).mock.calls[0][0].onSelect;
+      act(() => {
+        onSelect('change_auth');
+      });
+
+      expect(mockOnChoice).toHaveBeenCalledWith('change_auth');
+      unmount();
+    });
+
+    it('should call onChoice with verify when no validation link is provided', () => {
+      const { unmount } = render(<ValidationDialog onChoice={mockOnChoice} />);
+
+      const onSelect = (RadioButtonSelect as Mock).mock.calls[0][0].onSelect;
+      act(() => {
+        onSelect('verify');
+      });
+
+      expect(mockOnChoice).toHaveBeenCalledWith('verify');
+      unmount();
+    });
+
+    it('should open browser and transition to waiting state when verify is selected with a link', async () => {
+      const { lastFrame, unmount } = render(
+        <ValidationDialog
+          validationLink="https://accounts.google.com/verify"
+          onChoice={mockOnChoice}
+        />,
+      );
+
+      const onSelect = (RadioButtonSelect as Mock).mock.calls[0][0].onSelect;
+      await act(async () => {
+        await onSelect('verify');
+      });
+
+      expect(mockOpenBrowserSecurely).toHaveBeenCalledWith(
+        'https://accounts.google.com/verify',
+      );
+      expect(lastFrame()).toContain('Waiting for verification...');
+      unmount();
+    });
+  });
+
+  describe('headless mode', () => {
+    it('should show URL in message when browser cannot be launched', async () => {
+      mockShouldLaunchBrowser.mockReturnValue(false);
+
+      const { lastFrame, unmount } = render(
+        <ValidationDialog
+          validationLink="https://accounts.google.com/verify"
+          onChoice={mockOnChoice}
+        />,
+      );
+
+      const onSelect = (RadioButtonSelect as Mock).mock.calls[0][0].onSelect;
+      await act(async () => {
+        await onSelect('verify');
+      });
+
+      expect(mockOpenBrowserSecurely).not.toHaveBeenCalled();
+      expect(lastFrame()).toContain('Please open this URL in a browser:');
+      expect(lastFrame()).toContain('https://accounts.google.com/verify');
+      unmount();
+    });
+  });
+
+  describe('error state', () => {
+    it('should show error and options when browser fails to open', async () => {
+      mockOpenBrowserSecurely.mockRejectedValue(new Error('Browser not found'));
+
+      const { lastFrame, unmount } = render(
+        <ValidationDialog
+          validationLink="https://accounts.google.com/verify"
+          onChoice={mockOnChoice}
+        />,
+      );
+
+      const onSelect = (RadioButtonSelect as Mock).mock.calls[0][0].onSelect;
+      await act(async () => {
+        await onSelect('verify');
+      });
+
+      expect(lastFrame()).toContain('Browser not found');
+      // RadioButtonSelect should be rendered again with options in error state
+      expect((RadioButtonSelect as Mock).mock.calls.length).toBeGreaterThan(1);
+      unmount();
+    });
+  });
+});

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

@@ -0,0 +1,177 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { useState, useEffect, useCallback } from 'react';
+import { Box, Text } from 'ink';
+import { RadioButtonSelect } from './shared/RadioButtonSelect.js';
+import { theme } from '../semantic-colors.js';
+import { CliSpinner } from './CliSpinner.js';
+import {
+  openBrowserSecurely,
+  shouldLaunchBrowser,
+  type ValidationIntent,
+} from '@google/gemini-cli-core';
+import { useKeypress } from '../hooks/useKeypress.js';
+import { keyMatchers, Command } from '../keyMatchers.js';
+
+interface ValidationDialogProps {
+  validationLink?: string;
+  validationDescription?: string;
+  learnMoreUrl?: string;
+  onChoice: (choice: ValidationIntent) => void;
+}
+
+type DialogState = 'choosing' | 'waiting' | 'complete' | 'error';
+
+export function ValidationDialog({
+  validationLink,
+  learnMoreUrl,
+  onChoice,
+}: ValidationDialogProps): React.JSX.Element {
+  const [state, setState] = useState<DialogState>('choosing');
+  const [errorMessage, setErrorMessage] = useState<string>('');
+
+  const items = [
+    {
+      label: 'Verify your account',
+      value: 'verify' as const,
+      key: 'verify',
+    },
+    {
+      label: 'Change authentication',
+      value: 'change_auth' as const,
+      key: 'change_auth',
+    },
+  ];
+
+  // Handle keypresses during 'waiting' state (ESC to cancel, Enter to confirm completion)
+  useKeypress(
+    (key) => {
+      if (keyMatchers[Command.ESCAPE](key) || keyMatchers[Command.QUIT](key)) {
+        onChoice('cancel');
+      } else if (keyMatchers[Command.RETURN](key)) {
+        // User confirmed verification is complete - transition to 'complete' state
+        setState('complete');
+      }
+    },
+    { isActive: state === 'waiting' },
+  );
+
+  // When state becomes 'complete', show success message briefly then proceed
+  useEffect(() => {
+    if (state === 'complete') {
+      const timer = setTimeout(() => {
+        onChoice('verify');
+      }, 500);
+      return () => clearTimeout(timer);
+    }
+    return undefined;
+  }, [state, onChoice]);
+
+  const handleSelect = useCallback(
+    async (choice: ValidationIntent) => {
+      if (choice === 'verify') {
+        if (validationLink) {
+          // Check if we're in an environment where we can launch a browser
+          if (!shouldLaunchBrowser()) {
+            // In headless mode, show the link and wait for user to manually verify
+            setErrorMessage(
+              `Please open this URL in a browser: ${validationLink}`,
+            );
+            setState('waiting');
+            return;
+          }
+
+          try {
+            await openBrowserSecurely(validationLink);
+            setState('waiting');
+          } catch (error) {
+            setErrorMessage(
+              error instanceof Error ? error.message : 'Failed to open browser',
+            );
+            setState('error');
+          }
+        } else {
+          // No validation link, just retry
+          onChoice('verify');
+        }
+      } else {
+        // 'change_auth' or 'cancel'
+        onChoice(choice);
+      }
+    },
+    [validationLink, onChoice],
+  );
+
+  if (state === 'error') {
+    return (
+      <Box borderStyle="round" flexDirection="column" padding={1}>
+        <Text color={theme.status.error}>
+          {errorMessage ||
+            'Failed to open verification link. Please try again or change authentication.'}
+        </Text>
+        <Box marginTop={1}>
+          <RadioButtonSelect
+            items={items}
+            onSelect={(choice) => void handleSelect(choice as ValidationIntent)}
+          />
+        </Box>
+      </Box>
+    );
+  }
+
+  if (state === 'waiting') {
+    return (
+      <Box borderStyle="round" flexDirection="column" padding={1}>
+        <Box>
+          <CliSpinner />
+          <Text>
+            {' '}
+            Waiting for verification... (Press ESC or CTRL+C to cancel)
+          </Text>
+        </Box>
+        {errorMessage && (
+          <Box marginTop={1}>
+            <Text>{errorMessage}</Text>
+          </Box>
+        )}
+        <Box marginTop={1}>
+          <Text dimColor>Press Enter when verification is complete.</Text>
+        </Box>
+      </Box>
+    );
+  }
+
+  if (state === 'complete') {
+    return (
+      <Box borderStyle="round" flexDirection="column" padding={1}>
+        <Text color={theme.status.success}>Verification complete</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box borderStyle="round" flexDirection="column" padding={1}>
+      <Box marginBottom={1}>
+        <Text>Further action is required to use this service.</Text>
+      </Box>
+      <Box marginTop={1} marginBottom={1}>
+        <RadioButtonSelect
+          items={items}
+          onSelect={(choice) => void handleSelect(choice as ValidationIntent)}
+        />
+      </Box>
+      {learnMoreUrl && (
+        <Box marginTop={1}>
+          <Text dimColor>
+            Learn more: <Text color={theme.text.accent}>{learnMoreUrl}</Text>
+          </Text>
+        </Box>
+      )}
+    </Box>
+  );
+}

packages/cli/src/ui/contexts/UIActionsContext.tsx

@@ -46,6 +46,7 @@ export interface UIActions {
   handleProQuotaChoice: (
     choice: 'retry_later' | 'retry_once' | 'retry_always' | 'upgrade',
   ) => void;
+  handleValidationChoice: (choice: 'verify' | 'change_auth' | 'cancel') => void;
   openSessionBrowser: () => void;
   closeSessionBrowser: () => void;
   handleResumeSession: (session: SessionInfo) => Promise<void>;

packages/cli/src/ui/contexts/UIStateContext.tsx

@@ -23,6 +23,7 @@ import type {
   UserTierId,
   IdeInfo,
   FallbackIntent,
+  ValidationIntent,
 } from '@google/gemini-cli-core';
 import type { DOMElement } from 'ink';
 import type { SessionStatsState } from '../contexts/SessionContext.js';
@@ -38,6 +39,13 @@ export interface ProQuotaDialogRequest {
   resolve: (intent: FallbackIntent) => void;
 }
 
+export interface ValidationDialogRequest {
+  validationLink?: string;
+  validationDescription?: string;
+  learnMoreUrl?: string;
+  resolve: (intent: ValidationIntent) => void;
+}
+
 import { type UseHistoryManagerReturn } from '../hooks/useHistoryManager.js';
 import { type RestartReason } from '../hooks/useIdeTrustListener.js';
 import type { TerminalBackgroundColor } from '../utils/terminalCapabilityManager.js';
@@ -102,6 +110,7 @@ export interface UIState {
   // Quota-related state
   userTier: UserTierId | undefined;
   proQuotaRequest: ProQuotaDialogRequest | null;
+  validationRequest: ValidationDialogRequest | null;
   currentModel: string;
   contextFileNames: string[];
   errorCount: number;

packages/cli/src/ui/hooks/useGeminiStream.ts

@@ -28,6 +28,7 @@ import {
   processRestorableToolCalls,
   recordToolCallInteractions,
   ToolErrorType,
+  ValidationRequiredError,
   coreEvents,
   CoreEvent,
   MCPDiscoveryState,
@@ -1100,6 +1101,12 @@ export const useGeminiStream = (
               spanMetadata.error = error;
               if (error instanceof UnauthorizedError) {
                 onAuthError('Session expired or is unauthorized.');
+              } else if (
+                // Suppress ValidationRequiredError if it was marked as handled (e.g. user clicked change_auth or cancelled)
+                error instanceof ValidationRequiredError &&
+                error.userHandled
+              ) {
+                // Error was handled by validation dialog, don't display again
               } else if (!isNodeError(error) || error.name !== 'AbortError') {
                 addItem(
                   {

packages/cli/src/ui/hooks/useQuotaAndFallback.test.ts

@@ -498,4 +498,186 @@ To disable gemini-3-pro-preview, disable "Preview features" in /settings.`,
       );
     });
   });
+
+  describe('Validation Handler', () => {
+    let setValidationHandlerSpy: SpyInstance;
+
+    beforeEach(() => {
+      setValidationHandlerSpy = vi.spyOn(mockConfig, 'setValidationHandler');
+    });
+
+    it('should register a validation handler on initialization', () => {
+      renderHook(() =>
+        useQuotaAndFallback({
+          config: mockConfig,
+          historyManager: mockHistoryManager,
+          userTier: UserTierId.FREE,
+          setModelSwitchedFromQuotaError: mockSetModelSwitchedFromQuotaError,
+        }),
+      );
+
+      expect(setValidationHandlerSpy).toHaveBeenCalledTimes(1);
+      expect(setValidationHandlerSpy.mock.calls[0][0]).toBeInstanceOf(Function);
+    });
+
+    it('should set a validation request when handler is called', async () => {
+      const { result } = renderHook(() =>
+        useQuotaAndFallback({
+          config: mockConfig,
+          historyManager: mockHistoryManager,
+          userTier: UserTierId.FREE,
+          setModelSwitchedFromQuotaError: mockSetModelSwitchedFromQuotaError,
+        }),
+      );
+
+      const handler = setValidationHandlerSpy.mock.calls[0][0] as (
+        validationLink?: string,
+        validationDescription?: string,
+        learnMoreUrl?: string,
+      ) => Promise<'verify' | 'change_auth' | 'cancel'>;
+
+      let promise: Promise<'verify' | 'change_auth' | 'cancel'>;
+      act(() => {
+        promise = handler(
+          'https://example.com/verify',
+          'Please verify',
+          'https://example.com/help',
+        );
+      });
+
+      const request = result.current.validationRequest;
+      expect(request).not.toBeNull();
+      expect(request?.validationLink).toBe('https://example.com/verify');
+      expect(request?.validationDescription).toBe('Please verify');
+      expect(request?.learnMoreUrl).toBe('https://example.com/help');
+
+      // Simulate user choosing verify
+      act(() => {
+        result.current.handleValidationChoice('verify');
+      });
+
+      const intent = await promise!;
+      expect(intent).toBe('verify');
+      expect(result.current.validationRequest).toBeNull();
+    });
+
+    it('should handle race conditions by returning cancel for subsequent requests', async () => {
+      const { result } = renderHook(() =>
+        useQuotaAndFallback({
+          config: mockConfig,
+          historyManager: mockHistoryManager,
+          userTier: UserTierId.FREE,
+          setModelSwitchedFromQuotaError: mockSetModelSwitchedFromQuotaError,
+        }),
+      );
+
+      const handler = setValidationHandlerSpy.mock.calls[0][0] as (
+        validationLink?: string,
+      ) => Promise<'verify' | 'change_auth' | 'cancel'>;
+
+      let promise1: Promise<'verify' | 'change_auth' | 'cancel'>;
+      act(() => {
+        promise1 = handler('https://example.com/verify1');
+      });
+
+      const firstRequest = result.current.validationRequest;
+      expect(firstRequest).not.toBeNull();
+
+      let result2: 'verify' | 'change_auth' | 'cancel';
+      await act(async () => {
+        result2 = await handler('https://example.com/verify2');
+      });
+
+      // The lock should have stopped the second request
+      expect(result2!).toBe('cancel');
+      expect(result.current.validationRequest).toBe(firstRequest);
+
+      // Complete the first request
+      act(() => {
+        result.current.handleValidationChoice('verify');
+      });
+
+      const intent1 = await promise1!;
+      expect(intent1).toBe('verify');
+      expect(result.current.validationRequest).toBeNull();
+    });
+
+    it('should add info message when change_auth is chosen', async () => {
+      const { result } = renderHook(() =>
+        useQuotaAndFallback({
+          config: mockConfig,
+          historyManager: mockHistoryManager,
+          userTier: UserTierId.FREE,
+          setModelSwitchedFromQuotaError: mockSetModelSwitchedFromQuotaError,
+        }),
+      );
+
+      const handler = setValidationHandlerSpy.mock.calls[0][0] as (
+        validationLink?: string,
+      ) => Promise<'verify' | 'change_auth' | 'cancel'>;
+
+      let promise: Promise<'verify' | 'change_auth' | 'cancel'>;
+      act(() => {
+        promise = handler('https://example.com/verify');
+      });
+
+      act(() => {
+        result.current.handleValidationChoice('change_auth');
+      });
+
+      const intent = await promise!;
+      expect(intent).toBe('change_auth');
+
+      expect(mockHistoryManager.addItem).toHaveBeenCalledTimes(1);
+      const lastCall = (mockHistoryManager.addItem as Mock).mock.calls[0][0];
+      expect(lastCall.type).toBe(MessageType.INFO);
+      expect(lastCall.text).toBe('Use /auth to change authentication method.');
+    });
+
+    it('should not add info message when cancel is chosen', async () => {
+      const { result } = renderHook(() =>
+        useQuotaAndFallback({
+          config: mockConfig,
+          historyManager: mockHistoryManager,
+          userTier: UserTierId.FREE,
+          setModelSwitchedFromQuotaError: mockSetModelSwitchedFromQuotaError,
+        }),
+      );
+
+      const handler = setValidationHandlerSpy.mock.calls[0][0] as (
+        validationLink?: string,
+      ) => Promise<'verify' | 'change_auth' | 'cancel'>;
+
+      let promise: Promise<'verify' | 'change_auth' | 'cancel'>;
+      act(() => {
+        promise = handler('https://example.com/verify');
+      });
+
+      act(() => {
+        result.current.handleValidationChoice('cancel');
+      });
+
+      const intent = await promise!;
+      expect(intent).toBe('cancel');
+
+      expect(mockHistoryManager.addItem).not.toHaveBeenCalled();
+    });
+
+    it('should do nothing if handleValidationChoice is called without pending request', () => {
+      const { result } = renderHook(() =>
+        useQuotaAndFallback({
+          config: mockConfig,
+          historyManager: mockHistoryManager,
+          userTier: UserTierId.FREE,
+          setModelSwitchedFromQuotaError: mockSetModelSwitchedFromQuotaError,
+        }),
+      );
+
+      act(() => {
+        result.current.handleValidationChoice('verify');
+      });
+
+      expect(mockHistoryManager.addItem).not.toHaveBeenCalled();
+    });
+  });
 });

packages/cli/src/ui/hooks/useQuotaAndFallback.ts

@@ -9,6 +9,8 @@ import {
   type Config,
   type FallbackModelHandler,
   type FallbackIntent,
+  type ValidationHandler,
+  type ValidationIntent,
   TerminalQuotaError,
   ModelNotFoundError,
   type UserTierId,
@@ -19,7 +21,10 @@ import {
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { type UseHistoryManagerReturn } from './useHistoryManager.js';
 import { MessageType } from '../types.js';
-import { type ProQuotaDialogRequest } from '../contexts/UIStateContext.js';
+import {
+  type ProQuotaDialogRequest,
+  type ValidationDialogRequest,
+} from '../contexts/UIStateContext.js';
 
 interface UseQuotaAndFallbackArgs {
   config: Config;
@@ -36,7 +41,10 @@ export function useQuotaAndFallback({
 }: UseQuotaAndFallbackArgs) {
   const [proQuotaRequest, setProQuotaRequest] =
     useState<ProQuotaDialogRequest | null>(null);
+  const [validationRequest, setValidationRequest] =
+    useState<ValidationDialogRequest | null>(null);
   const isDialogPending = useRef(false);
+  const isValidationPending = useRef(false);
 
   // Set up Flash fallback handler
   useEffect(() => {
@@ -120,6 +128,36 @@ export function useQuotaAndFallback({
     config.setFallbackModelHandler(fallbackHandler);
   }, [config, historyManager, userTier, setModelSwitchedFromQuotaError]);
 
+  // Set up validation handler for 403 VALIDATION_REQUIRED errors
+  useEffect(() => {
+    const validationHandler: ValidationHandler = async (
+      validationLink,
+      validationDescription,
+      learnMoreUrl,
+    ): Promise<ValidationIntent> => {
+      if (isValidationPending.current) {
+        return 'cancel'; // A validation dialog is already active
+      }
+      isValidationPending.current = true;
+
+      const intent: ValidationIntent = await new Promise<ValidationIntent>(
+        (resolve) => {
+          // Call setValidationRequest directly - same pattern as proQuotaRequest
+          setValidationRequest({
+            validationLink,
+            validationDescription,
+            learnMoreUrl,
+            resolve,
+          });
+        },
+      );
+
+      return intent;
+    };
+
+    config.setValidationHandler(validationHandler);
+  }, [config]);
+
   const handleProQuotaChoice = useCallback(
     (choice: FallbackIntent) => {
       if (!proQuotaRequest) return;
@@ -148,9 +186,35 @@ export function useQuotaAndFallback({
     [proQuotaRequest, historyManager, config, setModelSwitchedFromQuotaError],
   );
 
+  const handleValidationChoice = useCallback(
+    (choice: ValidationIntent) => {
+      // Guard against double-execution (e.g. rapid clicks) and stale requests
+      if (!isValidationPending.current || !validationRequest) return;
+
+      // Immediately clear the flag to prevent any subsequent calls from passing the guard
+      isValidationPending.current = false;
+
+      validationRequest.resolve(choice);
+      setValidationRequest(null);
+
+      if (choice === 'change_auth') {
+        historyManager.addItem(
+          {
+            type: MessageType.INFO,
+            text: 'Use /auth to change authentication method.',
+          },
+          Date.now(),
+        );
+      }
+    },
+    [validationRequest, historyManager],
+  );
+
   return {
     proQuotaRequest,
     handleProQuotaChoice,
+    validationRequest,
+    handleValidationChoice,
   };
 }