Add files using upload-large-folder tool

packages/cli/src/commands/extensions/examples/custom-commands/.gitignore

@@ -0,0 +1,26 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-error.log
+yarn-debug.log
+
+# Build output
+dist/
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# TypeScript
+*.tsbuildinfo
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDEs
+.vscode/
+.idea/

packages/cli/src/commands/extensions/examples/custom-commands/commands/fs/grep-code.toml

@@ -0,0 +1,6 @@
+prompt = """
+Please summarize the findings for the pattern `{{args}}`.
+
+Search Results:
+!{grep -r {{args}} .}
+"""

packages/cli/src/commands/extensions/examples/custom-commands/gemini-extension.json

@@ -0,0 +1,4 @@
+{
+  "name": "custom-commands",
+  "version": "1.0.0"
+}

packages/cli/src/commands/extensions/examples/hooks/.gitignore

@@ -0,0 +1,26 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-error.log
+yarn-debug.log
+
+# Build output
+dist/
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# TypeScript
+*.tsbuildinfo
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDEs
+.vscode/
+.idea/

packages/cli/src/commands/extensions/examples/hooks/gemini-extension.json

@@ -0,0 +1,4 @@
+{
+  "name": "hooks-example",
+  "version": "1.0.0"
+}

packages/cli/src/commands/extensions/examples/hooks/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${extensionPath}/scripts/on-start.js"
+          }
+        ]
+      }
+    ]
+  }
+}

packages/cli/src/commands/extensions/examples/hooks/scripts/on-start.js

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+console.log(
+  'Session Started! This is running from a script in the hooks-example extension.',
+);

