Add files using upload-large-folder tool

packages/cli/src/__snapshots__/nonInteractiveCli.test.ts.snap

@@ -0,0 +1,35 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`runNonInteractive > should emit appropriate error event in streaming JSON mode: 'loop detected' 1`] = `
+"{"type":"init","timestamp":"<TIMESTAMP>","session_id":"test-session-id","model":"test-model"}
+{"type":"message","timestamp":"<TIMESTAMP>","role":"user","content":"Loop test"}
+{"type":"error","timestamp":"<TIMESTAMP>","severity":"warning","message":"Loop detected, stopping execution"}
+{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"cached":0,"input":0,"duration_ms":<DURATION>,"tool_calls":0,"models":{}}}
+"
+`;
+
+exports[`runNonInteractive > should emit appropriate error event in streaming JSON mode: 'max session turns' 1`] = `
+"{"type":"init","timestamp":"<TIMESTAMP>","session_id":"test-session-id","model":"test-model"}
+{"type":"message","timestamp":"<TIMESTAMP>","role":"user","content":"Max turns test"}
+{"type":"error","timestamp":"<TIMESTAMP>","severity":"error","message":"Maximum session turns exceeded"}
+{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"cached":0,"input":0,"duration_ms":<DURATION>,"tool_calls":0,"models":{}}}
+"
+`;
+
+exports[`runNonInteractive > should emit appropriate events for streaming JSON output 1`] = `
+"{"type":"init","timestamp":"<TIMESTAMP>","session_id":"test-session-id","model":"test-model"}
+{"type":"message","timestamp":"<TIMESTAMP>","role":"user","content":"Stream test"}
+{"type":"message","timestamp":"<TIMESTAMP>","role":"assistant","content":"Thinking...","delta":true}
+{"type":"tool_use","timestamp":"<TIMESTAMP>","tool_name":"testTool","tool_id":"tool-1","parameters":{"arg1":"value1"}}
+{"type":"tool_result","timestamp":"<TIMESTAMP>","tool_id":"tool-1","status":"success","output":"Tool executed successfully"}
+{"type":"message","timestamp":"<TIMESTAMP>","role":"assistant","content":"Final answer","delta":true}
+{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"cached":0,"input":0,"duration_ms":<DURATION>,"tool_calls":0,"models":{}}}
+"
+`;
+
+exports[`runNonInteractive > should write a single newline between sequential text outputs from the model 1`] = `
+"Use mock tool
+Use mock tool again
+Finished.
+"
+`;

packages/cli/src/__snapshots__/nonInteractiveCliAgentSession.test.ts.snap

@@ -0,0 +1,35 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`runNonInteractive > should emit appropriate error event in streaming JSON mode: 'loop detected' 1`] = `
+"{"type":"init","timestamp":"<TIMESTAMP>","session_id":"test-session-id","model":"test-model"}
+{"type":"message","timestamp":"<TIMESTAMP>","role":"user","content":"Loop test"}
+{"type":"error","timestamp":"<TIMESTAMP>","severity":"warning","message":"Loop detected, stopping execution"}
+{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"cached":0,"input":0,"duration_ms":<DURATION>,"tool_calls":0,"models":{}}}
+"
+`;
+
+exports[`runNonInteractive > should emit appropriate error event in streaming JSON mode: 'max session turns' 1`] = `
+"{"type":"init","timestamp":"<TIMESTAMP>","session_id":"test-session-id","model":"test-model"}
+{"type":"message","timestamp":"<TIMESTAMP>","role":"user","content":"Max turns test"}
+{"type":"error","timestamp":"<TIMESTAMP>","severity":"error","message":"Maximum session turns exceeded"}
+{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"cached":0,"input":0,"duration_ms":<DURATION>,"tool_calls":0,"models":{}}}
+"
+`;
+
+exports[`runNonInteractive > should emit appropriate events for streaming JSON output 1`] = `
+"{"type":"init","timestamp":"<TIMESTAMP>","session_id":"test-session-id","model":"test-model"}
+{"type":"message","timestamp":"<TIMESTAMP>","role":"user","content":"Stream test"}
+{"type":"message","timestamp":"<TIMESTAMP>","role":"assistant","content":"Thinking...","delta":true}
+{"type":"tool_use","timestamp":"<TIMESTAMP>","tool_name":"testTool","tool_id":"tool-1","parameters":{"arg1":"value1"}}
+{"type":"tool_result","timestamp":"<TIMESTAMP>","tool_id":"tool-1","status":"success","output":"Tool executed successfully"}
+{"type":"message","timestamp":"<TIMESTAMP>","role":"assistant","content":"Final answer","delta":true}
+{"type":"result","timestamp":"<TIMESTAMP>","status":"success","stats":{"total_tokens":0,"input_tokens":0,"output_tokens":0,"cached":0,"input":0,"duration_ms":<DURATION>,"tool_calls":0,"models":{}}}
+"
+`;
+
+exports[`runNonInteractive > should write a single newline between sequential text outputs from the model 1`] = `
+"Use mock tool
+Use mock tool again
+Finished.
+"
+`;

packages/cli/src/acp/README.md

@@ -0,0 +1,81 @@
+# Agent Client Protocol (ACP) Implementation
+
+This directory contains the implementation of the Agent Client Protocol (ACP)
+for the Gemini CLI. The ACP allows external clients (like IDE extensions) to
+communicate with the Gemini CLI agent over a structured JSON-RPC based protocol.
+
+## Directory Structure
+
+Following Phase 1 of the modularization refactor, the ACP client is organized
+into the following specialized modules, all sharing the `acp` prefix for
+consistency:
+
+- **[acpStdioTransport.ts](./acpStdioTransport.ts)**: Handles raw I/O. It sets
+  up the Web streams for standard input/output and creates the
+  `AgentSideConnection` using line-delimited JSON (ndjson).
+- **[acpRpcDispatcher.ts](./acpRpcDispatcher.ts)**: Contains the `GeminiAgent`
+  class. This is the main entry point for incoming JSON-RPC messages. It
+  implements the protocol methods and delegates session-specific work to the
+  manager and individual sessions.
+- **[acpSessionManager.ts](./acpSessionManager.ts)**: Manages multi-session
+  state. It handles session creation (`newSession`), loading (`loadSession`),
+  and configuration, isolating session state from the RPC routing.
+- **[acpSession.ts](./acpSession.ts)**: Manages individual active chat sessions.
+  It handles prompt execution, `@path` file resolution, tool execution, command
+  interception, and streaming updates back to the client.
+- **[acpUtils.ts](./acpUtils.ts)**: Contains shared helper functions, type
+  mappers (e.g., mapping internal tool kinds to ACP kinds), and Zod schemas used
+  across the modules.
+- **[acpErrors.ts](./acpErrors.ts)**: Centralized error handling and mapping to
+  ACP-compliant error codes.
+- **[acpCommandHandler.ts](./acpCommandHandler.ts)**: Handles interception and
+  execution of slash commands (e.g., `/memory`, `/init`) sent via ACP prompts.
+- **[acpFileSystemService.ts](./acpFileSystemService.ts)**: Provides access to
+  the file system restricted by the workspace boundaries and permissions.
+
+## Development Instructions
+
+### Running Tests
+
+Tests are co-located with the source files:
+
+- `acpRpcDispatcher.test.ts`: Tests for initialization, authentication, and
+  handler delegation.
+- `acpSessionManager.test.ts`: Tests for session lifecycle and configuration.
+- `acpSession.test.ts`: Tests for prompt loops, tool execution, and @path
+  resolution.
+- `acpResume.test.ts`: Integration tests for loading/resuming sessions.
+
+To run specific tests, use Vitest with the workspace filter:
+
+```bash
+# General pattern
+npm test -w @google/gemini-cli -- src/acp/<test-file-name>.ts
+
+# Example
+npm test -w @google/gemini-cli -- src/acp/acpRpcDispatcher.test.ts
+```
+
+Note: You may need to ensure your environment has Node available. If running in
+a restricted environment, try sourcing NVM first:
+
+```bash
+source ~/.nvm/nvm.sh && nvm use default && npm test -w @google/gemini-cli -- src/acp/acpSession.test.ts
+```
+
+### Adding New Features
+
+- **New RPC Method**: Add the method to `GeminiAgent` in `acpRpcDispatcher.ts`
+  and register it in the `AgentSideConnection` setup if necessary.
+- **Session State**: If a feature requires storing state across turns within a
+  session, add it to the `Session` class in `acpSession.ts`.
+- **Protocol Helpers**: Add any new mapping or serialization logic to
+  `acpUtils.ts`.
+
+### Coding Conventions
+
+- **Imports**: Use specific imports and do not import across package boundaries
+  using relative paths.
+- **License Headers**: All new files must include the Apache-2.0 license header.
+- **Type Safety**: Avoid using `any` assertions. Use Zod schemas to validate
+  untrusted input from the protocol.

packages/cli/src/acp/acpCommandHandler.test.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { CommandHandler } from './acpCommandHandler.js';
+import { describe, it, expect } from 'vitest';
+
+describe('CommandHandler', () => {
+  it('parses commands correctly', () => {
+    const handler = new CommandHandler();
+    // @ts-expect-error - testing private method
+    const parse = (query: string) => handler.parseSlashCommand(query);
+
+    const memShow = parse('/memory show');
+    expect(memShow.commandToExecute?.name).toBe('memory show');
+    expect(memShow.args).toBe('');
+
+    const memList = parse('/memory list');
+    expect(memList.commandToExecute?.name).toBe('memory list');
+
+    const extList = parse('/extensions list');
+    expect(extList.commandToExecute?.name).toBe('extensions list');
+
+    const init = parse('/init');
+    expect(init.commandToExecute?.name).toBe('init');
+
+    const about = parse('/about');
+    expect(about.commandToExecute?.name).toBe('about');
+
+    const help = parse('/help');
+    expect(help.commandToExecute?.name).toBe('help');
+  });
+});

packages/cli/src/acp/acpCommandHandler.ts

