Merge tag 'v0.3.0' into chore/sync-gemini-cli-v0.3.0

2025-12-20 16:57:46 +00:00 · 2025-09-10 21:01:40 +08:00
parent 03eb1faf0a 76553622f6
commit 14ea33063f
583 changed files with 30160 additions and 10770 deletions
--- a/packages/cli/src/config/config.integration.test.ts
+++ b/packages/cli/src/config/config.integration.test.ts
@@ -5,14 +5,14 @@
 */

 import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
-import * as fs from 'fs';
-import * as path from 'path';
-import { tmpdir } from 'os';
-import {
-  Config,
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { tmpdir } from 'node:os';
+import type {
  ConfigParameters,
  ContentGeneratorConfig,
 } from '@qwen-code/qwen-code-core';
+import { Config } from '@qwen-code/qwen-code-core';
 import { http, HttpResponse } from 'msw';
 import { setupServer } from 'msw/node';

@@ -282,7 +282,7 @@ describe('Configuration Integration Tests', () => {
          'test',
        ];

-        const argv = await parseArguments();
+        const argv = await parseArguments({} as Settings);

        // Verify that the argument was parsed correctly
        expect(argv.approvalMode).toBe('auto_edit');
@@ -306,7 +306,7 @@ describe('Configuration Integration Tests', () => {
          'test',
        ];

-        const argv = await parseArguments();
+        const argv = await parseArguments({} as Settings);

        expect(argv.approvalMode).toBe('yolo');
        expect(argv.prompt).toBe('test');
@@ -329,7 +329,7 @@ describe('Configuration Integration Tests', () => {
          'test',
        ];

-        const argv = await parseArguments();
+        const argv = await parseArguments({} as Settings);

        expect(argv.approvalMode).toBe('default');
        expect(argv.prompt).toBe('test');
@@ -345,7 +345,7 @@ describe('Configuration Integration Tests', () => {
      try {
        process.argv = ['node', 'script.js', '--yolo', '-p', 'test'];

-        const argv = await parseArguments();
+        const argv = await parseArguments({} as Settings);

        expect(argv.yolo).toBe(true);
        expect(argv.approvalMode).toBeUndefined(); // Should NOT be set when using --yolo
@@ -362,7 +362,7 @@ describe('Configuration Integration Tests', () => {
        process.argv = ['node', 'script.js', '--approval-mode', 'invalid_mode'];

        // Should throw during argument parsing due to yargs validation
-        await expect(parseArguments()).rejects.toThrow();
+        await expect(parseArguments({} as Settings)).rejects.toThrow();
      } finally {
        process.argv = originalArgv;
      }
@@ -381,7 +381,7 @@ describe('Configuration Integration Tests', () => {
        ];

        // Should throw during argument parsing due to conflict validation
-        await expect(parseArguments()).rejects.toThrow();
+        await expect(parseArguments({} as Settings)).rejects.toThrow();
      } finally {
        process.argv = originalArgv;
      }
@@ -394,7 +394,7 @@ describe('Configuration Integration Tests', () => {
        // Test that no approval mode arguments defaults to no flags set
        process.argv = ['node', 'script.js', '-p', 'test'];

-        const argv = await parseArguments();
+        const argv = await parseArguments({} as Settings);

        expect(argv.approvalMode).toBeUndefined();
        expect(argv.yolo).toBe(false);
--- a/packages/cli/src/config/config.test.ts
+++ b/packages/cli/src/config/config.test.ts
--- a/packages/cli/src/config/config.ts
+++ b/packages/cli/src/config/config.ts
@@ -4,37 +4,41 @@
 * SPDX-License-Identifier: Apache-2.0
 */

-import * as fs from 'fs';
-import * as path from 'path';
-import { homedir } from 'node:os';
-import yargs from 'yargs/yargs';
-import { hideBin } from 'yargs/helpers';
-import process from 'node:process';
-import { mcpCommand } from '../commands/mcp.js';
+import type {
+  ConfigParameters,
+  FileFilteringOptions,
+  MCPServerConfig,
+  TelemetryTarget,
+} from '@qwen-code/qwen-code-core';
 import {
+  ApprovalMode,
  Config,
+  DEFAULT_GEMINI_EMBEDDING_MODEL,
+  DEFAULT_GEMINI_MODEL,
+  DEFAULT_MEMORY_FILE_FILTERING_OPTIONS,
+  EditTool,
+  FileDiscoveryService,
+  getCurrentGeminiMdFilename,
  loadServerHierarchicalMemory,
  setGeminiMdFilename as setServerGeminiMdFilename,
-  getCurrentGeminiMdFilename,
-  ApprovalMode,
-  DEFAULT_GEMINI_MODEL,
-  DEFAULT_GEMINI_EMBEDDING_MODEL,
-  DEFAULT_MEMORY_FILE_FILTERING_OPTIONS,
-  FileDiscoveryService,
-  TelemetryTarget,
-  FileFilteringOptions,
  ShellTool,
-  EditTool,
  WriteFileTool,
-  MCPServerConfig,
-  ConfigParameters,
 } from '@qwen-code/qwen-code-core';
-import { Settings } from './settings.js';
+import * as fs from 'node:fs';
+import { homedir } from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+import { hideBin } from 'yargs/helpers';
+import yargs from 'yargs/yargs';
+import { extensionsCommand } from '../commands/extensions.js';
+import { mcpCommand } from '../commands/mcp.js';
+import type { Settings } from './settings.js';

-import { Extension, annotateActiveExtensions } from './extension.js';
-import { getCliVersion } from '../utils/version.js';
-import { loadSandboxConfig } from './sandboxConfig.js';
 import { resolvePath } from '../utils/resolvePath.js';
+import { getCliVersion } from '../utils/version.js';
+import type { Extension } from './extension.js';
+import { annotateActiveExtensions } from './extension.js';
+import { loadSandboxConfig } from './sandboxConfig.js';

 import { isWorkspaceTrusted } from './trustedFolders.js';

@@ -56,9 +60,7 @@ export interface CliArgs {
  prompt: string | undefined;
  promptInteractive: string | undefined;
  allFiles: boolean | undefined;
-  all_files: boolean | undefined;
  showMemoryUsage: boolean | undefined;
-  show_memory_usage: boolean | undefined;
  yolo: boolean | undefined;
  approvalMode: string | undefined;
  telemetry: boolean | undefined;
@@ -69,6 +71,7 @@ export interface CliArgs {
  telemetryLogPrompts: boolean | undefined;
  telemetryOutfile: string | undefined;
  allowedMcpServerNames: string[] | undefined;
+  allowedTools: string[] | undefined;
  experimentalAcp: boolean | undefined;
  extensions: string[] | undefined;
  listExtensions: boolean | undefined;
@@ -78,9 +81,10 @@ export interface CliArgs {
  proxy: string | undefined;
  includeDirectories: string[] | undefined;
  tavilyApiKey: string | undefined;
+  screenReader: boolean | undefined;
 }

-export async function parseArguments(): Promise<CliArgs> {
+export async function parseArguments(settings: Settings): Promise<CliArgs> {
  const yargsInstance = yargs(hideBin(process.argv))
    // Set locale to English for consistent output, especially in tests
    .locale('en')
@@ -128,29 +132,11 @@ export async function parseArguments(): Promise<CliArgs> {
          description: 'Include ALL files in context?',
          default: false,
        })
-        .option('all_files', {
-          type: 'boolean',
-          description: 'Include ALL files in context?',
-          default: false,
-        })
-        .deprecateOption(
-          'all_files',
-          'Use --all-files instead. We will be removing --all_files in the coming weeks.',
-        )
        .option('show-memory-usage', {
          type: 'boolean',
          description: 'Show memory usage in status bar',
          default: false,
        })
-        .option('show_memory_usage', {
-          type: 'boolean',
-          description: 'Show memory usage in status bar',
-          default: false,
-        })
-        .deprecateOption(
-          'show_memory_usage',
-          'Use --show-memory-usage instead. We will be removing --show_memory_usage in the coming weeks.',
-        )
        .option('yolo', {
          alias: 'y',
          type: 'boolean',
@@ -210,6 +196,11 @@ export async function parseArguments(): Promise<CliArgs> {
          string: true,
          description: 'Allowed MCP server names',
        })
+        .option('allowed-tools', {
+          type: 'array',
+          string: true,
+          description: 'Tools that are allowed to run without confirmation',
+        })
        .option('extensions', {
          alias: 'e',
          type: 'array',
@@ -253,7 +244,11 @@ export async function parseArguments(): Promise<CliArgs> {
          type: 'string',
          description: 'Tavily API key for web search functionality',
        })
-
+        .option('screen-reader', {
+          type: 'boolean',
+          description: 'Enable screen reader mode for accessibility.',
+          default: false,
+        })
        .check((argv) => {
          if (argv.prompt && argv['promptInteractive']) {
            throw new Error(
@@ -269,7 +264,13 @@ export async function parseArguments(): Promise<CliArgs> {
        }),
    )
    // Register MCP subcommands
-    .command(mcpCommand)
+    .command(mcpCommand);
+
+  if (settings?.experimental?.extensionManagement ?? false) {
+    yargsInstance.command(extensionsCommand);
+  }
+
+  yargsInstance
    .version(await getCliVersion()) // This will enable the --version flag based on package.json
    .alias('v', 'version')
    .help()
@@ -282,7 +283,10 @@ export async function parseArguments(): Promise<CliArgs> {

  // Handle case where MCP subcommands are executed - they should exit the process
  // and not return to main CLI logic
-  if (result._.length > 0 && result._[0] === 'mcp') {
+  if (
+    result._.length > 0 &&
+    (result._[0] === 'mcp' || result._[0] === 'extensions')
+  ) {
    // MCP commands handle their own execution and process exit
    process.exit(0);
  }
@@ -329,7 +333,7 @@ export async function loadHierarchicalGeminiMemory(
    extensionContextFilePaths,
    memoryImportFormat,
    fileFilteringOptions,
-    settings.memoryDiscoveryMaxDirs,
+    settings.context?.discoveryMaxDirs,
  );
 }

@@ -346,18 +350,20 @@ export async function loadCliConfig(
      (v) => v === 'true' || v === '1',
    ) ||
    false;
-  const memoryImportFormat = settings.memoryImportFormat || 'tree';
+  const memoryImportFormat = settings.context?.importFormat || 'tree';

-  const ideMode = settings.ideMode ?? false;
+  const ideMode = settings.ide?.enabled ?? false;

-  const folderTrustFeature = settings.folderTrustFeature ?? false;
-  const folderTrustSetting = settings.folderTrust ?? true;
+  const folderTrustFeature =
+    settings.security?.folderTrust?.featureEnabled ?? false;
+  const folderTrustSetting = settings.security?.folderTrust?.enabled ?? true;
  const folderTrust = folderTrustFeature && folderTrustSetting;
  const trustedFolder = isWorkspaceTrusted(settings);

  const allExtensions = annotateActiveExtensions(
    extensions,
    argv.extensions || [],
+    cwd,
  );

  const activeExtensions = extensions.filter(
@@ -382,8 +388,8 @@ export async function loadCliConfig(
  // TODO(b/343434939): This is a bit of a hack. The contextFileName should ideally be passed
  // directly to the Config constructor in core, and have core handle setGeminiMdFilename.
  // However, loadHierarchicalGeminiMemory is called *before* createServerConfig.
-  if (settings.contextFileName) {
-    setServerGeminiMdFilename(settings.contextFileName);
+  if (settings.context?.fileName) {
+    setServerGeminiMdFilename(settings.context.fileName);
  } else {
    // Reset to default if not provided in settings.
    setServerGeminiMdFilename(getCurrentGeminiMdFilename());
@@ -397,17 +403,19 @@ export async function loadCliConfig(

  const fileFiltering = {
    ...DEFAULT_MEMORY_FILE_FILTERING_OPTIONS,
-    ...settings.fileFiltering,
+    ...settings.context?.fileFiltering,
  };

-  const includeDirectories = (settings.includeDirectories || [])
+  const includeDirectories = (settings.context?.includeDirectories || [])
    .map(resolvePath)
    .concat((argv.includeDirectories || []).map(resolvePath));

  // Call the (now wrapper) loadHierarchicalGeminiMemory which calls the server's version
  const { memoryContent, fileCount } = await loadHierarchicalGeminiMemory(
    cwd,
-    settings.loadMemoryFromIncludeDirectories ? includeDirectories : [],
+    settings.context?.loadMemoryFromIncludeDirectories
+      ? includeDirectories
+      : [],
    debugMode,
    fileService,
    settings,
@@ -444,6 +452,14 @@ export async function loadCliConfig(
      argv.yolo || false ? ApprovalMode.YOLO : ApprovalMode.DEFAULT;
  }

+  // Force approval mode to default if the folder is not trusted.
+  if (!trustedFolder && approvalMode !== ApprovalMode.DEFAULT) {
+    logger.warn(
+      `Approval mode overridden to "default" because the current folder is not trusted.`,
+    );
+    approvalMode = ApprovalMode.DEFAULT;
+  }
+
  const interactive =
    !!argv.promptInteractive || (process.stdin.isTTY && question.length === 0);
  // In non-interactive mode, exclude tools that require a prompt.
@@ -475,16 +491,16 @@ export async function loadCliConfig(
  const blockedMcpServers: Array<{ name: string; extensionName: string }> = [];

  if (!argv.allowedMcpServerNames) {
-    if (settings.allowMCPServers) {
+    if (settings.mcp?.allowed) {
      mcpServers = allowedMcpServers(
        mcpServers,
-        settings.allowMCPServers,
+        settings.mcp.allowed,
        blockedMcpServers,
      );
    }

-    if (settings.excludeMCPServers) {
-      const excludedNames = new Set(settings.excludeMCPServers.filter(Boolean));
+    if (settings.mcp?.excluded) {
+      const excludedNames = new Set(settings.mcp.excluded.filter(Boolean));
      if (excludedNames.size > 0) {
        mcpServers = Object.fromEntries(
          Object.entries(mcpServers).filter(([key]) => !excludedNames.has(key)),
@@ -504,6 +520,10 @@ export async function loadCliConfig(
  const sandboxConfig = await loadSandboxConfig(settings, argv);
  const cliVersion = await getCliVersion();

+  const screenReader =
+    argv.screenReader !== undefined
+      ? argv.screenReader
+      : (settings.ui?.accessibility?.screenReader ?? false);
  return new Config({
    sessionId,
    embeddingModel: DEFAULT_GEMINI_EMBEDDING_MODEL,
@@ -511,25 +531,26 @@ export async function loadCliConfig(
    targetDir: cwd,
    includeDirectories,
    loadMemoryFromIncludeDirectories:
-      settings.loadMemoryFromIncludeDirectories || false,
+      settings.context?.loadMemoryFromIncludeDirectories || false,
    debugMode,
    question,
-    fullContext: argv.allFiles || argv.all_files || false,
-    coreTools: settings.coreTools || undefined,
+    fullContext: argv.allFiles || false,
+    coreTools: settings.tools?.core || undefined,
+    allowedTools: argv.allowedTools || settings.tools?.allowed || undefined,
    excludeTools,
-    toolDiscoveryCommand: settings.toolDiscoveryCommand,
-    toolCallCommand: settings.toolCallCommand,
-    mcpServerCommand: settings.mcpServerCommand,
+    toolDiscoveryCommand: settings.tools?.discoveryCommand,
+    toolCallCommand: settings.tools?.callCommand,
+    mcpServerCommand: settings.mcp?.serverCommand,
    mcpServers,
    userMemory: memoryContent,
    geminiMdFileCount: fileCount,
    approvalMode,
    showMemoryUsage:
-      argv.showMemoryUsage ||
-      argv.show_memory_usage ||
-      settings.showMemoryUsage ||
-      false,
-    accessibility: settings.accessibility,
+      argv.showMemoryUsage || settings.ui?.showMemoryUsage || false,
+    accessibility: {
+      ...settings.ui?.accessibility,
+      screenReader,
+    },
    telemetry: {
      enabled: argv.telemetry ?? settings.telemetry?.enabled,
      target: (argv.telemetryTarget ??
@@ -546,15 +567,17 @@ export async function loadCliConfig(
      logPrompts: argv.telemetryLogPrompts ?? settings.telemetry?.logPrompts,
      outfile: argv.telemetryOutfile ?? settings.telemetry?.outfile,
    },
-    usageStatisticsEnabled: settings.usageStatisticsEnabled ?? true,
+    usageStatisticsEnabled: settings.privacy?.usageStatisticsEnabled ?? true,
    // Git-aware file filtering settings
    fileFiltering: {
-      respectGitIgnore: settings.fileFiltering?.respectGitIgnore,
-      respectGeminiIgnore: settings.fileFiltering?.respectGeminiIgnore,
+      respectGitIgnore: settings.context?.fileFiltering?.respectGitIgnore,
+      respectGeminiIgnore: settings.context?.fileFiltering?.respectGeminiIgnore,
      enableRecursiveFileSearch:
-        settings.fileFiltering?.enableRecursiveFileSearch,
+        settings.context?.fileFiltering?.enableRecursiveFileSearch,
+      disableFuzzySearch: settings.context?.fileFiltering?.disableFuzzySearch,
    },
-    checkpointing: argv.checkpointing || settings.checkpointing?.enabled,
+    checkpointing:
+      argv.checkpointing || settings.general?.checkpointing?.enabled,
    proxy:
      argv.proxy ||
      process.env['HTTPS_PROXY'] ||
@@ -563,18 +586,16 @@ export async function loadCliConfig(
      process.env['http_proxy'],
    cwd,
    fileDiscoveryService: fileService,
-    bugCommand: settings.bugCommand,
-    model: argv.model || settings.model || DEFAULT_GEMINI_MODEL,
+    bugCommand: settings.advanced?.bugCommand,
+    model: argv.model || settings.model?.name || DEFAULT_GEMINI_MODEL,
    extensionContextFilePaths,
-    maxSessionTurns: settings.maxSessionTurns ?? -1,
    sessionTokenLimit: settings.sessionTokenLimit ?? -1,
+    maxSessionTurns: settings.model?.maxSessionTurns ?? -1,
    experimentalZedIntegration: argv.experimentalAcp || false,
    listExtensions: argv.listExtensions || false,
    extensions: allExtensions,
    blockedMcpServers,
    noBrowser: !!process.env['NO_BROWSER'],
-    summarizeToolOutput: settings.summarizeToolOutput,
-    ideMode,
    enableOpenAILogging:
      (typeof argv.openaiLogging === 'undefined'
        ? settings.enableOpenAILogging
@@ -590,20 +611,24 @@ export async function loadCliConfig(
          'SYSTEM_TEMPLATE:{"name":"qwen3_coder","params":{"is_git_repository":{RUNTIME_VARS_IS_GIT_REPO},"sandbox":"{RUNTIME_VARS_SANDBOX}"}}',
      },
    ]) as ConfigParameters['systemPromptMappings'],
-    authType: settings.selectedAuthType,
+    authType: settings.security?.auth?.selectedType,
    contentGenerator: settings.contentGenerator,
    cliVersion,
    tavilyApiKey:
      argv.tavilyApiKey ||
      settings.tavilyApiKey ||
      process.env['TAVILY_API_KEY'],
-    chatCompression: settings.chatCompression,
+    summarizeToolOutput: settings.model?.summarizeToolOutput,
+    ideMode,
+    chatCompression: settings.model?.chatCompression,
    folderTrustFeature,
    folderTrust,
    interactive,
    trustedFolder,
-    shouldUseNodePtyShell: settings.shouldUseNodePtyShell,
-    skipNextSpeakerCheck: settings.skipNextSpeakerCheck,
+    useRipgrep: settings.tools?.useRipgrep,
+    shouldUseNodePtyShell: settings.tools?.usePty,
+    skipNextSpeakerCheck: settings.model?.skipNextSpeakerCheck,
+    enablePromptCompletion: settings.general?.enablePromptCompletion ?? false,
  });
 }

@@ -665,7 +690,7 @@ function mergeExcludeTools(
  extraExcludes?: string[] | undefined,
 ): string[] {
  const allExcludeTools = new Set([
-    ...(settings.excludeTools || []),
+    ...(settings.tools?.exclude || []),
    ...(extraExcludes || []),
  ]);
  for (const extension of extensions) {
--- a/packages/cli/src/config/extension.test.ts
+++ b/packages/cli/src/config/extension.test.ts
@@ -5,24 +5,52 @@
 */

 import { vi } from 'vitest';
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import {
  EXTENSIONS_CONFIG_FILENAME,
-  EXTENSIONS_DIRECTORY_NAME,
+  INSTALL_METADATA_FILENAME,
  annotateActiveExtensions,
+  disableExtension,
+  enableExtension,
+  installExtension,
+  loadExtension,
  loadExtensions,
+  performWorkspaceExtensionMigration,
+  uninstallExtension,
+  updateExtension,
 } from './extension.js';
+import {
+  type GeminiCLIExtension,
+  type MCPServerConfig,
+} from '@qwen-code/qwen-code-core';
+import { execSync } from 'node:child_process';
+import { SettingScope, loadSettings } from './settings.js';
+import { type SimpleGit, simpleGit } from 'simple-git';
+
+vi.mock('simple-git', () => ({
+  simpleGit: vi.fn(),
+}));

 vi.mock('os', async (importOriginal) => {
-  const os = await importOriginal<typeof import('os')>();
+  const os = await importOriginal<typeof os>();
  return {
    ...os,
    homedir: vi.fn(),
  };
 });

+vi.mock('child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('child_process')>();
+  return {
+    ...actual,
+    execSync: vi.fn(),
+  };
+});
+
+const EXTENSIONS_DIRECTORY_NAME = path.join('.qwen', 'extensions');
+
 describe('loadExtensions', () => {
  let tempWorkspaceDir: string;
  let tempHomeDir: string;
@@ -40,56 +68,7 @@ describe('loadExtensions', () => {
  afterEach(() => {
    fs.rmSync(tempWorkspaceDir, { recursive: true, force: true });
    fs.rmSync(tempHomeDir, { recursive: true, force: true });
-  });
-
-  it('should include extension path in loaded extension', () => {
-    const workspaceExtensionsDir = path.join(
-      tempWorkspaceDir,
-      EXTENSIONS_DIRECTORY_NAME,
-    );
-    fs.mkdirSync(workspaceExtensionsDir, { recursive: true });
-
-    const extensionDir = path.join(workspaceExtensionsDir, 'test-extension');
-    fs.mkdirSync(extensionDir, { recursive: true });
-
-    const config = {
-      name: 'test-extension',
-      version: '1.0.0',
-    };
-    fs.writeFileSync(
-      path.join(extensionDir, EXTENSIONS_CONFIG_FILENAME),
-      JSON.stringify(config),
-    );
-
-    const extensions = loadExtensions(tempWorkspaceDir);
-    expect(extensions).toHaveLength(1);
-    expect(extensions[0].path).toBe(extensionDir);
-    expect(extensions[0].config.name).toBe('test-extension');
-  });
-
-  it('should include extension path in loaded extension', () => {
-    const workspaceExtensionsDir = path.join(
-      tempWorkspaceDir,
-      EXTENSIONS_DIRECTORY_NAME,
-    );
-    fs.mkdirSync(workspaceExtensionsDir, { recursive: true });
-
-    const extensionDir = path.join(workspaceExtensionsDir, 'test-extension');
-    fs.mkdirSync(extensionDir, { recursive: true });
-
-    const config = {
-      name: 'test-extension',
-      version: '1.0.0',
-    };
-    fs.writeFileSync(
-      path.join(extensionDir, EXTENSIONS_CONFIG_FILENAME),
-      JSON.stringify(config),
-    );
-
-    const extensions = loadExtensions(tempWorkspaceDir);
-    expect(extensions).toHaveLength(1);
-    expect(extensions[0].path).toBe(extensionDir);
-    expect(extensions[0].config.name).toBe('test-extension');
+    vi.restoreAllMocks();
  });

  it('should include extension path in loaded extension', () => {
@@ -159,26 +138,101 @@ describe('loadExtensions', () => {
      path.join(workspaceExtensionsDir, 'ext1', 'my-context-file.md'),
    ]);
  });
+
+  it('should filter out disabled extensions', () => {
+    const workspaceExtensionsDir = path.join(
+      tempWorkspaceDir,
+      EXTENSIONS_DIRECTORY_NAME,
+    );
+    fs.mkdirSync(workspaceExtensionsDir, { recursive: true });
+
+    createExtension(workspaceExtensionsDir, 'ext1', '1.0.0');
+    createExtension(workspaceExtensionsDir, 'ext2', '2.0.0');
+
+    const settingsDir = path.join(tempWorkspaceDir, '.qwen');
+    fs.mkdirSync(settingsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(settingsDir, 'settings.json'),
+      JSON.stringify({ extensions: { disabled: ['ext1'] } }),
+    );
+
+    const extensions = loadExtensions(tempWorkspaceDir);
+    const activeExtensions = annotateActiveExtensions(
+      extensions,
+      [],
+      tempWorkspaceDir,
+    ).filter((e) => e.isActive);
+    expect(activeExtensions).toHaveLength(1);
+    expect(activeExtensions[0].name).toBe('ext2');
+  });
+
+  it('should hydrate variables', () => {
+    const workspaceExtensionsDir = path.join(
+      tempWorkspaceDir,
+      EXTENSIONS_DIRECTORY_NAME,
+    );
+    fs.mkdirSync(workspaceExtensionsDir, { recursive: true });
+
+    createExtension(
+      workspaceExtensionsDir,
+      'test-extension',
+      '1.0.0',
+      false,
+      undefined,
+      {
+        'test-server': {
+          cwd: '${extensionPath}${/}server',
+        },
+      },
+    );
+
+    const extensions = loadExtensions(tempWorkspaceDir);
+    expect(extensions).toHaveLength(1);
+    const loadedConfig = extensions[0].config;
+    const expectedCwd = path.join(
+      workspaceExtensionsDir,
+      'test-extension',
+      'server',
+    );
+    expect(loadedConfig.mcpServers?.['test-server'].cwd).toBe(expectedCwd);
+  });
 });

 describe('annotateActiveExtensions', () => {
  const extensions = [
-    { config: { name: 'ext1', version: '1.0.0' }, contextFiles: [] },
-    { config: { name: 'ext2', version: '1.0.0' }, contextFiles: [] },
-    { config: { name: 'ext3', version: '1.0.0' }, contextFiles: [] },
+    {
+      path: '/path/to/ext1',
+      config: { name: 'ext1', version: '1.0.0' },
+      contextFiles: [],
+    },
+    {
+      path: '/path/to/ext2',
+      config: { name: 'ext2', version: '1.0.0' },
+      contextFiles: [],
+    },
+    {
+      path: '/path/to/ext3',
+      config: { name: 'ext3', version: '1.0.0' },
+      contextFiles: [],
+    },
  ];

  it('should mark all extensions as active if no enabled extensions are provided', () => {
-    const activeExtensions = annotateActiveExtensions(extensions, []);
+    const activeExtensions = annotateActiveExtensions(
+      extensions,
+      [],
+      '/path/to/workspace',
+    );
    expect(activeExtensions).toHaveLength(3);
    expect(activeExtensions.every((e) => e.isActive)).toBe(true);
  });

  it('should mark only the enabled extensions as active', () => {
-    const activeExtensions = annotateActiveExtensions(extensions, [
-      'ext1',
-      'ext3',
-    ]);
+    const activeExtensions = annotateActiveExtensions(
+      extensions,
+      ['ext1', 'ext3'],
+      '/path/to/workspace',
+    );
    expect(activeExtensions).toHaveLength(3);
    expect(activeExtensions.find((e) => e.name === 'ext1')?.isActive).toBe(
      true,
@@ -192,13 +246,21 @@ describe('annotateActiveExtensions', () => {
  });

  it('should mark all extensions as inactive when "none" is provided', () => {
-    const activeExtensions = annotateActiveExtensions(extensions, ['none']);
+    const activeExtensions = annotateActiveExtensions(
+      extensions,
+      ['none'],
+      '/path/to/workspace',
+    );
    expect(activeExtensions).toHaveLength(3);
    expect(activeExtensions.every((e) => !e.isActive)).toBe(true);
  });

  it('should handle case-insensitivity', () => {
-    const activeExtensions = annotateActiveExtensions(extensions, ['EXT1']);
+    const activeExtensions = annotateActiveExtensions(
+      extensions,
+      ['EXT1'],
+      '/path/to/workspace',
+    );
    expect(activeExtensions.find((e) => e.name === 'ext1')?.isActive).toBe(
      true,
    );
@@ -206,24 +268,258 @@ describe('annotateActiveExtensions', () => {

  it('should log an error for unknown extensions', () => {
    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
-    annotateActiveExtensions(extensions, ['ext4']);
+    annotateActiveExtensions(extensions, ['ext4'], '/path/to/workspace');
    expect(consoleSpy).toHaveBeenCalledWith('Extension not found: ext4');
    consoleSpy.mockRestore();
  });
 });

+describe('installExtension', () => {
+  let tempHomeDir: string;
+  let userExtensionsDir: string;
+
+  beforeEach(() => {
+    tempHomeDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'qwen-code-test-home-'),
+    );
+    vi.mocked(os.homedir).mockReturnValue(tempHomeDir);
+    userExtensionsDir = path.join(tempHomeDir, '.qwen', 'extensions');
+    // Clean up before each test
+    fs.rmSync(userExtensionsDir, { recursive: true, force: true });
+    fs.mkdirSync(userExtensionsDir, { recursive: true });
+
+    vi.mocked(execSync).mockClear();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempHomeDir, { recursive: true, force: true });
+  });
+
+  it('should install an extension from a local path', async () => {
+    const sourceExtDir = createExtension(
+      tempHomeDir,
+      'my-local-extension',
+      '1.0.0',
+    );
+    const targetExtDir = path.join(userExtensionsDir, 'my-local-extension');
+    const metadataPath = path.join(targetExtDir, INSTALL_METADATA_FILENAME);
+
+    await installExtension({ source: sourceExtDir, type: 'local' });
+
+    expect(fs.existsSync(targetExtDir)).toBe(true);
+    expect(fs.existsSync(metadataPath)).toBe(true);
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+    expect(metadata).toEqual({
+      source: sourceExtDir,
+      type: 'local',
+    });
+    fs.rmSync(targetExtDir, { recursive: true, force: true });
+  });
+
+  it('should throw an error if the extension already exists', async () => {
+    const sourceExtDir = createExtension(
+      tempHomeDir,
+      'my-local-extension',
+      '1.0.0',
+    );
+    await installExtension({ source: sourceExtDir, type: 'local' });
+    await expect(
+      installExtension({ source: sourceExtDir, type: 'local' }),
+    ).rejects.toThrow(
+      'Extension "my-local-extension" is already installed. Please uninstall it first.',
+    );
+  });
+
+  it('should throw an error and cleanup if gemini-extension.json is missing', async () => {
+    const sourceExtDir = path.join(tempHomeDir, 'bad-extension');
+    fs.mkdirSync(sourceExtDir, { recursive: true });
+
+    await expect(
+      installExtension({ source: sourceExtDir, type: 'local' }),
+    ).rejects.toThrow(
+      `Invalid extension at ${sourceExtDir}. Please make sure it has a valid gemini-extension.json file.`,
+    );
+
+    const targetExtDir = path.join(userExtensionsDir, 'bad-extension');
+    expect(fs.existsSync(targetExtDir)).toBe(false);
+  });
+
+  it('should install an extension from a git URL', async () => {
+    const gitUrl = 'https://github.com/google/gemini-extensions.git';
+    const extensionName = 'gemini-extensions';
+    const targetExtDir = path.join(userExtensionsDir, extensionName);
+    const metadataPath = path.join(targetExtDir, INSTALL_METADATA_FILENAME);
+
+    const clone = vi.fn().mockImplementation(async (_, destination) => {
+      fs.mkdirSync(destination, { recursive: true });
+      fs.writeFileSync(
+        path.join(destination, EXTENSIONS_CONFIG_FILENAME),
+        JSON.stringify({ name: extensionName, version: '1.0.0' }),
+      );
+    });
+
+    const mockedSimpleGit = simpleGit as vi.MockedFunction<typeof simpleGit>;
+    mockedSimpleGit.mockReturnValue({ clone } as unknown as SimpleGit);
+
+    await installExtension({ source: gitUrl, type: 'git' });
+
+    expect(fs.existsSync(targetExtDir)).toBe(true);
+    expect(fs.existsSync(metadataPath)).toBe(true);
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+    expect(metadata).toEqual({
+      source: gitUrl,
+      type: 'git',
+    });
+    fs.rmSync(targetExtDir, { recursive: true, force: true });
+  });
+});
+
+describe('uninstallExtension', () => {
+  let tempHomeDir: string;
+  let userExtensionsDir: string;
+
+  beforeEach(() => {
+    tempHomeDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'qwen-code-test-home-'),
+    );
+    vi.mocked(os.homedir).mockReturnValue(tempHomeDir);
+    userExtensionsDir = path.join(tempHomeDir, '.qwen', 'extensions');
+    // Clean up before each test
+    fs.rmSync(userExtensionsDir, { recursive: true, force: true });
+    fs.mkdirSync(userExtensionsDir, { recursive: true });
+
+    vi.mocked(execSync).mockClear();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempHomeDir, { recursive: true, force: true });
+  });
+
+  it('should uninstall an extension by name', async () => {
+    const sourceExtDir = createExtension(
+      userExtensionsDir,
+      'my-local-extension',
+      '1.0.0',
+    );
+
+    await uninstallExtension('my-local-extension');
+
+    expect(fs.existsSync(sourceExtDir)).toBe(false);
+  });
+
+  it('should uninstall an extension by name and retain existing extensions', async () => {
+    const sourceExtDir = createExtension(
+      userExtensionsDir,
+      'my-local-extension',
+      '1.0.0',
+    );
+    const otherExtDir = createExtension(
+      userExtensionsDir,
+      'other-extension',
+      '1.0.0',
+    );
+
+    await uninstallExtension('my-local-extension');
+
+    expect(fs.existsSync(sourceExtDir)).toBe(false);
+    expect(loadExtensions(tempHomeDir)).toHaveLength(1);
+    expect(fs.existsSync(otherExtDir)).toBe(true);
+  });
+
+  it('should throw an error if the extension does not exist', async () => {
+    await expect(uninstallExtension('nonexistent-extension')).rejects.toThrow(
+      'Extension "nonexistent-extension" not found.',
+    );
+  });
+});
+
+describe('performWorkspaceExtensionMigration', () => {
+  let tempWorkspaceDir: string;
+  let tempHomeDir: string;
+
+  beforeEach(() => {
+    tempWorkspaceDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'qwen-code-test-workspace-'),
+    );
+    tempHomeDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'qwen-code-test-home-'),
+    );
+    vi.mocked(os.homedir).mockReturnValue(tempHomeDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempWorkspaceDir, { recursive: true, force: true });
+    fs.rmSync(tempHomeDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it('should install the extensions in the user directory', async () => {
+    const workspaceExtensionsDir = path.join(
+      tempWorkspaceDir,
+      EXTENSIONS_DIRECTORY_NAME,
+    );
+    fs.mkdirSync(workspaceExtensionsDir, { recursive: true });
+    const ext1Path = createExtension(workspaceExtensionsDir, 'ext1', '1.0.0');
+    const ext2Path = createExtension(workspaceExtensionsDir, 'ext2', '1.0.0');
+    const extensionsToMigrate = [
+      loadExtension(ext1Path)!,
+      loadExtension(ext2Path)!,
+    ];
+    const failed =
+      await performWorkspaceExtensionMigration(extensionsToMigrate);
+
+    expect(failed).toEqual([]);
+
+    const userExtensionsDir = path.join(tempHomeDir, '.qwen', 'extensions');
+    const userExt1Path = path.join(userExtensionsDir, 'ext1');
+    const extensions = loadExtensions(tempWorkspaceDir);
+
+    expect(extensions).toHaveLength(2);
+    const metadataPath = path.join(userExt1Path, INSTALL_METADATA_FILENAME);
+    expect(fs.existsSync(metadataPath)).toBe(true);
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+    expect(metadata).toEqual({
+      source: ext1Path,
+      type: 'local',
+    });
+  });
+
+  it('should return the names of failed installations', async () => {
+    const workspaceExtensionsDir = path.join(
+      tempWorkspaceDir,
+      EXTENSIONS_DIRECTORY_NAME,
+    );
+    fs.mkdirSync(workspaceExtensionsDir, { recursive: true });
+
+    const ext1Path = createExtension(workspaceExtensionsDir, 'ext1', '1.0.0');
+
+    const extensions = [
+      loadExtension(ext1Path)!,
+      {
+        path: '/ext/path/1',
+        config: { name: 'ext2', version: '1.0.0' },
+        contextFiles: [],
+      },
+    ];
+
+    const failed = await performWorkspaceExtensionMigration(extensions);
+    expect(failed).toEqual(['ext2']);
+  });
+});
+
 function createExtension(
  extensionsDir: string,
  name: string,
  version: string,
  addContextFile = false,
  contextFileName?: string,
-): void {
+  mcpServers?: Record<string, MCPServerConfig>,
+): string {
  const extDir = path.join(extensionsDir, name);
-  fs.mkdirSync(extDir);
+  fs.mkdirSync(extDir, { recursive: true });
  fs.writeFileSync(
    path.join(extDir, EXTENSIONS_CONFIG_FILENAME),
-    JSON.stringify({ name, version, contextFileName }),
+    JSON.stringify({ name, version, contextFileName, mcpServers }),
  );

  if (addContextFile) {
@@ -233,4 +529,193 @@ function createExtension(
  if (contextFileName) {
    fs.writeFileSync(path.join(extDir, contextFileName), 'context');
  }
+  return extDir;
 }
+
+describe('updateExtension', () => {
+  let tempHomeDir: string;
+  let userExtensionsDir: string;
+
+  beforeEach(() => {
+    tempHomeDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'qwen-code-test-home-'),
+    );
+    vi.mocked(os.homedir).mockReturnValue(tempHomeDir);
+    userExtensionsDir = path.join(tempHomeDir, '.qwen', 'extensions');
+    // Clean up before each test
+    fs.rmSync(userExtensionsDir, { recursive: true, force: true });
+    fs.mkdirSync(userExtensionsDir, { recursive: true });
+
+    vi.mocked(execSync).mockClear();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempHomeDir, { recursive: true, force: true });
+  });
+
+  it('should update a git-installed extension', async () => {
+    // 1. "Install" an extension
+    const gitUrl = 'https://github.com/google/gemini-extensions.git';
+    const extensionName = 'gemini-extensions';
+    const targetExtDir = path.join(userExtensionsDir, extensionName);
+    const metadataPath = path.join(targetExtDir, INSTALL_METADATA_FILENAME);
+
+    // Create the "installed" extension directory and files
+    fs.mkdirSync(targetExtDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(targetExtDir, EXTENSIONS_CONFIG_FILENAME),
+      JSON.stringify({ name: extensionName, version: '1.0.0' }),
+    );
+    fs.writeFileSync(
+      metadataPath,
+      JSON.stringify({ source: gitUrl, type: 'git' }),
+    );
+
+    // 2. Mock the git clone for the update
+    const clone = vi.fn().mockImplementation(async (_, destination) => {
+      fs.mkdirSync(destination, { recursive: true });
+      // This is the "updated" version
+      fs.writeFileSync(
+        path.join(destination, EXTENSIONS_CONFIG_FILENAME),
+        JSON.stringify({ name: extensionName, version: '1.1.0' }),
+      );
+    });
+
+    const mockedSimpleGit = simpleGit as vi.MockedFunction<typeof simpleGit>;
+    mockedSimpleGit.mockReturnValue({
+      clone,
+    } as unknown as SimpleGit);
+
+    // 3. Call updateExtension
+    const updateInfo = await updateExtension(extensionName);
+
+    // 4. Assertions
+    expect(updateInfo).toEqual({
+      originalVersion: '1.0.0',
+      updatedVersion: '1.1.0',
+    });
+
+    // Check that the config file reflects the new version
+    const updatedConfig = JSON.parse(
+      fs.readFileSync(
+        path.join(targetExtDir, EXTENSIONS_CONFIG_FILENAME),
+        'utf-8',
+      ),
+    );
+    expect(updatedConfig.version).toBe('1.1.0');
+  });
+});
+
+describe('disableExtension', () => {
+  let tempWorkspaceDir: string;
+  let tempHomeDir: string;
+
+  beforeEach(() => {
+    tempWorkspaceDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'qwen-code-test-workspace-'),
+    );
+    tempHomeDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'qwen-code-test-home-'),
+    );
+    vi.mocked(os.homedir).mockReturnValue(tempHomeDir);
+    vi.spyOn(process, 'cwd').mockReturnValue(tempWorkspaceDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempWorkspaceDir, { recursive: true, force: true });
+    fs.rmSync(tempHomeDir, { recursive: true, force: true });
+  });
+
+  it('should disable an extension at the user scope', () => {
+    disableExtension('my-extension', SettingScope.User);
+    const settings = loadSettings(tempWorkspaceDir);
+    expect(
+      settings.forScope(SettingScope.User).settings.extensions?.disabled,
+    ).toEqual(['my-extension']);
+  });
+
+  it('should disable an extension at the workspace scope', () => {
+    disableExtension('my-extension', SettingScope.Workspace);
+    const settings = loadSettings(tempWorkspaceDir);
+    expect(
+      settings.forScope(SettingScope.Workspace).settings.extensions?.disabled,
+    ).toEqual(['my-extension']);
+  });
+
+  it('should handle disabling the same extension twice', () => {
+    disableExtension('my-extension', SettingScope.User);
+    disableExtension('my-extension', SettingScope.User);
+    const settings = loadSettings(tempWorkspaceDir);
+    expect(
+      settings.forScope(SettingScope.User).settings.extensions?.disabled,
+    ).toEqual(['my-extension']);
+  });
+
+  it('should throw an error if you request system scope', () => {
+    expect(() => disableExtension('my-extension', SettingScope.System)).toThrow(
+      'System and SystemDefaults scopes are not supported.',
+    );
+  });
+});
+
+describe('enableExtension', () => {
+  let tempWorkspaceDir: string;
+  let tempHomeDir: string;
+  let userExtensionsDir: string;
+
+  beforeEach(() => {
+    tempWorkspaceDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'qwen-code-test-workspace-'),
+    );
+    tempHomeDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'qwen-code-test-home-'),
+    );
+    userExtensionsDir = path.join(tempHomeDir, '.qwen', 'extensions');
+    vi.mocked(os.homedir).mockReturnValue(tempHomeDir);
+    vi.spyOn(process, 'cwd').mockReturnValue(tempWorkspaceDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempWorkspaceDir, { recursive: true, force: true });
+    fs.rmSync(tempHomeDir, { recursive: true, force: true });
+    fs.rmSync(userExtensionsDir, { recursive: true, force: true });
+  });
+
+  afterAll(() => {
+    vi.restoreAllMocks();
+  });
+
+  const getActiveExtensions = (): GeminiCLIExtension[] => {
+    const extensions = loadExtensions(tempWorkspaceDir);
+    const activeExtensions = annotateActiveExtensions(
+      extensions,
+      [],
+      tempWorkspaceDir,
+    );
+    return activeExtensions.filter((e) => e.isActive);
+  };
+
+  it('should enable an extension at the user scope', () => {
+    createExtension(userExtensionsDir, 'ext1', '1.0.0');
+    disableExtension('ext1', SettingScope.User);
+    let activeExtensions = getActiveExtensions();
+    expect(activeExtensions).toHaveLength(0);
+
+    enableExtension('ext1', [SettingScope.User]);
+    activeExtensions = getActiveExtensions();
+    expect(activeExtensions).toHaveLength(1);
+    expect(activeExtensions[0].name).toBe('ext1');
+  });
+
+  it('should enable an extension at the workspace scope', () => {
+    createExtension(userExtensionsDir, 'ext1', '1.0.0');
+    disableExtension('ext1', SettingScope.Workspace);
+    let activeExtensions = getActiveExtensions();
+    expect(activeExtensions).toHaveLength(0);
+
+    enableExtension('ext1', [SettingScope.Workspace]);
+    activeExtensions = getActiveExtensions();
+    expect(activeExtensions).toHaveLength(1);
+    expect(activeExtensions[0].name).toBe('ext1');
+  });
+});
--- a/packages/cli/src/config/extension.ts
+++ b/packages/cli/src/config/extension.ts
@@ -4,19 +4,29 @@
 * SPDX-License-Identifier: Apache-2.0
 */

-import { MCPServerConfig, GeminiCLIExtension } from '@qwen-code/qwen-code-core';
-import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
+import type {
+  MCPServerConfig,
+  GeminiCLIExtension,
+} from '@qwen-code/qwen-code-core';
+import { Storage } from '@qwen-code/qwen-code-core';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { simpleGit } from 'simple-git';
+import { SettingScope, loadSettings } from '../config/settings.js';
+import { getErrorMessage } from '../utils/errors.js';
+import { recursivelyHydrateStrings } from './extensions/variables.js';

 export const EXTENSIONS_DIRECTORY_NAME = path.join('.qwen', 'extensions');
 export const EXTENSIONS_CONFIG_FILENAME = 'qwen-extension.json';
 export const EXTENSIONS_CONFIG_FILENAME_OLD = 'gemini-extension.json';
+export const INSTALL_METADATA_FILENAME = '.qwen-extension-install.json';

 export interface Extension {
  path: string;
  config: ExtensionConfig;
  contextFiles: string[];
+  installMetadata?: ExtensionInstallMetadata | undefined;
 }

 export interface ExtensionConfig {
@@ -27,14 +37,103 @@ export interface ExtensionConfig {
  excludeTools?: string[];
 }

+export interface ExtensionInstallMetadata {
+  source: string;
+  type: 'git' | 'local';
+}
+
+export interface ExtensionUpdateInfo {
+  originalVersion: string;
+  updatedVersion: string;
+}
+
+export class ExtensionStorage {
+  private readonly extensionName: string;
+
+  constructor(extensionName: string) {
+    this.extensionName = extensionName;
+  }
+
+  getExtensionDir(): string {
+    return path.join(
+      ExtensionStorage.getUserExtensionsDir(),
+      this.extensionName,
+    );
+  }
+
+  getConfigPath(): string {
+    return path.join(this.getExtensionDir(), EXTENSIONS_CONFIG_FILENAME);
+  }
+
+  static getUserExtensionsDir(): string {
+    const storage = new Storage(os.homedir());
+    return storage.getExtensionsDir();
+  }
+
+  static async createTmpDir(): Promise<string> {
+    return await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), 'gemini-extension'),
+    );
+  }
+}
+
+export function getWorkspaceExtensions(workspaceDir: string): Extension[] {
+  return loadExtensionsFromDir(workspaceDir);
+}
+
+async function copyExtension(
+  source: string,
+  destination: string,
+): Promise<void> {
+  await fs.promises.cp(source, destination, { recursive: true });
+}
+
+export async function performWorkspaceExtensionMigration(
+  extensions: Extension[],
+): Promise<string[]> {
+  const failedInstallNames: string[] = [];
+
+  for (const extension of extensions) {
+    try {
+      const installMetadata: ExtensionInstallMetadata = {
+        source: extension.path,
+        type: 'local',
+      };
+      await installExtension(installMetadata);
+    } catch (_) {
+      failedInstallNames.push(extension.config.name);
+    }
+  }
+  return failedInstallNames;
+}
+
 export function loadExtensions(workspaceDir: string): Extension[] {
-  const allExtensions = [
-    ...loadExtensionsFromDir(workspaceDir),
-    ...loadExtensionsFromDir(os.homedir()),
-  ];
+  const settings = loadSettings(workspaceDir).merged;
+  const disabledExtensions = settings.extensions?.disabled ?? [];
+  const allExtensions = [...loadUserExtensions()];
+
+  if (!settings.experimental?.extensionManagement) {
+    allExtensions.push(...getWorkspaceExtensions(workspaceDir));
+  }

  const uniqueExtensions = new Map<string, Extension>();
  for (const extension of allExtensions) {
+    if (
+      !uniqueExtensions.has(extension.config.name) &&
+      !disabledExtensions.includes(extension.config.name)
+    ) {
+      uniqueExtensions.set(extension.config.name, extension);
+    }
+  }
+
+  return Array.from(uniqueExtensions.values());
+}
+
+export function loadUserExtensions(): Extension[] {
+  const userExtensions = loadExtensionsFromDir(os.homedir());
+
+  const uniqueExtensions = new Map<string, Extension>();
+  for (const extension of userExtensions) {
    if (!uniqueExtensions.has(extension.config.name)) {
      uniqueExtensions.set(extension.config.name, extension);
    }
@@ -43,8 +142,9 @@ export function loadExtensions(workspaceDir: string): Extension[] {
  return Array.from(uniqueExtensions.values());
 }

-function loadExtensionsFromDir(dir: string): Extension[] {
-  const extensionsDir = path.join(dir, EXTENSIONS_DIRECTORY_NAME);
+export function loadExtensionsFromDir(dir: string): Extension[] {
+  const storage = new Storage(dir);
+  const extensionsDir = storage.getExtensionsDir();
  if (!fs.existsSync(extensionsDir)) {
    return [];
  }
@@ -61,7 +161,7 @@ function loadExtensionsFromDir(dir: string): Extension[] {
  return extensions;
 }

-function loadExtension(extensionDir: string): Extension | null {
+export function loadExtension(extensionDir: string): Extension | null {
  if (!fs.statSync(extensionDir).isDirectory()) {
    console.error(
      `Warning: unexpected file ${extensionDir} in extensions directory.`,
@@ -86,7 +186,11 @@ function loadExtension(extensionDir: string): Extension | null {

  try {
    const configContent = fs.readFileSync(configFilePath, 'utf-8');
-    const config = JSON.parse(configContent) as ExtensionConfig;
+    const config = recursivelyHydrateStrings(JSON.parse(configContent), {
+      extensionPath: extensionDir,
+      '/': path.sep,
+      pathSeparator: path.sep,
+    }) as unknown as ExtensionConfig;
    if (!config.name || !config.version) {
      console.error(
        `Invalid extension config in ${configFilePath}: missing name or version.`,
@@ -102,15 +206,31 @@ function loadExtension(extensionDir: string): Extension | null {
      path: extensionDir,
      config,
      contextFiles,
+      installMetadata: loadInstallMetadata(extensionDir),
    };
  } catch (e) {
    console.error(
-      `Warning: error parsing extension config in ${configFilePath}: ${e}`,
+      `Warning: error parsing extension config in ${configFilePath}: ${getErrorMessage(
+        e,
+      )}`,
    );
    return null;
  }
 }

+function loadInstallMetadata(
+  extensionDir: string,
+): ExtensionInstallMetadata | undefined {
+  const metadataFilePath = path.join(extensionDir, INSTALL_METADATA_FILENAME);
+  try {
+    const configContent = fs.readFileSync(metadataFilePath, 'utf-8');
+    const metadata = JSON.parse(configContent) as ExtensionInstallMetadata;
+    return metadata;
+  } catch (_e) {
+    return undefined;
+  }
+}
+
 function getContextFileNames(config: ExtensionConfig): string[] {
  if (!config.contextFileName) {
    return ['QWEN.md'];
@@ -120,17 +240,28 @@ function getContextFileNames(config: ExtensionConfig): string[] {
  return config.contextFileName;
 }

+/**
+ * Returns an annotated list of extensions. If an extension is listed in enabledExtensionNames, it will be active.
+ * If enabledExtensionNames is empty, an extension is active unless it is in list of disabled extensions in settings.
+ * @param extensions The base list of extensions.
+ * @param enabledExtensionNames The names of explicitly enabled extensions.
+ * @param workspaceDir The current workspace directory.
+ */
 export function annotateActiveExtensions(
  extensions: Extension[],
  enabledExtensionNames: string[],
+  workspaceDir: string,
 ): GeminiCLIExtension[] {
+  const settings = loadSettings(workspaceDir).merged;
+  const disabledExtensions = settings.extensions?.disabled ?? [];
+
  const annotatedExtensions: GeminiCLIExtension[] = [];

  if (enabledExtensionNames.length === 0) {
    return extensions.map((extension) => ({
      name: extension.config.name,
      version: extension.config.version,
-      isActive: true,
+      isActive: !disabledExtensions.includes(extension.config.name),
      path: extension.path,
    }));
  }
@@ -175,3 +306,230 @@ export function annotateActiveExtensions(

  return annotatedExtensions;
 }
+
+/**
+ * Clones a Git repository to a specified local path.
+ * @param gitUrl The Git URL to clone.
+ * @param destination The destination path to clone the repository to.
+ */
+async function cloneFromGit(
+  gitUrl: string,
+  destination: string,
+): Promise<void> {
+  try {
+    // TODO(chrstnb): Download the archive instead to avoid unnecessary .git info.
+    await simpleGit().clone(gitUrl, destination, ['--depth', '1']);
+  } catch (error) {
+    throw new Error(`Failed to clone Git repository from ${gitUrl}`, {
+      cause: error,
+    });
+  }
+}
+
+export async function installExtension(
+  installMetadata: ExtensionInstallMetadata,
+  cwd: string = process.cwd(),
+): Promise<string> {
+  const extensionsDir = ExtensionStorage.getUserExtensionsDir();
+  await fs.promises.mkdir(extensionsDir, { recursive: true });
+
+  // Convert relative paths to absolute paths for the metadata file.
+  if (
+    installMetadata.type === 'local' &&
+    !path.isAbsolute(installMetadata.source)
+  ) {
+    installMetadata.source = path.resolve(cwd, installMetadata.source);
+  }
+
+  let localSourcePath: string;
+  let tempDir: string | undefined;
+  if (installMetadata.type === 'git') {
+    tempDir = await ExtensionStorage.createTmpDir();
+    await cloneFromGit(installMetadata.source, tempDir);
+    localSourcePath = tempDir;
+  } else {
+    localSourcePath = installMetadata.source;
+  }
+  let newExtensionName: string | undefined;
+  try {
+    const newExtension = loadExtension(localSourcePath);
+    if (!newExtension) {
+      throw new Error(
+        `Invalid extension at ${installMetadata.source}. Please make sure it has a valid gemini-extension.json file.`,
+      );
+    }
+
+    // ~/.gemini/extensions/{ExtensionConfig.name}.
+    newExtensionName = newExtension.config.name;
+    const extensionStorage = new ExtensionStorage(newExtensionName);
+    const destinationPath = extensionStorage.getExtensionDir();
+
+    const installedExtensions = loadUserExtensions();
+    if (
+      installedExtensions.some(
+        (installed) => installed.config.name === newExtensionName,
+      )
+    ) {
+      throw new Error(
+        `Extension "${newExtensionName}" is already installed. Please uninstall it first.`,
+      );
+    }
+
+    await copyExtension(localSourcePath, destinationPath);
+
+    const metadataString = JSON.stringify(installMetadata, null, 2);
+    const metadataPath = path.join(destinationPath, INSTALL_METADATA_FILENAME);
+    await fs.promises.writeFile(metadataPath, metadataString);
+  } finally {
+    if (tempDir) {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  }
+
+  return newExtensionName;
+}
+
+export async function uninstallExtension(
+  extensionName: string,
+  cwd: string = process.cwd(),
+): Promise<void> {
+  const installedExtensions = loadUserExtensions();
+  if (
+    !installedExtensions.some(
+      (installed) => installed.config.name === extensionName,
+    )
+  ) {
+    throw new Error(`Extension "${extensionName}" not found.`);
+  }
+  removeFromDisabledExtensions(
+    extensionName,
+    [SettingScope.User, SettingScope.Workspace],
+    cwd,
+  );
+  const storage = new ExtensionStorage(extensionName);
+  return await fs.promises.rm(storage.getExtensionDir(), {
+    recursive: true,
+    force: true,
+  });
+}
+
+export function toOutputString(extension: Extension): string {
+  let output = `${extension.config.name} (${extension.config.version})`;
+  output += `\n Path: ${extension.path}`;
+  if (extension.installMetadata) {
+    output += `\n Source: ${extension.installMetadata.source}`;
+  }
+  if (extension.contextFiles.length > 0) {
+    output += `\n Context files:`;
+    extension.contextFiles.forEach((contextFile) => {
+      output += `\n  ${contextFile}`;
+    });
+  }
+  if (extension.config.mcpServers) {
+    output += `\n MCP servers:`;
+    Object.keys(extension.config.mcpServers).forEach((key) => {
+      output += `\n  ${key}`;
+    });
+  }
+  if (extension.config.excludeTools) {
+    output += `\n Excluded tools:`;
+    extension.config.excludeTools.forEach((tool) => {
+      output += `\n  ${tool}`;
+    });
+  }
+  return output;
+}
+
+export async function updateExtension(
+  extensionName: string,
+  cwd: string = process.cwd(),
+): Promise<ExtensionUpdateInfo | undefined> {
+  const installedExtensions = loadUserExtensions();
+  const extension = installedExtensions.find(
+    (installed) => installed.config.name === extensionName,
+  );
+  if (!extension) {
+    throw new Error(
+      `Extension "${extensionName}" not found. Run gemini extensions list to see available extensions.`,
+    );
+  }
+  if (!extension.installMetadata) {
+    throw new Error(
+      `Extension cannot be updated because it is missing the .gemini-extension.install.json file. To update manually, uninstall and then reinstall the updated version.`,
+    );
+  }
+  const originalVersion = extension.config.version;
+  const tempDir = await ExtensionStorage.createTmpDir();
+  try {
+    await copyExtension(extension.path, tempDir);
+    await uninstallExtension(extensionName, cwd);
+    await installExtension(extension.installMetadata, cwd);
+
+    const updatedExtension = loadExtension(extension.path);
+    if (!updatedExtension) {
+      throw new Error('Updated extension not found after installation.');
+    }
+    const updatedVersion = updatedExtension.config.version;
+    return {
+      originalVersion,
+      updatedVersion,
+    };
+  } catch (e) {
+    console.error(
+      `Error updating extension, rolling back. ${getErrorMessage(e)}`,
+    );
+    await copyExtension(tempDir, extension.path);
+    throw e;
+  } finally {
+    await fs.promises.rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export function disableExtension(
+  name: string,
+  scope: SettingScope,
+  cwd: string = process.cwd(),
+) {
+  if (scope === SettingScope.System || scope === SettingScope.SystemDefaults) {
+    throw new Error('System and SystemDefaults scopes are not supported.');
+  }
+  const settings = loadSettings(cwd);
+  const settingsFile = settings.forScope(scope);
+  const extensionSettings = settingsFile.settings.extensions || {
+    disabled: [],
+  };
+  const disabledExtensions = extensionSettings.disabled || [];
+  if (!disabledExtensions.includes(name)) {
+    disabledExtensions.push(name);
+    extensionSettings.disabled = disabledExtensions;
+    settings.setValue(scope, 'extensions', extensionSettings);
+  }
+}
+
+export function enableExtension(name: string, scopes: SettingScope[]) {
+  removeFromDisabledExtensions(name, scopes);
+}
+
+/**
+ * Removes an extension from the list of disabled extensions.
+ * @param name The name of the extension to remove.
+ * @param scope The scopes to remove the name from.
+ */
+function removeFromDisabledExtensions(
+  name: string,
+  scopes: SettingScope[],
+  cwd: string = process.cwd(),
+) {
+  const settings = loadSettings(cwd);
+  for (const scope of scopes) {
+    const settingsFile = settings.forScope(scope);
+    const extensionSettings = settingsFile.settings.extensions || {
+      disabled: [],
+    };
+    const disabledExtensions = extensionSettings.disabled || [];
+    extensionSettings.disabled = disabledExtensions.filter(
+      (extension) => extension !== name,
+    );
+    settings.setValue(scope, 'extensions', extensionSettings);
+  }
+}
--- a/packages/cli/src/config/extensions/variableSchema.ts
+++ b/packages/cli/src/config/extensions/variableSchema.ts
@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface VariableDefinition {
+  type: 'string';
+  description: string;
+  default?: string;
+  required?: boolean;
+}
+
+export interface VariableSchema {
+  [key: string]: VariableDefinition;
+}
+
+const PATH_SEPARATOR_DEFINITION = {
+  type: 'string',
+  description: 'The path separator.',
+} as const;
+
+export const VARIABLE_SCHEMA = {
+  extensionPath: {
+    type: 'string',
+    description: 'The path of the extension in the filesystem.',
+  },
+  '/': PATH_SEPARATOR_DEFINITION,
+  pathSeparator: PATH_SEPARATOR_DEFINITION,
+} as const;
--- a/packages/cli/src/config/extensions/variables.test.ts
+++ b/packages/cli/src/config/extensions/variables.test.ts
@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { expect, describe, it } from 'vitest';
+import { hydrateString } from './variables.js';
+
+describe('hydrateString', () => {
+  it('should replace a single variable', () => {
+    const context = {
+      extensionPath: 'path/my-extension',
+    };
+    const result = hydrateString('Hello, ${extensionPath}!', context);
+    expect(result).toBe('Hello, path/my-extension!');
+  });
+});
--- a/packages/cli/src/config/extensions/variables.ts
+++ b/packages/cli/src/config/extensions/variables.ts
@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type VariableSchema, VARIABLE_SCHEMA } from './variableSchema.js';
+
+export type JsonObject = { [key: string]: JsonValue };
+export type JsonArray = JsonValue[];
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonObject
+  | JsonArray;
+
+export type VariableContext = {
+  [key in keyof typeof VARIABLE_SCHEMA]?: string;
+};
+
+export function validateVariables(
+  variables: VariableContext,
+  schema: VariableSchema,
+) {
+  for (const key in schema) {
+    const definition = schema[key];
+    if (definition.required && !variables[key as keyof VariableContext]) {
+      throw new Error(`Missing required variable: ${key}`);
+    }
+  }
+}
+
+export function hydrateString(str: string, context: VariableContext): string {
+  validateVariables(context, VARIABLE_SCHEMA);
+  const regex = /\${(.*?)}/g;
+  return str.replace(regex, (match, key) =>
+    context[key as keyof VariableContext] == null
+      ? match
+      : (context[key as keyof VariableContext] as string),
+  );
+}
+
+export function recursivelyHydrateStrings(
+  obj: JsonValue,
+  values: VariableContext,
+): JsonValue {
+  if (typeof obj === 'string') {
+    return hydrateString(obj, values);
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => recursivelyHydrateStrings(item, values));
+  }
+  if (typeof obj === 'object' && obj !== null) {
+    const newObj: JsonObject = {};
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        newObj[key] = recursivelyHydrateStrings(obj[key], values);
+      }
+    }
+    return newObj;
+  }
+  return obj;
+}
--- a/packages/cli/src/config/keyBindings.test.ts
+++ b/packages/cli/src/config/keyBindings.test.ts
@@ -5,11 +5,8 @@
 */

 import { describe, it, expect } from 'vitest';
-import {
-  Command,
-  KeyBindingConfig,
-  defaultKeyBindings,
-} from './keyBindings.js';
+import type { KeyBindingConfig } from './keyBindings.js';
+import { Command, defaultKeyBindings } from './keyBindings.js';

 describe('keyBindings config', () => {
  describe('defaultKeyBindings', () => {
--- a/packages/cli/src/config/sandboxConfig.ts
+++ b/packages/cli/src/config/sandboxConfig.ts
@@ -4,11 +4,12 @@
 * SPDX-License-Identifier: Apache-2.0
 */

-import { SandboxConfig } from '@qwen-code/qwen-code-core';
+import type { SandboxConfig } from '@qwen-code/qwen-code-core';
+import { FatalSandboxError } from '@qwen-code/qwen-code-core';
 import commandExists from 'command-exists';
 import * as os from 'node:os';
 import { getPackageJson } from '../utils/package.js';
-import { Settings } from './settings.js';
+import type { Settings } from './settings.js';

 // This is a stripped-down version of the CliArgs interface from config.ts
 // to avoid circular dependencies.
@@ -51,21 +52,19 @@ function getSandboxCommand(

  if (typeof sandbox === 'string' && sandbox) {
    if (!isSandboxCommand(sandbox)) {
-      console.error(
-        `ERROR: invalid sandbox command '${sandbox}'. Must be one of ${VALID_SANDBOX_COMMANDS.join(
+      throw new FatalSandboxError(
+        `Invalid sandbox command '${sandbox}'. Must be one of ${VALID_SANDBOX_COMMANDS.join(
          ', ',
        )}`,
      );
-      process.exit(1);
    }
    // confirm that specified command exists
    if (commandExists.sync(sandbox)) {
      return sandbox;
    }
-    console.error(
-      `ERROR: missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)`,
+    throw new FatalSandboxError(
+      `Missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)`,
    );
-    process.exit(1);
  }

  // look for seatbelt, docker, or podman, in that order
@@ -80,11 +79,10 @@ function getSandboxCommand(

  // throw an error if user requested sandbox but no command was found
  if (sandbox === true) {
-    console.error(
-      'ERROR: GEMINI_SANDBOX is true but failed to determine command for sandbox; ' +
+    throw new FatalSandboxError(
+      'GEMINI_SANDBOX is true but failed to determine command for sandbox; ' +
        'install docker or podman or specify command in GEMINI_SANDBOX',
    );
-    process.exit(1);
  }

  return '';
@@ -94,7 +92,7 @@ export async function loadSandboxConfig(
  settings: Settings,
  argv: SandboxCliArgs,
 ): Promise<SandboxConfig | undefined> {
-  const sandboxOption = argv.sandbox ?? settings.sandbox;
+  const sandboxOption = argv.sandbox ?? settings.tools?.sandbox;
  const command = getSandboxCommand(sandboxOption);

  const packageJson = await getPackageJson();
--- a/packages/cli/src/config/settings.test.ts
+++ b/packages/cli/src/config/settings.test.ts
--- a/packages/cli/src/config/settings.ts
+++ b/packages/cli/src/config/settings.ts
@@ -4,29 +4,84 @@
 * SPDX-License-Identifier: Apache-2.0
 */

-import * as fs from 'fs';
-import * as path from 'path';
-import { homedir, platform } from 'os';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { homedir, platform } from 'node:os';
 import * as dotenv from 'dotenv';
 import {
  GEMINI_CONFIG_DIR as GEMINI_DIR,
  getErrorMessage,
+  Storage,
 } from '@qwen-code/qwen-code-core';
 import stripJsonComments from 'strip-json-comments';
 import { DefaultLight } from '../ui/themes/default-light.js';
 import { DefaultDark } from '../ui/themes/default.js';
-import { Settings, MemoryImportFormat } from './settingsSchema.js';
+import { isWorkspaceTrusted } from './trustedFolders.js';
+import type { Settings, MemoryImportFormat } from './settingsSchema.js';
+import { mergeWith } from 'lodash-es';

 export type { Settings, MemoryImportFormat };

 export const SETTINGS_DIRECTORY_NAME = '.qwen';
-export const USER_SETTINGS_DIR = path.join(homedir(), SETTINGS_DIRECTORY_NAME);
-export const USER_SETTINGS_PATH = path.join(USER_SETTINGS_DIR, 'settings.json');
+export const USER_SETTINGS_PATH = Storage.getGlobalSettingsPath();
+export const USER_SETTINGS_DIR = path.dirname(USER_SETTINGS_PATH);
 export const DEFAULT_EXCLUDED_ENV_VARS = ['DEBUG', 'DEBUG_MODE'];

+const MIGRATE_V2_OVERWRITE = false;
+
+const MIGRATION_MAP: Record<string, string> = {
+  preferredEditor: 'general.preferredEditor',
+  vimMode: 'general.vimMode',
+  disableAutoUpdate: 'general.disableAutoUpdate',
+  disableUpdateNag: 'general.disableUpdateNag',
+  checkpointing: 'general.checkpointing',
+  theme: 'ui.theme',
+  customThemes: 'ui.customThemes',
+  hideWindowTitle: 'ui.hideWindowTitle',
+  hideTips: 'ui.hideTips',
+  hideBanner: 'ui.hideBanner',
+  hideFooter: 'ui.hideFooter',
+  showMemoryUsage: 'ui.showMemoryUsage',
+  showLineNumbers: 'ui.showLineNumbers',
+  accessibility: 'ui.accessibility',
+  ideMode: 'ide.enabled',
+  hasSeenIdeIntegrationNudge: 'ide.hasSeenNudge',
+  usageStatisticsEnabled: 'privacy.usageStatisticsEnabled',
+  telemetry: 'telemetry',
+  model: 'model.name',
+  maxSessionTurns: 'model.maxSessionTurns',
+  summarizeToolOutput: 'model.summarizeToolOutput',
+  chatCompression: 'model.chatCompression',
+  skipNextSpeakerCheck: 'model.skipNextSpeakerCheck',
+  contextFileName: 'context.fileName',
+  memoryImportFormat: 'context.importFormat',
+  memoryDiscoveryMaxDirs: 'context.discoveryMaxDirs',
+  includeDirectories: 'context.includeDirectories',
+  loadMemoryFromIncludeDirectories: 'context.loadFromIncludeDirectories',
+  fileFiltering: 'context.fileFiltering',
+  sandbox: 'tools.sandbox',
+  shouldUseNodePtyShell: 'tools.usePty',
+  allowedTools: 'tools.allowed',
+  coreTools: 'tools.core',
+  excludeTools: 'tools.exclude',
+  toolDiscoveryCommand: 'tools.discoveryCommand',
+  toolCallCommand: 'tools.callCommand',
+  mcpServerCommand: 'mcp.serverCommand',
+  allowMCPServers: 'mcp.allowed',
+  excludeMCPServers: 'mcp.excluded',
+  folderTrustFeature: 'security.folderTrust.featureEnabled',
+  folderTrust: 'security.folderTrust.enabled',
+  selectedAuthType: 'security.auth.selectedType',
+  useExternalAuth: 'security.auth.useExternal',
+  autoConfigureMaxOldSpaceSize: 'advanced.autoConfigureMemory',
+  dnsResolutionOrder: 'advanced.dnsResolutionOrder',
+  excludedProjectEnvVars: 'advanced.excludedEnvVars',
+  bugCommand: 'advanced.bugCommand',
+};
+
 export function getSystemSettingsPath(): string {
-  if (process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH']) {
-    return process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH'];
+  if (process.env['QWEN_CODE_SYSTEM_SETTINGS_PATH']) {
+    return process.env['QWEN_CODE_SYSTEM_SETTINGS_PATH'];
  }
  if (platform() === 'darwin') {
    return '/Library/Application Support/QwenCode/settings.json';
@@ -37,8 +92,14 @@ export function getSystemSettingsPath(): string {
  }
 }

-export function getWorkspaceSettingsPath(workspaceDir: string): string {
-  return path.join(workspaceDir, SETTINGS_DIRECTORY_NAME, 'settings.json');
+export function getSystemDefaultsPath(): string {
+  if (process.env['QWEN_CODE_SYSTEM_DEFAULTS_PATH']) {
+    return process.env['QWEN_CODE_SYSTEM_DEFAULTS_PATH'];
+  }
+  return path.join(
+    path.dirname(getSystemSettingsPath()),
+    'system-defaults.json',
+  );
 }

 export type { DnsResolutionOrder } from './settingsSchema.js';
@@ -47,6 +108,7 @@ export enum SettingScope {
  User = 'User',
  Workspace = 'Workspace',
  System = 'System',
+  SystemDefaults = 'SystemDefaults',
 }

 export interface CheckpointingSettings {
@@ -59,6 +121,7 @@ export interface SummarizeToolOutputSettings {

 export interface AccessibilitySettings {
  disableLoadingPhrases?: boolean;
+  screenReader?: boolean;
 }

 export interface SettingsError {
@@ -71,38 +134,290 @@ export interface SettingsFile {
  path: string;
 }

+function setNestedProperty(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+) {
+  const keys = path.split('.');
+  const lastKey = keys.pop();
+  if (!lastKey) return;
+
+  let current: Record<string, unknown> = obj;
+  for (const key of keys) {
+    if (current[key] === undefined) {
+      current[key] = {};
+    }
+    const next = current[key];
+    if (typeof next === 'object' && next !== null) {
+      current = next as Record<string, unknown>;
+    } else {
+      // This path is invalid, so we stop.
+      return;
+    }
+  }
+  current[lastKey] = value;
+}
+
+function needsMigration(settings: Record<string, unknown>): boolean {
+  return !('general' in settings);
+}
+
+function migrateSettingsToV2(
+  flatSettings: Record<string, unknown>,
+): Record<string, unknown> | null {
+  if (!needsMigration(flatSettings)) {
+    return null;
+  }
+
+  const v2Settings: Record<string, unknown> = {};
+  const flatKeys = new Set(Object.keys(flatSettings));
+
+  for (const [oldKey, newPath] of Object.entries(MIGRATION_MAP)) {
+    if (flatKeys.has(oldKey)) {
+      setNestedProperty(v2Settings, newPath, flatSettings[oldKey]);
+      flatKeys.delete(oldKey);
+    }
+  }
+
+  // Preserve mcpServers at the top level
+  if (flatSettings['mcpServers']) {
+    v2Settings['mcpServers'] = flatSettings['mcpServers'];
+    flatKeys.delete('mcpServers');
+  }
+
+  // Carry over any unrecognized keys
+  for (const remainingKey of flatKeys) {
+    v2Settings[remainingKey] = flatSettings[remainingKey];
+  }
+
+  return v2Settings;
+}
+
+function getNestedProperty(
+  obj: Record<string, unknown>,
+  path: string,
+): unknown {
+  const keys = path.split('.');
+  let current: unknown = obj;
+  for (const key of keys) {
+    if (typeof current !== 'object' || current === null || !(key in current)) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+const REVERSE_MIGRATION_MAP: Record<string, string> = Object.fromEntries(
+  Object.entries(MIGRATION_MAP).map(([key, value]) => [value, key]),
+);
+
+// Dynamically determine the top-level keys from the V2 settings structure.
+const KNOWN_V2_CONTAINERS = new Set(
+  Object.values(MIGRATION_MAP).map((path) => path.split('.')[0]),
+);
+
+export function migrateSettingsToV1(
+  v2Settings: Record<string, unknown>,
+): Record<string, unknown> {
+  const v1Settings: Record<string, unknown> = {};
+  const v2Keys = new Set(Object.keys(v2Settings));
+
+  for (const [newPath, oldKey] of Object.entries(REVERSE_MIGRATION_MAP)) {
+    const value = getNestedProperty(v2Settings, newPath);
+    if (value !== undefined) {
+      v1Settings[oldKey] = value;
+      v2Keys.delete(newPath.split('.')[0]);
+    }
+  }
+
+  // Preserve mcpServers at the top level
+  if (v2Settings['mcpServers']) {
+    v1Settings['mcpServers'] = v2Settings['mcpServers'];
+    v2Keys.delete('mcpServers');
+  }
+
+  // Carry over any unrecognized keys
+  for (const remainingKey of v2Keys) {
+    const value = v2Settings[remainingKey];
+    if (value === undefined) {
+      continue;
+    }
+
+    // Don't carry over empty objects that were just containers for migrated settings.
+    if (
+      KNOWN_V2_CONTAINERS.has(remainingKey) &&
+      typeof value === 'object' &&
+      value !== null &&
+      !Array.isArray(value) &&
+      Object.keys(value).length === 0
+    ) {
+      continue;
+    }
+
+    v1Settings[remainingKey] = value;
+  }
+
+  return v1Settings;
+}
+
 function mergeSettings(
  system: Settings,
+  systemDefaults: Settings,
  user: Settings,
  workspace: Settings,
+  isTrusted: boolean,
 ): Settings {
-  // folderTrust is not supported at workspace level.
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { folderTrust, ...workspaceWithoutFolderTrust } = workspace;
+  const safeWorkspace = isTrusted ? workspace : ({} as Settings);

+  // folderTrust is not supported at workspace level.
+  const { security, ...restOfWorkspace } = safeWorkspace;
+  const safeWorkspaceWithoutFolderTrust = security
+    ? {
+        ...restOfWorkspace,
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        security: (({ folderTrust, ...rest }) => rest)(security),
+      }
+    : {
+        ...restOfWorkspace,
+        security: {},
+      };
+
+  // Settings are merged with the following precedence (last one wins for
+  // single values):
+  // 1. System Defaults
+  // 2. User Settings
+  // 3. Workspace Settings
+  // 4. System Settings (as overrides)
+  //
+  // For properties that are arrays (e.g., includeDirectories), the arrays
+  // are concatenated. For objects (e.g., customThemes), they are merged.
  return {
+    ...systemDefaults,
    ...user,
-    ...workspaceWithoutFolderTrust,
+    ...safeWorkspaceWithoutFolderTrust,
    ...system,
-    customThemes: {
-      ...(user.customThemes || {}),
-      ...(workspace.customThemes || {}),
-      ...(system.customThemes || {}),
+    general: {
+      ...(systemDefaults.general || {}),
+      ...(user.general || {}),
+      ...(safeWorkspaceWithoutFolderTrust.general || {}),
+      ...(system.general || {}),
+    },
+    ui: {
+      ...(systemDefaults.ui || {}),
+      ...(user.ui || {}),
+      ...(safeWorkspaceWithoutFolderTrust.ui || {}),
+      ...(system.ui || {}),
+      customThemes: {
+        ...(systemDefaults.ui?.customThemes || {}),
+        ...(user.ui?.customThemes || {}),
+        ...(safeWorkspaceWithoutFolderTrust.ui?.customThemes || {}),
+        ...(system.ui?.customThemes || {}),
+      },
+    },
+    ide: {
+      ...(systemDefaults.ide || {}),
+      ...(user.ide || {}),
+      ...(safeWorkspaceWithoutFolderTrust.ide || {}),
+      ...(system.ide || {}),
+    },
+    privacy: {
+      ...(systemDefaults.privacy || {}),
+      ...(user.privacy || {}),
+      ...(safeWorkspaceWithoutFolderTrust.privacy || {}),
+      ...(system.privacy || {}),
+    },
+    telemetry: {
+      ...(systemDefaults.telemetry || {}),
+      ...(user.telemetry || {}),
+      ...(safeWorkspaceWithoutFolderTrust.telemetry || {}),
+      ...(system.telemetry || {}),
+    },
+    security: {
+      ...(systemDefaults.security || {}),
+      ...(user.security || {}),
+      ...(safeWorkspaceWithoutFolderTrust.security || {}),
+      ...(system.security || {}),
+    },
+    mcp: {
+      ...(systemDefaults.mcp || {}),
+      ...(user.mcp || {}),
+      ...(safeWorkspaceWithoutFolderTrust.mcp || {}),
+      ...(system.mcp || {}),
    },
    mcpServers: {
+      ...(systemDefaults.mcpServers || {}),
      ...(user.mcpServers || {}),
-      ...(workspace.mcpServers || {}),
+      ...(safeWorkspaceWithoutFolderTrust.mcpServers || {}),
      ...(system.mcpServers || {}),
    },
-    includeDirectories: [
-      ...(system.includeDirectories || []),
-      ...(user.includeDirectories || []),
-      ...(workspace.includeDirectories || []),
-    ],
-    chatCompression: {
-      ...(system.chatCompression || {}),
-      ...(user.chatCompression || {}),
-      ...(workspace.chatCompression || {}),
+    tools: {
+      ...(systemDefaults.tools || {}),
+      ...(user.tools || {}),
+      ...(safeWorkspaceWithoutFolderTrust.tools || {}),
+      ...(system.tools || {}),
+    },
+    context: {
+      ...(systemDefaults.context || {}),
+      ...(user.context || {}),
+      ...(safeWorkspaceWithoutFolderTrust.context || {}),
+      ...(system.context || {}),
+      includeDirectories: [
+        ...(systemDefaults.context?.includeDirectories || []),
+        ...(user.context?.includeDirectories || []),
+        ...(safeWorkspaceWithoutFolderTrust.context?.includeDirectories || []),
+        ...(system.context?.includeDirectories || []),
+      ],
+    },
+    model: {
+      ...(systemDefaults.model || {}),
+      ...(user.model || {}),
+      ...(safeWorkspaceWithoutFolderTrust.model || {}),
+      ...(system.model || {}),
+      chatCompression: {
+        ...(systemDefaults.model?.chatCompression || {}),
+        ...(user.model?.chatCompression || {}),
+        ...(safeWorkspaceWithoutFolderTrust.model?.chatCompression || {}),
+        ...(system.model?.chatCompression || {}),
+      },
+    },
+    advanced: {
+      ...(systemDefaults.advanced || {}),
+      ...(user.advanced || {}),
+      ...(safeWorkspaceWithoutFolderTrust.advanced || {}),
+      ...(system.advanced || {}),
+      excludedEnvVars: [
+        ...new Set([
+          ...(systemDefaults.advanced?.excludedEnvVars || []),
+          ...(user.advanced?.excludedEnvVars || []),
+          ...(safeWorkspaceWithoutFolderTrust.advanced?.excludedEnvVars || []),
+          ...(system.advanced?.excludedEnvVars || []),
+        ]),
+      ],
+    },
+    extensions: {
+      ...(systemDefaults.extensions || {}),
+      ...(user.extensions || {}),
+      ...(safeWorkspaceWithoutFolderTrust.extensions || {}),
+      ...(system.extensions || {}),
+      disabled: [
+        ...new Set([
+          ...(systemDefaults.extensions?.disabled || []),
+          ...(user.extensions?.disabled || []),
+          ...(safeWorkspaceWithoutFolderTrust.extensions?.disabled || []),
+          ...(system.extensions?.disabled || []),
+        ]),
+      ],
+      workspacesWithMigrationNudge: [
+        ...new Set([
+          ...(systemDefaults.extensions?.workspacesWithMigrationNudge || []),
+          ...(user.extensions?.workspacesWithMigrationNudge || []),
+          ...(safeWorkspaceWithoutFolderTrust.extensions
+            ?.workspacesWithMigrationNudge || []),
+          ...(system.extensions?.workspacesWithMigrationNudge || []),
+        ]),
+      ],
    },
  };
 }
@@ -110,21 +425,30 @@ function mergeSettings(
 export class LoadedSettings {
  constructor(
    system: SettingsFile,
+    systemDefaults: SettingsFile,
    user: SettingsFile,
    workspace: SettingsFile,
    errors: SettingsError[],
+    isTrusted: boolean,
+    migratedInMemorScopes: Set<SettingScope>,
  ) {
    this.system = system;
+    this.systemDefaults = systemDefaults;
    this.user = user;
    this.workspace = workspace;
    this.errors = errors;
+    this.isTrusted = isTrusted;
+    this.migratedInMemorScopes = migratedInMemorScopes;
    this._merged = this.computeMergedSettings();
  }

  readonly system: SettingsFile;
+  readonly systemDefaults: SettingsFile;
  readonly user: SettingsFile;
  readonly workspace: SettingsFile;
  readonly errors: SettingsError[];
+  readonly isTrusted: boolean;
+  readonly migratedInMemorScopes: Set<SettingScope>;

  private _merged: Settings;

@@ -135,8 +459,10 @@ export class LoadedSettings {
  private computeMergedSettings(): Settings {
    return mergeSettings(
      this.system.settings,
+      this.systemDefaults.settings,
      this.user.settings,
      this.workspace.settings,
+      this.isTrusted,
    );
  }

@@ -148,18 +474,16 @@ export class LoadedSettings {
        return this.workspace;
      case SettingScope.System:
        return this.system;
+      case SettingScope.SystemDefaults:
+        return this.systemDefaults;
      default:
        throw new Error(`Invalid scope: ${scope}`);
    }
  }

-  setValue<K extends keyof Settings>(
-    scope: SettingScope,
-    key: K,
-    value: Settings[K],
-  ): void {
+  setValue(scope: SettingScope, key: string, value: unknown): void {
    const settingsFile = this.forScope(scope);
-    settingsFile.settings[key] = value;
+    setNestedProperty(settingsFile.settings, key, value);
    this._merged = this.computeMergedSettings();
    saveSettings(settingsFile);
  }
@@ -269,7 +593,9 @@ export function loadEnvironment(settings?: Settings): void {
  // If no settings provided, try to load workspace settings for exclusions
  let resolvedSettings = settings;
  if (!resolvedSettings) {
-    const workspaceSettingsPath = getWorkspaceSettingsPath(process.cwd());
+    const workspaceSettingsPath = new Storage(
+      process.cwd(),
+    ).getWorkspaceSettingsPath();
    try {
      if (fs.existsSync(workspaceSettingsPath)) {
        const workspaceContent = fs.readFileSync(
@@ -294,7 +620,8 @@ export function loadEnvironment(settings?: Settings): void {
      const parsedEnv = dotenv.parse(envFileContent);

      const excludedVars =
-        resolvedSettings?.excludedProjectEnvVars || DEFAULT_EXCLUDED_ENV_VARS;
+        resolvedSettings?.advanced?.excludedEnvVars ||
+        DEFAULT_EXCLUDED_ENV_VARS;
      const isProjectEnvFile = !envFilePath.includes(GEMINI_DIR);

      for (const key in parsedEnv) {
@@ -322,10 +649,13 @@ export function loadEnvironment(settings?: Settings): void {
 */
 export function loadSettings(workspaceDir: string): LoadedSettings {
  let systemSettings: Settings = {};
+  let systemDefaultSettings: Settings = {};
  let userSettings: Settings = {};
  let workspaceSettings: Settings = {};
  const settingsErrors: SettingsError[] = [];
  const systemSettingsPath = getSystemSettingsPath();
+  const systemDefaultsPath = getSystemDefaultsPath();
+  const migratedInMemorScopes = new Set<SettingScope>();

  // Resolve paths to their canonical representation to handle symlinks
  const resolvedWorkspaceDir = path.resolve(workspaceDir);
@@ -342,70 +672,102 @@ export function loadSettings(workspaceDir: string): LoadedSettings {
  // We expect homedir to always exist and be resolvable.
  const realHomeDir = fs.realpathSync(resolvedHomeDir);

-  const workspaceSettingsPath = getWorkspaceSettingsPath(workspaceDir);
+  const workspaceSettingsPath = new Storage(
+    workspaceDir,
+  ).getWorkspaceSettingsPath();

-  // Load system settings
-  try {
-    if (fs.existsSync(systemSettingsPath)) {
-      const systemContent = fs.readFileSync(systemSettingsPath, 'utf-8');
-      systemSettings = JSON.parse(stripJsonComments(systemContent)) as Settings;
-    }
-  } catch (error: unknown) {
-    settingsErrors.push({
-      message: getErrorMessage(error),
-      path: systemSettingsPath,
-    });
-  }
-
-  // Load user settings
-  try {
-    if (fs.existsSync(USER_SETTINGS_PATH)) {
-      const userContent = fs.readFileSync(USER_SETTINGS_PATH, 'utf-8');
-      userSettings = JSON.parse(stripJsonComments(userContent)) as Settings;
-      // Support legacy theme names
-      if (userSettings.theme && userSettings.theme === 'VS') {
-        userSettings.theme = DefaultLight.name;
-      } else if (userSettings.theme && userSettings.theme === 'VS2015') {
-        userSettings.theme = DefaultDark.name;
-      }
-    }
-  } catch (error: unknown) {
-    settingsErrors.push({
-      message: getErrorMessage(error),
-      path: USER_SETTINGS_PATH,
-    });
-  }
-
-  if (realWorkspaceDir !== realHomeDir) {
-    // Load workspace settings
+  const loadAndMigrate = (filePath: string, scope: SettingScope): Settings => {
    try {
-      if (fs.existsSync(workspaceSettingsPath)) {
-        const projectContent = fs.readFileSync(workspaceSettingsPath, 'utf-8');
-        workspaceSettings = JSON.parse(
-          stripJsonComments(projectContent),
-        ) as Settings;
-        if (workspaceSettings.theme && workspaceSettings.theme === 'VS') {
-          workspaceSettings.theme = DefaultLight.name;
-        } else if (
-          workspaceSettings.theme &&
-          workspaceSettings.theme === 'VS2015'
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const rawSettings: unknown = JSON.parse(stripJsonComments(content));
+
+        if (
+          typeof rawSettings !== 'object' ||
+          rawSettings === null ||
+          Array.isArray(rawSettings)
        ) {
-          workspaceSettings.theme = DefaultDark.name;
+          settingsErrors.push({
+            message: 'Settings file is not a valid JSON object.',
+            path: filePath,
+          });
+          return {};
        }
+
+        let settingsObject = rawSettings as Record<string, unknown>;
+        if (needsMigration(settingsObject)) {
+          const migratedSettings = migrateSettingsToV2(settingsObject);
+          if (migratedSettings) {
+            if (MIGRATE_V2_OVERWRITE) {
+              try {
+                fs.renameSync(filePath, `${filePath}.orig`);
+                fs.writeFileSync(
+                  filePath,
+                  JSON.stringify(migratedSettings, null, 2),
+                  'utf-8',
+                );
+              } catch (e) {
+                console.error(
+                  `Error migrating settings file on disk: ${getErrorMessage(
+                    e,
+                  )}`,
+                );
+              }
+            } else {
+              migratedInMemorScopes.add(scope);
+            }
+            settingsObject = migratedSettings;
+          }
+        }
+        return settingsObject as Settings;
      }
    } catch (error: unknown) {
      settingsErrors.push({
        message: getErrorMessage(error),
-        path: workspaceSettingsPath,
+        path: filePath,
      });
    }
+    return {};
+  };
+
+  systemSettings = loadAndMigrate(systemSettingsPath, SettingScope.System);
+  systemDefaultSettings = loadAndMigrate(
+    systemDefaultsPath,
+    SettingScope.SystemDefaults,
+  );
+  userSettings = loadAndMigrate(USER_SETTINGS_PATH, SettingScope.User);
+
+  if (realWorkspaceDir !== realHomeDir) {
+    workspaceSettings = loadAndMigrate(
+      workspaceSettingsPath,
+      SettingScope.Workspace,
+    );
  }

+  // Support legacy theme names
+  if (userSettings.ui?.theme === 'VS') {
+    userSettings.ui.theme = DefaultLight.name;
+  } else if (userSettings.ui?.theme === 'VS2015') {
+    userSettings.ui.theme = DefaultDark.name;
+  }
+  if (workspaceSettings.ui?.theme === 'VS') {
+    workspaceSettings.ui.theme = DefaultLight.name;
+  } else if (workspaceSettings.ui?.theme === 'VS2015') {
+    workspaceSettings.ui.theme = DefaultDark.name;
+  }
+
+  // For the initial trust check, we can only use user and system settings.
+  const initialTrustCheckSettings = mergeWith({}, systemSettings, userSettings);
+  const isTrusted =
+    isWorkspaceTrusted(initialTrustCheckSettings as Settings) ?? true;
+
  // Create a temporary merged settings object to pass to loadEnvironment.
  const tempMergedSettings = mergeSettings(
    systemSettings,
+    systemDefaultSettings,
    userSettings,
    workspaceSettings,
+    isTrusted,
  );

  // loadEnviroment depends on settings so we have to create a temp version of
@@ -423,6 +785,10 @@ export function loadSettings(workspaceDir: string): LoadedSettings {
      path: systemSettingsPath,
      settings: systemSettings,
    },
+    {
+      path: systemDefaultsPath,
+      settings: systemDefaultSettings,
+    },
    {
      path: USER_SETTINGS_PATH,
      settings: userSettings,
@@ -432,21 +798,10 @@ export function loadSettings(workspaceDir: string): LoadedSettings {
      settings: workspaceSettings,
    },
    settingsErrors,
+    isTrusted,
+    migratedInMemorScopes,
  );

-  // Validate chatCompression settings
-  const chatCompression = loadedSettings.merged.chatCompression;
-  const threshold = chatCompression?.contextPercentageThreshold;
-  if (
-    threshold != null &&
-    (typeof threshold !== 'number' || threshold < 0 || threshold > 1)
-  ) {
-    console.warn(
-      `Invalid value for chatCompression.contextPercentageThreshold: "${threshold}". Please use a value between 0 and 1. Using default compression settings.`,
-    );
-    delete loadedSettings.merged.chatCompression;
-  }
-
  return loadedSettings;
 }

@@ -458,9 +813,16 @@ export function saveSettings(settingsFile: SettingsFile): void {
      fs.mkdirSync(dirPath, { recursive: true });
    }

+    let settingsToSave = settingsFile.settings;
+    if (!MIGRATE_V2_OVERWRITE) {
+      settingsToSave = migrateSettingsToV1(
+        settingsToSave as Record<string, unknown>,
+      ) as Settings;
+    }
+
    fs.writeFileSync(
      settingsFile.path,
-      JSON.stringify(settingsFile.settings, null, 2),
+      JSON.stringify(settingsToSave, null, 2),
      'utf-8',
    );
  } catch (error) {
--- a/packages/cli/src/config/settingsSchema.test.ts
+++ b/packages/cli/src/config/settingsSchema.test.ts
@@ -5,53 +5,25 @@
 */

 import { describe, it, expect } from 'vitest';
-import { SETTINGS_SCHEMA, Settings } from './settingsSchema.js';
+import type { Settings } from './settingsSchema.js';
+import { SETTINGS_SCHEMA } from './settingsSchema.js';

 describe('SettingsSchema', () => {
  describe('SETTINGS_SCHEMA', () => {
    it('should contain all expected top-level settings', () => {
      const expectedSettings = [
-        'theme',
-        'customThemes',
-        'showMemoryUsage',
-        'usageStatisticsEnabled',
-        'autoConfigureMaxOldSpaceSize',
-        'preferredEditor',
-        'maxSessionTurns',
-        'memoryImportFormat',
-        'memoryDiscoveryMaxDirs',
-        'contextFileName',
-        'vimMode',
-        'ideMode',
-        'accessibility',
-        'checkpointing',
-        'fileFiltering',
-        'disableAutoUpdate',
-        'hideWindowTitle',
-        'hideTips',
-        'hideBanner',
-        'selectedAuthType',
-        'useExternalAuth',
-        'sandbox',
-        'coreTools',
-        'excludeTools',
-        'toolDiscoveryCommand',
-        'toolCallCommand',
-        'mcpServerCommand',
        'mcpServers',
-        'allowMCPServers',
-        'excludeMCPServers',
+        'general',
+        'ui',
+        'ide',
+        'privacy',
        'telemetry',
-        'bugCommand',
-        'summarizeToolOutput',
-        'dnsResolutionOrder',
-        'excludedProjectEnvVars',
-        'disableUpdateNag',
-        'includeDirectories',
-        'loadMemoryFromIncludeDirectories',
        'model',
-        'hasSeenIdeIntegrationNudge',
-        'folderTrustFeature',
+        'context',
+        'tools',
+        'mcp',
+        'security',
+        'advanced',
      ];

      expectedSettings.forEach((setting) => {
@@ -77,9 +49,16 @@ describe('SettingsSchema', () => {

    it('should have correct nested setting structure', () => {
      const nestedSettings = [
-        'accessibility',
-        'checkpointing',
-        'fileFiltering',
+        'general',
+        'ui',
+        'ide',
+        'privacy',
+        'model',
+        'context',
+        'tools',
+        'mcp',
+        'security',
+        'advanced',
      ];

      nestedSettings.forEach((setting) => {
@@ -96,29 +75,36 @@ describe('SettingsSchema', () => {

    it('should have accessibility nested properties', () => {
      expect(
-        SETTINGS_SCHEMA.accessibility.properties?.disableLoadingPhrases,
+        SETTINGS_SCHEMA.ui?.properties?.accessibility?.properties,
      ).toBeDefined();
      expect(
-        SETTINGS_SCHEMA.accessibility.properties?.disableLoadingPhrases.type,
+        SETTINGS_SCHEMA.ui?.properties?.accessibility.properties
+          ?.disableLoadingPhrases.type,
      ).toBe('boolean');
    });

    it('should have checkpointing nested properties', () => {
-      expect(SETTINGS_SCHEMA.checkpointing.properties?.enabled).toBeDefined();
-      expect(SETTINGS_SCHEMA.checkpointing.properties?.enabled.type).toBe(
-        'boolean',
-      );
+      expect(
+        SETTINGS_SCHEMA.general?.properties?.checkpointing.properties?.enabled,
+      ).toBeDefined();
+      expect(
+        SETTINGS_SCHEMA.general?.properties?.checkpointing.properties?.enabled
+          .type,
+      ).toBe('boolean');
    });

    it('should have fileFiltering nested properties', () => {
      expect(
-        SETTINGS_SCHEMA.fileFiltering.properties?.respectGitIgnore,
+        SETTINGS_SCHEMA.context.properties.fileFiltering.properties
+          ?.respectGitIgnore,
      ).toBeDefined();
      expect(
-        SETTINGS_SCHEMA.fileFiltering.properties?.respectGeminiIgnore,
+        SETTINGS_SCHEMA.context.properties.fileFiltering.properties
+          ?.respectGeminiIgnore,
      ).toBeDefined();
      expect(
-        SETTINGS_SCHEMA.fileFiltering.properties?.enableRecursiveFileSearch,
+        SETTINGS_SCHEMA.context.properties.fileFiltering.properties
+          ?.enableRecursiveFileSearch,
      ).toBeDefined();
    });

@@ -147,11 +133,6 @@ describe('SettingsSchema', () => {
      expect(categories.size).toBeGreaterThan(0);
      expect(categories).toContain('General');
      expect(categories).toContain('UI');
-      expect(categories).toContain('Mode');
-      expect(categories).toContain('Updates');
-      expect(categories).toContain('Accessibility');
-      expect(categories).toContain('Checkpointing');
-      expect(categories).toContain('File Filtering');
      expect(categories).toContain('Advanced');
    });

@@ -180,73 +161,148 @@ describe('SettingsSchema', () => {

    it('should have showInDialog property configured', () => {
      // Check that user-facing settings are marked for dialog display
-      expect(SETTINGS_SCHEMA.showMemoryUsage.showInDialog).toBe(true);
-      expect(SETTINGS_SCHEMA.vimMode.showInDialog).toBe(true);
-      expect(SETTINGS_SCHEMA.ideMode.showInDialog).toBe(true);
-      expect(SETTINGS_SCHEMA.disableAutoUpdate.showInDialog).toBe(true);
-      expect(SETTINGS_SCHEMA.hideWindowTitle.showInDialog).toBe(true);
-      expect(SETTINGS_SCHEMA.hideTips.showInDialog).toBe(true);
-      expect(SETTINGS_SCHEMA.hideBanner.showInDialog).toBe(true);
-      expect(SETTINGS_SCHEMA.usageStatisticsEnabled.showInDialog).toBe(false);
+      expect(SETTINGS_SCHEMA.ui.properties.showMemoryUsage.showInDialog).toBe(
+        true,
+      );
+      expect(SETTINGS_SCHEMA.general.properties.vimMode.showInDialog).toBe(
+        true,
+      );
+      expect(SETTINGS_SCHEMA.ide.properties.enabled.showInDialog).toBe(true);
+      expect(
+        SETTINGS_SCHEMA.general.properties.disableAutoUpdate.showInDialog,
+      ).toBe(true);
+      expect(SETTINGS_SCHEMA.ui.properties.hideWindowTitle.showInDialog).toBe(
+        true,
+      );
+      expect(SETTINGS_SCHEMA.ui.properties.hideTips.showInDialog).toBe(true);
+      expect(SETTINGS_SCHEMA.ui.properties.hideBanner.showInDialog).toBe(true);
+      expect(
+        SETTINGS_SCHEMA.privacy.properties.usageStatisticsEnabled.showInDialog,
+      ).toBe(false);

      // Check that advanced settings are hidden from dialog
-      expect(SETTINGS_SCHEMA.selectedAuthType.showInDialog).toBe(false);
-      expect(SETTINGS_SCHEMA.coreTools.showInDialog).toBe(false);
+      expect(SETTINGS_SCHEMA.security.properties.auth.showInDialog).toBe(false);
+      expect(SETTINGS_SCHEMA.tools.properties.core.showInDialog).toBe(false);
      expect(SETTINGS_SCHEMA.mcpServers.showInDialog).toBe(false);
      expect(SETTINGS_SCHEMA.telemetry.showInDialog).toBe(false);

      // Check that some settings are appropriately hidden
-      expect(SETTINGS_SCHEMA.theme.showInDialog).toBe(false); // Changed to false
-      expect(SETTINGS_SCHEMA.customThemes.showInDialog).toBe(false); // Managed via theme editor
-      expect(SETTINGS_SCHEMA.checkpointing.showInDialog).toBe(false); // Experimental feature
-      expect(SETTINGS_SCHEMA.accessibility.showInDialog).toBe(false); // Changed to false
-      expect(SETTINGS_SCHEMA.fileFiltering.showInDialog).toBe(false); // Changed to false
-      expect(SETTINGS_SCHEMA.preferredEditor.showInDialog).toBe(false); // Changed to false
-      expect(SETTINGS_SCHEMA.autoConfigureMaxOldSpaceSize.showInDialog).toBe(
-        true,
-      );
+      expect(SETTINGS_SCHEMA.ui.properties.theme.showInDialog).toBe(false); // Changed to false
+      expect(SETTINGS_SCHEMA.ui.properties.customThemes.showInDialog).toBe(
+        false,
+      ); // Managed via theme editor
+      expect(
+        SETTINGS_SCHEMA.general.properties.checkpointing.showInDialog,
+      ).toBe(false); // Experimental feature
+      expect(SETTINGS_SCHEMA.ui.properties.accessibility.showInDialog).toBe(
+        false,
+      ); // Changed to false
+      expect(
+        SETTINGS_SCHEMA.context.properties.fileFiltering.showInDialog,
+      ).toBe(false); // Changed to false
+      expect(
+        SETTINGS_SCHEMA.general.properties.preferredEditor.showInDialog,
+      ).toBe(false); // Changed to false
+      expect(
+        SETTINGS_SCHEMA.advanced.properties.autoConfigureMemory.showInDialog,
+      ).toBe(false);
    });

    it('should infer Settings type correctly', () => {
      // This test ensures that the Settings type is properly inferred from the schema
      const settings: Settings = {
-        theme: 'dark',
-        includeDirectories: ['/path/to/dir'],
-        loadMemoryFromIncludeDirectories: true,
+        ui: {
+          theme: 'dark',
+        },
+        context: {
+          includeDirectories: ['/path/to/dir'],
+          loadMemoryFromIncludeDirectories: true,
+        },
      };

      // TypeScript should not complain about these properties
-      expect(settings.theme).toBe('dark');
-      expect(settings.includeDirectories).toEqual(['/path/to/dir']);
-      expect(settings.loadMemoryFromIncludeDirectories).toBe(true);
+      expect(settings.ui?.theme).toBe('dark');
+      expect(settings.context?.includeDirectories).toEqual(['/path/to/dir']);
+      expect(settings.context?.loadMemoryFromIncludeDirectories).toBe(true);
    });

    it('should have includeDirectories setting in schema', () => {
-      expect(SETTINGS_SCHEMA.includeDirectories).toBeDefined();
-      expect(SETTINGS_SCHEMA.includeDirectories.type).toBe('array');
-      expect(SETTINGS_SCHEMA.includeDirectories.category).toBe('General');
-      expect(SETTINGS_SCHEMA.includeDirectories.default).toEqual([]);
+      expect(
+        SETTINGS_SCHEMA.context?.properties.includeDirectories,
+      ).toBeDefined();
+      expect(SETTINGS_SCHEMA.context?.properties.includeDirectories.type).toBe(
+        'array',
+      );
+      expect(
+        SETTINGS_SCHEMA.context?.properties.includeDirectories.category,
+      ).toBe('Context');
+      expect(
+        SETTINGS_SCHEMA.context?.properties.includeDirectories.default,
+      ).toEqual([]);
    });

    it('should have loadMemoryFromIncludeDirectories setting in schema', () => {
-      expect(SETTINGS_SCHEMA.loadMemoryFromIncludeDirectories).toBeDefined();
-      expect(SETTINGS_SCHEMA.loadMemoryFromIncludeDirectories.type).toBe(
-        'boolean',
-      );
-      expect(SETTINGS_SCHEMA.loadMemoryFromIncludeDirectories.category).toBe(
-        'General',
-      );
-      expect(SETTINGS_SCHEMA.loadMemoryFromIncludeDirectories.default).toBe(
-        false,
-      );
+      expect(
+        SETTINGS_SCHEMA.context?.properties.loadMemoryFromIncludeDirectories,
+      ).toBeDefined();
+      expect(
+        SETTINGS_SCHEMA.context?.properties.loadMemoryFromIncludeDirectories
+          .type,
+      ).toBe('boolean');
+      expect(
+        SETTINGS_SCHEMA.context?.properties.loadMemoryFromIncludeDirectories
+          .category,
+      ).toBe('Context');
+      expect(
+        SETTINGS_SCHEMA.context?.properties.loadMemoryFromIncludeDirectories
+          .default,
+      ).toBe(false);
    });

    it('should have folderTrustFeature setting in schema', () => {
-      expect(SETTINGS_SCHEMA.folderTrustFeature).toBeDefined();
-      expect(SETTINGS_SCHEMA.folderTrustFeature.type).toBe('boolean');
-      expect(SETTINGS_SCHEMA.folderTrustFeature.category).toBe('General');
-      expect(SETTINGS_SCHEMA.folderTrustFeature.default).toBe(false);
-      expect(SETTINGS_SCHEMA.folderTrustFeature.showInDialog).toBe(true);
+      expect(
+        SETTINGS_SCHEMA.security.properties.folderTrust.properties.enabled,
+      ).toBeDefined();
+      expect(
+        SETTINGS_SCHEMA.security.properties.folderTrust.properties.enabled.type,
+      ).toBe('boolean');
+      expect(
+        SETTINGS_SCHEMA.security.properties.folderTrust.properties.enabled
+          .category,
+      ).toBe('Security');
+      expect(
+        SETTINGS_SCHEMA.security.properties.folderTrust.properties.enabled
+          .default,
+      ).toBe(false);
+      expect(
+        SETTINGS_SCHEMA.security.properties.folderTrust.properties.enabled
+          .showInDialog,
+      ).toBe(true);
+    });
+
+    it('should have debugKeystrokeLogging setting in schema', () => {
+      expect(
+        SETTINGS_SCHEMA.general.properties.debugKeystrokeLogging,
+      ).toBeDefined();
+      expect(
+        SETTINGS_SCHEMA.general.properties.debugKeystrokeLogging.type,
+      ).toBe('boolean');
+      expect(
+        SETTINGS_SCHEMA.general.properties.debugKeystrokeLogging.category,
+      ).toBe('General');
+      expect(
+        SETTINGS_SCHEMA.general.properties.debugKeystrokeLogging.default,
+      ).toBe(false);
+      expect(
+        SETTINGS_SCHEMA.general.properties.debugKeystrokeLogging
+          .requiresRestart,
+      ).toBe(false);
+      expect(
+        SETTINGS_SCHEMA.general.properties.debugKeystrokeLogging.showInDialog,
+      ).toBe(true);
+      expect(
+        SETTINGS_SCHEMA.general.properties.debugKeystrokeLogging.description,
+      ).toBe('Enable debug logging of keystrokes to the console.');
    });
  });
 });
--- a/packages/cli/src/config/settingsSchema.ts
+++ b/packages/cli/src/config/settingsSchema.ts
--- a/packages/cli/src/config/trustedFolders.test.ts
+++ b/packages/cli/src/config/trustedFolders.test.ts
@@ -5,7 +5,7 @@
 */

 // Mock 'os' first.
-import * as osActual from 'os';
+import * as osActual from 'node:os';
 vi.mock('os', async (importOriginal) => {
  const actualOs = await importOriginal<typeof osActual>();
  return {
@@ -25,9 +25,9 @@ import {
  type Mocked,
  type Mock,
 } from 'vitest';
-import * as fs from 'fs';
+import * as fs from 'node:fs';
 import stripJsonComments from 'strip-json-comments';
-import * as path from 'path';
+import * as path from 'node:path';

 import {
  loadTrustedFolders,
@@ -35,7 +35,7 @@ import {
  TrustLevel,
  isWorkspaceTrusted,
 } from './trustedFolders.js';
-import { Settings } from './settings.js';
+import type { Settings } from './settings.js';

 vi.mock('fs', async (importOriginal) => {
  const actualFs = await importOriginal<typeof fs>();
@@ -132,8 +132,12 @@ describe('isWorkspaceTrusted', () => {
  let mockCwd: string;
  const mockRules: Record<string, TrustLevel> = {};
  const mockSettings: Settings = {
-    folderTrustFeature: true,
-    folderTrust: true,
+    security: {
+      folderTrust: {
+        featureEnabled: true,
+        enabled: true,
+      },
+    },
  };

  beforeEach(() => {
--- a/packages/cli/src/config/trustedFolders.ts
+++ b/packages/cli/src/config/trustedFolders.ts
@@ -4,11 +4,11 @@
 * SPDX-License-Identifier: Apache-2.0
 */

-import * as fs from 'fs';
-import * as path from 'path';
-import { homedir } from 'os';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { homedir } from 'node:os';
 import { getErrorMessage, isWithinRoot } from '@qwen-code/qwen-code-core';
-import { Settings } from './settings.js';
+import type { Settings } from './settings.js';
 import stripJsonComments from 'strip-json-comments';

 export const TRUSTED_FOLDERS_FILENAME = 'trustedFolders.json';
@@ -111,8 +111,9 @@ export function saveTrustedFolders(
 }

 export function isWorkspaceTrusted(settings: Settings): boolean | undefined {
-  const folderTrustFeature = settings.folderTrustFeature ?? false;
-  const folderTrustSetting = settings.folderTrust ?? true;
+  const folderTrustFeature =
+    settings.security?.folderTrust?.featureEnabled ?? false;
+  const folderTrustSetting = settings.security?.folderTrust?.enabled ?? true;
  const folderTrustEnabled = folderTrustFeature && folderTrustSetting;

  if (!folderTrustEnabled) {