packages/cli/src/commands/extensions/examples/mcp-server/example.js

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const server = new McpServer({
+  name: 'prompt-server',
+  version: '1.0.0',
+});
+
+server.registerTool(
+  'fetch_posts',
+  {
+    description: 'Fetches a list of posts from a public API.',
+    inputSchema: z.object({}).shape,
+  },
+  async () => {
+    const apiResponse = await fetch(
+      'https://jsonplaceholder.typicode.com/posts',
+    );
+    const posts = await apiResponse.json();
+    const response = { posts: posts.slice(0, 5) };
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response),
+        },
+      ],
+    };
+  },
+);
+
+server.registerPrompt(
+  'poem-writer',
+  {
+    title: 'Poem Writer',
+    description: 'Write a nice haiku',
+    argsSchema: { title: z.string(), mood: z.string().optional() },
+  },
+  ({ title, mood }) => ({
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Write a haiku${mood ? ` with the mood ${mood}` : ''} called ${title}. Note that a haiku is 5 syllables followed by 7 syllables followed by 5 syllables `,
+        },
+      },
+    ],
+  }),
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

packages/cli/src/commands/extensions/examples/mcp-server/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "mcp-server-example",
+  "version": "1.0.0",
+  "description": "Example MCP Server for Gemini CLI Extension",
+  "type": "module",
+  "main": "example.js",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.23.0",
+    "zod": "3.22.4"
+  }
+}

packages/cli/src/commands/extensions/examples/policies/README.md

@@ -0,0 +1,41 @@
+# Policy engine example extension
+
+This extension demonstrates how to contribute security rules and safety checkers
+to the Gemini CLI Policy Engine.
+
+## Description
+
+The extension uses a `policies/` directory containing `.toml` files to define:
+
+- A rule that requires user confirmation for `rm -rf` commands.
+- A rule that denies searching for sensitive files (like `.env`) using `grep`.
+- A safety checker that validates file paths for all write operations.
+
+## Structure
+
+- `gemini-extension.json`: The manifest file.
+- `policies/`: Contains the `.toml` policy files.
+
+## How to use
+
+1.  Link this extension to your local Gemini CLI installation:
+
+    ```bash
+    gemini extensions link packages/cli/src/commands/extensions/examples/policies
+    ```
+
+2.  Restart your Gemini CLI session.
+
+3.  **Observe the policies:**
+    - Try asking the model to delete a directory: The policy engine will prompt
+      you for confirmation due to the `rm -rf` rule.
+    - Try asking the model to search for secrets: The `grep` rule will deny the
+      request and display the custom deny message.
+    - Any file write operation will now be processed through the `allowed-path`
+      safety checker.
+
+## Security note
+
+For security, Gemini CLI ignores any `allow` decisions or `yolo` mode
+configurations contributed by extensions. This ensures that extensions can
+strengthen security but cannot bypass user confirmation.

packages/cli/src/commands/extensions/examples/policies/gemini-extension.json

@@ -0,0 +1,5 @@
+{
+  "name": "policy-example",
+  "version": "1.0.0",
+  "description": "An example extension demonstrating Policy Engine support."
+}

packages/cli/src/commands/extensions/examples/policies/policies/policies.toml

@@ -0,0 +1,28 @@
+# Example Policy Rules for Gemini CLI Extension
+#
+# Extensions run in Tier 2 (Extension Tier).
+# Security Note: 'allow' decisions and 'yolo' mode configurations are ignored.
+
+# Rule: Always ask the user before running a specific dangerous shell command.
+[[rule]]
+toolName = "run_shell_command"
+commandPrefix = "rm -rf"
+decision = "ask_user"
+priority = 100
+
+# Rule: Deny access to sensitive files using the grep tool.
+[[rule]]
+toolName = "grep_search"
+argsPattern = "(\.env|id_rsa|passwd)"
+decision = "deny"
+priority = 200
+denyMessage = "Access to sensitive credentials or system files is restricted by the policy-example extension."
+
+# Safety Checker: Apply path validation to all write operations.
+[[safety_checker]]
+toolName = ["write_file", "replace"]
+priority = 300
+[safety_checker.checker]
+type = "in-process"
+name = "allowed-path"
+required_context = ["environment"]

packages/cli/src/commands/extensions/examples/skills/.gitignore

@@ -0,0 +1,26 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-error.log
+yarn-debug.log
+
+# Build output
+dist/
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# TypeScript
+*.tsbuildinfo
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDEs
+.vscode/
+.idea/

packages/cli/src/commands/extensions/examples/skills/gemini-extension.json

@@ -0,0 +1,4 @@
+{
+  "name": "skills-example",
+  "version": "1.0.0"
+}

packages/cli/src/commands/extensions/examples/skills/skills/greeter/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: greeter
+description: A friendly greeter skill
+---
+
+You are a friendly greeter. When the user says "hello" or asks for a greeting,
+you should reply with: "Greetings from the skills-example extension! 👋"

packages/cli/src/commands/extensions/examples/themes-example/README.md

@@ -0,0 +1,31 @@
+# Themes Example
+
+This is an example of a Gemini CLI extension that adds a custom theme.
+
+## How to use
+
+1.  Link this extension:
+
+    ```bash
+    gemini extensions link packages/cli/src/commands/extensions/examples/themes-example
+    ```
+
+2.  Set the theme in your settings file (`~/.gemini/settings.json`):
+
+    ```json
+    {
+      "ui": {
+        "theme": "shades-of-green (themes-example)"
+      }
+    }
+    ```
+
+    Alternatively, you can set it through the UI by running `gemini` and then
+    typing `/theme` and pressing Enter.
+
+3.  **Observe the Changes:**
+
+    After setting the theme, you should see the changes reflected in the Gemini
+    CLI's UI. The background will be a dark green, the primary text a lighter
+    green, and various other UI elements will display different shades of green,
+    as defined in this extension's `gemini-extension.json` file.

packages/cli/src/commands/extensions/examples/themes-example/gemini-extension.json

@@ -0,0 +1,29 @@
+{
+  "name": "themes-example",
+  "version": "1.0.0",
+  "themes": [
+    {
+      "name": "shades-of-green",
+      "type": "custom",
+      "background": {
+        "primary": "#1a362a"
+      },
+      "text": {
+        "primary": "#a6e3a1",
+        "secondary": "#6e8e7a",
+        "link": "#89e689"
+      },
+      "status": {
+        "success": "#76c076",
+        "warning": "#d9e689",
+        "error": "#b34e4e"
+      },
+      "border": {
+        "default": "#4a6c5a"
+      },
+      "ui": {
+        "comment": "#6e8e7a"
+      }
+    }
+  ]
+}

packages/cli/src/config/extensions/__snapshots__/consent.test.ts.snap

@@ -0,0 +1,106 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`consent > maybeRequestConsentOrFail > consent string generation > should generate a consent string with all fields 1`] = `
+"Installing extension "test-ext".
+This extension will run the following MCP servers:
+  * server1 (local): npm start
+    Config signature: 4fec6e8152e1eb7aa1a25665dde7964a218c1b60f801587e3c800f0d7fe5941a
+  * server2 (remote): https://remote.com
+    Config signature: 69391bfd3f62b97f9c7e944e9597ec5ba075838f8e29738f8adf0ba3eed35961
+This extension will append info to your gemini.md context using my-context.md
+This extension will exclude the following core tools: tool1,tool2
+
+The extension you are about to install may have been created by a third-party developer and sourced
+from a public repository. Google does not vet, endorse, or guarantee the functionality or security
+of extensions. Please carefully inspect any extension and its source code before installing to
+understand the permissions it requires and the actions it may perform."
+`;
+
+exports[`consent > maybeRequestConsentOrFail > consent string generation > should include warning when hooks are present 1`] = `
+"Installing extension "test-ext".
+⚠️  This extension contains Hooks which can automatically execute commands.
+
+The extension you are about to install may have been created by a third-party developer and sourced
+from a public repository. Google does not vet, endorse, or guarantee the functionality or security
+of extensions. Please carefully inspect any extension and its source code before installing to
+understand the permissions it requires and the actions it may perform."
+`;
+
+exports[`consent > maybeRequestConsentOrFail > consent string generation > should request consent if extension is migrated 1`] = `
+"Migrating extension "old-ext" to a new repository, renaming to "test-ext", and installing updates.
+
+The extension you are about to install may have been created by a third-party developer and sourced
+from a public repository. Google does not vet, endorse, or guarantee the functionality or security
+of extensions. Please carefully inspect any extension and its source code before installing to
+understand the permissions it requires and the actions it may perform."
+`;
+
+exports[`consent > maybeRequestConsentOrFail > consent string generation > should request consent if skills change 1`] = `
+"Installing extension "test-ext".
+This extension will run the following MCP servers:
+  * server1 (local): npm start
+    Config signature: 4fec6e8152e1eb7aa1a25665dde7964a218c1b60f801587e3c800f0d7fe5941a
+  * server2 (remote): https://remote.com
+    Config signature: 69391bfd3f62b97f9c7e944e9597ec5ba075838f8e29738f8adf0ba3eed35961
+This extension will append info to your gemini.md context using my-context.md
+This extension will exclude the following core tools: tool1,tool2
+
+Agent Skills:
+
+This extension will install the following agent skills:
+
+  * skill1: desc1
+    (Source: /mock/temp/dir/skill1/SKILL.md) (2 items in directory)
+
+  * skill2: desc2
+    (Source: /mock/temp/dir/skill2/SKILL.md) (1 items in directory)
+
+
+The extension you are about to install may have been created by a third-party developer and sourced
+from a public repository. Google does not vet, endorse, or guarantee the functionality or security
+of extensions. Please carefully inspect any extension and its source code before installing to
+understand the permissions it requires and the actions it may perform.
+
+Agent skills inject specialized instructions and domain-specific knowledge into the agent's system
+prompt. This can change how the agent interprets your requests and interacts with your environment.
+Review the skill definitions at the location(s) provided below to ensure they meet your security
+standards."
+`;
+
+exports[`consent > maybeRequestConsentOrFail > consent string generation > should show a warning if the skill directory cannot be read 1`] = `
+"Installing extension "test-ext".
+
+Agent Skills:
+
+This extension will install the following agent skills:
+
+  * locked-skill: A skill in a locked dir
+    (Source: /mock/temp/dir/locked/SKILL.md) ⚠️ (Could not count items in directory)
+
+
+The extension you are about to install may have been created by a third-party developer and sourced
+from a public repository. Google does not vet, endorse, or guarantee the functionality or security
+of extensions. Please carefully inspect any extension and its source code before installing to
+understand the permissions it requires and the actions it may perform.
+
+Agent skills inject specialized instructions and domain-specific knowledge into the agent's system
+prompt. This can change how the agent interprets your requests and interacts with your environment.
+Review the skill definitions at the location(s) provided below to ensure they meet your security
+standards."
+`;
+
+exports[`consent > skillsConsentString > should generate a consent string for skills 1`] = `
+"Installing agent skill(s) from "https://example.com/repo.git".
+
+The following agent skill(s) will be installing:
+
+  * skill1: desc1
+    (Source: /mock/temp/dir/skill1/SKILL.md) (1 items in directory)
+
+Install Destination: /mock/target/dir
+
+Agent skills inject specialized instructions and domain-specific knowledge into the agent's system
+prompt. This can change how the agent interprets your requests and interacts with your environment.
+Review the skill definitions at the location(s) provided below to ensure they meet your security
+standards."
+`;

packages/cli/src/config/extensions/consent.test.ts

@@ -0,0 +1,563 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from 'react';
+import { Text } from 'ink';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { render, cleanup } from '../../test-utils/render.js';
+import {
+  requestConsentNonInteractive,
+  requestConsentInteractive,
+  maybeRequestConsentOrFail,
+} from './consent.js';
+import type { ConfirmationRequest } from '../../ui/types.js';
+import type { ExtensionConfig } from '../extension.js';
+import { debugLogger, type SkillDefinition } from '@google/gemini-cli-core';
+
+const mockReadline = vi.hoisted(() => ({
+  createInterface: vi.fn().mockReturnValue({
+    question: vi.fn(),
+    close: vi.fn(),
+  }),
+}));
+
+const mockReaddir = vi.hoisted(() => vi.fn());
+const originalReaddir = vi.hoisted(() => ({
+  current: null as typeof fs.readdir | null,
+}));
+
+// Mocking readline for non-interactive prompts
+vi.mock('node:readline', () => ({
+  default: mockReadline,
+  createInterface: mockReadline.createInterface,
+}));
+
+vi.mock('node:fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs/promises')>();
+  originalReaddir.current = actual.readdir;
+  return {
+    ...actual,
+    readdir: mockReaddir,
+  };
+});
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    debugLogger: {
+      log: vi.fn(),
+    },
+  };
+});
+
+async function expectConsentSnapshot(consentString: string) {
+  const renderResult = await render(
+    React.createElement(Text, null, consentString),
+  );
+  await expect(renderResult).toMatchSvgSnapshot();
+}
+
+/**
+ * Normalizes a consent string for snapshot testing by:
+ * 1. Replacing the dynamic temp directory path with a static placeholder.
+ * 2. Converting Windows backslashes to forward slashes for platform-agnosticism.
+ */
+function normalizePathsForSnapshot(str: string, tempDir: string): string {
+  return str.replaceAll(tempDir, '/mock/temp/dir').replaceAll('\\', '/');
+}
+
+describe('consent', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    if (originalReaddir.current) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      mockReaddir.mockImplementation(originalReaddir.current as any);
+    }
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'consent-test-'));
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    if (tempDir) {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    }
+    cleanup();
+  });
+
+  describe('requestConsentNonInteractive', () => {
+    it.each([
+      { input: 'y', expected: true },
+      { input: 'Y', expected: true },
+      { input: '', expected: true },
+      { input: 'n', expected: false },
+      { input: 'N', expected: false },
+      { input: 'yes', expected: true },
+    ])(
+      'should return $expected for input "$input"',
+      async ({ input, expected }) => {
+        const questionMock = vi.fn().mockImplementation((_, callback) => {
+          callback(input);
+        });
+        mockReadline.createInterface.mockReturnValue({
+          question: questionMock,
+          close: vi.fn(),
+        });
+
+        const consent = await requestConsentNonInteractive('Test consent');
+        expect(debugLogger.log).toHaveBeenCalledWith('Test consent');
+        expect(questionMock).toHaveBeenCalledWith(
+          'Do you want to continue? [Y/n]: ',
+          expect.any(Function),
+        );
+        expect(consent).toBe(expected);
+      },
+    );
+  });
+
+  describe('requestConsentInteractive', () => {
+    it.each([
+      { confirmed: true, expected: true },
+      { confirmed: false, expected: false },
+    ])(
+      'should resolve with $expected when user confirms with $confirmed',
+      async ({ confirmed, expected }) => {
+        const addExtensionUpdateConfirmationRequest = vi
+          .fn()
+          .mockImplementation((request: ConfirmationRequest) => {
+            request.onConfirm(confirmed);
+          });
+
+        const consent = await requestConsentInteractive(
+          'Test consent',
+          addExtensionUpdateConfirmationRequest,
+        );
+
+        expect(addExtensionUpdateConfirmationRequest).toHaveBeenCalledWith({
+          prompt: 'Test consent\n\nDo you want to continue?',
+          onConfirm: expect.any(Function),
+        });
+        expect(consent).toBe(expected);
+      },
+    );
+
+    it('should clear the active confirmation request before resolving', async () => {
+      const clearConfirmationRequest = vi.fn();
+      const steps: string[] = [];
+      const addExtensionUpdateConfirmationRequest = vi
+        .fn()
+        .mockImplementation((request: ConfirmationRequest) => {
+          steps.push('prompted');
+          request.onConfirm(true);
+          steps.push('confirmed');
+        });
+
+      const consentPromise = requestConsentInteractive(
+        'Test consent',
+        addExtensionUpdateConfirmationRequest,
+        () => {
+          steps.push('cleared');
+          clearConfirmationRequest();
+        },
+      ).then((consent) => {
+        steps.push('resolved');
+        return consent;
+      });
+
+      expect(clearConfirmationRequest).toHaveBeenCalledTimes(1);
+      expect(steps).toEqual(['prompted', 'cleared', 'confirmed']);
+      await expect(consentPromise).resolves.toBe(true);
+      expect(steps).toEqual(['prompted', 'cleared', 'confirmed', 'resolved']);
+    });
+  });
+
+  describe('maybeRequestConsentOrFail', () => {
+    const baseConfig: ExtensionConfig = {
+      name: 'test-ext',
+      version: '1.0.0',
+    };
+
+    it('should request consent if there is no previous config', async () => {
+      const requestConsent = vi.fn().mockResolvedValue(true);
+      await maybeRequestConsentOrFail(
+        baseConfig,
+        requestConsent,
+        false,
+        undefined,
+      );
+      expect(requestConsent).toHaveBeenCalledTimes(1);
+    });
+
+    it('should not request consent if configs are identical', async () => {
+      const requestConsent = vi.fn().mockResolvedValue(true);
+      await maybeRequestConsentOrFail(
+        baseConfig,
+        requestConsent,
+        false,
+        baseConfig,
+        false,
+      );
+      expect(requestConsent).not.toHaveBeenCalled();
+    });
+
+    it('should throw an error if consent is denied', async () => {
+      const requestConsent = vi.fn().mockResolvedValue(false);
+      await expect(
+        maybeRequestConsentOrFail(baseConfig, requestConsent, false, undefined),
+      ).rejects.toThrow('Installation cancelled for "test-ext".');
+    });
+
+    describe('consent string generation', () => {
+      it('should generate a consent string with all fields', async () => {
+        const config: ExtensionConfig = {
+          ...baseConfig,
+          mcpServers: {
+            server1: { command: 'npm', args: ['start'] },
+            server2: { httpUrl: 'https://remote.com' },
+          },
+          contextFileName: 'my-context.md',
+          excludeTools: ['tool1', 'tool2'],
+        };
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          config,
+          requestConsent,
+          false,
+          undefined,
+        );
+
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+        const consentString = requestConsent.mock.calls[0][0] as string;
+        await expectConsentSnapshot(consentString);
+      });
+
+      it('should sort environment variables alphabetically and handle undefined envValue', async () => {
+        const config: ExtensionConfig = {
+          ...baseConfig,
+          mcpServers: {
+            server1: {
+              command: 'node',
+              args: ['server.js'],
+              env: {
+                VAR_B: 'b',
+                VAR_A: 'a',
+                VAR_C: undefined as unknown as string,
+              },
+            },
+          },
+        };
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          config,
+          requestConsent,
+          false,
+          undefined,
+        );
+
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+        const consentString = requestConsent.mock.calls[0][0] as string;
+        expect(consentString).toContain('      - VAR_A: a');
+        expect(consentString).toContain('      - VAR_B: b');
+        expect(consentString).toContain('      - VAR_C: ');
+
+        const posA = consentString.indexOf('      - VAR_A: a');
+        const posB = consentString.indexOf('      - VAR_B: b');
+        const posC = consentString.indexOf('      - VAR_C: ');
+        expect(posA).toBeLessThan(posB);
+        expect(posB).toBeLessThan(posC);
+      });
+
+      it('should mask sensitive environment variables, headers, and OAuth parameters', async () => {
+        const config: ExtensionConfig = {
+          ...baseConfig,
+          mcpServers: {
+            server1: {
+              command: 'node',
+              args: ['server.js'],
+              env: {
+                SAFE_VAR: 'safe-value',
+                SUPER_TOKEN: 'secret-token-123',
+                DB_PASSWORD: 'my-password',
+              },
+              headers: {
+                'X-API-Key': 'some-api-key',
+                Authorization: 'Bearer 12345',
+                'Content-Type': 'application/json',
+              },
+              oauth: {
+                clientId: 'my-client-id',
+                clientSecret: 'secret-oauth-value',
+              },
+            },
+          },
+        };
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          config,
+          requestConsent,
+          false,
+          undefined,
+        );
+
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+        const consentString = requestConsent.mock.calls[0][0] as string;
+
+        // Assert sensitive env values are masked
+        expect(consentString).toContain('      - SAFE_VAR: safe-value');
+        expect(consentString).toContain('      - SUPER_TOKEN: ********');
+        expect(consentString).toContain('      - DB_PASSWORD: ********');
+
+        // Assert sensitive headers are masked
+        expect(consentString).toContain(
+          '      - Content-Type: application/json',
+        );
+        expect(consentString).toContain('      - Authorization: ********');
+        expect(consentString).toContain('      - X-API-Key: ********');
+
+        // Assert sensitive OAuth parameters are masked
+        expect(consentString).toContain('      - clientId: my-client-id');
+        expect(consentString).toContain('      - clientSecret: ********');
+      });
+
+      it('should request consent if mcpServers change', async () => {
+        const prevConfig: ExtensionConfig = { ...baseConfig };
+        const newConfig: ExtensionConfig = {
+          ...baseConfig,
+          mcpServers: { server1: { command: 'npm', args: ['start'] } },
+        };
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          newConfig,
+          requestConsent,
+          false,
+          prevConfig,
+          false,
+        );
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+      });
+
+      it('should request consent if mcpServer env changes', async () => {
+        const prevConfig: ExtensionConfig = {
+          ...baseConfig,
+          mcpServers: {
+            server1: { command: 'node', args: ['server.js'] },
+          },
+        };
+        const newConfig: ExtensionConfig = {
+          ...baseConfig,
+          mcpServers: {
+            server1: {
+              command: 'node',
+              args: ['server.js'],
+              env: { NODE_OPTIONS: '--require=./payload.js' },
+            },
+          },
+        };
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          newConfig,
+          requestConsent,
+          false,
+          prevConfig,
+          false,
+        );
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+      });
+
+      it('should request consent if contextFileName changes', async () => {
+        const prevConfig: ExtensionConfig = { ...baseConfig };
+        const newConfig: ExtensionConfig = {
+          ...baseConfig,
+          contextFileName: 'new-context.md',
+        };
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          newConfig,
+          requestConsent,
+          false,
+          prevConfig,
+          false,
+        );
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+      });
+
+      it('should request consent if excludeTools changes', async () => {
+        const prevConfig: ExtensionConfig = { ...baseConfig };
+        const newConfig: ExtensionConfig = {
+          ...baseConfig,
+          excludeTools: ['new-tool'],
+        };
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          newConfig,
+          requestConsent,
+          false,
+          prevConfig,
+          false,
+        );
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+      });
+
+      it('should include warning when hooks are present', async () => {
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          baseConfig,
+          requestConsent,
+          true,
+          undefined,
+        );
+
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+        const consentString = requestConsent.mock.calls[0][0] as string;
+        await expectConsentSnapshot(consentString);
+      });
+
+      it('should request consent if hooks status changes', async () => {
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          baseConfig,
+          requestConsent,
+          true,
+          baseConfig,
+          false,
+        );
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+      });
+
+      it('should request consent if extension is migrated', async () => {
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          baseConfig,
+          requestConsent,
+          false,
+          { ...baseConfig, name: 'old-ext' },
+          false,
+          [],
+          [],
+          true,
+        );
+
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+        let consentString = requestConsent.mock.calls[0][0] as string;
+        consentString = normalizePathsForSnapshot(consentString, tempDir);
+        await expectConsentSnapshot(consentString);
+      });
+
+      it('should request consent if skills change', async () => {
+        const skill1Dir = path.join(tempDir, 'skill1');
+        const skill2Dir = path.join(tempDir, 'skill2');
+        await fs.mkdir(skill1Dir, { recursive: true });
+        await fs.mkdir(skill2Dir, { recursive: true });
+        await fs.writeFile(path.join(skill1Dir, 'SKILL.md'), 'body1');
+        await fs.writeFile(path.join(skill1Dir, 'extra.txt'), 'extra');
+        await fs.writeFile(path.join(skill2Dir, 'SKILL.md'), 'body2');
+
+        const skill1: SkillDefinition = {
+          name: 'skill1',
+          description: 'desc1',
+          location: path.join(skill1Dir, 'SKILL.md'),
+          body: 'body1',
+        };
+        const skill2: SkillDefinition = {
+          name: 'skill2',
+          description: 'desc2',
+          location: path.join(skill2Dir, 'SKILL.md'),
+          body: 'body2',
+        };
+
+        const config: ExtensionConfig = {
+          ...baseConfig,
+          mcpServers: {
+            server1: { command: 'npm', args: ['start'] },
+            server2: { httpUrl: 'https://remote.com' },
+          },
+          contextFileName: 'my-context.md',
+          excludeTools: ['tool1', 'tool2'],
+        };
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          config,
+          requestConsent,
+          false,
+          undefined,
+          false,
+          [skill1, skill2],
+        );
+
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+        let consentString = requestConsent.mock.calls[0][0] as string;
+        consentString = normalizePathsForSnapshot(consentString, tempDir);
+        await expectConsentSnapshot(consentString);
+      });
+
+      it('should show a warning if the skill directory cannot be read', async () => {
+        const lockedDir = path.join(tempDir, 'locked');
+        await fs.mkdir(lockedDir, { recursive: true });
+
+        const skill: SkillDefinition = {
+          name: 'locked-skill',
+          description: 'A skill in a locked dir',
+          location: path.join(lockedDir, 'SKILL.md'),
+          body: 'body',
+        };
+
+        // Mock readdir to simulate a permission error.
+        // We do this instead of using fs.mkdir(..., { mode: 0o000 }) because
+        // directory permissions work differently on Windows and 0o000 doesn't
+        // effectively block access there, leading to test failures in Windows CI.
+        mockReaddir.mockRejectedValueOnce(
+          new Error('EACCES: permission denied, scandir'),
+        );
+
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          baseConfig,
+          requestConsent,
+          false,
+          undefined,
+          false,
+          [skill],
+        );
+
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+        let consentString = requestConsent.mock.calls[0][0] as string;
+        consentString = normalizePathsForSnapshot(consentString, tempDir);
+        await expectConsentSnapshot(consentString);
+      });
+    });
+  });
+
+  describe('skillsConsentString', () => {
+    it('should generate a consent string for skills', async () => {
+      const skill1Dir = path.join(tempDir, 'skill1');
+      await fs.mkdir(skill1Dir, { recursive: true });
+      await fs.writeFile(path.join(skill1Dir, 'SKILL.md'), 'body1');
+
+      const skill1: SkillDefinition = {
+        name: 'skill1',
+        description: 'desc1',
+        location: path.join(skill1Dir, 'SKILL.md'),
+        body: 'body1',
+      };
+
+      const { skillsConsentString } = await import('./consent.js');
+      let consentString = await skillsConsentString(
+        [skill1],
+        'https://example.com/repo.git',
+        '/mock/target/dir',
+      );
+
+      consentString = normalizePathsForSnapshot(consentString, tempDir);
+      await expectConsentSnapshot(consentString);
+    });
+  });
+});

packages/cli/src/config/extensions/consent.ts

@@ -0,0 +1,399 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import {
+  debugLogger,
+  type SkillDefinition,
+  type MCPServerConfig,
+} from '@google/gemini-cli-core';
+import chalk from 'chalk';
+
+import type { ConfirmationRequest } from '../../ui/types.js';
+import { escapeAnsiCtrlCodes } from '../../ui/utils/textUtils.js';
+import type { ExtensionConfig } from '../extension.js';
+
+export const INSTALL_WARNING_MESSAGE = chalk.yellow(
+  'The extension you are about to install may have been created by a third-party developer and sourced from a public repository. Google does not vet, endorse, or guarantee the functionality or security of extensions. Please carefully inspect any extension and its source code before installing to understand the permissions it requires and the actions it may perform.',
+);
+
+export const SKILLS_WARNING_MESSAGE = chalk.yellow(
+  "Agent skills inject specialized instructions and domain-specific knowledge into the agent's system prompt. This can change how the agent interprets your requests and interacts with your environment. Review the skill definitions at the location(s) provided below to ensure they meet your security standards.",
+);
+
+/**
+ * Builds a consent string for installing agent skills.
+ */
+export async function skillsConsentString(
+  skills: SkillDefinition[],
+  source: string,
+  targetDir?: string,
+  isLink = false,
+): Promise<string> {
+  const action = isLink ? 'Linking' : 'Installing';
+  const output: string[] = [];
+  output.push(`${action} agent skill(s) from "${source}".`);
+  output.push(
+    `\nThe following agent skill(s) will be ${action.toLowerCase()}:\n`,
+  );
+  output.push(...(await renderSkillsList(skills)));
+
+  if (targetDir) {
+    const destLabel = isLink ? 'Link' : 'Install';
+    output.push(`${destLabel} Destination: ${targetDir}`);
+  }
+  output.push('\n' + SKILLS_WARNING_MESSAGE);
+
+  return output.join('\n');
+}
+
+/**
+ * Requests consent from the user to perform an action, by reading a Y/n
+ * character from stdin.
+ *
+ * This should not be called from interactive mode as it will break the CLI.
+ *
+ * @param consentDescription The description of the thing they will be consenting to.
+ * @returns boolean, whether they consented or not.
+ */
+export async function requestConsentNonInteractive(
+  consentDescription: string,
+): Promise<boolean> {
+  debugLogger.log(consentDescription);
+  const result = await promptForConsentNonInteractive(
+    'Do you want to continue? [Y/n]: ',
+  );
+  return result;
+}
+
+/**
+ * Requests consent from the user to perform an action, in interactive mode.
+ *
+ * This should not be called from non-interactive mode as it will not work.
+ *
+ * @param consentDescription The description of the thing they will be consenting to.
+ * @param addExtensionUpdateConfirmationRequest A function to actually add a prompt to the UI.
+ * @returns boolean, whether they consented or not.
+ */
+export async function requestConsentInteractive(
+  consentDescription: string,
+  addExtensionUpdateConfirmationRequest: (value: ConfirmationRequest) => void,
+  clearConfirmationRequest?: () => void,
+): Promise<boolean> {
+  return promptForConsentInteractive(
+    consentDescription + '\n\nDo you want to continue?',
+    addExtensionUpdateConfirmationRequest,
+    clearConfirmationRequest,
+  );
+}
+
+/**
+ * Asks users a prompt and awaits for a y/n response on stdin.
+ *
+ * This should not be called from interactive mode as it will break the CLI.
+ *
+ * @param prompt A yes/no prompt to ask the user
+ * @param defaultValue Whether to resolve as true or false on enter.
+ * @returns Whether or not the user answers 'y' (yes).
+ */
+export async function promptForConsentNonInteractive(
+  prompt: string,
+  defaultValue = true,
+): Promise<boolean> {
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      const trimmedAnswer = answer.trim().toLowerCase();
+      if (trimmedAnswer === '') {
+        resolve(defaultValue);
+      } else {
+        resolve(['y', 'yes'].includes(trimmedAnswer));
+      }
+    });
+  });
+}
+
+/**
+ * Asks users an interactive yes/no prompt.
+ *
+ * This should not be called from non-interactive mode as it will break the CLI.
+ *
+ * @param prompt A markdown prompt to ask the user
+ * @param addExtensionUpdateConfirmationRequest Function to update the UI state with the confirmation request.
+ * @returns Whether or not the user answers yes.
+ */
+async function promptForConsentInteractive(
+  prompt: string,
+  addExtensionUpdateConfirmationRequest: (value: ConfirmationRequest) => void,
+  clearConfirmationRequest?: () => void,
+): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    addExtensionUpdateConfirmationRequest({
+      prompt,
+      onConfirm: (resolvedConfirmed) => {
+        clearConfirmationRequest?.();
+        setImmediate(() => resolve(resolvedConfirmed));
+      },
+    });
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Helper to generate a deterministic canonical hash of an MCPServerConfig object.
+ * Excludes circular or complex fields like extension.
+ */
+function getMcpServerConfigHash(mcpServer: MCPServerConfig): string {
+  const plainMcpServer: Record<string, unknown> = isRecord(mcpServer)
+    ? mcpServer
+    : {};
+  const copy = { ...plainMcpServer };
+  delete copy['extension'];
+
+  const canonicalString = JSON.stringify(copy, (key, value) => {
+    if (value instanceof RegExp) {
+      return value.toString();
+    }
+    if (isRecord(value)) {
+      return Object.keys(value)
+        .sort()
+        .reduce((result: Record<string, unknown>, k) => {
+          result[k] = value[k];
+          return result;
+        }, {});
+    }
+    return value as unknown;
+  });
+
+  return crypto.createHash('sha256').update(canonicalString).digest('hex');
+}
+
+/**
+ * Builds a consent string for installing an extension based on it's
+ * extensionConfig.
+ */
+async function extensionConsentString(
+  extensionConfig: ExtensionConfig,
+  hasHooks: boolean,
+  skills: SkillDefinition[] = [],
+  previousName?: string,
+  wasMigrated?: boolean,
+): Promise<string> {
+  const sanitizedConfig = escapeAnsiCtrlCodes(extensionConfig);
+  const output: string[] = [];
+  const mcpServerEntries = Object.entries(sanitizedConfig.mcpServers || {});
+
+  if (wasMigrated) {
+    if (previousName && previousName !== sanitizedConfig.name) {
+      output.push(
+        `Migrating extension "${previousName}" to a new repository, renaming to "${sanitizedConfig.name}", and installing updates.`,
+      );
+    } else {
+      output.push(
+        `Migrating extension "${sanitizedConfig.name}" to a new repository and installing updates.`,
+      );
+    }
+  } else if (previousName && previousName !== sanitizedConfig.name) {
+    output.push(
+      `Renaming extension "${previousName}" to "${sanitizedConfig.name}" and installing updates.`,
+    );
+  } else {
+    output.push(`Installing extension "${sanitizedConfig.name}".`);
+  }
+
+  if (mcpServerEntries.length) {
+    output.push('This extension will run the following MCP servers:');
+    for (const [key, mcpServer] of mcpServerEntries) {
+      const isLocal = !!mcpServer.command;
+      const source =
+        mcpServer.httpUrl ??
+        `${mcpServer.command || ''}${mcpServer.args ? ' ' + mcpServer.args.join(' ') : ''}`;
+      output.push(`  * ${key} (${isLocal ? 'local' : 'remote'}): ${source}`);
+      if (mcpServer.cwd) {
+        output.push(`    Working directory: ${mcpServer.cwd}`);
+      }
+      if (mcpServer.env && Object.keys(mcpServer.env).length > 0) {
+        output.push('    Environment variables:');
+        const sortedEnv = Object.entries(mcpServer.env).sort(([a], [b]) =>
+          a.localeCompare(b),
+        );
+        for (const [envKey, envValue] of sortedEnv) {
+          const isSensitive =
+            /token|secret|password|passwd|key|auth|credential|creds|private|cert/i.test(
+              envKey,
+            );
+          const displayValue =
+            isSensitive && envValue ? '********' : (envValue ?? '');
+          output.push(`      - ${envKey}: ${displayValue}`);
+        }
+      }
+      if (mcpServer.headers && Object.keys(mcpServer.headers).length > 0) {
+        output.push('    Headers:');
+        const sortedHeaders = Object.entries(mcpServer.headers).sort(
+          ([a], [b]) => a.localeCompare(b),
+        );
+        for (const [headerKey, headerValue] of sortedHeaders) {
+          const isSensitive = /authorization|key|cookie|token|secret/i.test(
+            headerKey,
+          );
+          const displayValue =
+            isSensitive && headerValue ? '********' : (headerValue ?? '');
+          output.push(`      - ${headerKey}: ${displayValue}`);
+        }
+      }
+      if (mcpServer.url) {
+        output.push(`    URL: ${mcpServer.url}`);
+      }
+      if (mcpServer.tcp) {
+        output.push(`    TCP: ${mcpServer.tcp}`);
+      }
+      if (mcpServer.type) {
+        output.push(`    Type: ${mcpServer.type}`);
+      }
+      if (mcpServer.timeout !== undefined) {
+        output.push(`    Timeout: ${mcpServer.timeout}`);
+      }
+      if (mcpServer.trust !== undefined) {
+        output.push(`    Trust: ${mcpServer.trust}`);
+      }
+      if (mcpServer.description) {
+        output.push(`    Description: ${mcpServer.description}`);
+      }
+      if (mcpServer.includeTools && mcpServer.includeTools.length > 0) {
+        output.push(`    Include tools: ${mcpServer.includeTools.join(', ')}`);
+      }
+      if (mcpServer.excludeTools && mcpServer.excludeTools.length > 0) {
+        output.push(`    Exclude tools: ${mcpServer.excludeTools.join(', ')}`);
+      }
+      if (mcpServer.authProviderType) {
+        output.push(`    Auth Provider Type: ${mcpServer.authProviderType}`);
+      }
+      if (mcpServer.targetAudience) {
+        output.push(`    Target Audience: ${mcpServer.targetAudience}`);
+      }
+      if (mcpServer.targetServiceAccount) {
+        output.push(
+          `    Target Service Account: ${mcpServer.targetServiceAccount}`,
+        );
+      }
+      if (mcpServer.oauth) {
+        output.push('    OAuth Configuration:');
+        const sortedOauth = Object.entries(mcpServer.oauth).sort(([a], [b]) =>
+          a.localeCompare(b),
+        );
+        for (const [oKey, oValue] of sortedOauth) {
+          const isSensitive = /secret|token|password/i.test(oKey);
+          const valStr = Array.isArray(oValue)
+            ? oValue.join(', ')
+            : String(oValue ?? '');
+          const displayValue = isSensitive && valStr ? '********' : valStr;
+          output.push(`      - ${oKey}: ${displayValue}`);
+        }
+      }
+      output.push(`    Config signature: ${getMcpServerConfigHash(mcpServer)}`);
+    }
+  }
+  if (sanitizedConfig.contextFileName) {
+    output.push(
+      `This extension will append info to your gemini.md context using ${sanitizedConfig.contextFileName}`,
+    );
+  }
+  if (sanitizedConfig.excludeTools) {
+    output.push(
+      `This extension will exclude the following core tools: ${sanitizedConfig.excludeTools}`,
+    );
+  }
+  if (hasHooks) {
+    output.push(
+      '⚠️  This extension contains Hooks which can automatically execute commands.',
+    );
+  }
+  if (skills.length > 0) {
+    output.push(`\n${chalk.bold('Agent Skills:')}`);
+    output.push('\nThis extension will install the following agent skills:\n');
+    output.push(...(await renderSkillsList(skills)));
+  }
+
+  output.push('\n' + INSTALL_WARNING_MESSAGE);
+  if (skills.length > 0) {
+    output.push('\n' + SKILLS_WARNING_MESSAGE);
+  }
+
+  return output.join('\n');
+}
+
+/**
+ * Shared logic for formatting a list of agent skills for a consent prompt.
+ */
+async function renderSkillsList(skills: SkillDefinition[]): Promise<string[]> {
+  const output: string[] = [];
+  for (const skill of skills) {
+    output.push(`  * ${chalk.bold(skill.name)}: ${skill.description}`);
+    const skillDir = path.dirname(skill.location);
+    let fileCountStr = '';
+    try {
+      const skillDirItems = await fs.readdir(skillDir);
+      fileCountStr = ` (${skillDirItems.length} items in directory)`;
+    } catch {
+      fileCountStr = ` ${chalk.red('⚠️ (Could not count items in directory)')}`;
+    }
+    output.push(chalk.dim(`    (Source: ${skill.location})${fileCountStr}`));
+    output.push('');
+  }
+  return output;
+}
+
+/**
+ * Requests consent from the user to install an extension (extensionConfig), if
+ * there is any difference between the consent string for `extensionConfig` and
+ * `previousExtensionConfig`.
+ *
+ * Always requests consent if previousExtensionConfig is null.
+ *
+ * Throws if the user does not consent.
+ */
+export async function maybeRequestConsentOrFail(
+  extensionConfig: ExtensionConfig,
+  requestConsent: (consent: string) => Promise<boolean>,
+  hasHooks: boolean,
+  previousExtensionConfig?: ExtensionConfig,
+  previousHasHooks?: boolean,
+  skills: SkillDefinition[] = [],
+  previousSkills: SkillDefinition[] = [],
+  isMigrating: boolean = false,
+) {
+  const extensionConsent = await extensionConsentString(
+    extensionConfig,
+    hasHooks,
+    skills,
+    previousExtensionConfig?.name,
+    isMigrating,
+  );
+  if (previousExtensionConfig) {
+    const previousExtensionConsent = await extensionConsentString(
+      previousExtensionConfig,
+      previousHasHooks ?? false,
+      previousSkills,
+    );
+    if (previousExtensionConsent === extensionConsent) {
+      return;
+    }
+  }
+  if (!(await requestConsent(extensionConsent))) {
+    throw new Error(`Installation cancelled for "${extensionConfig.name}".`);
+  }
+}

packages/cli/src/config/extensions/extensionEnablement.test.ts

@@ -0,0 +1,534 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as path from 'node:path';
+import fs from 'node:fs';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ExtensionEnablementManager, Override } from './extensionEnablement.js';
+
+import { ExtensionStorage } from './storage.js';
+
+vi.mock('./storage.js');
+
+import {
+  coreEvents,
+  GEMINI_DIR,
+  type GeminiCLIExtension,
+} from '@google/gemini-cli-core';
+
+vi.mock('node:os', () => ({
+  homedir: vi.fn().mockReturnValue('/virtual-home'),
+  tmpdir: vi.fn().mockReturnValue('/virtual-tmp'),
+}));
+
+const inMemoryFs: { [key: string]: string } = {};
+
+// Helper to create a temporary directory for testing
+function createTestDir() {
+  const dirPath = `/virtual-tmp/gemini-test-${Math.random().toString(36).substring(2, 15)}`;
+  inMemoryFs[dirPath] = ''; // Simulate directory existence
+  return {
+    path: dirPath,
+    cleanup: () => {
+      for (const key in inMemoryFs) {
+        if (key.startsWith(dirPath)) {
+          delete inMemoryFs[key];
+        }
+      }
+    },
+  };
+}
+
+let testDir: { path: string; cleanup: () => void };
+let manager: ExtensionEnablementManager;
+
+describe('ExtensionEnablementManager', () => {
+  beforeEach(() => {
+    // Clear the in-memory file system before each test
+    for (const key in inMemoryFs) {
+      delete inMemoryFs[key];
+    }
+    expect(Object.keys(inMemoryFs).length).toBe(0); // Add this assertion
+
+    // Mock fs functions
+    vi.spyOn(fs, 'readFileSync').mockImplementation(
+      (path: fs.PathOrFileDescriptor) => {
+        const content = inMemoryFs[path.toString()];
+        if (content === undefined) {
+          const error = new Error(
+            `ENOENT: no such file or directory, open '${path}'`,
+          );
+          (error as NodeJS.ErrnoException).code = 'ENOENT';
+          throw error;
+        }
+        return content;
+      },
+    );
+    vi.spyOn(fs, 'writeFileSync').mockImplementation(
+      (
+        path: fs.PathOrFileDescriptor,
+        data: string | NodeJS.ArrayBufferView,
+      ) => {
+        inMemoryFs[path.toString()] = data.toString(); // Convert ArrayBufferView to string for inMemoryFs
+      },
+    );
+    vi.spyOn(fs, 'mkdirSync').mockImplementation(
+      (
+        _path: fs.PathLike,
+        _options?: fs.MakeDirectoryOptions | fs.Mode | null,
+      ) => undefined,
+    );
+    vi.spyOn(fs, 'mkdtempSync').mockImplementation((prefix: string) => {
+      const virtualPath = `/virtual-tmp/${prefix.replace(/[^a-zA-Z0-9]/g, '')}`;
+      return virtualPath;
+    });
+    vi.spyOn(fs, 'rmSync').mockImplementation(() => {});
+
+    testDir = createTestDir();
+    vi.mocked(ExtensionStorage.getUserExtensionsDir).mockReturnValue(
+      path.join(testDir.path, GEMINI_DIR),
+    );
+    manager = new ExtensionEnablementManager();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    // Reset the singleton instance for test isolation
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (ExtensionEnablementManager as any).instance = undefined;
+  });
+
+  describe('isEnabled', () => {
+    it('should return true if extension is not configured', () => {
+      expect(manager.isEnabled('ext-test', '/any/path')).toBe(true);
+    });
+
+    it('should return true if no overrides match', () => {
+      manager.disable('ext-test', false, '/another/path');
+      expect(manager.isEnabled('ext-test', '/any/path')).toBe(true);
+    });
+
+    it('should enable a path based on an override rule', () => {
+      manager.disable('ext-test', true, '/');
+      manager.enable('ext-test', true, '/home/user/projects/');
+      expect(manager.isEnabled('ext-test', '/home/user/projects/my-app')).toBe(
+        true,
+      );
+    });
+
+    it('should disable a path based on a disable override rule', () => {
+      manager.enable('ext-test', true, '/');
+      manager.disable('ext-test', true, '/home/user/projects/');
+      expect(manager.isEnabled('ext-test', '/home/user/projects/my-app')).toBe(
+        false,
+      );
+    });
+
+    it('should respect the last matching rule (enable wins)', () => {
+      manager.disable('ext-test', true, '/home/user/projects/');
+      manager.enable('ext-test', false, '/home/user/projects/my-app');
+      expect(manager.isEnabled('ext-test', '/home/user/projects/my-app')).toBe(
+        true,
+      );
+    });
+
+    it('should respect the last matching rule (disable wins)', () => {
+      manager.enable('ext-test', true, '/home/user/projects/');
+      manager.disable('ext-test', false, '/home/user/projects/my-app');
+      expect(manager.isEnabled('ext-test', '/home/user/projects/my-app')).toBe(
+        false,
+      );
+    });
+
+    it('should handle overlapping rules correctly', () => {
+      manager.enable('ext-test', true, '/home/user/projects');
+      manager.disable('ext-test', false, '/home/user/projects/my-app');
+      expect(manager.isEnabled('ext-test', '/home/user/projects/my-app')).toBe(
+        false,
+      );
+      expect(
+        manager.isEnabled('ext-test', '/home/user/projects/something-else'),
+      ).toBe(true);
+    });
+  });
+
+  describe('remove', () => {
+    it('should remove an extension from the config', () => {
+      manager.enable('ext-test', true, '/path/to/dir');
+      const config = manager.readConfig();
+      expect(config['ext-test']).toBeDefined();
+
+      manager.remove('ext-test');
+      const newConfig = manager.readConfig();
+      expect(newConfig['ext-test']).toBeUndefined();
+    });
+
+    it('should not throw when removing a non-existent extension', () => {
+      const config = manager.readConfig();
+      expect(config['ext-test']).toBeUndefined();
+      expect(() => manager.remove('ext-test')).not.toThrow();
+    });
+  });
+
+  describe('readConfig', () => {
+    it('should return an empty object if the config file is corrupted', () => {
+      const configPath = path.join(
+        testDir.path,
+        GEMINI_DIR,
+        'extension-enablement.json',
+      );
+      fs.mkdirSync(path.dirname(configPath), { recursive: true });
+      fs.writeFileSync(configPath, 'not a json');
+      const config = manager.readConfig();
+      expect(config).toEqual({});
+    });
+
+    it('should return an empty object on generic read error', () => {
+      vi.spyOn(fs, 'readFileSync').mockImplementation(() => {
+        throw new Error('Read error');
+      });
+      const config = manager.readConfig();
+      expect(config).toEqual({});
+    });
+  });
+
+  describe('includeSubdirs', () => {
+    it('should add a glob when enabling with includeSubdirs', () => {
+      manager.enable('ext-test', true, '/path/to/dir');
+      const config = manager.readConfig();
+      expect(config['ext-test'].overrides).toContain('/path/to/dir/*');
+    });
+
+    it('should not add a glob when enabling without includeSubdirs', () => {
+      manager.enable('ext-test', false, '/path/to/dir');
+      const config = manager.readConfig();
+      expect(config['ext-test'].overrides).toContain('/path/to/dir/');
+      expect(config['ext-test'].overrides).not.toContain('/path/to/dir/*');
+    });
+
+    it('should add a glob when disabling with includeSubdirs', () => {
+      manager.disable('ext-test', true, '/path/to/dir');
+      const config = manager.readConfig();
+      expect(config['ext-test'].overrides).toContain('!/path/to/dir/*');
+    });
+
+    it('should remove conflicting glob rule when enabling without subdirs', () => {
+      manager.enable('ext-test', true, '/path/to/dir'); // Adds /path/to/dir*
+      manager.enable('ext-test', false, '/path/to/dir'); // Should remove the glob
+      const config = manager.readConfig();
+      expect(config['ext-test'].overrides).toContain('/path/to/dir/');
+      expect(config['ext-test'].overrides).not.toContain('/path/to/dir/*');
+    });
+
+    it('should remove conflicting non-glob rule when enabling with subdirs', () => {
+      manager.enable('ext-test', false, '/path/to/dir'); // Adds /path/to/dir
+      manager.enable('ext-test', true, '/path/to/dir'); // Should remove the non-glob
+      const config = manager.readConfig();
+      expect(config['ext-test'].overrides).toContain('/path/to/dir/*');
+      expect(config['ext-test'].overrides).not.toContain('/path/to/dir/');
+    });
+
+    it('should remove conflicting rules when disabling', () => {
+      manager.enable('ext-test', true, '/path/to/dir'); // enabled with glob
+      manager.disable('ext-test', false, '/path/to/dir'); // disabled without
+      const config = manager.readConfig();
+      expect(config['ext-test'].overrides).toContain('!/path/to/dir/');
+      expect(config['ext-test'].overrides).not.toContain('/path/to/dir/*');
+    });
+
+    it('should correctly evaluate isEnabled with subdirs', () => {
+      manager.disable('ext-test', true, '/');
+      manager.enable('ext-test', true, '/path/to/dir');
+      expect(manager.isEnabled('ext-test', '/path/to/dir/')).toBe(true);
+      expect(manager.isEnabled('ext-test', '/path/to/dir/sub/')).toBe(true);
+      expect(manager.isEnabled('ext-test', '/path/to/another/')).toBe(false);
+    });
+
+    it('should correctly evaluate isEnabled without subdirs', () => {
+      manager.disable('ext-test', true, '/*');
+      manager.enable('ext-test', false, '/path/to/dir');
+      expect(manager.isEnabled('ext-test', '/path/to/dir')).toBe(true);
+      expect(manager.isEnabled('ext-test', '/path/to/dir/sub')).toBe(false);
+    });
+  });
+
+  describe('pruning child rules', () => {
+    it('should remove child rules when enabling a parent with subdirs', () => {
+      // Pre-existing rules for children
+      manager.enable('ext-test', false, '/path/to/dir/subdir1');
+      manager.disable('ext-test', true, '/path/to/dir/subdir2');
+      manager.enable('ext-test', false, '/path/to/another/dir');
+
+      // Enable the parent directory
+      manager.enable('ext-test', true, '/path/to/dir');
+
+      const config = manager.readConfig();
+      const overrides = config['ext-test'].overrides;
+
+      // The new parent rule should be present
+      expect(overrides).toContain(`/path/to/dir/*`);
+
+      // Child rules should be removed
+      expect(overrides).not.toContain('/path/to/dir/subdir1/');
+      expect(overrides).not.toContain(`!/path/to/dir/subdir2/*`);
+
+      // Unrelated rules should remain
+      expect(overrides).toContain('/path/to/another/dir/');
+    });
+
+    it('should remove child rules when disabling a parent with subdirs', () => {
+      // Pre-existing rules for children
+      manager.enable('ext-test', false, '/path/to/dir/subdir1');
+      manager.disable('ext-test', true, '/path/to/dir/subdir2');
+      manager.enable('ext-test', false, '/path/to/another/dir');
+
+      // Disable the parent directory
+      manager.disable('ext-test', true, '/path/to/dir');
+
+      const config = manager.readConfig();
+      const overrides = config['ext-test'].overrides;
+
+      // The new parent rule should be present
+      expect(overrides).toContain(`!/path/to/dir/*`);
+
+      // Child rules should be removed
+      expect(overrides).not.toContain('/path/to/dir/subdir1/');
+      expect(overrides).not.toContain(`!/path/to/dir/subdir2/*`);
+
+      // Unrelated rules should remain
+      expect(overrides).toContain('/path/to/another/dir/');
+    });
+
+    it('should not remove child rules if includeSubdirs is false', () => {
+      manager.enable('ext-test', false, '/path/to/dir/subdir1');
+      manager.enable('ext-test', false, '/path/to/dir'); // Not including subdirs
+
+      const config = manager.readConfig();
+      const overrides = config['ext-test'].overrides;
+
+      expect(overrides).toContain('/path/to/dir/subdir1/');
+      expect(overrides).toContain('/path/to/dir/');
+    });
+  });
+
+  it('should correctly prioritize more specific enable rules', () => {
+    manager.disable('ext-test', true, '/Users/chrstn');
+    manager.enable('ext-test', true, '/Users/chrstn/gemini-cli');
+
+    expect(manager.isEnabled('ext-test', '/Users/chrstn/gemini-cli')).toBe(
+      true,
+    );
+  });
+
+  it('should not disable subdirectories if includeSubdirs is false', () => {
+    manager.disable('ext-test', false, '/Users/chrstn');
+    expect(manager.isEnabled('ext-test', '/Users/chrstn/gemini-cli')).toBe(
+      true,
+    );
+  });
+
+  describe('extension overrides (-e <name>)', () => {
+    beforeEach(() => {
+      manager = new ExtensionEnablementManager(['ext-test']);
+    });
+
+    it('can enable extensions, case-insensitive', () => {
+      manager.disable('ext-test', true, '/');
+      expect(manager.isEnabled('ext-test', '/')).toBe(true);
+      expect(manager.isEnabled('Ext-Test', '/')).toBe(true);
+      // Double check that it would have been disabled otherwise
+      expect(new ExtensionEnablementManager().isEnabled('ext-test', '/')).toBe(
+        false,
+      );
+    });
+
+    it('disable all other extensions', () => {
+      manager = new ExtensionEnablementManager(['ext-test']);
+      manager.enable('ext-test-2', true, '/');
+      expect(manager.isEnabled('ext-test-2', '/')).toBe(false);
+      // Double check that it would have been enabled otherwise
+      expect(
+        new ExtensionEnablementManager().isEnabled('ext-test-2', '/'),
+      ).toBe(true);
+    });
+
+    it('none disables all extensions', () => {
+      manager = new ExtensionEnablementManager(['none']);
+      manager.enable('ext-test', true, '/');
+      expect(manager.isEnabled('ext-test', '/path/to/dir')).toBe(false);
+      // Double check that it would have been enabled otherwise
+      expect(new ExtensionEnablementManager().isEnabled('ext-test', '/')).toBe(
+        true,
+      );
+    });
+  });
+
+  describe('validateExtensionOverrides', () => {
+    let coreEventsEmitSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+      coreEventsEmitSpy = vi.spyOn(coreEvents, 'emitFeedback');
+    });
+
+    afterEach(() => {
+      coreEventsEmitSpy.mockRestore();
+    });
+
+    it('should not log an error if enabledExtensionNamesOverride is empty', () => {
+      const manager = new ExtensionEnablementManager([]);
+      manager.validateExtensionOverrides([]);
+      expect(coreEventsEmitSpy).not.toHaveBeenCalled();
+    });
+
+    it('should not log an error if all enabledExtensionNamesOverride are valid', () => {
+      const manager = new ExtensionEnablementManager(['ext-one', 'ext-two']);
+      const extensions = [
+        { name: 'ext-one' },
+        { name: 'ext-two' },
+      ] as GeminiCLIExtension[];
+      manager.validateExtensionOverrides(extensions);
+      expect(coreEventsEmitSpy).not.toHaveBeenCalled();
+    });
+
+    it('should log an error for each invalid extension name in enabledExtensionNamesOverride', () => {
+      const manager = new ExtensionEnablementManager([
+        'ext-one',
+        'ext-invalid',
+        'ext-another-invalid',
+      ]);
+      const extensions = [
+        { name: 'ext-one' },
+        { name: 'ext-two' },
+      ] as GeminiCLIExtension[];
+      manager.validateExtensionOverrides(extensions);
+      expect(coreEventsEmitSpy).toHaveBeenCalledTimes(2);
+      expect(coreEventsEmitSpy).toHaveBeenCalledWith(
+        'error',
+        'Extension not found: ext-invalid',
+      );
+      expect(coreEventsEmitSpy).toHaveBeenCalledWith(
+        'error',
+        'Extension not found: ext-another-invalid',
+      );
+    });
+
+    it('should not log an error if "none" is in enabledExtensionNamesOverride', () => {
+      const manager = new ExtensionEnablementManager(['none']);
+      manager.validateExtensionOverrides([]);
+      expect(coreEventsEmitSpy).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe('Override', () => {
+  it('should create an override from input', () => {
+    const override = Override.fromInput('/path/to/dir', true);
+    expect(override.baseRule).toBe(`/path/to/dir/`);
+    expect(override.isDisable).toBe(false);
+    expect(override.includeSubdirs).toBe(true);
+  });
+
+  it('should create a disable override from input', () => {
+    const override = Override.fromInput('!/path/to/dir', false);
+    expect(override.baseRule).toBe(`/path/to/dir/`);
+    expect(override.isDisable).toBe(true);
+    expect(override.includeSubdirs).toBe(false);
+  });
+
+  it('should create an override from a file rule', () => {
+    const override = Override.fromFileRule('/path/to/dir/');
+    expect(override.baseRule).toBe('/path/to/dir/');
+    expect(override.isDisable).toBe(false);
+    expect(override.includeSubdirs).toBe(false);
+  });
+
+  it('should create an override from a file rule without a trailing slash', () => {
+    const override = Override.fromFileRule('/path/to/dir');
+    expect(override.baseRule).toBe('/path/to/dir');
+    expect(override.isDisable).toBe(false);
+    expect(override.includeSubdirs).toBe(false);
+  });
+
+  it('should create a disable override from a file rule', () => {
+    const override = Override.fromFileRule('!/path/to/dir/');
+    expect(override.isDisable).toBe(true);
+    expect(override.baseRule).toBe('/path/to/dir/');
+    expect(override.includeSubdirs).toBe(false);
+  });
+
+  it('should create an override with subdirs from a file rule', () => {
+    const override = Override.fromFileRule('/path/to/dir/*');
+    expect(override.baseRule).toBe('/path/to/dir/');
+    expect(override.isDisable).toBe(false);
+    expect(override.includeSubdirs).toBe(true);
+  });
+
+  it('should correctly identify conflicting overrides', () => {
+    const override1 = Override.fromInput('/path/to/dir', true);
+    const override2 = Override.fromInput('/path/to/dir', false);
+    expect(override1.conflictsWith(override2)).toBe(true);
+  });
+
+  it('should correctly identify non-conflicting overrides', () => {
+    const override1 = Override.fromInput('/path/to/dir', true);
+    const override2 = Override.fromInput('/path/to/another/dir', true);
+    expect(override1.conflictsWith(override2)).toBe(false);
+  });
+
+  it('should correctly identify equal overrides', () => {
+    const override1 = Override.fromInput('/path/to/dir', true);
+    const override2 = Override.fromInput('/path/to/dir', true);
+    expect(override1.isEqualTo(override2)).toBe(true);
+  });
+
+  it('should correctly identify unequal overrides', () => {
+    const override1 = Override.fromInput('/path/to/dir', true);
+    const override2 = Override.fromInput('!/path/to/dir', true);
+    expect(override1.isEqualTo(override2)).toBe(false);
+  });
+
+  it('should generate the correct regex', () => {
+    const override = Override.fromInput('/path/to/dir', true);
+    const regex = override.asRegex();
+    expect(regex.test('/path/to/dir/')).toBe(true);
+    expect(regex.test('/path/to/dir/subdir')).toBe(true);
+    expect(regex.test('/path/to/another/dir')).toBe(false);
+  });
+
+  it('should correctly identify child overrides', () => {
+    const parent = Override.fromInput('/path/to/dir', true);
+    const child = Override.fromInput('/path/to/dir/subdir', false);
+    expect(child.isChildOf(parent)).toBe(true);
+  });
+
+  it('should correctly identify child overrides with glob', () => {
+    const parent = Override.fromInput('/path/to/dir/*', true);
+    const child = Override.fromInput('/path/to/dir/subdir', false);
+    expect(child.isChildOf(parent)).toBe(true);
+  });
+
+  it('should correctly identify non-child overrides', () => {
+    const parent = Override.fromInput('/path/to/dir', true);
+    const other = Override.fromInput('/path/to/another/dir', false);
+    expect(other.isChildOf(parent)).toBe(false);
+  });
+
+  it('should generate the correct output string', () => {
+    const override = Override.fromInput('/path/to/dir', true);
+    expect(override.output()).toBe(`/path/to/dir/*`);
+  });
+
+  it('should generate the correct output string for a disable override', () => {
+    const override = Override.fromInput('!/path/to/dir', false);
+    expect(override.output()).toBe(`!/path/to/dir/`);
+  });
+
+  it('should disable a path based on a disable override rule', () => {
+    const override = Override.fromInput('!/path/to/dir', false);
+    expect(override.output()).toBe(`!/path/to/dir/`);
+  });
+});

packages/cli/src/config/extensions/extensionEnablement.ts

@@ -0,0 +1,251 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { coreEvents, type GeminiCLIExtension } from '@google/gemini-cli-core';
+import { ExtensionStorage } from './storage.js';
+import { z } from 'zod';
+
+export interface ExtensionEnablementConfig {
+  overrides: string[];
+}
+
+export interface AllExtensionsEnablementConfig {
+  [extensionName: string]: ExtensionEnablementConfig;
+}
+
+export class Override {
+  constructor(
+    public baseRule: string,
+    public isDisable: boolean,
+    public includeSubdirs: boolean,
+  ) {}
+
+  static fromInput(inputRule: string, includeSubdirs: boolean): Override {
+    const isDisable = inputRule.startsWith('!');
+    let baseRule = isDisable ? inputRule.substring(1) : inputRule;
+    baseRule = ensureLeadingAndTrailingSlash(baseRule);
+    return new Override(baseRule, isDisable, includeSubdirs);
+  }
+
+  static fromFileRule(fileRule: string): Override {
+    const isDisable = fileRule.startsWith('!');
+    let baseRule = isDisable ? fileRule.substring(1) : fileRule;
+    const includeSubdirs = baseRule.endsWith('*');
+    baseRule = includeSubdirs
+      ? baseRule.substring(0, baseRule.length - 1)
+      : baseRule;
+    return new Override(baseRule, isDisable, includeSubdirs);
+  }
+
+  conflictsWith(other: Override): boolean {
+    if (this.baseRule === other.baseRule) {
+      return (
+        this.includeSubdirs !== other.includeSubdirs ||
+        this.isDisable !== other.isDisable
+      );
+    }
+    return false;
+  }
+
+  isEqualTo(other: Override): boolean {
+    return (
+      this.baseRule === other.baseRule &&
+      this.includeSubdirs === other.includeSubdirs &&
+      this.isDisable === other.isDisable
+    );
+  }
+
+  asRegex(): RegExp {
+    return globToRegex(`${this.baseRule}${this.includeSubdirs ? '*' : ''}`);
+  }
+
+  isChildOf(parent: Override) {
+    if (!parent.includeSubdirs) {
+      return false;
+    }
+    return parent.asRegex().test(this.baseRule);
+  }
+
+  output(): string {
+    return `${this.isDisable ? '!' : ''}${this.baseRule}${this.includeSubdirs ? '*' : ''}`;
+  }
+
+  matchesPath(path: string) {
+    return this.asRegex().test(path);
+  }
+}
+
+const ensureLeadingAndTrailingSlash = function (dirPath: string): string {
+  // Normalize separators to forward slashes for consistent matching across platforms.
+  let result = dirPath.replace(/\\/g, '/');
+  if (result.charAt(0) !== '/') {
+    result = '/' + result;
+  }
+  if (result.charAt(result.length - 1) !== '/') {
+    result = result + '/';
+  }
+  return result;
+};
+
+/**
+ * Converts a glob pattern to a RegExp object.
+ * This is a simplified implementation that supports `*`.
+ *
+ * @param glob The glob pattern to convert.
+ * @returns A RegExp object.
+ */
+function globToRegex(glob: string): RegExp {
+  const regexString = glob
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape special regex characters
+    .replace(/(\/?)\*/g, '($1.*)?'); // Convert * to optional group
+
+  return new RegExp(`^${regexString}$`);
+}
+
+export class ExtensionEnablementManager {
+  private configFilePath: string;
+  private configDir: string;
+  // If non-empty, this overrides all other extension configuration and enables
+  // only the ones in this list.
+  private enabledExtensionNamesOverride: string[];
+
+  constructor(enabledExtensionNames?: string[]) {
+    this.configDir = ExtensionStorage.getUserExtensionsDir();
+    this.configFilePath = path.join(
+      this.configDir,
+      'extension-enablement.json',
+    );
+    this.enabledExtensionNamesOverride =
+      enabledExtensionNames?.map((name) => name.toLowerCase()) ?? [];
+  }
+
+  validateExtensionOverrides(extensions: GeminiCLIExtension[]) {
+    for (const name of this.enabledExtensionNamesOverride) {
+      if (name === 'none') continue;
+      if (
+        !extensions.some((ext) => ext.name.toLowerCase() === name.toLowerCase())
+      ) {
+        coreEvents.emitFeedback('error', `Extension not found: ${name}`);
+      }
+    }
+  }
+
+  /**
+   * Determines if an extension is enabled based on its name and the current
+   * path. The last matching rule in the overrides list wins.
+   *
+   * @param extensionName The name of the extension.
+   * @param currentPath The absolute path of the current working directory.
+   * @returns True if the extension is enabled, false otherwise.
+   */
+  isEnabled(extensionName: string, currentPath: string): boolean {
+    // If we have a single override called 'none', this disables all extensions.
+    // Typically, this comes from the user passing `-e none`.
+    if (
+      this.enabledExtensionNamesOverride.length === 1 &&
+      this.enabledExtensionNamesOverride[0] === 'none'
+    ) {
+      return false;
+    }
+
+    // If we have explicit overrides, only enable those extensions.
+    if (this.enabledExtensionNamesOverride.length > 0) {
+      // When checking against overrides ONLY, we use a case insensitive match.
+      // The override names are already lowercased in the constructor.
+      return this.enabledExtensionNamesOverride.includes(
+        extensionName.toLocaleLowerCase(),
+      );
+    }
+
+    // Otherwise, we use the configuration settings
+    const config = this.readConfig();
+    const extensionConfig = config[extensionName];
+    // Extensions are enabled by default.
+    let enabled = true;
+    const allOverrides = extensionConfig?.overrides ?? [];
+    for (const rule of allOverrides) {
+      const override = Override.fromFileRule(rule);
+      if (override.matchesPath(ensureLeadingAndTrailingSlash(currentPath))) {
+        enabled = !override.isDisable;
+      }
+    }
+    return enabled;
+  }
+
+  readConfig(): AllExtensionsEnablementConfig {
+    try {
+      const content = fs.readFileSync(this.configFilePath, 'utf-8');
+      const parsed: unknown = JSON.parse(content);
+      const schema = z.record(
+        z.string(),
+        z.object({ overrides: z.array(z.string()) }),
+      );
+      return schema.parse(parsed);
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        'code' in error &&
+        error.code === 'ENOENT'
+      ) {
+        return {};
+      }
+      coreEvents.emitFeedback(
+        'error',
+        'Failed to read extension enablement config.',
+        error,
+      );
+      return {};
+    }
+  }
+
+  writeConfig(config: AllExtensionsEnablementConfig): void {
+    fs.mkdirSync(this.configDir, { recursive: true });
+    fs.writeFileSync(this.configFilePath, JSON.stringify(config, null, 2));
+  }
+
+  enable(
+    extensionName: string,
+    includeSubdirs: boolean,
+    scopePath: string,
+  ): void {
+    const config = this.readConfig();
+    if (!config[extensionName]) {
+      config[extensionName] = { overrides: [] };
+    }
+    const override = Override.fromInput(scopePath, includeSubdirs);
+    const overrides = config[extensionName].overrides.filter((rule) => {
+      const fileOverride = Override.fromFileRule(rule);
+      if (
+        fileOverride.conflictsWith(override) ||
+        fileOverride.isEqualTo(override)
+      ) {
+        return false; // Remove conflicts and equivalent values.
+      }
+      return !fileOverride.isChildOf(override);
+    });
+    overrides.push(override.output());
+    config[extensionName].overrides = overrides;
+    this.writeConfig(config);
+  }
+
+  disable(
+    extensionName: string,
+    includeSubdirs: boolean,
+    scopePath: string,
+  ): void {
+    this.enable(extensionName, includeSubdirs, `!${scopePath}`);
+  }
+
+  remove(extensionName: string): void {
+    const config = this.readConfig();
+    if (config[extensionName]) {
+      delete config[extensionName];
+      this.writeConfig(config);
+    }
+  }
+}

packages/cli/src/config/extensions/extensionSettings.test.ts

@@ -0,0 +1,937 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  getEnvContents,
+  maybePromptForSettings,
+  promptForSetting,
+  type ExtensionSetting,
+  updateSetting,
+  ExtensionSettingScope,
+  getScopedEnvContents,
+} from './extensionSettings.js';
+import type { ExtensionConfig } from '../extension.js';
+import { ExtensionStorage } from './storage.js';
+import prompts from 'prompts';
+import * as fsPromises from 'node:fs/promises';
+import * as fs from 'node:fs';
+import { KeychainTokenStorage } from '@google/gemini-cli-core';
+import { EXTENSION_SETTINGS_FILENAME } from './variables.js';
+
+vi.mock('prompts');
+vi.mock('os', async (importOriginal) => {
+  const mockedOs = await importOriginal<typeof os>();
+  return {
+    ...mockedOs,
+    homedir: vi.fn(),
+  };
+});
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    KeychainTokenStorage: vi.fn(),
+  };
+});
+
+describe('extensionSettings', () => {
+  let tempHomeDir: string;
+  let tempWorkspaceDir: string;
+  let extensionDir: string;
+  let mockKeychainData: Record<string, Record<string, string>>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockKeychainData = {};
+    vi.mocked(KeychainTokenStorage).mockImplementation(
+      (serviceName: string) => {
+        if (!mockKeychainData[serviceName]) {
+          mockKeychainData[serviceName] = {};
+        }
+        const keychainData = mockKeychainData[serviceName];
+        return {
+          getSecret: vi
+            .fn()
+            .mockImplementation(
+              async (key: string) => keychainData[key] || null,
+            ),
+          setSecret: vi
+            .fn()
+            .mockImplementation(async (key: string, value: string) => {
+              keychainData[key] = value;
+            }),
+          deleteSecret: vi.fn().mockImplementation(async (key: string) => {
+            delete keychainData[key];
+          }),
+          listSecrets: vi
+            .fn()
+            .mockImplementation(async () => Object.keys(keychainData)),
+          isAvailable: vi.fn().mockResolvedValue(true),
+        } as unknown as KeychainTokenStorage;
+      },
+    );
+    tempHomeDir = os.tmpdir() + path.sep + `gemini-cli-test-home-${Date.now()}`;
+    tempWorkspaceDir = path.join(
+      os.tmpdir(),
+      `gemini-cli-test-workspace-${Date.now()}`,
+    );
+    extensionDir = path.join(tempHomeDir, '.gemini', 'extensions', 'test-ext');
+    // Spy and mock the method, but also create the directory so we can write to it.
+    vi.spyOn(ExtensionStorage.prototype, 'getExtensionDir').mockReturnValue(
+      extensionDir,
+    );
+    fs.mkdirSync(extensionDir, { recursive: true });
+    fs.mkdirSync(tempWorkspaceDir, { recursive: true });
+    vi.mocked(os.homedir).mockReturnValue(tempHomeDir);
+    vi.spyOn(process, 'cwd').mockReturnValue(tempWorkspaceDir);
+    vi.mocked(prompts).mockClear();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempHomeDir, { recursive: true, force: true });
+    fs.rmSync(tempWorkspaceDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  describe('maybePromptForSettings', () => {
+    const mockRequestSetting = vi.fn(
+      async (setting: ExtensionSetting) => `mock-${setting.envVar}`,
+    );
+
+    beforeEach(() => {
+      mockRequestSetting.mockClear();
+    });
+
+    it('should do nothing if settings are undefined', async () => {
+      const config: ExtensionConfig = { name: 'test-ext', version: '1.0.0' };
+      await maybePromptForSettings(
+        config,
+        '12345',
+        mockRequestSetting,
+        undefined,
+        undefined,
+      );
+      expect(mockRequestSetting).not.toHaveBeenCalled();
+    });
+
+    it('should do nothing if settings are empty', async () => {
+      const config: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [],
+      };
+      await maybePromptForSettings(
+        config,
+        '12345',
+        mockRequestSetting,
+        undefined,
+        undefined,
+      );
+      expect(mockRequestSetting).not.toHaveBeenCalled();
+    });
+
+    it('should prompt for all settings if there is no previous config', async () => {
+      const config: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [
+          { name: 's1', description: 'd1', envVar: 'VAR1' },
+          { name: 's2', description: 'd2', envVar: 'VAR2' },
+        ],
+      };
+      await maybePromptForSettings(
+        config,
+        '12345',
+        mockRequestSetting,
+        undefined,
+        undefined,
+      );
+      expect(mockRequestSetting).toHaveBeenCalledTimes(2);
+      expect(mockRequestSetting).toHaveBeenCalledWith(config.settings![0]);
+      expect(mockRequestSetting).toHaveBeenCalledWith(config.settings![1]);
+    });
+
+    it('should only prompt for new settings', async () => {
+      const previousConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [{ name: 's1', description: 'd1', envVar: 'VAR1' }],
+      };
+      const newConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [
+          { name: 's1', description: 'd1', envVar: 'VAR1' },
+          { name: 's2', description: 'd2', envVar: 'VAR2' },
+        ],
+      };
+      const previousSettings = { VAR1: 'previous-VAR1' };
+
+      await maybePromptForSettings(
+        newConfig,
+        '12345',
+        mockRequestSetting,
+        previousConfig,
+        previousSettings,
+      );
+
+      expect(mockRequestSetting).toHaveBeenCalledTimes(1);
+      expect(mockRequestSetting).toHaveBeenCalledWith(newConfig.settings![1]);
+
+      const expectedEnvPath = path.join(extensionDir, '.env');
+      const actualContent = await fsPromises.readFile(expectedEnvPath, 'utf-8');
+      const expectedContent = 'VAR1=previous-VAR1\nVAR2=mock-VAR2\n';
+      expect(actualContent).toBe(expectedContent);
+    });
+
+    it('should clear settings if new config has no settings', async () => {
+      const previousConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [
+          { name: 's1', description: 'd1', envVar: 'VAR1' },
+          {
+            name: 's2',
+            description: 'd2',
+            envVar: 'SENSITIVE_VAR',
+            sensitive: true,
+          },
+        ],
+      };
+      const newConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [],
+      };
+      const previousSettings = {
+        VAR1: 'previous-VAR1',
+        SENSITIVE_VAR: 'secret',
+      };
+      const userKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext 12345`,
+      );
+      await userKeychain.setSecret('SENSITIVE_VAR', 'secret');
+      const envPath = path.join(extensionDir, '.env');
+      await fsPromises.writeFile(envPath, 'VAR1=previous-VAR1');
+
+      await maybePromptForSettings(
+        newConfig,
+        '12345',
+        mockRequestSetting,
+        previousConfig,
+        previousSettings,
+      );
+
+      expect(mockRequestSetting).not.toHaveBeenCalled();
+      const actualContent = await fsPromises.readFile(envPath, 'utf-8');
+      expect(actualContent).toBe('');
+      expect(await userKeychain.getSecret('SENSITIVE_VAR')).toBeNull();
+    });
+
+    it('should remove sensitive settings from keychain', async () => {
+      const previousConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [
+          {
+            name: 's1',
+            description: 'd1',
+            envVar: 'SENSITIVE_VAR',
+            sensitive: true,
+          },
+        ],
+      };
+      const newConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [],
+      };
+      const previousSettings = { SENSITIVE_VAR: 'secret' };
+      const userKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext 12345`,
+      );
+      await userKeychain.setSecret('SENSITIVE_VAR', 'secret');
+
+      await maybePromptForSettings(
+        newConfig,
+        '12345',
+        mockRequestSetting,
+        previousConfig,
+        previousSettings,
+      );
+
+      expect(await userKeychain.getSecret('SENSITIVE_VAR')).toBeNull();
+    });
+
+    it('should remove settings that are no longer in the config', async () => {
+      const previousConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [
+          { name: 's1', description: 'd1', envVar: 'VAR1' },
+          { name: 's2', description: 'd2', envVar: 'VAR2' },
+        ],
+      };
+      const newConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [{ name: 's1', description: 'd1', envVar: 'VAR1' }],
+      };
+      const previousSettings = {
+        VAR1: 'previous-VAR1',
+        VAR2: 'previous-VAR2',
+      };
+
+      await maybePromptForSettings(
+        newConfig,
+        '12345',
+        mockRequestSetting,
+        previousConfig,
+        previousSettings,
+      );
+
+      expect(mockRequestSetting).not.toHaveBeenCalled();
+
+      const expectedEnvPath = path.join(extensionDir, '.env');
+      const actualContent = await fsPromises.readFile(expectedEnvPath, 'utf-8');
+      const expectedContent = 'VAR1=previous-VAR1\n';
+      expect(actualContent).toBe(expectedContent);
+    });
+
+    it('should reprompt if a setting changes sensitivity', async () => {
+      const previousConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [
+          { name: 's1', description: 'd1', envVar: 'VAR1', sensitive: false },
+        ],
+      };
+      const newConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [
+          { name: 's1', description: 'd1', envVar: 'VAR1', sensitive: true },
+        ],
+      };
+      const previousSettings = { VAR1: 'previous-VAR1' };
+
+      await maybePromptForSettings(
+        newConfig,
+        '12345',
+        mockRequestSetting,
+        previousConfig,
+        previousSettings,
+      );
+
+      expect(mockRequestSetting).toHaveBeenCalledTimes(1);
+      expect(mockRequestSetting).toHaveBeenCalledWith(newConfig.settings![0]);
+
+      // The value should now be in keychain, not the .env file.
+      const expectedEnvPath = path.join(extensionDir, '.env');
+      const actualContent = await fsPromises.readFile(expectedEnvPath, 'utf-8');
+      expect(actualContent).toBe('');
+    });
+
+    it('should not prompt if settings are identical', async () => {
+      const previousConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [
+          { name: 's1', description: 'd1', envVar: 'VAR1' },
+          { name: 's2', description: 'd2', envVar: 'VAR2' },
+        ],
+      };
+      const newConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [
+          { name: 's1', description: 'd1', envVar: 'VAR1' },
+          { name: 's2', description: 'd2', envVar: 'VAR2' },
+        ],
+      };
+      const previousSettings = {
+        VAR1: 'previous-VAR1',
+        VAR2: 'previous-VAR2',
+      };
+
+      await maybePromptForSettings(
+        newConfig,
+        '12345',
+        mockRequestSetting,
+        previousConfig,
+        previousSettings,
+      );
+
+      expect(mockRequestSetting).not.toHaveBeenCalled();
+      const expectedEnvPath = path.join(extensionDir, '.env');
+      const actualContent = await fsPromises.readFile(expectedEnvPath, 'utf-8');
+      const expectedContent = 'VAR1=previous-VAR1\nVAR2=previous-VAR2\n';
+      expect(actualContent).toBe(expectedContent);
+    });
+
+    it('should wrap values with spaces in quotes', async () => {
+      const config: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [{ name: 's1', description: 'd1', envVar: 'VAR1' }],
+      };
+      mockRequestSetting.mockResolvedValue('a value with spaces');
+
+      await maybePromptForSettings(
+        config,
+        '12345',
+        mockRequestSetting,
+        undefined,
+        undefined,
+      );
+
+      const expectedEnvPath = path.join(extensionDir, '.env');
+      const actualContent = await fsPromises.readFile(expectedEnvPath, 'utf-8');
+      expect(actualContent).toBe('VAR1="a value with spaces"\n');
+    });
+
+    it('should not set sensitive settings if the value is empty during initial setup', async () => {
+      const config: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [
+          {
+            name: 's1',
+            description: 'd1',
+            envVar: 'SENSITIVE_VAR',
+            sensitive: true,
+          },
+        ],
+      };
+      mockRequestSetting.mockResolvedValue('');
+
+      await maybePromptForSettings(
+        config,
+        '12345',
+        mockRequestSetting,
+        undefined,
+        undefined,
+      );
+
+      const userKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext 12345`,
+      );
+      expect(await userKeychain.getSecret('SENSITIVE_VAR')).toBeNull();
+    });
+
+    it('should not attempt to clear secrets if keychain is unavailable', async () => {
+      // Arrange
+      const mockIsAvailable = vi.fn().mockResolvedValue(false);
+      const mockListSecrets = vi.fn();
+
+      vi.mocked(KeychainTokenStorage).mockImplementation(
+        () =>
+          ({
+            isAvailable: mockIsAvailable,
+            listSecrets: mockListSecrets,
+            deleteSecret: vi.fn(),
+            getSecret: vi.fn(),
+            setSecret: vi.fn(),
+          }) as unknown as KeychainTokenStorage,
+      );
+
+      const config: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [], // Empty settings triggers clearSettings
+      };
+
+      const previousConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [{ name: 's1', description: 'd1', envVar: 'VAR1' }],
+      };
+
+      // Act
+      await maybePromptForSettings(
+        config,
+        '12345',
+        mockRequestSetting,
+        previousConfig,
+        undefined,
+      );
+
+      // Assert
+      expect(mockIsAvailable).toHaveBeenCalled();
+      expect(mockListSecrets).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('promptForSetting', () => {
+    it.each([
+      {
+        description:
+          'should use prompts with type "password" for sensitive settings',
+        setting: {
+          name: 'API Key',
+          description: 'Your secret key',
+          envVar: 'API_KEY',
+          sensitive: true,
+        },
+        expectedType: 'password',
+        promptValue: 'secret-key',
+      },
+      {
+        description:
+          'should use prompts with type "text" for non-sensitive settings',
+        setting: {
+          name: 'Username',
+          description: 'Your public username',
+          envVar: 'USERNAME',
+          sensitive: false,
+        },
+        expectedType: 'text',
+        promptValue: 'test-user',
+      },
+      {
+        description: 'should default to "text" if sensitive is undefined',
+        setting: {
+          name: 'Username',
+          description: 'Your public username',
+          envVar: 'USERNAME',
+        },
+        expectedType: 'text',
+        promptValue: 'test-user',
+      },
+    ])('$description', async ({ setting, expectedType, promptValue }) => {
+      vi.mocked(prompts).mockResolvedValue({ value: promptValue });
+
+      const result = await promptForSetting(setting as ExtensionSetting);
+
+      expect(prompts).toHaveBeenCalledWith({
+        type: expectedType,
+        name: 'value',
+        message: `${setting.name}\n${setting.description}`,
+      });
+      expect(result).toBe(promptValue);
+    });
+
+    it('should return undefined if the user cancels the prompt', async () => {
+      vi.mocked(prompts).mockResolvedValue({ value: undefined });
+      const result = await promptForSetting({
+        name: 'Test',
+        description: 'Test desc',
+        envVar: 'TEST_VAR',
+      });
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('getScopedEnvContents', () => {
+    const config: ExtensionConfig = {
+      name: 'test-ext',
+      version: '1.0.0',
+      settings: [
+        { name: 's1', description: 'd1', envVar: 'VAR1' },
+        {
+          name: 's2',
+          description: 'd2',
+          envVar: 'SENSITIVE_VAR',
+          sensitive: true,
+        },
+      ],
+    };
+    const extensionId = '12345';
+
+    it('should return combined contents from user .env and keychain for USER scope', async () => {
+      const userEnvPath = path.join(extensionDir, EXTENSION_SETTINGS_FILENAME);
+      await fsPromises.writeFile(userEnvPath, 'VAR1=user-value1');
+      const userKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext 12345`,
+      );
+      await userKeychain.setSecret('SENSITIVE_VAR', 'user-secret');
+
+      const contents = await getScopedEnvContents(
+        config,
+        extensionId,
+        ExtensionSettingScope.USER,
+        tempWorkspaceDir,
+      );
+
+      expect(contents).toEqual({
+        VAR1: 'user-value1',
+        SENSITIVE_VAR: 'user-secret',
+      });
+    });
+
+    it('should return combined contents from workspace .env and keychain for WORKSPACE scope', async () => {
+      const workspaceEnvPath = path.join(
+        tempWorkspaceDir,
+        EXTENSION_SETTINGS_FILENAME,
+      );
+      await fsPromises.writeFile(workspaceEnvPath, 'VAR1=workspace-value1');
+      const workspaceKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext 12345 ${tempWorkspaceDir}`,
+      );
+      await workspaceKeychain.setSecret('SENSITIVE_VAR', 'workspace-secret');
+
+      const contents = await getScopedEnvContents(
+        config,
+        extensionId,
+        ExtensionSettingScope.WORKSPACE,
+        tempWorkspaceDir,
+      );
+
+      expect(contents).toEqual({
+        VAR1: 'workspace-value1',
+        SENSITIVE_VAR: 'workspace-secret',
+      });
+    });
+
+    it('should ignore .env if it is a directory', async () => {
+      const workspaceEnvPath = path.join(
+        tempWorkspaceDir,
+        EXTENSION_SETTINGS_FILENAME,
+      );
+      fs.mkdirSync(workspaceEnvPath);
+      const workspaceKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext 12345 ${tempWorkspaceDir}`,
+      );
+      await workspaceKeychain.setSecret('SENSITIVE_VAR', 'workspace-secret');
+
+      const contents = await getScopedEnvContents(
+        config,
+        extensionId,
+        ExtensionSettingScope.WORKSPACE,
+        tempWorkspaceDir,
+      );
+
+      expect(contents).toEqual({
+        SENSITIVE_VAR: 'workspace-secret',
+      });
+    });
+  });
+
+  describe('getEnvContents (merged)', () => {
+    const config: ExtensionConfig = {
+      name: 'test-ext',
+      version: '1.0.0',
+      settings: [
+        { name: 's1', description: 'd1', envVar: 'VAR1' },
+        { name: 's2', description: 'd2', envVar: 'VAR2', sensitive: true },
+        { name: 's3', description: 'd3', envVar: 'VAR3' },
+      ],
+    };
+    const extensionId = '12345';
+
+    it('should merge user and workspace settings, with workspace taking precedence', async () => {
+      // User settings
+      const userEnvPath = path.join(extensionDir, EXTENSION_SETTINGS_FILENAME);
+      await fsPromises.writeFile(
+        userEnvPath,
+        'VAR1=user-value1\nVAR3=user-value3',
+      );
+      const userKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext ${extensionId}`,
+      );
+      await userKeychain.setSecret('VAR2', 'user-secret2');
+
+      // Workspace settings
+      const workspaceEnvPath = path.join(
+        tempWorkspaceDir,
+        EXTENSION_SETTINGS_FILENAME,
+      );
+      await fsPromises.writeFile(workspaceEnvPath, 'VAR1=workspace-value1');
+      const workspaceKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext ${extensionId} ${tempWorkspaceDir}`,
+      );
+      await workspaceKeychain.setSecret('VAR2', 'workspace-secret2');
+
+      const contents = await getEnvContents(
+        config,
+        extensionId,
+        tempWorkspaceDir,
+      );
+
+      expect(contents).toEqual({
+        VAR1: 'workspace-value1',
+        VAR2: 'workspace-secret2',
+        VAR3: 'user-value3',
+      });
+    });
+  });
+
+  describe('updateSetting', () => {
+    const config: ExtensionConfig = {
+      name: 'test-ext',
+      version: '1.0.0',
+      settings: [
+        { name: 's1', description: 'd1', envVar: 'VAR1' },
+        { name: 's2', description: 'd2', envVar: 'VAR2', sensitive: true },
+      ],
+    };
+    const mockRequestSetting = vi.fn();
+
+    beforeEach(async () => {
+      const userEnvPath = path.join(extensionDir, '.env');
+      await fsPromises.writeFile(userEnvPath, 'VAR1=value1\n');
+      const userKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext 12345`,
+      );
+      await userKeychain.setSecret('VAR2', 'value2');
+      mockRequestSetting.mockClear();
+    });
+
+    it('should update a non-sensitive setting in USER scope', async () => {
+      mockRequestSetting.mockResolvedValue('new-value1');
+
+      await updateSetting(
+        config,
+        '12345',
+        'VAR1',
+        mockRequestSetting,
+        ExtensionSettingScope.USER,
+        tempWorkspaceDir,
+      );
+
+      const expectedEnvPath = path.join(extensionDir, '.env');
+      const actualContent = await fsPromises.readFile(expectedEnvPath, 'utf-8');
+      expect(actualContent).toContain('VAR1=new-value1');
+    });
+
+    it('should update a non-sensitive setting in WORKSPACE scope', async () => {
+      mockRequestSetting.mockResolvedValue('new-workspace-value');
+
+      await updateSetting(
+        config,
+        '12345',
+        'VAR1',
+        mockRequestSetting,
+        ExtensionSettingScope.WORKSPACE,
+        tempWorkspaceDir,
+      );
+
+      const expectedEnvPath = path.join(tempWorkspaceDir, '.env');
+      const actualContent = await fsPromises.readFile(expectedEnvPath, 'utf-8');
+      expect(actualContent).toContain('VAR1=new-workspace-value');
+    });
+
+    it('should throw an error when trying to write to a workspace with a .env directory', async () => {
+      const workspaceEnvPath = path.join(tempWorkspaceDir, '.env');
+      fs.mkdirSync(workspaceEnvPath);
+
+      mockRequestSetting.mockResolvedValue('new-workspace-value');
+
+      await expect(
+        updateSetting(
+          config,
+          '12345',
+          'VAR1',
+          mockRequestSetting,
+          ExtensionSettingScope.WORKSPACE,
+          tempWorkspaceDir,
+        ),
+      ).rejects.toThrow(
+        /Cannot write extension settings to .* because it is a directory./,
+      );
+    });
+
+    it('should update a sensitive setting in USER scope', async () => {
+      mockRequestSetting.mockResolvedValue('new-value2');
+
+      await updateSetting(
+        config,
+        '12345',
+        'VAR2',
+        mockRequestSetting,
+        ExtensionSettingScope.USER,
+        tempWorkspaceDir,
+      );
+
+      const userKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext 12345`,
+      );
+      expect(await userKeychain.getSecret('VAR2')).toBe('new-value2');
+    });
+
+    it('should update a sensitive setting in WORKSPACE scope', async () => {
+      mockRequestSetting.mockResolvedValue('new-workspace-secret');
+
+      await updateSetting(
+        config,
+        '12345',
+        'VAR2',
+        mockRequestSetting,
+        ExtensionSettingScope.WORKSPACE,
+        tempWorkspaceDir,
+      );
+
+      const workspaceKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext 12345 ${tempWorkspaceDir}`,
+      );
+      expect(await workspaceKeychain.getSecret('VAR2')).toBe(
+        'new-workspace-secret',
+      );
+    });
+
+    it('should leave existing, unmanaged .env variables intact when updating in WORKSPACE scope', async () => {
+      // Setup a pre-existing .env file in the workspace with unmanaged variables
+      const workspaceEnvPath = path.join(tempWorkspaceDir, '.env');
+      const originalEnvContent =
+        'PROJECT_VAR_1=value_1\nPROJECT_VAR_2=value_2\nVAR1=original-value'; // VAR1 is managed by extension
+      await fsPromises.writeFile(workspaceEnvPath, originalEnvContent);
+
+      // Simulate updating an extension-managed non-sensitive setting
+      mockRequestSetting.mockResolvedValue('updated-value');
+      await updateSetting(
+        config,
+        '12345',
+        'VAR1',
+        mockRequestSetting,
+        ExtensionSettingScope.WORKSPACE,
+        tempWorkspaceDir,
+      );
+
+      // Read the .env file after update
+      const actualContent = await fsPromises.readFile(
+        workspaceEnvPath,
+        'utf-8',
+      );
+
+      // Assert that original variables are intact and extension variable is updated
+      expect(actualContent).toContain('PROJECT_VAR_1=value_1');
+      expect(actualContent).toContain('PROJECT_VAR_2=value_2');
+      expect(actualContent).toContain('VAR1=updated-value');
+
+      // Ensure no other unexpected changes or deletions
+      const lines = actualContent.split('\n').filter((line) => line.length > 0);
+      expect(lines).toHaveLength(3); // Should only have the three variables
+    });
+
+    it('should delete a sensitive setting if the new value is empty', async () => {
+      mockRequestSetting.mockResolvedValue('');
+
+      await updateSetting(
+        config,
+        '12345',
+        'VAR2',
+        mockRequestSetting,
+        ExtensionSettingScope.USER,
+        tempWorkspaceDir,
+      );
+
+      const userKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext 12345`,
+      );
+      expect(await userKeychain.getSecret('VAR2')).toBeNull();
+    });
+
+    it('should delete a non-sensitive setting if the new value is empty', async () => {
+      mockRequestSetting.mockResolvedValue('');
+
+      await updateSetting(
+        config,
+        '12345',
+        'VAR1',
+        mockRequestSetting,
+        ExtensionSettingScope.USER,
+        tempWorkspaceDir,
+      );
+
+      const expectedEnvPath = path.join(extensionDir, '.env');
+      const actualContent = await fsPromises.readFile(expectedEnvPath, 'utf-8');
+      expect(actualContent).not.toContain('VAR1=');
+    });
+
+    it('should not throw if deleting a non-existent sensitive setting with empty value', async () => {
+      mockRequestSetting.mockResolvedValue('');
+      // Ensure it doesn't exist first
+      const userKeychain = new KeychainTokenStorage(
+        `Gemini CLI Extensions test-ext 12345`,
+      );
+      await userKeychain.deleteSecret('VAR2');
+
+      await updateSetting(
+        config,
+        '12345',
+        'VAR2',
+        mockRequestSetting,
+        ExtensionSettingScope.USER,
+        tempWorkspaceDir,
+      );
+      // Should complete without error
+    });
+
+    it('should throw error if env var name contains invalid characters', async () => {
+      const securityConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [{ name: 's2', description: 'd2', envVar: 'VAR-BAD' }],
+      };
+      mockRequestSetting.mockResolvedValue('value');
+
+      await expect(
+        updateSetting(
+          securityConfig,
+          '12345',
+          'VAR-BAD',
+          mockRequestSetting,
+          ExtensionSettingScope.USER,
+          tempWorkspaceDir,
+        ),
+      ).rejects.toThrow(/Invalid environment variable name/);
+    });
+
+    it('should throw error if env var value contains newlines', async () => {
+      mockRequestSetting.mockResolvedValue('value\nwith\nnewlines');
+
+      await expect(
+        updateSetting(
+          config,
+          '12345',
+          'VAR1',
+          mockRequestSetting,
+          ExtensionSettingScope.USER,
+          tempWorkspaceDir,
+        ),
+      ).rejects.toThrow(/Invalid environment variable value/);
+    });
+
+    it('should quote values with spaces', async () => {
+      mockRequestSetting.mockResolvedValue('value with spaces');
+
+      await updateSetting(
+        config,
+        '12345',
+        'VAR1',
+        mockRequestSetting,
+        ExtensionSettingScope.USER,
+        tempWorkspaceDir,
+      );
+
+      const expectedEnvPath = path.join(extensionDir, '.env');
+      const actualContent = await fsPromises.readFile(expectedEnvPath, 'utf-8');
+      expect(actualContent).toContain('VAR1="value with spaces"');
+    });
+
+    it('should escape quotes in values', async () => {
+      mockRequestSetting.mockResolvedValue('value with "quotes"');
+
+      await updateSetting(
+        config,
+        '12345',
+        'VAR1',
+        mockRequestSetting,
+        ExtensionSettingScope.USER,
+        tempWorkspaceDir,
+      );
+
+      const expectedEnvPath = path.join(extensionDir, '.env');
+      const actualContent = await fsPromises.readFile(expectedEnvPath, 'utf-8');
+      expect(actualContent).toContain('VAR1="value with \\"quotes\\""');
+    });
+  });
+});