@@ -0,0 +1,138 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Command, CommandContext } from './commands/types.js';
+import { CommandRegistry } from './commands/commandRegistry.js';
+import { MemoryCommand } from './commands/memory.js';
+import { ExtensionsCommand } from './commands/extensions.js';
+import { InitCommand } from './commands/init.js';
+import { RestoreCommand } from './commands/restore.js';
+import { AboutCommand } from './commands/about.js';
+import { HelpCommand } from './commands/help.js';
+
+export class CommandHandler {
+  private registry: CommandRegistry;
+
+  constructor() {
+    this.registry = CommandHandler.createRegistry();
+  }
+
+  private static createRegistry(): CommandRegistry {
+    const registry = new CommandRegistry();
+    registry.register(new MemoryCommand());
+    registry.register(new ExtensionsCommand());
+    registry.register(new InitCommand());
+    registry.register(new RestoreCommand());
+    registry.register(new AboutCommand());
+    registry.register(new HelpCommand(registry));
+    return registry;
+  }
+
+  getAvailableCommands(): Array<{ name: string; description: string }> {
+    return this.registry.getAllCommands().map((cmd) => ({
+      name: cmd.name,
+      description: cmd.description,
+    }));
+  }
+
+  /**
+   * Parses and executes a command string if it matches a registered command.
+   * Returns true if a command was handled, false otherwise.
+   */
+  async handleCommand(
+    commandText: string,
+    context: CommandContext,
+  ): Promise<boolean> {
+    const { commandToExecute, args } = this.parseSlashCommand(commandText);
+
+    if (commandToExecute) {
+      await this.runCommand(commandToExecute, args, context);
+      return true;
+    }
+
+    return false;
+  }
+
+  private async runCommand(
+    commandToExecute: Command,
+    args: string,
+    context: CommandContext,
+  ): Promise<void> {
+    try {
+      const result = await commandToExecute.execute(
+        context,
+        args ? args.split(/\s+/) : [],
+      );
+
+      let messageContent = '';
+      if (typeof result.data === 'string') {
+        messageContent = result.data;
+      } else if (
+        typeof result.data === 'object' &&
+        result.data !== null &&
+        'content' in result.data
+      ) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-explicit-any
+        messageContent = (result.data as Record<string, any>)[
+          'content'
+        ] as string;
+      } else {
+        messageContent = JSON.stringify(result.data, null, 2);
+      }
+
+      await context.sendMessage(messageContent);
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      await context.sendMessage(`Error: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Parses a raw slash command string into its matching headless command and arguments.
+   * Mirrors `packages/cli/src/utils/commands.ts` logic.
+   */
+  private parseSlashCommand(query: string): {
+    commandToExecute: Command | undefined;
+    args: string;
+  } {
+    const trimmed = query.trim();
+    const parts = trimmed.substring(1).trim().split(/\s+/);
+    const commandPath = parts.filter((p) => p);
+
+    let currentCommands = this.registry.getAllCommands();
+    let commandToExecute: Command | undefined;
+    let pathIndex = 0;
+
+    for (const part of commandPath) {
+      const foundCommand = currentCommands.find((cmd) => {
+        const expectedName = commandPath.slice(0, pathIndex + 1).join(' ');
+        return (
+          cmd.name === part ||
+          cmd.name === expectedName ||
+          cmd.aliases?.includes(part) ||
+          cmd.aliases?.includes(expectedName)
+        );
+      });
+
+      if (foundCommand) {
+        commandToExecute = foundCommand;
+        pathIndex++;
+        if (foundCommand.subCommands) {
+          currentCommands = foundCommand.subCommands;
+        } else {
+          break;
+        }
+      } else {
+        break;
+      }
+    }
+
+    const args = parts.slice(pathIndex).join(' ');
+
+    return { commandToExecute, args };
+  }
+}

packages/cli/src/acp/acpErrors.test.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { getAcpErrorMessage } from './acpErrors.js';
+
+describe('getAcpErrorMessage', () => {
+  it('should return plain error message', () => {
+    expect(getAcpErrorMessage(new Error('plain error'))).toBe('plain error');
+  });
+
+  it('should parse simple JSON error response', () => {
+    const json = JSON.stringify({ error: { message: 'json error' } });
+    expect(getAcpErrorMessage(new Error(json))).toBe('json error');
+  });
+
+  it('should parse double-encoded JSON error response', () => {
+    const innerJson = JSON.stringify({ error: { message: 'nested error' } });
+    const outerJson = JSON.stringify({ error: { message: innerJson } });
+    expect(getAcpErrorMessage(new Error(outerJson))).toBe('nested error');
+  });
+
+  it('should parse array-style JSON error response', () => {
+    const json = JSON.stringify([{ error: { message: 'array error' } }]);
+    expect(getAcpErrorMessage(new Error(json))).toBe('array error');
+  });
+
+  it('should parse JSON with top-level message field', () => {
+    const json = JSON.stringify({ message: 'top-level message' });
+    expect(getAcpErrorMessage(new Error(json))).toBe('top-level message');
+  });
+
+  it('should handle JSON with trailing newline', () => {
+    const json = JSON.stringify({ error: { message: 'newline error' } }) + '\n';
+    expect(getAcpErrorMessage(new Error(json))).toBe('newline error');
+  });
+
+  it('should return original message if JSON parsing fails', () => {
+    const invalidJson = '{ not-json }';
+    expect(getAcpErrorMessage(new Error(invalidJson))).toBe(invalidJson);
+  });
+});

packages/cli/src/acp/acpErrors.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { getErrorMessage as getCoreErrorMessage } from '@google/gemini-cli-core';
+
+/**
+ * Extracts a human-readable error message specifically for ACP (IDE) clients.
+ * This function recursively parses JSON error blobs that are common in
+ * Google API responses but ugly to display in an IDE's UI.
+ */
+export function getAcpErrorMessage(error: unknown): string {
+  const coreMessage = getCoreErrorMessage(error);
+  return extractRecursiveMessage(coreMessage);
+}
+
+function extractRecursiveMessage(input: string): string {
+  const trimmed = input.trim();
+
+  // Attempt to parse JSON error responses (common in Google API errors)
+  if (
+    (trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+    (trimmed.startsWith('[') && trimmed.endsWith(']'))
+  ) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const parsed = JSON.parse(trimmed);
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const next =
+        parsed?.error?.message ||
+        parsed?.[0]?.error?.message ||
+        parsed?.message;
+
+      if (next && typeof next === 'string' && next !== input) {
+        return extractRecursiveMessage(next);
+      }
+    } catch {
+      // Fall back to original string if parsing fails
+    }
+  }
+  return input;
+}

packages/cli/src/acp/acpFileSystemService.test.ts

@@ -0,0 +1,236 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type Mocked,
+} from 'vitest';
+import { AcpFileSystemService } from './acpFileSystemService.js';
+import type { AgentSideConnection } from '@agentclientprotocol/sdk';
+import type { FileSystemService } from '@google/gemini-cli-core';
+import os from 'node:os';
+
+vi.mock('node:os', () => ({
+  default: {
+    homedir: vi.fn(),
+  },
+}));
+
+describe('AcpFileSystemService', () => {
+  let mockConnection: Mocked<AgentSideConnection>;
+  let mockFallback: Mocked<FileSystemService>;
+  let service: AcpFileSystemService;
+
+  beforeEach(() => {
+    mockConnection = {
+      requestPermission: vi.fn(),
+      sessionUpdate: vi.fn(),
+      writeTextFile: vi.fn(),
+      readTextFile: vi.fn(),
+    } as unknown as Mocked<AgentSideConnection>;
+    mockFallback = {
+      readTextFile: vi.fn(),
+      writeTextFile: vi.fn(),
+    };
+    vi.mocked(os.homedir).mockReturnValue('/home/user');
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('readTextFile', () => {
+    it.each([
+      {
+        capability: true,
+        path: '/path/to/file',
+        desc: 'connection if capability exists and file is inside root',
+        setup: () => {
+          mockConnection.readTextFile.mockResolvedValue({ content: 'content' });
+        },
+        verify: () => {
+          expect(mockConnection.readTextFile).toHaveBeenCalledWith({
+            path: '/path/to/file',
+            sessionId: 'session-1',
+          });
+          expect(mockFallback.readTextFile).not.toHaveBeenCalled();
+        },
+      },
+      {
+        capability: false,
+        path: '/path/to/file',
+        desc: 'fallback if capability missing',
+        setup: () => {
+          mockFallback.readTextFile.mockResolvedValue('content');
+        },
+        verify: () => {
+          expect(mockFallback.readTextFile).toHaveBeenCalledWith(
+            '/path/to/file',
+          );
+          expect(mockConnection.readTextFile).not.toHaveBeenCalled();
+        },
+      },
+      {
+        capability: true,
+        path: '/outside/file',
+        desc: 'fallback if capability exists but file is outside root',
+        setup: () => {
+          mockFallback.readTextFile.mockResolvedValue('content');
+        },
+        verify: () => {
+          expect(mockFallback.readTextFile).toHaveBeenCalledWith(
+            '/outside/file',
+          );
+          expect(mockConnection.readTextFile).not.toHaveBeenCalled();
+        },
+      },
+      {
+        capability: true,
+        path: '/home/user/.gemini/tmp/file.md',
+        root: '/home/user',
+        desc: 'fallback if file is inside global gemini dir, even if root overlaps',
+        setup: () => {
+          mockFallback.readTextFile.mockResolvedValue('content');
+        },
+        verify: () => {
+          expect(mockFallback.readTextFile).toHaveBeenCalledWith(
+            '/home/user/.gemini/tmp/file.md',
+          );
+          expect(mockConnection.readTextFile).not.toHaveBeenCalled();
+        },
+      },
+    ])(
+      'should use $desc',
+      async ({ capability, path, root, setup, verify }) => {
+        service = new AcpFileSystemService(
+          mockConnection,
+          'session-1',
+          { readTextFile: capability, writeTextFile: true },
+          mockFallback,
+          root || '/path/to',
+        );
+        setup();
+
+        const result = await service.readTextFile(path);
+
+        expect(result).toBe('content');
+        verify();
+      },
+    );
+
+    it('should throw normalized ENOENT error when readTextFile encounters "Resource not found"', async () => {
+      service = new AcpFileSystemService(
+        mockConnection,
+        'session-1',
+        { readTextFile: true, writeTextFile: true },
+        mockFallback,
+        '/path/to',
+      );
+      mockConnection.readTextFile.mockRejectedValue(
+        new Error('Resource not found for document'),
+      );
+
+      await expect(
+        service.readTextFile('/path/to/missing'),
+      ).rejects.toMatchObject({
+        code: 'ENOENT',
+        message: 'Resource not found for document',
+      });
+    });
+  });
+
+  describe('writeTextFile', () => {
+    it.each([
+      {
+        capability: true,
+        path: '/path/to/file',
+        desc: 'connection if capability exists and file is inside root',
+        verify: () => {
+          expect(mockConnection.writeTextFile).toHaveBeenCalledWith({
+            path: '/path/to/file',
+            content: 'content',
+            sessionId: 'session-1',
+          });
+          expect(mockFallback.writeTextFile).not.toHaveBeenCalled();
+        },
+      },
+      {
+        capability: false,
+        path: '/path/to/file',
+        desc: 'fallback if capability missing',
+        verify: () => {
+          expect(mockFallback.writeTextFile).toHaveBeenCalledWith(
+            '/path/to/file',
+            'content',
+          );
+          expect(mockConnection.writeTextFile).not.toHaveBeenCalled();
+        },
+      },
+      {
+        capability: true,
+        path: '/outside/file',
+        desc: 'fallback if capability exists but file is outside root',
+        verify: () => {
+          expect(mockFallback.writeTextFile).toHaveBeenCalledWith(
+            '/outside/file',
+            'content',
+          );
+          expect(mockConnection.writeTextFile).not.toHaveBeenCalled();
+        },
+      },
+      {
+        capability: true,
+        path: '/home/user/.gemini/tmp/file.md',
+        root: '/home/user',
+        desc: 'fallback if file is inside global gemini dir, even if root overlaps',
+        verify: () => {
+          expect(mockFallback.writeTextFile).toHaveBeenCalledWith(
+            '/home/user/.gemini/tmp/file.md',
+            'content',
+          );
+          expect(mockConnection.writeTextFile).not.toHaveBeenCalled();
+        },
+      },
+    ])('should use $desc', async ({ capability, path, root, verify }) => {
+      service = new AcpFileSystemService(
+        mockConnection,
+        'session-1',
+        { writeTextFile: capability, readTextFile: true },
+        mockFallback,
+        root || '/path/to',
+      );
+
+      await service.writeTextFile(path, 'content');
+
+      verify();
+    });
+
+    it('should throw normalized ENOENT error when writeTextFile encounters "Resource not found"', async () => {
+      service = new AcpFileSystemService(
+        mockConnection,
+        'session-1',
+        { readTextFile: true, writeTextFile: true },
+        mockFallback,
+        '/path/to',
+      );
+      mockConnection.writeTextFile.mockRejectedValue(
+        new Error('Resource not found for directory'),
+      );
+
+      await expect(
+        service.writeTextFile('/path/to/missing', 'content'),
+      ).rejects.toMatchObject({
+        code: 'ENOENT',
+        message: 'Resource not found for directory',
+      });
+    });
+  });
+});

packages/cli/src/acp/acpFileSystemService.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { isWithinRoot, type FileSystemService } from '@google/gemini-cli-core';
+import type * as acp from '@agentclientprotocol/sdk';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * ACP client-based implementation of FileSystemService
+ */
+export class AcpFileSystemService implements FileSystemService {
+  private readonly geminiDir = path.join(os.homedir(), '.gemini');
+
+  constructor(
+    private readonly connection: acp.AgentSideConnection,
+    private readonly sessionId: string,
+    private readonly capabilities: acp.FileSystemCapabilities,
+    private readonly fallback: FileSystemService,
+    private readonly root: string,
+  ) {}
+
+  private shouldUseFallback(filePath: string): boolean {
+    // Files inside the global CLI directory must always use the native file system,
+    // even if the user runs the CLI directly from their home directory (which
+    // would make the IDE's project root overlap with the global directory).
+    return (
+      !isWithinRoot(filePath, this.root) ||
+      isWithinRoot(filePath, this.geminiDir)
+    );
+  }
+
+  private normalizeFileSystemError(err: unknown): never {
+    const errorMessage = err instanceof Error ? err.message : String(err);
+    if (
+      errorMessage.includes('Resource not found') ||
+      errorMessage.includes('ENOENT') ||
+      errorMessage.includes('does not exist') ||
+      errorMessage.includes('No such file')
+    ) {
+      const newErr = new Error(errorMessage) as NodeJS.ErrnoException;
+      newErr.code = 'ENOENT';
+      throw newErr;
+    }
+    throw err;
+  }
+
+  async readTextFile(filePath: string): Promise<string> {
+    if (!this.capabilities.readTextFile || this.shouldUseFallback(filePath)) {
+      return this.fallback.readTextFile(filePath);
+    }
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const response = await this.connection.readTextFile({
+        path: filePath,
+        sessionId: this.sessionId,
+      });
+
+      const content: unknown = response.content;
+      if (typeof content !== 'string') {
+        throw new Error('content must be a string'); // replace with other response type formats when modified in the future
+      }
+      return content;
+    } catch (err: unknown) {
+      this.normalizeFileSystemError(err);
+    }
+  }
+
+  async writeTextFile(filePath: string, content: string): Promise<void> {
+    if (!this.capabilities.writeTextFile || this.shouldUseFallback(filePath)) {
+      return this.fallback.writeTextFile(filePath, content);
+    }
+
+    try {
+      await this.connection.writeTextFile({
+        path: filePath,
+        content,
+        sessionId: this.sessionId,
+      });
+    } catch (err: unknown) {
+      this.normalizeFileSystemError(err);
+    }
+  }
+}

packages/cli/src/acp/acpResume.test.ts

@@ -0,0 +1,313 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  type Mocked,
+  type Mock,
+} from 'vitest';
+import { GeminiAgent } from './acpRpcDispatcher.js';
+import * as acp from '@agentclientprotocol/sdk';
+import {
+  ApprovalMode,
+  AuthType,
+  type Config,
+  CoreToolCallStatus,
+} from '@google/gemini-cli-core';
+import { loadCliConfig, type CliArgs } from '../config/config.js';
+import {
+  SessionSelector,
+  convertSessionToHistoryFormats,
+} from '../utils/sessionUtils.js';
+import { convertSessionToClientHistory } from '@google/gemini-cli-core';
+import type { LoadedSettings } from '../config/settings.js';
+import { waitFor } from '../test-utils/async.js';
+
+vi.mock('../config/config.js', () => ({
+  loadCliConfig: vi.fn(),
+}));
+
+vi.mock('../utils/sessionUtils.js', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('../utils/sessionUtils.js')>();
+  return {
+    ...actual,
+    SessionSelector: vi.fn(),
+    convertSessionToHistoryFormats: vi.fn(),
+  };
+});
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    CoreToolCallStatus: {
+      Validating: 'validating',
+      Scheduled: 'scheduled',
+      Error: 'error',
+      Success: 'success',
+      Executing: 'executing',
+      Cancelled: 'cancelled',
+      AwaitingApproval: 'awaiting_approval',
+    },
+    LlmRole: {
+      MAIN: 'main',
+      SUBAGENT: 'subagent',
+      UTILITY_TOOL: 'utility_tool',
+      USER: 'user',
+      MODEL: 'model',
+      SYSTEM: 'system',
+      TOOL: 'tool',
+    },
+    convertSessionToClientHistory: vi.fn(),
+  };
+});
+
+describe('GeminiAgent Session Resume', () => {
+  let mockConfig: Mocked<Config>;
+  let mockSettings: Mocked<LoadedSettings>;
+  let mockArgv: CliArgs;
+  let mockConnection: Mocked<acp.AgentSideConnection>;
+  let agent: GeminiAgent;
+
+  beforeEach(() => {
+    mockConfig = {
+      refreshAuth: vi.fn().mockResolvedValue(undefined),
+      initialize: vi.fn().mockResolvedValue(undefined),
+      getFileSystemService: vi.fn(),
+      setFileSystemService: vi.fn(),
+      getGeminiClient: vi.fn().mockReturnValue({
+        initialize: vi.fn().mockResolvedValue(undefined),
+        resumeChat: vi.fn().mockResolvedValue(undefined),
+        getChat: vi.fn().mockReturnValue({}),
+      }),
+      storage: {
+        getProjectTempDir: vi.fn().mockReturnValue('/tmp/project'),
+      },
+      getPolicyEngine: vi.fn().mockReturnValue({
+        addRule: vi.fn(),
+      }),
+      messageBus: {
+        publish: vi.fn(),
+        subscribe: vi.fn(),
+        unsubscribe: vi.fn(),
+      },
+      getMessageBus: vi.fn().mockReturnValue({
+        publish: vi.fn(),
+        subscribe: vi.fn(),
+        unsubscribe: vi.fn(),
+      }),
+      getApprovalMode: vi.fn().mockReturnValue('default'),
+      isAutoMemoryEnabled: vi.fn().mockReturnValue(false),
+      isPlanEnabled: vi.fn().mockReturnValue(true),
+      getModel: vi.fn().mockReturnValue('gemini-pro'),
+      getHasAccessToPreviewModel: vi.fn().mockReturnValue(false),
+      getGemini31LaunchedSync: vi.fn().mockReturnValue(false),
+      getCheckpointingEnabled: vi.fn().mockReturnValue(false),
+      toolRegistry: {
+        getTool: vi.fn().mockReturnValue({ kind: 'read' }),
+      },
+      get config() {
+        return this;
+      },
+    } as unknown as Mocked<Config>;
+    mockSettings = {
+      merged: {
+        security: { auth: { selectedType: AuthType.LOGIN_WITH_GOOGLE } },
+        mcpServers: {},
+      },
+      setValue: vi.fn(),
+    } as unknown as Mocked<LoadedSettings>;
+    mockArgv = {} as unknown as CliArgs;
+    mockConnection = {
+      sessionUpdate: vi.fn().mockResolvedValue(undefined),
+    } as unknown as Mocked<acp.AgentSideConnection>;
+
+    (loadCliConfig as Mock).mockResolvedValue(mockConfig);
+
+    agent = new GeminiAgent(mockConfig, mockSettings, mockArgv, mockConnection);
+  });
+
+  it('should advertise loadSession capability', async () => {
+    const response = await agent.initialize({
+      protocolVersion: acp.PROTOCOL_VERSION,
+    });
+    expect(response.agentCapabilities?.loadSession).toBe(true);
+  });
+
+  it('should load a session, resume chat, and stream all message types', async () => {
+    const sessionId = 'existing-session-id';
+    const sessionData = {
+      sessionId,
+      messages: [
+        { type: 'user', content: [{ text: 'Hello' }] },
+        {
+          type: 'gemini',
+          content: [{ text: 'Hi there' }],
+          thoughts: [{ subject: 'Thinking', description: 'about greeting' }],
+          toolCalls: [
+            {
+              id: 'call-1',
+              name: 'test_tool',
+              displayName: 'Test Tool',
+              status: CoreToolCallStatus.Success,
+              resultDisplay: 'Tool output',
+            },
+          ],
+        },
+        {
+          type: 'gemini',
+          content: [{ text: 'Trying a write' }],
+          toolCalls: [
+            {
+              id: 'call-2',
+              name: 'write_file',
+              displayName: 'Write File',
+              status: CoreToolCallStatus.Error,
+              resultDisplay: 'Permission denied',
+            },
+          ],
+        },
+      ],
+    };
+
+    (SessionSelector as unknown as Mock).mockImplementation(() => ({
+      resolveSession: vi.fn().mockResolvedValue({
+        sessionData,
+        sessionPath: '/path/to/session.json',
+      }),
+    }));
+
+    const mockClientHistory = [
+      { role: 'user', parts: [{ text: 'Hello' }] },
+      { role: 'model', parts: [{ text: 'Hi there' }] },
+    ];
+    (convertSessionToHistoryFormats as unknown as Mock).mockReturnValue({
+      uiHistory: [],
+    });
+    (convertSessionToClientHistory as unknown as Mock).mockReturnValue(
+      mockClientHistory,
+    );
+
+    const response = await agent.loadSession({
+      sessionId,
+      cwd: '/tmp',
+      mcpServers: [],
+    });
+
+    expect(response).toEqual({
+      modes: {
+        availableModes: [
+          {
+            id: ApprovalMode.DEFAULT,
+            name: 'Default',
+            description: 'Prompts for approval',
+          },
+          {
+            id: ApprovalMode.AUTO_EDIT,
+            name: 'Auto Edit',
+            description: 'Auto-approves edit tools',
+          },
+          {
+            id: ApprovalMode.YOLO,
+            name: 'YOLO',
+            description: 'Auto-approves all tools',
+          },
+          {
+            id: ApprovalMode.PLAN,
+            name: 'Plan',
+            description: 'Read-only mode',
+          },
+        ],
+        currentModeId: ApprovalMode.DEFAULT,
+      },
+      models: {
+        availableModels: expect.any(Array) as unknown,
+        currentModelId: 'gemini-pro',
+      },
+    });
+
+    // Verify resumeChat received the correct arguments
+    expect(mockConfig.getGeminiClient().resumeChat).toHaveBeenCalledWith(
+      mockClientHistory,
+      expect.objectContaining({
+        conversation: sessionData,
+        filePath: '/path/to/session.json',
+      }),
+    );
+
+    await waitFor(() => {
+      // User message
+      expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          update: expect.objectContaining({
+            sessionUpdate: 'user_message_chunk',
+            content: expect.objectContaining({ text: 'Hello' }),
+          }),
+        }),
+      );
+
+      // Agent thought
+      expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          update: expect.objectContaining({
+            sessionUpdate: 'agent_thought_chunk',
+            content: expect.objectContaining({
+              text: '**Thinking**\nabout greeting',
+            }),
+          }),
+        }),
+      );
+
+      // Agent message
+      expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          update: expect.objectContaining({
+            sessionUpdate: 'agent_message_chunk',
+            content: expect.objectContaining({ text: 'Hi there' }),
+          }),
+        }),
+      );
+
+      // Successful tool call → 'completed'
+      expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          update: expect.objectContaining({
+            sessionUpdate: 'tool_call',
+            toolCallId: 'call-1',
+            status: 'completed',
+            title: 'Test Tool',
+            kind: 'read',
+            content: [
+              {
+                type: 'content',
+                content: { type: 'text', text: 'Tool output' },
+              },
+            ],
+          }),
+        }),
+      );
+
+      // Failed tool call → 'failed'
+      expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          update: expect.objectContaining({
+            sessionUpdate: 'tool_call',
+            toolCallId: 'call-2',
+            status: 'failed',
+            title: 'Write File',
+            kind: 'read',
+          }),
+        }),
+      );
+    });
+  });
+});

packages/cli/src/acp/acpRpcDispatcher.test.ts

@@ -0,0 +1,339 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  type Mock,
+  type Mocked,
+} from 'vitest';
+import { GeminiAgent } from './acpRpcDispatcher.js';
+import * as acp from '@agentclientprotocol/sdk';
+import {
+  AuthType,
+  type Config,
+  type MessageBus,
+  type Storage,
+} from '@google/gemini-cli-core';
+import type { LoadedSettings } from '../config/settings.js';
+import { loadCliConfig, type CliArgs } from '../config/config.js';
+import { loadSettings, SettingScope } from '../config/settings.js';
+
+vi.mock('../config/config.js', () => ({
+  loadCliConfig: vi.fn(),
+}));
+
+vi.mock('../config/settings.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../config/settings.js')>();
+  return {
+    ...actual,
+    loadSettings: vi.fn(),
+  };
+});
+
+describe('GeminiAgent - RPC Dispatcher', () => {
+  let mockConfig: Mocked<Config>;
+  let mockSettings: Mocked<LoadedSettings>;
+  let mockArgv: CliArgs;
+  let mockConnection: Mocked<acp.AgentSideConnection>;
+  let agent: GeminiAgent;
+
+  beforeEach(() => {
+    mockConfig = {
+      refreshAuth: vi.fn(),
+      initialize: vi.fn(),
+      waitForMcpInit: vi.fn(),
+      getFileSystemService: vi.fn(),
+      setFileSystemService: vi.fn(),
+      getContentGeneratorConfig: vi.fn(),
+      getActiveModel: vi.fn().mockReturnValue('gemini-pro'),
+      getModel: vi.fn().mockReturnValue('gemini-pro'),
+      getGeminiClient: vi.fn().mockReturnValue({
+        startChat: vi.fn().mockResolvedValue({}),
+      }),
+      getMessageBus: vi.fn().mockReturnValue({
+        publish: vi.fn(),
+        subscribe: vi.fn(),
+        unsubscribe: vi.fn(),
+      }),
+      getApprovalMode: vi.fn().mockReturnValue('default'),
+      isPlanEnabled: vi.fn().mockReturnValue(true),
+      getGemini31LaunchedSync: vi.fn().mockReturnValue(false),
+      getHasAccessToPreviewModel: vi.fn().mockReturnValue(false),
+      getCheckpointingEnabled: vi.fn().mockReturnValue(false),
+      getDisableAlwaysAllow: vi.fn().mockReturnValue(false),
+      validatePathAccess: vi.fn().mockReturnValue(null),
+      getWorkspaceContext: vi.fn().mockReturnValue({
+        addReadOnlyPath: vi.fn(),
+        getDirectories: vi.fn().mockReturnValue(['/tmp']),
+      }),
+      getPolicyEngine: vi.fn().mockReturnValue({
+        addRule: vi.fn(),
+      }),
+      messageBus: {
+        publish: vi.fn(),
+        subscribe: vi.fn(),
+        unsubscribe: vi.fn(),
+      } as unknown as MessageBus,
+      storage: {
+        getWorkspaceAutoSavedPolicyPath: vi.fn(),
+        getAutoSavedPolicyPath: vi.fn(),
+      } as unknown as Storage,
+
+      get config() {
+        return this;
+      },
+    } as unknown as Mocked<Config>;
+    mockSettings = {
+      merged: {
+        security: { auth: { selectedType: 'login_with_google' } },
+        mcpServers: {},
+      },
+      setValue: vi.fn(),
+    } as unknown as Mocked<LoadedSettings>;
+    mockArgv = {} as unknown as CliArgs;
+    mockConnection = {
+      sessionUpdate: vi.fn(),
+      requestPermission: vi.fn(),
+    } as unknown as Mocked<acp.AgentSideConnection>;
+
+    (loadCliConfig as unknown as Mock).mockResolvedValue(mockConfig);
+    (loadSettings as unknown as Mock).mockImplementation(() => ({
+      merged: {
+        security: {
+          auth: { selectedType: AuthType.LOGIN_WITH_GOOGLE },
+          enablePermanentToolApproval: true,
+        },
+        mcpServers: {},
+      },
+      setValue: vi.fn(),
+    }));
+
+    agent = new GeminiAgent(mockConfig, mockSettings, mockArgv, mockConnection);
+  });
+
+  it('should initialize correctly', async () => {
+    const response = await agent.initialize({
+      clientCapabilities: { fs: { readTextFile: true, writeTextFile: true } },
+      protocolVersion: 1,
+    });
+
+    expect(response.protocolVersion).toBe(acp.PROTOCOL_VERSION);
+    expect(response.authMethods).toHaveLength(4);
+    const gatewayAuth = response.authMethods?.find(
+      (m) => m.id === AuthType.GATEWAY,
+    );
+    expect(gatewayAuth?._meta).toEqual({
+      gateway: {
+        protocol: 'google',
+        restartRequired: 'false',
+      },
+    });
+    const geminiAuth = response.authMethods?.find(
+      (m) => m.id === AuthType.USE_GEMINI,
+    );
+    expect(geminiAuth?._meta).toEqual({
+      'api-key': {
+        provider: 'google',
+      },
+    });
+    expect(response.agentCapabilities?.loadSession).toBe(true);
+  });
+
+  it('should authenticate correctly', async () => {
+    await agent.authenticate({
+      methodId: AuthType.LOGIN_WITH_GOOGLE,
+    });
+
+    expect(mockConfig.refreshAuth).toHaveBeenCalledWith(
+      AuthType.LOGIN_WITH_GOOGLE,
+      undefined,
+      undefined,
+      undefined,
+    );
+    expect(mockSettings.setValue).toHaveBeenCalledWith(
+      SettingScope.User,
+      'security.auth.selectedType',
+      AuthType.LOGIN_WITH_GOOGLE,
+    );
+  });
+
+  it('should authenticate correctly with api-key in _meta', async () => {
+    await agent.authenticate({
+      methodId: AuthType.USE_GEMINI,
+      _meta: {
+        'api-key': 'test-api-key',
+      },
+    } as unknown as acp.AuthenticateRequest);
+
+    expect(mockConfig.refreshAuth).toHaveBeenCalledWith(
+      AuthType.USE_GEMINI,
+      'test-api-key',
+      undefined,
+      undefined,
+    );
+    expect(mockSettings.setValue).toHaveBeenCalledWith(
+      SettingScope.User,
+      'security.auth.selectedType',
+      AuthType.USE_GEMINI,
+    );
+  });
+
+  it('should authenticate correctly with gateway method', async () => {
+    await agent.authenticate({
+      methodId: AuthType.GATEWAY,
+      _meta: {
+        gateway: {
+          baseUrl: 'https://example.com',
+          headers: { Authorization: 'Bearer token' },
+        },
+      },
+    } as unknown as acp.AuthenticateRequest);
+
+    expect(mockConfig.refreshAuth).toHaveBeenCalledWith(
+      AuthType.GATEWAY,
+      undefined,
+      'https://example.com',
+      { Authorization: 'Bearer token' },
+    );
+    expect(mockSettings.setValue).toHaveBeenCalledWith(
+      SettingScope.User,
+      'security.auth.selectedType',
+      AuthType.GATEWAY,
+    );
+  });
+
+  it('should throw acp.RequestError when gateway payload is malformed', async () => {
+    await expect(
+      agent.authenticate({
+        methodId: AuthType.GATEWAY,
+        _meta: {
+          gateway: {
+            baseUrl: 123,
+            headers: { Authorization: 'Bearer token' },
+          },
+        },
+      } as unknown as acp.AuthenticateRequest),
+    ).rejects.toThrow(/Malformed gateway payload/);
+  });
+
+  it('should cancel a session', async () => {
+    const mockSession = {
+      cancelPendingPrompt: vi.fn(),
+    };
+    (
+      agent as unknown as { sessionManager: { getSession: Mock } }
+    ).sessionManager = {
+      getSession: vi.fn().mockReturnValue(mockSession),
+    };
+
+    await agent.cancel({ sessionId: 'test-session-id' });
+
+    expect(mockSession.cancelPendingPrompt).toHaveBeenCalled();
+  });
+
+  it('should throw error when cancelling non-existent session', async () => {
+    (
+      agent as unknown as { sessionManager: { getSession: Mock } }
+    ).sessionManager = {
+      getSession: vi.fn().mockReturnValue(undefined),
+    };
+
+    await expect(agent.cancel({ sessionId: 'unknown' })).rejects.toThrow(
+      'Session not found',
+    );
+  });
+
+  it('should delegate prompt to session', async () => {
+    const mockSession = {
+      prompt: vi.fn().mockResolvedValue({ stopReason: 'end_turn' }),
+    };
+    (
+      agent as unknown as { sessionManager: { getSession: Mock } }
+    ).sessionManager = {
+      getSession: vi.fn().mockReturnValue(mockSession),
+    };
+
+    const result = await agent.prompt({
+      sessionId: 'test-session-id',
+      prompt: [],
+    });
+
+    expect(mockSession.prompt).toHaveBeenCalled();
+    expect(result).toMatchObject({ stopReason: 'end_turn' });
+  });
+
+  it('should delegate setMode to session', async () => {
+    const mockSession = {
+      setMode: vi.fn().mockReturnValue({}),
+    };
+    (
+      agent as unknown as { sessionManager: { getSession: Mock } }
+    ).sessionManager = {
+      getSession: vi.fn().mockReturnValue(mockSession),
+    };
+
+    const result = await agent.setSessionMode({
+      sessionId: 'test-session-id',
+      modeId: 'plan',
+    });
+
+    expect(mockSession.setMode).toHaveBeenCalledWith('plan');
+    expect(result).toEqual({});
+  });
+
+  it('should throw error when setting mode on non-existent session', async () => {
+    (
+      agent as unknown as { sessionManager: { getSession: Mock } }
+    ).sessionManager = {
+      getSession: vi.fn().mockReturnValue(undefined),
+    };
+
+    await expect(
+      agent.setSessionMode({
+        sessionId: 'unknown',
+        modeId: 'plan',
+      }),
+    ).rejects.toThrow('Session not found: unknown');
+  });
+
+  it('should delegate setModel to session (unstable)', async () => {
+    const mockSession = {
+      setModel: vi.fn().mockReturnValue({}),
+    };
+    (
+      agent as unknown as { sessionManager: { getSession: Mock } }
+    ).sessionManager = {
+      getSession: vi.fn().mockReturnValue(mockSession),
+    };
+
+    const result = await agent.unstable_setSessionModel({
+      sessionId: 'test-session-id',
+      modelId: 'gemini-2.0-pro-exp',
+    });
+
+    expect(mockSession.setModel).toHaveBeenCalledWith('gemini-2.0-pro-exp');
+    expect(result).toEqual({});
+  });
+
+  it('should throw error when setting model on non-existent session (unstable)', async () => {
+    (
+      agent as unknown as { sessionManager: { getSession: Mock } }
+    ).sessionManager = {
+      getSession: vi.fn().mockReturnValue(undefined),
+    };
+
+    await expect(
+      agent.unstable_setSessionModel({
+        sessionId: 'unknown',
+        modelId: 'gemini-2.0-pro-exp',
+      }),
+    ).rejects.toThrow('Session not found: unknown');
+  });
+});

packages/cli/src/acp/acpRpcDispatcher.ts

@@ -0,0 +1,236 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  type AgentLoopContext,
+  AuthType,
+  clearCachedCredentialFile,
+  getVersion,
+} from '@google/gemini-cli-core';
+import * as acp from '@agentclientprotocol/sdk';
+import { z } from 'zod';
+import { SettingScope, type LoadedSettings } from '../config/settings.js';
+import type { CliArgs } from '../config/config.js';
+import { getAcpErrorMessage } from './acpErrors.js';
+import { AcpSessionManager, type AuthDetails } from './acpSessionManager.js';
+import { hasMeta } from './acpUtils.js';
+
+export class GeminiAgent {
+  private apiKey: string | undefined;
+  private baseUrl: string | undefined;
+  private customHeaders: Record<string, string> | undefined;
+  private sessionManager: AcpSessionManager;
+
+  constructor(
+    private context: AgentLoopContext,
+    private settings: LoadedSettings,
+    argv: CliArgs,
+    connection: acp.AgentSideConnection,
+  ) {
+    this.sessionManager = new AcpSessionManager(settings, argv, connection);
+  }
+
+  dispose(): void {
+    this.sessionManager.dispose();
+  }
+
+  async initialize(
+    args: acp.InitializeRequest,
+  ): Promise<acp.InitializeResponse> {
+    if (args.clientCapabilities) {
+      this.sessionManager.setClientCapabilities(args.clientCapabilities);
+    }
+
+    const authMethods = [
+      {
+        id: AuthType.LOGIN_WITH_GOOGLE,
+        name: 'Log in with Google',
+        description: 'Log in with your Google account',
+      },
+      {
+        id: AuthType.USE_GEMINI,
+        name: 'Gemini API key',
+        description: 'Use an API key with Gemini Developer API',
+        _meta: {
+          'api-key': {
+            provider: 'google',
+          },
+        },
+      },
+      {
+        id: AuthType.USE_VERTEX_AI,
+        name: 'Vertex AI',
+        description: 'Use an API key with Vertex AI GenAI API',
+      },
+      {
+        id: AuthType.GATEWAY,
+        name: 'AI API Gateway',
+        description: 'Use a custom AI API Gateway',
+        _meta: {
+          gateway: {
+            protocol: 'google',
+            restartRequired: 'false',
+          },
+        },
+      },
+    ];
+
+    await this.context.config.initialize();
+    const version = await getVersion();
+    return {
+      protocolVersion: acp.PROTOCOL_VERSION,
+      authMethods,
+      agentInfo: {
+        name: 'gemini-cli',
+        title: 'Gemini CLI',
+        version,
+      },
+      agentCapabilities: {
+        loadSession: true,
+        promptCapabilities: {
+          image: true,
+          audio: true,
+          embeddedContext: true,
+        },
+        mcpCapabilities: {
+          http: true,
+          sse: true,
+        },
+      },
+    };
+  }
+
+  async authenticate(req: acp.AuthenticateRequest): Promise<void> {
+    const { methodId } = req;
+    const method = z.nativeEnum(AuthType).parse(methodId);
+    const selectedAuthType = this.settings.merged.security.auth.selectedType;
+
+    // Only clear credentials when switching to a different auth method
+    if (selectedAuthType && selectedAuthType !== method) {
+      await clearCachedCredentialFile();
+    }
+    // Check for api-key in _meta
+    const meta = hasMeta(req) ? req._meta : undefined;
+    const apiKey =
+      typeof meta?.['api-key'] === 'string' ? meta['api-key'] : undefined;
+
+    // Refresh auth with the requested method
+    // This will reuse existing credentials if they're valid,
+    // or perform new authentication if needed
+    try {
+      if (apiKey) {
+        this.apiKey = apiKey;
+      }
+
+      // Extract gateway details if present
+      const gatewaySchema = z.object({
+        baseUrl: z.string().optional(),
+        headers: z.record(z.string()).optional(),
+      });
+
+      let baseUrl: string | undefined;
+      let headers: Record<string, string> | undefined;
+
+      if (meta?.['gateway']) {
+        const result = gatewaySchema.safeParse(meta['gateway']);
+        if (result.success) {
+          baseUrl = result.data.baseUrl;
+          headers = result.data.headers;
+        } else {
+          throw new acp.RequestError(
+            -32602,
+            `Malformed gateway payload: ${result.error.message}`,
+          );
+        }
+      }
+
+      this.baseUrl = baseUrl;
+      this.customHeaders = headers;
+
+      await this.context.config.refreshAuth(
+        method,
+        apiKey ?? this.apiKey,
+        baseUrl,
+        headers,
+      );
+    } catch (e) {
+      throw new acp.RequestError(-32000, getAcpErrorMessage(e));
+    }
+    this.settings.setValue(
+      SettingScope.User,
+      'security.auth.selectedType',
+      method,
+    );
+  }
+
+  private getAuthDetails(): AuthDetails {
+    return {
+      apiKey: this.apiKey,
+      baseUrl: this.baseUrl,
+      customHeaders: this.customHeaders,
+    };
+  }
+
+  async newSession(
+    params: acp.NewSessionRequest,
+  ): Promise<acp.NewSessionResponse> {
+    return this.sessionManager.newSession(params, this.getAuthDetails());
+  }
+
+  async loadSession(
+    params: acp.LoadSessionRequest,
+  ): Promise<acp.LoadSessionResponse> {
+    return this.sessionManager.loadSession(params, this.getAuthDetails());
+  }
+
+  async cancel(params: acp.CancelNotification): Promise<void> {
+    const session = this.sessionManager.getSession(params.sessionId);
+    if (!session) {
+      throw new acp.RequestError(
+        -32602,
+        `Session not found: ${params.sessionId}`,
+      );
+    }
+    await session.cancelPendingPrompt();
+  }
+
+  async prompt(params: acp.PromptRequest): Promise<acp.PromptResponse> {
+    const session = this.sessionManager.getSession(params.sessionId);
+    if (!session) {
+      throw new acp.RequestError(
+        -32602,
+        `Session not found: ${params.sessionId}`,
+      );
+    }
+    return session.prompt(params);
+  }
+
+  async setSessionMode(
+    params: acp.SetSessionModeRequest,
+  ): Promise<acp.SetSessionModeResponse> {
+    const session = this.sessionManager.getSession(params.sessionId);
+    if (!session) {
+      throw new acp.RequestError(
+        -32602,
+        `Session not found: ${params.sessionId}`,
+      );
+    }
+    return session.setMode(params.modeId);
+  }
+
+  async unstable_setSessionModel(
+    params: acp.SetSessionModelRequest,
+  ): Promise<acp.SetSessionModelResponse> {
+    const session = this.sessionManager.getSession(params.sessionId);
+    if (!session) {
+      throw new acp.RequestError(
+        -32602,
+        `Session not found: ${params.sessionId}`,
+      );
+    }
+    return session.setModel(params.modelId);
+  }
+}

packages/cli/src/acp/acpSession.test.ts

@@ -0,0 +1,1144 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type Mock,
+  type Mocked,
+  type MockInstance,
+} from 'vitest';
+import { Session } from './acpSession.js';
+import type * as acp from '@agentclientprotocol/sdk';
+import {
+  ReadManyFilesTool,
+  type GeminiChat,
+  type Config,
+  type MessageBus,
+  type GitService,
+  InvalidStreamError,
+  GeminiEventType,
+  type ServerGeminiStreamEvent,
+  PolicyDecision,
+  MessageBusType,
+  type ToolConfirmationRequest,
+  DiscoveredMCPTool,
+} from '@google/gemini-cli-core';
+import type { LoadedSettings } from '../config/settings.js';
+import { type Part, FinishReason } from '@google/genai';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { CommandHandler } from './acpCommandHandler.js';
+
+vi.mock('node:fs/promises');
+vi.mock('node:path', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:path')>();
+  return {
+    ...actual,
+    resolve: vi.fn(),
+  };
+});
+
+vi.mock(
+  '@google/gemini-cli-core',
+  async (
+    importOriginal: () => Promise<typeof import('@google/gemini-cli-core')>,
+  ) => {
+    const actual = await importOriginal();
+    return {
+      ...actual,
+      updatePolicy: vi.fn(),
+      ReadManyFilesTool: vi.fn(),
+      logToolCall: vi.fn(),
+      processSingleFileContent: vi.fn(),
+    };
+  },
+);
+
+async function* createMockStream(
+  items: readonly ServerGeminiStreamEvent[],
+): AsyncGenerator<ServerGeminiStreamEvent> {
+  for (const item of items) {
+    yield item;
+  }
+
+  yield {
+    type: GeminiEventType.Finished,
+    value: {
+      reason: FinishReason.STOP,
+      usageMetadata: {
+        promptTokenCount: 5,
+        candidatesTokenCount: 10,
+      },
+    },
+  };
+}
+
+describe('Session', () => {
+  let mockChat: Mocked<GeminiChat>;
+  let mockConfig: Mocked<Config>;
+  let mockConnection: Mocked<acp.AgentSideConnection>;
+  let session: Session;
+  let mockToolRegistry: { getTool: Mock };
+  let mockTool: { kind: string; build: Mock };
+  let mockMessageBus: Mocked<MessageBus>;
+  let mockSendMessageStream: MockInstance<
+    (
+      request: Part[],
+      signal: AbortSignal,
+      promptId: string,
+    ) => AsyncGenerator<ServerGeminiStreamEvent>
+  >;
+
+  beforeEach(() => {
+    mockChat = {
+      sendMessageStream: vi.fn(),
+      addHistory: vi.fn(),
+      recordCompletedToolCalls: vi.fn(),
+      getHistory: vi.fn().mockReturnValue([]),
+    } as unknown as Mocked<GeminiChat>;
+    mockTool = {
+      kind: 'read',
+      build: vi.fn().mockReturnValue({
+        getDescription: () => 'Test Tool',
+        toolLocations: () => [],
+        shouldConfirmExecute: vi.fn().mockResolvedValue(null),
+        execute: vi.fn().mockResolvedValue({ llmContent: 'Tool Result' }),
+      }),
+    };
+    mockToolRegistry = {
+      getTool: vi.fn().mockReturnValue(mockTool),
+    };
+    mockMessageBus = {
+      publish: vi.fn(),
+      subscribe: vi.fn(),
+      unsubscribe: vi.fn(),
+    } as unknown as Mocked<MessageBus>;
+    mockSendMessageStream = vi.fn();
+    mockConfig = {
+      getModel: vi.fn().mockReturnValue('gemini-pro'),
+      getActiveModel: vi.fn().mockReturnValue('gemini-pro'),
+      getModelRouterService: vi.fn().mockReturnValue({
+        route: vi.fn().mockResolvedValue({ model: 'resolved-model' }),
+      }),
+      getToolRegistry: vi.fn().mockReturnValue(mockToolRegistry),
+      getFileService: vi.fn().mockReturnValue({
+        shouldIgnoreFile: vi.fn().mockReturnValue(false),
+      }),
+      getFileFilteringOptions: vi.fn().mockReturnValue({}),
+      getFileSystemService: vi.fn().mockReturnValue({}),
+      getTargetDir: vi.fn().mockReturnValue('/tmp'),
+      getEnableRecursiveFileSearch: vi.fn().mockReturnValue(false),
+      getDebugMode: vi.fn().mockReturnValue(false),
+      getMessageBus: vi.fn().mockReturnValue(mockMessageBus),
+      setApprovalMode: vi.fn(),
+      setModel: vi.fn(),
+      isPlanEnabled: vi.fn().mockReturnValue(true),
+      getCheckpointingEnabled: vi.fn().mockReturnValue(false),
+      getGitService: vi.fn().mockResolvedValue({} as GitService),
+      getPolicyEngine: vi.fn().mockReturnValue({
+        check: vi.fn(),
+      }),
+      validatePathAccess: vi.fn().mockReturnValue(null),
+      getWorkspaceContext: vi.fn().mockReturnValue({
+        addReadOnlyPath: vi.fn(),
+        getDirectories: vi.fn().mockReturnValue(['/tmp']),
+      }),
+      waitForMcpInit: vi.fn(),
+      getDisableAlwaysAllow: vi.fn().mockReturnValue(false),
+      getMaxSessionTurns: vi.fn().mockReturnValue(-1),
+      geminiClient: {
+        sendMessageStream: mockSendMessageStream,
+        getChat: vi.fn().mockReturnValue(mockChat),
+      },
+      get config() {
+        return this;
+      },
+      get toolRegistry() {
+        return mockToolRegistry;
+      },
+    } as unknown as Mocked<Config>;
+    mockConnection = {
+      sessionUpdate: vi.fn(),
+      requestPermission: vi.fn(),
+    } as unknown as Mocked<acp.AgentSideConnection>;
+
+    session = new Session('session-1', mockChat, mockConfig, mockConnection, {
+      merged: {
+        security: { enablePermanentToolApproval: true },
+        mcpServers: {},
+      },
+      errors: [],
+    } as unknown as LoadedSettings);
+
+    (ReadManyFilesTool as unknown as Mock).mockImplementation(() => ({
+      name: 'read_many_files',
+      kind: 'read',
+      build: vi.fn().mockReturnValue({
+        getDescription: () => 'Read files',
+        toolLocations: () => [],
+        execute: vi.fn().mockResolvedValue({
+          llmContent: ['--- file.txt ---\n\nFile content\n\n'],
+        }),
+      }),
+    }));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should send available commands', async () => {
+    await session.sendAvailableCommands();
+
+    expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        update: expect.objectContaining({
+          sessionUpdate: 'available_commands_update',
+        }),
+      }),
+    );
+  });
+
+  it('should await MCP initialization before processing a prompt', async () => {
+    const stream = createMockStream([
+      {
+        type: GeminiEventType.Content,
+        value: 'Hi',
+      },
+    ]);
+    mockSendMessageStream.mockReturnValue(stream);
+
+    await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'test' }],
+    });
+
+    expect(mockConfig.waitForMcpInit).toHaveBeenCalledOnce();
+  });
+
+  it('should handle prompt with text response', async () => {
+    const stream = createMockStream([
+      {
+        type: GeminiEventType.Content,
+        value: 'Hello',
+      },
+    ]);
+    mockSendMessageStream.mockReturnValue(stream);
+
+    const result = await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Hi' }],
+    });
+
+    expect(mockSendMessageStream).toHaveBeenCalled();
+    expect(mockConnection.sessionUpdate).toHaveBeenCalledWith({
+      sessionId: 'session-1',
+      update: {
+        sessionUpdate: 'agent_message_chunk',
+        content: { type: 'text', text: 'Hello' },
+      },
+    });
+    expect(result).toMatchObject({ stopReason: 'end_turn' });
+  });
+
+  it('should pass current session information directly onto geminiClient.sendMessageStream', async () => {
+    const stream = createMockStream([
+      {
+        type: GeminiEventType.Content,
+        value: 'Hello',
+      },
+    ]);
+    mockSendMessageStream.mockReturnValue(stream);
+
+    await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Hi' }],
+    });
+
+    expect(mockSendMessageStream).toHaveBeenCalledWith(
+      expect.arrayContaining([{ text: 'Hi' }]),
+      expect.any(AbortSignal),
+      expect.any(String),
+    );
+  });
+
+  it('should handle prompt with empty response (InvalidStreamError)', async () => {
+    const error = new InvalidStreamError('Empty response', 'NO_RESPONSE_TEXT');
+    mockSendMessageStream.mockImplementation(() => {
+      async function* errorGen(): AsyncGenerator<
+        ServerGeminiStreamEvent,
+        void,
+        unknown
+      > {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        yield* [] as any;
+        throw error;
+      }
+      return errorGen();
+    });
+
+    const result = await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Hi' }],
+    });
+
+    expect(result).toMatchObject({ stopReason: 'end_turn' });
+  });
+
+  it('should handle prompt with no finish reason (InvalidStreamError)', async () => {
+    const error = new InvalidStreamError(
+      'No finish reason',
+      'NO_FINISH_REASON',
+    );
+    mockSendMessageStream.mockImplementation(() => {
+      async function* errorGen(): AsyncGenerator<
+        ServerGeminiStreamEvent,
+        void,
+        unknown
+      > {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        yield* [] as any;
+        throw error;
+      }
+      return errorGen();
+    });
+
+    const result = await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Hi' }],
+    });
+
+    expect(result).toMatchObject({ stopReason: 'end_turn' });
+  });
+
+  it.each([
+    { type: 'MAX_TOKENS_EXCEEDED', reason: 'MAX_TOKENS' },
+    { type: 'SAFETY_BLOCKED', reason: 'SAFETY' },
+    { type: 'RECITATION_BLOCKED', reason: 'RECITATION' },
+    { type: 'OTHER_BLOCKED', reason: 'OTHER' },
+    { type: 'THINKING_ONLY_RESPONSE', reason: 'STOP' },
+  ])(
+    'should gracefully handle InvalidStreamError with type $type in ACP session',
+    async ({ type, reason }) => {
+      const error = new InvalidStreamError(
+        `Stream failed with ${reason}`,
+        type as InvalidStreamError['type'],
+      );
+      mockSendMessageStream.mockImplementation(() => {
+        async function* errorGen(): AsyncGenerator<
+          ServerGeminiStreamEvent,
+          void,
+          unknown
+        > {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          yield* [] as any;
+          throw error;
+        }
+        return errorGen();
+      });
+
+      const result = await session.prompt({
+        sessionId: 'session-1',
+        prompt: [{ type: 'text', text: 'Hi' }],
+      });
+
+      expect(result).toMatchObject({ stopReason: 'end_turn' });
+    },
+  );
+
+  it('should handle /memory command', async () => {
+    const handleCommandSpy = vi
+      .spyOn(
+        (session as unknown as { commandHandler: CommandHandler })
+          .commandHandler,
+        'handleCommand',
+      )
+      .mockResolvedValue(true);
+
+    const result = await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: '/memory view' }],
+    });
+
+    expect(result).toMatchObject({ stopReason: 'end_turn' });
+    expect(handleCommandSpy).toHaveBeenCalledWith(
+      '/memory view',
+      expect.any(Object),
+    );
+  });
+
+  it('should handle tool calls', async () => {
+    const stream1 = createMockStream([
+      {
+        type: GeminiEventType.ToolCallRequest,
+        value: {
+          callId: 'call-1',
+          name: 'test_tool',
+          args: { foo: 'bar' },
+          isClientInitiated: false,
+          prompt_id: 'prompt-1',
+        },
+      },
+    ]);
+    const stream2 = createMockStream([
+      {
+        type: GeminiEventType.Content,
+        value: 'Result',
+      },
+    ]);
+
+    mockSendMessageStream
+      .mockReturnValueOnce(stream1)
+      .mockReturnValueOnce(stream2);
+
+    const result = await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Call tool' }],
+    });
+
+    expect(mockToolRegistry.getTool).toHaveBeenCalledWith('test_tool');
+    expect(result).toMatchObject({ stopReason: 'end_turn' });
+  });
+
+  it('should handle tool call permission request', async () => {
+    const confirmationDetails = {
+      type: 'info',
+      onConfirm: vi.fn(),
+    };
+    mockTool.build.mockReturnValue({
+      getDescription: () => 'Test Tool',
+      toolLocations: () => [],
+      shouldConfirmExecute: vi.fn().mockResolvedValue(confirmationDetails),
+      execute: vi.fn().mockResolvedValue({ llmContent: 'Tool Result' }),
+    });
+
+    mockConnection.requestPermission.mockResolvedValue({
+      outcome: {
+        outcome: 'selected',
+        optionId: 'proceed_once',
+      },
+    });
+
+    const stream1 = createMockStream([
+      {
+        type: GeminiEventType.ToolCallRequest,
+        value: {
+          callId: 'call-1',
+          name: 'test_tool',
+          args: {},
+          isClientInitiated: false,
+          prompt_id: 'prompt-1',
+        },
+      },
+    ]);
+    const stream2 = createMockStream([
+      {
+        type: GeminiEventType.Content,
+        value: '',
+      },
+    ]);
+
+    mockSendMessageStream
+      .mockReturnValueOnce(stream1)
+      .mockReturnValueOnce(stream2);
+
+    await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Call tool' }],
+    });
+
+    expect(mockConnection.requestPermission).toHaveBeenCalled();
+    expect(confirmationDetails.onConfirm).toHaveBeenCalled();
+  });
+
+  it('should handle @path resolution', async () => {
+    (path.resolve as unknown as Mock).mockReturnValue('/tmp/file.txt');
+    (fs.stat as unknown as Mock).mockResolvedValue({
+      isDirectory: () => false,
+    });
+
+    const stream = createMockStream([
+      {
+        type: GeminiEventType.Content,
+        value: '',
+      },
+    ]);
+    mockSendMessageStream.mockReturnValue(stream);
+
+    await session.prompt({
+      sessionId: 'session-1',
+      prompt: [
+        { type: 'text', text: 'Read' },
+        {
+          type: 'resource_link',
+          uri: 'file://file.txt',
+          mimeType: 'text/plain',
+          name: 'file.txt',
+        },
+      ],
+    });
+
+    expect(path.resolve).toHaveBeenCalled();
+    expect(fs.stat).toHaveBeenCalled();
+    expect(mockSendMessageStream).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        expect.objectContaining({
+          text: expect.stringContaining('Content from @file.txt'),
+        }),
+      ]),
+      expect.any(AbortSignal),
+      expect.any(String),
+    );
+  });
+
+  it('should handle rate limit error', async () => {
+    const error = new Error('Rate limit');
+    const customError = error as { status?: number; message?: string };
+    customError.status = 429;
+
+    mockSendMessageStream.mockImplementation(() => {
+      async function* errorGen(): AsyncGenerator<
+        ServerGeminiStreamEvent,
+        void,
+        unknown
+      > {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        yield* [] as any;
+        throw customError;
+      }
+      return errorGen();
+    });
+
+    await expect(
+      session.prompt({
+        sessionId: 'session-1',
+        prompt: [{ type: 'text', text: 'Hi' }],
+      }),
+    ).rejects.toMatchObject({
+      code: 429,
+      message: 'Rate limit exceeded. Try again later.',
+    });
+  });
+
+  it('should handle missing tool', async () => {
+    mockToolRegistry.getTool.mockReturnValue(undefined);
+
+    const stream1 = createMockStream([
+      {
+        type: GeminiEventType.ToolCallRequest,
+        value: {
+          callId: 'call-1',
+          name: 'unknown_tool',
+          args: {},
+          isClientInitiated: false,
+          prompt_id: 'prompt-1',
+        },
+      },
+    ]);
+    const stream2 = createMockStream([
+      {
+        type: GeminiEventType.Content,
+        value: '',
+      },
+    ]);
+
+    mockSendMessageStream
+      .mockReturnValueOnce(stream1)
+      .mockReturnValueOnce(stream2);
+
+    await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Call tool' }],
+    });
+
+    expect(mockSendMessageStream).toHaveBeenCalledTimes(2);
+  });
+
+  it('should handle GeminiEventType.LoopDetected', async () => {
+    const stream = createMockStream([
+      {
+        type: GeminiEventType.LoopDetected,
+      },
+    ]);
+    mockSendMessageStream.mockReturnValue(stream);
+
+    const result = await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Trigger Loop Simulation' }],
+    });
+
+    expect(result.stopReason).toBe('max_turn_requests');
+  });
+
+  it('should handle GeminiEventType.ContextWindowWillOverflow', async () => {
+    const stream = createMockStream([
+      {
+        type: GeminiEventType.ContextWindowWillOverflow,
+        value: { estimatedRequestTokenCount: 1000, remainingTokenCount: 200 },
+      },
+    ]);
+    mockSendMessageStream.mockReturnValue(stream);
+
+    const result = await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Trigger Overflow Simulation' }],
+    });
+
+    expect(result.stopReason).toBe('max_tokens');
+  });
+
+  it('should handle GeminiEventType.MaxSessionTurns', async () => {
+    const stream = createMockStream([
+      {
+        type: GeminiEventType.MaxSessionTurns,
+      },
+    ]);
+    mockSendMessageStream.mockReturnValue(stream);
+
+    const result = await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Trigger Safety Limits' }],
+    });
+
+    expect(result.stopReason).toBe('max_turn_requests');
+  });
+
+  it('should send sessionUpdate when approval mode changes', async () => {
+    const { coreEvents, CoreEvent, ApprovalMode } = await import(
+      '@google/gemini-cli-core'
+    );
+
+    coreEvents.emit(CoreEvent.ApprovalModeChanged, {
+      sessionId: 'session-1',
+      mode: ApprovalMode.PLAN,
+    });
+
+    expect(mockConnection.sessionUpdate).toHaveBeenCalledWith({
+      sessionId: 'session-1',
+      update: {
+        sessionUpdate: 'agent_message_chunk',
+        content: {
+          type: 'text',
+          text: `[MODE_UPDATE] ${ApprovalMode.PLAN}`,
+        },
+      },
+    });
+  });
+
+  it('should add explanation to tool call content instead of thought chunk', async () => {
+    mockTool.build.mockReturnValue({
+      getDescription: () => 'Test Tool',
+      getExplanation: () => 'Test Explanation',
+      toolLocations: () => [],
+      shouldConfirmExecute: vi
+        .fn()
+        .mockResolvedValue({ type: 'info', onConfirm: vi.fn() }),
+      execute: vi.fn().mockResolvedValue({ llmContent: 'Tool Result' }),
+    });
+
+    mockConnection.requestPermission.mockResolvedValue({
+      outcome: {
+        outcome: 'selected',
+        optionId: 'proceed_once',
+      },
+    });
+
+    const stream1 = createMockStream([
+      {
+        type: GeminiEventType.ToolCallRequest,
+        value: {
+          callId: 'call-1',
+          name: 'test_tool',
+          args: {},
+          isClientInitiated: false,
+          prompt_id: 'prompt-1',
+        },
+      },
+    ]);
+    const stream2 = createMockStream([
+      {
+        type: GeminiEventType.Content,
+        value: '',
+      },
+    ]);
+
+    mockSendMessageStream
+      .mockReturnValueOnce(stream1)
+      .mockReturnValueOnce(stream2);
+
+    await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Call tool' }],
+    });
+
+    expect(mockConnection.sessionUpdate).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        update: expect.objectContaining({
+          sessionUpdate: 'agent_thought_chunk',
+          content: { type: 'text', text: 'Test Explanation' },
+        }),
+      }),
+    );
+
+    expect(mockConnection.requestPermission).toHaveBeenCalledWith(
+      expect.objectContaining({
+        toolCall: expect.objectContaining({
+          content: expect.arrayContaining([
+            {
+              type: 'content',
+              content: { type: 'text', text: 'Test Explanation' },
+            },
+          ]),
+        }),
+      }),
+    );
+  });
+
+  it('should include both diff and explanation in request_permission content for edit tools', async () => {
+    mockTool.build.mockReturnValue({
+      getDescription: () => 'edit_file(file_path: test.ts)',
+      getDisplayTitle: () => 'edit_file(file_path: test.ts)',
+      getExplanation: () => 'Updating configuration value',
+      toolLocations: () => [],
+      shouldConfirmExecute: vi.fn().mockResolvedValue({
+        type: 'edit',
+        filePath: 'test.ts',
+        originalContent: 'old',
+        newContent: 'new',
+        onConfirm: vi.fn(),
+      }),
+      execute: vi.fn().mockResolvedValue({ llmContent: 'Tool Result' }),
+    });
+
+    mockConnection.requestPermission.mockResolvedValue({
+      outcome: {
+        outcome: 'selected',
+        optionId: 'proceed_once',
+      },
+    });
+
+    const stream1 = createMockStream([
+      {
+        type: GeminiEventType.ToolCallRequest,
+        value: {
+          callId: 'call-edit-1',
+          name: 'test_tool',
+          args: {},
+          isClientInitiated: false,
+          prompt_id: 'prompt-1',
+        },
+      },
+    ]);
+    const stream2 = createMockStream([
+      {
+        type: GeminiEventType.Content,
+        value: '',
+      },
+    ]);
+
+    mockSendMessageStream
+      .mockReturnValueOnce(stream1)
+      .mockReturnValueOnce(stream2);
+
+    await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Edit file' }],
+    });
+
+    expect(mockConnection.requestPermission).toHaveBeenCalledWith(
+      expect.objectContaining({
+        toolCall: expect.objectContaining({
+          title: 'edit_file(file_path: test.ts)',
+          content: [
+            expect.objectContaining({
+              type: 'diff',
+              path: 'test.ts',
+            }),
+            {
+              type: 'content',
+              content: { type: 'text', text: 'Updating configuration value' },
+            },
+          ],
+        }),
+      }),
+    );
+  });
+
+  it('should add explanation to tool_call update content instead of thought chunk when no permission required', async () => {
+    mockTool.build.mockReturnValue({
+      getDescription: () => 'Test Tool',
+      getExplanation: () => 'Test Explanation',
+      toolLocations: () => [],
+      shouldConfirmExecute: vi.fn().mockResolvedValue(null),
+      execute: vi.fn().mockResolvedValue({ llmContent: 'Tool Result' }),
+    });
+
+    const stream1 = createMockStream([
+      {
+        type: GeminiEventType.ToolCallRequest,
+        value: {
+          callId: 'call-1',
+          name: 'test_tool',
+          args: {},
+          isClientInitiated: false,
+          prompt_id: 'prompt-1',
+        },
+      },
+    ]);
+    const stream2 = createMockStream([
+      {
+        type: GeminiEventType.Content,
+        value: '',
+      },
+    ]);
+
+    mockSendMessageStream
+      .mockReturnValueOnce(stream1)
+      .mockReturnValueOnce(stream2);
+
+    await session.prompt({
+      sessionId: 'session-1',
+      prompt: [{ type: 'text', text: 'Call tool' }],
+    });
+
+    expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        update: expect.objectContaining({
+          sessionUpdate: 'tool_call',
+          content: expect.arrayContaining([
+            {
+              type: 'content',
+              content: { type: 'text', text: 'Test Explanation' },
+            },
+          ]),
+        }),
+      }),
+    );
+  });
+
+  describe('Policy Handling', () => {
+    it('should auto-approve tool calls when PolicyEngine returns ALLOW', async () => {
+      const mockPolicyEngine = mockConfig.getPolicyEngine() as unknown as {
+        check: Mock<
+          (
+            toolCall: { name: string; args: Record<string, unknown> },
+            serverName?: string,
+            toolAnnotations?: Record<string, unknown>,
+            subagent?: string,
+          ) => Promise<{ decision: PolicyDecision }>
+        >;
+      };
+      mockPolicyEngine.check.mockResolvedValue({
+        decision: PolicyDecision.ALLOW,
+      });
+
+      // Trigger the subscription handler
+      const handler = mockMessageBus.subscribe.mock.calls.find(
+        (call) => call[0] === MessageBusType.TOOL_CONFIRMATION_REQUEST,
+      )?.[1] as (request: ToolConfirmationRequest) => Promise<void>;
+
+      expect(handler).toBeDefined();
+
+      await handler({
+        type: MessageBusType.TOOL_CONFIRMATION_REQUEST,
+        correlationId: 'test-id',
+        toolCall: { name: 'ls', args: {} },
+      });
+
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: 'test-id',
+          confirmed: true,
+          requiresUserConfirmation: false,
+        }),
+      );
+    });
+
+    it('should request user confirmation when PolicyEngine returns ASK_USER', async () => {
+      const mockPolicyEngine = mockConfig.getPolicyEngine() as unknown as {
+        check: Mock<
+          (
+            toolCall: { name: string; args: Record<string, unknown> },
+            serverName?: string,
+            toolAnnotations?: Record<string, unknown>,
+            subagent?: string,
+          ) => Promise<{ decision: PolicyDecision }>
+        >;
+      };
+      mockPolicyEngine.check.mockResolvedValue({
+        decision: PolicyDecision.ASK_USER,
+      });
+
+      const handler = mockMessageBus.subscribe.mock.calls.find(
+        (call) => call[0] === MessageBusType.TOOL_CONFIRMATION_REQUEST,
+      )?.[1] as (request: ToolConfirmationRequest) => Promise<void>;
+
+      await handler({
+        type: MessageBusType.TOOL_CONFIRMATION_REQUEST,
+        correlationId: 'test-id-2',
+        toolCall: { name: 'rm', args: { path: '/' } },
+      });
+
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: 'test-id-2',
+          confirmed: false,
+          requiresUserConfirmation: true,
+        }),
+      );
+    });
+
+    it('should deny tool calls when PolicyEngine returns DENY', async () => {
+      const mockPolicyEngine = mockConfig.getPolicyEngine() as unknown as {
+        check: Mock<
+          (
+            toolCall: { name: string; args: Record<string, unknown> },
+            serverName?: string,
+            toolAnnotations?: Record<string, unknown>,
+            subagent?: string,
+          ) => Promise<{ decision: PolicyDecision }>
+        >;
+      };
+      mockPolicyEngine.check.mockResolvedValue({
+        decision: PolicyDecision.DENY,
+      });
+
+      const handler = mockMessageBus.subscribe.mock.calls.find(
+        (call) => call[0] === MessageBusType.TOOL_CONFIRMATION_REQUEST,
+      )?.[1] as (request: ToolConfirmationRequest) => Promise<void>;
+
+      await handler({
+        type: MessageBusType.TOOL_CONFIRMATION_REQUEST,
+        correlationId: 'test-id-3',
+        toolCall: { name: 'forbidden', args: {} },
+      });
+
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: 'test-id-3',
+          confirmed: false,
+          requiresUserConfirmation: false,
+        }),
+      );
+    });
+
+    it('should pass subagent and trusted tool info to PolicyEngine', async () => {
+      const mockPolicyEngine = mockConfig.getPolicyEngine() as unknown as {
+        check: Mock<
+          (
+            toolCall: { name: string; args: Record<string, unknown> },
+            serverName?: string,
+            toolAnnotations?: Record<string, unknown>,
+            subagent?: string,
+          ) => Promise<{ decision: PolicyDecision }>
+        >;
+      };
+      mockPolicyEngine.check.mockResolvedValue({
+        decision: PolicyDecision.ALLOW,
+      });
+
+      // Mock tool in registry with trusted annotations
+      const trustedAnnotations = { safe: true };
+      mockToolRegistry.getTool.mockReturnValue({
+        name: 'ls',
+        toolAnnotations: trustedAnnotations,
+      });
+
+      const handler = mockMessageBus.subscribe.mock.calls.find(
+        (call) => call[0] === MessageBusType.TOOL_CONFIRMATION_REQUEST,
+      )?.[1] as (request: ToolConfirmationRequest) => Promise<void>;
+
+      await handler({
+        type: MessageBusType.TOOL_CONFIRMATION_REQUEST,
+        correlationId: 'test-id-trusted',
+        toolCall: { name: 'ls', args: {} },
+        subagent: 'restricted-subagent',
+        serverName: 'spoofed-server', // Should be ignored
+        toolAnnotations: { malicious: true }, // Should be ignored
+      });
+
+      expect(mockPolicyEngine.check).toHaveBeenCalledWith(
+        expect.anything(),
+        undefined, // serverName for non-MCP tool
+        trustedAnnotations,
+        'restricted-subagent',
+      );
+    });
+
+    it('should handle exceptions in PolicyEngine by failing closed', async () => {
+      const mockPolicyEngine = mockConfig.getPolicyEngine() as unknown as {
+        check: Mock<
+          (
+            toolCall: { name: string; args: Record<string, unknown> },
+            serverName?: string,
+            toolAnnotations?: Record<string, unknown>,
+            subagent?: string,
+          ) => Promise<{ decision: PolicyDecision }>
+        >;
+      };
+      mockPolicyEngine.check.mockRejectedValue(
+        new Error('Policy check failed'),
+      );
+
+      const handler = mockMessageBus.subscribe.mock.calls.find(
+        (call) => call[0] === MessageBusType.TOOL_CONFIRMATION_REQUEST,
+      )?.[1] as (request: ToolConfirmationRequest) => Promise<void>;
+
+      await handler({
+        type: MessageBusType.TOOL_CONFIRMATION_REQUEST,
+        correlationId: 'test-id-error',
+        toolCall: { name: 'ls', args: {} },
+      });
+
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: 'test-id-error',
+          confirmed: false,
+          requiresUserConfirmation: false,
+        }),
+      );
+    });
+
+    it('should fail closed when PolicyEngine is missing', async () => {
+      (mockConfig.getPolicyEngine as Mock).mockReturnValue(undefined);
+
+      const handler = mockMessageBus.subscribe.mock.calls.find(
+        (call) => call[0] === MessageBusType.TOOL_CONFIRMATION_REQUEST,
+      )?.[1] as (request: ToolConfirmationRequest) => Promise<void>;
+
+      await handler({
+        type: MessageBusType.TOOL_CONFIRMATION_REQUEST,
+        correlationId: 'test-id-no-engine',
+        toolCall: { name: 'ls', args: {} },
+      });
+
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: 'test-id-no-engine',
+          confirmed: false,
+          requiresUserConfirmation: false,
+        }),
+      );
+    });
+
+    it('should handle missing tool name in request by failing closed', async () => {
+      const handler = mockMessageBus.subscribe.mock.calls.find(
+        (call) => call[0] === MessageBusType.TOOL_CONFIRMATION_REQUEST,
+      )?.[1] as (request: ToolConfirmationRequest) => Promise<void>;
+
+      await handler({
+        type: MessageBusType.TOOL_CONFIRMATION_REQUEST,
+        correlationId: 'test-id-no-name',
+        toolCall: { name: '', args: {} },
+      });
+
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: 'test-id-no-name',
+          confirmed: false,
+          requiresUserConfirmation: false,
+        }),
+      );
+    });
+
+    it('should trim tool name before lookup and validation', async () => {
+      const handler = mockMessageBus.subscribe.mock.calls.find(
+        (call) => call[0] === MessageBusType.TOOL_CONFIRMATION_REQUEST,
+      )?.[1] as (request: ToolConfirmationRequest) => Promise<void>;
+
+      await handler({
+        type: MessageBusType.TOOL_CONFIRMATION_REQUEST,
+        correlationId: 'test-id-whitespace',
+        toolCall: { name: '  ', args: {} },
+      });
+
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: 'test-id-whitespace',
+          confirmed: false,
+          requiresUserConfirmation: false,
+        }),
+      );
+    });
+
+    it('should pass serverName from DiscoveredMCPTool to PolicyEngine', async () => {
+      const mockPolicyEngine = mockConfig.getPolicyEngine() as unknown as {
+        check: Mock<
+          (
+            toolCall: { name: string; args: Record<string, unknown> },
+            serverName?: string,
+            toolAnnotations?: Record<string, unknown>,
+            subagent?: string,
+          ) => Promise<{ decision: PolicyDecision }>
+        >;
+      };
+      mockPolicyEngine.check.mockResolvedValue({
+        decision: PolicyDecision.ALLOW,
+      });
+
+      // Mock tool in registry as a DiscoveredMCPTool instance
+      const mcpTool = {
+        name: 'mcp_server_tool',
+        serverName: 'test-server',
+        toolAnnotations: { mcp: true },
+      };
+      Object.setPrototypeOf(mcpTool, DiscoveredMCPTool.prototype);
+      mockToolRegistry.getTool.mockReturnValue(mcpTool);
+
+      const handler = mockMessageBus.subscribe.mock.calls.find(
+        (call) => call[0] === MessageBusType.TOOL_CONFIRMATION_REQUEST,
+      )?.[1] as (request: ToolConfirmationRequest) => Promise<void>;
+
+      await handler({
+        type: MessageBusType.TOOL_CONFIRMATION_REQUEST,
+        correlationId: 'test-id-mcp',
+        toolCall: { name: 'mcp_server_tool', args: {} },
+      });
+
+      expect(mockPolicyEngine.check).toHaveBeenCalledWith(
+        expect.anything(),
+        'test-server',
+        { mcp: true },
+        undefined,
+      );
+    });
+
+    it('should fail closed and deny unknown tools', async () => {
+      mockToolRegistry.getTool.mockReturnValue(undefined);
+
+      const handler = mockMessageBus.subscribe.mock.calls.find(
+        (call) => call[0] === MessageBusType.TOOL_CONFIRMATION_REQUEST,
+      )?.[1] as (request: ToolConfirmationRequest) => Promise<void>;
+
+      await handler({
+        type: MessageBusType.TOOL_CONFIRMATION_REQUEST,
+        correlationId: 'test-id-unknown',
+        toolCall: { name: 'unknown_tool', args: {} },
+      });
+
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: 'test-id-unknown',
+          confirmed: false,
+          requiresUserConfirmation: false,
+        }),
+      );
+    });
+  });
+});

packages/cli/src/acp/acpSession.ts

@@ -0,0 +1,1527 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  type ApprovalMode,
+  type ConversationRecord,
+  CoreToolCallStatus,
+  coreEvents,
+  CoreEvent,
+  type ApprovalModeChangedPayload,
+  logToolCall,
+  convertToFunctionResponse,
+  ToolConfirmationOutcome,
+  getErrorStatus,
+  DiscoveredMCPTool,
+  ToolCallEvent,
+  debugLogger,
+  ReadManyFilesTool,
+  partListUnionToString,
+  type AgentLoopContext,
+  updatePolicy,
+  getErrorMessage,
+  type FilterFilesOptions,
+  isTextPart,
+  GeminiEventType,
+  type ToolCallRequestInfo,
+  type GeminiChat,
+  type ToolResult,
+  isWithinRoot,
+  processSingleFileContent,
+  isNodeError,
+  REFERENCE_CONTENT_START,
+  InvalidStreamError,
+  MessageBusType,
+  PolicyDecision,
+  type ToolConfirmationRequest,
+  resolveAtCommandPath,
+  type ResolvedAtCommandPath,
+} from '@google/gemini-cli-core';
+import * as acp from '@agentclientprotocol/sdk';
+import type { Part, FunctionCall } from '@google/genai';
+import type { LoadedSettings } from '../config/settings.js';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { CommandHandler } from './acpCommandHandler.js';
+import {
+  toToolCallContent,
+  toPermissionOptions,
+  toAcpToolKind,
+  buildAvailableModes,
+  RequestPermissionResponseSchema,
+} from './acpUtils.js';
+import { z } from 'zod';
+import { getAcpErrorMessage } from './acpErrors.js';
+
+const StructuredErrorSchema = z.object({
+  status: z.number().optional(),
+  message: z.string().optional(),
+});
+
+export class Session {
+  private pendingPrompt: AbortController | null = null;
+  private commandHandler = new CommandHandler();
+  private callIdCounter = 0;
+  private readonly disposeController = new AbortController();
+
+  private generateCallId(name: string): string {
+    return `${name}-${Date.now()}-${++this.callIdCounter}`;
+  }
+
+  constructor(
+    private readonly id: string,
+    private readonly chat: GeminiChat,
+    private readonly context: AgentLoopContext,
+    private readonly connection: acp.AgentSideConnection,
+    private readonly settings: LoadedSettings,
+  ) {
+    coreEvents.on(
+      CoreEvent.ApprovalModeChanged,
+      this.handleApprovalModeChanged,
+    );
+
+    // Subscribe to tool confirmation requests to handle policy checks (e.g. auto-allowing safe shell commands)
+    this.context.config
+      .getMessageBus()
+      ?.subscribe(
+        MessageBusType.TOOL_CONFIRMATION_REQUEST,
+        this.handleToolConfirmationRequest,
+        { signal: this.disposeController.signal },
+      );
+  }
+
+  private handleToolConfirmationRequest = async (
+    request: ToolConfirmationRequest,
+  ) => {
+    try {
+      const policyEngine = this.context.config.getPolicyEngine?.();
+      const messageBus = this.context.config.getMessageBus();
+
+      if (!messageBus) {
+        return;
+      }
+
+      if (!policyEngine) {
+        debugLogger.warn(
+          'Policy engine missing. Denying tool confirmation request.',
+        );
+        await messageBus.publish({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: request.correlationId,
+          confirmed: false,
+          requiresUserConfirmation: false,
+        });
+        return;
+      }
+
+      const toolName = request.toolCall.name?.trim();
+      if (!toolName) {
+        debugLogger.warn(
+          'Tool confirmation request missing tool name. Denying.',
+        );
+        await messageBus.publish({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: request.correlationId,
+          confirmed: false,
+          requiresUserConfirmation: false,
+        });
+        return;
+      }
+
+      const tool = this.context.toolRegistry.getTool(toolName);
+      if (!tool) {
+        debugLogger.warn(
+          `Tool confirmation request for unknown tool: ${toolName}. Denying.`,
+        );
+        await messageBus.publish({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: request.correlationId,
+          confirmed: false,
+          requiresUserConfirmation: false,
+        });
+        return;
+      }
+
+      const serverName =
+        tool instanceof DiscoveredMCPTool ? tool.serverName : undefined;
+      const toolAnnotations = tool.toolAnnotations;
+
+      const result = await policyEngine.check(
+        request.toolCall,
+        serverName,
+        toolAnnotations,
+        request.subagent,
+      );
+
+      await messageBus.publish({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+        correlationId: request.correlationId,
+        confirmed: result.decision === PolicyDecision.ALLOW,
+        requiresUserConfirmation: result.decision === PolicyDecision.ASK_USER,
+      });
+    } catch (error) {
+      debugLogger.error('Error handling tool confirmation request:', error);
+      // Fail closed on exception
+      await this.context.config.getMessageBus()?.publish({
+        type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+        correlationId: request.correlationId,
+        confirmed: false,
+        requiresUserConfirmation: false,
+      });
+    }
+  };
+
+  private handleApprovalModeChanged = (payload: ApprovalModeChangedPayload) => {
+    if (payload.sessionId === this.id) {
+      void this.sendUpdate({
+        sessionUpdate: 'agent_message_chunk',
+        content: {
+          type: 'text',
+          text: `[MODE_UPDATE] ${payload.mode}`,
+        },
+      });
+    }
+  };
+
+  dispose(): void {
+    coreEvents.off(
+      CoreEvent.ApprovalModeChanged,
+      this.handleApprovalModeChanged,
+    );
+    this.disposeController.abort();
+  }
+
+  async cancelPendingPrompt(): Promise<void> {
+    if (!this.pendingPrompt) {
+      throw new Error('Not currently generating');
+    }
+
+    this.pendingPrompt.abort();
+    this.pendingPrompt = null;
+  }
+
+  setMode(modeId: acp.SessionModeId): acp.SetSessionModeResponse {
+    const availableModes = buildAvailableModes(
+      this.context.config.isPlanEnabled(),
+    );
+    const mode = availableModes.find((m) => m.id === modeId);
+    if (!mode) {
+      throw new Error(`Invalid or unavailable mode: ${modeId}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    this.context.config.setApprovalMode(mode.id as ApprovalMode);
+    return {};
+  }
+
+  private getAvailableCommands() {
+    return this.commandHandler.getAvailableCommands();
+  }
+
+  async sendAvailableCommands(): Promise<void> {
+    const availableCommands = this.getAvailableCommands().map((command) => ({
+      name: command.name,
+      description: command.description,
+    }));
+
+    await this.sendUpdate({
+      sessionUpdate: 'available_commands_update',
+      availableCommands,
+    });
+  }
+
+  setModel(modelId: acp.ModelId): acp.SetSessionModelResponse {
+    this.context.config.setModel(modelId);
+    return {};
+  }
+
+  async streamHistory(messages: ConversationRecord['messages']): Promise<void> {
+    for (const msg of messages) {
+      const contentString = partListUnionToString(msg.content);
+
+      if (msg.type === 'user') {
+        if (contentString.trim()) {
+          await this.sendUpdate({
+            sessionUpdate: 'user_message_chunk',
+            content: { type: 'text', text: contentString },
+          });
+        }
+      } else if (msg.type === 'gemini') {
+        // Thoughts
+        if (msg.thoughts) {
+          for (const thought of msg.thoughts) {
+            const thoughtText = `**${thought.subject}**\n${thought.description}`;
+            await this.sendUpdate({
+              sessionUpdate: 'agent_thought_chunk',
+              content: { type: 'text', text: thoughtText },
+            });
+          }
+        }
+
+        // Message text
+        if (contentString.trim()) {
+          await this.sendUpdate({
+            sessionUpdate: 'agent_message_chunk',
+            content: { type: 'text', text: contentString },
+          });
+        }
+
+        // Tool calls
+        if (msg.toolCalls) {
+          for (const toolCall of msg.toolCalls) {
+            const toolCallContent: acp.ToolCallContent[] = [];
+            if (toolCall.resultDisplay) {
+              if (typeof toolCall.resultDisplay === 'string') {
+                toolCallContent.push({
+                  type: 'content',
+                  content: { type: 'text', text: toolCall.resultDisplay },
+                });
+              } else if ('fileName' in toolCall.resultDisplay) {
+                toolCallContent.push({
+                  type: 'diff',
+                  path: toolCall.resultDisplay.fileName,
+                  oldText: toolCall.resultDisplay.originalContent,
+                  newText: toolCall.resultDisplay.newContent,
+                });
+              }
+            }
+
+            const tool = this.context.toolRegistry.getTool(toolCall.name);
+
+            await this.sendUpdate({
+              sessionUpdate: 'tool_call',
+              toolCallId: toolCall.id,
+              status:
+                toolCall.status === CoreToolCallStatus.Success
+                  ? 'completed'
+                  : 'failed',
+              title: toolCall.displayName || toolCall.name,
+              content: toolCallContent,
+              kind: tool ? toAcpToolKind(tool.kind) : 'other',
+            });
+          }
+        }
+      }
+    }
+  }
+
+  async prompt(params: acp.PromptRequest): Promise<acp.PromptResponse> {
+    this.pendingPrompt?.abort();
+    const pendingSend = new AbortController();
+    this.pendingPrompt = pendingSend;
+
+    await this.context.config.waitForMcpInit();
+
+    const promptId = Math.random().toString(16).slice(2);
+
+    const parts = await this.#resolvePrompt(params.prompt, pendingSend.signal);
+
+    // Command interception
+    let commandText = '';
+
+    for (const part of parts) {
+      if (typeof part === 'object' && part !== null) {
+        if (isTextPart(part)) {
+          // It is a text part
+          const text = part.text;
+          commandText += text;
+        } else {
+          // Non-text part (image, embedded resource)
+          // Stop looking for command
+          break;
+        }
+      }
+    }
+
+    commandText = commandText.trim();
+
+    if (
+      commandText &&
+      (commandText.startsWith('/') || commandText.startsWith('$'))
+    ) {
+      // If we found a command, pass it to handleCommand
+      // Note: handleCommand currently expects `commandText` to be the command string
+      // It uses `parts` argument but effectively ignores it in current implementation
+      const handled = await this.handleCommand(commandText, parts);
+      if (handled) {
+        return {
+          stopReason: 'end_turn',
+          _meta: {
+            quota: {
+              token_count: { input_tokens: 0, output_tokens: 0 },
+              model_usage: [],
+            },
+          },
+        };
+      }
+    }
+
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    const modelUsageMap = new Map<string, { input: number; output: number }>();
+
+    let currentParts: Part[] = parts;
+    let turnCount = 0;
+    const maxTurns = this.context.config.getMaxSessionTurns();
+
+    while (true) {
+      turnCount++;
+      if (maxTurns >= 0 && turnCount > maxTurns) {
+        return {
+          stopReason: 'max_turn_requests',
+          _meta: {
+            quota: {
+              token_count: {
+                input_tokens: totalInputTokens,
+                output_tokens: totalOutputTokens,
+              },
+              model_usage: Array.from(modelUsageMap.entries()).map(
+                ([modelName, counts]) => ({
+                  model: modelName,
+                  token_count: {
+                    input_tokens: counts.input,
+                    output_tokens: counts.output,
+                  },
+                }),
+              ),
+            },
+          },
+        };
+      }
+
+      if (pendingSend.signal.aborted) {
+        return { stopReason: 'cancelled' };
+      }
+
+      const toolCallRequests: ToolCallRequestInfo[] = [];
+      let stopReason: acp.StopReason = 'end_turn';
+      let turnModelId = this.context.config.getModel();
+      let turnInputTokens = 0;
+      let turnOutputTokens = 0;
+
+      try {
+        const responseStream = this.context.geminiClient.sendMessageStream(
+          currentParts,
+          pendingSend.signal,
+          promptId,
+        );
+
+        for await (const event of responseStream) {
+          if (pendingSend.signal.aborted) {
+            return { stopReason: 'cancelled' };
+          }
+
+          switch (event.type) {
+            case GeminiEventType.Content: {
+              const content: acp.ContentBlock = {
+                type: 'text',
+                text: event.value,
+              };
+
+              await this.sendUpdate({
+                sessionUpdate: 'agent_message_chunk',
+                content,
+              });
+              break;
+            }
+
+            case GeminiEventType.Thought: {
+              const thoughtText = `**${event.value.subject}**\n${event.value.description}`;
+              await this.sendUpdate({
+                sessionUpdate: 'agent_thought_chunk',
+                content: { type: 'text', text: thoughtText },
+              });
+              break;
+            }
+
+            case GeminiEventType.ToolCallRequest:
+              toolCallRequests.push(event.value);
+              break;
+
+            case GeminiEventType.Finished: {
+              const usage = event.value.usageMetadata;
+              if (usage) {
+                turnInputTokens = usage.promptTokenCount ?? turnInputTokens;
+                turnOutputTokens =
+                  usage.candidatesTokenCount ?? turnOutputTokens;
+              }
+              break;
+            }
+
+            case GeminiEventType.ModelInfo:
+              turnModelId = event.value;
+              break;
+
+            case GeminiEventType.MaxSessionTurns:
+              stopReason = 'max_turn_requests';
+              break;
+
+            case GeminiEventType.LoopDetected:
+              stopReason = 'max_turn_requests';
+              break;
+
+            case GeminiEventType.ContextWindowWillOverflow:
+              stopReason = 'max_tokens';
+              break;
+
+            case GeminiEventType.Error: {
+              const parseResult = StructuredErrorSchema.safeParse(
+                event.value.error,
+              );
+              const errData = parseResult.success ? parseResult.data : {};
+
+              throw new acp.RequestError(
+                errData.status ?? 500,
+                errData.message ?? 'Unknown stream execution error.',
+              );
+            }
+
+            default:
+              break;
+          }
+        }
+      } catch (error) {
+        if (getErrorStatus(error) === 429) {
+          throw new acp.RequestError(
+            429,
+            'Rate limit exceeded. Try again later.',
+          );
+        }
+
+        if (
+          pendingSend.signal.aborted ||
+          (error instanceof Error && error.name === 'AbortError')
+        ) {
+          return { stopReason: 'cancelled' };
+        }
+
+        if (error instanceof acp.RequestError) {
+          throw error;
+        }
+
+        if (
+          error instanceof InvalidStreamError ||
+          (error &&
+            typeof error === 'object' &&
+            'type' in error &&
+            (error.type === 'NO_RESPONSE_TEXT' ||
+              error.type === 'NO_FINISH_REASON' ||
+              error.type === 'MALFORMED_FUNCTION_CALL' ||
+              error.type === 'UNEXPECTED_TOOL_CALL' ||
+              error.type === 'MAX_TOKENS_EXCEEDED' ||
+              error.type === 'SAFETY_BLOCKED' ||
+              error.type === 'RECITATION_BLOCKED' ||
+              error.type === 'OTHER_BLOCKED' ||
+              error.type === 'THINKING_ONLY_RESPONSE'))
+        ) {
+          // The stream ended with an empty response or malformed tool call.
+          // Treat this as a graceful end to the model's turn rather than a crash.
+          return {
+            stopReason: 'end_turn',
+            _meta: {
+              quota: {
+                token_count: {
+                  input_tokens: totalInputTokens,
+                  output_tokens: totalOutputTokens,
+                },
+                model_usage: Array.from(modelUsageMap.entries()).map(
+                  ([modelName, counts]) => ({
+                    model: modelName,
+                    token_count: {
+                      input_tokens: counts.input,
+                      output_tokens: counts.output,
+                    },
+                  }),
+                ),
+              },
+            },
+          };
+        }
+
+        throw new acp.RequestError(
+          getErrorStatus(error) || 500,
+          getAcpErrorMessage(error),
+        );
+      }
+
+      totalInputTokens += turnInputTokens;
+      totalOutputTokens += turnOutputTokens;
+
+      if (turnInputTokens > 0 || turnOutputTokens > 0) {
+        const existing = modelUsageMap.get(turnModelId) ?? {
+          input: 0,
+          output: 0,
+        };
+        existing.input += turnInputTokens;
+        existing.output += turnOutputTokens;
+        modelUsageMap.set(turnModelId, existing);
+      }
+
+      if (stopReason !== 'end_turn') {
+        return {
+          stopReason,
+          _meta: {
+            quota: {
+              token_count: {
+                input_tokens: totalInputTokens,
+                output_tokens: totalOutputTokens,
+              },
+              model_usage: Array.from(modelUsageMap.entries()).map(
+                ([modelName, counts]) => ({
+                  model: modelName,
+                  token_count: {
+                    input_tokens: counts.input,
+                    output_tokens: counts.output,
+                  },
+                }),
+              ),
+            },
+          },
+        };
+      }
+
+      if (toolCallRequests.length === 0) {
+        break;
+      }
+
+      const toolResponseParts: Part[] = [];
+      for (const tReq of toolCallRequests) {
+        const fc: FunctionCall = {
+          id: tReq.callId,
+          name: tReq.name,
+          args: tReq.args,
+        };
+
+        const response = await this.runTool(pendingSend.signal, promptId, fc);
+        toolResponseParts.push(...response);
+      }
+
+      currentParts = toolResponseParts;
+    }
+
+    const modelUsageArray = Array.from(modelUsageMap.entries()).map(
+      ([modelName, counts]) => ({
+        model: modelName,
+        token_count: {
+          input_tokens: counts.input,
+          output_tokens: counts.output,
+        },
+      }),
+    );
+
+    return {
+      stopReason: 'end_turn',
+      _meta: {
+        quota: {
+          token_count: {
+            input_tokens: totalInputTokens,
+            output_tokens: totalOutputTokens,
+          },
+          model_usage: modelUsageArray,
+        },
+      },
+    };
+  }
+
+  private async handleCommand(
+    commandText: string,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    parts: Part[],
+  ): Promise<boolean> {
+    const gitService = await this.context.config.getGitService();
+    const commandContext = {
+      agentContext: this.context,
+      settings: this.settings,
+      git: gitService,
+      sendMessage: async (text: string) => {
+        await this.sendUpdate({
+          sessionUpdate: 'agent_message_chunk',
+          content: { type: 'text', text },
+        });
+      },
+    };
+
+    return this.commandHandler.handleCommand(commandText, commandContext);
+  }
+
+  private async sendUpdate(update: acp.SessionUpdate): Promise<void> {
+    const params: acp.SessionNotification = {
+      sessionId: this.id,
+      update,
+    };
+
+    await this.connection.sessionUpdate(params);
+  }
+
+  private async runTool(
+    abortSignal: AbortSignal,
+    promptId: string,
+    fc: FunctionCall,
+  ): Promise<Part[]> {
+    const callId = fc.id ?? this.generateCallId(fc.name || 'unknown');
+    const args = fc.args ?? {};
+
+    const startTime = Date.now();
+
+    const errorResponse = (error: Error) => {
+      const durationMs = Date.now() - startTime;
+      logToolCall(
+        this.context.config,
+        new ToolCallEvent(
+          undefined,
+          fc.name ?? '',
+          args,
+          durationMs,
+          false,
+          promptId,
+          typeof tool !== 'undefined' && tool instanceof DiscoveredMCPTool
+            ? 'mcp'
+            : 'native',
+          error.message,
+        ),
+      );
+
+      return [
+        {
+          functionResponse: {
+            id: callId,
+            name: fc.name ?? '',
+            response: { error: error.message },
+          },
+        },
+      ];
+    };
+
+    if (!fc.name) {
+      return errorResponse(new Error('Missing function name'));
+    }
+
+    const toolRegistry = this.context.toolRegistry;
+    const tool = toolRegistry.getTool(fc.name);
+
+    if (!tool) {
+      return errorResponse(
+        new Error(`Tool "${fc.name}" not found in registry.`),
+      );
+    }
+
+    try {
+      const invocation = tool.build(args);
+
+      const displayTitle =
+        typeof invocation.getDisplayTitle === 'function'
+          ? invocation.getDisplayTitle()
+          : invocation.getDescription();
+
+      const explanation =
+        typeof invocation.getExplanation === 'function'
+          ? invocation.getExplanation()
+          : '';
+
+      const confirmationDetails =
+        await invocation.shouldConfirmExecute(abortSignal);
+
+      if (confirmationDetails) {
+        const content: acp.ToolCallContent[] = [];
+
+        if (confirmationDetails.type === 'edit') {
+          content.push({
+            type: 'diff',
+            path: confirmationDetails.filePath,
+            oldText: confirmationDetails.originalContent,
+            newText: confirmationDetails.newContent,
+            _meta: {
+              kind: !confirmationDetails.originalContent
+                ? 'add'
+                : confirmationDetails.newContent === ''
+                  ? 'delete'
+                  : 'modify',
+            },
+          });
+        }
+
+        if (explanation) {
+          content.push({
+            type: 'content',
+            content: { type: 'text', text: explanation },
+          });
+        }
+
+        const params: acp.RequestPermissionRequest = {
+          sessionId: this.id,
+          options: toPermissionOptions(
+            confirmationDetails,
+            this.context.config,
+            this.settings.merged.security.enablePermanentToolApproval,
+          ),
+          toolCall: {
+            toolCallId: callId,
+            status: 'pending',
+            title: displayTitle,
+            content,
+            locations: invocation.toolLocations(),
+            kind: toAcpToolKind(tool.kind),
+          },
+        };
+
+        const output = RequestPermissionResponseSchema.parse(
+          await this.connection.requestPermission(params),
+        );
+
+        const outcome =
+          output.outcome.outcome === 'cancelled'
+            ? ToolConfirmationOutcome.Cancel
+            : z
+                .nativeEnum(ToolConfirmationOutcome)
+                .parse(output.outcome.optionId);
+
+        await confirmationDetails.onConfirm(outcome);
+
+        // Update policy to enable Always Allow persistence
+        await updatePolicy(
+          tool,
+          outcome,
+          confirmationDetails,
+          this.context,
+          this.context.messageBus,
+          invocation,
+        );
+
+        switch (outcome) {
+          case ToolConfirmationOutcome.Cancel:
+            return errorResponse(
+              new Error(`Tool "${fc.name}" was canceled by the user.`),
+            );
+          case ToolConfirmationOutcome.ProceedOnce:
+          case ToolConfirmationOutcome.ProceedAlways:
+          case ToolConfirmationOutcome.ProceedAlwaysAndSave:
+          case ToolConfirmationOutcome.ProceedAlwaysServer:
+          case ToolConfirmationOutcome.ProceedAlwaysTool:
+          case ToolConfirmationOutcome.ModifyWithEditor:
+            break;
+          default: {
+            const resultOutcome: never = outcome;
+            throw new Error(`Unexpected: ${resultOutcome}`);
+          }
+        }
+      } else {
+        const content: acp.ToolCallContent[] = [];
+
+        if (explanation) {
+          content.push({
+            type: 'content',
+            content: { type: 'text', text: explanation },
+          });
+        }
+
+        await this.sendUpdate({
+          sessionUpdate: 'tool_call',
+          toolCallId: callId,
+          status: 'in_progress',
+          title: displayTitle,
+          content,
+          locations: invocation.toolLocations(),
+          kind: toAcpToolKind(tool.kind),
+        });
+      }
+
+      const toolResult: ToolResult = await invocation.execute({
+        abortSignal,
+      });
+      const content = toToolCallContent(toolResult);
+
+      const updateContent: acp.ToolCallContent[] = content ? [content] : [];
+
+      await this.sendUpdate({
+        sessionUpdate: 'tool_call_update',
+        toolCallId: callId,
+        status: 'completed',
+        title: displayTitle,
+        content: updateContent,
+        locations: invocation.toolLocations(),
+        kind: toAcpToolKind(tool.kind),
+      });
+
+      const durationMs = Date.now() - startTime;
+      logToolCall(
+        this.context.config,
+        new ToolCallEvent(
+          undefined,
+          fc.name ?? '',
+          args,
+          durationMs,
+          true,
+          promptId,
+          typeof tool !== 'undefined' && tool instanceof DiscoveredMCPTool
+            ? 'mcp'
+            : 'native',
+        ),
+      );
+
+      this.chat.recordCompletedToolCalls(this.context.config.getActiveModel(), [
+        {
+          status: CoreToolCallStatus.Success,
+          request: {
+            callId,
+            name: fc.name,
+            args,
+            isClientInitiated: false,
+            prompt_id: promptId,
+          },
+          tool,
+          invocation,
+          response: {
+            callId,
+            responseParts: convertToFunctionResponse(
+              fc.name,
+              callId,
+              toolResult.llmContent,
+              this.context.config.getActiveModel(),
+              this.context.config,
+            ),
+            resultDisplay: toolResult.returnDisplay,
+            error: undefined,
+            errorType: undefined,
+          },
+        },
+      ]);
+
+      return convertToFunctionResponse(
+        fc.name,
+        callId,
+        toolResult.llmContent,
+        this.context.config.getActiveModel(),
+        this.context.config,
+      );
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e));
+
+      await this.sendUpdate({
+        sessionUpdate: 'tool_call_update',
+        toolCallId: callId,
+        status: 'failed',
+        content: [
+          { type: 'content', content: { type: 'text', text: error.message } },
+        ],
+        kind: toAcpToolKind(tool.kind),
+      });
+
+      this.chat.recordCompletedToolCalls(this.context.config.getActiveModel(), [
+        {
+          status: CoreToolCallStatus.Error,
+          request: {
+            callId,
+            name: fc.name,
+            args,
+            isClientInitiated: false,
+            prompt_id: promptId,
+          },
+          tool,
+          response: {
+            callId,
+            responseParts: [
+              {
+                functionResponse: {
+                  id: callId,
+                  name: fc.name ?? '',
+                  response: { error: error.message },
+                },
+              },
+            ],
+            resultDisplay: error.message,
+            error,
+            errorType: undefined,
+          },
+        },
+      ]);
+
+      return errorResponse(error);
+    }
+  }
+
+  async #resolvePrompt(
+    message: acp.ContentBlock[],
+    abortSignal: AbortSignal,
+  ): Promise<Part[]> {
+    const FILE_URI_SCHEME = 'file://';
+
+    const embeddedContext: acp.EmbeddedResourceResource[] = [];
+
+    const parts = message.map((part) => {
+      switch (part.type) {
+        case 'text':
+          return { text: part.text };
+        case 'image':
+        case 'audio':
+          return {
+            inlineData: {
+              mimeType: part.mimeType,
+              data: part.data,
+            },
+          };
+        case 'resource_link': {
+          if (part.uri.startsWith(FILE_URI_SCHEME)) {
+            return {
+              fileData: {
+                mimeData: part.mimeType,
+                name: part.name,
+                fileUri: part.uri.slice(FILE_URI_SCHEME.length),
+              },
+            };
+          } else {
+            return { text: `@${part.uri}` };
+          }
+        }
+        case 'resource': {
+          embeddedContext.push(part.resource);
+          return { text: `@${part.resource.uri}` };
+        }
+        default: {
+          const unreachable: never = part;
+          throw new Error(`Unexpected chunk type: '${unreachable}'`);
+        }
+      }
+    });
+
+    const atPathCommandParts = parts.filter((part) => 'fileData' in part);
+
+    if (atPathCommandParts.length === 0 && embeddedContext.length === 0) {
+      return parts;
+    }
+
+    const atPathToResolvedSpecMap = new Map<string, string>();
+
+    // Get centralized file discovery service
+    const fileDiscovery = this.context.config.getFileService();
+    const fileFilteringOptions: FilterFilesOptions =
+      this.context.config.getFileFilteringOptions();
+
+    const pathSpecsToRead: string[] = [];
+    const contentLabelsForDisplay: string[] = [];
+    const ignoredPaths: string[] = [];
+    const directContents: Array<{
+      spec: string;
+      content?: string;
+      part?: Part;
+    }> = [];
+
+    const toolRegistry = this.context.toolRegistry;
+    const readManyFilesTool = new ReadManyFilesTool(
+      this.context.config,
+      this.context.messageBus,
+    );
+    const globTool = toolRegistry.getTool('glob');
+
+    if (!readManyFilesTool) {
+      throw new Error('Error: read_many_files tool not found.');
+    }
+
+    for (const atPathPart of atPathCommandParts) {
+      const pathName = atPathPart.fileData!.fileUri;
+      // Check if path should be ignored
+      if (fileDiscovery.shouldIgnoreFile(pathName, fileFilteringOptions)) {
+        ignoredPaths.push(pathName);
+        debugLogger.warn(`Path ${pathName} is ignored and will be skipped.`);
+        continue;
+      }
+      let currentPathSpec = pathName;
+      let resolvedSuccessfully = false;
+      let readDirectly = false;
+
+      const result = await resolveAtCommandPath(
+        pathName,
+        this.context.config,
+        (msg) => this.debug(msg),
+      );
+
+      let validationError: string | null = null;
+      let absolutePath: string;
+      let resolved: ResolvedAtCommandPath | undefined;
+
+      if (result.status === 'resolved') {
+        resolved = result.resolved;
+        absolutePath = resolved.absolutePath;
+      } else if (result.status === 'unauthorized') {
+        absolutePath = result.absolutePath;
+        validationError = result.error;
+      } else if (result.status === 'invalid') {
+        // Already logged in resolveAtCommandPath
+        continue;
+      } else {
+        // Result is not_found.
+        // We still check if it's an unauthorized absolute path that we can ask permission for,
+        // specifically for paths that are completely outside the root and not even in any workspace directory.
+        // For relative paths not found anywhere, we resolve relative to targetDir for permission check.
+        absolutePath = path.resolve(
+          this.context.config.getTargetDir(),
+          pathName,
+        );
+      }
+
+      if (
+        !resolved &&
+        validationError &&
+        !isWithinRoot(absolutePath, this.context.config.getTargetDir())
+      ) {
+        try {
+          const stats = await fs.stat(absolutePath);
+          if (stats.isFile()) {
+            const syntheticCallId = `resolve-prompt-${pathName}-${randomUUID()}`;
+            const params = {
+              sessionId: this.id,
+              options: [
+                {
+                  optionId: ToolConfirmationOutcome.ProceedOnce,
+                  name: 'Allow once',
+                  kind: 'allow_once',
+                },
+                {
+                  optionId: ToolConfirmationOutcome.Cancel,
+                  name: 'Deny',
+                  kind: 'reject_once',
+                },
+              ] as acp.PermissionOption[],
+              toolCall: {
+                toolCallId: syntheticCallId,
+                status: 'pending',
+                title: `Allow access to absolute path: ${pathName}`,
+                content: [
+                  {
+                    type: 'content',
+                    content: {
+                      type: 'text',
+                      text: `The Agent needs access to read an attached file outside your workspace: ${pathName}`,
+                    },
+                  },
+                ],
+                locations: [],
+                kind: 'read',
+              },
+            };
+
+            const output = RequestPermissionResponseSchema.parse(
+              await this.connection.requestPermission(params),
+            );
+
+            const outcome =
+              output.outcome.outcome === 'cancelled'
+                ? ToolConfirmationOutcome.Cancel
+                : z
+                    .nativeEnum(ToolConfirmationOutcome)
+                    .parse(output.outcome.optionId);
+
+            if (outcome === ToolConfirmationOutcome.ProceedOnce) {
+              this.context.config
+                .getWorkspaceContext()
+                .addReadOnlyPath(absolutePath);
+              validationError = null;
+            } else {
+              this.debug(
+                `Direct read authorization denied for absolute path ${pathName}`,
+              );
+              directContents.push({
+                spec: pathName,
+                content: `[Warning: Access to absolute path \`${pathName}\` denied by user.]`,
+              });
+              continue;
+            }
+          }
+        } catch (error) {
+          this.debug(
+            `Failed to request permission for absolute attachment ${pathName}: ${getErrorMessage(error)}`,
+          );
+          await this.sendUpdate({
+            sessionUpdate: 'agent_thought_chunk',
+            content: {
+              type: 'text',
+              text: `Warning: Failed to display permission dialog for \`${absolutePath}\`. Error: ${getErrorMessage(error)}`,
+            },
+          });
+        }
+      }
+
+      try {
+        if (!validationError) {
+          // If it's an absolute path that is authorized (e.g. added via readOnlyPaths),
+          // read it directly to avoid ReadManyFilesTool absolute path resolution issues.
+          if (
+            (path.isAbsolute(pathName) ||
+              !isWithinRoot(
+                absolutePath,
+                this.context.config.getTargetDir(),
+              )) &&
+            !readDirectly
+          ) {
+            try {
+              const stats = resolved
+                ? resolved.stats
+                : await fs.stat(absolutePath);
+              if (stats.isFile()) {
+                const fileReadResult = await processSingleFileContent(
+                  absolutePath,
+                  this.context.config.getTargetDir(),
+                  this.context.config.getFileSystemService(),
+                );
+
+                if (!fileReadResult.error) {
+                  if (
+                    typeof fileReadResult.llmContent === 'object' &&
+                    'inlineData' in fileReadResult.llmContent
+                  ) {
+                    directContents.push({
+                      spec: pathName,
+                      part: fileReadResult.llmContent,
+                    });
+                  } else if (typeof fileReadResult.llmContent === 'string') {
+                    let contentToPush = fileReadResult.llmContent;
+                    if (fileReadResult.isTruncated) {
+                      contentToPush = `[WARNING: This file was truncated]\n\n${contentToPush}`;
+                    }
+                    directContents.push({
+                      spec: pathName,
+                      content: contentToPush,
+                    });
+                  }
+                  readDirectly = true;
+                  resolvedSuccessfully = true;
+                } else {
+                  this.debug(
+                    `Direct read failed for absolute path ${pathName}: ${fileReadResult.error}`,
+                  );
+                  await this.sendUpdate({
+                    sessionUpdate: 'agent_thought_chunk',
+                    content: {
+                      type: 'text',
+                      text: `Warning: file read failed for \`${pathName}\`. Reason: ${fileReadResult.error}`,
+                    },
+                  });
+                  continue;
+                }
+              }
+            } catch (error) {
+              this.debug(
+                `File stat/access error for absolute path ${pathName}: ${getErrorMessage(error)}`,
+              );
+              await this.sendUpdate({
+                sessionUpdate: 'agent_thought_chunk',
+                content: {
+                  type: 'text',
+                  text: `Warning: file access failed for \`${pathName}\`. Reason: ${getErrorMessage(error)}`,
+                },
+              });
+              continue;
+            }
+          }
+
+          if (!readDirectly) {
+            const stats = resolved
+              ? resolved.stats
+              : await fs.stat(absolutePath);
+            if (stats.isDirectory()) {
+              currentPathSpec = pathName.endsWith('/')
+                ? `${pathName}**`
+                : `${pathName}/**`;
+              this.debug(
+                `Path ${pathName} resolved to directory, using glob: ${currentPathSpec}`,
+              );
+            } else {
+              this.debug(
+                `Path ${pathName} resolved to file: ${currentPathSpec}`,
+              );
+            }
+            resolvedSuccessfully = true;
+          }
+        } else {
+          this.debug(
+            `Path ${pathName} access disallowed: ${validationError}. Skipping.`,
+          );
+          await this.sendUpdate({
+            sessionUpdate: 'agent_thought_chunk',
+            content: {
+              type: 'text',
+              text: `Warning: skipping access to \`${pathName}\`. Reason: ${validationError}`,
+            },
+          });
+        }
+      } catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+          if (this.context.config.getEnableRecursiveFileSearch() && globTool) {
+            this.debug(
+              `Path ${pathName} not found directly, attempting glob search.`,
+            );
+            try {
+              const globResult = await globTool.buildAndExecute(
+                {
+                  pattern: `**/*${pathName}*`,
+                  path: this.context.config.getTargetDir(),
+                },
+                abortSignal,
+              );
+              if (
+                globResult.llmContent &&
+                typeof globResult.llmContent === 'string' &&
+                !globResult.llmContent.startsWith('No files found') &&
+                !globResult.llmContent.startsWith('Error:')
+              ) {
+                const lines = globResult.llmContent.split('\n');
+                if (lines.length > 1 && lines[1]) {
+                  const firstMatchAbsolute = lines[1].trim();
+                  currentPathSpec = path.relative(
+                    this.context.config.getTargetDir(),
+                    firstMatchAbsolute,
+                  );
+                  this.debug(
+                    `Glob search for ${pathName} found ${firstMatchAbsolute}, using relative path: ${currentPathSpec}`,
+                  );
+                  resolvedSuccessfully = true;
+                } else {
+                  this.debug(
+                    `Glob search for '**/*${pathName}*' did not return a usable path. Path ${pathName} will be skipped.`,
+                  );
+                }
+              } else {
+                this.debug(
+                  `Glob search for '**/*${pathName}*' found no files or an error. Path ${pathName} will be skipped.`,
+                );
+              }
+            } catch (globError) {
+              debugLogger.error(
+                `Error during glob search for ${pathName}: ${getErrorMessage(globError)}`,
+              );
+            }
+          } else {
+            this.debug(
+              `Glob tool not found. Path ${pathName} will be skipped.`,
+            );
+          }
+        } else {
+          debugLogger.error(
+            `Error stating path ${pathName}. Path ${pathName} will be skipped.`,
+          );
+        }
+      }
+      if (resolvedSuccessfully) {
+        if (!readDirectly) {
+          pathSpecsToRead.push(currentPathSpec);
+        }
+        atPathToResolvedSpecMap.set(pathName, currentPathSpec);
+        contentLabelsForDisplay.push(pathName);
+      }
+    }
+
+    // Construct the initial part of the query for the LLM
+    let initialQueryText = '';
+    for (let i = 0; i < parts.length; i++) {
+      const chunk = parts[i];
+      if ('text' in chunk) {
+        initialQueryText += chunk.text;
+      } else {
+        // type === 'atPath'
+        const resolvedSpec =
+          chunk.fileData && atPathToResolvedSpecMap.get(chunk.fileData.fileUri);
+        if (
+          i > 0 &&
+          initialQueryText.length > 0 &&
+          !initialQueryText.endsWith(' ') &&
+          resolvedSpec
+        ) {
+          // Add space if previous part was text and didn't end with space, or if previous was @path
+          const prevPart = parts[i - 1];
+          if (
+            'text' in prevPart ||
+            ('fileData' in prevPart &&
+              atPathToResolvedSpecMap.has(prevPart.fileData!.fileUri))
+          ) {
+            initialQueryText += ' ';
+          }
+        }
+        if (resolvedSpec) {
+          initialQueryText += `@${resolvedSpec}`;
+        } else {
+          // If not resolved for reading (e.g. lone @ or invalid path that was skipped),
+          // add the original @-string back, ensuring spacing if it's not the first element.
+          if (
+            i > 0 &&
+            initialQueryText.length > 0 &&
+            !initialQueryText.endsWith(' ') &&
+            !chunk.fileData?.fileUri.startsWith(' ')
+          ) {
+            initialQueryText += ' ';
+          }
+          if (chunk.fileData?.fileUri) {
+            initialQueryText += `@${chunk.fileData.fileUri}`;
+          }
+        }
+      }
+    }
+    initialQueryText = initialQueryText.trim();
+    // Inform user about ignored paths
+    if (ignoredPaths.length > 0) {
+      this.debug(
+        `Ignored ${ignoredPaths.length} files: ${ignoredPaths.join(', ')}`,
+      );
+    }
+
+    const processedQueryParts: Part[] = [{ text: initialQueryText }];
+
+    if (
+      pathSpecsToRead.length === 0 &&
+      embeddedContext.length === 0 &&
+      directContents.length === 0
+    ) {
+      // Fallback for lone "@" or completely invalid @-commands resulting in empty initialQueryText
+      debugLogger.warn('No valid file paths found in @ commands to read.');
+      return [{ text: initialQueryText }];
+    }
+
+    if (pathSpecsToRead.length > 0) {
+      const toolArgs = {
+        include: pathSpecsToRead,
+      };
+
+      const callId = this.generateCallId(readManyFilesTool.name);
+
+      try {
+        const invocation = readManyFilesTool.build(toolArgs);
+
+        const displayTitle =
+          typeof invocation.getDisplayTitle === 'function'
+            ? invocation.getDisplayTitle()
+            : invocation.getDescription();
+
+        await this.sendUpdate({
+          sessionUpdate: 'tool_call',
+          toolCallId: callId,
+          status: 'in_progress',
+          title: displayTitle,
+          content: [],
+          locations: invocation.toolLocations(),
+          kind: toAcpToolKind(readManyFilesTool.kind),
+        });
+
+        const result = await invocation.execute({ abortSignal });
+        const content = toToolCallContent(result) || {
+          type: 'content',
+          content: {
+            type: 'text',
+            text: `Successfully read: ${contentLabelsForDisplay.join(', ')}`,
+          },
+        };
+        await this.sendUpdate({
+          sessionUpdate: 'tool_call_update',
+          toolCallId: callId,
+          status: 'completed',
+          title: displayTitle,
+          content: content ? [content] : [],
+          locations: invocation.toolLocations(),
+          kind: toAcpToolKind(readManyFilesTool.kind),
+        });
+        if (Array.isArray(result.llmContent)) {
+          const fileContentRegex = /^--- (.*?) ---\n\n([\s\S]*?)\n\n$/;
+          processedQueryParts.push({
+            text: `\n${REFERENCE_CONTENT_START}`,
+          });
+          for (const part of result.llmContent) {
+            if (typeof part === 'string') {
+              const match = fileContentRegex.exec(part);
+              if (match) {
+                const filePathSpecInContent = match[1]; // This is a resolved pathSpec
+                const fileActualContent = match[2].trim();
+                processedQueryParts.push({
+                  text: `\nContent from @${filePathSpecInContent}:\n`,
+                });
+                processedQueryParts.push({ text: fileActualContent });
+              } else {
+                processedQueryParts.push({ text: part });
+              }
+            } else {
+              // part is a Part object.
+              processedQueryParts.push(part);
+            }
+          }
+        } else {
+          debugLogger.warn(
+            'read_many_files tool returned no content or empty content.',
+          );
+        }
+      } catch (error: unknown) {
+        await this.sendUpdate({
+          sessionUpdate: 'tool_call_update',
+          toolCallId: callId,
+          status: 'failed',
+          content: [
+            {
+              type: 'content',
+              content: {
+                type: 'text',
+                text: `Error reading files (${contentLabelsForDisplay.join(', ')}): ${getErrorMessage(error)}`,
+              },
+            },
+          ],
+          kind: toAcpToolKind(readManyFilesTool.kind),
+        });
+
+        throw error;
+      }
+    }
+
+    if (directContents.length > 0) {
+      const hasReferenceStart = processedQueryParts.some(
+        (p) =>
+          'text' in p &&
+          typeof p.text === 'string' &&
+          p.text.includes(REFERENCE_CONTENT_START),
+      );
+      if (!hasReferenceStart) {
+        processedQueryParts.push({
+          text: `\n${REFERENCE_CONTENT_START}`,
+        });
+      }
+      for (const item of directContents) {
+        processedQueryParts.push({
+          text: `\nContent from @${item.spec}:\n`,
+        });
+        if (item.content) {
+          processedQueryParts.push({ text: item.content });
+        } else if (item.part) {
+          processedQueryParts.push(item.part);
+        }
+      }
+    }
+
+    if (embeddedContext.length > 0) {
+      processedQueryParts.push({
+        text: '\n--- Content from referenced context ---',
+      });
+
+      for (const contextPart of embeddedContext) {
+        processedQueryParts.push({
+          text: `\nContent from @${contextPart.uri}:\n`,
+        });
+        if ('text' in contextPart) {
+          processedQueryParts.push({
+            text: contextPart.text,
+          });
+        } else {
+          processedQueryParts.push({
+            inlineData: {
+              mimeType: contextPart.mimeType ?? 'application/octet-stream',
+              data: contextPart.blob,
+            },
+          });
+        }
+      }
+    }
+
+    return processedQueryParts;
+  }
+
+  debug(msg: string) {
+    if (this.context.config.getDebugMode()) {
+      debugLogger.warn(msg);
+    }
+  }
+}