packages/cli/src/config/extensions/extensionSettings.ts

@@ -0,0 +1,389 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+import * as dotenv from 'dotenv';
+import * as path from 'node:path';
+
+import { ExtensionStorage } from './storage.js';
+import type { ExtensionConfig } from '../extension.js';
+
+import prompts from 'prompts';
+import { debugLogger, KeychainTokenStorage } from '@google/gemini-cli-core';
+import { EXTENSION_SETTINGS_FILENAME } from './variables.js';
+
+export enum ExtensionSettingScope {
+  USER = 'user',
+  WORKSPACE = 'workspace',
+}
+
+export interface ExtensionSetting {
+  name: string;
+  description: string;
+  envVar: string;
+  // NOTE: If no value is set, this setting will be considered NOT sensitive.
+  sensitive?: boolean;
+}
+
+const getKeychainStorageName = (
+  extensionName: string,
+  extensionId: string,
+  scope: ExtensionSettingScope,
+  workspaceDir?: string,
+): string => {
+  const base = `Gemini CLI Extensions ${extensionName} ${extensionId}`;
+  if (scope === ExtensionSettingScope.WORKSPACE) {
+    if (!workspaceDir) {
+      throw new Error('Workspace directory is required for workspace scope');
+    }
+    return `${base} ${workspaceDir}`;
+  }
+  return base;
+};
+
+export const getEnvFilePath = (
+  extensionName: string,
+  scope: ExtensionSettingScope,
+  workspaceDir?: string,
+): string => {
+  if (scope === ExtensionSettingScope.WORKSPACE) {
+    if (!workspaceDir) {
+      throw new Error('Workspace directory is required for workspace scope');
+    }
+    return path.join(workspaceDir, EXTENSION_SETTINGS_FILENAME);
+  }
+  return new ExtensionStorage(extensionName).getEnvFilePath();
+};
+
+export async function maybePromptForSettings(
+  extensionConfig: ExtensionConfig,
+  extensionId: string,
+  requestSetting: (setting: ExtensionSetting) => Promise<string | undefined>,
+  previousExtensionConfig?: ExtensionConfig,
+  previousSettings?: Record<string, string>,
+): Promise<void> {
+  const { name: extensionName, settings } = extensionConfig;
+  if (
+    (!settings || settings.length === 0) &&
+    (!previousExtensionConfig?.settings ||
+      previousExtensionConfig.settings.length === 0)
+  ) {
+    return;
+  }
+  // We assume user scope here because we don't have a way to ask the user for scope during the initial setup.
+  // The user can change the scope later using the `settings set` command.
+  const scope = ExtensionSettingScope.USER;
+  const envFilePath = getEnvFilePath(extensionName, scope);
+  const keychain = new KeychainTokenStorage(
+    getKeychainStorageName(extensionName, extensionId, scope),
+  );
+
+  if (!settings || settings.length === 0) {
+    await clearSettings(envFilePath, keychain);
+    return;
+  }
+
+  const settingsChanges = getSettingsChanges(
+    settings,
+    previousExtensionConfig?.settings ?? [],
+  );
+
+  const allSettings: Record<string, string> = { ...previousSettings };
+
+  for (const removedEnvSetting of settingsChanges.removeEnv) {
+    delete allSettings[removedEnvSetting.envVar];
+  }
+
+  for (const removedSensitiveSetting of settingsChanges.removeSensitive) {
+    await keychain.deleteSecret(removedSensitiveSetting.envVar);
+  }
+
+  for (const setting of settingsChanges.promptForSensitive.concat(
+    settingsChanges.promptForEnv,
+  )) {
+    const answer = await requestSetting(setting);
+    if (answer !== undefined) {
+      allSettings[setting.envVar] = answer;
+    }
+  }
+
+  const nonSensitiveSettings: Record<string, string> = {};
+  for (const setting of settings) {
+    const value = allSettings[setting.envVar];
+    if (value === undefined || value === '') {
+      continue;
+    }
+    if (setting.sensitive) {
+      await keychain.setSecret(setting.envVar, value);
+    } else {
+      nonSensitiveSettings[setting.envVar] = value;
+    }
+  }
+
+  const envContent = formatEnvContent(nonSensitiveSettings);
+
+  if (fsSync.existsSync(envFilePath)) {
+    const stat = fsSync.statSync(envFilePath);
+    if (stat.isDirectory()) {
+      throw new Error(
+        `Cannot write extension settings to ${envFilePath} because it is a directory.`,
+      );
+    }
+  }
+
+  await fs.writeFile(envFilePath, envContent);
+}
+
+function formatEnvContent(settings: Record<string, string>): string {
+  let envContent = '';
+  for (const [key, value] of Object.entries(settings)) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) {
+      throw new Error(
+        `Invalid environment variable name: "${key}". Must contain only alphanumeric characters and underscores.`,
+      );
+    }
+    if (value.includes('\n') || value.includes('\r')) {
+      throw new Error(
+        `Invalid environment variable value for "${key}". Values cannot contain newlines.`,
+      );
+    }
+    const formattedValue = value.includes(' ')
+      ? `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+      : value;
+    envContent += `${key}=${formattedValue}\n`;
+  }
+  return envContent;
+}
+
+export async function promptForSetting(
+  setting: ExtensionSetting,
+): Promise<string | undefined> {
+  const response = await prompts({
+    type: setting.sensitive ? 'password' : 'text',
+    name: 'value',
+    message: `${setting.name}\n${setting.description}`,
+  });
+  return typeof response.value === 'string' ? response.value : undefined;
+}
+
+export async function getScopedEnvContents(
+  extensionConfig: ExtensionConfig,
+  extensionId: string,
+  scope: ExtensionSettingScope,
+  workspaceDir?: string,
+): Promise<Record<string, string>> {
+  const { name: extensionName } = extensionConfig;
+  const keychain = new KeychainTokenStorage(
+    getKeychainStorageName(extensionName, extensionId, scope, workspaceDir),
+  );
+  const envFilePath = getEnvFilePath(extensionName, scope, workspaceDir);
+  let customEnv: Record<string, string> = {};
+  if (fsSync.existsSync(envFilePath)) {
+    const stat = fsSync.statSync(envFilePath);
+    if (!stat.isDirectory()) {
+      const envFile = fsSync.readFileSync(envFilePath, 'utf-8');
+      customEnv = dotenv.parse(envFile);
+    }
+  }
+
+  if (extensionConfig.settings) {
+    for (const setting of extensionConfig.settings) {
+      if (setting.sensitive) {
+        const secret = await keychain.getSecret(setting.envVar);
+        if (secret) {
+          customEnv[setting.envVar] = secret;
+        }
+      }
+    }
+  }
+  return customEnv;
+}
+
+export async function getEnvContents(
+  extensionConfig: ExtensionConfig,
+  extensionId: string,
+  workspaceDir: string,
+): Promise<Record<string, string>> {
+  if (!extensionConfig.settings || extensionConfig.settings.length === 0) {
+    return Promise.resolve({});
+  }
+
+  const userSettings = await getScopedEnvContents(
+    extensionConfig,
+    extensionId,
+    ExtensionSettingScope.USER,
+  );
+  const workspaceSettings = await getScopedEnvContents(
+    extensionConfig,
+    extensionId,
+    ExtensionSettingScope.WORKSPACE,
+    workspaceDir,
+  );
+
+  return { ...userSettings, ...workspaceSettings };
+}
+
+export async function updateSetting(
+  extensionConfig: ExtensionConfig,
+  extensionId: string,
+  settingKey: string,
+  requestSetting: (setting: ExtensionSetting) => Promise<string | undefined>,
+  scope: ExtensionSettingScope,
+  workspaceDir: string,
+): Promise<void> {
+  const { name: extensionName, settings } = extensionConfig;
+  if (!settings || settings.length === 0) {
+    debugLogger.log('This extension does not have any settings.');
+    return;
+  }
+
+  const settingToUpdate = settings.find(
+    (s) => s.name === settingKey || s.envVar === settingKey,
+  );
+
+  if (!settingToUpdate) {
+    debugLogger.log(`Setting ${settingKey} not found.`);
+    return;
+  }
+
+  const newValue = await requestSetting(settingToUpdate);
+  if (newValue === undefined) {
+    return;
+  }
+
+  const keychain = new KeychainTokenStorage(
+    getKeychainStorageName(extensionName, extensionId, scope, workspaceDir),
+  );
+
+  if (settingToUpdate.sensitive) {
+    if (newValue) {
+      await keychain.setSecret(settingToUpdate.envVar, newValue);
+    } else {
+      try {
+        await keychain.deleteSecret(settingToUpdate.envVar);
+      } catch {
+        // Ignore if secret does not exist
+      }
+    }
+    return;
+  }
+
+  // For non-sensitive settings, we need to read the existing .env file,
+  // update the value, and write it back, preserving any other values.
+  const envFilePath = getEnvFilePath(extensionName, scope, workspaceDir);
+  let envContent = '';
+  if (fsSync.existsSync(envFilePath)) {
+    const stat = fsSync.statSync(envFilePath);
+    if (stat.isDirectory()) {
+      throw new Error(
+        `Cannot write extension settings to ${envFilePath} because it is a directory.`,
+      );
+    }
+    envContent = await fs.readFile(envFilePath, 'utf-8');
+  }
+
+  const parsedEnv = dotenv.parse(envContent);
+  if (!newValue) {
+    delete parsedEnv[settingToUpdate.envVar];
+  } else {
+    parsedEnv[settingToUpdate.envVar] = newValue;
+  }
+
+  // We only want to write back the variables that are not sensitive.
+  const nonSensitiveSettings: Record<string, string> = {};
+  const sensitiveEnvVars = new Set(
+    settings.filter((s) => s.sensitive).map((s) => s.envVar),
+  );
+  for (const [key, value] of Object.entries(parsedEnv)) {
+    if (!sensitiveEnvVars.has(key)) {
+      nonSensitiveSettings[key] = value;
+    }
+  }
+
+  const newEnvContent = formatEnvContent(nonSensitiveSettings);
+  await fs.writeFile(envFilePath, newEnvContent);
+}
+
+interface settingsChanges {
+  promptForSensitive: ExtensionSetting[];
+  removeSensitive: ExtensionSetting[];
+  promptForEnv: ExtensionSetting[];
+  removeEnv: ExtensionSetting[];
+}
+function getSettingsChanges(
+  settings: ExtensionSetting[],
+  oldSettings: ExtensionSetting[],
+): settingsChanges {
+  const isSameSetting = (a: ExtensionSetting, b: ExtensionSetting) =>
+    a.envVar === b.envVar && (a.sensitive ?? false) === (b.sensitive ?? false);
+
+  const sensitiveOld = oldSettings.filter((s) => s.sensitive ?? false);
+  const sensitiveNew = settings.filter((s) => s.sensitive ?? false);
+  const envOld = oldSettings.filter((s) => !(s.sensitive ?? false));
+  const envNew = settings.filter((s) => !(s.sensitive ?? false));
+
+  return {
+    promptForSensitive: sensitiveNew.filter(
+      (s) => !sensitiveOld.some((old) => isSameSetting(s, old)),
+    ),
+    removeSensitive: sensitiveOld.filter(
+      (s) => !sensitiveNew.some((neu) => isSameSetting(s, neu)),
+    ),
+    promptForEnv: envNew.filter(
+      (s) => !envOld.some((old) => isSameSetting(s, old)),
+    ),
+    removeEnv: envOld.filter(
+      (s) => !envNew.some((neu) => isSameSetting(s, neu)),
+    ),
+  };
+}
+
+async function clearSettings(
+  envFilePath: string,
+  keychain: KeychainTokenStorage,
+) {
+  if (fsSync.existsSync(envFilePath)) {
+    const stat = fsSync.statSync(envFilePath);
+    if (!stat.isDirectory()) {
+      await fs.writeFile(envFilePath, '');
+    }
+  }
+  if (!(await keychain.isAvailable())) {
+    return;
+  }
+  const secrets = await keychain.listSecrets();
+  for (const secret of secrets) {
+    await keychain.deleteSecret(secret);
+  }
+  return;
+}
+
+export async function getMissingSettings(
+  extensionConfig: ExtensionConfig,
+  extensionId: string,
+  workspaceDir: string,
+): Promise<ExtensionSetting[]> {
+  const { settings } = extensionConfig;
+  if (!settings || settings.length === 0) {
+    return [];
+  }
+
+  const existingSettings = await getEnvContents(
+    extensionConfig,
+    extensionId,
+    workspaceDir,
+  );
+  const missingSettings: ExtensionSetting[] = [];
+
+  for (const setting of settings) {
+    if (existingSettings[setting.envVar] === undefined) {
+      missingSettings.push(setting);
+    }
+  }
+
+  return missingSettings;
+}

packages/cli/src/config/extensions/extensionUpdates.test.ts

@@ -0,0 +1,308 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs';
+import { getMissingSettings } from './extensionSettings.js';
+import type { ExtensionConfig } from '../extension.js';
+import {
+  debugLogger,
+  type ExtensionInstallMetadata,
+  type GeminiCLIExtension,
+  coreEvents,
+} from '@google/gemini-cli-core';
+import { ExtensionManager } from '../extension-manager.js';
+import { createTestMergedSettings } from '../settings.js';
+import { isWorkspaceTrusted } from '../trustedFolders.js';
+
+// --- Mocks ---
+
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>();
+  return {
+    ...actual,
+    existsSync: vi.fn(),
+    statSync: vi.fn(),
+    lstatSync: vi.fn(),
+    realpathSync: vi.fn((p) => p),
+    promises: {
+      ...actual.promises,
+      mkdir: vi.fn(),
+      readdir: vi.fn(),
+      writeFile: vi.fn(),
+      rm: vi.fn(),
+      cp: vi.fn(),
+      readFile: vi.fn(),
+      lstat: vi.fn(),
+      chmod: vi.fn(),
+    },
+  };
+});
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    KeychainTokenStorage: vi.fn(),
+    debugLogger: {
+      warn: vi.fn(),
+      error: vi.fn(),
+      log: vi.fn(),
+    },
+    coreEvents: {
+      emitFeedback: vi.fn(),
+      on: vi.fn(),
+      off: vi.fn(),
+      emitConsoleLog: vi.fn(),
+    },
+    loadSkillsFromDir: vi.fn().mockResolvedValue([]),
+    loadAgentsFromDirectory: vi
+      .fn()
+      .mockResolvedValue({ agents: [], errors: [] }),
+    logExtensionInstallEvent: vi.fn().mockResolvedValue(undefined),
+    logExtensionUpdateEvent: vi.fn().mockResolvedValue(undefined),
+    logExtensionUninstall: vi.fn().mockResolvedValue(undefined),
+    logExtensionEnable: vi.fn().mockResolvedValue(undefined),
+    logExtensionDisable: vi.fn().mockResolvedValue(undefined),
+    Config: vi.fn().mockImplementation(() => ({
+      getEnableExtensionReloading: vi.fn().mockReturnValue(true),
+    })),
+    KeychainService: class {
+      isAvailable = vi.fn().mockResolvedValue(true);
+      getPassword = vi.fn().mockResolvedValue('test-key');
+      setPassword = vi.fn().mockResolvedValue(undefined);
+    },
+    ExtensionIntegrityManager: class {
+      verify = vi.fn().mockResolvedValue('verified');
+      store = vi.fn().mockResolvedValue(undefined);
+    },
+    IntegrityDataStatus: {
+      VERIFIED: 'verified',
+      MISSING: 'missing',
+      INVALID: 'invalid',
+    },
+  };
+});
+
+vi.mock('./consent.js', () => ({
+  maybeRequestConsentOrFail: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('./extensionSettings.js', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('./extensionSettings.js')>();
+  return {
+    ...actual,
+    getEnvContents: vi.fn().mockResolvedValue({}),
+    getMissingSettings: vi.fn(), // We will mock this implementation per test
+  };
+});
+
+vi.mock('../trustedFolders.js', () => ({
+  isWorkspaceTrusted: vi.fn().mockReturnValue({ isTrusted: true }), // Default to trusted to simplify flow
+  loadTrustedFolders: vi.fn().mockReturnValue({
+    setValue: vi.fn().mockResolvedValue(undefined),
+  }),
+  TrustLevel: { TRUST_FOLDER: 'TRUST_FOLDER' },
+}));
+
+// Mock ExtensionStorage to avoid real FS paths
+vi.mock('./storage.js', () => ({
+  ExtensionStorage: class {
+    constructor(public name: string) {}
+    getExtensionDir() {
+      return `/mock/extensions/${this.name}`;
+    }
+    static getUserExtensionsDir() {
+      return '/mock/extensions';
+    }
+    static createTmpDir() {
+      return Promise.resolve('/mock/tmp');
+    }
+  },
+}));
+
+vi.mock('os', async (importOriginal) => {
+  const mockedOs = await importOriginal<typeof import('node:os')>();
+  return {
+    ...mockedOs,
+    homedir: vi.fn().mockReturnValue('/mock/home'),
+  };
+});
+
+describe('extensionUpdates', () => {
+  let tempWorkspaceDir: string;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Default fs mocks
+    vi.mocked(fs.promises.mkdir).mockResolvedValue(undefined);
+    vi.mocked(fs.promises.writeFile).mockResolvedValue(undefined);
+    vi.mocked(fs.promises.rm).mockResolvedValue(undefined);
+    vi.mocked(fs.promises.cp).mockResolvedValue(undefined);
+    vi.mocked(fs.promises.readdir).mockResolvedValue([]);
+    vi.mocked(fs.promises.lstat).mockResolvedValue({
+      isDirectory: () => true,
+      mode: 0o755,
+    } as unknown as fs.Stats);
+    vi.mocked(fs.promises.chmod).mockResolvedValue(undefined);
+    vi.mocked(isWorkspaceTrusted).mockReturnValue({
+      isTrusted: true,
+      source: 'file',
+    });
+    vi.mocked(getMissingSettings).mockResolvedValue([]);
+
+    // Allow directories to exist by default to satisfy Config/WorkspaceContext checks
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.statSync).mockReturnValue({
+      isDirectory: () => true,
+    } as unknown as fs.Stats);
+    vi.mocked(fs.lstatSync).mockReturnValue({
+      isDirectory: () => true,
+    } as unknown as fs.Stats);
+    vi.mocked(fs.realpathSync).mockImplementation((p) => p as string);
+
+    tempWorkspaceDir = '/mock/workspace';
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('ExtensionManager integration', () => {
+    it('should warn about missing settings after update', async () => {
+      // 1. Setup Data
+      const newConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.1.0',
+        settings: [{ name: 's1', description: 'd1', envVar: 'VAR1' }],
+      };
+
+      const previousConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+        settings: [],
+      };
+
+      const installMetadata: ExtensionInstallMetadata = {
+        source: '/mock/source',
+        type: 'local',
+        autoUpdate: true,
+      };
+
+      // 2. Setup Manager
+      const manager = new ExtensionManager({
+        workspaceDir: tempWorkspaceDir,
+        settings: createTestMergedSettings({
+          telemetry: { enabled: false },
+          experimental: { extensionConfig: true },
+        }),
+        requestConsent: vi.fn().mockResolvedValue(true),
+        requestSetting: null,
+      });
+
+      // 3. Mock Internal Manager Methods
+      vi.spyOn(manager, 'loadExtensionConfig').mockResolvedValue(newConfig);
+      vi.spyOn(manager, 'getExtensions').mockReturnValue([
+        {
+          name: 'test-ext',
+          version: '1.0.0',
+          installMetadata,
+          path: '/mock/extensions/test-ext',
+          contextFiles: [],
+          mcpServers: {},
+          hooks: undefined,
+          isActive: true,
+          id: 'test-id',
+          settings: [],
+          resolvedSettings: [],
+          skills: [],
+        } as unknown as GeminiCLIExtension,
+      ]);
+      vi.spyOn(manager, 'uninstallExtension').mockResolvedValue(undefined);
+      // Mock loadExtension to return something so the method doesn't crash at the end
+      vi.spyOn(manager, 'loadExtension').mockResolvedValue({
+        name: 'test-ext',
+        version: '1.1.0',
+      } as unknown as GeminiCLIExtension);
+
+      // 4. Mock External Helpers
+      // This is the key fix: we explicitly mock `getMissingSettings` to return
+      // the result we expect, avoiding any real FS or logic execution during the update.
+      vi.mocked(getMissingSettings).mockResolvedValue([
+        {
+          name: 's1',
+          description: 'd1',
+          envVar: 'VAR1',
+        },
+      ]);
+
+      // 5. Execute
+      await manager.installOrUpdateExtension(installMetadata, previousConfig);
+
+      // 6. Assert
+      expect(debugLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'Extension "test-ext" has missing settings: s1',
+        ),
+      );
+      expect(coreEvents.emitFeedback).toHaveBeenCalledWith(
+        'warning',
+        expect.stringContaining(
+          'Please run "gemini extensions config test-ext [setting-name]"',
+        ),
+      );
+    });
+
+    it('should store integrity data after update', async () => {
+      const newConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.1.0',
+      };
+
+      const previousConfig: ExtensionConfig = {
+        name: 'test-ext',
+        version: '1.0.0',
+      };
+
+      const installMetadata: ExtensionInstallMetadata = {
+        source: '/mock/source',
+        type: 'local',
+      };
+
+      const manager = new ExtensionManager({
+        workspaceDir: tempWorkspaceDir,
+        settings: createTestMergedSettings(),
+        requestConsent: vi.fn().mockResolvedValue(true),
+        requestSetting: null,
+      });
+
+      await manager.loadExtensions();
+      vi.spyOn(manager, 'loadExtensionConfig').mockResolvedValue(newConfig);
+      vi.spyOn(manager, 'getExtensions').mockReturnValue([
+        {
+          name: 'test-ext',
+          version: '1.0.0',
+          installMetadata,
+          path: '/mock/extensions/test-ext',
+          isActive: true,
+        } as unknown as GeminiCLIExtension,
+      ]);
+      vi.spyOn(manager, 'uninstallExtension').mockResolvedValue(undefined);
+      vi.spyOn(manager, 'loadExtension').mockResolvedValue({
+        name: 'test-ext',
+        version: '1.1.0',
+      } as unknown as GeminiCLIExtension);
+
+      const storeSpy = vi.spyOn(manager, 'storeExtensionIntegrity');
+
+      await manager.installOrUpdateExtension(installMetadata, previousConfig);
+
+      expect(storeSpy).toHaveBeenCalledWith('test-ext', installMetadata);
+    });
+  });
+});

packages/cli/src/config/extensions/github.test.ts

@@ -0,0 +1,654 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  cloneFromGit,
+  tryParseGithubUrl,
+  fetchReleaseFromGithub,
+  checkForExtensionUpdate,
+  downloadFromGitHubRelease,
+  findReleaseAsset,
+  downloadFile,
+  extractFile,
+} from './github.js';
+import { simpleGit, type SimpleGit } from 'simple-git';
+import { ExtensionUpdateState } from '../../ui/state/extensions.js';
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+import * as https from 'node:https';
+import * as tar from 'tar';
+import * as extract from 'extract-zip';
+import type { ExtensionManager } from '../extension-manager.js';
+import { fetchJson } from './github_fetch.js';
+import { EventEmitter } from 'node:events';
+import type {
+  GeminiCLIExtension,
+  ExtensionInstallMetadata,
+} from '@google/gemini-cli-core';
+import type { ExtensionConfig } from '../extension.js';
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    Storage: {
+      getGlobalSettingsPath: vi.fn().mockReturnValue('/mock/settings.json'),
+      getGlobalGeminiDir: vi.fn().mockReturnValue('/mock/.gemini'),
+    },
+    debugLogger: {
+      error: vi.fn(),
+      log: vi.fn(),
+      warn: vi.fn(),
+    },
+  };
+});
+
+vi.mock('simple-git');
+vi.mock('node:os');
+vi.mock('node:fs');
+vi.mock('node:https');
+vi.mock('tar');
+vi.mock('extract-zip');
+vi.mock('./github_fetch.js');
+vi.mock('../extension-manager.js');
+// Mock settings.ts to avoid top-level side effects if possible, or just rely on Storage mock
+vi.mock('../settings.js', () => ({
+  loadSettings: vi.fn(),
+  USER_SETTINGS_PATH: '/mock/settings.json',
+}));
+
+describe('github.ts', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  describe('cloneFromGit', () => {
+    let mockGit: {
+      clone: ReturnType<typeof vi.fn>;
+      getRemotes: ReturnType<typeof vi.fn>;
+      fetch: ReturnType<typeof vi.fn>;
+      checkout: ReturnType<typeof vi.fn>;
+      listRemote: ReturnType<typeof vi.fn>;
+      revparse: ReturnType<typeof vi.fn>;
+      env: ReturnType<typeof vi.fn>;
+    };
+
+    beforeEach(() => {
+      mockGit = {
+        clone: vi.fn(),
+        getRemotes: vi.fn(),
+        fetch: vi.fn(),
+        checkout: vi.fn(),
+        listRemote: vi.fn(),
+        revparse: vi.fn(),
+        env: vi.fn().mockReturnThis(),
+      };
+      vi.mocked(simpleGit).mockReturnValue(mockGit as unknown as SimpleGit);
+    });
+
+    it('should clone, fetch and checkout a repo', async () => {
+      mockGit.getRemotes.mockResolvedValue([{ name: 'origin' }]);
+
+      await cloneFromGit(
+        {
+          type: 'git',
+          source: 'https://github.com/owner/repo.git',
+          ref: 'v1.0.0',
+        },
+        '/dest',
+      );
+
+      expect(mockGit.clone).toHaveBeenCalledWith(
+        'https://github.com/owner/repo.git',
+        './',
+        ['--depth', '1'],
+      );
+      expect(mockGit.fetch).toHaveBeenCalledWith('origin', 'v1.0.0');
+      expect(mockGit.checkout).toHaveBeenCalledWith('FETCH_HEAD');
+    });
+
+    it('should throw if no remotes found', async () => {
+      mockGit.getRemotes.mockResolvedValue([]);
+
+      await expect(
+        cloneFromGit({ type: 'git', source: 'src' }, '/dest'),
+      ).rejects.toThrow('Unable to find any remotes');
+    });
+
+    it('should throw on clone error', async () => {
+      mockGit.clone.mockRejectedValue(new Error('Clone failed'));
+
+      await expect(
+        cloneFromGit({ type: 'git', source: 'src' }, '/dest'),
+      ).rejects.toThrow('Failed to clone Git repository');
+    });
+  });
+
+  describe('tryParseGithubUrl', () => {
+    it.each([
+      ['https://github.com/owner/repo', 'owner', 'repo'],
+      ['https://github.com/owner/repo.git', 'owner', 'repo'],
+      ['git@github.com:owner/repo.git', 'owner', 'repo'],
+      ['owner/repo', 'owner', 'repo'],
+    ])('should parse %s to %s/%s', (url, owner, repo) => {
+      expect(tryParseGithubUrl(url)).toEqual({ owner, repo });
+    });
+
+    it.each([
+      'https://gitlab.com/owner/repo',
+      'https://my-git-host.com/owner/group/repo',
+      'git@gitlab.com:some-group/some-project/some-repo.git',
+    ])('should return null for non-GitHub URLs', (url) => {
+      expect(tryParseGithubUrl(url)).toBeNull();
+    });
+
+    it('should throw for invalid formats', () => {
+      expect(() => tryParseGithubUrl('invalid')).toThrow(
+        'Invalid GitHub repository source',
+      );
+    });
+  });
+
+  describe('fetchReleaseFromGithub', () => {
+    it('should fetch latest release if no ref provided', async () => {
+      vi.mocked(fetchJson).mockResolvedValue({ tag_name: 'v1.0.0' });
+
+      await fetchReleaseFromGithub('owner', 'repo');
+
+      expect(fetchJson).toHaveBeenCalledWith(
+        'https://api.github.com/repos/owner/repo/releases/latest',
+      );
+    });
+
+    it('should fetch specific ref if provided', async () => {
+      vi.mocked(fetchJson).mockResolvedValue({ tag_name: 'v1.0.0' });
+
+      await fetchReleaseFromGithub('owner', 'repo', 'v1.0.0');
+
+      expect(fetchJson).toHaveBeenCalledWith(
+        'https://api.github.com/repos/owner/repo/releases/tags/v1.0.0',
+      );
+    });
+
+    it('should handle pre-releases if allowed', async () => {
+      vi.mocked(fetchJson).mockResolvedValueOnce([{ tag_name: 'v1.0.0-beta' }]);
+
+      const result = await fetchReleaseFromGithub(
+        'owner',
+        'repo',
+        undefined,
+        true,
+      );
+
+      expect(result).toEqual({ tag_name: 'v1.0.0-beta' });
+    });
+
+    it('should return null if no releases found', async () => {
+      vi.mocked(fetchJson).mockResolvedValueOnce([]);
+
+      const result = await fetchReleaseFromGithub(
+        'owner',
+        'repo',
+        undefined,
+        true,
+      );
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('checkForExtensionUpdate', () => {
+    let mockExtensionManager: ExtensionManager;
+    let mockGit: {
+      getRemotes: ReturnType<typeof vi.fn>;
+      listRemote: ReturnType<typeof vi.fn>;
+      revparse: ReturnType<typeof vi.fn>;
+      env: ReturnType<typeof vi.fn>;
+    };
+
+    beforeEach(() => {
+      mockExtensionManager = {
+        loadExtensionConfig: vi.fn(),
+      } as unknown as ExtensionManager;
+      mockGit = {
+        getRemotes: vi.fn(),
+        listRemote: vi.fn(),
+        revparse: vi.fn(),
+        env: vi.fn().mockReturnThis(),
+      };
+      vi.mocked(simpleGit).mockReturnValue(mockGit as unknown as SimpleGit);
+    });
+
+    it('should return NOT_UPDATABLE for non-git/non-release extensions', async () => {
+      vi.mocked(mockExtensionManager.loadExtensionConfig).mockReturnValue(
+        Promise.resolve({
+          version: '1.0.0',
+        } as unknown as ExtensionConfig),
+      );
+
+      const linkExt = {
+        installMetadata: { type: 'link' },
+      } as unknown as GeminiCLIExtension;
+      expect(await checkForExtensionUpdate(linkExt, mockExtensionManager)).toBe(
+        ExtensionUpdateState.NOT_UPDATABLE,
+      );
+    });
+
+    it('should return UPDATE_AVAILABLE if git remote hash differs', async () => {
+      mockGit.getRemotes.mockResolvedValue([
+        { name: 'origin', refs: { fetch: 'url' } },
+      ]);
+      mockGit.listRemote.mockResolvedValue('remote-hash\tHEAD');
+      mockGit.revparse.mockResolvedValue('local-hash');
+
+      const ext = {
+        path: '/path',
+        installMetadata: { type: 'git', source: 'url' },
+      } as unknown as GeminiCLIExtension;
+      expect(await checkForExtensionUpdate(ext, mockExtensionManager)).toBe(
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+      );
+    });
+
+    it('should return UP_TO_DATE if git remote hash matches', async () => {
+      mockGit.getRemotes.mockResolvedValue([
+        { name: 'origin', refs: { fetch: 'url' } },
+      ]);
+      mockGit.listRemote.mockResolvedValue('hash\tHEAD');
+      mockGit.revparse.mockResolvedValue('hash');
+
+      const ext = {
+        path: '/path',
+        installMetadata: { type: 'git', source: 'url' },
+      } as unknown as GeminiCLIExtension;
+      expect(await checkForExtensionUpdate(ext, mockExtensionManager)).toBe(
+        ExtensionUpdateState.UP_TO_DATE,
+      );
+    });
+
+    it('should return NOT_UPDATABLE if local extension config cannot be loaded', async () => {
+      vi.mocked(mockExtensionManager.loadExtensionConfig).mockImplementation(
+        async () => {
+          throw new Error('Config not found');
+        },
+      );
+
+      const ext = {
+        name: 'local-ext',
+        version: '1.0.0',
+        path: '/path/to/installed/ext',
+        installMetadata: { type: 'local', source: '/path/to/source/ext' },
+      } as unknown as GeminiCLIExtension;
+
+      expect(await checkForExtensionUpdate(ext, mockExtensionManager)).toBe(
+        ExtensionUpdateState.NOT_UPDATABLE,
+      );
+    });
+
+    it('should check migratedTo source if present and return UPDATE_AVAILABLE', async () => {
+      mockGit.getRemotes.mockResolvedValue([
+        { name: 'origin', refs: { fetch: 'new-url' } },
+      ]);
+      mockGit.listRemote.mockResolvedValue('hash\tHEAD');
+      mockGit.revparse.mockResolvedValue('hash');
+
+      const ext = {
+        path: '/path',
+        migratedTo: 'new-url',
+        installMetadata: { type: 'git', source: 'old-url' },
+      } as unknown as GeminiCLIExtension;
+      expect(await checkForExtensionUpdate(ext, mockExtensionManager)).toBe(
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+      );
+    });
+  });
+
+  describe('downloadFromGitHubRelease', () => {
+    it('should fail if no release data found', async () => {
+      // Mock fetchJson to throw for latest release check
+      vi.mocked(fetchJson).mockRejectedValue(new Error('Not found'));
+
+      const result = await downloadFromGitHubRelease(
+        {
+          type: 'github-release',
+          source: 'owner/repo',
+          ref: 'v1',
+        } as unknown as ExtensionInstallMetadata,
+        '/dest',
+        { owner: 'owner', repo: 'repo' },
+      );
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.failureReason).toBe('failed to fetch release data');
+      }
+    });
+
+    it('should use correct headers for release assets', async () => {
+      vi.mocked(fetchJson).mockResolvedValue({
+        tag_name: 'v1.0.0',
+        assets: [{ name: 'asset.tar.gz', url: 'http://asset.url' }],
+      });
+      vi.mocked(os.platform).mockReturnValue('linux');
+      vi.mocked(os.arch).mockReturnValue('x64');
+
+      // Mock https.get and fs.createWriteStream for downloadFile
+      const mockReq = new EventEmitter();
+      const mockRes =
+        new EventEmitter() as unknown as import('node:http').IncomingMessage;
+      Object.assign(mockRes, { statusCode: 200, pipe: vi.fn() });
+
+      vi.mocked(https.get).mockImplementation((url, options, cb) => {
+        if (typeof options === 'function') {
+          cb = options;
+        }
+        if (cb) cb(mockRes);
+        return mockReq as unknown as import('node:http').ClientRequest;
+      });
+
+      const mockStream = new EventEmitter() as unknown as fs.WriteStream;
+      Object.assign(mockStream, { close: vi.fn((cb) => cb && cb()) });
+      vi.mocked(fs.createWriteStream).mockReturnValue(mockStream);
+
+      // Mock fs.promises.readdir to return empty array (no cleanup needed)
+      vi.mocked(fs.promises.readdir).mockResolvedValue([]);
+      // Mock fs.promises.unlink
+      vi.mocked(fs.promises.unlink).mockResolvedValue(undefined);
+
+      const promise = downloadFromGitHubRelease(
+        {
+          type: 'github-release',
+          source: 'owner/repo',
+          ref: 'v1.0.0',
+        } as unknown as ExtensionInstallMetadata,
+        '/dest',
+        { owner: 'owner', repo: 'repo' },
+      );
+
+      // Wait for downloadFile to be called and stream to be created
+      await vi.waitUntil(
+        () => vi.mocked(fs.createWriteStream).mock.calls.length > 0,
+      );
+
+      // Trigger stream events to complete download
+      mockRes.emit('end');
+      mockStream.emit('finish');
+
+      await promise;
+
+      expect(https.get).toHaveBeenCalledWith(
+        'http://asset.url',
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Accept: 'application/octet-stream',
+          }),
+        }),
+        expect.anything(),
+      );
+    });
+
+    it('should use correct headers for source tarballs', async () => {
+      vi.mocked(fetchJson).mockResolvedValue({
+        tag_name: 'v1.0.0',
+        assets: [],
+        tarball_url: 'http://tarball.url',
+      });
+
+      // Mock https.get and fs.createWriteStream for downloadFile
+      const mockReq = new EventEmitter();
+      const mockRes =
+        new EventEmitter() as unknown as import('node:http').IncomingMessage;
+      Object.assign(mockRes, { statusCode: 200, pipe: vi.fn() });
+
+      vi.mocked(https.get).mockImplementation((url, options, cb) => {
+        if (typeof options === 'function') {
+          cb = options;
+        }
+        if (cb) cb(mockRes);
+        return mockReq as unknown as import('node:http').ClientRequest;
+      });
+
+      const mockStream = new EventEmitter() as unknown as fs.WriteStream;
+      Object.assign(mockStream, { close: vi.fn((cb) => cb && cb()) });
+      vi.mocked(fs.createWriteStream).mockReturnValue(mockStream);
+
+      // Mock fs.promises.readdir to return empty array
+      vi.mocked(fs.promises.readdir).mockResolvedValue([]);
+      // Mock fs.promises.unlink
+      vi.mocked(fs.promises.unlink).mockResolvedValue(undefined);
+
+      const promise = downloadFromGitHubRelease(
+        {
+          type: 'github-release',
+          source: 'owner/repo',
+          ref: 'v1.0.0',
+        } as unknown as ExtensionInstallMetadata,
+        '/dest',
+        { owner: 'owner', repo: 'repo' },
+      );
+
+      // Wait for downloadFile to be called and stream to be created
+      await vi.waitUntil(
+        () => vi.mocked(fs.createWriteStream).mock.calls.length > 0,
+      );
+
+      // Trigger stream events to complete download
+      mockRes.emit('end');
+      mockStream.emit('finish');
+
+      await promise;
+
+      expect(https.get).toHaveBeenCalledWith(
+        'http://tarball.url',
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Accept: 'application/vnd.github+json',
+          }),
+        }),
+        expect.anything(),
+      );
+    });
+  });
+
+  describe('findReleaseAsset', () => {
+    it('should find platform/arch specific asset', () => {
+      vi.mocked(os.platform).mockReturnValue('darwin');
+      vi.mocked(os.arch).mockReturnValue('arm64');
+      const assets = [
+        { name: 'darwin.arm64.tar.gz', url: 'url1' },
+        { name: 'linux.x64.tar.gz', url: 'url2' },
+      ];
+      expect(findReleaseAsset(assets)).toEqual(assets[0]);
+    });
+
+    it('should find generic asset', () => {
+      vi.mocked(os.platform).mockReturnValue('darwin');
+      const assets = [{ name: 'generic.tar.gz', url: 'url' }];
+      expect(findReleaseAsset(assets)).toEqual(assets[0]);
+    });
+  });
+
+  describe('downloadFile', () => {
+    it('should download file successfully', async () => {
+      const mockReq = new EventEmitter();
+      const mockRes =
+        new EventEmitter() as unknown as import('node:http').IncomingMessage;
+      Object.assign(mockRes, { statusCode: 200, pipe: vi.fn() });
+
+      vi.mocked(https.get).mockImplementation((url, options, cb) => {
+        if (typeof options === 'function') {
+          cb = options;
+        }
+        if (cb) cb(mockRes);
+        return mockReq as unknown as import('node:http').ClientRequest;
+      });
+
+      const mockStream = new EventEmitter() as unknown as fs.WriteStream;
+      Object.assign(mockStream, { close: vi.fn((cb) => cb && cb()) });
+      vi.mocked(fs.createWriteStream).mockReturnValue(mockStream);
+
+      const promise = downloadFile('url', '/dest');
+      mockRes.emit('end');
+      mockStream.emit('finish');
+
+      await expect(promise).resolves.toBeUndefined();
+    });
+
+    it('should fail on non-200 status', async () => {
+      const mockReq = new EventEmitter();
+      const mockRes =
+        new EventEmitter() as unknown as import('node:http').IncomingMessage;
+      Object.assign(mockRes, { statusCode: 404 });
+
+      vi.mocked(https.get).mockImplementation((url, options, cb) => {
+        if (typeof options === 'function') {
+          cb = options;
+        }
+        if (cb) cb(mockRes);
+        return mockReq as unknown as import('node:http').ClientRequest;
+      });
+
+      await expect(downloadFile('url', '/dest')).rejects.toThrow(
+        'Request failed with status code 404',
+      );
+    });
+
+    it('should follow redirects', async () => {
+      const mockReq = new EventEmitter();
+      const mockResRedirect =
+        new EventEmitter() as unknown as import('node:http').IncomingMessage;
+      Object.assign(mockResRedirect, {
+        statusCode: 302,
+        headers: { location: 'new-url' },
+      });
+
+      const mockResSuccess =
+        new EventEmitter() as unknown as import('node:http').IncomingMessage;
+      Object.assign(mockResSuccess, { statusCode: 200, pipe: vi.fn() });
+
+      vi.mocked(https.get)
+        .mockImplementationOnce((url, options, cb) => {
+          if (typeof options === 'function') cb = options;
+          if (cb) cb(mockResRedirect);
+          return mockReq as unknown as import('node:http').ClientRequest;
+        })
+        .mockImplementationOnce((url, options, cb) => {
+          if (typeof options === 'function') cb = options;
+          if (cb) cb(mockResSuccess);
+          return mockReq as unknown as import('node:http').ClientRequest;
+        });
+
+      const mockStream = new EventEmitter() as unknown as fs.WriteStream;
+      Object.assign(mockStream, { close: vi.fn((cb) => cb && cb()) });
+      vi.mocked(fs.createWriteStream).mockReturnValue(mockStream);
+
+      const promise = downloadFile('url', '/dest');
+      mockResSuccess.emit('end');
+      mockStream.emit('finish');
+
+      await expect(promise).resolves.toBeUndefined();
+      expect(https.get).toHaveBeenCalledTimes(2);
+      expect(https.get).toHaveBeenLastCalledWith(
+        'new-url',
+        expect.anything(),
+        expect.anything(),
+      );
+    });
+
+    it('should fail after too many redirects', async () => {
+      const mockReq = new EventEmitter();
+      const mockResRedirect =
+        new EventEmitter() as unknown as import('node:http').IncomingMessage;
+      Object.assign(mockResRedirect, {
+        statusCode: 302,
+        headers: { location: 'new-url' },
+      });
+
+      vi.mocked(https.get).mockImplementation((url, options, cb) => {
+        if (typeof options === 'function') cb = options;
+        if (cb) cb(mockResRedirect);
+        return mockReq as unknown as import('node:http').ClientRequest;
+      });
+
+      await expect(downloadFile('url', '/dest')).rejects.toThrow(
+        'Too many redirects',
+      );
+    }, 10000); // Increase timeout for this test if needed, though with mocks it should be fast
+
+    it('should fail if redirect location is missing', async () => {
+      const mockReq = new EventEmitter();
+      const mockResRedirect =
+        new EventEmitter() as unknown as import('node:http').IncomingMessage;
+      Object.assign(mockResRedirect, {
+        statusCode: 302,
+        headers: {}, // No location
+      });
+
+      vi.mocked(https.get).mockImplementation((url, options, cb) => {
+        if (typeof options === 'function') cb = options;
+        if (cb) cb(mockResRedirect);
+        return mockReq as unknown as import('node:http').ClientRequest;
+      });
+
+      await expect(downloadFile('url', '/dest')).rejects.toThrow(
+        'Redirect response missing Location header',
+      );
+    });
+
+    it('should pass custom headers', async () => {
+      const mockReq = new EventEmitter();
+      const mockRes =
+        new EventEmitter() as unknown as import('node:http').IncomingMessage;
+      Object.assign(mockRes, { statusCode: 200, pipe: vi.fn() });
+
+      vi.mocked(https.get).mockImplementation((url, options, cb) => {
+        if (typeof options === 'function') cb = options;
+        if (cb) cb(mockRes);
+        return mockReq as unknown as import('node:http').ClientRequest;
+      });
+
+      const mockStream = new EventEmitter() as unknown as fs.WriteStream;
+      Object.assign(mockStream, { close: vi.fn((cb) => cb && cb()) });
+      vi.mocked(fs.createWriteStream).mockReturnValue(mockStream);
+
+      const promise = downloadFile('url', '/dest', {
+        headers: { 'X-Custom': 'value' },
+      });
+      mockRes.emit('end');
+      mockStream.emit('finish');
+
+      await expect(promise).resolves.toBeUndefined();
+      expect(https.get).toHaveBeenCalledWith(
+        'url',
+        expect.objectContaining({
+          headers: expect.objectContaining({ 'X-Custom': 'value' }),
+        }),
+        expect.anything(),
+      );
+    });
+  });
+
+  describe('extractFile', () => {
+    it('should extract tar.gz using tar', async () => {
+      await extractFile('file.tar.gz', '/dest');
+      expect(tar.x).toHaveBeenCalled();
+    });
+
+    it('should extract zip using extract-zip', async () => {
+      vi.mocked(extract.default || extract).mockResolvedValue(undefined);
+      await extractFile('file.zip', '/dest');
+      // Check if extract was called. Note: extract-zip export might be default or named depending on mock
+    });
+
+    it('should throw for unsupported extensions', async () => {
+      await expect(extractFile('file.txt', '/dest')).rejects.toThrow(
+        'Unsupported file extension',
+      );
+    });
+  });
+});

packages/cli/src/config/extensions/github.ts

@@ -0,0 +1,576 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { simpleGit } from 'simple-git';
+import {
+  debugLogger,
+  getErrorMessage,
+  getSafeGitEnv,
+  type ExtensionInstallMetadata,
+  type GeminiCLIExtension,
+} from '@google/gemini-cli-core';
+import { ExtensionUpdateState } from '../../ui/state/extensions.js';
+import * as os from 'node:os';
+import * as https from 'node:https';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as tar from 'tar';
+import extract from 'extract-zip';
+import { fetchJson, getGitHubToken } from './github_fetch.js';
+import type { ExtensionConfig } from '../extension.js';
+import type { ExtensionManager } from '../extension-manager.js';
+import { EXTENSIONS_CONFIG_FILENAME } from './variables.js';
+
+/**
+ * Clones a Git repository to a specified local path.
+ * @param installMetadata The metadata for the extension to install.
+ * @param destination The destination path to clone the repository to.
+ */
+export async function cloneFromGit(
+  installMetadata: ExtensionInstallMetadata,
+  destination: string,
+): Promise<void> {
+  try {
+    const git = simpleGit(destination).env(getSafeGitEnv());
+    let sourceUrl = installMetadata.source;
+    const token = getGitHubToken();
+    if (token) {
+      try {
+        const parsedUrl = new URL(sourceUrl);
+        if (
+          parsedUrl.protocol === 'https:' &&
+          parsedUrl.hostname === 'github.com'
+        ) {
+          if (!parsedUrl.username) {
+            parsedUrl.username = token;
+          }
+          sourceUrl = parsedUrl.toString();
+        }
+      } catch {
+        // If source is not a valid URL, we don't inject the token.
+        // We let git handle the source as is.
+      }
+    }
+    await git.clone(sourceUrl, './', ['--depth', '1']);
+
+    const remotes = await git.getRemotes(true);
+    if (remotes.length === 0) {
+      throw new Error(
+        `Unable to find any remotes for repo ${installMetadata.source}`,
+      );
+    }
+
+    const refToFetch = installMetadata.ref || 'HEAD';
+
+    await git.fetch(remotes[0].name, refToFetch);
+
+    // After fetching, checkout FETCH_HEAD to get the content of the fetched ref.
+    // This results in a detached HEAD state, which is fine for this purpose.
+    await git.checkout('FETCH_HEAD');
+  } catch (error) {
+    throw new Error(
+      `Failed to clone Git repository from ${installMetadata.source} ${getErrorMessage(error)}`,
+      {
+        cause: error,
+      },
+    );
+  }
+}
+
+export interface GithubRepoInfo {
+  owner: string;
+  repo: string;
+}
+
+export function tryParseGithubUrl(source: string): GithubRepoInfo | null {
+  // Handle SCP-style SSH URLs.
+  if (source.startsWith('git@')) {
+    if (source.startsWith('git@github.com:')) {
+      // It's a GitHub SSH URL, so normalize it for the URL parser.
+      source = source.replace('git@github.com:', '');
+    } else {
+      // It's another provider's SSH URL (e.g., gitlab), so not a GitHub repo.
+      return null;
+    }
+  }
+  // Default to a github repo path, so `source` can be just an org/repo
+  let parsedUrl: URL;
+  try {
+    // Use the standard URL constructor for backward compatibility.
+    parsedUrl = new URL(source, 'https://github.com');
+  } catch (e) {
+    // Throw a TypeError to maintain a consistent error contract for invalid URLs.
+    // This avoids a breaking change for consumers who might expect a TypeError.
+    throw new TypeError(`Invalid repo URL: ${source}`, { cause: e });
+  }
+
+  if (!parsedUrl) {
+    throw new Error(`Invalid repo URL: ${source}`);
+  }
+  if (parsedUrl?.host !== 'github.com') {
+    return null;
+  }
+  // The pathname should be "/owner/repo".
+  const parts = parsedUrl?.pathname
+    .split('/')
+    // Remove the empty segments, fixes trailing and leading slashes
+    .filter((part) => part !== '');
+
+  if (parts?.length !== 2) {
+    throw new Error(
+      `Invalid GitHub repository source: ${source}. Expected "owner/repo" or a github repo uri.`,
+    );
+  }
+  const owner = parts[0];
+  const repo = parts[1].replace('.git', '');
+
+  return {
+    owner,
+    repo,
+  };
+}
+
+export async function fetchReleaseFromGithub(
+  owner: string,
+  repo: string,
+  ref?: string,
+  allowPreRelease?: boolean,
+): Promise<GithubReleaseData | null> {
+  if (ref) {
+    return fetchJson(
+      `https://api.github.com/repos/${owner}/${repo}/releases/tags/${ref}`,
+    );
+  }
+
+  if (!allowPreRelease) {
+    // Grab the release that is tagged as the "latest", github does not allow
+    // this to be a pre-release so we can blindly grab it.
+    try {
+      return await fetchJson(
+        `https://api.github.com/repos/${owner}/${repo}/releases/latest`,
+      );
+    } catch {
+      // This can fail if there is no release marked latest. In that case
+      // we want to just try the pre-release logic below.
+    }
+  }
+
+  // If pre-releases are allowed, we just grab the most recent release.
+  const releases = await fetchJson<GithubReleaseData[]>(
+    `https://api.github.com/repos/${owner}/${repo}/releases?per_page=1`,
+  );
+  if (releases.length === 0) {
+    return null;
+  }
+  return releases[0];
+}
+
+export async function checkForExtensionUpdate(
+  extension: GeminiCLIExtension,
+  extensionManager: ExtensionManager,
+): Promise<ExtensionUpdateState> {
+  const installMetadata = extension.installMetadata;
+  if (installMetadata?.type === 'local') {
+    let latestConfig: ExtensionConfig | undefined;
+    try {
+      latestConfig = await extensionManager.loadExtensionConfig(
+        installMetadata.source,
+      );
+    } catch (e) {
+      debugLogger.warn(
+        `Failed to check for update for local extension "${extension.name}". Could not load extension from source path: ${installMetadata.source}. Error: ${getErrorMessage(e)}`,
+      );
+      return ExtensionUpdateState.NOT_UPDATABLE;
+    }
+
+    if (!latestConfig) {
+      debugLogger.warn(
+        `Failed to check for update for local extension "${extension.name}". Could not load extension from source path: ${installMetadata.source}`,
+      );
+      return ExtensionUpdateState.NOT_UPDATABLE;
+    }
+    if (latestConfig.version !== extension.version) {
+      return ExtensionUpdateState.UPDATE_AVAILABLE;
+    }
+    return ExtensionUpdateState.UP_TO_DATE;
+  }
+  if (
+    !installMetadata ||
+    (installMetadata.type !== 'git' &&
+      installMetadata.type !== 'github-release')
+  ) {
+    return ExtensionUpdateState.NOT_UPDATABLE;
+  }
+
+  if (extension.migratedTo) {
+    const migratedState = await checkForExtensionUpdate(
+      {
+        ...extension,
+        installMetadata: { ...installMetadata, source: extension.migratedTo },
+        migratedTo: undefined,
+      },
+      extensionManager,
+    );
+    if (
+      migratedState === ExtensionUpdateState.UPDATE_AVAILABLE ||
+      migratedState === ExtensionUpdateState.UP_TO_DATE
+    ) {
+      return ExtensionUpdateState.UPDATE_AVAILABLE;
+    }
+  }
+
+  try {
+    if (installMetadata.type === 'git') {
+      const git = simpleGit(extension.path).env(getSafeGitEnv());
+      const remotes = await git.getRemotes(true);
+      if (remotes.length === 0) {
+        debugLogger.error('No git remotes found.');
+        return ExtensionUpdateState.ERROR;
+      }
+      const remoteUrl = remotes[0].refs.fetch;
+      if (!remoteUrl) {
+        debugLogger.error(
+          `No fetch URL found for git remote ${remotes[0].name}.`,
+        );
+        return ExtensionUpdateState.ERROR;
+      }
+
+      // Determine the ref to check on the remote.
+      const refToCheck = installMetadata.ref || 'HEAD';
+
+      const lsRemoteOutput = await git.listRemote([remoteUrl, refToCheck]);
+
+      if (typeof lsRemoteOutput !== 'string' || lsRemoteOutput.trim() === '') {
+        debugLogger.error(`Git ref ${refToCheck} not found.`);
+        return ExtensionUpdateState.ERROR;
+      }
+
+      const remoteHash = lsRemoteOutput.split('\t')[0];
+      const localHash = await git.revparse(['HEAD']);
+
+      if (!remoteHash) {
+        debugLogger.error(
+          `Unable to parse hash from git ls-remote output "${lsRemoteOutput}"`,
+        );
+        return ExtensionUpdateState.ERROR;
+      }
+      if (remoteHash === localHash) {
+        return ExtensionUpdateState.UP_TO_DATE;
+      }
+      return ExtensionUpdateState.UPDATE_AVAILABLE;
+    } else {
+      const { source, releaseTag } = installMetadata;
+      if (!source) {
+        debugLogger.error(`No "source" provided for extension.`);
+        return ExtensionUpdateState.ERROR;
+      }
+      const repoInfo = tryParseGithubUrl(source);
+      if (!repoInfo) {
+        debugLogger.error(
+          `Source is not a valid GitHub repository for release checks: ${source}`,
+        );
+        return ExtensionUpdateState.ERROR;
+      }
+      const { owner, repo } = repoInfo;
+
+      const releaseData = await fetchReleaseFromGithub(
+        owner,
+        repo,
+        installMetadata.ref,
+        installMetadata.allowPreRelease,
+      );
+      if (!releaseData) {
+        return ExtensionUpdateState.ERROR;
+      }
+      if (releaseData.tag_name !== releaseTag) {
+        return ExtensionUpdateState.UPDATE_AVAILABLE;
+      }
+      return ExtensionUpdateState.UP_TO_DATE;
+    }
+  } catch (error) {
+    debugLogger.error(
+      `Failed to check for updates for extension "${installMetadata.source}": ${getErrorMessage(error)}`,
+    );
+    return ExtensionUpdateState.ERROR;
+  }
+}
+
+export type GitHubDownloadResult =
+  | {
+      tagName?: string;
+      type: 'git' | 'github-release';
+      success: false;
+      failureReason:
+        | 'failed to fetch release data'
+        | 'no release data'
+        | 'no release asset found'
+        | 'failed to download asset'
+        | 'failed to extract asset'
+        | 'unknown';
+      errorMessage: string;
+    }
+  | {
+      tagName?: string;
+      type: 'git' | 'github-release';
+      success: true;
+    };
+export async function downloadFromGitHubRelease(
+  installMetadata: ExtensionInstallMetadata,
+  destination: string,
+  githubRepoInfo: GithubRepoInfo,
+): Promise<GitHubDownloadResult> {
+  const { ref, allowPreRelease: preRelease } = installMetadata;
+  const { owner, repo } = githubRepoInfo;
+  let releaseData: GithubReleaseData | null = null;
+
+  try {
+    try {
+      releaseData = await fetchReleaseFromGithub(owner, repo, ref, preRelease);
+      if (!releaseData) {
+        return {
+          failureReason: 'no release data',
+          success: false,
+          type: 'github-release',
+          errorMessage: `No release data found for ${owner}/${repo} at tag ${ref}`,
+        };
+      }
+    } catch (error) {
+      return {
+        failureReason: 'failed to fetch release data',
+        success: false,
+        type: 'github-release',
+        errorMessage: `Failed to fetch release data for ${owner}/${repo} at tag ${ref}: ${getErrorMessage(error)}`,
+      };
+    }
+
+    const asset = findReleaseAsset(releaseData.assets);
+    let archiveUrl: string | undefined;
+    let isTar = false;
+    let isZip = false;
+    let fileName: string | undefined;
+
+    if (asset) {
+      archiveUrl = asset.url;
+      fileName = asset.name;
+    } else {
+      if (releaseData.tarball_url) {
+        archiveUrl = releaseData.tarball_url;
+        isTar = true;
+      } else if (releaseData.zipball_url) {
+        archiveUrl = releaseData.zipball_url;
+        isZip = true;
+      }
+    }
+    if (!archiveUrl) {
+      return {
+        failureReason: 'no release asset found',
+        success: false,
+        type: 'github-release',
+        tagName: releaseData.tag_name,
+        errorMessage: `No assets found for release with tag ${releaseData.tag_name}`,
+      };
+    }
+    if (!fileName) {
+      fileName = path.basename(new URL(archiveUrl).pathname);
+    }
+    let downloadedAssetPath = path.join(destination, fileName);
+    if (isTar && !downloadedAssetPath.endsWith('.tar.gz')) {
+      downloadedAssetPath += '.tar.gz';
+    } else if (isZip && !downloadedAssetPath.endsWith('.zip')) {
+      downloadedAssetPath += '.zip';
+    }
+
+    try {
+      // GitHub API requires different Accept headers for different types of downloads:
+      // 1. Binary Assets (e.g. release artifacts): Require 'application/octet-stream' to return the raw content.
+      // 2. Source Tarballs (e.g. /tarball/{ref}): Require 'application/vnd.github+json' (or similar) to return
+      //    a 302 Redirect to the actual download location (codeload.github.com).
+      //    Sending 'application/octet-stream' for tarballs results in a 415 Unsupported Media Type error.
+      const headers = {
+        ...(asset
+          ? { Accept: 'application/octet-stream' }
+          : { Accept: 'application/vnd.github+json' }),
+      };
+      await downloadFile(archiveUrl, downloadedAssetPath, { headers });
+    } catch (error) {
+      return {
+        failureReason: 'failed to download asset',
+        success: false,
+        type: 'github-release',
+        tagName: releaseData.tag_name,
+        errorMessage: `Failed to download asset from ${archiveUrl}: ${getErrorMessage(error)}`,
+      };
+    }
+
+    try {
+      await extractFile(downloadedAssetPath, destination);
+    } catch (error) {
+      return {
+        failureReason: 'failed to extract asset',
+        success: false,
+        type: 'github-release',
+        tagName: releaseData.tag_name,
+        errorMessage: `Failed to extract asset from ${downloadedAssetPath}: ${getErrorMessage(error)}`,
+      };
+    }
+
+    // For regular github releases, the repository is put inside of a top level
+    // directory. In this case we should see exactly two file in the destination
+    // dir, the archive and the directory. If we see that, validate that the
+    // dir has a gemini extension configuration file and then move all files
+    // from the directory up one level into the destination directory.
+    const entries = await fs.promises.readdir(destination, {
+      withFileTypes: true,
+    });
+    if (entries.length === 2) {
+      const lonelyDir = entries.find((entry) => entry.isDirectory());
+      if (
+        lonelyDir &&
+        fs.existsSync(
+          path.join(destination, lonelyDir.name, EXTENSIONS_CONFIG_FILENAME),
+        )
+      ) {
+        const dirPathToExtract = path.join(destination, lonelyDir.name);
+        const extractedDirFiles = await fs.promises.readdir(dirPathToExtract);
+        for (const file of extractedDirFiles) {
+          await fs.promises.rename(
+            path.join(dirPathToExtract, file),
+            path.join(destination, file),
+          );
+        }
+        await fs.promises.rmdir(dirPathToExtract);
+      }
+    }
+
+    await fs.promises.unlink(downloadedAssetPath);
+    return {
+      tagName: releaseData.tag_name,
+      type: 'github-release',
+      success: true,
+    };
+  } catch (error) {
+    return {
+      failureReason: 'unknown',
+      success: false,
+      type: 'github-release',
+      tagName: releaseData?.tag_name,
+      errorMessage: `Failed to download release from ${installMetadata.source}: ${getErrorMessage(error)}`,
+    };
+  }
+}
+
+interface GithubReleaseData {
+  assets: Asset[];
+  tag_name: string;
+  tarball_url?: string;
+  zipball_url?: string;
+}
+
+interface Asset {
+  name: string;
+  url: string;
+}
+
+export function findReleaseAsset(assets: Asset[]): Asset | undefined {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  const platformArchPrefix = `${platform}.${arch}.`;
+  const platformPrefix = `${platform}.`;
+
+  // Check for platform + architecture specific asset
+  const platformArchAsset = assets.find((asset) =>
+    asset.name.toLowerCase().startsWith(platformArchPrefix),
+  );
+  if (platformArchAsset) {
+    return platformArchAsset;
+  }
+
+  // Check for platform specific asset
+  const platformAsset = assets.find((asset) =>
+    asset.name.toLowerCase().startsWith(platformPrefix),
+  );
+  if (platformAsset) {
+    return platformAsset;
+  }
+
+  // Check for generic asset if only one is available
+  const genericAsset = assets.find(
+    (asset) =>
+      !asset.name.toLowerCase().includes('darwin') &&
+      !asset.name.toLowerCase().includes('linux') &&
+      !asset.name.toLowerCase().includes('win32'),
+  );
+  if (assets.length === 1) {
+    return genericAsset;
+  }
+
+  return undefined;
+}
+
+export interface DownloadOptions {
+  headers?: Record<string, string>;
+}
+
+export async function downloadFile(
+  url: string,
+  dest: string,
+  options?: DownloadOptions,
+  redirectCount: number = 0,
+): Promise<void> {
+  const headers: Record<string, string> = {
+    'User-agent': 'gemini-cli',
+    Accept: 'application/octet-stream',
+    ...options?.headers,
+  };
+  const token = getGitHubToken();
+  if (token) {
+    headers['Authorization'] = `token ${token}`;
+  }
+
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers }, (res) => {
+        if (res.statusCode === 302 || res.statusCode === 301) {
+          if (redirectCount >= 10) {
+            return reject(new Error('Too many redirects'));
+          }
+
+          if (!res.headers.location) {
+            return reject(
+              new Error('Redirect response missing Location header'),
+            );
+          }
+          downloadFile(res.headers.location, dest, options, redirectCount + 1)
+            .then(resolve)
+            .catch(reject);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          return reject(
+            new Error(`Request failed with status code ${res.statusCode}`),
+          );
+        }
+        const file = fs.createWriteStream(dest);
+        res.pipe(file);
+        file.on('finish', () => file.close(resolve as () => void));
+      })
+      .on('error', reject);
+  });
+}
+
+export async function extractFile(file: string, dest: string): Promise<void> {
+  if (file.endsWith('.tar.gz')) {
+    await tar.x({
+      file,
+      cwd: dest,
+    });
+  } else if (file.endsWith('.zip')) {
+    await extract(file, { dir: dest });
+  } else {
+    throw new Error(`Unsupported file extension for extraction: ${file}`);
+  }
+}

packages/cli/src/config/extensions/github_fetch.test.ts

@@ -0,0 +1,201 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import * as https from 'node:https';
+import { EventEmitter } from 'node:events';
+import { fetchJson, getGitHubToken } from './github_fetch.js';
+import type { ClientRequest, IncomingMessage } from 'node:http';
+
+vi.mock('node:https');
+
+describe('getGitHubToken', () => {
+  const originalToken = process.env['GITHUB_TOKEN'];
+
+  afterEach(() => {
+    if (originalToken) {
+      process.env['GITHUB_TOKEN'] = originalToken;
+    } else {
+      delete process.env['GITHUB_TOKEN'];
+    }
+  });
+
+  it('should return the token if GITHUB_TOKEN is set', () => {
+    process.env['GITHUB_TOKEN'] = 'test-token';
+    expect(getGitHubToken()).toBe('test-token');
+  });
+
+  it('should return undefined if GITHUB_TOKEN is not set', () => {
+    delete process.env['GITHUB_TOKEN'];
+    expect(getGitHubToken()).toBeUndefined();
+  });
+});
+
+describe('fetchJson', () => {
+  const getMock = vi.mocked(https.get);
+
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it('should fetch and parse JSON successfully', async () => {
+    getMock.mockImplementationOnce((_url, _options, callback) => {
+      const res = new EventEmitter() as IncomingMessage;
+      res.statusCode = 200;
+      (callback as (res: IncomingMessage) => void)(res);
+      res.emit('data', Buffer.from('{"foo":'));
+      res.emit('data', Buffer.from('"bar"}'));
+      res.emit('end');
+      return new EventEmitter() as ClientRequest;
+    });
+    await expect(fetchJson('https://example.com/data.json')).resolves.toEqual({
+      foo: 'bar',
+    });
+  });
+
+  it('should handle redirects (301 and 302)', async () => {
+    // Test 302
+    getMock.mockImplementationOnce((_url, _options, callback) => {
+      const res = new EventEmitter() as IncomingMessage;
+      res.statusCode = 302;
+      res.headers = { location: 'https://example.com/final' };
+      res.resume = vi.fn();
+      (callback as (res: IncomingMessage) => void)(res);
+      res.emit('end');
+      return new EventEmitter() as ClientRequest;
+    });
+    getMock.mockImplementationOnce((url, _options, callback) => {
+      expect(url).toBe('https://example.com/final');
+      const res = new EventEmitter() as IncomingMessage;
+      res.statusCode = 200;
+      (callback as (res: IncomingMessage) => void)(res);
+      res.emit('data', Buffer.from('{"success": true}'));
+      res.emit('end');
+      return new EventEmitter() as ClientRequest;
+    });
+
+    await expect(fetchJson('https://example.com/redirect')).resolves.toEqual({
+      success: true,
+    });
+
+    // Test 301
+    getMock.mockImplementationOnce((_url, _options, callback) => {
+      const res = new EventEmitter() as IncomingMessage;
+      res.statusCode = 301;
+      res.headers = { location: 'https://example.com/final-permanent' };
+      res.resume = vi.fn();
+      (callback as (res: IncomingMessage) => void)(res);
+      res.emit('end');
+      return new EventEmitter() as ClientRequest;
+    });
+    getMock.mockImplementationOnce((url, _options, callback) => {
+      expect(url).toBe('https://example.com/final-permanent');
+      const res = new EventEmitter() as IncomingMessage;
+      res.statusCode = 200;
+      (callback as (res: IncomingMessage) => void)(res);
+      res.emit('data', Buffer.from('{"permanent": true}'));
+      res.emit('end');
+      return new EventEmitter() as ClientRequest;
+    });
+
+    await expect(
+      fetchJson('https://example.com/redirect-perm'),
+    ).resolves.toEqual({ permanent: true });
+  });
+
+  it('should reject on non-200/30x status code', async () => {
+    getMock.mockImplementationOnce((_url, _options, callback) => {
+      const res = new EventEmitter() as IncomingMessage;
+      res.statusCode = 404;
+      (callback as (res: IncomingMessage) => void)(res);
+      res.emit('end');
+      return new EventEmitter() as ClientRequest;
+    });
+
+    await expect(fetchJson('https://example.com/error')).rejects.toThrow(
+      'Request failed with status code 404',
+    );
+  });
+
+  it('should reject on request error', async () => {
+    const error = new Error('Network error');
+    getMock.mockImplementationOnce(() => {
+      const req = new EventEmitter() as ClientRequest;
+      req.emit('error', error);
+      return req;
+    });
+
+    await expect(fetchJson('https://example.com/error')).rejects.toThrow(
+      'Network error',
+    );
+  });
+
+  describe('with GITHUB_TOKEN', () => {
+    const originalToken = process.env['GITHUB_TOKEN'];
+
+    beforeEach(() => {
+      process.env['GITHUB_TOKEN'] = 'my-secret-token';
+    });
+
+    afterEach(() => {
+      if (originalToken) {
+        process.env['GITHUB_TOKEN'] = originalToken;
+      } else {
+        delete process.env['GITHUB_TOKEN'];
+      }
+    });
+
+    it('should include Authorization header if token is present', async () => {
+      getMock.mockImplementationOnce((_url, options, callback) => {
+        expect(options.headers).toEqual({
+          'User-Agent': 'gemini-cli',
+          Authorization: 'token my-secret-token',
+        });
+        const res = new EventEmitter() as IncomingMessage;
+        res.statusCode = 200;
+        (callback as (res: IncomingMessage) => void)(res);
+        res.emit('data', Buffer.from('{"foo": "bar"}'));
+        res.emit('end');
+        return new EventEmitter() as ClientRequest;
+      });
+      await expect(fetchJson('https://api.github.com/user')).resolves.toEqual({
+        foo: 'bar',
+      });
+    });
+  });
+
+  describe('without GITHUB_TOKEN', () => {
+    const originalToken = process.env['GITHUB_TOKEN'];
+
+    beforeEach(() => {
+      delete process.env['GITHUB_TOKEN'];
+    });
+
+    afterEach(() => {
+      if (originalToken) {
+        process.env['GITHUB_TOKEN'] = originalToken;
+      }
+    });
+
+    it('should not include Authorization header if token is not present', async () => {
+      getMock.mockImplementationOnce((_url, options, callback) => {
+        expect(options.headers).toEqual({
+          'User-Agent': 'gemini-cli',
+        });
+        const res = new EventEmitter() as IncomingMessage;
+        res.statusCode = 200;
+        (callback as (res: IncomingMessage) => void)(res);
+        res.emit('data', Buffer.from('{"foo": "bar"}'));
+        res.emit('end');
+        return new EventEmitter() as ClientRequest;
+      });
+
+      await expect(fetchJson('https://api.github.com/user')).resolves.toEqual({
+        foo: 'bar',
+      });
+    });
+  });
+});