packages/cli/src/acp/acpSessionManager.test.ts

@@ -0,0 +1,382 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type Mock,
+  type Mocked,
+} from 'vitest';
+import { AcpSessionManager } from './acpSessionManager.js';
+import type * as acp from '@agentclientprotocol/sdk';
+import {
+  AuthType,
+  type Config,
+  GEMINI_MODEL_ALIAS_AUTO,
+  type MessageBus,
+  type Storage,
+} from '@google/gemini-cli-core';
+import type { LoadedSettings } from '../config/settings.js';
+import { loadCliConfig, type CliArgs } from '../config/config.js';
+import { loadSettings } from '../config/settings.js';
+
+vi.mock('../config/config.js', () => ({
+  loadCliConfig: vi.fn(),
+}));
+
+vi.mock('../config/settings.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../config/settings.js')>();
+  return {
+    ...actual,
+    loadSettings: vi.fn(),
+  };
+});
+
+const startAutoMemoryIfEnabledMock = vi.fn();
+vi.mock('../utils/autoMemory.js', () => ({
+  startAutoMemoryIfEnabled: (config: Config) =>
+    startAutoMemoryIfEnabledMock(config),
+}));
+
+describe('AcpSessionManager', () => {
+  let mockConfig: Mocked<Config>;
+  let mockSettings: Mocked<LoadedSettings>;
+  let mockArgv: CliArgs;
+  let mockConnection: Mocked<acp.AgentSideConnection>;
+  let manager: AcpSessionManager;
+
+  beforeEach(() => {
+    mockConfig = {
+      refreshAuth: vi.fn(),
+      initialize: vi.fn(),
+      waitForMcpInit: vi.fn(),
+      getFileSystemService: vi.fn(),
+      setFileSystemService: vi.fn(),
+      getContentGeneratorConfig: vi.fn(),
+      getActiveModel: vi.fn().mockReturnValue('gemini-pro'),
+      getModel: vi.fn().mockReturnValue('gemini-pro'),
+      getGeminiClient: vi.fn().mockReturnValue({
+        startChat: vi.fn().mockResolvedValue({}),
+      }),
+      getMessageBus: vi.fn().mockReturnValue({
+        publish: vi.fn(),
+        subscribe: vi.fn(),
+        unsubscribe: vi.fn(),
+      }),
+      getApprovalMode: vi.fn().mockReturnValue('default'),
+      isPlanEnabled: vi.fn().mockReturnValue(true),
+      getGemini31LaunchedSync: vi.fn().mockReturnValue(false),
+      getHasAccessToPreviewModel: vi.fn().mockReturnValue(false),
+      getCheckpointingEnabled: vi.fn().mockReturnValue(false),
+      getDisableAlwaysAllow: vi.fn().mockReturnValue(false),
+      validatePathAccess: vi.fn().mockReturnValue(null),
+      getWorkspaceContext: vi.fn().mockReturnValue({
+        addReadOnlyPath: vi.fn(),
+        getDirectories: vi.fn().mockReturnValue(['/tmp']),
+      }),
+      getPolicyEngine: vi.fn().mockReturnValue({
+        addRule: vi.fn(),
+      }),
+      messageBus: {
+        publish: vi.fn(),
+        subscribe: vi.fn(),
+        unsubscribe: vi.fn(),
+      } as unknown as MessageBus,
+      storage: {
+        getWorkspaceAutoSavedPolicyPath: vi.fn(),
+        getAutoSavedPolicyPath: vi.fn(),
+      } as unknown as Storage,
+
+      get config() {
+        return this;
+      },
+    } as unknown as Mocked<Config>;
+    mockSettings = {
+      merged: {
+        security: { auth: { selectedType: 'login_with_google' } },
+        mcpServers: {},
+      },
+      setValue: vi.fn(),
+    } as unknown as Mocked<LoadedSettings>;
+    mockArgv = {} as unknown as CliArgs;
+    mockConnection = {
+      sessionUpdate: vi.fn(),
+      requestPermission: vi.fn(),
+    } as unknown as Mocked<acp.AgentSideConnection>;
+
+    (loadCliConfig as unknown as Mock).mockResolvedValue(mockConfig);
+    (loadSettings as unknown as Mock).mockImplementation(() => ({
+      merged: {
+        security: {
+          auth: { selectedType: AuthType.LOGIN_WITH_GOOGLE },
+          enablePermanentToolApproval: true,
+        },
+        mcpServers: {},
+      },
+      setValue: vi.fn(),
+    }));
+
+    manager = new AcpSessionManager(mockSettings, mockArgv, mockConnection);
+    vi.mock('node:crypto', () => ({
+      randomUUID: () => 'test-session-id',
+    }));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should create a new session', async () => {
+    vi.useFakeTimers();
+    mockConfig.getContentGeneratorConfig = vi.fn().mockReturnValue({
+      apiKey: 'test-key',
+    });
+    const response = await manager.newSession(
+      {
+        cwd: '/tmp',
+        mcpServers: [],
+      },
+      {},
+    );
+
+    expect(response.sessionId).toBe('test-session-id');
+    expect(loadCliConfig).toHaveBeenCalled();
+    expect(mockConfig.initialize).toHaveBeenCalled();
+    expect(mockConfig.getGeminiClient).toHaveBeenCalled();
+
+    // Verify deferred call (sendAvailableCommands)
+    await vi.runAllTimersAsync();
+    expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        update: expect.objectContaining({
+          sessionUpdate: 'available_commands_update',
+        }),
+      }),
+    );
+    vi.useRealTimers();
+  });
+
+  it('should return modes without plan mode when plan is disabled', async () => {
+    mockConfig.getContentGeneratorConfig = vi.fn().mockReturnValue({
+      apiKey: 'test-key',
+    });
+    mockConfig.isPlanEnabled = vi.fn().mockReturnValue(false);
+    mockConfig.getApprovalMode = vi.fn().mockReturnValue('default');
+
+    const response = await manager.newSession(
+      {
+        cwd: '/tmp',
+        mcpServers: [],
+      },
+      {},
+    );
+
+    expect(response.modes).toEqual({
+      availableModes: [
+        { id: 'default', name: 'Default', description: 'Prompts for approval' },
+        {
+          id: 'autoEdit',
+          name: 'Auto Edit',
+          description: 'Auto-approves edit tools',
+        },
+        { id: 'yolo', name: 'YOLO', description: 'Auto-approves all tools' },
+      ],
+      currentModeId: 'default',
+    });
+  });
+
+  it('should include preview models when user has access', async () => {
+    mockConfig.getContentGeneratorConfig = vi.fn().mockReturnValue({
+      apiKey: 'test-key',
+    });
+    mockConfig.getHasAccessToPreviewModel = vi.fn().mockReturnValue(true);
+    mockConfig.getGemini31LaunchedSync = vi.fn().mockReturnValue(true);
+
+    const response = await manager.newSession(
+      {
+        cwd: '/tmp',
+        mcpServers: [],
+      },
+      {},
+    );
+
+    expect(response.models?.availableModels).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          modelId: GEMINI_MODEL_ALIAS_AUTO,
+          name: expect.stringContaining('Auto'),
+        }),
+      ]),
+    );
+  });
+
+  it('should NOT include retired preview models (none) in available models', async () => {
+    mockConfig.getContentGeneratorConfig = vi.fn().mockReturnValue({
+      apiKey: 'test-key',
+    });
+    mockConfig.getHasAccessToPreviewModel = vi.fn().mockReturnValue(true);
+    mockConfig.getGemini31LaunchedSync = vi.fn().mockReturnValue(true);
+
+    const response = await manager.newSession(
+      {
+        cwd: '/tmp',
+        mcpServers: [],
+      },
+      {},
+    );
+
+    const modelIds =
+      response.models?.availableModels?.map((m) => m.modelId) ?? [];
+    expect(modelIds).not.toContain('none');
+  });
+
+  it('should return modes with plan mode when plan is enabled', async () => {
+    mockConfig.getContentGeneratorConfig = vi.fn().mockReturnValue({
+      apiKey: 'test-key',
+    });
+    mockConfig.isPlanEnabled = vi.fn().mockReturnValue(true);
+    mockConfig.getApprovalMode = vi.fn().mockReturnValue('plan');
+
+    const response = await manager.newSession(
+      {
+        cwd: '/tmp',
+        mcpServers: [],
+      },
+      {},
+    );
+
+    expect(response.modes).toEqual({
+      availableModes: [
+        { id: 'default', name: 'Default', description: 'Prompts for approval' },
+        {
+          id: 'autoEdit',
+          name: 'Auto Edit',
+          description: 'Auto-approves edit tools',
+        },
+        { id: 'yolo', name: 'YOLO', description: 'Auto-approves all tools' },
+        { id: 'plan', name: 'Plan', description: 'Read-only mode' },
+      ],
+      currentModeId: 'plan',
+    });
+  });
+
+  it('should fail session creation if Gemini API key is missing', async () => {
+    (loadSettings as unknown as Mock).mockImplementation(() => ({
+      merged: {
+        security: { auth: { selectedType: AuthType.USE_GEMINI } },
+        mcpServers: {},
+      },
+      setValue: vi.fn(),
+    }));
+    mockConfig.getContentGeneratorConfig = vi.fn().mockReturnValue({
+      apiKey: undefined,
+    });
+
+    await expect(
+      manager.newSession(
+        {
+          cwd: '/tmp',
+          mcpServers: [],
+        },
+        {},
+      ),
+    ).rejects.toMatchObject({
+      message: 'Gemini API key is missing or not configured.',
+    });
+  });
+
+  it('should create a new session with mcp servers', async () => {
+    mockConfig.getContentGeneratorConfig = vi.fn().mockReturnValue({
+      apiKey: 'test-key',
+    });
+    const mcpServers = [
+      {
+        name: 'test-server',
+        command: 'node',
+        args: ['server.js'],
+        env: [{ name: 'KEY', value: 'VALUE' }],
+      },
+    ];
+
+    await manager.newSession(
+      {
+        cwd: '/tmp',
+        mcpServers,
+      },
+      {},
+    );
+
+    expect(loadCliConfig).toHaveBeenCalledWith(
+      expect.objectContaining({
+        mcpServers: expect.objectContaining({
+          'test-server': expect.objectContaining({
+            command: 'node',
+            args: ['server.js'],
+            env: { KEY: 'VALUE' },
+          }),
+        }),
+      }),
+      'test-session-id',
+      mockArgv,
+      { cwd: '/tmp' },
+    );
+  });
+
+  it('should handle authentication failure gracefully', async () => {
+    mockConfig.refreshAuth.mockRejectedValue(new Error('Auth failed'));
+
+    await expect(
+      manager.newSession(
+        {
+          cwd: '/tmp',
+          mcpServers: [],
+        },
+        {},
+      ),
+    ).rejects.toMatchObject({
+      message: 'Auth failed',
+    });
+  });
+
+  it('should initialize file system service if client supports it', async () => {
+    mockConfig.getContentGeneratorConfig = vi.fn().mockReturnValue({
+      apiKey: 'test-key',
+    });
+    manager.setClientCapabilities({
+      fs: { readTextFile: true, writeTextFile: true },
+    });
+
+    await manager.newSession(
+      {
+        cwd: '/tmp',
+        mcpServers: [],
+      },
+      {},
+    );
+
+    expect(mockConfig.setFileSystemService).toHaveBeenCalled();
+  });
+
+  it('should start auto memory for new ACP sessions', async () => {
+    mockConfig.getContentGeneratorConfig = vi.fn().mockReturnValue({
+      apiKey: 'test-key',
+    });
+
+    await manager.newSession(
+      {
+        cwd: '/tmp',
+        mcpServers: [],
+      },
+      {},
+    );
+
+    expect(startAutoMemoryIfEnabledMock).toHaveBeenCalledWith(mockConfig);
+  });
+});