packages/cli/src/config/extensions/github_fetch.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as https from 'node:https';
+
+export function getGitHubToken(): string | undefined {
+  return process.env['GITHUB_TOKEN'];
+}
+
+export async function fetchJson<T>(
+  url: string,
+  redirectCount: number = 0,
+): Promise<T> {
+  const headers: { 'User-Agent': string; Authorization?: string } = {
+    'User-Agent': 'gemini-cli',
+  };
+  const token = getGitHubToken();
+  if (token) {
+    headers.Authorization = `token ${token}`;
+  }
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers }, (res) => {
+        if (res.statusCode === 302 || res.statusCode === 301) {
+          if (redirectCount >= 10) {
+            return reject(new Error('Too many redirects'));
+          }
+          if (!res.headers.location) {
+            return reject(new Error('No location header in redirect response'));
+          }
+          res.resume();
+          fetchJson<T>(
+            new URL(res.headers.location, url).toString(),
+            redirectCount + 1,
+          )
+            .then(resolve)
+            .catch(reject);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          return reject(
+            new Error(`Request failed with status code ${res.statusCode}`),
+          );
+        }
+        const chunks: Buffer[] = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => {
+          const data = Buffer.concat(chunks).toString();
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+          resolve(JSON.parse(data) as T);
+        });
+      })
+      .on('error', reject);
+  });
+}

packages/cli/src/config/extensions/storage.test.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ExtensionStorage } from './storage.js';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import {
+  EXTENSION_SETTINGS_FILENAME,
+  EXTENSIONS_CONFIG_FILENAME,
+} from './variables.js';
+import { Storage } from '@google/gemini-cli-core';
+
+vi.mock('node:os');
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof fs>();
+  return {
+    ...actual,
+    promises: {
+      ...actual.promises,
+      mkdtemp: vi.fn(),
+    },
+  };
+});
+vi.mock('@google/gemini-cli-core');
+
+describe('ExtensionStorage', () => {
+  const mockHomeDir = '/mock/home';
+  const extensionName = 'test-extension';
+  let storage: ExtensionStorage;
+
+  beforeEach(() => {
+    vi.mocked(os.homedir).mockReturnValue(mockHomeDir);
+    vi.mocked(Storage).mockImplementation(
+      () =>
+        ({
+          getExtensionsDir: () =>
+            path.join(mockHomeDir, '.gemini', 'extensions'),
+        }) as any, // eslint-disable-line @typescript-eslint/no-explicit-any
+    );
+    storage = new ExtensionStorage(extensionName);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should return the correct extension directory', () => {
+    const expectedDir = path.join(
+      mockHomeDir,
+      '.gemini',
+      'extensions',
+      extensionName,
+    );
+    expect(storage.getExtensionDir()).toBe(expectedDir);
+  });
+
+  it('should return the correct config path', () => {
+    const expectedPath = path.join(
+      mockHomeDir,
+      '.gemini',
+      'extensions',
+      extensionName,
+      EXTENSIONS_CONFIG_FILENAME, // EXTENSIONS_CONFIG_FILENAME
+    );
+    expect(storage.getConfigPath()).toBe(expectedPath);
+  });
+
+  it('should return the correct env file path', () => {
+    const expectedPath = path.join(
+      mockHomeDir,
+      '.gemini',
+      'extensions',
+      extensionName,
+      EXTENSION_SETTINGS_FILENAME, // EXTENSION_SETTINGS_FILENAME
+    );
+    expect(storage.getEnvFilePath()).toBe(expectedPath);
+  });
+
+  it('should return the correct user extensions directory', () => {
+    const expectedDir = path.join(mockHomeDir, '.gemini', 'extensions');
+    expect(ExtensionStorage.getUserExtensionsDir()).toBe(expectedDir);
+  });
+
+  it('should create a temporary directory', async () => {
+    const mockTmpDir = '/tmp/gemini-extension-123';
+    vi.mocked(fs.promises.mkdtemp).mockResolvedValue(mockTmpDir);
+    vi.mocked(os.tmpdir).mockReturnValue('/tmp');
+
+    const result = await ExtensionStorage.createTmpDir();
+
+    expect(fs.promises.mkdtemp).toHaveBeenCalledWith(
+      path.join('/tmp', 'gemini-extension'),
+    );
+    expect(result).toBe(mockTmpDir);
+  });
+});

packages/cli/src/config/extensions/storage.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import {
+  EXTENSION_SETTINGS_FILENAME,
+  EXTENSIONS_CONFIG_FILENAME,
+} from './variables.js';
+import { Storage, homedir } from '@google/gemini-cli-core';
+
+export class ExtensionStorage {
+  private readonly extensionName: string;
+
+  constructor(extensionName: string) {
+    this.extensionName = extensionName;
+  }
+
+  getExtensionDir(): string {
+    return path.join(
+      ExtensionStorage.getUserExtensionsDir(),
+      this.extensionName,
+    );
+  }
+
+  getConfigPath(): string {
+    return path.join(this.getExtensionDir(), EXTENSIONS_CONFIG_FILENAME);
+  }
+
+  getEnvFilePath(): string {
+    return path.join(this.getExtensionDir(), EXTENSION_SETTINGS_FILENAME);
+  }
+
+  static getUserExtensionsDir(): string {
+    return new Storage(homedir()).getExtensionsDir();
+  }
+
+  static async createTmpDir(): Promise<string> {
+    return fs.promises.mkdtemp(path.join(os.tmpdir(), 'gemini-extension'));
+  }
+}

packages/cli/src/config/extensions/update.test.ts