packages/cli/src/acp/acpSessionManager.ts

@@ -0,0 +1,343 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  type Config,
+  AuthType,
+  MCPServerConfig,
+  debugLogger,
+  startupProfiler,
+  convertSessionToClientHistory,
+  createPolicyUpdater,
+} from '@google/gemini-cli-core';
+import * as acp from '@agentclientprotocol/sdk';
+import { randomUUID } from 'node:crypto';
+import { loadSettings, type LoadedSettings } from '../config/settings.js';
+import { SessionSelector } from '../utils/sessionUtils.js';
+import { Session } from './acpSession.js';
+import { AcpFileSystemService } from './acpFileSystemService.js';
+import { getAcpErrorMessage } from './acpErrors.js';
+import { buildAvailableModels, buildAvailableModes } from './acpUtils.js';
+import { loadCliConfig, type CliArgs } from '../config/config.js';
+import { startAutoMemoryIfEnabled } from '../utils/autoMemory.js';
+
+export interface AuthDetails {
+  apiKey?: string;
+  baseUrl?: string;
+  customHeaders?: Record<string, string>;
+}
+
+export class AcpSessionManager {
+  private sessions: Map<string, Session> = new Map();
+  private clientCapabilities: acp.ClientCapabilities | undefined;
+
+  constructor(
+    private settings: LoadedSettings,
+    private argv: CliArgs,
+    private connection: acp.AgentSideConnection,
+  ) {}
+
+  setClientCapabilities(capabilities: acp.ClientCapabilities) {
+    this.clientCapabilities = capabilities;
+  }
+
+  getSession(sessionId: string): Session | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  dispose(): void {
+    for (const session of this.sessions.values()) {
+      session.dispose();
+    }
+    this.sessions.clear();
+  }
+
+  async newSession(
+    { cwd, mcpServers }: acp.NewSessionRequest,
+    authDetails: AuthDetails,
+  ): Promise<acp.NewSessionResponse> {
+    const sessionId = randomUUID();
+    const loadedSettings = loadSettings(cwd);
+    const config = await this.newSessionConfig(
+      sessionId,
+      cwd,
+      mcpServers,
+      loadedSettings,
+    );
+
+    const authType =
+      loadedSettings.merged.security.auth.selectedType ||
+      (authDetails.baseUrl || process.env['GOOGLE_GEMINI_BASE_URL']
+        ? AuthType.GATEWAY
+        : AuthType.USE_GEMINI);
+
+    let isAuthenticated = false;
+    let authErrorMessage = '';
+    try {
+      await config.refreshAuth(
+        authType,
+        authDetails.apiKey,
+        authDetails.baseUrl,
+        authDetails.customHeaders,
+      );
+      isAuthenticated = true;
+
+      // Extra validation for Gemini API key
+      const contentGeneratorConfig = config.getContentGeneratorConfig();
+      if (
+        authType === AuthType.USE_GEMINI &&
+        (!contentGeneratorConfig || !contentGeneratorConfig.apiKey)
+      ) {
+        isAuthenticated = false;
+        authErrorMessage = 'Gemini API key is missing or not configured.';
+      }
+    } catch (e) {
+      isAuthenticated = false;
+      authErrorMessage = getAcpErrorMessage(e);
+      debugLogger.error(
+        `Authentication failed: ${e instanceof Error ? e.stack : e}`,
+      );
+    }
+
+    if (!isAuthenticated) {
+      throw new acp.RequestError(
+        -32000,
+        authErrorMessage || 'Authentication required.',
+      );
+    }
+
+    if (this.clientCapabilities?.fs) {
+      const acpFileSystemService = new AcpFileSystemService(
+        this.connection,
+        sessionId,
+        this.clientCapabilities.fs,
+        config.getFileSystemService(),
+        cwd,
+      );
+      config.setFileSystemService(acpFileSystemService);
+    }
+
+    await config.initialize();
+    startupProfiler.flush(config);
+    startAutoMemoryIfEnabled(config);
+
+    const geminiClient = config.getGeminiClient();
+
+    const chat = await geminiClient.startChat();
+
+    const session = new Session(
+      sessionId,
+      chat,
+      config,
+      this.connection,
+      this.settings,
+    );
+    this.sessions.set(sessionId, session);
+
+    setTimeout(() => {
+      // eslint-disable-next-line @typescript-eslint/no-floating-promises
+      session.sendAvailableCommands();
+    }, 0);
+
+    const { availableModels, currentModelId } = buildAvailableModels(
+      config,
+      loadedSettings,
+    );
+
+    const response = {
+      sessionId,
+      modes: {
+        availableModes: buildAvailableModes(config.isPlanEnabled()),
+        currentModeId: config.getApprovalMode(),
+      },
+      models: {
+        availableModels,
+        currentModelId,
+      },
+    };
+    return response;
+  }
+
+  async loadSession(
+    { sessionId, cwd, mcpServers }: acp.LoadSessionRequest,
+    authDetails: AuthDetails,
+  ): Promise<acp.LoadSessionResponse> {
+    const config = await this.initializeSessionConfig(
+      sessionId,
+      cwd,
+      mcpServers,
+      authDetails,
+    );
+
+    const sessionSelector = new SessionSelector(config.storage);
+
+    const { sessionData, sessionPath } =
+      await sessionSelector.resolveSession(sessionId);
+
+    const clientHistory = convertSessionToClientHistory(sessionData.messages);
+
+    const geminiClient = config.getGeminiClient();
+    await geminiClient.initialize();
+    await geminiClient.resumeChat(clientHistory, {
+      conversation: sessionData,
+      filePath: sessionPath,
+    });
+
+    const session = new Session(
+      sessionId,
+      geminiClient.getChat(),
+      config,
+      this.connection,
+      this.settings,
+    );
+
+    const existingSession = this.sessions.get(sessionId);
+    if (existingSession) {
+      existingSession.dispose();
+    }
+
+    this.sessions.set(sessionId, session);
+
+    // Stream history back to client
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    session.streamHistory(sessionData.messages);
+
+    setTimeout(() => {
+      // eslint-disable-next-line @typescript-eslint/no-floating-promises
+      session.sendAvailableCommands();
+    }, 0);
+
+    const { availableModels, currentModelId } = buildAvailableModels(
+      config,
+      this.settings,
+    );
+
+    const response = {
+      modes: {
+        availableModes: buildAvailableModes(config.isPlanEnabled()),
+        currentModeId: config.getApprovalMode(),
+      },
+      models: {
+        availableModels,
+        currentModelId,
+      },
+    };
+    return response;
+  }
+
+  private async initializeSessionConfig(
+    sessionId: string,
+    cwd: string,
+    mcpServers: acp.McpServer[],
+    authDetails: AuthDetails,
+  ): Promise<Config> {
+    const selectedAuthType =
+      this.settings.merged.security.auth.selectedType ||
+      (authDetails.baseUrl || process.env['GOOGLE_GEMINI_BASE_URL']
+        ? AuthType.GATEWAY
+        : undefined);
+
+    if (!selectedAuthType) {
+      throw acp.RequestError.authRequired();
+    }
+
+    // 1. Create config WITHOUT initializing it (no MCP servers started yet)
+    const config = await this.newSessionConfig(sessionId, cwd, mcpServers);
+
+    // 2. Authenticate BEFORE initializing configuration or starting MCP servers.
+    // This satisfies the security requirement to verify the user before executing
+    // potentially unsafe server definitions.
+    try {
+      await config.refreshAuth(
+        selectedAuthType,
+        authDetails.apiKey,
+        authDetails.baseUrl,
+        authDetails.customHeaders,
+      );
+    } catch (e) {
+      debugLogger.error(`Authentication failed: ${e}`);
+      throw acp.RequestError.authRequired();
+    }
+
+    // 3. Set the ACP FileSystemService (if supported) before config initialization
+    if (this.clientCapabilities?.fs) {
+      const acpFileSystemService = new AcpFileSystemService(
+        this.connection,
+        sessionId,
+        this.clientCapabilities.fs,
+        config.getFileSystemService(),
+        cwd,
+      );
+      config.setFileSystemService(acpFileSystemService);
+    }
+
+    // 4. Now that we are authenticated, it is safe to initialize the config
+    // which starts the MCP servers and other heavy resources.
+    await config.initialize();
+    startupProfiler.flush(config);
+    startAutoMemoryIfEnabled(config);
+
+    return config;
+  }
+
+  async newSessionConfig(
+    sessionId: string,
+    cwd: string,
+    mcpServers: acp.McpServer[],
+    loadedSettings?: LoadedSettings,
+  ): Promise<Config> {
+    const currentSettings = loadedSettings || this.settings;
+    const mergedMcpServers = { ...currentSettings.merged.mcpServers };
+
+    for (const server of mcpServers) {
+      if (
+        'type' in server &&
+        (server.type === 'sse' || server.type === 'http')
+      ) {
+        // HTTP or SSE MCP server
+        const headers = Object.fromEntries(
+          server.headers.map(({ name, value }) => [name, value]),
+        );
+        mergedMcpServers[server.name] = new MCPServerConfig(
+          undefined, // command
+          undefined, // args
+          undefined, // env
+          undefined, // cwd
+          server.type === 'sse' ? server.url : undefined, // url (sse)
+          server.type === 'http' ? server.url : undefined, // httpUrl
+          headers,
+        );
+      } else if ('command' in server) {
+        // Stdio MCP server
+        const env: Record<string, string> = {};
+        for (const { name: envName, value } of server.env) {
+          env[envName] = value;
+        }
+        mergedMcpServers[server.name] = new MCPServerConfig(
+          server.command,
+          server.args,
+          env,
+          cwd,
+        );
+      }
+    }
+
+    const settings = {
+      ...currentSettings.merged,
+      mcpServers: mergedMcpServers,
+    };
+
+    const config = await loadCliConfig(settings, sessionId, this.argv, { cwd });
+
+    createPolicyUpdater(
+      config.getPolicyEngine(),
+      config.messageBus,
+      config.storage,
+    );
+
+    return config;
+  }
+}