@@ -0,0 +1,480 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  updateExtension,
+  updateAllUpdatableExtensions,
+  checkForAllExtensionUpdates,
+} from './update.js';
+import {
+  ExtensionUpdateState,
+  type ExtensionUpdateStatus,
+} from '../../ui/state/extensions.js';
+import { ExtensionStorage } from './storage.js';
+import { type ExtensionManager, copyExtension } from '../extension-manager.js';
+import { checkForExtensionUpdate } from './github.js';
+import { loadInstallMetadata } from '../extension.js';
+import * as fs from 'node:fs';
+import {
+  type GeminiCLIExtension,
+  type ExtensionInstallMetadata,
+  IntegrityDataStatus,
+} from '@google/gemini-cli-core';
+
+vi.mock('./storage.js', () => ({
+  ExtensionStorage: {
+    createTmpDir: vi.fn(),
+  },
+}));
+
+vi.mock('../extension-manager.js', () => ({
+  copyExtension: vi.fn(),
+  // We don't need to mock the class implementation if we pass a mock instance
+}));
+
+vi.mock('./github.js', () => ({
+  checkForExtensionUpdate: vi.fn(),
+}));
+
+vi.mock('../extension.js', () => ({
+  loadInstallMetadata: vi.fn(),
+}));
+
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>();
+  return {
+    ...actual,
+    promises: {
+      ...actual.promises,
+      rm: vi.fn(),
+    },
+  };
+});
+
+describe('Extension Update Logic', () => {
+  let mockExtensionManager: ExtensionManager;
+  let mockDispatch: ReturnType<typeof vi.fn>;
+  const mockExtension: GeminiCLIExtension = {
+    name: 'test-extension',
+    version: '1.0.0',
+    path: '/path/to/extension',
+  } as GeminiCLIExtension;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockExtensionManager = {
+      loadExtensionConfig: vi.fn().mockResolvedValue({
+        name: 'test-extension',
+        version: '1.0.0',
+      }),
+      installOrUpdateExtension: vi.fn().mockResolvedValue({
+        ...mockExtension,
+        version: '1.1.0',
+      }),
+      verifyExtensionIntegrity: vi
+        .fn()
+        .mockResolvedValue(IntegrityDataStatus.VERIFIED),
+      storeExtensionIntegrity: vi.fn().mockResolvedValue(undefined),
+    } as unknown as ExtensionManager;
+    mockDispatch = vi.fn();
+
+    // Default mock behaviors
+    vi.mocked(ExtensionStorage.createTmpDir).mockResolvedValue('/tmp/mock-dir');
+    vi.mocked(loadInstallMetadata).mockReturnValue({
+      source: 'https://example.com/repo.git',
+      type: 'git',
+    });
+  });
+
+  describe('updateExtension', () => {
+    it('should return undefined if state is already UPDATING', async () => {
+      const result = await updateExtension(
+        mockExtension,
+        mockExtensionManager,
+        ExtensionUpdateState.UPDATING,
+        mockDispatch,
+      );
+      expect(result).toBeUndefined();
+      expect(mockDispatch).not.toHaveBeenCalled();
+    });
+
+    it('should throw error and set state to ERROR if install metadata type is unknown', async () => {
+      vi.mocked(loadInstallMetadata).mockReturnValue({
+        type: undefined,
+      } as unknown as ExtensionInstallMetadata);
+
+      await expect(
+        updateExtension(
+          mockExtension,
+          mockExtensionManager,
+          ExtensionUpdateState.UPDATE_AVAILABLE,
+          mockDispatch,
+        ),
+      ).rejects.toThrow('type is unknown');
+
+      expect(mockDispatch).toHaveBeenCalledWith({
+        type: 'SET_STATE',
+        payload: {
+          name: mockExtension.name,
+          state: ExtensionUpdateState.UPDATING,
+        },
+      });
+      expect(mockDispatch).toHaveBeenCalledWith({
+        type: 'SET_STATE',
+        payload: {
+          name: mockExtension.name,
+          state: ExtensionUpdateState.ERROR,
+        },
+      });
+    });
+
+    it('should throw error and set state to UP_TO_DATE if extension is linked', async () => {
+      vi.mocked(loadInstallMetadata).mockReturnValue({
+        type: 'link',
+        source: '',
+      });
+
+      await expect(
+        updateExtension(
+          mockExtension,
+          mockExtensionManager,
+          ExtensionUpdateState.UPDATE_AVAILABLE,
+          mockDispatch,
+        ),
+      ).rejects.toThrow('Extension is linked');
+
+      expect(mockDispatch).toHaveBeenCalledWith({
+        type: 'SET_STATE',
+        payload: {
+          name: mockExtension.name,
+          state: ExtensionUpdateState.UP_TO_DATE,
+        },
+      });
+    });
+
+    it('should successfully update extension and set state to UPDATED_NEEDS_RESTART by default', async () => {
+      vi.mocked(mockExtensionManager.loadExtensionConfig).mockReturnValue(
+        Promise.resolve({
+          name: 'test-extension',
+          version: '1.0.0',
+        }),
+      );
+      vi.mocked(
+        mockExtensionManager.installOrUpdateExtension,
+      ).mockResolvedValue({
+        ...mockExtension,
+        version: '1.1.0',
+      });
+
+      const result = await updateExtension(
+        mockExtension,
+        mockExtensionManager,
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+        mockDispatch,
+      );
+
+      expect(mockExtensionManager.installOrUpdateExtension).toHaveBeenCalled();
+      expect(mockDispatch).toHaveBeenCalledWith({
+        type: 'SET_STATE',
+        payload: {
+          name: mockExtension.name,
+          state: ExtensionUpdateState.UPDATED_NEEDS_RESTART,
+        },
+      });
+      expect(result).toEqual({
+        name: 'test-extension',
+        originalVersion: '1.0.0',
+        updatedVersion: '1.1.0',
+      });
+      expect(fs.promises.rm).toHaveBeenCalledWith('/tmp/mock-dir', {
+        recursive: true,
+        force: true,
+      });
+    });
+
+    it('should migrate source if migratedTo is set and an update is available', async () => {
+      vi.mocked(mockExtensionManager.loadExtensionConfig).mockReturnValue(
+        Promise.resolve({
+          name: 'test-extension',
+          version: '1.0.0',
+        }),
+      );
+      vi.mocked(
+        mockExtensionManager.installOrUpdateExtension,
+      ).mockResolvedValue({
+        ...mockExtension,
+        version: '1.1.0',
+      });
+      vi.mocked(checkForExtensionUpdate).mockResolvedValue(
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+      );
+
+      const extensionWithMigratedTo = {
+        ...mockExtension,
+        migratedTo: 'https://new-source.com/repo.git',
+      };
+
+      await updateExtension(
+        extensionWithMigratedTo,
+        mockExtensionManager,
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+        mockDispatch,
+      );
+
+      expect(checkForExtensionUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          installMetadata: expect.objectContaining({
+            source: 'https://new-source.com/repo.git',
+          }),
+        }),
+        mockExtensionManager,
+      );
+
+      expect(
+        mockExtensionManager.installOrUpdateExtension,
+      ).toHaveBeenCalledWith(
+        expect.objectContaining({
+          source: 'https://new-source.com/repo.git',
+        }),
+        expect.anything(),
+      );
+    });
+
+    it('should set state to UPDATED if enableExtensionReloading is true', async () => {
+      vi.mocked(mockExtensionManager.loadExtensionConfig).mockReturnValue(
+        Promise.resolve({
+          name: 'test-extension',
+          version: '1.0.0',
+        }),
+      );
+      vi.mocked(
+        mockExtensionManager.installOrUpdateExtension,
+      ).mockResolvedValue({
+        ...mockExtension,
+        version: '1.1.0',
+      });
+
+      await updateExtension(
+        mockExtension,
+        mockExtensionManager,
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+        mockDispatch,
+        true, // enableExtensionReloading
+      );
+
+      expect(mockDispatch).toHaveBeenCalledWith({
+        type: 'SET_STATE',
+        payload: {
+          name: mockExtension.name,
+          state: ExtensionUpdateState.UPDATED,
+        },
+      });
+    });
+
+    it('should rollback and set state to ERROR if installation fails', async () => {
+      vi.mocked(mockExtensionManager.loadExtensionConfig).mockReturnValue(
+        Promise.resolve({
+          name: 'test-extension',
+          version: '1.0.0',
+        }),
+      );
+      vi.mocked(
+        mockExtensionManager.installOrUpdateExtension,
+      ).mockRejectedValue(new Error('Install failed'));
+
+      await expect(
+        updateExtension(
+          mockExtension,
+          mockExtensionManager,
+          ExtensionUpdateState.UPDATE_AVAILABLE,
+          mockDispatch,
+        ),
+      ).rejects.toThrow('Updated extension not found after installation');
+
+      expect(copyExtension).toHaveBeenCalledWith(
+        '/tmp/mock-dir',
+        mockExtension.path,
+      );
+      expect(mockDispatch).toHaveBeenCalledWith({
+        type: 'SET_STATE',
+        payload: {
+          name: mockExtension.name,
+          state: ExtensionUpdateState.ERROR,
+        },
+      });
+      expect(fs.promises.rm).toHaveBeenCalled();
+    });
+
+    describe('Integrity Verification', () => {
+      it('should fail update with security alert if integrity is invalid', async () => {
+        vi.mocked(
+          mockExtensionManager.verifyExtensionIntegrity,
+        ).mockResolvedValue(IntegrityDataStatus.INVALID);
+
+        await expect(
+          updateExtension(
+            mockExtension,
+            mockExtensionManager,
+            ExtensionUpdateState.UPDATE_AVAILABLE,
+            mockDispatch,
+          ),
+        ).rejects.toThrow(
+          'Extension test-extension cannot be updated. Extension integrity cannot be verified.',
+        );
+
+        expect(mockDispatch).toHaveBeenCalledWith({
+          type: 'SET_STATE',
+          payload: {
+            name: mockExtension.name,
+            state: ExtensionUpdateState.ERROR,
+          },
+        });
+      });
+
+      it('should establish trust on first update if integrity data is missing', async () => {
+        vi.mocked(
+          mockExtensionManager.verifyExtensionIntegrity,
+        ).mockResolvedValue(IntegrityDataStatus.MISSING);
+
+        await updateExtension(
+          mockExtension,
+          mockExtensionManager,
+          ExtensionUpdateState.UPDATE_AVAILABLE,
+          mockDispatch,
+        );
+
+        // Verify updateExtension delegates to installOrUpdateExtension,
+        // which is responsible for establishing trust internally.
+        expect(
+          mockExtensionManager.installOrUpdateExtension,
+        ).toHaveBeenCalled();
+
+        expect(mockDispatch).toHaveBeenCalledWith({
+          type: 'SET_STATE',
+          payload: {
+            name: mockExtension.name,
+            state: ExtensionUpdateState.UPDATED_NEEDS_RESTART,
+          },
+        });
+      });
+
+      it('should throw if integrity manager throws', async () => {
+        vi.mocked(
+          mockExtensionManager.verifyExtensionIntegrity,
+        ).mockRejectedValue(new Error('Verification failed'));
+
+        await expect(
+          updateExtension(
+            mockExtension,
+            mockExtensionManager,
+            ExtensionUpdateState.UPDATE_AVAILABLE,
+            mockDispatch,
+          ),
+        ).rejects.toThrow(
+          'Extension test-extension cannot be updated. Verification failed',
+        );
+      });
+    });
+  });
+
+  describe('updateAllUpdatableExtensions', () => {
+    it('should update all extensions with UPDATE_AVAILABLE status', async () => {
+      const extensions: GeminiCLIExtension[] = [
+        { ...mockExtension, name: 'ext1' },
+        { ...mockExtension, name: 'ext2' },
+        { ...mockExtension, name: 'ext3' },
+      ];
+      const extensionsState = new Map([
+        ['ext1', { status: ExtensionUpdateState.UPDATE_AVAILABLE }],
+        ['ext2', { status: ExtensionUpdateState.UP_TO_DATE }],
+        ['ext3', { status: ExtensionUpdateState.UPDATE_AVAILABLE }],
+      ]);
+
+      vi.mocked(mockExtensionManager.loadExtensionConfig).mockReturnValue(
+        Promise.resolve({
+          name: 'ext',
+          version: '1.0.0',
+        }),
+      );
+      vi.mocked(
+        mockExtensionManager.installOrUpdateExtension,
+      ).mockResolvedValue({ ...mockExtension, version: '1.1.0' });
+
+      const results = await updateAllUpdatableExtensions(
+        extensions,
+        extensionsState as Map<string, ExtensionUpdateStatus>,
+        mockExtensionManager,
+        mockDispatch,
+      );
+
+      expect(results).toHaveLength(2);
+      expect(results.map((r) => r.name)).toEqual(['ext1', 'ext3']);
+      expect(
+        mockExtensionManager.installOrUpdateExtension,
+      ).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('checkForAllExtensionUpdates', () => {
+    it('should dispatch BATCH_CHECK_START and BATCH_CHECK_END', async () => {
+      await checkForAllExtensionUpdates([], mockExtensionManager, mockDispatch);
+
+      expect(mockDispatch).toHaveBeenCalledWith({ type: 'BATCH_CHECK_START' });
+      expect(mockDispatch).toHaveBeenCalledWith({ type: 'BATCH_CHECK_END' });
+    });
+
+    it('should set state to NOT_UPDATABLE if no install metadata', async () => {
+      const extensions: GeminiCLIExtension[] = [
+        { ...mockExtension, installMetadata: undefined },
+      ];
+
+      await checkForAllExtensionUpdates(
+        extensions,
+        mockExtensionManager,
+        mockDispatch,
+      );
+
+      expect(mockDispatch).toHaveBeenCalledWith({
+        type: 'SET_STATE',
+        payload: {
+          name: mockExtension.name,
+          state: ExtensionUpdateState.NOT_UPDATABLE,
+        },
+      });
+    });
+
+    it('should check for updates and update state', async () => {
+      const extensions: GeminiCLIExtension[] = [
+        { ...mockExtension, installMetadata: { type: 'git', source: '...' } },
+      ];
+      vi.mocked(checkForExtensionUpdate).mockResolvedValue(
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+      );
+
+      await checkForAllExtensionUpdates(
+        extensions,
+        mockExtensionManager,
+        mockDispatch,
+      );
+
+      expect(mockDispatch).toHaveBeenCalledWith({
+        type: 'SET_STATE',
+        payload: {
+          name: mockExtension.name,
+          state: ExtensionUpdateState.CHECKING_FOR_UPDATES,
+        },
+      });
+      expect(mockDispatch).toHaveBeenCalledWith({
+        type: 'SET_STATE',
+        payload: {
+          name: mockExtension.name,
+          state: ExtensionUpdateState.UPDATE_AVAILABLE,
+        },
+      });
+    });
+  });
+});

packages/cli/src/config/extensions/update.ts

@@ -0,0 +1,225 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  type ExtensionUpdateAction,
+  ExtensionUpdateState,
+  type ExtensionUpdateStatus,
+} from '../../ui/state/extensions.js';
+import { loadInstallMetadata } from '../extension.js';
+import { checkForExtensionUpdate } from './github.js';
+import {
+  debugLogger,
+  getErrorMessage,
+  type GeminiCLIExtension,
+  IntegrityDataStatus,
+} from '@google/gemini-cli-core';
+import * as fs from 'node:fs';
+import { copyExtension, type ExtensionManager } from '../extension-manager.js';
+import { ExtensionStorage } from './storage.js';
+
+export interface ExtensionUpdateInfo {
+  name: string;
+  originalVersion: string;
+  updatedVersion: string;
+}
+
+export async function updateExtension(
+  extension: GeminiCLIExtension,
+  extensionManager: ExtensionManager,
+  currentState: ExtensionUpdateState,
+  dispatchExtensionStateUpdate: (action: ExtensionUpdateAction) => void,
+  enableExtensionReloading?: boolean,
+): Promise<ExtensionUpdateInfo | undefined> {
+  if (currentState === ExtensionUpdateState.UPDATING) {
+    return undefined;
+  }
+  dispatchExtensionStateUpdate({
+    type: 'SET_STATE',
+    payload: { name: extension.name, state: ExtensionUpdateState.UPDATING },
+  });
+  const installMetadata = loadInstallMetadata(extension.path);
+
+  if (!installMetadata?.type) {
+    dispatchExtensionStateUpdate({
+      type: 'SET_STATE',
+      payload: { name: extension.name, state: ExtensionUpdateState.ERROR },
+    });
+    throw new Error(
+      `Extension ${extension.name} cannot be updated, type is unknown.`,
+    );
+  }
+
+  try {
+    const status = await extensionManager.verifyExtensionIntegrity(
+      extension.name,
+      installMetadata,
+    );
+
+    if (status === IntegrityDataStatus.INVALID) {
+      throw new Error('Extension integrity cannot be verified');
+    }
+  } catch (e) {
+    dispatchExtensionStateUpdate({
+      type: 'SET_STATE',
+      payload: { name: extension.name, state: ExtensionUpdateState.ERROR },
+    });
+    throw new Error(
+      `Extension ${extension.name} cannot be updated. ${getErrorMessage(e)}. To fix this, reinstall the extension.`,
+    );
+  }
+
+  if (installMetadata?.type === 'link') {
+    dispatchExtensionStateUpdate({
+      type: 'SET_STATE',
+      payload: { name: extension.name, state: ExtensionUpdateState.UP_TO_DATE },
+    });
+    throw new Error(`Extension is linked so does not need to be updated`);
+  }
+
+  if (extension.migratedTo) {
+    const migratedState = await checkForExtensionUpdate(
+      {
+        ...extension,
+        installMetadata: { ...installMetadata, source: extension.migratedTo },
+        migratedTo: undefined,
+      },
+      extensionManager,
+    );
+    if (
+      migratedState === ExtensionUpdateState.UPDATE_AVAILABLE ||
+      migratedState === ExtensionUpdateState.UP_TO_DATE
+    ) {
+      installMetadata.source = extension.migratedTo;
+    }
+  }
+
+  const originalVersion = extension.version;
+
+  const tempDir = await ExtensionStorage.createTmpDir();
+  try {
+    const previousExtensionConfig = await extensionManager.loadExtensionConfig(
+      extension.path,
+    );
+    let updatedExtension: GeminiCLIExtension;
+    try {
+      updatedExtension = await extensionManager.installOrUpdateExtension(
+        installMetadata,
+        previousExtensionConfig,
+      );
+    } catch (e) {
+      dispatchExtensionStateUpdate({
+        type: 'SET_STATE',
+        payload: { name: extension.name, state: ExtensionUpdateState.ERROR },
+      });
+      throw new Error(
+        `Updated extension not found after installation, got error:\n${e}`,
+      );
+    }
+    const updatedVersion = updatedExtension.version;
+    dispatchExtensionStateUpdate({
+      type: 'SET_STATE',
+      payload: {
+        name: extension.name,
+        state: enableExtensionReloading
+          ? ExtensionUpdateState.UPDATED
+          : ExtensionUpdateState.UPDATED_NEEDS_RESTART,
+      },
+    });
+    return {
+      name: extension.name,
+      originalVersion,
+      updatedVersion,
+    };
+  } catch (e) {
+    debugLogger.error(
+      `Error updating extension, rolling back. ${getErrorMessage(e)}`,
+    );
+    dispatchExtensionStateUpdate({
+      type: 'SET_STATE',
+      payload: { name: extension.name, state: ExtensionUpdateState.ERROR },
+    });
+    await copyExtension(tempDir, extension.path);
+    throw e;
+  } finally {
+    await fs.promises.rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export async function updateAllUpdatableExtensions(
+  extensions: GeminiCLIExtension[],
+  extensionsState: Map<string, ExtensionUpdateStatus>,
+  extensionManager: ExtensionManager,
+  dispatch: (action: ExtensionUpdateAction) => void,
+  enableExtensionReloading?: boolean,
+): Promise<ExtensionUpdateInfo[]> {
+  const results = await Promise.all(
+    extensions
+      .filter(
+        (extension) =>
+          extensionsState.get(extension.name)?.status ===
+          ExtensionUpdateState.UPDATE_AVAILABLE,
+      )
+      .map((extension) =>
+        updateExtension(
+          extension,
+          extensionManager,
+          extensionsState.get(extension.name)!.status,
+          dispatch,
+          enableExtensionReloading,
+        ),
+      ),
+  );
+  return results.filter(
+    (updateInfo): updateInfo is ExtensionUpdateInfo => !!updateInfo,
+  );
+}
+
+export interface ExtensionUpdateCheckResult {
+  state: ExtensionUpdateState;
+  error?: string;
+}
+
+export async function checkForAllExtensionUpdates(
+  extensions: GeminiCLIExtension[],
+  extensionManager: ExtensionManager,
+  dispatch: (action: ExtensionUpdateAction) => void,
+): Promise<void> {
+  dispatch({ type: 'BATCH_CHECK_START' });
+  try {
+    const promises: Array<Promise<void>> = [];
+    for (const extension of extensions) {
+      if (!extension.installMetadata) {
+        dispatch({
+          type: 'SET_STATE',
+          payload: {
+            name: extension.name,
+            state: ExtensionUpdateState.NOT_UPDATABLE,
+          },
+        });
+        continue;
+      }
+      dispatch({
+        type: 'SET_STATE',
+        payload: {
+          name: extension.name,
+          state: ExtensionUpdateState.CHECKING_FOR_UPDATES,
+        },
+      });
+      promises.push(
+        checkForExtensionUpdate(extension, extensionManager).then((state) =>
+          dispatch({
+            type: 'SET_STATE',
+            payload: { name: extension.name, state },
+          }),
+        ),
+      );
+    }
+    await Promise.all(promises);
+  } finally {
+    dispatch({ type: 'BATCH_CHECK_END' });
+  }
+}

packages/cli/src/config/extensions/variableSchema.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface VariableDefinition {
+  type: 'string';
+  description: string;
+  default?: string;
+  required?: boolean;
+}
+
+export interface VariableSchema {
+  [key: string]: VariableDefinition;
+}
+
+const PATH_SEPARATOR_DEFINITION = {
+  type: 'string',
+  description: 'The path separator.',
+} as const;
+
+export const VARIABLE_SCHEMA = {
+  extensionPath: {
+    type: 'string',
+    description: 'The path of the extension in the filesystem.',
+  },
+  workspacePath: {
+    type: 'string',
+    description: 'The absolute path of the current workspace.',
+  },
+  '/': PATH_SEPARATOR_DEFINITION,
+  pathSeparator: PATH_SEPARATOR_DEFINITION,
+} as const;

packages/cli/src/config/extensions/variables.test.ts

@@ -0,0 +1,153 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { expect, describe, it } from 'vitest';
+import {
+  hydrateString,
+  recursivelyHydrateStrings,
+  validateVariables,
+  type VariableContext,
+} from './variables.js';
+
+describe('validateVariables', () => {
+  it('should not throw if all required variables are present', () => {
+    const schema = {
+      extensionPath: { type: 'string', description: 'test', required: true },
+    } as const;
+    const context = { extensionPath: 'value' };
+    expect(() => validateVariables(context, schema)).not.toThrow();
+  });
+
+  it('should throw if a required variable is missing', () => {
+    const schema = {
+      extensionPath: { type: 'string', description: 'test', required: true },
+    } as const;
+    const context = {};
+    expect(() => validateVariables(context, schema)).toThrow(
+      'Missing required variable: extensionPath',
+    );
+  });
+});
+
+describe('hydrateString', () => {
+  it('should replace a single variable', () => {
+    const context = {
+      extensionPath: 'path/my-extension',
+    };
+    const result = hydrateString('Hello, ${extensionPath}!', context);
+    expect(result).toBe('Hello, path/my-extension!');
+  });
+
+  it('should replace multiple variables', () => {
+    const context = {
+      extensionPath: 'path/my-extension',
+      workspacePath: '/ws',
+    };
+    const result = hydrateString(
+      'Ext: ${extensionPath}, WS: ${workspacePath}',
+      context,
+    );
+    expect(result).toBe('Ext: path/my-extension, WS: /ws');
+  });
+
+  it('should ignore unknown variables', () => {
+    const context = {
+      extensionPath: 'path/my-extension',
+    };
+    const result = hydrateString('Hello, ${unknown}!', context);
+    expect(result).toBe('Hello, ${unknown}!');
+  });
+
+  it('should handle null and undefined context values', () => {
+    const context: VariableContext = {
+      extensionPath: undefined,
+    };
+    const result = hydrateString(
+      'Ext: ${extensionPath}, WS: ${workspacePath}',
+      context,
+    );
+    expect(result).toBe('Ext: ${extensionPath}, WS: ${workspacePath}');
+  });
+});
+
+describe('recursivelyHydrateStrings', () => {
+  const context = {
+    extensionPath: 'path/my-extension',
+    workspacePath: '/ws',
+  };
+
+  it('should hydrate strings in a flat object', () => {
+    const obj = {
+      a: 'Hello, ${workspacePath}',
+      b: 'Hi, ${extensionPath}',
+    };
+    const result = recursivelyHydrateStrings(obj, context);
+    expect(result).toEqual({
+      a: 'Hello, /ws',
+      b: 'Hi, path/my-extension',
+    });
+  });
+
+  it('should hydrate strings in an array', () => {
+    const arr = ['${workspacePath}', '${extensionPath}'];
+    const result = recursivelyHydrateStrings(arr, context);
+    expect(result).toEqual(['/ws', 'path/my-extension']);
+  });
+
+  it('should hydrate strings in a nested object', () => {
+    const obj = {
+      a: 'Hello, ${workspacePath}',
+      b: {
+        c: 'Hi, ${extensionPath}',
+        d: ['${workspacePath}/foo'],
+      },
+    };
+    const result = recursivelyHydrateStrings(obj, context);
+    expect(result).toEqual({
+      a: 'Hello, /ws',
+      b: {
+        c: 'Hi, path/my-extension',
+        d: ['/ws/foo'],
+      },
+    });
+  });
+
+  it('should not modify non-string values', () => {
+    const obj = {
+      a: 123,
+      b: true,
+      c: null,
+    };
+    const result = recursivelyHydrateStrings(obj, context);
+    expect(result).toEqual(obj);
+  });
+
+  it('should not allow prototype pollution via __proto__', () => {
+    const payload = JSON.parse('{"__proto__": {"polluted": "yes"}}');
+    const result = recursivelyHydrateStrings(payload, context);
+
+    expect(result.polluted).toBeUndefined();
+    expect(Object.prototype.hasOwnProperty.call(result, 'polluted')).toBe(
+      false,
+    );
+  });
+
+  it('should not allow prototype pollution via constructor', () => {
+    const payload = JSON.parse(
+      '{"constructor": {"prototype": {"polluted": "yes"}}}',
+    );
+    const result = recursivelyHydrateStrings(payload, context);
+
+    expect(result.polluted).toBeUndefined();
+  });
+
+  it('should not allow prototype pollution via prototype', () => {
+    const payload = JSON.parse('{"prototype": {"polluted": "yes"}}');
+    const result = recursivelyHydrateStrings(payload, context);
+
+    expect(result.polluted).toBeUndefined();
+  });
+});

packages/cli/src/config/extensions/variables.ts

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as path from 'node:path';
+import { type VariableSchema, VARIABLE_SCHEMA } from './variableSchema.js';
+import { GEMINI_DIR } from '@google/gemini-cli-core';
+
+/**
+ * Represents a set of keys that will be considered invalid while unmarshalling
+ * JSON in recursivelyHydrateStrings.
+ */
+const UNMARSHALL_KEY_IGNORE_LIST: Set<string> = new Set<string>([
+  '__proto__',
+  'constructor',
+  'prototype',
+]);
+
+export const EXTENSIONS_DIRECTORY_NAME = path.join(GEMINI_DIR, 'extensions');
+export const EXTENSIONS_CONFIG_FILENAME = 'gemini-extension.json';
+export const INSTALL_METADATA_FILENAME = '.gemini-extension-install.json';
+export const EXTENSION_SETTINGS_FILENAME = '.env';
+
+export type JsonObject = { [key: string]: JsonValue };
+export type JsonArray = JsonValue[];
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonObject
+  | JsonArray;
+
+export type VariableContext = {
+  [key: string]: string | undefined;
+};
+
+export function validateVariables(
+  variables: VariableContext,
+  schema: VariableSchema,
+) {
+  for (const key in schema) {
+    const definition = schema[key];
+    if (definition.required && !variables[key]) {
+      throw new Error(`Missing required variable: ${key}`);
+    }
+  }
+}
+
+export function hydrateString(str: string, context: VariableContext): string {
+  validateVariables(context, VARIABLE_SCHEMA);
+  const regex = /\${(.*?)}/g;
+  return str.replace(regex, (match, key) => {
+    const val = context[key];
+    return val == null ? match : String(val);
+  });
+}
+
+export function recursivelyHydrateStrings<T>(
+  obj: T,
+  values: VariableContext,
+): T {
+  if (typeof obj === 'string') {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return hydrateString(obj, values) as unknown as T;
+  }
+  if (Array.isArray(obj)) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return (obj as unknown[]).map((item) =>
+      recursivelyHydrateStrings(item, values),
+    ) as unknown as T;
+  }
+  if (typeof obj === 'object' && obj !== null) {
+    const newObj: Record<string, unknown> = {};
+    for (const key in obj) {
+      if (
+        !UNMARSHALL_KEY_IGNORE_LIST.has(key) &&
+        Object.prototype.hasOwnProperty.call(obj, key)
+      ) {
+        newObj[key] = recursivelyHydrateStrings(
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+          (obj as Record<string, unknown>)[key],
+          values,
+        );
+      }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return newObj as T;
+  }
+  return obj;
+}

packages/cli/src/config/mcp/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export {
+  McpServerEnablementManager,
+  canLoadServer,
+  normalizeServerId,
+  isInSettingsList,
+  type McpServerEnablementState,
+  type McpServerEnablementConfig,
+  type McpServerDisplayState,
+  type EnablementCallbacks,
+  type ServerLoadResult,
+} from './mcpServerEnablement.js';

packages/cli/src/config/mcp/mcpServerEnablement.test.ts

@@ -0,0 +1,189 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import fs from 'node:fs/promises';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    Storage: {
+      // eslint-disable-next-line @typescript-eslint/no-misused-spread
+      ...actual.Storage,
+      getGlobalGeminiDir: () => '/virtual-home/.gemini',
+    },
+  };
+});
+
+import {
+  McpServerEnablementManager,
+  canLoadServer,
+  normalizeServerId,
+  isInSettingsList,
+  type EnablementCallbacks,
+} from './mcpServerEnablement.js';
+
+let inMemoryFs: Record<string, string> = {};
+
+function createMockEnablement(
+  sessionDisabled: boolean,
+  fileEnabled: boolean,
+): EnablementCallbacks {
+  return {
+    isSessionDisabled: () => sessionDisabled,
+    isFileEnabled: () => Promise.resolve(fileEnabled),
+  };
+}
+
+function setupFsMocks(): void {
+  vi.spyOn(fs, 'readFile').mockImplementation(async (filePath) => {
+    const content = inMemoryFs[filePath.toString()];
+    if (content === undefined) {
+      const error = new Error(`ENOENT: ${filePath}`);
+      (error as NodeJS.ErrnoException).code = 'ENOENT';
+      throw error;
+    }
+    return content;
+  });
+  vi.spyOn(fs, 'writeFile').mockImplementation(async (filePath, data) => {
+    inMemoryFs[filePath.toString()] = data.toString();
+  });
+  vi.spyOn(fs, 'mkdir').mockImplementation(async () => undefined);
+}
+
+describe('McpServerEnablementManager', () => {
+  let manager: McpServerEnablementManager;
+
+  beforeEach(() => {
+    inMemoryFs = {};
+    setupFsMocks();
+    McpServerEnablementManager.resetInstance();
+    manager = McpServerEnablementManager.getInstance();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    McpServerEnablementManager.resetInstance();
+  });
+
+  it('should enable/disable servers with persistence', async () => {
+    expect(await manager.isFileEnabled('server')).toBe(true);
+    await manager.disable('server');
+    expect(await manager.isFileEnabled('server')).toBe(false);
+    await manager.enable('server');
+    expect(await manager.isFileEnabled('server')).toBe(true);
+  });
+
+  it('should handle session disable separately', async () => {
+    manager.disableForSession('server');
+    expect(manager.isSessionDisabled('server')).toBe(true);
+    expect(await manager.isFileEnabled('server')).toBe(true);
+    expect(await manager.isEffectivelyEnabled('server')).toBe(false);
+    manager.clearSessionDisable('server');
+    expect(await manager.isEffectivelyEnabled('server')).toBe(true);
+  });
+
+  it('should be case-insensitive', async () => {
+    await manager.disable('PlayWright');
+    expect(await manager.isFileEnabled('playwright')).toBe(false);
+  });
+
+  it('should return correct display state', async () => {
+    await manager.disable('file-disabled');
+    manager.disableForSession('session-disabled');
+
+    expect(await manager.getDisplayState('enabled')).toEqual({
+      enabled: true,
+      isSessionDisabled: false,
+      isPersistentDisabled: false,
+    });
+    expect(
+      (await manager.getDisplayState('file-disabled')).isPersistentDisabled,
+    ).toBe(true);
+    expect(
+      (await manager.getDisplayState('session-disabled')).isSessionDisabled,
+    ).toBe(true);
+  });
+
+  it('should share session state across getInstance calls', () => {
+    const instance1 = McpServerEnablementManager.getInstance();
+    const instance2 = McpServerEnablementManager.getInstance();
+
+    instance1.disableForSession('test-server');
+
+    expect(instance2.isSessionDisabled('test-server')).toBe(true);
+    expect(instance1).toBe(instance2);
+  });
+});
+
+describe('canLoadServer', () => {
+  it('blocks when admin has disabled MCP', async () => {
+    const result = await canLoadServer('s', { adminMcpEnabled: false });
+    expect(result.blockType).toBe('admin');
+  });
+
+  it('blocks when server is not in allowlist', async () => {
+    const result = await canLoadServer('s', {
+      adminMcpEnabled: true,
+      allowedList: ['other'],
+    });
+    expect(result.blockType).toBe('allowlist');
+  });
+
+  it('blocks when server is in excludelist', async () => {
+    const result = await canLoadServer('s', {
+      adminMcpEnabled: true,
+      excludedList: ['s'],
+    });
+    expect(result.blockType).toBe('excludelist');
+  });
+
+  it('blocks when server is session-disabled', async () => {
+    const result = await canLoadServer('s', {
+      adminMcpEnabled: true,
+      enablement: createMockEnablement(true, true),
+    });
+    expect(result.blockType).toBe('session');
+  });
+
+  it('blocks when server is file-disabled', async () => {
+    const result = await canLoadServer('s', {
+      adminMcpEnabled: true,
+      enablement: createMockEnablement(false, false),
+    });
+    expect(result.blockType).toBe('enablement');
+  });
+
+  it('allows when admin MCP is enabled and no restrictions', async () => {
+    const result = await canLoadServer('s', { adminMcpEnabled: true });
+    expect(result.allowed).toBe(true);
+  });
+
+  it('allows when server passes all checks', async () => {
+    const result = await canLoadServer('s', {
+      adminMcpEnabled: true,
+      allowedList: ['s'],
+      enablement: createMockEnablement(false, true),
+    });
+    expect(result.allowed).toBe(true);
+  });
+});
+
+describe('helper functions', () => {
+  it('normalizeServerId lowercases and trims', () => {
+    expect(normalizeServerId('  PlayWright  ')).toBe('playwright');
+  });
+
+  it('isInSettingsList supports ext: backward compat', () => {
+    expect(isInSettingsList('playwright', ['playwright']).found).toBe(true);
+    expect(isInSettingsList('ext:github:mcp', ['mcp']).found).toBe(true);
+    expect(
+      isInSettingsList('ext:github:mcp', ['mcp']).deprecationWarning,
+    ).toBeTruthy();
+  });
+});

packages/cli/src/config/mcp/mcpServerEnablement.ts

@@ -0,0 +1,387 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Storage, coreEvents } from '@google/gemini-cli-core';
+
+/**
+ * Stored in JSON file - represents persistent enablement state.
+ */
+export interface McpServerEnablementState {
+  enabled: boolean;
+}
+
+/**
+ * File config format - map of server ID to enablement state.
+ */
+export interface McpServerEnablementConfig {
+  [serverId: string]: McpServerEnablementState;
+}
+
+/**
+ * For UI display - combines file and session state.
+ */
+export interface McpServerDisplayState {
+  /** Effective state (considering session override) */
+  enabled: boolean;
+  /** True if disabled via --session flag */
+  isSessionDisabled: boolean;
+  /** True if disabled in file */
+  isPersistentDisabled: boolean;
+}
+
+/**
+ * Callback types for enablement checks (passed from CLI to core).
+ */
+export interface EnablementCallbacks {
+  isSessionDisabled: (serverId: string) => boolean;
+  isFileEnabled: (serverId: string) => Promise<boolean>;
+}
+
+/**
+ * Result of canLoadServer check.
+ */
+export interface ServerLoadResult {
+  allowed: boolean;
+  reason?: string;
+  blockType?: 'admin' | 'allowlist' | 'excludelist' | 'session' | 'enablement';
+}
+
+/**
+ * Normalize a server ID to canonical lowercase form.
+ */
+export function normalizeServerId(serverId: string): string {
+  return serverId.toLowerCase().trim();
+}
+
+/**
+ * Check if a server ID is in a settings list (with backward compatibility).
+ * Handles case-insensitive matching and plain name fallback for ext: servers.
+ */
+export function isInSettingsList(
+  serverId: string,
+  list: string[],
+): { found: boolean; deprecationWarning?: string } {
+  const normalizedId = normalizeServerId(serverId);
+  const normalizedList = list.map(normalizeServerId);
+
+  // Exact canonical match
+  if (normalizedList.includes(normalizedId)) {
+    return { found: true };
+  }
+
+  // Backward compat: for ext: servers, check if plain name matches
+  if (normalizedId.startsWith('ext:')) {
+    const plainName = normalizedId.split(':').pop();
+    if (plainName && normalizedList.includes(plainName)) {
+      return {
+        found: true,
+        deprecationWarning:
+          `Settings reference '${plainName}' matches extension server '${serverId}'. ` +
+          `Update your settings to use the full identifier '${serverId}' instead.`,
+      };
+    }
+  }
+
+  return { found: false };
+}
+
+/**
+ * Single source of truth for whether a server can be loaded.
+ * Used by: isAllowedMcpServer(), connectServer(), CLI handlers, slash handlers.
+ *
+ * Uses callbacks instead of direct enablementManager reference to keep
+ * packages/core independent of packages/cli.
+ */
+export async function canLoadServer(
+  serverId: string,
+  config: {
+    adminMcpEnabled: boolean;
+    allowedList?: string[];
+    excludedList?: string[];
+    enablement?: EnablementCallbacks;
+  },
+): Promise<ServerLoadResult> {
+  const normalizedId = normalizeServerId(serverId);
+
+  // 1. Admin kill switch
+  if (!config.adminMcpEnabled) {
+    return {
+      allowed: false,
+      reason:
+        'MCP servers are disabled by administrator. Check admin settings or contact your admin.',
+      blockType: 'admin',
+    };
+  }
+
+  // 2. Allowlist check
+  if (config.allowedList !== undefined) {
+    const { found, deprecationWarning } = isInSettingsList(
+      normalizedId,
+      config.allowedList,
+    );
+    if (deprecationWarning) {
+      coreEvents.emitFeedback('warning', deprecationWarning);
+    }
+    if (!found) {
+      return {
+        allowed: false,
+        reason: `Server '${serverId}' is not in mcp.allowed list. Add it to settings.json mcp.allowed array to enable.`,
+        blockType: 'allowlist',
+      };
+    }
+  }
+
+  // 3. Excludelist check
+  if (config.excludedList) {
+    const { found, deprecationWarning } = isInSettingsList(
+      normalizedId,
+      config.excludedList,
+    );
+    if (deprecationWarning) {
+      coreEvents.emitFeedback('warning', deprecationWarning);
+    }
+    if (found) {
+      return {
+        allowed: false,
+        reason: `Server '${serverId}' is blocked by mcp.excluded. Remove it from settings.json mcp.excluded array to enable.`,
+        blockType: 'excludelist',
+      };
+    }
+  }
+
+  // 4. Session disable check (before file-based enablement)
+  if (config.enablement?.isSessionDisabled(normalizedId)) {
+    return {
+      allowed: false,
+      reason: `Server '${serverId}' is disabled for this session. Run 'gemini mcp enable ${serverId} --session' to clear.`,
+      blockType: 'session',
+    };
+  }
+
+  // 5. File-based enablement check
+  if (
+    config.enablement &&
+    !(await config.enablement.isFileEnabled(normalizedId))
+  ) {
+    return {
+      allowed: false,
+      reason: `Server '${serverId}' is disabled. Run 'gemini mcp enable ${serverId}' to enable.`,
+      blockType: 'enablement',
+    };
+  }
+
+  return { allowed: true };
+}
+
+const MCP_ENABLEMENT_FILENAME = 'mcp-server-enablement.json';
+
+/**
+ * McpServerEnablementManager
+ *
+ * Manages the enabled/disabled state of MCP servers.
+ * Uses a simplified format compared to ExtensionEnablementManager.
+ * Supports both persistent (file) and session-only (in-memory) states.
+ *
+ * NOTE: Use getInstance() to get the singleton instance. This ensures
+ * session state (sessionDisabled Set) is shared across all code paths.
+ */
+export class McpServerEnablementManager {
+  private static instance: McpServerEnablementManager | null = null;
+
+  private readonly configFilePath: string;
+  private readonly configDir: string;
+  private readonly sessionDisabled = new Set<string>();
+
+  /**
+   * Get the singleton instance.
+   */
+  static getInstance(): McpServerEnablementManager {
+    if (!McpServerEnablementManager.instance) {
+      McpServerEnablementManager.instance = new McpServerEnablementManager();
+    }
+    return McpServerEnablementManager.instance;
+  }
+
+  /**
+   * Reset the singleton instance (for testing only).
+   */
+  static resetInstance(): void {
+    McpServerEnablementManager.instance = null;
+  }
+
+  constructor() {
+    this.configDir = Storage.getGlobalGeminiDir();
+    this.configFilePath = path.join(this.configDir, MCP_ENABLEMENT_FILENAME);
+  }
+
+  /**
+   * Check if server is enabled in FILE (persistent config only).
+   * Does NOT include session state.
+   */
+  async isFileEnabled(serverName: string): Promise<boolean> {
+    const config = await this.readConfig();
+    const state = config[normalizeServerId(serverName)];
+    return state?.enabled ?? true;
+  }
+
+  /**
+   * Check if server is session-disabled.
+   */
+  isSessionDisabled(serverName: string): boolean {
+    return this.sessionDisabled.has(normalizeServerId(serverName));
+  }
+
+  /**
+   * Check effective enabled state (combines file + session).
+   * Convenience method; canLoadServer() uses separate callbacks for granular blockType.
+   */
+  async isEffectivelyEnabled(serverName: string): Promise<boolean> {
+    if (this.isSessionDisabled(serverName)) {
+      return false;
+    }
+    return this.isFileEnabled(serverName);
+  }
+
+  /**
+   * Enable a server persistently.
+   * Removes the server from config file (defaults to enabled).
+   */
+  async enable(serverName: string): Promise<void> {
+    const normalizedName = normalizeServerId(serverName);
+    const config = await this.readConfig();
+
+    if (normalizedName in config) {
+      delete config[normalizedName];
+      await this.writeConfig(config);
+    }
+  }
+
+  /**
+   * Disable a server persistently.
+   * Adds server to config file with enabled: false.
+   */
+  async disable(serverName: string): Promise<void> {
+    const config = await this.readConfig();
+    config[normalizeServerId(serverName)] = { enabled: false };
+    await this.writeConfig(config);
+  }
+
+  /**
+   * Disable a server for current session only (in-memory).
+   */
+  disableForSession(serverName: string): void {
+    this.sessionDisabled.add(normalizeServerId(serverName));
+  }
+
+  /**
+   * Clear session disable for a server.
+   */
+  clearSessionDisable(serverName: string): void {
+    this.sessionDisabled.delete(normalizeServerId(serverName));
+  }
+
+  /**
+   * Get display state for a specific server (for UI).
+   */
+  async getDisplayState(serverName: string): Promise<McpServerDisplayState> {
+    const isSessionDisabled = this.isSessionDisabled(serverName);
+    const isPersistentDisabled = !(await this.isFileEnabled(serverName));
+
+    return {
+      enabled: !isSessionDisabled && !isPersistentDisabled,
+      isSessionDisabled,
+      isPersistentDisabled,
+    };
+  }
+
+  /**
+   * Get all display states (for UI listing).
+   */
+  async getAllDisplayStates(
+    serverIds: string[],
+  ): Promise<Record<string, McpServerDisplayState>> {
+    const result: Record<string, McpServerDisplayState> = {};
+    for (const serverId of serverIds) {
+      result[normalizeServerId(serverId)] =
+        await this.getDisplayState(serverId);
+    }
+    return result;
+  }
+
+  /**
+   * Get enablement callbacks for passing to core.
+   */
+  getEnablementCallbacks(): EnablementCallbacks {
+    return {
+      isSessionDisabled: (id) => this.isSessionDisabled(id),
+      isFileEnabled: (id) => this.isFileEnabled(id),
+    };
+  }
+
+  /**
+   * Auto-enable any disabled MCP servers by name.
+   * Returns server names that were actually re-enabled.
+   */
+  async autoEnableServers(serverNames: string[]): Promise<string[]> {
+    const enabledServers: string[] = [];
+
+    for (const serverName of serverNames) {
+      const normalizedName = normalizeServerId(serverName);
+      const state = await this.getDisplayState(normalizedName);
+
+      let wasDisabled = false;
+      if (state.isPersistentDisabled) {
+        await this.enable(normalizedName);
+        wasDisabled = true;
+      }
+      if (state.isSessionDisabled) {
+        this.clearSessionDisable(normalizedName);
+        wasDisabled = true;
+      }
+
+      if (wasDisabled) {
+        enabledServers.push(serverName);
+      }
+    }
+
+    return enabledServers;
+  }
+
+  /**
+   * Read config from file asynchronously.
+   */
+  private async readConfig(): Promise<McpServerEnablementConfig> {
+    try {
+      const content = await fs.readFile(this.configFilePath, 'utf-8');
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      return JSON.parse(content) as McpServerEnablementConfig;
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        'code' in error &&
+        error.code === 'ENOENT'
+      ) {
+        return {};
+      }
+      coreEvents.emitFeedback(
+        'error',
+        'Failed to read MCP server enablement config.',
+        error,
+      );
+      return {};
+    }
+  }
+
+  /**
+   * Write config to file asynchronously.
+   */
+  private async writeConfig(config: McpServerEnablementConfig): Promise<void> {
+    await fs.mkdir(this.configDir, { recursive: true });
+    await fs.writeFile(this.configFilePath, JSON.stringify(config, null, 2));
+  }
+}

packages/cli/src/test-utils/fixtures/simple.responses

@@ -0,0 +1 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"Hello! How can I help you today?"}],"role":"model"},"finishReason":"STOP"}]}]}

packages/cli/src/test-utils/fixtures/steering.responses

@@ -0,0 +1,3 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"role":"model","parts":[{"text":"Starting a long task. First, I'll list the files."},{"functionCall":{"name":"list_directory","args":{"dir_path":"."}}}]},"finishReason":"STOP"}]}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"role":"model","parts":[{"text":"I see the files. Since you want me to focus on .txt files, I will read file1.txt."},{"functionCall":{"name":"read_file","args":{"file_path":"file1.txt"}}}]},"finishReason":"STOP"}]}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"role":"model","parts":[{"text":"I have read file1.txt. Task complete."}]},"finishReason":"STOP"}]}]}

packages/cli/src/ui/auth/ApiAuthDialog.test.tsx

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { renderWithProviders } from '../../test-utils/render.js';
+import { waitFor } from '../../test-utils/async.js';
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { ApiAuthDialog } from './ApiAuthDialog.js';
+import { useKeypress } from '../hooks/useKeypress.js';
+import {
+  useTextBuffer,
+  type TextBuffer,
+} from '../components/shared/text-buffer.js';
+import { clearApiKey } from '@google/gemini-cli-core';
+
+// Mocks
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    clearApiKey: vi.fn().mockResolvedValue(undefined),
+  };
+});
+
+vi.mock('../hooks/useKeypress.js', () => ({
+  useKeypress: vi.fn(),
+}));
+
+vi.mock('../components/shared/text-buffer.js', async (importOriginal) => {
+  const actual =
+    await importOriginal<
+      typeof import('../components/shared/text-buffer.js')
+    >();
+  return {
+    ...actual,
+    useTextBuffer: vi.fn(),
+  };
+});
+
+vi.mock('../contexts/UIStateContext.js', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('../contexts/UIStateContext.js')>();
+  return {
+    ...actual,
+    useUIState: vi.fn(() => ({
+      terminalWidth: 80,
+    })),
+  };
+});
+
+const mockedUseKeypress = useKeypress as Mock;
+const mockedUseTextBuffer = useTextBuffer as Mock;
+
+describe('ApiAuthDialog', () => {
+  const onSubmit = vi.fn();
+  const onCancel = vi.fn();
+  let mockBuffer: TextBuffer;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.stubEnv('GEMINI_API_KEY', '');
+    mockBuffer = {
+      text: '',
+      lines: [''],
+      cursor: [0, 0],
+      visualCursor: [0, 0],
+      viewportVisualLines: [''],
+      handleInput: vi.fn(),
+      setText: vi.fn((newText) => {
+        mockBuffer.text = newText;
+        mockBuffer.viewportVisualLines = [newText];
+      }),
+    } as unknown as TextBuffer;
+    mockedUseTextBuffer.mockReturnValue(mockBuffer);
+  });
+
+  it('renders correctly', async () => {
+    const { lastFrame, unmount } = await renderWithProviders(
+      <ApiAuthDialog onSubmit={onSubmit} onCancel={onCancel} />,
+    );
+    expect(lastFrame()).toMatchSnapshot();
+    unmount();
+  });
+
+  it('renders with a defaultValue', async () => {
+    const { unmount } = await renderWithProviders(
+      <ApiAuthDialog
+        onSubmit={onSubmit}
+        onCancel={onCancel}
+        defaultValue="test-key"
+      />,
+    );
+    expect(mockedUseTextBuffer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        initialText: 'test-key',
+        viewport: expect.objectContaining({
+          height: 4,
+        }),
+      }),
+    );
+    unmount();
+  });
+
+  it.each([
+    {
+      keyName: 'enter',
+      sequence: '\r',
+      expectedCall: onSubmit,
+      args: ['submitted-key'],
+    },
+    { keyName: 'escape', sequence: '\u001b', expectedCall: onCancel, args: [] },
+  ])(
+    'calls $expectedCall.name when $keyName is pressed',
+    async ({ keyName, sequence, expectedCall, args }) => {
+      mockBuffer.text = 'submitted-key'; // Set for the onSubmit case
+      const { unmount } = await renderWithProviders(
+        <ApiAuthDialog onSubmit={onSubmit} onCancel={onCancel} />,
+      );
+      // calls[0] is the ApiAuthDialog's useKeypress (Ctrl+C handler)
+      // calls[1] is the TextInput's useKeypress (typing handler)
+      const keypressHandler = mockedUseKeypress.mock.calls[1][0];
+
+      keypressHandler({
+        name: keyName,
+        shift: false,
+        alt: false,
+        ctrl: false,
+        cmd: false,
+        sequence,
+      });
+
+      expect(expectedCall).toHaveBeenCalledWith(...args);
+      unmount();
+    },
+  );
+
+  it('displays an error message', async () => {
+    const { lastFrame, unmount } = await renderWithProviders(
+      <ApiAuthDialog
+        onSubmit={onSubmit}
+        onCancel={onCancel}
+        error="Invalid API Key"
+      />,
+    );
+
+    expect(lastFrame()).toContain('Invalid API Key');
+    unmount();
+  });
+
+  it('calls clearApiKey and clears buffer when Ctrl+C is pressed', async () => {
+    const { unmount } = await renderWithProviders(
+      <ApiAuthDialog onSubmit={onSubmit} onCancel={onCancel} />,
+    );
+    // Call 0 is ApiAuthDialog (isActive: true)
+    // Call 1 is TextInput (isActive: true, priority: true)
+    const keypressHandler = mockedUseKeypress.mock.calls[0][0];
+
+    keypressHandler({
+      name: 'c',
+      shift: false,
+      ctrl: true,
+      cmd: false,
+    });
+
+    await waitFor(() => {
+      expect(clearApiKey).toHaveBeenCalled();
+      expect(mockBuffer.setText).toHaveBeenCalledWith('');
+    });
+    unmount();
+  });
+});

packages/cli/src/ui/auth/ApiAuthDialog.tsx

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { useRef, useEffect } from 'react';
+import { Box, Text } from 'ink';
+import { theme } from '../semantic-colors.js';
+import { TextInput } from '../components/shared/TextInput.js';
+import { useTextBuffer } from '../components/shared/text-buffer.js';
+import { useUIState } from '../contexts/UIStateContext.js';
+import { clearApiKey, debugLogger } from '@google/gemini-cli-core';
+import { useKeypress } from '../hooks/useKeypress.js';
+import { Command } from '../key/keyMatchers.js';
+import { useKeyMatchers } from '../hooks/useKeyMatchers.js';
+
+interface ApiAuthDialogProps {
+  onSubmit: (apiKey: string) => void;
+  onCancel: () => void;
+  error?: string | null;
+  defaultValue?: string;
+}
+
+export function ApiAuthDialog({
+  onSubmit,
+  onCancel,
+  error,
+  defaultValue = '',
+}: ApiAuthDialogProps): React.JSX.Element {
+  const keyMatchers = useKeyMatchers();
+  const { terminalWidth } = useUIState();
+  const viewportWidth = terminalWidth - 8;
+
+  const pendingPromise = useRef<{ cancel: () => void } | null>(null);
+
+  useEffect(
+    () => () => {
+      pendingPromise.current?.cancel();
+    },
+    [],
+  );
+
+  const initialApiKey = defaultValue;
+
+  const buffer = useTextBuffer({
+    initialText: initialApiKey || '',
+    initialCursorOffset: initialApiKey?.length || 0,
+    viewport: {
+      width: viewportWidth,
+      height: 4,
+    },
+    inputFilter: (text) =>
+      text.replace(/[^a-zA-Z0-9_.-]/g, '').replace(/[\r\n]/g, ''),
+    singleLine: true,
+  });
+
+  const handleSubmit = (value: string) => {
+    onSubmit(value);
+  };
+
+  const handleClear = () => {
+    pendingPromise.current?.cancel();
+
+    let isCancelled = false;
+    const wrappedPromise = new Promise<void>((resolve, reject) => {
+      clearApiKey().then(
+        () => !isCancelled && resolve(),
+        (error) => !isCancelled && reject(error),
+      );
+    });
+
+    pendingPromise.current = {
+      cancel: () => {
+        isCancelled = true;
+      },
+    };
+
+    return wrappedPromise
+      .then(() => {
+        buffer.setText('');
+      })
+      .catch((err) => {
+        debugLogger.debug('Failed to clear API key:', err);
+      });
+  };
+
+  useKeypress(
+    (key) => {
+      if (keyMatchers[Command.CLEAR_INPUT](key)) {
+        void handleClear();
+        return true;
+      }
+      return false;
+    },
+    { isActive: true },
+  );
+
+  return (
+    <Box
+      borderStyle="round"
+      borderColor={theme.ui.focus}
+      flexDirection="column"
+      padding={1}
+      width="100%"
+    >
+      <Text bold color={theme.text.primary}>
+        Enter Gemini API Key
+      </Text>
+      <Box marginTop={1} flexDirection="column">
+        <Text color={theme.text.primary}>
+          Please enter your Gemini API key. It will be securely stored in your
+          system keychain.
+        </Text>
+        <Text color={theme.text.secondary}>
+          You can get an API key from{' '}
+          <Text color={theme.text.link}>
+            https://aistudio.google.com/app/apikey
+          </Text>
+        </Text>
+      </Box>
+      <Box marginTop={1} flexDirection="row">
+        <Box
+          borderStyle="round"
+          borderColor={theme.border.default}
+          paddingX={1}
+          flexGrow={1}
+        >
+          <TextInput
+            buffer={buffer}
+            onSubmit={handleSubmit}
+            onCancel={onCancel}
+            placeholder="Paste your API key here"
+          />
+        </Box>
+      </Box>
+      {error && (
+        <Box marginTop={1}>
+          <Text color={theme.status.error}>{error}</Text>
+        </Box>
+      )}
+      <Box marginTop={1}>
+        <Text color={theme.text.secondary}>
+          (Press Enter to submit, Esc to cancel, Ctrl+C to clear stored key)
+        </Text>
+      </Box>
+    </Box>
+  );
+}

packages/cli/src/ui/auth/AuthDialog.test.tsx

@@ -0,0 +1,458 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { act } from 'react';
+import { renderWithProviders } from '../../test-utils/render.js';
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type Mock,
+} from 'vitest';
+import { AuthDialog } from './AuthDialog.js';
+import { AuthType, type Config, debugLogger } from '@google/gemini-cli-core';
+import type { LoadedSettings } from '../../config/settings.js';
+import { AuthState } from '../types.js';
+import { RadioButtonSelect } from '../components/shared/RadioButtonSelect.js';
+import { useKeypress } from '../hooks/useKeypress.js';
+import { validateAuthMethodWithSettings } from './useAuth.js';
+import { runExitCleanup } from '../../utils/cleanup.js';
+import { Text } from 'ink';
+import { RELAUNCH_EXIT_CODE } from '../../utils/processUtils.js';
+
+// Mocks
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    clearCachedCredentialFile: vi.fn(),
+  };
+});
+
+vi.mock('../../utils/cleanup.js', () => ({
+  runExitCleanup: vi.fn(),
+}));
+
+vi.mock('./useAuth.js', () => ({
+  validateAuthMethodWithSettings: vi.fn(),
+}));
+
+vi.mock('../hooks/useKeypress.js', () => ({
+  useKeypress: vi.fn(),
+}));
+
+vi.mock('../components/shared/RadioButtonSelect.js', () => ({
+  RadioButtonSelect: vi.fn(({ items, initialIndex }) => (
+    <>
+      {items.map((item: { value: string; label: string }, index: number) => (
+        <Text key={item.value}>
+          {index === initialIndex ? '(selected)' : '(not selected)'}{' '}
+          {item.label}
+        </Text>
+      ))}
+    </>
+  )),
+}));
+
+const mockedUseKeypress = useKeypress as Mock;
+const mockedRadioButtonSelect = RadioButtonSelect as Mock;
+const mockedValidateAuthMethod = validateAuthMethodWithSettings as Mock;
+const mockedRunExitCleanup = runExitCleanup as Mock;
+
+describe('AuthDialog', () => {
+  let props: {
+    config: Config;
+    settings: LoadedSettings;
+    setAuthState: (state: AuthState) => void;
+    authError: string | null;
+    onAuthError: (error: string | null) => void;
+    setAuthContext: (context: { requiresRestart?: boolean }) => void;
+  };
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.stubEnv('CLOUD_SHELL', undefined as unknown as string);
+    vi.stubEnv('GEMINI_CLI_USE_COMPUTE_ADC', undefined as unknown as string);
+    vi.stubEnv('GEMINI_DEFAULT_AUTH_TYPE', undefined as unknown as string);
+    vi.stubEnv('GEMINI_API_KEY', undefined as unknown as string);
+
+    props = {
+      config: {
+        isBrowserLaunchSuppressed: vi.fn().mockReturnValue(false),
+      } as unknown as Config,
+      settings: {
+        merged: {
+          security: {
+            auth: {},
+          },
+        },
+        setValue: vi.fn(),
+      } as unknown as LoadedSettings,
+      setAuthState: vi.fn(),
+      authError: null,
+      onAuthError: vi.fn(),
+      setAuthContext: vi.fn(),
+    };
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  describe('Environment Variable Effects on Auth Options', () => {
+    const cloudShellLabel = 'Use Cloud Shell user credentials';
+    const metadataServerLabel =
+      'Use metadata server application default credentials';
+    const computeAdcItem = (label: string) => ({
+      label,
+      value: AuthType.COMPUTE_ADC,
+      key: AuthType.COMPUTE_ADC,
+    });
+
+    it.each([
+      {
+        env: { CLOUD_SHELL: 'true' },
+        shouldContain: [computeAdcItem(cloudShellLabel)],
+        shouldNotContain: [computeAdcItem(metadataServerLabel)],
+        desc: 'in Cloud Shell',
+      },
+      {
+        env: { GEMINI_CLI_USE_COMPUTE_ADC: 'true' },
+        shouldContain: [computeAdcItem(metadataServerLabel)],
+        shouldNotContain: [computeAdcItem(cloudShellLabel)],
+        desc: 'with GEMINI_CLI_USE_COMPUTE_ADC',
+      },
+      {
+        env: {},
+        shouldContain: [],
+        shouldNotContain: [
+          computeAdcItem(cloudShellLabel),
+          computeAdcItem(metadataServerLabel),
+        ],
+        desc: 'by default',
+      },
+    ])(
+      'correctly shows/hides COMPUTE_ADC options $desc',
+      async ({ env, shouldContain, shouldNotContain }) => {
+        for (const [key, value] of Object.entries(env)) {
+          vi.stubEnv(key, value as string);
+        }
+        const { unmount } = await renderWithProviders(
+          <AuthDialog {...props} />,
+        );
+        const items = mockedRadioButtonSelect.mock.calls[0][0].items;
+        for (const item of shouldContain) {
+          expect(items).toContainEqual(item);
+        }
+        for (const item of shouldNotContain) {
+          expect(items).not.toContainEqual(item);
+        }
+        unmount();
+      },
+    );
+  });
+
+  it('filters auth types when enforcedType is set', async () => {
+    props.settings.merged.security.auth.enforcedType = AuthType.USE_GEMINI;
+    const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+    const items = mockedRadioButtonSelect.mock.calls[0][0].items;
+    expect(items).toHaveLength(1);
+    expect(items[0].value).toBe(AuthType.USE_GEMINI);
+    unmount();
+  });
+
+  it('sets initial index to 0 when enforcedType is set', async () => {
+    props.settings.merged.security.auth.enforcedType = AuthType.USE_GEMINI;
+    const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+    const { initialIndex } = mockedRadioButtonSelect.mock.calls[0][0];
+    expect(initialIndex).toBe(0);
+    unmount();
+  });
+
+  describe('Initial Auth Type Selection', () => {
+    it.each([
+      {
+        setup: () => {
+          props.settings.merged.security.auth.selectedType =
+            AuthType.USE_VERTEX_AI;
+        },
+        expected: AuthType.USE_VERTEX_AI,
+        desc: 'from settings',
+      },
+      {
+        setup: () => {
+          vi.stubEnv('GEMINI_DEFAULT_AUTH_TYPE', AuthType.USE_GEMINI);
+        },
+        expected: AuthType.USE_GEMINI,
+        desc: 'from GEMINI_DEFAULT_AUTH_TYPE env var',
+      },
+      {
+        setup: () => {
+          vi.stubEnv('GEMINI_API_KEY', 'test-key');
+        },
+        expected: AuthType.USE_GEMINI,
+        desc: 'from GEMINI_API_KEY env var',
+      },
+      {
+        setup: () => {},
+        expected: AuthType.LOGIN_WITH_GOOGLE,
+        desc: 'defaults to Sign in with Google',
+      },
+    ])('selects initial auth type $desc', async ({ setup, expected }) => {
+      setup();
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const { items, initialIndex } = mockedRadioButtonSelect.mock.calls[0][0];
+      expect(items[initialIndex].value).toBe(expected);
+      unmount();
+    });
+  });
+
+  describe('handleAuthSelect', () => {
+    it('calls onAuthError if validation fails', async () => {
+      mockedValidateAuthMethod.mockResolvedValue('Invalid method');
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const { onSelect: handleAuthSelect } =
+        mockedRadioButtonSelect.mock.calls[0][0];
+      await handleAuthSelect(AuthType.USE_GEMINI);
+
+      expect(mockedValidateAuthMethod).toHaveBeenCalledWith(
+        AuthType.USE_GEMINI,
+        props.settings,
+      );
+      expect(props.onAuthError).toHaveBeenCalledWith('Invalid method');
+      expect(props.settings.setValue).not.toHaveBeenCalled();
+      unmount();
+    });
+
+    it('sets auth context with requiresRestart: true for LOGIN_WITH_GOOGLE', async () => {
+      mockedValidateAuthMethod.mockResolvedValue(null);
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const { onSelect: handleAuthSelect } =
+        mockedRadioButtonSelect.mock.calls[0][0];
+      await handleAuthSelect(AuthType.LOGIN_WITH_GOOGLE);
+
+      expect(props.setAuthContext).toHaveBeenCalledWith({
+        requiresRestart: true,
+      });
+      unmount();
+    });
+
+    it('sets auth context with requiresRestart: true for USE_VERTEX_AI in Cloud Shell', async () => {
+      vi.stubEnv('CLOUD_SHELL', 'true');
+      mockedValidateAuthMethod.mockResolvedValue(null);
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const { onSelect: handleAuthSelect } =
+        mockedRadioButtonSelect.mock.calls[0][0];
+      await handleAuthSelect(AuthType.USE_VERTEX_AI);
+
+      expect(props.setAuthContext).toHaveBeenCalledWith({
+        requiresRestart: true,
+      });
+      unmount();
+    });
+
+    it('sets auth context with empty object for USE_VERTEX_AI outside Cloud Shell', async () => {
+      vi.stubEnv('CLOUD_SHELL', '');
+      mockedValidateAuthMethod.mockResolvedValue(null);
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const { onSelect: handleAuthSelect } =
+        mockedRadioButtonSelect.mock.calls[0][0];
+      await handleAuthSelect(AuthType.USE_VERTEX_AI);
+
+      expect(props.setAuthContext).toHaveBeenCalledWith({});
+      unmount();
+    });
+
+    it('sets auth context with empty object for other auth types', async () => {
+      mockedValidateAuthMethod.mockResolvedValue(null);
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const { onSelect: handleAuthSelect } =
+        mockedRadioButtonSelect.mock.calls[0][0];
+      await handleAuthSelect(AuthType.USE_GEMINI);
+
+      expect(props.setAuthContext).toHaveBeenCalledWith({});
+      unmount();
+    });
+
+    it('always shows API key dialog even when env var is present', async () => {
+      mockedValidateAuthMethod.mockResolvedValue(null);
+      vi.stubEnv('GEMINI_API_KEY', 'test-key-from-env');
+      // props.settings.merged.security.auth.selectedType is undefined here, simulating initial setup
+
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const { onSelect: handleAuthSelect } =
+        mockedRadioButtonSelect.mock.calls[0][0];
+      await handleAuthSelect(AuthType.USE_GEMINI);
+
+      expect(props.setAuthState).toHaveBeenCalledWith(
+        AuthState.AwaitingApiKeyInput,
+      );
+      unmount();
+    });
+
+    it('always shows API key dialog even when env var is empty string', async () => {
+      mockedValidateAuthMethod.mockResolvedValue(null);
+      vi.stubEnv('GEMINI_API_KEY', ''); // Empty string
+      // props.settings.merged.security.auth.selectedType is undefined here
+
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const { onSelect: handleAuthSelect } =
+        mockedRadioButtonSelect.mock.calls[0][0];
+      await handleAuthSelect(AuthType.USE_GEMINI);
+
+      expect(props.setAuthState).toHaveBeenCalledWith(
+        AuthState.AwaitingApiKeyInput,
+      );
+      unmount();
+    });
+
+    it('shows API key dialog on initial setup if no env var is present', async () => {
+      mockedValidateAuthMethod.mockResolvedValue(null);
+      // process.env['GEMINI_API_KEY'] is not set
+      // props.settings.merged.security.auth.selectedType is undefined here, simulating initial setup
+
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const { onSelect: handleAuthSelect } =
+        mockedRadioButtonSelect.mock.calls[0][0];
+      await handleAuthSelect(AuthType.USE_GEMINI);
+
+      expect(props.setAuthState).toHaveBeenCalledWith(
+        AuthState.AwaitingApiKeyInput,
+      );
+      unmount();
+    });
+
+    it('always shows API key dialog on re-auth even if env var is present', async () => {
+      mockedValidateAuthMethod.mockResolvedValue(null);
+      vi.stubEnv('GEMINI_API_KEY', 'test-key-from-env');
+      // Simulate switching from a different auth method (e.g., Google Login → API key)
+      props.settings.merged.security.auth.selectedType =
+        AuthType.LOGIN_WITH_GOOGLE;
+
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const { onSelect: handleAuthSelect } =
+        mockedRadioButtonSelect.mock.calls[0][0];
+      await handleAuthSelect(AuthType.USE_GEMINI);
+
+      expect(props.setAuthState).toHaveBeenCalledWith(
+        AuthState.AwaitingApiKeyInput,
+      );
+      unmount();
+    });
+
+    it('exits process for Sign in with Google when browser is suppressed', async () => {
+      vi.useFakeTimers();
+      const exitSpy = vi
+        .spyOn(process, 'exit')
+        .mockImplementation(() => undefined as never);
+      const logSpy = vi.spyOn(debugLogger, 'log').mockImplementation(() => {});
+      vi.mocked(props.config.isBrowserLaunchSuppressed).mockReturnValue(true);
+      mockedValidateAuthMethod.mockResolvedValue(null);
+
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const { onSelect: handleAuthSelect } =
+        mockedRadioButtonSelect.mock.calls[0][0];
+      await act(async () => {
+        await handleAuthSelect(AuthType.LOGIN_WITH_GOOGLE);
+        await vi.runAllTimersAsync();
+      });
+
+      expect(mockedRunExitCleanup).toHaveBeenCalled();
+      expect(exitSpy).toHaveBeenCalledWith(RELAUNCH_EXIT_CODE);
+
+      exitSpy.mockRestore();
+      logSpy.mockRestore();
+      vi.useRealTimers();
+      unmount();
+    });
+  });
+
+  it('displays authError when provided', async () => {
+    props.authError = 'Something went wrong';
+    const { lastFrame, unmount } = await renderWithProviders(
+      <AuthDialog {...props} />,
+    );
+    expect(lastFrame()).toContain('Something went wrong');
+    unmount();
+  });
+
+  describe('useKeypress', () => {
+    it.each([
+      {
+        desc: 'does nothing on escape if authError is present',
+        setup: () => {
+          props.authError = 'Some error';
+        },
+        expectations: (p: typeof props) => {
+          expect(p.onAuthError).not.toHaveBeenCalled();
+          expect(p.setAuthState).not.toHaveBeenCalled();
+        },
+      },
+      {
+        desc: 'calls onAuthError on escape if no auth method is set',
+        setup: () => {
+          props.settings.merged.security.auth.selectedType = undefined;
+        },
+        expectations: (p: typeof props) => {
+          expect(p.onAuthError).toHaveBeenCalledWith(
+            'You must select an auth method to proceed. Press Ctrl+C twice to exit.',
+          );
+        },
+      },
+      {
+        desc: 'calls setAuthState(Unauthenticated) on escape if auth method is set',
+        setup: () => {
+          props.settings.merged.security.auth.selectedType =
+            AuthType.USE_GEMINI;
+        },
+        expectations: (p: typeof props) => {
+          expect(p.setAuthState).toHaveBeenCalledWith(
+            AuthState.Unauthenticated,
+          );
+          expect(p.settings.setValue).not.toHaveBeenCalled();
+        },
+      },
+    ])('$desc', async ({ setup, expectations }) => {
+      setup();
+      const { unmount } = await renderWithProviders(<AuthDialog {...props} />);
+      const keypressHandler = mockedUseKeypress.mock.calls[0][0];
+      keypressHandler({ name: 'escape' });
+      expectations(props);
+      unmount();
+    });
+  });
+
+  describe('Snapshots', () => {
+    it('renders correctly with default props', async () => {
+      const { lastFrame, unmount } = await renderWithProviders(
+        <AuthDialog {...props} />,
+      );
+      expect(lastFrame()).toMatchSnapshot();
+      unmount();
+    });
+
+    it('renders correctly with auth error', async () => {
+      props.authError = 'Something went wrong';
+      const { lastFrame, unmount } = await renderWithProviders(
+        <AuthDialog {...props} />,
+      );
+      expect(lastFrame()).toMatchSnapshot();
+      unmount();
+    });
+
+    it('renders correctly with enforced auth type', async () => {
+      props.settings.merged.security.auth.enforcedType = AuthType.USE_GEMINI;
+      const { lastFrame, unmount } = await renderWithProviders(
+        <AuthDialog {...props} />,
+      );
+      expect(lastFrame()).toMatchSnapshot();
+      unmount();
+    });
+  });
+});