packages/cli/src/acp/acpStdioTransport.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type Config, createWorkingStdio } from '@google/gemini-cli-core';
+import { runExitCleanup } from '../utils/cleanup.js';
+import * as acp from '@agentclientprotocol/sdk';
+import { Readable, Writable } from 'node:stream';
+import type { LoadedSettings } from '../config/settings.js';
+import type { CliArgs } from '../config/config.js';
+import { GeminiAgent } from './acpRpcDispatcher.js';
+
+export async function runAcpClient(
+  config: Config,
+  settings: LoadedSettings,
+  argv: CliArgs,
+) {
+  const { stdout: workingStdout } = createWorkingStdio();
+  const stdout = Writable.toWeb(workingStdout) as WritableStream;
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  const stdin = Readable.toWeb(process.stdin) as ReadableStream<Uint8Array>;
+
+  const stream = acp.ndJsonStream(stdout, stdin);
+  const connection = new acp.AgentSideConnection(
+    (connection) => new GeminiAgent(config, settings, argv, connection),
+    stream,
+  );
+
+  // SIGTERM/SIGINT handlers (in sdk.ts) don't fire when stdin closes.
+  // We must explicitly await the connection close to flush telemetry.
+  // Use finally() to ensure cleanup runs even on stream errors.
+  await connection.closed.finally(runExitCleanup);
+}

packages/cli/src/acp/acpUtils.ts

@@ -0,0 +1,365 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  type Config,
+  type ToolResult,
+  type ToolCallConfirmationDetails,
+  Kind,
+  ApprovalMode,
+  GEMINI_MODEL_ALIAS_AUTO,
+  DEFAULT_GEMINI_MODEL,
+  DEFAULT_GEMINI_FLASH_MODEL,
+  DEFAULT_GEMINI_FLASH_LITE_MODEL,
+  PREVIEW_GEMINI_3_1_MODEL,
+  PREVIEW_GEMINI_MODEL,
+  PREVIEW_GEMINI_3_1_CUSTOM_TOOLS_MODEL,
+  PREVIEW_GEMINI_FLASH_MODEL,
+  PREVIEW_GEMINI_FLASH_LITE_MODEL,
+  getDisplayString,
+  AuthType,
+  ToolConfirmationOutcome,
+  getAutoModelDescription,
+} from '@google/gemini-cli-core';
+import type * as acp from '@agentclientprotocol/sdk';
+import { z } from 'zod';
+import type { LoadedSettings } from '../config/settings.js';
+
+export function hasMeta(
+  obj: unknown,
+): obj is { _meta?: Record<string, unknown> } {
+  return typeof obj === 'object' && obj !== null && '_meta' in obj;
+}
+
+export const RequestPermissionResponseSchema = z.object({
+  outcome: z.discriminatedUnion('outcome', [
+    z.object({ outcome: z.literal('cancelled') }),
+    z.object({
+      outcome: z.literal('selected'),
+      optionId: z.string(),
+    }),
+  ]),
+});
+
+export function toToolCallContent(
+  toolResult: ToolResult,
+): acp.ToolCallContent | null {
+  if (toolResult.error?.message) {
+    throw new Error(toolResult.error.message);
+  }
+
+  if (toolResult.returnDisplay) {
+    if (typeof toolResult.returnDisplay === 'string') {
+      return {
+        type: 'content',
+        content: { type: 'text', text: toolResult.returnDisplay },
+      };
+    } else {
+      if ('fileName' in toolResult.returnDisplay) {
+        return {
+          type: 'diff',
+          path:
+            toolResult.returnDisplay.filePath ??
+            toolResult.returnDisplay.fileName,
+          oldText: toolResult.returnDisplay.originalContent,
+          newText: toolResult.returnDisplay.newContent,
+          _meta: {
+            kind: !toolResult.returnDisplay.originalContent
+              ? 'add'
+              : toolResult.returnDisplay.newContent === ''
+                ? 'delete'
+                : 'modify',
+          },
+        };
+      }
+      return null;
+    }
+  } else {
+    return null;
+  }
+}
+
+const basicPermissionOptions = [
+  {
+    optionId: ToolConfirmationOutcome.ProceedOnce,
+    name: 'Allow',
+    kind: 'allow_once',
+  },
+  {
+    optionId: ToolConfirmationOutcome.Cancel,
+    name: 'Reject',
+    kind: 'reject_once',
+  },
+] as const;
+
+export function toPermissionOptions(
+  confirmation: ToolCallConfirmationDetails,
+  config: Config,
+  enablePermanentToolApproval: boolean = false,
+): acp.PermissionOption[] {
+  const disableAlwaysAllow = config.getDisableAlwaysAllow();
+  const options: acp.PermissionOption[] = [];
+
+  if (!disableAlwaysAllow) {
+    switch (confirmation.type) {
+      case 'edit':
+        options.push({
+          optionId: ToolConfirmationOutcome.ProceedAlways,
+          name: 'Allow for this session',
+          kind: 'allow_always',
+        });
+        if (enablePermanentToolApproval) {
+          options.push({
+            optionId: ToolConfirmationOutcome.ProceedAlwaysAndSave,
+            name: 'Allow for this file in all future sessions',
+            kind: 'allow_always',
+          });
+        }
+        break;
+      case 'exec':
+        options.push({
+          optionId: ToolConfirmationOutcome.ProceedAlways,
+          name: 'Allow for this session',
+          kind: 'allow_always',
+        });
+        if (enablePermanentToolApproval) {
+          options.push({
+            optionId: ToolConfirmationOutcome.ProceedAlwaysAndSave,
+            name: 'Allow this command for all future sessions',
+            kind: 'allow_always',
+          });
+        }
+        break;
+      case 'mcp':
+        options.push(
+          {
+            optionId: ToolConfirmationOutcome.ProceedAlwaysServer,
+            name: 'Allow all server tools for this session',
+            kind: 'allow_always',
+          },
+          {
+            optionId: ToolConfirmationOutcome.ProceedAlwaysTool,
+            name: 'Allow tool for this session',
+            kind: 'allow_always',
+          },
+        );
+        if (enablePermanentToolApproval) {
+          options.push({
+            optionId: ToolConfirmationOutcome.ProceedAlwaysAndSave,
+            name: 'Allow tool for all future sessions',
+            kind: 'allow_always',
+          });
+        }
+        break;
+      case 'info':
+        options.push({
+          optionId: ToolConfirmationOutcome.ProceedAlways,
+          name: 'Allow for this session',
+          kind: 'allow_always',
+        });
+        if (enablePermanentToolApproval) {
+          options.push({
+            optionId: ToolConfirmationOutcome.ProceedAlwaysAndSave,
+            name: 'Allow for all future sessions',
+            kind: 'allow_always',
+          });
+        }
+        break;
+      case 'ask_user':
+      case 'exit_plan_mode':
+        // askuser and exit_plan_mode don't need "always allow" options
+        break;
+      default:
+        // No "always allow" options for other types
+        break;
+    }
+  }
+
+  options.push(...basicPermissionOptions);
+
+  // Exhaustive check
+  switch (confirmation.type) {
+    case 'edit':
+    case 'exec':
+    case 'mcp':
+    case 'info':
+    case 'ask_user':
+    case 'exit_plan_mode':
+    case 'sandbox_expansion':
+      break;
+    default: {
+      const unreachable: never = confirmation;
+      throw new Error(`Unexpected: ${unreachable}`);
+    }
+  }
+
+  return options;
+}
+
+export function toAcpToolKind(kind: Kind): acp.ToolKind {
+  switch (kind) {
+    case Kind.Read:
+    case Kind.Edit:
+    case Kind.Execute:
+    case Kind.Search:
+    case Kind.Delete:
+    case Kind.Move:
+    case Kind.Think:
+    case Kind.Fetch:
+    case Kind.SwitchMode:
+    case Kind.Other:
+      return kind as acp.ToolKind;
+    case Kind.Agent:
+      return 'think';
+    case Kind.Plan:
+    case Kind.Communicate:
+    default:
+      return 'other';
+  }
+}
+
+export function buildAvailableModes(isPlanEnabled: boolean): acp.SessionMode[] {
+  const modes: acp.SessionMode[] = [
+    {
+      id: ApprovalMode.DEFAULT,
+      name: 'Default',
+      description: 'Prompts for approval',
+    },
+    {
+      id: ApprovalMode.AUTO_EDIT,
+      name: 'Auto Edit',
+      description: 'Auto-approves edit tools',
+    },
+    {
+      id: ApprovalMode.YOLO,
+      name: 'YOLO',
+      description: 'Auto-approves all tools',
+    },
+  ];
+
+  if (isPlanEnabled) {
+    modes.push({
+      id: ApprovalMode.PLAN,
+      name: 'Plan',
+      description: 'Read-only mode',
+    });
+  }
+
+  return modes;
+}
+
+export function buildAvailableModels(
+  config: Config,
+  settings: LoadedSettings,
+): {
+  availableModels: Array<{
+    modelId: string;
+    name: string;
+    description?: string;
+  }>;
+  currentModelId: string;
+} {
+  const preferredModel = config.getModel() || GEMINI_MODEL_ALIAS_AUTO;
+  const shouldShowPreviewModels = config.getHasAccessToPreviewModel();
+  const useGemini31 = config.getGemini31LaunchedSync?.() ?? false;
+  const useGemini3_5Flash = config.hasGemini35FlashGAAccess?.() ?? false;
+  const selectedAuthType = settings.merged.security.auth.selectedType;
+  const useCustomToolModel =
+    useGemini31 && selectedAuthType === AuthType.USE_GEMINI;
+
+  // --- DYNAMIC PATH ---
+  if (
+    config.getExperimentalDynamicModelConfiguration?.() === true &&
+    config.getModelConfigService
+  ) {
+    const options = config.getModelConfigService().getAvailableModelOptions({
+      useGemini3_1: useGemini31,
+      useGemini3_5Flash,
+      useCustomTools: useCustomToolModel,
+      hasAccessToPreview: shouldShowPreviewModels,
+    });
+
+    return {
+      availableModels: options,
+      currentModelId: preferredModel,
+    };
+  }
+
+  // --- LEGACY PATH ---
+  const mainOptions = [
+    {
+      value: GEMINI_MODEL_ALIAS_AUTO,
+      title: getDisplayString(GEMINI_MODEL_ALIAS_AUTO),
+      description: getAutoModelDescription(
+        shouldShowPreviewModels,
+        useGemini31,
+        useGemini3_5Flash,
+      ),
+    },
+  ];
+
+  const manualOptions = [
+    {
+      value: DEFAULT_GEMINI_MODEL,
+      title: getDisplayString(DEFAULT_GEMINI_MODEL),
+    },
+    {
+      value: DEFAULT_GEMINI_FLASH_MODEL,
+      title: getDisplayString(DEFAULT_GEMINI_FLASH_MODEL),
+    },
+    {
+      value: DEFAULT_GEMINI_FLASH_LITE_MODEL,
+      title: getDisplayString(DEFAULT_GEMINI_FLASH_LITE_MODEL),
+    },
+  ];
+
+  if (shouldShowPreviewModels) {
+    const previewProModel = useGemini31
+      ? PREVIEW_GEMINI_3_1_MODEL
+      : PREVIEW_GEMINI_MODEL;
+
+    const previewProValue = useCustomToolModel
+      ? PREVIEW_GEMINI_3_1_CUSTOM_TOOLS_MODEL
+      : previewProModel;
+
+    const previewOptions = [
+      {
+        value: previewProValue,
+        title: getDisplayString(previewProModel),
+      },
+      {
+        value: PREVIEW_GEMINI_FLASH_MODEL,
+        title: getDisplayString(PREVIEW_GEMINI_FLASH_MODEL),
+      },
+    ];
+
+    if (PREVIEW_GEMINI_FLASH_LITE_MODEL !== 'none') {
+      previewOptions.push({
+        value: PREVIEW_GEMINI_FLASH_LITE_MODEL,
+        title: getDisplayString(PREVIEW_GEMINI_FLASH_LITE_MODEL),
+      });
+    }
+
+    manualOptions.unshift(...previewOptions);
+  }
+
+  const scaleOptions = (
+    options: Array<{ value: string; title: string; description?: string }>,
+  ) =>
+    options.map((o) => ({
+      modelId: o.value,
+      name: o.title,
+      description: o.description,
+    }));
+
+  return {
+    availableModels: [
+      ...scaleOptions(mainOptions),
+      ...scaleOptions(manualOptions),
+    ],
+    currentModelId: preferredModel,
+  };
+}

packages/cli/src/acp/commands/about.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  IdeClient,
+  UserAccountManager,
+  getVersion,
+} from '@google/gemini-cli-core';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+import process from 'node:process';
+
+export class AboutCommand implements Command {
+  readonly name = 'about';
+  readonly description = 'Show version and environment info';
+
+  async execute(
+    context: CommandContext,
+    _args: string[] = [],
+  ): Promise<CommandExecutionResponse> {
+    const osVersion = process.platform;
+    let sandboxEnv = 'no sandbox';
+    if (process.env['SANDBOX'] && process.env['SANDBOX'] !== 'sandbox-exec') {
+      sandboxEnv = process.env['SANDBOX'];
+    } else if (process.env['SANDBOX'] === 'sandbox-exec') {
+      sandboxEnv = `sandbox-exec (${
+        process.env['SEATBELT_PROFILE'] || 'unknown'
+      })`;
+    }
+    const modelVersion = context.agentContext.config.getModel() || 'Unknown';
+    const cliVersion = await getVersion();
+    const selectedAuthType =
+      context.settings.merged?.security?.auth?.selectedType ?? '';
+    const gcpProject = process.env['GOOGLE_CLOUD_PROJECT'] || '';
+    const ideClient = await getIdeClientName(context);
+
+    const userAccountManager = new UserAccountManager();
+    const cachedAccount = userAccountManager.getCachedGoogleAccount();
+    const userEmail = cachedAccount ?? 'Unknown';
+
+    const tier = context.agentContext.config.getUserTierName() || 'Unknown';
+
+    const info = [
+      `- Version: ${cliVersion}`,
+      `- OS: ${osVersion}`,
+      `- Sandbox: ${sandboxEnv}`,
+      `- Model: ${modelVersion}`,
+      `- Auth Type: ${selectedAuthType}`,
+      `- GCP Project: ${gcpProject}`,
+      `- IDE Client: ${ideClient}`,
+      `- User Email: ${userEmail}`,
+      `- Tier: ${tier}`,
+    ].join('\n');
+
+    return {
+      name: this.name,
+      data: `Gemini CLI Info:\n${info}`,
+    };
+  }
+}
+
+async function getIdeClientName(context: CommandContext) {
+  if (!context.agentContext.config.getIdeMode()) {
+    return '';
+  }
+  const ideClient = await IdeClient.getInstance();
+  return ideClient?.getDetectedIdeDisplayName() ?? '';
+}

packages/cli/src/acp/commands/commandRegistry.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { debugLogger } from '@google/gemini-cli-core';
+import type { Command } from './types.js';
+
+export class CommandRegistry {
+  private readonly commands = new Map<string, Command>();
+
+  register(command: Command) {
+    if (this.commands.has(command.name)) {
+      debugLogger.warn(`Command ${command.name} already registered. Skipping.`);
+      return;
+    }
+
+    this.commands.set(command.name, command);
+
+    for (const subCommand of command.subCommands ?? []) {
+      this.register(subCommand);
+    }
+  }
+
+  get(commandName: string): Command | undefined {
+    return this.commands.get(commandName);
+  }
+
+  getAllCommands(): Command[] {
+    return [...this.commands.values()];
+  }
+}

packages/cli/src/acp/commands/extensions.test.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { CommandContext } from './types.js';
+import {
+  DisableExtensionCommand,
+  UninstallExtensionCommand,
+} from './extensions.js';
+import { ExtensionManager } from '../../config/extension-manager.js';
+
+const mockGetErrorMessage = vi.hoisted(() => vi.fn());
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    getErrorMessage: mockGetErrorMessage,
+  };
+});
+
+vi.mock('../../config/extension-manager.js', () => {
+  class MockExtensionManager {
+    disableExtension = vi.fn(async () => undefined);
+    uninstallExtension = vi.fn(async () => undefined);
+    getExtensions = vi.fn(() => []);
+  }
+
+  return {
+    ExtensionManager: MockExtensionManager,
+    inferInstallMetadata: vi.fn(),
+  };
+});
+
+type TestExtensionManager = InstanceType<typeof ExtensionManager> & {
+  disableExtension: ReturnType<typeof vi.fn>;
+  uninstallExtension: ReturnType<typeof vi.fn>;
+  getExtensions: ReturnType<typeof vi.fn>;
+};
+
+function createExtensionManager(): TestExtensionManager {
+  return new ExtensionManager({} as never) as TestExtensionManager;
+}
+
+function createContext(extensionLoader: unknown): CommandContext {
+  return {
+    agentContext: {
+      config: {
+        getExtensionLoader: vi.fn().mockReturnValue(extensionLoader),
+      },
+    } as unknown as CommandContext['agentContext'],
+    settings: {} as CommandContext['settings'],
+    sendMessage: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe('ACP extensions error paths', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockGetErrorMessage.mockImplementation((error: unknown) =>
+      error instanceof Error ? error.message : String(error),
+    );
+  });
+
+  it('returns error when disabling fails', async () => {
+    const command = new DisableExtensionCommand();
+    const extensionManager = createExtensionManager();
+    extensionManager.disableExtension.mockRejectedValue(
+      new Error('Extension not found.'),
+    );
+    const context = createContext(extensionManager);
+
+    const result = await command.execute(context, ['missing-ext']);
+
+    expect(result).toEqual({
+      name: 'extensions disable',
+      data: 'Failed to disable "missing-ext": Extension not found.',
+    });
+  });
+
+  it('returns error when uninstalling a non-existent extension', async () => {
+    const command = new UninstallExtensionCommand();
+    const extensionManager = createExtensionManager();
+    extensionManager.uninstallExtension.mockRejectedValue(
+      new Error('Extension not found.'),
+    );
+    const context = createContext(extensionManager);
+
+    const result = await command.execute(context, ['non-existent-ext']);
+
+    expect(result).toEqual({
+      name: 'extensions uninstall',
+      data: 'Failed to uninstall extension "non-existent-ext": Extension not found.',
+    });
+  });
+});

packages/cli/src/acp/commands/extensions.ts

@@ -0,0 +1,448 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  listExtensions,
+  type Config,
+  getErrorMessage,
+} from '@google/gemini-cli-core';
+import { SettingScope } from '../../config/settings.js';
+import {
+  ExtensionManager,
+  inferInstallMetadata,
+} from '../../config/extension-manager.js';
+import { McpServerEnablementManager } from '../../config/mcp/mcpServerEnablement.js';
+import { stat } from 'node:fs/promises';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+
+export class ExtensionsCommand implements Command {
+  readonly name = 'extensions';
+  readonly description = 'Manage extensions.';
+  readonly subCommands = [
+    new ListExtensionsCommand(),
+    new ExploreExtensionsCommand(),
+    new EnableExtensionCommand(),
+    new DisableExtensionCommand(),
+    new InstallExtensionCommand(),
+    new LinkExtensionCommand(),
+    new UninstallExtensionCommand(),
+    new RestartExtensionCommand(),
+    new UpdateExtensionCommand(),
+  ];
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    return new ListExtensionsCommand().execute(context, _);
+  }
+}
+
+export class ListExtensionsCommand implements Command {
+  readonly name = 'extensions list';
+  readonly description = 'Lists all installed extensions.';
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    const extensions = listExtensions(context.agentContext.config);
+    const data = extensions.length ? extensions : 'No extensions installed.';
+
+    return { name: this.name, data };
+  }
+}
+
+export class ExploreExtensionsCommand implements Command {
+  readonly name = 'extensions explore';
+  readonly description = 'Explore available extensions.';
+
+  async execute(
+    _context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    const extensionsUrl = 'https://geminicli.com/extensions/';
+    return {
+      name: this.name,
+      data: `View or install available extensions at ${extensionsUrl}`,
+    };
+  }
+}
+
+function getEnableDisableContext(
+  config: Config,
+  args: string[],
+  invocationName: string,
+) {
+  const extensionManager = config.getExtensionLoader();
+  if (!(extensionManager instanceof ExtensionManager)) {
+    return {
+      error: `Cannot ${invocationName} extensions in this environment.`,
+    };
+  }
+
+  if (args.length === 0) {
+    return {
+      error: `Usage: /extensions ${invocationName} <extension> [--scope=<user|workspace|session>]`,
+    };
+  }
+
+  let scope = SettingScope.User;
+  if (args.includes('--scope=workspace') || args.includes('workspace')) {
+    scope = SettingScope.Workspace;
+  } else if (args.includes('--scope=session') || args.includes('session')) {
+    scope = SettingScope.Session;
+  }
+
+  const name = args.filter(
+    (a) =>
+      !a.startsWith('--scope') && !['user', 'workspace', 'session'].includes(a),
+  )[0];
+
+  let names: string[] = [];
+  if (name === '--all') {
+    let extensions = extensionManager.getExtensions();
+    if (invocationName === 'enable') {
+      extensions = extensions.filter((ext) => !ext.isActive);
+    }
+    if (invocationName === 'disable') {
+      extensions = extensions.filter((ext) => ext.isActive);
+    }
+    names = extensions.map((ext) => ext.name);
+  } else if (name) {
+    names = [name];
+  } else {
+    return { error: 'No extension name provided.' };
+  }
+
+  return { extensionManager, names, scope };
+}
+
+export class EnableExtensionCommand implements Command {
+  readonly name = 'extensions enable';
+  readonly description = 'Enable an extension.';
+
+  async execute(
+    context: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse> {
+    const enableContext = getEnableDisableContext(
+      context.agentContext.config,
+      args,
+      'enable',
+    );
+    if ('error' in enableContext) {
+      return { name: this.name, data: enableContext.error };
+    }
+
+    const { names, scope, extensionManager } = enableContext;
+    const output: string[] = [];
+
+    for (const name of names) {
+      try {
+        await extensionManager.enableExtension(name, scope);
+        output.push(`Extension "${name}" enabled for scope "${scope}".`);
+
+        const extension = extensionManager
+          .getExtensions()
+          .find((e) => e.name === name);
+
+        if (extension?.mcpServers) {
+          const mcpEnablementManager = McpServerEnablementManager.getInstance();
+          const mcpClientManager =
+            context.agentContext.config.getMcpClientManager();
+          const enabledServers = await mcpEnablementManager.autoEnableServers(
+            Object.keys(extension.mcpServers),
+          );
+
+          if (mcpClientManager && enabledServers.length > 0) {
+            const restartPromises = enabledServers.map((serverName) =>
+              mcpClientManager.restartServer(serverName).catch((error) => {
+                output.push(
+                  `Failed to restart MCP server '${serverName}': ${getErrorMessage(error)}`,
+                );
+              }),
+            );
+            await Promise.all(restartPromises);
+            output.push(`Re-enabled MCP servers: ${enabledServers.join(', ')}`);
+          }
+        }
+      } catch (e) {
+        output.push(`Failed to enable "${name}": ${getErrorMessage(e)}`);
+      }
+    }
+
+    return { name: this.name, data: output.join('\n') || 'No action taken.' };
+  }
+}
+
+export class DisableExtensionCommand implements Command {
+  readonly name = 'extensions disable';
+  readonly description = 'Disable an extension.';
+
+  async execute(
+    context: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse> {
+    const enableContext = getEnableDisableContext(
+      context.agentContext.config,
+      args,
+      'disable',
+    );
+    if ('error' in enableContext) {
+      return { name: this.name, data: enableContext.error };
+    }
+
+    const { names, scope, extensionManager } = enableContext;
+    const output: string[] = [];
+
+    for (const name of names) {
+      try {
+        await extensionManager.disableExtension(name, scope);
+        output.push(`Extension "${name}" disabled for scope "${scope}".`);
+      } catch (e) {
+        output.push(`Failed to disable "${name}": ${getErrorMessage(e)}`);
+      }
+    }
+
+    return { name: this.name, data: output.join('\n') || 'No action taken.' };
+  }
+}
+
+export class InstallExtensionCommand implements Command {
+  readonly name = 'extensions install';
+  readonly description = 'Install an extension from a git repo or local path.';
+
+  async execute(
+    context: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse> {
+    const extensionLoader = context.agentContext.config.getExtensionLoader();
+    if (!(extensionLoader instanceof ExtensionManager)) {
+      return {
+        name: this.name,
+        data: 'Cannot install extensions in this environment.',
+      };
+    }
+
+    const source = args.join(' ').trim();
+    if (!source) {
+      return { name: this.name, data: `Usage: /extensions install <source>` };
+    }
+
+    if (/[;&|`'"]/.test(source)) {
+      return {
+        name: this.name,
+        data: `Invalid source: contains disallowed characters.`,
+      };
+    }
+
+    try {
+      const installMetadata = await inferInstallMetadata(source);
+      const extension =
+        await extensionLoader.installOrUpdateExtension(installMetadata);
+      return {
+        name: this.name,
+        data: `Extension "${extension.name}" installed successfully.`,
+      };
+    } catch (error) {
+      return {
+        name: this.name,
+        data: `Failed to install extension from "${source}": ${getErrorMessage(error)}`,
+      };
+    }
+  }
+}
+
+export class LinkExtensionCommand implements Command {
+  readonly name = 'extensions link';
+  readonly description = 'Link an extension from a local path.';
+
+  async execute(
+    context: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse> {
+    const extensionLoader = context.agentContext.config.getExtensionLoader();
+    if (!(extensionLoader instanceof ExtensionManager)) {
+      return {
+        name: this.name,
+        data: 'Cannot link extensions in this environment.',
+      };
+    }
+
+    const sourceFilepath = args.join(' ').trim();
+    if (!sourceFilepath) {
+      return { name: this.name, data: `Usage: /extensions link <source>` };
+    }
+
+    try {
+      await stat(sourceFilepath);
+    } catch {
+      return { name: this.name, data: `Invalid source: ${sourceFilepath}` };
+    }
+
+    try {
+      const extension = await extensionLoader.installOrUpdateExtension({
+        source: sourceFilepath,
+        type: 'link',
+      });
+      return {
+        name: this.name,
+        data: `Extension "${extension.name}" linked successfully.`,
+      };
+    } catch (error) {
+      return {
+        name: this.name,
+        data: `Failed to link extension: ${getErrorMessage(error)}`,
+      };
+    }
+  }
+}
+
+export class UninstallExtensionCommand implements Command {
+  readonly name = 'extensions uninstall';
+  readonly description = 'Uninstall an extension.';
+
+  async execute(
+    context: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse> {
+    const extensionLoader = context.agentContext.config.getExtensionLoader();
+    if (!(extensionLoader instanceof ExtensionManager)) {
+      return {
+        name: this.name,
+        data: 'Cannot uninstall extensions in this environment.',
+      };
+    }
+
+    const all = args.includes('--all');
+    const names = args.filter((a) => !a.startsWith('--')).map((a) => a.trim());
+
+    if (!all && names.length === 0) {
+      return {
+        name: this.name,
+        data: `Usage: /extensions uninstall <extension-names...>|--all`,
+      };
+    }
+
+    let namesToUninstall: string[] = [];
+    if (all) {
+      namesToUninstall = extensionLoader.getExtensions().map((ext) => ext.name);
+    } else {
+      namesToUninstall = names;
+    }
+
+    if (namesToUninstall.length === 0) {
+      return {
+        name: this.name,
+        data: all ? 'No extensions installed.' : 'No extension name provided.',
+      };
+    }
+
+    const output: string[] = [];
+    for (const extensionName of namesToUninstall) {
+      try {
+        await extensionLoader.uninstallExtension(extensionName, false);
+        output.push(`Extension "${extensionName}" uninstalled successfully.`);
+      } catch (error) {
+        output.push(
+          `Failed to uninstall extension "${extensionName}": ${getErrorMessage(error)}`,
+        );
+      }
+    }
+
+    return { name: this.name, data: output.join('\n') };
+  }
+}
+
+export class RestartExtensionCommand implements Command {
+  readonly name = 'extensions restart';
+  readonly description = 'Restart an extension.';
+
+  async execute(
+    context: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse> {
+    const extensionLoader = context.agentContext.config.getExtensionLoader();
+    if (!(extensionLoader instanceof ExtensionManager)) {
+      return { name: this.name, data: 'Cannot restart extensions.' };
+    }
+
+    const all = args.includes('--all');
+    const names = all ? null : args.filter((a) => !!a);
+
+    if (!all && names?.length === 0) {
+      return {
+        name: this.name,
+        data: 'Usage: /extensions restart <extension-names>|--all',
+      };
+    }
+
+    let extensionsToRestart = extensionLoader
+      .getExtensions()
+      .filter((e) => e.isActive);
+    if (names) {
+      extensionsToRestart = extensionsToRestart.filter((e) =>
+        names.includes(e.name),
+      );
+    }
+
+    if (extensionsToRestart.length === 0) {
+      return {
+        name: this.name,
+        data: 'No active extensions matched the request.',
+      };
+    }
+
+    const output: string[] = [];
+    for (const extension of extensionsToRestart) {
+      try {
+        await extensionLoader.restartExtension(extension);
+        output.push(`Restarted "${extension.name}".`);
+      } catch (e) {
+        output.push(
+          `Failed to restart "${extension.name}": ${getErrorMessage(e)}`,
+        );
+      }
+    }
+
+    return { name: this.name, data: output.join('\n') };
+  }
+}
+
+export class UpdateExtensionCommand implements Command {
+  readonly name = 'extensions update';
+  readonly description = 'Update an extension.';
+
+  async execute(
+    context: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse> {
+    const extensionLoader = context.agentContext.config.getExtensionLoader();
+    if (!(extensionLoader instanceof ExtensionManager)) {
+      return { name: this.name, data: 'Cannot update extensions.' };
+    }
+
+    const all = args.includes('--all');
+    const names = all ? null : args.filter((a) => !!a);
+
+    if (!all && names?.length === 0) {
+      return {
+        name: this.name,
+        data: 'Usage: /extensions update <extension-names>|--all',
+      };
+    }
+
+    return {
+      name: this.name,
+      data: 'Headless extension updating requires internal UI dispatches. Please use `gemini extensions update` directly in the terminal.',
+    };
+  }
+}

packages/cli/src/acp/commands/help.test.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { HelpCommand } from './help.js';
+import { CommandRegistry } from './commandRegistry.js';
+import type { Command, CommandContext } from './types.js';
+
+describe('HelpCommand', () => {
+  it('returns formatted help text with sorted commands', async () => {
+    const registry = new CommandRegistry();
+
+    const cmdB: Command = {
+      name: 'bravo',
+      description: 'Bravo command',
+      execute: async () => ({ name: 'bravo', data: '' }),
+    };
+
+    const cmdA: Command = {
+      name: 'alpha',
+      description: 'Alpha command',
+      execute: async () => ({ name: 'alpha', data: '' }),
+    };
+
+    registry.register(cmdB);
+    registry.register(cmdA);
+
+    const helpCommand = new HelpCommand(registry);
+
+    const context = {} as CommandContext;
+
+    const response = await helpCommand.execute(context, []);
+
+    expect(response.name).toBe('help');
+
+    const data = response.data as string;
+
+    expect(data).toContain('Gemini CLI Help:');
+    expect(data).toContain('### Basics');
+    expect(data).toContain('### Commands');
+
+    const lines = data.split('\n');
+    const alphaIndex = lines.findIndex((l) => l.includes('/alpha'));
+    const bravoIndex = lines.findIndex((l) => l.includes('/bravo'));
+
+    expect(alphaIndex).toBeLessThan(bravoIndex);
+    expect(alphaIndex).not.toBe(-1);
+    expect(bravoIndex).not.toBe(-1);
+  });
+});

packages/cli/src/acp/commands/help.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+import type { CommandRegistry } from './commandRegistry.js';
+
+export class HelpCommand implements Command {
+  readonly name = 'help';
+  readonly description = 'Show available commands';
+
+  constructor(private registry: CommandRegistry) {}
+
+  async execute(
+    _context: CommandContext,
+    _args: string[] = [],
+  ): Promise<CommandExecutionResponse> {
+    const commands = this.registry
+      .getAllCommands()
+      .sort((a, b) => a.name.localeCompare(b.name));
+
+    const lines: string[] = [];
+
+    lines.push('Gemini CLI Help:');
+    lines.push('');
+    lines.push('### Basics');
+    lines.push(
+      '- **Add context**: Use `@` to specify files for context (e.g., `@src/myFile.ts`) to target specific files or folders.',
+    );
+    lines.push('');
+
+    lines.push('### Commands');
+    for (const cmd of commands) {
+      if (cmd.description) {
+        lines.push(`- **/${cmd.name}** - ${cmd.description}`);
+      }
+    }
+
+    return {
+      name: this.name,
+      data: lines.join('\n'),
+    };
+  }
+}

packages/cli/src/acp/commands/init.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { performInit } from '@google/gemini-cli-core';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+
+export class InitCommand implements Command {
+  name = 'init';
+  description = 'Analyzes the project and creates a tailored GEMINI.md file';
+  requiresWorkspace = true;
+
+  async execute(
+    context: CommandContext,
+    _args: string[] = [],
+  ): Promise<CommandExecutionResponse> {
+    const targetDir = context.agentContext.config.getTargetDir();
+    if (!targetDir) {
+      throw new Error('Command requires a workspace.');
+    }
+
+    const geminiMdPath = path.join(targetDir, 'GEMINI.md');
+    const result = performInit(fs.existsSync(geminiMdPath));
+
+    switch (result.type) {
+      case 'message':
+        return {
+          name: this.name,
+          data: result,
+        };
+      case 'submit_prompt':
+        fs.writeFileSync(geminiMdPath, '', 'utf8');
+
+        if (typeof result.content !== 'string') {
+          throw new Error('Init command content must be a string.');
+        }
+
+        // Inform the user since we can't trigger the UI-based interactive agent loop here directly.
+        // We output the prompt text they can use to re-trigger the generation manually,
+        // or just seed the GEMINI.md file as we've done above.
+        return {
+          name: this.name,
+          data: {
+            type: 'message',
+            messageType: 'info',
+            content: `A template GEMINI.md has been created at ${geminiMdPath}.\n\nTo populate it with project context, you can run the following prompt in a new chat:\n\n${result.content}`,
+          },
+        };
+
+      default:
+        throw new Error('Unknown result type from performInit');
+    }
+  }
+}

packages/cli/src/acp/commands/memory.ts

@@ -0,0 +1,142 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  listInboxMemoryPatches,
+  listInboxSkills,
+  listInboxPatches,
+  listMemoryFiles,
+  refreshMemory,
+  showMemory,
+} from '@google/gemini-cli-core';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+
+export class MemoryCommand implements Command {
+  readonly name = 'memory';
+  readonly description = 'Manage memory.';
+  readonly subCommands = [
+    new ShowMemoryCommand(),
+    new RefreshMemoryCommand(),
+    new ListMemoryCommand(),
+    new InboxMemoryCommand(),
+  ];
+  readonly requiresWorkspace = true;
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    return new ShowMemoryCommand().execute(context, _);
+  }
+}
+
+export class ShowMemoryCommand implements Command {
+  readonly name = 'memory show';
+  readonly description = 'Shows the current memory contents.';
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    const result = showMemory(context.agentContext.config);
+    return { name: this.name, data: result.content };
+  }
+}
+
+export class RefreshMemoryCommand implements Command {
+  readonly name = 'memory refresh';
+  readonly aliases = ['memory reload'];
+  readonly description = 'Refreshes the memory from the source.';
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    const result = await refreshMemory(context.agentContext.config);
+    return { name: this.name, data: result.content };
+  }
+}
+
+export class ListMemoryCommand implements Command {
+  readonly name = 'memory list';
+  readonly description = 'Lists the paths of the GEMINI.md files in use.';
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    const result = listMemoryFiles(context.agentContext.config);
+    return { name: this.name, data: result.content };
+  }
+}
+
+export class InboxMemoryCommand implements Command {
+  readonly name = 'memory inbox';
+  readonly description =
+    'Lists memory items extracted from past sessions that are pending review.';
+
+  async execute(
+    context: CommandContext,
+    _: string[],
+  ): Promise<CommandExecutionResponse> {
+    if (!context.agentContext.config.isAutoMemoryEnabled()) {
+      return {
+        name: this.name,
+        data: 'The memory inbox requires Auto Memory. Enable it with: experimental.autoMemory = true in settings.',
+      };
+    }
+
+    const [skills, patches, memoryPatches] = await Promise.all([
+      listInboxSkills(context.agentContext.config),
+      listInboxPatches(context.agentContext.config),
+      listInboxMemoryPatches(context.agentContext.config),
+    ]);
+
+    if (
+      skills.length === 0 &&
+      patches.length === 0 &&
+      memoryPatches.length === 0
+    ) {
+      return { name: this.name, data: 'No items in inbox.' };
+    }
+
+    const lines: string[] = [];
+    for (const s of skills) {
+      const date = s.extractedAt
+        ? ` (extracted: ${new Date(s.extractedAt).toLocaleDateString()})`
+        : '';
+      lines.push(`- **${s.name}**: ${s.description}${date}`);
+    }
+    for (const p of patches) {
+      const targets = p.entries.map((e) => e.targetPath).join(', ');
+      const date = p.extractedAt
+        ? ` (extracted: ${new Date(p.extractedAt).toLocaleDateString()})`
+        : '';
+      lines.push(`- **${p.name}** (update): patches ${targets}${date}`);
+    }
+    for (const memoryPatch of memoryPatches) {
+      const targets = memoryPatch.entries.map((e) => e.targetPath).join(', ');
+      const date = memoryPatch.extractedAt
+        ? ` (latest extract: ${new Date(memoryPatch.extractedAt).toLocaleDateString()})`
+        : '';
+      const sourceCount = memoryPatch.sourceFiles.length;
+      const sourceLabel = sourceCount === 1 ? 'patch' : 'patches';
+      lines.push(
+        `- **${memoryPatch.name}** (${sourceCount} source ${sourceLabel}, ${memoryPatch.entries.length} hunks): targets ${targets}${date}`,
+      );
+    }
+
+    const total = skills.length + patches.length + memoryPatches.length;
+    return {
+      name: this.name,
+      data: `Memory inbox (${total}):\n${lines.join('\n')}`,
+    };
+  }
+}

packages/cli/src/acp/commands/restore.test.ts

@@ -0,0 +1,244 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { RestoreCommand, ListCheckpointsCommand } from './restore.js';
+import * as fs from 'node:fs/promises';
+import {
+  getCheckpointInfoList,
+  getToolCallDataSchema,
+  isNodeError,
+  performRestore,
+} from '@google/gemini-cli-core';
+import type { CommandContext } from './types.js';
+import type { Mock } from 'vitest';
+
+vi.mock('node:fs/promises');
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    getCheckpointInfoList: vi.fn(),
+    getToolCallDataSchema: vi.fn(),
+    isNodeError: vi.fn(),
+    performRestore: vi.fn(),
+  };
+});
+
+describe('RestoreCommand', () => {
+  let context: CommandContext;
+  let restoreCommand: RestoreCommand;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    restoreCommand = new RestoreCommand();
+    context = {
+      agentContext: {
+        config: {
+          getCheckpointingEnabled: vi.fn().mockReturnValue(true),
+          storage: {
+            getProjectTempCheckpointsDir: vi
+              .fn()
+              .mockReturnValue('/tmp/checkpoints'),
+          },
+        },
+      },
+      git: {},
+      sendMessage: vi.fn(),
+    } as unknown as CommandContext;
+  });
+
+  it('delegates to list behavior when invoked without args', async () => {
+    const listExecuteSpy = vi
+      .spyOn(ListCheckpointsCommand.prototype, 'execute')
+      .mockResolvedValue({
+        name: 'restore list',
+        data: 'list data',
+      });
+
+    const response = await restoreCommand.execute(context, []);
+
+    expect(listExecuteSpy).toHaveBeenCalledWith(context);
+    expect(response).toEqual({
+      name: 'restore list',
+      data: 'list data',
+    });
+  });
+
+  it('returns checkpointing-disabled message when disabled', async () => {
+    (
+      context.agentContext.config.getCheckpointingEnabled as Mock
+    ).mockReturnValue(false);
+
+    const response = await restoreCommand.execute(context, ['checkpoint1']);
+
+    expect(response.data).toContain('Checkpointing is not enabled');
+  });
+
+  it('returns file-not-found message for missing checkpoint', async () => {
+    const error = new Error('ENOENT');
+    (error as Error & { code: string }).code = 'ENOENT';
+    vi.mocked(fs.readFile).mockRejectedValue(error);
+    vi.mocked(isNodeError).mockReturnValue(true);
+
+    const response = await restoreCommand.execute(context, ['missing']);
+
+    expect(response.data).toBe('File not found: missing.json');
+  });
+
+  it('handles checkpoint filename already ending in .json', async () => {
+    const error = new Error('ENOENT');
+    (error as Error & { code: string }).code = 'ENOENT';
+    vi.mocked(fs.readFile).mockRejectedValue(error);
+    vi.mocked(isNodeError).mockReturnValue(true);
+
+    const response = await restoreCommand.execute(context, ['existing.json']);
+
+    expect(response.data).toBe('File not found: existing.json');
+    expect(fs.readFile).toHaveBeenCalledWith(
+      expect.stringContaining('existing.json'),
+      'utf-8',
+    );
+  });
+
+  it('returns invalid/corrupt checkpoint message when schema parse fails', async () => {
+    vi.mocked(fs.readFile).mockResolvedValue('{"invalid": "data"}');
+    vi.mocked(getToolCallDataSchema).mockReturnValue({
+      safeParse: vi.fn().mockReturnValue({ success: false }),
+    } as unknown as ReturnType<typeof getToolCallDataSchema>);
+
+    const response = await restoreCommand.execute(context, ['invalid']);
+
+    expect(response.data).toBe('Checkpoint file is invalid or corrupted.');
+  });
+
+  it('formats streamed restore results correctly', async () => {
+    vi.mocked(fs.readFile).mockResolvedValue('{"valid": "data"}');
+    vi.mocked(getToolCallDataSchema).mockReturnValue({
+      safeParse: vi
+        .fn()
+        .mockReturnValue({ success: true, data: { some: 'data' } }),
+    } as unknown as ReturnType<typeof getToolCallDataSchema>);
+
+    async function* mockRestoreGenerator() {
+      yield { type: 'message', messageType: 'info', content: 'Restoring...' };
+      yield { type: 'load_history', clientHistory: [{}, {}] };
+      yield { type: 'other', some: 'other' };
+    }
+    vi.mocked(performRestore).mockReturnValue(
+      mockRestoreGenerator() as unknown as ReturnType<typeof performRestore>,
+    );
+
+    const response = await restoreCommand.execute(context, ['valid']);
+
+    expect(response.data).toContain('[INFO] Restoring...');
+    expect(response.data).toContain('Loaded history with 2 messages.');
+    expect(response.data).toContain(
+      'Restored: {"type":"other","some":"other"}',
+    );
+  });
+
+  it('returns generic unexpected error message for non-ENOENT failures', async () => {
+    vi.mocked(fs.readFile).mockRejectedValue(new Error('Random error'));
+    vi.mocked(isNodeError).mockReturnValue(false);
+
+    const response = await restoreCommand.execute(context, ['error']);
+
+    expect(response.data).toContain(
+      'An unexpected error occurred during restore: Error: Random error',
+    );
+  });
+});
+
+describe('ListCheckpointsCommand', () => {
+  let context: CommandContext;
+  let listCommand: ListCheckpointsCommand;
+  let mockReaddir: Mock<(path: string) => Promise<string[]>>;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    listCommand = new ListCheckpointsCommand();
+    mockReaddir = vi.mocked(fs.readdir) as unknown as Mock<
+      (path: string) => Promise<string[]>
+    >;
+
+    context = {
+      agentContext: {
+        config: {
+          getCheckpointingEnabled: vi.fn().mockReturnValue(true),
+          storage: {
+            getProjectTempCheckpointsDir: vi
+              .fn()
+              .mockReturnValue('/tmp/checkpoints'),
+          },
+        },
+      },
+    } as unknown as CommandContext;
+  });
+
+  it('returns checkpointing-disabled message when disabled', async () => {
+    (
+      context.agentContext.config.getCheckpointingEnabled as Mock
+    ).mockReturnValue(false);
+
+    const response = await listCommand.execute(context);
+
+    expect(response.data).toContain('Checkpointing is not enabled');
+  });
+
+  it('returns "No checkpoints found." when no .json checkpoints exist', async () => {
+    mockReaddir.mockResolvedValue(['not-a-checkpoint.txt']);
+
+    const response = await listCommand.execute(context);
+
+    expect(response.data).toBe('No checkpoints found.');
+  });
+
+  it('ignores error when mkdir fails', async () => {
+    vi.mocked(fs.mkdir).mockRejectedValue(new Error('mkdir fail'));
+    mockReaddir.mockResolvedValue([]);
+
+    const response = await listCommand.execute(context);
+
+    expect(response.data).toBe('No checkpoints found.');
+    expect(fs.mkdir).toHaveBeenCalled();
+  });
+
+  it('formats checkpoint summary output from checkpoint metadata', async () => {
+    mockReaddir.mockResolvedValue(['cp1.json', 'cp2.json']);
+    vi.mocked(getCheckpointInfoList).mockReturnValue([
+      { messageId: 'id1', checkpoint: 'cp1' },
+      { messageId: 'id2', checkpoint: 'cp2' },
+    ]);
+
+    const response = await listCommand.execute(context);
+
+    expect(response.data).toContain('Available Checkpoints:');
+    // Note: The current implementation of ListCheckpointsCommand incorrectly accesses
+    // fileName, toolName, etc. which don't exist on CheckpointInfo, resulting in 'Unknown'.
+    expect(response.data).toContain('- **Unknown**: Unknown (Status: Unknown)');
+  });
+
+  it('handles empty checkpoint info list', async () => {
+    mockReaddir.mockResolvedValue(['some.json']);
+    vi.mocked(getCheckpointInfoList).mockReturnValue([]);
+
+    const response = await listCommand.execute(context);
+
+    expect(response.data).toBe('Available Checkpoints:\n');
+  });
+
+  it('returns generic unexpected error message on failures', async () => {
+    mockReaddir.mockRejectedValue(new Error('Readdir fail'));
+
+    const response = await listCommand.execute(context);
+
+    expect(response.data).toBe(
+      'An unexpected error occurred while listing checkpoints.',
+    );
+  });
+});

packages/cli/src/acp/commands/restore.ts

@@ -0,0 +1,179 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  getCheckpointInfoList,
+  getToolCallDataSchema,
+  isNodeError,
+  performRestore,
+} from '@google/gemini-cli-core';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type {
+  Command,
+  CommandContext,
+  CommandExecutionResponse,
+} from './types.js';
+
+export class RestoreCommand implements Command {
+  readonly name = 'restore';
+  readonly description =
+    'Restore to a previous checkpoint, or list available checkpoints to restore. This will reset the conversation and file history to the state it was in when the checkpoint was created';
+  readonly requiresWorkspace = true;
+  readonly subCommands = [new ListCheckpointsCommand()];
+
+  async execute(
+    context: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse> {
+    const { agentContext: agentContext, git: gitService } = context;
+    const { config } = agentContext;
+    const argsStr = args.join(' ');
+
+    try {
+      if (!argsStr) {
+        return await new ListCheckpointsCommand().execute(context);
+      }
+
+      if (!config.getCheckpointingEnabled()) {
+        return {
+          name: this.name,
+          data: 'Checkpointing is not enabled. Please enable it in your settings (`general.checkpointing.enabled: true`) to use /restore.',
+        };
+      }
+
+      const selectedFile = argsStr.endsWith('.json')
+        ? argsStr
+        : `${argsStr}.json`;
+
+      const checkpointDir = config.storage.getProjectTempCheckpointsDir();
+      const filePath = path.join(checkpointDir, selectedFile);
+
+      let data: string;
+      try {
+        data = await fs.readFile(filePath, 'utf-8');
+      } catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+          return {
+            name: this.name,
+            data: `File not found: ${selectedFile}`,
+          };
+        }
+        throw error;
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const toolCallData = JSON.parse(data);
+      const ToolCallDataSchema = getToolCallDataSchema();
+      const parseResult = ToolCallDataSchema.safeParse(toolCallData);
+
+      if (!parseResult.success) {
+        return {
+          name: this.name,
+          data: 'Checkpoint file is invalid or corrupted.',
+        };
+      }
+
+      const restoreResultGenerator = performRestore(
+        parseResult.data,
+        gitService,
+      );
+
+      const restoreResult = [];
+      for await (const result of restoreResultGenerator) {
+        restoreResult.push(result);
+      }
+
+      // Format the result nicely since Zed just dumps data
+      const formattedResult = restoreResult
+        .map((r) => {
+          if (r.type === 'message') {
+            return `[${r.messageType.toUpperCase()}] ${r.content}`;
+          } else if (r.type === 'load_history') {
+            return `Loaded history with ${r.clientHistory.length} messages.`;
+          }
+          return `Restored: ${JSON.stringify(r)}`;
+        })
+        .join('\n');
+
+      return {
+        name: this.name,
+        data: formattedResult,
+      };
+    } catch (error) {
+      return {
+        name: this.name,
+        data: `An unexpected error occurred during restore: ${error}`,
+      };
+    }
+  }
+}
+
+export class ListCheckpointsCommand implements Command {
+  readonly name = 'restore list';
+  readonly description = 'Lists all available checkpoints.';
+
+  async execute(context: CommandContext): Promise<CommandExecutionResponse> {
+    const { config } = context.agentContext;
+
+    try {
+      if (!config.getCheckpointingEnabled()) {
+        return {
+          name: this.name,
+          data: 'Checkpointing is not enabled. Please enable it in your settings (`general.checkpointing.enabled: true`) to use /restore.',
+        };
+      }
+
+      const checkpointDir = config.storage.getProjectTempCheckpointsDir();
+      try {
+        await fs.mkdir(checkpointDir, { recursive: true });
+      } catch {
+        // Ignore
+      }
+
+      const files = await fs.readdir(checkpointDir);
+      const jsonFiles = files.filter((file) => file.endsWith('.json'));
+
+      if (jsonFiles.length === 0) {
+        return { name: this.name, data: 'No checkpoints found.' };
+      }
+
+      const checkpointFiles = new Map<string, string>();
+      for (const file of jsonFiles) {
+        const filePath = path.join(checkpointDir, file);
+        const data = await fs.readFile(filePath, 'utf-8');
+        checkpointFiles.set(file, data);
+      }
+
+      const checkpointInfoList = getCheckpointInfoList(checkpointFiles);
+
+      const formatted = checkpointInfoList
+        .map((info) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const i = info as Record<string, any>;
+          const fileName = String(i['fileName'] || 'Unknown');
+          const toolName = String(i['toolName'] || 'Unknown');
+          const status = String(i['status'] || 'Unknown');
+          const timestamp = new Date(
+            Number(i['timestamp']) || 0,
+          ).toLocaleString();
+
+          return `- **${fileName}**: ${toolName} (Status: ${status}) [${timestamp}]`;
+        })
+        .join('\n');
+
+      return {
+        name: this.name,
+        data: `Available Checkpoints:\n${formatted}`,
+      };
+    } catch {
+      return {
+        name: this.name,
+        data: 'An unexpected error occurred while listing checkpoints.',
+      };
+    }
+  }
+}

packages/cli/src/acp/commands/types.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { AgentLoopContext, GitService } from '@google/gemini-cli-core';
+import type { LoadedSettings } from '../../config/settings.js';
+
+export interface CommandContext {
+  agentContext: AgentLoopContext;
+  settings: LoadedSettings;
+  git?: GitService;
+  sendMessage: (text: string) => Promise<void>;
+}
+
+export interface CommandArgument {
+  readonly name: string;
+  readonly description: string;
+  readonly isRequired?: boolean;
+}
+
+export interface Command {
+  readonly name: string;
+  readonly aliases?: string[];
+  readonly description: string;
+  readonly arguments?: CommandArgument[];
+  readonly subCommands?: Command[];
+  readonly requiresWorkspace?: boolean;
+
+  execute(
+    context: CommandContext,
+    args: string[],
+  ): Promise<CommandExecutionResponse>;
+}
+
+export interface CommandExecutionResponse {
+  readonly name: string;
+  readonly data: unknown;
+}

packages/cli/src/commands/extensions.test.tsx

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { extensionsCommand } from './extensions.js';
+
+// Mock subcommands
+vi.mock('./extensions/install.js', () => ({
+  installCommand: { command: 'install' },
+}));
+vi.mock('./extensions/uninstall.js', () => ({
+  uninstallCommand: { command: 'uninstall' },
+}));
+vi.mock('./extensions/list.js', () => ({ listCommand: { command: 'list' } }));
+vi.mock('./extensions/update.js', () => ({
+  updateCommand: { command: 'update' },
+}));
+vi.mock('./extensions/disable.js', () => ({
+  disableCommand: { command: 'disable' },
+}));
+vi.mock('./extensions/enable.js', () => ({
+  enableCommand: { command: 'enable' },
+}));
+vi.mock('./extensions/link.js', () => ({ linkCommand: { command: 'link' } }));
+vi.mock('./extensions/new.js', () => ({ newCommand: { command: 'new' } }));
+vi.mock('./extensions/validate.js', () => ({
+  validateCommand: { command: 'validate' },
+}));
+
+// Mock gemini.js
+vi.mock('../gemini.js', () => ({
+  initializeOutputListenersAndFlush: vi.fn(),
+}));
+
+describe('extensionsCommand', () => {
+  it('should have correct command and aliases', () => {
+    expect(extensionsCommand.command).toBe('extensions <command>');
+    expect(extensionsCommand.aliases).toEqual(['extension']);
+    expect(extensionsCommand.describe).toBe('Manage Gemini CLI extensions.');
+  });
+
+  it('should register all subcommands in builder', () => {
+    const mockYargs = {
+      middleware: vi.fn().mockReturnThis(),
+      command: vi.fn().mockReturnThis(),
+      demandCommand: vi.fn().mockReturnThis(),
+      version: vi.fn().mockReturnThis(),
+    };
+
+    // @ts-expect-error - Mocking yargs
+    extensionsCommand.builder(mockYargs);
+
+    expect(mockYargs.middleware).toHaveBeenCalled();
+    expect(mockYargs.command).toHaveBeenCalledWith(
+      expect.objectContaining({ command: 'install' }),
+    );
+    expect(mockYargs.command).toHaveBeenCalledWith(
+      expect.objectContaining({ command: 'uninstall' }),
+    );
+    expect(mockYargs.command).toHaveBeenCalledWith(
+      expect.objectContaining({ command: 'list' }),
+    );
+    expect(mockYargs.command).toHaveBeenCalledWith(
+      expect.objectContaining({ command: 'update' }),
+    );
+    expect(mockYargs.command).toHaveBeenCalledWith(
+      expect.objectContaining({ command: 'disable' }),
+    );
+    expect(mockYargs.command).toHaveBeenCalledWith(
+      expect.objectContaining({ command: 'enable' }),
+    );
+    expect(mockYargs.command).toHaveBeenCalledWith(
+      expect.objectContaining({ command: 'link' }),
+    );
+    expect(mockYargs.command).toHaveBeenCalledWith(
+      expect.objectContaining({ command: 'new' }),
+    );
+    expect(mockYargs.command).toHaveBeenCalledWith(
+      expect.objectContaining({ command: 'validate' }),
+    );
+    expect(mockYargs.demandCommand).toHaveBeenCalledWith(1, expect.any(String));
+    expect(mockYargs.version).toHaveBeenCalledWith(false);
+  });
+
+  it('should have a handler that does nothing', () => {
+    // @ts-expect-error - Handler doesn't take arguments in this case
+    expect(extensionsCommand.handler()).toBeUndefined();
+  });
+});

packages/cli/src/commands/extensions.tsx

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { CommandModule } from 'yargs';
+import { installCommand } from './extensions/install.js';
+import { uninstallCommand } from './extensions/uninstall.js';
+import { listCommand } from './extensions/list.js';
+import { updateCommand } from './extensions/update.js';
+import { disableCommand } from './extensions/disable.js';
+import { enableCommand } from './extensions/enable.js';
+import { linkCommand } from './extensions/link.js';
+import { newCommand } from './extensions/new.js';
+import { validateCommand } from './extensions/validate.js';
+import { configureCommand } from './extensions/configure.js';
+import { initializeOutputListenersAndFlush } from '../gemini.js';
+import { defer } from '../deferred.js';
+
+export const extensionsCommand: CommandModule = {
+  command: 'extensions <command>',
+  aliases: ['extension'],
+  describe: 'Manage Gemini CLI extensions.',
+  builder: (yargs) =>
+    yargs
+      .middleware((argv) => {
+        initializeOutputListenersAndFlush();
+        argv['isCommand'] = true;
+      })
+      .command(defer(installCommand, 'extensions'))
+      .command(defer(uninstallCommand, 'extensions'))
+      .command(defer(listCommand, 'extensions'))
+      .command(defer(updateCommand, 'extensions'))
+      .command(defer(disableCommand, 'extensions'))
+      .command(defer(enableCommand, 'extensions'))
+      .command(defer(linkCommand, 'extensions'))
+      .command(defer(newCommand, 'extensions'))
+      .command(defer(validateCommand, 'extensions'))
+      .command(defer(configureCommand, 'extensions'))
+      .demandCommand(1, 'You need at least one command before continuing.')
+      .version(false),
+  handler: () => {
+    // This handler is not called when a subcommand is provided.
+    // Yargs will show the help menu.
+  },
+};

packages/cli/src/commands/extensions/configure.test.ts

@@ -0,0 +1,290 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type Mock,
+} from 'vitest';
+import { configureCommand } from './configure.js';
+import yargs from 'yargs';
+import { debugLogger } from '@google/gemini-cli-core';
+import {
+  updateSetting,
+  getScopedEnvContents,
+  type ExtensionSetting,
+} from '../../config/extensions/extensionSettings.js';
+import { cleanupTmpDir } from '@google/gemini-cli-test-utils';
+import prompts from 'prompts';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+const { mockExtensionManager, mockGetExtensionManager, mockLoadSettings } =
+  vi.hoisted(() => {
+    const extensionManager = {
+      loadExtensionConfig: vi.fn(),
+      getExtensions: vi.fn(),
+      loadExtensions: vi.fn(),
+      getSettings: vi.fn(),
+    };
+    return {
+      mockExtensionManager: extensionManager,
+      mockGetExtensionManager: vi.fn(),
+      mockLoadSettings: vi.fn().mockReturnValue({ merged: {} }),
+    };
+  });
+
+vi.mock('../../config/extension-manager.js', () => ({
+  ExtensionManager: vi.fn().mockImplementation(() => mockExtensionManager),
+}));
+
+vi.mock('../../config/extensions/extensionSettings.js', () => ({
+  updateSetting: vi.fn(),
+  promptForSetting: vi.fn(),
+  getScopedEnvContents: vi.fn(),
+  ExtensionSettingScope: {
+    USER: 'user',
+    WORKSPACE: 'workspace',
+  },
+}));
+
+vi.mock('../utils.js', () => ({
+  exitCli: vi.fn(),
+}));
+
+vi.mock('./utils.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('./utils.js')>();
+  return {
+    ...actual,
+    getExtensionManager: mockGetExtensionManager,
+  };
+});
+
+vi.mock('prompts');
+
+vi.mock('../../config/extensions/consent.js', () => ({
+  requestConsentNonInteractive: vi.fn(),
+}));
+
+import { ExtensionManager } from '../../config/extension-manager.js';
+
+vi.mock('../../config/settings.js', () => ({
+  loadSettings: mockLoadSettings,
+}));
+
+describe('extensions configure command', () => {
+  let tempWorkspaceDir: string;
+
+  beforeEach(() => {
+    vi.spyOn(debugLogger, 'log');
+    vi.spyOn(debugLogger, 'error');
+    vi.clearAllMocks();
+
+    tempWorkspaceDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'gemini-cli-test-workspace-'),
+    );
+    vi.spyOn(process, 'cwd').mockReturnValue(tempWorkspaceDir);
+    // Default behaviors
+    mockLoadSettings.mockReturnValue({ merged: {} });
+    mockGetExtensionManager.mockResolvedValue(mockExtensionManager);
+    (ExtensionManager as unknown as Mock).mockImplementation(
+      () => mockExtensionManager,
+    );
+  });
+
+  afterEach(async () => {
+    await cleanupTmpDir(tempWorkspaceDir);
+    vi.restoreAllMocks();
+  });
+
+  const runCommand = async (command: string) => {
+    const parser = yargs().command(configureCommand).help(false).version(false);
+    await parser.parse(command);
+  };
+
+  const setupExtension = (
+    name: string,
+    settings: Array<Partial<ExtensionSetting>> = [],
+    id = 'test-id',
+    path = '/test/path',
+  ) => {
+    const extension = { name, path, id };
+
+    mockExtensionManager.getExtensions.mockReturnValue([extension]);
+    mockExtensionManager.loadExtensionConfig.mockResolvedValue({
+      name,
+      settings,
+    });
+    return extension;
+  };
+
+  describe('Specific setting configuration', () => {
+    it('should configure a specific setting', async () => {
+      setupExtension('test-ext', [
+        { name: 'Test Setting', envVar: 'TEST_VAR' },
+      ]);
+      (updateSetting as Mock).mockResolvedValue(undefined);
+
+      await runCommand('config test-ext TEST_VAR');
+
+      expect(updateSetting).toHaveBeenCalledWith(
+        expect.objectContaining({ name: 'test-ext' }),
+        'test-id',
+        'TEST_VAR',
+        expect.any(Function),
+        'user',
+        tempWorkspaceDir,
+      );
+    });
+
+    it('should handle missing extension', async () => {
+      mockExtensionManager.getExtensions.mockReturnValue([]);
+
+      await runCommand('config missing-ext TEST_VAR');
+
+      expect(updateSetting).not.toHaveBeenCalled();
+    });
+
+    it('should reject invalid extension names', async () => {
+      await runCommand('config ../invalid TEST_VAR');
+      expect(debugLogger.error).toHaveBeenCalledWith(
+        expect.stringContaining('Invalid extension name'),
+      );
+
+      await runCommand('config ext/with/slash TEST_VAR');
+      expect(debugLogger.error).toHaveBeenCalledWith(
+        expect.stringContaining('Invalid extension name'),
+      );
+    });
+  });
+
+  describe('Extension configuration (all settings)', () => {
+    it('should configure all settings for an extension', async () => {
+      const settings = [{ name: 'Setting 1', envVar: 'VAR_1' }];
+      setupExtension('test-ext', settings);
+      (getScopedEnvContents as Mock).mockResolvedValue({});
+      (updateSetting as Mock).mockResolvedValue(undefined);
+
+      await runCommand('config test-ext');
+
+      expect(debugLogger.log).toHaveBeenCalledWith(
+        'Configuring settings for "test-ext"...',
+      );
+      expect(updateSetting).toHaveBeenCalledWith(
+        expect.objectContaining({ name: 'test-ext' }),
+        'test-id',
+        'VAR_1',
+        expect.any(Function),
+        'user',
+        tempWorkspaceDir,
+      );
+    });
+
+    it('should verify overwrite if setting is already set', async () => {
+      const settings = [{ name: 'Setting 1', envVar: 'VAR_1' }];
+      setupExtension('test-ext', settings);
+      (getScopedEnvContents as Mock).mockImplementation(
+        async (_config, _id, scope) => {
+          if (scope === 'user') return { VAR_1: 'existing' };
+          return {};
+        },
+      );
+      (prompts as unknown as Mock).mockResolvedValue({ confirm: true });
+      (updateSetting as Mock).mockResolvedValue(undefined);
+
+      await runCommand('config test-ext');
+
+      expect(prompts).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'confirm',
+          message: expect.stringContaining('is already set. Overwrite?'),
+        }),
+      );
+      expect(updateSetting).toHaveBeenCalled();
+    });
+
+    it('should note if setting is configured in workspace', async () => {
+      const settings = [{ name: 'Setting 1', envVar: 'VAR_1' }];
+      setupExtension('test-ext', settings);
+      (getScopedEnvContents as Mock).mockImplementation(
+        async (_config, _id, scope) => {
+          if (scope === 'workspace') return { VAR_1: 'workspace_value' };
+          return {};
+        },
+      );
+      (updateSetting as Mock).mockResolvedValue(undefined);
+
+      await runCommand('config test-ext');
+
+      expect(debugLogger.log).toHaveBeenCalledWith(
+        expect.stringContaining('is already configured in the workspace scope'),
+      );
+    });
+
+    it('should skip update if user denies overwrite', async () => {
+      const settings = [{ name: 'Setting 1', envVar: 'VAR_1' }];
+      setupExtension('test-ext', settings);
+      (getScopedEnvContents as Mock).mockResolvedValue({ VAR_1: 'existing' });
+      (prompts as unknown as Mock).mockResolvedValue({ confirm: false });
+
+      await runCommand('config test-ext');
+
+      expect(prompts).toHaveBeenCalled();
+      expect(updateSetting).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Configure all extensions', () => {
+    it('should configure settings for all installed extensions', async () => {
+      const ext1 = {
+        name: 'ext1',
+        path: '/p1',
+        id: 'id1',
+        settings: [{ envVar: 'V1' }],
+      };
+      const ext2 = {
+        name: 'ext2',
+        path: '/p2',
+        id: 'id2',
+        settings: [{ envVar: 'V2' }],
+      };
+      mockExtensionManager.getExtensions.mockReturnValue([ext1, ext2]);
+
+      mockExtensionManager.loadExtensionConfig.mockImplementation(
+        async (path) => {
+          if (path === '/p1')
+            return { name: 'ext1', settings: [{ name: 'S1', envVar: 'V1' }] };
+          if (path === '/p2')
+            return { name: 'ext2', settings: [{ name: 'S2', envVar: 'V2' }] };
+          return null;
+        },
+      );
+
+      (getScopedEnvContents as Mock).mockResolvedValue({});
+      (updateSetting as Mock).mockResolvedValue(undefined);
+
+      await runCommand('config');
+
+      expect(debugLogger.log).toHaveBeenCalledWith(
+        expect.stringContaining('Configuring settings for "ext1"'),
+      );
+      expect(debugLogger.log).toHaveBeenCalledWith(
+        expect.stringContaining('Configuring settings for "ext2"'),
+      );
+      expect(updateSetting).toHaveBeenCalledTimes(2);
+    });
+
+    it('should log if no extensions installed', async () => {
+      mockExtensionManager.getExtensions.mockReturnValue([]);
+      await runCommand('config');
+      expect(debugLogger.log).toHaveBeenCalledWith('No extensions installed.');
+    });
+  });
+});

packages/cli/src/commands/extensions/configure.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { CommandModule } from 'yargs';
+import type { ExtensionSettingScope } from '../../config/extensions/extensionSettings.js';
+import {
+  configureAllExtensions,
+  configureExtension,
+  configureSpecificSetting,
+  getExtensionManager,
+} from './utils.js';
+import { loadSettings } from '../../config/settings.js';
+import { coreEvents, debugLogger } from '@google/gemini-cli-core';
+import { exitCli } from '../utils.js';
+
+interface ConfigureArgs {
+  name?: string;
+  setting?: string;
+  scope: string;
+}
+
+export const configureCommand: CommandModule<object, ConfigureArgs> = {
+  command: 'config [name] [setting]',
+  describe: 'Configure extension settings.',
+  builder: (yargs) =>
+    yargs
+      .positional('name', {
+        describe: 'Name of the extension to configure.',
+        type: 'string',
+      })
+      .positional('setting', {
+        describe: 'The specific setting to configure (name or env var).',
+        type: 'string',
+      })
+      .option('scope', {
+        describe: 'The scope to set the setting in.',
+        type: 'string',
+        choices: ['user', 'workspace'],
+        default: 'user',
+      }),
+  handler: async (args) => {
+    const { name, setting, scope } = args;
+    const settings = loadSettings(process.cwd()).merged;
+
+    if (!(settings.experimental?.extensionConfig ?? true)) {
+      coreEvents.emitFeedback(
+        'error',
+        'Extension configuration is currently disabled. Enable it by setting "experimental.extensionConfig" to true.',
+      );
+      await exitCli();
+      return;
+    }
+
+    if (name) {
+      if (name.includes('/') || name.includes('\\') || name.includes('..')) {
+        debugLogger.error(
+          'Invalid extension name. Names cannot contain path separators or "..".',
+        );
+        return;
+      }
+    }
+
+    const extensionManager = await getExtensionManager();
+
+    // Case 1: Configure specific setting for an extension
+    if (name && setting) {
+      await configureSpecificSetting(
+        extensionManager,
+        name,
+        setting,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        scope as ExtensionSettingScope,
+      );
+    }
+    // Case 2: Configure all settings for an extension
+    else if (name) {
+      await configureExtension(
+        extensionManager,
+        name,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        scope as ExtensionSettingScope,
+      );
+    }
+    // Case 3: Configure all extensions
+    else {
+      await configureAllExtensions(
+        extensionManager,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        scope as ExtensionSettingScope,
+      );
+    }
+
+    await exitCli();
+  },
+};

packages/cli/src/commands/extensions/disable.test.ts

@@ -0,0 +1,250 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  vi,
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  type Mock,
+} from 'vitest';
+import { format } from 'node:util';
+import { type Argv } from 'yargs';
+import { handleDisable, disableCommand } from './disable.js';
+import { ExtensionManager } from '../../config/extension-manager.js';
+import {
+  loadSettings,
+  SettingScope,
+  type LoadedSettings,
+} from '../../config/settings.js';
+import { getErrorMessage } from '@google/gemini-cli-core';
+
+// Mock dependencies
+const emitConsoleLog = vi.hoisted(() => vi.fn());
+const debugLogger = vi.hoisted(() => ({
+  log: vi.fn((message, ...args) => {
+    emitConsoleLog('log', format(message, ...args));
+  }),
+  error: vi.fn((message, ...args) => {
+    emitConsoleLog('error', format(message, ...args));
+  }),
+}));
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    coreEvents: {
+      emitConsoleLog,
+    },
+    debugLogger,
+    getErrorMessage: vi.fn(),
+  };
+});
+
+vi.mock('../../config/extension-manager.js');
+vi.mock('../../config/settings.js');
+vi.mock('../../config/extensions/consent.js', () => ({
+  requestConsentNonInteractive: vi.fn(),
+}));
+vi.mock('../../config/extensions/extensionSettings.js', () => ({
+  promptForSetting: vi.fn(),
+}));
+vi.mock('../utils.js', () => ({
+  exitCli: vi.fn(),
+}));
+
+describe('extensions disable command', () => {
+  const mockLoadSettings = vi.mocked(loadSettings);
+  const mockGetErrorMessage = vi.mocked(getErrorMessage);
+  const mockExtensionManager = vi.mocked(ExtensionManager);
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockLoadSettings.mockReturnValue({
+      merged: {},
+    } as unknown as LoadedSettings);
+    mockExtensionManager.prototype.loadExtensions = vi
+      .fn()
+      .mockResolvedValue(undefined);
+    mockExtensionManager.prototype.disableExtension = vi
+      .fn()
+      .mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('handleDisable', () => {
+    it.each([
+      {
+        name: 'my-extension',
+        scope: undefined,
+        expectedScope: SettingScope.User,
+        expectedLog:
+          'Extension "my-extension" successfully disabled for scope "undefined".',
+      },
+      {
+        name: 'my-extension',
+        scope: 'user',
+        expectedScope: SettingScope.User,
+        expectedLog:
+          'Extension "my-extension" successfully disabled for scope "user".',
+      },
+      {
+        name: 'my-extension',
+        scope: 'workspace',
+        expectedScope: SettingScope.Workspace,
+        expectedLog:
+          'Extension "my-extension" successfully disabled for scope "workspace".',
+      },
+    ])(
+      'should disable an extension in the $expectedScope scope when scope is $scope',
+      async ({ name, scope, expectedScope, expectedLog }) => {
+        const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+        await handleDisable({ name, scope });
+        expect(mockExtensionManager).toHaveBeenCalledWith(
+          expect.objectContaining({
+            workspaceDir: '/test/dir',
+          }),
+        );
+        expect(
+          mockExtensionManager.prototype.loadExtensions,
+        ).toHaveBeenCalled();
+        expect(
+          mockExtensionManager.prototype.disableExtension,
+        ).toHaveBeenCalledWith(name, expectedScope);
+        expect(emitConsoleLog).toHaveBeenCalledWith('log', expectedLog);
+        mockCwd.mockRestore();
+      },
+    );
+
+    it('should log an error message and exit with code 1 when extension disabling fails', async () => {
+      const mockProcessExit = vi
+        .spyOn(process, 'exit')
+        .mockImplementation((() => {}) as (
+          code?: string | number | null | undefined,
+        ) => never);
+      const error = new Error('Disable failed');
+      (
+        mockExtensionManager.prototype.disableExtension as Mock
+      ).mockRejectedValue(error);
+      mockGetErrorMessage.mockReturnValue('Disable failed message');
+      await handleDisable({ name: 'my-extension' });
+      expect(emitConsoleLog).toHaveBeenCalledWith(
+        'error',
+        'Disable failed message',
+      );
+      expect(mockProcessExit).toHaveBeenCalledWith(1);
+      mockProcessExit.mockRestore();
+    });
+  });
+
+  describe('disableCommand', () => {
+    const command = disableCommand;
+
+    it('should have correct command and describe', () => {
+      expect(command.command).toBe('disable [--scope] <name>');
+      expect(command.describe).toBe('Disables an extension.');
+    });
+
+    describe('builder', () => {
+      interface MockYargs {
+        positional: Mock;
+        option: Mock;
+        check: Mock;
+      }
+
+      let yargsMock: MockYargs;
+
+      beforeEach(() => {
+        yargsMock = {
+          positional: vi.fn().mockReturnThis(),
+          option: vi.fn().mockReturnThis(),
+          check: vi.fn().mockReturnThis(),
+        };
+      });
+
+      it('should configure positional and option arguments', () => {
+        (command.builder as (yargs: Argv) => Argv)(
+          yargsMock as unknown as Argv,
+        );
+        expect(yargsMock.positional).toHaveBeenCalledWith('name', {
+          describe: 'The name of the extension to disable.',
+          type: 'string',
+        });
+        expect(yargsMock.option).toHaveBeenCalledWith('scope', {
+          describe: 'The scope to disable the extension in.',
+          type: 'string',
+          default: SettingScope.User,
+        });
+        expect(yargsMock.check).toHaveBeenCalled();
+      });
+
+      it('check function should throw for invalid scope', () => {
+        (command.builder as (yargs: Argv) => Argv)(
+          yargsMock as unknown as Argv,
+        );
+        const checkCallback = yargsMock.check.mock.calls[0][0];
+        const expectedError = `Invalid scope: invalid. Please use one of ${Object.values(
+          SettingScope,
+        )
+          .map((s) => s.toLowerCase())
+          .join(', ')}.`;
+        expect(() => checkCallback({ scope: 'invalid' })).toThrow(
+          expectedError,
+        );
+      });
+
+      it.each(['user', 'workspace', 'USER', 'WorkSpace'])(
+        'check function should return true for valid scope "%s"',
+        (scope) => {
+          (command.builder as (yargs: Argv) => Argv)(
+            yargsMock as unknown as Argv,
+          );
+          const checkCallback = yargsMock.check.mock.calls[0][0];
+          expect(checkCallback({ scope })).toBe(true);
+        },
+      );
+    });
+
+    it('handler should trigger extension disabling', async () => {
+      const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+      interface TestArgv {
+        name: string;
+        scope: string;
+        [key: string]: unknown;
+      }
+      const argv: TestArgv = {
+        name: 'test-ext',
+        scope: 'workspace',
+        _: [],
+        $0: '',
+      };
+      await (command.handler as unknown as (args: TestArgv) => Promise<void>)(
+        argv,
+      );
+      expect(mockExtensionManager).toHaveBeenCalledWith(
+        expect.objectContaining({
+          workspaceDir: '/test/dir',
+        }),
+      );
+      expect(mockExtensionManager.prototype.loadExtensions).toHaveBeenCalled();
+      expect(
+        mockExtensionManager.prototype.disableExtension,
+      ).toHaveBeenCalledWith('test-ext', SettingScope.Workspace);
+      expect(emitConsoleLog).toHaveBeenCalledWith(
+        'log',
+        'Extension "test-ext" successfully disabled for scope "workspace".',
+      );
+      mockCwd.mockRestore();
+    });
+  });
+});

packages/cli/src/commands/extensions/disable.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type CommandModule } from 'yargs';
+import { loadSettings, SettingScope } from '../../config/settings.js';
+import { debugLogger, getErrorMessage } from '@google/gemini-cli-core';
+import { ExtensionManager } from '../../config/extension-manager.js';
+import { requestConsentNonInteractive } from '../../config/extensions/consent.js';
+import { promptForSetting } from '../../config/extensions/extensionSettings.js';
+import { exitCli } from '../utils.js';
+
+interface DisableArgs {
+  name: string;
+  scope?: string;
+}
+
+export async function handleDisable(args: DisableArgs) {
+  const workspaceDir = process.cwd();
+  const extensionManager = new ExtensionManager({
+    workspaceDir,
+    requestConsent: requestConsentNonInteractive,
+    requestSetting: promptForSetting,
+    settings: loadSettings(workspaceDir).merged,
+  });
+  await extensionManager.loadExtensions();
+
+  try {
+    if (args.scope?.toLowerCase() === 'workspace') {
+      await extensionManager.disableExtension(
+        args.name,
+        SettingScope.Workspace,
+      );
+    } else {
+      await extensionManager.disableExtension(args.name, SettingScope.User);
+    }
+    debugLogger.log(
+      `Extension "${args.name}" successfully disabled for scope "${args.scope}".`,
+    );
+  } catch (error) {
+    debugLogger.error(getErrorMessage(error));
+    process.exit(1);
+  }
+}
+
+export const disableCommand: CommandModule = {
+  command: 'disable [--scope] <name>',
+  describe: 'Disables an extension.',
+  builder: (yargs) =>
+    yargs
+      .positional('name', {
+        describe: 'The name of the extension to disable.',
+        type: 'string',
+      })
+      .option('scope', {
+        describe: 'The scope to disable the extension in.',
+        type: 'string',
+        default: SettingScope.User,
+      })
+      .check((argv) => {
+        if (
+          argv.scope &&
+          !Object.values(SettingScope)
+            .map((s) => s.toLowerCase())
+            .includes(argv.scope.toLowerCase())
+        ) {
+          throw new Error(
+            `Invalid scope: ${argv.scope}. Please use one of ${Object.values(
+              SettingScope,
+            )
+              .map((s) => s.toLowerCase())
+              .join(', ')}.`,
+          );
+        }
+        return true;
+      }),
+  handler: async (argv) => {
+    await handleDisable({
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      name: argv['name'] as string,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      scope: argv['scope'] as string,
+    });
+    await exitCli();
+  },
+};

packages/cli/src/commands/extensions/enable.test.ts

@@ -0,0 +1,280 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  vi,
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  type Mock,
+} from 'vitest';
+import { format } from 'node:util';
+import { type Argv } from 'yargs';
+import { handleEnable, enableCommand } from './enable.js';
+import { ExtensionManager } from '../../config/extension-manager.js';
+import {
+  loadSettings,
+  SettingScope,
+  type LoadedSettings,
+} from '../../config/settings.js';
+import { FatalConfigError } from '@google/gemini-cli-core';
+
+// Mock dependencies
+const emitConsoleLog = vi.hoisted(() => vi.fn());
+const debugLogger = vi.hoisted(() => ({
+  log: vi.fn((message, ...args) => {
+    emitConsoleLog('log', format(message, ...args));
+  }),
+  error: vi.fn((message, ...args) => {
+    emitConsoleLog('error', format(message, ...args));
+  }),
+}));
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    coreEvents: {
+      emitConsoleLog,
+    },
+    debugLogger,
+    getErrorMessage: vi.fn((error: { message: string }) => error.message),
+    FatalConfigError: class extends Error {
+      constructor(message: string) {
+        super(message);
+        this.name = 'FatalConfigError';
+      }
+    },
+  };
+});
+
+vi.mock('../../config/extension-manager.js');
+vi.mock('../../config/settings.js');
+vi.mock('../../config/extensions/consent.js');
+vi.mock('../../config/extensions/extensionSettings.js');
+vi.mock('../utils.js', () => ({
+  exitCli: vi.fn(),
+}));
+
+const mockEnablementInstance = vi.hoisted(() => ({
+  getDisplayState: vi.fn(),
+  enable: vi.fn(),
+  clearSessionDisable: vi.fn(),
+  autoEnableServers: vi.fn(),
+}));
+vi.mock('../../config/mcp/mcpServerEnablement.js', () => ({
+  McpServerEnablementManager: {
+    getInstance: () => mockEnablementInstance,
+  },
+}));
+
+describe('extensions enable command', () => {
+  const mockLoadSettings = vi.mocked(loadSettings);
+  const mockExtensionManager = vi.mocked(ExtensionManager);
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockLoadSettings.mockReturnValue({
+      merged: {},
+    } as unknown as LoadedSettings);
+    mockExtensionManager.prototype.loadExtensions = vi
+      .fn()
+      .mockResolvedValue(undefined);
+    mockExtensionManager.prototype.enableExtension = vi.fn();
+    mockExtensionManager.prototype.getExtensions = vi.fn().mockReturnValue([]);
+    mockEnablementInstance.getDisplayState.mockReset();
+    mockEnablementInstance.enable.mockReset();
+    mockEnablementInstance.clearSessionDisable.mockReset();
+    mockEnablementInstance.autoEnableServers.mockReset();
+    mockEnablementInstance.autoEnableServers.mockResolvedValue([]);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('handleEnable', () => {
+    it.each([
+      {
+        name: 'my-extension',
+        scope: undefined,
+        expectedScope: SettingScope.User,
+        expectedLog:
+          'Extension "my-extension" successfully enabled in all scopes.',
+      },
+      {
+        name: 'my-extension',
+        scope: 'workspace',
+        expectedScope: SettingScope.Workspace,
+        expectedLog:
+          'Extension "my-extension" successfully enabled for scope "workspace".',
+      },
+    ])(
+      'should enable an extension in the $expectedScope scope when scope is $scope',
+      async ({ name, scope, expectedScope, expectedLog }) => {
+        const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+        await handleEnable({ name, scope });
+
+        expect(mockExtensionManager).toHaveBeenCalledWith(
+          expect.objectContaining({
+            workspaceDir: '/test/dir',
+          }),
+        );
+        expect(
+          mockExtensionManager.prototype.loadExtensions,
+        ).toHaveBeenCalled();
+        expect(
+          mockExtensionManager.prototype.enableExtension,
+        ).toHaveBeenCalledWith(name, expectedScope);
+        expect(emitConsoleLog).toHaveBeenCalledWith('log', expectedLog);
+        mockCwd.mockRestore();
+      },
+    );
+
+    it('should throw FatalConfigError when extension enabling fails', async () => {
+      const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+      const error = new Error('Enable failed');
+      (
+        mockExtensionManager.prototype.enableExtension as Mock
+      ).mockImplementation(() => {
+        throw error;
+      });
+
+      const promise = handleEnable({ name: 'my-extension' });
+      await expect(promise).rejects.toThrow(FatalConfigError);
+      await expect(promise).rejects.toThrow('Enable failed');
+
+      mockCwd.mockRestore();
+    });
+
+    it('should auto-enable disabled MCP servers for the extension', async () => {
+      const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+      mockEnablementInstance.autoEnableServers.mockResolvedValue([
+        'test-server',
+      ]);
+      mockExtensionManager.prototype.getExtensions = vi
+        .fn()
+        .mockReturnValue([
+          { name: 'my-extension', mcpServers: { 'test-server': {} } },
+        ]);
+
+      await handleEnable({ name: 'my-extension' });
+
+      expect(mockEnablementInstance.autoEnableServers).toHaveBeenCalledWith([
+        'test-server',
+      ]);
+      expect(emitConsoleLog).toHaveBeenCalledWith(
+        'log',
+        expect.stringContaining("MCP server 'test-server' was disabled"),
+      );
+      mockCwd.mockRestore();
+    });
+
+    it('should not log when MCP servers are already enabled', async () => {
+      const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+      mockEnablementInstance.autoEnableServers.mockResolvedValue([]);
+      mockExtensionManager.prototype.getExtensions = vi
+        .fn()
+        .mockReturnValue([
+          { name: 'my-extension', mcpServers: { 'test-server': {} } },
+        ]);
+
+      await handleEnable({ name: 'my-extension' });
+
+      expect(mockEnablementInstance.autoEnableServers).toHaveBeenCalledWith([
+        'test-server',
+      ]);
+      expect(emitConsoleLog).not.toHaveBeenCalledWith(
+        'log',
+        expect.stringContaining("MCP server 'test-server' was disabled"),
+      );
+      mockCwd.mockRestore();
+    });
+  });
+
+  describe('enableCommand', () => {
+    const command = enableCommand;
+
+    it('should have correct command and describe', () => {
+      expect(command.command).toBe('enable [--scope] <name>');
+      expect(command.describe).toBe('Enables an extension.');
+    });
+
+    describe('builder', () => {
+      interface MockYargs {
+        positional: Mock;
+        option: Mock;
+        check: Mock;
+      }
+
+      let yargsMock: MockYargs;
+      beforeEach(() => {
+        yargsMock = {
+          positional: vi.fn().mockReturnThis(),
+          option: vi.fn().mockReturnThis(),
+          check: vi.fn().mockReturnThis(),
+        };
+      });
+
+      it('should configure positional and option arguments', () => {
+        (command.builder as (yargs: Argv) => Argv)(
+          yargsMock as unknown as Argv,
+        );
+        expect(yargsMock.positional).toHaveBeenCalledWith('name', {
+          describe: 'The name of the extension to enable.',
+          type: 'string',
+        });
+        expect(yargsMock.option).toHaveBeenCalledWith('scope', {
+          describe:
+            'The scope to enable the extension in. If not set, will be enabled in all scopes.',
+          type: 'string',
+        });
+        expect(yargsMock.check).toHaveBeenCalled();
+      });
+
+      it('check function should throw for invalid scope', () => {
+        (command.builder as (yargs: Argv) => Argv)(
+          yargsMock as unknown as Argv,
+        );
+        const checkCallback = yargsMock.check.mock.calls[0][0];
+        const expectedError = `Invalid scope: invalid. Please use one of ${Object.values(
+          SettingScope,
+        )
+          .map((s) => s.toLowerCase())
+          .join(', ')}.`;
+        expect(() => checkCallback({ scope: 'invalid' })).toThrow(
+          expectedError,
+        );
+      });
+    });
+
+    it('handler should call handleEnable', async () => {
+      const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+      interface TestArgv {
+        name: string;
+        scope: string;
+        [key: string]: unknown;
+      }
+      const argv: TestArgv = {
+        name: 'test-ext',
+        scope: 'workspace',
+        _: [],
+        $0: '',
+      };
+      await (command.handler as unknown as (args: TestArgv) => Promise<void>)(
+        argv,
+      );
+
+      expect(
+        mockExtensionManager.prototype.enableExtension,
+      ).toHaveBeenCalledWith('test-ext', SettingScope.Workspace);
+      mockCwd.mockRestore();
+    });
+  });
+});

packages/cli/src/commands/extensions/enable.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type CommandModule } from 'yargs';
+import { loadSettings, SettingScope } from '../../config/settings.js';
+import { requestConsentNonInteractive } from '../../config/extensions/consent.js';
+import { ExtensionManager } from '../../config/extension-manager.js';
+import {
+  debugLogger,
+  FatalConfigError,
+  getErrorMessage,
+} from '@google/gemini-cli-core';
+import { promptForSetting } from '../../config/extensions/extensionSettings.js';
+import { exitCli } from '../utils.js';
+import { McpServerEnablementManager } from '../../config/mcp/mcpServerEnablement.js';
+
+interface EnableArgs {
+  name: string;
+  scope?: string;
+}
+
+export async function handleEnable(args: EnableArgs) {
+  const workingDir = process.cwd();
+  const extensionManager = new ExtensionManager({
+    workspaceDir: workingDir,
+    requestConsent: requestConsentNonInteractive,
+    requestSetting: promptForSetting,
+    settings: loadSettings(workingDir).merged,
+  });
+  await extensionManager.loadExtensions();
+
+  try {
+    if (args.scope?.toLowerCase() === 'workspace') {
+      await extensionManager.enableExtension(args.name, SettingScope.Workspace);
+    } else {
+      await extensionManager.enableExtension(args.name, SettingScope.User);
+    }
+
+    // Auto-enable any disabled MCP servers for this extension
+    const extension = extensionManager
+      .getExtensions()
+      .find((e) => e.name === args.name);
+
+    if (extension?.mcpServers) {
+      const mcpEnablementManager = McpServerEnablementManager.getInstance();
+      const enabledServers = await mcpEnablementManager.autoEnableServers(
+        Object.keys(extension.mcpServers ?? {}),
+      );
+
+      for (const serverName of enabledServers) {
+        debugLogger.log(
+          `MCP server '${serverName}' was disabled - now enabled.`,
+        );
+      }
+      // Note: No restartServer() - CLI exits immediately, servers load on next session
+    }
+
+    if (args.scope) {
+      debugLogger.log(
+        `Extension "${args.name}" successfully enabled for scope "${args.scope}".`,
+      );
+    } else {
+      debugLogger.log(
+        `Extension "${args.name}" successfully enabled in all scopes.`,
+      );
+    }
+  } catch (error) {
+    throw new FatalConfigError(getErrorMessage(error));
+  }
+}
+
+export const enableCommand: CommandModule = {
+  command: 'enable [--scope] <name>',
+  describe: 'Enables an extension.',
+  builder: (yargs) =>
+    yargs
+      .positional('name', {
+        describe: 'The name of the extension to enable.',
+        type: 'string',
+      })
+      .option('scope', {
+        describe:
+          'The scope to enable the extension in. If not set, will be enabled in all scopes.',
+        type: 'string',
+      })
+      .check((argv) => {
+        if (
+          argv.scope &&
+          !Object.values(SettingScope)
+            .map((s) => s.toLowerCase())
+            .includes(argv.scope.toLowerCase())
+        ) {
+          throw new Error(
+            `Invalid scope: ${argv.scope}. Please use one of ${Object.values(
+              SettingScope,
+            )
+              .map((s) => s.toLowerCase())
+              .join(', ')}.`,
+          );
+        }
+        return true;
+      }),
+  handler: async (argv) => {
+    await handleEnable({
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      name: argv['name'] as string,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      scope: argv['scope'] as string,
+    });
+    await exitCli();
+  },
+};

packages/cli/src/commands/extensions/examples/exclude-tools/.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/exclude-tools/gemini-extension.json

@@ -0,0 +1,5 @@
+{
+  "name": "excludeTools",
+  "version": "1.0.0",
+  "excludeTools": ["run_shell_command(rm -rf)"]
+}

packages/cli/src/commands/extensions/examples/mcp-server/.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/mcp-server/README.md

@@ -0,0 +1,35 @@
+# MCP Server Example
+
+This is a basic example of an MCP (Model Context Protocol) server used as a
+Gemini CLI extension. It demonstrates how to expose tools and prompts to the
+Gemini CLI.
+
+## Description
+
+The contents of this directory are a valid MCP server implementation using the
+`@modelcontextprotocol/sdk`. It exposes:
+
+- A tool `fetch_posts` that mock-fetches posts.
+- A prompt `poem-writer`.
+
+## Structure
+
+- `example.js`: The main server entry point.
+- `gemini-extension.json`: The configuration file that tells Gemini CLI how to
+  use this extension.
+- `package.json`: Helper for dependencies.
+
+## How to Use
+
+1.  Navigate to this directory:
+
+    ```bash
+    cd packages/cli/src/commands/extensions/examples/mcp-server
+    ```
+
+2.  Install dependencies:
+    ```bash
+    npm install
+    ```
+
+This example is typically used by `gemini extensions new`.

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

@@ -0,0 +1,11 @@
+{
+  "name": "mcp-server-example",
+  "version": "1.0.0",
+  "mcpServers": {
+    "nodeServer": {
+      "command": "node",
+      "args": ["${extensionPath}${/}example.js"],
+      "cwd": "${extensionPath}"
+    }
+  }
+}

packages/cli/src/commands/extensions/install.test.ts

@@ -0,0 +1,464 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type MockInstance,
+} from 'vitest';
+import { handleInstall, installCommand } from './install.js';
+import yargs from 'yargs';
+import * as core from '@google/gemini-cli-core';
+import type { Stats } from 'node:fs';
+import * as path from 'node:path';
+import { promptForSetting } from '../../config/extensions/extensionSettings.js';
+
+const {
+  mockInstallOrUpdateExtension,
+  mockLoadExtensions,
+  mockExtensionManager,
+  mockRequestConsentNonInteractive,
+  mockPromptForConsentNonInteractive,
+  mockStat,
+  mockInferInstallMetadata,
+  mockIsWorkspaceTrusted,
+  mockLoadTrustedFolders,
+  mockDiscover,
+} = vi.hoisted(() => {
+  const mockLoadExtensions = vi.fn();
+  const mockInstallOrUpdateExtension = vi.fn();
+  const mockExtensionManager = vi.fn().mockImplementation(() => ({
+    loadExtensions: mockLoadExtensions,
+    installOrUpdateExtension: mockInstallOrUpdateExtension,
+  }));
+
+  return {
+    mockLoadExtensions,
+    mockInstallOrUpdateExtension,
+    mockExtensionManager,
+    mockRequestConsentNonInteractive: vi.fn(),
+    mockPromptForConsentNonInteractive: vi.fn(),
+    mockStat: vi.fn(),
+    mockInferInstallMetadata: vi.fn(),
+    mockIsWorkspaceTrusted: vi.fn(),
+    mockLoadTrustedFolders: vi.fn(),
+    mockDiscover: vi.fn(),
+  };
+});
+
+vi.mock('../../config/extensions/consent.js', () => ({
+  requestConsentNonInteractive: mockRequestConsentNonInteractive,
+  promptForConsentNonInteractive: mockPromptForConsentNonInteractive,
+  INSTALL_WARNING_MESSAGE: 'warning',
+}));
+
+vi.mock('../../config/trustedFolders.js', () => ({
+  isWorkspaceTrusted: mockIsWorkspaceTrusted,
+  loadTrustedFolders: mockLoadTrustedFolders,
+  TrustLevel: {
+    TRUST_FOLDER: 'TRUST_FOLDER',
+  },
+}));
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    FolderTrustDiscoveryService: {
+      discover: mockDiscover,
+    },
+  };
+});
+
+vi.mock('../../config/extension-manager.js', async (importOriginal) => ({
+  ...(await importOriginal<
+    typeof import('../../config/extension-manager.js')
+  >()),
+  ExtensionManager: mockExtensionManager,
+  inferInstallMetadata: mockInferInstallMetadata,
+}));
+
+vi.mock('../../utils/errors.js', () => ({
+  getErrorMessage: vi.fn((error: Error) => error.message),
+}));
+
+vi.mock('node:fs/promises', () => ({
+  stat: mockStat,
+  default: {
+    stat: mockStat,
+  },
+}));
+
+vi.mock('../utils.js', () => ({
+  exitCli: vi.fn(),
+}));
+
+describe('extensions install command', () => {
+  it('should fail if no source is provided', () => {
+    const validationParser = yargs([])
+      .locale('en')
+      .command(installCommand)
+      .fail(false);
+    expect(() => validationParser.parse('install')).toThrow(
+      'Not enough non-option arguments: got 0, need at least 1',
+    );
+  });
+});
+
+describe('handleInstall', () => {
+  let debugLogSpy: MockInstance;
+  let debugErrorSpy: MockInstance;
+  let processSpy: MockInstance;
+
+  beforeEach(() => {
+    debugLogSpy = vi
+      .spyOn(core.debugLogger, 'log')
+      .mockImplementation(() => {});
+    debugErrorSpy = vi
+      .spyOn(core.debugLogger, 'error')
+      .mockImplementation(() => {});
+    processSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never);
+
+    mockLoadExtensions.mockResolvedValue([]);
+    mockInstallOrUpdateExtension.mockReset();
+
+    mockIsWorkspaceTrusted.mockReturnValue({ isTrusted: true, source: 'file' });
+    mockDiscover.mockResolvedValue({
+      commands: [],
+      mcps: [],
+      hooks: [],
+      skills: [],
+      agents: [],
+      settings: [],
+      securityWarnings: [],
+      discoveryErrors: [],
+    });
+
+    mockInferInstallMetadata.mockImplementation(async (source, args) => {
+      if (
+        source.startsWith('http://') ||
+        source.startsWith('https://') ||
+        source.startsWith('git@') ||
+        source.startsWith('sso://')
+      ) {
+        return {
+          source,
+          type: 'git',
+          ref: args?.ref,
+          autoUpdate: args?.autoUpdate,
+          allowPreRelease: args?.allowPreRelease,
+        };
+      }
+      return { source, type: 'local' };
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  function createMockExtension(
+    overrides: Partial<core.GeminiCLIExtension> = {},
+  ): core.GeminiCLIExtension {
+    return {
+      name: 'mock-extension',
+      version: '1.0.0',
+      isActive: true,
+      path: '/mock/path',
+      contextFiles: [],
+      id: 'mock-id',
+      ...overrides,
+    };
+  }
+
+  it('should install an extension from a http source', async () => {
+    mockInstallOrUpdateExtension.mockResolvedValue(
+      createMockExtension({
+        name: 'http-extension',
+      }),
+    );
+
+    await handleInstall({
+      source: 'http://google.com',
+    });
+
+    expect(debugLogSpy).toHaveBeenCalledWith(
+      'Extension "http-extension" installed successfully and enabled.',
+    );
+  });
+
+  it('should install an extension from a https source', async () => {
+    mockInstallOrUpdateExtension.mockResolvedValue(
+      createMockExtension({
+        name: 'https-extension',
+      }),
+    );
+
+    await handleInstall({
+      source: 'https://google.com',
+    });
+
+    expect(debugLogSpy).toHaveBeenCalledWith(
+      'Extension "https-extension" installed successfully and enabled.',
+    );
+  });
+
+  it('should install an extension from a git source', async () => {
+    mockInstallOrUpdateExtension.mockResolvedValue(
+      createMockExtension({
+        name: 'git-extension',
+      }),
+    );
+
+    await handleInstall({
+      source: 'git@some-url',
+    });
+
+    expect(debugLogSpy).toHaveBeenCalledWith(
+      'Extension "git-extension" installed successfully and enabled.',
+    );
+  });
+
+  it('throws an error from an unknown source', async () => {
+    mockInferInstallMetadata.mockRejectedValue(
+      new Error('Install source not found.'),
+    );
+    await handleInstall({
+      source: 'test://google.com',
+    });
+
+    expect(debugErrorSpy).toHaveBeenCalledWith('Install source not found.');
+    expect(processSpy).toHaveBeenCalledWith(1);
+  });
+
+  it('should install an extension from a sso source', async () => {
+    mockInstallOrUpdateExtension.mockResolvedValue(
+      createMockExtension({
+        name: 'sso-extension',
+      }),
+    );
+
+    await handleInstall({
+      source: 'sso://google.com',
+    });
+
+    expect(debugLogSpy).toHaveBeenCalledWith(
+      'Extension "sso-extension" installed successfully and enabled.',
+    );
+  });
+
+  it('should install an extension from a local path', async () => {
+    mockInstallOrUpdateExtension.mockResolvedValue(
+      createMockExtension({
+        name: 'local-extension',
+      }),
+    );
+    mockStat.mockResolvedValue({} as Stats);
+    await handleInstall({
+      source: path.join('/', 'some', 'path'),
+    });
+
+    expect(debugLogSpy).toHaveBeenCalledWith(
+      'Extension "local-extension" installed successfully and enabled.',
+    );
+  });
+
+  it('should throw an error if install extension fails', async () => {
+    mockInstallOrUpdateExtension.mockRejectedValue(
+      new Error('Install extension failed'),
+    );
+
+    await handleInstall({ source: 'git@some-url' });
+
+    expect(debugErrorSpy).toHaveBeenCalledWith('Install extension failed');
+    expect(processSpy).toHaveBeenCalledWith(1);
+  });
+
+  it('should pass promptForSetting when skipSettings is not provided', async () => {
+    mockInstallOrUpdateExtension.mockResolvedValue({
+      name: 'test-extension',
+    } as unknown as core.GeminiCLIExtension);
+
+    await handleInstall({
+      source: 'http://google.com',
+    });
+
+    expect(mockExtensionManager).toHaveBeenCalledWith(
+      expect.objectContaining({
+        requestSetting: promptForSetting,
+      }),
+    );
+  });
+
+  it('should pass null for requestSetting when skipSettings is true', async () => {
+    mockInstallOrUpdateExtension.mockResolvedValue({
+      name: 'test-extension',
+    } as unknown as core.GeminiCLIExtension);
+
+    await handleInstall({
+      source: 'http://google.com',
+      skipSettings: true,
+    });
+
+    expect(mockExtensionManager).toHaveBeenCalledWith(
+      expect.objectContaining({
+        requestSetting: null,
+      }),
+    );
+  });
+
+  it('should proceed if local path is already trusted', async () => {
+    mockInstallOrUpdateExtension.mockResolvedValue(
+      createMockExtension({
+        name: 'local-extension',
+      }),
+    );
+    mockStat.mockResolvedValue({} as Stats);
+    mockIsWorkspaceTrusted.mockReturnValue({ isTrusted: true, source: 'file' });
+
+    await handleInstall({
+      source: path.join('/', 'some', 'path'),
+    });
+
+    expect(mockIsWorkspaceTrusted).toHaveBeenCalled();
+    expect(mockPromptForConsentNonInteractive).not.toHaveBeenCalled();
+    expect(debugLogSpy).toHaveBeenCalledWith(
+      'Extension "local-extension" installed successfully and enabled.',
+    );
+  });
+
+  it('should prompt and proceed if user accepts trust', async () => {
+    mockInstallOrUpdateExtension.mockResolvedValue(
+      createMockExtension({
+        name: 'local-extension',
+      }),
+    );
+    mockStat.mockResolvedValue({} as Stats);
+    mockIsWorkspaceTrusted.mockReturnValue({
+      isTrusted: undefined,
+      source: undefined,
+    });
+    mockPromptForConsentNonInteractive.mockResolvedValue(true);
+    const mockSetValue = vi.fn();
+    mockLoadTrustedFolders.mockReturnValue({
+      setValue: mockSetValue,
+      user: { path: '', config: {} },
+      errors: [],
+      rules: [],
+      isPathTrusted: vi.fn(),
+    });
+
+    await handleInstall({
+      source: path.join('/', 'untrusted', 'path'),
+    });
+
+    expect(mockIsWorkspaceTrusted).toHaveBeenCalled();
+    expect(mockPromptForConsentNonInteractive).toHaveBeenCalled();
+    expect(mockSetValue).toHaveBeenCalledWith(
+      expect.stringContaining(path.join('untrusted', 'path')),
+      'TRUST_FOLDER',
+    );
+    expect(debugLogSpy).toHaveBeenCalledWith(
+      'Extension "local-extension" installed successfully and enabled.',
+    );
+  });
+
+  it('should prompt and abort if user denies trust', async () => {
+    mockStat.mockResolvedValue({} as Stats);
+    mockIsWorkspaceTrusted.mockReturnValue({
+      isTrusted: undefined,
+      source: undefined,
+    });
+    mockPromptForConsentNonInteractive.mockResolvedValue(false);
+
+    await handleInstall({
+      source: path.join('/', 'evil', 'path'),
+    });
+
+    expect(mockIsWorkspaceTrusted).toHaveBeenCalled();
+    expect(mockPromptForConsentNonInteractive).toHaveBeenCalled();
+    expect(debugErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Installation aborted: Folder'),
+    );
+    expect(processSpy).toHaveBeenCalledWith(1);
+  });
+
+  it('should include discovery results in trust prompt', async () => {
+    mockInstallOrUpdateExtension.mockResolvedValue(
+      createMockExtension({
+        name: 'local-extension',
+      }),
+    );
+    mockStat.mockResolvedValue({} as Stats);
+    mockIsWorkspaceTrusted.mockReturnValue({
+      isTrusted: undefined,
+      source: undefined,
+    });
+    mockDiscover.mockResolvedValue({
+      commands: ['custom-cmd'],
+      mcps: [],
+      hooks: [],
+      skills: ['cool-skill'],
+      agents: ['cool-agent'],
+      settings: [],
+      securityWarnings: ['Security risk!'],
+      discoveryErrors: ['Read error'],
+    });
+    mockPromptForConsentNonInteractive.mockResolvedValue(true);
+    mockLoadTrustedFolders.mockReturnValue({
+      setValue: vi.fn(),
+      user: { path: '', config: {} },
+      errors: [],
+      rules: [],
+      isPathTrusted: vi.fn(),
+    });
+
+    await handleInstall({
+      source: '/untrusted/path',
+    });
+
+    expect(mockPromptForConsentNonInteractive).toHaveBeenCalledWith(
+      expect.stringContaining('This folder contains:'),
+      false,
+    );
+    expect(mockPromptForConsentNonInteractive).toHaveBeenCalledWith(
+      expect.stringContaining('custom-cmd'),
+      false,
+    );
+    expect(mockPromptForConsentNonInteractive).toHaveBeenCalledWith(
+      expect.stringContaining('cool-skill'),
+      false,
+    );
+    expect(mockPromptForConsentNonInteractive).toHaveBeenCalledWith(
+      expect.stringContaining('cool-agent'),
+      false,
+    );
+    expect(mockPromptForConsentNonInteractive).toHaveBeenCalledWith(
+      expect.stringContaining('Security Warnings:'),
+      false,
+    );
+    expect(mockPromptForConsentNonInteractive).toHaveBeenCalledWith(
+      expect.stringContaining('Security risk!'),
+      false,
+    );
+    expect(mockPromptForConsentNonInteractive).toHaveBeenCalledWith(
+      expect.stringContaining('Discovery Errors:'),
+      false,
+    );
+    expect(mockPromptForConsentNonInteractive).toHaveBeenCalledWith(
+      expect.stringContaining('Read error'),
+      false,
+    );
+  });
+});
+// Implementation completed.

packages/cli/src/commands/extensions/install.ts

@@ -0,0 +1,228 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { CommandModule } from 'yargs';
+import * as path from 'node:path';
+import chalk from 'chalk';
+import {
+  debugLogger,
+  FolderTrustDiscoveryService,
+  getRealPath,
+  getErrorMessage,
+} from '@google/gemini-cli-core';
+import {
+  INSTALL_WARNING_MESSAGE,
+  promptForConsentNonInteractive,
+  requestConsentNonInteractive,
+} from '../../config/extensions/consent.js';
+import {
+  ExtensionManager,
+  inferInstallMetadata,
+} from '../../config/extension-manager.js';
+import { loadSettings } from '../../config/settings.js';
+import {
+  isWorkspaceTrusted,
+  loadTrustedFolders,
+  TrustLevel,
+} from '../../config/trustedFolders.js';
+import { promptForSetting } from '../../config/extensions/extensionSettings.js';
+import { exitCli } from '../utils.js';
+
+interface InstallArgs {
+  source: string;
+  ref?: string;
+  autoUpdate?: boolean;
+  allowPreRelease?: boolean;
+  consent?: boolean;
+  skipSettings?: boolean;
+}
+
+export async function handleInstall(args: InstallArgs) {
+  try {
+    const { source } = args;
+    const installMetadata = await inferInstallMetadata(source, {
+      ref: args.ref,
+      autoUpdate: args.autoUpdate,
+      allowPreRelease: args.allowPreRelease,
+    });
+
+    const workspaceDir = process.cwd();
+    const settings = loadSettings(workspaceDir).merged;
+
+    if (installMetadata.type === 'local' || installMetadata.type === 'link') {
+      const absolutePath = path.resolve(source);
+      const realPath = getRealPath(absolutePath);
+      installMetadata.source = absolutePath;
+      const trustResult = isWorkspaceTrusted(settings, absolutePath);
+      if (trustResult.isTrusted !== true) {
+        const discoveryResults =
+          await FolderTrustDiscoveryService.discover(realPath);
+
+        const hasDiscovery =
+          discoveryResults.commands.length > 0 ||
+          discoveryResults.mcps.length > 0 ||
+          discoveryResults.hooks.length > 0 ||
+          discoveryResults.skills.length > 0 ||
+          discoveryResults.settings.length > 0;
+
+        const promptLines = [
+          '',
+          chalk.bold('Do you trust the files in this folder?'),
+          '',
+          `The extension source at "${absolutePath}" is not trusted.`,
+          '',
+          'Trusting a folder allows Gemini CLI to load its local configurations,',
+          'including custom commands, hooks, MCP servers, agent skills, and',
+          'settings. These configurations could execute code on your behalf or',
+          'change the behavior of the CLI.',
+          '',
+        ];
+
+        if (discoveryResults.discoveryErrors.length > 0) {
+          promptLines.push(chalk.red('❌ Discovery Errors:'));
+          for (const error of discoveryResults.discoveryErrors) {
+            promptLines.push(chalk.red(`  • ${error}`));
+          }
+          promptLines.push('');
+        }
+
+        if (discoveryResults.securityWarnings.length > 0) {
+          promptLines.push(chalk.yellow('⚠️  Security Warnings:'));
+          for (const warning of discoveryResults.securityWarnings) {
+            promptLines.push(chalk.yellow(`  • ${warning}`));
+          }
+          promptLines.push('');
+        }
+
+        if (hasDiscovery) {
+          promptLines.push(chalk.bold('This folder contains:'));
+          const groups = [
+            { label: 'Commands', items: discoveryResults.commands ?? [] },
+            { label: 'MCP Servers', items: discoveryResults.mcps ?? [] },
+            { label: 'Hooks', items: discoveryResults.hooks ?? [] },
+            { label: 'Skills', items: discoveryResults.skills ?? [] },
+            { label: 'Agents', items: discoveryResults.agents ?? [] },
+            {
+              label: 'Setting overrides',
+              items: discoveryResults.settings ?? [],
+            },
+          ].filter((g) => g.items.length > 0);
+
+          for (const group of groups) {
+            promptLines.push(
+              `  • ${chalk.bold(group.label)} (${group.items.length}):`,
+            );
+            for (const item of group.items) {
+              promptLines.push(`    - ${item}`);
+            }
+          }
+          promptLines.push('');
+        }
+
+        promptLines.push(
+          chalk.yellow(
+            'Do you want to trust this folder and continue with the installation? [y/N]: ',
+          ),
+        );
+
+        const confirmed = await promptForConsentNonInteractive(
+          promptLines.join('\n'),
+          false,
+        );
+        if (confirmed) {
+          const trustedFolders = loadTrustedFolders();
+          await trustedFolders.setValue(realPath, TrustLevel.TRUST_FOLDER);
+        } else {
+          throw new Error(
+            `Installation aborted: Folder "${absolutePath}" is not trusted.`,
+          );
+        }
+      }
+    }
+
+    const requestConsent = args.consent
+      ? () => Promise.resolve(true)
+      : requestConsentNonInteractive;
+    if (args.consent) {
+      debugLogger.log('You have consented to the following:');
+      debugLogger.log(INSTALL_WARNING_MESSAGE);
+    }
+
+    const extensionManager = new ExtensionManager({
+      workspaceDir,
+      requestConsent,
+      requestSetting: args.skipSettings ? null : promptForSetting,
+      settings,
+    });
+    await extensionManager.loadExtensions();
+    const extension =
+      await extensionManager.installOrUpdateExtension(installMetadata);
+    debugLogger.log(
+      `Extension "${extension.name}" installed successfully and enabled.`,
+    );
+  } catch (error) {
+    debugLogger.error(getErrorMessage(error));
+    process.exit(1);
+  }
+}
+
+export const installCommand: CommandModule = {
+  command: 'install <source> [--auto-update] [--pre-release]',
+  describe: 'Installs an extension from a git repository URL or a local path.',
+  builder: (yargs) =>
+    yargs
+      .positional('source', {
+        describe: 'The github URL or local path of the extension to install.',
+        type: 'string',
+        demandOption: true,
+      })
+      .option('ref', {
+        describe: 'The git ref to install from.',
+        type: 'string',
+      })
+      .option('auto-update', {
+        describe: 'Enable auto-update for this extension.',
+        type: 'boolean',
+      })
+      .option('pre-release', {
+        describe: 'Enable pre-release versions for this extension.',
+        type: 'boolean',
+      })
+      .option('consent', {
+        describe:
+          'Acknowledge the security risks of installing an extension and skip the confirmation prompt.',
+        type: 'boolean',
+        default: false,
+      })
+      .option('skip-settings', {
+        describe: 'Skip the configuration on install process.',
+        type: 'boolean',
+        default: false,
+      })
+      .check((argv) => {
+        if (!argv.source) {
+          throw new Error('The source argument must be provided.');
+        }
+        return true;
+      }),
+  handler: async (argv) => {
+    await handleInstall({
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      source: argv['source'] as string,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      ref: argv['ref'] as string | undefined,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      autoUpdate: argv['auto-update'] as boolean | undefined,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      allowPreRelease: argv['pre-release'] as boolean | undefined,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      consent: argv['consent'] as boolean | undefined,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      skipSettings: argv['skip-settings'] as boolean | undefined,
+    });
+    await exitCli();
+  },
+};

packages/cli/src/commands/extensions/link.test.ts

@@ -0,0 +1,181 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  vi,
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  type Mock,
+} from 'vitest';
+import { coreEvents, getErrorMessage } from '@google/gemini-cli-core';
+import { type Argv } from 'yargs';
+import { handleLink, linkCommand } from './link.js';
+import { ExtensionManager } from '../../config/extension-manager.js';
+import { loadSettings, type LoadedSettings } from '../../config/settings.js';
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const { mockCoreDebugLogger } = await import(
+    '../../test-utils/mockDebugLogger.js'
+  );
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  const mocked = mockCoreDebugLogger(actual, { stripAnsi: true });
+  return { ...mocked, getErrorMessage: vi.fn() };
+});
+
+vi.mock('../../config/extension-manager.js');
+vi.mock('../../config/settings.js');
+vi.mock('../../config/extensions/consent.js', () => ({
+  requestConsentNonInteractive: vi.fn(),
+}));
+vi.mock('../../config/extensions/extensionSettings.js', () => ({
+  promptForSetting: vi.fn(),
+}));
+vi.mock('../utils.js', () => ({
+  exitCli: vi.fn(),
+}));
+
+describe('extensions link command', () => {
+  const mockLoadSettings = vi.mocked(loadSettings);
+  const mockGetErrorMessage = vi.mocked(getErrorMessage);
+  const mockExtensionManager = vi.mocked(ExtensionManager);
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockLoadSettings.mockReturnValue({
+      merged: {},
+    } as unknown as LoadedSettings);
+    mockExtensionManager.prototype.loadExtensions = vi
+      .fn()
+      .mockResolvedValue(undefined);
+    mockExtensionManager.prototype.installOrUpdateExtension = vi
+      .fn()
+      .mockResolvedValue({ name: 'my-linked-extension' });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('handleLink', () => {
+    it('should link an extension from a local path', async () => {
+      const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+      await handleLink({ path: '/local/path/to/extension' });
+
+      expect(mockExtensionManager).toHaveBeenCalledWith(
+        expect.objectContaining({
+          workspaceDir: '/test/dir',
+        }),
+      );
+      expect(mockExtensionManager.prototype.loadExtensions).toHaveBeenCalled();
+      expect(
+        mockExtensionManager.prototype.installOrUpdateExtension,
+      ).toHaveBeenCalledWith({
+        source: '/local/path/to/extension',
+        type: 'link',
+      });
+      expect(coreEvents.emitConsoleLog).toHaveBeenCalledWith(
+        'log',
+        'Extension "my-linked-extension" linked successfully and enabled.',
+      );
+      mockCwd.mockRestore();
+    });
+
+    it('should log an error message and exit with code 1 when linking fails', async () => {
+      const mockProcessExit = vi
+        .spyOn(process, 'exit')
+        .mockImplementation((() => {}) as (
+          code?: string | number | null | undefined,
+        ) => never);
+      const error = new Error('Link failed');
+      (
+        mockExtensionManager.prototype.installOrUpdateExtension as Mock
+      ).mockRejectedValue(error);
+      mockGetErrorMessage.mockReturnValue('Link failed message');
+
+      await handleLink({ path: '/local/path/to/extension' });
+
+      expect(coreEvents.emitConsoleLog).toHaveBeenCalledWith(
+        'error',
+        'Link failed message',
+      );
+      expect(mockProcessExit).toHaveBeenCalledWith(1);
+      mockProcessExit.mockRestore();
+    });
+  });
+
+  describe('linkCommand', () => {
+    const command = linkCommand;
+
+    it('should have correct command and describe', () => {
+      expect(command.command).toBe('link <path>');
+      expect(command.describe).toBe(
+        'Links an extension from a local path. Updates made to the local path will always be reflected.',
+      );
+    });
+
+    describe('builder', () => {
+      interface MockYargs {
+        positional: Mock;
+        option: Mock;
+        check: Mock;
+      }
+
+      let yargsMock: MockYargs;
+      beforeEach(() => {
+        yargsMock = {
+          positional: vi.fn().mockReturnThis(),
+          option: vi.fn().mockReturnThis(),
+          check: vi.fn().mockReturnThis(),
+        };
+      });
+
+      it('should configure positional argument', () => {
+        (command.builder as (yargs: Argv) => Argv)(
+          yargsMock as unknown as Argv,
+        );
+        expect(yargsMock.positional).toHaveBeenCalledWith('path', {
+          describe: 'The name of the extension to link.',
+          type: 'string',
+        });
+        expect(yargsMock.option).toHaveBeenCalledWith('consent', {
+          describe:
+            'Acknowledge the security risks of installing an extension and skip the confirmation prompt.',
+          type: 'boolean',
+          default: false,
+        });
+        expect(yargsMock.check).toHaveBeenCalled();
+      });
+    });
+
+    it('handler should call handleLink', async () => {
+      const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+      interface TestArgv {
+        path: string;
+        [key: string]: unknown;
+      }
+      const argv: TestArgv = {
+        path: '/local/path/to/extension',
+        _: [],
+        $0: '',
+      };
+      await (command.handler as unknown as (args: TestArgv) => Promise<void>)(
+        argv,
+      );
+
+      expect(
+        mockExtensionManager.prototype.installOrUpdateExtension,
+      ).toHaveBeenCalledWith({
+        source: '/local/path/to/extension',
+        type: 'link',
+      });
+      mockCwd.mockRestore();
+    });
+  });
+});

packages/cli/src/commands/extensions/link.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { CommandModule } from 'yargs';
+import chalk from 'chalk';
+import {
+  debugLogger,
+  getErrorMessage,
+  type ExtensionInstallMetadata,
+} from '@google/gemini-cli-core';
+
+import {
+  INSTALL_WARNING_MESSAGE,
+  requestConsentNonInteractive,
+} from '../../config/extensions/consent.js';
+import { ExtensionManager } from '../../config/extension-manager.js';
+import { loadSettings } from '../../config/settings.js';
+import { promptForSetting } from '../../config/extensions/extensionSettings.js';
+import { exitCli } from '../utils.js';
+
+interface InstallArgs {
+  path: string;
+  consent?: boolean;
+}
+
+export async function handleLink(args: InstallArgs) {
+  try {
+    const installMetadata: ExtensionInstallMetadata = {
+      source: args.path,
+      type: 'link',
+    };
+    const requestConsent = args.consent
+      ? () => Promise.resolve(true)
+      : requestConsentNonInteractive;
+    if (args.consent) {
+      debugLogger.log('You have consented to the following:');
+      debugLogger.log(INSTALL_WARNING_MESSAGE);
+    }
+    const workspaceDir = process.cwd();
+    const extensionManager = new ExtensionManager({
+      workspaceDir,
+      requestConsent,
+      requestSetting: promptForSetting,
+      settings: loadSettings(workspaceDir).merged,
+    });
+    await extensionManager.loadExtensions();
+    const extension =
+      await extensionManager.installOrUpdateExtension(installMetadata);
+    debugLogger.log(
+      chalk.green(
+        `Extension "${extension.name}" linked successfully and enabled.`,
+      ),
+    );
+  } catch (error) {
+    debugLogger.error(getErrorMessage(error));
+    process.exit(1);
+  }
+}
+
+export const linkCommand: CommandModule = {
+  command: 'link <path>',
+  describe:
+    'Links an extension from a local path. Updates made to the local path will always be reflected.',
+  builder: (yargs) =>
+    yargs
+      .positional('path', {
+        describe: 'The name of the extension to link.',
+        type: 'string',
+      })
+      .option('consent', {
+        describe:
+          'Acknowledge the security risks of installing an extension and skip the confirmation prompt.',
+        type: 'boolean',
+        default: false,
+      })
+      .check((_) => true),
+  handler: async (argv) => {
+    await handleLink({
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      path: argv['path'] as string,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      consent: argv['consent'] as boolean | undefined,
+    });
+    await exitCli();
+  },
+};

packages/cli/src/commands/extensions/list.test.ts

@@ -0,0 +1,179 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { coreEvents, getErrorMessage } from '@google/gemini-cli-core';
+import { handleList, listCommand } from './list.js';
+import { ExtensionManager } from '../../config/extension-manager.js';
+import { loadSettings, type LoadedSettings } from '../../config/settings.js';
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const { mockCoreDebugLogger } = await import(
+    '../../test-utils/mockDebugLogger.js'
+  );
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  const mocked = mockCoreDebugLogger(actual, { stripAnsi: false });
+  return { ...mocked, getErrorMessage: vi.fn() };
+});
+
+vi.mock('../../config/extension-manager.js');
+vi.mock('../../config/settings.js');
+vi.mock('../../config/extensions/consent.js', () => ({
+  requestConsentNonInteractive: vi.fn(),
+}));
+vi.mock('../../config/extensions/extensionSettings.js', () => ({
+  promptForSetting: vi.fn(),
+}));
+vi.mock('../utils.js', () => ({
+  exitCli: vi.fn(),
+}));
+
+describe('extensions list command', () => {
+  const mockLoadSettings = vi.mocked(loadSettings);
+  const mockGetErrorMessage = vi.mocked(getErrorMessage);
+  const mockExtensionManager = vi.mocked(ExtensionManager);
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockLoadSettings.mockReturnValue({
+      merged: {},
+    } as unknown as LoadedSettings);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('handleList', () => {
+    it('should log a message if no extensions are installed', async () => {
+      const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+      mockExtensionManager.prototype.loadExtensions = vi
+        .fn()
+        .mockResolvedValue([]);
+      await handleList();
+
+      expect(coreEvents.emitConsoleLog).toHaveBeenCalledWith(
+        'log',
+        'No extensions installed.',
+      );
+      mockCwd.mockRestore();
+    });
+
+    it('should output empty JSON array if no extensions are installed and output-format is json', async () => {
+      const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+      mockExtensionManager.prototype.loadExtensions = vi
+        .fn()
+        .mockResolvedValue([]);
+      await handleList({ outputFormat: 'json' });
+
+      expect(coreEvents.emitConsoleLog).toHaveBeenCalledWith('log', '[]');
+      mockCwd.mockRestore();
+    });
+
+    it('should list all installed extensions', async () => {
+      const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+      const extensions = [
+        { name: 'ext1', version: '1.0.0' },
+        { name: 'ext2', version: '2.0.0' },
+      ];
+      mockExtensionManager.prototype.loadExtensions = vi
+        .fn()
+        .mockResolvedValue(extensions);
+      mockExtensionManager.prototype.toOutputString = vi.fn(
+        (ext) => `${ext.name}@${ext.version}`,
+      );
+      await handleList();
+
+      expect(coreEvents.emitConsoleLog).toHaveBeenCalledWith(
+        'log',
+        'ext1@1.0.0\n\next2@2.0.0',
+      );
+      mockCwd.mockRestore();
+    });
+
+    it('should list all installed extensions in JSON format', async () => {
+      const mockCwd = vi.spyOn(process, 'cwd').mockReturnValue('/test/dir');
+      const extensions = [
+        { name: 'ext1', version: '1.0.0' },
+        { name: 'ext2', version: '2.0.0' },
+      ];
+      mockExtensionManager.prototype.loadExtensions = vi
+        .fn()
+        .mockResolvedValue(extensions);
+      await handleList({ outputFormat: 'json' });
+
+      expect(coreEvents.emitConsoleLog).toHaveBeenCalledWith(
+        'log',
+        JSON.stringify(extensions, null, 2),
+      );
+      mockCwd.mockRestore();
+    });
+
+    it('should log an error message and exit with code 1 when listing fails', async () => {
+      const mockProcessExit = vi
+        .spyOn(process, 'exit')
+        .mockImplementation((() => {}) as (
+          code?: string | number | null | undefined,
+        ) => never);
+      const error = new Error('List failed');
+      mockExtensionManager.prototype.loadExtensions = vi
+        .fn()
+        .mockRejectedValue(error);
+      mockGetErrorMessage.mockReturnValue('List failed message');
+
+      await handleList();
+
+      expect(coreEvents.emitConsoleLog).toHaveBeenCalledWith(
+        'error',
+        'List failed message',
+      );
+      expect(mockProcessExit).toHaveBeenCalledWith(1);
+      mockProcessExit.mockRestore();
+    });
+  });
+
+  describe('listCommand', () => {
+    const command = listCommand;
+
+    it('should have correct command and describe', () => {
+      expect(command.command).toBe('list');
+      expect(command.describe).toBe('Lists installed extensions.');
+    });
+
+    it('builder should have output-format option', () => {
+      const mockYargs = {
+        option: vi.fn().mockReturnThis(),
+      };
+      (
+        command.builder as unknown as (
+          yargs: typeof mockYargs,
+        ) => typeof mockYargs
+      )(mockYargs);
+      expect(mockYargs.option).toHaveBeenCalledWith('output-format', {
+        alias: 'o',
+        type: 'string',
+        describe: 'The format of the CLI output.',
+        choices: ['text', 'json'],
+        default: 'text',
+      });
+    });
+
+    it('handler should call handleList with parsed arguments', async () => {
+      mockExtensionManager.prototype.loadExtensions = vi
+        .fn()
+        .mockResolvedValue([]);
+      await (
+        command.handler as unknown as (args: {
+          'output-format': string;
+        }) => Promise<void>
+      )({
+        'output-format': 'json',
+      });
+      expect(mockExtensionManager.prototype.loadExtensions).toHaveBeenCalled();
+    });
+  });
+});

packages/cli/src/commands/extensions/list.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { CommandModule } from 'yargs';
+import { debugLogger, getErrorMessage } from '@google/gemini-cli-core';
+import { ExtensionManager } from '../../config/extension-manager.js';
+import { requestConsentNonInteractive } from '../../config/extensions/consent.js';
+import { loadSettings } from '../../config/settings.js';
+import { promptForSetting } from '../../config/extensions/extensionSettings.js';
+import { exitCli } from '../utils.js';
+
+export async function handleList(options?: { outputFormat?: 'text' | 'json' }) {
+  try {
+    const workspaceDir = process.cwd();
+    const extensionManager = new ExtensionManager({
+      workspaceDir,
+      requestConsent: requestConsentNonInteractive,
+      requestSetting: promptForSetting,
+      settings: loadSettings(workspaceDir).merged,
+    });
+    const extensions = await extensionManager.loadExtensions();
+    if (extensions.length === 0) {
+      if (options?.outputFormat === 'json') {
+        debugLogger.log('[]');
+      } else {
+        debugLogger.log('No extensions installed.');
+      }
+      return;
+    }
+
+    if (options?.outputFormat === 'json') {
+      debugLogger.log(JSON.stringify(extensions, null, 2));
+    } else {
+      debugLogger.log(
+        extensions
+          .map((extension, _): string =>
+            extensionManager.toOutputString(extension),
+          )
+          .join('\n\n'),
+      );
+    }
+  } catch (error) {
+    debugLogger.error(getErrorMessage(error));
+    process.exit(1);
+  }
+}
+
+export const listCommand: CommandModule = {
+  command: 'list',
+  describe: 'Lists installed extensions.',
+  builder: (yargs) =>
+    yargs.option('output-format', {
+      alias: 'o',
+      type: 'string',
+      describe: 'The format of the CLI output.',
+      choices: ['text', 'json'],
+      default: 'text',
+    }),
+  handler: async (argv) => {
+    await handleList({
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      outputFormat: argv['output-format'] as 'text' | 'json',
+    });
+    await exitCli();
+  },
+};

packages/cli/src/commands/extensions/new.test.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { newCommand } from './new.js';
+import yargs from 'yargs';
+import * as fsPromises from 'node:fs/promises';
+import path from 'node:path';
+
+vi.mock('node:fs/promises');
+vi.mock('../utils.js', () => ({
+  exitCli: vi.fn(),
+}));
+
+const mockedFs = vi.mocked(fsPromises);
+
+describe('extensions new command', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+
+    const fakeFiles = [
+      { name: 'context', isDirectory: () => true },
+      { name: 'custom-commands', isDirectory: () => true },
+      { name: 'mcp-server', isDirectory: () => true },
+    ];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    mockedFs.readdir.mockResolvedValue(fakeFiles as any);
+  });
+
+  it('should fail if no path is provided', async () => {
+    const parser = yargs([]).command(newCommand).fail(false).locale('en');
+    await expect(parser.parseAsync('new')).rejects.toThrow(
+      'Not enough non-option arguments: got 0, need at least 1',
+    );
+  });
+
+  it('should create directory when no template is provided', async () => {
+    mockedFs.access.mockRejectedValue(new Error('ENOENT'));
+    mockedFs.mkdir.mockResolvedValue(undefined);
+
+    const parser = yargs([]).command(newCommand).fail(false);
+
+    await parser.parseAsync('new /some/path');
+
+    expect(mockedFs.mkdir).toHaveBeenCalledWith('/some/path', {
+      recursive: true,
+    });
+    expect(mockedFs.cp).not.toHaveBeenCalled();
+  });
+
+  it('should create directory and copy files when path does not exist', async () => {
+    mockedFs.access.mockRejectedValue(new Error('ENOENT'));
+    mockedFs.mkdir.mockResolvedValue(undefined);
+    mockedFs.cp.mockResolvedValue(undefined);
+
+    const parser = yargs([]).command(newCommand).fail(false);
+
+    await parser.parseAsync('new /some/path context');
+
+    expect(mockedFs.mkdir).toHaveBeenCalledWith('/some/path', {
+      recursive: true,
+    });
+    expect(mockedFs.cp).toHaveBeenCalledWith(
+      expect.stringContaining(path.normalize('context/context')),
+      path.normalize('/some/path/context'),
+      { recursive: true },
+    );
+    expect(mockedFs.cp).toHaveBeenCalledWith(
+      expect.stringContaining(path.normalize('context/custom-commands')),
+      path.normalize('/some/path/custom-commands'),
+      { recursive: true },
+    );
+    expect(mockedFs.cp).toHaveBeenCalledWith(
+      expect.stringContaining(path.normalize('context/mcp-server')),
+      path.normalize('/some/path/mcp-server'),
+      { recursive: true },
+    );
+  });
+
+  it('should throw an error if the path already exists', async () => {
+    mockedFs.access.mockResolvedValue(undefined);
+    const parser = yargs([]).command(newCommand).fail(false);
+
+    await expect(parser.parseAsync('new /some/path context')).rejects.toThrow(
+      'Path already exists: /some/path',
+    );
+
+    expect(mockedFs.mkdir).not.toHaveBeenCalled();
+    expect(mockedFs.cp).not.toHaveBeenCalled();
+  });
+});

packages/cli/src/commands/extensions/new.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { access, cp, mkdir, readdir, writeFile } from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import type { CommandModule } from 'yargs';
+import { fileURLToPath } from 'node:url';
+import { debugLogger } from '@google/gemini-cli-core';
+import { exitCli } from '../utils.js';
+
+interface NewArgs {
+  path: string;
+  template?: string;
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const EXAMPLES_PATH = join(__dirname, 'examples');
+
+async function pathExists(path: string) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function createDirectory(path: string) {
+  if (await pathExists(path)) {
+    throw new Error(`Path already exists: ${path}`);
+  }
+  await mkdir(path, { recursive: true });
+}
+
+async function copyDirectory(template: string, path: string) {
+  await createDirectory(path);
+
+  const examplePath = join(EXAMPLES_PATH, template);
+  const entries = await readdir(examplePath, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(examplePath, entry.name);
+    const destPath = join(path, entry.name);
+    await cp(srcPath, destPath, { recursive: true });
+  }
+}
+
+async function handleNew(args: NewArgs) {
+  if (args.template) {
+    await copyDirectory(args.template, args.path);
+    debugLogger.log(
+      `Successfully created new extension from template "${args.template}" at ${args.path}.`,
+    );
+  } else {
+    await createDirectory(args.path);
+    const extensionName = basename(args.path);
+    const manifest = {
+      name: extensionName,
+      version: '1.0.0',
+    };
+    await writeFile(
+      join(args.path, 'gemini-extension.json'),
+      JSON.stringify(manifest, null, 2),
+    );
+    debugLogger.log(`Successfully created new extension at ${args.path}.`);
+  }
+  debugLogger.log(
+    `You can install this using "gemini extensions link ${args.path}" to test it out.`,
+  );
+}
+
+async function getBoilerplateChoices() {
+  const entries = await readdir(EXAMPLES_PATH, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+}
+
+export const newCommand: CommandModule = {
+  command: 'new <path> [template]',
+  describe: 'Create a new extension from a boilerplate example.',
+  builder: async (yargs) => {
+    const choices = await getBoilerplateChoices();
+    return yargs
+      .positional('path', {
+        describe: 'The path to create the extension in.',
+        type: 'string',
+      })
+      .positional('template', {
+        describe: 'The boilerplate template to use.',
+        type: 'string',
+        choices,
+      });
+  },
+  handler: async (args) => {
+    await handleNew({
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      path: args['path'] as string,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      template: args['template'] as string | undefined,
+    });
+    await exitCli();
+  },
+};