From 02adfe2bca6d2f9769dcc1426b52daee2447bd4f Mon Sep 17 00:00:00 2001
From: Jerop Kipruto <jerop@google.com>
Date: Wed, 11 Feb 2026 15:04:01 -0500
Subject: [PATCH 01/44] docs(plan): add `ask_user` tool documentation (#18830)

---
 docs/cli/plan-mode.md  |  5 ++-
 docs/tools/ask-user.md | 95 ++++++++++++++++++++++++++++++++++++++++++
 docs/tools/index.md    |  2 +
 3 files changed, 100 insertions(+), 2 deletions(-)
 create mode 100644 docs/tools/ask-user.md

diff --git a/docs/cli/plan-mode.md b/docs/cli/plan-mode.md
index 6c85515755..751794996b 100644
--- a/docs/cli/plan-mode.md
+++ b/docs/cli/plan-mode.md
@@ -68,7 +68,7 @@ You can enter Plan Mode in three ways:
 
 ### The Planning Workflow
 
-1.  **Requirements:** The agent clarifies goals using `ask_user`.
+1.  **Requirements:** The agent clarifies goals using [`ask_user`].
 2.  **Exploration:** The agent uses read-only tools (like [`read_file`]) to map
     the codebase and validate assumptions.
 3.  **Design:** The agent proposes alternative approaches with a recommended
@@ -95,7 +95,7 @@ These are the only allowed tools:
 
 - **FileSystem (Read):** [`read_file`], [`list_directory`], [`glob`]
 - **Search:** [`grep_search`], [`google_web_search`]
-- **Interaction:** `ask_user`
+- **Interaction:** [`ask_user`]
 - **MCP Tools (Read):** Read-only [MCP tools] (e.g., `github_read_issue`,
   `postgres_read_schema`) are allowed.
 - **Planning (Write):** [`write_file`] and [`replace`] ONLY allowed for `.md`
@@ -183,3 +183,4 @@ Guide].
 [Policy Engine Guide]: /docs/core/policy-engine.md
 [`enter_plan_mode`]: /docs/tools/planning.md#1-enter_plan_mode-enterplanmode
 [`exit_plan_mode`]: /docs/tools/planning.md#2-exit_plan_mode-exitplanmode
+[`ask_user`]: /docs/tools/ask-user.md
diff --git a/docs/tools/ask-user.md b/docs/tools/ask-user.md
new file mode 100644
index 0000000000..ad6c3b5a06
--- /dev/null
+++ b/docs/tools/ask-user.md
@@ -0,0 +1,95 @@
+# Ask User Tool
+
+The `ask_user` tool allows the agent to ask you one or more questions to gather
+preferences, clarify requirements, or make decisions. It supports multiple
+question types including multiple-choice, free-form text, and Yes/No
+confirmation.
+
+## `ask_user` (Ask User)
+
+- **Tool name:** `ask_user`
+- **Display name:** Ask User
+- **File:** `ask-user.ts`
+- **Parameters:**
+  - `questions` (array of objects, required): A list of 1 to 4 questions to ask.
+    Each question object has the following properties:
+    - `question` (string, required): The complete question text.
+    - `header` (string, required): A short label (max 16 chars) displayed as a
+      chip/tag (e.g., "Auth", "Database").
+    - `type` (string, optional): The type of question. Defaults to `'choice'`.
+      - `'choice'`: Multiple-choice with options (supports multi-select).
+      - `'text'`: Free-form text input.
+      - `'yesno'`: Yes/No confirmation.
+    - `options` (array of objects, optional): Required for `'choice'` type. 2-4
+      selectable options.
+      - `label` (string, required): Display text (1-5 words).
+      - `description` (string, required): Brief explanation.
+    - `multiSelect` (boolean, optional): For `'choice'` type, allows selecting
+      multiple options.
+    - `placeholder` (string, optional): Hint text for input fields.
+
+- **Behavior:**
+  - Presents an interactive dialog to the user with the specified questions.
+  - Pauses execution until the user provides answers or dismisses the dialog.
+  - Returns the user's answers to the model.
+
+- **Output (`llmContent`):** A JSON string containing the user's answers,
+  indexed by question position (e.g.,
+  `{"answers":{"0": "Option A", "1": "Some text"}}`).
+
+- **Confirmation:** Yes. The tool inherently involves user interaction.
+
+## Usage Examples
+
+### Multiple Choice Question
+
+```json
+{
+  "questions": [
+    {
+      "header": "Database",
+      "question": "Which database would you like to use?",
+      "type": "choice",
+      "options": [
+        {
+          "label": "PostgreSQL",
+          "description": "Powerful, open source object-relational database system."
+        },
+        {
+          "label": "SQLite",
+          "description": "C-library that implements a SQL database engine."
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Text Input Question
+
+```json
+{
+  "questions": [
+    {
+      "header": "Project Name",
+      "question": "What is the name of your new project?",
+      "type": "text",
+      "placeholder": "e.g., my-awesome-app"
+    }
+  ]
+}
+```
+
+### Yes/No Question
+
+```json
+{
+  "questions": [
+    {
+      "header": "Deploy",
+      "question": "Do you want to deploy the application now?",
+      "type": "yesno"
+    }
+  ]
+}
+```
diff --git a/docs/tools/index.md b/docs/tools/index.md
index ff594056ac..c7b2c1fc72 100644
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -87,6 +87,8 @@ Gemini CLI's built-in tools can be broadly categorized as follows:
 - **[Todo Tool](./todos.md) (`write_todos`):** For managing subtasks of complex
   requests.
 - **[Planning Tools](./planning.md):** For entering and exiting Plan Mode.
+- **[Ask User Tool](./ask-user.md) (`ask_user`):** For gathering user input and
+  making decisions.
 
 Additionally, these tools incorporate:
 

From e9a94748107ac24a05f51b4c5b0c0a8952374285 Mon Sep 17 00:00:00 2001
From: Adib234 <30782825+Adib234@users.noreply.github.com>
Date: Wed, 11 Feb 2026 15:06:28 -0500
Subject: [PATCH 02/44] Revert unintended credentials exposure (#18840)

---
 docs/tools/mcp-server.md                      | 13 +---
 packages/cli/src/commands/mcp/add.ts          |  7 --
 .../services/environmentSanitization.test.ts  |  3 -
 .../src/services/environmentSanitization.ts   |  3 -
 packages/core/src/tools/mcp-client.test.ts    | 73 +------------------
 packages/core/src/tools/mcp-client.ts         | 41 ++---------
 6 files changed, 8 insertions(+), 132 deletions(-)

diff --git a/docs/tools/mcp-server.md b/docs/tools/mcp-server.md
index eb246fd86f..dd3842759c 100644
--- a/docs/tools/mcp-server.md
+++ b/docs/tools/mcp-server.md
@@ -739,21 +739,10 @@ The MCP integration tracks several states:
   cautiously and only for servers you completely control
 - **Access tokens:** Be security-aware when configuring environment variables
   containing API keys or tokens
-- **Environment variable redaction:** By default, the Gemini CLI redacts
-  sensitive environment variables (such as `GEMINI_API_KEY`, `GOOGLE_API_KEY`,
-  and variables matching patterns like `*TOKEN*`, `*SECRET*`, `*PASSWORD*`) when
-  spawning MCP servers using the `stdio` transport. This prevents unintended
-  exposure of your credentials to third-party servers.
-- **Explicit environment variables:** If you need to pass a specific environment
-  variable to an MCP server, you should define it explicitly in the `env`
-  property of the server configuration in `settings.json`.
 - **Sandbox compatibility:** When using sandboxing, ensure MCP servers are
-  available within the sandbox environment.
+  available within the sandbox environment
 - **Private data:** Using broadly scoped personal access tokens can lead to
   information leakage between repositories.
-- **Untrusted servers:** Be extremely cautious when adding MCP servers from
-  untrusted or third-party sources. Malicious servers could attempt to
-  exfiltrate data or perform unauthorized actions through the tools they expose.
 
 ### Performance and resource management
 
diff --git a/packages/cli/src/commands/mcp/add.ts b/packages/cli/src/commands/mcp/add.ts
index 7d744a1daa..98e6a70879 100644
--- a/packages/cli/src/commands/mcp/add.ts
+++ b/packages/cli/src/commands/mcp/add.ts
@@ -128,13 +128,6 @@ async function addMcpServer(
 
   settings.setValue(settingsScope, 'mcpServers', mcpServers);
 
-  if (transport === 'stdio') {
-    debugLogger.warn(
-      'Security Warning: Running MCP servers with stdio transport can expose inherited environment variables. ' +
-        'While the Gemini CLI redacts common API keys and secrets by default, you should only run servers from trusted sources.',
-    );
-  }
-
   if (isExistingServer) {
     debugLogger.log(`MCP server "${name}" updated in ${scope} settings.`);
   } else {
diff --git a/packages/core/src/services/environmentSanitization.test.ts b/packages/core/src/services/environmentSanitization.test.ts
index 97f7e575ca..cc26d7547d 100644
--- a/packages/core/src/services/environmentSanitization.test.ts
+++ b/packages/core/src/services/environmentSanitization.test.ts
@@ -46,9 +46,6 @@ describe('sanitizeEnvironment', () => {
       CLIENT_ID: 'sensitive-id',
       DB_URI: 'sensitive-uri',
       DATABASE_URL: 'sensitive-url',
-      GEMINI_API_KEY: 'sensitive-gemini-key',
-      GOOGLE_API_KEY: 'sensitive-google-key',
-      GOOGLE_APPLICATION_CREDENTIALS: '/path/to/creds.json',
       SAFE_VAR: 'is-safe',
     };
     const sanitized = sanitizeEnvironment(env, EMPTY_OPTIONS);
diff --git a/packages/core/src/services/environmentSanitization.ts b/packages/core/src/services/environmentSanitization.ts
index b30b229079..dc9c92484d 100644
--- a/packages/core/src/services/environmentSanitization.ts
+++ b/packages/core/src/services/environmentSanitization.ts
@@ -103,9 +103,6 @@ export const NEVER_ALLOWED_ENVIRONMENT_VARIABLES: ReadonlySet<string> = new Set(
     'GOOGLE_CLOUD_PROJECT',
     'GOOGLE_CLOUD_ACCOUNT',
     'FIREBASE_PROJECT_ID',
-    'GEMINI_API_KEY',
-    'GOOGLE_API_KEY',
-    'GOOGLE_APPLICATION_CREDENTIALS',
   ],
 );
 
diff --git a/packages/core/src/tools/mcp-client.test.ts b/packages/core/src/tools/mcp-client.test.ts
index 77dec9d657..39165bde45 100644
--- a/packages/core/src/tools/mcp-client.test.ts
+++ b/packages/core/src/tools/mcp-client.test.ts
@@ -1623,7 +1623,7 @@ describe('mcp-client', () => {
         {
           command: 'test-command',
           args: ['--foo', 'bar'],
-          env: { GEMINI_CLI_FOO: 'bar' },
+          env: { FOO: 'bar' },
           cwd: 'test/cwd',
         },
         false,
@@ -1634,80 +1634,11 @@ describe('mcp-client', () => {
         command: 'test-command',
         args: ['--foo', 'bar'],
         cwd: 'test/cwd',
-        env: expect.objectContaining({ GEMINI_CLI_FOO: 'bar' }),
+        env: expect.objectContaining({ FOO: 'bar' }),
         stderr: 'pipe',
       });
     });
 
-    it('should redact sensitive environment variables for command transport', async () => {
-      const mockedTransport = vi
-        .spyOn(SdkClientStdioLib, 'StdioClientTransport')
-        .mockReturnValue({} as SdkClientStdioLib.StdioClientTransport);
-
-      const originalEnv = process.env;
-      process.env = {
-        ...originalEnv,
-        GEMINI_API_KEY: 'sensitive-key',
-        GEMINI_CLI_SAFE_VAR: 'safe-value',
-      };
-      // Ensure strict sanitization is not triggered for this test
-      delete process.env['GITHUB_SHA'];
-      delete process.env['SURFACE'];
-
-      try {
-        await createTransport(
-          'test-server',
-          {
-            command: 'test-command',
-          },
-          false,
-          EMPTY_CONFIG,
-        );
-
-        const callArgs = mockedTransport.mock.calls[0][0];
-        expect(callArgs.env).toBeDefined();
-        expect(callArgs.env!['GEMINI_CLI_SAFE_VAR']).toBe('safe-value');
-        expect(callArgs.env!['GEMINI_API_KEY']).toBeUndefined();
-      } finally {
-        process.env = originalEnv;
-      }
-    });
-
-    it('should include extension settings in environment', async () => {
-      const mockedTransport = vi
-        .spyOn(SdkClientStdioLib, 'StdioClientTransport')
-        .mockReturnValue({} as SdkClientStdioLib.StdioClientTransport);
-
-      await createTransport(
-        'test-server',
-        {
-          command: 'test-command',
-          extension: {
-            name: 'test-ext',
-            resolvedSettings: [
-              {
-                envVar: 'GEMINI_CLI_EXT_VAR',
-                value: 'ext-value',
-                sensitive: false,
-                name: 'ext-setting',
-              },
-            ],
-            version: '',
-            isActive: false,
-            path: '',
-            contextFiles: [],
-            id: '',
-          },
-        },
-        false,
-        EMPTY_CONFIG,
-      );
-
-      const callArgs = mockedTransport.mock.calls[0][0];
-      expect(callArgs.env).toBeDefined();
-      expect(callArgs.env!['GEMINI_CLI_EXT_VAR']).toBe('ext-value');
-    });
-
     it('should exclude extension settings with undefined values from environment', async () => {
       const mockedTransport = vi
         .spyOn(SdkClientStdioLib, 'StdioClientTransport')
diff --git a/packages/core/src/tools/mcp-client.ts b/packages/core/src/tools/mcp-client.ts
index c069f7a211..2588d54dba 100644
--- a/packages/core/src/tools/mcp-client.ts
+++ b/packages/core/src/tools/mcp-client.ts
@@ -34,11 +34,7 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import { ApprovalMode, PolicyDecision } from '../policy/types.js';
 import { parse } from 'shell-quote';
-import type {
-  Config,
-  GeminiCLIExtension,
-  MCPServerConfig,
-} from '../config/config.js';
+import type { Config, MCPServerConfig } from '../config/config.js';
 import { AuthProviderType } from '../config/config.js';
 import { GoogleCredentialProvider } from '../mcp/google-auth-provider.js';
 import { ServiceAccountImpersonationProvider } from '../mcp/sa-impersonation-provider.js';
@@ -1902,23 +1898,10 @@ export async function createTransport(
       command: mcpServerConfig.command,
       args: mcpServerConfig.args || [],
       // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-      env: sanitizeEnvironment(
-        {
-          ...process.env,
-          ...getExtensionEnvironment(mcpServerConfig.extension),
-          ...(mcpServerConfig.env || {}),
-        },
-        {
-          ...sanitizationConfig,
-          allowedEnvironmentVariables: [
-            ...(sanitizationConfig.allowedEnvironmentVariables ?? []),
-            ...(mcpServerConfig.extension?.resolvedSettings?.map(
-              (s) => s.envVar,
-            ) ?? []),
-          ],
-          enableEnvironmentVariableRedaction: true,
-        },
-      ) as Record<string, string>,
+      env: {
+        ...sanitizeEnvironment(process.env, sanitizationConfig),
+        ...(mcpServerConfig.env || {}),
+      } as Record<string, string>,
       cwd: mcpServerConfig.cwd,
       stderr: 'pipe',
     });
@@ -1993,17 +1976,3 @@ export function isEnabled(
     )
   );
 }
-
-function getExtensionEnvironment(
-  extension?: GeminiCLIExtension,
-): Record<string, string> {
-  const env: Record<string, string> = {};
-  if (extension?.resolvedSettings) {
-    for (const setting of extension.resolvedSettings) {
-      if (setting.value) {
-        env[setting.envVar] = setting.value;
-      }
-    }
-  }
-  return env;
-}

From bfa791e13d11501b2c93ae1e1864be14f86b43ba Mon Sep 17 00:00:00 2001
From: Sandy Tao <sandytao520@icloud.com>
Date: Wed, 11 Feb 2026 12:20:14 -0800
Subject: [PATCH 03/44] feat(core): update internal utility models to Gemini 3
 (#18773)

---
 docs/get-started/configuration.md             | 22 +++++----
 .../availability/fallbackIntegration.test.ts  |  6 +--
 .../src/availability/policyHelpers.test.ts    | 13 +++++
 .../core/src/availability/policyHelpers.ts    | 32 +++++++++----
 .../core/src/config/defaultModelConfigs.ts    | 22 +++++----
 .../resolved-aliases-retry.golden.json        | 23 +++++----
 .../test-data/resolved-aliases.golden.json    | 23 +++++----
 schemas/settings.schema.json                  | 48 ++++++++++++-------
 8 files changed, 128 insertions(+), 61 deletions(-)

diff --git a/docs/get-started/configuration.md b/docs/get-started/configuration.md
index 84818a59be..263dd815a8 100644
--- a/docs/get-started/configuration.md
+++ b/docs/get-started/configuration.md
@@ -447,6 +447,12 @@ their corresponding top-level category object in your `settings.json` file.
           "model": "gemini-2.5-flash"
         }
       },
+      "gemini-3-flash-base": {
+        "extends": "base",
+        "modelConfig": {
+          "model": "gemini-3-flash-preview"
+        }
+      },
       "classifier": {
         "extends": "base",
         "modelConfig": {
@@ -502,7 +508,7 @@ their corresponding top-level category object in your `settings.json` file.
         }
       },
       "web-search": {
-        "extends": "gemini-2.5-flash-base",
+        "extends": "gemini-3-flash-base",
         "modelConfig": {
           "generateContentConfig": {
             "tools": [
@@ -514,7 +520,7 @@ their corresponding top-level category object in your `settings.json` file.
         }
       },
       "web-fetch": {
-        "extends": "gemini-2.5-flash-base",
+        "extends": "gemini-3-flash-base",
         "modelConfig": {
           "generateContentConfig": {
             "tools": [
@@ -526,25 +532,25 @@ their corresponding top-level category object in your `settings.json` file.
         }
       },
       "web-fetch-fallback": {
-        "extends": "gemini-2.5-flash-base",
+        "extends": "gemini-3-flash-base",
         "modelConfig": {}
       },
       "loop-detection": {
-        "extends": "gemini-2.5-flash-base",
+        "extends": "gemini-3-flash-base",
         "modelConfig": {}
       },
       "loop-detection-double-check": {
         "extends": "base",
         "modelConfig": {
-          "model": "gemini-2.5-pro"
+          "model": "gemini-3-pro-preview"
         }
       },
       "llm-edit-fixer": {
-        "extends": "gemini-2.5-flash-base",
+        "extends": "gemini-3-flash-base",
         "modelConfig": {}
       },
       "next-speaker-checker": {
-        "extends": "gemini-2.5-flash-base",
+        "extends": "gemini-3-flash-base",
         "modelConfig": {}
       },
       "chat-compression-3-pro": {
@@ -574,7 +580,7 @@ their corresponding top-level category object in your `settings.json` file.
       },
       "chat-compression-default": {
         "modelConfig": {
-          "model": "gemini-2.5-pro"
+          "model": "gemini-3-pro-preview"
         }
       }
     }
diff --git a/packages/core/src/availability/fallbackIntegration.test.ts b/packages/core/src/availability/fallbackIntegration.test.ts
index 55f9ac800f..f9de1f3b2b 100644
--- a/packages/core/src/availability/fallbackIntegration.test.ts
+++ b/packages/core/src/availability/fallbackIntegration.test.ts
@@ -58,7 +58,7 @@ describe('Fallback Integration', () => {
     );
   });
 
-  it('should NOT fallback if config is NOT in AUTO mode', () => {
+  it('should fallback for Gemini 3 models even if config is NOT in AUTO mode', () => {
     // 1. Config is explicitly set to Pro, not Auto
     vi.spyOn(config, 'getModel').mockReturnValue(PREVIEW_GEMINI_MODEL);
 
@@ -71,7 +71,7 @@ describe('Fallback Integration', () => {
     // 4. Apply model selection
     const result = applyModelSelection(config, { model: requestedModel });
 
-    // 5. Expect it to stay on Pro (because single model chain)
-    expect(result.model).toBe(PREVIEW_GEMINI_MODEL);
+    // 5. Expect it to fallback to Flash (because Gemini 3 uses PREVIEW_CHAIN)
+    expect(result.model).toBe(PREVIEW_GEMINI_FLASH_MODEL);
   });
 });
diff --git a/packages/core/src/availability/policyHelpers.test.ts b/packages/core/src/availability/policyHelpers.test.ts
index 4e923f638e..298f17eb74 100644
--- a/packages/core/src/availability/policyHelpers.test.ts
+++ b/packages/core/src/availability/policyHelpers.test.ts
@@ -115,6 +115,19 @@ describe('policyHelpers', () => {
       expect(chain[0]?.model).toBe('gemini-2.5-flash');
       expect(chain[1]?.model).toBe('gemini-2.5-pro');
     });
+
+    it('proactively returns Gemini 2.5 chain if Gemini 3 requested but user lacks access', () => {
+      const config = createMockConfig({
+        getModel: () => 'auto-gemini-3',
+        getHasAccessToPreviewModel: () => false,
+      });
+      const chain = resolvePolicyChain(config);
+
+      // Should downgrade to [Pro 2.5, Flash 2.5]
+      expect(chain).toHaveLength(2);
+      expect(chain[0]?.model).toBe('gemini-2.5-pro');
+      expect(chain[1]?.model).toBe('gemini-2.5-flash');
+    });
   });
 
   describe('buildFallbackPolicyContext', () => {
diff --git a/packages/core/src/availability/policyHelpers.ts b/packages/core/src/availability/policyHelpers.ts
index 4d65b84d77..569157561f 100644
--- a/packages/core/src/availability/policyHelpers.ts
+++ b/packages/core/src/availability/policyHelpers.ts
@@ -24,6 +24,7 @@ import {
   DEFAULT_GEMINI_MODEL,
   PREVIEW_GEMINI_MODEL_AUTO,
   isAutoModel,
+  isGemini3Model,
   resolveModel,
 } from '../config/models.js';
 import type { ModelSelectionResult } from './modelAvailabilityService.js';
@@ -46,17 +47,32 @@ export function resolvePolicyChain(
   const resolvedModel = resolveModel(modelFromConfig);
   const isAutoPreferred = preferredModel ? isAutoModel(preferredModel) : false;
   const isAutoConfigured = isAutoModel(configuredModel);
+  const hasAccessToPreview = config.getHasAccessToPreviewModel?.() ?? true;
 
   if (resolvedModel === DEFAULT_GEMINI_FLASH_LITE_MODEL) {
     chain = getFlashLitePolicyChain();
-  } else if (isAutoPreferred || isAutoConfigured) {
-    const previewEnabled =
-      preferredModel === PREVIEW_GEMINI_MODEL_AUTO ||
-      configuredModel === PREVIEW_GEMINI_MODEL_AUTO;
-    chain = getModelPolicyChain({
-      previewEnabled,
-      userTier: config.getUserTier(),
-    });
+  } else if (
+    isGemini3Model(resolvedModel) ||
+    isAutoPreferred ||
+    isAutoConfigured
+  ) {
+    if (hasAccessToPreview) {
+      const previewEnabled =
+        isGemini3Model(resolvedModel) ||
+        preferredModel === PREVIEW_GEMINI_MODEL_AUTO ||
+        configuredModel === PREVIEW_GEMINI_MODEL_AUTO;
+      chain = getModelPolicyChain({
+        previewEnabled,
+        userTier: config.getUserTier(),
+      });
+    } else {
+      // User requested Gemini 3 but has no access. Proactively downgrade
+      // to the stable Gemini 2.5 chain.
+      return getModelPolicyChain({
+        previewEnabled: false,
+        userTier: config.getUserTier(),
+      });
+    }
   } else {
     chain = createSingleModelChain(modelFromConfig);
   }
diff --git a/packages/core/src/config/defaultModelConfigs.ts b/packages/core/src/config/defaultModelConfigs.ts
index 773223dc0c..c0424de9e3 100644
--- a/packages/core/src/config/defaultModelConfigs.ts
+++ b/packages/core/src/config/defaultModelConfigs.ts
@@ -96,6 +96,12 @@ export const DEFAULT_MODEL_CONFIGS: ModelConfigServiceConfig = {
         model: 'gemini-2.5-flash',
       },
     },
+    'gemini-3-flash-base': {
+      extends: 'base',
+      modelConfig: {
+        model: 'gemini-3-flash-preview',
+      },
+    },
     classifier: {
       extends: 'base',
       modelConfig: {
@@ -151,7 +157,7 @@ export const DEFAULT_MODEL_CONFIGS: ModelConfigServiceConfig = {
       },
     },
     'web-search': {
-      extends: 'gemini-2.5-flash-base',
+      extends: 'gemini-3-flash-base',
       modelConfig: {
         generateContentConfig: {
           tools: [{ googleSearch: {} }],
@@ -159,7 +165,7 @@ export const DEFAULT_MODEL_CONFIGS: ModelConfigServiceConfig = {
       },
     },
     'web-fetch': {
-      extends: 'gemini-2.5-flash-base',
+      extends: 'gemini-3-flash-base',
       modelConfig: {
         generateContentConfig: {
           tools: [{ urlContext: {} }],
@@ -168,25 +174,25 @@ export const DEFAULT_MODEL_CONFIGS: ModelConfigServiceConfig = {
     },
     // TODO(joshualitt): During cleanup, make modelConfig optional.
     'web-fetch-fallback': {
-      extends: 'gemini-2.5-flash-base',
+      extends: 'gemini-3-flash-base',
       modelConfig: {},
     },
     'loop-detection': {
-      extends: 'gemini-2.5-flash-base',
+      extends: 'gemini-3-flash-base',
       modelConfig: {},
     },
     'loop-detection-double-check': {
       extends: 'base',
       modelConfig: {
-        model: 'gemini-2.5-pro',
+        model: 'gemini-3-pro-preview',
       },
     },
     'llm-edit-fixer': {
-      extends: 'gemini-2.5-flash-base',
+      extends: 'gemini-3-flash-base',
       modelConfig: {},
     },
     'next-speaker-checker': {
-      extends: 'gemini-2.5-flash-base',
+      extends: 'gemini-3-flash-base',
       modelConfig: {},
     },
     'chat-compression-3-pro': {
@@ -216,7 +222,7 @@ export const DEFAULT_MODEL_CONFIGS: ModelConfigServiceConfig = {
     },
     'chat-compression-default': {
       modelConfig: {
-        model: 'gemini-2.5-pro',
+        model: 'gemini-3-pro-preview',
       },
     },
   },
diff --git a/packages/core/src/services/test-data/resolved-aliases-retry.golden.json b/packages/core/src/services/test-data/resolved-aliases-retry.golden.json
index 3b38b909d8..9bfd252b88 100644
--- a/packages/core/src/services/test-data/resolved-aliases-retry.golden.json
+++ b/packages/core/src/services/test-data/resolved-aliases-retry.golden.json
@@ -104,6 +104,13 @@
       "topP": 1
     }
   },
+  "gemini-3-flash-base": {
+    "model": "gemini-3-flash-preview",
+    "generateContentConfig": {
+      "temperature": 0,
+      "topP": 1
+    }
+  },
   "classifier": {
     "model": "gemini-2.5-flash-lite",
     "generateContentConfig": {
@@ -153,7 +160,7 @@
     }
   },
   "web-search": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1,
@@ -165,7 +172,7 @@
     }
   },
   "web-fetch": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1,
@@ -177,35 +184,35 @@
     }
   },
   "web-fetch-fallback": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1
     }
   },
   "loop-detection": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1
     }
   },
   "loop-detection-double-check": {
-    "model": "gemini-2.5-pro",
+    "model": "gemini-3-pro-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1
     }
   },
   "llm-edit-fixer": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1
     }
   },
   "next-speaker-checker": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1
@@ -232,7 +239,7 @@
     "generateContentConfig": {}
   },
   "chat-compression-default": {
-    "model": "gemini-2.5-pro",
+    "model": "gemini-3-pro-preview",
     "generateContentConfig": {}
   }
 }
diff --git a/packages/core/src/services/test-data/resolved-aliases.golden.json b/packages/core/src/services/test-data/resolved-aliases.golden.json
index 3b38b909d8..9bfd252b88 100644
--- a/packages/core/src/services/test-data/resolved-aliases.golden.json
+++ b/packages/core/src/services/test-data/resolved-aliases.golden.json
@@ -104,6 +104,13 @@
       "topP": 1
     }
   },
+  "gemini-3-flash-base": {
+    "model": "gemini-3-flash-preview",
+    "generateContentConfig": {
+      "temperature": 0,
+      "topP": 1
+    }
+  },
   "classifier": {
     "model": "gemini-2.5-flash-lite",
     "generateContentConfig": {
@@ -153,7 +160,7 @@
     }
   },
   "web-search": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1,
@@ -165,7 +172,7 @@
     }
   },
   "web-fetch": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1,
@@ -177,35 +184,35 @@
     }
   },
   "web-fetch-fallback": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1
     }
   },
   "loop-detection": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1
     }
   },
   "loop-detection-double-check": {
-    "model": "gemini-2.5-pro",
+    "model": "gemini-3-pro-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1
     }
   },
   "llm-edit-fixer": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1
     }
   },
   "next-speaker-checker": {
-    "model": "gemini-2.5-flash",
+    "model": "gemini-3-flash-preview",
     "generateContentConfig": {
       "temperature": 0,
       "topP": 1
@@ -232,7 +239,7 @@
     "generateContentConfig": {}
   },
   "chat-compression-default": {
-    "model": "gemini-2.5-pro",
+    "model": "gemini-3-pro-preview",
     "generateContentConfig": {}
   }
 }
diff --git a/schemas/settings.schema.json b/schemas/settings.schema.json
index dd2702e712..06ad037929 100644
--- a/schemas/settings.schema.json
+++ b/schemas/settings.schema.json
@@ -514,7 +514,7 @@
     "modelConfigs": {
       "title": "Model Configs",
       "description": "Model configurations.",
-      "markdownDescription": "Model configurations.\n\n- Category: `Model`\n- Requires restart: `no`\n- Default: `{\n  \"aliases\": {\n    \"base\": {\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"temperature\": 0,\n          \"topP\": 1\n        }\n      }\n    },\n    \"chat-base\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"thinkingConfig\": {\n            \"includeThoughts\": true\n          },\n          \"temperature\": 1,\n          \"topP\": 0.95,\n          \"topK\": 64\n        }\n      }\n    },\n    \"chat-base-2.5\": {\n      \"extends\": \"chat-base\",\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"thinkingConfig\": {\n            \"thinkingBudget\": 8192\n          }\n        }\n      }\n    },\n    \"chat-base-3\": {\n      \"extends\": \"chat-base\",\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"thinkingConfig\": {\n            \"thinkingLevel\": \"HIGH\"\n          }\n        }\n      }\n    },\n    \"gemini-3-pro-preview\": {\n      \"extends\": \"chat-base-3\",\n      \"modelConfig\": {\n        \"model\": \"gemini-3-pro-preview\"\n      }\n    },\n    \"gemini-3-flash-preview\": {\n      \"extends\": \"chat-base-3\",\n      \"modelConfig\": {\n        \"model\": \"gemini-3-flash-preview\"\n      }\n    },\n    \"gemini-2.5-pro\": {\n      \"extends\": \"chat-base-2.5\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-pro\"\n      }\n    },\n    \"gemini-2.5-flash\": {\n      \"extends\": \"chat-base-2.5\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash\"\n      }\n    },\n    \"gemini-2.5-flash-lite\": {\n      \"extends\": \"chat-base-2.5\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\"\n      }\n    },\n    \"gemini-2.5-flash-base\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash\"\n      }\n    },\n    \"classifier\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\",\n        \"generateContentConfig\": {\n          \"maxOutputTokens\": 1024,\n          \"thinkingConfig\": {\n            \"thinkingBudget\": 512\n          }\n        }\n      }\n    },\n    \"prompt-completion\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\",\n        \"generateContentConfig\": {\n          \"temperature\": 0.3,\n          \"maxOutputTokens\": 16000,\n          \"thinkingConfig\": {\n            \"thinkingBudget\": 0\n          }\n        }\n      }\n    },\n    \"edit-corrector\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\",\n        \"generateContentConfig\": {\n          \"thinkingConfig\": {\n            \"thinkingBudget\": 0\n          }\n        }\n      }\n    },\n    \"summarizer-default\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\",\n        \"generateContentConfig\": {\n          \"maxOutputTokens\": 2000\n        }\n      }\n    },\n    \"summarizer-shell\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\",\n        \"generateContentConfig\": {\n          \"maxOutputTokens\": 2000\n        }\n      }\n    },\n    \"web-search\": {\n      \"extends\": \"gemini-2.5-flash-base\",\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"tools\": [\n            {\n              \"googleSearch\": {}\n            }\n          ]\n        }\n      }\n    },\n    \"web-fetch\": {\n      \"extends\": \"gemini-2.5-flash-base\",\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"tools\": [\n            {\n              \"urlContext\": {}\n            }\n          ]\n        }\n      }\n    },\n    \"web-fetch-fallback\": {\n      \"extends\": \"gemini-2.5-flash-base\",\n      \"modelConfig\": {}\n    },\n    \"loop-detection\": {\n      \"extends\": \"gemini-2.5-flash-base\",\n      \"modelConfig\": {}\n    },\n    \"loop-detection-double-check\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-pro\"\n      }\n    },\n    \"llm-edit-fixer\": {\n      \"extends\": \"gemini-2.5-flash-base\",\n      \"modelConfig\": {}\n    },\n    \"next-speaker-checker\": {\n      \"extends\": \"gemini-2.5-flash-base\",\n      \"modelConfig\": {}\n    },\n    \"chat-compression-3-pro\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-3-pro-preview\"\n      }\n    },\n    \"chat-compression-3-flash\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-3-flash-preview\"\n      }\n    },\n    \"chat-compression-2.5-pro\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-pro\"\n      }\n    },\n    \"chat-compression-2.5-flash\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash\"\n      }\n    },\n    \"chat-compression-2.5-flash-lite\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\"\n      }\n    },\n    \"chat-compression-default\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-pro\"\n      }\n    }\n  },\n  \"overrides\": [\n    {\n      \"match\": {\n        \"model\": \"chat-base\",\n        \"isRetry\": true\n      },\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"temperature\": 1\n        }\n      }\n    }\n  ]\n}`",
+      "markdownDescription": "Model configurations.\n\n- Category: `Model`\n- Requires restart: `no`\n- Default: `{\n  \"aliases\": {\n    \"base\": {\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"temperature\": 0,\n          \"topP\": 1\n        }\n      }\n    },\n    \"chat-base\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"thinkingConfig\": {\n            \"includeThoughts\": true\n          },\n          \"temperature\": 1,\n          \"topP\": 0.95,\n          \"topK\": 64\n        }\n      }\n    },\n    \"chat-base-2.5\": {\n      \"extends\": \"chat-base\",\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"thinkingConfig\": {\n            \"thinkingBudget\": 8192\n          }\n        }\n      }\n    },\n    \"chat-base-3\": {\n      \"extends\": \"chat-base\",\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"thinkingConfig\": {\n            \"thinkingLevel\": \"HIGH\"\n          }\n        }\n      }\n    },\n    \"gemini-3-pro-preview\": {\n      \"extends\": \"chat-base-3\",\n      \"modelConfig\": {\n        \"model\": \"gemini-3-pro-preview\"\n      }\n    },\n    \"gemini-3-flash-preview\": {\n      \"extends\": \"chat-base-3\",\n      \"modelConfig\": {\n        \"model\": \"gemini-3-flash-preview\"\n      }\n    },\n    \"gemini-2.5-pro\": {\n      \"extends\": \"chat-base-2.5\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-pro\"\n      }\n    },\n    \"gemini-2.5-flash\": {\n      \"extends\": \"chat-base-2.5\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash\"\n      }\n    },\n    \"gemini-2.5-flash-lite\": {\n      \"extends\": \"chat-base-2.5\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\"\n      }\n    },\n    \"gemini-2.5-flash-base\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash\"\n      }\n    },\n    \"gemini-3-flash-base\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-3-flash-preview\"\n      }\n    },\n    \"classifier\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\",\n        \"generateContentConfig\": {\n          \"maxOutputTokens\": 1024,\n          \"thinkingConfig\": {\n            \"thinkingBudget\": 512\n          }\n        }\n      }\n    },\n    \"prompt-completion\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\",\n        \"generateContentConfig\": {\n          \"temperature\": 0.3,\n          \"maxOutputTokens\": 16000,\n          \"thinkingConfig\": {\n            \"thinkingBudget\": 0\n          }\n        }\n      }\n    },\n    \"edit-corrector\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\",\n        \"generateContentConfig\": {\n          \"thinkingConfig\": {\n            \"thinkingBudget\": 0\n          }\n        }\n      }\n    },\n    \"summarizer-default\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\",\n        \"generateContentConfig\": {\n          \"maxOutputTokens\": 2000\n        }\n      }\n    },\n    \"summarizer-shell\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\",\n        \"generateContentConfig\": {\n          \"maxOutputTokens\": 2000\n        }\n      }\n    },\n    \"web-search\": {\n      \"extends\": \"gemini-3-flash-base\",\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"tools\": [\n            {\n              \"googleSearch\": {}\n            }\n          ]\n        }\n      }\n    },\n    \"web-fetch\": {\n      \"extends\": \"gemini-3-flash-base\",\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"tools\": [\n            {\n              \"urlContext\": {}\n            }\n          ]\n        }\n      }\n    },\n    \"web-fetch-fallback\": {\n      \"extends\": \"gemini-3-flash-base\",\n      \"modelConfig\": {}\n    },\n    \"loop-detection\": {\n      \"extends\": \"gemini-3-flash-base\",\n      \"modelConfig\": {}\n    },\n    \"loop-detection-double-check\": {\n      \"extends\": \"base\",\n      \"modelConfig\": {\n        \"model\": \"gemini-3-pro-preview\"\n      }\n    },\n    \"llm-edit-fixer\": {\n      \"extends\": \"gemini-3-flash-base\",\n      \"modelConfig\": {}\n    },\n    \"next-speaker-checker\": {\n      \"extends\": \"gemini-3-flash-base\",\n      \"modelConfig\": {}\n    },\n    \"chat-compression-3-pro\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-3-pro-preview\"\n      }\n    },\n    \"chat-compression-3-flash\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-3-flash-preview\"\n      }\n    },\n    \"chat-compression-2.5-pro\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-pro\"\n      }\n    },\n    \"chat-compression-2.5-flash\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash\"\n      }\n    },\n    \"chat-compression-2.5-flash-lite\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-2.5-flash-lite\"\n      }\n    },\n    \"chat-compression-default\": {\n      \"modelConfig\": {\n        \"model\": \"gemini-3-pro-preview\"\n      }\n    }\n  },\n  \"overrides\": [\n    {\n      \"match\": {\n        \"model\": \"chat-base\",\n        \"isRetry\": true\n      },\n      \"modelConfig\": {\n        \"generateContentConfig\": {\n          \"temperature\": 1\n        }\n      }\n    }\n  ]\n}`",
       "default": {
         "aliases": {
           "base": {
@@ -594,6 +594,12 @@
               "model": "gemini-2.5-flash"
             }
           },
+          "gemini-3-flash-base": {
+            "extends": "base",
+            "modelConfig": {
+              "model": "gemini-3-flash-preview"
+            }
+          },
           "classifier": {
             "extends": "base",
             "modelConfig": {
@@ -649,7 +655,7 @@
             }
           },
           "web-search": {
-            "extends": "gemini-2.5-flash-base",
+            "extends": "gemini-3-flash-base",
             "modelConfig": {
               "generateContentConfig": {
                 "tools": [
@@ -661,7 +667,7 @@
             }
           },
           "web-fetch": {
-            "extends": "gemini-2.5-flash-base",
+            "extends": "gemini-3-flash-base",
             "modelConfig": {
               "generateContentConfig": {
                 "tools": [
@@ -673,25 +679,25 @@
             }
           },
           "web-fetch-fallback": {
-            "extends": "gemini-2.5-flash-base",
+            "extends": "gemini-3-flash-base",
             "modelConfig": {}
           },
           "loop-detection": {
-            "extends": "gemini-2.5-flash-base",
+            "extends": "gemini-3-flash-base",
             "modelConfig": {}
           },
           "loop-detection-double-check": {
             "extends": "base",
             "modelConfig": {
-              "model": "gemini-2.5-pro"
+              "model": "gemini-3-pro-preview"
             }
           },
           "llm-edit-fixer": {
-            "extends": "gemini-2.5-flash-base",
+            "extends": "gemini-3-flash-base",
             "modelConfig": {}
           },
           "next-speaker-checker": {
-            "extends": "gemini-2.5-flash-base",
+            "extends": "gemini-3-flash-base",
             "modelConfig": {}
           },
           "chat-compression-3-pro": {
@@ -721,7 +727,7 @@
           },
           "chat-compression-default": {
             "modelConfig": {
-              "model": "gemini-2.5-pro"
+              "model": "gemini-3-pro-preview"
             }
           }
         },
@@ -744,7 +750,7 @@
         "aliases": {
           "title": "Model Config Aliases",
           "description": "Named presets for model configs. Can be used in place of a model name and can inherit from other aliases using an `extends` property.",
-          "markdownDescription": "Named presets for model configs. Can be used in place of a model name and can inherit from other aliases using an `extends` property.\n\n- Category: `Model`\n- Requires restart: `no`\n- Default: `{\n  \"base\": {\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"temperature\": 0,\n        \"topP\": 1\n      }\n    }\n  },\n  \"chat-base\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"thinkingConfig\": {\n          \"includeThoughts\": true\n        },\n        \"temperature\": 1,\n        \"topP\": 0.95,\n        \"topK\": 64\n      }\n    }\n  },\n  \"chat-base-2.5\": {\n    \"extends\": \"chat-base\",\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"thinkingConfig\": {\n          \"thinkingBudget\": 8192\n        }\n      }\n    }\n  },\n  \"chat-base-3\": {\n    \"extends\": \"chat-base\",\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"thinkingConfig\": {\n          \"thinkingLevel\": \"HIGH\"\n        }\n      }\n    }\n  },\n  \"gemini-3-pro-preview\": {\n    \"extends\": \"chat-base-3\",\n    \"modelConfig\": {\n      \"model\": \"gemini-3-pro-preview\"\n    }\n  },\n  \"gemini-3-flash-preview\": {\n    \"extends\": \"chat-base-3\",\n    \"modelConfig\": {\n      \"model\": \"gemini-3-flash-preview\"\n    }\n  },\n  \"gemini-2.5-pro\": {\n    \"extends\": \"chat-base-2.5\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-pro\"\n    }\n  },\n  \"gemini-2.5-flash\": {\n    \"extends\": \"chat-base-2.5\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash\"\n    }\n  },\n  \"gemini-2.5-flash-lite\": {\n    \"extends\": \"chat-base-2.5\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\"\n    }\n  },\n  \"gemini-2.5-flash-base\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash\"\n    }\n  },\n  \"classifier\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\",\n      \"generateContentConfig\": {\n        \"maxOutputTokens\": 1024,\n        \"thinkingConfig\": {\n          \"thinkingBudget\": 512\n        }\n      }\n    }\n  },\n  \"prompt-completion\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\",\n      \"generateContentConfig\": {\n        \"temperature\": 0.3,\n        \"maxOutputTokens\": 16000,\n        \"thinkingConfig\": {\n          \"thinkingBudget\": 0\n        }\n      }\n    }\n  },\n  \"edit-corrector\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\",\n      \"generateContentConfig\": {\n        \"thinkingConfig\": {\n          \"thinkingBudget\": 0\n        }\n      }\n    }\n  },\n  \"summarizer-default\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\",\n      \"generateContentConfig\": {\n        \"maxOutputTokens\": 2000\n      }\n    }\n  },\n  \"summarizer-shell\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\",\n      \"generateContentConfig\": {\n        \"maxOutputTokens\": 2000\n      }\n    }\n  },\n  \"web-search\": {\n    \"extends\": \"gemini-2.5-flash-base\",\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"tools\": [\n          {\n            \"googleSearch\": {}\n          }\n        ]\n      }\n    }\n  },\n  \"web-fetch\": {\n    \"extends\": \"gemini-2.5-flash-base\",\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"tools\": [\n          {\n            \"urlContext\": {}\n          }\n        ]\n      }\n    }\n  },\n  \"web-fetch-fallback\": {\n    \"extends\": \"gemini-2.5-flash-base\",\n    \"modelConfig\": {}\n  },\n  \"loop-detection\": {\n    \"extends\": \"gemini-2.5-flash-base\",\n    \"modelConfig\": {}\n  },\n  \"loop-detection-double-check\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-pro\"\n    }\n  },\n  \"llm-edit-fixer\": {\n    \"extends\": \"gemini-2.5-flash-base\",\n    \"modelConfig\": {}\n  },\n  \"next-speaker-checker\": {\n    \"extends\": \"gemini-2.5-flash-base\",\n    \"modelConfig\": {}\n  },\n  \"chat-compression-3-pro\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-3-pro-preview\"\n    }\n  },\n  \"chat-compression-3-flash\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-3-flash-preview\"\n    }\n  },\n  \"chat-compression-2.5-pro\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-pro\"\n    }\n  },\n  \"chat-compression-2.5-flash\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash\"\n    }\n  },\n  \"chat-compression-2.5-flash-lite\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\"\n    }\n  },\n  \"chat-compression-default\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-pro\"\n    }\n  }\n}`",
+          "markdownDescription": "Named presets for model configs. Can be used in place of a model name and can inherit from other aliases using an `extends` property.\n\n- Category: `Model`\n- Requires restart: `no`\n- Default: `{\n  \"base\": {\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"temperature\": 0,\n        \"topP\": 1\n      }\n    }\n  },\n  \"chat-base\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"thinkingConfig\": {\n          \"includeThoughts\": true\n        },\n        \"temperature\": 1,\n        \"topP\": 0.95,\n        \"topK\": 64\n      }\n    }\n  },\n  \"chat-base-2.5\": {\n    \"extends\": \"chat-base\",\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"thinkingConfig\": {\n          \"thinkingBudget\": 8192\n        }\n      }\n    }\n  },\n  \"chat-base-3\": {\n    \"extends\": \"chat-base\",\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"thinkingConfig\": {\n          \"thinkingLevel\": \"HIGH\"\n        }\n      }\n    }\n  },\n  \"gemini-3-pro-preview\": {\n    \"extends\": \"chat-base-3\",\n    \"modelConfig\": {\n      \"model\": \"gemini-3-pro-preview\"\n    }\n  },\n  \"gemini-3-flash-preview\": {\n    \"extends\": \"chat-base-3\",\n    \"modelConfig\": {\n      \"model\": \"gemini-3-flash-preview\"\n    }\n  },\n  \"gemini-2.5-pro\": {\n    \"extends\": \"chat-base-2.5\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-pro\"\n    }\n  },\n  \"gemini-2.5-flash\": {\n    \"extends\": \"chat-base-2.5\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash\"\n    }\n  },\n  \"gemini-2.5-flash-lite\": {\n    \"extends\": \"chat-base-2.5\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\"\n    }\n  },\n  \"gemini-2.5-flash-base\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash\"\n    }\n  },\n  \"gemini-3-flash-base\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-3-flash-preview\"\n    }\n  },\n  \"classifier\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\",\n      \"generateContentConfig\": {\n        \"maxOutputTokens\": 1024,\n        \"thinkingConfig\": {\n          \"thinkingBudget\": 512\n        }\n      }\n    }\n  },\n  \"prompt-completion\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\",\n      \"generateContentConfig\": {\n        \"temperature\": 0.3,\n        \"maxOutputTokens\": 16000,\n        \"thinkingConfig\": {\n          \"thinkingBudget\": 0\n        }\n      }\n    }\n  },\n  \"edit-corrector\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\",\n      \"generateContentConfig\": {\n        \"thinkingConfig\": {\n          \"thinkingBudget\": 0\n        }\n      }\n    }\n  },\n  \"summarizer-default\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\",\n      \"generateContentConfig\": {\n        \"maxOutputTokens\": 2000\n      }\n    }\n  },\n  \"summarizer-shell\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\",\n      \"generateContentConfig\": {\n        \"maxOutputTokens\": 2000\n      }\n    }\n  },\n  \"web-search\": {\n    \"extends\": \"gemini-3-flash-base\",\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"tools\": [\n          {\n            \"googleSearch\": {}\n          }\n        ]\n      }\n    }\n  },\n  \"web-fetch\": {\n    \"extends\": \"gemini-3-flash-base\",\n    \"modelConfig\": {\n      \"generateContentConfig\": {\n        \"tools\": [\n          {\n            \"urlContext\": {}\n          }\n        ]\n      }\n    }\n  },\n  \"web-fetch-fallback\": {\n    \"extends\": \"gemini-3-flash-base\",\n    \"modelConfig\": {}\n  },\n  \"loop-detection\": {\n    \"extends\": \"gemini-3-flash-base\",\n    \"modelConfig\": {}\n  },\n  \"loop-detection-double-check\": {\n    \"extends\": \"base\",\n    \"modelConfig\": {\n      \"model\": \"gemini-3-pro-preview\"\n    }\n  },\n  \"llm-edit-fixer\": {\n    \"extends\": \"gemini-3-flash-base\",\n    \"modelConfig\": {}\n  },\n  \"next-speaker-checker\": {\n    \"extends\": \"gemini-3-flash-base\",\n    \"modelConfig\": {}\n  },\n  \"chat-compression-3-pro\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-3-pro-preview\"\n    }\n  },\n  \"chat-compression-3-flash\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-3-flash-preview\"\n    }\n  },\n  \"chat-compression-2.5-pro\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-pro\"\n    }\n  },\n  \"chat-compression-2.5-flash\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash\"\n    }\n  },\n  \"chat-compression-2.5-flash-lite\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-2.5-flash-lite\"\n    }\n  },\n  \"chat-compression-default\": {\n    \"modelConfig\": {\n      \"model\": \"gemini-3-pro-preview\"\n    }\n  }\n}`",
           "default": {
             "base": {
               "modelConfig": {
@@ -823,6 +829,12 @@
                 "model": "gemini-2.5-flash"
               }
             },
+            "gemini-3-flash-base": {
+              "extends": "base",
+              "modelConfig": {
+                "model": "gemini-3-flash-preview"
+              }
+            },
             "classifier": {
               "extends": "base",
               "modelConfig": {
@@ -878,7 +890,7 @@
               }
             },
             "web-search": {
-              "extends": "gemini-2.5-flash-base",
+              "extends": "gemini-3-flash-base",
               "modelConfig": {
                 "generateContentConfig": {
                   "tools": [
@@ -890,7 +902,7 @@
               }
             },
             "web-fetch": {
-              "extends": "gemini-2.5-flash-base",
+              "extends": "gemini-3-flash-base",
               "modelConfig": {
                 "generateContentConfig": {
                   "tools": [
@@ -902,25 +914,25 @@
               }
             },
             "web-fetch-fallback": {
-              "extends": "gemini-2.5-flash-base",
+              "extends": "gemini-3-flash-base",
               "modelConfig": {}
             },
             "loop-detection": {
-              "extends": "gemini-2.5-flash-base",
+              "extends": "gemini-3-flash-base",
               "modelConfig": {}
             },
             "loop-detection-double-check": {
               "extends": "base",
               "modelConfig": {
-                "model": "gemini-2.5-pro"
+                "model": "gemini-3-pro-preview"
               }
             },
             "llm-edit-fixer": {
-              "extends": "gemini-2.5-flash-base",
+              "extends": "gemini-3-flash-base",
               "modelConfig": {}
             },
             "next-speaker-checker": {
-              "extends": "gemini-2.5-flash-base",
+              "extends": "gemini-3-flash-base",
               "modelConfig": {}
             },
             "chat-compression-3-pro": {
@@ -950,7 +962,7 @@
             },
             "chat-compression-default": {
               "modelConfig": {
-                "model": "gemini-2.5-pro"
+                "model": "gemini-3-pro-preview"
               }
             }
           },

From 4138667bae4259169114d4911fafa8496cc42a36 Mon Sep 17 00:00:00 2001
From: Adam Weidman <65992621+adamfweidman@users.noreply.github.com>
Date: Wed, 11 Feb 2026 16:23:28 -0500
Subject: [PATCH 04/44] feat(a2a): add value-resolver for auth credential
 resolution (#18653)

---
 packages/core/src/agents/agentLoader.test.ts  | 167 ++++++++++++++++++
 packages/core/src/agents/agentLoader.ts       | 153 ++++++++++++++++
 .../src/agents/auth-provider/base-provider.ts |  29 ++-
 .../auth-provider/value-resolver.test.ts      | 136 ++++++++++++++
 .../agents/auth-provider/value-resolver.ts    | 102 +++++++++++
 5 files changed, 583 insertions(+), 4 deletions(-)
 create mode 100644 packages/core/src/agents/auth-provider/value-resolver.test.ts
 create mode 100644 packages/core/src/agents/auth-provider/value-resolver.ts

diff --git a/packages/core/src/agents/agentLoader.test.ts b/packages/core/src/agents/agentLoader.test.ts
index 3649558b64..a54626b637 100644
--- a/packages/core/src/agents/agentLoader.test.ts
+++ b/packages/core/src/agents/agentLoader.test.ts
@@ -363,4 +363,171 @@ Hidden`,
       expect(result.errors).toHaveLength(1);
     });
   });
+
+  describe('remote agent auth configuration', () => {
+    it('should parse remote agent with apiKey auth', async () => {
+      const filePath = await writeAgentMarkdown(`---
+kind: remote
+name: api-key-agent
+agent_card_url: https://example.com/card
+auth:
+  type: apiKey
+  key: $MY_API_KEY
+  in: header
+  name: X-Custom-Key
+---
+`);
+      const result = await parseAgentMarkdown(filePath);
+      expect(result).toHaveLength(1);
+      expect(result[0]).toMatchObject({
+        kind: 'remote',
+        name: 'api-key-agent',
+        auth: {
+          type: 'apiKey',
+          key: '$MY_API_KEY',
+          in: 'header',
+          name: 'X-Custom-Key',
+        },
+      });
+    });
+
+    it('should parse remote agent with http Bearer auth', async () => {
+      const filePath = await writeAgentMarkdown(`---
+kind: remote
+name: bearer-agent
+agent_card_url: https://example.com/card
+auth:
+  type: http
+  scheme: Bearer
+  token: $BEARER_TOKEN
+---
+`);
+      const result = await parseAgentMarkdown(filePath);
+      expect(result).toHaveLength(1);
+      expect(result[0]).toMatchObject({
+        kind: 'remote',
+        name: 'bearer-agent',
+        auth: {
+          type: 'http',
+          scheme: 'Bearer',
+          token: '$BEARER_TOKEN',
+        },
+      });
+    });
+
+    it('should parse remote agent with http Basic auth', async () => {
+      const filePath = await writeAgentMarkdown(`---
+kind: remote
+name: basic-agent
+agent_card_url: https://example.com/card
+auth:
+  type: http
+  scheme: Basic
+  username: $AUTH_USER
+  password: $AUTH_PASS
+---
+`);
+      const result = await parseAgentMarkdown(filePath);
+      expect(result).toHaveLength(1);
+      expect(result[0]).toMatchObject({
+        kind: 'remote',
+        name: 'basic-agent',
+        auth: {
+          type: 'http',
+          scheme: 'Basic',
+          username: '$AUTH_USER',
+          password: '$AUTH_PASS',
+        },
+      });
+    });
+
+    it('should throw error for Bearer auth without token', async () => {
+      const filePath = await writeAgentMarkdown(`---
+kind: remote
+name: invalid-bearer
+agent_card_url: https://example.com/card
+auth:
+  type: http
+  scheme: Bearer
+---
+`);
+      await expect(parseAgentMarkdown(filePath)).rejects.toThrow(
+        /Bearer scheme requires "token"/,
+      );
+    });
+
+    it('should throw error for Basic auth without credentials', async () => {
+      const filePath = await writeAgentMarkdown(`---
+kind: remote
+name: invalid-basic
+agent_card_url: https://example.com/card
+auth:
+  type: http
+  scheme: Basic
+  username: user
+---
+`);
+      await expect(parseAgentMarkdown(filePath)).rejects.toThrow(
+        /Basic scheme requires "username" and "password"/,
+      );
+    });
+
+    it('should throw error for apiKey auth without key', async () => {
+      const filePath = await writeAgentMarkdown(`---
+kind: remote
+name: invalid-apikey
+agent_card_url: https://example.com/card
+auth:
+  type: apiKey
+---
+`);
+      await expect(parseAgentMarkdown(filePath)).rejects.toThrow(
+        /auth\.key.*Required/,
+      );
+    });
+
+    it('should convert auth config in markdownToAgentDefinition', () => {
+      const markdown = {
+        kind: 'remote' as const,
+        name: 'auth-agent',
+        agent_card_url: 'https://example.com/card',
+        auth: {
+          type: 'apiKey' as const,
+          key: '$API_KEY',
+          in: 'header' as const,
+        },
+      };
+
+      const result = markdownToAgentDefinition(markdown);
+      expect(result).toMatchObject({
+        kind: 'remote',
+        name: 'auth-agent',
+        auth: {
+          type: 'apiKey',
+          key: '$API_KEY',
+          location: 'header',
+        },
+      });
+    });
+
+    it('should parse auth with agent_card_requires_auth flag', async () => {
+      const filePath = await writeAgentMarkdown(`---
+kind: remote
+name: protected-card-agent
+agent_card_url: https://example.com/card
+auth:
+  type: apiKey
+  key: $MY_API_KEY
+  agent_card_requires_auth: true
+---
+`);
+      const result = await parseAgentMarkdown(filePath);
+      expect(result[0]).toMatchObject({
+        auth: {
+          type: 'apiKey',
+          agent_card_requires_auth: true,
+        },
+      });
+    });
+  });
 });
diff --git a/packages/core/src/agents/agentLoader.ts b/packages/core/src/agents/agentLoader.ts
index 8d5e44b93c..cb2a605779 100644
--- a/packages/core/src/agents/agentLoader.ts
+++ b/packages/core/src/agents/agentLoader.ts
@@ -15,6 +15,7 @@ import {
   DEFAULT_MAX_TURNS,
   DEFAULT_MAX_TIME_MINUTES,
 } from './types.js';
+import type { A2AAuthConfig } from './auth-provider/types.js';
 import { isValidToolName } from '../tools/tool-names.js';
 import { FRONTMATTER_REGEX } from '../skills/skillLoader.js';
 import { getErrorMessage } from '../utils/errors.js';
@@ -39,11 +40,29 @@ interface FrontmatterLocalAgentDefinition
   timeout_mins?: number;
 }
 
+/**
+ * Authentication configuration for remote agents in frontmatter format.
+ */
+interface FrontmatterAuthConfig {
+  type: 'apiKey' | 'http';
+  agent_card_requires_auth?: boolean;
+  // API Key
+  key?: string;
+  in?: 'header' | 'query' | 'cookie';
+  name?: string;
+  // HTTP
+  scheme?: 'Bearer' | 'Basic';
+  token?: string;
+  username?: string;
+  password?: string;
+}
+
 interface FrontmatterRemoteAgentDefinition
   extends FrontmatterBaseAgentDefinition {
   kind: 'remote';
   description?: string;
   agent_card_url: string;
+  auth?: FrontmatterAuthConfig;
 }
 
 type FrontmatterAgentDefinition =
@@ -95,6 +114,66 @@ const localAgentSchema = z
   })
   .strict();
 
+/**
+ * Base fields shared by all auth configs.
+ */
+const baseAuthFields = {
+  agent_card_requires_auth: z.boolean().optional(),
+};
+
+/**
+ * API Key auth schema.
+ * Supports sending key in header, query parameter, or cookie.
+ */
+const apiKeyAuthSchema = z.object({
+  ...baseAuthFields,
+  type: z.literal('apiKey'),
+  key: z.string().min(1, 'API key is required'),
+  in: z.enum(['header', 'query', 'cookie']).optional(),
+  name: z.string().optional(),
+});
+
+/**
+ * HTTP auth schema (Bearer or Basic).
+ * Note: Validation for scheme-specific fields is applied in authConfigSchema
+ * since discriminatedUnion doesn't support refined schemas directly.
+ */
+const httpAuthSchemaBase = z.object({
+  ...baseAuthFields,
+  type: z.literal('http'),
+  scheme: z.enum(['Bearer', 'Basic']),
+  token: z.string().optional(),
+  username: z.string().optional(),
+  password: z.string().optional(),
+});
+
+/**
+ * Combined auth schema - discriminated union of all auth types.
+ * Note: We use the base schema for discriminatedUnion, then apply refinements
+ * via superRefine since discriminatedUnion doesn't support refined schemas directly.
+ */
+const authConfigSchema = z
+  .discriminatedUnion('type', [apiKeyAuthSchema, httpAuthSchemaBase])
+  .superRefine((data, ctx) => {
+    // Apply HTTP auth validation after union parsing
+    if (data.type === 'http') {
+      if (data.scheme === 'Bearer' && !data.token) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Bearer scheme requires "token"',
+          path: ['token'],
+        });
+      }
+      if (data.scheme === 'Basic' && (!data.username || !data.password)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Basic scheme requires "username" and "password"',
+          path: data.username ? ['password'] : ['username'],
+        });
+      }
+    }
+  });
+
 const remoteAgentSchema = z
   .object({
     kind: z.literal('remote').optional().default('remote'),
@@ -102,6 +181,7 @@ const remoteAgentSchema = z
     description: z.string().optional(),
     display_name: z.string().optional(),
     agent_card_url: z.string().url(),
+    auth: authConfigSchema.optional(),
   })
   .strict();
 
@@ -238,6 +318,76 @@ export async function parseAgentMarkdown(
   return [agentDef];
 }
 
+/**
+ * Converts frontmatter auth config to the internal A2AAuthConfig type.
+ * This handles the mapping from snake_case YAML to the internal type structure.
+ */
+function convertFrontmatterAuthToConfig(
+  frontmatter: FrontmatterAuthConfig,
+): A2AAuthConfig {
+  const base = {
+    agent_card_requires_auth: frontmatter.agent_card_requires_auth,
+  };
+
+  switch (frontmatter.type) {
+    case 'apiKey':
+      if (!frontmatter.key) {
+        throw new Error('Internal error: API key missing after validation.');
+      }
+      return {
+        ...base,
+        type: 'apiKey',
+        key: frontmatter.key,
+        location: frontmatter.in,
+        name: frontmatter.name,
+      };
+
+    case 'http': {
+      if (!frontmatter.scheme) {
+        throw new Error(
+          'Internal error: HTTP scheme missing after validation.',
+        );
+      }
+      switch (frontmatter.scheme) {
+        case 'Bearer':
+          if (!frontmatter.token) {
+            throw new Error(
+              'Internal error: Bearer token missing after validation.',
+            );
+          }
+          return {
+            ...base,
+            type: 'http',
+            scheme: 'Bearer',
+            token: frontmatter.token,
+          };
+        case 'Basic':
+          if (!frontmatter.username || !frontmatter.password) {
+            throw new Error(
+              'Internal error: Basic auth credentials missing after validation.',
+            );
+          }
+          return {
+            ...base,
+            type: 'http',
+            scheme: 'Basic',
+            username: frontmatter.username,
+            password: frontmatter.password,
+          };
+        default: {
+          const exhaustive: never = frontmatter.scheme;
+          throw new Error(`Unknown HTTP scheme: ${exhaustive}`);
+        }
+      }
+    }
+
+    default: {
+      const exhaustive: never = frontmatter.type;
+      throw new Error(`Unknown auth type: ${exhaustive}`);
+    }
+  }
+}
+
 /**
  * Converts a FrontmatterAgentDefinition DTO to the internal AgentDefinition structure.
  *
@@ -270,6 +420,9 @@ export function markdownToAgentDefinition(
       description: markdown.description || '(Loading description...)',
       displayName: markdown.display_name,
       agentCardUrl: markdown.agent_card_url,
+      auth: markdown.auth
+        ? convertFrontmatterAuthToConfig(markdown.auth)
+        : undefined,
       inputConfig,
       metadata,
     };
diff --git a/packages/core/src/agents/auth-provider/base-provider.ts b/packages/core/src/agents/auth-provider/base-provider.ts
index 7b21853a09..7fb2e61acc 100644
--- a/packages/core/src/agents/auth-provider/base-provider.ts
+++ b/packages/core/src/agents/auth-provider/base-provider.ts
@@ -9,17 +9,33 @@ import type { A2AAuthProvider, A2AAuthProviderType } from './types.js';
 
 /**
  * Abstract base class for A2A authentication providers.
+ * Provides default implementations for optional methods.
  */
 export abstract class BaseA2AAuthProvider implements A2AAuthProvider {
+  /**
+   * The type of authentication provider.
+   */
   abstract readonly type: A2AAuthProviderType;
+
+  /**
+   * Get the HTTP headers to include in requests.
+   * Subclasses must implement this method.
+   */
   abstract headers(): Promise<HttpHeaders>;
 
   private static readonly MAX_AUTH_RETRIES = 2;
   private authRetryCount = 0;
 
   /**
-   * Default: retry on 401/403 with fresh headers.
-   * Subclasses with cached tokens must override to force-refresh to avoid infinite retries.
+   * Check if a request should be retried with new headers.
+   *
+   * The default implementation checks for 401/403 status codes and
+   * returns fresh headers for retry. Subclasses can override for
+   * custom retry logic.
+   *
+   * @param _req The original request init
+   * @param res The response from the server
+   * @returns New headers for retry, or undefined if no retry should be made
    */
   async shouldRetryWithHeaders(
     _req: RequestInit,
@@ -32,10 +48,15 @@ export abstract class BaseA2AAuthProvider implements A2AAuthProvider {
       this.authRetryCount++;
       return this.headers();
     }
-    // Reset on success
+    // Reset count if not an auth error
     this.authRetryCount = 0;
     return undefined;
   }
 
-  async initialize(): Promise<void> {}
+  /**
+   * Initialize the provider. Override in subclasses that need async setup.
+   */
+  async initialize(): Promise<void> {
+    // Default: no-op
+  }
 }
diff --git a/packages/core/src/agents/auth-provider/value-resolver.test.ts b/packages/core/src/agents/auth-provider/value-resolver.test.ts
new file mode 100644
index 0000000000..58aa84c077
--- /dev/null
+++ b/packages/core/src/agents/auth-provider/value-resolver.test.ts
@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import {
+  resolveAuthValue,
+  needsResolution,
+  maskSensitiveValue,
+} from './value-resolver.js';
+
+describe('value-resolver', () => {
+  describe('resolveAuthValue', () => {
+    describe('environment variables', () => {
+      afterEach(() => {
+        vi.unstubAllEnvs();
+      });
+
+      it('should resolve environment variable with $ prefix', async () => {
+        vi.stubEnv('TEST_API_KEY', 'secret-key-123');
+        const result = await resolveAuthValue('$TEST_API_KEY');
+        expect(result).toBe('secret-key-123');
+      });
+
+      it('should throw error for unset environment variable', async () => {
+        await expect(resolveAuthValue('$UNSET_VAR_12345')).rejects.toThrow(
+          "Environment variable 'UNSET_VAR_12345' is not set or is empty",
+        );
+      });
+
+      it('should throw error for empty environment variable', async () => {
+        vi.stubEnv('EMPTY_VAR', '');
+        await expect(resolveAuthValue('$EMPTY_VAR')).rejects.toThrow(
+          "Environment variable 'EMPTY_VAR' is not set or is empty",
+        );
+      });
+    });
+
+    describe('shell commands', () => {
+      it('should execute shell command with ! prefix', async () => {
+        const result = await resolveAuthValue('!echo hello');
+        expect(result).toBe('hello');
+      });
+
+      it('should trim whitespace from command output', async () => {
+        const result = await resolveAuthValue('!echo "  hello  "');
+        expect(result).toBe('hello');
+      });
+
+      it('should throw error for empty command', async () => {
+        await expect(resolveAuthValue('!')).rejects.toThrow(
+          'Empty command in auth value',
+        );
+      });
+
+      it('should throw error for command that returns empty output', async () => {
+        await expect(resolveAuthValue('!echo -n ""')).rejects.toThrow(
+          'returned empty output',
+        );
+      });
+
+      it('should throw error for failed command', async () => {
+        await expect(
+          resolveAuthValue('!nonexistent-command-12345'),
+        ).rejects.toThrow(/Command.*failed/);
+      });
+    });
+
+    describe('literal values', () => {
+      it('should return literal value as-is', async () => {
+        const result = await resolveAuthValue('literal-api-key');
+        expect(result).toBe('literal-api-key');
+      });
+
+      it('should return empty string as-is', async () => {
+        const result = await resolveAuthValue('');
+        expect(result).toBe('');
+      });
+
+      it('should not treat values starting with other characters as special', async () => {
+        const result = await resolveAuthValue('api-key-123');
+        expect(result).toBe('api-key-123');
+      });
+    });
+
+    describe('escaped literals', () => {
+      it('should return $ literal when value starts with $$', async () => {
+        const result = await resolveAuthValue('$$LITERAL');
+        expect(result).toBe('$LITERAL');
+      });
+
+      it('should return ! literal when value starts with !!', async () => {
+        const result = await resolveAuthValue('!!not-a-command');
+        expect(result).toBe('!not-a-command');
+      });
+    });
+  });
+
+  describe('needsResolution', () => {
+    it('should return true for environment variable reference', () => {
+      expect(needsResolution('$ENV_VAR')).toBe(true);
+    });
+
+    it('should return true for command reference', () => {
+      expect(needsResolution('!command')).toBe(true);
+    });
+
+    it('should return false for literal value', () => {
+      expect(needsResolution('literal')).toBe(false);
+    });
+
+    it('should return false for empty string', () => {
+      expect(needsResolution('')).toBe(false);
+    });
+  });
+
+  describe('maskSensitiveValue', () => {
+    it('should mask value longer than 12 characters', () => {
+      expect(maskSensitiveValue('1234567890abcd')).toBe('12****cd');
+    });
+
+    it('should return **** for short values', () => {
+      expect(maskSensitiveValue('short')).toBe('****');
+    });
+
+    it('should return **** for exactly 12 characters', () => {
+      expect(maskSensitiveValue('123456789012')).toBe('****');
+    });
+
+    it('should return **** for empty string', () => {
+      expect(maskSensitiveValue('')).toBe('****');
+    });
+  });
+});
diff --git a/packages/core/src/agents/auth-provider/value-resolver.ts b/packages/core/src/agents/auth-provider/value-resolver.ts
new file mode 100644
index 0000000000..c349a57498
--- /dev/null
+++ b/packages/core/src/agents/auth-provider/value-resolver.ts
@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { debugLogger } from '../../utils/debugLogger.js';
+import { getShellConfiguration, spawnAsync } from '../../utils/shell-utils.js';
+
+const COMMAND_TIMEOUT_MS = 60_000;
+
+/**
+ * Resolves a value that may be an environment variable reference,
+ * a shell command, or a literal value.
+ *
+ * Supported formats:
+ * - `$ENV_VAR`: Read from environment variable
+ * - `!command`: Execute shell command and use output (trimmed)
+ * - `$$` or `!!`: Escape prefix, returns rest as literal
+ * - Any other string: Use as literal value
+ *
+ * @param value The value to resolve
+ * @returns The resolved value
+ * @throws Error if environment variable is not set or command fails
+ */
+export async function resolveAuthValue(value: string): Promise<string> {
+  // Support escaping with double prefix (e.g. $$ or !!).
+  // Strips one prefix char: $$FOO → $FOO, !!cmd → !cmd (literal, not resolved).
+  if (value.startsWith('$$') || value.startsWith('!!')) {
+    return value.slice(1);
+  }
+
+  // Environment variable: $MY_VAR
+  if (value.startsWith('$')) {
+    const envVar = value.slice(1);
+    const resolved = process.env[envVar];
+    if (resolved === undefined || resolved === '') {
+      throw new Error(
+        `Environment variable '${envVar}' is not set or is empty. ` +
+          `Please set it before using this agent.`,
+      );
+    }
+    debugLogger.debug(`[AuthValueResolver] Resolved env var: ${envVar}`);
+    return resolved;
+  }
+
+  // Shell command: !command arg1 arg2
+  if (value.startsWith('!')) {
+    const command = value.slice(1).trim();
+    if (!command) {
+      throw new Error('Empty command in auth value. Expected format: !command');
+    }
+
+    debugLogger.debug(`[AuthValueResolver] Executing command for auth value`);
+
+    const shellConfig = getShellConfiguration();
+    try {
+      const { stdout } = await spawnAsync(
+        shellConfig.executable,
+        [...shellConfig.argsPrefix, command],
+        {
+          signal: AbortSignal.timeout(COMMAND_TIMEOUT_MS),
+          windowsHide: true,
+        },
+      );
+
+      const trimmed = stdout.trim();
+      if (!trimmed) {
+        throw new Error(`Command '${command}' returned empty output`);
+      }
+      return trimmed;
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new Error(
+          `Command '${command}' timed out after ${COMMAND_TIMEOUT_MS / 1000} seconds`,
+        );
+      }
+      throw error;
+    }
+  }
+
+  // Literal value - return as-is
+  return value;
+}
+
+/**
+ * Check if a value needs resolution (is an env var or command reference).
+ */
+export function needsResolution(value: string): boolean {
+  return value.startsWith('$') || value.startsWith('!');
+}
+
+/**
+ * Mask a sensitive value for logging purposes.
+ * Shows the first and last 2 characters with asterisks in between.
+ */
+export function maskSensitiveValue(value: string): string {
+  if (value.length <= 12) {
+    return '****';
+  }
+  return `${value.slice(0, 2)}****${value.slice(-2)}`;
+}

From 00966062b82d552e703d2aec186e7b4ae0a16aac Mon Sep 17 00:00:00 2001
From: Dev Randalpura <devrandalpura@google.com>
Date: Wed, 11 Feb 2026 13:47:02 -0800
Subject: [PATCH 05/44] Removed getPlainTextLength (#18848)

---
 .../ui/utils/InlineMarkdownRenderer.test.ts   | 25 -------------------
 .../src/ui/utils/InlineMarkdownRenderer.tsx   | 17 -------------
 2 files changed, 42 deletions(-)
 delete mode 100644 packages/cli/src/ui/utils/InlineMarkdownRenderer.test.ts

diff --git a/packages/cli/src/ui/utils/InlineMarkdownRenderer.test.ts b/packages/cli/src/ui/utils/InlineMarkdownRenderer.test.ts
deleted file mode 100644
index 11fb6d56eb..0000000000
--- a/packages/cli/src/ui/utils/InlineMarkdownRenderer.test.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { getPlainTextLength } from './InlineMarkdownRenderer.js';
-import { describe, it, expect } from 'vitest';
-
-describe('getPlainTextLength', () => {
-  it.each([
-    ['**Primary Go', 12],
-    ['*Primary Go', 11],
-    ['**Primary Go**', 10],
-    ['*Primary Go*', 10],
-    ['**', 2],
-    ['*', 1],
-    ['compile-time**', 14],
-  ])(
-    'should measure markdown text length correctly for "%s"',
-    (input, expected) => {
-      expect(getPlainTextLength(input)).toBe(expected);
-    },
-  );
-});
diff --git a/packages/cli/src/ui/utils/InlineMarkdownRenderer.tsx b/packages/cli/src/ui/utils/InlineMarkdownRenderer.tsx
index 8d4c6a7da6..0418582919 100644
--- a/packages/cli/src/ui/utils/InlineMarkdownRenderer.tsx
+++ b/packages/cli/src/ui/utils/InlineMarkdownRenderer.tsx
@@ -7,7 +7,6 @@
 import React from 'react';
 import { Text } from 'ink';
 import { theme } from '../semantic-colors.js';
-import stringWidth from 'string-width';
 import { debugLogger } from '@google/gemini-cli-core';
 
 // Constants for Markdown parsing
@@ -171,19 +170,3 @@ const RenderInlineInternal: React.FC<RenderInlineProps> = ({
 };
 
 export const RenderInline = React.memo(RenderInlineInternal);
-
-/**
- * Utility function to get the plain text length of a string with markdown formatting
- * This is useful for calculating column widths in tables
- */
-export const getPlainTextLength = (text: string): number => {
-  const cleanText = text
-    .replace(/\*\*(.*?)\*\*/g, '$1')
-    .replace(/\*(.+?)\*/g, '$1')
-    .replace(/_(.*?)_/g, '$1')
-    .replace(/~~(.*?)~~/g, '$1')
-    .replace(/`(.*?)`/g, '$1')
-    .replace(/<u>(.*?)<\/u>/g, '$1')
-    .replace(/.*\[(.*?)\]\(.*\)/g, '$1');
-  return stringWidth(cleanText);
-};

From 6c1773170e952cc95dacd88e3d63996364527d34 Mon Sep 17 00:00:00 2001
From: Christian Gunderman <gundermanc@gmail.com>
Date: Wed, 11 Feb 2026 21:55:27 +0000
Subject: [PATCH 06/44] More grep prompt tweaks (#18846)

---
 evals/frugalSearch.eval.ts                    | 36 ++++++++++-------
 .../core/__snapshots__/prompts.test.ts.snap   | 39 ++++++++++++-------
 packages/core/src/prompts/snippets.ts         |  3 +-
 3 files changed, 51 insertions(+), 27 deletions(-)

diff --git a/evals/frugalSearch.eval.ts b/evals/frugalSearch.eval.ts
index e4f3e85956..11c51e8529 100644
--- a/evals/frugalSearch.eval.ts
+++ b/evals/frugalSearch.eval.ts
@@ -7,6 +7,11 @@
 import { describe, expect } from 'vitest';
 import { evalTest } from './test-helper.js';
 
+/**
+ * Evals to verify that the agent uses search tools efficiently (frugally)
+ * by utilizing limiting parameters like `total_max_matches` and `max_matches_per_file`.
+ * This ensures the agent doesn't flood the context window with unnecessary search results.
+ */
 describe('Frugal Search', () => {
   const getGrepParams = (call: any): any => {
     let args = call.toolRequest.args;
@@ -112,21 +117,26 @@ describe('Frugal Search', () => {
 
       expect(grepCalls.length).toBeGreaterThan(0);
 
-      const hasFrugalLimit = grepCalls.some((call) => {
-        const params = getGrepParams(call);
-        // Check for explicitly set small limit for "sample" or "example" requests
-        return (
-          params.total_max_matches !== undefined &&
-          params.total_max_matches <= 100
-        );
-      });
+      const grepParams = grepCalls.map(getGrepParams);
 
+      const hasTotalMaxLimit = grepParams.some(
+        (p) => p.total_max_matches !== undefined && p.total_max_matches <= 100,
+      );
       expect(
-        hasFrugalLimit,
-        `Expected agent to use a small total_max_matches for a sample usage request. Params used: ${JSON.stringify(
-          grepCalls.map(getGrepParams),
-          null,
-          2,
+        hasTotalMaxLimit,
+        `Expected agent to use a small total_max_matches (<= 100) for a sample usage request. Actual values: ${JSON.stringify(
+          grepParams.map((p) => p.total_max_matches),
+        )}`,
+      ).toBe(true);
+
+      const hasMaxMatchesPerFileLimit = grepParams.some(
+        (p) =>
+          p.max_matches_per_file !== undefined && p.max_matches_per_file <= 5,
+      );
+      expect(
+        hasMaxMatchesPerFileLimit,
+        `Expected agent to use a small max_matches_per_file (<= 5) for a sample usage request. Actual values: ${JSON.stringify(
+          grepParams.map((p) => p.max_matches_per_file),
         )}`,
       ).toBe(true);
     },
diff --git a/packages/core/src/core/__snapshots__/prompts.test.ts.snap b/packages/core/src/core/__snapshots__/prompts.test.ts.snap
index c827d66ddc..e944565366 100644
--- a/packages/core/src/core/__snapshots__/prompts.test.ts.snap
+++ b/packages/core/src/core/__snapshots__/prompts.test.ts.snap
@@ -520,7 +520,8 @@ exports[`Core System Prompt (prompts.ts) > should append userMemory with separat
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -650,7 +651,8 @@ exports[`Core System Prompt (prompts.ts) > should handle CodebaseInvestigator wi
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -745,7 +747,8 @@ exports[`Core System Prompt (prompts.ts) > should handle CodebaseInvestigator wi
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1309,7 +1312,8 @@ exports[`Core System Prompt (prompts.ts) > should include available_skills with
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1435,7 +1439,8 @@ exports[`Core System Prompt (prompts.ts) > should include correct sandbox instru
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1552,7 +1557,8 @@ exports[`Core System Prompt (prompts.ts) > should include correct sandbox instru
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1669,7 +1675,8 @@ exports[`Core System Prompt (prompts.ts) > should include correct sandbox instru
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1782,7 +1789,8 @@ exports[`Core System Prompt (prompts.ts) > should include planning phase suggest
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1895,7 +1903,8 @@ exports[`Core System Prompt (prompts.ts) > should include sub-agents in XML for
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -2247,7 +2256,8 @@ exports[`Core System Prompt (prompts.ts) > should return the base prompt when us
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -2360,7 +2370,8 @@ exports[`Core System Prompt (prompts.ts) > should return the base prompt when us
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -2584,7 +2595,8 @@ exports[`Core System Prompt (prompts.ts) > should use chatty system prompt for p
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -2697,7 +2709,8 @@ exports[`Core System Prompt (prompts.ts) > should use chatty system prompt for p
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your grep_search searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
diff --git a/packages/core/src/prompts/snippets.ts b/packages/core/src/prompts/snippets.ts
index f1b9f6dc12..3dcf346de6 100644
--- a/packages/core/src/prompts/snippets.ts
+++ b/packages/core/src/prompts/snippets.ts
@@ -165,7 +165,8 @@ export function renderCoreMandates(options?: CoreMandatesOptions): string {
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always minimize wasted context window by scoping and limiting all of your ${GREP_TOOL_NAME} searches. e.g.: pass total_max_matches, include, and max_matches_per_file.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in ${formattedFilenames} files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.

From b8008695dbedc8d2e03de2d97c697a87e15c4fc9 Mon Sep 17 00:00:00 2001
From: Pyush Sinha <pyushsinha20@gmail.com>
Date: Wed, 11 Feb 2026 15:40:27 -0800
Subject: [PATCH 07/44] refactor(cli): Reactive useSettingsStore hook (#14915)

---
 packages/cli/src/config/settings.test.ts      |  44 +++++
 packages/cli/src/config/settings.ts           |  48 +++++
 .../src/ui/contexts/SettingsContext.test.tsx  | 167 ++++++++++++++++++
 .../cli/src/ui/contexts/SettingsContext.tsx   |  70 +++++++-
 4 files changed, 326 insertions(+), 3 deletions(-)
 create mode 100644 packages/cli/src/ui/contexts/SettingsContext.test.tsx

diff --git a/packages/cli/src/config/settings.test.ts b/packages/cli/src/config/settings.test.ts
index 721458952f..e88c9104dd 100644
--- a/packages/cli/src/config/settings.test.ts
+++ b/packages/cli/src/config/settings.test.ts
@@ -2546,6 +2546,50 @@ describe('Settings Loading and Merging', () => {
     });
   });
 
+  describe('Reactivity & Snapshots', () => {
+    let loadedSettings: LoadedSettings;
+
+    beforeEach(() => {
+      const emptySettingsFile: SettingsFile = {
+        path: '/mock/path',
+        settings: {},
+        originalSettings: {},
+      };
+
+      loadedSettings = new LoadedSettings(
+        { ...emptySettingsFile, path: getSystemSettingsPath() },
+        { ...emptySettingsFile, path: getSystemDefaultsPath() },
+        { ...emptySettingsFile, path: USER_SETTINGS_PATH },
+        { ...emptySettingsFile, path: MOCK_WORKSPACE_SETTINGS_PATH },
+        true, // isTrusted
+        [],
+      );
+    });
+
+    it('getSnapshot() should return stable reference if no changes occur', () => {
+      const snap1 = loadedSettings.getSnapshot();
+      const snap2 = loadedSettings.getSnapshot();
+      expect(snap1).toBe(snap2);
+    });
+
+    it('setValue() should create a new snapshot reference and emit event', () => {
+      const oldSnapshot = loadedSettings.getSnapshot();
+      const oldUserRef = oldSnapshot.user.settings;
+
+      loadedSettings.setValue(SettingScope.User, 'ui.theme', 'high-contrast');
+
+      const newSnapshot = loadedSettings.getSnapshot();
+
+      expect(newSnapshot).not.toBe(oldSnapshot);
+      expect(newSnapshot.user.settings).not.toBe(oldUserRef);
+      expect(newSnapshot.user.settings.ui?.theme).toBe('high-contrast');
+
+      expect(newSnapshot.system.settings).not.toBe(oldSnapshot.system.settings);
+
+      expect(mockCoreEvents.emitSettingsChanged).toHaveBeenCalled();
+    });
+  });
+
   describe('Security and Sandbox', () => {
     let originalArgv: string[];
     let originalEnv: NodeJS.ProcessEnv;
diff --git a/packages/cli/src/config/settings.ts b/packages/cli/src/config/settings.ts
index 8e9ff7380f..b2b526a010 100644
--- a/packages/cli/src/config/settings.ts
+++ b/packages/cli/src/config/settings.ts
@@ -10,6 +10,7 @@ import { platform } from 'node:os';
 import * as dotenv from 'dotenv';
 import process from 'node:process';
 import {
+  CoreEvent,
   FatalConfigError,
   GEMINI_DIR,
   getErrorMessage,
@@ -284,6 +285,20 @@ export function createTestMergedSettings(
   ) as MergedSettings;
 }
 
+/**
+ * An immutable snapshot of settings state.
+ * Used with useSyncExternalStore for reactive updates.
+ */
+export interface LoadedSettingsSnapshot {
+  system: SettingsFile;
+  systemDefaults: SettingsFile;
+  user: SettingsFile;
+  workspace: SettingsFile;
+  isTrusted: boolean;
+  errors: SettingsError[];
+  merged: MergedSettings;
+}
+
 export class LoadedSettings {
   constructor(
     system: SettingsFile,
@@ -303,6 +318,7 @@ export class LoadedSettings {
       : this.createEmptyWorkspace(workspace);
     this.errors = errors;
     this._merged = this.computeMergedSettings();
+    this._snapshot = this.computeSnapshot();
   }
 
   readonly system: SettingsFile;
@@ -314,6 +330,7 @@ export class LoadedSettings {
 
   private _workspaceFile: SettingsFile;
   private _merged: MergedSettings;
+  private _snapshot: LoadedSettingsSnapshot;
   private _remoteAdminSettings: Partial<Settings> | undefined;
 
   get merged(): MergedSettings {
@@ -368,6 +385,36 @@ export class LoadedSettings {
     return merged;
   }
 
+  private computeSnapshot(): LoadedSettingsSnapshot {
+    const cloneSettingsFile = (file: SettingsFile): SettingsFile => ({
+      path: file.path,
+      rawJson: file.rawJson,
+      settings: structuredClone(file.settings),
+      originalSettings: structuredClone(file.originalSettings),
+    });
+    return {
+      system: cloneSettingsFile(this.system),
+      systemDefaults: cloneSettingsFile(this.systemDefaults),
+      user: cloneSettingsFile(this.user),
+      workspace: cloneSettingsFile(this.workspace),
+      isTrusted: this.isTrusted,
+      errors: [...this.errors],
+      merged: structuredClone(this._merged),
+    };
+  }
+
+  // Passing this along with getSnapshot to useSyncExternalStore allows for idiomatic reactivity on settings changes
+  // React will pass a listener fn into this subscribe fn
+  // that listener fn will perform an object identity check on the snapshot and trigger a React re render if the snapshot has changed
+  subscribe(listener: () => void): () => void {
+    coreEvents.on(CoreEvent.SettingsChanged, listener);
+    return () => coreEvents.off(CoreEvent.SettingsChanged, listener);
+  }
+
+  getSnapshot(): LoadedSettingsSnapshot {
+    return this._snapshot;
+  }
+
   forScope(scope: LoadableSettingScope): SettingsFile {
     switch (scope) {
       case SettingScope.User:
@@ -409,6 +456,7 @@ export class LoadedSettings {
     }
 
     this._merged = this.computeMergedSettings();
+    this._snapshot = this.computeSnapshot();
     coreEvents.emitSettingsChanged();
   }
 
diff --git a/packages/cli/src/ui/contexts/SettingsContext.test.tsx b/packages/cli/src/ui/contexts/SettingsContext.test.tsx
new file mode 100644
index 0000000000..3124108f90
--- /dev/null
+++ b/packages/cli/src/ui/contexts/SettingsContext.test.tsx
@@ -0,0 +1,167 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { Component, type ReactNode } from 'react';
+import { renderHook, render } from '../../test-utils/render.js';
+import { act } from 'react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SettingsContext, useSettingsStore } from './SettingsContext.js';
+import {
+  type LoadedSettings,
+  SettingScope,
+  type LoadedSettingsSnapshot,
+  type SettingsFile,
+  createTestMergedSettings,
+} from '../../config/settings.js';
+
+const createMockSettingsFile = (path: string): SettingsFile => ({
+  path,
+  settings: {},
+  originalSettings: {},
+});
+
+const mockSnapshot: LoadedSettingsSnapshot = {
+  system: createMockSettingsFile('/system'),
+  systemDefaults: createMockSettingsFile('/defaults'),
+  user: createMockSettingsFile('/user'),
+  workspace: createMockSettingsFile('/workspace'),
+  isTrusted: true,
+  errors: [],
+  merged: createTestMergedSettings({
+    ui: { theme: 'default-theme' },
+  }),
+};
+
+class ErrorBoundary extends Component<
+  { children: ReactNode; onError: (error: Error) => void },
+  { hasError: boolean }
+> {
+  constructor(props: { children: ReactNode; onError: (error: Error) => void }) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(_error: Error) {
+    return { hasError: true };
+  }
+
+  override componentDidCatch(error: Error) {
+    this.props.onError(error);
+  }
+
+  override render() {
+    if (this.state.hasError) {
+      return null;
+    }
+    return this.props.children;
+  }
+}
+
+const TestHarness = () => {
+  useSettingsStore();
+  return null;
+};
+
+describe('SettingsContext', () => {
+  let mockLoadedSettings: LoadedSettings;
+  let listeners: Array<() => void> = [];
+
+  beforeEach(() => {
+    listeners = [];
+
+    mockLoadedSettings = {
+      subscribe: vi.fn((listener: () => void) => {
+        listeners.push(listener);
+        return () => {
+          listeners = listeners.filter((l) => l !== listener);
+        };
+      }),
+      getSnapshot: vi.fn(() => mockSnapshot),
+      setValue: vi.fn(),
+    } as unknown as LoadedSettings;
+  });
+
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <SettingsContext.Provider value={mockLoadedSettings}>
+      {children}
+    </SettingsContext.Provider>
+  );
+
+  it('should provide the correct initial state', () => {
+    const { result } = renderHook(() => useSettingsStore(), { wrapper });
+
+    expect(result.current.settings.merged).toEqual(mockSnapshot.merged);
+    expect(result.current.settings.isTrusted).toBe(true);
+  });
+
+  it('should allow accessing settings for a specific scope', () => {
+    const { result } = renderHook(() => useSettingsStore(), { wrapper });
+
+    const userSettings = result.current.settings.forScope(SettingScope.User);
+    expect(userSettings).toBe(mockSnapshot.user);
+
+    const workspaceSettings = result.current.settings.forScope(
+      SettingScope.Workspace,
+    );
+    expect(workspaceSettings).toBe(mockSnapshot.workspace);
+  });
+
+  it('should trigger re-renders when settings change (external event)', () => {
+    const { result } = renderHook(() => useSettingsStore(), { wrapper });
+
+    expect(result.current.settings.merged.ui?.theme).toBe('default-theme');
+
+    const newSnapshot = {
+      ...mockSnapshot,
+      merged: { ui: { theme: 'new-theme' } },
+    };
+    (
+      mockLoadedSettings.getSnapshot as ReturnType<typeof vi.fn>
+    ).mockReturnValue(newSnapshot);
+
+    // Trigger the listeners (simulate coreEvents emission)
+    act(() => {
+      listeners.forEach((l) => l());
+    });
+
+    expect(result.current.settings.merged.ui?.theme).toBe('new-theme');
+  });
+
+  it('should call store.setValue when setSetting is called', () => {
+    const { result } = renderHook(() => useSettingsStore(), { wrapper });
+
+    act(() => {
+      result.current.setSetting(SettingScope.User, 'ui.theme', 'dark');
+    });
+
+    expect(mockLoadedSettings.setValue).toHaveBeenCalledWith(
+      SettingScope.User,
+      'ui.theme',
+      'dark',
+    );
+  });
+
+  it('should throw error if used outside provider', () => {
+    const onError = vi.fn();
+    // Suppress console.error (React logs error boundary info)
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    render(
+      <ErrorBoundary onError={onError}>
+        <TestHarness />
+      </ErrorBoundary>,
+    );
+
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: 'useSettingsStore must be used within a SettingsProvider',
+      }),
+    );
+
+    consoleSpy.mockRestore();
+  });
+});
diff --git a/packages/cli/src/ui/contexts/SettingsContext.tsx b/packages/cli/src/ui/contexts/SettingsContext.tsx
index 144e1a2859..2c5ae37dfd 100644
--- a/packages/cli/src/ui/contexts/SettingsContext.tsx
+++ b/packages/cli/src/ui/contexts/SettingsContext.tsx
@@ -4,17 +4,81 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import React, { useContext } from 'react';
-import type { LoadedSettings } from '../../config/settings.js';
+import React, { useContext, useMemo, useSyncExternalStore } from 'react';
+import type {
+  LoadableSettingScope,
+  LoadedSettings,
+  LoadedSettingsSnapshot,
+  SettingsFile,
+} from '../../config/settings.js';
+import { SettingScope } from '../../config/settings.js';
 
 export const SettingsContext = React.createContext<LoadedSettings | undefined>(
   undefined,
 );
 
-export const useSettings = () => {
+export const useSettings = (): LoadedSettings => {
   const context = useContext(SettingsContext);
   if (context === undefined) {
     throw new Error('useSettings must be used within a SettingsProvider');
   }
   return context;
 };
+
+export interface SettingsState extends LoadedSettingsSnapshot {
+  forScope: (scope: LoadableSettingScope) => SettingsFile;
+}
+
+export interface SettingsStoreValue {
+  settings: SettingsState;
+  setSetting: (
+    scope: LoadableSettingScope,
+    key: string,
+    value: unknown,
+  ) => void;
+}
+
+// Components that call this hook will re render when a settings change event is emitted
+export const useSettingsStore = (): SettingsStoreValue => {
+  const store = useContext(SettingsContext);
+  if (store === undefined) {
+    throw new Error('useSettingsStore must be used within a SettingsProvider');
+  }
+
+  // React passes a listener fn into the subscribe function
+  // When the listener runs, it re renders the component if the snapshot changed
+  const snapshot = useSyncExternalStore(
+    (listener) => store.subscribe(listener),
+    () => store.getSnapshot(),
+  );
+
+  const settings: SettingsState = useMemo(
+    () => ({
+      ...snapshot,
+      forScope: (scope: LoadableSettingScope) => {
+        switch (scope) {
+          case SettingScope.User:
+            return snapshot.user;
+          case SettingScope.Workspace:
+            return snapshot.workspace;
+          case SettingScope.System:
+            return snapshot.system;
+          case SettingScope.SystemDefaults:
+            return snapshot.systemDefaults;
+          default:
+            throw new Error(`Invalid scope: ${scope}`);
+        }
+      },
+    }),
+    [snapshot],
+  );
+
+  return useMemo(
+    () => ({
+      settings,
+      setSetting: (scope: LoadableSettingScope, key: string, value: unknown) =>
+        store.setValue(scope, key, value),
+    }),
+    [settings, store],
+  );
+};

From 941691ce72367f278ff6807e5e98d60d977c1e52 Mon Sep 17 00:00:00 2001
From: Richie Foreman <richie.foreman@gmail.com>
Date: Wed, 11 Feb 2026 16:07:51 -0800
Subject: [PATCH 08/44] fix(mcp): Ensure that stdio MCP server execution has
 the `GEMINI_CLI=1` env variable populated. (#18832)

---
 .../src/services/shellExecutionService.ts     | 15 ++++++++++++-
 packages/core/src/tools/mcp-client.test.ts    | 22 +++++++++++++++++++
 packages/core/src/tools/mcp-client.ts         |  7 +++++-
 3 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/services/shellExecutionService.ts b/packages/core/src/services/shellExecutionService.ts
index 23ac63f772..96cae8c269 100644
--- a/packages/core/src/services/shellExecutionService.ts
+++ b/packages/core/src/services/shellExecutionService.ts
@@ -32,6 +32,18 @@ const { Terminal } = pkg;
 
 const MAX_CHILD_PROCESS_BUFFER_SIZE = 16 * 1024 * 1024; // 16MB
 
+/**
+ * An environment variable that is set for shell executions. This can be used
+ * by downstream executables and scripts to identify that they were executed
+ * from within Gemini CLI.
+ */
+export const GEMINI_CLI_IDENTIFICATION_ENV_VAR = 'GEMINI_CLI';
+
+/**
+ * The value of {@link GEMINI_CLI_IDENTIFICATION_ENV_VAR}
+ */
+export const GEMINI_CLI_IDENTIFICATION_ENV_VAR_VALUE = '1';
+
 // We want to allow shell outputs that are close to the context window in size.
 // 300,000 lines is roughly equivalent to a large context window, ensuring
 // we capture significant output from long-running commands.
@@ -302,7 +314,8 @@ export class ShellExecutionService {
         detached: !isWindows,
         env: {
           ...sanitizeEnvironment(process.env, sanitizationConfig),
-          GEMINI_CLI: '1',
+          [GEMINI_CLI_IDENTIFICATION_ENV_VAR]:
+            GEMINI_CLI_IDENTIFICATION_ENV_VAR_VALUE,
           TERM: 'xterm-256color',
           PAGER: 'cat',
           GIT_PAGER: 'cat',
diff --git a/packages/core/src/tools/mcp-client.test.ts b/packages/core/src/tools/mcp-client.test.ts
index 39165bde45..3f289f1732 100644
--- a/packages/core/src/tools/mcp-client.test.ts
+++ b/packages/core/src/tools/mcp-client.test.ts
@@ -1639,6 +1639,28 @@ describe('mcp-client', () => {
       });
     });
 
+    it('sets an env variable GEMINI_CLI=1 for stdio MCP servers', async () => {
+      const mockedTransport = vi
+        .spyOn(SdkClientStdioLib, 'StdioClientTransport')
+        .mockReturnValue({} as SdkClientStdioLib.StdioClientTransport);
+
+      await createTransport(
+        'test-server',
+        {
+          command: 'test-command',
+          args: ['--foo', 'bar'],
+          env: {},
+          cwd: 'test/cwd',
+        },
+        false,
+        EMPTY_CONFIG,
+      );
+
+      const callArgs = mockedTransport.mock.calls[0][0];
+      expect(callArgs.env).toBeDefined();
+      expect(callArgs.env!['GEMINI_CLI']).toBe('1');
+    });
+
     it('should exclude extension settings with undefined values from environment', async () => {
       const mockedTransport = vi
         .spyOn(SdkClientStdioLib, 'StdioClientTransport')
diff --git a/packages/core/src/tools/mcp-client.ts b/packages/core/src/tools/mcp-client.ts
index 2588d54dba..7902d8953a 100644
--- a/packages/core/src/tools/mcp-client.ts
+++ b/packages/core/src/tools/mcp-client.ts
@@ -67,6 +67,10 @@ import {
   sanitizeEnvironment,
   type EnvironmentSanitizationConfig,
 } from '../services/environmentSanitization.js';
+import {
+  GEMINI_CLI_IDENTIFICATION_ENV_VAR,
+  GEMINI_CLI_IDENTIFICATION_ENV_VAR_VALUE,
+} from '../services/shellExecutionService.js';
 
 export const MCP_DEFAULT_TIMEOUT_MSEC = 10 * 60 * 1000; // default to 10 minutes
 
@@ -1897,10 +1901,11 @@ export async function createTransport(
     let transport: Transport = new StdioClientTransport({
       command: mcpServerConfig.command,
       args: mcpServerConfig.args || [],
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
       env: {
         ...sanitizeEnvironment(process.env, sanitizationConfig),
         ...(mcpServerConfig.env || {}),
+        [GEMINI_CLI_IDENTIFICATION_ENV_VAR]:
+          GEMINI_CLI_IDENTIFICATION_ENV_VAR_VALUE,
       } as Record<string, string>,
       cwd: mcpServerConfig.cwd,
       stderr: 'pipe',

From 08e8eeab841fbd16554d01a273f9a67a0825d233 Mon Sep 17 00:00:00 2001
From: Gal Zahavi <38544478+galz10@users.noreply.github.com>
Date: Wed, 11 Feb 2026 16:20:54 -0800
Subject: [PATCH 09/44] fix(core): improve headless mode detection for flags
 and query args (#18855)

---
 packages/cli/src/config/config.ts             |  9 ++--
 .../cli/src/config/trustedFolders.test.ts     |  8 +++
 packages/cli/src/config/trustedFolders.ts     | 21 ++++++--
 packages/core/src/utils/headless.test.ts      | 52 ++++++++++++++++---
 packages/core/src/utils/headless.ts           | 29 +++++++----
 5 files changed, 94 insertions(+), 25 deletions(-)

diff --git a/packages/cli/src/config/config.ts b/packages/cli/src/config/config.ts
index 87eb1e8fa7..f164ce77d8 100755
--- a/packages/cli/src/config/config.ts
+++ b/packages/cli/src/config/config.ts
@@ -445,7 +445,11 @@ export async function loadCliConfig(
     process.env['VITEST'] === 'true'
       ? false
       : (settings.security?.folderTrust?.enabled ?? false);
-  const trustedFolder = isWorkspaceTrusted(settings, cwd)?.isTrusted ?? false;
+  const trustedFolder =
+    isWorkspaceTrusted(settings, cwd, undefined, {
+      prompt: argv.prompt,
+      query: argv.query,
+    })?.isTrusted ?? false;
 
   // Set the context filename in the server's memoryTool module BEFORE loading memory
   // TODO(b/343434939): This is a bit of a hack. The contextFileName should ideally be passed
@@ -602,8 +606,7 @@ export async function loadCliConfig(
   const interactive =
     !!argv.promptInteractive ||
     !!argv.experimentalAcp ||
-    (!isHeadlessMode({ prompt: argv.prompt }) &&
-      !argv.query &&
+    (!isHeadlessMode({ prompt: argv.prompt, query: argv.query }) &&
       !argv.isCommand);
 
   const allowedTools = argv.allowedTools || settings.tools?.allowed || [];
diff --git a/packages/cli/src/config/trustedFolders.test.ts b/packages/cli/src/config/trustedFolders.test.ts
index dff4610b90..892cd86e4b 100644
--- a/packages/cli/src/config/trustedFolders.test.ts
+++ b/packages/cli/src/config/trustedFolders.test.ts
@@ -449,6 +449,14 @@ describe('Trusted Folders', () => {
         false,
       );
     });
+
+    it('should return true for isPathTrusted when isHeadlessMode is true', async () => {
+      const geminiCore = await import('@google/gemini-cli-core');
+      vi.spyOn(geminiCore, 'isHeadlessMode').mockReturnValue(true);
+
+      const folders = loadTrustedFolders();
+      expect(folders.isPathTrusted('/any-untrusted-path')).toBe(true);
+    });
   });
 
   describe('Trusted Folders Caching', () => {
diff --git a/packages/cli/src/config/trustedFolders.ts b/packages/cli/src/config/trustedFolders.ts
index 1f85684900..761bc368d3 100644
--- a/packages/cli/src/config/trustedFolders.ts
+++ b/packages/cli/src/config/trustedFolders.ts
@@ -17,6 +17,7 @@ import {
   homedir,
   isHeadlessMode,
   coreEvents,
+  type HeadlessModeOptions,
 } from '@google/gemini-cli-core';
 import type { Settings } from './settings.js';
 import stripJsonComments from 'strip-json-comments';
@@ -128,7 +129,11 @@ export class LoadedTrustedFolders {
   isPathTrusted(
     location: string,
     config?: Record<string, TrustLevel>,
+    headlessOptions?: HeadlessModeOptions,
   ): boolean | undefined {
+    if (isHeadlessMode(headlessOptions)) {
+      return true;
+    }
     const configToUse = config ?? this.user.config;
 
     // Resolve location to its realpath for canonical comparison
@@ -333,6 +338,7 @@ export function isFolderTrustEnabled(settings: Settings): boolean {
 function getWorkspaceTrustFromLocalConfig(
   workspaceDir: string,
   trustConfig?: Record<string, TrustLevel>,
+  headlessOptions?: HeadlessModeOptions,
 ): TrustResult {
   const folders = loadTrustedFolders();
   const configToUse = trustConfig ?? folders.user.config;
@@ -346,7 +352,11 @@ function getWorkspaceTrustFromLocalConfig(
     );
   }
 
-  const isTrusted = folders.isPathTrusted(workspaceDir, configToUse);
+  const isTrusted = folders.isPathTrusted(
+    workspaceDir,
+    configToUse,
+    headlessOptions,
+  );
   return {
     isTrusted,
     source: isTrusted !== undefined ? 'file' : undefined,
@@ -357,8 +367,9 @@ export function isWorkspaceTrusted(
   settings: Settings,
   workspaceDir: string = process.cwd(),
   trustConfig?: Record<string, TrustLevel>,
+  headlessOptions?: HeadlessModeOptions,
 ): TrustResult {
-  if (isHeadlessMode()) {
+  if (isHeadlessMode(headlessOptions)) {
     return { isTrusted: true, source: undefined };
   }
 
@@ -372,5 +383,9 @@ export function isWorkspaceTrusted(
   }
 
   // Fall back to the local user configuration
-  return getWorkspaceTrustFromLocalConfig(workspaceDir, trustConfig);
+  return getWorkspaceTrustFromLocalConfig(
+    workspaceDir,
+    trustConfig,
+    headlessOptions,
+  );
 }
diff --git a/packages/core/src/utils/headless.test.ts b/packages/core/src/utils/headless.test.ts
index 89f42ffcd6..4708c79969 100644
--- a/packages/core/src/utils/headless.test.ts
+++ b/packages/core/src/utils/headless.test.ts
@@ -99,16 +99,50 @@ describe('isHeadlessMode', () => {
     expect(isHeadlessMode({ prompt: true })).toBe(true);
   });
 
-  it('should return false if query is provided but it is still a TTY', () => {
-    // Note: per current logic, query alone doesn't force headless if TTY
-    // This matches the existing behavior in packages/cli/src/config/config.ts
-    expect(isHeadlessMode({ query: 'test query' })).toBe(false);
+  it('should return true if query is provided', () => {
+    expect(isHeadlessMode({ query: 'test query' })).toBe(true);
+  });
+
+  it('should return true if -p or --prompt is in process.argv as a fallback', () => {
+    const originalArgv = process.argv;
+    process.argv = ['node', 'index.js', '-p', 'hello'];
+    try {
+      expect(isHeadlessMode()).toBe(true);
+    } finally {
+      process.argv = originalArgv;
+    }
+
+    process.argv = ['node', 'index.js', '--prompt', 'hello'];
+    try {
+      expect(isHeadlessMode()).toBe(true);
+    } finally {
+      process.argv = originalArgv;
+    }
+  });
+
+  it('should return true if -y or --yolo is in process.argv as a fallback', () => {
+    const originalArgv = process.argv;
+    process.argv = ['node', 'index.js', '-y'];
+    try {
+      expect(isHeadlessMode()).toBe(true);
+    } finally {
+      process.argv = originalArgv;
+    }
+
+    process.argv = ['node', 'index.js', '--yolo'];
+    try {
+      expect(isHeadlessMode()).toBe(true);
+    } finally {
+      process.argv = originalArgv;
+    }
   });
 
   it('should handle undefined process.stdout gracefully', () => {
     const originalStdout = process.stdout;
-    // @ts-expect-error - testing edge case
-    delete process.stdout;
+    Object.defineProperty(process, 'stdout', {
+      value: undefined,
+      configurable: true,
+    });
 
     try {
       expect(isHeadlessMode()).toBe(false);
@@ -122,8 +156,10 @@ describe('isHeadlessMode', () => {
 
   it('should handle undefined process.stdin gracefully', () => {
     const originalStdin = process.stdin;
-    // @ts-expect-error - testing edge case
-    delete process.stdin;
+    Object.defineProperty(process, 'stdin', {
+      value: undefined,
+      configurable: true,
+    });
 
     try {
       expect(isHeadlessMode()).toBe(false);
diff --git a/packages/core/src/utils/headless.ts b/packages/core/src/utils/headless.ts
index 27ea5f9cbf..5a46b90d6d 100644
--- a/packages/core/src/utils/headless.ts
+++ b/packages/core/src/utils/headless.ts
@@ -28,18 +28,25 @@ export interface HeadlessModeOptions {
  * @returns true if the environment is considered headless.
  */
 export function isHeadlessMode(options?: HeadlessModeOptions): boolean {
-  if (process.env['GEMINI_CLI_INTEGRATION_TEST'] === 'true') {
-    return (
-      !!options?.prompt ||
-      (!!process.stdin && !process.stdin.isTTY) ||
-      (!!process.stdout && !process.stdout.isTTY)
-    );
+  if (process.env['GEMINI_CLI_INTEGRATION_TEST'] !== 'true') {
+    const isCI =
+      process.env['CI'] === 'true' || process.env['GITHUB_ACTIONS'] === 'true';
+    if (isCI) {
+      return true;
+    }
   }
-  return (
-    process.env['CI'] === 'true' ||
-    process.env['GITHUB_ACTIONS'] === 'true' ||
-    !!options?.prompt ||
+
+  const isNotTTY =
     (!!process.stdin && !process.stdin.isTTY) ||
-    (!!process.stdout && !process.stdout.isTTY)
+    (!!process.stdout && !process.stdout.isTTY);
+
+  if (isNotTTY || !!options?.prompt || !!options?.query) {
+    return true;
+  }
+
+  // Fallback: check process.argv for flags that imply headless or auto-approve mode.
+  return process.argv.some(
+    (arg) =>
+      arg === '-p' || arg === '--prompt' || arg === '-y' || arg === '--yolo',
   );
 }

From c370d2397b17f02dbdabff366bcec0bca073a937 Mon Sep 17 00:00:00 2001
From: Abhi <43648792+abhipatel12@users.noreply.github.com>
Date: Wed, 11 Feb 2026 19:46:58 -0500
Subject: [PATCH 10/44] refactor(cli): simplify UI and remove legacy inline
 tool confirmation logic (#18566)

---
 .../AlternateBufferQuittingDisplay.tsx        |   6 +-
 .../src/ui/components/HistoryItemDisplay.tsx  |   3 -
 .../cli/src/ui/components/MainContent.tsx     |   7 +-
 .../ToolConfirmationMessageOverflow.test.tsx  | 128 ------
 .../messages/ToolGroupMessage.test.tsx        | 381 +++---------------
 .../components/messages/ToolGroupMessage.tsx  |  72 +---
 .../ToolGroupMessage.test.tsx.snap            | 111 +----
 7 files changed, 83 insertions(+), 625 deletions(-)
 delete mode 100644 packages/cli/src/ui/components/messages/ToolConfirmationMessageOverflow.test.tsx

diff --git a/packages/cli/src/ui/components/AlternateBufferQuittingDisplay.tsx b/packages/cli/src/ui/components/AlternateBufferQuittingDisplay.tsx
index fec35d46c3..8e0ede2e09 100644
--- a/packages/cli/src/ui/components/AlternateBufferQuittingDisplay.tsx
+++ b/packages/cli/src/ui/components/AlternateBufferQuittingDisplay.tsx
@@ -12,18 +12,15 @@ import { QuittingDisplay } from './QuittingDisplay.js';
 import { useAppContext } from '../contexts/AppContext.js';
 import { MAX_GEMINI_MESSAGE_LINES } from '../constants.js';
 import { useConfirmingTool } from '../hooks/useConfirmingTool.js';
-import { useConfig } from '../contexts/ConfigContext.js';
 import { ToolStatusIndicator, ToolInfo } from './messages/ToolShared.js';
 import { theme } from '../semantic-colors.js';
 
 export const AlternateBufferQuittingDisplay = () => {
   const { version } = useAppContext();
   const uiState = useUIState();
-  const config = useConfig();
 
   const confirmingTool = useConfirmingTool();
-  const showPromptedTool =
-    config.isEventDrivenSchedulerEnabled() && confirmingTool !== null;
+  const showPromptedTool = confirmingTool !== null;
 
   // We render the entire chat history and header here to ensure that the
   // conversation history is visible to the user after the app quits and the
@@ -56,7 +53,6 @@ export const AlternateBufferQuittingDisplay = () => {
           terminalWidth={uiState.mainAreaWidth}
           item={{ ...item, id: 0 }}
           isPending={true}
-          isFocused={false}
           activeShellPtyId={uiState.activePtyId}
           embeddedShellFocused={uiState.embeddedShellFocused}
         />
diff --git a/packages/cli/src/ui/components/HistoryItemDisplay.tsx b/packages/cli/src/ui/components/HistoryItemDisplay.tsx
index 41340c1b08..f41ee20895 100644
--- a/packages/cli/src/ui/components/HistoryItemDisplay.tsx
+++ b/packages/cli/src/ui/components/HistoryItemDisplay.tsx
@@ -43,7 +43,6 @@ interface HistoryItemDisplayProps {
   availableTerminalHeight?: number;
   terminalWidth: number;
   isPending: boolean;
-  isFocused?: boolean;
   commands?: readonly SlashCommand[];
   activeShellPtyId?: number | null;
   embeddedShellFocused?: boolean;
@@ -56,7 +55,6 @@ export const HistoryItemDisplay: React.FC<HistoryItemDisplayProps> = ({
   terminalWidth,
   isPending,
   commands,
-  isFocused = true,
   activeShellPtyId,
   embeddedShellFocused,
   availableTerminalHeightGemini,
@@ -179,7 +177,6 @@ export const HistoryItemDisplay: React.FC<HistoryItemDisplayProps> = ({
           groupId={itemForDisplay.id}
           availableTerminalHeight={availableTerminalHeight}
           terminalWidth={terminalWidth}
-          isFocused={isFocused}
           activeShellPtyId={activeShellPtyId}
           embeddedShellFocused={embeddedShellFocused}
           borderTop={itemForDisplay.borderTop}
diff --git a/packages/cli/src/ui/components/MainContent.tsx b/packages/cli/src/ui/components/MainContent.tsx
index 32c70e8cad..586553a1f2 100644
--- a/packages/cli/src/ui/components/MainContent.tsx
+++ b/packages/cli/src/ui/components/MainContent.tsx
@@ -19,7 +19,6 @@ import { useMemo, memo, useCallback, useEffect, useRef } from 'react';
 import { MAX_GEMINI_MESSAGE_LINES } from '../constants.js';
 import { useConfirmingTool } from '../hooks/useConfirmingTool.js';
 import { ToolConfirmationQueue } from './ToolConfirmationQueue.js';
-import { useConfig } from '../contexts/ConfigContext.js';
 
 const MemoizedHistoryItemDisplay = memo(HistoryItemDisplay);
 const MemoizedAppHeader = memo(AppHeader);
@@ -31,12 +30,10 @@ const MemoizedAppHeader = memo(AppHeader);
 export const MainContent = () => {
   const { version } = useAppContext();
   const uiState = useUIState();
-  const config = useConfig();
   const isAlternateBuffer = useAlternateBuffer();
 
   const confirmingTool = useConfirmingTool();
-  const showConfirmationQueue =
-    config.isEventDrivenSchedulerEnabled() && confirmingTool !== null;
+  const showConfirmationQueue = confirmingTool !== null;
 
   const scrollableListRef = useRef<VirtualizedListRef<unknown>>(null);
 
@@ -89,7 +86,6 @@ export const MainContent = () => {
             terminalWidth={mainAreaWidth}
             item={{ ...item, id: 0 }}
             isPending={true}
-            isFocused={!uiState.isEditorDialogOpen}
             activeShellPtyId={uiState.activePtyId}
             embeddedShellFocused={uiState.embeddedShellFocused}
           />
@@ -105,7 +101,6 @@ export const MainContent = () => {
       isAlternateBuffer,
       availableTerminalHeight,
       mainAreaWidth,
-      uiState.isEditorDialogOpen,
       uiState.activePtyId,
       uiState.embeddedShellFocused,
       showConfirmationQueue,
diff --git a/packages/cli/src/ui/components/messages/ToolConfirmationMessageOverflow.test.tsx b/packages/cli/src/ui/components/messages/ToolConfirmationMessageOverflow.test.tsx
deleted file mode 100644
index b59b6c5adf..0000000000
--- a/packages/cli/src/ui/components/messages/ToolConfirmationMessageOverflow.test.tsx
+++ /dev/null
@@ -1,128 +0,0 @@
-/**
- * @license
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import { ToolGroupMessage } from './ToolGroupMessage.js';
-import type {
-  ToolCallConfirmationDetails,
-  Config,
-} from '@google/gemini-cli-core';
-import { renderWithProviders } from '../../../test-utils/render.js';
-import { useToolActions } from '../../contexts/ToolActionsContext.js';
-import {
-  StreamingState,
-  ToolCallStatus,
-  type IndividualToolCallDisplay,
-} from '../../types.js';
-import { OverflowProvider } from '../../contexts/OverflowContext.js';
-import { waitFor } from '../../../test-utils/async.js';
-
-vi.mock('../../contexts/ToolActionsContext.js', async (importOriginal) => {
-  const actual =
-    await importOriginal<
-      typeof import('../../contexts/ToolActionsContext.js')
-    >();
-  return {
-    ...actual,
-    useToolActions: vi.fn(),
-  };
-});
-
-describe('ToolConfirmationMessage Overflow', () => {
-  const mockConfirm = vi.fn();
-  vi.mocked(useToolActions).mockReturnValue({
-    confirm: mockConfirm,
-    cancel: vi.fn(),
-    isDiffingEnabled: false,
-  });
-
-  const mockConfig = {
-    isTrustedFolder: () => true,
-    getIdeMode: () => false,
-    getMessageBus: () => ({
-      subscribe: vi.fn(),
-      unsubscribe: vi.fn(),
-      publish: vi.fn(),
-    }),
-    isEventDrivenSchedulerEnabled: () => false,
-    getTheme: () => ({
-      status: { warning: 'yellow' },
-      text: { primary: 'white', secondary: 'gray', link: 'blue' },
-      border: { default: 'gray' },
-      ui: { symbol: 'cyan' },
-    }),
-  } as unknown as Config;
-
-  it('should display "press ctrl-o" hint when content overflows in ToolGroupMessage', async () => {
-    // Large diff that will definitely overflow
-    const diffLines = ['--- a/test.txt', '+++ b/test.txt', '@@ -1,20 +1,20 @@'];
-    for (let i = 0; i < 50; i++) {
-      diffLines.push(`+ line ${i + 1}`);
-    }
-    const fileDiff = diffLines.join('\n');
-
-    const confirmationDetails: ToolCallConfirmationDetails = {
-      type: 'edit',
-      title: 'Confirm Edit',
-      fileName: 'test.txt',
-      filePath: '/test.txt',
-      fileDiff,
-      originalContent: '',
-      newContent: 'lots of lines',
-      onConfirm: vi.fn(),
-    };
-
-    const toolCalls: IndividualToolCallDisplay[] = [
-      {
-        callId: 'test-call-id',
-        name: 'test-tool',
-        description: 'a test tool',
-        status: ToolCallStatus.Confirming,
-        confirmationDetails,
-        resultDisplay: undefined,
-      },
-    ];
-
-    const { lastFrame } = renderWithProviders(
-      <OverflowProvider>
-        <ToolGroupMessage
-          groupId={1}
-          toolCalls={toolCalls}
-          availableTerminalHeight={15} // Small height to force overflow
-          terminalWidth={80}
-        />
-      </OverflowProvider>,
-      {
-        config: mockConfig,
-        uiState: {
-          streamingState: StreamingState.WaitingForConfirmation,
-          constrainHeight: true,
-        },
-      },
-    );
-
-    // ResizeObserver might take a tick
-    await waitFor(() =>
-      expect(lastFrame()).toContain('Press ctrl-o to show more lines'),
-    );
-
-    const frame = lastFrame();
-    expect(frame).toBeDefined();
-    if (frame) {
-      expect(frame).toContain('Press ctrl-o to show more lines');
-      // Ensure it's AFTER the bottom border
-      const linesOfOutput = frame.split('\n');
-      const bottomBorderIndex = linesOfOutput.findLastIndex((l) =>
-        l.includes('╰─'),
-      );
-      const hintIndex = linesOfOutput.findIndex((l) =>
-        l.includes('Press ctrl-o to show more lines'),
-      );
-      expect(hintIndex).toBeGreaterThan(bottomBorderIndex);
-      expect(frame).toMatchSnapshot();
-    }
-  });
-});
diff --git a/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx b/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx
index 5368684ea2..d2d3cd277a 100644
--- a/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx
+++ b/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx
@@ -5,7 +5,6 @@
  */
 
 import { renderWithProviders } from '../../../test-utils/render.js';
-import { createMockSettings } from '../../../test-utils/settings.js';
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import { ToolGroupMessage } from './ToolGroupMessage.js';
 import type { IndividualToolCallDisplay } from '../../types.js';
@@ -35,7 +34,6 @@ describe('<ToolGroupMessage />', () => {
   const baseProps = {
     groupId: 1,
     terminalWidth: 80,
-    isFocused: true,
   };
 
   const baseMockConfig = makeFakeConfig({
@@ -45,7 +43,6 @@ describe('<ToolGroupMessage />', () => {
     folderTrust: false,
     ideMode: false,
     enableInteractiveShell: true,
-    enableEventDrivenScheduler: true,
   });
 
   describe('Golden Snapshots', () => {
@@ -64,7 +61,31 @@ describe('<ToolGroupMessage />', () => {
       unmount();
     });
 
-    it('renders multiple tool calls with different statuses', () => {
+    it('hides confirming tools (standard behavior)', () => {
+      const toolCalls = [
+        createToolCall({
+          callId: 'confirm-tool',
+          status: ToolCallStatus.Confirming,
+          confirmationDetails: {
+            type: 'info',
+            title: 'Confirm tool',
+            prompt: 'Do you want to proceed?',
+            onConfirm: vi.fn(),
+          },
+        }),
+      ];
+
+      const { lastFrame, unmount } = renderWithProviders(
+        <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
+        { config: baseMockConfig },
+      );
+
+      // Should render nothing because all tools in the group are confirming
+      expect(lastFrame()).toBe('');
+      unmount();
+    });
+
+    it('renders multiple tool calls with different statuses (only visible ones)', () => {
       const toolCalls = [
         createToolCall({
           callId: 'tool-1',
@@ -85,68 +106,7 @@ describe('<ToolGroupMessage />', () => {
           status: ToolCallStatus.Error,
         }),
       ];
-      const mockConfig = makeFakeConfig({
-        model: 'gemini-pro',
-        targetDir: os.tmpdir(),
-        enableEventDrivenScheduler: false,
-      });
 
-      const { lastFrame, unmount } = renderWithProviders(
-        <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
-        {
-          config: mockConfig,
-          uiState: {
-            pendingHistoryItems: [{ type: 'tool_group', tools: toolCalls }],
-          },
-        },
-      );
-      expect(lastFrame()).toMatchSnapshot();
-      unmount();
-    });
-
-    it('renders tool call awaiting confirmation', () => {
-      const toolCalls = [
-        createToolCall({
-          callId: 'tool-confirm',
-          name: 'confirmation-tool',
-          description: 'This tool needs confirmation',
-          status: ToolCallStatus.Confirming,
-          confirmationDetails: {
-            type: 'info',
-            title: 'Confirm Tool Execution',
-            prompt: 'Are you sure you want to proceed?',
-            onConfirm: vi.fn(),
-          },
-        }),
-      ];
-      const mockConfig = makeFakeConfig({
-        model: 'gemini-pro',
-        targetDir: os.tmpdir(),
-        enableEventDrivenScheduler: false,
-      });
-
-      const { lastFrame, unmount } = renderWithProviders(
-        <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
-        {
-          config: mockConfig,
-          uiState: {
-            pendingHistoryItems: [{ type: 'tool_group', tools: toolCalls }],
-          },
-        },
-      );
-      expect(lastFrame()).toMatchSnapshot();
-      unmount();
-    });
-
-    it('renders shell command with yellow border', () => {
-      const toolCalls = [
-        createToolCall({
-          callId: 'shell-1',
-          name: 'run_shell_command',
-          description: 'Execute shell command',
-          status: ToolCallStatus.Success,
-        }),
-      ];
       const { lastFrame, unmount } = renderWithProviders(
         <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
         {
@@ -156,7 +116,12 @@ describe('<ToolGroupMessage />', () => {
           },
         },
       );
-      expect(lastFrame()).toMatchSnapshot();
+      // pending-tool should be hidden
+      const output = lastFrame();
+      expect(output).toContain('successful-tool');
+      expect(output).not.toContain('pending-tool');
+      expect(output).toContain('error-tool');
+      expect(output).toMatchSnapshot();
       unmount();
     });
 
@@ -181,22 +146,22 @@ describe('<ToolGroupMessage />', () => {
           status: ToolCallStatus.Pending,
         }),
       ];
-      const mockConfig = makeFakeConfig({
-        model: 'gemini-pro',
-        targetDir: os.tmpdir(),
-        enableEventDrivenScheduler: false,
-      });
 
       const { lastFrame, unmount } = renderWithProviders(
         <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
         {
-          config: mockConfig,
+          config: baseMockConfig,
           uiState: {
             pendingHistoryItems: [{ type: 'tool_group', tools: toolCalls }],
           },
         },
       );
-      expect(lastFrame()).toMatchSnapshot();
+      // write_file (Pending) should be hidden
+      const output = lastFrame();
+      expect(output).toContain('read_file');
+      expect(output).toContain('run_shell_command');
+      expect(output).not.toContain('write_file');
+      expect(output).toMatchSnapshot();
       unmount();
     });
 
@@ -233,25 +198,6 @@ describe('<ToolGroupMessage />', () => {
       unmount();
     });
 
-    it('renders when not focused', () => {
-      const toolCalls = [createToolCall()];
-      const { lastFrame, unmount } = renderWithProviders(
-        <ToolGroupMessage
-          {...baseProps}
-          toolCalls={toolCalls}
-          isFocused={false}
-        />,
-        {
-          config: baseMockConfig,
-          uiState: {
-            pendingHistoryItems: [{ type: 'tool_group', tools: toolCalls }],
-          },
-        },
-      );
-      expect(lastFrame()).toMatchSnapshot();
-      unmount();
-    });
-
     it('renders with narrow terminal width', () => {
       const toolCalls = [
         createToolCall({
@@ -384,28 +330,6 @@ describe('<ToolGroupMessage />', () => {
   });
 
   describe('Border Color Logic', () => {
-    it('uses yellow border when tools are pending', () => {
-      const toolCalls = [createToolCall({ status: ToolCallStatus.Pending })];
-      const mockConfig = makeFakeConfig({
-        model: 'gemini-pro',
-        targetDir: os.tmpdir(),
-        enableEventDrivenScheduler: false,
-      });
-
-      const { lastFrame, unmount } = renderWithProviders(
-        <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
-        {
-          config: mockConfig,
-          uiState: {
-            pendingHistoryItems: [{ type: 'tool_group', tools: toolCalls }],
-          },
-        },
-      );
-      // The snapshot will capture the visual appearance including border color
-      expect(lastFrame()).toMatchSnapshot();
-      unmount();
-    });
-
     it('uses yellow border for shell commands even when successful', () => {
       const toolCalls = [
         createToolCall({
@@ -483,210 +407,6 @@ describe('<ToolGroupMessage />', () => {
     });
   });
 
-  describe('Confirmation Handling', () => {
-    it('shows confirmation dialog for first confirming tool only', () => {
-      const toolCalls = [
-        createToolCall({
-          callId: 'tool-1',
-          name: 'first-confirm',
-          status: ToolCallStatus.Confirming,
-          confirmationDetails: {
-            type: 'info',
-            title: 'Confirm First Tool',
-            prompt: 'Confirm first tool',
-            onConfirm: vi.fn(),
-          },
-        }),
-        createToolCall({
-          callId: 'tool-2',
-          name: 'second-confirm',
-          status: ToolCallStatus.Confirming,
-          confirmationDetails: {
-            type: 'info',
-            title: 'Confirm Second Tool',
-            prompt: 'Confirm second tool',
-            onConfirm: vi.fn(),
-          },
-        }),
-      ];
-      const mockConfig = makeFakeConfig({
-        model: 'gemini-pro',
-        targetDir: os.tmpdir(),
-        enableEventDrivenScheduler: false,
-      });
-
-      const { lastFrame, unmount } = renderWithProviders(
-        <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
-        {
-          config: mockConfig,
-          uiState: {
-            pendingHistoryItems: [{ type: 'tool_group', tools: toolCalls }],
-          },
-        },
-      );
-      // Should only show confirmation for the first tool
-      expect(lastFrame()).toMatchSnapshot();
-      unmount();
-    });
-
-    it('renders confirmation with permanent approval enabled', () => {
-      const toolCalls = [
-        createToolCall({
-          callId: 'tool-1',
-          name: 'confirm-tool',
-          status: ToolCallStatus.Confirming,
-          confirmationDetails: {
-            type: 'info',
-            title: 'Confirm Tool',
-            prompt: 'Do you want to proceed?',
-            onConfirm: vi.fn(),
-          },
-        }),
-      ];
-      const settings = createMockSettings({
-        security: { enablePermanentToolApproval: true },
-      });
-      const mockConfig = makeFakeConfig({
-        model: 'gemini-pro',
-        targetDir: os.tmpdir(),
-        enableEventDrivenScheduler: false,
-      });
-
-      const { lastFrame, unmount } = renderWithProviders(
-        <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
-        {
-          settings,
-          config: mockConfig,
-          uiState: {
-            pendingHistoryItems: [{ type: 'tool_group', tools: toolCalls }],
-          },
-        },
-      );
-      expect(lastFrame()).toContain('Allow for all future sessions');
-      expect(lastFrame()).toMatchSnapshot();
-      unmount();
-    });
-
-    it('renders confirmation with permanent approval disabled', () => {
-      const toolCalls = [
-        createToolCall({
-          callId: 'confirm-tool',
-          name: 'confirm-tool',
-          status: ToolCallStatus.Confirming,
-          confirmationDetails: {
-            type: 'info',
-            title: 'Confirm tool',
-            prompt: 'Do you want to proceed?',
-            onConfirm: vi.fn(),
-          },
-        }),
-      ];
-
-      const mockConfig = makeFakeConfig({
-        model: 'gemini-pro',
-        targetDir: os.tmpdir(),
-        enableEventDrivenScheduler: false,
-      });
-
-      const { lastFrame, unmount } = renderWithProviders(
-        <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
-        { config: mockConfig },
-      );
-      expect(lastFrame()).not.toContain('Allow for all future sessions');
-      expect(lastFrame()).toMatchSnapshot();
-      unmount();
-    });
-  });
-
-  describe('Event-Driven Scheduler', () => {
-    it('hides confirming tools when event-driven scheduler is enabled', () => {
-      const toolCalls = [
-        createToolCall({
-          callId: 'confirm-tool',
-          status: ToolCallStatus.Confirming,
-          confirmationDetails: {
-            type: 'info',
-            title: 'Confirm tool',
-            prompt: 'Do you want to proceed?',
-            onConfirm: vi.fn(),
-          },
-        }),
-      ];
-
-      const mockConfig = baseMockConfig;
-
-      const { lastFrame, unmount } = renderWithProviders(
-        <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
-        { config: mockConfig },
-      );
-
-      // Should render nothing because all tools in the group are confirming
-      expect(lastFrame()).toBe('');
-      expect(lastFrame()).toMatchSnapshot();
-      unmount();
-    });
-
-    it('shows only successful tools when mixed with confirming tools', () => {
-      const toolCalls = [
-        createToolCall({
-          callId: 'success-tool',
-          name: 'success-tool',
-          status: ToolCallStatus.Success,
-        }),
-        createToolCall({
-          callId: 'confirm-tool',
-          name: 'confirm-tool',
-          status: ToolCallStatus.Confirming,
-          confirmationDetails: {
-            type: 'info',
-            title: 'Confirm tool',
-            prompt: 'Do you want to proceed?',
-            onConfirm: vi.fn(),
-          },
-        }),
-      ];
-
-      const mockConfig = baseMockConfig;
-
-      const { lastFrame, unmount } = renderWithProviders(
-        <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
-        { config: mockConfig },
-      );
-
-      const output = lastFrame();
-      expect(output).toContain('success-tool');
-      expect(output).not.toContain('confirm-tool');
-      expect(output).not.toContain('Do you want to proceed?');
-      expect(output).toMatchSnapshot();
-      unmount();
-    });
-
-    it('renders nothing when only tool is in-progress AskUser with borderBottom=false', () => {
-      // AskUser tools in progress are rendered by AskUserDialog, not ToolGroupMessage.
-      // When AskUser is the only tool and borderBottom=false (no border to close),
-      // the component should render nothing.
-      const toolCalls = [
-        createToolCall({
-          callId: 'ask-user-tool',
-          name: 'Ask User',
-          status: ToolCallStatus.Executing,
-        }),
-      ];
-
-      const { lastFrame, unmount } = renderWithProviders(
-        <ToolGroupMessage
-          {...baseProps}
-          toolCalls={toolCalls}
-          borderBottom={false}
-        />,
-        { config: baseMockConfig },
-      );
-      // AskUser tools in progress are rendered by AskUserDialog, so we expect nothing.
-      expect(lastFrame()).toMatchSnapshot();
-      unmount();
-    });
-  });
-
   describe('Ask User Filtering', () => {
     it.each([
       ToolCallStatus.Pending,
@@ -753,5 +473,30 @@ describe('<ToolGroupMessage />', () => {
       expect(lastFrame()).toMatchSnapshot();
       unmount();
     });
+
+    it('renders nothing when only tool is in-progress AskUser with borderBottom=false', () => {
+      // AskUser tools in progress are rendered by AskUserDialog, not ToolGroupMessage.
+      // When AskUser is the only tool and borderBottom=false (no border to close),
+      // the component should render nothing.
+      const toolCalls = [
+        createToolCall({
+          callId: 'ask-user-tool',
+          name: ASK_USER_DISPLAY_NAME,
+          status: ToolCallStatus.Executing,
+        }),
+      ];
+
+      const { lastFrame, unmount } = renderWithProviders(
+        <ToolGroupMessage
+          {...baseProps}
+          toolCalls={toolCalls}
+          borderBottom={false}
+        />,
+        { config: baseMockConfig },
+      );
+      // AskUser tools in progress are rendered by AskUserDialog, so we expect nothing.
+      expect(lastFrame()).toBe('');
+      unmount();
+    });
   });
 });
diff --git a/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx b/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx
index f9225b60e7..07ae280558 100644
--- a/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx
+++ b/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx
@@ -11,7 +11,6 @@ import type { IndividualToolCallDisplay } from '../../types.js';
 import { ToolCallStatus } from '../../types.js';
 import { ToolMessage } from './ToolMessage.js';
 import { ShellToolMessage } from './ShellToolMessage.js';
-import { ToolConfirmationMessage } from './ToolConfirmationMessage.js';
 import { theme } from '../../semantic-colors.js';
 import { useConfig } from '../../contexts/ConfigContext.js';
 import { isShellTool, isThisShellFocused } from './ToolShared.js';
@@ -24,7 +23,6 @@ interface ToolGroupMessageProps {
   toolCalls: IndividualToolCallDisplay[];
   availableTerminalHeight?: number;
   terminalWidth: number;
-  isFocused?: boolean;
   activeShellPtyId?: number | null;
   embeddedShellFocused?: boolean;
   onShellInputSubmit?: (input: string) => void;
@@ -43,13 +41,11 @@ const isAskUserInProgress = (t: IndividualToolCallDisplay): boolean =>
 
 // Main component renders the border and maps the tools using ToolMessage
 const TOOL_MESSAGE_HORIZONTAL_MARGIN = 4;
-const TOOL_CONFIRMATION_INTERNAL_PADDING = 4;
 
 export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
   toolCalls: allToolCalls,
   availableTerminalHeight,
   terminalWidth,
-  isFocused = true,
   activeShellPtyId,
   embeddedShellFocused,
   borderTop: borderTopOverride,
@@ -64,24 +60,20 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
   const config = useConfig();
   const { constrainHeight } = useUIState();
 
-  const isEventDriven = config.isEventDrivenSchedulerEnabled();
-
-  // If Event-Driven Scheduler is enabled, we HIDE tools that are still in
-  // pre-execution states (Confirming, Pending) from the History log.
-  // They live in the Global Queue or wait for their turn.
-  const visibleToolCalls = useMemo(() => {
-    if (!isEventDriven) {
-      return toolCalls;
-    }
-    // Only show tools that are actually running or finished.
-    // We explicitly exclude Pending and Confirming to ensure they only
-    // appear in the Global Queue until they are approved and start executing.
-    return toolCalls.filter(
-      (t) =>
-        t.status !== ToolCallStatus.Pending &&
-        t.status !== ToolCallStatus.Confirming,
-    );
-  }, [toolCalls, isEventDriven]);
+  // We HIDE tools that are still in pre-execution states (Confirming, Pending)
+  // from the History log. They live in the Global Queue or wait for their turn.
+  // Only show tools that are actually running or finished.
+  // We explicitly exclude Pending and Confirming to ensure they only
+  // appear in the Global Queue until they are approved and start executing.
+  const visibleToolCalls = useMemo(
+    () =>
+      toolCalls.filter(
+        (t) =>
+          t.status !== ToolCallStatus.Pending &&
+          t.status !== ToolCallStatus.Confirming,
+      ),
+    [toolCalls],
+  );
 
   const isEmbeddedShellFocused = visibleToolCalls.some((t) =>
     isThisShellFocused(
@@ -110,17 +102,8 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
 
   const staticHeight = /* border */ 2 + /* marginBottom */ 1;
 
-  // Inline confirmations are ONLY used when the Global Queue is disabled.
-  const toolAwaitingApproval = useMemo(
-    () =>
-      isEventDriven
-        ? undefined
-        : toolCalls.find((tc) => tc.status === ToolCallStatus.Confirming),
-    [toolCalls, isEventDriven],
-  );
-
-  // If all tools are filtered out (e.g., in-progress AskUser tools, confirming tools
-  // in event-driven mode), only render if we need to close a border from previous
+  // If all tools are filtered out (e.g., in-progress AskUser tools, confirming tools),
+  // only render if we need to close a border from previous
   // tool groups. borderBottomOverride=true means we must render the closing border;
   // undefined or false means there's nothing to display.
   if (visibleToolCalls.length === 0 && borderBottomOverride !== true) {
@@ -163,7 +146,6 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
       paddingRight={TOOL_MESSAGE_HORIZONTAL_MARGIN}
     >
       {visibleToolCalls.map((tool, index) => {
-        const isConfirming = toolAwaitingApproval?.callId === tool.callId;
         const isFirst = index === 0;
         const isShellToolCall = isShellTool(tool.name);
 
@@ -171,11 +153,7 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
           ...tool,
           availableTerminalHeight: availableTerminalHeightPerToolMessage,
           terminalWidth: contentWidth,
-          emphasis: isConfirming
-            ? ('high' as const)
-            : toolAwaitingApproval
-              ? ('low' as const)
-              : ('medium' as const),
+          emphasis: 'medium' as const,
           isFirst:
             borderTopOverride !== undefined
               ? borderTopOverride && isFirst
@@ -213,22 +191,6 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
               paddingLeft={1}
               paddingRight={1}
             >
-              {tool.status === ToolCallStatus.Confirming &&
-                isConfirming &&
-                tool.confirmationDetails && (
-                  <ToolConfirmationMessage
-                    callId={tool.callId}
-                    confirmationDetails={tool.confirmationDetails}
-                    config={config}
-                    isFocused={isFocused}
-                    availableTerminalHeight={
-                      availableTerminalHeightPerToolMessage
-                    }
-                    terminalWidth={
-                      contentWidth - TOOL_CONFIRMATION_INTERNAL_PADDING
-                    }
-                  />
-                )}
               {tool.outputFile && (
                 <Box>
                   <Text color={theme.text.primary}>
diff --git a/packages/cli/src/ui/components/messages/__snapshots__/ToolGroupMessage.test.tsx.snap b/packages/cli/src/ui/components/messages/__snapshots__/ToolGroupMessage.test.tsx.snap
index 369fa59174..3586b32c21 100644
--- a/packages/cli/src/ui/components/messages/__snapshots__/ToolGroupMessage.test.tsx.snap
+++ b/packages/cli/src/ui/components/messages/__snapshots__/ToolGroupMessage.test.tsx.snap
@@ -50,76 +50,6 @@ exports[`<ToolGroupMessage /> > Border Color Logic > uses yellow border for shel
 ╰──────────────────────────────────────────────────────────────────────────╯"
 `;
 
-exports[`<ToolGroupMessage /> > Border Color Logic > uses yellow border when tools are pending 1`] = `
-"╭──────────────────────────────────────────────────────────────────────────╮
-│ o  test-tool A tool for testing                                          │
-│                                                                          │
-│ Test result                                                              │
-╰──────────────────────────────────────────────────────────────────────────╯"
-`;
-
-exports[`<ToolGroupMessage /> > Confirmation Handling > renders confirmation with permanent approval disabled 1`] = `
-"╭──────────────────────────────────────────────────────────────────────────╮
-│ ?  confirm-tool A tool for testing                                     ← │
-│                                                                          │
-│ Test result                                                              │
-│ Do you want to proceed?                                                  │
-│ Do you want to proceed?                                                  │
-│                                                                          │
-│ ● 1. Allow once                                                          │
-│   2. Allow for this session                                              │
-│   3. No, suggest changes (esc)                                           │
-│                                                                          │
-╰──────────────────────────────────────────────────────────────────────────╯"
-`;
-
-exports[`<ToolGroupMessage /> > Confirmation Handling > renders confirmation with permanent approval enabled 1`] = `
-"╭──────────────────────────────────────────────────────────────────────────╮
-│ ?  confirm-tool A tool for testing                                     ← │
-│                                                                          │
-│ Test result                                                              │
-│ Do you want to proceed?                                                  │
-│ Do you want to proceed?                                                  │
-│                                                                          │
-│ ● 1. Allow once                                                          │
-│   2. Allow for this session                                              │
-│   3. Allow for all future sessions                                       │
-│   4. No, suggest changes (esc)                                           │
-│                                                                          │
-╰──────────────────────────────────────────────────────────────────────────╯"
-`;
-
-exports[`<ToolGroupMessage /> > Confirmation Handling > shows confirmation dialog for first confirming tool only 1`] = `
-"╭──────────────────────────────────────────────────────────────────────────╮
-│ ?  first-confirm A tool for testing                                    ← │
-│                                                                          │
-│ Test result                                                              │
-│ Confirm first tool                                                       │
-│ Do you want to proceed?                                                  │
-│                                                                          │
-│ ● 1. Allow once                                                          │
-│   2. Allow for this session                                              │
-│   3. No, suggest changes (esc)                                           │
-│                                                                          │
-│                                                                          │
-│ ?  second-confirm A tool for testing                                     │
-│                                                                          │
-│ Test result                                                              │
-╰──────────────────────────────────────────────────────────────────────────╯"
-`;
-
-exports[`<ToolGroupMessage /> > Event-Driven Scheduler > hides confirming tools when event-driven scheduler is enabled 1`] = `""`;
-
-exports[`<ToolGroupMessage /> > Event-Driven Scheduler > renders nothing when only tool is in-progress AskUser with borderBottom=false 1`] = `""`;
-
-exports[`<ToolGroupMessage /> > Event-Driven Scheduler > shows only successful tools when mixed with confirming tools 1`] = `
-"╭──────────────────────────────────────────────────────────────────────────╮
-│ ✓  success-tool A tool for testing                                       │
-│                                                                          │
-│ Test result                                                              │
-╰──────────────────────────────────────────────────────────────────────────╯"
-`;
-
 exports[`<ToolGroupMessage /> > Golden Snapshots > renders empty tool calls array 1`] = `""`;
 
 exports[`<ToolGroupMessage /> > Golden Snapshots > renders header when scrolled 1`] = `
@@ -144,37 +74,21 @@ exports[`<ToolGroupMessage /> > Golden Snapshots > renders mixed tool calls incl
 │ ⊷  run_shell_command Run command                                         │
 │                                                                          │
 │ Test result                                                              │
-│                                                                          │
-│ o  write_file Write to file                                              │
-│                                                                          │
-│ Test result                                                              │
 ╰──────────────────────────────────────────────────────────────────────────╯"
 `;
 
-exports[`<ToolGroupMessage /> > Golden Snapshots > renders multiple tool calls with different statuses 1`] = `
+exports[`<ToolGroupMessage /> > Golden Snapshots > renders multiple tool calls with different statuses (only visible ones) 1`] = `
 "╭──────────────────────────────────────────────────────────────────────────╮
 │ ✓  successful-tool This tool succeeded                                   │
 │                                                                          │
 │ Test result                                                              │
 │                                                                          │
-│ o  pending-tool This tool is pending                                     │
-│                                                                          │
-│ Test result                                                              │
-│                                                                          │
 │ x  error-tool This tool failed                                           │
 │                                                                          │
 │ Test result                                                              │
 ╰──────────────────────────────────────────────────────────────────────────╯"
 `;
 
-exports[`<ToolGroupMessage /> > Golden Snapshots > renders shell command with yellow border 1`] = `
-"╭──────────────────────────────────────────────────────────────────────────╮
-│ ✓  run_shell_command Execute shell command                               │
-│                                                                          │
-│ Test result                                                              │
-╰──────────────────────────────────────────────────────────────────────────╯"
-`;
-
 exports[`<ToolGroupMessage /> > Golden Snapshots > renders single successful tool call 1`] = `
 "╭──────────────────────────────────────────────────────────────────────────╮
 │ ✓  test-tool A tool for testing                                          │
@@ -183,21 +97,6 @@ exports[`<ToolGroupMessage /> > Golden Snapshots > renders single successful too
 ╰──────────────────────────────────────────────────────────────────────────╯"
 `;
 
-exports[`<ToolGroupMessage /> > Golden Snapshots > renders tool call awaiting confirmation 1`] = `
-"╭──────────────────────────────────────────────────────────────────────────╮
-│ ?  confirmation-tool This tool needs confirmation                      ← │
-│                                                                          │
-│ Test result                                                              │
-│ Are you sure you want to proceed?                                        │
-│ Do you want to proceed?                                                  │
-│                                                                          │
-│ ● 1. Allow once                                                          │
-│   2. Allow for this session                                              │
-│   3. No, suggest changes (esc)                                           │
-│                                                                          │
-╰──────────────────────────────────────────────────────────────────────────╯"
-`;
-
 exports[`<ToolGroupMessage /> > Golden Snapshots > renders tool call with outputFile 1`] = `
 "╭──────────────────────────────────────────────────────────────────────────╮
 │ ✓  tool-with-file Tool that saved output to file                         │
@@ -216,14 +115,6 @@ exports[`<ToolGroupMessage /> > Golden Snapshots > renders two tool groups where
 ╰──────────────────────────────────────────────────────────────────────────╯                                           █"
 `;
 
-exports[`<ToolGroupMessage /> > Golden Snapshots > renders when not focused 1`] = `
-"╭──────────────────────────────────────────────────────────────────────────╮
-│ ✓  test-tool A tool for testing                                          │
-│                                                                          │
-│ Test result                                                              │
-╰──────────────────────────────────────────────────────────────────────────╯"
-`;
-
 exports[`<ToolGroupMessage /> > Golden Snapshots > renders with limited terminal height 1`] = `
 "╭──────────────────────────────────────────────────────────────────────────╮
 │ ✓  tool-with-result Tool with output                                     │

From 0e85e021dcfdbe7abb2594f38f516ba3bb7ef33e Mon Sep 17 00:00:00 2001
From: Abhijit Balaji <abhijitbalaji@google.com>
Date: Wed, 11 Feb 2026 16:49:48 -0800
Subject: [PATCH 11/44] feat(cli): deprecate --allowed-tools and excludeTools
 in favor of policy engine (#18508)

---
 docs/cli/cli-reference.md                     |  46 +++---
 docs/cli/enterprise.md                        |  11 +-
 docs/get-started/configuration-v1.md          |   8 +-
 docs/tools/shell.md                           |   9 +-
 packages/cli/src/config/config.ts             |   3 +-
 packages/cli/src/gemini.tsx                   |  20 +++
 packages/core/src/config/config.ts            |  13 +-
 .../core/src/policy/policy-engine.test.ts     | 150 ++++++++++++++++++
 packages/core/src/policy/policy-engine.ts     | 106 ++++++++++++-
 9 files changed, 327 insertions(+), 39 deletions(-)

diff --git a/docs/cli/cli-reference.md b/docs/cli/cli-reference.md
index d1094a15e2..8199445625 100644
--- a/docs/cli/cli-reference.md
+++ b/docs/cli/cli-reference.md
@@ -27,29 +27,29 @@ and parameters.
 
 ## CLI Options
 
-| Option                           | Alias | Type    | Default   | Description                                                                                                |
-| -------------------------------- | ----- | ------- | --------- | ---------------------------------------------------------------------------------------------------------- |
-| `--debug`                        | `-d`  | boolean | `false`   | Run in debug mode with verbose logging                                                                     |
-| `--version`                      | `-v`  | -       | -         | Show CLI version number and exit                                                                           |
-| `--help`                         | `-h`  | -       | -         | Show help information                                                                                      |
-| `--model`                        | `-m`  | string  | `auto`    | Model to use. See [Model Selection](#model-selection) for available values.                                |
-| `--prompt`                       | `-p`  | string  | -         | Prompt text. Appended to stdin input if provided. **Deprecated:** Use positional arguments instead.        |
-| `--prompt-interactive`           | `-i`  | string  | -         | Execute prompt and continue in interactive mode                                                            |
-| `--sandbox`                      | `-s`  | boolean | `false`   | Run in a sandboxed environment for safer execution                                                         |
-| `--approval-mode`                | -     | string  | `default` | Approval mode for tool execution. Choices: `default`, `auto_edit`, `yolo`                                  |
-| `--yolo`                         | `-y`  | boolean | `false`   | **Deprecated.** Auto-approve all actions. Use `--approval-mode=yolo` instead.                              |
-| `--experimental-acp`             | -     | boolean | -         | Start in ACP (Agent Code Pilot) mode. **Experimental feature.**                                            |
-| `--experimental-zed-integration` | -     | boolean | -         | Run in Zed editor integration mode. **Experimental feature.**                                              |
-| `--allowed-mcp-server-names`     | -     | array   | -         | Allowed MCP server names (comma-separated or multiple flags)                                               |
-| `--allowed-tools`                | -     | array   | -         | Tools that are allowed to run without confirmation (comma-separated or multiple flags)                     |
-| `--extensions`                   | `-e`  | array   | -         | List of extensions to use. If not provided, all extensions are enabled (comma-separated or multiple flags) |
-| `--list-extensions`              | `-l`  | boolean | -         | List all available extensions and exit                                                                     |
-| `--resume`                       | `-r`  | string  | -         | Resume a previous session. Use `"latest"` for most recent or index number (e.g. `--resume 5`)              |
-| `--list-sessions`                | -     | boolean | -         | List available sessions for the current project and exit                                                   |
-| `--delete-session`               | -     | string  | -         | Delete a session by index number (use `--list-sessions` to see available sessions)                         |
-| `--include-directories`          | -     | array   | -         | Additional directories to include in the workspace (comma-separated or multiple flags)                     |
-| `--screen-reader`                | -     | boolean | -         | Enable screen reader mode for accessibility                                                                |
-| `--output-format`                | `-o`  | string  | `text`    | The format of the CLI output. Choices: `text`, `json`, `stream-json`                                       |
+| Option                           | Alias | Type    | Default   | Description                                                                                                                                                       |
+| -------------------------------- | ----- | ------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--debug`                        | `-d`  | boolean | `false`   | Run in debug mode with verbose logging                                                                                                                            |
+| `--version`                      | `-v`  | -       | -         | Show CLI version number and exit                                                                                                                                  |
+| `--help`                         | `-h`  | -       | -         | Show help information                                                                                                                                             |
+| `--model`                        | `-m`  | string  | `auto`    | Model to use. See [Model Selection](#model-selection) for available values.                                                                                       |
+| `--prompt`                       | `-p`  | string  | -         | Prompt text. Appended to stdin input if provided. **Deprecated:** Use positional arguments instead.                                                               |
+| `--prompt-interactive`           | `-i`  | string  | -         | Execute prompt and continue in interactive mode                                                                                                                   |
+| `--sandbox`                      | `-s`  | boolean | `false`   | Run in a sandboxed environment for safer execution                                                                                                                |
+| `--approval-mode`                | -     | string  | `default` | Approval mode for tool execution. Choices: `default`, `auto_edit`, `yolo`                                                                                         |
+| `--yolo`                         | `-y`  | boolean | `false`   | **Deprecated.** Auto-approve all actions. Use `--approval-mode=yolo` instead.                                                                                     |
+| `--experimental-acp`             | -     | boolean | -         | Start in ACP (Agent Code Pilot) mode. **Experimental feature.**                                                                                                   |
+| `--experimental-zed-integration` | -     | boolean | -         | Run in Zed editor integration mode. **Experimental feature.**                                                                                                     |
+| `--allowed-mcp-server-names`     | -     | array   | -         | Allowed MCP server names (comma-separated or multiple flags)                                                                                                      |
+| `--allowed-tools`                | -     | array   | -         | **Deprecated.** Use the [Policy Engine](../core/policy-engine.md) instead. Tools that are allowed to run without confirmation (comma-separated or multiple flags) |
+| `--extensions`                   | `-e`  | array   | -         | List of extensions to use. If not provided, all extensions are enabled (comma-separated or multiple flags)                                                        |
+| `--list-extensions`              | `-l`  | boolean | -         | List all available extensions and exit                                                                                                                            |
+| `--resume`                       | `-r`  | string  | -         | Resume a previous session. Use `"latest"` for most recent or index number (e.g. `--resume 5`)                                                                     |
+| `--list-sessions`                | -     | boolean | -         | List available sessions for the current project and exit                                                                                                          |
+| `--delete-session`               | -     | string  | -         | Delete a session by index number (use `--list-sessions` to see available sessions)                                                                                |
+| `--include-directories`          | -     | array   | -         | Additional directories to include in the workspace (comma-separated or multiple flags)                                                                            |
+| `--screen-reader`                | -     | boolean | -         | Enable screen reader mode for accessibility                                                                                                                       |
+| `--output-format`                | `-o`  | string  | `text`    | The format of the CLI output. Choices: `text`, `json`, `stream-json`                                                                                              |
 
 ## Model selection
 
diff --git a/docs/cli/enterprise.md b/docs/cli/enterprise.md
index f22ec81c37..861fc68c71 100644
--- a/docs/cli/enterprise.md
+++ b/docs/cli/enterprise.md
@@ -223,9 +223,9 @@ gemini
 ## Restricting tool access
 
 You can significantly enhance security by controlling which tools the Gemini
-model can use. This is achieved through the `tools.core` and `tools.exclude`
-settings. For a list of available tools, see the
-[Tools documentation](../tools/index.md).
+model can use. This is achieved through the `tools.core` setting and the
+[Policy Engine](../core/policy-engine.md). For a list of available tools, see
+the [Tools documentation](../tools/index.md).
 
 ### Allowlisting with `coreTools`
 
@@ -243,7 +243,10 @@ on the approved list.
 }
 ```
 
-### Blocklisting with `excludeTools`
+### Blocklisting with `excludeTools` (Deprecated)
+
+> **Deprecated:** Use the [Policy Engine](../core/policy-engine.md) for more
+> robust control.
 
 Alternatively, you can add specific tools that are considered dangerous in your
 environment to a blocklist.
diff --git a/docs/get-started/configuration-v1.md b/docs/get-started/configuration-v1.md
index 050dce32b6..cd1325b977 100644
--- a/docs/get-started/configuration-v1.md
+++ b/docs/get-started/configuration-v1.md
@@ -166,19 +166,21 @@ a few things you can try in order of recommendation:
   - **Default:** All tools available for use by the Gemini model.
   - **Example:** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]`.
 
-- **`allowedTools`** (array of strings):
+- **`allowedTools`** (array of strings) [DEPRECATED]:
   - **Default:** `undefined`
   - **Description:** A list of tool names that will bypass the confirmation
     dialog. This is useful for tools that you trust and use frequently. The
-    match semantics are the same as `coreTools`.
+    match semantics are the same as `coreTools`. **Deprecated**: Use the
+    [Policy Engine](../core/policy-engine.md) instead.
   - **Example:** `"allowedTools": ["ShellTool(git status)"]`.
 
-- **`excludeTools`** (array of strings):
+- **`excludeTools`** (array of strings) [DEPRECATED]:
   - **Description:** Allows you to specify a list of core tool names that should
     be excluded from the model. A tool listed in both `excludeTools` and
     `coreTools` is excluded. You can also specify command-specific restrictions
     for tools that support it, like the `ShellTool`. For example,
     `"excludeTools": ["ShellTool(rm -rf)"]` will block the `rm -rf` command.
+    **Deprecated**: Use the [Policy Engine](../core/policy-engine.md) instead.
   - **Default**: No tools excluded.
   - **Example:** `"excludeTools": ["run_shell_command", "findFiles"]`.
   - **Security Note:** Command-specific restrictions in `excludeTools` for
diff --git a/docs/tools/shell.md b/docs/tools/shell.md
index 0bb4b68244..48854e82f1 100644
--- a/docs/tools/shell.md
+++ b/docs/tools/shell.md
@@ -167,10 +167,11 @@ configuration file.
   `"tools": {"core": ["run_shell_command(git)"]}` will only allow `git`
   commands. Including the generic `run_shell_command` acts as a wildcard,
   allowing any command not explicitly blocked.
-- `tools.exclude`: To block specific commands, add entries to the `exclude` list
-  under the `tools` category in the format `run_shell_command(<command>)`. For
-  example, `"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm`
-  commands.
+- `tools.exclude` [DEPRECATED]: To block specific commands, use the
+  [Policy Engine](../core/policy-engine.md). Historically, this setting allowed
+  adding entries to the `exclude` list under the `tools` category in the format
+  `run_shell_command(<command>)`. For example,
+  `"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm` commands.
 
 The validation logic is designed to be secure and flexible:
 
diff --git a/packages/cli/src/config/config.ts b/packages/cli/src/config/config.ts
index f164ce77d8..ea7d6f72a5 100755
--- a/packages/cli/src/config/config.ts
+++ b/packages/cli/src/config/config.ts
@@ -177,7 +177,8 @@ export async function parseArguments(
           type: 'array',
           string: true,
           nargs: 1,
-          description: 'Tools that are allowed to run without confirmation',
+          description:
+            '[DEPRECATED: Use Policy Engine instead See https://geminicli.com/docs/core/policy-engine] Tools that are allowed to run without confirmation',
           coerce: (tools: string[]) =>
             // Handle comma-separated values
             tools.flatMap((tool) => tool.split(',').map((t) => t.trim())),
diff --git a/packages/cli/src/gemini.tsx b/packages/cli/src/gemini.tsx
index a18f3ace37..e138cfe03a 100644
--- a/packages/cli/src/gemini.tsx
+++ b/packages/cli/src/gemini.tsx
@@ -361,6 +361,26 @@ export async function main() {
   const argv = await parseArguments(settings.merged);
   parseArgsHandle?.end();
 
+  if (
+    (argv.allowedTools && argv.allowedTools.length > 0) ||
+    (settings.merged.tools?.allowed && settings.merged.tools.allowed.length > 0)
+  ) {
+    coreEvents.emitFeedback(
+      'warning',
+      'Warning: --allowed-tools cli argument and tools.allowed in settings.json are deprecated and will be removed in 1.0: Migrate to Policy Engine: https://geminicli.com/docs/core/policy-engine/',
+    );
+  }
+
+  if (
+    settings.merged.tools?.exclude &&
+    settings.merged.tools.exclude.length > 0
+  ) {
+    coreEvents.emitFeedback(
+      'warning',
+      'Warning: tools.exclude in settings.json is deprecated and will be removed in 1.0. Migrate to Policy Engine: https://geminicli.com/docs/core/policy-engine/',
+    );
+  }
+
   if (argv.startupMessages) {
     argv.startupMessages.forEach((msg) => {
       coreEvents.emitFeedback('info', msg);
diff --git a/packages/core/src/config/config.ts b/packages/core/src/config/config.ts
index 6d811799bc..db4085c1fa 100644
--- a/packages/core/src/config/config.ts
+++ b/packages/core/src/config/config.ts
@@ -383,7 +383,9 @@ export interface ConfigParameters {
   question?: string;
 
   coreTools?: string[];
+  /** @deprecated Use Policy Engine instead */
   allowedTools?: string[];
+  /** @deprecated Use Policy Engine instead */
   excludeTools?: string[];
   toolDiscoveryCommand?: string;
   toolCallCommand?: string;
@@ -516,7 +518,9 @@ export class Config {
   private readonly question: string | undefined;
 
   private readonly coreTools: string[] | undefined;
+  /** @deprecated Use Policy Engine instead */
   private readonly allowedTools: string[] | undefined;
+  /** @deprecated Use Policy Engine instead */
   private readonly excludeTools: string[] | undefined;
   private readonly toolDiscoveryCommand: string | undefined;
   private readonly toolCallCommand: string | undefined;
@@ -1487,11 +1491,12 @@ export class Config {
 
   /**
    * All the excluded tools from static configuration, loaded extensions, or
-   * other sources.
+   * other sources (like the Policy Engine).
    *
    * May change over time.
    */
   getExcludeTools(): Set<string> | undefined {
+    // Right now this is present for backward compatibility with settings.json exclude
     const excludeToolsSet = new Set([...(this.excludeTools ?? [])]);
     for (const extension of this.getExtensionLoader().getExtensions()) {
       if (!extension.isActive) {
@@ -1501,6 +1506,12 @@ export class Config {
         excludeToolsSet.add(tool);
       }
     }
+
+    const policyExclusions = this.policyEngine.getExcludedTools();
+    for (const tool of policyExclusions) {
+      excludeToolsSet.add(tool);
+    }
+
     return excludeToolsSet;
   }
 
diff --git a/packages/core/src/policy/policy-engine.test.ts b/packages/core/src/policy/policy-engine.test.ts
index 59b0fd8106..26aecaa1eb 100644
--- a/packages/core/src/policy/policy-engine.test.ts
+++ b/packages/core/src/policy/policy-engine.test.ts
@@ -2031,6 +2031,156 @@ describe('PolicyEngine', () => {
     });
   });
 
+  describe('getExcludedTools', () => {
+    interface TestCase {
+      name: string;
+      rules: PolicyRule[];
+      approvalMode?: ApprovalMode;
+      nonInteractive?: boolean;
+      expected: string[];
+    }
+
+    const testCases: TestCase[] = [
+      {
+        name: 'should return empty set when no rules provided',
+        rules: [],
+        expected: [],
+      },
+      {
+        name: 'should include tools with DENY decision',
+        rules: [
+          { toolName: 'tool1', decision: PolicyDecision.DENY },
+          { toolName: 'tool2', decision: PolicyDecision.ALLOW },
+        ],
+        expected: ['tool1'],
+      },
+      {
+        name: 'should respect priority and ignore lower priority rules (DENY wins)',
+        rules: [
+          { toolName: 'tool1', decision: PolicyDecision.DENY, priority: 100 },
+          { toolName: 'tool1', decision: PolicyDecision.ALLOW, priority: 10 },
+        ],
+        expected: ['tool1'],
+      },
+      {
+        name: 'should respect priority and ignore lower priority rules (ALLOW wins)',
+        rules: [
+          { toolName: 'tool1', decision: PolicyDecision.ALLOW, priority: 100 },
+          { toolName: 'tool1', decision: PolicyDecision.DENY, priority: 10 },
+        ],
+        expected: [],
+      },
+      {
+        name: 'should NOT include ASK_USER tools even in non-interactive mode',
+        rules: [{ toolName: 'tool1', decision: PolicyDecision.ASK_USER }],
+        nonInteractive: true,
+        expected: [],
+      },
+      {
+        name: 'should ignore rules with argsPattern',
+        rules: [
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.DENY,
+            argsPattern: /something/,
+          },
+        ],
+        expected: [],
+      },
+      {
+        name: 'should respect approval mode (PLAN mode)',
+        rules: [
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.DENY,
+            modes: [ApprovalMode.PLAN],
+          },
+        ],
+        approvalMode: ApprovalMode.PLAN,
+        expected: ['tool1'],
+      },
+      {
+        name: 'should respect approval mode (DEFAULT mode)',
+        rules: [
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.DENY,
+            modes: [ApprovalMode.PLAN],
+          },
+        ],
+        approvalMode: ApprovalMode.DEFAULT,
+        expected: [],
+      },
+      {
+        name: 'should respect wildcard ALLOW rules (e.g. YOLO mode)',
+        rules: [
+          {
+            decision: PolicyDecision.ALLOW,
+            priority: 999,
+            modes: [ApprovalMode.YOLO],
+          },
+          {
+            toolName: 'dangerous-tool',
+            decision: PolicyDecision.DENY,
+            priority: 10,
+          },
+        ],
+        approvalMode: ApprovalMode.YOLO,
+        expected: [],
+      },
+      {
+        name: 'should respect server wildcard DENY',
+        rules: [{ toolName: 'server__*', decision: PolicyDecision.DENY }],
+        expected: ['server__*'],
+      },
+      {
+        name: 'should expand server wildcard for specific tools if already processed',
+        rules: [
+          {
+            toolName: 'server__*',
+            decision: PolicyDecision.DENY,
+            priority: 100,
+          },
+          {
+            toolName: 'server__tool1',
+            decision: PolicyDecision.DENY,
+            priority: 10,
+          },
+        ],
+        expected: ['server__*', 'server__tool1'],
+      },
+      {
+        name: 'should NOT exclude tool if covered by a higher priority wildcard ALLOW',
+        rules: [
+          {
+            toolName: 'server__*',
+            decision: PolicyDecision.ALLOW,
+            priority: 100,
+          },
+          {
+            toolName: 'server__tool1',
+            decision: PolicyDecision.DENY,
+            priority: 10,
+          },
+        ],
+        expected: [],
+      },
+    ];
+
+    it.each(testCases)(
+      '$name',
+      ({ rules, approvalMode, nonInteractive, expected }) => {
+        engine = new PolicyEngine({
+          rules,
+          approvalMode: approvalMode ?? ApprovalMode.DEFAULT,
+          nonInteractive: nonInteractive ?? false,
+        });
+        const excluded = engine.getExcludedTools();
+        expect(Array.from(excluded).sort()).toEqual(expected.sort());
+      },
+    );
+  });
+
   describe('YOLO mode with ask_user tool', () => {
     it('should return ASK_USER for ask_user tool even in YOLO mode', async () => {
       const rules: PolicyRule[] = [
diff --git a/packages/core/src/policy/policy-engine.ts b/packages/core/src/policy/policy-engine.ts
index 8a643c8930..1fc5e7cde5 100644
--- a/packages/core/src/policy/policy-engine.ts
+++ b/packages/core/src/policy/policy-engine.ts
@@ -26,6 +26,22 @@ import {
 } from '../utils/shell-utils.js';
 import { getToolAliases } from '../tools/tool-names.js';
 
+function isWildcardPattern(name: string): boolean {
+  return name.endsWith('__*');
+}
+
+function getWildcardPrefix(pattern: string): string {
+  return pattern.slice(0, -3);
+}
+
+function matchesWildcard(pattern: string, toolName: string): boolean {
+  if (!isWildcardPattern(pattern)) {
+    return false;
+  }
+  const prefix = getWildcardPrefix(pattern);
+  return toolName.startsWith(prefix + '__');
+}
+
 function ruleMatches(
   rule: PolicyRule | SafetyCheckerRule,
   toolCall: FunctionCall,
@@ -43,8 +59,8 @@ function ruleMatches(
   // Check tool name if specified
   if (rule.toolName) {
     // Support wildcard patterns: "serverName__*" matches "serverName__anyTool"
-    if (rule.toolName.endsWith('__*')) {
-      const prefix = rule.toolName.slice(0, -3); // Remove "__*"
+    if (isWildcardPattern(rule.toolName)) {
+      const prefix = getWildcardPrefix(rule.toolName);
       if (serverName !== undefined) {
         // Robust check: if serverName is provided, it MUST match the prefix exactly.
         // This prevents "malicious-server" from spoofing "trusted-server" by naming itself "trusted-server__malicious".
@@ -53,7 +69,7 @@ function ruleMatches(
         }
       }
       // Always verify the prefix, even if serverName matched
-      if (!toolCall.name || !toolCall.name.startsWith(prefix + '__')) {
+      if (!toolCall.name || !matchesWildcard(rule.toolName, toolCall.name)) {
         return false;
       }
     } else if (toolCall.name !== rule.toolName) {
@@ -509,6 +525,90 @@ export class PolicyEngine {
     return this.hookCheckers;
   }
 
+  /**
+   * Get tools that are effectively denied by the current rules.
+   * This takes into account:
+   * 1. Global rules (no argsPattern)
+   * 2. Priority order (higher priority wins)
+   * 3. Non-interactive mode (ASK_USER becomes DENY)
+   */
+  getExcludedTools(): Set<string> {
+    const excludedTools = new Set<string>();
+    const processedTools = new Set<string>();
+    let globalVerdict: PolicyDecision | undefined;
+
+    for (const rule of this.rules) {
+      // We only care about rules without args pattern for exclusion from the model
+      if (rule.argsPattern) {
+        continue;
+      }
+
+      // Check if rule applies to current approval mode
+      if (rule.modes && rule.modes.length > 0) {
+        if (!rule.modes.includes(this.approvalMode)) {
+          continue;
+        }
+      }
+
+      // Handle Global Rules
+      if (!rule.toolName) {
+        if (globalVerdict === undefined) {
+          globalVerdict = rule.decision;
+          if (globalVerdict !== PolicyDecision.DENY) {
+            // Global ALLOW/ASK found.
+            // Since rules are sorted by priority, this overrides any lower-priority rules.
+            // We can stop processing because nothing else will be excluded.
+            break;
+          }
+          // If Global DENY, we continue to find specific tools to add to excluded set
+        }
+        continue;
+      }
+
+      const toolName = rule.toolName;
+
+      // Check if already processed (exact match)
+      if (processedTools.has(toolName)) {
+        continue;
+      }
+
+      // Check if covered by a processed wildcard
+      let coveredByWildcard = false;
+      for (const processed of processedTools) {
+        if (
+          isWildcardPattern(processed) &&
+          matchesWildcard(processed, toolName)
+        ) {
+          // It's covered by a higher-priority wildcard rule.
+          // If that wildcard rule resulted in exclusion, this tool should also be excluded.
+          if (excludedTools.has(processed)) {
+            excludedTools.add(toolName);
+          }
+          coveredByWildcard = true;
+          break;
+        }
+      }
+      if (coveredByWildcard) {
+        continue;
+      }
+
+      processedTools.add(toolName);
+
+      // Determine decision
+      let decision: PolicyDecision;
+      if (globalVerdict !== undefined) {
+        decision = globalVerdict;
+      } else {
+        decision = rule.decision;
+      }
+
+      if (decision === PolicyDecision.DENY) {
+        excludedTools.add(toolName);
+      }
+    }
+    return excludedTools;
+  }
+
   private applyNonInteractiveMode(decision: PolicyDecision): PolicyDecision {
     // In non-interactive mode, ASK_USER becomes DENY
     if (this.nonInteractive && decision === PolicyDecision.ASK_USER) {

From a1148ea1f189e9839bccf33e6a9afe6b45e92729 Mon Sep 17 00:00:00 2001
From: Bryan Morgan <bryanmorgan@google.com>
Date: Wed, 11 Feb 2026 20:56:43 -0500
Subject: [PATCH 12/44] fix(workflows): improve maintainer detection for
 automated PR actions (#18869)

---
 .../gemini-scheduled-stale-pr-closer.yml      | 65 ++++++++++++++-----
 .../pr-contribution-guidelines-notifier.yml   | 26 +++++++-
 2 files changed, 73 insertions(+), 18 deletions(-)

diff --git a/.github/workflows/gemini-scheduled-stale-pr-closer.yml b/.github/workflows/gemini-scheduled-stale-pr-closer.yml
index 90d7417b05..bd7fd0ddc9 100644
--- a/.github/workflows/gemini-scheduled-stale-pr-closer.yml
+++ b/.github/workflows/gemini-scheduled-stale-pr-closer.yml
@@ -43,23 +43,56 @@ jobs:
 
             // 1. Fetch maintainers for verification
             let maintainerLogins = new Set();
-            let teamFetchSucceeded = false;
-            try {
-              const members = await github.paginate(github.rest.teams.listMembersInOrg, {
-                org: context.repo.owner,
-                team_slug: 'gemini-cli-maintainers'
-              });
-              maintainerLogins = new Set(members.map(m => m.login.toLowerCase()));
-              teamFetchSucceeded = true;
-              core.info(`Successfully fetched ${maintainerLogins.size} team members from gemini-cli-maintainers`);
-            } catch (e) {
-              core.warning(`Failed to fetch team members from gemini-cli-maintainers: ${e.message}. Falling back to author_association only.`);
+            const teams = ['gemini-cli-maintainers', 'gemini-cli-askmode-approvers', 'gemini-cli-docs'];
+
+            for (const team_slug of teams) {
+              try {
+                const members = await github.paginate(github.rest.teams.listMembersInOrg, {
+                  org: context.repo.owner,
+                  team_slug: team_slug
+                });
+                for (const m of members) maintainerLogins.add(m.login.toLowerCase());
+                core.info(`Successfully fetched ${members.length} team members from ${team_slug}`);
+              } catch (e) {
+                core.warning(`Failed to fetch team members from ${team_slug}: ${e.message}`);
+              }
             }
 
-            const isMaintainer = (login, assoc) => {
+            const isGooglerCache = new Map();
+            const isGoogler = async (login) => {
+              if (isGooglerCache.has(login)) return isGooglerCache.get(login);
+
+              try {
+                // Check membership in 'googlers' or 'google' orgs
+                const orgs = ['googlers', 'google'];
+                for (const org of orgs) {
+                  try {
+                    await github.rest.orgs.checkMembershipForUser({
+                      org: org,
+                      username: login
+                    });
+                    core.info(`User ${login} is a member of ${org} organization.`);
+                    isGooglerCache.set(login, true);
+                    return true;
+                  } catch (e) {
+                    // 404 just means they aren't a member, which is fine
+                    if (e.status !== 404) throw e;
+                  }
+                }
+              } catch (e) {
+                core.warning(`Failed to check org membership for ${login}: ${e.message}`);
+              }
+
+              isGooglerCache.set(login, false);
+              return false;
+            };
+
+            const isMaintainer = async (login, assoc) => {
               const isTeamMember = maintainerLogins.has(login.toLowerCase());
               const isRepoMaintainer = ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(assoc);
-              return isTeamMember || isRepoMaintainer;
+              if (isTeamMember || isRepoMaintainer) return true;
+
+              return await isGoogler(login);
             };
 
             // 2. Determine which PRs to check
@@ -81,7 +114,7 @@ jobs:
             }
 
             for (const pr of prs) {
-              const maintainerPr = isMaintainer(pr.user.login, pr.author_association);
+              const maintainerPr = await isMaintainer(pr.user.login, pr.author_association);
               const isBot = pr.user.type === 'Bot' || pr.user.login.endsWith('[bot]');
 
               // Detection Logic for Linked Issues
@@ -175,7 +208,7 @@ jobs:
                     pull_number: pr.number
                   });
                   for (const r of reviews) {
-                    if (isMaintainer(r.user.login, r.author_association)) {
+                    if (await isMaintainer(r.user.login, r.author_association)) {
                       const d = new Date(r.submitted_at || r.updated_at);
                       if (d > lastActivity) lastActivity = d;
                     }
@@ -186,7 +219,7 @@ jobs:
                     issue_number: pr.number
                   });
                   for (const c of comments) {
-                    if (isMaintainer(c.user.login, c.author_association)) {
+                    if (await isMaintainer(c.user.login, c.author_association)) {
                       const d = new Date(c.updated_at);
                       if (d > lastActivity) lastActivity = d;
                     }
diff --git a/.github/workflows/pr-contribution-guidelines-notifier.yml b/.github/workflows/pr-contribution-guidelines-notifier.yml
index fdabd20f3d..2658520371 100644
--- a/.github/workflows/pr-contribution-guidelines-notifier.yml
+++ b/.github/workflows/pr-contribution-guidelines-notifier.yml
@@ -35,9 +35,31 @@ jobs:
             const pr_number = context.payload.pull_request.number;
 
             // 1. Check if the PR author is a maintainer
+            const isGoogler = async (login) => {
+              try {
+                const orgs = ['googlers', 'google'];
+                for (const org of orgs) {
+                  try {
+                    await github.rest.orgs.checkMembershipForUser({
+                      org: org,
+                      username: login
+                    });
+                    return true;
+                  } catch (e) {
+                    if (e.status !== 404) throw e;
+                  }
+                }
+              } catch (e) {
+                core.warning(`Failed to check org membership for ${login}: ${e.message}`);
+              }
+              return false;
+            };
+
             const authorAssociation = context.payload.pull_request.author_association;
-            if (['OWNER', 'MEMBER', 'COLLABORATOR'].includes(authorAssociation)) {
-              core.info(`${username} is a maintainer (Association: ${authorAssociation}). No notification needed.`);
+            const isRepoMaintainer = ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(authorAssociation);
+
+            if (isRepoMaintainer || await isGoogler(username)) {
+              core.info(`${username} is a maintainer or Googler. No notification needed.`);
               return;
             }
 

From fad9f462734670cc9431c9da34cc5183e9199b86 Mon Sep 17 00:00:00 2001
From: Abhi <43648792+abhipatel12@users.noreply.github.com>
Date: Wed, 11 Feb 2026 20:49:30 -0500
Subject: [PATCH 13/44] refactor(cli): consolidate useToolScheduler and delete
 legacy implementation (#18567)

---
 packages/cli/src/test-utils/mockConfig.ts     |    1 +
 packages/cli/src/ui/App.test.tsx              |    4 -
 packages/cli/src/ui/AppContainer.test.tsx     |    2 +-
 .../useToolScheduler.test.ts.snap             |   97 --
 .../cli/src/ui/hooks/useGeminiStream.test.tsx |    1 -
 .../ui/hooks/useReactToolScheduler.test.ts    |   77 -
 .../cli/src/ui/hooks/useReactToolScheduler.ts |  221 ---
 .../src/ui/hooks/useShellInactivityStatus.ts  |    2 +-
 .../hooks/useToolExecutionScheduler.test.ts   |  525 ------
 .../src/ui/hooks/useToolExecutionScheduler.ts |  253 ---
 .../cli/src/ui/hooks/useToolScheduler.test.ts | 1534 +++++------------
 packages/cli/src/ui/hooks/useToolScheduler.ts |  302 +++-
 .../ui/hooks/useTurnActivityMonitor.test.ts   |    2 +-
 .../src/ui/hooks/useTurnActivityMonitor.ts    |    2 +-
 14 files changed, 721 insertions(+), 2302 deletions(-)
 delete mode 100644 packages/cli/src/ui/hooks/__snapshots__/useToolScheduler.test.ts.snap
 delete mode 100644 packages/cli/src/ui/hooks/useReactToolScheduler.test.ts
 delete mode 100644 packages/cli/src/ui/hooks/useReactToolScheduler.ts
 delete mode 100644 packages/cli/src/ui/hooks/useToolExecutionScheduler.test.ts
 delete mode 100644 packages/cli/src/ui/hooks/useToolExecutionScheduler.ts

diff --git a/packages/cli/src/test-utils/mockConfig.ts b/packages/cli/src/test-utils/mockConfig.ts
index ac2176c0e3..0a02e01889 100644
--- a/packages/cli/src/test-utils/mockConfig.ts
+++ b/packages/cli/src/test-utils/mockConfig.ts
@@ -18,6 +18,7 @@ export const createMockConfig = (overrides: Partial<Config> = {}): Config =>
     getSandbox: vi.fn(() => undefined),
     getQuestion: vi.fn(() => ''),
     isInteractive: vi.fn(() => false),
+    isInitialized: vi.fn(() => true),
     setTerminalBackground: vi.fn(),
     storage: {
       getProjectTempDir: vi.fn().mockReturnValue('/tmp/gemini-test'),
diff --git a/packages/cli/src/ui/App.test.tsx b/packages/cli/src/ui/App.test.tsx
index 6a19d80184..7d817f44f5 100644
--- a/packages/cli/src/ui/App.test.tsx
+++ b/packages/cli/src/ui/App.test.tsx
@@ -220,10 +220,6 @@ describe('App', () => {
     } as UIState;
 
     const configWithExperiment = makeFakeConfig();
-    vi.spyOn(
-      configWithExperiment,
-      'isEventDrivenSchedulerEnabled',
-    ).mockReturnValue(true);
     vi.spyOn(configWithExperiment, 'isTrustedFolder').mockReturnValue(true);
     vi.spyOn(configWithExperiment, 'getIdeMode').mockReturnValue(false);
 
diff --git a/packages/cli/src/ui/AppContainer.test.tsx b/packages/cli/src/ui/AppContainer.test.tsx
index b6fdd53325..0c333176e0 100644
--- a/packages/cli/src/ui/AppContainer.test.tsx
+++ b/packages/cli/src/ui/AppContainer.test.tsx
@@ -20,7 +20,7 @@ import { cleanup } from 'ink-testing-library';
 import { act, useContext, type ReactElement } from 'react';
 import { AppContainer } from './AppContainer.js';
 import { SettingsContext } from './contexts/SettingsContext.js';
-import { type TrackedToolCall } from './hooks/useReactToolScheduler.js';
+import { type TrackedToolCall } from './hooks/useToolScheduler.js';
 import {
   type Config,
   makeFakeConfig,
diff --git a/packages/cli/src/ui/hooks/__snapshots__/useToolScheduler.test.ts.snap b/packages/cli/src/ui/hooks/__snapshots__/useToolScheduler.test.ts.snap
deleted file mode 100644
index 3195316980..0000000000
--- a/packages/cli/src/ui/hooks/__snapshots__/useToolScheduler.test.ts.snap
+++ /dev/null
@@ -1,97 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`useReactToolScheduler > should handle live output updates 1`] = `
-{
-  "callId": "liveCall",
-  "contentLength": 12,
-  "data": undefined,
-  "error": undefined,
-  "errorType": undefined,
-  "outputFile": undefined,
-  "responseParts": [
-    {
-      "functionResponse": {
-        "id": "liveCall",
-        "name": "mockToolWithLiveOutput",
-        "response": {
-          "output": "Final output",
-        },
-      },
-    },
-  ],
-  "resultDisplay": "Final display",
-}
-`;
-
-exports[`useReactToolScheduler > should handle tool requiring confirmation - approved 1`] = `
-{
-  "callId": "callConfirm",
-  "contentLength": 16,
-  "data": undefined,
-  "error": undefined,
-  "errorType": undefined,
-  "outputFile": undefined,
-  "responseParts": [
-    {
-      "functionResponse": {
-        "id": "callConfirm",
-        "name": "mockToolRequiresConfirmation",
-        "response": {
-          "output": "Confirmed output",
-        },
-      },
-    },
-  ],
-  "resultDisplay": "Confirmed display",
-}
-`;
-
-exports[`useReactToolScheduler > should handle tool requiring confirmation - cancelled by user 1`] = `
-{
-  "callId": "callConfirmCancel",
-  "contentLength": 59,
-  "error": undefined,
-  "errorType": undefined,
-  "responseParts": [
-    {
-      "functionResponse": {
-        "id": "callConfirmCancel",
-        "name": "mockToolRequiresConfirmation",
-        "response": {
-          "error": "[Operation Cancelled] Reason: User cancelled the operation.",
-        },
-      },
-    },
-  ],
-  "resultDisplay": {
-    "fileDiff": "Mock tool requires confirmation",
-    "fileName": "mockToolRequiresConfirmation.ts",
-    "filePath": undefined,
-    "newContent": undefined,
-    "originalContent": undefined,
-  },
-}
-`;
-
-exports[`useReactToolScheduler > should schedule and execute a tool call successfully 1`] = `
-{
-  "callId": "call1",
-  "contentLength": 11,
-  "data": undefined,
-  "error": undefined,
-  "errorType": undefined,
-  "outputFile": undefined,
-  "responseParts": [
-    {
-      "functionResponse": {
-        "id": "call1",
-        "name": "mockTool",
-        "response": {
-          "output": "Tool output",
-        },
-      },
-    },
-  ],
-  "resultDisplay": "Formatted tool output",
-}
-`;
diff --git a/packages/cli/src/ui/hooks/useGeminiStream.test.tsx b/packages/cli/src/ui/hooks/useGeminiStream.test.tsx
index 294c537af4..ed7168667a 100644
--- a/packages/cli/src/ui/hooks/useGeminiStream.test.tsx
+++ b/packages/cli/src/ui/hooks/useGeminiStream.test.tsx
@@ -246,7 +246,6 @@ describe('useGeminiStream', () => {
     getContentGenerator: vi.fn(),
     isInteractive: () => false,
     getExperiments: () => {},
-    isEventDrivenSchedulerEnabled: vi.fn(() => false),
     getMaxSessionTurns: vi.fn(() => 100),
     isJitContextEnabled: vi.fn(() => false),
     getGlobalMemory: vi.fn(() => ''),
diff --git a/packages/cli/src/ui/hooks/useReactToolScheduler.test.ts b/packages/cli/src/ui/hooks/useReactToolScheduler.test.ts
deleted file mode 100644
index ed2c64d212..0000000000
--- a/packages/cli/src/ui/hooks/useReactToolScheduler.test.ts
+++ /dev/null
@@ -1,77 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { CoreToolScheduler } from '@google/gemini-cli-core';
-import type { Config } from '@google/gemini-cli-core';
-import { renderHook } from '../../test-utils/render.js';
-import { vi, describe, it, expect, beforeEach } from 'vitest';
-import { useReactToolScheduler } from './useReactToolScheduler.js';
-
-vi.mock('@google/gemini-cli-core', async (importOriginal) => {
-  const actual =
-    await importOriginal<typeof import('@google/gemini-cli-core')>();
-  return {
-    ...actual,
-    CoreToolScheduler: vi.fn(),
-  };
-});
-
-const mockCoreToolScheduler = vi.mocked(CoreToolScheduler);
-
-describe('useReactToolScheduler', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('only creates one instance of CoreToolScheduler even if props change', () => {
-    const onComplete = vi.fn();
-    const getPreferredEditor = vi.fn();
-    const config = {} as Config;
-
-    const { rerender } = renderHook(
-      (props) =>
-        useReactToolScheduler(
-          props.onComplete,
-          props.config,
-          props.getPreferredEditor,
-        ),
-      {
-        initialProps: {
-          onComplete,
-          config,
-          getPreferredEditor,
-        },
-      },
-    );
-
-    expect(mockCoreToolScheduler).toHaveBeenCalledTimes(1);
-
-    // Rerender with a new onComplete function
-    const newOnComplete = vi.fn();
-    rerender({
-      onComplete: newOnComplete,
-      config,
-      getPreferredEditor,
-    });
-    expect(mockCoreToolScheduler).toHaveBeenCalledTimes(1);
-
-    // Rerender with a new getPreferredEditor function
-    const newGetPreferredEditor = vi.fn();
-    rerender({
-      onComplete: newOnComplete,
-      config,
-      getPreferredEditor: newGetPreferredEditor,
-    });
-    expect(mockCoreToolScheduler).toHaveBeenCalledTimes(1);
-
-    rerender({
-      onComplete: newOnComplete,
-      config,
-      getPreferredEditor: newGetPreferredEditor,
-    });
-    expect(mockCoreToolScheduler).toHaveBeenCalledTimes(1);
-  });
-});
diff --git a/packages/cli/src/ui/hooks/useReactToolScheduler.ts b/packages/cli/src/ui/hooks/useReactToolScheduler.ts
deleted file mode 100644
index cd17b305b5..0000000000
--- a/packages/cli/src/ui/hooks/useReactToolScheduler.ts
+++ /dev/null
@@ -1,221 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import type {
-  Config,
-  ToolCallRequestInfo,
-  OutputUpdateHandler,
-  AllToolCallsCompleteHandler,
-  ToolCallsUpdateHandler,
-  ToolCall,
-  EditorType,
-  CompletedToolCall,
-  ExecutingToolCall,
-  ScheduledToolCall,
-  ValidatingToolCall,
-  WaitingToolCall,
-  CancelledToolCall,
-} from '@google/gemini-cli-core';
-import { CoreToolScheduler } from '@google/gemini-cli-core';
-import { useCallback, useState, useMemo, useEffect, useRef } from 'react';
-
-export type ScheduleFn = (
-  request: ToolCallRequestInfo | ToolCallRequestInfo[],
-  signal: AbortSignal,
-) => Promise<void>;
-export type MarkToolsAsSubmittedFn = (callIds: string[]) => void;
-export type CancelAllFn = (signal: AbortSignal) => void;
-
-export type TrackedScheduledToolCall = ScheduledToolCall & {
-  responseSubmittedToGemini?: boolean;
-};
-export type TrackedValidatingToolCall = ValidatingToolCall & {
-  responseSubmittedToGemini?: boolean;
-};
-export type TrackedWaitingToolCall = WaitingToolCall & {
-  responseSubmittedToGemini?: boolean;
-};
-export type TrackedExecutingToolCall = ExecutingToolCall & {
-  responseSubmittedToGemini?: boolean;
-};
-export type TrackedCompletedToolCall = CompletedToolCall & {
-  responseSubmittedToGemini?: boolean;
-};
-export type TrackedCancelledToolCall = CancelledToolCall & {
-  responseSubmittedToGemini?: boolean;
-};
-
-export type TrackedToolCall =
-  | TrackedScheduledToolCall
-  | TrackedValidatingToolCall
-  | TrackedWaitingToolCall
-  | TrackedExecutingToolCall
-  | TrackedCompletedToolCall
-  | TrackedCancelledToolCall;
-
-/**
- * Legacy scheduler implementation based on CoreToolScheduler callbacks.
- *
- * This is currently the default implementation used by useGeminiStream.
- * It will be phased out once the event-driven scheduler migration is complete.
- */
-export function useReactToolScheduler(
-  onComplete: (tools: CompletedToolCall[]) => Promise<void>,
-  config: Config,
-  getPreferredEditor: () => EditorType | undefined,
-): [
-  TrackedToolCall[],
-  ScheduleFn,
-  MarkToolsAsSubmittedFn,
-  React.Dispatch<React.SetStateAction<TrackedToolCall[]>>,
-  CancelAllFn,
-  number,
-] {
-  const [toolCallsForDisplay, setToolCallsForDisplay] = useState<
-    TrackedToolCall[]
-  >([]);
-  const [lastToolOutputTime, setLastToolOutputTime] = useState<number>(0);
-
-  const onCompleteRef = useRef(onComplete);
-  const getPreferredEditorRef = useRef(getPreferredEditor);
-
-  useEffect(() => {
-    onCompleteRef.current = onComplete;
-  }, [onComplete]);
-
-  useEffect(() => {
-    getPreferredEditorRef.current = getPreferredEditor;
-  }, [getPreferredEditor]);
-
-  const outputUpdateHandler: OutputUpdateHandler = useCallback(
-    (toolCallId, outputChunk) => {
-      setLastToolOutputTime(Date.now());
-      setToolCallsForDisplay((prevCalls) =>
-        prevCalls.map((tc) => {
-          if (tc.request.callId === toolCallId && tc.status === 'executing') {
-            const executingTc = tc;
-            return { ...executingTc, liveOutput: outputChunk };
-          }
-          return tc;
-        }),
-      );
-    },
-    [],
-  );
-
-  const allToolCallsCompleteHandler: AllToolCallsCompleteHandler = useCallback(
-    async (completedToolCalls) => {
-      await onCompleteRef.current(completedToolCalls);
-    },
-    [],
-  );
-
-  const toolCallsUpdateHandler: ToolCallsUpdateHandler = useCallback(
-    (allCoreToolCalls: ToolCall[]) => {
-      setToolCallsForDisplay((prevTrackedCalls) => {
-        const prevCallsMap = new Map(
-          prevTrackedCalls.map((c) => [c.request.callId, c]),
-        );
-
-        return allCoreToolCalls.map((coreTc): TrackedToolCall => {
-          const existingTrackedCall = prevCallsMap.get(coreTc.request.callId);
-
-          const responseSubmittedToGemini =
-            existingTrackedCall?.responseSubmittedToGemini ?? false;
-
-          if (coreTc.status === 'executing') {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-            const liveOutput = (existingTrackedCall as TrackedExecutingToolCall)
-              ?.liveOutput;
-            return {
-              ...coreTc,
-              responseSubmittedToGemini,
-              liveOutput,
-            };
-          } else if (
-            coreTc.status === 'success' ||
-            coreTc.status === 'error' ||
-            coreTc.status === 'cancelled'
-          ) {
-            return {
-              ...coreTc,
-              responseSubmittedToGemini,
-            };
-          } else {
-            return {
-              ...coreTc,
-              responseSubmittedToGemini,
-            };
-          }
-        });
-      });
-    },
-    [setToolCallsForDisplay],
-  );
-
-  const stableGetPreferredEditor = useCallback(
-    () => getPreferredEditorRef.current(),
-    [],
-  );
-
-  const scheduler = useMemo(
-    () =>
-      new CoreToolScheduler({
-        outputUpdateHandler,
-        onAllToolCallsComplete: allToolCallsCompleteHandler,
-        onToolCallsUpdate: toolCallsUpdateHandler,
-        getPreferredEditor: stableGetPreferredEditor,
-        config,
-      }),
-    [
-      config,
-      outputUpdateHandler,
-      allToolCallsCompleteHandler,
-      toolCallsUpdateHandler,
-      stableGetPreferredEditor,
-    ],
-  );
-
-  const schedule: ScheduleFn = useCallback(
-    (
-      request: ToolCallRequestInfo | ToolCallRequestInfo[],
-      signal: AbortSignal,
-    ) => {
-      setToolCallsForDisplay([]);
-      return scheduler.schedule(request, signal);
-    },
-    [scheduler, setToolCallsForDisplay],
-  );
-
-  const markToolsAsSubmitted: MarkToolsAsSubmittedFn = useCallback(
-    (callIdsToMark: string[]) => {
-      setToolCallsForDisplay((prevCalls) =>
-        prevCalls.map((tc) =>
-          callIdsToMark.includes(tc.request.callId)
-            ? { ...tc, responseSubmittedToGemini: true }
-            : tc,
-        ),
-      );
-    },
-    [],
-  );
-
-  const cancelAllToolCalls = useCallback(
-    (signal: AbortSignal) => {
-      scheduler.cancelAll(signal);
-    },
-    [scheduler],
-  );
-
-  return [
-    toolCallsForDisplay,
-    schedule,
-    markToolsAsSubmitted,
-    setToolCallsForDisplay,
-    cancelAllToolCalls,
-    lastToolOutputTime,
-  ];
-}
diff --git a/packages/cli/src/ui/hooks/useShellInactivityStatus.ts b/packages/cli/src/ui/hooks/useShellInactivityStatus.ts
index d0e5c0706d..092e58baae 100644
--- a/packages/cli/src/ui/hooks/useShellInactivityStatus.ts
+++ b/packages/cli/src/ui/hooks/useShellInactivityStatus.ts
@@ -12,7 +12,7 @@ import {
   SHELL_SILENT_WORKING_TITLE_DELAY_MS,
 } from '../constants.js';
 import type { StreamingState } from '../types.js';
-import { type TrackedToolCall } from './useReactToolScheduler.js';
+import { type TrackedToolCall } from './useToolScheduler.js';
 
 interface ShellInactivityStatusProps {
   activePtyId: number | string | null | undefined;
diff --git a/packages/cli/src/ui/hooks/useToolExecutionScheduler.test.ts b/packages/cli/src/ui/hooks/useToolExecutionScheduler.test.ts
deleted file mode 100644
index 797109499b..0000000000
--- a/packages/cli/src/ui/hooks/useToolExecutionScheduler.test.ts
+++ /dev/null
@@ -1,525 +0,0 @@
-/**
- * @license
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { act } from 'react';
-import { renderHook } from '../../test-utils/render.js';
-import { useToolExecutionScheduler } from './useToolExecutionScheduler.js';
-import {
-  MessageBusType,
-  ToolConfirmationOutcome,
-  Scheduler,
-  type Config,
-  type MessageBus,
-  type CompletedToolCall,
-  type ToolCallConfirmationDetails,
-  type ToolCallsUpdateMessage,
-  type AnyDeclarativeTool,
-  type AnyToolInvocation,
-  ROOT_SCHEDULER_ID,
-} from '@google/gemini-cli-core';
-import { createMockMessageBus } from '@google/gemini-cli-core/src/test-utils/mock-message-bus.js';
-
-// Mock Core Scheduler
-vi.mock('@google/gemini-cli-core', async (importOriginal) => {
-  const actual =
-    await importOriginal<typeof import('@google/gemini-cli-core')>();
-  return {
-    ...actual,
-    Scheduler: vi.fn().mockImplementation(() => ({
-      schedule: vi.fn().mockResolvedValue([]),
-      cancelAll: vi.fn(),
-    })),
-  };
-});
-
-const createMockTool = (
-  overrides: Partial<AnyDeclarativeTool> = {},
-): AnyDeclarativeTool =>
-  ({
-    name: 'test_tool',
-    displayName: 'Test Tool',
-    description: 'A test tool',
-    kind: 'function',
-    parameterSchema: {},
-    isOutputMarkdown: false,
-    build: vi.fn(),
-    ...overrides,
-  }) as AnyDeclarativeTool;
-
-const createMockInvocation = (
-  overrides: Partial<AnyToolInvocation> = {},
-): AnyToolInvocation =>
-  ({
-    getDescription: () => 'Executing test tool',
-    shouldConfirmExecute: vi.fn(),
-    execute: vi.fn(),
-    params: {},
-    toolLocations: [],
-    ...overrides,
-  }) as AnyToolInvocation;
-
-describe('useToolExecutionScheduler', () => {
-  let mockConfig: Config;
-  let mockMessageBus: MessageBus;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockMessageBus = createMockMessageBus() as unknown as MessageBus;
-    mockConfig = {
-      getMessageBus: () => mockMessageBus,
-    } as unknown as Config;
-  });
-
-  afterEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('initializes with empty tool calls', () => {
-    const { result } = renderHook(() =>
-      useToolExecutionScheduler(
-        vi.fn().mockResolvedValue(undefined),
-        mockConfig,
-        () => undefined,
-      ),
-    );
-    const [toolCalls] = result.current;
-    expect(toolCalls).toEqual([]);
-  });
-
-  it('updates tool calls when MessageBus emits TOOL_CALLS_UPDATE', () => {
-    const { result } = renderHook(() =>
-      useToolExecutionScheduler(
-        vi.fn().mockResolvedValue(undefined),
-        mockConfig,
-        () => undefined,
-      ),
-    );
-
-    const mockToolCall = {
-      status: 'executing' as const,
-      request: {
-        callId: 'call-1',
-        name: 'test_tool',
-        args: {},
-        isClientInitiated: false,
-        prompt_id: 'p1',
-      },
-      tool: createMockTool(),
-      invocation: createMockInvocation(),
-      liveOutput: 'Loading...',
-    };
-
-    act(() => {
-      void mockMessageBus.publish({
-        type: MessageBusType.TOOL_CALLS_UPDATE,
-        toolCalls: [mockToolCall],
-        schedulerId: ROOT_SCHEDULER_ID,
-      } as ToolCallsUpdateMessage);
-    });
-
-    const [toolCalls] = result.current;
-    expect(toolCalls).toHaveLength(1);
-    // Expect Core Object structure, not Display Object
-    expect(toolCalls[0]).toMatchObject({
-      request: { callId: 'call-1', name: 'test_tool' },
-      status: 'executing', // Core status
-      liveOutput: 'Loading...',
-      responseSubmittedToGemini: false,
-    });
-  });
-
-  it('injects onConfirm callback for awaiting_approval tools (Adapter Pattern)', async () => {
-    const { result } = renderHook(() =>
-      useToolExecutionScheduler(
-        vi.fn().mockResolvedValue(undefined),
-        mockConfig,
-        () => undefined,
-      ),
-    );
-
-    const mockToolCall = {
-      status: 'awaiting_approval' as const,
-      request: {
-        callId: 'call-1',
-        name: 'test_tool',
-        args: {},
-        isClientInitiated: false,
-        prompt_id: 'p1',
-      },
-      tool: createMockTool(),
-      invocation: createMockInvocation({
-        getDescription: () => 'Confirming test tool',
-      }),
-      confirmationDetails: { type: 'info', title: 'Confirm', prompt: 'Sure?' },
-      correlationId: 'corr-123',
-    };
-
-    act(() => {
-      void mockMessageBus.publish({
-        type: MessageBusType.TOOL_CALLS_UPDATE,
-        toolCalls: [mockToolCall],
-        schedulerId: ROOT_SCHEDULER_ID,
-      } as ToolCallsUpdateMessage);
-    });
-
-    const [toolCalls] = result.current;
-    const call = toolCalls[0];
-    if (call.status !== 'awaiting_approval') {
-      throw new Error('Expected status to be awaiting_approval');
-    }
-    const confirmationDetails =
-      call.confirmationDetails as ToolCallConfirmationDetails;
-
-    expect(confirmationDetails).toBeDefined();
-    expect(typeof confirmationDetails.onConfirm).toBe('function');
-
-    // Test that onConfirm publishes to MessageBus
-    const publishSpy = vi.spyOn(mockMessageBus, 'publish');
-    await confirmationDetails.onConfirm(ToolConfirmationOutcome.ProceedOnce);
-
-    expect(publishSpy).toHaveBeenCalledWith({
-      type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
-      correlationId: 'corr-123',
-      confirmed: true,
-      requiresUserConfirmation: false,
-      outcome: ToolConfirmationOutcome.ProceedOnce,
-      payload: undefined,
-    });
-  });
-
-  it('injects onConfirm with payload (Inline Edit support)', async () => {
-    const { result } = renderHook(() =>
-      useToolExecutionScheduler(
-        vi.fn().mockResolvedValue(undefined),
-        mockConfig,
-        () => undefined,
-      ),
-    );
-
-    const mockToolCall = {
-      status: 'awaiting_approval' as const,
-      request: {
-        callId: 'call-1',
-        name: 'test_tool',
-        args: {},
-        isClientInitiated: false,
-        prompt_id: 'p1',
-      },
-      tool: createMockTool(),
-      invocation: createMockInvocation(),
-      confirmationDetails: { type: 'edit', title: 'Edit', filePath: 'test.ts' },
-      correlationId: 'corr-edit',
-    };
-
-    act(() => {
-      void mockMessageBus.publish({
-        type: MessageBusType.TOOL_CALLS_UPDATE,
-        toolCalls: [mockToolCall],
-        schedulerId: ROOT_SCHEDULER_ID,
-      } as ToolCallsUpdateMessage);
-    });
-
-    const [toolCalls] = result.current;
-    const call = toolCalls[0];
-    if (call.status !== 'awaiting_approval') {
-      throw new Error('Expected awaiting_approval');
-    }
-    const confirmationDetails =
-      call.confirmationDetails as ToolCallConfirmationDetails;
-
-    const publishSpy = vi.spyOn(mockMessageBus, 'publish');
-    const mockPayload = { newContent: 'updated code' };
-    await confirmationDetails.onConfirm(
-      ToolConfirmationOutcome.ProceedOnce,
-      mockPayload,
-    );
-
-    expect(publishSpy).toHaveBeenCalledWith({
-      type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
-      correlationId: 'corr-edit',
-      confirmed: true,
-      requiresUserConfirmation: false,
-      outcome: ToolConfirmationOutcome.ProceedOnce,
-      payload: mockPayload,
-    });
-  });
-
-  it('preserves responseSubmittedToGemini flag across updates', () => {
-    const { result } = renderHook(() =>
-      useToolExecutionScheduler(
-        vi.fn().mockResolvedValue(undefined),
-        mockConfig,
-        () => undefined,
-      ),
-    );
-
-    const mockToolCall = {
-      status: 'success' as const,
-      request: {
-        callId: 'call-1',
-        name: 'test',
-        args: {},
-        isClientInitiated: false,
-        prompt_id: 'p1',
-      },
-      tool: createMockTool(),
-      invocation: createMockInvocation(),
-      response: {
-        callId: 'call-1',
-        resultDisplay: 'OK',
-        responseParts: [],
-        error: undefined,
-        errorType: undefined,
-      },
-    };
-
-    // 1. Initial success
-    act(() => {
-      void mockMessageBus.publish({
-        type: MessageBusType.TOOL_CALLS_UPDATE,
-        toolCalls: [mockToolCall],
-        schedulerId: ROOT_SCHEDULER_ID,
-      } as ToolCallsUpdateMessage);
-    });
-
-    // 2. Mark as submitted
-    act(() => {
-      const [, , markAsSubmitted] = result.current;
-      markAsSubmitted(['call-1']);
-    });
-
-    expect(result.current[0][0].responseSubmittedToGemini).toBe(true);
-
-    // 3. Receive another update (should preserve the true flag)
-    act(() => {
-      void mockMessageBus.publish({
-        type: MessageBusType.TOOL_CALLS_UPDATE,
-        toolCalls: [mockToolCall],
-        schedulerId: ROOT_SCHEDULER_ID,
-      } as ToolCallsUpdateMessage);
-    });
-
-    expect(result.current[0][0].responseSubmittedToGemini).toBe(true);
-  });
-
-  it('updates lastToolOutputTime when tools are executing', () => {
-    vi.useFakeTimers();
-    const { result } = renderHook(() =>
-      useToolExecutionScheduler(
-        vi.fn().mockResolvedValue(undefined),
-        mockConfig,
-        () => undefined,
-      ),
-    );
-
-    const startTime = Date.now();
-    vi.advanceTimersByTime(1000);
-
-    act(() => {
-      void mockMessageBus.publish({
-        type: MessageBusType.TOOL_CALLS_UPDATE,
-        toolCalls: [
-          {
-            status: 'executing' as const,
-            request: {
-              callId: 'call-1',
-              name: 'test',
-              args: {},
-              isClientInitiated: false,
-              prompt_id: 'p1',
-            },
-            tool: createMockTool(),
-            invocation: createMockInvocation(),
-          },
-        ],
-        schedulerId: ROOT_SCHEDULER_ID,
-      } as ToolCallsUpdateMessage);
-    });
-
-    const [, , , , , lastOutputTime] = result.current;
-    expect(lastOutputTime).toBeGreaterThan(startTime);
-    vi.useRealTimers();
-  });
-
-  it('delegates cancelAll to the Core Scheduler', () => {
-    const { result } = renderHook(() =>
-      useToolExecutionScheduler(
-        vi.fn().mockResolvedValue(undefined),
-        mockConfig,
-        () => undefined,
-      ),
-    );
-
-    const [, , , , cancelAll] = result.current;
-    const signal = new AbortController().signal;
-
-    // We need to find the mock instance of Scheduler
-    // Since we used vi.mock at top level, we can get it from vi.mocked(Scheduler)
-    const schedulerInstance = vi.mocked(Scheduler).mock.results[0].value;
-
-    cancelAll(signal);
-
-    expect(schedulerInstance.cancelAll).toHaveBeenCalled();
-  });
-
-  it('resolves the schedule promise when scheduler resolves', async () => {
-    const onComplete = vi.fn().mockResolvedValue(undefined);
-
-    const completedToolCall = {
-      status: 'success' as const,
-      request: {
-        callId: 'call-1',
-        name: 'test',
-        args: {},
-        isClientInitiated: false,
-        prompt_id: 'p1',
-      },
-      tool: createMockTool(),
-      invocation: createMockInvocation(),
-      response: {
-        callId: 'call-1',
-        responseParts: [],
-        resultDisplay: 'Success',
-        error: undefined,
-        errorType: undefined,
-      },
-    };
-
-    // Mock the specific return value for this test
-    const { Scheduler } = await import('@google/gemini-cli-core');
-    vi.mocked(Scheduler).mockImplementation(
-      () =>
-        ({
-          schedule: vi.fn().mockResolvedValue([completedToolCall]),
-          cancelAll: vi.fn(),
-        }) as unknown as Scheduler,
-    );
-
-    const { result } = renderHook(() =>
-      useToolExecutionScheduler(onComplete, mockConfig, () => undefined),
-    );
-
-    const [, schedule] = result.current;
-    const signal = new AbortController().signal;
-
-    let completedResult: CompletedToolCall[] = [];
-    await act(async () => {
-      completedResult = await schedule(
-        {
-          callId: 'call-1',
-          name: 'test',
-          args: {},
-          isClientInitiated: false,
-          prompt_id: 'p1',
-        },
-        signal,
-      );
-    });
-
-    expect(completedResult).toEqual([completedToolCall]);
-    expect(onComplete).toHaveBeenCalledWith([completedToolCall]);
-  });
-
-  it('setToolCallsForDisplay re-groups tools by schedulerId (Multi-Scheduler support)', () => {
-    const { result } = renderHook(() =>
-      useToolExecutionScheduler(
-        vi.fn().mockResolvedValue(undefined),
-        mockConfig,
-        () => undefined,
-      ),
-    );
-
-    const callRoot = {
-      status: 'success' as const,
-      request: {
-        callId: 'call-root',
-        name: 'test',
-        args: {},
-        isClientInitiated: false,
-        prompt_id: 'p1',
-      },
-      tool: createMockTool(),
-      invocation: createMockInvocation(),
-      response: {
-        callId: 'call-root',
-        responseParts: [],
-        resultDisplay: 'OK',
-        error: undefined,
-        errorType: undefined,
-      },
-      schedulerId: ROOT_SCHEDULER_ID,
-    };
-
-    const callSub = {
-      ...callRoot,
-      request: { ...callRoot.request, callId: 'call-sub' },
-      schedulerId: 'subagent-1',
-    };
-
-    // 1. Populate state with multiple schedulers
-    act(() => {
-      void mockMessageBus.publish({
-        type: MessageBusType.TOOL_CALLS_UPDATE,
-        toolCalls: [callRoot],
-        schedulerId: ROOT_SCHEDULER_ID,
-      } as ToolCallsUpdateMessage);
-
-      void mockMessageBus.publish({
-        type: MessageBusType.TOOL_CALLS_UPDATE,
-        toolCalls: [callSub],
-        schedulerId: 'subagent-1',
-      } as ToolCallsUpdateMessage);
-    });
-
-    let [toolCalls] = result.current;
-    expect(toolCalls).toHaveLength(2);
-    expect(
-      toolCalls.find((t) => t.request.callId === 'call-root')?.schedulerId,
-    ).toBe(ROOT_SCHEDULER_ID);
-    expect(
-      toolCalls.find((t) => t.request.callId === 'call-sub')?.schedulerId,
-    ).toBe('subagent-1');
-
-    // 2. Call setToolCallsForDisplay (e.g., simulate a manual update or clear)
-    act(() => {
-      const [, , , setToolCalls] = result.current;
-      setToolCalls((prev) =>
-        prev.map((t) => ({ ...t, responseSubmittedToGemini: true })),
-      );
-    });
-
-    // 3. Verify that tools are still present and maintain their scheduler IDs
-    // The internal map should have been re-grouped.
-    [toolCalls] = result.current;
-    expect(toolCalls).toHaveLength(2);
-    expect(toolCalls.every((t) => t.responseSubmittedToGemini)).toBe(true);
-
-    const updatedRoot = toolCalls.find((t) => t.request.callId === 'call-root');
-    const updatedSub = toolCalls.find((t) => t.request.callId === 'call-sub');
-
-    expect(updatedRoot?.schedulerId).toBe(ROOT_SCHEDULER_ID);
-    expect(updatedSub?.schedulerId).toBe('subagent-1');
-
-    // 4. Verify that a subsequent update to ONE scheduler doesn't wipe the other
-    act(() => {
-      void mockMessageBus.publish({
-        type: MessageBusType.TOOL_CALLS_UPDATE,
-        toolCalls: [{ ...callRoot, status: 'executing' }],
-        schedulerId: ROOT_SCHEDULER_ID,
-      } as ToolCallsUpdateMessage);
-    });
-
-    [toolCalls] = result.current;
-    expect(toolCalls).toHaveLength(2);
-    expect(
-      toolCalls.find((t) => t.request.callId === 'call-root')?.status,
-    ).toBe('executing');
-    expect(
-      toolCalls.find((t) => t.request.callId === 'call-sub')?.schedulerId,
-    ).toBe('subagent-1');
-  });
-});
diff --git a/packages/cli/src/ui/hooks/useToolExecutionScheduler.ts b/packages/cli/src/ui/hooks/useToolExecutionScheduler.ts
deleted file mode 100644
index 0c58e7fc41..0000000000
--- a/packages/cli/src/ui/hooks/useToolExecutionScheduler.ts
+++ /dev/null
@@ -1,253 +0,0 @@
-/**
- * @license
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import {
-  type Config,
-  type MessageBus,
-  type ToolCallRequestInfo,
-  type ToolCall,
-  type CompletedToolCall,
-  type ToolConfirmationPayload,
-  MessageBusType,
-  ToolConfirmationOutcome,
-  Scheduler,
-  type EditorType,
-  type ToolCallsUpdateMessage,
-  ROOT_SCHEDULER_ID,
-} from '@google/gemini-cli-core';
-import { useCallback, useState, useMemo, useEffect, useRef } from 'react';
-
-// Re-exporting types compatible with legacy hook expectations
-export type ScheduleFn = (
-  request: ToolCallRequestInfo | ToolCallRequestInfo[],
-  signal: AbortSignal,
-) => Promise<CompletedToolCall[]>;
-
-export type MarkToolsAsSubmittedFn = (callIds: string[]) => void;
-export type CancelAllFn = (signal: AbortSignal) => void;
-
-/**
- * The shape expected by useGeminiStream.
- * It matches the Core ToolCall structure + the UI metadata flag.
- */
-export type TrackedToolCall = ToolCall & {
-  responseSubmittedToGemini?: boolean;
-};
-
-/**
- * Modern tool scheduler hook using the event-driven Core Scheduler.
- *
- * This hook acts as an Adapter between the new MessageBus-driven Core
- * and the legacy callback-based UI components.
- */
-export function useToolExecutionScheduler(
-  onComplete: (tools: CompletedToolCall[]) => Promise<void>,
-  config: Config,
-  getPreferredEditor: () => EditorType | undefined,
-): [
-  TrackedToolCall[],
-  ScheduleFn,
-  MarkToolsAsSubmittedFn,
-  React.Dispatch<React.SetStateAction<TrackedToolCall[]>>,
-  CancelAllFn,
-  number,
-] {
-  // State stores tool calls organized by their originating schedulerId
-  const [toolCallsMap, setToolCallsMap] = useState<
-    Record<string, TrackedToolCall[]>
-  >({});
-  const [lastToolOutputTime, setLastToolOutputTime] = useState<number>(0);
-
-  const messageBus = useMemo(() => config.getMessageBus(), [config]);
-
-  const onCompleteRef = useRef(onComplete);
-  useEffect(() => {
-    onCompleteRef.current = onComplete;
-  }, [onComplete]);
-
-  const getPreferredEditorRef = useRef(getPreferredEditor);
-  useEffect(() => {
-    getPreferredEditorRef.current = getPreferredEditor;
-  }, [getPreferredEditor]);
-
-  const scheduler = useMemo(
-    () =>
-      new Scheduler({
-        config,
-        messageBus,
-        getPreferredEditor: () => getPreferredEditorRef.current(),
-        schedulerId: ROOT_SCHEDULER_ID,
-      }),
-    [config, messageBus],
-  );
-
-  const internalAdaptToolCalls = useCallback(
-    (coreCalls: ToolCall[], prevTracked: TrackedToolCall[]) =>
-      adaptToolCalls(coreCalls, prevTracked, messageBus),
-    [messageBus],
-  );
-
-  useEffect(() => {
-    const handler = (event: ToolCallsUpdateMessage) => {
-      // Update output timer for UI spinners (Side Effect)
-      if (event.toolCalls.some((tc) => tc.status === 'executing')) {
-        setLastToolOutputTime(Date.now());
-      }
-
-      setToolCallsMap((prev) => {
-        const adapted = internalAdaptToolCalls(
-          event.toolCalls,
-          prev[event.schedulerId] ?? [],
-        );
-
-        return {
-          ...prev,
-          [event.schedulerId]: adapted,
-        };
-      });
-    };
-
-    messageBus.subscribe(MessageBusType.TOOL_CALLS_UPDATE, handler);
-    return () => {
-      messageBus.unsubscribe(MessageBusType.TOOL_CALLS_UPDATE, handler);
-    };
-  }, [messageBus, internalAdaptToolCalls]);
-
-  const schedule: ScheduleFn = useCallback(
-    async (request, signal) => {
-      // Clear state for new run
-      setToolCallsMap({});
-
-      // 1. Await Core Scheduler directly
-      const results = await scheduler.schedule(request, signal);
-
-      // 2. Trigger legacy reinjection logic (useGeminiStream loop)
-      // Since this hook instance owns the "root" scheduler, we always trigger
-      // onComplete when it finishes its batch.
-      await onCompleteRef.current(results);
-
-      return results;
-    },
-    [scheduler],
-  );
-
-  const cancelAll: CancelAllFn = useCallback(
-    (_signal) => {
-      scheduler.cancelAll();
-    },
-    [scheduler],
-  );
-
-  const markToolsAsSubmitted: MarkToolsAsSubmittedFn = useCallback(
-    (callIdsToMark: string[]) => {
-      setToolCallsMap((prevMap) => {
-        const nextMap = { ...prevMap };
-        for (const [sid, calls] of Object.entries(nextMap)) {
-          nextMap[sid] = calls.map((tc) =>
-            callIdsToMark.includes(tc.request.callId)
-              ? { ...tc, responseSubmittedToGemini: true }
-              : tc,
-          );
-        }
-        return nextMap;
-      });
-    },
-    [],
-  );
-
-  // Flatten the map for the UI components that expect a single list of tools.
-  const toolCalls = useMemo(
-    () => Object.values(toolCallsMap).flat(),
-    [toolCallsMap],
-  );
-
-  // Provide a setter that maintains compatibility with legacy [].
-  const setToolCallsForDisplay = useCallback(
-    (action: React.SetStateAction<TrackedToolCall[]>) => {
-      setToolCallsMap((prev) => {
-        const currentFlattened = Object.values(prev).flat();
-        const nextFlattened =
-          typeof action === 'function' ? action(currentFlattened) : action;
-
-        if (nextFlattened.length === 0) {
-          return {};
-        }
-
-        // Re-group by schedulerId to preserve multi-scheduler state
-        const nextMap: Record<string, TrackedToolCall[]> = {};
-        for (const call of nextFlattened) {
-          // All tool calls should have a schedulerId from the core.
-          // Default to ROOT_SCHEDULER_ID as a safeguard.
-          const sid = call.schedulerId ?? ROOT_SCHEDULER_ID;
-          if (!nextMap[sid]) {
-            nextMap[sid] = [];
-          }
-          nextMap[sid].push(call);
-        }
-        return nextMap;
-      });
-    },
-    [],
-  );
-
-  return [
-    toolCalls,
-    schedule,
-    markToolsAsSubmitted,
-    setToolCallsForDisplay,
-    cancelAll,
-    lastToolOutputTime,
-  ];
-}
-
-/**
- * ADAPTER: Merges UI metadata (submitted flag) and injects legacy callbacks.
- */
-function adaptToolCalls(
-  coreCalls: ToolCall[],
-  prevTracked: TrackedToolCall[],
-  messageBus: MessageBus,
-): TrackedToolCall[] {
-  const prevMap = new Map(prevTracked.map((t) => [t.request.callId, t]));
-
-  return coreCalls.map((coreCall): TrackedToolCall => {
-    const prev = prevMap.get(coreCall.request.callId);
-    const responseSubmittedToGemini = prev?.responseSubmittedToGemini ?? false;
-
-    // Inject onConfirm adapter for tools awaiting approval.
-    // The Core provides data-only (serializable) confirmationDetails. We must
-    // inject the legacy callback function that proxies responses back to the
-    // MessageBus.
-    if (coreCall.status === 'awaiting_approval' && coreCall.correlationId) {
-      const correlationId = coreCall.correlationId;
-      return {
-        ...coreCall,
-        confirmationDetails: {
-          ...coreCall.confirmationDetails,
-          onConfirm: async (
-            outcome: ToolConfirmationOutcome,
-            payload?: ToolConfirmationPayload,
-          ) => {
-            await messageBus.publish({
-              type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
-              correlationId,
-              confirmed: outcome !== ToolConfirmationOutcome.Cancel,
-              requiresUserConfirmation: false,
-              outcome,
-              payload,
-            });
-          },
-        },
-        responseSubmittedToGemini,
-      };
-    }
-
-    return {
-      ...coreCall,
-      responseSubmittedToGemini,
-    };
-  });
-}
diff --git a/packages/cli/src/ui/hooks/useToolScheduler.test.ts b/packages/cli/src/ui/hooks/useToolScheduler.test.ts
index 81cafb4f34..4a04d6225c 100644
--- a/packages/cli/src/ui/hooks/useToolScheduler.test.ts
+++ b/packages/cli/src/ui/hooks/useToolScheduler.test.ts
@@ -1,1135 +1,525 @@
 /**
  * @license
- * Copyright 2025 Google LLC
+ * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import type { Mock } from 'vitest';
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { act } from 'react';
 import { renderHook } from '../../test-utils/render.js';
-import { useReactToolScheduler } from './useReactToolScheduler.js';
-import { mapToDisplay } from './toolMapping.js';
-import type { PartUnion, FunctionResponse } from '@google/genai';
-import type {
-  Config,
-  ToolCallRequestInfo,
-  ToolRegistry,
-  ToolResult,
-  ToolCallConfirmationDetails,
-  ToolCallResponseInfo,
-  ToolCall, // Import from core
-  Status as ToolCallStatusType,
-  AnyDeclarativeTool,
-  AnyToolInvocation,
-} from '@google/gemini-cli-core';
+import { useToolScheduler } from './useToolScheduler.js';
 import {
-  DEFAULT_TRUNCATE_TOOL_OUTPUT_THRESHOLD,
+  MessageBusType,
   ToolConfirmationOutcome,
-  ApprovalMode,
-  HookSystem,
-  PREVIEW_GEMINI_MODEL,
-  PolicyDecision,
+  Scheduler,
+  type Config,
+  type MessageBus,
+  type CompletedToolCall,
+  type ToolCallConfirmationDetails,
+  type ToolCallsUpdateMessage,
+  type AnyDeclarativeTool,
+  type AnyToolInvocation,
+  ROOT_SCHEDULER_ID,
 } from '@google/gemini-cli-core';
-import { MockTool } from '@google/gemini-cli-core/src/test-utils/mock-tool.js';
 import { createMockMessageBus } from '@google/gemini-cli-core/src/test-utils/mock-message-bus.js';
-import { ToolCallStatus } from '../types.js';
 
-// Mocks
-vi.mock('@google/gemini-cli-core', async () => {
-  const actual = await vi.importActual<any>('@google/gemini-cli-core');
-  // Patch CoreToolScheduler to have cancelAll if it's missing in the test environment
-  if (
-    actual.CoreToolScheduler &&
-    !actual.CoreToolScheduler.prototype.cancelAll
-  ) {
-    actual.CoreToolScheduler.prototype.cancelAll = vi.fn();
-  }
+// Mock Core Scheduler
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
   return {
     ...actual,
-    ToolRegistry: vi.fn(),
-    Config: vi.fn(),
+    Scheduler: vi.fn().mockImplementation(() => ({
+      schedule: vi.fn().mockResolvedValue([]),
+      cancelAll: vi.fn(),
+    })),
   };
 });
 
-const mockToolRegistry = {
-  getTool: vi.fn(),
-  getAllToolNames: vi.fn(() => ['mockTool', 'anotherTool']),
-};
+const createMockTool = (
+  overrides: Partial<AnyDeclarativeTool> = {},
+): AnyDeclarativeTool =>
+  ({
+    name: 'test_tool',
+    displayName: 'Test Tool',
+    description: 'A test tool',
+    kind: 'function',
+    parameterSchema: {},
+    isOutputMarkdown: false,
+    build: vi.fn(),
+    ...overrides,
+  }) as AnyDeclarativeTool;
 
-const mockConfig = {
-  getToolRegistry: vi.fn(() => mockToolRegistry as unknown as ToolRegistry),
-  getApprovalMode: vi.fn(() => ApprovalMode.DEFAULT),
-  getSessionId: () => 'test-session-id',
-  getUsageStatisticsEnabled: () => true,
-  getDebugMode: () => false,
-  getWorkingDir: () => '/working/dir',
-  storage: {
-    getProjectTempDir: () => '/tmp',
-  },
-  getTruncateToolOutputThreshold: () => DEFAULT_TRUNCATE_TOOL_OUTPUT_THRESHOLD,
-  getAllowedTools: vi.fn(() => []),
-  getActiveModel: () => PREVIEW_GEMINI_MODEL,
-  getContentGeneratorConfig: () => ({
-    model: 'test-model',
-    authType: 'oauth-personal',
-  }),
-  getGeminiClient: () => null, // No client needed for these tests
-  getShellExecutionConfig: () => ({ terminalWidth: 80, terminalHeight: 24 }),
-  getMessageBus: () => null,
-  isInteractive: () => false,
-  getExperiments: () => {},
-  getEnableHooks: () => false,
-} as unknown as Config;
-mockConfig.getMessageBus = vi.fn().mockReturnValue(createMockMessageBus());
-mockConfig.getHookSystem = vi.fn().mockReturnValue(new HookSystem(mockConfig));
-mockConfig.getPolicyEngine = vi.fn().mockReturnValue({
-  check: async () => {
-    const mode = mockConfig.getApprovalMode();
-    if (mode === ApprovalMode.YOLO) {
-      return { decision: PolicyDecision.ALLOW };
-    }
-    return { decision: PolicyDecision.ASK_USER };
-  },
-});
+const createMockInvocation = (
+  overrides: Partial<AnyToolInvocation> = {},
+): AnyToolInvocation =>
+  ({
+    getDescription: () => 'Executing test tool',
+    shouldConfirmExecute: vi.fn(),
+    execute: vi.fn(),
+    params: {},
+    toolLocations: [],
+    ...overrides,
+  }) as AnyToolInvocation;
 
-function createMockConfigOverride(overrides: Partial<Config> = {}): Config {
-  return { ...mockConfig, ...overrides } as Config;
-}
-
-const mockTool = new MockTool({
-  name: 'mockTool',
-  displayName: 'Mock Tool',
-  execute: vi.fn(),
-  shouldConfirmExecute: vi.fn(),
-});
-const mockToolWithLiveOutput = new MockTool({
-  name: 'mockToolWithLiveOutput',
-  displayName: 'Mock Tool With Live Output',
-  description: 'A mock tool for testing',
-  params: {},
-  isOutputMarkdown: true,
-  canUpdateOutput: true,
-  execute: vi.fn(),
-  shouldConfirmExecute: vi.fn(),
-});
-let mockOnUserConfirmForToolConfirmation: Mock;
-const mockToolRequiresConfirmation = new MockTool({
-  name: 'mockToolRequiresConfirmation',
-  displayName: 'Mock Tool Requires Confirmation',
-  execute: vi.fn(),
-  shouldConfirmExecute: vi.fn(),
-});
-
-describe('useReactToolScheduler in YOLO Mode', () => {
-  let onComplete: Mock;
+describe('useToolScheduler', () => {
+  let mockConfig: Config;
+  let mockMessageBus: MessageBus;
 
   beforeEach(() => {
-    onComplete = vi.fn();
-    mockToolRegistry.getTool.mockClear();
-    (mockToolRequiresConfirmation.execute as Mock).mockClear();
-    (mockToolRequiresConfirmation.shouldConfirmExecute as Mock).mockClear();
-
-    // IMPORTANT: Enable YOLO mode for this test suite
-    (mockConfig.getApprovalMode as Mock).mockReturnValue(ApprovalMode.YOLO);
-
-    vi.useFakeTimers();
+    vi.clearAllMocks();
+    mockMessageBus = createMockMessageBus() as unknown as MessageBus;
+    mockConfig = {
+      getMessageBus: () => mockMessageBus,
+    } as unknown as Config;
   });
 
   afterEach(() => {
-    vi.clearAllTimers();
-    vi.useRealTimers();
-    // IMPORTANT: Disable YOLO mode after this test suite
-    (mockConfig.getApprovalMode as Mock).mockReturnValue(ApprovalMode.DEFAULT);
+    vi.clearAllMocks();
   });
 
-  const renderSchedulerInYoloMode = () =>
-    renderHook(() =>
-      useReactToolScheduler(
-        onComplete,
-        mockConfig as unknown as Config,
+  it('initializes with empty tool calls', () => {
+    const { result } = renderHook(() =>
+      useToolScheduler(
+        vi.fn().mockResolvedValue(undefined),
+        mockConfig,
+        () => undefined,
+      ),
+    );
+    const [toolCalls] = result.current;
+    expect(toolCalls).toEqual([]);
+  });
+
+  it('updates tool calls when MessageBus emits TOOL_CALLS_UPDATE', () => {
+    const { result } = renderHook(() =>
+      useToolScheduler(
+        vi.fn().mockResolvedValue(undefined),
+        mockConfig,
         () => undefined,
       ),
     );
 
-  it('should skip confirmation and execute tool directly when yoloMode is true', async () => {
-    mockToolRegistry.getTool.mockReturnValue(mockToolRequiresConfirmation);
-    const expectedOutput = 'YOLO Confirmed output';
-    (mockToolRequiresConfirmation.execute as Mock).mockResolvedValue({
-      llmContent: expectedOutput,
-      returnDisplay: 'YOLO Formatted tool output',
-    } as ToolResult);
+    const mockToolCall = {
+      status: 'executing' as const,
+      request: {
+        callId: 'call-1',
+        name: 'test_tool',
+        args: {},
+        isClientInitiated: false,
+        prompt_id: 'p1',
+      },
+      tool: createMockTool(),
+      invocation: createMockInvocation(),
+      liveOutput: 'Loading...',
+    };
 
-    const { result } = renderSchedulerInYoloMode();
-    const schedule = result.current[1];
-    const request: ToolCallRequestInfo = {
-      callId: 'yoloCall',
-      name: 'mockToolRequiresConfirmation',
-      args: { data: 'any data' },
-    } as any;
-
-    await act(async () => {
-      await schedule(request, new AbortController().signal);
+    act(() => {
+      void mockMessageBus.publish({
+        type: MessageBusType.TOOL_CALLS_UPDATE,
+        toolCalls: [mockToolCall],
+        schedulerId: ROOT_SCHEDULER_ID,
+      } as ToolCallsUpdateMessage);
     });
 
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(0); // Process validation
-    });
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(0); // Process scheduling
-    });
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(0); // Process execution
+    const [toolCalls] = result.current;
+    expect(toolCalls).toHaveLength(1);
+    // Expect Core Object structure, not Display Object
+    expect(toolCalls[0]).toMatchObject({
+      request: { callId: 'call-1', name: 'test_tool' },
+      status: 'executing', // Core status
+      liveOutput: 'Loading...',
+      responseSubmittedToGemini: false,
     });
+  });
 
-    // Check that execute WAS called
-    expect(mockToolRequiresConfirmation.execute).toHaveBeenCalledWith(
-      request.args,
+  it('injects onConfirm callback for awaiting_approval tools (Adapter Pattern)', async () => {
+    const { result } = renderHook(() =>
+      useToolScheduler(
+        vi.fn().mockResolvedValue(undefined),
+        mockConfig,
+        () => undefined,
+      ),
     );
 
-    // Check that onComplete was called with success
-    expect(onComplete).toHaveBeenCalledWith([
-      expect.objectContaining({
-        status: 'success',
-        request,
-        response: expect.objectContaining({
-          resultDisplay: 'YOLO Formatted tool output',
-          responseParts: [
-            {
-              functionResponse: {
-                id: 'yoloCall',
-                name: 'mockToolRequiresConfirmation',
-                response: { output: expectedOutput },
-              },
-            },
-          ],
-        }),
+    const mockToolCall = {
+      status: 'awaiting_approval' as const,
+      request: {
+        callId: 'call-1',
+        name: 'test_tool',
+        args: {},
+        isClientInitiated: false,
+        prompt_id: 'p1',
+      },
+      tool: createMockTool(),
+      invocation: createMockInvocation({
+        getDescription: () => 'Confirming test tool',
       }),
-    ]);
+      confirmationDetails: { type: 'info', title: 'Confirm', prompt: 'Sure?' },
+      correlationId: 'corr-123',
+    };
+
+    act(() => {
+      void mockMessageBus.publish({
+        type: MessageBusType.TOOL_CALLS_UPDATE,
+        toolCalls: [mockToolCall],
+        schedulerId: ROOT_SCHEDULER_ID,
+      } as ToolCallsUpdateMessage);
+    });
+
+    const [toolCalls] = result.current;
+    const call = toolCalls[0];
+    if (call.status !== 'awaiting_approval') {
+      throw new Error('Expected status to be awaiting_approval');
+    }
+    const confirmationDetails =
+      call.confirmationDetails as ToolCallConfirmationDetails;
+
+    expect(confirmationDetails).toBeDefined();
+    expect(typeof confirmationDetails.onConfirm).toBe('function');
+
+    // Test that onConfirm publishes to MessageBus
+    const publishSpy = vi.spyOn(mockMessageBus, 'publish');
+    await confirmationDetails.onConfirm(ToolConfirmationOutcome.ProceedOnce);
+
+    expect(publishSpy).toHaveBeenCalledWith({
+      type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+      correlationId: 'corr-123',
+      confirmed: true,
+      requiresUserConfirmation: false,
+      outcome: ToolConfirmationOutcome.ProceedOnce,
+      payload: undefined,
+    });
   });
-});
 
-describe('useReactToolScheduler', () => {
-  let onComplete: Mock;
-  let capturedOnConfirmForTest:
-    | ((outcome: ToolConfirmationOutcome) => void | Promise<void>)
-    | undefined;
-
-  const advanceAndSettle = async () => {
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(0);
-    });
-  };
-
-  const scheduleAndWaitForExecution = async (
-    schedule: (
-      req: ToolCallRequestInfo | ToolCallRequestInfo[],
-      signal: AbortSignal,
-    ) => Promise<void>,
-    request: ToolCallRequestInfo | ToolCallRequestInfo[],
-  ) => {
-    await act(async () => {
-      await schedule(request, new AbortController().signal);
-    });
-
-    await advanceAndSettle();
-    await advanceAndSettle();
-    await advanceAndSettle();
-  };
-
-  beforeEach(() => {
-    onComplete = vi.fn();
-    capturedOnConfirmForTest = undefined;
-
-    mockToolRegistry.getTool.mockClear();
-    (mockTool.execute as Mock).mockClear();
-    (mockTool.shouldConfirmExecute as Mock).mockClear();
-    (mockToolWithLiveOutput.execute as Mock).mockClear();
-    (mockToolWithLiveOutput.shouldConfirmExecute as Mock).mockClear();
-    (mockToolRequiresConfirmation.execute as Mock).mockClear();
-    (mockToolRequiresConfirmation.shouldConfirmExecute as Mock).mockClear();
-
-    mockOnUserConfirmForToolConfirmation = vi.fn();
-    (
-      mockToolRequiresConfirmation.shouldConfirmExecute as Mock
-    ).mockImplementation(
-      async (): Promise<ToolCallConfirmationDetails | null> =>
-        ({
-          onConfirm: mockOnUserConfirmForToolConfirmation,
-          fileName: 'mockToolRequiresConfirmation.ts',
-          fileDiff: 'Mock tool requires confirmation',
-          type: 'edit',
-          title: 'Mock Tool Requires Confirmation',
-        }) as any,
+  it('injects onConfirm with payload (Inline Edit support)', async () => {
+    const { result } = renderHook(() =>
+      useToolScheduler(
+        vi.fn().mockResolvedValue(undefined),
+        mockConfig,
+        () => undefined,
+      ),
     );
 
-    vi.useFakeTimers();
+    const mockToolCall = {
+      status: 'awaiting_approval' as const,
+      request: {
+        callId: 'call-1',
+        name: 'test_tool',
+        args: {},
+        isClientInitiated: false,
+        prompt_id: 'p1',
+      },
+      tool: createMockTool(),
+      invocation: createMockInvocation(),
+      confirmationDetails: { type: 'edit', title: 'Edit', filePath: 'test.ts' },
+      correlationId: 'corr-edit',
+    };
+
+    act(() => {
+      void mockMessageBus.publish({
+        type: MessageBusType.TOOL_CALLS_UPDATE,
+        toolCalls: [mockToolCall],
+        schedulerId: ROOT_SCHEDULER_ID,
+      } as ToolCallsUpdateMessage);
+    });
+
+    const [toolCalls] = result.current;
+    const call = toolCalls[0];
+    if (call.status !== 'awaiting_approval') {
+      throw new Error('Expected awaiting_approval');
+    }
+    const confirmationDetails =
+      call.confirmationDetails as ToolCallConfirmationDetails;
+
+    const publishSpy = vi.spyOn(mockMessageBus, 'publish');
+    const mockPayload = { newContent: 'updated code' };
+    await confirmationDetails.onConfirm(
+      ToolConfirmationOutcome.ProceedOnce,
+      mockPayload,
+    );
+
+    expect(publishSpy).toHaveBeenCalledWith({
+      type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+      correlationId: 'corr-edit',
+      confirmed: true,
+      requiresUserConfirmation: false,
+      outcome: ToolConfirmationOutcome.ProceedOnce,
+      payload: mockPayload,
+    });
   });
 
-  afterEach(() => {
-    vi.clearAllTimers();
+  it('preserves responseSubmittedToGemini flag across updates', () => {
+    const { result } = renderHook(() =>
+      useToolScheduler(
+        vi.fn().mockResolvedValue(undefined),
+        mockConfig,
+        () => undefined,
+      ),
+    );
+
+    const mockToolCall = {
+      status: 'success' as const,
+      request: {
+        callId: 'call-1',
+        name: 'test',
+        args: {},
+        isClientInitiated: false,
+        prompt_id: 'p1',
+      },
+      tool: createMockTool(),
+      invocation: createMockInvocation(),
+      response: {
+        callId: 'call-1',
+        resultDisplay: 'OK',
+        responseParts: [],
+        error: undefined,
+        errorType: undefined,
+      },
+    };
+
+    // 1. Initial success
+    act(() => {
+      void mockMessageBus.publish({
+        type: MessageBusType.TOOL_CALLS_UPDATE,
+        toolCalls: [mockToolCall],
+        schedulerId: ROOT_SCHEDULER_ID,
+      } as ToolCallsUpdateMessage);
+    });
+
+    // 2. Mark as submitted
+    act(() => {
+      const [, , markAsSubmitted] = result.current;
+      markAsSubmitted(['call-1']);
+    });
+
+    expect(result.current[0][0].responseSubmittedToGemini).toBe(true);
+
+    // 3. Receive another update (should preserve the true flag)
+    act(() => {
+      void mockMessageBus.publish({
+        type: MessageBusType.TOOL_CALLS_UPDATE,
+        toolCalls: [mockToolCall],
+        schedulerId: ROOT_SCHEDULER_ID,
+      } as ToolCallsUpdateMessage);
+    });
+
+    expect(result.current[0][0].responseSubmittedToGemini).toBe(true);
+  });
+
+  it('updates lastToolOutputTime when tools are executing', () => {
+    vi.useFakeTimers();
+    const { result } = renderHook(() =>
+      useToolScheduler(
+        vi.fn().mockResolvedValue(undefined),
+        mockConfig,
+        () => undefined,
+      ),
+    );
+
+    const startTime = Date.now();
+    vi.advanceTimersByTime(1000);
+
+    act(() => {
+      void mockMessageBus.publish({
+        type: MessageBusType.TOOL_CALLS_UPDATE,
+        toolCalls: [
+          {
+            status: 'executing' as const,
+            request: {
+              callId: 'call-1',
+              name: 'test',
+              args: {},
+              isClientInitiated: false,
+              prompt_id: 'p1',
+            },
+            tool: createMockTool(),
+            invocation: createMockInvocation(),
+          },
+        ],
+        schedulerId: ROOT_SCHEDULER_ID,
+      } as ToolCallsUpdateMessage);
+    });
+
+    const [, , , , , lastOutputTime] = result.current;
+    expect(lastOutputTime).toBeGreaterThan(startTime);
     vi.useRealTimers();
   });
 
-  const renderScheduler = (config: Config = mockConfig) =>
-    renderHook(() =>
-      useReactToolScheduler(onComplete, config, () => undefined),
-    );
-
-  it('initial state should be empty', () => {
-    const { result } = renderScheduler();
-    expect(result.current[0]).toEqual([]);
-  });
-
-  it('should schedule and execute a tool call successfully', async () => {
-    mockToolRegistry.getTool.mockReturnValue(mockTool);
-    (mockTool.execute as Mock).mockResolvedValue({
-      llmContent: 'Tool output',
-      returnDisplay: 'Formatted tool output',
-    } as ToolResult);
-    (mockTool.shouldConfirmExecute as Mock).mockResolvedValue(null);
-
-    const { result } = renderScheduler();
-    const request: ToolCallRequestInfo = {
-      callId: 'call1',
-      name: 'mockTool',
-      args: { param: 'value' },
-    } as any;
-
-    let completedToolCalls: ToolCall[] = [];
-    onComplete.mockImplementation((calls) => {
-      completedToolCalls = calls;
-    });
-
-    await scheduleAndWaitForExecution(result.current[1], request);
-
-    expect(mockTool.execute).toHaveBeenCalledWith(request.args);
-    expect(completedToolCalls).toHaveLength(1);
-    expect(completedToolCalls[0].status).toBe('success');
-    expect(completedToolCalls[0].request).toBe(request);
-
-    if (
-      completedToolCalls[0].status === 'success' ||
-      completedToolCalls[0].status === 'error'
-    ) {
-      expect(completedToolCalls[0].response).toMatchSnapshot();
-    }
-  });
-
-  it('should clear previous tool calls when scheduling new ones', async () => {
-    mockToolRegistry.getTool.mockReturnValue(mockTool);
-    (mockTool.execute as Mock).mockImplementation(async () => {
-      await new Promise((r) => setTimeout(r, 10));
-      return {
-        llmContent: 'Tool output',
-        returnDisplay: 'Formatted tool output',
-      };
-    });
-
-    const { result } = renderScheduler();
-    const schedule = result.current[1];
-    const setToolCallsForDisplay = result.current[3];
-
-    // Manually set a tool call in the display.
-    const oldToolCall = {
-      request: { callId: 'oldCall' },
-      status: 'success',
-    } as any;
-    act(() => {
-      setToolCallsForDisplay([oldToolCall]);
-    });
-    expect(result.current[0]).toEqual([oldToolCall]);
-
-    const newRequest: ToolCallRequestInfo = {
-      callId: 'newCall',
-      name: 'mockTool',
-      args: {},
-    } as any;
-    let schedulePromise: Promise<void>;
-    await act(async () => {
-      schedulePromise = schedule(newRequest, new AbortController().signal);
-    });
-
-    await advanceAndSettle();
-
-    // After scheduling, the old call should be gone,
-    // and the new one should be in the display in its initial state.
-    expect(result.current[0].length).toBe(1);
-    expect(result.current[0][0].request.callId).toBe('newCall');
-    expect(result.current[0][0].request.callId).not.toBe('oldCall');
-
-    // Let the new call finish.
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(20);
-    });
-
-    await act(async () => {
-      await schedulePromise;
-    });
-
-    expect(onComplete).toHaveBeenCalled();
-  });
-
-  it('should cancel all running tool calls', async () => {
-    mockToolRegistry.getTool.mockReturnValue(mockTool);
-
-    let resolveExecute: (value: ToolResult) => void = () => {};
-    const executePromise = new Promise<ToolResult>((resolve) => {
-      resolveExecute = resolve;
-    });
-    (mockTool.execute as Mock).mockReturnValue(executePromise);
-    (mockTool.shouldConfirmExecute as Mock).mockResolvedValue(null);
-
-    const { result } = renderScheduler();
-    const schedule = result.current[1];
-    const cancelAllToolCalls = result.current[4];
-    const request: ToolCallRequestInfo = {
-      callId: 'cancelCall',
-      name: 'mockTool',
-      args: {},
-    } as any;
-
-    let schedulePromise: Promise<void>;
-    await act(async () => {
-      schedulePromise = schedule(request, new AbortController().signal);
-    });
-
-    await advanceAndSettle(); // validation
-    await advanceAndSettle(); // Process scheduling
-
-    // At this point, the tool is 'executing' and waiting on the promise.
-    expect(result.current[0][0].status).toBe('executing');
-
-    const cancelController = new AbortController();
-    act(() => {
-      cancelAllToolCalls(cancelController.signal);
-    });
-
-    await advanceAndSettle();
-
-    expect(onComplete).toHaveBeenCalledWith([
-      expect.objectContaining({
-        status: 'cancelled',
-        request,
-      }),
-    ]);
-
-    // Clean up the pending promise to avoid open handles.
-    await act(async () => {
-      resolveExecute({ llmContent: 'output', returnDisplay: 'display' });
-    });
-
-    // Now await the schedule promise
-    await act(async () => {
-      await schedulePromise;
-    });
-  });
-
-  it.each([
-    {
-      desc: 'tool not found',
-      setup: () => {
-        mockToolRegistry.getTool.mockReturnValue(undefined);
-      },
-      request: {
-        callId: 'call1',
-        name: 'nonexistentTool',
-        args: {},
-      } as any,
-      expectedErrorContains: [
-        'Tool "nonexistentTool" not found in registry',
-        'Did you mean one of:',
-      ],
-    },
-    {
-      desc: 'error during shouldConfirmExecute',
-      setup: () => {
-        mockToolRegistry.getTool.mockReturnValue(mockTool);
-        const confirmError = new Error('Confirmation check failed');
-        (mockTool.shouldConfirmExecute as Mock).mockRejectedValue(confirmError);
-      },
-      request: {
-        callId: 'call1',
-        name: 'mockTool',
-        args: {},
-      } as any,
-      expectedError: new Error('Confirmation check failed'),
-    },
-    {
-      desc: 'error during execute',
-      setup: () => {
-        mockToolRegistry.getTool.mockReturnValue(mockTool);
-        (mockTool.shouldConfirmExecute as Mock).mockResolvedValue(null);
-        const execError = new Error('Execution failed');
-        (mockTool.execute as Mock).mockRejectedValue(execError);
-      },
-      request: {
-        callId: 'call1',
-        name: 'mockTool',
-        args: {},
-      } as any,
-      expectedError: new Error('Execution failed'),
-    },
-  ])(
-    'should handle $desc',
-    async ({ setup, request, expectedErrorContains, expectedError }) => {
-      setup();
-      const { result } = renderScheduler();
-
-      let completedToolCalls: ToolCall[] = [];
-      onComplete.mockImplementation((calls) => {
-        completedToolCalls = calls;
-      });
-
-      await scheduleAndWaitForExecution(result.current[1], request);
-
-      expect(completedToolCalls).toHaveLength(1);
-      expect(completedToolCalls[0].status).toBe('error');
-      expect(completedToolCalls[0].request).toBe(request);
-
-      if (expectedErrorContains) {
-        expectedErrorContains.forEach((errorText) => {
-          expect(
-            (completedToolCalls[0] as any).response.error.message,
-          ).toContain(errorText);
-        });
-      }
-
-      if (expectedError) {
-        expect((completedToolCalls[0] as any).response.error.message).toBe(
-          expectedError.message,
-        );
-      }
-    },
-  );
-
-  it('should handle tool requiring confirmation - approved', async () => {
-    mockToolRegistry.getTool.mockReturnValue(mockToolRequiresConfirmation);
-    const config = createMockConfigOverride({
-      isInteractive: () => true,
-    });
-    const expectedOutput = 'Confirmed output';
-    (mockToolRequiresConfirmation.execute as Mock).mockResolvedValue({
-      llmContent: expectedOutput,
-      returnDisplay: 'Confirmed display',
-    } as ToolResult);
-
-    const { result } = renderScheduler(config);
-    const schedule = result.current[1];
-    const request: ToolCallRequestInfo = {
-      callId: 'callConfirm',
-      name: 'mockToolRequiresConfirmation',
-      args: { data: 'sensitive' },
-    } as any;
-
-    let schedulePromise: Promise<void>;
-    await act(async () => {
-      schedulePromise = schedule(request, new AbortController().signal);
-    });
-    await advanceAndSettle();
-
-    const waitingCall = result.current[0][0] as any;
-    expect(waitingCall.status).toBe('awaiting_approval');
-    capturedOnConfirmForTest = waitingCall.confirmationDetails?.onConfirm;
-    expect(capturedOnConfirmForTest).toBeDefined();
-
-    await act(async () => {
-      await capturedOnConfirmForTest?.(ToolConfirmationOutcome.ProceedOnce);
-    });
-
-    await advanceAndSettle();
-
-    // Now await the schedule promise as it should complete
-    await act(async () => {
-      await schedulePromise;
-    });
-
-    expect(mockOnUserConfirmForToolConfirmation).toHaveBeenCalledWith(
-      ToolConfirmationOutcome.ProceedOnce,
-    );
-    expect(mockToolRequiresConfirmation.execute).toHaveBeenCalled();
-
-    const completedCalls = onComplete.mock.calls[0][0] as ToolCall[];
-    expect(completedCalls[0].status).toBe('success');
-    expect(completedCalls[0].request).toBe(request);
-    if (
-      completedCalls[0].status === 'success' ||
-      completedCalls[0].status === 'error'
-    ) {
-      expect(completedCalls[0].response).toMatchSnapshot();
-    }
-  });
-
-  it('should handle tool requiring confirmation - cancelled by user', async () => {
-    mockToolRegistry.getTool.mockReturnValue(mockToolRequiresConfirmation);
-    const config = createMockConfigOverride({
-      isInteractive: () => true,
-    });
-    const { result } = renderScheduler(config);
-    const schedule = result.current[1];
-    const request: ToolCallRequestInfo = {
-      callId: 'callConfirmCancel',
-      name: 'mockToolRequiresConfirmation',
-      args: {},
-    } as any;
-
-    let schedulePromise: Promise<void>;
-    await act(async () => {
-      schedulePromise = schedule(request, new AbortController().signal);
-    });
-    await advanceAndSettle();
-
-    const waitingCall = result.current[0][0] as any;
-    expect(waitingCall.status).toBe('awaiting_approval');
-    capturedOnConfirmForTest = waitingCall.confirmationDetails?.onConfirm;
-    expect(capturedOnConfirmForTest).toBeDefined();
-
-    await act(async () => {
-      await capturedOnConfirmForTest?.(ToolConfirmationOutcome.Cancel);
-    });
-
-    await advanceAndSettle();
-
-    // Now await the schedule promise
-    await act(async () => {
-      await schedulePromise;
-    });
-
-    expect(mockOnUserConfirmForToolConfirmation).toHaveBeenCalledWith(
-      ToolConfirmationOutcome.Cancel,
-    );
-
-    const completedCalls = onComplete.mock.calls[0][0] as ToolCall[];
-    expect(completedCalls[0].status).toBe('cancelled');
-    expect(completedCalls[0].request).toBe(request);
-    if (
-      completedCalls[0].status === 'success' ||
-      completedCalls[0].status === 'error' ||
-      completedCalls[0].status === 'cancelled'
-    ) {
-      expect(completedCalls[0].response).toMatchSnapshot();
-    }
-  });
-
-  it('should handle live output updates', async () => {
-    mockToolRegistry.getTool.mockReturnValue(mockToolWithLiveOutput);
-    let liveUpdateFn: ((output: string) => void) | undefined;
-    let resolveExecutePromise: (value: ToolResult) => void;
-    const executePromise = new Promise<ToolResult>((resolve) => {
-      resolveExecutePromise = resolve;
-    });
-
-    (mockToolWithLiveOutput.execute as Mock).mockImplementation(
-      async (
-        _args: Record<string, unknown>,
-        _signal: AbortSignal,
-        updateFn: ((output: string) => void) | undefined,
-      ) => {
-        liveUpdateFn = updateFn;
-        return executePromise;
-      },
-    );
-    (mockToolWithLiveOutput.shouldConfirmExecute as Mock).mockResolvedValue(
-      null,
-    );
-
-    const { result } = renderScheduler();
-    const request: ToolCallRequestInfo = {
-      callId: 'liveCall',
-      name: 'mockToolWithLiveOutput',
-      args: {},
-    } as any;
-
-    let schedulePromise: Promise<void>;
-    await act(async () => {
-      schedulePromise = result.current[1](
-        request,
-        new AbortController().signal,
-      );
-    });
-    await advanceAndSettle();
-
-    expect(liveUpdateFn).toBeDefined();
-    expect(result.current[0][0].status).toBe('executing');
-
-    await act(async () => {
-      liveUpdateFn?.('Live output 1');
-    });
-    await advanceAndSettle();
-
-    await act(async () => {
-      liveUpdateFn?.('Live output 2');
-    });
-    await advanceAndSettle();
-
-    act(() => {
-      resolveExecutePromise({
-        llmContent: 'Final output',
-        returnDisplay: 'Final display',
-      } as ToolResult);
-    });
-    await advanceAndSettle();
-
-    // Now await schedule
-    await act(async () => {
-      await schedulePromise;
-    });
-
-    const completedCalls = onComplete.mock.calls[0][0] as ToolCall[];
-    expect(completedCalls[0].status).toBe('success');
-    expect(completedCalls[0].request).toBe(request);
-    if (
-      completedCalls[0].status === 'success' ||
-      completedCalls[0].status === 'error'
-    ) {
-      expect(completedCalls[0].response).toMatchSnapshot();
-    }
-    expect(result.current[0]).toEqual([]);
-  });
-
-  it('should schedule and execute multiple tool calls', async () => {
-    const tool1 = new MockTool({
-      name: 'tool1',
-      displayName: 'Tool 1',
-      execute: vi.fn().mockResolvedValue({
-        llmContent: 'Output 1',
-        returnDisplay: 'Display 1',
-      } as ToolResult),
-    });
-
-    const tool2 = new MockTool({
-      name: 'tool2',
-      displayName: 'Tool 2',
-      execute: vi.fn().mockResolvedValue({
-        llmContent: 'Output 2',
-        returnDisplay: 'Display 2',
-      } as ToolResult),
-    });
-
-    mockToolRegistry.getTool.mockImplementation((name) => {
-      if (name === 'tool1') return tool1;
-      if (name === 'tool2') return tool2;
-      return undefined;
-    });
-
-    const { result } = renderScheduler();
-    const schedule = result.current[1];
-    const requests: ToolCallRequestInfo[] = [
-      { callId: 'multi1', name: 'tool1', args: { p: 1 } } as any,
-      { callId: 'multi2', name: 'tool2', args: { p: 2 } } as any,
-    ];
-
-    await act(async () => {
-      await schedule(requests, new AbortController().signal);
-    });
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(0);
-    });
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(0);
-    });
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(0);
-    });
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(0);
-    });
-
-    expect(onComplete).toHaveBeenCalledTimes(1);
-    const completedCalls = onComplete.mock.calls[0][0] as ToolCall[];
-    expect(completedCalls.length).toBe(2);
-
-    const call1Result = completedCalls.find(
-      (c) => c.request.callId === 'multi1',
-    );
-    const call2Result = completedCalls.find(
-      (c) => c.request.callId === 'multi2',
-    );
-
-    expect(call1Result).toMatchObject({
-      status: 'success',
-      request: requests[0],
-      response: expect.objectContaining({
-        resultDisplay: 'Display 1',
-        responseParts: [
-          {
-            functionResponse: {
-              id: 'multi1',
-              name: 'tool1',
-              response: { output: 'Output 1' },
-            },
-          },
-        ],
-      }),
-    });
-    expect(call2Result).toMatchObject({
-      status: 'success',
-      request: requests[1],
-      response: expect.objectContaining({
-        resultDisplay: 'Display 2',
-        responseParts: [
-          {
-            functionResponse: {
-              id: 'multi2',
-              name: 'tool2',
-              response: { output: 'Output 2' },
-            },
-          },
-        ],
-      }),
-    });
-
-    expect(completedCalls).toHaveLength(2);
-    expect(completedCalls.every((t) => t.status === 'success')).toBe(true);
-  });
-
-  it('should queue if scheduling while already running', async () => {
-    mockToolRegistry.getTool.mockReturnValue(mockTool);
-    const longExecutePromise = new Promise<ToolResult>((resolve) =>
-      setTimeout(
-        () =>
-          resolve({
-            llmContent: 'done',
-            returnDisplay: 'done display',
-          }),
-        50,
+  it('delegates cancelAll to the Core Scheduler', () => {
+    const { result } = renderHook(() =>
+      useToolScheduler(
+        vi.fn().mockResolvedValue(undefined),
+        mockConfig,
+        () => undefined,
       ),
     );
-    (mockTool.execute as Mock).mockReturnValue(longExecutePromise);
-    (mockTool.shouldConfirmExecute as Mock).mockResolvedValue(null);
 
-    const { result } = renderScheduler();
-    const schedule = result.current[1];
-    const request1: ToolCallRequestInfo = {
-      callId: 'run1',
-      name: 'mockTool',
-      args: {},
-    } as any;
-    const request2: ToolCallRequestInfo = {
-      callId: 'run2',
-      name: 'mockTool',
-      args: {},
-    } as any;
+    const [, , , , cancelAll] = result.current;
+    const signal = new AbortController().signal;
 
-    let schedulePromise1: Promise<void>;
-    let schedulePromise2: Promise<void>;
+    // We need to find the mock instance of Scheduler
+    // Since we used vi.mock at top level, we can get it from vi.mocked(Scheduler)
+    const schedulerInstance = vi.mocked(Scheduler).mock.results[0].value;
 
+    cancelAll(signal);
+
+    expect(schedulerInstance.cancelAll).toHaveBeenCalled();
+  });
+
+  it('resolves the schedule promise when scheduler resolves', async () => {
+    const onComplete = vi.fn().mockResolvedValue(undefined);
+
+    const completedToolCall = {
+      status: 'success' as const,
+      request: {
+        callId: 'call-1',
+        name: 'test',
+        args: {},
+        isClientInitiated: false,
+        prompt_id: 'p1',
+      },
+      tool: createMockTool(),
+      invocation: createMockInvocation(),
+      response: {
+        callId: 'call-1',
+        responseParts: [],
+        resultDisplay: 'Success',
+        error: undefined,
+        errorType: undefined,
+      },
+    };
+
+    // Mock the specific return value for this test
+    const { Scheduler } = await import('@google/gemini-cli-core');
+    vi.mocked(Scheduler).mockImplementation(
+      () =>
+        ({
+          schedule: vi.fn().mockResolvedValue([completedToolCall]),
+          cancelAll: vi.fn(),
+        }) as unknown as Scheduler,
+    );
+
+    const { result } = renderHook(() =>
+      useToolScheduler(onComplete, mockConfig, () => undefined),
+    );
+
+    const [, schedule] = result.current;
+    const signal = new AbortController().signal;
+
+    let completedResult: CompletedToolCall[] = [];
     await act(async () => {
-      schedulePromise1 = schedule(request1, new AbortController().signal);
-    });
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(0);
+      completedResult = await schedule(
+        {
+          callId: 'call-1',
+          name: 'test',
+          args: {},
+          isClientInitiated: false,
+          prompt_id: 'p1',
+        },
+        signal,
+      );
     });
 
-    await act(async () => {
-      schedulePromise2 = schedule(request2, new AbortController().signal);
+    expect(completedResult).toEqual([completedToolCall]);
+    expect(onComplete).toHaveBeenCalledWith([completedToolCall]);
+  });
+
+  it('setToolCallsForDisplay re-groups tools by schedulerId (Multi-Scheduler support)', () => {
+    const { result } = renderHook(() =>
+      useToolScheduler(
+        vi.fn().mockResolvedValue(undefined),
+        mockConfig,
+        () => undefined,
+      ),
+    );
+
+    const callRoot = {
+      status: 'success' as const,
+      request: {
+        callId: 'call-root',
+        name: 'test',
+        args: {},
+        isClientInitiated: false,
+        prompt_id: 'p1',
+      },
+      tool: createMockTool(),
+      invocation: createMockInvocation(),
+      response: {
+        callId: 'call-root',
+        responseParts: [],
+        resultDisplay: 'OK',
+        error: undefined,
+        errorType: undefined,
+      },
+      schedulerId: ROOT_SCHEDULER_ID,
+    };
+
+    const callSub = {
+      ...callRoot,
+      request: { ...callRoot.request, callId: 'call-sub' },
+      schedulerId: 'subagent-1',
+    };
+
+    // 1. Populate state with multiple schedulers
+    act(() => {
+      void mockMessageBus.publish({
+        type: MessageBusType.TOOL_CALLS_UPDATE,
+        toolCalls: [callRoot],
+        schedulerId: ROOT_SCHEDULER_ID,
+      } as ToolCallsUpdateMessage);
+
+      void mockMessageBus.publish({
+        type: MessageBusType.TOOL_CALLS_UPDATE,
+        toolCalls: [callSub],
+        schedulerId: 'subagent-1',
+      } as ToolCallsUpdateMessage);
     });
 
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(50);
-      await vi.advanceTimersByTimeAsync(0);
+    let [toolCalls] = result.current;
+    expect(toolCalls).toHaveLength(2);
+    expect(
+      toolCalls.find((t) => t.request.callId === 'call-root')?.schedulerId,
+    ).toBe(ROOT_SCHEDULER_ID);
+    expect(
+      toolCalls.find((t) => t.request.callId === 'call-sub')?.schedulerId,
+    ).toBe('subagent-1');
+
+    // 2. Call setToolCallsForDisplay (e.g., simulate a manual update or clear)
+    act(() => {
+      const [, , , setToolCalls] = result.current;
+      setToolCalls((prev) =>
+        prev.map((t) => ({ ...t, responseSubmittedToGemini: true })),
+      );
     });
 
-    // Wait for first to complete
-    await act(async () => {
-      await schedulePromise1;
+    // 3. Verify that tools are still present and maintain their scheduler IDs
+    // The internal map should have been re-grouped.
+    [toolCalls] = result.current;
+    expect(toolCalls).toHaveLength(2);
+    expect(toolCalls.every((t) => t.responseSubmittedToGemini)).toBe(true);
+
+    const updatedRoot = toolCalls.find((t) => t.request.callId === 'call-root');
+    const updatedSub = toolCalls.find((t) => t.request.callId === 'call-sub');
+
+    expect(updatedRoot?.schedulerId).toBe(ROOT_SCHEDULER_ID);
+    expect(updatedSub?.schedulerId).toBe('subagent-1');
+
+    // 4. Verify that a subsequent update to ONE scheduler doesn't wipe the other
+    act(() => {
+      void mockMessageBus.publish({
+        type: MessageBusType.TOOL_CALLS_UPDATE,
+        toolCalls: [{ ...callRoot, status: 'executing' }],
+        schedulerId: ROOT_SCHEDULER_ID,
+      } as ToolCallsUpdateMessage);
     });
 
-    expect(onComplete).toHaveBeenCalledWith([
-      expect.objectContaining({
-        status: 'success',
-        request: request1,
-        response: expect.objectContaining({ resultDisplay: 'done display' }),
-      }),
-    ]);
-
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(50);
-      await vi.advanceTimersByTimeAsync(0);
-    });
-
-    // Wait for second to complete
-    await act(async () => {
-      await schedulePromise2;
-    });
-
-    expect(onComplete).toHaveBeenCalledWith([
-      expect.objectContaining({
-        status: 'success',
-        request: request2,
-        response: expect.objectContaining({ resultDisplay: 'done display' }),
-      }),
-    ]);
-    const toolCalls = result.current[0];
-    expect(toolCalls).toHaveLength(0);
-  });
-});
-
-describe('mapToDisplay', () => {
-  const baseRequest: ToolCallRequestInfo = {
-    callId: 'testCallId',
-    name: 'testTool',
-    args: { foo: 'bar' },
-  } as any;
-
-  const baseTool = new MockTool({
-    name: 'testTool',
-    displayName: 'Test Tool Display',
-    execute: vi.fn(),
-    shouldConfirmExecute: vi.fn(),
-  });
-
-  const baseResponse: ToolCallResponseInfo = {
-    callId: 'testCallId',
-    responseParts: [
-      {
-        functionResponse: {
-          name: 'testTool',
-          id: 'testCallId',
-          response: { output: 'Test output' },
-        } as FunctionResponse,
-      } as PartUnion,
-    ],
-    resultDisplay: 'Test display output',
-    error: undefined,
-  } as any;
-
-  // Define a more specific type for extraProps for these tests
-  // This helps ensure that tool and confirmationDetails are only accessed when they are expected to exist.
-  type MapToDisplayExtraProps =
-    | {
-        tool?: AnyDeclarativeTool;
-        invocation?: AnyToolInvocation;
-        liveOutput?: string;
-        response?: ToolCallResponseInfo;
-        confirmationDetails?: ToolCallConfirmationDetails;
-      }
-    | {
-        tool: AnyDeclarativeTool;
-        invocation?: AnyToolInvocation;
-        response?: ToolCallResponseInfo;
-        confirmationDetails?: ToolCallConfirmationDetails;
-      }
-    | {
-        response: ToolCallResponseInfo;
-        tool?: undefined;
-        confirmationDetails?: ToolCallConfirmationDetails;
-      }
-    | {
-        confirmationDetails: ToolCallConfirmationDetails;
-        tool?: AnyDeclarativeTool;
-        invocation?: AnyToolInvocation;
-        response?: ToolCallResponseInfo;
-      };
-
-  const baseInvocation = baseTool.build(baseRequest.args);
-  const testCases: Array<{
-    name: string;
-    status: ToolCallStatusType;
-    extraProps?: MapToDisplayExtraProps;
-    expectedStatus: ToolCallStatus;
-    expectedResultDisplay?: string;
-    expectedName?: string;
-    expectedDescription?: string;
-  }> = [
-    {
-      name: 'validating',
-      status: 'validating',
-      extraProps: { tool: baseTool, invocation: baseInvocation },
-      expectedStatus: ToolCallStatus.Pending,
-      expectedName: baseTool.displayName,
-      expectedDescription: baseInvocation.getDescription(),
-    },
-    {
-      name: 'awaiting_approval',
-      status: 'awaiting_approval',
-      extraProps: {
-        tool: baseTool,
-        invocation: baseInvocation,
-        confirmationDetails: {
-          onConfirm: vi.fn(),
-          type: 'edit',
-          title: 'Test Tool Display',
-          serverName: 'testTool',
-          toolName: 'testTool',
-          toolDisplayName: 'Test Tool Display',
-          filePath: 'mock',
-          fileName: 'test.ts',
-          fileDiff: 'Test diff',
-          originalContent: 'Original content',
-          newContent: 'New content',
-        } as ToolCallConfirmationDetails,
-      },
-      expectedStatus: ToolCallStatus.Confirming,
-      expectedName: baseTool.displayName,
-      expectedDescription: baseInvocation.getDescription(),
-    },
-    {
-      name: 'scheduled',
-      status: 'scheduled',
-      extraProps: { tool: baseTool, invocation: baseInvocation },
-      expectedStatus: ToolCallStatus.Pending,
-      expectedName: baseTool.displayName,
-      expectedDescription: baseInvocation.getDescription(),
-    },
-    {
-      name: 'executing no live output',
-      status: 'executing',
-      extraProps: { tool: baseTool, invocation: baseInvocation },
-      expectedStatus: ToolCallStatus.Executing,
-      expectedName: baseTool.displayName,
-      expectedDescription: baseInvocation.getDescription(),
-    },
-    {
-      name: 'executing with live output',
-      status: 'executing',
-      extraProps: {
-        tool: baseTool,
-        invocation: baseInvocation,
-        liveOutput: 'Live test output',
-      },
-      expectedStatus: ToolCallStatus.Executing,
-      expectedResultDisplay: 'Live test output',
-      expectedName: baseTool.displayName,
-      expectedDescription: baseInvocation.getDescription(),
-    },
-    {
-      name: 'success',
-      status: 'success',
-      extraProps: {
-        tool: baseTool,
-        invocation: baseInvocation,
-        response: baseResponse,
-      },
-      expectedStatus: ToolCallStatus.Success,
-      expectedResultDisplay: baseResponse.resultDisplay as any,
-      expectedName: baseTool.displayName,
-      expectedDescription: baseInvocation.getDescription(),
-    },
-    {
-      name: 'error tool not found',
-      status: 'error',
-      extraProps: {
-        response: {
-          ...baseResponse,
-          error: new Error('Test error tool not found'),
-          resultDisplay: 'Error display tool not found',
-        },
-      },
-      expectedStatus: ToolCallStatus.Error,
-      expectedResultDisplay: 'Error display tool not found',
-      expectedName: baseRequest.name,
-      expectedDescription: JSON.stringify(baseRequest.args),
-    },
-    {
-      name: 'error tool execution failed',
-      status: 'error',
-      extraProps: {
-        tool: baseTool,
-        response: {
-          ...baseResponse,
-          error: new Error('Tool execution failed'),
-          resultDisplay: 'Execution failed display',
-        },
-      },
-      expectedStatus: ToolCallStatus.Error,
-      expectedResultDisplay: 'Execution failed display',
-      expectedName: baseTool.displayName, // Changed from baseTool.name
-      expectedDescription: JSON.stringify(baseRequest.args),
-    },
-    {
-      name: 'cancelled',
-      status: 'cancelled',
-      extraProps: {
-        tool: baseTool,
-        invocation: baseInvocation,
-        response: {
-          ...baseResponse,
-          resultDisplay: 'Cancelled display',
-        },
-      },
-      expectedStatus: ToolCallStatus.Canceled,
-      expectedResultDisplay: 'Cancelled display',
-      expectedName: baseTool.displayName,
-      expectedDescription: baseInvocation.getDescription(),
-    },
-  ];
-
-  testCases.forEach(
-    ({
-      name: testName,
-      status,
-      extraProps,
-      expectedStatus,
-      expectedResultDisplay,
-      expectedName,
-      expectedDescription,
-    }) => {
-      it(`should map ToolCall with status '${status}' (${testName}) correctly`, () => {
-        const toolCall: ToolCall = {
-          request: baseRequest,
-          status,
-          ...(extraProps || {}),
-        } as ToolCall;
-
-        const display = mapToDisplay(toolCall);
-        expect(display.type).toBe('tool_group');
-        expect(display.tools.length).toBe(1);
-        const toolDisplay = display.tools[0];
-
-        expect(toolDisplay.callId).toBe(baseRequest.callId);
-        expect(toolDisplay.status).toBe(expectedStatus);
-        expect(toolDisplay.resultDisplay).toBe(expectedResultDisplay);
-
-        expect(toolDisplay.name).toBe(expectedName);
-        expect(toolDisplay.description).toBe(expectedDescription);
-
-        expect(toolDisplay.renderOutputAsMarkdown).toBe(
-          extraProps?.tool?.isOutputMarkdown ?? false,
-        );
-        if (status === 'awaiting_approval') {
-          expect(toolDisplay.confirmationDetails).toBe(
-            extraProps!.confirmationDetails,
-          );
-        } else {
-          expect(toolDisplay.confirmationDetails).toBeUndefined();
-        }
-      });
-    },
-  );
-
-  it('should map an array of ToolCalls correctly', () => {
-    const toolCall1: ToolCall = {
-      request: { ...baseRequest, callId: 'call1' },
-      status: 'success',
-      tool: baseTool,
-      invocation: baseTool.build(baseRequest.args),
-      response: { ...baseResponse, callId: 'call1' },
-    } as ToolCall;
-    const toolForCall2 = new MockTool({
-      name: baseTool.name,
-      displayName: baseTool.displayName,
-      isOutputMarkdown: true,
-      execute: vi.fn(),
-      shouldConfirmExecute: vi.fn(),
-    });
-    const toolCall2: ToolCall = {
-      request: { ...baseRequest, callId: 'call2' },
-      status: 'executing',
-      tool: toolForCall2,
-      invocation: toolForCall2.build(baseRequest.args),
-      liveOutput: 'markdown output',
-    } as ToolCall;
-
-    const display = mapToDisplay([toolCall1, toolCall2]);
-    expect(display.tools.length).toBe(2);
-    expect(display.tools[0].callId).toBe('call1');
-    expect(display.tools[0].status).toBe(ToolCallStatus.Success);
-    expect(display.tools[0].renderOutputAsMarkdown).toBe(false);
-    expect(display.tools[1].callId).toBe('call2');
-    expect(display.tools[1].status).toBe(ToolCallStatus.Executing);
-    expect(display.tools[1].resultDisplay).toBe('markdown output');
-    expect(display.tools[1].renderOutputAsMarkdown).toBe(true);
+    [toolCalls] = result.current;
+    expect(toolCalls).toHaveLength(2);
+    expect(
+      toolCalls.find((t) => t.request.callId === 'call-root')?.status,
+    ).toBe('executing');
+    expect(
+      toolCalls.find((t) => t.request.callId === 'call-sub')?.schedulerId,
+    ).toBe('subagent-1');
   });
 });
diff --git a/packages/cli/src/ui/hooks/useToolScheduler.ts b/packages/cli/src/ui/hooks/useToolScheduler.ts
index b6835565e7..b50ed1b717 100644
--- a/packages/cli/src/ui/hooks/useToolScheduler.ts
+++ b/packages/cli/src/ui/hooks/useToolScheduler.ts
@@ -4,67 +4,273 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type {
-  Config,
-  EditorType,
-  CompletedToolCall,
-  ToolCallRequestInfo,
+import {
+  type Config,
+  type MessageBus,
+  type ToolCallRequestInfo,
+  type ToolCall,
+  type CompletedToolCall,
+  type ToolConfirmationPayload,
+  MessageBusType,
+  ToolConfirmationOutcome,
+  Scheduler,
+  type EditorType,
+  type ToolCallsUpdateMessage,
+  ROOT_SCHEDULER_ID,
 } from '@google/gemini-cli-core';
-import {
-  type TrackedScheduledToolCall,
-  type TrackedValidatingToolCall,
-  type TrackedWaitingToolCall,
-  type TrackedExecutingToolCall,
-  type TrackedCompletedToolCall,
-  type TrackedCancelledToolCall,
-  type MarkToolsAsSubmittedFn,
-  type CancelAllFn,
-} from './useReactToolScheduler.js';
-import {
-  useToolExecutionScheduler,
-  type TrackedToolCall,
-} from './useToolExecutionScheduler.js';
+import { useCallback, useState, useMemo, useEffect, useRef } from 'react';
 
-// Re-export specific state types from Legacy, as the structures are compatible
-// and useGeminiStream relies on them for narrowing.
-export type {
-  TrackedToolCall,
-  TrackedScheduledToolCall,
-  TrackedValidatingToolCall,
-  TrackedWaitingToolCall,
-  TrackedExecutingToolCall,
-  TrackedCompletedToolCall,
-  TrackedCancelledToolCall,
-  MarkToolsAsSubmittedFn,
-  CancelAllFn,
-};
-
-// Unified Schedule function (Promise<void> | Promise<CompletedToolCall[]>)
+// Re-exporting types compatible with legacy hook expectations
 export type ScheduleFn = (
   request: ToolCallRequestInfo | ToolCallRequestInfo[],
   signal: AbortSignal,
-) => Promise<void | CompletedToolCall[]>;
+) => Promise<CompletedToolCall[]>;
 
-export type UseToolSchedulerReturn = [
+export type MarkToolsAsSubmittedFn = (callIds: string[]) => void;
+export type CancelAllFn = (signal: AbortSignal) => void;
+
+/**
+ * The shape expected by useGeminiStream.
+ * It matches the Core ToolCall structure + the UI metadata flag.
+ */
+export type TrackedToolCall = ToolCall & {
+  responseSubmittedToGemini?: boolean;
+};
+
+// Narrowed types for specific statuses (used by useGeminiStream)
+export type TrackedScheduledToolCall = Extract<
+  TrackedToolCall,
+  { status: 'scheduled' }
+>;
+export type TrackedValidatingToolCall = Extract<
+  TrackedToolCall,
+  { status: 'validating' }
+>;
+export type TrackedWaitingToolCall = Extract<
+  TrackedToolCall,
+  { status: 'awaiting_approval' }
+>;
+export type TrackedExecutingToolCall = Extract<
+  TrackedToolCall,
+  { status: 'executing' }
+>;
+export type TrackedCompletedToolCall = Extract<
+  TrackedToolCall,
+  { status: 'success' | 'error' }
+>;
+export type TrackedCancelledToolCall = Extract<
+  TrackedToolCall,
+  { status: 'cancelled' }
+>;
+
+/**
+ * Modern tool scheduler hook using the event-driven Core Scheduler.
+ */
+export function useToolScheduler(
+  onComplete: (tools: CompletedToolCall[]) => Promise<void>,
+  config: Config,
+  getPreferredEditor: () => EditorType | undefined,
+): [
   TrackedToolCall[],
   ScheduleFn,
   MarkToolsAsSubmittedFn,
   React.Dispatch<React.SetStateAction<TrackedToolCall[]>>,
   CancelAllFn,
   number,
-];
+] {
+  // State stores tool calls organized by their originating schedulerId
+  const [toolCallsMap, setToolCallsMap] = useState<
+    Record<string, TrackedToolCall[]>
+  >({});
+  const [lastToolOutputTime, setLastToolOutputTime] = useState<number>(0);
+
+  const messageBus = useMemo(() => config.getMessageBus(), [config]);
+
+  const onCompleteRef = useRef(onComplete);
+  useEffect(() => {
+    onCompleteRef.current = onComplete;
+  }, [onComplete]);
+
+  const getPreferredEditorRef = useRef(getPreferredEditor);
+  useEffect(() => {
+    getPreferredEditorRef.current = getPreferredEditor;
+  }, [getPreferredEditor]);
+
+  const scheduler = useMemo(
+    () =>
+      new Scheduler({
+        config,
+        messageBus,
+        getPreferredEditor: () => getPreferredEditorRef.current(),
+        schedulerId: ROOT_SCHEDULER_ID,
+      }),
+    [config, messageBus],
+  );
+
+  const internalAdaptToolCalls = useCallback(
+    (coreCalls: ToolCall[], prevTracked: TrackedToolCall[]) =>
+      adaptToolCalls(coreCalls, prevTracked, messageBus),
+    [messageBus],
+  );
+
+  useEffect(() => {
+    const handler = (event: ToolCallsUpdateMessage) => {
+      // Update output timer for UI spinners (Side Effect)
+      if (event.toolCalls.some((tc) => tc.status === 'executing')) {
+        setLastToolOutputTime(Date.now());
+      }
+
+      setToolCallsMap((prev) => {
+        const adapted = internalAdaptToolCalls(
+          event.toolCalls,
+          prev[event.schedulerId] ?? [],
+        );
+
+        return {
+          ...prev,
+          [event.schedulerId]: adapted,
+        };
+      });
+    };
+
+    messageBus.subscribe(MessageBusType.TOOL_CALLS_UPDATE, handler);
+    return () => {
+      messageBus.unsubscribe(MessageBusType.TOOL_CALLS_UPDATE, handler);
+    };
+  }, [messageBus, internalAdaptToolCalls]);
+
+  const schedule: ScheduleFn = useCallback(
+    async (request, signal) => {
+      // Clear state for new run
+      setToolCallsMap({});
+
+      // 1. Await Core Scheduler directly
+      const results = await scheduler.schedule(request, signal);
+
+      // 2. Trigger legacy reinjection logic (useGeminiStream loop)
+      // Since this hook instance owns the "root" scheduler, we always trigger
+      // onComplete when it finishes its batch.
+      await onCompleteRef.current(results);
+
+      return results;
+    },
+    [scheduler],
+  );
+
+  const cancelAll: CancelAllFn = useCallback(
+    (_signal) => {
+      scheduler.cancelAll();
+    },
+    [scheduler],
+  );
+
+  const markToolsAsSubmitted: MarkToolsAsSubmittedFn = useCallback(
+    (callIdsToMark: string[]) => {
+      setToolCallsMap((prevMap) => {
+        const nextMap = { ...prevMap };
+        for (const [sid, calls] of Object.entries(nextMap)) {
+          nextMap[sid] = calls.map((tc) =>
+            callIdsToMark.includes(tc.request.callId)
+              ? { ...tc, responseSubmittedToGemini: true }
+              : tc,
+          );
+        }
+        return nextMap;
+      });
+    },
+    [],
+  );
+
+  // Flatten the map for the UI components that expect a single list of tools.
+  const toolCalls = useMemo(
+    () => Object.values(toolCallsMap).flat(),
+    [toolCallsMap],
+  );
+
+  // Provide a setter that maintains compatibility with legacy [].
+  const setToolCallsForDisplay = useCallback(
+    (action: React.SetStateAction<TrackedToolCall[]>) => {
+      setToolCallsMap((prev) => {
+        const currentFlattened = Object.values(prev).flat();
+        const nextFlattened =
+          typeof action === 'function' ? action(currentFlattened) : action;
+
+        if (nextFlattened.length === 0) {
+          return {};
+        }
+
+        // Re-group by schedulerId to preserve multi-scheduler state
+        const nextMap: Record<string, TrackedToolCall[]> = {};
+        for (const call of nextFlattened) {
+          // All tool calls should have a schedulerId from the core.
+          // Default to ROOT_SCHEDULER_ID as a safeguard.
+          const sid = call.schedulerId ?? ROOT_SCHEDULER_ID;
+          if (!nextMap[sid]) {
+            nextMap[sid] = [];
+          }
+          nextMap[sid].push(call);
+        }
+        return nextMap;
+      });
+    },
+    [],
+  );
+
+  return [
+    toolCalls,
+    schedule,
+    markToolsAsSubmitted,
+    setToolCallsForDisplay,
+    cancelAll,
+    lastToolOutputTime,
+  ];
+}
 
 /**
- * Hook that uses the Event-Driven scheduler for tool execution.
+ * ADAPTER: Merges UI metadata (submitted flag) and injects legacy callbacks.
  */
-export function useToolScheduler(
-  onComplete: (tools: CompletedToolCall[]) => Promise<void>,
-  config: Config,
-  getPreferredEditor: () => EditorType | undefined,
-): UseToolSchedulerReturn {
-  return useToolExecutionScheduler(
-    onComplete,
-    config,
-    getPreferredEditor,
-  ) as UseToolSchedulerReturn;
+function adaptToolCalls(
+  coreCalls: ToolCall[],
+  prevTracked: TrackedToolCall[],
+  messageBus: MessageBus,
+): TrackedToolCall[] {
+  const prevMap = new Map(prevTracked.map((t) => [t.request.callId, t]));
+
+  return coreCalls.map((coreCall): TrackedToolCall => {
+    const prev = prevMap.get(coreCall.request.callId);
+    const responseSubmittedToGemini = prev?.responseSubmittedToGemini ?? false;
+
+    // Inject onConfirm adapter for tools awaiting approval.
+    // The Core provides data-only (serializable) confirmationDetails. We must
+    // inject the legacy callback function that proxies responses back to the
+    // MessageBus.
+    if (coreCall.status === 'awaiting_approval' && coreCall.correlationId) {
+      const correlationId = coreCall.correlationId;
+      return {
+        ...coreCall,
+        confirmationDetails: {
+          ...coreCall.confirmationDetails,
+          onConfirm: async (
+            outcome: ToolConfirmationOutcome,
+            payload?: ToolConfirmationPayload,
+          ) => {
+            await messageBus.publish({
+              type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+              correlationId,
+              confirmed: outcome !== ToolConfirmationOutcome.Cancel,
+              requiresUserConfirmation: false,
+              outcome,
+              payload,
+            });
+          },
+        },
+        responseSubmittedToGemini,
+      };
+    }
+
+    return {
+      ...coreCall,
+      responseSubmittedToGemini,
+    };
+  });
 }
diff --git a/packages/cli/src/ui/hooks/useTurnActivityMonitor.test.ts b/packages/cli/src/ui/hooks/useTurnActivityMonitor.test.ts
index 9ac44c3ebc..f77ab7504d 100644
--- a/packages/cli/src/ui/hooks/useTurnActivityMonitor.test.ts
+++ b/packages/cli/src/ui/hooks/useTurnActivityMonitor.test.ts
@@ -9,7 +9,7 @@ import { renderHook } from '../../test-utils/render.js';
 import { useTurnActivityMonitor } from './useTurnActivityMonitor.js';
 import { StreamingState } from '../types.js';
 import { hasRedirection } from '@google/gemini-cli-core';
-import { type TrackedToolCall } from './useReactToolScheduler.js';
+import { type TrackedToolCall } from './useToolScheduler.js';
 
 vi.mock('@google/gemini-cli-core', async (importOriginal) => {
   const actual = await importOriginal<Record<string, unknown>>();
diff --git a/packages/cli/src/ui/hooks/useTurnActivityMonitor.ts b/packages/cli/src/ui/hooks/useTurnActivityMonitor.ts
index cd6ee7ee8a..8cd7883007 100644
--- a/packages/cli/src/ui/hooks/useTurnActivityMonitor.ts
+++ b/packages/cli/src/ui/hooks/useTurnActivityMonitor.ts
@@ -7,7 +7,7 @@
 import { useState, useEffect, useRef, useMemo } from 'react';
 import { StreamingState } from '../types.js';
 import { hasRedirection } from '@google/gemini-cli-core';
-import { type TrackedToolCall } from './useReactToolScheduler.js';
+import { type TrackedToolCall } from './useToolScheduler.js';
 
 export interface TurnActivityStatus {
   operationStartTime: number;

From fe75de3efb8d0e1c2a72e9a1edec2a1177f574b9 Mon Sep 17 00:00:00 2001
From: g-samroberts <158088236+g-samroberts@users.noreply.github.com>
Date: Wed, 11 Feb 2026 18:03:00 -0800
Subject: [PATCH 14/44] Update changelog for v0.28.0 and v0.29.0-preview0
 (#18819)

---
 docs/changelogs/index.md   |  20 +
 docs/changelogs/latest.md  | 722 +++++++++++++++----------------------
 docs/changelogs/preview.md | 628 +++++++++++++++++---------------
 3 files changed, 659 insertions(+), 711 deletions(-)

diff --git a/docs/changelogs/index.md b/docs/changelogs/index.md
index 98e290c30d..013ee3281c 100644
--- a/docs/changelogs/index.md
+++ b/docs/changelogs/index.md
@@ -18,6 +18,26 @@ on GitHub.
 | [Preview](preview.md) | Experimental features ready for early feedback. |
 | [Stable](latest.md)   | Stable, recommended for general use.            |
 
+## Announcements: v0.28.0 - 2026-02-03
+
+- **Slash Command:** We've added a new `/prompt-suggest` slash command to help
+  you generate prompt suggestions
+  ([#17264](https://github.com/google-gemini/gemini-cli/pull/17264) by
+  @NTaylorMullen).
+- **IDE Support:** Gemini CLI now supports the Positron IDE
+  ([#15047](https://github.com/google-gemini/gemini-cli/pull/15047) by
+  @kapsner).
+- **Customization:** You can now use custom themes in extensions, and we've
+  implemented automatic theme switching based on your terminal's background
+  ([#17327](https://github.com/google-gemini/gemini-cli/pull/17327) by
+  @spencer426, [#17976](https://github.com/google-gemini/gemini-cli/pull/17976)
+  by @Abhijit-2592).
+- **Authentication:** We've added interactive and non-interactive consent for
+  OAuth, and you can now include your auth method in bug reports
+  ([#17699](https://github.com/google-gemini/gemini-cli/pull/17699) by
+  @ehedlund, [#17569](https://github.com/google-gemini/gemini-cli/pull/17569) by
+  @erikus).
+
 ## Announcements: v0.27.0 - 2026-02-03
 
 - **Event-Driven Architecture:** The CLI now uses a new event-driven scheduler
diff --git a/docs/changelogs/latest.md b/docs/changelogs/latest.md
index ce0a0fdfff..6ba7b88e1c 100644
--- a/docs/changelogs/latest.md
+++ b/docs/changelogs/latest.md
@@ -1,6 +1,6 @@
-# Latest stable release: v0.27.0
+# Latest stable release: v0.28.0
 
-Released: February 3, 2026
+Released: February 10, 2026
 
 For most users, our latest stable release is the recommended release. Install
 the latest stable version with:
@@ -11,437 +11,305 @@ npm install -g @google/gemini-cli
 
 ## Highlights
 
-- **Event-Driven Architecture:** The CLI now uses an event-driven scheduler for
-  tool execution, improving performance and responsiveness. This includes
-  migrating non-interactive flows and sub-agents to the new scheduler.
-- **Enhanced User Experience:** This release introduces several UI/UX
-  improvements, including queued tool confirmations and the ability to expand
-  and collapse large pasted text blocks. The `Settings` dialog has been improved
-  to reduce jitter and preserve focus.
-- **Agent and Skill Improvements:** Agent Skills have been promoted to a stable
-  feature. Sub-agents now use a JSON schema for input and are tracked by an
-  `AgentRegistry`.
-- **New `/rewind` Command:** A new `/rewind` command has been implemented to
-  allow users to go back in their session history.
-- **Improved Shell and File Handling:** The shell tool's output format has been
-  optimized, and the CLI now gracefully handles disk-full errors during chat
-  recording. A bug in detecting already added paths has been fixed.
-- **Linux Clipboard Support:** Image pasting capabilities for Wayland and X11 on
-  Linux have been added.
+- **Commands & UX Enhancements:** Introduced `/prompt-suggest` command,
+  alongside updated undo/redo keybindings and automatic theme switching.
+- **Expanded IDE Support:** Now offering compatibility with Positron IDE,
+  expanding integration options for developers.
+- **Enhanced Security & Authentication:** Implemented interactive and
+  non-interactive OAuth consent, improving both security and diagnostic
+  capabilities for bug reports.
+- **Advanced Planning & Agent Tools:** Integrated a generic Checklist component
+  for structured task management and evolved subagent capabilities with dynamic
+  policy registration.
+- **Improved Core Stability & Reliability:** Resolved critical environment
+  loading, authentication, and session management issues, ensuring a more robust
+  experience.
+- **Background Shell Commands:** Enabled the execution of shell commands in the
+  background for increased workflow efficiency.
 
 ## What's Changed
 
-- remove fireAgent and beforeAgent hook by @ishaanxgupta in
-  [#16919](https://github.com/google-gemini/gemini-cli/pull/16919)
-- Remove unused modelHooks and toolHooks by @ved015 in
-  [#17115](https://github.com/google-gemini/gemini-cli/pull/17115)
-- feat(cli): sanitize ANSI escape sequences in non-interactive output by
-  @sehoon38 in [#17172](https://github.com/google-gemini/gemini-cli/pull/17172)
-- Update Attempt text to Retry when showing the retry happening to the … by
-  @sehoon38 in [#17178](https://github.com/google-gemini/gemini-cli/pull/17178)
-- chore(skills): update pr-creator skill workflow by @sehoon38 in
-  [#17180](https://github.com/google-gemini/gemini-cli/pull/17180)
-- feat(cli): implement event-driven tool execution scheduler by @abhipatel12 in
-  [#17078](https://github.com/google-gemini/gemini-cli/pull/17078)
-- chore(release): bump version to 0.27.0-nightly.20260121.97aac696f by
+- feat(commands): add /prompt-suggest slash command by @NTaylorMullen in
+  [#17264](https://github.com/google-gemini/gemini-cli/pull/17264)
+- feat(cli): align hooks enable/disable with skills and improve completion by
+  @sehoon38 in [#16822](https://github.com/google-gemini/gemini-cli/pull/16822)
+- docs: add CLI reference documentation by @leochiu-a in
+  [#17504](https://github.com/google-gemini/gemini-cli/pull/17504)
+- chore(release): bump version to 0.28.0-nightly.20260128.adc8e11bb by
   @gemini-cli-robot in
-  [#17181](https://github.com/google-gemini/gemini-cli/pull/17181)
-- Remove other rewind reference in docs by @chrstnb in
-  [#17149](https://github.com/google-gemini/gemini-cli/pull/17149)
-- feat(skills): add code-reviewer skill by @sehoon38 in
-  [#17187](https://github.com/google-gemini/gemini-cli/pull/17187)
-- feat(plan): Extend Shift+Tab Mode Cycling to include Plan Mode by @Adib234 in
-  [#17177](https://github.com/google-gemini/gemini-cli/pull/17177)
-- feat(plan): refactor TestRig and eval helper to support configurable approval
-  modes by @jerop in
-  [#17171](https://github.com/google-gemini/gemini-cli/pull/17171)
-- feat(workflows): support recursive workstream labeling and new IDs by
-  @bdmorgan in [#17207](https://github.com/google-gemini/gemini-cli/pull/17207)
-- Run evals for all models. by @gundermanc in
-  [#17123](https://github.com/google-gemini/gemini-cli/pull/17123)
-- fix(github): improve label-workstream-rollup efficiency with GraphQL by
-  @bdmorgan in [#17217](https://github.com/google-gemini/gemini-cli/pull/17217)
-- Docs: Update changelogs for v.0.25.0 and v0.26.0-preview.0 releases. by
-  @g-samroberts in
-  [#17215](https://github.com/google-gemini/gemini-cli/pull/17215)
-- Migrate beforeTool and afterTool hooks to hookSystem by @ved015 in
-  [#17204](https://github.com/google-gemini/gemini-cli/pull/17204)
-- fix(github): improve label-workstream-rollup efficiency and fix bugs by
-  @bdmorgan in [#17219](https://github.com/google-gemini/gemini-cli/pull/17219)
-- feat(cli): improve skill enablement/disablement verbiage by @NTaylorMullen in
-  [#17192](https://github.com/google-gemini/gemini-cli/pull/17192)
-- fix(admin): Ensure CLI commands run in non-interactive mode by @skeshive in
-  [#17218](https://github.com/google-gemini/gemini-cli/pull/17218)
-- feat(core): support dynamic variable substitution in system prompt override by
-  @NTaylorMullen in
-  [#17042](https://github.com/google-gemini/gemini-cli/pull/17042)
-- fix(core,cli): enable recursive directory access for by @galz10 in
-  [#17094](https://github.com/google-gemini/gemini-cli/pull/17094)
-- Docs: Marking for experimental features by @jkcinouye in
-  [#16760](https://github.com/google-gemini/gemini-cli/pull/16760)
-- Support command/ctrl/alt backspace correctly by @scidomino in
-  [#17175](https://github.com/google-gemini/gemini-cli/pull/17175)
-- feat(plan): add approval mode instructions to system prompt by @jerop in
-  [#17151](https://github.com/google-gemini/gemini-cli/pull/17151)
-- feat(core): enable disableLLMCorrection by default by @SandyTao520 in
-  [#17223](https://github.com/google-gemini/gemini-cli/pull/17223)
-- Remove unused slug from sidebar by @chrstnb in
-  [#17229](https://github.com/google-gemini/gemini-cli/pull/17229)
-- drain stdin on exit by @scidomino in
-  [#17241](https://github.com/google-gemini/gemini-cli/pull/17241)
-- refactor(cli): decouple UI from live tool execution via ToolActionsContext by
+  [#17725](https://github.com/google-gemini/gemini-cli/pull/17725)
+- feat(skills): final stable promotion cleanup by @abhipatel12 in
+  [#17726](https://github.com/google-gemini/gemini-cli/pull/17726)
+- test(core): mock fetch in OAuth transport fallback tests by @jw409 in
+  [#17059](https://github.com/google-gemini/gemini-cli/pull/17059)
+- feat(cli): include auth method in /bug by @erikus in
+  [#17569](https://github.com/google-gemini/gemini-cli/pull/17569)
+- Add a email privacy note to bug_report template by @nemyung in
+  [#17474](https://github.com/google-gemini/gemini-cli/pull/17474)
+- Rewind documentation by @Adib234 in
+  [#17446](https://github.com/google-gemini/gemini-cli/pull/17446)
+- fix: verify audio/video MIME types with content check by @maru0804 in
+  [#16907](https://github.com/google-gemini/gemini-cli/pull/16907)
+- feat(core): add support for positron ide
+  ([#15045](https://github.com/google-gemini/gemini-cli/pull/15045)) by @kapsner
+  in [#15047](https://github.com/google-gemini/gemini-cli/pull/15047)
+- /oncall dedup - wrap texts to nextlines by @sehoon38 in
+  [#17782](https://github.com/google-gemini/gemini-cli/pull/17782)
+- fix(admin): rename advanced features admin setting by @skeshive in
+  [#17786](https://github.com/google-gemini/gemini-cli/pull/17786)
+- [extension config] Make breaking optional value non-optional by @chrstnb in
+  [#17785](https://github.com/google-gemini/gemini-cli/pull/17785)
+- Fix docs-writer skill issues by @g-samroberts in
+  [#17734](https://github.com/google-gemini/gemini-cli/pull/17734)
+- fix(core): suppress duplicate hook failure warnings during streaming by
   @abhipatel12 in
-  [#17183](https://github.com/google-gemini/gemini-cli/pull/17183)
-- fix(core): update token count and telemetry on /chat resume history load by
-  @psinha40898 in
-  [#16279](https://github.com/google-gemini/gemini-cli/pull/16279)
-- fix: /policy to display policies according to mode by @ishaanxgupta in
-  [#16772](https://github.com/google-gemini/gemini-cli/pull/16772)
-- fix(core): simplify replace tool error message by @SandyTao520 in
-  [#17246](https://github.com/google-gemini/gemini-cli/pull/17246)
-- feat(cli): consolidate shell inactivity and redirection monitoring by
-  @NTaylorMullen in
-  [#17086](https://github.com/google-gemini/gemini-cli/pull/17086)
-- fix(scheduler): prevent stale tool re-publication and fix stuck UI state by
+  [#17727](https://github.com/google-gemini/gemini-cli/pull/17727)
+- test: add more tests for AskUser by @jackwotherspoon in
+  [#17720](https://github.com/google-gemini/gemini-cli/pull/17720)
+- feat(cli): enable activity logging for non-interactive mode and evals by
+  @SandyTao520 in
+  [#17703](https://github.com/google-gemini/gemini-cli/pull/17703)
+- feat(core): add support for custom deny messages in policy rules by
+  @allenhutchison in
+  [#17427](https://github.com/google-gemini/gemini-cli/pull/17427)
+- Fix unintended credential exposure to MCP Servers by @Adib234 in
+  [#17311](https://github.com/google-gemini/gemini-cli/pull/17311)
+- feat(extensions): add support for custom themes in extensions by @spencer426
+  in [#17327](https://github.com/google-gemini/gemini-cli/pull/17327)
+- fix: persist and restore workspace directories on session resume by
+  @korade-krushna in
+  [#17454](https://github.com/google-gemini/gemini-cli/pull/17454)
+- Update release notes pages for 0.26.0 and 0.27.0-preview. by @g-samroberts in
+  [#17744](https://github.com/google-gemini/gemini-cli/pull/17744)
+- feat(ux): update cell border color and created test file for table rendering
+  by @devr0306 in
+  [#17798](https://github.com/google-gemini/gemini-cli/pull/17798)
+- Change height for the ToolConfirmationQueue. by @jacob314 in
+  [#17799](https://github.com/google-gemini/gemini-cli/pull/17799)
+- feat(cli): add user identity info to stats command by @sehoon38 in
+  [#17612](https://github.com/google-gemini/gemini-cli/pull/17612)
+- fix(ux): fixed off-by-some wrapping caused by fixed-width characters by
+  @devr0306 in [#17816](https://github.com/google-gemini/gemini-cli/pull/17816)
+- feat(cli): update undo/redo keybindings to Cmd+Z/Alt+Z and
+  Shift+Cmd+Z/Shift+Alt+Z by @scidomino in
+  [#17800](https://github.com/google-gemini/gemini-cli/pull/17800)
+- fix(evals): use absolute path for activity log directory by @SandyTao520 in
+  [#17830](https://github.com/google-gemini/gemini-cli/pull/17830)
+- test: add integration test to verify stdout/stderr routing by @ved015 in
+  [#17280](https://github.com/google-gemini/gemini-cli/pull/17280)
+- fix(cli): list installed extensions when update target missing by @tt-a1i in
+  [#17082](https://github.com/google-gemini/gemini-cli/pull/17082)
+- fix(cli): handle PAT tokens and credentials in git remote URL parsing by
+  @afarber in [#14650](https://github.com/google-gemini/gemini-cli/pull/14650)
+- fix(core): use returnDisplay for error result display by @Nubebuster in
+  [#14994](https://github.com/google-gemini/gemini-cli/pull/14994)
+- Fix detection of bun as package manager by @Randomblock1 in
+  [#17462](https://github.com/google-gemini/gemini-cli/pull/17462)
+- feat(cli): show hooksConfig.enabled in settings dialog by @abhipatel12 in
+  [#17810](https://github.com/google-gemini/gemini-cli/pull/17810)
+- feat(cli): Display user identity (auth, email, tier) on startup by @yunaseoul
+  in [#17591](https://github.com/google-gemini/gemini-cli/pull/17591)
+- fix: prevent ghost border for AskUserDialog by @jackwotherspoon in
+  [#17788](https://github.com/google-gemini/gemini-cli/pull/17788)
+- docs: mark A2A subagents as experimental in subagents.md by @adamfweidman in
+  [#17863](https://github.com/google-gemini/gemini-cli/pull/17863)
+- Resolve error thrown for sensitive values by @chrstnb in
+  [#17826](https://github.com/google-gemini/gemini-cli/pull/17826)
+- fix(admin): Rename secureModeEnabled to strictModeDisabled by @skeshive in
+  [#17789](https://github.com/google-gemini/gemini-cli/pull/17789)
+- feat(ux): update truncate dots to be shorter in tables by @devr0306 in
+  [#17825](https://github.com/google-gemini/gemini-cli/pull/17825)
+- fix(core): resolve DEP0040 punycode deprecation via patch-package by
+  @ATHARVA262005 in
+  [#17692](https://github.com/google-gemini/gemini-cli/pull/17692)
+- feat(plan): create generic Checklist component and refactor Todo by @Adib234
+  in [#17741](https://github.com/google-gemini/gemini-cli/pull/17741)
+- Cleanup post delegate_to_agent removal by @gundermanc in
+  [#17875](https://github.com/google-gemini/gemini-cli/pull/17875)
+- fix(core): use GIT_CONFIG_GLOBAL to isolate shadow git repo configuration -
+  Fixes [#17877](https://github.com/google-gemini/gemini-cli/pull/17877) by
+  @cocosheng-g in
+  [#17803](https://github.com/google-gemini/gemini-cli/pull/17803)
+- Disable mouse tracking e2e by @alisa-alisa in
+  [#17880](https://github.com/google-gemini/gemini-cli/pull/17880)
+- fix(cli): use correct setting key for Cloud Shell auth by @sehoon38 in
+  [#17884](https://github.com/google-gemini/gemini-cli/pull/17884)
+- chore: revert IDE specific ASCII logo by @jackwotherspoon in
+  [#17887](https://github.com/google-gemini/gemini-cli/pull/17887)
+- Revert "fix(core): resolve DEP0040 punycode deprecation via patch-package" by
+  @sehoon38 in [#17898](https://github.com/google-gemini/gemini-cli/pull/17898)
+- Refactoring of disabling of mouse tracking in e2e tests by @alisa-alisa in
+  [#17902](https://github.com/google-gemini/gemini-cli/pull/17902)
+- feat(core): Add GOOGLE_GENAI_API_VERSION environment variable support by
+  @deyim in [#16177](https://github.com/google-gemini/gemini-cli/pull/16177)
+- feat(core): Isolate and cleanup truncated tool outputs by @SandyTao520 in
+  [#17594](https://github.com/google-gemini/gemini-cli/pull/17594)
+- Create skills page, update commands, refine docs by @g-samroberts in
+  [#17842](https://github.com/google-gemini/gemini-cli/pull/17842)
+- feat: preserve EOL in files by @Thomas-Shephard in
+  [#16087](https://github.com/google-gemini/gemini-cli/pull/16087)
+- Fix HalfLinePaddedBox in screenreader mode. by @jacob314 in
+  [#17914](https://github.com/google-gemini/gemini-cli/pull/17914)
+- bug(ux) vim mode fixes. Start in insert mode. Fix bug blocking F12 and ctrl-X
+  in vim mode. by @jacob314 in
+  [#17938](https://github.com/google-gemini/gemini-cli/pull/17938)
+- feat(core): implement interactive and non-interactive consent for OAuth by
+  @ehedlund in [#17699](https://github.com/google-gemini/gemini-cli/pull/17699)
+- perf(core): optimize token calculation and add support for multimodal tool
+  responses by @abhipatel12 in
+  [#17835](https://github.com/google-gemini/gemini-cli/pull/17835)
+- refactor(hooks): remove legacy tools.enableHooks setting by @abhipatel12 in
+  [#17867](https://github.com/google-gemini/gemini-cli/pull/17867)
+- feat(ci): add npx smoke test to verify installability by @bdmorgan in
+  [#17927](https://github.com/google-gemini/gemini-cli/pull/17927)
+- feat(core): implement dynamic policy registration for subagents by
   @abhipatel12 in
-  [#17227](https://github.com/google-gemini/gemini-cli/pull/17227)
-- feat(config): default enableEventDrivenScheduler to true by @abhipatel12 in
-  [#17211](https://github.com/google-gemini/gemini-cli/pull/17211)
-- feat(hooks): enable hooks system by default by @abhipatel12 in
-  [#17247](https://github.com/google-gemini/gemini-cli/pull/17247)
-- feat(core): Enable AgentRegistry to track all discovered subagents by
+  [#17838](https://github.com/google-gemini/gemini-cli/pull/17838)
+- feat: Implement background shell commands by @galz10 in
+  [#14849](https://github.com/google-gemini/gemini-cli/pull/14849)
+- feat(admin): provide actionable error messages for disabled features by
+  @skeshive in [#17815](https://github.com/google-gemini/gemini-cli/pull/17815)
+- Fix bugs where Rewind and Resume showed Ugly and 100X too verbose content. by
+  @jacob314 in [#17940](https://github.com/google-gemini/gemini-cli/pull/17940)
+- Fix broken link in docs by @chrstnb in
+  [#17959](https://github.com/google-gemini/gemini-cli/pull/17959)
+- feat(plan): reuse standard tool confirmation for AskUser tool by @jerop in
+  [#17864](https://github.com/google-gemini/gemini-cli/pull/17864)
+- feat(core): enable overriding CODE_ASSIST_API_VERSION with env var by
+  @lottielin in [#17942](https://github.com/google-gemini/gemini-cli/pull/17942)
+- run npx pointing to the specific commit SHA by @sehoon38 in
+  [#17970](https://github.com/google-gemini/gemini-cli/pull/17970)
+- Add allowedExtensions setting by @kevinjwang1 in
+  [#17695](https://github.com/google-gemini/gemini-cli/pull/17695)
+- feat(plan): refactor ToolConfirmationPayload to union type by @jerop in
+  [#17980](https://github.com/google-gemini/gemini-cli/pull/17980)
+- lower the default max retries to reduce contention by @sehoon38 in
+  [#17975](https://github.com/google-gemini/gemini-cli/pull/17975)
+- fix(core): ensure YOLO mode auto-approves complex shell commands when parsing
+  fails by @abhipatel12 in
+  [#17920](https://github.com/google-gemini/gemini-cli/pull/17920)
+- Fix broken link. by @g-samroberts in
+  [#17972](https://github.com/google-gemini/gemini-cli/pull/17972)
+- Support ctrl-C and Ctrl-D correctly Refactor so InputPrompt has priority over
+  AppContainer for input handling. by @jacob314 in
+  [#17993](https://github.com/google-gemini/gemini-cli/pull/17993)
+- Fix truncation for AskQuestion by @jacob314 in
+  [#18001](https://github.com/google-gemini/gemini-cli/pull/18001)
+- fix(workflow): update maintainer check logic to be inclusive and
+  case-insensitive by @bdmorgan in
+  [#18009](https://github.com/google-gemini/gemini-cli/pull/18009)
+- Fix Esc cancel during streaming by @LyalinDotCom in
+  [#18039](https://github.com/google-gemini/gemini-cli/pull/18039)
+- feat(acp): add session resume support by @bdmorgan in
+  [#18043](https://github.com/google-gemini/gemini-cli/pull/18043)
+- fix(ci): prevent stale PR closer from incorrectly closing new PRs by @bdmorgan
+  in [#18069](https://github.com/google-gemini/gemini-cli/pull/18069)
+- chore: delete autoAccept setting unused in production by @victorvianna in
+  [#17862](https://github.com/google-gemini/gemini-cli/pull/17862)
+- feat(plan): use placeholder for choice question "Other" option by @jerop in
+  [#18101](https://github.com/google-gemini/gemini-cli/pull/18101)
+- docs: update clearContext to hookSpecificOutput by @jackwotherspoon in
+  [#18024](https://github.com/google-gemini/gemini-cli/pull/18024)
+- docs-writer skill: Update docs writer skill by @jkcinouye in
+  [#17928](https://github.com/google-gemini/gemini-cli/pull/17928)
+- Sehoon/oncall filter by @sehoon38 in
+  [#18105](https://github.com/google-gemini/gemini-cli/pull/18105)
+- feat(core): add setting to disable loop detection by @SandyTao520 in
+  [#18008](https://github.com/google-gemini/gemini-cli/pull/18008)
+- Docs: Revise docs/index.md by @jkcinouye in
+  [#17879](https://github.com/google-gemini/gemini-cli/pull/17879)
+- Fix up/down arrow regression and add test. by @jacob314 in
+  [#18108](https://github.com/google-gemini/gemini-cli/pull/18108)
+- fix(ui): prevent content leak in MaxSizedBox bottom overflow by @jerop in
+  [#17991](https://github.com/google-gemini/gemini-cli/pull/17991)
+- refactor: migrate checks.ts utility to core and deduplicate by @jerop in
+  [#18139](https://github.com/google-gemini/gemini-cli/pull/18139)
+- feat(core): implement tool name aliasing for backward compatibility by
   @SandyTao520 in
-  [#17253](https://github.com/google-gemini/gemini-cli/pull/17253)
-- feat(core): Have subagents use a JSON schema type for input. by @joshualitt in
-  [#17152](https://github.com/google-gemini/gemini-cli/pull/17152)
-- feat: replace large text pastes with [Pasted Text: X lines] placeholder by
-  @jackwotherspoon in
-  [#16422](https://github.com/google-gemini/gemini-cli/pull/16422)
-- security(hooks): Wrap hook-injected context in distinct XML tags by @yunaseoul
-  in [#17237](https://github.com/google-gemini/gemini-cli/pull/17237)
-- Enable the ability to queue specific nightly eval tests by @gundermanc in
-  [#17262](https://github.com/google-gemini/gemini-cli/pull/17262)
-- docs(hooks): comprehensive update of hook documentation and specs by
-  @abhipatel12 in
-  [#16816](https://github.com/google-gemini/gemini-cli/pull/16816)
-- refactor: improve large text paste placeholder by @jacob314 in
-  [#17269](https://github.com/google-gemini/gemini-cli/pull/17269)
-- feat: implement /rewind command by @Adib234 in
-  [#15720](https://github.com/google-gemini/gemini-cli/pull/15720)
-- Feature/jetbrains ide detection by @SoLoHiC in
-  [#16243](https://github.com/google-gemini/gemini-cli/pull/16243)
-- docs: update typo in mcp-server.md file by @schifferl in
-  [#17099](https://github.com/google-gemini/gemini-cli/pull/17099)
-- Sanitize command names and descriptions by @ehedlund in
-  [#17228](https://github.com/google-gemini/gemini-cli/pull/17228)
-- fix(auth): don't crash when initial auth fails by @skeshive in
-  [#17308](https://github.com/google-gemini/gemini-cli/pull/17308)
-- Added image pasting capabilities for Wayland and X11 on Linux by @devr0306 in
-  [#17144](https://github.com/google-gemini/gemini-cli/pull/17144)
-- feat: add AskUser tool schema by @jackwotherspoon in
-  [#16988](https://github.com/google-gemini/gemini-cli/pull/16988)
-- fix cli settings: resolve layout jitter in settings bar by @Mag1ck in
-  [#16256](https://github.com/google-gemini/gemini-cli/pull/16256)
-- fix: show whitespace changes in edit tool diffs by @Ujjiyara in
-  [#17213](https://github.com/google-gemini/gemini-cli/pull/17213)
-- Remove redundant calls setting linuxClipboardTool. getUserLinuxClipboardTool()
-  now handles the caching internally by @jacob314 in
-  [#17320](https://github.com/google-gemini/gemini-cli/pull/17320)
-- ci: allow failure in evals-nightly run step by @gundermanc in
-  [#17319](https://github.com/google-gemini/gemini-cli/pull/17319)
-- feat(cli): Add state management and plumbing for agent configuration dialog by
-  @SandyTao520 in
-  [#17259](https://github.com/google-gemini/gemini-cli/pull/17259)
-- bug: fix ide-client connection to ide-companion when inside docker via
-  ssh/devcontainer by @kapsner in
-  [#15049](https://github.com/google-gemini/gemini-cli/pull/15049)
-- Emit correct newline type return by @scidomino in
-  [#17331](https://github.com/google-gemini/gemini-cli/pull/17331)
-- New skill: docs-writer by @g-samroberts in
-  [#17268](https://github.com/google-gemini/gemini-cli/pull/17268)
-- fix(core): Resolve AbortSignal MaxListenersExceededWarning (#5950) by
-  @spencer426 in
-  [#16735](https://github.com/google-gemini/gemini-cli/pull/16735)
-- Disable tips after 10 runs by @Adib234 in
-  [#17101](https://github.com/google-gemini/gemini-cli/pull/17101)
-- Fix so rewind starts at the bottom and loadHistory refreshes static content.
-  by @jacob314 in
-  [#17335](https://github.com/google-gemini/gemini-cli/pull/17335)
-- feat(core): Remove legacy settings. by @joshualitt in
-  [#17244](https://github.com/google-gemini/gemini-cli/pull/17244)
-- feat(plan): add 'communicate' tool kind by @jerop in
-  [#17341](https://github.com/google-gemini/gemini-cli/pull/17341)
-- feat(routing): A/B Test Numerical Complexity Scoring for Gemini 3 by
-  @mattKorwel in
-  [#16041](https://github.com/google-gemini/gemini-cli/pull/16041)
-- feat(plan): update UI Theme for Plan Mode by @Adib234 in
-  [#17243](https://github.com/google-gemini/gemini-cli/pull/17243)
-- fix(ui): stabilize rendering during terminal resize in alternate buffer by
-  @lkk214 in [#15783](https://github.com/google-gemini/gemini-cli/pull/15783)
-- feat(cli): add /agents config command and improve agent discovery by
-  @SandyTao520 in
-  [#17342](https://github.com/google-gemini/gemini-cli/pull/17342)
-- feat(mcp): add enable/disable commands for MCP servers (#11057) by @jasmeetsb
-  in [#16299](https://github.com/google-gemini/gemini-cli/pull/16299)
-- fix(cli)!: Default to interactive mode for positional arguments by
-  @ishaanxgupta in
-  [#16329](https://github.com/google-gemini/gemini-cli/pull/16329)
-- Fix issue #17080 by @jacob314 in
-  [#17100](https://github.com/google-gemini/gemini-cli/pull/17100)
-- feat(core): Refresh agents after loading an extension. by @joshualitt in
-  [#17355](https://github.com/google-gemini/gemini-cli/pull/17355)
-- fix(cli): include source in policy rule display by @allenhutchison in
-  [#17358](https://github.com/google-gemini/gemini-cli/pull/17358)
-- fix: remove obsolete CloudCode PerDay quota and 120s terminal threshold by
+  [#17974](https://github.com/google-gemini/gemini-cli/pull/17974)
+- docs: fix help-wanted label spelling by @pavan-sh in
+  [#18114](https://github.com/google-gemini/gemini-cli/pull/18114)
+- feat(cli): implement automatic theme switching based on terminal background by
+  @Abhijit-2592 in
+  [#17976](https://github.com/google-gemini/gemini-cli/pull/17976)
+- fix(ide): no-op refactoring that moves the connection logic to helper
+  functions by @skeshive in
+  [#18118](https://github.com/google-gemini/gemini-cli/pull/18118)
+- feat: update review-frontend-and-fix slash command to review-and-fix by
+  @galz10 in [#18146](https://github.com/google-gemini/gemini-cli/pull/18146)
+- fix: improve Ctrl+R reverse search by @jackwotherspoon in
+  [#18075](https://github.com/google-gemini/gemini-cli/pull/18075)
+- feat(plan): handle inconsistency in schedulers by @Adib234 in
+  [#17813](https://github.com/google-gemini/gemini-cli/pull/17813)
+- feat(plan): add core logic and exit_plan_mode tool definition by @jerop in
+  [#18110](https://github.com/google-gemini/gemini-cli/pull/18110)
+- feat(core): rename search_file_content tool to grep_search and add legacy
+  alias by @SandyTao520 in
+  [#18003](https://github.com/google-gemini/gemini-cli/pull/18003)
+- fix(core): prioritize detailed error messages for code assist setup by
   @gsquared94 in
-  [#17236](https://github.com/google-gemini/gemini-cli/pull/17236)
-- Refactor subagent delegation to be one tool per agent by @gundermanc in
-  [#17346](https://github.com/google-gemini/gemini-cli/pull/17346)
-- fix(core): Include MCP server name in OAuth message by @jerop in
-  [#17351](https://github.com/google-gemini/gemini-cli/pull/17351)
-- Fix pr-triage.sh script to update pull requests with tags "help wanted" and
-  "maintainer only" by @jacob314 in
-  [#17324](https://github.com/google-gemini/gemini-cli/pull/17324)
-- feat(plan): implement simple workflow for planning in main agent by @jerop in
-  [#17326](https://github.com/google-gemini/gemini-cli/pull/17326)
-- fix: exit with non-zero code when esbuild is missing by @yuvrajangadsingh in
-  [#16967](https://github.com/google-gemini/gemini-cli/pull/16967)
-- fix: ensure @docs/cli/custom-commands.md UI message ordering and test by
-  @medic-code in
-  [#12038](https://github.com/google-gemini/gemini-cli/pull/12038)
-- fix(core): add alternative command names for Antigravity editor detec… by
-  @baeseokjae in
-  [#16829](https://github.com/google-gemini/gemini-cli/pull/16829)
-- Refactor: Migrate CLI appEvents to Core coreEvents by @Adib234 in
-  [#15737](https://github.com/google-gemini/gemini-cli/pull/15737)
-- fix(core): await MCP initialization in non-interactive mode by @Ratish1 in
-  [#17390](https://github.com/google-gemini/gemini-cli/pull/17390)
-- Fix modifyOtherKeys enablement on unsupported terminals by @seekskyworld in
-  [#16714](https://github.com/google-gemini/gemini-cli/pull/16714)
-- fix(core): gracefully handle disk full errors in chat recording by
-  @godwiniheuwa in
-  [#17305](https://github.com/google-gemini/gemini-cli/pull/17305)
-- fix(oauth): update oauth to use 127.0.0.1 instead of localhost by @skeshive in
-  [#17388](https://github.com/google-gemini/gemini-cli/pull/17388)
-- fix(core): use RFC 9728 compliant path-based OAuth protected resource
-  discovery by @vrv in
-  [#15756](https://github.com/google-gemini/gemini-cli/pull/15756)
-- Update Code Wiki README badge by @PatoBeltran in
-  [#15229](https://github.com/google-gemini/gemini-cli/pull/15229)
-- Add conda installation instructions for Gemini CLI by @ishaanxgupta in
-  [#16921](https://github.com/google-gemini/gemini-cli/pull/16921)
-- chore(refactor): extract BaseSettingsDialog component by @SandyTao520 in
-  [#17369](https://github.com/google-gemini/gemini-cli/pull/17369)
-- fix(cli): preserve input text when declining tool approval (#15624) by
-  @ManojINaik in
-  [#15659](https://github.com/google-gemini/gemini-cli/pull/15659)
-- chore: upgrade dep: diff 7.0.0-> 8.0.3 by @scidomino in
-  [#17403](https://github.com/google-gemini/gemini-cli/pull/17403)
-- feat: add AskUserDialog for UI component of AskUser tool by @jackwotherspoon
-  in [#17344](https://github.com/google-gemini/gemini-cli/pull/17344)
-- feat(ui): display user tier in about command by @sehoon38 in
-  [#17400](https://github.com/google-gemini/gemini-cli/pull/17400)
-- feat: add clearContext to AfterAgent hooks by @jackwotherspoon in
-  [#16574](https://github.com/google-gemini/gemini-cli/pull/16574)
-- fix(cli): change image paste location to global temp directory (#17396) by
-  @devr0306 in [#17396](https://github.com/google-gemini/gemini-cli/pull/17396)
-- Fix line endings issue with Notice file by @scidomino in
-  [#17417](https://github.com/google-gemini/gemini-cli/pull/17417)
-- feat(plan): implement persistent approvalMode setting by @Adib234 in
-  [#17350](https://github.com/google-gemini/gemini-cli/pull/17350)
-- feat(ui): Move keyboard handling into BaseSettingsDialog by @SandyTao520 in
-  [#17404](https://github.com/google-gemini/gemini-cli/pull/17404)
-- Allow prompt queueing during MCP initialization by @Adib234 in
-  [#17395](https://github.com/google-gemini/gemini-cli/pull/17395)
-- feat: implement AgentConfigDialog for /agents config command by @SandyTao520
-  in [#17370](https://github.com/google-gemini/gemini-cli/pull/17370)
-- fix(agents): default to all tools when tool list is omitted in subagents by
-  @gundermanc in
-  [#17422](https://github.com/google-gemini/gemini-cli/pull/17422)
-- feat(cli): Moves tool confirmations to a queue UX by @abhipatel12 in
-  [#17276](https://github.com/google-gemini/gemini-cli/pull/17276)
-- fix(core): hide user tier name by @sehoon38 in
-  [#17418](https://github.com/google-gemini/gemini-cli/pull/17418)
-- feat: Enforce unified folder trust for /directory add by @galz10 in
-  [#17359](https://github.com/google-gemini/gemini-cli/pull/17359)
-- migrate fireToolNotificationHook to hookSystem by @ved015 in
-  [#17398](https://github.com/google-gemini/gemini-cli/pull/17398)
-- Clean up dead code by @scidomino in
-  [#17443](https://github.com/google-gemini/gemini-cli/pull/17443)
-- feat(workflow): add stale pull request closer with linked-issue enforcement by
-  @bdmorgan in [#17449](https://github.com/google-gemini/gemini-cli/pull/17449)
-- feat(workflow): expand stale-exempt labels to include help wanted and Public
-  Roadmap by @bdmorgan in
-  [#17459](https://github.com/google-gemini/gemini-cli/pull/17459)
-- chore(workflow): remove redundant label-enforcer workflow by @bdmorgan in
-  [#17460](https://github.com/google-gemini/gemini-cli/pull/17460)
-- Resolves the confusing error message `ripgrep exited with code null that
-  occurs when a search operation is cancelled or aborted by @maximmasiutin in
-  [#14267](https://github.com/google-gemini/gemini-cli/pull/14267)
-- fix: detect pnpm/pnpx in ~/.local by @rwakulszowa in
-  [#15254](https://github.com/google-gemini/gemini-cli/pull/15254)
-- docs: Add instructions for MacPorts and uninstall instructions for Homebrew by
-  @breun in [#17412](https://github.com/google-gemini/gemini-cli/pull/17412)
-- docs(hooks): clarify mandatory 'type' field and update hook schema
-  documentation by @abhipatel12 in
-  [#17499](https://github.com/google-gemini/gemini-cli/pull/17499)
-- Improve error messages on failed onboarding by @gsquared94 in
-  [#17357](https://github.com/google-gemini/gemini-cli/pull/17357)
-- Follow up to "enableInteractiveShell for external tooling relying on a2a
-  server" by @DavidAPierce in
-  [#17130](https://github.com/google-gemini/gemini-cli/pull/17130)
-- Fix/issue 17070 by @alih552 in
-  [#17242](https://github.com/google-gemini/gemini-cli/pull/17242)
-- fix(core): handle URI-encoded workspace paths in IdeClient by @dong-jun-shin
-  in [#17476](https://github.com/google-gemini/gemini-cli/pull/17476)
-- feat(cli): add quick clear input shortcuts in vim mode by @harshanadim in
-  [#17470](https://github.com/google-gemini/gemini-cli/pull/17470)
-- feat(core): optimize shell tool llmContent output format by @SandyTao520 in
-  [#17538](https://github.com/google-gemini/gemini-cli/pull/17538)
-- Fix bug in detecting already added paths. by @jacob314 in
-  [#17430](https://github.com/google-gemini/gemini-cli/pull/17430)
-- feat(scheduler): support multi-scheduler tool aggregation and nested call IDs
-  by @abhipatel12 in
-  [#17429](https://github.com/google-gemini/gemini-cli/pull/17429)
-- feat(agents): implement first-run experience for project-level sub-agents by
-  @gundermanc in
-  [#17266](https://github.com/google-gemini/gemini-cli/pull/17266)
-- Update extensions docs by @chrstnb in
-  [#16093](https://github.com/google-gemini/gemini-cli/pull/16093)
-- Docs: Refactor left nav on the website by @jkcinouye in
-  [#17558](https://github.com/google-gemini/gemini-cli/pull/17558)
-- fix(core): stream grep/ripgrep output to prevent OOM by @adamfweidman in
-  [#17146](https://github.com/google-gemini/gemini-cli/pull/17146)
-- feat(plan): add persistent plan file storage by @jerop in
-  [#17563](https://github.com/google-gemini/gemini-cli/pull/17563)
-- feat(agents): migrate subagents to event-driven scheduler by @abhipatel12 in
-  [#17567](https://github.com/google-gemini/gemini-cli/pull/17567)
-- Fix extensions config error by @chrstnb in
-  [#17580](https://github.com/google-gemini/gemini-cli/pull/17580)
-- fix(plan): remove subagent invocation from plan mode by @jerop in
-  [#17593](https://github.com/google-gemini/gemini-cli/pull/17593)
-- feat(ui): add solid background color option for input prompt by @jacob314 in
-  [#16563](https://github.com/google-gemini/gemini-cli/pull/16563)
-- feat(plan): refresh system prompt when approval mode changes (Shift+Tab) by
-  @jerop in [#17585](https://github.com/google-gemini/gemini-cli/pull/17585)
-- feat(cli): add global setting to disable UI spinners by @galz10 in
-  [#17234](https://github.com/google-gemini/gemini-cli/pull/17234)
-- fix(security): enforce strict policy directory permissions by @yunaseoul in
-  [#17353](https://github.com/google-gemini/gemini-cli/pull/17353)
-- test(core): fix tests in windows by @scidomino in
-  [#17592](https://github.com/google-gemini/gemini-cli/pull/17592)
-- feat(mcp/extensions): Allow users to selectively enable/disable MCP servers
-  included in an extension( Issue #11057 & #17402) by @jasmeetsb in
-  [#17434](https://github.com/google-gemini/gemini-cli/pull/17434)
-- Always map mac keys, even on other platforms by @scidomino in
-  [#17618](https://github.com/google-gemini/gemini-cli/pull/17618)
-- Ctrl-O by @jacob314 in
-  [#17617](https://github.com/google-gemini/gemini-cli/pull/17617)
-- feat(plan): update cycling order of approval modes by @Adib234 in
-  [#17622](https://github.com/google-gemini/gemini-cli/pull/17622)
-- fix(cli): restore 'Modify with editor' option in external terminals by
-  @abhipatel12 in
-  [#17621](https://github.com/google-gemini/gemini-cli/pull/17621)
-- Slash command for helping in debugging by @gundermanc in
-  [#17609](https://github.com/google-gemini/gemini-cli/pull/17609)
-- feat: add double-click to expand/collapse large paste placeholders by
-  @jackwotherspoon in
-  [#17471](https://github.com/google-gemini/gemini-cli/pull/17471)
-- refactor(cli): migrate non-interactive flow to event-driven scheduler by
-  @abhipatel12 in
-  [#17572](https://github.com/google-gemini/gemini-cli/pull/17572)
-- fix: loadcodeassist eligible tiers getting ignored for unlicensed users
-  (regression) by @gsquared94 in
-  [#17581](https://github.com/google-gemini/gemini-cli/pull/17581)
-- chore(core): delete legacy nonInteractiveToolExecutor by @abhipatel12 in
-  [#17573](https://github.com/google-gemini/gemini-cli/pull/17573)
-- feat(core): enforce server prefixes for MCP tools in agent definitions by
-  @abhipatel12 in
-  [#17574](https://github.com/google-gemini/gemini-cli/pull/17574)
-- feat (mcp): Refresh MCP prompts on list changed notification by @MrLesk in
-  [#14863](https://github.com/google-gemini/gemini-cli/pull/14863)
-- feat(ui): pretty JSON rendering tool outputs by @medic-code in
-  [#9767](https://github.com/google-gemini/gemini-cli/pull/9767)
-- Fix iterm alternate buffer mode issue rendering backgrounds by @jacob314 in
-  [#17634](https://github.com/google-gemini/gemini-cli/pull/17634)
-- feat(cli): add gemini extensions list --output-format=json by @AkihiroSuda in
-  [#14479](https://github.com/google-gemini/gemini-cli/pull/14479)
-- fix(extensions): add .gitignore to extension templates by @godwiniheuwa in
-  [#17293](https://github.com/google-gemini/gemini-cli/pull/17293)
-- paste transform followup by @jacob314 in
-  [#17624](https://github.com/google-gemini/gemini-cli/pull/17624)
-- refactor: rename formatMemoryUsage to formatBytes by @Nubebuster in
-  [#14997](https://github.com/google-gemini/gemini-cli/pull/14997)
-- chore: remove extra top margin from /hooks and /extensions by @jackwotherspoon
-  in [#17663](https://github.com/google-gemini/gemini-cli/pull/17663)
-- feat(cli): add oncall command for issue triage by @sehoon38 in
-  [#17661](https://github.com/google-gemini/gemini-cli/pull/17661)
-- Fix sidebar issue for extensions link by @chrstnb in
-  [#17668](https://github.com/google-gemini/gemini-cli/pull/17668)
-- Change formatting to prevent UI redressing attacks by @scidomino in
-  [#17611](https://github.com/google-gemini/gemini-cli/pull/17611)
-- Fix cluster of bugs in the settings dialog. by @jacob314 in
-  [#17628](https://github.com/google-gemini/gemini-cli/pull/17628)
-- Update sidebar to resolve site build issues by @chrstnb in
-  [#17674](https://github.com/google-gemini/gemini-cli/pull/17674)
-- fix(admin): fix a few bugs related to admin controls by @skeshive in
-  [#17590](https://github.com/google-gemini/gemini-cli/pull/17590)
-- revert bad changes to tests by @scidomino in
-  [#17673](https://github.com/google-gemini/gemini-cli/pull/17673)
-- feat(cli): show candidate issue state reason and duplicate status in triage by
-  @sehoon38 in [#17676](https://github.com/google-gemini/gemini-cli/pull/17676)
-- Fix missing slash commands when Gemini CLI is in a project with a package.json
-  that doesn't follow semantic versioning by @Adib234 in
-  [#17561](https://github.com/google-gemini/gemini-cli/pull/17561)
-- feat(core): Model family-specific system prompts by @joshualitt in
-  [#17614](https://github.com/google-gemini/gemini-cli/pull/17614)
-- Sub-agents documentation. by @gundermanc in
-  [#16639](https://github.com/google-gemini/gemini-cli/pull/16639)
-- feat: wire up AskUserTool with dialog by @jackwotherspoon in
-  [#17411](https://github.com/google-gemini/gemini-cli/pull/17411)
-- Load extension settings for hooks, agents, skills by @chrstnb in
-  [#17245](https://github.com/google-gemini/gemini-cli/pull/17245)
-- Fix issue where Gemini CLI can make changes when simply asked a question by
-  @gundermanc in
-  [#17608](https://github.com/google-gemini/gemini-cli/pull/17608)
-- Update docs-writer skill for editing and add style guide for reference. by
-  @g-samroberts in
-  [#17669](https://github.com/google-gemini/gemini-cli/pull/17669)
-- fix(ux): have user message display a short path for pasted images by @devr0306
-  in [#17613](https://github.com/google-gemini/gemini-cli/pull/17613)
-- feat(plan): enable AskUser tool in Plan mode for clarifying questions by
-  @jerop in [#17694](https://github.com/google-gemini/gemini-cli/pull/17694)
-- GEMINI.md polish by @jacob314 in
-  [#17680](https://github.com/google-gemini/gemini-cli/pull/17680)
-- refactor(core): centralize path validation and allow temp dir access for tools
-  by @NTaylorMullen in
-  [#17185](https://github.com/google-gemini/gemini-cli/pull/17185)
-- feat(skills): promote Agent Skills to stable by @abhipatel12 in
-  [#17693](https://github.com/google-gemini/gemini-cli/pull/17693)
-- refactor(cli): keyboard handling and AskUserDialog by @jacob314 in
-  [#17414](https://github.com/google-gemini/gemini-cli/pull/17414)
-- docs: Add Experimental Remote Agent Docs by @adamfweidman in
-  [#17697](https://github.com/google-gemini/gemini-cli/pull/17697)
-- revert: promote Agent Skills to stable (#17693) by @abhipatel12 in
-  [#17712](https://github.com/google-gemini/gemini-cli/pull/17712)
-- feat(ux) Expandable (ctrl-O) and scrollable approvals in alternate buffer
-  mode. by @jacob314 in
-  [#17640](https://github.com/google-gemini/gemini-cli/pull/17640)
-- feat(skills): promote skills settings to stable by @abhipatel12 in
-  [#17713](https://github.com/google-gemini/gemini-cli/pull/17713)
-- fix(cli): Preserve settings dialog focus when searching by @SandyTao520 in
-  [#17701](https://github.com/google-gemini/gemini-cli/pull/17701)
-- feat(ui): add terminal cursor support by @jacob314 in
-  [#17711](https://github.com/google-gemini/gemini-cli/pull/17711)
-- docs(skills): remove experimental labels and update tutorials by @abhipatel12
-  in [#17714](https://github.com/google-gemini/gemini-cli/pull/17714)
-- docs: remove 'experimental' syntax for hooks in docs by @abhipatel12 in
-  [#17660](https://github.com/google-gemini/gemini-cli/pull/17660)
-- Add support for an additional exclusion file besides .gitignore and
-  .geminiignore by @alisa-alisa in
-  [#16487](https://github.com/google-gemini/gemini-cli/pull/16487)
-- feat: add review-frontend-and-fix command by @galz10 in
-  [#17707](https://github.com/google-gemini/gemini-cli/pull/17707)
+  [#17852](https://github.com/google-gemini/gemini-cli/pull/17852)
+- fix(cli): resolve environment loading and auth validation issues in ACP mode
+  by @bdmorgan in
+  [#18025](https://github.com/google-gemini/gemini-cli/pull/18025)
+- feat(core): add .agents/skills directory alias for skill discovery by
+  @NTaylorMullen in
+  [#18151](https://github.com/google-gemini/gemini-cli/pull/18151)
+- chore(core): reassign telemetry keys to avoid server conflict by @mattKorwel
+  in [#18161](https://github.com/google-gemini/gemini-cli/pull/18161)
+- Add link to rewind doc in commands.md by @Adib234 in
+  [#17961](https://github.com/google-gemini/gemini-cli/pull/17961)
+- feat(core): add draft-2020-12 JSON Schema support with lenient fallback by
+  @afarber in [#15060](https://github.com/google-gemini/gemini-cli/pull/15060)
+- refactor(core): robust trimPreservingTrailingNewline and regression test by
+  @adamfweidman in
+  [#18196](https://github.com/google-gemini/gemini-cli/pull/18196)
+- Remove MCP servers on extension uninstall by @chrstnb in
+  [#18121](https://github.com/google-gemini/gemini-cli/pull/18121)
+- refactor: localize ACP error parsing logic to cli package by @bdmorgan in
+  [#18193](https://github.com/google-gemini/gemini-cli/pull/18193)
+- feat(core): Add A2A auth config types by @adamfweidman in
+  [#18205](https://github.com/google-gemini/gemini-cli/pull/18205)
+- Set default max attempts to 3 and use the common variable by @sehoon38 in
+  [#18209](https://github.com/google-gemini/gemini-cli/pull/18209)
+- feat(plan): add exit_plan_mode ui and prompt by @jerop in
+  [#18162](https://github.com/google-gemini/gemini-cli/pull/18162)
+- fix(test): improve test isolation and enable subagent evaluations by
+  @cocosheng-g in
+  [#18138](https://github.com/google-gemini/gemini-cli/pull/18138)
+- feat(plan): use custom deny messages in plan mode policies by @Adib234 in
+  [#18195](https://github.com/google-gemini/gemini-cli/pull/18195)
+- Match on extension ID when stopping extensions by @chrstnb in
+  [#18218](https://github.com/google-gemini/gemini-cli/pull/18218)
+- fix(core): Respect user's .gitignore preference by @xyrolle in
+  [#15482](https://github.com/google-gemini/gemini-cli/pull/15482)
+- docs: document GEMINI_CLI_HOME environment variable by @adamfweidman in
+  [#18219](https://github.com/google-gemini/gemini-cli/pull/18219)
+- chore(core): explicitly state plan storage path in prompt by @jerop in
+  [#18222](https://github.com/google-gemini/gemini-cli/pull/18222)
+- A2a admin setting by @DavidAPierce in
+  [#17868](https://github.com/google-gemini/gemini-cli/pull/17868)
+- feat(a2a): Add pluggable auth provider infrastructure by @adamfweidman in
+  [#17934](https://github.com/google-gemini/gemini-cli/pull/17934)
+- Fix handling of empty settings by @chrstnb in
+  [#18131](https://github.com/google-gemini/gemini-cli/pull/18131)
+- Reload skills when extensions change by @chrstnb in
+  [#18225](https://github.com/google-gemini/gemini-cli/pull/18225)
+- feat: Add markdown rendering to ask_user tool by @jackwotherspoon in
+  [#18211](https://github.com/google-gemini/gemini-cli/pull/18211)
+- Add telemetry to rewind by @Adib234 in
+  [#18122](https://github.com/google-gemini/gemini-cli/pull/18122)
+- feat(admin): add support for MCP configuration via admin controls (pt1) by
+  @skeshive in [#18223](https://github.com/google-gemini/gemini-cli/pull/18223)
+- feat(core): require user consent before MCP server OAuth by @ehedlund in
+  [#18132](https://github.com/google-gemini/gemini-cli/pull/18132)
+- fix(sandbox): propagate GOOGLE_GEMINI_BASE_URL&GOOGLE_VERTEX_BASE_URL env vars
+  by @skeshive in
+  [#18231](https://github.com/google-gemini/gemini-cli/pull/18231)
+- feat(ui): move user identity display to header by @sehoon38 in
+  [#18216](https://github.com/google-gemini/gemini-cli/pull/18216)
+- fix: enforce folder trust for workspace settings, skills, and context by
+  @galz10 in [#17596](https://github.com/google-gemini/gemini-cli/pull/17596)
 
-**Full changelog**:
-https://github.com/google-gemini/gemini-cli/compare/v0.26.0...v0.27.0
+**Full Changelog**:
+https://github.com/google-gemini/gemini-cli/compare/v0.27.0...v0.28.0
diff --git a/docs/changelogs/preview.md b/docs/changelogs/preview.md
index 93ed5a2a9c..cab75c4446 100644
--- a/docs/changelogs/preview.md
+++ b/docs/changelogs/preview.md
@@ -1,6 +1,6 @@
-# Preview release: Release v0.28.0-preview.0
+# Preview release: Release v0.29.0-preview.0
 
-Released: February 3, 2026
+Released: February 10, 2026
 
 Our preview release includes the latest, new, and experimental features. This
 release may not be as stable as our [latest weekly release](latest.md).
@@ -13,295 +13,355 @@ npm install -g @google/gemini-cli@preview
 
 ## Highlights
 
-- **Improved Hooks Management:** Hooks enable/disable functionality now aligns
-  with skills and offers improved completion.
-- **Custom Themes for Extensions:** Extensions can now support custom themes,
-  allowing for greater personalization.
-- **User Identity Display:** User identity information (auth, email, tier) is
-  now displayed on startup and in the `stats` command.
-- **Plan Mode Enhancements:** Plan mode has been improved with a generic
-  `Checklist` component and refactored `Todo`.
-- **Background Shell Commands:** Implementation of background shell commands.
+- **Plan Mode Enhancements**: Significant updates to Plan Mode, including new
+  commands, support for MCP servers, integration of planning artifacts, and
+  improved iteration guidance.
+- **Core Agent Improvements**: Enhancements to the core agent, including better
+  system prompt rigor, improved subagent definitions, and enhanced tool
+  execution limits.
+- **CLI UX/UI Updates**: Various UI and UX improvements, such as autocomplete in
+  the input prompt, updated approval mode labels, DevTools integration, and
+  improved header spacing.
+- **Tooling & Extension Updates**: Improvements to existing tools like
+  `ask_user` and `grep_search`, and new features for extension management.
+- **Bug Fixes**: Numerous bug fixes across the CLI and core, addressing issues
+  with interactive commands, memory leaks, permission checks, and more.
+- **Context and Tool Output Management**: Features for observation masking for
+  tool outputs, session-linked tool output storage, and persistence for masked
+  tool outputs.
 
 ## What's Changed
 
-- feat(commands): add /prompt-suggest slash command by NTaylorMullen in
-  [#17264](https://github.com/google-gemini/gemini-cli/pull/17264)
-- feat(cli): align hooks enable/disable with skills and improve completion by
-  sehoon38 in [#16822](https://github.com/google-gemini/gemini-cli/pull/16822)
-- docs: add CLI reference documentation by leochiu-a in
-  [#17504](https://github.com/google-gemini/gemini-cli/pull/17504)
-- chore(release): bump version to 0.28.0-nightly.20260128.adc8e11bb by
+- fix: remove ask_user tool from non-interactive modes by jackwotherspoon in
+  [#18154](https://github.com/google-gemini/gemini-cli/pull/18154)
+- fix(cli): allow restricted .env loading in untrusted sandboxed folders by
+  galz10 in [#17806](https://github.com/google-gemini/gemini-cli/pull/17806)
+- Encourage agent to utilize ecosystem tools to perform work by gundermanc in
+  [#17881](https://github.com/google-gemini/gemini-cli/pull/17881)
+- feat(plan): unify workflow location in system prompt to optimize caching by
+  jerop in [#18258](https://github.com/google-gemini/gemini-cli/pull/18258)
+- feat(core): enable getUserTierName in config by sehoon38 in
+  [#18265](https://github.com/google-gemini/gemini-cli/pull/18265)
+- feat(core): add default execution limits for subagents by abhipatel12 in
+  [#18274](https://github.com/google-gemini/gemini-cli/pull/18274)
+- Fix issue where agent gets stuck at interactive commands. by gundermanc in
+  [#18272](https://github.com/google-gemini/gemini-cli/pull/18272)
+- chore(release): bump version to 0.29.0-nightly.20260203.71f46f116 by
   gemini-cli-robot in
-  [#17725](https://github.com/google-gemini/gemini-cli/pull/17725)
-- feat(skills): final stable promotion cleanup by abhipatel12 in
-  [#17726](https://github.com/google-gemini/gemini-cli/pull/17726)
-- test(core): mock fetch in OAuth transport fallback tests by jw409 in
-  [#17059](https://github.com/google-gemini/gemini-cli/pull/17059)
-- feat(cli): include auth method in /bug by erikus in
-  [#17569](https://github.com/google-gemini/gemini-cli/pull/17569)
-- Add a email privacy note to bug_report template by nemyung in
-  [#17474](https://github.com/google-gemini/gemini-cli/pull/17474)
-- Rewind documentation by Adib234 in
-  [#17446](https://github.com/google-gemini/gemini-cli/pull/17446)
-- fix: verify audio/video MIME types with content check by maru0804 in
-  [#16907](https://github.com/google-gemini/gemini-cli/pull/16907)
-- feat(core): add support for positron ide (#15045) by kapsner in
-  [#15047](https://github.com/google-gemini/gemini-cli/pull/15047)
-- /oncall dedup - wrap texts to nextlines by sehoon38 in
-  [#17782](https://github.com/google-gemini/gemini-cli/pull/17782)
-- fix(admin): rename advanced features admin setting by skeshive in
-  [#17786](https://github.com/google-gemini/gemini-cli/pull/17786)
-- [extension config] Make breaking optional value non-optional by chrstnb in
-  [#17785](https://github.com/google-gemini/gemini-cli/pull/17785)
-- Fix docs-writer skill issues by g-samroberts in
-  [#17734](https://github.com/google-gemini/gemini-cli/pull/17734)
-- fix(core): suppress duplicate hook failure warnings during streaming by
+  [#18243](https://github.com/google-gemini/gemini-cli/pull/18243)
+- feat(core): remove hardcoded policy bypass for local subagents by abhipatel12
+  in [#18153](https://github.com/google-gemini/gemini-cli/pull/18153)
+- feat(plan): implement plan slash command by Adib234 in
+  [#17698](https://github.com/google-gemini/gemini-cli/pull/17698)
+- feat: increase ask_user label limit to 16 characters by jackwotherspoon in
+  [#18320](https://github.com/google-gemini/gemini-cli/pull/18320)
+- Add information about the agent skills lifecycle and clarify docs-writer skill
+  metadata. by g-samroberts in
+  [#18234](https://github.com/google-gemini/gemini-cli/pull/18234)
+- feat(core): add enter_plan_mode tool by jerop in
+  [#18324](https://github.com/google-gemini/gemini-cli/pull/18324)
+- Stop showing an error message in /plan by Adib234 in
+  [#18333](https://github.com/google-gemini/gemini-cli/pull/18333)
+- fix(hooks): remove unnecessary logging for hook registration by abhipatel12 in
+  [#18332](https://github.com/google-gemini/gemini-cli/pull/18332)
+- fix(mcp): ensure MCP transport is closed to prevent memory leaks by cbcoutinho
+  in [#18054](https://github.com/google-gemini/gemini-cli/pull/18054)
+- feat(skills): implement linking for agent skills by MushuEE in
+  [#18295](https://github.com/google-gemini/gemini-cli/pull/18295)
+- Changelogs for 0.27.0 and 0.28.0-preview0 by g-samroberts in
+  [#18336](https://github.com/google-gemini/gemini-cli/pull/18336)
+- chore: correct docs as skills and hooks are stable by jackwotherspoon in
+  [#18358](https://github.com/google-gemini/gemini-cli/pull/18358)
+- feat(admin): Implement admin allowlist for MCP server configurations by
+  skeshive in [#18311](https://github.com/google-gemini/gemini-cli/pull/18311)
+- fix(core): add retry logic for transient SSL/TLS errors
+  ([#17318](https://github.com/google-gemini/gemini-cli/pull/17318)) by
+  ppgranger in [#18310](https://github.com/google-gemini/gemini-cli/pull/18310)
+- Add support for /extensions config command by chrstnb in
+  [#17895](https://github.com/google-gemini/gemini-cli/pull/17895)
+- fix(core): handle non-compliant mcpbridge responses from Xcode 26.3 by
+  peterfriese in
+  [#18376](https://github.com/google-gemini/gemini-cli/pull/18376)
+- feat(cli): Add W, B, E Vim motions and operator support by ademuri in
+  [#16209](https://github.com/google-gemini/gemini-cli/pull/16209)
+- fix: Windows Specific Agent Quality & System Prompt by scidomino in
+  [#18351](https://github.com/google-gemini/gemini-cli/pull/18351)
+- feat(plan): support replace tool in plan mode to edit plans by jerop in
+  [#18379](https://github.com/google-gemini/gemini-cli/pull/18379)
+- Improving memory tool instructions and eval testing by alisa-alisa in
+  [#18091](https://github.com/google-gemini/gemini-cli/pull/18091)
+- fix(cli): color extension link success message green by MushuEE in
+  [#18386](https://github.com/google-gemini/gemini-cli/pull/18386)
+- undo by jacob314 in
+  [#18147](https://github.com/google-gemini/gemini-cli/pull/18147)
+- feat(plan): add guidance on iterating on approved plans vs creating new plans
+  by jerop in [#18346](https://github.com/google-gemini/gemini-cli/pull/18346)
+- feat(plan): fix invalid tool calls in plan mode by Adib234 in
+  [#18352](https://github.com/google-gemini/gemini-cli/pull/18352)
+- feat(plan): integrate planning artifacts and tools into primary workflows by
+  jerop in [#18375](https://github.com/google-gemini/gemini-cli/pull/18375)
+- Fix permission check by scidomino in
+  [#18395](https://github.com/google-gemini/gemini-cli/pull/18395)
+- ux(polish) autocomplete in the input prompt by jacob314 in
+  [#18181](https://github.com/google-gemini/gemini-cli/pull/18181)
+- fix: resolve infinite loop when using 'Modify with external editor' by
+  ppgranger in [#17453](https://github.com/google-gemini/gemini-cli/pull/17453)
+- feat: expand verify-release to macOS and Windows by yunaseoul in
+  [#18145](https://github.com/google-gemini/gemini-cli/pull/18145)
+- feat(plan): implement support for MCP servers in Plan mode by Adib234 in
+  [#18229](https://github.com/google-gemini/gemini-cli/pull/18229)
+- chore: update folder trust error messaging by galz10 in
+  [#18402](https://github.com/google-gemini/gemini-cli/pull/18402)
+- feat(plan): create a metric for execution of plans generated in plan mode by
+  Adib234 in [#18236](https://github.com/google-gemini/gemini-cli/pull/18236)
+- perf(ui): optimize stripUnsafeCharacters with regex by gsquared94 in
+  [#18413](https://github.com/google-gemini/gemini-cli/pull/18413)
+- feat(context): implement observation masking for tool outputs by abhipatel12
+  in [#18389](https://github.com/google-gemini/gemini-cli/pull/18389)
+- feat(core,cli): implement session-linked tool output storage and cleanup by
   abhipatel12 in
-  [#17727](https://github.com/google-gemini/gemini-cli/pull/17727)
-- test: add more tests for AskUser by jackwotherspoon in
-  [#17720](https://github.com/google-gemini/gemini-cli/pull/17720)
-- feat(cli): enable activity logging for non-interactive mode and evals by
-  SandyTao520 in
-  [#17703](https://github.com/google-gemini/gemini-cli/pull/17703)
-- feat(core): add support for custom deny messages in policy rules by
-  allenhutchison in
-  [#17427](https://github.com/google-gemini/gemini-cli/pull/17427)
-- Fix unintended credential exposure to MCP Servers by Adib234 in
-  [#17311](https://github.com/google-gemini/gemini-cli/pull/17311)
-- feat(extensions): add support for custom themes in extensions by spencer426 in
-  [#17327](https://github.com/google-gemini/gemini-cli/pull/17327)
-- fix: persist and restore workspace directories on session resume by
-  korade-krushna in
-  [#17454](https://github.com/google-gemini/gemini-cli/pull/17454)
-- Update release notes pages for 0.26.0 and 0.27.0-preview. by g-samroberts in
-  [#17744](https://github.com/google-gemini/gemini-cli/pull/17744)
-- feat(ux): update cell border color and created test file for table rendering
-  by devr0306 in
-  [#17798](https://github.com/google-gemini/gemini-cli/pull/17798)
-- Change height for the ToolConfirmationQueue. by jacob314 in
-  [#17799](https://github.com/google-gemini/gemini-cli/pull/17799)
-- feat(cli): add user identity info to stats command by sehoon38 in
-  [#17612](https://github.com/google-gemini/gemini-cli/pull/17612)
-- fix(ux): fixed off-by-some wrapping caused by fixed-width characters by
-  devr0306 in [#17816](https://github.com/google-gemini/gemini-cli/pull/17816)
-- feat(cli): update undo/redo keybindings to Cmd+Z/Alt+Z and
-  Shift+Cmd+Z/Shift+Alt+Z by scidomino in
-  [#17800](https://github.com/google-gemini/gemini-cli/pull/17800)
-- fix(evals): use absolute path for activity log directory by SandyTao520 in
-  [#17830](https://github.com/google-gemini/gemini-cli/pull/17830)
-- test: add integration test to verify stdout/stderr routing by ved015 in
-  [#17280](https://github.com/google-gemini/gemini-cli/pull/17280)
-- fix(cli): list installed extensions when update target missing by tt-a1i in
-  [#17082](https://github.com/google-gemini/gemini-cli/pull/17082)
-- fix(cli): handle PAT tokens and credentials in git remote URL parsing by
-  afarber in [#14650](https://github.com/google-gemini/gemini-cli/pull/14650)
-- fix(core): use returnDisplay for error result display by Nubebuster in
-  [#14994](https://github.com/google-gemini/gemini-cli/pull/14994)
-- Fix detection of bun as package manager by Randomblock1 in
-  [#17462](https://github.com/google-gemini/gemini-cli/pull/17462)
-- feat(cli): show hooksConfig.enabled in settings dialog by abhipatel12 in
-  [#17810](https://github.com/google-gemini/gemini-cli/pull/17810)
-- feat(cli): Display user identity (auth, email, tier) on startup by yunaseoul
-  in [#17591](https://github.com/google-gemini/gemini-cli/pull/17591)
-- fix: prevent ghost border for AskUserDialog by jackwotherspoon in
-  [#17788](https://github.com/google-gemini/gemini-cli/pull/17788)
-- docs: mark A2A subagents as experimental in subagents.md by adamfweidman in
-  [#17863](https://github.com/google-gemini/gemini-cli/pull/17863)
-- Resolve error thrown for sensitive values by chrstnb in
-  [#17826](https://github.com/google-gemini/gemini-cli/pull/17826)
-- fix(admin): Rename secureModeEnabled to strictModeDisabled by skeshive in
-  [#17789](https://github.com/google-gemini/gemini-cli/pull/17789)
-- feat(ux): update truncate dots to be shorter in tables by devr0306 in
-  [#17825](https://github.com/google-gemini/gemini-cli/pull/17825)
-- fix(core): resolve DEP0040 punycode deprecation via patch-package by
-  ATHARVA262005 in
-  [#17692](https://github.com/google-gemini/gemini-cli/pull/17692)
-- feat(plan): create generic Checklist component and refactor Todo by Adib234 in
-  [#17741](https://github.com/google-gemini/gemini-cli/pull/17741)
-- Cleanup post delegate_to_agent removal by gundermanc in
-  [#17875](https://github.com/google-gemini/gemini-cli/pull/17875)
-- fix(core): use GIT_CONFIG_GLOBAL to isolate shadow git repo configuration -
-  Fixes #17877 by cocosheng-g in
-  [#17803](https://github.com/google-gemini/gemini-cli/pull/17803)
-- Disable mouse tracking e2e by alisa-alisa in
-  [#17880](https://github.com/google-gemini/gemini-cli/pull/17880)
-- fix(cli): use correct setting key for Cloud Shell auth by sehoon38 in
-  [#17884](https://github.com/google-gemini/gemini-cli/pull/17884)
-- chore: revert IDE specific ASCII logo by jackwotherspoon in
-  [#17887](https://github.com/google-gemini/gemini-cli/pull/17887)
-- Revert "fix(core): resolve DEP0040 punycode deprecation via patch-package" by
-  sehoon38 in [#17898](https://github.com/google-gemini/gemini-cli/pull/17898)
-- Refactoring of disabling of mouse tracking in e2e tests by alisa-alisa in
-  [#17902](https://github.com/google-gemini/gemini-cli/pull/17902)
-- feat(core): Add GOOGLE_GENAI_API_VERSION environment variable support by deyim
-  in [#16177](https://github.com/google-gemini/gemini-cli/pull/16177)
-- feat(core): Isolate and cleanup truncated tool outputs by SandyTao520 in
-  [#17594](https://github.com/google-gemini/gemini-cli/pull/17594)
-- Create skills page, update commands, refine docs by g-samroberts in
-  [#17842](https://github.com/google-gemini/gemini-cli/pull/17842)
-- feat: preserve EOL in files by Thomas-Shephard in
-  [#16087](https://github.com/google-gemini/gemini-cli/pull/16087)
-- Fix HalfLinePaddedBox in screenreader mode. by jacob314 in
-  [#17914](https://github.com/google-gemini/gemini-cli/pull/17914)
-- bug(ux) vim mode fixes. Start in insert mode. Fix bug blocking F12 and ctrl-X
-  in vim mode. by jacob314 in
-  [#17938](https://github.com/google-gemini/gemini-cli/pull/17938)
-- feat(core): implement interactive and non-interactive consent for OAuth by
-  ehedlund in [#17699](https://github.com/google-gemini/gemini-cli/pull/17699)
-- perf(core): optimize token calculation and add support for multimodal tool
-  responses by abhipatel12 in
-  [#17835](https://github.com/google-gemini/gemini-cli/pull/17835)
-- refactor(hooks): remove legacy tools.enableHooks setting by abhipatel12 in
-  [#17867](https://github.com/google-gemini/gemini-cli/pull/17867)
-- feat(ci): add npx smoke test to verify installability by bdmorgan in
-  [#17927](https://github.com/google-gemini/gemini-cli/pull/17927)
-- feat(core): implement dynamic policy registration for subagents by abhipatel12
-  in [#17838](https://github.com/google-gemini/gemini-cli/pull/17838)
-- feat: Implement background shell commands by galz10 in
-  [#14849](https://github.com/google-gemini/gemini-cli/pull/14849)
-- feat(admin): provide actionable error messages for disabled features by
-  skeshive in [#17815](https://github.com/google-gemini/gemini-cli/pull/17815)
-- Fix bugs where Rewind and Resume showed Ugly and 100X too verbose content. by
-  jacob314 in [#17940](https://github.com/google-gemini/gemini-cli/pull/17940)
-- Fix broken link in docs by chrstnb in
-  [#17959](https://github.com/google-gemini/gemini-cli/pull/17959)
-- feat(plan): reuse standard tool confirmation for AskUser tool by jerop in
-  [#17864](https://github.com/google-gemini/gemini-cli/pull/17864)
-- feat(core): enable overriding CODE_ASSIST_API_VERSION with env var by
-  lottielin in [#17942](https://github.com/google-gemini/gemini-cli/pull/17942)
-- run npx pointing to the specific commit SHA by sehoon38 in
-  [#17970](https://github.com/google-gemini/gemini-cli/pull/17970)
-- Add allowedExtensions setting by kevinjwang1 in
-  [#17695](https://github.com/google-gemini/gemini-cli/pull/17695)
-- feat(plan): refactor ToolConfirmationPayload to union type by jerop in
-  [#17980](https://github.com/google-gemini/gemini-cli/pull/17980)
-- lower the default max retries to reduce contention by sehoon38 in
-  [#17975](https://github.com/google-gemini/gemini-cli/pull/17975)
-- fix(core): ensure YOLO mode auto-approves complex shell commands when parsing
-  fails by abhipatel12 in
-  [#17920](https://github.com/google-gemini/gemini-cli/pull/17920)
-- Fix broken link. by g-samroberts in
-  [#17972](https://github.com/google-gemini/gemini-cli/pull/17972)
-- Support ctrl-C and Ctrl-D correctly Refactor so InputPrompt has priority over
-  AppContainer for input handling. by jacob314 in
-  [#17993](https://github.com/google-gemini/gemini-cli/pull/17993)
-- Fix truncation for AskQuestion by jacob314 in
-  [#18001](https://github.com/google-gemini/gemini-cli/pull/18001)
-- fix(workflow): update maintainer check logic to be inclusive and
-  case-insensitive by bdmorgan in
-  [#18009](https://github.com/google-gemini/gemini-cli/pull/18009)
-- Fix Esc cancel during streaming by LyalinDotCom in
-  [#18039](https://github.com/google-gemini/gemini-cli/pull/18039)
-- feat(acp): add session resume support by bdmorgan in
-  [#18043](https://github.com/google-gemini/gemini-cli/pull/18043)
-- fix(ci): prevent stale PR closer from incorrectly closing new PRs by bdmorgan
-  in [#18069](https://github.com/google-gemini/gemini-cli/pull/18069)
-- chore: delete autoAccept setting unused in production by victorvianna in
-  [#17862](https://github.com/google-gemini/gemini-cli/pull/17862)
-- feat(plan): use placeholder for choice question "Other" option by jerop in
-  [#18101](https://github.com/google-gemini/gemini-cli/pull/18101)
-- docs: update clearContext to hookSpecificOutput by jackwotherspoon in
-  [#18024](https://github.com/google-gemini/gemini-cli/pull/18024)
-- docs-writer skill: Update docs writer skill by jkcinouye in
-  [#17928](https://github.com/google-gemini/gemini-cli/pull/17928)
-- Sehoon/oncall filter by sehoon38 in
-  [#18105](https://github.com/google-gemini/gemini-cli/pull/18105)
-- feat(core): add setting to disable loop detection by SandyTao520 in
-  [#18008](https://github.com/google-gemini/gemini-cli/pull/18008)
-- Docs: Revise docs/index.md by jkcinouye in
-  [#17879](https://github.com/google-gemini/gemini-cli/pull/17879)
-- Fix up/down arrow regression and add test. by jacob314 in
-  [#18108](https://github.com/google-gemini/gemini-cli/pull/18108)
-- fix(ui): prevent content leak in MaxSizedBox bottom overflow by jerop in
-  [#17991](https://github.com/google-gemini/gemini-cli/pull/17991)
-- refactor: migrate checks.ts utility to core and deduplicate by jerop in
-  [#18139](https://github.com/google-gemini/gemini-cli/pull/18139)
-- feat(core): implement tool name aliasing for backward compatibility by
-  SandyTao520 in
-  [#17974](https://github.com/google-gemini/gemini-cli/pull/17974)
-- docs: fix help-wanted label spelling by pavan-sh in
-  [#18114](https://github.com/google-gemini/gemini-cli/pull/18114)
-- feat(cli): implement automatic theme switching based on terminal background by
+  [#18416](https://github.com/google-gemini/gemini-cli/pull/18416)
+- Shorten temp directory by joshualitt in
+  [#17901](https://github.com/google-gemini/gemini-cli/pull/17901)
+- feat(plan): add behavioral evals for plan mode by jerop in
+  [#18437](https://github.com/google-gemini/gemini-cli/pull/18437)
+- Add extension registry client by chrstnb in
+  [#18396](https://github.com/google-gemini/gemini-cli/pull/18396)
+- Enable extension config by default by chrstnb in
+  [#18447](https://github.com/google-gemini/gemini-cli/pull/18447)
+- Automatically generate change logs on release by g-samroberts in
+  [#18401](https://github.com/google-gemini/gemini-cli/pull/18401)
+- Remove previewFeatures and default to Gemini 3 by sehoon38 in
+  [#18414](https://github.com/google-gemini/gemini-cli/pull/18414)
+- feat(admin): apply MCP allowlist to extensions & gemini mcp list command by
+  skeshive in [#18442](https://github.com/google-gemini/gemini-cli/pull/18442)
+- fix(cli): improve focus navigation for interactive and background shells by
+  galz10 in [#18343](https://github.com/google-gemini/gemini-cli/pull/18343)
+- Add shortcuts hint and panel for discoverability by LyalinDotCom in
+  [#18035](https://github.com/google-gemini/gemini-cli/pull/18035)
+- fix(config): treat system settings as read-only during migration and warn user
+  by spencer426 in
+  [#18277](https://github.com/google-gemini/gemini-cli/pull/18277)
+- feat(plan): add positive test case and update eval stability policy by jerop
+  in [#18457](https://github.com/google-gemini/gemini-cli/pull/18457)
+- fix- windows: add shell: true for spawnSync to fix EINVAL with .cmd editors by
+  zackoch in [#18408](https://github.com/google-gemini/gemini-cli/pull/18408)
+- bug(core): Fix bug when saving plans. by joshualitt in
+  [#18465](https://github.com/google-gemini/gemini-cli/pull/18465)
+- Refactor atCommandProcessor by scidomino in
+  [#18461](https://github.com/google-gemini/gemini-cli/pull/18461)
+- feat(core): implement persistence and resumption for masked tool outputs by
+  abhipatel12 in
+  [#18451](https://github.com/google-gemini/gemini-cli/pull/18451)
+- refactor: simplify tool output truncation to single config by SandyTao520 in
+  [#18446](https://github.com/google-gemini/gemini-cli/pull/18446)
+- bug(core): Ensure storage is initialized early, even if config is not. by
+  joshualitt in [#18471](https://github.com/google-gemini/gemini-cli/pull/18471)
+- chore: Update build-and-start script to support argument forwarding by
   Abhijit-2592 in
-  [#17976](https://github.com/google-gemini/gemini-cli/pull/17976)
-- fix(ide): no-op refactoring that moves the connection logic to helper
-  functions by skeshive in
-  [#18118](https://github.com/google-gemini/gemini-cli/pull/18118)
-- feat: update review-frontend-and-fix slash command to review-and-fix by galz10
-  in [#18146](https://github.com/google-gemini/gemini-cli/pull/18146)
-- fix: improve Ctrl+R reverse search by jackwotherspoon in
-  [#18075](https://github.com/google-gemini/gemini-cli/pull/18075)
-- feat(plan): handle inconsistency in schedulers by Adib234 in
-  [#17813](https://github.com/google-gemini/gemini-cli/pull/17813)
-- feat(plan): add core logic and exit_plan_mode tool definition by jerop in
-  [#18110](https://github.com/google-gemini/gemini-cli/pull/18110)
-- feat(core): rename search_file_content tool to grep_search and add legacy
-  alias by SandyTao520 in
-  [#18003](https://github.com/google-gemini/gemini-cli/pull/18003)
-- fix(core): prioritize detailed error messages for code assist setup by
-  gsquared94 in [#17852](https://github.com/google-gemini/gemini-cli/pull/17852)
-- fix(cli): resolve environment loading and auth validation issues in ACP mode
-  by bdmorgan in
-  [#18025](https://github.com/google-gemini/gemini-cli/pull/18025)
-- feat(core): add .agents/skills directory alias for skill discovery by
+  [#18241](https://github.com/google-gemini/gemini-cli/pull/18241)
+- fix(core): prevent subagent bypass in plan mode by jerop in
+  [#18484](https://github.com/google-gemini/gemini-cli/pull/18484)
+- feat(cli): add WebSocket-based network logging and streaming chunk support by
+  SandyTao520 in
+  [#18383](https://github.com/google-gemini/gemini-cli/pull/18383)
+- feat(cli): update approval modes UI by jerop in
+  [#18476](https://github.com/google-gemini/gemini-cli/pull/18476)
+- fix(cli): reload skills and agents on extension restart by NTaylorMullen in
+  [#18411](https://github.com/google-gemini/gemini-cli/pull/18411)
+- fix(core): expand excludeTools with legacy aliases for renamed tools by
+  SandyTao520 in
+  [#18498](https://github.com/google-gemini/gemini-cli/pull/18498)
+- feat(core): overhaul system prompt for rigor, integrity, and intent alignment
+  by NTaylorMullen in
+  [#17263](https://github.com/google-gemini/gemini-cli/pull/17263)
+- Patch for generate changelog docs yaml file by g-samroberts in
+  [#18496](https://github.com/google-gemini/gemini-cli/pull/18496)
+- Code review fixes for show question mark pr. by jacob314 in
+  [#18480](https://github.com/google-gemini/gemini-cli/pull/18480)
+- fix(cli): add SS3 Shift+Tab support for Windows terminals by ThanhNguyxn in
+  [#18187](https://github.com/google-gemini/gemini-cli/pull/18187)
+- chore: remove redundant planning prompt from final shell by jerop in
+  [#18528](https://github.com/google-gemini/gemini-cli/pull/18528)
+- docs: require pr-creator skill for PR generation by NTaylorMullen in
+  [#18536](https://github.com/google-gemini/gemini-cli/pull/18536)
+- chore: update colors for ask_user dialog by jackwotherspoon in
+  [#18543](https://github.com/google-gemini/gemini-cli/pull/18543)
+- feat(core): exempt high-signal tools from output masking by abhipatel12 in
+  [#18545](https://github.com/google-gemini/gemini-cli/pull/18545)
+- refactor(core): remove memory tool instructions from Gemini 3 prompt by
   NTaylorMullen in
-  [#18151](https://github.com/google-gemini/gemini-cli/pull/18151)
-- chore(core): reassign telemetry keys to avoid server conflict by mattKorwel in
-  [#18161](https://github.com/google-gemini/gemini-cli/pull/18161)
-- Add link to rewind doc in commands.md by Adib234 in
-  [#17961](https://github.com/google-gemini/gemini-cli/pull/17961)
-- feat(core): add draft-2020-12 JSON Schema support with lenient fallback by
-  afarber in [#15060](https://github.com/google-gemini/gemini-cli/pull/15060)
-- refactor(core): robust trimPreservingTrailingNewline and regression test by
+  [#18559](https://github.com/google-gemini/gemini-cli/pull/18559)
+- chore: remove feedback instruction from system prompt by NTaylorMullen in
+  [#18560](https://github.com/google-gemini/gemini-cli/pull/18560)
+- feat(context): add remote configuration for tool output masking thresholds by
+  abhipatel12 in
+  [#18553](https://github.com/google-gemini/gemini-cli/pull/18553)
+- feat(core): pause agent timeout budget while waiting for tool confirmation by
+  abhipatel12 in
+  [#18415](https://github.com/google-gemini/gemini-cli/pull/18415)
+- refactor(config): remove experimental.enableEventDrivenScheduler setting by
+  abhipatel12 in
+  [#17924](https://github.com/google-gemini/gemini-cli/pull/17924)
+- feat(cli): truncate shell output in UI history and improve active shell
+  display by jwhelangoog in
+  [#17438](https://github.com/google-gemini/gemini-cli/pull/17438)
+- refactor(cli): switch useToolScheduler to event-driven engine by abhipatel12
+  in [#18565](https://github.com/google-gemini/gemini-cli/pull/18565)
+- fix(core): correct escaped interpolation in system prompt by NTaylorMullen in
+  [#18557](https://github.com/google-gemini/gemini-cli/pull/18557)
+- propagate abortSignal by scidomino in
+  [#18477](https://github.com/google-gemini/gemini-cli/pull/18477)
+- feat(core): conditionally include ctrl+f prompt based on interactive shell
+  setting by NTaylorMullen in
+  [#18561](https://github.com/google-gemini/gemini-cli/pull/18561)
+- fix(core): ensure enter_plan_mode tool registration respects experimental.plan
+  by jerop in [#18587](https://github.com/google-gemini/gemini-cli/pull/18587)
+- feat(core): transition sub-agents to XML format and improve definitions by
+  NTaylorMullen in
+  [#18555](https://github.com/google-gemini/gemini-cli/pull/18555)
+- docs: Add Plan Mode documentation by jerop in
+  [#18582](https://github.com/google-gemini/gemini-cli/pull/18582)
+- chore: strengthen validation guidance in system prompt by NTaylorMullen in
+  [#18544](https://github.com/google-gemini/gemini-cli/pull/18544)
+- Fix newline insertion bug in replace tool by werdnum in
+  [#18595](https://github.com/google-gemini/gemini-cli/pull/18595)
+- fix(evals): update save_memory evals and simplify tool description by
+  NTaylorMullen in
+  [#18610](https://github.com/google-gemini/gemini-cli/pull/18610)
+- chore(evals): update validation_fidelity_pre_existing_errors to USUALLY_PASSES
+  by NTaylorMullen in
+  [#18617](https://github.com/google-gemini/gemini-cli/pull/18617)
+- fix: shorten tool call IDs and fix duplicate tool name in truncated output
+  filenames by SandyTao520 in
+  [#18600](https://github.com/google-gemini/gemini-cli/pull/18600)
+- feat(cli): implement atomic writes and safety checks for trusted folders by
+  galz10 in [#18406](https://github.com/google-gemini/gemini-cli/pull/18406)
+- Remove relative docs links by chrstnb in
+  [#18650](https://github.com/google-gemini/gemini-cli/pull/18650)
+- docs: add legacy snippets convention to GEMINI.md by NTaylorMullen in
+  [#18597](https://github.com/google-gemini/gemini-cli/pull/18597)
+- fix(chore): Support linting for cjs by aswinashok44 in
+  [#18639](https://github.com/google-gemini/gemini-cli/pull/18639)
+- feat: move shell efficiency guidelines to tool description by NTaylorMullen in
+  [#18614](https://github.com/google-gemini/gemini-cli/pull/18614)
+- Added "" as default value, since getText() used to expect a string only and
+  thus crashed when undefined... Fixes #18076 by 019-Abhi in
+  [#18099](https://github.com/google-gemini/gemini-cli/pull/18099)
+- Allow @-includes outside of workspaces (with permission) by scidomino in
+  [#18470](https://github.com/google-gemini/gemini-cli/pull/18470)
+- chore: make ask_user header description more clear by jackwotherspoon in
+  [#18657](https://github.com/google-gemini/gemini-cli/pull/18657)
+- refactor(core): model-dependent tool definitions by aishaneeshah in
+  [#18563](https://github.com/google-gemini/gemini-cli/pull/18563)
+- Harded code assist converter. by jacob314 in
+  [#18656](https://github.com/google-gemini/gemini-cli/pull/18656)
+- bug(core): Fix minor bug in migration logic. by joshualitt in
+  [#18661](https://github.com/google-gemini/gemini-cli/pull/18661)
+- feat: enable plan mode experiment in settings by jerop in
+  [#18636](https://github.com/google-gemini/gemini-cli/pull/18636)
+- refactor: push isValidPath() into parsePastedPaths() by scidomino in
+  [#18664](https://github.com/google-gemini/gemini-cli/pull/18664)
+- fix(cli): correct 'esc to cancel' position and restore duration display by
+  NTaylorMullen in
+  [#18534](https://github.com/google-gemini/gemini-cli/pull/18534)
+- feat(cli): add DevTools integration with gemini-cli-devtools by SandyTao520 in
+  [#18648](https://github.com/google-gemini/gemini-cli/pull/18648)
+- chore: remove unused exports and redundant hook files by SandyTao520 in
+  [#18681](https://github.com/google-gemini/gemini-cli/pull/18681)
+- Fix number of lines being reported in rewind confirmation dialog by Adib234 in
+  [#18675](https://github.com/google-gemini/gemini-cli/pull/18675)
+- feat(cli): disable folder trust in headless mode by galz10 in
+  [#18407](https://github.com/google-gemini/gemini-cli/pull/18407)
+- Disallow unsafe type assertions by gundermanc in
+  [#18688](https://github.com/google-gemini/gemini-cli/pull/18688)
+- Change event type for release by g-samroberts in
+  [#18693](https://github.com/google-gemini/gemini-cli/pull/18693)
+- feat: handle multiple dynamic context filenames in system prompt by
+  NTaylorMullen in
+  [#18598](https://github.com/google-gemini/gemini-cli/pull/18598)
+- Properly parse at-commands with narrow non-breaking spaces by scidomino in
+  [#18677](https://github.com/google-gemini/gemini-cli/pull/18677)
+- refactor(core): centralize core tool definitions and support model-specific
+  schemas by aishaneeshah in
+  [#18662](https://github.com/google-gemini/gemini-cli/pull/18662)
+- feat(core): Render memory hierarchically in context. by joshualitt in
+  [#18350](https://github.com/google-gemini/gemini-cli/pull/18350)
+- feat: Ctrl+O to expand paste placeholder by jackwotherspoon in
+  [#18103](https://github.com/google-gemini/gemini-cli/pull/18103)
+- fix(cli): Improve header spacing by NTaylorMullen in
+  [#18531](https://github.com/google-gemini/gemini-cli/pull/18531)
+- Feature/quota visibility 16795 by spencer426 in
+  [#18203](https://github.com/google-gemini/gemini-cli/pull/18203)
+- Inline thinking bubbles with summary/full modes by LyalinDotCom in
+  [#18033](https://github.com/google-gemini/gemini-cli/pull/18033)
+- docs: remove TOC marker from Plan Mode header by jerop in
+  [#18678](https://github.com/google-gemini/gemini-cli/pull/18678)
+- fix(ui): remove redundant newlines in Gemini messages by NTaylorMullen in
+  [#18538](https://github.com/google-gemini/gemini-cli/pull/18538)
+- test(cli): fix AppContainer act() warnings and improve waitFor resilience by
+  NTaylorMullen in
+  [#18676](https://github.com/google-gemini/gemini-cli/pull/18676)
+- refactor(core): refine Security & System Integrity section in system prompt by
+  NTaylorMullen in
+  [#18601](https://github.com/google-gemini/gemini-cli/pull/18601)
+- Fix layout rounding. by gundermanc in
+  [#18667](https://github.com/google-gemini/gemini-cli/pull/18667)
+- docs(skills): enhance pr-creator safety and interactivity by NTaylorMullen in
+  [#18616](https://github.com/google-gemini/gemini-cli/pull/18616)
+- test(core): remove hardcoded model from TestRig by NTaylorMullen in
+  [#18710](https://github.com/google-gemini/gemini-cli/pull/18710)
+- feat(core): optimize sub-agents system prompt intro by NTaylorMullen in
+  [#18608](https://github.com/google-gemini/gemini-cli/pull/18608)
+- feat(cli): update approval mode labels and shortcuts per latest UX spec by
+  jerop in [#18698](https://github.com/google-gemini/gemini-cli/pull/18698)
+- fix(plan): update persistent approval mode setting by Adib234 in
+  [#18638](https://github.com/google-gemini/gemini-cli/pull/18638)
+- fix: move toasts location to left side by jackwotherspoon in
+  [#18705](https://github.com/google-gemini/gemini-cli/pull/18705)
+- feat(routing): restrict numerical routing to Gemini 3 family by mattKorwel in
+  [#18478](https://github.com/google-gemini/gemini-cli/pull/18478)
+- fix(ide): fix ide nudge setting by skeshive in
+  [#18733](https://github.com/google-gemini/gemini-cli/pull/18733)
+- fix(core): standardize tool formatting in system prompts by NTaylorMullen in
+  [#18615](https://github.com/google-gemini/gemini-cli/pull/18615)
+- chore: consolidate to green in ask user dialog by jackwotherspoon in
+  [#18734](https://github.com/google-gemini/gemini-cli/pull/18734)
+- feat: add extensionsExplore setting to enable extensions explore UI. by
+  sripasg in [#18686](https://github.com/google-gemini/gemini-cli/pull/18686)
+- feat(cli): defer devtools startup and integrate with F12 by SandyTao520 in
+  [#18695](https://github.com/google-gemini/gemini-cli/pull/18695)
+- ui: update & subdue footer colors and animate progress indicator by
+  keithguerin in
+  [#18570](https://github.com/google-gemini/gemini-cli/pull/18570)
+- test: add model-specific snapshots for coreTools by aishaneeshah in
+  [#18707](https://github.com/google-gemini/gemini-cli/pull/18707)
+- ci: shard windows tests and fix event listener leaks by NTaylorMullen in
+  [#18670](https://github.com/google-gemini/gemini-cli/pull/18670)
+- fix: allow ask_user tool in yolo mode by jackwotherspoon in
+  [#18541](https://github.com/google-gemini/gemini-cli/pull/18541)
+- feat: redact disabled tools from system prompt
+  ([#13597](https://github.com/google-gemini/gemini-cli/pull/13597)) by
+  NTaylorMullen in
+  [#18613](https://github.com/google-gemini/gemini-cli/pull/18613)
+- Update Gemini.md to use the curent year on creating new files by sehoon38 in
+  [#18460](https://github.com/google-gemini/gemini-cli/pull/18460)
+- Code review cleanup for thinking display by jacob314 in
+  [#18720](https://github.com/google-gemini/gemini-cli/pull/18720)
+- fix(cli): hide scrollbars when in alternate buffer copy mode by werdnum in
+  [#18354](https://github.com/google-gemini/gemini-cli/pull/18354)
+- Fix issues with rip grep by gundermanc in
+  [#18756](https://github.com/google-gemini/gemini-cli/pull/18756)
+- fix(cli): fix history navigation regression after prompt autocomplete by
+  sehoon38 in [#18752](https://github.com/google-gemini/gemini-cli/pull/18752)
+- chore: cleanup unused and add unlisted dependencies in packages/cli by
   adamfweidman in
-  [#18196](https://github.com/google-gemini/gemini-cli/pull/18196)
-- Remove MCP servers on extension uninstall by chrstnb in
-  [#18121](https://github.com/google-gemini/gemini-cli/pull/18121)
-- refactor: localize ACP error parsing logic to cli package by bdmorgan in
-  [#18193](https://github.com/google-gemini/gemini-cli/pull/18193)
-- feat(core): Add A2A auth config types by adamfweidman in
-  [#18205](https://github.com/google-gemini/gemini-cli/pull/18205)
-- Set default max attempts to 3 and use the common variable by sehoon38 in
-  [#18209](https://github.com/google-gemini/gemini-cli/pull/18209)
-- feat(plan): add exit_plan_mode ui and prompt by jerop in
-  [#18162](https://github.com/google-gemini/gemini-cli/pull/18162)
-- fix(test): improve test isolation and enable subagent evaluations by
-  cocosheng-g in
-  [#18138](https://github.com/google-gemini/gemini-cli/pull/18138)
-- feat(plan): use custom deny messages in plan mode policies by Adib234 in
-  [#18195](https://github.com/google-gemini/gemini-cli/pull/18195)
-- Match on extension ID when stopping extensions by chrstnb in
-  [#18218](https://github.com/google-gemini/gemini-cli/pull/18218)
-- fix(core): Respect user's .gitignore preference by xyrolle in
-  [#15482](https://github.com/google-gemini/gemini-cli/pull/15482)
-- docs: document GEMINI_CLI_HOME environment variable by adamfweidman in
-  [#18219](https://github.com/google-gemini/gemini-cli/pull/18219)
-- chore(core): explicitly state plan storage path in prompt by jerop in
-  [#18222](https://github.com/google-gemini/gemini-cli/pull/18222)
-- A2a admin setting by DavidAPierce in
-  [#17868](https://github.com/google-gemini/gemini-cli/pull/17868)
-- feat(a2a): Add pluggable auth provider infrastructure by adamfweidman in
-  [#17934](https://github.com/google-gemini/gemini-cli/pull/17934)
-- Fix handling of empty settings by chrstnb in
-  [#18131](https://github.com/google-gemini/gemini-cli/pull/18131)
-- Reload skills when extensions change by chrstnb in
-  [#18225](https://github.com/google-gemini/gemini-cli/pull/18225)
-- feat: Add markdown rendering to ask_user tool by jackwotherspoon in
-  [#18211](https://github.com/google-gemini/gemini-cli/pull/18211)
-- Add telemetry to rewind by Adib234 in
-  [#18122](https://github.com/google-gemini/gemini-cli/pull/18122)
-- feat(admin): add support for MCP configuration via admin controls (pt1) by
-  skeshive in [#18223](https://github.com/google-gemini/gemini-cli/pull/18223)
-- feat(core): require user consent before MCP server OAuth by ehedlund in
-  [#18132](https://github.com/google-gemini/gemini-cli/pull/18132)
-- fix(sandbox): propagate GOOGLE_GEMINI_BASE_URL&GOOGLE_VERTEX_BASE_URL env vars
-  by skeshive in
-  [#18231](https://github.com/google-gemini/gemini-cli/pull/18231)
-- feat(ui): move user identity display to header by sehoon38 in
-  [#18216](https://github.com/google-gemini/gemini-cli/pull/18216)
-- fix: enforce folder trust for workspace settings, skills, and context by
-  galz10 in [#17596](https://github.com/google-gemini/gemini-cli/pull/17596)
+  [#18749](https://github.com/google-gemini/gemini-cli/pull/18749)
+- Fix issue where Gemini CLI creates tests in a new file by gundermanc in
+  [#18409](https://github.com/google-gemini/gemini-cli/pull/18409)
+- feat(telemetry): Ensure experiment IDs are included in OpenTelemetry logs by
+  kevin-ramdass in
+  [#18747](https://github.com/google-gemini/gemini-cli/pull/18747)
 
 **Full changelog**:
-https://github.com/google-gemini/gemini-cli/compare/v0.27.0-preview.8...v0.28.0-preview.0
+https://github.com/google-gemini/gemini-cli/compare/v0.28.0-preview.0...v0.29.0-preview.0

From 099aa9621c530885fd69687953f5b1fe4bf006df Mon Sep 17 00:00:00 2001
From: matt korwel <matt.korwel@gmail.com>
Date: Wed, 11 Feb 2026 20:12:01 -0600
Subject: [PATCH 15/44] fix(core): ensure sub-agents are registered regardless
 of tools.allowed (#18870)

---
 packages/core/src/config/config.test.ts | 38 +++++++++++++++++++++++++
 packages/core/src/config/config.ts      | 24 +++++-----------
 2 files changed, 45 insertions(+), 17 deletions(-)

diff --git a/packages/core/src/config/config.test.ts b/packages/core/src/config/config.test.ts
index 886e722ba0..4a732bbedb 100644
--- a/packages/core/src/config/config.test.ts
+++ b/packages/core/src/config/config.test.ts
@@ -1036,6 +1036,44 @@ describe('Server Config (config.ts)', () => {
       expect(registeredWrappers).toHaveLength(1);
     });
 
+    it('should register subagents as tools even when they are not in allowedTools', async () => {
+      const params: ConfigParameters = {
+        ...baseParams,
+        allowedTools: ['read_file'], // codebase-investigator is NOT here
+        agents: {
+          overrides: {
+            codebase_investigator: { enabled: true },
+          },
+        },
+      };
+      const config = new Config(params);
+
+      const mockAgentDefinition = {
+        name: 'codebase-investigator',
+        description: 'Agent 1',
+        instructions: 'Inst 1',
+      };
+
+      const AgentRegistryMock = (
+        (await vi.importMock('../agents/registry.js')) as {
+          AgentRegistry: Mock;
+        }
+      ).AgentRegistry;
+      AgentRegistryMock.prototype.getAllDefinitions.mockReturnValue([
+        mockAgentDefinition,
+      ]);
+
+      const SubAgentToolMock = (
+        (await vi.importMock('../agents/subagent-tool.js')) as {
+          SubagentTool: Mock;
+        }
+      ).SubagentTool;
+
+      await config.initialize();
+
+      expect(SubAgentToolMock).toHaveBeenCalled();
+    });
+
     it('should not register subagents as tools when agents are disabled', async () => {
       const params: ConfigParameters = {
         ...baseParams,
diff --git a/packages/core/src/config/config.ts b/packages/core/src/config/config.ts
index db4085c1fa..944d14fb39 100644
--- a/packages/core/src/config/config.ts
+++ b/packages/core/src/config/config.ts
@@ -2469,26 +2469,16 @@ export class Config {
       agentsOverrides['codebase_investigator']?.enabled !== false ||
       agentsOverrides['cli_help']?.enabled !== false
     ) {
-      const allowedTools = this.getAllowedTools();
       const definitions = this.agentRegistry.getAllDefinitions();
 
       for (const definition of definitions) {
-        const isAllowed =
-          !allowedTools || allowedTools.includes(definition.name);
-
-        if (isAllowed) {
-          try {
-            const tool = new SubagentTool(
-              definition,
-              this,
-              this.getMessageBus(),
-            );
-            registry.registerTool(tool);
-          } catch (e: unknown) {
-            debugLogger.warn(
-              `Failed to register tool for agent ${definition.name}: ${getErrorMessage(e)}`,
-            );
-          }
+        try {
+          const tool = new SubagentTool(definition, this, this.getMessageBus());
+          registry.registerTool(tool);
+        } catch (e: unknown) {
+          debugLogger.warn(
+            `Failed to register tool for agent ${definition.name}: ${getErrorMessage(e)}`,
+          );
         }
       }
     }

From 2ca183ffc9d2ab38b4835de1b657003963abe643 Mon Sep 17 00:00:00 2001
From: christine betts <chrstn@uw.edu>
Date: Thu, 12 Feb 2026 11:29:06 -0500
Subject: [PATCH 16/44] Show notification when there's a conflict with an
 extensions command (#17890)

---
 packages/cli/src/gemini.tsx                   |   6 +
 .../cli/src/services/CommandService.test.ts   | 113 ++++++++++++++
 packages/cli/src/services/CommandService.ts   |  59 ++++++-
 .../services/SlashCommandConflictHandler.ts   |  54 +++++++
 .../ui/hooks/slashCommandProcessor.test.tsx   | 144 +++++++++++++++++-
 .../cli/src/ui/hooks/slashCommandProcessor.ts |   5 +
 packages/core/src/utils/events.ts             |  18 +++
 7 files changed, 395 insertions(+), 4 deletions(-)
 create mode 100644 packages/cli/src/services/SlashCommandConflictHandler.ts

diff --git a/packages/cli/src/gemini.tsx b/packages/cli/src/gemini.tsx
index e138cfe03a..31e8bd433b 100644
--- a/packages/cli/src/gemini.tsx
+++ b/packages/cli/src/gemini.tsx
@@ -104,6 +104,7 @@ import { TerminalProvider } from './ui/contexts/TerminalContext.js';
 import { setupTerminalAndTheme } from './utils/terminalTheme.js';
 import { profiler } from './ui/components/DebugProfiler.js';
 import { runDeferredCommand } from './deferred.js';
+import { SlashCommandConflictHandler } from './services/SlashCommandConflictHandler.js';
 
 const SLOW_RENDER_MS = 200;
 
@@ -335,6 +336,11 @@ export async function main() {
   });
 
   setupUnhandledRejectionHandler();
+
+  const slashCommandConflictHandler = new SlashCommandConflictHandler();
+  slashCommandConflictHandler.start();
+  registerCleanup(() => slashCommandConflictHandler.stop());
+
   const loadSettingsHandle = startupProfiler.start('load_settings');
   const settings = loadSettings();
   loadSettingsHandle?.end();
diff --git a/packages/cli/src/services/CommandService.test.ts b/packages/cli/src/services/CommandService.test.ts
index 31dfdcace8..ea906a3da6 100644
--- a/packages/cli/src/services/CommandService.test.ts
+++ b/packages/cli/src/services/CommandService.test.ts
@@ -350,4 +350,117 @@ describe('CommandService', () => {
     expect(deployExtension).toBeDefined();
     expect(deployExtension?.description).toBe('[gcp] Deploy to Google Cloud');
   });
+
+  it('should report conflicts via getConflicts', async () => {
+    const builtinCommand = createMockCommand('deploy', CommandKind.BUILT_IN);
+    const extensionCommand = {
+      ...createMockCommand('deploy', CommandKind.FILE),
+      extensionName: 'firebase',
+    };
+
+    const mockLoader = new MockCommandLoader([
+      builtinCommand,
+      extensionCommand,
+    ]);
+
+    const service = await CommandService.create(
+      [mockLoader],
+      new AbortController().signal,
+    );
+
+    const conflicts = service.getConflicts();
+    expect(conflicts).toHaveLength(1);
+
+    expect(conflicts[0]).toMatchObject({
+      name: 'deploy',
+      winner: builtinCommand,
+      losers: [
+        {
+          renamedTo: 'firebase.deploy',
+          command: expect.objectContaining({
+            name: 'deploy',
+            extensionName: 'firebase',
+          }),
+        },
+      ],
+    });
+  });
+
+  it('should report extension vs extension conflicts correctly', async () => {
+    // Both extensions try to register 'deploy'
+    const extension1Command = {
+      ...createMockCommand('deploy', CommandKind.FILE),
+      extensionName: 'firebase',
+    };
+    const extension2Command = {
+      ...createMockCommand('deploy', CommandKind.FILE),
+      extensionName: 'aws',
+    };
+
+    const mockLoader = new MockCommandLoader([
+      extension1Command,
+      extension2Command,
+    ]);
+
+    const service = await CommandService.create(
+      [mockLoader],
+      new AbortController().signal,
+    );
+
+    const conflicts = service.getConflicts();
+    expect(conflicts).toHaveLength(1);
+
+    expect(conflicts[0]).toMatchObject({
+      name: 'deploy',
+      winner: expect.objectContaining({
+        name: 'deploy',
+        extensionName: 'firebase',
+      }),
+      losers: [
+        {
+          renamedTo: 'aws.deploy', // ext2 is 'aws' and it lost because it was second in the list
+          command: expect.objectContaining({
+            name: 'deploy',
+            extensionName: 'aws',
+          }),
+        },
+      ],
+    });
+  });
+
+  it('should report multiple conflicts for the same command name', async () => {
+    const builtinCommand = createMockCommand('deploy', CommandKind.BUILT_IN);
+    const ext1 = {
+      ...createMockCommand('deploy', CommandKind.FILE),
+      extensionName: 'ext1',
+    };
+    const ext2 = {
+      ...createMockCommand('deploy', CommandKind.FILE),
+      extensionName: 'ext2',
+    };
+
+    const mockLoader = new MockCommandLoader([builtinCommand, ext1, ext2]);
+
+    const service = await CommandService.create(
+      [mockLoader],
+      new AbortController().signal,
+    );
+
+    const conflicts = service.getConflicts();
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0].name).toBe('deploy');
+    expect(conflicts[0].losers).toHaveLength(2);
+    expect(conflicts[0].losers).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          renamedTo: 'ext1.deploy',
+          command: expect.objectContaining({ extensionName: 'ext1' }),
+        }),
+        expect.objectContaining({
+          renamedTo: 'ext2.deploy',
+          command: expect.objectContaining({ extensionName: 'ext2' }),
+        }),
+      ]),
+    );
+  });
 });
diff --git a/packages/cli/src/services/CommandService.ts b/packages/cli/src/services/CommandService.ts
index 0e29a81d00..bd42226a32 100644
--- a/packages/cli/src/services/CommandService.ts
+++ b/packages/cli/src/services/CommandService.ts
@@ -4,10 +4,19 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { debugLogger } from '@google/gemini-cli-core';
+import { debugLogger, coreEvents } from '@google/gemini-cli-core';
 import type { SlashCommand } from '../ui/commands/types.js';
 import type { ICommandLoader } from './types.js';
 
+export interface CommandConflict {
+  name: string;
+  winner: SlashCommand;
+  losers: Array<{
+    command: SlashCommand;
+    renamedTo: string;
+  }>;
+}
+
 /**
  * Orchestrates the discovery and loading of all slash commands for the CLI.
  *
@@ -23,8 +32,12 @@ export class CommandService {
   /**
    * Private constructor to enforce the use of the async factory.
    * @param commands A readonly array of the fully loaded and de-duplicated commands.
+   * @param conflicts A readonly array of conflicts that occurred during loading.
    */
-  private constructor(private readonly commands: readonly SlashCommand[]) {}
+  private constructor(
+    private readonly commands: readonly SlashCommand[],
+    private readonly conflicts: readonly CommandConflict[],
+  ) {}
 
   /**
    * Asynchronously creates and initializes a new CommandService instance.
@@ -63,11 +76,14 @@ export class CommandService {
     }
 
     const commandMap = new Map<string, SlashCommand>();
+    const conflictsMap = new Map<string, CommandConflict>();
+
     for (const cmd of allCommands) {
       let finalName = cmd.name;
 
       // Extension commands get renamed if they conflict with existing commands
       if (cmd.extensionName && commandMap.has(cmd.name)) {
+        const winner = commandMap.get(cmd.name)!;
         let renamedName = `${cmd.extensionName}.${cmd.name}`;
         let suffix = 1;
 
@@ -78,6 +94,19 @@ export class CommandService {
         }
 
         finalName = renamedName;
+
+        if (!conflictsMap.has(cmd.name)) {
+          conflictsMap.set(cmd.name, {
+            name: cmd.name,
+            winner,
+            losers: [],
+          });
+        }
+
+        conflictsMap.get(cmd.name)!.losers.push({
+          command: cmd,
+          renamedTo: finalName,
+        });
       }
 
       commandMap.set(finalName, {
@@ -86,8 +115,23 @@ export class CommandService {
       });
     }
 
+    const conflicts = Array.from(conflictsMap.values());
+    if (conflicts.length > 0) {
+      coreEvents.emitSlashCommandConflicts(
+        conflicts.flatMap((c) =>
+          c.losers.map((l) => ({
+            name: c.name,
+            renamedTo: l.renamedTo,
+            loserExtensionName: l.command.extensionName,
+            winnerExtensionName: c.winner.extensionName,
+          })),
+        ),
+      );
+    }
+
     const finalCommands = Object.freeze(Array.from(commandMap.values()));
-    return new CommandService(finalCommands);
+    const finalConflicts = Object.freeze(conflicts);
+    return new CommandService(finalCommands, finalConflicts);
   }
 
   /**
@@ -101,4 +145,13 @@ export class CommandService {
   getCommands(): readonly SlashCommand[] {
     return this.commands;
   }
+
+  /**
+   * Retrieves the list of conflicts that occurred during command loading.
+   *
+   * @returns A readonly array of command conflicts.
+   */
+  getConflicts(): readonly CommandConflict[] {
+    return this.conflicts;
+  }
 }
diff --git a/packages/cli/src/services/SlashCommandConflictHandler.ts b/packages/cli/src/services/SlashCommandConflictHandler.ts
new file mode 100644
index 0000000000..31e110732b
--- /dev/null
+++ b/packages/cli/src/services/SlashCommandConflictHandler.ts
@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  coreEvents,
+  CoreEvent,
+  type SlashCommandConflictsPayload,
+} from '@google/gemini-cli-core';
+
+export class SlashCommandConflictHandler {
+  private notifiedConflicts = new Set<string>();
+
+  constructor() {
+    this.handleConflicts = this.handleConflicts.bind(this);
+  }
+
+  start() {
+    coreEvents.on(CoreEvent.SlashCommandConflicts, this.handleConflicts);
+  }
+
+  stop() {
+    coreEvents.off(CoreEvent.SlashCommandConflicts, this.handleConflicts);
+  }
+
+  private handleConflicts(payload: SlashCommandConflictsPayload) {
+    const newConflicts = payload.conflicts.filter((c) => {
+      const key = `${c.name}:${c.loserExtensionName}`;
+      if (this.notifiedConflicts.has(key)) {
+        return false;
+      }
+      this.notifiedConflicts.add(key);
+      return true;
+    });
+
+    if (newConflicts.length > 0) {
+      const conflictMessages = newConflicts
+        .map((c) => {
+          const winnerSource = c.winnerExtensionName
+            ? `extension '${c.winnerExtensionName}'`
+            : 'an existing command';
+          return `- Command '/${c.name}' from extension '${c.loserExtensionName}' was renamed to '/${c.renamedTo}' because it conflicts with ${winnerSource}.`;
+        })
+        .join('\n');
+
+      coreEvents.emitFeedback(
+        'info',
+        `Command conflicts detected:\n${conflictMessages}`,
+      );
+    }
+  }
+}
diff --git a/packages/cli/src/ui/hooks/slashCommandProcessor.test.tsx b/packages/cli/src/ui/hooks/slashCommandProcessor.test.tsx
index 049720d58a..11f47e12d3 100644
--- a/packages/cli/src/ui/hooks/slashCommandProcessor.test.tsx
+++ b/packages/cli/src/ui/hooks/slashCommandProcessor.test.tsx
@@ -18,10 +18,13 @@ import { FileCommandLoader } from '../../services/FileCommandLoader.js';
 import { McpPromptLoader } from '../../services/McpPromptLoader.js';
 import {
   type GeminiClient,
+  type UserFeedbackPayload,
   SlashCommandStatus,
   makeFakeConfig,
   coreEvents,
+  CoreEvent,
 } from '@google/gemini-cli-core';
+import { SlashCommandConflictHandler } from '../../services/SlashCommandConflictHandler.js';
 
 const {
   logSlashCommand,
@@ -182,6 +185,26 @@ describe('useSlashCommandProcessor', () => {
     mockFileLoadCommands.mockResolvedValue(Object.freeze(fileCommands));
     mockMcpLoadCommands.mockResolvedValue(Object.freeze(mcpCommands));
 
+    const conflictHandler = new SlashCommandConflictHandler();
+    conflictHandler.start();
+
+    const handleFeedback = (payload: UserFeedbackPayload) => {
+      let type = MessageType.INFO;
+      if (payload.severity === 'error') {
+        type = MessageType.ERROR;
+      } else if (payload.severity === 'warning') {
+        type = MessageType.WARNING;
+      }
+      mockAddItem(
+        {
+          type,
+          text: payload.message,
+        },
+        Date.now(),
+      );
+    };
+    coreEvents.on(CoreEvent.UserFeedback, handleFeedback);
+
     let result!: { current: ReturnType<typeof useSlashCommandProcessor> };
     let unmount!: () => void;
     let rerender!: (props?: unknown) => void;
@@ -228,7 +251,11 @@ describe('useSlashCommandProcessor', () => {
       rerender = hook.rerender;
     });
 
-    unmountHook = async () => unmount();
+    unmountHook = async () => {
+      conflictHandler.stop();
+      coreEvents.off(CoreEvent.UserFeedback, handleFeedback);
+      unmount();
+    };
 
     await waitFor(() => {
       expect(result.current.slashCommands).toBeDefined();
@@ -1052,4 +1079,119 @@ describe('useSlashCommandProcessor', () => {
       expect(result.current.slashCommands).toEqual([newCommand]),
     );
   });
+
+  describe('Conflict Notifications', () => {
+    it('should display a warning when a command conflict occurs', async () => {
+      const builtinCommand = createTestCommand({ name: 'deploy' });
+      const extensionCommand = createTestCommand(
+        {
+          name: 'deploy',
+          extensionName: 'firebase',
+        },
+        CommandKind.FILE,
+      );
+
+      const result = await setupProcessorHook({
+        builtinCommands: [builtinCommand],
+        fileCommands: [extensionCommand],
+      });
+
+      await waitFor(() => expect(result.current.slashCommands).toHaveLength(2));
+
+      expect(mockAddItem).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageType.INFO,
+          text: expect.stringContaining('Command conflicts detected'),
+        }),
+        expect.any(Number),
+      );
+
+      expect(mockAddItem).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageType.INFO,
+          text: expect.stringContaining(
+            "- Command '/deploy' from extension 'firebase' was renamed",
+          ),
+        }),
+        expect.any(Number),
+      );
+    });
+
+    it('should deduplicate conflict warnings across re-renders', async () => {
+      const builtinCommand = createTestCommand({ name: 'deploy' });
+      const extensionCommand = createTestCommand(
+        {
+          name: 'deploy',
+          extensionName: 'firebase',
+        },
+        CommandKind.FILE,
+      );
+
+      const result = await setupProcessorHook({
+        builtinCommands: [builtinCommand],
+        fileCommands: [extensionCommand],
+      });
+
+      await waitFor(() => expect(result.current.slashCommands).toHaveLength(2));
+
+      // First notification
+      expect(mockAddItem).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageType.INFO,
+          text: expect.stringContaining('Command conflicts detected'),
+        }),
+        expect.any(Number),
+      );
+
+      mockAddItem.mockClear();
+
+      // Trigger a reload or re-render
+      await act(async () => {
+        result.current.commandContext.ui.reloadCommands();
+      });
+
+      // Wait a bit for effect to run
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Should NOT have notified again
+      expect(mockAddItem).not.toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageType.INFO,
+          text: expect.stringContaining('Command conflicts detected'),
+        }),
+        expect.any(Number),
+      );
+    });
+
+    it('should correctly identify the winner extension in the message', async () => {
+      const ext1Command = createTestCommand(
+        {
+          name: 'deploy',
+          extensionName: 'firebase',
+        },
+        CommandKind.FILE,
+      );
+      const ext2Command = createTestCommand(
+        {
+          name: 'deploy',
+          extensionName: 'aws',
+        },
+        CommandKind.FILE,
+      );
+
+      const result = await setupProcessorHook({
+        fileCommands: [ext1Command, ext2Command],
+      });
+
+      await waitFor(() => expect(result.current.slashCommands).toHaveLength(2));
+
+      expect(mockAddItem).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageType.INFO,
+          text: expect.stringContaining("conflicts with extension 'firebase'"),
+        }),
+        expect.any(Number),
+      );
+    });
+  });
 });
diff --git a/packages/cli/src/ui/hooks/slashCommandProcessor.ts b/packages/cli/src/ui/hooks/slashCommandProcessor.ts
index 7289906a36..2c6c463e42 100644
--- a/packages/cli/src/ui/hooks/slashCommandProcessor.ts
+++ b/packages/cli/src/ui/hooks/slashCommandProcessor.ts
@@ -329,6 +329,11 @@ export const useSlashCommandProcessor = (
         ],
         controller.signal,
       );
+
+      if (controller.signal.aborted) {
+        return;
+      }
+
       setCommands(commandService.getCommands());
     })();
 
diff --git a/packages/core/src/utils/events.ts b/packages/core/src/utils/events.ts
index 5bd3c0f206..8784da07a2 100644
--- a/packages/core/src/utils/events.ts
+++ b/packages/core/src/utils/events.ts
@@ -127,6 +127,17 @@ export interface AgentsDiscoveredPayload {
   agents: AgentDefinition[];
 }
 
+export interface SlashCommandConflict {
+  name: string;
+  renamedTo: string;
+  loserExtensionName?: string;
+  winnerExtensionName?: string;
+}
+
+export interface SlashCommandConflictsPayload {
+  conflicts: SlashCommandConflict[];
+}
+
 /**
  * Payload for the 'quota-changed' event.
  */
@@ -155,6 +166,7 @@ export enum CoreEvent {
   AgentsDiscovered = 'agents-discovered',
   RequestEditorSelection = 'request-editor-selection',
   EditorSelected = 'editor-selected',
+  SlashCommandConflicts = 'slash-command-conflicts',
   QuotaChanged = 'quota-changed',
 }
 
@@ -185,6 +197,7 @@ export interface CoreEvents extends ExtensionEvents {
   [CoreEvent.AgentsDiscovered]: [AgentsDiscoveredPayload];
   [CoreEvent.RequestEditorSelection]: never[];
   [CoreEvent.EditorSelected]: [EditorSelectedPayload];
+  [CoreEvent.SlashCommandConflicts]: [SlashCommandConflictsPayload];
 }
 
 type EventBacklogItem = {
@@ -322,6 +335,11 @@ export class CoreEventEmitter extends EventEmitter<CoreEvents> {
     this._emitOrQueue(CoreEvent.AgentsDiscovered, payload);
   }
 
+  emitSlashCommandConflicts(conflicts: SlashCommandConflict[]): void {
+    const payload: SlashCommandConflictsPayload = { conflicts };
+    this._emitOrQueue(CoreEvent.SlashCommandConflicts, payload);
+  }
+
   /**
    * Notifies subscribers that the quota has changed.
    */

From f603f4a12b36b7835b3f2655d4b1be44ee739658 Mon Sep 17 00:00:00 2001
From: Dmitry Lyalin <dmitry.lyalin@lyalin.com>
Date: Thu, 12 Feb 2026 11:35:40 -0500
Subject: [PATCH 17/44] fix(cli): dismiss '?' shortcuts help on hotkeys and
 active states (#18583)

Co-authored-by: jacob314 <jacob314@gmail.com>
---
 docs/cli/keyboard-shortcuts.md                |   7 +-
 packages/cli/src/ui/AppContainer.test.tsx     | 125 +++++++++++++++++-
 packages/cli/src/ui/AppContainer.tsx          |  36 +++++
 .../cli/src/ui/components/Composer.test.tsx   |  44 +++++-
 packages/cli/src/ui/components/Composer.tsx   |  54 ++++++--
 .../src/ui/components/InputPrompt.test.tsx    |  12 ++
 .../cli/src/ui/components/InputPrompt.tsx     |   5 +
 packages/cli/src/ui/utils/shortcutsHelp.ts    |  12 ++
 8 files changed, 280 insertions(+), 15 deletions(-)
 create mode 100644 packages/cli/src/ui/utils/shortcutsHelp.ts

diff --git a/docs/cli/keyboard-shortcuts.md b/docs/cli/keyboard-shortcuts.md
index d377cfd3e2..91baedc8c9 100644
--- a/docs/cli/keyboard-shortcuts.md
+++ b/docs/cli/keyboard-shortcuts.md
@@ -130,9 +130,10 @@ available combinations.
   terminal isn't configured to send Meta with Option.
 - `!` on an empty prompt: Enter or exit shell mode.
 - `?` on an empty prompt: Toggle the shortcuts panel above the input. Press
-  `Esc`, `Backspace`, or any printable key to close it. Press `?` again to close
-  the panel and insert a `?` into the prompt. You can hide only the hint text
-  via `ui.showShortcutsHint`, without changing this keyboard behavior.
+  `Esc`, `Backspace`, any printable key, or a registered app hotkey to close it.
+  The panel also auto-hides while the agent is running/streaming or when
+  action-required dialogs are shown. Press `?` again to close the panel and
+  insert a `?` into the prompt.
 - `\` (at end of a line) + `Enter`: Insert a newline without leaving single-line
   mode.
 - `Esc` pressed twice quickly: Clear the input prompt if it is not empty,
diff --git a/packages/cli/src/ui/AppContainer.test.tsx b/packages/cli/src/ui/AppContainer.test.tsx
index 0c333176e0..063315f8ac 100644
--- a/packages/cli/src/ui/AppContainer.test.tsx
+++ b/packages/cli/src/ui/AppContainer.test.tsx
@@ -197,7 +197,8 @@ import { useTextBuffer } from './components/shared/text-buffer.js';
 import { useLogger } from './hooks/useLogger.js';
 import { useLoadingIndicator } from './hooks/useLoadingIndicator.js';
 import { useInputHistoryStore } from './hooks/useInputHistoryStore.js';
-import { useKeypress } from './hooks/useKeypress.js';
+import { useKeypress, type Key } from './hooks/useKeypress.js';
+import * as useKeypressModule from './hooks/useKeypress.js';
 import { measureElement } from 'ink';
 import { useTerminalSize } from './hooks/useTerminalSize.js';
 import {
@@ -2091,6 +2092,128 @@ describe('AppContainer State Management', () => {
     });
   });
 
+  describe('Shortcuts Help Visibility', () => {
+    let handleGlobalKeypress: (key: Key) => boolean;
+    let mockedUseKeypress: Mock;
+    let rerender: () => void;
+    let unmount: () => void;
+
+    const setupShortcutsVisibilityTest = async () => {
+      const renderResult = renderAppContainer();
+      await act(async () => {
+        vi.advanceTimersByTime(0);
+      });
+      rerender = () => renderResult.rerender(getAppContainer());
+      unmount = renderResult.unmount;
+    };
+
+    const pressKey = (key: Partial<Key>) => {
+      act(() => {
+        handleGlobalKeypress({
+          name: 'r',
+          shift: false,
+          alt: false,
+          ctrl: false,
+          cmd: false,
+          insertable: false,
+          sequence: '',
+          ...key,
+        } as Key);
+      });
+      rerender();
+    };
+
+    beforeEach(() => {
+      mockedUseKeypress = vi.spyOn(useKeypressModule, 'useKeypress') as Mock;
+      mockedUseKeypress.mockImplementation(
+        (callback: (key: Key) => boolean, options: { isActive: boolean }) => {
+          // AppContainer registers multiple keypress handlers; capture only
+          // active handlers so inactive copy-mode handler doesn't override.
+          if (options?.isActive) {
+            handleGlobalKeypress = callback;
+          }
+        },
+      );
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      mockedUseKeypress.mockRestore();
+      vi.useRealTimers();
+      vi.restoreAllMocks();
+    });
+
+    it('dismisses shortcuts help when a registered hotkey is pressed', async () => {
+      await setupShortcutsVisibilityTest();
+
+      act(() => {
+        capturedUIActions.setShortcutsHelpVisible(true);
+      });
+      rerender();
+      expect(capturedUIState.shortcutsHelpVisible).toBe(true);
+
+      pressKey({ name: 'r', ctrl: true, sequence: '\x12' }); // Ctrl+R
+      expect(capturedUIState.shortcutsHelpVisible).toBe(false);
+
+      unmount();
+    });
+
+    it('dismisses shortcuts help when streaming starts', async () => {
+      await setupShortcutsVisibilityTest();
+
+      act(() => {
+        capturedUIActions.setShortcutsHelpVisible(true);
+      });
+      rerender();
+      expect(capturedUIState.shortcutsHelpVisible).toBe(true);
+
+      mockedUseGeminiStream.mockReturnValue({
+        ...DEFAULT_GEMINI_STREAM_MOCK,
+        streamingState: 'responding',
+      });
+
+      await act(async () => {
+        rerender();
+      });
+      await waitFor(() => {
+        expect(capturedUIState.shortcutsHelpVisible).toBe(false);
+      });
+
+      unmount();
+    });
+
+    it('dismisses shortcuts help when action-required confirmation appears', async () => {
+      await setupShortcutsVisibilityTest();
+
+      act(() => {
+        capturedUIActions.setShortcutsHelpVisible(true);
+      });
+      rerender();
+      expect(capturedUIState.shortcutsHelpVisible).toBe(true);
+
+      mockedUseSlashCommandProcessor.mockReturnValue({
+        handleSlashCommand: vi.fn(),
+        slashCommands: [],
+        pendingHistoryItems: [],
+        commandContext: {},
+        shellConfirmationRequest: null,
+        confirmationRequest: {
+          prompt: 'Confirm this action?',
+          onConfirm: vi.fn(),
+        },
+      });
+
+      await act(async () => {
+        rerender();
+      });
+      await waitFor(() => {
+        expect(capturedUIState.shortcutsHelpVisible).toBe(false);
+      });
+
+      unmount();
+    });
+  });
+
   describe('Copy Mode (CTRL+S)', () => {
     let rerender: () => void;
     let unmount: () => void;
diff --git a/packages/cli/src/ui/AppContainer.tsx b/packages/cli/src/ui/AppContainer.tsx
index 72fdb0ce48..7489d07e2a 100644
--- a/packages/cli/src/ui/AppContainer.tsx
+++ b/packages/cli/src/ui/AppContainer.tsx
@@ -147,6 +147,7 @@ import { isSlashCommand } from './utils/commandUtils.js';
 import { useTerminalTheme } from './hooks/useTerminalTheme.js';
 import { useTimedMessage } from './hooks/useTimedMessage.js';
 import { isITerm2 } from './utils/terminalUtils.js';
+import { shouldDismissShortcutsHelpOnHotkey } from './utils/shortcutsHelp.js';
 
 function isToolExecuting(pendingHistoryItems: HistoryItemWithoutId[]) {
   return pendingHistoryItems.some((item) => {
@@ -1489,6 +1490,10 @@ Logging in with Google... Restarting Gemini CLI to continue.
         debugLogger.log('[DEBUG] Keystroke:', JSON.stringify(key));
       }
 
+      if (shortcutsHelpVisible && shouldDismissShortcutsHelpOnHotkey(key)) {
+        setShortcutsHelpVisible(false);
+      }
+
       if (isAlternateBuffer && keyMatchers[Command.TOGGLE_COPY_MODE](key)) {
         setCopyModeEnabled(true);
         disableMouseEvents();
@@ -1652,6 +1657,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       refreshStatic,
       setCopyModeEnabled,
       isAlternateBuffer,
+      shortcutsHelpVisible,
       backgroundCurrentShell,
       toggleBackgroundShell,
       backgroundShells,
@@ -1811,6 +1817,36 @@ Logging in with Google... Restarting Gemini CLI to continue.
     [pendingSlashCommandHistoryItems, pendingGeminiHistoryItems],
   );
 
+  const hasPendingToolConfirmation = useMemo(
+    () => isToolAwaitingConfirmation(pendingHistoryItems),
+    [pendingHistoryItems],
+  );
+
+  const hasPendingActionRequired =
+    hasPendingToolConfirmation ||
+    !!commandConfirmationRequest ||
+    !!authConsentRequest ||
+    confirmUpdateExtensionRequests.length > 0 ||
+    !!loopDetectionConfirmationRequest ||
+    !!proQuotaRequest ||
+    !!validationRequest ||
+    !!customDialog;
+
+  const isPassiveShortcutsHelpState =
+    isInputActive &&
+    streamingState === StreamingState.Idle &&
+    !hasPendingActionRequired;
+
+  useEffect(() => {
+    if (shortcutsHelpVisible && !isPassiveShortcutsHelpState) {
+      setShortcutsHelpVisible(false);
+    }
+  }, [
+    shortcutsHelpVisible,
+    isPassiveShortcutsHelpState,
+    setShortcutsHelpVisible,
+  ]);
+
   const allToolCalls = useMemo(
     () =>
       pendingHistoryItems
diff --git a/packages/cli/src/ui/components/Composer.test.tsx b/packages/cli/src/ui/components/Composer.test.tsx
index ee3a441c04..1a25d2bb56 100644
--- a/packages/cli/src/ui/components/Composer.test.tsx
+++ b/packages/cli/src/ui/components/Composer.test.tsx
@@ -189,6 +189,7 @@ const createMockUIActions = (): UIActions =>
     setShellModeActive: vi.fn(),
     onEscapePromptChange: vi.fn(),
     vimHandleInput: vi.fn(),
+    setShortcutsHelpVisible: vi.fn(),
   }) as Partial<UIActions> as UIActions;
 
 const createMockConfig = (overrides = {}): Config =>
@@ -337,7 +338,7 @@ describe('Composer', () => {
       expect(output).toContain('LoadingIndicator: Thinking ...');
     });
 
-    it('keeps shortcuts hint visible while loading', () => {
+    it('hides shortcuts hint while loading', () => {
       const uiState = createMockUIState({
         streamingState: StreamingState.Responding,
         elapsedTime: 1,
@@ -347,7 +348,7 @@ describe('Composer', () => {
 
       const output = lastFrame();
       expect(output).toContain('LoadingIndicator');
-      expect(output).toContain('ShortcutsHint');
+      expect(output).not.toContain('ShortcutsHint');
     });
 
     it('renders LoadingIndicator without thought when accessibility disables loading phrases', () => {
@@ -686,4 +687,43 @@ describe('Composer', () => {
       expect(lastFrame()).toContain('ShortcutsHint');
     });
   });
+
+  describe('Shortcuts Help', () => {
+    it('shows shortcuts help in passive state', () => {
+      const uiState = createMockUIState({
+        shortcutsHelpVisible: true,
+        streamingState: StreamingState.Idle,
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+
+      expect(lastFrame()).toContain('ShortcutsHelp');
+    });
+
+    it('hides shortcuts help while streaming', () => {
+      const uiState = createMockUIState({
+        shortcutsHelpVisible: true,
+        streamingState: StreamingState.Responding,
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+
+      expect(lastFrame()).not.toContain('ShortcutsHelp');
+    });
+
+    it('hides shortcuts help when action is required', () => {
+      const uiState = createMockUIState({
+        shortcutsHelpVisible: true,
+        customDialog: (
+          <Box>
+            <Text>Dialog content</Text>
+          </Box>
+        ),
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+
+      expect(lastFrame()).not.toContain('ShortcutsHelp');
+    });
+  });
 });
diff --git a/packages/cli/src/ui/components/Composer.tsx b/packages/cli/src/ui/components/Composer.tsx
index e87e86e801..b5b88b4e15 100644
--- a/packages/cli/src/ui/components/Composer.tsx
+++ b/packages/cli/src/ui/components/Composer.tsx
@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { useState } from 'react';
+import { useState, useEffect, useMemo } from 'react';
 import { Box, useIsScreenReaderEnabled } from 'ink';
 import { LoadingIndicator } from './LoadingIndicator.js';
 import { StatusDisplay } from './StatusDisplay.js';
@@ -28,7 +28,11 @@ import { useVimMode } from '../contexts/VimModeContext.js';
 import { useConfig } from '../contexts/ConfigContext.js';
 import { useSettings } from '../contexts/SettingsContext.js';
 import { useAlternateBuffer } from '../hooks/useAlternateBuffer.js';
-import { StreamingState, ToolCallStatus } from '../types.js';
+import {
+  StreamingState,
+  type HistoryItemToolGroup,
+  ToolCallStatus,
+} from '../types.js';
 import { ConfigInitDisplay } from '../components/ConfigInitDisplay.js';
 import { TodoTray } from './messages/Todo.js';
 import { getInlineThinkingMode } from '../utils/inlineThinkingMode.js';
@@ -51,11 +55,19 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
   const suggestionsPosition = isAlternateBuffer ? 'above' : 'below';
   const hideContextSummary =
     suggestionsVisible && suggestionsPosition === 'above';
-  const hasPendingToolConfirmation = (uiState.pendingHistoryItems ?? []).some(
-    (item) =>
-      item.type === 'tool_group' &&
-      item.tools.some((tool) => tool.status === ToolCallStatus.Confirming),
+
+  const hasPendingToolConfirmation = useMemo(
+    () =>
+      (uiState.pendingHistoryItems ?? [])
+        .filter(
+          (item): item is HistoryItemToolGroup => item.type === 'tool_group',
+        )
+        .some((item) =>
+          item.tools.some((tool) => tool.status === ToolCallStatus.Confirming),
+        ),
+    [uiState.pendingHistoryItems],
   );
+
   const hasPendingActionRequired =
     hasPendingToolConfirmation ||
     Boolean(uiState.commandConfirmationRequest) ||
@@ -65,6 +77,31 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
     Boolean(uiState.quota.proQuotaRequest) ||
     Boolean(uiState.quota.validationRequest) ||
     Boolean(uiState.customDialog);
+  const isPassiveShortcutsHelpState =
+    uiState.isInputActive &&
+    uiState.streamingState === StreamingState.Idle &&
+    !hasPendingActionRequired;
+
+  const { setShortcutsHelpVisible } = uiActions;
+
+  useEffect(() => {
+    if (uiState.shortcutsHelpVisible && !isPassiveShortcutsHelpState) {
+      setShortcutsHelpVisible(false);
+    }
+  }, [
+    uiState.shortcutsHelpVisible,
+    isPassiveShortcutsHelpState,
+    setShortcutsHelpVisible,
+  ]);
+
+  const showShortcutsHelp =
+    uiState.shortcutsHelpVisible &&
+    uiState.streamingState === StreamingState.Idle &&
+    !hasPendingActionRequired;
+  const showShortcutsHint =
+    settings.merged.ui.showShortcutsHint &&
+    uiState.streamingState === StreamingState.Idle &&
+    !hasPendingActionRequired;
   const hasToast = shouldShowToast(uiState);
   const showLoadingIndicator =
     (!uiState.embeddedShellFocused || uiState.isBackgroundShellVisible) &&
@@ -133,11 +170,10 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
             flexDirection="column"
             alignItems={isNarrow ? 'flex-start' : 'flex-end'}
           >
-            {settings.merged.ui.showShortcutsHint &&
-              !hasPendingActionRequired && <ShortcutsHint />}
+            {showShortcutsHint && <ShortcutsHint />}
           </Box>
         </Box>
-        {uiState.shortcutsHelpVisible && <ShortcutsHelp />}
+        {showShortcutsHelp && <ShortcutsHelp />}
         <HorizontalLine />
         <Box
           justifyContent={
diff --git a/packages/cli/src/ui/components/InputPrompt.test.tsx b/packages/cli/src/ui/components/InputPrompt.test.tsx
index 0446f67381..d4d9775f02 100644
--- a/packages/cli/src/ui/components/InputPrompt.test.tsx
+++ b/packages/cli/src/ui/components/InputPrompt.test.tsx
@@ -4342,6 +4342,18 @@ describe('InputPrompt', () => {
           vi.mocked(clipboardy.read).mockResolvedValue('clipboard text');
         },
       },
+      {
+        name: 'Ctrl+R hotkey is pressed',
+        input: '\x12',
+      },
+      {
+        name: 'Ctrl+X hotkey is pressed',
+        input: '\x18',
+      },
+      {
+        name: 'F12 hotkey is pressed',
+        input: '\x1b[24~',
+      },
     ])(
       'should close shortcuts help when a $name',
       async ({ input, setupMocks, mouseEventsEnabled }) => {
diff --git a/packages/cli/src/ui/components/InputPrompt.tsx b/packages/cli/src/ui/components/InputPrompt.tsx
index f2f23f5506..22fd317c10 100644
--- a/packages/cli/src/ui/components/InputPrompt.tsx
+++ b/packages/cli/src/ui/components/InputPrompt.tsx
@@ -75,6 +75,7 @@ import { useMouseClick } from '../hooks/useMouseClick.js';
 import { useMouse, type MouseEvent } from '../contexts/MouseContext.js';
 import { useUIActions } from '../contexts/UIActionsContext.js';
 import { useAlternateBuffer } from '../hooks/useAlternateBuffer.js';
+import { shouldDismissShortcutsHelpOnHotkey } from '../utils/shortcutsHelp.js';
 
 /**
  * Returns if the terminal can be trusted to handle paste events atomically
@@ -661,6 +662,10 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
         return true;
       }
 
+      if (shortcutsHelpVisible && shouldDismissShortcutsHelpOnHotkey(key)) {
+        setShortcutsHelpVisible(false);
+      }
+
       if (shortcutsHelpVisible) {
         if (key.sequence === '?' && key.insertable) {
           setShortcutsHelpVisible(false);
diff --git a/packages/cli/src/ui/utils/shortcutsHelp.ts b/packages/cli/src/ui/utils/shortcutsHelp.ts
new file mode 100644
index 0000000000..65ab8f2a13
--- /dev/null
+++ b/packages/cli/src/ui/utils/shortcutsHelp.ts
@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Command, keyMatchers } from '../keyMatchers.js';
+import type { Key } from '../hooks/useKeypress.js';
+
+export function shouldDismissShortcutsHelpOnHotkey(key: Key): boolean {
+  return Object.values(Command).some((command) => keyMatchers[command](key));
+}

From ddcfe5b1f2de77c708b5b4c1c3b3cb6d88740abe Mon Sep 17 00:00:00 2001
From: Abhijit Balaji <abhijitbalaji@google.com>
Date: Thu, 12 Feb 2026 09:04:39 -0800
Subject: [PATCH 18/44] fix(core): prioritize conditional policy rules and
 harden Plan Mode (#18882)

---
 .../core/src/policy/policy-engine.test.ts     | 113 ++++++++++++++++--
 packages/core/src/policy/policy-engine.ts     |   4 +-
 2 files changed, 108 insertions(+), 9 deletions(-)

diff --git a/packages/core/src/policy/policy-engine.test.ts b/packages/core/src/policy/policy-engine.test.ts
index 26aecaa1eb..693ae3a4b2 100644
--- a/packages/core/src/policy/policy-engine.test.ts
+++ b/packages/core/src/policy/policy-engine.test.ts
@@ -2046,33 +2046,91 @@ describe('PolicyEngine', () => {
         rules: [],
         expected: [],
       },
+      {
+        name: 'should apply rules without explicit modes to all modes',
+        rules: [{ toolName: 'tool1', decision: PolicyDecision.DENY }],
+        expected: ['tool1'],
+      },
+      {
+        name: 'should NOT exclude tool if higher priority argsPattern rule exists',
+        rules: [
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.ALLOW,
+            argsPattern: /safe/,
+            priority: 100,
+            modes: [ApprovalMode.DEFAULT],
+          },
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.DENY,
+            priority: 10,
+            modes: [ApprovalMode.DEFAULT],
+          },
+        ],
+        expected: [],
+      },
       {
         name: 'should include tools with DENY decision',
         rules: [
-          { toolName: 'tool1', decision: PolicyDecision.DENY },
-          { toolName: 'tool2', decision: PolicyDecision.ALLOW },
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.DENY,
+            modes: [ApprovalMode.DEFAULT],
+          },
+          {
+            toolName: 'tool2',
+            decision: PolicyDecision.ALLOW,
+            modes: [ApprovalMode.DEFAULT],
+          },
         ],
         expected: ['tool1'],
       },
       {
         name: 'should respect priority and ignore lower priority rules (DENY wins)',
         rules: [
-          { toolName: 'tool1', decision: PolicyDecision.DENY, priority: 100 },
-          { toolName: 'tool1', decision: PolicyDecision.ALLOW, priority: 10 },
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.DENY,
+            priority: 100,
+            modes: [ApprovalMode.DEFAULT],
+          },
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.ALLOW,
+            priority: 10,
+            modes: [ApprovalMode.DEFAULT],
+          },
         ],
         expected: ['tool1'],
       },
       {
         name: 'should respect priority and ignore lower priority rules (ALLOW wins)',
         rules: [
-          { toolName: 'tool1', decision: PolicyDecision.ALLOW, priority: 100 },
-          { toolName: 'tool1', decision: PolicyDecision.DENY, priority: 10 },
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.ALLOW,
+            priority: 100,
+            modes: [ApprovalMode.DEFAULT],
+          },
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.DENY,
+            priority: 10,
+            modes: [ApprovalMode.DEFAULT],
+          },
         ],
         expected: [],
       },
       {
         name: 'should NOT include ASK_USER tools even in non-interactive mode',
-        rules: [{ toolName: 'tool1', decision: PolicyDecision.ASK_USER }],
+        rules: [
+          {
+            toolName: 'tool1',
+            decision: PolicyDecision.ASK_USER,
+            modes: [ApprovalMode.DEFAULT],
+          },
+        ],
         nonInteractive: true,
         expected: [],
       },
@@ -2083,6 +2141,7 @@ describe('PolicyEngine', () => {
             toolName: 'tool1',
             decision: PolicyDecision.DENY,
             argsPattern: /something/,
+            modes: [ApprovalMode.DEFAULT],
           },
         ],
         expected: [],
@@ -2123,6 +2182,7 @@ describe('PolicyEngine', () => {
             toolName: 'dangerous-tool',
             decision: PolicyDecision.DENY,
             priority: 10,
+            modes: [ApprovalMode.YOLO],
           },
         ],
         approvalMode: ApprovalMode.YOLO,
@@ -2130,7 +2190,13 @@ describe('PolicyEngine', () => {
       },
       {
         name: 'should respect server wildcard DENY',
-        rules: [{ toolName: 'server__*', decision: PolicyDecision.DENY }],
+        rules: [
+          {
+            toolName: 'server__*',
+            decision: PolicyDecision.DENY,
+            modes: [ApprovalMode.DEFAULT],
+          },
+        ],
         expected: ['server__*'],
       },
       {
@@ -2140,15 +2206,44 @@ describe('PolicyEngine', () => {
             toolName: 'server__*',
             decision: PolicyDecision.DENY,
             priority: 100,
+            modes: [ApprovalMode.DEFAULT],
           },
           {
             toolName: 'server__tool1',
             decision: PolicyDecision.DENY,
             priority: 10,
+            modes: [ApprovalMode.DEFAULT],
           },
         ],
         expected: ['server__*', 'server__tool1'],
       },
+      {
+        name: 'should exclude run_shell_command but NOT write_file in simulated Plan Mode',
+        approvalMode: ApprovalMode.PLAN,
+        rules: [
+          {
+            // Simulates the high-priority allow for plans directory
+            toolName: 'write_file',
+            decision: PolicyDecision.ALLOW,
+            priority: 70,
+            argsPattern: /plans/,
+            modes: [ApprovalMode.PLAN],
+          },
+          {
+            // Simulates the global deny in Plan Mode
+            decision: PolicyDecision.DENY,
+            priority: 60,
+            modes: [ApprovalMode.PLAN],
+          },
+          {
+            // Simulates a tool from another policy (e.g. write.toml)
+            toolName: 'run_shell_command',
+            decision: PolicyDecision.ASK_USER,
+            priority: 10,
+          },
+        ],
+        expected: ['run_shell_command'],
+      },
       {
         name: 'should NOT exclude tool if covered by a higher priority wildcard ALLOW',
         rules: [
@@ -2156,11 +2251,13 @@ describe('PolicyEngine', () => {
             toolName: 'server__*',
             decision: PolicyDecision.ALLOW,
             priority: 100,
+            modes: [ApprovalMode.DEFAULT],
           },
           {
             toolName: 'server__tool1',
             decision: PolicyDecision.DENY,
             priority: 10,
+            modes: [ApprovalMode.DEFAULT],
           },
         ],
         expected: [],
diff --git a/packages/core/src/policy/policy-engine.ts b/packages/core/src/policy/policy-engine.ts
index 1fc5e7cde5..3f386edd8f 100644
--- a/packages/core/src/policy/policy-engine.ts
+++ b/packages/core/src/policy/policy-engine.ts
@@ -538,8 +538,10 @@ export class PolicyEngine {
     let globalVerdict: PolicyDecision | undefined;
 
     for (const rule of this.rules) {
-      // We only care about rules without args pattern for exclusion from the model
       if (rule.argsPattern) {
+        if (rule.toolName && rule.decision !== PolicyDecision.DENY) {
+          processedTools.add(rule.toolName);
+        }
         continue;
       }
 

From 27a1bae03bc50657475bc0a31c6407a4a13a610a Mon Sep 17 00:00:00 2001
From: "N. Taylor Mullen" <ntaylormullen@google.com>
Date: Thu, 12 Feb 2026 09:37:47 -0800
Subject: [PATCH 19/44] feat(core): refine Plan Mode system prompt for agentic
 execution (#18799)

---
 .../core/__snapshots__/prompts.test.ts.snap   | 136 ++++++++---------
 packages/core/src/core/prompts.test.ts        |   2 +-
 packages/core/src/prompts/promptProvider.ts   |   4 +-
 packages/core/src/prompts/snippets.ts         | 138 ++++++++----------
 4 files changed, 125 insertions(+), 155 deletions(-)

diff --git a/packages/core/src/core/__snapshots__/prompts.test.ts.snap b/packages/core/src/core/__snapshots__/prompts.test.ts.snap
index e944565366..ed79a3a497 100644
--- a/packages/core/src/core/__snapshots__/prompts.test.ts.snap
+++ b/packages/core/src/core/__snapshots__/prompts.test.ts.snap
@@ -42,8 +42,8 @@ You are operating in **Plan Mode** - a structured planning workflow for designin
 
 ## Available Tools
 The following read-only tools are available in Plan Mode:
-- \`glob\`
-- \`grep_search\`
+  <tool>\`glob\`</tool>
+  <tool>\`grep_search\`</tool>
 - \`write_file\` - Save plans to the plans directory (see Plan Storage below)
 - \`replace\` - Update plans in the plans directory
 
@@ -173,8 +173,8 @@ You are operating in **Plan Mode** - a structured planning workflow for designin
 
 ## Available Tools
 The following read-only tools are available in Plan Mode:
-- \`glob\`
-- \`grep_search\`
+  <tool>\`glob\`</tool>
+  <tool>\`grep_search\`</tool>
 - \`write_file\` - Save plans to the plans directory (see Plan Storage below)
 - \`replace\` - Update plans in the plans directory
 
@@ -421,8 +421,8 @@ You are operating in **Plan Mode** - a structured planning workflow for designin
 
 ## Available Tools
 The following read-only tools are available in Plan Mode:
-- \`glob\`
-- \`grep_search\`
+  <tool>\`glob\`</tool>
+  <tool>\`grep_search\`</tool>
 - \`write_file\` - Save plans to the plans directory (see Plan Storage below)
 - \`replace\` - Update plans in the plans directory
 
@@ -580,7 +580,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype.
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user and obtain their approval before proceeding. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns).
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -588,10 +588,9 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
+4. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
+5. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
 
 # Operational Guidelines
 
@@ -695,7 +694,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets, describe the strategy for sourcing or generating placeholders.
+2. **Plan:** Formulate an internal development plan. For applications requiring visual assets, describe the strategy for sourcing or generating placeholders.
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested.
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -703,7 +702,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. Implementation: Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\`. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons). Never link to external services or assume local paths for assets that have not been created.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\`. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons). Never link to external services or assume local paths for assets that have not been created.
 4. **Verify:** Review work against the original request. Fix bugs and deviations. **Build the application and ensure there are no compile errors.**
 
 # Operational Guidelines
@@ -791,7 +790,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets, describe the strategy for sourcing or generating placeholders.
+2. **Plan:** Formulate an internal development plan. For applications requiring visual assets, describe the strategy for sourcing or generating placeholders.
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested.
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -799,7 +798,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. Implementation: Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\`. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons). Never link to external services or assume local paths for assets that have not been created.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\`. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons). Never link to external services or assume local paths for assets that have not been created.
 4. **Verify:** Review work against the original request. Fix bugs and deviations. **Build the application and ensure there are no compile errors.**
 
 # Operational Guidelines
@@ -1385,7 +1384,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype.
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user and obtain their approval before proceeding. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns).
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -1393,10 +1392,9 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
+4. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
+5. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
 
 # Operational Guidelines
 
@@ -1499,7 +1497,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype.
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user and obtain their approval before proceeding. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns).
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -1507,10 +1505,9 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
+4. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
+5. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
 
 # Operational Guidelines
 
@@ -1617,7 +1614,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype.
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user and obtain their approval before proceeding. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns).
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -1625,10 +1622,9 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
+4. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
+5. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
 
 # Operational Guidelines
 
@@ -1735,7 +1731,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype.
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user and obtain their approval before proceeding. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns).
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -1743,10 +1739,9 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
+4. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
+5. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
 
 # Operational Guidelines
 
@@ -1835,7 +1830,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use search tools extensively to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.** For complex tasks, consider using the \`enter_plan_mode\` tool to enter a dedicated planning phase before starting implementation.
+1. **Research:** Systematically map the codebase and validate assumptions. Use search tools extensively to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.** If the request is ambiguous, broad in scope, or involves creating a new feature/application, you MUST use the \`enter_plan_mode\` tool to design your approach before making changes. Do NOT use Plan Mode for straightforward bug fixes, answering questions, or simple inquiries.
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -1848,19 +1843,17 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
-1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype. For complex tasks, consider using the \`enter_plan_mode\` tool to enter a dedicated planning phase before starting implementation.
-   - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
-   - **Default Tech Stack:**
-     - **Web:** React (TypeScript) or Angular with Vanilla CSS.
-     - **APIs:** Node.js (Express) or Python (FastAPI).
-     - **Mobile:** Compose Multiplatform or Flutter.
-     - **Games:** HTML/CSS/JS (Three.js for 3D).
-     - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
+1. **Mandatory Planning:** You MUST use the \`enter_plan_mode\` tool to draft a comprehensive design document and obtain user approval before writing any code.
+2. **Design Constraints:** When drafting your plan, adhere to these defaults unless explicitly overridden by the user:
+   - **Goal:** Autonomously design a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, typography, and interactive feedback.
+   - **Visuals:** Describe your strategy for sourcing or generating placeholders (e.g., stylized CSS shapes, gradients, procedurally generated patterns) to ensure a visually complete prototype. Never plan for assets that cannot be locally generated.
+   - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested.
+   - **Web:** React (TypeScript) or Angular with Vanilla CSS.
+   - **APIs:** Node.js (Express) or Python (FastAPI).
+   - **Mobile:** Compose Multiplatform or Flutter.
+   - **Games:** HTML/CSS/JS (Three.js for 3D).
+   - **CLIs:** Python or Go.
+3. **Implementation:** Once the plan is approved, follow the standard **Execution** cycle to build the application, utilizing platform-native primitives to realize the rich aesthetic you planned.
 
 # Operational Guidelines
 
@@ -1963,7 +1956,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype.
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user and obtain their approval before proceeding. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns).
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -1971,10 +1964,9 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
+4. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
+5. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
 
 # Operational Guidelines
 
@@ -2316,7 +2308,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype.
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user and obtain their approval before proceeding. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns).
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -2324,10 +2316,9 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
+4. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
+5. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
 
 # Operational Guidelines
 
@@ -2430,7 +2421,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype.
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user and obtain their approval before proceeding. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns).
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -2438,10 +2429,9 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
+4. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
+5. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
 
 # Operational Guidelines
 
@@ -2655,7 +2645,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype.
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user and obtain their approval before proceeding. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns).
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -2663,10 +2653,9 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
+4. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
+5. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
 
 # Operational Guidelines
 
@@ -2769,7 +2758,7 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 **Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, interactive feedback, and platform-appropriate design.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype.
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user and obtain their approval before proceeding. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns).
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -2777,10 +2766,9 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using \`run_shell_command\` for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
+4. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
+5. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.
 
 # Operational Guidelines
 
diff --git a/packages/core/src/core/prompts.test.ts b/packages/core/src/core/prompts.test.ts
index 8f2739c389..54f8250fc7 100644
--- a/packages/core/src/core/prompts.test.ts
+++ b/packages/core/src/core/prompts.test.ts
@@ -612,7 +612,7 @@ describe('Core System Prompt (prompts.ts)', () => {
     const prompt = getCoreSystemPrompt(mockConfig);
 
     expect(prompt).toContain(
-      'For complex tasks, consider using the `enter_plan_mode` tool to enter a dedicated planning phase before starting implementation.',
+      'If the request is ambiguous, broad in scope, or involves creating a new feature/application, you MUST use the `enter_plan_mode` tool to design your approach before making changes. Do NOT use Plan Mode for straightforward bug fixes, answering questions, or simple inquiries.',
     );
     expect(prompt).toMatchSnapshot();
   });
diff --git a/packages/core/src/prompts/promptProvider.ts b/packages/core/src/prompts/promptProvider.ts
index 47f7e936cf..51224555cf 100644
--- a/packages/core/src/prompts/promptProvider.ts
+++ b/packages/core/src/prompts/promptProvider.ts
@@ -67,7 +67,7 @@ export class PromptProvider {
     let planModeToolsList = PLAN_MODE_TOOLS.filter((t) =>
       enabledToolNames.has(t),
     )
-      .map((t) => `- \`${t}\``)
+      .map((t) => `  <tool>\`${t}\`</tool>`)
       .join('\n');
 
     // Add read-only MCP tools to the list
@@ -79,7 +79,7 @@ export class PromptProvider {
       );
       if (readOnlyMcpTools.length > 0) {
         const mcpToolsList = readOnlyMcpTools
-          .map((t) => `- \`${t.name}\` (${t.serverName})`)
+          .map((t) => `  <tool>\`${t.name}\` (${t.serverName})</tool>`)
           .join('\n');
         planModeToolsList += `\n${mcpToolsList}`;
       }
diff --git a/packages/core/src/prompts/snippets.ts b/packages/core/src/prompts/snippets.ts
index 3dcf346de6..bd062373df 100644
--- a/packages/core/src/prompts/snippets.ts
+++ b/packages/core/src/prompts/snippets.ts
@@ -419,78 +419,48 @@ export function renderPlanningWorkflow(
   return `
 # Active Approval Mode: Plan
 
-You are operating in **Plan Mode** - a structured planning workflow for designing implementation strategies before execution.
+You are operating in **Plan Mode**. Your goal is to produce a detailed implementation plan in \`${options.plansDir}/\` and get user approval before editing source code.
 
 ## Available Tools
 The following read-only tools are available in Plan Mode:
+<available_tools>
 ${options.planModeToolsList}
-- ${formatToolName(WRITE_FILE_TOOL_NAME)} - Save plans to the plans directory (see Plan Storage below)
-- ${formatToolName(EDIT_TOOL_NAME)} - Update plans in the plans directory
+  <tool>${formatToolName(WRITE_FILE_TOOL_NAME)} - Save plans to the plans directory</tool>
+  <tool>${formatToolName(EDIT_TOOL_NAME)} - Update plans in the plans directory</tool>
+</available_tools>
 
-## Plan Storage
-- Save your plans as Markdown (.md) files ONLY within: \`${options.plansDir}/\`
-- You are restricted to writing files within this directory while in Plan Mode.
-- Use descriptive filenames: \`feature-name.md\` or \`bugfix-description.md\`
+## Rules
+1. **Read-Only:** You cannot modify source code. You may ONLY use read-only tools to explore, and you can only write to \`${options.plansDir}/\`.
+2. **Efficiency:** Autonomously combine discovery and drafting phases to minimize conversational turns. If the request is ambiguous, use ${formatToolName(ASK_USER_TOOL_NAME)} to clarify. Otherwise, explore the codebase and write the draft in one fluid motion.
+3. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames (e.g., \`feature-x.md\`).
 
-## Workflow Rules
-1.  Sequential Execution: Complete ONE phase at a time. Do NOT skip ahead or combine phases.
-2.  User Confirmation: Wait for user input/approval before proceeding to the next phase.
-3.  Step Back Protocol: If new information discovered during Exploration or Design invalidates previous assumptions or requirements, you MUST pause, inform the user, and request to return to the appropriate previous phase.
+## Required Plan Structure
+When writing the plan file, you MUST include the following structure:
+  # Objective
+  (A concise summary of what needs to be built or fixed)
+  # Key Files & Context
+  (List the specific files that will be modified, including helpful context like function signatures or code snippets)
+  # Implementation Steps
+  (Iterative development steps, e.g., "1. Implement X in [File]", "2. Verify with test Y")
+  # Verification & Testing
+  (Specific unit tests, manual checks, or build commands to verify success)
 
-## Workflow Phases
+## Workflow
+1. **Explore & Analyze:** Analyze requirements and use search/read tools to explore the codebase. For complex tasks, identify at least two viable implementation approaches.
+2. **Consult:** Present a concise summary of the identified approaches (including pros/cons and your recommendation) to the user via ${formatToolName(ASK_USER_TOOL_NAME)} and wait for their selection. For simple or canonical tasks, you may skip this and proceed to drafting.
+3. **Draft:** Write the detailed implementation plan for the selected approach to the plans directory using ${formatToolName(WRITE_FILE_TOOL_NAME)}.
+4. **Review & Approval:** Present a brief summary of the drafted plan in your chat response and concurrently call the ${formatToolName(EXIT_PLAN_MODE_TOOL_NAME)} tool to formally request approval. If rejected, iterate.
 
-### Phase 1: Requirements
-- Analyze the user's request to identify core requirements and constraints.
-- Proactively identify ambiguities, implicit assumptions, and edge cases.
-- Categorize questions: functional requirements, non-functional constraints (performance, compatibility), and scope boundaries.
-- Use the ${formatToolName(ASK_USER_TOOL_NAME)} tool with well-structured options to clarify ambiguities. Prefer providing multiple-choice options for the user to select from when possible.
-
-### Phase 2: Exploration
-- Only begin this phase after requirements are clear.
-- Use the available read-only tools to explore the project.
-- Map relevant code paths, dependencies, and architectural patterns.
-- Identify existing utilities, patterns, and abstractions that can be reused.
-- Note potential constraints (e.g., existing conventions, test infrastructure).
-- Output: Summarize key findings to the user before proceeding to design.
-
-### Phase 3: Design
-- Only begin this phase after exploration is complete.
-- **Identify Approaches:**
-    - For Complex Tasks: Identify at least 2 viable implementation approaches. Document the approach summary, pros, cons, complexity estimate, and risk factors for each.
-    - For Canonical Tasks: If there is only one reasonable, standard approach (e.g., a standard library pattern or specific bug fix), detail it and explicitly explain why no other viable alternatives were considered.
-- Mandatory User Interaction: Present the analysis to the user via ${formatToolName(ASK_USER_TOOL_NAME)} and recommend a preferred approach.
-- Wait for Selection: You MUST pause and wait for the user to select an approach before proceeding. Do NOT assume the user will agree with your recommendation.
-
-### Phase 4: Planning
-- Pre-requisite: You MUST have a user-selected approach from Phase 3 before generating the plan.
-- Create a detailed implementation plan and save it to the designated plans directory.
-- **Document Structure:** The plan MUST be a structured Markdown document (focused on implementation guidance, not workflow logging) using exactly these H2 headings:
-  - \`## Problem Statement\` - Describe the problem or need this change addresses.
-  - \`## Proposed Solution\` - Provide technical details of the implementation.
-  - \`## Implementation Plan\` - List ordered steps with specific file paths and the nature of each change.
-  - \`## Verification Plan\` - Define specific tests or manual steps to verify the change works and breaks nothing else.
-  - \`## Risks & Mitigations\` - Identify potential failure modes and mitigation strategies.
-  - \`## Alternatives Considered\` - Provide a brief analysis of other approaches considered and why they were rejected.
-
-### Phase 5: Approval
-- Present the plan and request approval for the finalized plan using the ${formatToolName(EXIT_PLAN_MODE_TOOL_NAME)} tool
-- If plan is approved, you can begin implementation.
-- If plan is rejected, address the feedback and iterate on the plan.
-
-${renderApprovedPlanSection(options.approvedPlanPath)}
-
-## Constraints
-- You may ONLY use the read-only tools listed above
-- You MUST NOT modify source code, configs, or any files
-- If asked to modify code, explain you are in Plan Mode and suggest exiting Plan Mode to enable edits`.trim();
+${renderApprovedPlanSection(options.approvedPlanPath)}`.trim();
 }
 
 function renderApprovedPlanSection(approvedPlanPath?: string): string {
   if (!approvedPlanPath) return '';
   return `## Approved Plan
-An approved plan is available for this task.
-- **Iterate:** You should default to refining the existing approved plan.
-- **New Plan:** Only create a new plan file if the user explicitly asks for a "new plan" or if the current request is for a completely different feature or bug.
+An approved plan is available for this task at \`${approvedPlanPath}\`.
+- **Read First:** You MUST read this file using the ${formatToolName(READ_FILE_TOOL_NAME)} tool before proposing any changes or starting discovery.
+- **Iterate:** Default to refining the existing approved plan.
+- **New Plan:** Only create a new plan file if the user explicitly asks for a "new plan".
 `;
 }
 
@@ -528,7 +498,7 @@ function mandateContinueWork(interactive: boolean): string {
 function workflowStepResearch(options: PrimaryWorkflowsOptions): string {
   let suggestion = '';
   if (options.enableEnterPlanModeTool) {
-    suggestion = ` For complex tasks, consider using the ${formatToolName(ENTER_PLAN_MODE_TOOL_NAME)} tool to enter a dedicated planning phase before starting implementation.`;
+    suggestion = ` If the request is ambiguous, broad in scope, or involves creating a new feature/application, you MUST use the ${formatToolName(ENTER_PLAN_MODE_TOOL_NAME)} tool to design your approach before making changes. Do NOT use Plan Mode for straightforward bug fixes, answering questions, or simple inquiries.`;
   }
 
   const searchTools: string[] = [];
@@ -558,7 +528,7 @@ function workflowStepResearch(options: PrimaryWorkflowsOptions): string {
 
 function workflowStepStrategy(options: PrimaryWorkflowsOptions): string {
   if (options.approvedPlan) {
-    return `2. **Strategy:** An approved plan is available for this task. Use this file as a guide for your implementation. You MUST read this file before proceeding. If you discover new requirements or need to change the approach, confirm with the user and update this plan file to reflect the updated design decisions or discovered requirements.`;
+    return `2. **Strategy:** An approved plan is available for this task. Treat this file as your single source of truth. You MUST read this file before proceeding. If you discover new requirements or need to change the approach, confirm with the user and update this plan file to reflect the updated design decisions or discovered requirements.`;
   }
 
   if (options.enableWriteTodosTool) {
@@ -582,16 +552,35 @@ function newApplicationSteps(options: PrimaryWorkflowsOptions): string {
 
   if (options.approvedPlan) {
     return `
-1. **Understand:** Read the approved plan. Use this file as a guide for your implementation.
-2. **Implement:** Implement the application according to the plan. If you discover new requirements or need to change the approach, confirm with the user and update this plan file to reflect the updated design decisions or discovered requirements.
-3. **Verify:** Review work against the original request, the approved plan. Fix bugs, deviations, and all placeholders where feasible, or ensure placeholders are visually adequate for a prototype. Ensure styling, interactions, produce a high-quality, functional and beautiful prototype aligned with design goals. Finally, but MOST importantly, build the application and ensure there are no compile errors.
+1. **Understand:** Read the approved plan. Treat this file as your single source of truth.
+2. **Implement:** Implement the application according to the plan. When starting, scaffold the application using ${formatToolName(SHELL_TOOL_NAME)}. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, CSS animations, icons) to ensure a complete, rich, and coherent experience. Never link to external services or assume local paths for assets that have not been created. If you discover new requirements or need to change the approach, confirm with the user and update the plan file.
+3. **Verify:** Review work against the original request and the approved plan. Fix bugs, deviations, and ensure placeholders are visually adequate. **Ensure styling and interactions produce a high-quality, polished, and beautiful prototype.** Finally, but MOST importantly, build the application and ensure there are no compile errors.
 4. **Finish:** Provide a brief summary of what was built.`.trim();
   }
 
+  // When Plan Mode is enabled globally, mandate its use for new apps and let the
+  // standard 'Execution' loop handle implementation once the plan is approved.
+  if (options.enableEnterPlanModeTool) {
+    return `
+1. **Mandatory Planning:** You MUST use the ${formatToolName(ENTER_PLAN_MODE_TOOL_NAME)} tool to draft a comprehensive design document and obtain user approval before writing any code.
+2. **Design Constraints:** When drafting your plan, adhere to these defaults unless explicitly overridden by the user:
+   - **Goal:** Autonomously design a visually appealing, substantially complete, and functional prototype with rich aesthetics. Users judge applications by their visual impact; ensure they feel modern, "alive," and polished through consistent spacing, typography, and interactive feedback.
+   - **Visuals:** Describe your strategy for sourcing or generating placeholders (e.g., stylized CSS shapes, gradients, procedurally generated patterns) to ensure a visually complete prototype. Never plan for assets that cannot be locally generated.
+   - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested.
+   - **Web:** React (TypeScript) or Angular with Vanilla CSS.
+   - **APIs:** Node.js (Express) or Python (FastAPI).
+   - **Mobile:** Compose Multiplatform or Flutter.
+   - **Games:** HTML/CSS/JS (Three.js for 3D).
+   - **CLIs:** Python or Go.
+3. **Implementation:** Once the plan is approved, follow the standard **Execution** cycle to build the application, utilizing platform-native primitives to realize the rich aesthetic you planned.`.trim();
+  }
+
+  // --- FALLBACK: Legacy workflow for when Plan Mode is disabled ---
+
   if (interactive) {
     return `
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns) to ensure a visually complete initial prototype.${planningPhaseSuggestion(options)}
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user and obtain their approval before proceeding. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns).
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested; if requested, confirm the specific version (e.g., v3 or v4).
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -599,14 +588,14 @@ function newApplicationSteps(options: PrimaryWorkflowsOptions): string {
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. **User Approval:** Obtain user approval for the proposed plan.
-4. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using ${formatToolName(SHELL_TOOL_NAME)} for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
-5. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
-6. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.`.trim();
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using ${formatToolName(SHELL_TOOL_NAME)} for commands like 'npm init', 'npx create-react-app'. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons) to ensure a complete, coherent experience. Never link to external services or assume local paths for assets that have not been created.
+4. **Verify:** Review work against the original request. Fix bugs and deviations. Ensure styling and interactions produce a high-quality, functional, and beautiful prototype. **Build the application and ensure there are no compile errors.**
+5. **Solicit Feedback:** Provide instructions on how to start the application and request user feedback on the prototype.`.trim();
   }
+
   return `
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints.
-2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. For applications requiring visual assets, describe the strategy for sourcing or generating placeholders.
+2. **Plan:** Formulate an internal development plan. For applications requiring visual assets, describe the strategy for sourcing or generating placeholders.
    - **Styling:** **Prefer Vanilla CSS** for maximum flexibility. **Avoid TailwindCSS** unless explicitly requested.
    - **Default Tech Stack:**
      - **Web:** React (TypeScript) or Angular with Vanilla CSS.
@@ -614,17 +603,10 @@ function newApplicationSteps(options: PrimaryWorkflowsOptions): string {
      - **Mobile:** Compose Multiplatform or Flutter.
      - **Games:** HTML/CSS/JS (Three.js for 3D).
      - **CLIs:** Python or Go.
-3. Implementation: Autonomously implement each feature per the approved plan. When starting, scaffold the application using ${formatToolName(SHELL_TOOL_NAME)}. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons). Never link to external services or assume local paths for assets that have not been created.
+3. **Implementation:** Autonomously implement each feature per the approved plan. When starting, scaffold the application using ${formatToolName(SHELL_TOOL_NAME)}. For visual assets, utilize **platform-native primitives** (e.g., stylized shapes, gradients, icons). Never link to external services or assume local paths for assets that have not been created.
 4. **Verify:** Review work against the original request. Fix bugs and deviations. **Build the application and ensure there are no compile errors.**`.trim();
 }
 
-function planningPhaseSuggestion(options: PrimaryWorkflowsOptions): string {
-  if (options.enableEnterPlanModeTool) {
-    return ` For complex tasks, consider using the ${formatToolName(ENTER_PLAN_MODE_TOOL_NAME)} tool to enter a dedicated planning phase before starting implementation.`;
-  }
-  return '';
-}
-
 function toneAndStyleNoChitchat(isGemini3: boolean): string {
   return isGemini3
     ? `

From 868f43927e634ed7b8f97ecf893f643d605aed13 Mon Sep 17 00:00:00 2001
From: Adib234 <30782825+Adib234@users.noreply.github.com>
Date: Thu, 12 Feb 2026 12:46:59 -0500
Subject: [PATCH 20/44] feat(plan): create metrics for usage of `AskUser` tool
 (#18820)

Co-authored-by: Jerop Kipruto <jerop@google.com>
---
 docs/cli/telemetry.md                         | 22 ++++-
 .../clearcut-logger/clearcut-logger.test.ts   | 88 +++++++++++++++++++
 .../clearcut-logger/clearcut-logger.ts        | 32 +++++++
 .../clearcut-logger/event-metadata-key.ts     | 18 +++-
 packages/core/src/telemetry/loggers.test.ts   | 48 ++++++++++
 packages/core/src/telemetry/types.ts          |  5 ++
 packages/core/src/tools/ask-user.test.ts      | 22 +++++
 packages/core/src/tools/ask-user.ts           | 20 +++++
 8 files changed, 250 insertions(+), 5 deletions(-)

diff --git a/docs/cli/telemetry.md b/docs/cli/telemetry.md
index 407ba101f2..ca44bccaf0 100644
--- a/docs/cli/telemetry.md
+++ b/docs/cli/telemetry.md
@@ -275,9 +275,9 @@ For local development and debugging, you can capture telemetry data locally:
 The following section describes the structure of logs and metrics generated for
 Gemini CLI.
 
-The `session.id`, `installation.id`, and `user.email` (available only when
-authenticated with a Google account) are included as common attributes on all
-logs and metrics.
+The `session.id`, `installation.id`, `active_approval_mode`, and `user.email`
+(available only when authenticated with a Google account) are included as common
+attributes on all logs and metrics.
 
 ### Logs
 
@@ -360,7 +360,21 @@ Captures tool executions, output truncation, and Edit behavior.
     - `extension_name` (string, if applicable)
     - `extension_id` (string, if applicable)
     - `content_length` (int, if applicable)
-    - `metadata` (if applicable)
+    - `metadata` (if applicable), which includes for the `AskUser` tool:
+      - `ask_user` (object):
+        - `question_types` (array of strings)
+        - `ask_user_dismissed` (boolean)
+        - `ask_user_empty_submission` (boolean)
+        - `ask_user_answer_count` (number)
+      - `diffStat` (if applicable), which includes:
+        - `model_added_lines` (number)
+        - `model_removed_lines` (number)
+        - `model_added_chars` (number)
+        - `model_removed_chars` (number)
+        - `user_added_lines` (number)
+        - `user_removed_lines` (number)
+        - `user_added_chars` (number)
+        - `user_removed_chars` (number)
 
 - `gemini_cli.tool_output_truncated`: Output of a tool call was truncated.
   - **Attributes**:
diff --git a/packages/core/src/telemetry/clearcut-logger/clearcut-logger.test.ts b/packages/core/src/telemetry/clearcut-logger/clearcut-logger.test.ts
index 3cad76b491..a5bed404d9 100644
--- a/packages/core/src/telemetry/clearcut-logger/clearcut-logger.test.ts
+++ b/packages/core/src/telemetry/clearcut-logger/clearcut-logger.test.ts
@@ -336,6 +336,10 @@ describe('ClearcutLogger', () => {
             gemini_cli_key: EventMetadataKey.GEMINI_CLI_USER_SETTINGS,
             value: logger?.getConfigJson(),
           },
+          {
+            gemini_cli_key: EventMetadataKey.GEMINI_CLI_ACTIVE_APPROVAL_MODE,
+            value: 'default',
+          },
         ]),
       );
     });
@@ -1239,6 +1243,90 @@ describe('ClearcutLogger', () => {
         EventMetadataKey.GEMINI_CLI_AI_ADDED_LINES,
       );
     });
+
+    it('logs AskUser tool metadata', () => {
+      const { logger } = setup();
+      const completedToolCall = {
+        request: {
+          name: 'ask_user',
+          args: { questions: [] },
+          prompt_id: 'prompt-123',
+        },
+        response: {
+          resultDisplay: 'User answered: ...',
+          data: {
+            ask_user: {
+              question_types: ['choice', 'text'],
+              dismissed: false,
+              empty_submission: false,
+              answer_count: 2,
+            },
+          },
+        },
+        status: 'success',
+      } as unknown as SuccessfulToolCall;
+
+      logger?.logToolCallEvent(new ToolCallEvent(completedToolCall));
+
+      const events = getEvents(logger!);
+      expect(events.length).toBe(1);
+      expect(events[0]).toHaveEventName(EventNames.TOOL_CALL);
+      expect(events[0]).toHaveMetadataValue([
+        EventMetadataKey.GEMINI_CLI_ASK_USER_QUESTION_TYPES,
+        JSON.stringify(['choice', 'text']),
+      ]);
+      expect(events[0]).toHaveMetadataValue([
+        EventMetadataKey.GEMINI_CLI_ASK_USER_DISMISSED,
+        'false',
+      ]);
+      expect(events[0]).toHaveMetadataValue([
+        EventMetadataKey.GEMINI_CLI_ASK_USER_EMPTY_SUBMISSION,
+        'false',
+      ]);
+      expect(events[0]).toHaveMetadataValue([
+        EventMetadataKey.GEMINI_CLI_ASK_USER_ANSWER_COUNT,
+        '2',
+      ]);
+    });
+
+    it('does not log AskUser tool metadata for other tools', () => {
+      const { logger } = setup();
+      const completedToolCall = {
+        request: {
+          name: 'some_other_tool',
+          args: {},
+          prompt_id: 'prompt-123',
+        },
+        response: {
+          resultDisplay: 'Result',
+          data: {
+            ask_user_question_types: ['choice', 'text'],
+            ask_user_dismissed: false,
+            ask_user_empty_submission: false,
+            ask_user_answer_count: 2,
+          },
+        },
+        status: 'success',
+      } as unknown as SuccessfulToolCall;
+
+      logger?.logToolCallEvent(new ToolCallEvent(completedToolCall));
+
+      const events = getEvents(logger!);
+      expect(events.length).toBe(1);
+      expect(events[0]).toHaveEventName(EventNames.TOOL_CALL);
+      expect(events[0]).not.toHaveMetadataKey(
+        EventMetadataKey.GEMINI_CLI_ASK_USER_QUESTION_TYPES,
+      );
+      expect(events[0]).not.toHaveMetadataKey(
+        EventMetadataKey.GEMINI_CLI_ASK_USER_DISMISSED,
+      );
+      expect(events[0]).not.toHaveMetadataKey(
+        EventMetadataKey.GEMINI_CLI_ASK_USER_EMPTY_SUBMISSION,
+      );
+      expect(events[0]).not.toHaveMetadataKey(
+        EventMetadataKey.GEMINI_CLI_ASK_USER_ANSWER_COUNT,
+      );
+    });
   });
 
   describe('flushIfNeeded', () => {
diff --git a/packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts b/packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts
index b63cac58eb..570725318a 100644
--- a/packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts
+++ b/packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts
@@ -56,6 +56,7 @@ import {
   safeJsonStringify,
   safeJsonStringifyBooleanValuesOnly,
 } from '../../utils/safeJsonStringify.js';
+import { ASK_USER_TOOL_NAME } from '../../tools/tool-names.js';
 import { FixedDeque } from 'mnemonist';
 import { GIT_COMMIT_INFO, CLI_VERSION } from '../../generated/git-commit.js';
 import {
@@ -704,6 +705,29 @@ export class ClearcutLogger {
         user_removed_chars: EventMetadataKey.GEMINI_CLI_USER_REMOVED_CHARS,
       };
 
+      if (
+        event.function_name === ASK_USER_TOOL_NAME &&
+        event.metadata['ask_user']
+      ) {
+        const askUser = event.metadata['ask_user'];
+        const askUserMapping: { [key: string]: EventMetadataKey } = {
+          question_types: EventMetadataKey.GEMINI_CLI_ASK_USER_QUESTION_TYPES,
+          dismissed: EventMetadataKey.GEMINI_CLI_ASK_USER_DISMISSED,
+          empty_submission:
+            EventMetadataKey.GEMINI_CLI_ASK_USER_EMPTY_SUBMISSION,
+          answer_count: EventMetadataKey.GEMINI_CLI_ASK_USER_ANSWER_COUNT,
+        };
+
+        for (const [key, gemini_cli_key] of Object.entries(askUserMapping)) {
+          if (askUser[key] !== undefined) {
+            data.push({
+              gemini_cli_key,
+              value: JSON.stringify(askUser[key]),
+            });
+          }
+        }
+      }
+
       for (const [key, gemini_cli_key] of Object.entries(metadataMapping)) {
         if (event.metadata[key] !== undefined) {
           data.push({
@@ -1625,6 +1649,14 @@ export class ClearcutLogger {
         gemini_cli_key: EventMetadataKey.GEMINI_CLI_INTERACTIVE,
         value: this.config?.isInteractive().toString() ?? 'false',
       },
+      {
+        gemini_cli_key: EventMetadataKey.GEMINI_CLI_ACTIVE_APPROVAL_MODE,
+        value:
+          typeof this.config?.getPolicyEngine === 'function' &&
+          typeof this.config.getPolicyEngine()?.getApprovalMode === 'function'
+            ? this.config.getPolicyEngine().getApprovalMode()
+            : '',
+      },
     ];
     if (this.config?.getExperiments()) {
       defaultLogMetadata.push({
diff --git a/packages/core/src/telemetry/clearcut-logger/event-metadata-key.ts b/packages/core/src/telemetry/clearcut-logger/event-metadata-key.ts
index 25e6e18d13..8934db5570 100644
--- a/packages/core/src/telemetry/clearcut-logger/event-metadata-key.ts
+++ b/packages/core/src/telemetry/clearcut-logger/event-metadata-key.ts
@@ -7,7 +7,7 @@
 // Defines valid event metadata keys for Clearcut logging.
 export enum EventMetadataKey {
   // Deleted enums: 24
-  // Next ID: 152
+  // Next ID: 156
 
   GEMINI_CLI_KEY_UNKNOWN = 0,
 
@@ -577,4 +577,20 @@ export enum EventMetadataKey {
 
   // Logs the total prunable tokens identified at the trigger point.
   GEMINI_CLI_TOOL_OUTPUT_MASKING_TOTAL_PRUNABLE_TOKENS = 151,
+
+  // ==========================================================================
+  // Ask User Stats Event Keys
+  // ==========================================================================
+
+  // Logs the types of questions asked in the ask_user tool.
+  GEMINI_CLI_ASK_USER_QUESTION_TYPES = 152,
+
+  // Logs whether the ask_user dialog was dismissed.
+  GEMINI_CLI_ASK_USER_DISMISSED = 153,
+
+  // Logs whether the ask_user dialog was submitted empty.
+  GEMINI_CLI_ASK_USER_EMPTY_SUBMISSION = 154,
+
+  // Logs the number of questions answered in the ask_user tool.
+  GEMINI_CLI_ASK_USER_ANSWER_COUNT = 155,
 }
diff --git a/packages/core/src/telemetry/loggers.test.ts b/packages/core/src/telemetry/loggers.test.ts
index 16da103244..fd2d1bc221 100644
--- a/packages/core/src/telemetry/loggers.test.ts
+++ b/packages/core/src/telemetry/loggers.test.ts
@@ -5,6 +5,7 @@
  */
 
 import type {
+  AnyDeclarativeTool,
   AnyToolInvocation,
   CompletedToolCall,
   ContentGeneratorConfig,
@@ -1184,6 +1185,53 @@ describe('loggers', () => {
         { function_name: 'test-function' },
       );
     });
+
+    it('should merge data from response into metadata', () => {
+      const call: CompletedToolCall = {
+        status: 'success',
+        request: {
+          name: 'ask_user',
+          args: { questions: [] },
+          callId: 'test-call-id',
+          isClientInitiated: true,
+          prompt_id: 'prompt-id-1',
+        },
+        response: {
+          callId: 'test-call-id',
+          responseParts: [{ text: 'test-response' }],
+          resultDisplay: 'User answered: ...',
+          error: undefined,
+          errorType: undefined,
+          data: {
+            ask_user: {
+              question_types: ['choice'],
+              dismissed: false,
+            },
+          },
+        },
+        tool: undefined as unknown as AnyDeclarativeTool,
+        invocation: {} as AnyToolInvocation,
+        durationMs: 100,
+        outcome: ToolConfirmationOutcome.ProceedOnce,
+      };
+      const event = new ToolCallEvent(call);
+
+      logToolCall(mockConfig, event);
+
+      expect(mockLogger.emit).toHaveBeenCalledWith({
+        body: 'Tool call: ask_user. Decision: accept. Success: true. Duration: 100ms.',
+        attributes: expect.objectContaining({
+          function_name: 'ask_user',
+          metadata: expect.objectContaining({
+            ask_user: {
+              question_types: ['choice'],
+              dismissed: false,
+            },
+          }),
+        }),
+      });
+    });
+
     it('should log a tool call with a reject decision', () => {
       const call: ErroredToolCall = {
         status: 'error',
diff --git a/packages/core/src/telemetry/types.ts b/packages/core/src/telemetry/types.ts
index 0c438764f1..cf0e5f853f 100644
--- a/packages/core/src/telemetry/types.ts
+++ b/packages/core/src/telemetry/types.ts
@@ -304,6 +304,7 @@ export class ToolCallEvent implements BaseTelemetryEvent {
         const diffStat = fileDiff.diffStat;
         if (diffStat) {
           this.metadata = {
+            ...this.metadata,
             model_added_lines: diffStat.model_added_lines,
             model_removed_lines: diffStat.model_removed_lines,
             model_added_chars: diffStat.model_added_chars,
@@ -315,6 +316,10 @@ export class ToolCallEvent implements BaseTelemetryEvent {
           };
         }
       }
+
+      if (call.status === 'success' && call.response.data) {
+        this.metadata = { ...this.metadata, ...call.response.data };
+      }
     } else {
       // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
       this.function_name = function_name as string;
diff --git a/packages/core/src/tools/ask-user.test.ts b/packages/core/src/tools/ask-user.test.ts
index 969a4f7f15..c7d64eae6e 100644
--- a/packages/core/src/tools/ask-user.test.ts
+++ b/packages/core/src/tools/ask-user.test.ts
@@ -337,6 +337,14 @@ describe('AskUserTool', () => {
       expect(JSON.parse(result.llmContent as string)).toEqual({
         answers: { '0': 'Quick fix (Recommended)' },
       });
+      expect(result.data).toEqual({
+        ask_user: {
+          question_types: [QuestionType.CHOICE],
+          dismissed: false,
+          empty_submission: false,
+          answer_count: 1,
+        },
+      });
     });
 
     it('should display message when user submits without answering', async () => {
@@ -368,6 +376,14 @@ describe('AskUserTool', () => {
         'User submitted without answering questions.',
       );
       expect(JSON.parse(result.llmContent as string)).toEqual({ answers: {} });
+      expect(result.data).toEqual({
+        ask_user: {
+          question_types: [QuestionType.CHOICE],
+          dismissed: false,
+          empty_submission: true,
+          answer_count: 0,
+        },
+      });
     });
 
     it('should handle cancellation', async () => {
@@ -405,6 +421,12 @@ describe('AskUserTool', () => {
       expect(result.llmContent).toBe(
         'User dismissed ask_user dialog without answering.',
       );
+      expect(result.data).toEqual({
+        ask_user: {
+          question_types: [QuestionType.CHOICE],
+          dismissed: true,
+        },
+      });
     });
   });
 });
diff --git a/packages/core/src/tools/ask-user.ts b/packages/core/src/tools/ask-user.ts
index 071dd1b317..db9103c720 100644
--- a/packages/core/src/tools/ask-user.ts
+++ b/packages/core/src/tools/ask-user.ts
@@ -192,16 +192,35 @@ export class AskUserInvocation extends BaseToolInvocation<
   }
 
   async execute(_signal: AbortSignal): Promise<ToolResult> {
+    const questionTypes = this.params.questions.map(
+      (q) => q.type ?? QuestionType.CHOICE,
+    );
+
     if (this.confirmationOutcome === ToolConfirmationOutcome.Cancel) {
       return {
         llmContent: 'User dismissed ask_user dialog without answering.',
         returnDisplay: 'User dismissed dialog',
+        data: {
+          ask_user: {
+            question_types: questionTypes,
+            dismissed: true,
+          },
+        },
       };
     }
 
     const answerEntries = Object.entries(this.userAnswers);
     const hasAnswers = answerEntries.length > 0;
 
+    const metrics: Record<string, unknown> = {
+      ask_user: {
+        question_types: questionTypes,
+        dismissed: false,
+        empty_submission: !hasAnswers,
+        answer_count: answerEntries.length,
+      },
+    };
+
     const returnDisplay = hasAnswers
       ? `**User answered:**\n${answerEntries
           .map(([index, answer]) => {
@@ -219,6 +238,7 @@ export class AskUserInvocation extends BaseToolInvocation<
     return {
       llmContent: JSON.stringify({ answers: this.userAnswers }),
       returnDisplay,
+      data: metrics,
     };
   }
 }

From 375ebca2da8b82949ba263a0d9255f28d5472eec Mon Sep 17 00:00:00 2001
From: Tommaso Sciortino <sciortino@gmail.com>
Date: Thu, 12 Feb 2026 09:55:56 -0800
Subject: [PATCH 21/44] feat(cli): support Ctrl-Z suspension (#18931)

Co-authored-by: Bharat Kunwar <brtkwr@gmail.com>
---
 docs/cli/keyboard-shortcuts.md                |   2 +-
 packages/cli/src/config/keyBindings.ts        |   2 +-
 packages/cli/src/ui/AppContainer.test.tsx     |  73 ++++---
 packages/cli/src/ui/AppContainer.tsx          |  61 ++++--
 .../__snapshots__/InputPrompt.test.tsx.snap   |  33 +++
 packages/cli/src/ui/hooks/useSuspend.test.ts  | 201 ++++++++++++++++++
 packages/cli/src/ui/hooks/useSuspend.ts       | 155 ++++++++++++++
 packages/cli/src/ui/keyMatchers.test.ts       |  12 ++
 .../src/ui/utils/terminalCapabilityManager.ts |  37 ++--
 9 files changed, 515 insertions(+), 61 deletions(-)
 create mode 100644 packages/cli/src/ui/hooks/useSuspend.test.ts
 create mode 100644 packages/cli/src/ui/hooks/useSuspend.ts

diff --git a/docs/cli/keyboard-shortcuts.md b/docs/cli/keyboard-shortcuts.md
index 91baedc8c9..0dc32b7779 100644
--- a/docs/cli/keyboard-shortcuts.md
+++ b/docs/cli/keyboard-shortcuts.md
@@ -120,7 +120,7 @@ available combinations.
 | Move focus from the shell back to Gemini.                                                             | `Shift + Tab`              |
 | Clear the terminal screen and redraw the UI.                                                          | `Ctrl + L`                 |
 | Restart the application.                                                                              | `R`                        |
-| Suspend the application (not yet implemented).                                                        | `Ctrl + Z`                 |
+| Suspend the CLI and move it to the background.                                                        | `Ctrl + Z`                 |
 
 <!-- KEYBINDINGS-AUTOGEN:END -->
 
diff --git a/packages/cli/src/config/keyBindings.ts b/packages/cli/src/config/keyBindings.ts
index 96e50f36d6..adf88d4d25 100644
--- a/packages/cli/src/config/keyBindings.ts
+++ b/packages/cli/src/config/keyBindings.ts
@@ -523,5 +523,5 @@ export const commandDescriptions: Readonly<Record<Command, string>> = {
   [Command.UNFOCUS_SHELL_INPUT]: 'Move focus from the shell back to Gemini.',
   [Command.CLEAR_SCREEN]: 'Clear the terminal screen and redraw the UI.',
   [Command.RESTART_APP]: 'Restart the application.',
-  [Command.SUSPEND_APP]: 'Suspend the application (not yet implemented).',
+  [Command.SUSPEND_APP]: 'Suspend the CLI and move it to the background.',
 };
diff --git a/packages/cli/src/ui/AppContainer.test.tsx b/packages/cli/src/ui/AppContainer.test.tsx
index 063315f8ac..ff84834c69 100644
--- a/packages/cli/src/ui/AppContainer.test.tsx
+++ b/packages/cli/src/ui/AppContainer.test.tsx
@@ -135,6 +135,7 @@ vi.mock('./hooks/vim.js');
 vi.mock('./hooks/useFocus.js');
 vi.mock('./hooks/useBracketedPaste.js');
 vi.mock('./hooks/useLoadingIndicator.js');
+vi.mock('./hooks/useSuspend.js');
 vi.mock('./hooks/useFolderTrust.js');
 vi.mock('./hooks/useIdeTrustListener.js');
 vi.mock('./hooks/useMessageQueue.js');
@@ -199,6 +200,7 @@ import { useLoadingIndicator } from './hooks/useLoadingIndicator.js';
 import { useInputHistoryStore } from './hooks/useInputHistoryStore.js';
 import { useKeypress, type Key } from './hooks/useKeypress.js';
 import * as useKeypressModule from './hooks/useKeypress.js';
+import { useSuspend } from './hooks/useSuspend.js';
 import { measureElement } from 'ink';
 import { useTerminalSize } from './hooks/useTerminalSize.js';
 import {
@@ -271,6 +273,7 @@ describe('AppContainer State Management', () => {
   const mockedUseTextBuffer = useTextBuffer as Mock;
   const mockedUseLogger = useLogger as Mock;
   const mockedUseLoadingIndicator = useLoadingIndicator as Mock;
+  const mockedUseSuspend = useSuspend as Mock;
   const mockedUseInputHistoryStore = useInputHistoryStore as Mock;
   const mockedUseHookDisplayState = useHookDisplayState as Mock;
   const mockedUseTerminalTheme = useTerminalTheme as Mock;
@@ -402,6 +405,9 @@ describe('AppContainer State Management', () => {
       elapsedTime: '0.0s',
       currentLoadingPhrase: '',
     });
+    mockedUseSuspend.mockReturnValue({
+      handleSuspend: vi.fn(),
+    });
     mockedUseHookDisplayState.mockReturnValue([]);
     mockedUseTerminalTheme.mockReturnValue(undefined);
     mockedUseShellInactivityStatus.mockReturnValue({
@@ -441,8 +447,8 @@ describe('AppContainer State Management', () => {
           ...defaultMergedSettings.ui,
           showStatusInTitle: false,
           hideWindowTitle: false,
+          useAlternateBuffer: false,
         },
-        useAlternateBuffer: false,
       },
     } as unknown as LoadedSettings;
 
@@ -728,10 +734,10 @@ describe('AppContainer State Management', () => {
         getChatRecordingService: vi.fn(() => mockChatRecordingService),
       };
 
-      const configWithRecording = {
-        ...mockConfig,
-        getGeminiClient: vi.fn(() => mockGeminiClient),
-      } as unknown as Config;
+      const configWithRecording = makeFakeConfig();
+      vi.spyOn(configWithRecording, 'getGeminiClient').mockReturnValue(
+        mockGeminiClient as unknown as ReturnType<Config['getGeminiClient']>,
+      );
 
       expect(() => {
         renderAppContainer({
@@ -762,11 +768,13 @@ describe('AppContainer State Management', () => {
         setHistory: vi.fn(),
       };
 
-      const configWithRecording = {
-        ...mockConfig,
-        getGeminiClient: vi.fn(() => mockGeminiClient),
-        getSessionId: vi.fn(() => 'test-session-123'),
-      } as unknown as Config;
+      const configWithRecording = makeFakeConfig();
+      vi.spyOn(configWithRecording, 'getGeminiClient').mockReturnValue(
+        mockGeminiClient as unknown as ReturnType<Config['getGeminiClient']>,
+      );
+      vi.spyOn(configWithRecording, 'getSessionId').mockReturnValue(
+        'test-session-123',
+      );
 
       expect(() => {
         renderAppContainer({
@@ -802,10 +810,10 @@ describe('AppContainer State Management', () => {
         getUserTier: vi.fn(),
       };
 
-      const configWithRecording = {
-        ...mockConfig,
-        getGeminiClient: vi.fn(() => mockGeminiClient),
-      } as unknown as Config;
+      const configWithRecording = makeFakeConfig();
+      vi.spyOn(configWithRecording, 'getGeminiClient').mockReturnValue(
+        mockGeminiClient as unknown as ReturnType<Config['getGeminiClient']>,
+      );
 
       renderAppContainer({
         config: configWithRecording,
@@ -836,10 +844,10 @@ describe('AppContainer State Management', () => {
         })),
       };
 
-      const configWithClient = {
-        ...mockConfig,
-        getGeminiClient: vi.fn(() => mockGeminiClient),
-      } as unknown as Config;
+      const configWithClient = makeFakeConfig();
+      vi.spyOn(configWithClient, 'getGeminiClient').mockReturnValue(
+        mockGeminiClient as unknown as ReturnType<Config['getGeminiClient']>,
+      );
 
       const resumedData = {
         conversation: {
@@ -892,10 +900,10 @@ describe('AppContainer State Management', () => {
         getChatRecordingService: vi.fn(),
       };
 
-      const configWithClient = {
-        ...mockConfig,
-        getGeminiClient: vi.fn(() => mockGeminiClient),
-      } as unknown as Config;
+      const configWithClient = makeFakeConfig();
+      vi.spyOn(configWithClient, 'getGeminiClient').mockReturnValue(
+        mockGeminiClient as unknown as ReturnType<Config['getGeminiClient']>,
+      );
 
       const resumedData = {
         conversation: {
@@ -945,10 +953,10 @@ describe('AppContainer State Management', () => {
         getUserTier: vi.fn(),
       };
 
-      const configWithRecording = {
-        ...mockConfig,
-        getGeminiClient: vi.fn(() => mockGeminiClient),
-      } as unknown as Config;
+      const configWithRecording = makeFakeConfig();
+      vi.spyOn(configWithRecording, 'getGeminiClient').mockReturnValue(
+        mockGeminiClient as unknown as ReturnType<Config['getGeminiClient']>,
+      );
 
       renderAppContainer({
         config: configWithRecording,
@@ -1943,6 +1951,19 @@ describe('AppContainer State Management', () => {
       });
     });
 
+    describe('CTRL+Z', () => {
+      it('should call handleSuspend', async () => {
+        const handleSuspend = vi.fn();
+        mockedUseSuspend.mockReturnValue({ handleSuspend });
+        await setupKeypressTest();
+
+        pressKey('\x1A'); // Ctrl+Z
+
+        expect(handleSuspend).toHaveBeenCalledTimes(1);
+        unmount();
+      });
+    });
+
     describe('Focus Handling (Tab / Shift+Tab)', () => {
       beforeEach(() => {
         // Mock activePtyId to enable focus
diff --git a/packages/cli/src/ui/AppContainer.tsx b/packages/cli/src/ui/AppContainer.tsx
index 7489d07e2a..a2f25a71de 100644
--- a/packages/cli/src/ui/AppContainer.tsx
+++ b/packages/cli/src/ui/AppContainer.tsx
@@ -12,7 +12,14 @@ import {
   useRef,
   useLayoutEffect,
 } from 'react';
-import { type DOMElement, measureElement } from 'ink';
+import {
+  type DOMElement,
+  measureElement,
+  useApp,
+  useStdout,
+  useStdin,
+  type AppProps,
+} from 'ink';
 import { App } from './App.js';
 import { AppContext } from './contexts/AppContext.js';
 import { UIStateContext, type UIState } from './contexts/UIStateContext.js';
@@ -87,7 +94,6 @@ import { useVimMode } from './contexts/VimModeContext.js';
 import { useConsoleMessages } from './hooks/useConsoleMessages.js';
 import { useTerminalSize } from './hooks/useTerminalSize.js';
 import { calculatePromptWidths } from './components/InputPrompt.js';
-import { useApp, useStdout, useStdin } from 'ink';
 import { calculateMainAreaWidth } from './utils/ui-sizing.js';
 import ansiEscapes from 'ansi-escapes';
 import { basename } from 'node:path';
@@ -146,8 +152,8 @@ import { NewAgentsChoice } from './components/NewAgentsNotification.js';
 import { isSlashCommand } from './utils/commandUtils.js';
 import { useTerminalTheme } from './hooks/useTerminalTheme.js';
 import { useTimedMessage } from './hooks/useTimedMessage.js';
-import { isITerm2 } from './utils/terminalUtils.js';
 import { shouldDismissShortcutsHelpOnHotkey } from './utils/shortcutsHelp.js';
+import { useSuspend } from './hooks/useSuspend.js';
 
 function isToolExecuting(pendingHistoryItems: HistoryItemWithoutId[]) {
   return pendingHistoryItems.some((item) => {
@@ -201,6 +207,7 @@ export const AppContainer = (props: AppContainerProps) => {
   useMemoryMonitor(historyManager);
   const isAlternateBuffer = useAlternateBuffer();
   const [corgiMode, setCorgiMode] = useState(false);
+  const [forceRerenderKey, setForceRerenderKey] = useState(0);
   const [debugMessage, setDebugMessage] = useState<string>('');
   const [quittingMessages, setQuittingMessages] = useState<
     HistoryItem[] | null
@@ -347,7 +354,7 @@ export const AppContainer = (props: AppContainerProps) => {
   const { columns: terminalWidth, rows: terminalHeight } = useTerminalSize();
   const { stdin, setRawMode } = useStdin();
   const { stdout } = useStdout();
-  const app = useApp();
+  const app: AppProps = useApp();
 
   // Additional hooks moved from App.tsx
   const { stats: sessionStats } = useSessionStats();
@@ -536,10 +543,13 @@ export const AppContainer = (props: AppContainerProps) => {
     setHistoryRemountKey((prev) => prev + 1);
   }, [setHistoryRemountKey, isAlternateBuffer, stdout]);
 
+  const shouldUseAlternateScreen = shouldEnterAlternateScreen(
+    isAlternateBuffer,
+    config.getScreenReader(),
+  );
+
   const handleEditorClose = useCallback(() => {
-    if (
-      shouldEnterAlternateScreen(isAlternateBuffer, config.getScreenReader())
-    ) {
+    if (shouldUseAlternateScreen) {
       // The editor may have exited alternate buffer mode so we need to
       // enter it again to be safe.
       enterAlternateScreen();
@@ -549,7 +559,7 @@ export const AppContainer = (props: AppContainerProps) => {
     }
     terminalCapabilityManager.enableSupportedModes();
     refreshStatic();
-  }, [refreshStatic, isAlternateBuffer, app, config]);
+  }, [refreshStatic, shouldUseAlternateScreen, app]);
 
   const [editorError, setEditorError] = useState<string | null>(null);
   const {
@@ -1370,6 +1380,24 @@ Logging in with Google... Restarting Gemini CLI to continue.
     };
   }, [showTransientMessage]);
 
+  const handleWarning = useCallback(
+    (message: string) => {
+      showTransientMessage({
+        text: message,
+        type: TransientMessageType.Warning,
+      });
+    },
+    [showTransientMessage],
+  );
+
+  const { handleSuspend } = useSuspend({
+    handleWarning,
+    setRawMode,
+    refreshStatic,
+    setForceRerenderKey,
+    shouldUseAlternateScreen,
+  });
+
   useEffect(() => {
     if (ideNeedsRestart) {
       // IDE trust changed, force a restart.
@@ -1510,6 +1538,9 @@ Logging in with Google... Restarting Gemini CLI to continue.
       } else if (keyMatchers[Command.EXIT](key)) {
         setCtrlDPressCount((prev) => prev + 1);
         return true;
+      } else if (keyMatchers[Command.SUSPEND_APP](key)) {
+        handleSuspend();
+        return true;
       }
 
       let enteringConstrainHeightMode = false;
@@ -1535,15 +1566,6 @@ Logging in with Google... Restarting Gemini CLI to continue.
           setShowErrorDetails((prev) => !prev);
         }
         return true;
-      } else if (keyMatchers[Command.SUSPEND_APP](key)) {
-        const undoMessage = isITerm2()
-          ? 'Undo has been moved to Option + Z'
-          : 'Undo has been moved to Alt/Option + Z or Cmd + Z';
-        showTransientMessage({
-          text: undoMessage,
-          type: TransientMessageType.Warning,
-        });
-        return true;
       } else if (keyMatchers[Command.SHOW_FULL_TODOS](key)) {
         setShowFullTodos((prev) => !prev);
         return true;
@@ -1652,10 +1674,12 @@ Logging in with Google... Restarting Gemini CLI to continue.
       handleSlashCommand,
       cancelOngoingRequest,
       activePtyId,
+      handleSuspend,
       embeddedShellFocused,
       settings.merged.general.debugKeystrokeLogging,
       refreshStatic,
       setCopyModeEnabled,
+      tabFocusTimeoutRef,
       isAlternateBuffer,
       shortcutsHelpVisible,
       backgroundCurrentShell,
@@ -1664,7 +1688,6 @@ Logging in with Google... Restarting Gemini CLI to continue.
       isBackgroundShellVisible,
       setIsBackgroundShellListOpen,
       lastOutputTimeRef,
-      tabFocusTimeoutRef,
       showTransientMessage,
       settings.merged.general.devtools,
       showErrorDetails,
@@ -2276,7 +2299,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
           >
             <ToolActionsProvider config={config} toolCalls={allToolCalls}>
               <ShellFocusContext.Provider value={isFocused}>
-                <App />
+                <App key={`app-${forceRerenderKey}`} />
               </ShellFocusContext.Provider>
             </ToolActionsProvider>
           </AppContext.Provider>
diff --git a/packages/cli/src/ui/components/__snapshots__/InputPrompt.test.tsx.snap b/packages/cli/src/ui/components/__snapshots__/InputPrompt.test.tsx.snap
index ff3818d6f8..05d128f738 100644
--- a/packages/cli/src/ui/components/__snapshots__/InputPrompt.test.tsx.snap
+++ b/packages/cli/src/ui/components/__snapshots__/InputPrompt.test.tsx.snap
@@ -77,6 +77,39 @@ exports[`InputPrompt > mouse interaction > should toggle paste expansion on doub
 ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄"
 `;
 
+exports[`InputPrompt > mouse interaction > should toggle paste expansion on double-click 4`] = `
+"▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+ > [Pasted Text: 10 lines]
+▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄"
+`;
+
+exports[`InputPrompt > mouse interaction > should toggle paste expansion on double-click 5`] = `
+"▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+ > [Pasted Text: 10 lines]                                                                                              
+▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄"
+`;
+
+exports[`InputPrompt > mouse interaction > should toggle paste expansion on double-click 6`] = `
+"▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+ > line1                                                                                                                
+   line2                                                                                                                
+   line3                                                                                                                
+   line4                                                                                                                
+   line5                                                                                                                
+   line6                                                                                                                
+   line7                                                                                                                
+   line8                                                                                                                
+   line9                                                                                                                
+   line10                                                                                                               
+▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄"
+`;
+
+exports[`InputPrompt > mouse interaction > should toggle paste expansion on double-click 7`] = `
+"▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+ > [Pasted Text: 10 lines]                                                                                              
+▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄"
+`;
+
 exports[`InputPrompt > snapshots > should not show inverted cursor when shell is focused 1`] = `
 "▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  >   Type your message or @path/to/file
diff --git a/packages/cli/src/ui/hooks/useSuspend.test.ts b/packages/cli/src/ui/hooks/useSuspend.test.ts
new file mode 100644
index 0000000000..9aa90d16b3
--- /dev/null
+++ b/packages/cli/src/ui/hooks/useSuspend.test.ts
@@ -0,0 +1,201 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type Mock,
+} from 'vitest';
+import { act } from 'react';
+import { renderHook } from '../../test-utils/render.js';
+import { useSuspend } from './useSuspend.js';
+import {
+  writeToStdout,
+  disableMouseEvents,
+  enableMouseEvents,
+  enterAlternateScreen,
+  exitAlternateScreen,
+  enableLineWrapping,
+  disableLineWrapping,
+} from '@google/gemini-cli-core';
+import {
+  cleanupTerminalOnExit,
+  terminalCapabilityManager,
+} from '../utils/terminalCapabilityManager.js';
+
+vi.mock('@google/gemini-cli-core', async () => {
+  const actual = await vi.importActual('@google/gemini-cli-core');
+  return {
+    ...actual,
+    writeToStdout: vi.fn(),
+    disableMouseEvents: vi.fn(),
+    enableMouseEvents: vi.fn(),
+    enterAlternateScreen: vi.fn(),
+    exitAlternateScreen: vi.fn(),
+    enableLineWrapping: vi.fn(),
+    disableLineWrapping: vi.fn(),
+  };
+});
+
+vi.mock('../utils/terminalCapabilityManager.js', () => ({
+  cleanupTerminalOnExit: vi.fn(),
+  terminalCapabilityManager: {
+    enableSupportedModes: vi.fn(),
+  },
+}));
+
+describe('useSuspend', () => {
+  const originalPlatform = process.platform;
+  let killSpy: Mock;
+
+  const setPlatform = (platform: NodeJS.Platform) => {
+    Object.defineProperty(process, 'platform', {
+      value: platform,
+      configurable: true,
+    });
+  };
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+    killSpy = vi
+      .spyOn(process, 'kill')
+      .mockReturnValue(true) as unknown as Mock;
+    // Default tests to a POSIX platform so suspend path assertions are stable.
+    setPlatform('linux');
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    killSpy.mockRestore();
+    setPlatform(originalPlatform);
+  });
+
+  it('cleans terminal state on suspend and restores/repaints on resume in alternate screen mode', () => {
+    const handleWarning = vi.fn();
+    const setRawMode = vi.fn();
+    const refreshStatic = vi.fn();
+    const setForceRerenderKey = vi.fn();
+    const enableSupportedModes =
+      terminalCapabilityManager.enableSupportedModes as unknown as Mock;
+
+    const { result, unmount } = renderHook(() =>
+      useSuspend({
+        handleWarning,
+        setRawMode,
+        refreshStatic,
+        setForceRerenderKey,
+        shouldUseAlternateScreen: true,
+      }),
+    );
+
+    act(() => {
+      result.current.handleSuspend();
+    });
+    expect(handleWarning).toHaveBeenCalledWith(
+      'Press Ctrl+Z again to suspend. Undo has moved to Cmd + Z or Alt/Opt + Z.',
+    );
+
+    act(() => {
+      result.current.handleSuspend();
+    });
+
+    expect(exitAlternateScreen).toHaveBeenCalledTimes(1);
+    expect(enableLineWrapping).toHaveBeenCalledTimes(1);
+    expect(writeToStdout).toHaveBeenCalledWith('\x1b[2J\x1b[H');
+    expect(disableMouseEvents).toHaveBeenCalledTimes(1);
+    expect(cleanupTerminalOnExit).toHaveBeenCalledTimes(1);
+    expect(setRawMode).toHaveBeenCalledWith(false);
+    expect(killSpy).toHaveBeenCalledWith(0, 'SIGTSTP');
+
+    act(() => {
+      process.emit('SIGCONT');
+      vi.runAllTimers();
+    });
+
+    expect(enterAlternateScreen).toHaveBeenCalledTimes(1);
+    expect(disableLineWrapping).toHaveBeenCalledTimes(1);
+    expect(enableSupportedModes).toHaveBeenCalledTimes(1);
+    expect(enableMouseEvents).toHaveBeenCalledTimes(1);
+    expect(setRawMode).toHaveBeenCalledWith(true);
+    expect(refreshStatic).toHaveBeenCalledTimes(1);
+    expect(setForceRerenderKey).toHaveBeenCalledTimes(1);
+
+    unmount();
+  });
+
+  it('does not toggle alternate screen or mouse restore when alternate screen mode is disabled', () => {
+    const handleWarning = vi.fn();
+    const setRawMode = vi.fn();
+    const refreshStatic = vi.fn();
+    const setForceRerenderKey = vi.fn();
+
+    const { result, unmount } = renderHook(() =>
+      useSuspend({
+        handleWarning,
+        setRawMode,
+        refreshStatic,
+        setForceRerenderKey,
+        shouldUseAlternateScreen: false,
+      }),
+    );
+
+    act(() => {
+      result.current.handleSuspend();
+      result.current.handleSuspend();
+      process.emit('SIGCONT');
+      vi.runAllTimers();
+    });
+
+    expect(exitAlternateScreen).not.toHaveBeenCalled();
+    expect(enterAlternateScreen).not.toHaveBeenCalled();
+    expect(enableLineWrapping).not.toHaveBeenCalled();
+    expect(disableLineWrapping).not.toHaveBeenCalled();
+    expect(enableMouseEvents).not.toHaveBeenCalled();
+
+    unmount();
+  });
+
+  it('warns and skips suspension on windows', () => {
+    setPlatform('win32');
+
+    const handleWarning = vi.fn();
+    const setRawMode = vi.fn();
+    const refreshStatic = vi.fn();
+    const setForceRerenderKey = vi.fn();
+
+    const { result, unmount } = renderHook(() =>
+      useSuspend({
+        handleWarning,
+        setRawMode,
+        refreshStatic,
+        setForceRerenderKey,
+        shouldUseAlternateScreen: true,
+      }),
+    );
+
+    act(() => {
+      result.current.handleSuspend();
+    });
+    handleWarning.mockClear();
+
+    act(() => {
+      result.current.handleSuspend();
+    });
+
+    expect(handleWarning).toHaveBeenCalledWith(
+      'Ctrl+Z suspend is not supported on Windows.',
+    );
+    expect(killSpy).not.toHaveBeenCalled();
+    expect(cleanupTerminalOnExit).not.toHaveBeenCalled();
+
+    unmount();
+  });
+});
diff --git a/packages/cli/src/ui/hooks/useSuspend.ts b/packages/cli/src/ui/hooks/useSuspend.ts
new file mode 100644
index 0000000000..9c986d30d6
--- /dev/null
+++ b/packages/cli/src/ui/hooks/useSuspend.ts
@@ -0,0 +1,155 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useState, useRef, useEffect, useCallback } from 'react';
+import {
+  writeToStdout,
+  disableMouseEvents,
+  enableMouseEvents,
+  enterAlternateScreen,
+  exitAlternateScreen,
+  enableLineWrapping,
+  disableLineWrapping,
+} from '@google/gemini-cli-core';
+import process from 'node:process';
+import {
+  cleanupTerminalOnExit,
+  terminalCapabilityManager,
+} from '../utils/terminalCapabilityManager.js';
+import { WARNING_PROMPT_DURATION_MS } from '../constants.js';
+
+interface UseSuspendProps {
+  handleWarning: (message: string) => void;
+  setRawMode: (mode: boolean) => void;
+  refreshStatic: () => void;
+  setForceRerenderKey: (updater: (prev: number) => number) => void;
+  shouldUseAlternateScreen: boolean;
+}
+
+export function useSuspend({
+  handleWarning,
+  setRawMode,
+  refreshStatic,
+  setForceRerenderKey,
+  shouldUseAlternateScreen,
+}: UseSuspendProps) {
+  const [ctrlZPressCount, setCtrlZPressCount] = useState(0);
+  const ctrlZTimerRef = useRef<NodeJS.Timeout | null>(null);
+  const onResumeHandlerRef = useRef<(() => void) | null>(null);
+
+  useEffect(
+    () => () => {
+      if (ctrlZTimerRef.current) {
+        clearTimeout(ctrlZTimerRef.current);
+        ctrlZTimerRef.current = null;
+      }
+      if (onResumeHandlerRef.current) {
+        process.off('SIGCONT', onResumeHandlerRef.current);
+        onResumeHandlerRef.current = null;
+      }
+    },
+    [],
+  );
+
+  useEffect(() => {
+    if (ctrlZTimerRef.current) {
+      clearTimeout(ctrlZTimerRef.current);
+      ctrlZTimerRef.current = null;
+    }
+    if (ctrlZPressCount > 1) {
+      setCtrlZPressCount(0);
+      if (process.platform === 'win32') {
+        handleWarning('Ctrl+Z suspend is not supported on Windows.');
+        return;
+      }
+
+      if (shouldUseAlternateScreen) {
+        // Leave alternate buffer before suspension so the shell stays usable.
+        exitAlternateScreen();
+        enableLineWrapping();
+        writeToStdout('\x1b[2J\x1b[H');
+      }
+
+      // Cleanup before suspend.
+      writeToStdout('\x1b[?25h'); // Show cursor
+      disableMouseEvents();
+      cleanupTerminalOnExit();
+
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      setRawMode(false);
+
+      const onResume = () => {
+        try {
+          // Restore terminal state.
+          if (process.stdin.isTTY) {
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            process.stdin.ref();
+          }
+          setRawMode(true);
+
+          if (shouldUseAlternateScreen) {
+            enterAlternateScreen();
+            disableLineWrapping();
+            writeToStdout('\x1b[2J\x1b[H');
+          }
+
+          terminalCapabilityManager.enableSupportedModes();
+          writeToStdout('\x1b[?25l'); // Hide cursor
+          if (shouldUseAlternateScreen) {
+            enableMouseEvents();
+          }
+
+          // Force Ink to do a complete repaint by:
+          // 1. Emitting a resize event (tricks Ink into full redraw)
+          // 2. Remounting components via state changes
+          process.stdout.emit('resize');
+
+          // Give a tick for resize to process, then trigger remount
+          setImmediate(() => {
+            refreshStatic();
+            setForceRerenderKey((prev) => prev + 1);
+          });
+        } finally {
+          if (onResumeHandlerRef.current === onResume) {
+            onResumeHandlerRef.current = null;
+          }
+        }
+      };
+
+      if (onResumeHandlerRef.current) {
+        process.off('SIGCONT', onResumeHandlerRef.current);
+      }
+      onResumeHandlerRef.current = onResume;
+      process.once('SIGCONT', onResume);
+
+      process.kill(0, 'SIGTSTP');
+    } else if (ctrlZPressCount > 0) {
+      handleWarning(
+        'Press Ctrl+Z again to suspend. Undo has moved to Cmd + Z or Alt/Opt + Z.',
+      );
+      ctrlZTimerRef.current = setTimeout(() => {
+        setCtrlZPressCount(0);
+        ctrlZTimerRef.current = null;
+      }, WARNING_PROMPT_DURATION_MS);
+    }
+  }, [
+    ctrlZPressCount,
+    handleWarning,
+    setRawMode,
+    refreshStatic,
+    setForceRerenderKey,
+    shouldUseAlternateScreen,
+  ]);
+
+  const handleSuspend = useCallback(() => {
+    setCtrlZPressCount((prev) => prev + 1);
+  }, []);
+
+  return { handleSuspend };
+}
diff --git a/packages/cli/src/ui/keyMatchers.test.ts b/packages/cli/src/ui/keyMatchers.test.ts
index 3b7c14d896..a014d2bdc1 100644
--- a/packages/cli/src/ui/keyMatchers.test.ts
+++ b/packages/cli/src/ui/keyMatchers.test.ts
@@ -330,6 +330,18 @@ describe('keyMatchers', () => {
       positive: [createKey('d', { ctrl: true })],
       negative: [createKey('d'), createKey('c', { ctrl: true })],
     },
+    {
+      command: Command.SUSPEND_APP,
+      positive: [
+        createKey('z', { ctrl: true }),
+        createKey('z', { ctrl: true, shift: true }),
+      ],
+      negative: [
+        createKey('z'),
+        createKey('y', { ctrl: true }),
+        createKey('z', { alt: true }),
+      ],
+    },
     {
       command: Command.SHOW_MORE_LINES,
       positive: [
diff --git a/packages/cli/src/ui/utils/terminalCapabilityManager.ts b/packages/cli/src/ui/utils/terminalCapabilityManager.ts
index 94e3ecb8ff..8fa2146072 100644
--- a/packages/cli/src/ui/utils/terminalCapabilityManager.ts
+++ b/packages/cli/src/ui/utils/terminalCapabilityManager.ts
@@ -18,6 +18,23 @@ import { parseColor } from '../themes/color-utils.js';
 
 export type TerminalBackgroundColor = string | undefined;
 
+const TERMINAL_CLEANUP_SEQUENCE = '\x1b[<u\x1b[>4;0m\x1b[?2004l';
+
+export function cleanupTerminalOnExit() {
+  try {
+    if (process.stdout?.fd !== undefined) {
+      fs.writeSync(process.stdout.fd, TERMINAL_CLEANUP_SEQUENCE);
+      return;
+    }
+  } catch (e) {
+    debugLogger.warn('Failed to synchronously cleanup terminal modes:', e);
+  }
+
+  disableKittyKeyboardProtocol();
+  disableModifyOtherKeys();
+  disableBracketedPasteMode();
+}
+
 export class TerminalCapabilityManager {
   private static instance: TerminalCapabilityManager | undefined;
 
@@ -64,14 +81,6 @@ export class TerminalCapabilityManager {
     this.instance = undefined;
   }
 
-  private static cleanupOnExit(): void {
-    // don't bother catching errors since if one write
-    // fails, the other probably will too
-    disableKittyKeyboardProtocol();
-    disableModifyOtherKeys();
-    disableBracketedPasteMode();
-  }
-
   /**
    * Detects terminal capabilities (Kitty protocol support, terminal name,
    * background color).
@@ -85,12 +94,12 @@ export class TerminalCapabilityManager {
       return;
     }
 
-    process.off('exit', TerminalCapabilityManager.cleanupOnExit);
-    process.off('SIGTERM', TerminalCapabilityManager.cleanupOnExit);
-    process.off('SIGINT', TerminalCapabilityManager.cleanupOnExit);
-    process.on('exit', TerminalCapabilityManager.cleanupOnExit);
-    process.on('SIGTERM', TerminalCapabilityManager.cleanupOnExit);
-    process.on('SIGINT', TerminalCapabilityManager.cleanupOnExit);
+    process.off('exit', cleanupTerminalOnExit);
+    process.off('SIGTERM', cleanupTerminalOnExit);
+    process.off('SIGINT', cleanupTerminalOnExit);
+    process.on('exit', cleanupTerminalOnExit);
+    process.on('SIGTERM', cleanupTerminalOnExit);
+    process.on('SIGINT', cleanupTerminalOnExit);
 
     return new Promise((resolve) => {
       const originalRawMode = process.stdin.isRaw;

From 2d38623472284a5bf7ef7f644ef8eccb2e7dd2fd Mon Sep 17 00:00:00 2001
From: Sandy Tao <sandytao520@icloud.com>
Date: Thu, 12 Feb 2026 10:01:04 -0800
Subject: [PATCH 22/44] fix(github-actions): use robot PAT for release creation
 to trigger release notes (#18794)

---
 .github/actions/publish-release/action.yml    | 5 ++++-
 .github/workflows/release-manual.yml          | 1 +
 .github/workflows/release-nightly.yml         | 3 ++-
 .github/workflows/release-patch-3-release.yml | 1 +
 .github/workflows/release-promote.yml         | 4 +++-
 5 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/.github/actions/publish-release/action.yml b/.github/actions/publish-release/action.yml
index c37444498a..5c74524ddb 100644
--- a/.github/actions/publish-release/action.yml
+++ b/.github/actions/publish-release/action.yml
@@ -20,6 +20,9 @@ inputs:
   github-token:
     description: 'The GitHub token for creating the release.'
     required: true
+  github-release-token:
+    description: 'The GitHub token used specifically for creating the GitHub release (to trigger other workflows).'
+    required: false
   dry-run:
     description: 'Whether to run in dry-run mode.'
     type: 'string'
@@ -254,7 +257,7 @@ runs:
       working-directory: '${{ inputs.working-directory }}'
       if: "${{ inputs.dry-run != 'true' && inputs.skip-github-release != 'true' && inputs.npm-tag != 'dev' && inputs.npm-registry-url != 'https://npm.pkg.github.com/' }}"
       env:
-        GITHUB_TOKEN: '${{ inputs.github-token }}'
+        GITHUB_TOKEN: '${{ inputs.github-release-token || inputs.github-token }}'
       shell: 'bash'
       run: |
         gh release create "${{ inputs.release-tag }}" \
diff --git a/.github/workflows/release-manual.yml b/.github/workflows/release-manual.yml
index b393d87ea9..c9d2290a1c 100644
--- a/.github/workflows/release-manual.yml
+++ b/.github/workflows/release-manual.yml
@@ -110,6 +110,7 @@ jobs:
           wombat-token-cli: '${{ secrets.WOMBAT_TOKEN_CLI }}'
           wombat-token-a2a-server: '${{ secrets.WOMBAT_TOKEN_A2A_SERVER }}'
           github-token: '${{ secrets.GITHUB_TOKEN }}'
+          github-release-token: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'
           dry-run: '${{ github.event.inputs.dry_run }}'
           previous-tag: '${{ steps.release_info.outputs.PREVIOUS_TAG }}'
           skip-github-release: '${{ github.event.inputs.skip_github_release }}'
diff --git a/.github/workflows/release-nightly.yml b/.github/workflows/release-nightly.yml
index 5fe7bca115..0a04e93517 100644
--- a/.github/workflows/release-nightly.yml
+++ b/.github/workflows/release-nightly.yml
@@ -124,6 +124,7 @@ jobs:
           wombat-token-cli: '${{ secrets.WOMBAT_TOKEN_CLI }}'
           wombat-token-a2a-server: '${{ secrets.WOMBAT_TOKEN_A2A_SERVER }}'
           github-token: '${{ secrets.GITHUB_TOKEN }}'
+          github-release-token: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'
           dry-run: '${{ steps.vars.outputs.is_dry_run }}'
           previous-tag: '${{ steps.nightly_version.outputs.PREVIOUS_TAG }}'
           working-directory: './release'
@@ -144,7 +145,7 @@ jobs:
           branch-name: 'release/${{ steps.nightly_version.outputs.RELEASE_TAG }}'
           pr-title: 'chore/release: bump version to ${{ steps.nightly_version.outputs.RELEASE_VERSION }}'
           pr-body: 'Automated version bump for nightly release.'
-          github-token: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'
+          github-token: '${{ secrets.GITHUB_TOKEN }}'
           dry-run: '${{ steps.vars.outputs.is_dry_run }}'
           working-directory: './release'
 
diff --git a/.github/workflows/release-patch-3-release.yml b/.github/workflows/release-patch-3-release.yml
index 19241b7396..b0d459f256 100644
--- a/.github/workflows/release-patch-3-release.yml
+++ b/.github/workflows/release-patch-3-release.yml
@@ -184,6 +184,7 @@ jobs:
           wombat-token-cli: '${{ secrets.WOMBAT_TOKEN_CLI }}'
           wombat-token-a2a-server: '${{ secrets.WOMBAT_TOKEN_A2A_SERVER }}'
           github-token: '${{ secrets.GITHUB_TOKEN }}'
+          github-release-token: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'
           dry-run: '${{ github.event.inputs.dry_run }}'
           previous-tag: '${{ steps.patch_version.outputs.PREVIOUS_TAG }}'
           gemini_api_key: '${{ secrets.GEMINI_API_KEY }}'
diff --git a/.github/workflows/release-promote.yml b/.github/workflows/release-promote.yml
index 486b9a2558..ebe16b1a39 100644
--- a/.github/workflows/release-promote.yml
+++ b/.github/workflows/release-promote.yml
@@ -239,6 +239,7 @@ jobs:
           wombat-token-cli: '${{ secrets.WOMBAT_TOKEN_CLI }}'
           wombat-token-a2a-server: '${{ secrets.WOMBAT_TOKEN_A2A_SERVER }}'
           github-token: '${{ secrets.GITHUB_TOKEN }}'
+          github-release-token: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'
           dry-run: '${{ github.event.inputs.dry_run }}'
           previous-tag: '${{ needs.calculate-versions.outputs.PREVIOUS_PREVIEW_TAG }}'
           working-directory: './release'
@@ -305,6 +306,7 @@ jobs:
           wombat-token-cli: '${{ secrets.WOMBAT_TOKEN_CLI }}'
           wombat-token-a2a-server: '${{ secrets.WOMBAT_TOKEN_A2A_SERVER }}'
           github-token: '${{ secrets.GITHUB_TOKEN }}'
+          github-release-token: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'
           dry-run: '${{ github.event.inputs.dry_run }}'
           previous-tag: '${{ needs.calculate-versions.outputs.PREVIOUS_STABLE_TAG }}'
           working-directory: './release'
@@ -390,7 +392,7 @@ jobs:
           branch-name: '${{ steps.release_branch.outputs.BRANCH_NAME }}'
           pr-title: 'chore(release): bump version to ${{ needs.calculate-versions.outputs.NEXT_NIGHTLY_VERSION }}'
           pr-body: 'Automated version bump to prepare for the next nightly release.'
-          github-token: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'
+          github-token: '${{ secrets.GITHUB_TOKEN }}'
           dry-run: '${{ github.event.inputs.dry_run }}'
 
       - name: 'Create Issue on Failure'

From 2e91c03e08f485c21c0d991cead81436ae8635b9 Mon Sep 17 00:00:00 2001
From: Sandy Tao <sandytao520@icloud.com>
Date: Thu, 12 Feb 2026 10:33:54 -0800
Subject: [PATCH 23/44] feat: add strict seatbelt profiles and remove unusable
 closed profiles (#18876)

---
 CONTRIBUTING.md                               |  13 +-
 docs/cli/sandbox.md                           |   5 +-
 docs/get-started/configuration.md             |   5 +-
 .../utils/sandbox-macos-permissive-closed.sb  |  32 -----
 ...closed.sb => sandbox-macos-strict-open.sb} |  46 +++++-
 .../src/utils/sandbox-macos-strict-proxied.sb | 133 ++++++++++++++++++
 packages/cli/src/utils/sandboxUtils.ts        |   4 +-
 packages/core/src/config/config.ts            |   3 +-
 8 files changed, 193 insertions(+), 48 deletions(-)
 delete mode 100644 packages/cli/src/utils/sandbox-macos-permissive-closed.sb
 rename packages/cli/src/utils/{sandbox-macos-restrictive-closed.sb => sandbox-macos-strict-open.sb} (64%)
 create mode 100644 packages/cli/src/utils/sandbox-macos-strict-proxied.sb

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e3ff7505c7..6d8252f86c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -408,12 +408,13 @@ On macOS, `gemini` uses Seatbelt (`sandbox-exec`) under a `permissive-open`
 profile (see `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) that
 restricts writes to the project folder but otherwise allows all other operations
 and outbound network traffic ("open") by default. You can switch to a
-`restrictive-closed` profile (see
-`packages/cli/src/utils/sandbox-macos-restrictive-closed.sb`) that declines all
-operations and outbound network traffic ("closed") by default by setting
-`SEATBELT_PROFILE=restrictive-closed` in your environment or `.env` file.
-Available built-in profiles are `{permissive,restrictive}-{open,closed,proxied}`
-(see below for proxied networking). You can also switch to a custom profile
+`strict-open` profile (see
+`packages/cli/src/utils/sandbox-macos-strict-open.sb`) that restricts both reads
+and writes to the working directory while allowing outbound network traffic by
+setting `SEATBELT_PROFILE=strict-open` in your environment or `.env` file.
+Available built-in profiles are `permissive-{open,proxied}`,
+`restrictive-{open,proxied}`, and `strict-{open,proxied}` (see below for proxied
+networking). You can also switch to a custom profile
 `SEATBELT_PROFILE=<profile>` if you also create a file
 `.gemini/sandbox-macos-<profile>.sb` under your project settings directory
 `.gemini`.
diff --git a/docs/cli/sandbox.md b/docs/cli/sandbox.md
index 28b54851c2..9f632693c7 100644
--- a/docs/cli/sandbox.md
+++ b/docs/cli/sandbox.md
@@ -82,10 +82,11 @@ gemini -p "run the test suite"
 Built-in profiles (set via `SEATBELT_PROFILE` env var):
 
 - `permissive-open` (default): Write restrictions, network allowed
-- `permissive-closed`: Write restrictions, no network
 - `permissive-proxied`: Write restrictions, network via proxy
 - `restrictive-open`: Strict restrictions, network allowed
-- `restrictive-closed`: Maximum restrictions
+- `restrictive-proxied`: Strict restrictions, network via proxy
+- `strict-open`: Read and write restrictions, network allowed
+- `strict-proxied`: Read and write restrictions, network via proxy
 
 ### Custom sandbox flags
 
diff --git a/docs/get-started/configuration.md b/docs/get-started/configuration.md
index 263dd815a8..32c0bf30b1 100644
--- a/docs/get-started/configuration.md
+++ b/docs/get-started/configuration.md
@@ -1290,7 +1290,10 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file.
     few other folders, see
     `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) but allows other
     operations.
-  - `strict`: Uses a strict profile that declines operations by default.
+  - `restrictive-open`: Declines operations by default, allows network.
+  - `strict-open`: Restricts both reads and writes to the working directory,
+    allows network.
+  - `strict-proxied`: Same as `strict-open` but routes network through proxy.
   - `<profile_name>`: Uses a custom profile. To define a custom profile, create
     a file named `sandbox-macos-<profile_name>.sb` in your project's `.gemini/`
     directory (e.g., `my-project/.gemini/sandbox-macos-custom.sb`).
diff --git a/packages/cli/src/utils/sandbox-macos-permissive-closed.sb b/packages/cli/src/utils/sandbox-macos-permissive-closed.sb
deleted file mode 100644
index cf64da9450..0000000000
--- a/packages/cli/src/utils/sandbox-macos-permissive-closed.sb
+++ /dev/null
@@ -1,32 +0,0 @@
-(version 1)
-
-;; allow everything by default
-(allow default)
-
-;; deny all writes EXCEPT under specific paths
-(deny file-write*)
-(allow file-write*
-    (subpath (param "TARGET_DIR"))
-    (subpath (param "TMP_DIR"))
-    (subpath (param "CACHE_DIR"))
-    (subpath (string-append (param "HOME_DIR") "/.gemini"))
-    (subpath (string-append (param "HOME_DIR") "/.npm"))
-    (subpath (string-append (param "HOME_DIR") "/.cache"))
-    (subpath (string-append (param "HOME_DIR") "/.gitconfig"))
-    ;; Allow writes to included directories from --include-directories
-    (subpath (param "INCLUDE_DIR_0"))
-    (subpath (param "INCLUDE_DIR_1"))
-    (subpath (param "INCLUDE_DIR_2"))
-    (subpath (param "INCLUDE_DIR_3"))
-    (subpath (param "INCLUDE_DIR_4"))
-    (literal "/dev/stdout")
-    (literal "/dev/stderr")
-    (literal "/dev/null")
-)
-
-;; deny all inbound network traffic EXCEPT on debugger port
-(deny network-inbound)
-(allow network-inbound (local ip "localhost:9229"))
-
-;; deny all outbound network traffic
-(deny network-outbound)
diff --git a/packages/cli/src/utils/sandbox-macos-restrictive-closed.sb b/packages/cli/src/utils/sandbox-macos-strict-open.sb
similarity index 64%
rename from packages/cli/src/utils/sandbox-macos-restrictive-closed.sb
rename to packages/cli/src/utils/sandbox-macos-strict-open.sb
index 17d0c07320..e5cbd1b334 100644
--- a/packages/cli/src/utils/sandbox-macos-restrictive-closed.sb
+++ b/packages/cli/src/utils/sandbox-macos-strict-open.sb
@@ -3,8 +3,43 @@
 ;; deny everything by default
 (deny default)
 
-;; allow reading files from anywhere on host
-(allow file-read*)
+;; allow reading ONLY from working directory, system paths, and essential user paths
+(allow file-read*
+    (literal "/")
+    (subpath (param "TARGET_DIR"))
+    (subpath (param "TMP_DIR"))
+    (subpath (param "CACHE_DIR"))
+    ;; Only allow reading essential dotfiles/directories under HOME, not the entire HOME
+    (subpath (string-append (param "HOME_DIR") "/.gemini"))
+    (subpath (string-append (param "HOME_DIR") "/.npm"))
+    (subpath (string-append (param "HOME_DIR") "/.cache"))
+    (literal (string-append (param "HOME_DIR") "/.gitconfig"))
+    (subpath (string-append (param "HOME_DIR") "/.nvm"))
+    (subpath (string-append (param "HOME_DIR") "/.fnm"))
+    (subpath (string-append (param "HOME_DIR") "/.node"))
+    (subpath (string-append (param "HOME_DIR") "/.config"))
+    ;; Allow reads from included directories
+    (subpath (param "INCLUDE_DIR_0"))
+    (subpath (param "INCLUDE_DIR_1"))
+    (subpath (param "INCLUDE_DIR_2"))
+    (subpath (param "INCLUDE_DIR_3"))
+    (subpath (param "INCLUDE_DIR_4"))
+    ;; System paths required for Node.js, shell, and common tools
+    (subpath "/usr")
+    (subpath "/bin")
+    (subpath "/sbin")
+    (subpath "/Library")
+    (subpath "/System")
+    (subpath "/private")
+    (subpath "/dev")
+    (subpath "/etc")
+    (subpath "/opt")
+    (subpath "/Applications")
+)
+
+;; allow path traversal everywhere (metadata only: stat/lstat, NOT readdir or file content)
+;; this is needed for Node.js module resolution to traverse intermediate directories
+(allow file-read-metadata)
 
 ;; allow exec/fork (children inherit policy)
 (allow process-exec)
@@ -70,7 +105,7 @@
     (subpath (string-append (param "HOME_DIR") "/.gemini"))
     (subpath (string-append (param "HOME_DIR") "/.npm"))
     (subpath (string-append (param "HOME_DIR") "/.cache"))
-    (subpath (string-append (param "HOME_DIR") "/.gitconfig"))
+    (literal (string-append (param "HOME_DIR") "/.gitconfig"))
     ;; Allow writes to included directories from --include-directories
     (subpath (param "INCLUDE_DIR_0"))
     (subpath (param "INCLUDE_DIR_1"))
@@ -90,4 +125,7 @@
 (allow file-ioctl (regex #"^/dev/tty.*"))
 
 ;; allow inbound network traffic on debugger port
-(allow network-inbound (local ip "localhost:9229"))
\ No newline at end of file
+(allow network-inbound (local ip "localhost:9229"))
+
+;; allow all outbound network traffic
+(allow network-outbound)
diff --git a/packages/cli/src/utils/sandbox-macos-strict-proxied.sb b/packages/cli/src/utils/sandbox-macos-strict-proxied.sb
new file mode 100644
index 0000000000..53b102f43e
--- /dev/null
+++ b/packages/cli/src/utils/sandbox-macos-strict-proxied.sb
@@ -0,0 +1,133 @@
+(version 1)
+
+;; deny everything by default
+(deny default)
+
+;; allow reading ONLY from working directory, system paths, and essential user paths
+(allow file-read*
+    (literal "/")
+    (subpath (param "TARGET_DIR"))
+    (subpath (param "TMP_DIR"))
+    (subpath (param "CACHE_DIR"))
+    ;; Only allow reading essential dotfiles/directories under HOME, not the entire HOME
+    (subpath (string-append (param "HOME_DIR") "/.gemini"))
+    (subpath (string-append (param "HOME_DIR") "/.npm"))
+    (subpath (string-append (param "HOME_DIR") "/.cache"))
+    (literal (string-append (param "HOME_DIR") "/.gitconfig"))
+    (subpath (string-append (param "HOME_DIR") "/.nvm"))
+    (subpath (string-append (param "HOME_DIR") "/.fnm"))
+    (subpath (string-append (param "HOME_DIR") "/.node"))
+    (subpath (string-append (param "HOME_DIR") "/.config"))
+    ;; Allow reads from included directories
+    (subpath (param "INCLUDE_DIR_0"))
+    (subpath (param "INCLUDE_DIR_1"))
+    (subpath (param "INCLUDE_DIR_2"))
+    (subpath (param "INCLUDE_DIR_3"))
+    (subpath (param "INCLUDE_DIR_4"))
+    ;; System paths required for Node.js, shell, and common tools
+    (subpath "/usr")
+    (subpath "/bin")
+    (subpath "/sbin")
+    (subpath "/Library")
+    (subpath "/System")
+    (subpath "/private")
+    (subpath "/dev")
+    (subpath "/etc")
+    (subpath "/opt")
+    (subpath "/Applications")
+)
+
+;; allow path traversal everywhere (metadata only: stat/lstat, NOT readdir or file content)
+;; this is needed for Node.js module resolution to traverse intermediate directories
+(allow file-read-metadata)
+
+;; allow exec/fork (children inherit policy)
+(allow process-exec)
+(allow process-fork)
+
+;; allow signals to self, e.g. SIGPIPE on write to closed pipe
+(allow signal (target self))
+
+;; allow read access to specific information about system
+;; from https://source.chromium.org/chromium/chromium/src/+/main:sandbox/policy/mac/common.sb;l=273-319;drc=7b3962fe2e5fc9e2ee58000dc8fbf3429d84d3bd
+(allow sysctl-read
+  (sysctl-name "hw.activecpu")
+  (sysctl-name "hw.busfrequency_compat")
+  (sysctl-name "hw.byteorder")
+  (sysctl-name "hw.cacheconfig")
+  (sysctl-name "hw.cachelinesize_compat")
+  (sysctl-name "hw.cpufamily")
+  (sysctl-name "hw.cpufrequency_compat")
+  (sysctl-name "hw.cputype")
+  (sysctl-name "hw.l1dcachesize_compat")
+  (sysctl-name "hw.l1icachesize_compat")
+  (sysctl-name "hw.l2cachesize_compat")
+  (sysctl-name "hw.l3cachesize_compat")
+  (sysctl-name "hw.logicalcpu_max")
+  (sysctl-name "hw.machine")
+  (sysctl-name "hw.ncpu")
+  (sysctl-name "hw.nperflevels")
+  (sysctl-name "hw.optional.arm.FEAT_BF16")
+  (sysctl-name "hw.optional.arm.FEAT_DotProd")
+  (sysctl-name "hw.optional.arm.FEAT_FCMA")
+  (sysctl-name "hw.optional.arm.FEAT_FHM")
+  (sysctl-name "hw.optional.arm.FEAT_FP16")
+  (sysctl-name "hw.optional.arm.FEAT_I8MM")
+  (sysctl-name "hw.optional.arm.FEAT_JSCVT")
+  (sysctl-name "hw.optional.arm.FEAT_LSE")
+  (sysctl-name "hw.optional.arm.FEAT_RDM")
+  (sysctl-name "hw.optional.arm.FEAT_SHA512")
+  (sysctl-name "hw.optional.armv8_2_sha512")
+  (sysctl-name "hw.packages")
+  (sysctl-name "hw.pagesize_compat")
+  (sysctl-name "hw.physicalcpu_max")
+  (sysctl-name "hw.tbfrequency_compat")
+  (sysctl-name "hw.vectorunit")
+  (sysctl-name "kern.hostname")
+  (sysctl-name "kern.maxfilesperproc")
+  (sysctl-name "kern.osproductversion")
+  (sysctl-name "kern.osrelease")
+  (sysctl-name "kern.ostype")
+  (sysctl-name "kern.osvariant_status")
+  (sysctl-name "kern.osversion")
+  (sysctl-name "kern.secure_kernel")
+  (sysctl-name "kern.usrstack64")
+  (sysctl-name "kern.version")
+  (sysctl-name "sysctl.proc_cputype")
+  (sysctl-name-prefix "hw.perflevel")
+)
+
+;; allow writes to specific paths
+(allow file-write*
+    (subpath (param "TARGET_DIR"))
+    (subpath (param "TMP_DIR"))
+    (subpath (param "CACHE_DIR"))
+    (subpath (string-append (param "HOME_DIR") "/.gemini"))
+    (subpath (string-append (param "HOME_DIR") "/.npm"))
+    (subpath (string-append (param "HOME_DIR") "/.cache"))
+    (literal (string-append (param "HOME_DIR") "/.gitconfig"))
+    ;; Allow writes to included directories from --include-directories
+    (subpath (param "INCLUDE_DIR_0"))
+    (subpath (param "INCLUDE_DIR_1"))
+    (subpath (param "INCLUDE_DIR_2"))
+    (subpath (param "INCLUDE_DIR_3"))
+    (subpath (param "INCLUDE_DIR_4"))
+    (literal "/dev/stdout")
+    (literal "/dev/stderr")
+    (literal "/dev/null")
+)
+
+;; allow communication with sysmond for process listing (e.g. for pgrep)
+(allow mach-lookup (global-name "com.apple.sysmond"))
+
+;; enable terminal access required by ink
+;; fixes setRawMode EPERM failure (at node:tty:81:24)
+(allow file-ioctl (regex #"^/dev/tty.*"))
+
+;; allow inbound network traffic on debugger port
+(allow network-inbound (local ip "localhost:9229"))
+
+;; allow outbound network traffic through proxy on localhost:8877
+;; set `GEMINI_SANDBOX_PROXY_COMMAND=<command>` to run proxy alongside sandbox
+;; proxy must listen on :::8877 (see docs/examples/proxy-script.md)
+(allow network-outbound (remote tcp "localhost:8877"))
diff --git a/packages/cli/src/utils/sandboxUtils.ts b/packages/cli/src/utils/sandboxUtils.ts
index 48cfb30f00..b33a1af3a3 100644
--- a/packages/cli/src/utils/sandboxUtils.ts
+++ b/packages/cli/src/utils/sandboxUtils.ts
@@ -15,11 +15,11 @@ export const SANDBOX_NETWORK_NAME = 'gemini-cli-sandbox';
 export const SANDBOX_PROXY_NAME = 'gemini-cli-sandbox-proxy';
 export const BUILTIN_SEATBELT_PROFILES = [
   'permissive-open',
-  'permissive-closed',
   'permissive-proxied',
   'restrictive-open',
-  'restrictive-closed',
   'restrictive-proxied',
+  'strict-open',
+  'strict-proxied',
 ];
 
 export function getContainerPath(hostPath: string): string {
diff --git a/packages/core/src/config/config.ts b/packages/core/src/config/config.ts
index 944d14fb39..8aab58da08 100644
--- a/packages/core/src/config/config.ts
+++ b/packages/core/src/config/config.ts
@@ -1343,7 +1343,8 @@ export class Config {
       !!sandboxConfig &&
       sandboxConfig.command === 'sandbox-exec' &&
       !!seatbeltProfile &&
-      seatbeltProfile.startsWith('restrictive-')
+      (seatbeltProfile.startsWith('restrictive-') ||
+        seatbeltProfile.startsWith('strict-'))
     );
   }
 

From d243dfce142dcf252118f529817040f94cc72712 Mon Sep 17 00:00:00 2001
From: Adam Weidman <65992621+adamfweidman@users.noreply.github.com>
Date: Thu, 12 Feb 2026 13:40:52 -0500
Subject: [PATCH 24/44] chore: cleanup unused and add unlisted dependencies in
 packages/a2a-server (#18916)

---
 package-lock.json                | 2 ++
 packages/a2a-server/package.json | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/package-lock.json b/package-lock.json
index e8bb6e6902..c457eb7d55 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -17245,6 +17245,7 @@
         "@google/gemini-cli-core": "file:../core",
         "express": "^5.1.0",
         "fs-extra": "^11.3.0",
+        "strip-json-comments": "^3.1.1",
         "tar": "^7.5.2",
         "uuid": "^13.0.0",
         "winston": "^3.17.0"
@@ -17253,6 +17254,7 @@
         "gemini-cli-a2a-server": "dist/a2a-server.mjs"
       },
       "devDependencies": {
+        "@google/genai": "^1.30.0",
         "@types/express": "^5.0.3",
         "@types/fs-extra": "^11.0.4",
         "@types/supertest": "^6.0.3",
diff --git a/packages/a2a-server/package.json b/packages/a2a-server/package.json
index 774b2f5c83..96001898a0 100644
--- a/packages/a2a-server/package.json
+++ b/packages/a2a-server/package.json
@@ -30,11 +30,13 @@
     "@google/gemini-cli-core": "file:../core",
     "express": "^5.1.0",
     "fs-extra": "^11.3.0",
+    "strip-json-comments": "^3.1.1",
     "tar": "^7.5.2",
     "uuid": "^13.0.0",
     "winston": "^3.17.0"
   },
   "devDependencies": {
+    "@google/genai": "^1.30.0",
     "@types/express": "^5.0.3",
     "@types/fs-extra": "^11.0.4",
     "@types/supertest": "^6.0.3",

From 0b3130cec7efd70b32806e2c7dfc86c0ca7ea83d Mon Sep 17 00:00:00 2001
From: Adib234 <30782825+Adib234@users.noreply.github.com>
Date: Thu, 12 Feb 2026 14:02:59 -0500
Subject: [PATCH 25/44] fix(plan): isolate plan files per session (#18757)

---
 docs/cli/plan-mode.md                              |  2 +-
 .../src/config/policy-engine.integration.test.ts   |  7 +++----
 packages/core/src/config/config.ts                 |  2 +-
 packages/core/src/config/storage.test.ts           | 14 +++++++++++++-
 packages/core/src/config/storage.ts                | 14 +++++++++++++-
 packages/core/src/policy/policies/plan.toml        |  2 +-
 6 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/docs/cli/plan-mode.md b/docs/cli/plan-mode.md
index 751794996b..1e88560f7a 100644
--- a/docs/cli/plan-mode.md
+++ b/docs/cli/plan-mode.md
@@ -99,7 +99,7 @@ These are the only allowed tools:
 - **MCP Tools (Read):** Read-only [MCP tools] (e.g., `github_read_issue`,
   `postgres_read_schema`) are allowed.
 - **Planning (Write):** [`write_file`] and [`replace`] ONLY allowed for `.md`
-  files in the `~/.gemini/tmp/<project>/plans/` directory.
+  files in the `~/.gemini/tmp/<project>/<session-id>/plans/` directory.
 - **Skills:** [`activate_skill`] (allows loading specialized instructions and
   resources in a read-only manner)
 
diff --git a/packages/cli/src/config/policy-engine.integration.test.ts b/packages/cli/src/config/policy-engine.integration.test.ts
index 0568aa62bc..2c7ce599da 100644
--- a/packages/cli/src/config/policy-engine.integration.test.ts
+++ b/packages/cli/src/config/policy-engine.integration.test.ts
@@ -336,9 +336,9 @@ describe('Policy Engine Integration Tests', () => {
 
           // Valid plan file paths
           const validPaths = [
-            '/home/user/.gemini/tmp/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2/plans/my-plan.md',
-            '/home/user/.gemini/tmp/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2/plans/feature_auth.md',
-            '/home/user/.gemini/tmp/new-temp_dir_123/plans/plan.md', // new style of temp directory
+            '/home/user/.gemini/tmp/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2/session-1/plans/my-plan.md',
+            '/home/user/.gemini/tmp/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2/session-1/plans/feature_auth.md',
+            '/home/user/.gemini/tmp/new-temp_dir_123/session-1/plans/plan.md', // new style of temp directory
           ];
 
           for (const file_path of validPaths) {
@@ -365,7 +365,6 @@ describe('Policy Engine Integration Tests', () => {
             '/project/src/file.ts', // Workspace
             '/home/user/.gemini/tmp/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2/plans/script.js', // Wrong extension
             '/home/user/.gemini/tmp/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2/plans/../../../etc/passwd.md', // Path traversal
-            '/home/user/.gemini/tmp/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2/plans/subdir/plan.md', // Subdirectory
             '/home/user/.gemini/non-tmp/new-temp_dir_123/plans/plan.md', // outside of temp dir
           ];
 
diff --git a/packages/core/src/config/config.ts b/packages/core/src/config/config.ts
index 8aab58da08..6dfc62f322 100644
--- a/packages/core/src/config/config.ts
+++ b/packages/core/src/config/config.ts
@@ -823,7 +823,7 @@ export class Config {
       (params.shellToolInactivityTimeout ?? 300) * 1000; // 5 minutes
     this.extensionManagement = params.extensionManagement ?? true;
     this.enableExtensionReloading = params.enableExtensionReloading ?? false;
-    this.storage = new Storage(this.targetDir);
+    this.storage = new Storage(this.targetDir, this.sessionId);
 
     this.fakeResponses = params.fakeResponses;
     this.recordResponses = params.recordResponses;
diff --git a/packages/core/src/config/storage.test.ts b/packages/core/src/config/storage.test.ts
index 8232033c07..8d91ca1a3e 100644
--- a/packages/core/src/config/storage.test.ts
+++ b/packages/core/src/config/storage.test.ts
@@ -154,12 +154,24 @@ describe('Storage – additional helpers', () => {
     expect(Storage.getGlobalBinDir()).toBe(expected);
   });
 
-  it('getProjectTempPlansDir returns ~/.gemini/tmp/<identifier>/plans', async () => {
+  it('getProjectTempPlansDir returns ~/.gemini/tmp/<identifier>/plans when no sessionId is provided', async () => {
     await storage.initialize();
     const tempDir = storage.getProjectTempDir();
     const expected = path.join(tempDir, 'plans');
     expect(storage.getProjectTempPlansDir()).toBe(expected);
   });
+
+  it('getProjectTempPlansDir returns ~/.gemini/tmp/<identifier>/<sessionId>/plans when sessionId is provided', async () => {
+    const sessionId = 'test-session-id';
+    const storageWithSession = new Storage(projectRoot, sessionId);
+    ProjectRegistry.prototype.getShortId = vi
+      .fn()
+      .mockReturnValue(PROJECT_SLUG);
+    await storageWithSession.initialize();
+    const tempDir = storageWithSession.getProjectTempDir();
+    const expected = path.join(tempDir, sessionId, 'plans');
+    expect(storageWithSession.getProjectTempPlansDir()).toBe(expected);
+  });
 });
 
 describe('Storage - System Paths', () => {
diff --git a/packages/core/src/config/storage.ts b/packages/core/src/config/storage.ts
index f407c29539..bd0fec1c8e 100644
--- a/packages/core/src/config/storage.ts
+++ b/packages/core/src/config/storage.ts
@@ -20,11 +20,13 @@ const AGENTS_DIR_NAME = '.agents';
 
 export class Storage {
   private readonly targetDir: string;
+  private readonly sessionId: string | undefined;
   private projectIdentifier: string | undefined;
   private initPromise: Promise<void> | undefined;
 
-  constructor(targetDir: string) {
+  constructor(targetDir: string, sessionId?: string) {
     this.targetDir = targetDir;
+    this.sessionId = sessionId;
   }
 
   static getGlobalGeminiDir(): string {
@@ -242,9 +244,19 @@ export class Storage {
   }
 
   getProjectTempPlansDir(): string {
+    if (this.sessionId) {
+      return path.join(this.getProjectTempDir(), this.sessionId, 'plans');
+    }
     return path.join(this.getProjectTempDir(), 'plans');
   }
 
+  getProjectTempTasksDir(): string {
+    if (this.sessionId) {
+      return path.join(this.getProjectTempDir(), this.sessionId, 'tasks');
+    }
+    return path.join(this.getProjectTempDir(), 'tasks');
+  }
+
   getExtensionsDir(): string {
     return path.join(this.getGeminiDir(), 'extensions');
   }
diff --git a/packages/core/src/policy/policies/plan.toml b/packages/core/src/policy/policies/plan.toml
index 656c100845..12648fec5f 100644
--- a/packages/core/src/policy/policies/plan.toml
+++ b/packages/core/src/policy/policies/plan.toml
@@ -53,4 +53,4 @@ toolName = ["write_file", "replace"]
 decision = "allow"
 priority = 70
 modes = ["plan"]
-argsPattern = "\"file_path\":\"[^\"]+/\\.gemini/tmp/[a-zA-Z0-9_-]+/plans/[a-zA-Z0-9_-]+\\.md\""
+argsPattern = "\"file_path\":\"[^\"]+/\\.gemini/tmp/[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+/plans/[a-zA-Z0-9_-]+\\.md\""

From b0cfbc6cd8546dfcf18087068811d1fce1329c2d Mon Sep 17 00:00:00 2001
From: Jack Wotherspoon <jackwoth@google.com>
Date: Thu, 12 Feb 2026 14:16:56 -0500
Subject: [PATCH 26/44] fix: character truncation in raw markdown mode (#18938)

---
 .../components/messages/GeminiMessage.test.tsx  | 17 +++++++++++++++++
 .../ui/components/messages/GeminiMessage.tsx    |  2 +-
 .../messages/GeminiMessageContent.tsx           |  2 +-
 .../__snapshots__/GeminiMessage.test.tsx.snap   |  9 +++++++++
 4 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/packages/cli/src/ui/components/messages/GeminiMessage.test.tsx b/packages/cli/src/ui/components/messages/GeminiMessage.test.tsx
index 06a551554a..e8209d884d 100644
--- a/packages/cli/src/ui/components/messages/GeminiMessage.test.tsx
+++ b/packages/cli/src/ui/components/messages/GeminiMessage.test.tsx
@@ -46,4 +46,21 @@ describe('<GeminiMessage /> - Raw Markdown Display Snapshots', () => {
       expect(lastFrame()).toMatchSnapshot();
     },
   );
+
+  it('wraps long lines correctly in raw markdown mode', () => {
+    const terminalWidth = 20;
+    const text =
+      'This is a long line that should wrap correctly without truncation';
+    const { lastFrame } = renderWithProviders(
+      <GeminiMessage
+        text={text}
+        isPending={false}
+        terminalWidth={terminalWidth}
+      />,
+      {
+        uiState: { renderMarkdown: false, streamingState: StreamingState.Idle },
+      },
+    );
+    expect(lastFrame()).toMatchSnapshot();
+  });
 });
diff --git a/packages/cli/src/ui/components/messages/GeminiMessage.tsx b/packages/cli/src/ui/components/messages/GeminiMessage.tsx
index 95e392dab7..3c17a3850f 100644
--- a/packages/cli/src/ui/components/messages/GeminiMessage.tsx
+++ b/packages/cli/src/ui/components/messages/GeminiMessage.tsx
@@ -47,7 +47,7 @@ export const GeminiMessage: React.FC<GeminiMessageProps> = ({
               ? undefined
               : Math.max(availableTerminalHeight - 1, 1)
           }
-          terminalWidth={terminalWidth}
+          terminalWidth={Math.max(terminalWidth - prefixWidth, 0)}
           renderMarkdown={renderMarkdown}
         />
         <Box
diff --git a/packages/cli/src/ui/components/messages/GeminiMessageContent.tsx b/packages/cli/src/ui/components/messages/GeminiMessageContent.tsx
index 847e95a357..259a0016f3 100644
--- a/packages/cli/src/ui/components/messages/GeminiMessageContent.tsx
+++ b/packages/cli/src/ui/components/messages/GeminiMessageContent.tsx
@@ -45,7 +45,7 @@ export const GeminiMessageContent: React.FC<GeminiMessageContentProps> = ({
             ? undefined
             : Math.max(availableTerminalHeight - 1, 1)
         }
-        terminalWidth={terminalWidth}
+        terminalWidth={Math.max(terminalWidth - prefixWidth, 0)}
         renderMarkdown={renderMarkdown}
       />
       <Box
diff --git a/packages/cli/src/ui/components/messages/__snapshots__/GeminiMessage.test.tsx.snap b/packages/cli/src/ui/components/messages/__snapshots__/GeminiMessage.test.tsx.snap
index 166ac605be..6e624485e2 100644
--- a/packages/cli/src/ui/components/messages/__snapshots__/GeminiMessage.test.tsx.snap
+++ b/packages/cli/src/ui/components/messages/__snapshots__/GeminiMessage.test.tsx.snap
@@ -31,3 +31,12 @@ exports[`<GeminiMessage /> - Raw Markdown Display Snapshots > renders with rende
    1 const x = 1;
 "
 `;
+
+exports[`<GeminiMessage /> - Raw Markdown Display Snapshots > wraps long lines correctly in raw markdown mode 1`] = `
+"✦  This is a long
+   line that should
+   wrap correctly
+   without
+   truncation
+"
+`;

From db00c5abf388e07202af227ac77b31e07238b379 Mon Sep 17 00:00:00 2001
From: Dmitry Lyalin <dmitry.lyalin@lyalin.com>
Date: Thu, 12 Feb 2026 14:25:24 -0500
Subject: [PATCH 27/44] feat(cli): prototype clean UI toggle and minimal-mode
 bleed-through (#18683)

---
 docs/cli/commands.md                          |   2 +
 docs/cli/keyboard-shortcuts.md                |   9 +-
 packages/cli/src/config/keyBindings.ts        |   4 +-
 packages/cli/src/test-utils/render.tsx        |   5 +
 packages/cli/src/ui/App.test.tsx              |   1 +
 packages/cli/src/ui/AppContainer.test.tsx     |  34 ++-
 packages/cli/src/ui/AppContainer.tsx          |  92 +++++-
 packages/cli/src/ui/components/AppHeader.tsx  |  11 +-
 .../cli/src/ui/components/Composer.test.tsx   | 227 +++++++++++++-
 packages/cli/src/ui/components/Composer.tsx   | 286 +++++++++++++-----
 .../src/ui/components/InputPrompt.test.tsx    | 106 ++++++-
 .../cli/src/ui/components/InputPrompt.tsx     |  37 ++-
 .../src/ui/components/MainContent.test.tsx    |  94 +++++-
 .../cli/src/ui/components/MainContent.tsx     |  18 +-
 .../src/ui/components/ShortcutsHelp.test.tsx  |   6 +
 .../cli/src/ui/components/ShortcutsHelp.tsx   |  29 +-
 .../cli/src/ui/components/ShortcutsHint.tsx   |   7 +-
 .../__snapshots__/MainContent.test.tsx.snap   |  19 +-
 .../__snapshots__/ShortcutsHelp.test.tsx.snap |  28 +-
 .../cli/src/ui/contexts/UIActionsContext.tsx  |   4 +
 .../cli/src/ui/contexts/UIStateContext.tsx    |   1 +
 packages/cli/src/ui/keyMatchers.test.ts       |   2 +-
 packages/cli/src/utils/persistentState.ts     |   1 +
 23 files changed, 872 insertions(+), 151 deletions(-)

diff --git a/docs/cli/commands.md b/docs/cli/commands.md
index 6e563cda11..c5e6b6747f 100644
--- a/docs/cli/commands.md
+++ b/docs/cli/commands.md
@@ -120,6 +120,8 @@ Slash commands provide meta-level control over the CLI itself.
 - **`/shortcuts`**
   - **Description:** Toggle the shortcuts panel above the input.
   - **Shortcut:** Press `?` when the prompt is empty.
+  - **Note:** This is separate from the clean UI detail toggle on double-`Tab`,
+    which switches between minimal and full UI chrome.
 
 - **`/hooks`**
   - **Description:** Manage hooks, which allow you to intercept and customize
diff --git a/docs/cli/keyboard-shortcuts.md b/docs/cli/keyboard-shortcuts.md
index 0dc32b7779..ffc0a39fda 100644
--- a/docs/cli/keyboard-shortcuts.md
+++ b/docs/cli/keyboard-shortcuts.md
@@ -114,8 +114,8 @@ available combinations.
 | Dismiss background shell list.                                                                        | `Esc`                      |
 | Move focus from background shell to Gemini.                                                           | `Shift + Tab`              |
 | Move focus from background shell list to Gemini.                                                      | `Tab (no Shift)`           |
-| Show warning when trying to unfocus background shell via Tab.                                         | `Tab (no Shift)`           |
-| Show warning when trying to unfocus shell input via Tab.                                              | `Tab (no Shift)`           |
+| Show warning when trying to move focus away from background shell.                                    | `Tab (no Shift)`           |
+| Show warning when trying to move focus away from shell input.                                         | `Tab (no Shift)`           |
 | Move focus from Gemini to the active shell.                                                           | `Tab (no Shift)`           |
 | Move focus from the shell back to Gemini.                                                             | `Shift + Tab`              |
 | Clear the terminal screen and redraw the UI.                                                          | `Ctrl + L`                 |
@@ -134,6 +134,11 @@ available combinations.
   The panel also auto-hides while the agent is running/streaming or when
   action-required dialogs are shown. Press `?` again to close the panel and
   insert a `?` into the prompt.
+- `Tab` + `Tab` (while typing in the prompt): Toggle between minimal and full UI
+  details when no completion/search interaction is active. The selected mode is
+  remembered for future sessions. Full UI remains the default on first run, and
+  single `Tab` keeps its existing completion/focus behavior.
+- `Shift + Tab` (while typing in the prompt): Cycle approval modes.
 - `\` (at end of a line) + `Enter`: Insert a newline without leaving single-line
   mode.
 - `Esc` pressed twice quickly: Clear the input prompt if it is not empty,
diff --git a/packages/cli/src/config/keyBindings.ts b/packages/cli/src/config/keyBindings.ts
index adf88d4d25..c3f1f70fbe 100644
--- a/packages/cli/src/config/keyBindings.ts
+++ b/packages/cli/src/config/keyBindings.ts
@@ -516,9 +516,9 @@ export const commandDescriptions: Readonly<Record<Command, string>> = {
   [Command.UNFOCUS_BACKGROUND_SHELL_LIST]:
     'Move focus from background shell list to Gemini.',
   [Command.SHOW_BACKGROUND_SHELL_UNFOCUS_WARNING]:
-    'Show warning when trying to unfocus background shell via Tab.',
+    'Show warning when trying to move focus away from background shell.',
   [Command.SHOW_SHELL_INPUT_UNFOCUS_WARNING]:
-    'Show warning when trying to unfocus shell input via Tab.',
+    'Show warning when trying to move focus away from shell input.',
   [Command.FOCUS_SHELL_INPUT]: 'Move focus from Gemini to the active shell.',
   [Command.UNFOCUS_SHELL_INPUT]: 'Move focus from the shell back to Gemini.',
   [Command.CLEAR_SCREEN]: 'Clear the terminal screen and redraw the UI.',
diff --git a/packages/cli/src/test-utils/render.tsx b/packages/cli/src/test-utils/render.tsx
index 0c8eac325e..10ad4281ef 100644
--- a/packages/cli/src/test-utils/render.tsx
+++ b/packages/cli/src/test-utils/render.tsx
@@ -150,6 +150,7 @@ const baseMockUiState = {
   terminalWidth: 120,
   terminalHeight: 40,
   currentModel: 'gemini-pro',
+  cleanUiDetailsVisible: false,
   terminalBackgroundColor: undefined,
   activePtyId: undefined,
   backgroundShells: new Map(),
@@ -204,6 +205,10 @@ const mockUIActions: UIActions = {
   handleApiKeyCancel: vi.fn(),
   setBannerVisible: vi.fn(),
   setShortcutsHelpVisible: vi.fn(),
+  setCleanUiDetailsVisible: vi.fn(),
+  toggleCleanUiDetailsVisible: vi.fn(),
+  revealCleanUiDetailsTemporarily: vi.fn(),
+  handleWarning: vi.fn(),
   setEmbeddedShellFocused: vi.fn(),
   dismissBackgroundShell: vi.fn(),
   setActiveBackgroundShellPid: vi.fn(),
diff --git a/packages/cli/src/ui/App.test.tsx b/packages/cli/src/ui/App.test.tsx
index 7d817f44f5..475a04e18e 100644
--- a/packages/cli/src/ui/App.test.tsx
+++ b/packages/cli/src/ui/App.test.tsx
@@ -66,6 +66,7 @@ describe('App', () => {
 
   const mockUIState: Partial<UIState> = {
     streamingState: StreamingState.Idle,
+    cleanUiDetailsVisible: true,
     quittingMessages: null,
     dialogsVisible: false,
     mainControlsRef: {
diff --git a/packages/cli/src/ui/AppContainer.test.tsx b/packages/cli/src/ui/AppContainer.test.tsx
index ff84834c69..028584537d 100644
--- a/packages/cli/src/ui/AppContainer.test.tsx
+++ b/packages/cli/src/ui/AppContainer.test.tsx
@@ -14,7 +14,7 @@ import {
   type Mock,
   type MockedObject,
 } from 'vitest';
-import { render } from '../test-utils/render.js';
+import { render, persistentStateMock } from '../test-utils/render.js';
 import { waitFor } from '../test-utils/async.js';
 import { cleanup } from 'ink-testing-library';
 import { act, useContext, type ReactElement } from 'react';
@@ -299,6 +299,7 @@ describe('AppContainer State Management', () => {
   };
 
   beforeEach(() => {
+    persistentStateMock.reset();
     vi.clearAllMocks();
 
     mockIdeClient.getInstance.mockReturnValue(new Promise(() => {}));
@@ -488,6 +489,37 @@ describe('AppContainer State Management', () => {
       await waitFor(() => expect(capturedUIState).toBeTruthy());
       unmount!();
     });
+
+    it('shows full UI details by default', async () => {
+      let unmount: () => void;
+      await act(async () => {
+        const result = renderAppContainer();
+        unmount = result.unmount;
+      });
+
+      await waitFor(() => {
+        expect(capturedUIState.cleanUiDetailsVisible).toBe(true);
+      });
+      unmount!();
+    });
+
+    it('starts in minimal UI mode when Focus UI preference is persisted', async () => {
+      persistentStateMock.get.mockReturnValueOnce(true);
+
+      let unmount: () => void;
+      await act(async () => {
+        const result = renderAppContainer({
+          settings: mockSettings,
+        });
+        unmount = result.unmount;
+      });
+
+      await waitFor(() => {
+        expect(capturedUIState.cleanUiDetailsVisible).toBe(false);
+      });
+      expect(persistentStateMock.get).toHaveBeenCalledWith('focusUiEnabled');
+      unmount!();
+    });
   });
 
   describe('State Initialization', () => {
diff --git a/packages/cli/src/ui/AppContainer.tsx b/packages/cli/src/ui/AppContainer.tsx
index a2f25a71de..4c590c21eb 100644
--- a/packages/cli/src/ui/AppContainer.tsx
+++ b/packages/cli/src/ui/AppContainer.tsx
@@ -49,6 +49,7 @@ import {
   type UserTierId,
   type UserFeedbackPayload,
   type AgentDefinition,
+  type ApprovalMode,
   IdeClient,
   ideContextStore,
   getErrorMessage,
@@ -133,6 +134,7 @@ import { ShellFocusContext } from './contexts/ShellFocusContext.js';
 import { type ExtensionManager } from '../config/extension-manager.js';
 import { requestConsentInteractive } from '../config/extensions/consent.js';
 import { useSessionBrowser } from './hooks/useSessionBrowser.js';
+import { persistentState } from '../utils/persistentState.js';
 import { useSessionResume } from './hooks/useSessionResume.js';
 import { useIncludeDirsTrust } from './hooks/useIncludeDirsTrust.js';
 import { isWorkspaceTrusted } from '../config/trustedFolders.js';
@@ -184,6 +186,9 @@ interface AppContainerProps {
   resumedSessionData?: ResumedSessionData;
 }
 
+const APPROVAL_MODE_REVEAL_DURATION_MS = 1200;
+const FOCUS_UI_ENABLED_STATE_KEY = 'focusUiEnabled';
+
 /**
  * The fraction of the terminal width to allocate to the shell.
  * This provides horizontal padding.
@@ -796,7 +801,65 @@ Logging in with Google... Restarting Gemini CLI to continue.
   const setIsBackgroundShellListOpenRef = useRef<(open: boolean) => void>(
     () => {},
   );
+  const [focusUiEnabledByDefault] = useState(
+    () => persistentState.get(FOCUS_UI_ENABLED_STATE_KEY) === true,
+  );
   const [shortcutsHelpVisible, setShortcutsHelpVisible] = useState(false);
+  const [cleanUiDetailsVisible, setCleanUiDetailsVisibleState] = useState(
+    !focusUiEnabledByDefault,
+  );
+  const modeRevealTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const cleanUiDetailsPinnedRef = useRef(!focusUiEnabledByDefault);
+
+  const clearModeRevealTimeout = useCallback(() => {
+    if (modeRevealTimeoutRef.current) {
+      clearTimeout(modeRevealTimeoutRef.current);
+      modeRevealTimeoutRef.current = null;
+    }
+  }, []);
+
+  const persistFocusUiPreference = useCallback((isFullUiVisible: boolean) => {
+    persistentState.set(FOCUS_UI_ENABLED_STATE_KEY, !isFullUiVisible);
+  }, []);
+
+  const setCleanUiDetailsVisible = useCallback(
+    (visible: boolean) => {
+      clearModeRevealTimeout();
+      cleanUiDetailsPinnedRef.current = visible;
+      setCleanUiDetailsVisibleState(visible);
+      persistFocusUiPreference(visible);
+    },
+    [clearModeRevealTimeout, persistFocusUiPreference],
+  );
+
+  const toggleCleanUiDetailsVisible = useCallback(() => {
+    clearModeRevealTimeout();
+    setCleanUiDetailsVisibleState((visible) => {
+      const nextVisible = !visible;
+      cleanUiDetailsPinnedRef.current = nextVisible;
+      persistFocusUiPreference(nextVisible);
+      return nextVisible;
+    });
+  }, [clearModeRevealTimeout, persistFocusUiPreference]);
+
+  const revealCleanUiDetailsTemporarily = useCallback(
+    (durationMs: number = APPROVAL_MODE_REVEAL_DURATION_MS) => {
+      if (cleanUiDetailsPinnedRef.current) {
+        return;
+      }
+      clearModeRevealTimeout();
+      setCleanUiDetailsVisibleState(true);
+      modeRevealTimeoutRef.current = setTimeout(() => {
+        if (!cleanUiDetailsPinnedRef.current) {
+          setCleanUiDetailsVisibleState(false);
+        }
+        modeRevealTimeoutRef.current = null;
+      }, durationMs);
+    },
+    [clearModeRevealTimeout],
+  );
+
+  useEffect(() => () => clearModeRevealTimeout(), [clearModeRevealTimeout]);
 
   const slashCommandActions = useMemo(
     () => ({
@@ -1057,11 +1120,25 @@ Logging in with Google... Restarting Gemini CLI to continue.
   const shouldShowActionRequiredTitle = inactivityStatus === 'action_required';
   const shouldShowSilentWorkingTitle = inactivityStatus === 'silent_working';
 
+  const handleApprovalModeChangeWithUiReveal = useCallback(
+    (mode: ApprovalMode) => {
+      void handleApprovalModeChange(mode);
+      if (!cleanUiDetailsVisible) {
+        revealCleanUiDetailsTemporarily(APPROVAL_MODE_REVEAL_DURATION_MS);
+      }
+    },
+    [
+      handleApprovalModeChange,
+      cleanUiDetailsVisible,
+      revealCleanUiDetailsTemporarily,
+    ],
+  );
+
   // Auto-accept indicator
   const showApprovalModeIndicator = useApprovalModeIndicator({
     config,
     addItem: historyManager.addItem,
-    onApprovalModeChange: handleApprovalModeChange,
+    onApprovalModeChange: handleApprovalModeChangeWithUiReveal,
     isActive: !embeddedShellFocused,
   });
 
@@ -1377,6 +1454,9 @@ Logging in with Google... Restarting Gemini CLI to continue.
       if (tabFocusTimeoutRef.current) {
         clearTimeout(tabFocusTimeoutRef.current);
       }
+      if (modeRevealTimeoutRef.current) {
+        clearTimeout(modeRevealTimeoutRef.current);
+      }
     };
   }, [showTransientMessage]);
 
@@ -1977,6 +2057,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       ctrlDPressedOnce: ctrlDPressCount >= 1,
       showEscapePrompt,
       shortcutsHelpVisible,
+      cleanUiDetailsVisible,
       isFocused,
       elapsedTime,
       currentLoadingPhrase,
@@ -2087,6 +2168,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       ctrlDPressCount,
       showEscapePrompt,
       shortcutsHelpVisible,
+      cleanUiDetailsVisible,
       isFocused,
       elapsedTime,
       currentLoadingPhrase,
@@ -2188,6 +2270,10 @@ Logging in with Google... Restarting Gemini CLI to continue.
       handleApiKeyCancel,
       setBannerVisible,
       setShortcutsHelpVisible,
+      setCleanUiDetailsVisible,
+      toggleCleanUiDetailsVisible,
+      revealCleanUiDetailsTemporarily,
+      handleWarning,
       setEmbeddedShellFocused,
       dismissBackgroundShell,
       setActiveBackgroundShellPid,
@@ -2264,6 +2350,10 @@ Logging in with Google... Restarting Gemini CLI to continue.
       handleApiKeyCancel,
       setBannerVisible,
       setShortcutsHelpVisible,
+      setCleanUiDetailsVisible,
+      toggleCleanUiDetailsVisible,
+      revealCleanUiDetailsTemporarily,
+      handleWarning,
       setEmbeddedShellFocused,
       dismissBackgroundShell,
       setActiveBackgroundShellPid,
diff --git a/packages/cli/src/ui/components/AppHeader.tsx b/packages/cli/src/ui/components/AppHeader.tsx
index 38b0f9b468..ad5e2f67d2 100644
--- a/packages/cli/src/ui/components/AppHeader.tsx
+++ b/packages/cli/src/ui/components/AppHeader.tsx
@@ -17,9 +17,10 @@ import { useTips } from '../hooks/useTips.js';
 
 interface AppHeaderProps {
   version: string;
+  showDetails?: boolean;
 }
 
-export const AppHeader = ({ version }: AppHeaderProps) => {
+export const AppHeader = ({ version, showDetails = true }: AppHeaderProps) => {
   const settings = useSettings();
   const config = useConfig();
   const { nightly, terminalWidth, bannerData, bannerVisible } = useUIState();
@@ -27,6 +28,14 @@ export const AppHeader = ({ version }: AppHeaderProps) => {
   const { bannerText } = useBanner(bannerData);
   const { showTips } = useTips();
 
+  if (!showDetails) {
+    return (
+      <Box flexDirection="column">
+        <Header version={version} nightly={false} />
+      </Box>
+    );
+  }
+
   return (
     <Box flexDirection="column">
       {!(settings.merged.ui.hideBanner || config.getScreenReader()) && (
diff --git a/packages/cli/src/ui/components/Composer.test.tsx b/packages/cli/src/ui/components/Composer.test.tsx
index 1a25d2bb56..353e1ad535 100644
--- a/packages/cli/src/ui/components/Composer.test.tsx
+++ b/packages/cli/src/ui/components/Composer.test.tsx
@@ -4,9 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi, afterEach } from 'vitest';
+import { beforeEach, afterEach, describe, it, expect, vi } from 'vitest';
 import { render } from '../../test-utils/render.js';
 import { Box, Text } from 'ink';
+import { useEffect } from 'react';
 import { Composer } from './Composer.js';
 import { UIStateContext, type UIState } from '../contexts/UIStateContext.js';
 import {
@@ -23,13 +24,18 @@ vi.mock('../contexts/VimModeContext.js', () => ({
     vimMode: 'INSERT',
   })),
 }));
-import { ApprovalMode } from '@google/gemini-cli-core';
+import { ApprovalMode, tokenLimit } from '@google/gemini-cli-core';
 import type { Config } from '@google/gemini-cli-core';
 import { StreamingState, ToolCallStatus } from '../types.js';
 import { TransientMessageType } from '../../utils/events.js';
 import type { LoadedSettings } from '../../config/settings.js';
 import type { SessionMetrics } from '../contexts/SessionContext.js';
 
+const composerTestControls = vi.hoisted(() => ({
+  suggestionsVisible: false,
+  isAlternateBuffer: false,
+}));
+
 // Mock child components
 vi.mock('./LoadingIndicator.js', () => ({
   LoadingIndicator: ({
@@ -90,9 +96,19 @@ vi.mock('./DetailedMessagesDisplay.js', () => ({
 }));
 
 vi.mock('./InputPrompt.js', () => ({
-  InputPrompt: ({ placeholder }: { placeholder?: string }) => (
-    <Text>InputPrompt: {placeholder}</Text>
-  ),
+  InputPrompt: ({
+    placeholder,
+    onSuggestionsVisibilityChange,
+  }: {
+    placeholder?: string;
+    onSuggestionsVisibilityChange?: (visible: boolean) => void;
+  }) => {
+    useEffect(() => {
+      onSuggestionsVisibilityChange?.(composerTestControls.suggestionsVisible);
+    }, [onSuggestionsVisibilityChange]);
+
+    return <Text>InputPrompt: {placeholder}</Text>;
+  },
   calculatePromptWidths: vi.fn(() => ({
     inputWidth: 80,
     suggestionsWidth: 40,
@@ -100,6 +116,10 @@ vi.mock('./InputPrompt.js', () => ({
   })),
 }));
 
+vi.mock('../hooks/useAlternateBuffer.js', () => ({
+  useAlternateBuffer: () => composerTestControls.isAlternateBuffer,
+}));
+
 vi.mock('./Footer.js', () => ({
   Footer: () => <Text>Footer</Text>,
 }));
@@ -154,15 +174,19 @@ const createMockUIState = (overrides: Partial<UIState> = {}): UIState =>
     ctrlDPressedOnce: false,
     showEscapePrompt: false,
     shortcutsHelpVisible: false,
+    cleanUiDetailsVisible: true,
     ideContextState: null,
     geminiMdFileCount: 0,
     renderMarkdown: true,
     filteredConsoleMessages: [],
     history: [],
     sessionStats: {
+      sessionId: 'test-session',
+      sessionStartTime: new Date(),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      metrics: {} as any,
       lastPromptTokenCount: 0,
-      sessionTokenCount: 0,
-      totalPrompts: 0,
+      promptCount: 0,
     },
     branchName: 'main',
     debugMessage: '',
@@ -187,6 +211,9 @@ const createMockUIActions = (): UIActions =>
     handleFinalSubmit: vi.fn(),
     handleClearScreen: vi.fn(),
     setShellModeActive: vi.fn(),
+    setCleanUiDetailsVisible: vi.fn(),
+    toggleCleanUiDetailsVisible: vi.fn(),
+    revealCleanUiDetailsTemporarily: vi.fn(),
     onEscapePromptChange: vi.fn(),
     vimHandleInput: vi.fn(),
     setShortcutsHelpVisible: vi.fn(),
@@ -233,6 +260,11 @@ const renderComposer = (
   );
 
 describe('Composer', () => {
+  beforeEach(() => {
+    composerTestControls.suggestionsVisible = false;
+    composerTestControls.isAlternateBuffer = false;
+  });
+
   afterEach(() => {
     vi.restoreAllMocks();
   });
@@ -342,6 +374,7 @@ describe('Composer', () => {
       const uiState = createMockUIState({
         streamingState: StreamingState.Responding,
         elapsedTime: 1,
+        cleanUiDetailsVisible: false,
       });
 
       const { lastFrame } = renderComposer(uiState);
@@ -514,6 +547,21 @@ describe('Composer', () => {
   });
 
   describe('Input and Indicators', () => {
+    it('hides non-essential UI details in clean mode', () => {
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: false,
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+
+      const output = lastFrame();
+      expect(output).toContain('ShortcutsHint');
+      expect(output).toContain('InputPrompt');
+      expect(output).not.toContain('Footer');
+      expect(output).not.toContain('ApprovalModeIndicator');
+      expect(output).not.toContain('ContextSummaryDisplay');
+    });
+
     it('renders InputPrompt when input is active', () => {
       const uiState = createMockUIState({
         isInputActive: true,
@@ -582,6 +630,92 @@ describe('Composer', () => {
 
       expect(lastFrame()).not.toContain('raw markdown mode');
     });
+
+    it.each([
+      [ApprovalMode.YOLO, 'YOLO'],
+      [ApprovalMode.PLAN, 'plan'],
+      [ApprovalMode.AUTO_EDIT, 'auto edit'],
+    ])(
+      'shows minimal mode badge "%s" when clean UI details are hidden',
+      (mode, label) => {
+        const uiState = createMockUIState({
+          cleanUiDetailsVisible: false,
+          showApprovalModeIndicator: mode,
+        });
+
+        const { lastFrame } = renderComposer(uiState);
+        expect(lastFrame()).toContain(label);
+      },
+    );
+
+    it('hides minimal mode badge while loading in clean mode', () => {
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: false,
+        streamingState: StreamingState.Responding,
+        elapsedTime: 1,
+        showApprovalModeIndicator: ApprovalMode.PLAN,
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+      const output = lastFrame();
+      expect(output).toContain('LoadingIndicator');
+      expect(output).not.toContain('plan');
+      expect(output).not.toContain('ShortcutsHint');
+    });
+
+    it('hides minimal mode badge while action-required state is active', () => {
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: false,
+        showApprovalModeIndicator: ApprovalMode.PLAN,
+        customDialog: (
+          <Box>
+            <Text>Prompt</Text>
+          </Box>
+        ),
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+      const output = lastFrame();
+      expect(output).not.toContain('plan');
+      expect(output).not.toContain('ShortcutsHint');
+    });
+
+    it('shows Esc rewind prompt in minimal mode without showing full UI', () => {
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: false,
+        showEscapePrompt: true,
+        history: [{ id: 1, type: 'user', text: 'msg' }],
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+      const output = lastFrame();
+      expect(output).toContain('ToastDisplay');
+      expect(output).not.toContain('ContextSummaryDisplay');
+    });
+
+    it('shows context usage bleed-through when over 60%', () => {
+      const model = 'gemini-2.5-pro';
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: false,
+        currentModel: model,
+        sessionStats: {
+          sessionId: 'test-session',
+          sessionStartTime: new Date(),
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          metrics: {} as any,
+          lastPromptTokenCount: Math.floor(tokenLimit(model) * 0.7),
+          promptCount: 0,
+        },
+      });
+      const settings = createMockSettings({
+        ui: {
+          footer: { hideContextPercentage: false },
+        },
+      });
+
+      const { lastFrame } = renderComposer(uiState, settings);
+      expect(lastFrame()).toContain('%');
+    });
   });
 
   describe('Error Details Display', () => {
@@ -680,7 +814,84 @@ describe('Composer', () => {
     });
 
     it('keeps shortcuts hint visible when no action is required', () => {
-      const uiState = createMockUIState();
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: false,
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+
+      expect(lastFrame()).toContain('ShortcutsHint');
+    });
+
+    it('shows shortcuts hint when full UI details are visible', () => {
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: true,
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+
+      expect(lastFrame()).toContain('ShortcutsHint');
+    });
+
+    it('hides shortcuts hint while loading in minimal mode', () => {
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: false,
+        streamingState: StreamingState.Responding,
+        elapsedTime: 1,
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+
+      expect(lastFrame()).not.toContain('ShortcutsHint');
+    });
+
+    it('shows shortcuts help in minimal mode when toggled on', () => {
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: false,
+        shortcutsHelpVisible: true,
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+
+      expect(lastFrame()).toContain('ShortcutsHelp');
+    });
+
+    it('hides shortcuts hint when suggestions are visible above input in alternate buffer', () => {
+      composerTestControls.isAlternateBuffer = true;
+      composerTestControls.suggestionsVisible = true;
+
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: false,
+        showApprovalModeIndicator: ApprovalMode.PLAN,
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+
+      expect(lastFrame()).not.toContain('ShortcutsHint');
+      expect(lastFrame()).not.toContain('plan');
+    });
+
+    it('hides approval mode indicator when suggestions are visible above input in alternate buffer', () => {
+      composerTestControls.isAlternateBuffer = true;
+      composerTestControls.suggestionsVisible = true;
+
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: true,
+        showApprovalModeIndicator: ApprovalMode.YOLO,
+      });
+
+      const { lastFrame } = renderComposer(uiState);
+
+      expect(lastFrame()).not.toContain('ApprovalModeIndicator');
+    });
+
+    it('keeps shortcuts hint when suggestions are visible below input in regular buffer', () => {
+      composerTestControls.isAlternateBuffer = false;
+      composerTestControls.suggestionsVisible = true;
+
+      const uiState = createMockUIState({
+        cleanUiDetailsVisible: false,
+      });
 
       const { lastFrame } = renderComposer(uiState);
 
diff --git a/packages/cli/src/ui/components/Composer.tsx b/packages/cli/src/ui/components/Composer.tsx
index b5b88b4e15..8101e7303c 100644
--- a/packages/cli/src/ui/components/Composer.tsx
+++ b/packages/cli/src/ui/components/Composer.tsx
@@ -5,7 +5,8 @@
  */
 
 import { useState, useEffect, useMemo } from 'react';
-import { Box, useIsScreenReaderEnabled } from 'ink';
+import { Box, Text, useIsScreenReaderEnabled } from 'ink';
+import { ApprovalMode, tokenLimit } from '@google/gemini-cli-core';
 import { LoadingIndicator } from './LoadingIndicator.js';
 import { StatusDisplay } from './StatusDisplay.js';
 import { ToastDisplay, shouldShowToast } from './ToastDisplay.js';
@@ -19,6 +20,7 @@ import { InputPrompt } from './InputPrompt.js';
 import { Footer } from './Footer.js';
 import { ShowMoreLines } from './ShowMoreLines.js';
 import { QueuedMessageDisplay } from './QueuedMessageDisplay.js';
+import { ContextUsageDisplay } from './ContextUsageDisplay.js';
 import { HorizontalLine } from './shared/HorizontalLine.js';
 import { OverflowProvider } from '../contexts/OverflowContext.js';
 import { isNarrowWidth } from '../utils/isNarrowWidth.js';
@@ -36,6 +38,7 @@ import {
 import { ConfigInitDisplay } from '../components/ConfigInitDisplay.js';
 import { TodoTray } from './messages/Todo.js';
 import { getInlineThinkingMode } from '../utils/inlineThinkingMode.js';
+import { theme } from '../semantic-colors.js';
 
 export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
   const config = useConfig();
@@ -52,6 +55,7 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
 
   const isAlternateBuffer = useAlternateBuffer();
   const { showApprovalModeIndicator } = uiState;
+  const showUiDetails = uiState.cleanUiDetailsVisible;
   const suggestionsPosition = isAlternateBuffer ? 'above' : 'below';
   const hideContextSummary =
     suggestionsVisible && suggestionsPosition === 'above';
@@ -98,17 +102,60 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
     uiState.shortcutsHelpVisible &&
     uiState.streamingState === StreamingState.Idle &&
     !hasPendingActionRequired;
-  const showShortcutsHint =
-    settings.merged.ui.showShortcutsHint &&
-    uiState.streamingState === StreamingState.Idle &&
-    !hasPendingActionRequired;
   const hasToast = shouldShowToast(uiState);
   const showLoadingIndicator =
     (!uiState.embeddedShellFocused || uiState.isBackgroundShellVisible) &&
     uiState.streamingState === StreamingState.Responding &&
     !hasPendingActionRequired;
-  const showApprovalIndicator = !uiState.shellModeActive;
+  const hideUiDetailsForSuggestions =
+    suggestionsVisible && suggestionsPosition === 'above';
+  const showApprovalIndicator =
+    !uiState.shellModeActive && !hideUiDetailsForSuggestions;
   const showRawMarkdownIndicator = !uiState.renderMarkdown;
+  const modeBleedThrough =
+    showApprovalModeIndicator === ApprovalMode.YOLO
+      ? { text: 'YOLO', color: theme.status.error }
+      : showApprovalModeIndicator === ApprovalMode.PLAN
+        ? { text: 'plan', color: theme.status.success }
+        : showApprovalModeIndicator === ApprovalMode.AUTO_EDIT
+          ? { text: 'auto edit', color: theme.status.warning }
+          : null;
+  const hideMinimalModeHintWhileBusy =
+    !showUiDetails && (showLoadingIndicator || hasPendingActionRequired);
+  const minimalModeBleedThrough = hideMinimalModeHintWhileBusy
+    ? null
+    : modeBleedThrough;
+  const hasMinimalStatusBleedThrough = shouldShowToast(uiState);
+  const contextTokenLimit =
+    typeof uiState.currentModel === 'string' && uiState.currentModel.length > 0
+      ? tokenLimit(uiState.currentModel)
+      : 0;
+  const showMinimalContextBleedThrough =
+    !settings.merged.ui.footer.hideContextPercentage &&
+    typeof uiState.currentModel === 'string' &&
+    uiState.currentModel.length > 0 &&
+    contextTokenLimit > 0 &&
+    uiState.sessionStats.lastPromptTokenCount / contextTokenLimit > 0.6;
+  const hideShortcutsHintForSuggestions = hideUiDetailsForSuggestions;
+  const showShortcutsHint =
+    settings.merged.ui.showShortcutsHint &&
+    !hideShortcutsHintForSuggestions &&
+    !hideMinimalModeHintWhileBusy &&
+    !hasPendingActionRequired &&
+    (!showUiDetails || !showLoadingIndicator);
+  const showMinimalModeBleedThrough =
+    !hideUiDetailsForSuggestions && Boolean(minimalModeBleedThrough);
+  const showMinimalInlineLoading = !showUiDetails && showLoadingIndicator;
+  const showMinimalBleedThroughRow =
+    !showUiDetails &&
+    (showMinimalModeBleedThrough ||
+      hasMinimalStatusBleedThrough ||
+      showMinimalContextBleedThrough);
+  const showMinimalMetaRow =
+    !showUiDetails &&
+    (showMinimalInlineLoading ||
+      showMinimalBleedThroughRow ||
+      showShortcutsHint);
 
   return (
     <Box
@@ -125,9 +172,11 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
         />
       )}
 
-      <QueuedMessageDisplay messageQueue={uiState.messageQueue} />
+      {showUiDetails && (
+        <QueuedMessageDisplay messageQueue={uiState.messageQueue} />
+      )}
 
-      <TodoTray />
+      {showUiDetails && <TodoTray />}
 
       <Box marginTop={1} width="100%" flexDirection="column">
         <Box
@@ -143,7 +192,7 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
             alignItems="center"
             flexGrow={1}
           >
-            {showLoadingIndicator && (
+            {showUiDetails && showLoadingIndicator && (
               <LoadingIndicator
                 inline
                 thought={
@@ -170,86 +219,169 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
             flexDirection="column"
             alignItems={isNarrow ? 'flex-start' : 'flex-end'}
           >
-            {showShortcutsHint && <ShortcutsHint />}
+            {showUiDetails && showShortcutsHint && <ShortcutsHint />}
           </Box>
         </Box>
-        {showShortcutsHelp && <ShortcutsHelp />}
-        <HorizontalLine />
-        <Box
-          justifyContent={
-            settings.merged.ui.hideContextSummary
-              ? 'flex-start'
-              : 'space-between'
-          }
-          width="100%"
-          flexDirection={isNarrow ? 'column' : 'row'}
-          alignItems={isNarrow ? 'flex-start' : 'center'}
-        >
+        {showMinimalMetaRow && (
           <Box
-            marginLeft={1}
-            marginRight={isNarrow ? 0 : 1}
-            flexDirection="row"
-            alignItems="center"
-            flexGrow={1}
+            justifyContent="space-between"
+            width="100%"
+            flexDirection={isNarrow ? 'column' : 'row'}
+            alignItems={isNarrow ? 'flex-start' : 'center'}
           >
-            {hasToast ? (
-              <ToastDisplay />
-            ) : (
-              !showLoadingIndicator && (
+            <Box
+              marginLeft={1}
+              marginRight={isNarrow ? 0 : 1}
+              flexDirection="row"
+              alignItems={isNarrow ? 'flex-start' : 'center'}
+              flexGrow={1}
+            >
+              {showMinimalInlineLoading && (
+                <LoadingIndicator
+                  inline
+                  thought={
+                    uiState.streamingState ===
+                      StreamingState.WaitingForConfirmation ||
+                    config.getAccessibility()?.enableLoadingPhrases === false
+                      ? undefined
+                      : uiState.thought
+                  }
+                  currentLoadingPhrase={
+                    config.getAccessibility()?.enableLoadingPhrases === false
+                      ? undefined
+                      : uiState.currentLoadingPhrase
+                  }
+                  thoughtLabel={
+                    inlineThinkingMode === 'full' ? 'Thinking ...' : undefined
+                  }
+                  elapsedTime={uiState.elapsedTime}
+                />
+              )}
+              {showMinimalModeBleedThrough && minimalModeBleedThrough && (
+                <Text color={minimalModeBleedThrough.color}>
+                  ● {minimalModeBleedThrough.text}
+                </Text>
+              )}
+              {hasMinimalStatusBleedThrough && (
                 <Box
-                  flexDirection={isNarrow ? 'column' : 'row'}
-                  alignItems={isNarrow ? 'flex-start' : 'center'}
+                  marginLeft={
+                    showMinimalInlineLoading || showMinimalModeBleedThrough
+                      ? 1
+                      : 0
+                  }
                 >
-                  {showApprovalIndicator && (
-                    <ApprovalModeIndicator
-                      approvalMode={showApprovalModeIndicator}
-                      isPlanEnabled={config.isPlanEnabled()}
-                    />
-                  )}
-                  {uiState.shellModeActive && (
-                    <Box
-                      marginLeft={showApprovalIndicator && !isNarrow ? 1 : 0}
-                      marginTop={showApprovalIndicator && isNarrow ? 1 : 0}
-                    >
-                      <ShellModeIndicator />
-                    </Box>
-                  )}
-                  {showRawMarkdownIndicator && (
-                    <Box
-                      marginLeft={
-                        (showApprovalIndicator || uiState.shellModeActive) &&
-                        !isNarrow
-                          ? 1
-                          : 0
-                      }
-                      marginTop={
-                        (showApprovalIndicator || uiState.shellModeActive) &&
-                        isNarrow
-                          ? 1
-                          : 0
-                      }
-                    >
-                      <RawMarkdownIndicator />
-                    </Box>
-                  )}
+                  <ToastDisplay />
                 </Box>
-              )
+              )}
+            </Box>
+            {(showMinimalContextBleedThrough || showShortcutsHint) && (
+              <Box
+                marginTop={isNarrow && showMinimalBleedThroughRow ? 1 : 0}
+                flexDirection={isNarrow ? 'column' : 'row'}
+                alignItems={isNarrow ? 'flex-start' : 'flex-end'}
+              >
+                {showMinimalContextBleedThrough && (
+                  <ContextUsageDisplay
+                    promptTokenCount={uiState.sessionStats.lastPromptTokenCount}
+                    model={uiState.currentModel}
+                    terminalWidth={uiState.terminalWidth}
+                  />
+                )}
+                {showShortcutsHint && (
+                  <Box
+                    marginLeft={
+                      showMinimalContextBleedThrough && !isNarrow ? 1 : 0
+                    }
+                    marginTop={
+                      showMinimalContextBleedThrough && isNarrow ? 1 : 0
+                    }
+                  >
+                    <ShortcutsHint />
+                  </Box>
+                )}
+              </Box>
             )}
           </Box>
-
+        )}
+        {showShortcutsHelp && <ShortcutsHelp />}
+        {showUiDetails && <HorizontalLine />}
+        {showUiDetails && (
           <Box
-            marginTop={isNarrow ? 1 : 0}
-            flexDirection="column"
-            alignItems={isNarrow ? 'flex-start' : 'flex-end'}
+            justifyContent={
+              settings.merged.ui.hideContextSummary
+                ? 'flex-start'
+                : 'space-between'
+            }
+            width="100%"
+            flexDirection={isNarrow ? 'column' : 'row'}
+            alignItems={isNarrow ? 'flex-start' : 'center'}
           >
-            {!showLoadingIndicator && (
-              <StatusDisplay hideContextSummary={hideContextSummary} />
-            )}
+            <Box
+              marginLeft={1}
+              marginRight={isNarrow ? 0 : 1}
+              flexDirection="row"
+              alignItems="center"
+              flexGrow={1}
+            >
+              {hasToast ? (
+                <ToastDisplay />
+              ) : (
+                !showLoadingIndicator && (
+                  <Box
+                    flexDirection={isNarrow ? 'column' : 'row'}
+                    alignItems={isNarrow ? 'flex-start' : 'center'}
+                  >
+                    {showApprovalIndicator && (
+                      <ApprovalModeIndicator
+                        approvalMode={showApprovalModeIndicator}
+                        isPlanEnabled={config.isPlanEnabled()}
+                      />
+                    )}
+                    {uiState.shellModeActive && (
+                      <Box
+                        marginLeft={showApprovalIndicator && !isNarrow ? 1 : 0}
+                        marginTop={showApprovalIndicator && isNarrow ? 1 : 0}
+                      >
+                        <ShellModeIndicator />
+                      </Box>
+                    )}
+                    {showRawMarkdownIndicator && (
+                      <Box
+                        marginLeft={
+                          (showApprovalIndicator || uiState.shellModeActive) &&
+                          !isNarrow
+                            ? 1
+                            : 0
+                        }
+                        marginTop={
+                          (showApprovalIndicator || uiState.shellModeActive) &&
+                          isNarrow
+                            ? 1
+                            : 0
+                        }
+                      >
+                        <RawMarkdownIndicator />
+                      </Box>
+                    )}
+                  </Box>
+                )
+              )}
+            </Box>
+
+            <Box
+              marginTop={isNarrow ? 1 : 0}
+              flexDirection="column"
+              alignItems={isNarrow ? 'flex-start' : 'flex-end'}
+            >
+              {!showLoadingIndicator && (
+                <StatusDisplay hideContextSummary={hideContextSummary} />
+              )}
+            </Box>
           </Box>
-        </Box>
+        )}
       </Box>
 
-      {uiState.showErrorDetails && (
+      {showUiDetails && uiState.showErrorDetails && (
         <OverflowProvider>
           <Box flexDirection="column">
             <DetailedMessagesDisplay
@@ -301,7 +433,9 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
         />
       )}
 
-      {!settings.merged.ui.hideFooter && !isScreenReaderEnabled && <Footer />}
+      {showUiDetails &&
+        !settings.merged.ui.hideFooter &&
+        !isScreenReaderEnabled && <Footer />}
     </Box>
   );
 };
diff --git a/packages/cli/src/ui/components/InputPrompt.test.tsx b/packages/cli/src/ui/components/InputPrompt.test.tsx
index d4d9775f02..31448cf6df 100644
--- a/packages/cli/src/ui/components/InputPrompt.test.tsx
+++ b/packages/cli/src/ui/components/InputPrompt.test.tsx
@@ -149,8 +149,14 @@ describe('InputPrompt', () => {
   );
   const mockedUseKittyKeyboardProtocol = vi.mocked(useKittyKeyboardProtocol);
   const mockSetEmbeddedShellFocused = vi.fn();
+  const mockSetCleanUiDetailsVisible = vi.fn();
+  const mockToggleCleanUiDetailsVisible = vi.fn();
+  const mockRevealCleanUiDetailsTemporarily = vi.fn();
   const uiActions = {
     setEmbeddedShellFocused: mockSetEmbeddedShellFocused,
+    setCleanUiDetailsVisible: mockSetCleanUiDetailsVisible,
+    toggleCleanUiDetailsVisible: mockToggleCleanUiDetailsVisible,
+    revealCleanUiDetailsTemporarily: mockRevealCleanUiDetailsTemporarily,
   };
 
   beforeEach(() => {
@@ -2945,29 +2951,29 @@ describe('InputPrompt', () => {
     });
   });
 
-  describe('Tab focus toggle', () => {
+  describe('Tab clean UI toggle', () => {
     it.each([
       {
-        name: 'should toggle focus in on Tab when no suggestions or ghost text',
+        name: 'should toggle clean UI details on double-Tab when no suggestions or ghost text',
         showSuggestions: false,
         ghostText: '',
         suggestions: [],
-        expectedFocusToggle: true,
+        expectedUiToggle: true,
       },
       {
-        name: 'should accept ghost text and NOT toggle focus on Tab',
+        name: 'should accept ghost text and NOT toggle clean UI details on Tab',
         showSuggestions: false,
         ghostText: 'ghost text',
         suggestions: [],
-        expectedFocusToggle: false,
+        expectedUiToggle: false,
         expectedAcceptCall: true,
       },
       {
-        name: 'should NOT toggle focus on Tab when suggestions are present',
+        name: 'should NOT toggle clean UI details on Tab when suggestions are present',
         showSuggestions: true,
         ghostText: '',
         suggestions: [{ label: 'test', value: 'test' }],
-        expectedFocusToggle: false,
+        expectedUiToggle: false,
       },
     ])(
       '$name',
@@ -2975,7 +2981,7 @@ describe('InputPrompt', () => {
         showSuggestions,
         ghostText,
         suggestions,
-        expectedFocusToggle,
+        expectedUiToggle,
         expectedAcceptCall,
       }) => {
         const mockAccept = vi.fn();
@@ -2997,21 +3003,24 @@ describe('InputPrompt', () => {
           <InputPrompt {...props} />,
           {
             uiActions,
-            uiState: { activePtyId: 1 },
+            uiState: {},
           },
         );
 
         await act(async () => {
           stdin.write('\t');
+          if (expectedUiToggle) {
+            stdin.write('\t');
+          }
         });
 
         await waitFor(() => {
-          if (expectedFocusToggle) {
-            expect(uiActions.setEmbeddedShellFocused).toHaveBeenCalledWith(
-              true,
-            );
+          if (expectedUiToggle) {
+            expect(uiActions.toggleCleanUiDetailsVisible).toHaveBeenCalled();
           } else {
-            expect(uiActions.setEmbeddedShellFocused).not.toHaveBeenCalled();
+            expect(
+              uiActions.toggleCleanUiDetailsVisible,
+            ).not.toHaveBeenCalled();
           }
 
           if (expectedAcceptCall) {
@@ -3021,6 +3030,75 @@ describe('InputPrompt', () => {
         unmount();
       },
     );
+
+    it('should not reveal clean UI details on Shift+Tab when hidden', async () => {
+      mockedUseCommandCompletion.mockReturnValue({
+        ...mockCommandCompletion,
+        showSuggestions: false,
+        suggestions: [],
+        promptCompletion: {
+          text: '',
+          accept: vi.fn(),
+          clear: vi.fn(),
+          isLoading: false,
+          isActive: false,
+          markSelected: vi.fn(),
+        },
+      });
+
+      const { stdin, unmount } = renderWithProviders(
+        <InputPrompt {...props} />,
+        {
+          uiActions,
+          uiState: { activePtyId: 1, cleanUiDetailsVisible: false },
+        },
+      );
+
+      await act(async () => {
+        stdin.write('\x1b[Z');
+      });
+
+      await waitFor(() => {
+        expect(
+          uiActions.revealCleanUiDetailsTemporarily,
+        ).not.toHaveBeenCalled();
+      });
+      unmount();
+    });
+
+    it('should toggle clean UI details on double-Tab by default', async () => {
+      mockedUseCommandCompletion.mockReturnValue({
+        ...mockCommandCompletion,
+        showSuggestions: false,
+        suggestions: [],
+        promptCompletion: {
+          text: '',
+          accept: vi.fn(),
+          clear: vi.fn(),
+          isLoading: false,
+          isActive: false,
+          markSelected: vi.fn(),
+        },
+      });
+
+      const { stdin, unmount } = renderWithProviders(
+        <InputPrompt {...props} />,
+        {
+          uiActions,
+          uiState: {},
+        },
+      );
+
+      await act(async () => {
+        stdin.write('\t');
+        stdin.write('\t');
+      });
+
+      await waitFor(() => {
+        expect(uiActions.toggleCleanUiDetailsVisible).toHaveBeenCalled();
+      });
+      unmount();
+    });
   });
 
   describe('mouse interaction', () => {
diff --git a/packages/cli/src/ui/components/InputPrompt.tsx b/packages/cli/src/ui/components/InputPrompt.tsx
index 22fd317c10..5cb23ac433 100644
--- a/packages/cli/src/ui/components/InputPrompt.tsx
+++ b/packages/cli/src/ui/components/InputPrompt.tsx
@@ -144,6 +144,8 @@ export function isLargePaste(text: string): boolean {
   );
 }
 
+const DOUBLE_TAB_CLEAN_UI_TOGGLE_WINDOW_MS = 350;
+
 /**
  * Attempt to toggle expansion of a paste placeholder in the buffer.
  * Returns true if a toggle action was performed or hint was shown, false otherwise.
@@ -211,7 +213,11 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
   const { merged: settings } = useSettings();
   const kittyProtocol = useKittyKeyboardProtocol();
   const isShellFocused = useShellFocusState();
-  const { setEmbeddedShellFocused, setShortcutsHelpVisible } = useUIActions();
+  const {
+    setEmbeddedShellFocused,
+    setShortcutsHelpVisible,
+    toggleCleanUiDetailsVisible,
+  } = useUIActions();
   const {
     terminalWidth,
     activePtyId,
@@ -223,6 +229,7 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
   } = useUIState();
   const [suppressCompletion, setSuppressCompletion] = useState(false);
   const escPressCount = useRef(0);
+  const lastPlainTabPressTimeRef = useRef<number | null>(null);
   const [showEscapePrompt, setShowEscapePrompt] = useState(false);
   const escapeTimerRef = useRef<NodeJS.Timeout | null>(null);
   const [recentUnsafePasteTime, setRecentUnsafePasteTime] = useState<
@@ -624,6 +631,33 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
         return false;
       }
 
+      const isPlainTab =
+        key.name === 'tab' && !key.shift && !key.alt && !key.ctrl && !key.cmd;
+      const hasTabCompletionInteraction =
+        completion.showSuggestions ||
+        Boolean(completion.promptCompletion.text) ||
+        reverseSearchActive ||
+        commandSearchActive;
+      if (isPlainTab) {
+        if (!hasTabCompletionInteraction) {
+          const now = Date.now();
+          const isDoubleTabPress =
+            lastPlainTabPressTimeRef.current !== null &&
+            now - lastPlainTabPressTimeRef.current <=
+              DOUBLE_TAB_CLEAN_UI_TOGGLE_WINDOW_MS;
+          if (isDoubleTabPress) {
+            lastPlainTabPressTimeRef.current = null;
+            toggleCleanUiDetailsVisible();
+            return true;
+          }
+          lastPlainTabPressTimeRef.current = now;
+        } else {
+          lastPlainTabPressTimeRef.current = null;
+        }
+      } else {
+        lastPlainTabPressTimeRef.current = null;
+      }
+
       if (key.name === 'paste') {
         if (shortcutsHelpVisible) {
           setShortcutsHelpVisible(false);
@@ -1172,6 +1206,7 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
       kittyProtocol.enabled,
       shortcutsHelpVisible,
       setShortcutsHelpVisible,
+      toggleCleanUiDetailsVisible,
       tryLoadQueuedMessages,
       setBannerVisible,
       onSubmit,
diff --git a/packages/cli/src/ui/components/MainContent.test.tsx b/packages/cli/src/ui/components/MainContent.test.tsx
index 5586ad8e59..4e6d8c7803 100644
--- a/packages/cli/src/ui/components/MainContent.test.tsx
+++ b/packages/cli/src/ui/components/MainContent.test.tsx
@@ -9,11 +9,15 @@ import { waitFor } from '../../test-utils/async.js';
 import { MainContent } from './MainContent.js';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { Box, Text } from 'ink';
-import type React from 'react';
+import { act, useState, type JSX } from 'react';
 import { useAlternateBuffer } from '../hooks/useAlternateBuffer.js';
 import { ToolCallStatus } from '../types.js';
 import { SHELL_COMMAND_NAME } from '../constants.js';
-import type { UIState } from '../contexts/UIStateContext.js';
+import {
+  UIStateContext,
+  useUIState,
+  type UIState,
+} from '../contexts/UIStateContext.js';
 
 // Mock dependencies
 vi.mock('../contexts/SettingsContext.js', async () => {
@@ -45,7 +49,9 @@ vi.mock('../hooks/useAlternateBuffer.js', () => ({
 }));
 
 vi.mock('./AppHeader.js', () => ({
-  AppHeader: () => <Text>AppHeader</Text>,
+  AppHeader: ({ showDetails = true }: { showDetails?: boolean }) => (
+    <Text>{showDetails ? 'AppHeader(full)' : 'AppHeader(minimal)'}</Text>
+  ),
 }));
 
 vi.mock('./ShowMoreLines.js', () => ({
@@ -58,7 +64,7 @@ vi.mock('./shared/ScrollableList.js', () => ({
     renderItem,
   }: {
     data: unknown[];
-    renderItem: (props: { item: unknown }) => React.JSX.Element;
+    renderItem: (props: { item: unknown }) => JSX.Element;
   }) => (
     <Box flexDirection="column">
       <Text>ScrollableList</Text>
@@ -87,6 +93,7 @@ describe('MainContent', () => {
     activePtyId: undefined,
     embeddedShellFocused: false,
     historyRemountKey: 0,
+    cleanUiDetailsVisible: true,
     bannerData: { defaultText: '', warningText: '' },
     bannerVisible: false,
     copyModeEnabled: false,
@@ -101,7 +108,7 @@ describe('MainContent', () => {
     const { lastFrame } = renderWithProviders(<MainContent />, {
       uiState: defaultMockUiState as Partial<UIState>,
     });
-    await waitFor(() => expect(lastFrame()).toContain('AppHeader'));
+    await waitFor(() => expect(lastFrame()).toContain('AppHeader(full)'));
     const output = lastFrame();
 
     expect(output).toContain('Hello');
@@ -116,11 +123,81 @@ describe('MainContent', () => {
     await waitFor(() => expect(lastFrame()).toContain('ScrollableList'));
     const output = lastFrame();
 
-    expect(output).toContain('AppHeader');
+    expect(output).toContain('AppHeader(full)');
     expect(output).toContain('Hello');
     expect(output).toContain('Hi there');
   });
 
+  it('renders minimal header in minimal mode (alternate buffer)', async () => {
+    vi.mocked(useAlternateBuffer).mockReturnValue(true);
+
+    const { lastFrame } = renderWithProviders(<MainContent />, {
+      uiState: {
+        ...defaultMockUiState,
+        cleanUiDetailsVisible: false,
+      } as Partial<UIState>,
+    });
+    await waitFor(() => expect(lastFrame()).toContain('Hello'));
+    const output = lastFrame();
+
+    expect(output).toContain('AppHeader(minimal)');
+    expect(output).not.toContain('AppHeader(full)');
+    expect(output).toContain('Hello');
+  });
+
+  it('restores full header details after toggle in alternate buffer mode', async () => {
+    vi.mocked(useAlternateBuffer).mockReturnValue(true);
+
+    let setShowDetails: ((visible: boolean) => void) | undefined;
+    const ToggleHarness = () => {
+      const outerState = useUIState();
+      const [showDetails, setShowDetailsState] = useState(
+        outerState.cleanUiDetailsVisible,
+      );
+      setShowDetails = setShowDetailsState;
+
+      return (
+        <UIStateContext.Provider
+          value={{ ...outerState, cleanUiDetailsVisible: showDetails }}
+        >
+          <MainContent />
+        </UIStateContext.Provider>
+      );
+    };
+
+    const { lastFrame } = renderWithProviders(<ToggleHarness />, {
+      uiState: {
+        ...defaultMockUiState,
+        cleanUiDetailsVisible: false,
+      } as Partial<UIState>,
+    });
+
+    await waitFor(() => expect(lastFrame()).toContain('AppHeader(minimal)'));
+    if (!setShowDetails) {
+      throw new Error('setShowDetails was not initialized');
+    }
+    const setShowDetailsSafe = setShowDetails;
+
+    act(() => {
+      setShowDetailsSafe(true);
+    });
+
+    await waitFor(() => expect(lastFrame()).toContain('AppHeader(full)'));
+  });
+
+  it('always renders full header details in normal buffer mode', async () => {
+    vi.mocked(useAlternateBuffer).mockReturnValue(false);
+    const { lastFrame } = renderWithProviders(<MainContent />, {
+      uiState: {
+        ...defaultMockUiState,
+        cleanUiDetailsVisible: false,
+      } as Partial<UIState>,
+    });
+
+    await waitFor(() => expect(lastFrame()).toContain('AppHeader(full)'));
+    expect(lastFrame()).not.toContain('AppHeader(minimal)');
+  });
+
   it('does not constrain height in alternate buffer mode', async () => {
     vi.mocked(useAlternateBuffer).mockReturnValue(true);
     const { lastFrame } = renderWithProviders(<MainContent />, {
@@ -129,7 +206,9 @@ describe('MainContent', () => {
     await waitFor(() => expect(lastFrame()).toContain('Hello'));
     const output = lastFrame();
 
-    expect(output).toMatchSnapshot();
+    expect(output).toContain('AppHeader(full)');
+    expect(output).toContain('Hello');
+    expect(output).toContain('Hi there');
   });
 
   describe('MainContent Tool Output Height Logic', () => {
@@ -210,6 +289,7 @@ describe('MainContent', () => {
           isEditorDialogOpen: false,
           slashCommands: [],
           historyRemountKey: 0,
+          cleanUiDetailsVisible: true,
           bannerData: {
             defaultText: '',
             warningText: '',
diff --git a/packages/cli/src/ui/components/MainContent.tsx b/packages/cli/src/ui/components/MainContent.tsx
index 586553a1f2..1dcc32ffd4 100644
--- a/packages/cli/src/ui/components/MainContent.tsx
+++ b/packages/cli/src/ui/components/MainContent.tsx
@@ -48,7 +48,9 @@ export const MainContent = () => {
     mainAreaWidth,
     staticAreaMaxItemHeight,
     availableTerminalHeight,
+    cleanUiDetailsVisible,
   } = uiState;
+  const showHeaderDetails = cleanUiDetailsVisible;
 
   const historyItems = useMemo(
     () =>
@@ -120,7 +122,13 @@ export const MainContent = () => {
   const renderItem = useCallback(
     ({ item }: { item: (typeof virtualizedData)[number] }) => {
       if (item.type === 'header') {
-        return <MemoizedAppHeader key="app-header" version={version} />;
+        return (
+          <MemoizedAppHeader
+            key="app-header"
+            version={version}
+            showDetails={showHeaderDetails}
+          />
+        );
       } else if (item.type === 'history') {
         return (
           <MemoizedHistoryItemDisplay
@@ -137,7 +145,13 @@ export const MainContent = () => {
         return pendingItems;
       }
     },
-    [version, mainAreaWidth, uiState.slashCommands, pendingItems],
+    [
+      showHeaderDetails,
+      version,
+      mainAreaWidth,
+      uiState.slashCommands,
+      pendingItems,
+    ],
   );
 
   if (isAlternateBuffer) {
diff --git a/packages/cli/src/ui/components/ShortcutsHelp.test.tsx b/packages/cli/src/ui/components/ShortcutsHelp.test.tsx
index e03f2c538b..3ccab4ac64 100644
--- a/packages/cli/src/ui/components/ShortcutsHelp.test.tsx
+++ b/packages/cli/src/ui/components/ShortcutsHelp.test.tsx
@@ -46,4 +46,10 @@ describe('ShortcutsHelp', () => {
       expect(lastFrame()).toMatchSnapshot();
     },
   );
+
+  it('always shows Tab Tab focus UI shortcut', () => {
+    const rendered = renderWithProviders(<ShortcutsHelp />);
+    expect(rendered.lastFrame()).toContain('Tab Tab');
+    rendered.unmount();
+  });
 });
diff --git a/packages/cli/src/ui/components/ShortcutsHelp.tsx b/packages/cli/src/ui/components/ShortcutsHelp.tsx
index e18938fd62..dfa867d46c 100644
--- a/packages/cli/src/ui/components/ShortcutsHelp.tsx
+++ b/packages/cli/src/ui/components/ShortcutsHelp.tsx
@@ -22,13 +22,14 @@ const buildShortcutItems = (): ShortcutItem[] => {
 
   return [
     { key: '!', description: 'shell mode' },
+    { key: '@', description: 'select file or folder' },
+    { key: 'Esc Esc', description: 'clear & rewind' },
+    { key: 'Tab Tab', description: 'focus UI' },
+    { key: 'Ctrl+Y', description: 'YOLO mode' },
     { key: 'Shift+Tab', description: 'cycle mode' },
     { key: 'Ctrl+V', description: 'paste images' },
-    { key: '@', description: 'select file or folder' },
-    { key: 'Ctrl+Y', description: 'YOLO mode' },
-    { key: 'Ctrl+R', description: 'reverse-search history' },
-    { key: 'Esc Esc', description: 'clear prompt / rewind' },
     { key: `${altLabel}+M`, description: 'raw markdown mode' },
+    { key: 'Ctrl+R', description: 'reverse-search history' },
     { key: 'Ctrl+X', description: 'open external editor' },
   ];
 };
@@ -46,15 +47,29 @@ const Shortcut: React.FC<{ item: ShortcutItem }> = ({ item }) => (
 
 export const ShortcutsHelp: React.FC = () => {
   const { terminalWidth } = useUIState();
-  const items = buildShortcutItems();
-
   const isNarrow = isNarrowWidth(terminalWidth);
+  const items = buildShortcutItems();
+  const itemsForDisplay = isNarrow
+    ? items
+    : [
+        // Keep first column stable: !, @, Esc Esc, Tab Tab.
+        items[0],
+        items[5],
+        items[6],
+        items[1],
+        items[4],
+        items[7],
+        items[2],
+        items[8],
+        items[9],
+        items[3],
+      ];
 
   return (
     <Box flexDirection="column" width="100%">
       <SectionHeader title="Shortcuts (for more, see /help)" />
       <Box flexDirection="row" flexWrap="wrap" paddingLeft={1} paddingRight={2}>
-        {items.map((item, index) => (
+        {itemsForDisplay.map((item, index) => (
           <Box
             key={`${item.key}-${index}`}
             width={isNarrow ? '100%' : '33%'}
diff --git a/packages/cli/src/ui/components/ShortcutsHint.tsx b/packages/cli/src/ui/components/ShortcutsHint.tsx
index 70b72e902e..4ecb01e9d8 100644
--- a/packages/cli/src/ui/components/ShortcutsHint.tsx
+++ b/packages/cli/src/ui/components/ShortcutsHint.tsx
@@ -10,7 +10,12 @@ import { theme } from '../semantic-colors.js';
 import { useUIState } from '../contexts/UIStateContext.js';
 
 export const ShortcutsHint: React.FC = () => {
-  const { shortcutsHelpVisible } = useUIState();
+  const { cleanUiDetailsVisible, shortcutsHelpVisible } = useUIState();
+
+  if (!cleanUiDetailsVisible) {
+    return <Text color={theme.text.secondary}> press tab twice for more </Text>;
+  }
+
   const highlightColor = shortcutsHelpVisible
     ? theme.text.accent
     : theme.text.secondary;
diff --git a/packages/cli/src/ui/components/__snapshots__/MainContent.test.tsx.snap b/packages/cli/src/ui/components/__snapshots__/MainContent.test.tsx.snap
index 22cbd276a1..0d3bb5beec 100644
--- a/packages/cli/src/ui/components/__snapshots__/MainContent.test.tsx.snap
+++ b/packages/cli/src/ui/components/__snapshots__/MainContent.test.tsx.snap
@@ -2,7 +2,7 @@
 
 exports[`MainContent > MainContent Tool Output Height Logic > 'ASB mode - Focused shell should expand' 1`] = `
 "ScrollableList
-AppHeader
+AppHeader(full)
 ╭──────────────────────────────────────────────────────────────────────────────────────────────╮
 │ ⊷  Shell Command Running a long command...                                                   │
 │                                                                                              │
@@ -33,7 +33,7 @@ ShowMoreLines"
 
 exports[`MainContent > MainContent Tool Output Height Logic > 'ASB mode - Unfocused shell' 1`] = `
 "ScrollableList
-AppHeader
+AppHeader(full)
 ╭──────────────────────────────────────────────────────────────────────────────────────────────╮
 │ ⊷  Shell Command Running a long command...                                                   │
 │                                                                                              │
@@ -57,7 +57,7 @@ ShowMoreLines"
 `;
 
 exports[`MainContent > MainContent Tool Output Height Logic > 'Normal mode - Constrained height' 1`] = `
-"AppHeader
+"AppHeader(full)
 ╭──────────────────────────────────────────────────────────────────────────────────────────────╮
 │ ⊷  Shell Command Running a long command...                                                   │
 │                                                                                              │
@@ -81,7 +81,7 @@ ShowMoreLines"
 `;
 
 exports[`MainContent > MainContent Tool Output Height Logic > 'Normal mode - Unconstrained height' 1`] = `
-"AppHeader
+"AppHeader(full)
 ╭──────────────────────────────────────────────────────────────────────────────────────────────╮
 │ ⊷  Shell Command Running a long command...                                                   │
 │                                                                                              │
@@ -103,14 +103,3 @@ exports[`MainContent > MainContent Tool Output Height Logic > 'Normal mode - Unc
 ╰──────────────────────────────────────────────────────────────────────────────────────────────╯
 ShowMoreLines"
 `;
-
-exports[`MainContent > does not constrain height in alternate buffer mode 1`] = `
-"ScrollableList
-AppHeader
-▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
- > Hello
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-✦ Hi there
-  ShowMoreLines
-"
-`;
diff --git a/packages/cli/src/ui/components/__snapshots__/ShortcutsHelp.test.tsx.snap b/packages/cli/src/ui/components/__snapshots__/ShortcutsHelp.test.tsx.snap
index 692ac0c2d8..829bebd4cb 100644
--- a/packages/cli/src/ui/components/__snapshots__/ShortcutsHelp.test.tsx.snap
+++ b/packages/cli/src/ui/components/__snapshots__/ShortcutsHelp.test.tsx.snap
@@ -3,39 +3,43 @@
 exports[`ShortcutsHelp > renders correctly in 'narrow' mode on 'linux' 1`] = `
 "── Shortcuts (for more, see /help) ─────
  ! shell mode
+ @ select file or folder
+ Esc Esc clear & rewind
+ Tab Tab focus UI
+ Ctrl+Y YOLO mode
  Shift+Tab cycle mode
  Ctrl+V paste images
- @ select file or folder
- Ctrl+Y YOLO mode
- Ctrl+R reverse-search history
- Esc Esc clear prompt / rewind
  Alt+M raw markdown mode
+ Ctrl+R reverse-search history
  Ctrl+X open external editor"
 `;
 
 exports[`ShortcutsHelp > renders correctly in 'narrow' mode on 'mac' 1`] = `
 "── Shortcuts (for more, see /help) ─────
  ! shell mode
+ @ select file or folder
+ Esc Esc clear & rewind
+ Tab Tab focus UI
+ Ctrl+Y YOLO mode
  Shift+Tab cycle mode
  Ctrl+V paste images
- @ select file or folder
- Ctrl+Y YOLO mode
- Ctrl+R reverse-search history
- Esc Esc clear prompt / rewind
  Option+M raw markdown mode
+ Ctrl+R reverse-search history
  Ctrl+X open external editor"
 `;
 
 exports[`ShortcutsHelp > renders correctly in 'wide' mode on 'linux' 1`] = `
 "── Shortcuts (for more, see /help) ─────────────────────────────────────────────────────────────────
  ! shell mode                    Shift+Tab cycle mode            Ctrl+V paste images
- @ select file or folder         Ctrl+Y YOLO mode                Ctrl+R reverse-search history
- Esc Esc clear prompt / rewind   Alt+M raw markdown mode         Ctrl+X open external editor"
+ @ select file or folder         Ctrl+Y YOLO mode                Alt+M raw markdown mode
+ Esc Esc clear & rewind          Ctrl+R reverse-search history   Ctrl+X open external editor
+ Tab Tab focus UI"
 `;
 
 exports[`ShortcutsHelp > renders correctly in 'wide' mode on 'mac' 1`] = `
 "── Shortcuts (for more, see /help) ─────────────────────────────────────────────────────────────────
  ! shell mode                    Shift+Tab cycle mode            Ctrl+V paste images
- @ select file or folder         Ctrl+Y YOLO mode                Ctrl+R reverse-search history
- Esc Esc clear prompt / rewind   Option+M raw markdown mode      Ctrl+X open external editor"
+ @ select file or folder         Ctrl+Y YOLO mode                Option+M raw markdown mode
+ Esc Esc clear & rewind          Ctrl+R reverse-search history   Ctrl+X open external editor
+ Tab Tab focus UI"
 `;
diff --git a/packages/cli/src/ui/contexts/UIActionsContext.tsx b/packages/cli/src/ui/contexts/UIActionsContext.tsx
index 8ad79f6b25..0fb98c34ff 100644
--- a/packages/cli/src/ui/contexts/UIActionsContext.tsx
+++ b/packages/cli/src/ui/contexts/UIActionsContext.tsx
@@ -68,6 +68,10 @@ export interface UIActions {
   handleApiKeyCancel: () => void;
   setBannerVisible: (visible: boolean) => void;
   setShortcutsHelpVisible: (visible: boolean) => void;
+  setCleanUiDetailsVisible: (visible: boolean) => void;
+  toggleCleanUiDetailsVisible: () => void;
+  revealCleanUiDetailsTemporarily: (durationMs?: number) => void;
+  handleWarning: (message: string) => void;
   setEmbeddedShellFocused: (value: boolean) => void;
   dismissBackgroundShell: (pid: number) => void;
   setActiveBackgroundShellPid: (pid: number) => void;
diff --git a/packages/cli/src/ui/contexts/UIStateContext.tsx b/packages/cli/src/ui/contexts/UIStateContext.tsx
index cf41896232..54bde1732a 100644
--- a/packages/cli/src/ui/contexts/UIStateContext.tsx
+++ b/packages/cli/src/ui/contexts/UIStateContext.tsx
@@ -120,6 +120,7 @@ export interface UIState {
   ctrlDPressedOnce: boolean;
   showEscapePrompt: boolean;
   shortcutsHelpVisible: boolean;
+  cleanUiDetailsVisible: boolean;
   elapsedTime: number;
   currentLoadingPhrase: string | undefined;
   historyRemountKey: number;
diff --git a/packages/cli/src/ui/keyMatchers.test.ts b/packages/cli/src/ui/keyMatchers.test.ts
index a014d2bdc1..329549c08d 100644
--- a/packages/cli/src/ui/keyMatchers.test.ts
+++ b/packages/cli/src/ui/keyMatchers.test.ts
@@ -370,7 +370,7 @@ describe('keyMatchers', () => {
     {
       command: Command.FOCUS_SHELL_INPUT,
       positive: [createKey('tab')],
-      negative: [createKey('f', { ctrl: true }), createKey('f')],
+      negative: [createKey('f6'), createKey('f', { ctrl: true })],
     },
     {
       command: Command.TOGGLE_YOLO,
diff --git a/packages/cli/src/utils/persistentState.ts b/packages/cli/src/utils/persistentState.ts
index b849703f53..cbdf1fc6cb 100644
--- a/packages/cli/src/utils/persistentState.ts
+++ b/packages/cli/src/utils/persistentState.ts
@@ -14,6 +14,7 @@ interface PersistentStateData {
   defaultBannerShownCount?: Record<string, number>;
   tipsShown?: number;
   hasSeenScreenReaderNudge?: boolean;
+  focusUiEnabled?: boolean;
   // Add other persistent state keys here as needed
 }
 

From 207ac6f2dc9fe8738cf38423015bb6ed61e271ea Mon Sep 17 00:00:00 2001
From: Jacob Richman <jacob314@gmail.com>
Date: Thu, 12 Feb 2026 11:56:07 -0800
Subject: [PATCH 28/44] ui(polish) blend background color with theme (#18802)

---
 packages/cli/src/test-utils/render.tsx        |  14 +-
 packages/cli/src/ui/AppContainer.tsx          |   4 +-
 packages/cli/src/ui/colors.ts                 |   4 +-
 .../src/ui/components/InputPrompt.test.tsx    |   6 +-
 .../cli/src/ui/components/InputPrompt.tsx     |   3 +-
 .../cli/src/ui/components/ThemeDialog.tsx     |  47 ++--
 .../__snapshots__/ThemeDialog.test.tsx.snap   |  24 +--
 .../components/shared/HalfLinePaddedBox.tsx   |   5 +-
 .../src/ui/contexts/TerminalContext.test.tsx  |   5 +
 .../cli/src/ui/contexts/TerminalContext.tsx   |  25 ++-
 .../cli/src/ui/contexts/UIActionsContext.tsx  |   5 +-
 .../cli/src/ui/hooks/useSnowfall.test.tsx     |   4 +
 .../src/ui/hooks/useTerminalTheme.test.tsx    |  24 ++-
 packages/cli/src/ui/hooks/useTerminalTheme.ts |  15 +-
 packages/cli/src/ui/hooks/useThemeCommand.ts  |  19 +-
 packages/cli/src/ui/themes/color-utils.ts     | 202 ++++--------------
 .../cli/src/ui/themes/theme-manager.test.ts   | 111 ++++++++++
 packages/cli/src/ui/themes/theme-manager.ts   | 130 ++++++++++-
 .../src/ui/utils/terminalCapabilityManager.ts |  12 +-
 packages/cli/src/utils/terminalTheme.ts       |  13 +-
 20 files changed, 432 insertions(+), 240 deletions(-)

diff --git a/packages/cli/src/test-utils/render.tsx b/packages/cli/src/test-utils/render.tsx
index 10ad4281ef..de0afc9c50 100644
--- a/packages/cli/src/test-utils/render.tsx
+++ b/packages/cli/src/test-utils/render.tsx
@@ -33,6 +33,9 @@ import { makeFakeConfig, type Config } from '@google/gemini-cli-core';
 import { FakePersistentState } from './persistentStateFake.js';
 import { AppContext, type AppState } from '../ui/contexts/AppContext.js';
 import { createMockSettings } from './settings.js';
+import { themeManager, DEFAULT_THEME } from '../ui/themes/theme-manager.js';
+import { DefaultLight } from '../ui/themes/default-light.js';
+import { pickDefaultThemeName } from '../ui/themes/theme.js';
 
 export const persistentStateMock = new FakePersistentState();
 
@@ -150,8 +153,8 @@ const baseMockUiState = {
   terminalWidth: 120,
   terminalHeight: 40,
   currentModel: 'gemini-pro',
+  terminalBackgroundColor: 'black',
   cleanUiDetailsVisible: false,
-  terminalBackgroundColor: undefined,
   activePtyId: undefined,
   backgroundShells: new Map(),
   backgroundShellHeight: 0,
@@ -298,6 +301,15 @@ export const renderWithProviders = (
     mainAreaWidth,
   };
 
+  themeManager.setTerminalBackground(baseState.terminalBackgroundColor);
+  const themeName = pickDefaultThemeName(
+    baseState.terminalBackgroundColor,
+    themeManager.getAllThemes(),
+    DEFAULT_THEME.name,
+    DefaultLight.name,
+  );
+  themeManager.setActiveTheme(themeName);
+
   const finalUIActions = { ...mockUIActions, ...uiActions };
 
   const allToolCalls = (finalUiState.pendingHistoryItems || [])
diff --git a/packages/cli/src/ui/AppContainer.tsx b/packages/cli/src/ui/AppContainer.tsx
index 4c590c21eb..17e54f4771 100644
--- a/packages/cli/src/ui/AppContainer.tsx
+++ b/packages/cli/src/ui/AppContainer.tsx
@@ -496,7 +496,7 @@ export const AppContainer = (props: AppContainerProps) => {
       );
       coreEvents.off(CoreEvent.AgentsDiscovered, handleAgentsDiscovered);
     };
-  }, []);
+  }, [settings]);
 
   const { consoleMessages, clearConsoleMessages: clearConsoleMessagesState } =
     useConsoleMessages();
@@ -612,7 +612,7 @@ export const AppContainer = (props: AppContainerProps) => {
   );
 
   // Poll for terminal background color changes to auto-switch theme
-  useTerminalTheme(handleThemeSelect, config);
+  useTerminalTheme(handleThemeSelect, config, refreshStatic);
 
   const {
     authState,
diff --git a/packages/cli/src/ui/colors.ts b/packages/cli/src/ui/colors.ts
index 87ec04b730..0825527cf5 100644
--- a/packages/cli/src/ui/colors.ts
+++ b/packages/cli/src/ui/colors.ts
@@ -15,7 +15,7 @@ export const Colors: ColorsTheme = {
     return themeManager.getActiveTheme().colors.Foreground;
   },
   get Background() {
-    return themeManager.getActiveTheme().colors.Background;
+    return themeManager.getColors().Background;
   },
   get LightBlue() {
     return themeManager.getActiveTheme().colors.LightBlue;
@@ -51,7 +51,7 @@ export const Colors: ColorsTheme = {
     return themeManager.getActiveTheme().colors.Gray;
   },
   get DarkGray() {
-    return themeManager.getActiveTheme().colors.DarkGray;
+    return themeManager.getColors().DarkGray;
   },
   get GradientColors() {
     return themeManager.getActiveTheme().colors.GradientColors;
diff --git a/packages/cli/src/ui/components/InputPrompt.test.tsx b/packages/cli/src/ui/components/InputPrompt.test.tsx
index 31448cf6df..8257cd8acc 100644
--- a/packages/cli/src/ui/components/InputPrompt.test.tsx
+++ b/packages/cli/src/ui/components/InputPrompt.test.tsx
@@ -1549,7 +1549,6 @@ describe('InputPrompt', () => {
       { color: 'black', name: 'black' },
       { color: '#000000', name: '#000000' },
       { color: '#000', name: '#000' },
-      { color: undefined, name: 'default (black)' },
       { color: 'white', name: 'white' },
       { color: '#ffffff', name: '#ffffff' },
       { color: '#fff', name: '#fff' },
@@ -1619,6 +1618,11 @@ describe('InputPrompt', () => {
 
       const { stdout, unmount } = renderWithProviders(
         <InputPrompt {...props} />,
+        {
+          uiState: {
+            terminalBackgroundColor: 'black',
+          } as Partial<UIState>,
+        },
       );
 
       await waitFor(() => {
diff --git a/packages/cli/src/ui/components/InputPrompt.tsx b/packages/cli/src/ui/components/InputPrompt.tsx
index 5cb23ac433..d9f0f34288 100644
--- a/packages/cli/src/ui/components/InputPrompt.tsx
+++ b/packages/cli/src/ui/components/InputPrompt.tsx
@@ -222,7 +222,6 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
     terminalWidth,
     activePtyId,
     history,
-    terminalBackgroundColor,
     backgroundShells,
     backgroundShellHeight,
     shortcutsHelpVisible,
@@ -1352,7 +1351,7 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
 
   const useBackgroundColor = config.getUseBackgroundColor();
   const isLowColor = isLowColorDepth();
-  const terminalBg = terminalBackgroundColor || 'black';
+  const terminalBg = theme.background.primary || 'black';
 
   // We should fallback to lines if the background color is disabled OR if it is
   // enabled but we are in a low color depth terminal where we don't have a safe
diff --git a/packages/cli/src/ui/components/ThemeDialog.tsx b/packages/cli/src/ui/components/ThemeDialog.tsx
index f04ae5172a..65e26aae49 100644
--- a/packages/cli/src/ui/components/ThemeDialog.tsx
+++ b/packages/cli/src/ui/components/ThemeDialog.tsx
@@ -9,7 +9,7 @@ import { useCallback, useState } from 'react';
 import { Box, Text } from 'ink';
 import { theme } from '../semantic-colors.js';
 import { themeManager, DEFAULT_THEME } from '../themes/theme-manager.js';
-import { pickDefaultThemeName } from '../themes/theme.js';
+import { pickDefaultThemeName, type Theme } from '../themes/theme.js';
 import { RadioButtonSelect } from './shared/RadioButtonSelect.js';
 import { DiffRenderer } from './messages/DiffRenderer.js';
 import { colorizeCode } from '../utils/CodeColorizer.js';
@@ -27,7 +27,10 @@ import { useUIState } from '../contexts/UIStateContext.js';
 
 interface ThemeDialogProps {
   /** Callback function when a theme is selected */
-  onSelect: (themeName: string, scope: LoadableSettingScope) => void;
+  onSelect: (
+    themeName: string,
+    scope: LoadableSettingScope,
+  ) => void | Promise<void>;
 
   /** Callback function when the dialog is cancelled */
   onCancel: () => void;
@@ -40,24 +43,21 @@ interface ThemeDialogProps {
   terminalWidth: number;
 }
 
-import {
-  getThemeTypeFromBackgroundColor,
-  resolveColor,
-} from '../themes/color-utils.js';
+import { resolveColor } from '../themes/color-utils.js';
 
 function generateThemeItem(
   name: string,
   typeDisplay: string,
-  themeType: string,
-  themeBackground: string | undefined,
+  fullTheme: Theme | undefined,
   terminalBackgroundColor: string | undefined,
-  terminalThemeType: 'light' | 'dark' | undefined,
 ) {
-  const isCompatible =
-    themeType === 'custom' ||
-    terminalThemeType === undefined ||
-    themeType === 'ansi' ||
-    themeType === terminalThemeType;
+  const isCompatible = fullTheme
+    ? themeManager.isThemeCompatible(fullTheme, terminalBackgroundColor)
+    : true;
+
+  const themeBackground = fullTheme
+    ? resolveColor(fullTheme.colors.Background)
+    : undefined;
 
   const isBackgroundMatch =
     terminalBackgroundColor &&
@@ -111,26 +111,17 @@ export function ThemeDialog({
 
   const capitalize = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
 
-  const terminalThemeType = getThemeTypeFromBackgroundColor(
-    terminalBackgroundColor,
-  );
-
   // Generate theme items
   const themeItems = themeManager
     .getAvailableThemes()
     .map((theme) => {
       const fullTheme = themeManager.getTheme(theme.name);
-      const themeBackground = fullTheme
-        ? resolveColor(fullTheme.colors.Background)
-        : undefined;
 
       return generateThemeItem(
         theme.name,
         capitalize(theme.type),
-        theme.type,
-        themeBackground,
+        fullTheme,
         terminalBackgroundColor,
-        terminalThemeType,
       );
     })
     .sort((a, b) => {
@@ -149,8 +140,8 @@ export function ThemeDialog({
   const safeInitialThemeIndex = initialThemeIndex >= 0 ? initialThemeIndex : 0;
 
   const handleThemeSelect = useCallback(
-    (themeName: string) => {
-      onSelect(themeName, selectedScope);
+    async (themeName: string) => {
+      await onSelect(themeName, selectedScope);
       refreshStatic();
     },
     [onSelect, selectedScope, refreshStatic],
@@ -166,8 +157,8 @@ export function ThemeDialog({
   }, []);
 
   const handleScopeSelect = useCallback(
-    (scope: LoadableSettingScope) => {
-      onSelect(highlightedThemeName, scope);
+    async (scope: LoadableSettingScope) => {
+      await onSelect(highlightedThemeName, scope);
       refreshStatic();
     },
     [onSelect, highlightedThemeName, refreshStatic],
diff --git a/packages/cli/src/ui/components/__snapshots__/ThemeDialog.test.tsx.snap b/packages/cli/src/ui/components/__snapshots__/ThemeDialog.test.tsx.snap
index 86eb35c24d..ab402d263f 100644
--- a/packages/cli/src/ui/components/__snapshots__/ThemeDialog.test.tsx.snap
+++ b/packages/cli/src/ui/components/__snapshots__/ThemeDialog.test.tsx.snap
@@ -90,18 +90,18 @@ exports[`ThemeDialog Snapshots > should render correctly in theme selection mode
 │                                                                                                                      │
 │ > Select Theme                                        Preview                                                        │
 │ ▲                                                     ┌────────────────────────────────────────────────────────────┐ │
-│    1. ANSI Dark                                       │                                                            │ │
-│    2. ANSI Light Light                                │ 1 # function                                               │ │
-│    3. Atom One Dark                                   │ 2 def fibonacci(n):                                        │ │
-│    4. Ayu Dark                                        │ 3     a, b = 0, 1                                          │ │
-│    5. Ayu Light Light                                 │ 4     for _ in range(n):                                   │ │
-│ ●  6. Default Dark                                    │ 5         a, b = b, a + b                                  │ │
-│    7. Default Light Light                             │ 6     return a                                             │ │
-│    8. Dracula Dark                                    │                                                            │ │
-│    9. GitHub Dark                                     │ 1 - print("Hello, " + name)                                │ │
-│   10. GitHub Light Light                              │ 1 + print(f"Hello, {name}!")                               │ │
-│   11. Google Code Light                               │                                                            │ │
-│   12. Holiday Dark                                    └────────────────────────────────────────────────────────────┘ │
+│ ●  1. ANSI Dark (Matches terminal)                    │                                                            │ │
+│    2. Atom One Dark                                   │ 1 # function                                               │ │
+│    3. Ayu Dark                                        │ 2 def fibonacci(n):                                        │ │
+│    4. Default Dark                                    │ 3     a, b = 0, 1                                          │ │
+│    5. Dracula Dark                                    │ 4     for _ in range(n):                                   │ │
+│    6. GitHub Dark                                     │ 5         a, b = b, a + b                                  │ │
+│    7. Holiday Dark                                    │ 6     return a                                             │ │
+│    8. Shades Of Purple Dark                           │                                                            │ │
+│    9. ANSI Light Light (Incompatible)                 │ 1 - print("Hello, " + name)                                │ │
+│   10. Ayu Light Light (Incompatible)                  │ 1 + print(f"Hello, {name}!")                               │ │
+│   11. Default Light Light (Incompatible)              │                                                            │ │
+│   12. GitHub Light Light (Incompatible)               └────────────────────────────────────────────────────────────┘ │
 │ ▼                                                                                                                    │
 │                                                                                                                      │
 │ (Use Enter to select, Tab to configure scope, Esc to close)                                                          │
diff --git a/packages/cli/src/ui/components/shared/HalfLinePaddedBox.tsx b/packages/cli/src/ui/components/shared/HalfLinePaddedBox.tsx
index 0b15c58beb..add5353245 100644
--- a/packages/cli/src/ui/components/shared/HalfLinePaddedBox.tsx
+++ b/packages/cli/src/ui/components/shared/HalfLinePaddedBox.tsx
@@ -8,6 +8,7 @@ import type React from 'react';
 import { useMemo } from 'react';
 import { Box, Text, useIsScreenReaderEnabled } from 'ink';
 import { useUIState } from '../../contexts/UIStateContext.js';
+import { theme } from '../../semantic-colors.js';
 import {
   interpolateColor,
   resolveColor,
@@ -52,8 +53,8 @@ const HalfLinePaddedBoxInternal: React.FC<HalfLinePaddedBoxProps> = ({
   backgroundOpacity,
   children,
 }) => {
-  const { terminalWidth, terminalBackgroundColor } = useUIState();
-  const terminalBg = terminalBackgroundColor || 'black';
+  const { terminalWidth } = useUIState();
+  const terminalBg = theme.background.primary || 'black';
 
   const isLowColor = isLowColorDepth();
 
diff --git a/packages/cli/src/ui/contexts/TerminalContext.test.tsx b/packages/cli/src/ui/contexts/TerminalContext.test.tsx
index dc1ceca62e..509cd3c9c5 100644
--- a/packages/cli/src/ui/contexts/TerminalContext.test.tsx
+++ b/packages/cli/src/ui/contexts/TerminalContext.test.tsx
@@ -29,6 +29,11 @@ vi.mock('ink', () => ({
   useStdin: () => ({
     stdin: mockStdin,
   }),
+  useStdout: () => ({
+    stdout: {
+      write: vi.fn(),
+    },
+  }),
 }));
 
 const TestComponent = ({ onColor }: { onColor: (c: string) => void }) => {
diff --git a/packages/cli/src/ui/contexts/TerminalContext.tsx b/packages/cli/src/ui/contexts/TerminalContext.tsx
index e954029207..20d6b097ae 100644
--- a/packages/cli/src/ui/contexts/TerminalContext.tsx
+++ b/packages/cli/src/ui/contexts/TerminalContext.tsx
@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { useStdin } from 'ink';
+import { useStdin, useStdout } from 'ink';
 import type React from 'react';
 import {
   createContext,
@@ -20,6 +20,7 @@ export type TerminalEventHandler = (event: string) => void;
 interface TerminalContextValue {
   subscribe: (handler: TerminalEventHandler) => void;
   unsubscribe: (handler: TerminalEventHandler) => void;
+  queryTerminalBackground: () => Promise<void>;
 }
 
 const TerminalContext = createContext<TerminalContextValue | undefined>(
@@ -38,6 +39,7 @@ export function useTerminalContext() {
 
 export function TerminalProvider({ children }: { children: React.ReactNode }) {
   const { stdin } = useStdin();
+  const { stdout } = useStdout();
   const subscribers = useRef<Set<TerminalEventHandler>>(new Set()).current;
   const bufferRef = useRef('');
 
@@ -55,6 +57,23 @@ export function TerminalProvider({ children }: { children: React.ReactNode }) {
     [subscribers],
   );
 
+  const queryTerminalBackground = useCallback(
+    async () =>
+      new Promise<void>((resolve) => {
+        const handler = () => {
+          unsubscribe(handler);
+          resolve();
+        };
+        subscribe(handler);
+        TerminalCapabilityManager.queryBackgroundColor(stdout);
+        setTimeout(() => {
+          unsubscribe(handler);
+          resolve();
+        }, 100);
+      }),
+    [stdout, subscribe, unsubscribe],
+  );
+
   useEffect(() => {
     const handleData = (data: Buffer | string) => {
       bufferRef.current +=
@@ -89,7 +108,9 @@ export function TerminalProvider({ children }: { children: React.ReactNode }) {
   }, [stdin, subscribers]);
 
   return (
-    <TerminalContext.Provider value={{ subscribe, unsubscribe }}>
+    <TerminalContext.Provider
+      value={{ subscribe, unsubscribe, queryTerminalBackground }}
+    >
       {children}
     </TerminalContext.Provider>
   );
diff --git a/packages/cli/src/ui/contexts/UIActionsContext.tsx b/packages/cli/src/ui/contexts/UIActionsContext.tsx
index 0fb98c34ff..c80507f9d7 100644
--- a/packages/cli/src/ui/contexts/UIActionsContext.tsx
+++ b/packages/cli/src/ui/contexts/UIActionsContext.tsx
@@ -20,7 +20,10 @@ import type { SessionInfo } from '../../utils/sessionUtils.js';
 import { type NewAgentsChoice } from '../components/NewAgentsNotification.js';
 
 export interface UIActions {
-  handleThemeSelect: (themeName: string, scope: LoadableSettingScope) => void;
+  handleThemeSelect: (
+    themeName: string,
+    scope: LoadableSettingScope,
+  ) => Promise<void>;
   closeThemeDialog: () => void;
   handleThemeHighlight: (themeName: string | undefined) => void;
   handleAuthSelect: (
diff --git a/packages/cli/src/ui/hooks/useSnowfall.test.tsx b/packages/cli/src/ui/hooks/useSnowfall.test.tsx
index 004af733ca..321da83090 100644
--- a/packages/cli/src/ui/hooks/useSnowfall.test.tsx
+++ b/packages/cli/src/ui/hooks/useSnowfall.test.tsx
@@ -16,7 +16,11 @@ import type { UIState } from '../contexts/UIStateContext.js';
 vi.mock('../themes/theme-manager.js', () => ({
   themeManager: {
     getActiveTheme: vi.fn(),
+    setTerminalBackground: vi.fn(),
+    getAllThemes: vi.fn(() => []),
+    setActiveTheme: vi.fn(),
   },
+  DEFAULT_THEME: { name: 'Default' },
 }));
 
 vi.mock('../themes/holiday.js', () => ({
diff --git a/packages/cli/src/ui/hooks/useTerminalTheme.test.tsx b/packages/cli/src/ui/hooks/useTerminalTheme.test.tsx
index da2a9b2c04..21eabba6cc 100644
--- a/packages/cli/src/ui/hooks/useTerminalTheme.test.tsx
+++ b/packages/cli/src/ui/hooks/useTerminalTheme.test.tsx
@@ -15,6 +15,7 @@ const mockWrite = vi.fn();
 const mockSubscribe = vi.fn();
 const mockUnsubscribe = vi.fn();
 const mockHandleThemeSelect = vi.fn();
+const mockQueryTerminalBackground = vi.fn();
 
 vi.mock('ink', async () => ({
   useStdout: () => ({
@@ -28,6 +29,7 @@ vi.mock('../contexts/TerminalContext.js', () => ({
   useTerminalContext: () => ({
     subscribe: mockSubscribe,
     unsubscribe: mockUnsubscribe,
+    queryTerminalBackground: mockQueryTerminalBackground,
   }),
 }));
 
@@ -52,6 +54,7 @@ vi.mock('../themes/theme-manager.js', async () => {
     themeManager: {
       isDefaultTheme: (name: string) =>
         name === 'default' || name === 'default-light',
+      setTerminalBackground: vi.fn(),
     },
     DEFAULT_THEME: { name: 'default' },
   };
@@ -78,6 +81,7 @@ describe('useTerminalTheme', () => {
     mockSubscribe.mockClear();
     mockUnsubscribe.mockClear();
     mockHandleThemeSelect.mockClear();
+    mockQueryTerminalBackground.mockClear();
     // Reset any settings modifications
     mockSettings.merged.ui.autoThemeSwitching = true;
     mockSettings.merged.ui.theme = 'default';
@@ -89,37 +93,37 @@ describe('useTerminalTheme', () => {
   });
 
   it('should subscribe to terminal background events on mount', () => {
-    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config));
+    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config, vi.fn()));
     expect(mockSubscribe).toHaveBeenCalled();
   });
 
   it('should unsubscribe on unmount', () => {
     const { unmount } = renderHook(() =>
-      useTerminalTheme(mockHandleThemeSelect, config),
+      useTerminalTheme(mockHandleThemeSelect, config, vi.fn()),
     );
     unmount();
     expect(mockUnsubscribe).toHaveBeenCalled();
   });
 
   it('should poll for terminal background', () => {
-    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config));
+    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config, vi.fn()));
 
     // Fast-forward time (1 minute)
     vi.advanceTimersByTime(60000);
-    expect(mockWrite).toHaveBeenCalledWith('\x1b]11;?\x1b\\');
+    expect(mockQueryTerminalBackground).toHaveBeenCalled();
   });
 
   it('should not poll if terminal background is undefined at startup', () => {
     config.getTerminalBackground = vi.fn().mockReturnValue(undefined);
-    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config));
+    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config, vi.fn()));
 
     // Poll should not happen
     vi.advanceTimersByTime(60000);
-    expect(mockWrite).not.toHaveBeenCalled();
+    expect(mockQueryTerminalBackground).not.toHaveBeenCalled();
   });
 
   it('should switch to light theme when background is light', () => {
-    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config));
+    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config, vi.fn()));
 
     const handler = mockSubscribe.mock.calls[0][0];
 
@@ -137,7 +141,7 @@ describe('useTerminalTheme', () => {
     // Start with light theme
     mockSettings.merged.ui.theme = 'default-light';
 
-    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config));
+    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config, vi.fn()));
 
     const handler = mockSubscribe.mock.calls[0][0];
 
@@ -156,11 +160,11 @@ describe('useTerminalTheme', () => {
 
   it('should not switch theme if autoThemeSwitching is disabled', () => {
     mockSettings.merged.ui.autoThemeSwitching = false;
-    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config));
+    renderHook(() => useTerminalTheme(mockHandleThemeSelect, config, vi.fn()));
 
     // Poll should not happen
     vi.advanceTimersByTime(60000);
-    expect(mockWrite).not.toHaveBeenCalled();
+    expect(mockQueryTerminalBackground).not.toHaveBeenCalled();
 
     mockSettings.merged.ui.autoThemeSwitching = true;
   });
diff --git a/packages/cli/src/ui/hooks/useTerminalTheme.ts b/packages/cli/src/ui/hooks/useTerminalTheme.ts
index 69292616fd..b3ac7522bc 100644
--- a/packages/cli/src/ui/hooks/useTerminalTheme.ts
+++ b/packages/cli/src/ui/hooks/useTerminalTheme.ts
@@ -5,7 +5,6 @@
  */
 
 import { useEffect } from 'react';
-import { useStdout } from 'ink';
 import {
   getLuminance,
   parseColor,
@@ -22,10 +21,11 @@ import type { UIActions } from '../contexts/UIActionsContext.js';
 export function useTerminalTheme(
   handleThemeSelect: UIActions['handleThemeSelect'],
   config: Config,
+  refreshStatic: () => void,
 ) {
-  const { stdout } = useStdout();
   const settings = useSettings();
-  const { subscribe, unsubscribe } = useTerminalContext();
+  const { subscribe, unsubscribe, queryTerminalBackground } =
+    useTerminalContext();
 
   useEffect(() => {
     if (settings.merged.ui.autoThemeSwitching === false) {
@@ -44,7 +44,7 @@ export function useTerminalTheme(
         return;
       }
 
-      stdout.write('\x1b]11;?\x1b\\');
+      void queryTerminalBackground();
     }, settings.merged.ui.terminalBackgroundPollingInterval * 1000);
 
     const handleTerminalBackground = (colorStr: string) => {
@@ -58,6 +58,8 @@ export function useTerminalTheme(
       const hexColor = parseColor(match[1], match[2], match[3]);
       const luminance = getLuminance(hexColor);
       config.setTerminalBackground(hexColor);
+      themeManager.setTerminalBackground(hexColor);
+      refreshStatic();
 
       const currentThemeName = settings.merged.ui.theme;
 
@@ -69,7 +71,7 @@ export function useTerminalTheme(
       );
 
       if (newTheme) {
-        handleThemeSelect(newTheme, SettingScope.User);
+        void handleThemeSelect(newTheme, SettingScope.User);
       }
     };
 
@@ -83,10 +85,11 @@ export function useTerminalTheme(
     settings.merged.ui.theme,
     settings.merged.ui.autoThemeSwitching,
     settings.merged.ui.terminalBackgroundPollingInterval,
-    stdout,
     config,
     handleThemeSelect,
     subscribe,
     unsubscribe,
+    queryTerminalBackground,
+    refreshStatic,
   ]);
 }
diff --git a/packages/cli/src/ui/hooks/useThemeCommand.ts b/packages/cli/src/ui/hooks/useThemeCommand.ts
index 790019db15..d1d17da428 100644
--- a/packages/cli/src/ui/hooks/useThemeCommand.ts
+++ b/packages/cli/src/ui/hooks/useThemeCommand.ts
@@ -13,12 +13,16 @@ import type {
 import { MessageType } from '../types.js';
 import process from 'node:process';
 import type { UseHistoryManagerReturn } from './useHistoryManager.js';
+import { useTerminalContext } from '../contexts/TerminalContext.js';
 
 interface UseThemeCommandReturn {
   isThemeDialogOpen: boolean;
   openThemeDialog: () => void;
   closeThemeDialog: () => void;
-  handleThemeSelect: (themeName: string, scope: LoadableSettingScope) => void;
+  handleThemeSelect: (
+    themeName: string,
+    scope: LoadableSettingScope,
+  ) => Promise<void>;
   handleThemeHighlight: (themeName: string | undefined) => void;
 }
 
@@ -30,8 +34,9 @@ export const useThemeCommand = (
 ): UseThemeCommandReturn => {
   const [isThemeDialogOpen, setIsThemeDialogOpen] =
     useState(!!initialThemeError);
+  const { queryTerminalBackground } = useTerminalContext();
 
-  const openThemeDialog = useCallback(() => {
+  const openThemeDialog = useCallback(async () => {
     if (process.env['NO_COLOR']) {
       addItem(
         {
@@ -42,8 +47,14 @@ export const useThemeCommand = (
       );
       return;
     }
+
+    // Ensure we have an up to date terminal background color when opening the
+    // theme dialog as the user may have just changed it before opening the
+    // dialog.
+    await queryTerminalBackground();
+
     setIsThemeDialogOpen(true);
-  }, [addItem]);
+  }, [addItem, queryTerminalBackground]);
 
   const applyTheme = useCallback(
     (themeName: string | undefined) => {
@@ -72,7 +83,7 @@ export const useThemeCommand = (
   }, [applyTheme, loadedSettings]);
 
   const handleThemeSelect = useCallback(
-    (themeName: string, scope: LoadableSettingScope) => {
+    async (themeName: string, scope: LoadableSettingScope) => {
       try {
         const mergedCustomThemes = {
           ...(loadedSettings.user.settings.ui?.customThemes || {}),
diff --git a/packages/cli/src/ui/themes/color-utils.ts b/packages/cli/src/ui/themes/color-utils.ts
index ecfec6ab08..476703a7fc 100644
--- a/packages/cli/src/ui/themes/color-utils.ts
+++ b/packages/cli/src/ui/themes/color-utils.ts
@@ -6,149 +6,7 @@
 
 import { debugLogger } from '@google/gemini-cli-core';
 import tinygradient from 'tinygradient';
-
-// Mapping from common CSS color names (lowercase) to hex codes (lowercase)
-// Excludes names directly supported by Ink
-export const CSS_NAME_TO_HEX_MAP: Readonly<Record<string, string>> = {
-  aliceblue: '#f0f8ff',
-  antiquewhite: '#faebd7',
-  aqua: '#00ffff',
-  aquamarine: '#7fffd4',
-  azure: '#f0ffff',
-  beige: '#f5f5dc',
-  bisque: '#ffe4c4',
-  blanchedalmond: '#ffebcd',
-  blueviolet: '#8a2be2',
-  brown: '#a52a2a',
-  burlywood: '#deb887',
-  cadetblue: '#5f9ea0',
-  chartreuse: '#7fff00',
-  chocolate: '#d2691e',
-  coral: '#ff7f50',
-  cornflowerblue: '#6495ed',
-  cornsilk: '#fff8dc',
-  crimson: '#dc143c',
-  darkblue: '#00008b',
-  darkcyan: '#008b8b',
-  darkgoldenrod: '#b8860b',
-  darkgray: '#a9a9a9',
-  darkgrey: '#a9a9a9',
-  darkgreen: '#006400',
-  darkkhaki: '#bdb76b',
-  darkmagenta: '#8b008b',
-  darkolivegreen: '#556b2f',
-  darkorange: '#ff8c00',
-  darkorchid: '#9932cc',
-  darkred: '#8b0000',
-  darksalmon: '#e9967a',
-  darkseagreen: '#8fbc8f',
-  darkslateblue: '#483d8b',
-  darkslategray: '#2f4f4f',
-  darkslategrey: '#2f4f4f',
-  darkturquoise: '#00ced1',
-  darkviolet: '#9400d3',
-  deeppink: '#ff1493',
-  deepskyblue: '#00bfff',
-  dimgray: '#696969',
-  dimgrey: '#696969',
-  dodgerblue: '#1e90ff',
-  firebrick: '#b22222',
-  floralwhite: '#fffaf0',
-  forestgreen: '#228b22',
-  fuchsia: '#ff00ff',
-  gainsboro: '#dcdcdc',
-  ghostwhite: '#f8f8ff',
-  gold: '#ffd700',
-  goldenrod: '#daa520',
-  greenyellow: '#adff2f',
-  honeydew: '#f0fff0',
-  hotpink: '#ff69b4',
-  indianred: '#cd5c5c',
-  indigo: '#4b0082',
-  ivory: '#fffff0',
-  khaki: '#f0e68c',
-  lavender: '#e6e6fa',
-  lavenderblush: '#fff0f5',
-  lawngreen: '#7cfc00',
-  lemonchiffon: '#fffacd',
-  lightblue: '#add8e6',
-  lightcoral: '#f08080',
-  lightcyan: '#e0ffff',
-  lightgoldenrodyellow: '#fafad2',
-  lightgray: '#d3d3d3',
-  lightgrey: '#d3d3d3',
-  lightgreen: '#90ee90',
-  lightpink: '#ffb6c1',
-  lightsalmon: '#ffa07a',
-  lightseagreen: '#20b2aa',
-  lightskyblue: '#87cefa',
-  lightslategray: '#778899',
-  lightslategrey: '#778899',
-  lightsteelblue: '#b0c4de',
-  lightyellow: '#ffffe0',
-  lime: '#00ff00',
-  limegreen: '#32cd32',
-  linen: '#faf0e6',
-  maroon: '#800000',
-  mediumaquamarine: '#66cdaa',
-  mediumblue: '#0000cd',
-  mediumorchid: '#ba55d3',
-  mediumpurple: '#9370db',
-  mediumseagreen: '#3cb371',
-  mediumslateblue: '#7b68ee',
-  mediumspringgreen: '#00fa9a',
-  mediumturquoise: '#48d1cc',
-  mediumvioletred: '#c71585',
-  midnightblue: '#191970',
-  mintcream: '#f5fffa',
-  mistyrose: '#ffe4e1',
-  moccasin: '#ffe4b5',
-  navajowhite: '#ffdead',
-  navy: '#000080',
-  oldlace: '#fdf5e6',
-  olive: '#808000',
-  olivedrab: '#6b8e23',
-  orange: '#ffa500',
-  orangered: '#ff4500',
-  orchid: '#da70d6',
-  palegoldenrod: '#eee8aa',
-  palegreen: '#98fb98',
-  paleturquoise: '#afeeee',
-  palevioletred: '#db7093',
-  papayawhip: '#ffefd5',
-  peachpuff: '#ffdab9',
-  peru: '#cd853f',
-  pink: '#ffc0cb',
-  plum: '#dda0dd',
-  powderblue: '#b0e0e6',
-  purple: '#800080',
-  rebeccapurple: '#663399',
-  rosybrown: '#bc8f8f',
-  royalblue: '#4169e1',
-  saddlebrown: '#8b4513',
-  salmon: '#fa8072',
-  sandybrown: '#f4a460',
-  seagreen: '#2e8b57',
-  seashell: '#fff5ee',
-  sienna: '#a0522d',
-  silver: '#c0c0c0',
-  skyblue: '#87ceeb',
-  slateblue: '#6a5acd',
-  slategray: '#708090',
-  slategrey: '#708090',
-  snow: '#fffafa',
-  springgreen: '#00ff7f',
-  steelblue: '#4682b4',
-  tan: '#d2b48c',
-  teal: '#008080',
-  thistle: '#d8bfd8',
-  tomato: '#ff6347',
-  turquoise: '#40e0d0',
-  violet: '#ee82ee',
-  wheat: '#f5deb3',
-  whitesmoke: '#f5f5f5',
-  yellowgreen: '#9acd32',
-};
+import tinycolor from 'tinycolor2';
 
 // Define the set of Ink's named colors for quick lookup
 export const INK_SUPPORTED_NAMES = new Set([
@@ -172,6 +30,13 @@ export const INK_SUPPORTED_NAMES = new Set([
   'whitebright',
 ]);
 
+// Use tinycolor's built-in names map for CSS colors, excluding ones Ink supports
+export const CSS_NAME_TO_HEX_MAP = Object.fromEntries(
+  Object.entries(tinycolor.names)
+    .filter(([name]) => !INK_SUPPORTED_NAMES.has(name))
+    .map(([name, hex]) => [name, `#${hex}`]),
+);
+
 /**
  * Checks if a color string is valid (hex, Ink-supported color name, or CSS color name).
  * This function uses the same validation logic as the Theme class's _resolveColor method
@@ -217,12 +82,19 @@ export function resolveColor(colorValue: string): string | undefined {
       return undefined;
     }
   }
+
+  // Handle hex codes without #
+  if (/^[0-9A-Fa-f]{3}([0-9A-Fa-f]{3})?$/.test(colorValue)) {
+    return `#${lowerColor}`;
+  }
+
   // 2. Check if it's an Ink supported name (lowercase)
-  else if (INK_SUPPORTED_NAMES.has(lowerColor)) {
+  if (INK_SUPPORTED_NAMES.has(lowerColor)) {
     return lowerColor; // Use Ink name directly
   }
+
   // 3. Check if it's a known CSS name we can map to hex
-  else if (CSS_NAME_TO_HEX_MAP[lowerColor]) {
+  if (CSS_NAME_TO_HEX_MAP[lowerColor]) {
     return CSS_NAME_TO_HEX_MAP[lowerColor]; // Use mapped hex
   }
 
@@ -286,27 +158,45 @@ export function getThemeTypeFromBackgroundColor(
     return undefined;
   }
 
-  const luminance = getLuminance(backgroundColor);
+  const resolvedColor = resolveColor(backgroundColor);
+  if (!resolvedColor) {
+    return undefined;
+  }
+
+  const luminance = getLuminance(resolvedColor);
   return luminance > 128 ? 'light' : 'dark';
 }
 
+// Mapping for ANSI bright colors that are not in tinycolor's standard CSS names
+export const INK_NAME_TO_HEX_MAP: Readonly<Record<string, string>> = {
+  blackbright: '#555555',
+  redbright: '#ff5555',
+  greenbright: '#55ff55',
+  yellowbright: '#ffff55',
+  bluebright: '#5555ff',
+  magentabright: '#ff55ff',
+  cyanbright: '#55ffff',
+  whitebright: '#ffffff',
+};
+
 /**
  * Calculates the relative luminance of a color.
  * See https://www.w3.org/TR/WCAG20/#relativeluminancedef
  *
- * @param backgroundColor Hex color string (with or without #)
+ * @param color Color string (hex or Ink-supported name)
  * @returns Luminance value (0-255)
  */
-export function getLuminance(backgroundColor: string): number {
-  let hex = backgroundColor.replace(/^#/, '');
-  if (hex.length === 3) {
-    hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
-  }
-  const r = parseInt(hex.substring(0, 2), 16);
-  const g = parseInt(hex.substring(2, 4), 16);
-  const b = parseInt(hex.substring(4, 6), 16);
+export function getLuminance(color: string): number {
+  const resolved = color.toLowerCase();
+  const hex = INK_NAME_TO_HEX_MAP[resolved] || resolved;
 
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  const colorObj = tinycolor(hex);
+  if (!colorObj.isValid()) {
+    return 0;
+  }
+
+  // tinycolor returns 0-1, we need 0-255
+  return colorObj.getLuminance() * 255;
 }
 
 // Hysteresis thresholds to prevent flickering when the background color
diff --git a/packages/cli/src/ui/themes/theme-manager.test.ts b/packages/cli/src/ui/themes/theme-manager.test.ts
index e80c03c5e1..40f55ec860 100644
--- a/packages/cli/src/ui/themes/theme-manager.test.ts
+++ b/packages/cli/src/ui/themes/theme-manager.test.ts
@@ -59,6 +59,7 @@ describe('ThemeManager', () => {
     // Reset themeManager state
     themeManager.loadCustomThemes({});
     themeManager.setActiveTheme(DEFAULT_THEME.name);
+    themeManager.setTerminalBackground(undefined);
   });
 
   afterEach(() => {
@@ -238,4 +239,114 @@ describe('ThemeManager', () => {
       expect(themeManager.isCustomTheme('SettingsTheme')).toBe(true);
     });
   });
+
+  describe('terminalBackground override', () => {
+    it('should store and retrieve terminal background', () => {
+      themeManager.setTerminalBackground('#123456');
+      expect(themeManager.getTerminalBackground()).toBe('#123456');
+      themeManager.setTerminalBackground(undefined);
+      expect(themeManager.getTerminalBackground()).toBeUndefined();
+    });
+
+    it('should override background.primary in semantic colors when terminal background is set', () => {
+      const color = '#1a1a1a';
+      themeManager.setTerminalBackground(color);
+      const semanticColors = themeManager.getSemanticColors();
+      expect(semanticColors.background.primary).toBe(color);
+    });
+
+    it('should override Background in colors when terminal background is set', () => {
+      const color = '#1a1a1a';
+      themeManager.setTerminalBackground(color);
+      const colors = themeManager.getColors();
+      expect(colors.Background).toBe(color);
+    });
+
+    it('should re-calculate dependent semantic colors when terminal background is set', () => {
+      themeManager.setTerminalBackground('#000000');
+      const semanticColors = themeManager.getSemanticColors();
+
+      // border.default should be interpolated from background (#000000) and Gray
+      // ui.dark should be interpolated from Gray and background (#000000)
+      expect(semanticColors.border.default).toBeDefined();
+      expect(semanticColors.ui.dark).toBeDefined();
+      expect(semanticColors.border.default).not.toBe(
+        DEFAULT_THEME.semanticColors.border.default,
+      );
+    });
+
+    it('should return original semantic colors when terminal background is NOT set', () => {
+      themeManager.setTerminalBackground(undefined);
+      const semanticColors = themeManager.getSemanticColors();
+      expect(semanticColors).toEqual(DEFAULT_THEME.semanticColors);
+    });
+
+    it('should NOT override background when theme is incompatible (Light theme on Dark terminal)', () => {
+      themeManager.setActiveTheme('Default Light');
+      const darkTerminalBg = '#000000';
+      themeManager.setTerminalBackground(darkTerminalBg);
+
+      const semanticColors = themeManager.getSemanticColors();
+      expect(semanticColors.background.primary).toBe(
+        themeManager.getTheme('Default Light')!.colors.Background,
+      );
+
+      const colors = themeManager.getColors();
+      expect(colors.Background).toBe(
+        themeManager.getTheme('Default Light')!.colors.Background,
+      );
+    });
+
+    it('should NOT override background when theme is incompatible (Dark theme on Light terminal)', () => {
+      themeManager.setActiveTheme('Default');
+      const lightTerminalBg = '#FFFFFF';
+      themeManager.setTerminalBackground(lightTerminalBg);
+
+      const semanticColors = themeManager.getSemanticColors();
+      expect(semanticColors.background.primary).toBe(
+        themeManager.getTheme('Default')!.colors.Background,
+      );
+
+      const colors = themeManager.getColors();
+      expect(colors.Background).toBe(
+        themeManager.getTheme('Default')!.colors.Background,
+      );
+    });
+
+    it('should override background for custom theme when compatible', () => {
+      themeManager.loadCustomThemes({
+        MyDark: {
+          name: 'MyDark',
+          type: 'custom',
+          Background: '#000000',
+          Foreground: '#ffffff',
+        },
+      });
+      themeManager.setActiveTheme('MyDark');
+
+      const darkTerminalBg = '#1a1a1a';
+      themeManager.setTerminalBackground(darkTerminalBg);
+
+      const semanticColors = themeManager.getSemanticColors();
+      expect(semanticColors.background.primary).toBe(darkTerminalBg);
+    });
+
+    it('should NOT override background for custom theme when incompatible', () => {
+      themeManager.loadCustomThemes({
+        MyLight: {
+          name: 'MyLight',
+          type: 'custom',
+          Background: '#ffffff',
+          Foreground: '#000000',
+        },
+      });
+      themeManager.setActiveTheme('MyLight');
+
+      const darkTerminalBg = '#000000';
+      themeManager.setTerminalBackground(darkTerminalBg);
+
+      const semanticColors = themeManager.getSemanticColors();
+      expect(semanticColors.background.primary).toBe('#ffffff');
+    });
+  });
 });
diff --git a/packages/cli/src/ui/themes/theme-manager.ts b/packages/cli/src/ui/themes/theme-manager.ts
index 7452d093f8..3ee4d5af1a 100644
--- a/packages/cli/src/ui/themes/theme-manager.ts
+++ b/packages/cli/src/ui/themes/theme-manager.ts
@@ -18,10 +18,16 @@ import { ShadesOfPurple } from './shades-of-purple.js';
 import { XCode } from './xcode.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import type { Theme, ThemeType } from './theme.js';
+import type { Theme, ThemeType, ColorsTheme } from './theme.js';
 import type { CustomTheme } from '@google/gemini-cli-core';
 import { createCustomTheme, validateCustomTheme } from './theme.js';
 import type { SemanticColors } from './semantic-tokens.js';
+import {
+  interpolateColor,
+  getThemeTypeFromBackgroundColor,
+  resolveColor,
+} from './color-utils.js';
+import { DEFAULT_BORDER_OPACITY } from '../constants.js';
 import { ANSI } from './ansi.js';
 import { ANSILight } from './ansi-light.js';
 import { NoColorTheme } from './no-color.js';
@@ -42,6 +48,12 @@ class ThemeManager {
   private settingsThemes: Map<string, Theme> = new Map();
   private extensionThemes: Map<string, Theme> = new Map();
   private fileThemes: Map<string, Theme> = new Map();
+  private terminalBackground: string | undefined;
+
+  // Cache for dynamic colors
+  private cachedColors: ColorsTheme | undefined;
+  private cachedSemanticColors: SemanticColors | undefined;
+  private lastCacheKey: string | undefined;
 
   constructor() {
     this.availableThemes = [
@@ -63,6 +75,23 @@ class ThemeManager {
     this.activeTheme = DEFAULT_THEME;
   }
 
+  setTerminalBackground(color: string | undefined): void {
+    if (this.terminalBackground !== color) {
+      this.terminalBackground = color;
+      this.clearCache();
+    }
+  }
+
+  getTerminalBackground(): string | undefined {
+    return this.terminalBackground;
+  }
+
+  private clearCache(): void {
+    this.cachedColors = undefined;
+    this.cachedSemanticColors = undefined;
+    this.lastCacheKey = undefined;
+  }
+
   isDefaultTheme(themeName: string | undefined): boolean {
     return (
       themeName === undefined ||
@@ -214,7 +243,10 @@ class ThemeManager {
     if (!theme) {
       return false;
     }
-    this.activeTheme = theme;
+    if (this.activeTheme !== theme) {
+      this.activeTheme = theme;
+      this.clearCache();
+    }
     return true;
   }
 
@@ -255,12 +287,104 @@ class ThemeManager {
     return this.activeTheme;
   }
 
+  /**
+   * Gets the colors for the active theme, respecting the terminal background.
+   * @returns The theme colors.
+   */
+  getColors(): ColorsTheme {
+    const activeTheme = this.getActiveTheme();
+    const cacheKey = `${activeTheme.name}:${this.terminalBackground}`;
+    if (this.cachedColors && this.lastCacheKey === cacheKey) {
+      return this.cachedColors;
+    }
+
+    const colors = activeTheme.colors;
+    if (
+      this.terminalBackground &&
+      this.isThemeCompatible(activeTheme, this.terminalBackground)
+    ) {
+      this.cachedColors = {
+        ...colors,
+        Background: this.terminalBackground,
+        DarkGray: interpolateColor(colors.Gray, this.terminalBackground, 0.5),
+      };
+    } else {
+      this.cachedColors = colors;
+    }
+
+    this.lastCacheKey = cacheKey;
+    return this.cachedColors;
+  }
+
   /**
    * Gets the semantic colors for the active theme.
    * @returns The semantic colors.
    */
   getSemanticColors(): SemanticColors {
-    return this.getActiveTheme().semanticColors;
+    const activeTheme = this.getActiveTheme();
+    const cacheKey = `${activeTheme.name}:${this.terminalBackground}`;
+    if (this.cachedSemanticColors && this.lastCacheKey === cacheKey) {
+      return this.cachedSemanticColors;
+    }
+
+    const semanticColors = activeTheme.semanticColors;
+    if (
+      this.terminalBackground &&
+      this.isThemeCompatible(activeTheme, this.terminalBackground)
+    ) {
+      this.cachedSemanticColors = {
+        ...semanticColors,
+        background: {
+          ...semanticColors.background,
+          primary: this.terminalBackground,
+        },
+        border: {
+          ...semanticColors.border,
+          default: interpolateColor(
+            this.terminalBackground,
+            activeTheme.colors.Gray,
+            DEFAULT_BORDER_OPACITY,
+          ),
+        },
+        ui: {
+          ...semanticColors.ui,
+          dark: interpolateColor(
+            activeTheme.colors.Gray,
+            this.terminalBackground,
+            0.5,
+          ),
+        },
+      };
+    } else {
+      this.cachedSemanticColors = semanticColors;
+    }
+
+    this.lastCacheKey = cacheKey;
+    return this.cachedSemanticColors;
+  }
+
+  isThemeCompatible(
+    activeTheme: Theme,
+    terminalBackground: string | undefined,
+  ): boolean {
+    if (activeTheme.type === 'ansi') {
+      return true;
+    }
+
+    const backgroundType = getThemeTypeFromBackgroundColor(terminalBackground);
+    if (!backgroundType) {
+      return true;
+    }
+
+    const themeType =
+      activeTheme.type === 'custom'
+        ? getThemeTypeFromBackgroundColor(
+            resolveColor(activeTheme.colors.Background) ||
+              activeTheme.colors.Background,
+          )
+        : activeTheme.type;
+
+    return themeType === backgroundType;
   }
 
   private _getAllCustomThemes(): Theme[] {
diff --git a/packages/cli/src/ui/utils/terminalCapabilityManager.ts b/packages/cli/src/ui/utils/terminalCapabilityManager.ts
index 8fa2146072..447c79ce91 100644
--- a/packages/cli/src/ui/utils/terminalCapabilityManager.ts
+++ b/packages/cli/src/ui/utils/terminalCapabilityManager.ts
@@ -44,6 +44,16 @@ export class TerminalCapabilityManager {
   private static readonly DEVICE_ATTRIBUTES_QUERY = '\x1b[c';
   private static readonly MODIFY_OTHER_KEYS_QUERY = '\x1b[>4;?m';
 
+  /**
+   * Triggers a terminal background color query.
+   * @param stdout The stdout stream to write to.
+   */
+  static queryBackgroundColor(stdout: {
+    write: (data: string) => void | boolean;
+  }): void {
+    stdout.write(TerminalCapabilityManager.OSC_11_QUERY);
+  }
+
   // Kitty keyboard flags: CSI ? flags u
   // eslint-disable-next-line no-control-regex
   private static readonly KITTY_REGEX = /\x1b\[\?(\d+)u/;
@@ -56,7 +66,7 @@ export class TerminalCapabilityManager {
   // OSC 11 response: OSC 11 ; rgb:rrrr/gggg/bbbb ST (or BEL)
   static readonly OSC_11_REGEX =
     // eslint-disable-next-line no-control-regex
-    /\x1b\]11;rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})(\x1b\\|\x07)?/;
+    /\x1b\]11;rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})(\x1b\\|\x07)/;
   // modifyOtherKeys response: CSI > 4 ; level m
   // eslint-disable-next-line no-control-regex
   private static readonly MODIFY_OTHER_KEYS_REGEX = /\x1b\[>4;(\d+)m/;
diff --git a/packages/cli/src/utils/terminalTheme.ts b/packages/cli/src/utils/terminalTheme.ts
index 7707d24a8c..72315d3fa5 100644
--- a/packages/cli/src/utils/terminalTheme.ts
+++ b/packages/cli/src/utils/terminalTheme.ts
@@ -54,18 +54,17 @@ export async function setupTerminalAndTheme(
   }
 
   config.setTerminalBackground(terminalBackground);
+  themeManager.setTerminalBackground(terminalBackground);
 
   if (terminalBackground !== undefined) {
     const currentTheme = themeManager.getActiveTheme();
-    if (currentTheme.type !== 'ansi' && currentTheme.type !== 'custom') {
+    if (!themeManager.isThemeCompatible(currentTheme, terminalBackground)) {
       const backgroundType =
         getThemeTypeFromBackgroundColor(terminalBackground);
-      if (backgroundType && currentTheme.type !== backgroundType) {
-        coreEvents.emitFeedback(
-          'warning',
-          `Theme '${currentTheme.name}' (${currentTheme.type}) might look incorrect on your ${backgroundType} terminal background. Type /theme to change theme.`,
-        );
-      }
+      coreEvents.emitFeedback(
+        'warning',
+        `Theme '${currentTheme.name}' (${currentTheme.type}) might look incorrect on your ${backgroundType} terminal background. Type /theme to change theme.`,
+      );
     }
   }
 

From 991b2c60022a074ea8c19a71e93782b22e18191c Mon Sep 17 00:00:00 2001
From: christine betts <chrstn@uw.edu>
Date: Thu, 12 Feb 2026 15:50:41 -0500
Subject: [PATCH 29/44] Add generic searchable list to back settings and
 extensions (#18838)

---
 .../cli/src/ui/components/SettingsDialog.tsx  | 122 +----------
 .../components/shared/BaseSettingsDialog.tsx  |  47 +++--
 .../components/shared/SearchableList.test.tsx | 156 +++++++++++++++
 .../ui/components/shared/SearchableList.tsx   | 189 ++++++++++++++++++
 packages/cli/src/ui/hooks/useFuzzyList.ts     | 151 ++++++++++++++
 5 files changed, 532 insertions(+), 133 deletions(-)
 create mode 100644 packages/cli/src/ui/components/shared/SearchableList.test.tsx
 create mode 100644 packages/cli/src/ui/components/shared/SearchableList.tsx
 create mode 100644 packages/cli/src/ui/hooks/useFuzzyList.ts

diff --git a/packages/cli/src/ui/components/SettingsDialog.tsx b/packages/cli/src/ui/components/SettingsDialog.tsx
index fe3acbd1f1..2bfbe7a9fa 100644
--- a/packages/cli/src/ui/components/SettingsDialog.tsx
+++ b/packages/cli/src/ui/components/SettingsDialog.tsx
@@ -7,7 +7,6 @@
 import type React from 'react';
 import { useState, useEffect, useMemo, useCallback } from 'react';
 import { Text } from 'ink';
-import { AsyncFzf } from 'fzf';
 import type { Key } from '../hooks/useKeypress.js';
 import { theme } from '../semantic-colors.js';
 import type {
@@ -32,27 +31,17 @@ import {
   getEffectiveValue,
 } from '../../utils/settingsUtils.js';
 import { useVimMode } from '../contexts/VimModeContext.js';
-import { getCachedStringWidth } from '../utils/textUtils.js';
 import {
   type SettingsValue,
   TOGGLE_TYPES,
 } from '../../config/settingsSchema.js';
 import { coreEvents, debugLogger } from '@google/gemini-cli-core';
 import type { Config } from '@google/gemini-cli-core';
-import { useUIState } from '../contexts/UIStateContext.js';
-import { useTextBuffer } from './shared/text-buffer.js';
 import {
-  BaseSettingsDialog,
   type SettingsDialogItem,
+  BaseSettingsDialog,
 } from './shared/BaseSettingsDialog.js';
-
-interface FzfResult {
-  item: string;
-  start: number;
-  end: number;
-  score: number;
-  positions?: number[];
-}
+import { useFuzzyList } from '../hooks/useFuzzyList.js';
 
 interface SettingsDialogProps {
   settings: LoadedSettings;
@@ -81,60 +70,6 @@ export function SettingsDialog({
 
   const [showRestartPrompt, setShowRestartPrompt] = useState(false);
 
-  // Search state
-  const [searchQuery, setSearchQuery] = useState('');
-  const [filteredKeys, setFilteredKeys] = useState<string[]>(() =>
-    getDialogSettingKeys(),
-  );
-  const { fzfInstance, searchMap } = useMemo(() => {
-    const keys = getDialogSettingKeys();
-    const map = new Map<string, string>();
-    const searchItems: string[] = [];
-
-    keys.forEach((key) => {
-      const def = getSettingDefinition(key);
-      if (def?.label) {
-        searchItems.push(def.label);
-        map.set(def.label.toLowerCase(), key);
-      }
-    });
-
-    const fzf = new AsyncFzf(searchItems, {
-      fuzzy: 'v2',
-      casing: 'case-insensitive',
-    });
-    return { fzfInstance: fzf, searchMap: map };
-  }, []);
-
-  // Perform search
-  useEffect(() => {
-    let active = true;
-    if (!searchQuery.trim() || !fzfInstance) {
-      setFilteredKeys(getDialogSettingKeys());
-      return;
-    }
-
-    const doSearch = async () => {
-      const results = await fzfInstance.find(searchQuery);
-
-      if (!active) return;
-
-      const matchedKeys = new Set<string>();
-      results.forEach((res: FzfResult) => {
-        const key = searchMap.get(res.item.toLowerCase());
-        if (key) matchedKeys.add(key);
-      });
-      setFilteredKeys(Array.from(matchedKeys));
-    };
-
-    // eslint-disable-next-line @typescript-eslint/no-floating-promises
-    doSearch();
-
-    return () => {
-      active = false;
-    };
-  }, [searchQuery, fzfInstance, searchMap]);
-
   // Local pending settings state for the selected scope
   const [pendingSettings, setPendingSettings] = useState<Settings>(() =>
     // Deep clone to avoid mutation
@@ -182,49 +117,8 @@ export function SettingsDialog({
     setShowRestartPrompt(newRestartRequired.size > 0);
   }, [selectedScope, settings, globalPendingChanges]);
 
-  // Calculate max width for the left column (Label/Description) to keep values aligned or close
-  const maxLabelOrDescriptionWidth = useMemo(() => {
-    const allKeys = getDialogSettingKeys();
-    let max = 0;
-    for (const key of allKeys) {
-      const def = getSettingDefinition(key);
-      if (!def) continue;
-
-      const scopeMessage = getScopeMessageForSetting(
-        key,
-        selectedScope,
-        settings,
-      );
-      const label = def.label || key;
-      const labelFull = label + (scopeMessage ? ` ${scopeMessage}` : '');
-      const lWidth = getCachedStringWidth(labelFull);
-      const dWidth = def.description
-        ? getCachedStringWidth(def.description)
-        : 0;
-
-      max = Math.max(max, lWidth, dWidth);
-    }
-    return max;
-  }, [selectedScope, settings]);
-
-  // Get mainAreaWidth for search buffer viewport
-  const { mainAreaWidth } = useUIState();
-  const viewportWidth = mainAreaWidth - 8;
-
-  // Search input buffer
-  const searchBuffer = useTextBuffer({
-    initialText: '',
-    initialCursorOffset: 0,
-    viewport: {
-      width: viewportWidth,
-      height: 1,
-    },
-    singleLine: true,
-    onChange: (text) => setSearchQuery(text),
-  });
-
-  // Generate items for BaseSettingsDialog
-  const settingKeys = searchQuery ? filteredKeys : getDialogSettingKeys();
+  // Generate items for SearchableList
+  const settingKeys = useMemo(() => getDialogSettingKeys(), []);
   const items: SettingsDialogItem[] = useMemo(() => {
     const scopeSettings = settings.forScope(selectedScope).settings;
     const mergedSettings = settings.merged;
@@ -270,6 +164,10 @@ export function SettingsDialog({
     });
   }, [settingKeys, selectedScope, settings, modifiedSettings, pendingSettings]);
 
+  const { filteredItems, searchBuffer, maxLabelWidth } = useFuzzyList({
+    items,
+  });
+
   // Scope selection handler
   const handleScopeChange = useCallback((scope: LoadableSettingScope) => {
     setSelectedScope(scope);
@@ -696,12 +594,12 @@ export function SettingsDialog({
       borderColor={showRestartPrompt ? theme.status.warning : undefined}
       searchEnabled={showSearch}
       searchBuffer={searchBuffer}
-      items={items}
+      items={filteredItems}
       showScopeSelector={showScopeSelection}
       selectedScope={selectedScope}
       onScopeChange={handleScopeChange}
       maxItemsToShow={effectiveMaxItemsToShow}
-      maxLabelWidth={maxLabelOrDescriptionWidth}
+      maxLabelWidth={maxLabelWidth}
       onItemToggle={handleItemToggle}
       onEditCommit={handleEditCommit}
       onItemClear={handleItemClear}
diff --git a/packages/cli/src/ui/components/shared/BaseSettingsDialog.tsx b/packages/cli/src/ui/components/shared/BaseSettingsDialog.tsx
index ed454da08a..e257600188 100644
--- a/packages/cli/src/ui/components/shared/BaseSettingsDialog.tsx
+++ b/packages/cli/src/ui/components/shared/BaseSettingsDialog.tsx
@@ -144,28 +144,30 @@ export function BaseSettingsDialog({
   useEffect(() => {
     const prevItems = prevItemsRef.current;
     if (prevItems !== items) {
-      const prevActiveItem = prevItems[activeIndex];
-      if (prevActiveItem) {
-        const newIndex = items.findIndex((i) => i.key === prevActiveItem.key);
-        if (newIndex !== -1) {
-          // Item still exists in the filtered list, keep focus on it
-          setActiveIndex(newIndex);
-          // Adjust scroll offset to ensure the item is visible
-          let newScroll = scrollOffset;
-          if (newIndex < scrollOffset) newScroll = newIndex;
-          else if (newIndex >= scrollOffset + maxItemsToShow)
-            newScroll = newIndex - maxItemsToShow + 1;
-
-          const maxScroll = Math.max(0, items.length - maxItemsToShow);
-          setScrollOffset(Math.min(newScroll, maxScroll));
-        } else {
-          // Item was filtered out, reset to the top
-          setActiveIndex(0);
-          setScrollOffset(0);
-        }
-      } else {
+      if (items.length === 0) {
         setActiveIndex(0);
         setScrollOffset(0);
+      } else {
+        const prevActiveItem = prevItems[activeIndex];
+        if (prevActiveItem) {
+          const newIndex = items.findIndex((i) => i.key === prevActiveItem.key);
+          if (newIndex !== -1) {
+            // Item still exists in the filtered list, keep focus on it
+            setActiveIndex(newIndex);
+            // Adjust scroll offset to ensure the item is visible
+            let newScroll = scrollOffset;
+            if (newIndex < scrollOffset) newScroll = newIndex;
+            else if (newIndex >= scrollOffset + maxItemsToShow)
+              newScroll = newIndex - maxItemsToShow + 1;
+
+            const maxScroll = Math.max(0, items.length - maxItemsToShow);
+            setScrollOffset(Math.min(newScroll, maxScroll));
+          } else {
+            // Item was filtered out, reset to the top
+            setActiveIndex(0);
+            setScrollOffset(0);
+          }
+        }
       }
       prevItemsRef.current = items;
     }
@@ -416,7 +418,10 @@ export function BaseSettingsDialog({
 
       return;
     },
-    { isActive: true },
+    {
+      isActive: true,
+      priority: focusSection === 'settings' && !editingKey,
+    },
   );
 
   return (
diff --git a/packages/cli/src/ui/components/shared/SearchableList.test.tsx b/packages/cli/src/ui/components/shared/SearchableList.test.tsx
new file mode 100644
index 0000000000..5b366ea4f6
--- /dev/null
+++ b/packages/cli/src/ui/components/shared/SearchableList.test.tsx
@@ -0,0 +1,156 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from 'react';
+import { render } from '../../../test-utils/render.js';
+import { waitFor } from '../../../test-utils/async.js';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SearchableList, type SearchableListProps } from './SearchableList.js';
+import { KeypressProvider } from '../../contexts/KeypressContext.js';
+import { type GenericListItem } from '../../hooks/useFuzzyList.js';
+
+// Mock UI State
+vi.mock('../../contexts/UIStateContext.js', () => ({
+  useUIState: () => ({
+    mainAreaWidth: 100,
+  }),
+}));
+
+const mockItems: GenericListItem[] = [
+  {
+    key: 'item-1',
+    label: 'Item One',
+    description: 'Description for item one',
+  },
+  {
+    key: 'item-2',
+    label: 'Item Two',
+    description: 'Description for item two',
+  },
+  {
+    key: 'item-3',
+    label: 'Item Three',
+    description: 'Description for item three',
+  },
+];
+
+describe('SearchableList', () => {
+  let mockOnSelect: ReturnType<typeof vi.fn>;
+  let mockOnClose: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockOnSelect = vi.fn();
+    mockOnClose = vi.fn();
+  });
+
+  const renderList = (
+    props: Partial<SearchableListProps<GenericListItem>> = {},
+  ) => {
+    const defaultProps: SearchableListProps<GenericListItem> = {
+      title: 'Test List',
+      items: mockItems,
+      onSelect: mockOnSelect,
+      onClose: mockOnClose,
+      ...props,
+    };
+
+    return render(
+      <KeypressProvider>
+        <SearchableList {...defaultProps} />
+      </KeypressProvider>,
+    );
+  };
+
+  it('should render all items initially', () => {
+    const { lastFrame } = renderList();
+    const frame = lastFrame();
+
+    // Check for title
+    expect(frame).toContain('Test List');
+
+    // Check for items
+    expect(frame).toContain('Item One');
+    expect(frame).toContain('Item Two');
+    expect(frame).toContain('Item Three');
+
+    // Check for descriptions
+    expect(frame).toContain('Description for item one');
+  });
+
+  it('should filter items based on search query', async () => {
+    const { lastFrame, stdin } = renderList();
+
+    // Type "Two" into search
+    await React.act(async () => {
+      stdin.write('Two');
+    });
+
+    await waitFor(() => {
+      const frame = lastFrame();
+      expect(frame).toContain('Item Two');
+      expect(frame).not.toContain('Item One');
+      expect(frame).not.toContain('Item Three');
+    });
+  });
+
+  it('should show "No items found." when no items match', async () => {
+    const { lastFrame, stdin } = renderList();
+
+    // Type something that won't match
+    await React.act(async () => {
+      stdin.write('xyz123');
+    });
+
+    await waitFor(() => {
+      const frame = lastFrame();
+      expect(frame).toContain('No items found.');
+    });
+  });
+
+  it('should handle selection with Enter', async () => {
+    const { stdin } = renderList();
+
+    // Select first item (default active)
+    await React.act(async () => {
+      stdin.write('\r'); // Enter
+    });
+
+    await waitFor(() => {
+      expect(mockOnSelect).toHaveBeenCalledWith(mockItems[0]);
+    });
+  });
+
+  it('should handle navigation and selection', async () => {
+    const { stdin } = renderList();
+
+    // Navigate down to second item
+    await React.act(async () => {
+      stdin.write('\u001B[B'); // Down Arrow
+    });
+
+    // Select second item
+    await React.act(async () => {
+      stdin.write('\r'); // Enter
+    });
+
+    await waitFor(() => {
+      expect(mockOnSelect).toHaveBeenCalledWith(mockItems[1]);
+    });
+  });
+
+  it('should handle close with Esc', async () => {
+    const { stdin } = renderList();
+
+    await React.act(async () => {
+      stdin.write('\u001B'); // Esc
+    });
+
+    await waitFor(() => {
+      expect(mockOnClose).toHaveBeenCalled();
+    });
+  });
+});
diff --git a/packages/cli/src/ui/components/shared/SearchableList.tsx b/packages/cli/src/ui/components/shared/SearchableList.tsx
new file mode 100644
index 0000000000..07720ce5d6
--- /dev/null
+++ b/packages/cli/src/ui/components/shared/SearchableList.tsx
@@ -0,0 +1,189 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { useState, useEffect } from 'react';
+import { Box, Text } from 'ink';
+import { theme } from '../../semantic-colors.js';
+import { TextInput } from './TextInput.js';
+import { useKeypress, type Key } from '../../hooks/useKeypress.js';
+import { keyMatchers, Command } from '../../keyMatchers.js';
+import {
+  useFuzzyList,
+  type GenericListItem,
+} from '../../hooks/useFuzzyList.js';
+
+export interface SearchableListProps<T extends GenericListItem> {
+  /** List title */
+  title?: string;
+  /** Available items */
+  items: T[];
+  /** Callback when an item is selected */
+  onSelect: (item: T) => void;
+  /** Callback when the list is closed (e.g. via Esc) */
+  onClose?: () => void;
+  /** Initial search query */
+  initialSearchQuery?: string;
+  /** Placeholder for search input */
+  searchPlaceholder?: string;
+  /** Max items to show at once */
+  maxItemsToShow?: number;
+}
+
+/**
+ * A generic searchable list component.
+ */
+export function SearchableList<T extends GenericListItem>({
+  title,
+  items,
+  onSelect,
+  onClose,
+  initialSearchQuery = '',
+  searchPlaceholder = 'Search...',
+  maxItemsToShow = 10,
+}: SearchableListProps<T>): React.JSX.Element {
+  const { filteredItems, searchBuffer, maxLabelWidth } = useFuzzyList({
+    items,
+    initialQuery: initialSearchQuery,
+  });
+
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [scrollOffset, setScrollOffset] = useState(0);
+
+  // Reset selection when filtered items change
+  useEffect(() => {
+    setActiveIndex(0);
+    setScrollOffset(0);
+  }, [filteredItems]);
+
+  // Calculate visible items
+  const visibleItems = filteredItems.slice(
+    scrollOffset,
+    scrollOffset + maxItemsToShow,
+  );
+  const showScrollUp = scrollOffset > 0;
+  const showScrollDown = scrollOffset + maxItemsToShow < filteredItems.length;
+
+  useKeypress(
+    (key: Key) => {
+      // Navigation
+      if (keyMatchers[Command.DIALOG_NAVIGATION_UP](key)) {
+        const newIndex =
+          activeIndex > 0 ? activeIndex - 1 : filteredItems.length - 1;
+        setActiveIndex(newIndex);
+        if (newIndex === filteredItems.length - 1) {
+          setScrollOffset(Math.max(0, filteredItems.length - maxItemsToShow));
+        } else if (newIndex < scrollOffset) {
+          setScrollOffset(newIndex);
+        }
+        return;
+      }
+      if (keyMatchers[Command.DIALOG_NAVIGATION_DOWN](key)) {
+        const newIndex =
+          activeIndex < filteredItems.length - 1 ? activeIndex + 1 : 0;
+        setActiveIndex(newIndex);
+        if (newIndex === 0) {
+          setScrollOffset(0);
+        } else if (newIndex >= scrollOffset + maxItemsToShow) {
+          setScrollOffset(newIndex - maxItemsToShow + 1);
+        }
+        return;
+      }
+
+      // Selection
+      if (keyMatchers[Command.RETURN](key)) {
+        const item = filteredItems[activeIndex];
+        if (item) {
+          onSelect(item);
+        }
+        return;
+      }
+
+      // Close
+      if (keyMatchers[Command.ESCAPE](key)) {
+        onClose?.();
+        return;
+      }
+    },
+    { isActive: true },
+  );
+
+  return (
+    <Box
+      borderStyle="round"
+      borderColor={theme.border.default}
+      flexDirection="column"
+      padding={1}
+      width="100%"
+    >
+      {/* Header */}
+      {title && (
+        <Box marginBottom={1}>
+          <Text bold>{title}</Text>
+        </Box>
+      )}
+
+      {/* Search Input */}
+      {searchBuffer && (
+        <Box
+          borderStyle="round"
+          borderColor={theme.border.focused}
+          paddingX={1}
+          marginBottom={1}
+        >
+          <TextInput
+            buffer={searchBuffer}
+            placeholder={searchPlaceholder}
+            focus={true}
+          />
+        </Box>
+      )}
+
+      {/* List */}
+      <Box flexDirection="column">
+        {visibleItems.length === 0 ? (
+          <Text color={theme.text.secondary}>No items found.</Text>
+        ) : (
+          visibleItems.map((item, idx) => {
+            const index = scrollOffset + idx;
+            const isActive = index === activeIndex;
+
+            return (
+              <Box key={item.key} flexDirection="row">
+                <Text
+                  color={isActive ? theme.status.success : theme.text.secondary}
+                >
+                  {isActive ? '> ' : '  '}
+                </Text>
+                <Box width={maxLabelWidth + 2}>
+                  <Text
+                    color={isActive ? theme.status.success : theme.text.primary}
+                  >
+                    {item.label}
+                  </Text>
+                </Box>
+                {item.description && (
+                  <Text color={theme.text.secondary}>{item.description}</Text>
+                )}
+              </Box>
+            );
+          })
+        )}
+      </Box>
+
+      {/* Footer/Scroll Indicators */}
+      {(showScrollUp || showScrollDown) && (
+        <Box marginTop={1} justifyContent="center">
+          <Text color={theme.text.secondary}>
+            {showScrollUp ? '▲ ' : '  '}
+            {filteredItems.length} items
+            {showScrollDown ? ' ▼' : '  '}
+          </Text>
+        </Box>
+      )}
+    </Box>
+  );
+}
diff --git a/packages/cli/src/ui/hooks/useFuzzyList.ts b/packages/cli/src/ui/hooks/useFuzzyList.ts
new file mode 100644
index 0000000000..6d07b0ea75
--- /dev/null
+++ b/packages/cli/src/ui/hooks/useFuzzyList.ts
@@ -0,0 +1,151 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useState, useMemo, useEffect } from 'react';
+import { AsyncFzf } from 'fzf';
+import { useUIState } from '../contexts/UIStateContext.js';
+import {
+  useTextBuffer,
+  type TextBuffer,
+} from '../components/shared/text-buffer.js';
+import { getCachedStringWidth } from '../utils/textUtils.js';
+
+interface FzfResult {
+  item: string;
+  start: number;
+  end: number;
+  score: number;
+  positions?: number[];
+}
+
+export interface GenericListItem {
+  key: string;
+  label: string;
+  description?: string;
+  scopeMessage?: string;
+}
+
+export interface UseFuzzyListProps<T extends GenericListItem> {
+  items: T[];
+  initialQuery?: string;
+  onSearch?: (query: string) => void;
+}
+
+export interface UseFuzzyListResult<T extends GenericListItem> {
+  filteredItems: T[];
+  searchBuffer: TextBuffer | undefined;
+  searchQuery: string;
+  setSearchQuery: (query: string) => void;
+  maxLabelWidth: number;
+}
+
+export function useFuzzyList<T extends GenericListItem>({
+  items,
+  initialQuery = '',
+  onSearch,
+}: UseFuzzyListProps<T>): UseFuzzyListResult<T> {
+  // Search state
+  const [searchQuery, setSearchQuery] = useState(initialQuery);
+  const [filteredKeys, setFilteredKeys] = useState<string[]>(() =>
+    items.map((i) => i.key),
+  );
+
+  // FZF instance for fuzzy searching
+  const { fzfInstance, searchMap } = useMemo(() => {
+    const map = new Map<string, string>();
+    const searchItems: string[] = [];
+
+    items.forEach((item) => {
+      searchItems.push(item.label);
+      map.set(item.label.toLowerCase(), item.key);
+    });
+
+    const fzf = new AsyncFzf(searchItems, {
+      fuzzy: 'v2',
+      casing: 'case-insensitive',
+    });
+    return { fzfInstance: fzf, searchMap: map };
+  }, [items]);
+
+  // Perform search
+  useEffect(() => {
+    let active = true;
+    if (!searchQuery.trim() || !fzfInstance) {
+      setFilteredKeys(items.map((i) => i.key));
+      return;
+    }
+
+    const doSearch = async () => {
+      const results = await fzfInstance.find(searchQuery);
+
+      if (!active) return;
+
+      const matchedKeys = new Set<string>();
+      results.forEach((res: FzfResult) => {
+        const key = searchMap.get(res.item.toLowerCase());
+        if (key) matchedKeys.add(key);
+      });
+      setFilteredKeys(Array.from(matchedKeys));
+      onSearch?.(searchQuery);
+    };
+
+    void doSearch().catch((error) => {
+      // eslint-disable-next-line no-console
+      console.error('Search failed:', error);
+      setFilteredKeys(items.map((i) => i.key)); // Reset to all items on error
+    });
+
+    return () => {
+      active = false;
+    };
+  }, [searchQuery, fzfInstance, searchMap, items, onSearch]);
+
+  // Get mainAreaWidth for search buffer viewport from UIState
+  const { mainAreaWidth } = useUIState();
+  const viewportWidth = Math.max(20, mainAreaWidth - 8);
+
+  // Search input buffer
+  const searchBuffer = useTextBuffer({
+    initialText: searchQuery,
+    initialCursorOffset: searchQuery.length,
+    viewport: {
+      width: viewportWidth,
+      height: 1,
+    },
+    singleLine: true,
+    onChange: (text) => setSearchQuery(text),
+  });
+
+  // Filtered items to display
+  const filteredItems = useMemo(() => {
+    if (!searchQuery) return items;
+    return items.filter((item) => filteredKeys.includes(item.key));
+  }, [items, filteredKeys, searchQuery]);
+
+  // Calculate max label width for alignment
+  const maxLabelWidth = useMemo(() => {
+    let max = 0;
+    // We use all items for consistent alignment even when filtered
+    items.forEach((item) => {
+      const labelFull =
+        item.label + (item.scopeMessage ? ` ${item.scopeMessage}` : '');
+      const lWidth = getCachedStringWidth(labelFull);
+      const dWidth = item.description
+        ? getCachedStringWidth(item.description)
+        : 0;
+      max = Math.max(max, lWidth, dWidth);
+    });
+    return max;
+  }, [items]);
+
+  return {
+    filteredItems,
+    searchBuffer,
+    searchQuery,
+    setSearchQuery,
+    maxLabelWidth,
+  };
+}

From e8e681c6707143ac7165b48e2eb6de5c9d9babea Mon Sep 17 00:00:00 2001
From: Jerop Kipruto <jerop@google.com>
Date: Thu, 12 Feb 2026 16:10:25 -0500
Subject: [PATCH 30/44] feat(ui): align `AskUser` color scheme with UX spec
 (#18943)

---
 .../components/ToolConfirmationQueue.test.tsx | 117 +++++++++++++++++-
 .../ui/components/ToolConfirmationQueue.tsx   |   7 +-
 .../ToolConfirmationQueue.test.tsx.snap       |  27 ++++
 3 files changed, 147 insertions(+), 4 deletions(-)

diff --git a/packages/cli/src/ui/components/ToolConfirmationQueue.test.tsx b/packages/cli/src/ui/components/ToolConfirmationQueue.test.tsx
index f0e11bddd4..6df45442c1 100644
--- a/packages/cli/src/ui/components/ToolConfirmationQueue.test.tsx
+++ b/packages/cli/src/ui/components/ToolConfirmationQueue.test.tsx
@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { Box } from 'ink';
 import { ToolConfirmationQueue } from './ToolConfirmationQueue.js';
 import { ToolCallStatus, StreamingState } from '../types.js';
@@ -12,6 +12,31 @@ import { renderWithProviders } from '../../test-utils/render.js';
 import { waitFor } from '../../test-utils/async.js';
 import type { Config } from '@google/gemini-cli-core';
 import type { ConfirmingToolState } from '../hooks/useConfirmingTool.js';
+import { theme } from '../semantic-colors.js';
+
+vi.mock('./StickyHeader.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('./StickyHeader.js')>();
+  return {
+    ...actual,
+    StickyHeader: vi.fn((props) => actual.StickyHeader(props)),
+  };
+});
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@google/gemini-cli-core')>();
+  return {
+    ...actual,
+    validatePlanPath: vi.fn().mockResolvedValue(undefined),
+    validatePlanContent: vi.fn().mockResolvedValue(undefined),
+    processSingleFileContent: vi.fn().mockResolvedValue({
+      llmContent: 'Plan content goes here',
+      error: undefined,
+    }),
+  };
+});
+
+const { StickyHeader } = await import('./StickyHeader.js');
 
 describe('ToolConfirmationQueue', () => {
   const mockConfig = {
@@ -19,8 +44,19 @@ describe('ToolConfirmationQueue', () => {
     getIdeMode: () => false,
     getModel: () => 'gemini-pro',
     getDebugMode: () => false,
+    getTargetDir: () => '/mock/target/dir',
+    getFileSystemService: () => ({
+      readFile: vi.fn().mockResolvedValue('Plan content'),
+    }),
+    storage: {
+      getProjectTempPlansDir: () => '/mock/temp/plans',
+    },
   } as unknown as Config;
 
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
   it('renders the confirming tool with progress indicator', () => {
     const confirmingTool = {
       tool: {
@@ -60,6 +96,9 @@ describe('ToolConfirmationQueue', () => {
     expect(output).toContain('list files'); // Tool description
     expect(output).toContain("Allow execution of: 'ls'?");
     expect(output).toMatchSnapshot();
+
+    const stickyHeaderProps = vi.mocked(StickyHeader).mock.calls[0][0];
+    expect(stickyHeaderProps.borderColor).toBe(theme.status.warning);
   });
 
   it('returns null if tool has no confirmation details', () => {
@@ -229,4 +268,80 @@ describe('ToolConfirmationQueue', () => {
     expect(output).not.toContain('Press ctrl-o to show more lines');
     expect(output).toMatchSnapshot();
   });
+
+  it('renders AskUser tool confirmation with Success color', () => {
+    const confirmingTool = {
+      tool: {
+        callId: 'call-1',
+        name: 'ask_user',
+        description: 'ask user',
+        status: ToolCallStatus.Confirming,
+        confirmationDetails: {
+          type: 'ask_user' as const,
+          questions: [],
+          onConfirm: vi.fn(),
+        },
+      },
+      index: 1,
+      total: 1,
+    };
+
+    const { lastFrame } = renderWithProviders(
+      <ToolConfirmationQueue
+        confirmingTool={confirmingTool as unknown as ConfirmingToolState}
+      />,
+      {
+        config: mockConfig,
+        uiState: {
+          terminalWidth: 80,
+        },
+      },
+    );
+
+    const output = lastFrame();
+    expect(output).toMatchSnapshot();
+
+    const stickyHeaderProps = vi.mocked(StickyHeader).mock.calls[0][0];
+    expect(stickyHeaderProps.borderColor).toBe(theme.status.success);
+  });
+
+  it('renders ExitPlanMode tool confirmation with Success color', async () => {
+    const confirmingTool = {
+      tool: {
+        callId: 'call-1',
+        name: 'exit_plan_mode',
+        description: 'exit plan mode',
+        status: ToolCallStatus.Confirming,
+        confirmationDetails: {
+          type: 'exit_plan_mode' as const,
+          planPath: '/path/to/plan',
+          onConfirm: vi.fn(),
+        },
+      },
+      index: 1,
+      total: 1,
+    };
+
+    const { lastFrame } = renderWithProviders(
+      <ToolConfirmationQueue
+        confirmingTool={confirmingTool as unknown as ConfirmingToolState}
+      />,
+      {
+        config: mockConfig,
+        uiState: {
+          terminalWidth: 80,
+        },
+      },
+    );
+
+    await waitFor(() => {
+      expect(lastFrame()).toContain('Plan content goes here');
+    });
+
+    const output = lastFrame();
+    expect(output).toMatchSnapshot();
+
+    const stickyHeaderProps = vi.mocked(StickyHeader).mock.calls[0][0];
+    expect(stickyHeaderProps.borderColor).toBe(theme.status.success);
+  });
 });
diff --git a/packages/cli/src/ui/components/ToolConfirmationQueue.tsx b/packages/cli/src/ui/components/ToolConfirmationQueue.tsx
index eb47d768bd..52cba7e0d7 100644
--- a/packages/cli/src/ui/components/ToolConfirmationQueue.tsx
+++ b/packages/cli/src/ui/components/ToolConfirmationQueue.tsx
@@ -70,10 +70,11 @@ export const ToolConfirmationQueue: React.FC<ToolConfirmationQueueProps> = ({
       ? Math.max(maxHeight - 6, 4)
       : undefined;
 
-  const borderColor = theme.status.warning;
-  const hideToolIdentity =
+  const isRoutine =
     tool.confirmationDetails?.type === 'ask_user' ||
     tool.confirmationDetails?.type === 'exit_plan_mode';
+  const borderColor = isRoutine ? theme.status.success : theme.status.warning;
+  const hideToolIdentity = isRoutine;
 
   return (
     <OverflowProvider>
@@ -90,7 +91,7 @@ export const ToolConfirmationQueue: React.FC<ToolConfirmationQueueProps> = ({
               marginBottom={hideToolIdentity ? 0 : 1}
               justifyContent="space-between"
             >
-              <Text color={theme.status.warning} bold>
+              <Text color={borderColor} bold>
                 {getConfirmationHeader(tool.confirmationDetails)}
               </Text>
               {total > 1 && (
diff --git a/packages/cli/src/ui/components/__snapshots__/ToolConfirmationQueue.test.tsx.snap b/packages/cli/src/ui/components/__snapshots__/ToolConfirmationQueue.test.tsx.snap
index d4bbfdeaeb..aad58b92a7 100644
--- a/packages/cli/src/ui/components/__snapshots__/ToolConfirmationQueue.test.tsx.snap
+++ b/packages/cli/src/ui/components/__snapshots__/ToolConfirmationQueue.test.tsx.snap
@@ -40,6 +40,33 @@ exports[`ToolConfirmationQueue > does not render expansion hint when constrainHe
 ╰──────────────────────────────────────────────────────────────────────────────╯"
 `;
 
+exports[`ToolConfirmationQueue > renders AskUser tool confirmation with Success color 1`] = `
+"╭──────────────────────────────────────────────────────────────────────────────╮
+│ Answer Questions                                                             │
+│                                                                              │
+│ Review your answers:                                                         │
+│                                                                              │
+│                                                                              │
+│ Enter to submit · Tab/Shift+Tab to edit answers · Esc to cancel              │
+╰──────────────────────────────────────────────────────────────────────────────╯"
+`;
+
+exports[`ToolConfirmationQueue > renders ExitPlanMode tool confirmation with Success color 1`] = `
+"╭──────────────────────────────────────────────────────────────────────────────╮
+│ Ready to start implementation?                                               │
+│                                                                              │
+│ Plan content goes here                                                       │
+│                                                                              │
+│ ● 1.  Yes, automatically accept edits                                        │
+│       Approves plan and allows tools to run automatically                    │
+│   2.  Yes, manually accept edits                                             │
+│       Approves plan but requires confirmation for each tool                  │
+│   3.  Type your feedback...                                                  │
+│                                                                              │
+│ Enter to select · ↑/↓ to navigate · Esc to cancel                            │
+╰──────────────────────────────────────────────────────────────────────────────╯"
+`;
+
 exports[`ToolConfirmationQueue > renders expansion hint when content is long and constrained 1`] = `
 "╭──────────────────────────────────────────────────────────────────────────────╮
 │ Action Required                                                              │

From 827587196368dc688913b8ce79503762f83d0555 Mon Sep 17 00:00:00 2001
From: Jerop Kipruto <jerop@google.com>
Date: Thu, 12 Feb 2026 16:49:07 -0500
Subject: [PATCH 31/44] Hide AskUser tool validation errors from UI (agent
 self-corrects) (#18954)

---
 .../messages/ToolGroupMessage.test.tsx        |  60 ++++----
 .../components/messages/ToolGroupMessage.tsx  |  18 +--
 .../src/ui/components/messages/ToolShared.tsx |  10 +-
 .../ToolGroupMessage.test.tsx.snap            |  14 +-
 packages/core/src/index.ts                    |   1 +
 packages/core/src/tools/ask-user.test.ts      | 138 +++++++++++++++++-
 packages/core/src/tools/ask-user.ts           |  60 ++++++++
 7 files changed, 245 insertions(+), 56 deletions(-)

diff --git a/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx b/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx
index d2d3cd277a..d2ada4d659 100644
--- a/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx
+++ b/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx
@@ -409,35 +409,41 @@ describe('<ToolGroupMessage />', () => {
 
   describe('Ask User Filtering', () => {
     it.each([
-      ToolCallStatus.Pending,
-      ToolCallStatus.Executing,
-      ToolCallStatus.Confirming,
-    ])('filters out ask_user when status is %s', (status) => {
-      const toolCalls = [
-        createToolCall({
-          callId: `ask-user-${status}`,
-          name: ASK_USER_DISPLAY_NAME,
-          status,
-        }),
-      ];
-
-      const { lastFrame, unmount } = renderWithProviders(
-        <ToolGroupMessage {...baseProps} toolCalls={toolCalls} />,
-        { config: baseMockConfig },
-      );
-
-      expect(lastFrame()).toMatchSnapshot();
-      unmount();
-    });
-
-    it.each([ToolCallStatus.Success, ToolCallStatus.Error])(
-      'does NOT filter out ask_user when status is %s',
-      (status) => {
+      {
+        status: ToolCallStatus.Pending,
+        resultDisplay: 'test result',
+        shouldHide: true,
+      },
+      {
+        status: ToolCallStatus.Executing,
+        resultDisplay: 'test result',
+        shouldHide: true,
+      },
+      {
+        status: ToolCallStatus.Confirming,
+        resultDisplay: 'test result',
+        shouldHide: true,
+      },
+      {
+        status: ToolCallStatus.Success,
+        resultDisplay: 'test result',
+        shouldHide: false,
+      },
+      { status: ToolCallStatus.Error, resultDisplay: '', shouldHide: true },
+      {
+        status: ToolCallStatus.Error,
+        resultDisplay: 'error message',
+        shouldHide: false,
+      },
+    ])(
+      'filtering logic for status=$status and hasResult=$resultDisplay',
+      ({ status, resultDisplay, shouldHide }) => {
         const toolCalls = [
           createToolCall({
             callId: `ask-user-${status}`,
             name: ASK_USER_DISPLAY_NAME,
             status,
+            resultDisplay,
           }),
         ];
 
@@ -446,7 +452,11 @@ describe('<ToolGroupMessage />', () => {
           { config: baseMockConfig },
         );
 
-        expect(lastFrame()).toMatchSnapshot();
+        if (shouldHide) {
+          expect(lastFrame()).toBe('');
+        } else {
+          expect(lastFrame()).toMatchSnapshot();
+        }
         unmount();
       },
     );
diff --git a/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx b/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx
index 07ae280558..a553679562 100644
--- a/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx
+++ b/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx
@@ -14,7 +14,7 @@ import { ShellToolMessage } from './ShellToolMessage.js';
 import { theme } from '../../semantic-colors.js';
 import { useConfig } from '../../contexts/ConfigContext.js';
 import { isShellTool, isThisShellFocused } from './ToolShared.js';
-import { ASK_USER_DISPLAY_NAME } from '@google/gemini-cli-core';
+import { shouldHideAskUserTool } from '@google/gemini-cli-core';
 import { ShowMoreLines } from '../ShowMoreLines.js';
 import { useUIState } from '../../contexts/UIStateContext.js';
 
@@ -30,15 +30,6 @@ interface ToolGroupMessageProps {
   borderBottom?: boolean;
 }
 
-// Helper to identify Ask User tools that are in progress (have their own dialog UI)
-const isAskUserInProgress = (t: IndividualToolCallDisplay): boolean =>
-  t.name === ASK_USER_DISPLAY_NAME &&
-  [
-    ToolCallStatus.Pending,
-    ToolCallStatus.Executing,
-    ToolCallStatus.Confirming,
-  ].includes(t.status);
-
 // Main component renders the border and maps the tools using ToolMessage
 const TOOL_MESSAGE_HORIZONTAL_MARGIN = 4;
 
@@ -51,9 +42,12 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
   borderTop: borderTopOverride,
   borderBottom: borderBottomOverride,
 }) => {
-  // Filter out in-progress Ask User tools (they have their own AskUserDialog UI)
+  // Filter out Ask User tools that should be hidden (e.g. in-progress or errors without result)
   const toolCalls = useMemo(
-    () => allToolCalls.filter((t) => !isAskUserInProgress(t)),
+    () =>
+      allToolCalls.filter(
+        (t) => !shouldHideAskUserTool(t.name, t.status, !!t.resultDisplay),
+      ),
     [allToolCalls],
   );
 
diff --git a/packages/cli/src/ui/components/messages/ToolShared.tsx b/packages/cli/src/ui/components/messages/ToolShared.tsx
index a48aefdc7c..eaf3c73bfb 100644
--- a/packages/cli/src/ui/components/messages/ToolShared.tsx
+++ b/packages/cli/src/ui/components/messages/ToolShared.tsx
@@ -18,7 +18,7 @@ import { theme } from '../../semantic-colors.js';
 import {
   type Config,
   SHELL_TOOL_NAME,
-  ASK_USER_DISPLAY_NAME,
+  isCompletedAskUserTool,
   type ToolResultDisplay,
 } from '@google/gemini-cli-core';
 import { useInactivityTimer } from '../../hooks/useInactivityTimer.js';
@@ -205,13 +205,7 @@ export const ToolInfo: React.FC<ToolInfoProps> = ({
   }, [emphasis]);
 
   // Hide description for completed Ask User tools (the result display speaks for itself)
-  const isCompletedAskUser =
-    name === ASK_USER_DISPLAY_NAME &&
-    [
-      ToolCallStatus.Success,
-      ToolCallStatus.Error,
-      ToolCallStatus.Canceled,
-    ].includes(status);
+  const isCompletedAskUser = isCompletedAskUserTool(name, status);
 
   return (
     <Box overflow="hidden" height={1} flexGrow={1} flexShrink={1}>
diff --git a/packages/cli/src/ui/components/messages/__snapshots__/ToolGroupMessage.test.tsx.snap b/packages/cli/src/ui/components/messages/__snapshots__/ToolGroupMessage.test.tsx.snap
index 3586b32c21..7cda673c07 100644
--- a/packages/cli/src/ui/components/messages/__snapshots__/ToolGroupMessage.test.tsx.snap
+++ b/packages/cli/src/ui/components/messages/__snapshots__/ToolGroupMessage.test.tsx.snap
@@ -1,27 +1,21 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`<ToolGroupMessage /> > Ask User Filtering > does NOT filter out ask_user when status is Error 1`] = `
+exports[`<ToolGroupMessage /> > Ask User Filtering > filtering logic for status='Error' and hasResult='error message' 1`] = `
 "╭──────────────────────────────────────────────────────────────────────────╮
 │ x  Ask User                                                              │
 │                                                                          │
-│ Test result                                                              │
+│ error message                                                            │
 ╰──────────────────────────────────────────────────────────────────────────╯"
 `;
 
-exports[`<ToolGroupMessage /> > Ask User Filtering > does NOT filter out ask_user when status is Success 1`] = `
+exports[`<ToolGroupMessage /> > Ask User Filtering > filtering logic for status='Success' and hasResult='test result' 1`] = `
 "╭──────────────────────────────────────────────────────────────────────────╮
 │ ✓  Ask User                                                              │
 │                                                                          │
-│ Test result                                                              │
+│ test result                                                              │
 ╰──────────────────────────────────────────────────────────────────────────╯"
 `;
 
-exports[`<ToolGroupMessage /> > Ask User Filtering > filters out ask_user when status is Confirming 1`] = `""`;
-
-exports[`<ToolGroupMessage /> > Ask User Filtering > filters out ask_user when status is Executing 1`] = `""`;
-
-exports[`<ToolGroupMessage /> > Ask User Filtering > filters out ask_user when status is Pending 1`] = `""`;
-
 exports[`<ToolGroupMessage /> > Ask User Filtering > shows other tools when ask_user is filtered out 1`] = `
 "╭──────────────────────────────────────────────────────────────────────────╮
 │ ✓  other-tool A tool for testing                                         │
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 8232f73570..448e555df4 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -157,6 +157,7 @@ export * from './tools/read-many-files.js';
 export * from './tools/mcp-client.js';
 export * from './tools/mcp-tool.js';
 export * from './tools/write-todos.js';
+export * from './tools/ask-user.js';
 
 // MCP OAuth
 export { MCPOAuthProvider } from './mcp/oauth-provider.js';
diff --git a/packages/core/src/tools/ask-user.test.ts b/packages/core/src/tools/ask-user.test.ts
index c7d64eae6e..19c98fbc6b 100644
--- a/packages/core/src/tools/ask-user.test.ts
+++ b/packages/core/src/tools/ask-user.test.ts
@@ -5,10 +5,97 @@
  */
 
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { AskUserTool } from './ask-user.js';
+import {
+  AskUserTool,
+  shouldHideAskUserTool,
+  isCompletedAskUserTool,
+} from './ask-user.js';
 import { QuestionType, type Question } from '../confirmation-bus/types.js';
 import type { MessageBus } from '../confirmation-bus/message-bus.js';
 import { ToolConfirmationOutcome } from './tools.js';
+import { ToolErrorType } from './tool-error.js';
+import { ASK_USER_DISPLAY_NAME } from './tool-names.js';
+
+describe('AskUserTool Helpers', () => {
+  describe('shouldHideAskUserTool', () => {
+    it('returns false for non-AskUser tools', () => {
+      expect(shouldHideAskUserTool('other-tool', 'Success', true)).toBe(false);
+    });
+
+    it('hides Pending AskUser tool', () => {
+      expect(
+        shouldHideAskUserTool(ASK_USER_DISPLAY_NAME, 'Pending', false),
+      ).toBe(true);
+    });
+
+    it('hides Executing AskUser tool', () => {
+      expect(
+        shouldHideAskUserTool(ASK_USER_DISPLAY_NAME, 'Executing', false),
+      ).toBe(true);
+    });
+
+    it('hides Confirming AskUser tool', () => {
+      expect(
+        shouldHideAskUserTool(ASK_USER_DISPLAY_NAME, 'Confirming', false),
+      ).toBe(true);
+    });
+
+    it('shows Success AskUser tool', () => {
+      expect(
+        shouldHideAskUserTool(ASK_USER_DISPLAY_NAME, 'Success', true),
+      ).toBe(false);
+    });
+
+    it('shows Canceled AskUser tool', () => {
+      expect(
+        shouldHideAskUserTool(ASK_USER_DISPLAY_NAME, 'Canceled', true),
+      ).toBe(false);
+    });
+
+    it('hides Error AskUser tool without result display', () => {
+      expect(shouldHideAskUserTool(ASK_USER_DISPLAY_NAME, 'Error', false)).toBe(
+        true,
+      );
+    });
+
+    it('shows Error AskUser tool with result display', () => {
+      expect(shouldHideAskUserTool(ASK_USER_DISPLAY_NAME, 'Error', true)).toBe(
+        false,
+      );
+    });
+  });
+
+  describe('isCompletedAskUserTool', () => {
+    it('returns false for non-AskUser tools', () => {
+      expect(isCompletedAskUserTool('other-tool', 'Success')).toBe(false);
+    });
+
+    it('returns true for Success status', () => {
+      expect(isCompletedAskUserTool(ASK_USER_DISPLAY_NAME, 'Success')).toBe(
+        true,
+      );
+    });
+
+    it('returns true for Error status', () => {
+      expect(isCompletedAskUserTool(ASK_USER_DISPLAY_NAME, 'Error')).toBe(true);
+    });
+
+    it('returns true for Canceled status', () => {
+      expect(isCompletedAskUserTool(ASK_USER_DISPLAY_NAME, 'Canceled')).toBe(
+        true,
+      );
+    });
+
+    it('returns false for in-progress statuses', () => {
+      expect(isCompletedAskUserTool(ASK_USER_DISPLAY_NAME, 'Executing')).toBe(
+        false,
+      );
+      expect(isCompletedAskUserTool(ASK_USER_DISPLAY_NAME, 'Pending')).toBe(
+        false,
+      );
+    });
+  });
+});
 
 describe('AskUserTool', () => {
   let mockMessageBus: MessageBus;
@@ -228,6 +315,55 @@ describe('AskUserTool', () => {
     });
   });
 
+  describe('validateBuildAndExecute', () => {
+    it('should hide validation errors from returnDisplay', async () => {
+      const params = {
+        questions: [{ question: 'Test?', header: 'This is way too long' }],
+      };
+
+      const result = await tool.validateBuildAndExecute(
+        params,
+        new AbortController().signal,
+      );
+
+      expect(result.error).toBeDefined();
+      expect(result.error?.type).toBe(ToolErrorType.INVALID_TOOL_PARAMS);
+      expect(result.returnDisplay).toBe('');
+    });
+
+    it('should NOT hide non-validation errors (if any were to occur)', async () => {
+      const validateParamsSpy = vi
+        .spyOn(tool, 'validateToolParams')
+        .mockReturnValue(null);
+
+      const params = {
+        questions: [{ question: 'Valid?', header: 'Valid' }],
+      };
+
+      const mockInvocation = {
+        execute: vi.fn().mockRejectedValue(new Error('Some execution error')),
+        params,
+        getDescription: vi.fn().mockReturnValue(''),
+        toolLocations: vi.fn().mockReturnValue([]),
+        shouldConfirmExecute: vi.fn().mockResolvedValue(false),
+      };
+
+      const buildSpy = vi.spyOn(tool, 'build').mockReturnValue(mockInvocation);
+
+      const result = await tool.validateBuildAndExecute(
+        params,
+        new AbortController().signal,
+      );
+
+      expect(result.error).toBeDefined();
+      expect(result.error?.type).toBe(ToolErrorType.EXECUTION_FAILED);
+      expect(result.returnDisplay).toBe('Some execution error');
+
+      buildSpy.mockRestore();
+      validateParamsSpy.mockRestore();
+    });
+  });
+
   describe('shouldConfirmExecute', () => {
     it('should return confirmation details with normalized questions', async () => {
       const questions = [
diff --git a/packages/core/src/tools/ask-user.ts b/packages/core/src/tools/ask-user.ts
index db9103c720..951094d9ad 100644
--- a/packages/core/src/tools/ask-user.ts
+++ b/packages/core/src/tools/ask-user.ts
@@ -13,6 +13,7 @@ import {
   type ToolConfirmationPayload,
   ToolConfirmationOutcome,
 } from './tools.js';
+import { ToolErrorType } from './tool-error.js';
 import type { MessageBus } from '../confirmation-bus/message-bus.js';
 import { QuestionType, type Question } from '../confirmation-bus/types.js';
 import { ASK_USER_TOOL_NAME, ASK_USER_DISPLAY_NAME } from './tool-names.js';
@@ -154,6 +155,23 @@ export class AskUserTool extends BaseDeclarativeTool<
   ): AskUserInvocation {
     return new AskUserInvocation(params, messageBus, toolName, toolDisplayName);
   }
+
+  override async validateBuildAndExecute(
+    params: AskUserParams,
+    abortSignal: AbortSignal,
+  ): Promise<ToolResult> {
+    const result = await super.validateBuildAndExecute(params, abortSignal);
+    if (
+      result.error &&
+      result.error.type === ToolErrorType.INVALID_TOOL_PARAMS
+    ) {
+      return {
+        ...result,
+        returnDisplay: '',
+      };
+    }
+    return result;
+  }
 }
 
 export class AskUserInvocation extends BaseToolInvocation<
@@ -242,3 +260,45 @@ export class AskUserInvocation extends BaseToolInvocation<
     };
   }
 }
+
+/**
+ * Determines if an 'Ask User' tool call should be hidden from the standard tool history UI.
+ *
+ * We hide Ask User tools in two cases:
+ * 1. They are in progress because they are displayed using a specialized UI (AskUserDialog).
+ * 2. They have errored without a result display (e.g. validation errors), in which case
+ *    the agent self-corrects and we don't want to clutter the UI.
+ *
+ * NOTE: The 'status' parameter values are intended to match the CLI's ToolCallStatus enum.
+ */
+export function shouldHideAskUserTool(
+  name: string,
+  status: string,
+  hasResultDisplay: boolean,
+): boolean {
+  if (name !== ASK_USER_DISPLAY_NAME) {
+    return false;
+  }
+
+  // Case 1: In-progress tools (Pending, Executing, Confirming)
+  if (['Pending', 'Executing', 'Confirming'].includes(status)) {
+    return true;
+  }
+
+  // Case 2: Error without result display
+  if (status === 'Error' && !hasResultDisplay) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Returns true if the tool name and status correspond to a completed 'Ask User' tool call.
+ */
+export function isCompletedAskUserTool(name: string, status: string): boolean {
+  return (
+    name === ASK_USER_DISPLAY_NAME &&
+    ['Success', 'Error', 'Canceled'].includes(status)
+  );
+}

From c00de442e5910a5fce1e7b2b4f8a46316a04d16f Mon Sep 17 00:00:00 2001
From: Jacob Richman <jacob314@gmail.com>
Date: Thu, 12 Feb 2026 14:16:46 -0800
Subject: [PATCH 32/44] bug(cli) fix flicker due to AppContainer continuous
 initialization (#18958)

---
 packages/cli/src/gemini.tsx | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/packages/cli/src/gemini.tsx b/packages/cli/src/gemini.tsx
index 31e8bd433b..7b385453bf 100644
--- a/packages/cli/src/gemini.tsx
+++ b/packages/cli/src/gemini.tsx
@@ -89,7 +89,6 @@ import { SessionStatsProvider } from './ui/contexts/SessionContext.js';
 import { VimModeProvider } from './ui/contexts/VimModeContext.js';
 import { KeypressProvider } from './ui/contexts/KeypressContext.js';
 import { useKittyKeyboardProtocol } from './ui/hooks/useKittyKeyboardProtocol.js';
-import { useTerminalSize } from './ui/hooks/useTerminalSize.js';
 import {
   relaunchAppInChildProcess,
   relaunchOnExitCode,
@@ -221,7 +220,6 @@ export async function startInteractiveUI(
   // Create wrapper component to use hooks inside render
   const AppWrapper = () => {
     useKittyKeyboardProtocol();
-    const { columns, rows } = useTerminalSize();
 
     return (
       <SettingsContext.Provider value={settings}>
@@ -240,7 +238,6 @@ export async function startInteractiveUI(
                 <SessionStatsProvider>
                   <VimModeProvider settings={settings}>
                     <AppContainer
-                      key={`${columns}-${rows}`}
                       config={config}
                       startupWarnings={startupWarnings}
                       version={version}

From 44bcba323fe8153a9e70b78bde97340e401e36fc Mon Sep 17 00:00:00 2001
From: Shreya Keshive <shreyakeshive@google.com>
Date: Thu, 12 Feb 2026 17:39:42 -0500
Subject: [PATCH 33/44] feat(admin): Add admin controls documentation (#18644)

---
 docs/admin/enterprise-controls.md | 115 ++++++++++++++++++++++++++++++
 docs/sidebar.json                 |   4 ++
 2 files changed, 119 insertions(+)
 create mode 100644 docs/admin/enterprise-controls.md

diff --git a/docs/admin/enterprise-controls.md b/docs/admin/enterprise-controls.md
new file mode 100644
index 0000000000..8c9ba60a13
--- /dev/null
+++ b/docs/admin/enterprise-controls.md
@@ -0,0 +1,115 @@
+# Enterprise Admin Controls
+
+Gemini CLI empowers enterprise administrators to manage and enforce security
+policies and configuration settings across their entire organization. Secure
+defaults are enabled automatically for all enterprise users, but can be
+customized via the [Management Console](https://goo.gle/manage-gemini-cli).
+
+**Enterprise Admin Controls are enforced globally and cannot be overridden by
+users locally**, ensuring a consistent security posture.
+
+## Admin Controls vs. System Settings
+
+While [System-wide settings](../cli/settings.md) act as convenient configuration
+overrides, they can still be modified by users with sufficient privileges. In
+contrast, admin controls are immutable at the local level, making them the
+preferred method for enforcing policy.
+
+## Available Controls
+
+### Strict Mode
+
+**Enabled/Disabled** | Default: enabled
+
+If enabled, users will not be able to enter yolo mode.
+
+### Extensions
+
+**Enabled/Disabled** | Default: disabled
+
+If disabled, users will not be able to use or install extensions. See
+[Extensions](../extensions/index.md) for more details.
+
+### MCP
+
+#### Enabled/Disabled
+
+**Enabled/Disabled** | Default: disabled
+
+If disabled, users will not be able to use MCP servers. See
+[MCP Server Integration](../tools/mcp-server.md) for more details.
+
+#### MCP Servers (preview)
+
+**Default**: empty
+
+Allows administrators to define an explicit allowlist of MCP servers. This
+guarantees that users can only connect to trusted MCP servers defined by the
+organization.
+
+**Allowlist Format:**
+
+```json
+{
+  "mcpServers": {
+    "external-provider": {
+      "url": "https://api.mcp-provider.com",
+      "type": "sse",
+      "trust": true,
+      "includeTools": ["toolA", "toolB"],
+      "excludeTools": []
+    },
+    "internal-corp-tool": {
+      "url": "https://mcp.internal-tool.corp",
+      "type": "http",
+      "includeTools": [],
+      "excludeTools": ["adminTool"]
+    }
+  }
+}
+```
+
+**Supported Fields:**
+
+- `url`: (Required) The full URL of the MCP server endpoint.
+- `type`: (Required) The connection type (e.g., `sse` or `http`).
+- `trust`: (Optional) If set to `true`, the server is trusted and tool execution
+  will not require user approval.
+- `includeTools`: (Optional) An explicit list of tool names to allow. If
+  specified, only these tools will be available.
+- `excludeTools`: (Optional) A list of tool names to hide. These tools will be
+  blocked.
+
+**Client Enforcement Logic:**
+
+- **Empty Allowlist**: If the admin allowlist is empty, the client uses the
+  user’s local configuration as is (unless the MCP toggle above is disabled).
+- **Active Allowlist**: If the allowlist contains one or more servers, **all
+  locally configured servers not present in the allowlist are ignored**.
+- **Configuration Merging**: For a server to be active, it must exist in
+  **both** the admin allowlist and the user’s local configuration (matched by
+  name). The client merges these definitions as follows:
+  - **Override Fields**: The `url`, `type`, & `trust` are always taken from the
+    admin allowlist, overriding any local values.
+  - **Tools Filtering**: If `includeTools` or `excludeTools` are defined in the
+    allowlist, the admin’s rules are used exclusively. If both are undefined in
+    the admin allowlist, the client falls back to the user’s local tool
+    settings.
+  - **Cleared Fields**: To ensure security and consistency, the client
+    automatically clears local execution fields (`command`, `args`, `env`,
+    `cwd`, `httpUrl`, `tcp`). This prevents users from overriding the connection
+    method.
+  - **Other Fields**: All other MCP fields are pulled from the user’s local
+    configuration.
+- **Missing Allowlisted Servers**: If a server appears in the admin allowlist
+  but is missing from the local configuration, it will not be initialized. This
+  ensures users maintain final control over which permitted servers are actually
+  active in their environment.
+
+### Unmanaged Capabilities
+
+**Enabled/Disabled** | Default: disabled
+
+If disabled, users will not be able to use certain features. Currently, this
+control disables Agent Skills. See [Agent Skills](../cli/skills.md) for more
+details.
diff --git a/docs/sidebar.json b/docs/sidebar.json
index d6f884204a..376fba2acd 100644
--- a/docs/sidebar.json
+++ b/docs/sidebar.json
@@ -45,6 +45,10 @@
       { "label": "Checkpointing", "slug": "docs/cli/checkpointing" },
       { "label": "Custom commands", "slug": "docs/cli/custom-commands" },
       { "label": "Enterprise features", "slug": "docs/cli/enterprise" },
+      {
+        "label": "Enterprise admin controls",
+        "slug": "docs/admin/enterprise-controls"
+      },
       { "label": "Headless mode & scripting", "slug": "docs/cli/headless" },
       { "label": "Sandboxing", "slug": "docs/cli/sandbox" },
       { "label": "System prompt override", "slug": "docs/cli/system-prompt" },

From 55ec0f043c8ead4480d05af89b2dd11459e46d2c Mon Sep 17 00:00:00 2001
From: Jacob Richman <jacob314@gmail.com>
Date: Thu, 12 Feb 2026 15:00:13 -0800
Subject: [PATCH 34/44] feat(cli): disable ctrl-s shortcut outside of alternate
 buffer mode (#18887)

---
 docs/cli/keyboard-shortcuts.md          | 50 ++++++++++++-------------
 packages/cli/src/config/keyBindings.ts  |  7 +---
 packages/cli/src/ui/AppContainer.tsx    |  8 ++++
 packages/cli/src/ui/keyMatchers.test.ts |  7 ++--
 4 files changed, 39 insertions(+), 33 deletions(-)

diff --git a/docs/cli/keyboard-shortcuts.md b/docs/cli/keyboard-shortcuts.md
index ffc0a39fda..ac2705f757 100644
--- a/docs/cli/keyboard-shortcuts.md
+++ b/docs/cli/keyboard-shortcuts.md
@@ -96,31 +96,31 @@ available combinations.
 
 #### App Controls
 
-| Action                                                                                                | Keys                       |
-| ----------------------------------------------------------------------------------------------------- | -------------------------- |
-| Toggle detailed error information.                                                                    | `F12`                      |
-| Toggle the full TODO list.                                                                            | `Ctrl + T`                 |
-| Show IDE context details.                                                                             | `Ctrl + G`                 |
-| Toggle Markdown rendering.                                                                            | `Alt + M`                  |
-| Toggle copy mode when in alternate buffer mode.                                                       | `Ctrl + S`                 |
-| Toggle YOLO (auto-approval) mode for tool calls.                                                      | `Ctrl + Y`                 |
-| Cycle through approval modes: default (prompt), auto_edit (auto-approve edits), and plan (read-only). | `Shift + Tab`              |
-| Expand a height-constrained response to show additional lines when not in alternate buffer mode.      | `Ctrl + O`<br />`Ctrl + S` |
-| Expand or collapse a paste placeholder when cursor is over placeholder.                               | `Ctrl + O`                 |
-| Toggle current background shell visibility.                                                           | `Ctrl + B`                 |
-| Toggle background shell list.                                                                         | `Ctrl + L`                 |
-| Kill the active background shell.                                                                     | `Ctrl + K`                 |
-| Confirm selection in background shell list.                                                           | `Enter`                    |
-| Dismiss background shell list.                                                                        | `Esc`                      |
-| Move focus from background shell to Gemini.                                                           | `Shift + Tab`              |
-| Move focus from background shell list to Gemini.                                                      | `Tab (no Shift)`           |
-| Show warning when trying to move focus away from background shell.                                    | `Tab (no Shift)`           |
-| Show warning when trying to move focus away from shell input.                                         | `Tab (no Shift)`           |
-| Move focus from Gemini to the active shell.                                                           | `Tab (no Shift)`           |
-| Move focus from the shell back to Gemini.                                                             | `Shift + Tab`              |
-| Clear the terminal screen and redraw the UI.                                                          | `Ctrl + L`                 |
-| Restart the application.                                                                              | `R`                        |
-| Suspend the CLI and move it to the background.                                                        | `Ctrl + Z`                 |
+| Action                                                                                                | Keys             |
+| ----------------------------------------------------------------------------------------------------- | ---------------- |
+| Toggle detailed error information.                                                                    | `F12`            |
+| Toggle the full TODO list.                                                                            | `Ctrl + T`       |
+| Show IDE context details.                                                                             | `Ctrl + G`       |
+| Toggle Markdown rendering.                                                                            | `Alt + M`        |
+| Toggle copy mode when in alternate buffer mode.                                                       | `Ctrl + S`       |
+| Toggle YOLO (auto-approval) mode for tool calls.                                                      | `Ctrl + Y`       |
+| Cycle through approval modes: default (prompt), auto_edit (auto-approve edits), and plan (read-only). | `Shift + Tab`    |
+| Expand and collapse blocks of content when not in alternate buffer mode.                              | `Ctrl + O`       |
+| Expand or collapse a paste placeholder when cursor is over placeholder.                               | `Ctrl + O`       |
+| Toggle current background shell visibility.                                                           | `Ctrl + B`       |
+| Toggle background shell list.                                                                         | `Ctrl + L`       |
+| Kill the active background shell.                                                                     | `Ctrl + K`       |
+| Confirm selection in background shell list.                                                           | `Enter`          |
+| Dismiss background shell list.                                                                        | `Esc`            |
+| Move focus from background shell to Gemini.                                                           | `Shift + Tab`    |
+| Move focus from background shell list to Gemini.                                                      | `Tab (no Shift)` |
+| Show warning when trying to move focus away from background shell.                                    | `Tab (no Shift)` |
+| Show warning when trying to move focus away from shell input.                                         | `Tab (no Shift)` |
+| Move focus from Gemini to the active shell.                                                           | `Tab (no Shift)` |
+| Move focus from the shell back to Gemini.                                                             | `Shift + Tab`    |
+| Clear the terminal screen and redraw the UI.                                                          | `Ctrl + L`       |
+| Restart the application.                                                                              | `R`              |
+| Suspend the CLI and move it to the background.                                                        | `Ctrl + Z`       |
 
 <!-- KEYBINDINGS-AUTOGEN:END -->
 
diff --git a/packages/cli/src/config/keyBindings.ts b/packages/cli/src/config/keyBindings.ts
index c3f1f70fbe..35e1bb8041 100644
--- a/packages/cli/src/config/keyBindings.ts
+++ b/packages/cli/src/config/keyBindings.ts
@@ -286,10 +286,7 @@ export const defaultKeyBindings: KeyBindingConfig = {
   [Command.SHOW_SHELL_INPUT_UNFOCUS_WARNING]: [{ key: 'tab', shift: false }],
   [Command.BACKGROUND_SHELL_SELECT]: [{ key: 'return' }],
   [Command.BACKGROUND_SHELL_ESCAPE]: [{ key: 'escape' }],
-  [Command.SHOW_MORE_LINES]: [
-    { key: 'o', ctrl: true },
-    { key: 's', ctrl: true },
-  ],
+  [Command.SHOW_MORE_LINES]: [{ key: 'o', ctrl: true }],
   [Command.EXPAND_PASTE]: [{ key: 'o', ctrl: true }],
   [Command.FOCUS_SHELL_INPUT]: [{ key: 'tab', shift: false }],
   [Command.UNFOCUS_SHELL_INPUT]: [{ key: 'tab', shift: true }],
@@ -501,7 +498,7 @@ export const commandDescriptions: Readonly<Record<Command, string>> = {
   [Command.CYCLE_APPROVAL_MODE]:
     'Cycle through approval modes: default (prompt), auto_edit (auto-approve edits), and plan (read-only).',
   [Command.SHOW_MORE_LINES]:
-    'Expand a height-constrained response to show additional lines when not in alternate buffer mode.',
+    'Expand and collapse blocks of content when not in alternate buffer mode.',
   [Command.EXPAND_PASTE]:
     'Expand or collapse a paste placeholder when cursor is over placeholder.',
   [Command.BACKGROUND_SHELL_SELECT]:
diff --git a/packages/cli/src/ui/AppContainer.tsx b/packages/cli/src/ui/AppContainer.tsx
index 17e54f4771..1d91d44256 100644
--- a/packages/cli/src/ui/AppContainer.tsx
+++ b/packages/cli/src/ui/AppContainer.tsx
@@ -1620,6 +1620,14 @@ Logging in with Google... Restarting Gemini CLI to continue.
         return true;
       } else if (keyMatchers[Command.SUSPEND_APP](key)) {
         handleSuspend();
+      } else if (
+        keyMatchers[Command.TOGGLE_COPY_MODE](key) &&
+        !isAlternateBuffer
+      ) {
+        showTransientMessage({
+          text: 'Use Ctrl+O to expand and collapse blocks of content.',
+          type: TransientMessageType.Warning,
+        });
         return true;
       }
 
diff --git a/packages/cli/src/ui/keyMatchers.test.ts b/packages/cli/src/ui/keyMatchers.test.ts
index 329549c08d..7a3a077994 100644
--- a/packages/cli/src/ui/keyMatchers.test.ts
+++ b/packages/cli/src/ui/keyMatchers.test.ts
@@ -344,11 +344,12 @@ describe('keyMatchers', () => {
     },
     {
       command: Command.SHOW_MORE_LINES,
-      positive: [
+      positive: [createKey('o', { ctrl: true })],
+      negative: [
         createKey('s', { ctrl: true }),
-        createKey('o', { ctrl: true }),
+        createKey('s'),
+        createKey('l', { ctrl: true }),
       ],
-      negative: [createKey('s'), createKey('l', { ctrl: true })],
     },
 
     // Shell commands

From 5b4884692b436c4e39c4f3fc95f7c9c6c1ed476d Mon Sep 17 00:00:00 2001
From: Philippe <90652303+ppgranger@users.noreply.github.com>
Date: Fri, 13 Feb 2026 01:22:39 +0100
Subject: [PATCH 35/44] fix(vim): vim support that feels (more) complete
 (#18755)

Co-authored-by: Tommaso Sciortino <sciortino@gmail.com>
---
 docs/cli/keyboard-shortcuts.md                |  12 +-
 packages/cli/src/config/keyBindings.ts        |   2 +-
 .../src/ui/components/shared/text-buffer.ts   |  90 ++-
 .../shared/vim-buffer-actions.test.ts         | 538 +++++++++++++++++-
 .../components/shared/vim-buffer-actions.ts   | 362 +++++++++---
 packages/cli/src/ui/hooks/vim.test.tsx        |   4 +
 packages/cli/src/ui/hooks/vim.ts              | 348 ++++++++++-
 7 files changed, 1241 insertions(+), 115 deletions(-)

diff --git a/docs/cli/keyboard-shortcuts.md b/docs/cli/keyboard-shortcuts.md
index ac2705f757..938bc6ff7d 100644
--- a/docs/cli/keyboard-shortcuts.md
+++ b/docs/cli/keyboard-shortcuts.md
@@ -8,12 +8,12 @@ available combinations.
 
 #### Basic Controls
 
-| Action                                                          | Keys       |
-| --------------------------------------------------------------- | ---------- |
-| Confirm the current selection or choice.                        | `Enter`    |
-| Dismiss dialogs or cancel the current focus.                    | `Esc`      |
-| Cancel the current request or quit the CLI when input is empty. | `Ctrl + C` |
-| Exit the CLI when the input buffer is empty.                    | `Ctrl + D` |
+| Action                                                          | Keys                  |
+| --------------------------------------------------------------- | --------------------- |
+| Confirm the current selection or choice.                        | `Enter`               |
+| Dismiss dialogs or cancel the current focus.                    | `Esc`<br />`Ctrl + [` |
+| Cancel the current request or quit the CLI when input is empty. | `Ctrl + C`            |
+| Exit the CLI when the input buffer is empty.                    | `Ctrl + D`            |
 
 #### Cursor Movement
 
diff --git a/packages/cli/src/config/keyBindings.ts b/packages/cli/src/config/keyBindings.ts
index 35e1bb8041..94ceba1858 100644
--- a/packages/cli/src/config/keyBindings.ts
+++ b/packages/cli/src/config/keyBindings.ts
@@ -129,7 +129,7 @@ export type KeyBindingConfig = {
 export const defaultKeyBindings: KeyBindingConfig = {
   // Basic Controls
   [Command.RETURN]: [{ key: 'return' }],
-  [Command.ESCAPE]: [{ key: 'escape' }],
+  [Command.ESCAPE]: [{ key: 'escape' }, { key: '[', ctrl: true }],
   [Command.QUIT]: [{ key: 'c', ctrl: true }],
   [Command.EXIT]: [{ key: 'd', ctrl: true }],
 
diff --git a/packages/cli/src/ui/components/shared/text-buffer.ts b/packages/cli/src/ui/components/shared/text-buffer.ts
index 77edace6c9..d0f425129b 100644
--- a/packages/cli/src/ui/components/shared/text-buffer.ts
+++ b/packages/cli/src/ui/components/shared/text-buffer.ts
@@ -1657,8 +1657,9 @@ export type TextBufferAction =
   | { type: 'vim_change_big_word_end'; payload: { count: number } }
   | { type: 'vim_delete_line'; payload: { count: number } }
   | { type: 'vim_change_line'; payload: { count: number } }
-  | { type: 'vim_delete_to_end_of_line' }
-  | { type: 'vim_change_to_end_of_line' }
+  | { type: 'vim_delete_to_end_of_line'; payload: { count: number } }
+  | { type: 'vim_delete_to_start_of_line' }
+  | { type: 'vim_change_to_end_of_line'; payload: { count: number } }
   | {
       type: 'vim_change_movement';
       payload: { movement: 'h' | 'j' | 'k' | 'l'; count: number };
@@ -1688,6 +1689,11 @@ export type TextBufferAction =
   | { type: 'vim_move_to_last_line' }
   | { type: 'vim_move_to_line'; payload: { lineNumber: number } }
   | { type: 'vim_escape_insert_mode' }
+  | { type: 'vim_delete_to_first_nonwhitespace' }
+  | { type: 'vim_change_to_start_of_line' }
+  | { type: 'vim_change_to_first_nonwhitespace' }
+  | { type: 'vim_delete_to_first_line'; payload: { count: number } }
+  | { type: 'vim_delete_to_last_line'; payload: { count: number } }
   | {
       type: 'toggle_paste_expansion';
       payload: { id: string; row: number; col: number };
@@ -2437,6 +2443,7 @@ function textBufferReducerLogic(
     case 'vim_delete_line':
     case 'vim_change_line':
     case 'vim_delete_to_end_of_line':
+    case 'vim_delete_to_start_of_line':
     case 'vim_change_to_end_of_line':
     case 'vim_change_movement':
     case 'vim_move_left':
@@ -2463,6 +2470,11 @@ function textBufferReducerLogic(
     case 'vim_move_to_last_line':
     case 'vim_move_to_line':
     case 'vim_escape_insert_mode':
+    case 'vim_delete_to_first_nonwhitespace':
+    case 'vim_change_to_start_of_line':
+    case 'vim_change_to_first_nonwhitespace':
+    case 'vim_delete_to_first_line':
+    case 'vim_delete_to_last_line':
       return handleVimAction(state, action as VimAction);
 
     case 'toggle_paste_expansion': {
@@ -2945,12 +2957,36 @@ export function useTextBuffer({
     dispatch({ type: 'vim_change_line', payload: { count } });
   }, []);
 
-  const vimDeleteToEndOfLine = useCallback((): void => {
-    dispatch({ type: 'vim_delete_to_end_of_line' });
+  const vimDeleteToEndOfLine = useCallback((count: number = 1): void => {
+    dispatch({ type: 'vim_delete_to_end_of_line', payload: { count } });
   }, []);
 
-  const vimChangeToEndOfLine = useCallback((): void => {
-    dispatch({ type: 'vim_change_to_end_of_line' });
+  const vimDeleteToStartOfLine = useCallback((): void => {
+    dispatch({ type: 'vim_delete_to_start_of_line' });
+  }, []);
+
+  const vimChangeToEndOfLine = useCallback((count: number = 1): void => {
+    dispatch({ type: 'vim_change_to_end_of_line', payload: { count } });
+  }, []);
+
+  const vimDeleteToFirstNonWhitespace = useCallback((): void => {
+    dispatch({ type: 'vim_delete_to_first_nonwhitespace' });
+  }, []);
+
+  const vimChangeToStartOfLine = useCallback((): void => {
+    dispatch({ type: 'vim_change_to_start_of_line' });
+  }, []);
+
+  const vimChangeToFirstNonWhitespace = useCallback((): void => {
+    dispatch({ type: 'vim_change_to_first_nonwhitespace' });
+  }, []);
+
+  const vimDeleteToFirstLine = useCallback((count: number): void => {
+    dispatch({ type: 'vim_delete_to_first_line', payload: { count } });
+  }, []);
+
+  const vimDeleteToLastLine = useCallback((count: number): void => {
+    dispatch({ type: 'vim_delete_to_last_line', payload: { count } });
   }, []);
 
   const vimChangeMovement = useCallback(
@@ -3510,7 +3546,13 @@ export function useTextBuffer({
       vimDeleteLine,
       vimChangeLine,
       vimDeleteToEndOfLine,
+      vimDeleteToStartOfLine,
       vimChangeToEndOfLine,
+      vimDeleteToFirstNonWhitespace,
+      vimChangeToStartOfLine,
+      vimChangeToFirstNonWhitespace,
+      vimDeleteToFirstLine,
+      vimDeleteToLastLine,
       vimChangeMovement,
       vimMoveLeft,
       vimMoveRight,
@@ -3592,7 +3634,13 @@ export function useTextBuffer({
       vimDeleteLine,
       vimChangeLine,
       vimDeleteToEndOfLine,
+      vimDeleteToStartOfLine,
       vimChangeToEndOfLine,
+      vimDeleteToFirstNonWhitespace,
+      vimChangeToStartOfLine,
+      vimChangeToFirstNonWhitespace,
+      vimDeleteToFirstLine,
+      vimDeleteToLastLine,
       vimChangeMovement,
       vimMoveLeft,
       vimMoveRight,
@@ -3832,12 +3880,38 @@ export interface TextBuffer {
   vimChangeLine: (count: number) => void;
   /**
    * Delete from cursor to end of line (vim 'D' command)
+   * With count > 1, deletes to end of current line plus (count-1) additional lines
    */
-  vimDeleteToEndOfLine: () => void;
+  vimDeleteToEndOfLine: (count?: number) => void;
+  /**
+   * Delete from start of line to cursor (vim 'd0' command)
+   */
+  vimDeleteToStartOfLine: () => void;
   /**
    * Change from cursor to end of line (vim 'C' command)
+   * With count > 1, changes to end of current line plus (count-1) additional lines
    */
-  vimChangeToEndOfLine: () => void;
+  vimChangeToEndOfLine: (count?: number) => void;
+  /**
+   * Delete from cursor to first non-whitespace character (vim 'd^' command)
+   */
+  vimDeleteToFirstNonWhitespace: () => void;
+  /**
+   * Change from cursor to start of line (vim 'c0' command)
+   */
+  vimChangeToStartOfLine: () => void;
+  /**
+   * Change from cursor to first non-whitespace character (vim 'c^' command)
+   */
+  vimChangeToFirstNonWhitespace: () => void;
+  /**
+   * Delete from current line to first line (vim 'dgg' command)
+   */
+  vimDeleteToFirstLine: (count: number) => void;
+  /**
+   * Delete from current line to last line (vim 'dG' command)
+   */
+  vimDeleteToLastLine: (count: number) => void;
   /**
    * Change movement operations (vim 'ch', 'cj', 'ck', 'cl' commands)
    */
diff --git a/packages/cli/src/ui/components/shared/vim-buffer-actions.test.ts b/packages/cli/src/ui/components/shared/vim-buffer-actions.test.ts
index 925a3511e0..9cbfd9457b 100644
--- a/packages/cli/src/ui/components/shared/vim-buffer-actions.test.ts
+++ b/packages/cli/src/ui/components/shared/vim-buffer-actions.test.ts
@@ -469,6 +469,24 @@ describe('vim-buffer-actions', () => {
         expect(result.cursorCol).toBe(3); // Position of 'h'
       });
 
+      it('vim_move_to_first_nonwhitespace should go to column 0 on whitespace-only line', () => {
+        const state = createTestState(['     '], 0, 3);
+        const action = { type: 'vim_move_to_first_nonwhitespace' as const };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.cursorCol).toBe(0);
+      });
+
+      it('vim_move_to_first_nonwhitespace should go to column 0 on empty line', () => {
+        const state = createTestState([''], 0, 0);
+        const action = { type: 'vim_move_to_first_nonwhitespace' as const };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.cursorCol).toBe(0);
+      });
+
       it('vim_move_to_first_line should move to row 0', () => {
         const state = createTestState(['line1', 'line2', 'line3'], 2, 5);
         const action = { type: 'vim_move_to_first_line' as const };
@@ -725,7 +743,10 @@ describe('vim-buffer-actions', () => {
     describe('vim_delete_to_end_of_line', () => {
       it('should delete from cursor to end of line', () => {
         const state = createTestState(['hello world'], 0, 5);
-        const action = { type: 'vim_delete_to_end_of_line' as const };
+        const action = {
+          type: 'vim_delete_to_end_of_line' as const,
+          payload: { count: 1 },
+        };
 
         const result = handleVimAction(state, action);
         expect(result).toHaveOnlyValidCharacters();
@@ -735,12 +756,401 @@ describe('vim-buffer-actions', () => {
 
       it('should do nothing at end of line', () => {
         const state = createTestState(['hello'], 0, 5);
-        const action = { type: 'vim_delete_to_end_of_line' as const };
+        const action = {
+          type: 'vim_delete_to_end_of_line' as const,
+          payload: { count: 1 },
+        };
 
         const result = handleVimAction(state, action);
         expect(result).toHaveOnlyValidCharacters();
         expect(result.lines[0]).toBe('hello');
       });
+
+      it('should delete to end of line plus additional lines with count > 1', () => {
+        const state = createTestState(
+          ['line one', 'line two', 'line three'],
+          0,
+          5,
+        );
+        const action = {
+          type: 'vim_delete_to_end_of_line' as const,
+          payload: { count: 2 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        // 2D at position 5 on "line one" should delete "one" + entire "line two"
+        expect(result.lines).toEqual(['line ', 'line three']);
+        expect(result.cursorCol).toBe(5);
+      });
+
+      it('should handle count exceeding available lines', () => {
+        const state = createTestState(['line one', 'line two'], 0, 5);
+        const action = {
+          type: 'vim_delete_to_end_of_line' as const,
+          payload: { count: 5 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        // Should delete to end of available lines
+        expect(result.lines).toEqual(['line ']);
+      });
+    });
+
+    describe('vim_delete_to_first_nonwhitespace', () => {
+      it('should delete from cursor backwards to first non-whitespace', () => {
+        const state = createTestState(['    hello world'], 0, 10);
+        const action = { type: 'vim_delete_to_first_nonwhitespace' as const };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        // Delete from 'h' (col 4) to cursor (col 10), leaving "    world"
+        expect(result.lines[0]).toBe('    world');
+        expect(result.cursorCol).toBe(4);
+      });
+
+      it('should delete from cursor forwards when cursor is in whitespace', () => {
+        const state = createTestState(['    hello'], 0, 2);
+        const action = { type: 'vim_delete_to_first_nonwhitespace' as const };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        // Delete from cursor (col 2) to first non-ws (col 4), leaving "  hello"
+        expect(result.lines[0]).toBe('  hello');
+        expect(result.cursorCol).toBe(2);
+      });
+
+      it('should do nothing when cursor is at first non-whitespace', () => {
+        const state = createTestState(['    hello'], 0, 4);
+        const action = { type: 'vim_delete_to_first_nonwhitespace' as const };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines[0]).toBe('    hello');
+      });
+
+      it('should delete to column 0 on whitespace-only line', () => {
+        const state = createTestState(['    '], 0, 2);
+        const action = { type: 'vim_delete_to_first_nonwhitespace' as const };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        // On whitespace-only line, ^ goes to col 0, so d^ deletes cols 0-2
+        expect(result.lines[0]).toBe('  ');
+        expect(result.cursorCol).toBe(0);
+      });
+    });
+
+    describe('vim_delete_to_first_line', () => {
+      it('should delete from current line to first line (dgg)', () => {
+        const state = createTestState(
+          ['line1', 'line2', 'line3', 'line4'],
+          2,
+          0,
+        );
+        const action = {
+          type: 'vim_delete_to_first_line' as const,
+          payload: { count: 0 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        // Delete lines 0, 1, 2 (current), leaving line4
+        expect(result.lines).toEqual(['line4']);
+        expect(result.cursorRow).toBe(0);
+      });
+
+      it('should delete from current line to specified line (d5gg)', () => {
+        const state = createTestState(
+          ['line1', 'line2', 'line3', 'line4', 'line5'],
+          4,
+          0,
+        );
+        const action = {
+          type: 'vim_delete_to_first_line' as const,
+          payload: { count: 2 }, // Delete to line 2 (1-based)
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        // Delete lines 1-4 (line2 to line5), leaving line1
+        expect(result.lines).toEqual(['line1']);
+        expect(result.cursorRow).toBe(0);
+      });
+
+      it('should keep one empty line when deleting all lines', () => {
+        const state = createTestState(['line1', 'line2'], 1, 0);
+        const action = {
+          type: 'vim_delete_to_first_line' as const,
+          payload: { count: 0 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['']);
+      });
+    });
+
+    describe('vim_delete_to_last_line', () => {
+      it('should delete from current line to last line (dG)', () => {
+        const state = createTestState(
+          ['line1', 'line2', 'line3', 'line4'],
+          1,
+          0,
+        );
+        const action = {
+          type: 'vim_delete_to_last_line' as const,
+          payload: { count: 0 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        // Delete lines 1, 2, 3 (from current to last), leaving line1
+        expect(result.lines).toEqual(['line1']);
+        expect(result.cursorRow).toBe(0);
+      });
+
+      it('should delete from current line to specified line (d3G)', () => {
+        const state = createTestState(
+          ['line1', 'line2', 'line3', 'line4', 'line5'],
+          0,
+          0,
+        );
+        const action = {
+          type: 'vim_delete_to_last_line' as const,
+          payload: { count: 3 }, // Delete to line 3 (1-based)
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        // Delete lines 0-2 (line1 to line3), leaving line4 and line5
+        expect(result.lines).toEqual(['line4', 'line5']);
+        expect(result.cursorRow).toBe(0);
+      });
+
+      it('should keep one empty line when deleting all lines', () => {
+        const state = createTestState(['line1', 'line2'], 0, 0);
+        const action = {
+          type: 'vim_delete_to_last_line' as const,
+          payload: { count: 0 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['']);
+      });
+    });
+
+    describe('vim_change_to_start_of_line', () => {
+      it('should delete from start of line to cursor (c0)', () => {
+        const state = createTestState(['hello world'], 0, 6);
+        const action = { type: 'vim_change_to_start_of_line' as const };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines[0]).toBe('world');
+        expect(result.cursorCol).toBe(0);
+      });
+
+      it('should do nothing at start of line', () => {
+        const state = createTestState(['hello'], 0, 0);
+        const action = { type: 'vim_change_to_start_of_line' as const };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines[0]).toBe('hello');
+      });
+    });
+
+    describe('vim_change_to_first_nonwhitespace', () => {
+      it('should delete from first non-whitespace to cursor (c^)', () => {
+        const state = createTestState(['    hello world'], 0, 10);
+        const action = { type: 'vim_change_to_first_nonwhitespace' as const };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines[0]).toBe('    world');
+        expect(result.cursorCol).toBe(4);
+      });
+
+      it('should delete backwards when cursor before first non-whitespace', () => {
+        const state = createTestState(['    hello'], 0, 2);
+        const action = { type: 'vim_change_to_first_nonwhitespace' as const };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines[0]).toBe('  hello');
+        expect(result.cursorCol).toBe(2);
+      });
+
+      it('should handle whitespace-only line', () => {
+        const state = createTestState(['     '], 0, 3);
+        const action = { type: 'vim_change_to_first_nonwhitespace' as const };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines[0]).toBe('  ');
+        expect(result.cursorCol).toBe(0);
+      });
+    });
+
+    describe('vim_change_to_end_of_line', () => {
+      it('should delete from cursor to end of line (C)', () => {
+        const state = createTestState(['hello world'], 0, 6);
+        const action = {
+          type: 'vim_change_to_end_of_line' as const,
+          payload: { count: 1 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines[0]).toBe('hello ');
+        expect(result.cursorCol).toBe(6);
+      });
+
+      it('should delete multiple lines with count (2C)', () => {
+        const state = createTestState(['line1 hello', 'line2', 'line3'], 0, 6);
+        const action = {
+          type: 'vim_change_to_end_of_line' as const,
+          payload: { count: 2 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['line1 ', 'line3']);
+        expect(result.cursorRow).toBe(0);
+        expect(result.cursorCol).toBe(6);
+      });
+
+      it('should delete remaining lines when count exceeds available (3C on 2 lines)', () => {
+        const state = createTestState(['hello world', 'end'], 0, 6);
+        const action = {
+          type: 'vim_change_to_end_of_line' as const,
+          payload: { count: 3 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['hello ']);
+        expect(result.cursorCol).toBe(6);
+      });
+
+      it('should handle count at last line', () => {
+        const state = createTestState(['first', 'last line'], 1, 5);
+        const action = {
+          type: 'vim_change_to_end_of_line' as const,
+          payload: { count: 2 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['first', 'last ']);
+        expect(result.cursorRow).toBe(1);
+        expect(result.cursorCol).toBe(5);
+      });
+    });
+
+    describe('vim_change_to_first_line', () => {
+      it('should delete from first line to current line (cgg)', () => {
+        const state = createTestState(['line1', 'line2', 'line3'], 2, 3);
+        const action = {
+          type: 'vim_delete_to_first_line' as const,
+          payload: { count: 0 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['']);
+        expect(result.cursorRow).toBe(0);
+      });
+
+      it('should delete from line 1 to target line (c3gg)', () => {
+        const state = createTestState(
+          ['line1', 'line2', 'line3', 'line4', 'line5'],
+          0,
+          0,
+        );
+        const action = {
+          type: 'vim_delete_to_first_line' as const,
+          payload: { count: 3 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['line4', 'line5']);
+        expect(result.cursorRow).toBe(0);
+      });
+
+      it('should handle cursor below target line', () => {
+        // Cursor on line 4 (index 3), target line 2 (index 1)
+        // Should delete lines 2-4 (indices 1-3), leaving line1 and line5
+        const state = createTestState(
+          ['line1', 'line2', 'line3', 'line4', 'line5'],
+          3,
+          0,
+        );
+        const action = {
+          type: 'vim_delete_to_first_line' as const,
+          payload: { count: 2 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['line1', 'line5']);
+        expect(result.cursorRow).toBe(1);
+      });
+    });
+
+    describe('vim_change_to_last_line', () => {
+      it('should delete from current line to last line (cG)', () => {
+        const state = createTestState(['line1', 'line2', 'line3'], 0, 3);
+        const action = {
+          type: 'vim_delete_to_last_line' as const,
+          payload: { count: 0 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['']);
+        expect(result.cursorRow).toBe(0);
+      });
+
+      it('should delete from cursor to target line (c2G)', () => {
+        const state = createTestState(
+          ['line1', 'line2', 'line3', 'line4'],
+          0,
+          0,
+        );
+        const action = {
+          type: 'vim_delete_to_last_line' as const,
+          payload: { count: 2 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['line3', 'line4']);
+        expect(result.cursorRow).toBe(0);
+      });
+
+      it('should handle cursor above target', () => {
+        // Cursor on line 2 (index 1), target line 3 (index 2)
+        // Should delete lines 2-3 (indices 1-2), leaving line1 and line4
+        const state = createTestState(
+          ['line1', 'line2', 'line3', 'line4'],
+          1,
+          0,
+        );
+        const action = {
+          type: 'vim_delete_to_last_line' as const,
+          payload: { count: 3 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['line1', 'line4']);
+        expect(result.cursorRow).toBe(1);
+      });
     });
   });
 
@@ -922,11 +1332,127 @@ describe('vim-buffer-actions', () => {
 
         const result = handleVimAction(state, action);
         expect(result).toHaveOnlyValidCharacters();
-        // The movement 'j' with count 2 changes 2 lines starting from cursor row
-        // Since we're at cursor position 2, it changes lines starting from current row
-        expect(result.lines).toEqual(['line1', 'line2', 'line3']); // No change because count > available lines
+        // In VIM, 2cj deletes current line + 2 lines below = 3 lines total
+        // Since there are exactly 3 lines, all are deleted
+        expect(result.lines).toEqual(['']);
         expect(result.cursorRow).toBe(0);
-        expect(result.cursorCol).toBe(2);
+        expect(result.cursorCol).toBe(0);
+      });
+
+      it('should handle Unicode characters in cj (down)', () => {
+        const state = createTestState(
+          ['hello 🎉 world', 'line2 émoji', 'line3'],
+          0,
+          0,
+        );
+        const action = {
+          type: 'vim_change_movement' as const,
+          payload: { movement: 'j' as const, count: 1 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['line3']);
+        expect(result.cursorRow).toBe(0);
+        expect(result.cursorCol).toBe(0);
+      });
+
+      it('should handle Unicode characters in ck (up)', () => {
+        const state = createTestState(
+          ['line1', 'hello 🎉 world', 'line3 émoji'],
+          2,
+          0,
+        );
+        const action = {
+          type: 'vim_change_movement' as const,
+          payload: { movement: 'k' as const, count: 1 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['line1']);
+        expect(result.cursorRow).toBe(0);
+        expect(result.cursorCol).toBe(0);
+      });
+
+      it('should handle cj on first line of 2 lines (delete all)', () => {
+        const state = createTestState(['line1', 'line2'], 0, 0);
+        const action = {
+          type: 'vim_change_movement' as const,
+          payload: { movement: 'j' as const, count: 1 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['']);
+        expect(result.cursorRow).toBe(0);
+        expect(result.cursorCol).toBe(0);
+      });
+
+      it('should handle cj on last line (delete only current line)', () => {
+        const state = createTestState(['line1', 'line2', 'line3'], 2, 0);
+        const action = {
+          type: 'vim_change_movement' as const,
+          payload: { movement: 'j' as const, count: 1 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['line1', 'line2']);
+        expect(result.cursorRow).toBe(1);
+        expect(result.cursorCol).toBe(0);
+      });
+
+      it('should handle ck on first line (delete only current line)', () => {
+        const state = createTestState(['line1', 'line2', 'line3'], 0, 0);
+        const action = {
+          type: 'vim_change_movement' as const,
+          payload: { movement: 'k' as const, count: 1 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        expect(result.lines).toEqual(['line2', 'line3']);
+        expect(result.cursorRow).toBe(0);
+        expect(result.cursorCol).toBe(0);
+      });
+
+      it('should handle 2cj from middle line', () => {
+        const state = createTestState(
+          ['line1', 'line2', 'line3', 'line4', 'line5'],
+          1,
+          0,
+        );
+        const action = {
+          type: 'vim_change_movement' as const,
+          payload: { movement: 'j' as const, count: 2 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        // 2cj from line 1: delete lines 1, 2, 3 (current + 2 below)
+        expect(result.lines).toEqual(['line1', 'line5']);
+        expect(result.cursorRow).toBe(1);
+        expect(result.cursorCol).toBe(0);
+      });
+
+      it('should handle 2ck from middle line', () => {
+        const state = createTestState(
+          ['line1', 'line2', 'line3', 'line4', 'line5'],
+          3,
+          0,
+        );
+        const action = {
+          type: 'vim_change_movement' as const,
+          payload: { movement: 'k' as const, count: 2 },
+        };
+
+        const result = handleVimAction(state, action);
+        expect(result).toHaveOnlyValidCharacters();
+        // 2ck from line 3: delete lines 1, 2, 3 (current + 2 above)
+        expect(result.lines).toEqual(['line1', 'line5']);
+        expect(result.cursorRow).toBe(1);
+        expect(result.cursorCol).toBe(0);
       });
     });
   });
diff --git a/packages/cli/src/ui/components/shared/vim-buffer-actions.ts b/packages/cli/src/ui/components/shared/vim-buffer-actions.ts
index 1018199474..1479f6c3c3 100644
--- a/packages/cli/src/ui/components/shared/vim-buffer-actions.ts
+++ b/packages/cli/src/ui/components/shared/vim-buffer-actions.ts
@@ -39,7 +39,13 @@ export type VimAction = Extract<
   | { type: 'vim_delete_line' }
   | { type: 'vim_change_line' }
   | { type: 'vim_delete_to_end_of_line' }
+  | { type: 'vim_delete_to_start_of_line' }
+  | { type: 'vim_delete_to_first_nonwhitespace' }
   | { type: 'vim_change_to_end_of_line' }
+  | { type: 'vim_change_to_start_of_line' }
+  | { type: 'vim_change_to_first_nonwhitespace' }
+  | { type: 'vim_delete_to_first_line' }
+  | { type: 'vim_delete_to_last_line' }
   | { type: 'vim_change_movement' }
   | { type: 'vim_move_left' }
   | { type: 'vim_move_right' }
@@ -387,21 +393,253 @@ export function handleVimAction(
 
     case 'vim_delete_to_end_of_line':
     case 'vim_change_to_end_of_line': {
+      const { count } = action.payload;
       const currentLine = lines[cursorRow] || '';
-      if (cursorCol < cpLen(currentLine)) {
+      const totalLines = lines.length;
+
+      if (count === 1) {
+        // Single line: delete from cursor to end of current line
+        if (cursorCol < cpLen(currentLine)) {
+          const nextState = detachExpandedPaste(pushUndo(state));
+          return replaceRangeInternal(
+            nextState,
+            cursorRow,
+            cursorCol,
+            cursorRow,
+            cpLen(currentLine),
+            '',
+          );
+        }
+        return state;
+      } else {
+        // Multi-line: delete from cursor to end of current line, plus (count-1) entire lines below
+        // For example, 2D = delete to EOL + delete next line entirely
+        const linesToDelete = Math.min(count - 1, totalLines - cursorRow - 1);
+        const endRow = cursorRow + linesToDelete;
+
+        if (endRow === cursorRow) {
+          // No additional lines to delete, just delete to EOL
+          if (cursorCol < cpLen(currentLine)) {
+            const nextState = detachExpandedPaste(pushUndo(state));
+            return replaceRangeInternal(
+              nextState,
+              cursorRow,
+              cursorCol,
+              cursorRow,
+              cpLen(currentLine),
+              '',
+            );
+          }
+          return state;
+        }
+
+        // Delete from cursor position to end of endRow (including newlines)
         const nextState = detachExpandedPaste(pushUndo(state));
+        const endLine = lines[endRow] || '';
         return replaceRangeInternal(
           nextState,
           cursorRow,
           cursorCol,
+          endRow,
+          cpLen(endLine),
+          '',
+        );
+      }
+    }
+
+    case 'vim_delete_to_start_of_line': {
+      if (cursorCol > 0) {
+        const nextState = detachExpandedPaste(pushUndo(state));
+        return replaceRangeInternal(
+          nextState,
           cursorRow,
-          cpLen(currentLine),
+          0,
+          cursorRow,
+          cursorCol,
           '',
         );
       }
       return state;
     }
 
+    case 'vim_delete_to_first_nonwhitespace': {
+      // Delete from cursor to first non-whitespace character (vim 'd^')
+      const currentLine = lines[cursorRow] || '';
+      const lineCodePoints = toCodePoints(currentLine);
+      let firstNonWs = 0;
+      while (
+        firstNonWs < lineCodePoints.length &&
+        /\s/.test(lineCodePoints[firstNonWs])
+      ) {
+        firstNonWs++;
+      }
+      // If line is all whitespace, firstNonWs would be lineCodePoints.length
+      // In VIM, ^ on whitespace-only line goes to column 0
+      if (firstNonWs >= lineCodePoints.length) {
+        firstNonWs = 0;
+      }
+      // Delete between cursor and first non-whitespace (whichever direction)
+      if (cursorCol !== firstNonWs) {
+        const startCol = Math.min(cursorCol, firstNonWs);
+        const endCol = Math.max(cursorCol, firstNonWs);
+        const nextState = detachExpandedPaste(pushUndo(state));
+        return replaceRangeInternal(
+          nextState,
+          cursorRow,
+          startCol,
+          cursorRow,
+          endCol,
+          '',
+        );
+      }
+      return state;
+    }
+
+    case 'vim_change_to_start_of_line': {
+      // Change from cursor to start of line (vim 'c0')
+      if (cursorCol > 0) {
+        const nextState = detachExpandedPaste(pushUndo(state));
+        return replaceRangeInternal(
+          nextState,
+          cursorRow,
+          0,
+          cursorRow,
+          cursorCol,
+          '',
+        );
+      }
+      return state;
+    }
+
+    case 'vim_change_to_first_nonwhitespace': {
+      // Change from cursor to first non-whitespace character (vim 'c^')
+      const currentLine = lines[cursorRow] || '';
+      const lineCodePoints = toCodePoints(currentLine);
+      let firstNonWs = 0;
+      while (
+        firstNonWs < lineCodePoints.length &&
+        /\s/.test(lineCodePoints[firstNonWs])
+      ) {
+        firstNonWs++;
+      }
+      // If line is all whitespace, firstNonWs would be lineCodePoints.length
+      // In VIM, ^ on whitespace-only line goes to column 0
+      if (firstNonWs >= lineCodePoints.length) {
+        firstNonWs = 0;
+      }
+      // Change between cursor and first non-whitespace (whichever direction)
+      if (cursorCol !== firstNonWs) {
+        const startCol = Math.min(cursorCol, firstNonWs);
+        const endCol = Math.max(cursorCol, firstNonWs);
+        const nextState = detachExpandedPaste(pushUndo(state));
+        return replaceRangeInternal(
+          nextState,
+          cursorRow,
+          startCol,
+          cursorRow,
+          endCol,
+          '',
+        );
+      }
+      return state;
+    }
+
+    case 'vim_delete_to_first_line': {
+      // Delete from first line (or line N if count given) to current line (vim 'dgg' or 'd5gg')
+      // count is the target line number (1-based), or 0 for first line
+      const { count } = action.payload;
+      const totalLines = lines.length;
+
+      // Determine target row (0-based)
+      // count=0 means go to first line, count=N means go to line N (1-based)
+      let targetRow: number;
+      if (count > 0) {
+        targetRow = Math.min(count - 1, totalLines - 1);
+      } else {
+        targetRow = 0;
+      }
+
+      // Determine the range to delete (from min to max row, inclusive)
+      const startRow = Math.min(cursorRow, targetRow);
+      const endRow = Math.max(cursorRow, targetRow);
+      const linesToDelete = endRow - startRow + 1;
+
+      if (linesToDelete >= totalLines) {
+        // Deleting all lines - keep one empty line
+        const nextState = detachExpandedPaste(pushUndo(state));
+        return {
+          ...nextState,
+          lines: [''],
+          cursorRow: 0,
+          cursorCol: 0,
+          preferredCol: null,
+        };
+      }
+
+      const nextState = detachExpandedPaste(pushUndo(state));
+      const newLines = [...nextState.lines];
+      newLines.splice(startRow, linesToDelete);
+
+      // Cursor goes to start of the deleted range, clamped to valid bounds
+      const newCursorRow = Math.min(startRow, newLines.length - 1);
+
+      return {
+        ...nextState,
+        lines: newLines,
+        cursorRow: newCursorRow,
+        cursorCol: 0,
+        preferredCol: null,
+      };
+    }
+
+    case 'vim_delete_to_last_line': {
+      // Delete from current line to last line (vim 'dG') or to line N (vim 'd5G')
+      // count is the target line number (1-based), or 0 for last line
+      const { count } = action.payload;
+      const totalLines = lines.length;
+
+      // Determine target row (0-based)
+      // count=0 means go to last line, count=N means go to line N (1-based)
+      let targetRow: number;
+      if (count > 0) {
+        targetRow = Math.min(count - 1, totalLines - 1);
+      } else {
+        targetRow = totalLines - 1;
+      }
+
+      // Determine the range to delete (from min to max row, inclusive)
+      const startRow = Math.min(cursorRow, targetRow);
+      const endRow = Math.max(cursorRow, targetRow);
+      const linesToDelete = endRow - startRow + 1;
+
+      if (linesToDelete >= totalLines) {
+        // Deleting all lines - keep one empty line
+        const nextState = detachExpandedPaste(pushUndo(state));
+        return {
+          ...nextState,
+          lines: [''],
+          cursorRow: 0,
+          cursorCol: 0,
+          preferredCol: null,
+        };
+      }
+
+      const nextState = detachExpandedPaste(pushUndo(state));
+      const newLines = [...nextState.lines];
+      newLines.splice(startRow, linesToDelete);
+
+      // Move cursor to the start of the deleted range (or last line if needed)
+      const newCursorRow = Math.min(startRow, newLines.length - 1);
+
+      return {
+        ...nextState,
+        lines: newLines,
+        cursorRow: newCursorRow,
+        cursorCol: 0,
+        preferredCol: null,
+      };
+    }
+
     case 'vim_change_movement': {
       const { movement, count } = action.payload;
       const totalLines = lines.length;
@@ -422,88 +660,65 @@ export function handleVimAction(
         }
 
         case 'j': {
-          // Down
-          const linesToChange = Math.min(count, totalLines - cursorRow);
+          // Down - delete/change current line + count lines below
+          const linesToChange = Math.min(count + 1, totalLines - cursorRow);
           if (linesToChange > 0) {
-            if (totalLines === 1) {
-              const currentLine = state.lines[0] || '';
-              return replaceRangeInternal(
-                detachExpandedPaste(pushUndo(state)),
-                0,
-                0,
-                0,
-                cpLen(currentLine),
-                '',
-              );
-            } else {
+            if (linesToChange >= totalLines) {
+              // Deleting all lines - keep one empty line
               const nextState = detachExpandedPaste(pushUndo(state));
-              const { startOffset, endOffset } = getLineRangeOffsets(
-                cursorRow,
-                linesToChange,
-                nextState.lines,
-              );
-              const { startRow, startCol, endRow, endCol } =
-                getPositionFromOffsets(startOffset, endOffset, nextState.lines);
-              return replaceRangeInternal(
-                nextState,
-                startRow,
-                startCol,
-                endRow,
-                endCol,
-                '',
-              );
+              return {
+                ...nextState,
+                lines: [''],
+                cursorRow: 0,
+                cursorCol: 0,
+                preferredCol: null,
+              };
             }
+
+            const nextState = detachExpandedPaste(pushUndo(state));
+            const newLines = [...nextState.lines];
+            newLines.splice(cursorRow, linesToChange);
+
+            return {
+              ...nextState,
+              lines: newLines,
+              cursorRow: Math.min(cursorRow, newLines.length - 1),
+              cursorCol: 0,
+              preferredCol: null,
+            };
           }
           return state;
         }
 
         case 'k': {
-          // Up
-          const upLines = Math.min(count, cursorRow + 1);
-          if (upLines > 0) {
-            if (state.lines.length === 1) {
-              const currentLine = state.lines[0] || '';
-              return replaceRangeInternal(
-                detachExpandedPaste(pushUndo(state)),
-                0,
-                0,
-                0,
-                cpLen(currentLine),
-                '',
-              );
-            } else {
-              const startRow = Math.max(0, cursorRow - count + 1);
-              const linesToChange = cursorRow - startRow + 1;
+          // Up - delete/change current line + count lines above
+          const startRow = Math.max(0, cursorRow - count);
+          const linesToChange = cursorRow - startRow + 1;
+
+          if (linesToChange > 0) {
+            if (linesToChange >= totalLines) {
+              // Deleting all lines - keep one empty line
               const nextState = detachExpandedPaste(pushUndo(state));
-              const { startOffset, endOffset } = getLineRangeOffsets(
-                startRow,
-                linesToChange,
-                nextState.lines,
-              );
-              const {
-                startRow: newStartRow,
-                startCol,
-                endRow,
-                endCol,
-              } = getPositionFromOffsets(
-                startOffset,
-                endOffset,
-                nextState.lines,
-              );
-              const resultState = replaceRangeInternal(
-                nextState,
-                newStartRow,
-                startCol,
-                endRow,
-                endCol,
-                '',
-              );
               return {
-                ...resultState,
-                cursorRow: startRow,
+                ...nextState,
+                lines: [''],
+                cursorRow: 0,
                 cursorCol: 0,
+                preferredCol: null,
               };
             }
+
+            const nextState = detachExpandedPaste(pushUndo(state));
+            const newLines = [...nextState.lines];
+            newLines.splice(startRow, linesToChange);
+
+            return {
+              ...nextState,
+              lines: newLines,
+              cursorRow: Math.min(startRow, newLines.length - 1),
+              cursorCol: 0,
+              preferredCol: null,
+            };
           }
           return state;
         }
@@ -910,6 +1125,11 @@ export function handleVimAction(
         col++;
       }
 
+      // If line is all whitespace or empty, ^ goes to column 0 (standard Vim behavior)
+      if (col >= lineCodePoints.length) {
+        col = 0;
+      }
+
       return {
         ...state,
         cursorCol: col,
diff --git a/packages/cli/src/ui/hooks/vim.test.tsx b/packages/cli/src/ui/hooks/vim.test.tsx
index 5a5ca6a858..7b03354eae 100644
--- a/packages/cli/src/ui/hooks/vim.test.tsx
+++ b/packages/cli/src/ui/hooks/vim.test.tsx
@@ -1708,6 +1708,7 @@ describe('useVim hook', () => {
         cursorRow: 0,
         cursorCol: 6,
         actionType: 'vim_delete_to_end_of_line' as const,
+        count: 1,
         expectedLines: ['hello '],
         expectedCursorRow: 0,
         expectedCursorCol: 6,
@@ -1719,6 +1720,7 @@ describe('useVim hook', () => {
         cursorRow: 0,
         cursorCol: 11,
         actionType: 'vim_delete_to_end_of_line' as const,
+        count: 1,
         expectedLines: ['hello world'],
         expectedCursorRow: 0,
         expectedCursorCol: 11,
@@ -1730,6 +1732,7 @@ describe('useVim hook', () => {
         cursorRow: 0,
         cursorCol: 6,
         actionType: 'vim_change_to_end_of_line' as const,
+        count: 1,
         expectedLines: ['hello '],
         expectedCursorRow: 0,
         expectedCursorCol: 6,
@@ -1741,6 +1744,7 @@ describe('useVim hook', () => {
         cursorRow: 0,
         cursorCol: 0,
         actionType: 'vim_change_to_end_of_line' as const,
+        count: 1,
         expectedLines: [''],
         expectedCursorRow: 0,
         expectedCursorCol: 0,
diff --git a/packages/cli/src/ui/hooks/vim.ts b/packages/cli/src/ui/hooks/vim.ts
index bf91ba062b..9de771564c 100644
--- a/packages/cli/src/ui/hooks/vim.ts
+++ b/packages/cli/src/ui/hooks/vim.ts
@@ -44,19 +44,33 @@ const CMD_TYPES = {
     UP: 'ck',
     RIGHT: 'cl',
   },
+  DELETE_MOVEMENT: {
+    LEFT: 'dh',
+    DOWN: 'dj',
+    UP: 'dk',
+    RIGHT: 'dl',
+  },
+  DELETE_TO_SOL: 'd0',
+  DELETE_TO_FIRST_NONWS: 'd^',
+  CHANGE_TO_SOL: 'c0',
+  CHANGE_TO_FIRST_NONWS: 'c^',
+  DELETE_TO_FIRST_LINE: 'dgg',
+  DELETE_TO_LAST_LINE: 'dG',
+  CHANGE_TO_FIRST_LINE: 'cgg',
+  CHANGE_TO_LAST_LINE: 'cG',
 } as const;
 
 // Helper function to clear pending state
 const createClearPendingState = () => ({
   count: 0,
-  pendingOperator: null as 'g' | 'd' | 'c' | null,
+  pendingOperator: null as 'g' | 'd' | 'c' | 'dg' | 'cg' | null,
 });
 
 // State and action types for useReducer
 type VimState = {
   mode: VimMode;
   count: number;
-  pendingOperator: 'g' | 'd' | 'c' | null;
+  pendingOperator: 'g' | 'd' | 'c' | 'dg' | 'cg' | null;
   lastCommand: { type: string; count: number } | null;
 };
 
@@ -65,7 +79,10 @@ type VimAction =
   | { type: 'SET_COUNT'; count: number }
   | { type: 'INCREMENT_COUNT'; digit: number }
   | { type: 'CLEAR_COUNT' }
-  | { type: 'SET_PENDING_OPERATOR'; operator: 'g' | 'd' | 'c' | null }
+  | {
+      type: 'SET_PENDING_OPERATOR';
+      operator: 'g' | 'd' | 'c' | 'dg' | 'cg' | null;
+    }
   | {
       type: 'SET_LAST_COMMAND';
       command: { type: string; count: number } | null;
@@ -279,12 +296,73 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
         }
 
         case CMD_TYPES.DELETE_TO_EOL: {
-          buffer.vimDeleteToEndOfLine();
+          buffer.vimDeleteToEndOfLine(count);
+          break;
+        }
+
+        case CMD_TYPES.DELETE_TO_SOL: {
+          buffer.vimDeleteToStartOfLine();
+          break;
+        }
+
+        case CMD_TYPES.DELETE_MOVEMENT.LEFT:
+        case CMD_TYPES.DELETE_MOVEMENT.DOWN:
+        case CMD_TYPES.DELETE_MOVEMENT.UP:
+        case CMD_TYPES.DELETE_MOVEMENT.RIGHT: {
+          const movementMap: Record<string, 'h' | 'j' | 'k' | 'l'> = {
+            [CMD_TYPES.DELETE_MOVEMENT.LEFT]: 'h',
+            [CMD_TYPES.DELETE_MOVEMENT.DOWN]: 'j',
+            [CMD_TYPES.DELETE_MOVEMENT.UP]: 'k',
+            [CMD_TYPES.DELETE_MOVEMENT.RIGHT]: 'l',
+          };
+          const movementType = movementMap[cmdType];
+          if (movementType) {
+            buffer.vimChangeMovement(movementType, count);
+          }
           break;
         }
 
         case CMD_TYPES.CHANGE_TO_EOL: {
-          buffer.vimChangeToEndOfLine();
+          buffer.vimChangeToEndOfLine(count);
+          updateMode('INSERT');
+          break;
+        }
+
+        case CMD_TYPES.DELETE_TO_FIRST_NONWS: {
+          buffer.vimDeleteToFirstNonWhitespace();
+          break;
+        }
+
+        case CMD_TYPES.CHANGE_TO_SOL: {
+          buffer.vimChangeToStartOfLine();
+          updateMode('INSERT');
+          break;
+        }
+
+        case CMD_TYPES.CHANGE_TO_FIRST_NONWS: {
+          buffer.vimChangeToFirstNonWhitespace();
+          updateMode('INSERT');
+          break;
+        }
+
+        case CMD_TYPES.DELETE_TO_FIRST_LINE: {
+          buffer.vimDeleteToFirstLine(count);
+          break;
+        }
+
+        case CMD_TYPES.DELETE_TO_LAST_LINE: {
+          buffer.vimDeleteToLastLine(count);
+          break;
+        }
+
+        case CMD_TYPES.CHANGE_TO_FIRST_LINE: {
+          buffer.vimDeleteToFirstLine(count);
+          updateMode('INSERT');
+          break;
+        }
+
+        case CMD_TYPES.CHANGE_TO_LAST_LINE: {
+          buffer.vimDeleteToLastLine(count);
           updateMode('INSERT');
           break;
         }
@@ -324,6 +402,14 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
         return false; // Let InputPrompt handle completion
       }
 
+      // Let InputPrompt handle Ctrl+U (kill line left) and Ctrl+K (kill line right)
+      if (
+        normalizedKey.ctrl &&
+        (normalizedKey.name === 'u' || normalizedKey.name === 'k')
+      ) {
+        return false;
+      }
+
       // Let InputPrompt handle Ctrl+V for clipboard image pasting
       if (normalizedKey.ctrl && normalizedKey.name === 'v') {
         return false; // Let InputPrompt handle clipboard functionality
@@ -403,6 +489,37 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
     [getCurrentCount, dispatch, buffer, updateMode],
   );
 
+  /**
+   * Handles delete movement commands (dh, dj, dk, dl)
+   * @param movement - The movement direction
+   * @returns boolean indicating if command was handled
+   */
+  const handleDeleteMovement = useCallback(
+    (movement: 'h' | 'j' | 'k' | 'l'): boolean => {
+      const count = getCurrentCount();
+      dispatch({ type: 'CLEAR_COUNT' });
+      // Note: vimChangeMovement performs the same deletion operation as what we need.
+      // The only difference between 'change' and 'delete' is that 'change' enters
+      // INSERT mode after deletion, which is handled here (we simply don't call updateMode).
+      buffer.vimChangeMovement(movement, count);
+
+      const cmdTypeMap = {
+        h: CMD_TYPES.DELETE_MOVEMENT.LEFT,
+        j: CMD_TYPES.DELETE_MOVEMENT.DOWN,
+        k: CMD_TYPES.DELETE_MOVEMENT.UP,
+        l: CMD_TYPES.DELETE_MOVEMENT.RIGHT,
+      };
+
+      dispatch({
+        type: 'SET_LAST_COMMAND',
+        command: { type: cmdTypeMap[movement], count },
+      });
+      dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+      return true;
+    },
+    [getCurrentCount, dispatch, buffer],
+  );
+
   /**
    * Handles operator-motion commands (dw/cw, db/cb, de/ce)
    * @param operator - The operator type ('d' for delete, 'c' for change)
@@ -510,7 +627,10 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
 
         switch (normalizedKey.sequence) {
           case 'h': {
-            // Check if this is part of a change command (ch)
+            // Check if this is part of a delete or change command (dh/ch)
+            if (state.pendingOperator === 'd') {
+              return handleDeleteMovement('h');
+            }
             if (state.pendingOperator === 'c') {
               return handleChangeMovement('h');
             }
@@ -522,7 +642,10 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
           }
 
           case 'j': {
-            // Check if this is part of a change command (cj)
+            // Check if this is part of a delete or change command (dj/cj)
+            if (state.pendingOperator === 'd') {
+              return handleDeleteMovement('j');
+            }
             if (state.pendingOperator === 'c') {
               return handleChangeMovement('j');
             }
@@ -534,7 +657,10 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
           }
 
           case 'k': {
-            // Check if this is part of a change command (ck)
+            // Check if this is part of a delete or change command (dk/ck)
+            if (state.pendingOperator === 'd') {
+              return handleDeleteMovement('k');
+            }
             if (state.pendingOperator === 'c') {
               return handleChangeMovement('k');
             }
@@ -546,7 +672,10 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
           }
 
           case 'l': {
-            // Check if this is part of a change command (cl)
+            // Check if this is part of a delete or change command (dl/cl)
+            if (state.pendingOperator === 'd') {
+              return handleDeleteMovement('l');
+            }
             if (state.pendingOperator === 'c') {
               return handleChangeMovement('l');
             }
@@ -691,6 +820,30 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
           }
 
           case '0': {
+            // Check if this is part of a delete command (d0)
+            if (state.pendingOperator === 'd') {
+              buffer.vimDeleteToStartOfLine();
+              dispatch({
+                type: 'SET_LAST_COMMAND',
+                command: { type: CMD_TYPES.DELETE_TO_SOL, count: 1 },
+              });
+              dispatch({ type: 'CLEAR_COUNT' });
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+              return true;
+            }
+            // Check if this is part of a change command (c0)
+            if (state.pendingOperator === 'c') {
+              buffer.vimChangeToStartOfLine();
+              dispatch({
+                type: 'SET_LAST_COMMAND',
+                command: { type: CMD_TYPES.CHANGE_TO_SOL, count: 1 },
+              });
+              dispatch({ type: 'CLEAR_COUNT' });
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+              updateMode('INSERT');
+              return true;
+            }
+
             // Move to start of line
             buffer.vimMoveToLineStart();
             dispatch({ type: 'CLEAR_COUNT' });
@@ -698,13 +851,64 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
           }
 
           case '$': {
-            // Move to end of line
+            // Check if this is part of a delete command (d$)
+            if (state.pendingOperator === 'd') {
+              buffer.vimDeleteToEndOfLine(repeatCount);
+              dispatch({
+                type: 'SET_LAST_COMMAND',
+                command: { type: CMD_TYPES.DELETE_TO_EOL, count: repeatCount },
+              });
+              dispatch({ type: 'CLEAR_COUNT' });
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+              return true;
+            }
+            // Check if this is part of a change command (c$)
+            if (state.pendingOperator === 'c') {
+              buffer.vimChangeToEndOfLine(repeatCount);
+              dispatch({
+                type: 'SET_LAST_COMMAND',
+                command: { type: CMD_TYPES.CHANGE_TO_EOL, count: repeatCount },
+              });
+              dispatch({ type: 'CLEAR_COUNT' });
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+              updateMode('INSERT');
+              return true;
+            }
+
+            // Move to end of line (with count, move down count-1 lines first)
+            if (repeatCount > 1) {
+              buffer.vimMoveDown(repeatCount - 1);
+            }
             buffer.vimMoveToLineEnd();
             dispatch({ type: 'CLEAR_COUNT' });
             return true;
           }
 
           case '^': {
+            // Check if this is part of a delete command (d^)
+            if (state.pendingOperator === 'd') {
+              buffer.vimDeleteToFirstNonWhitespace();
+              dispatch({
+                type: 'SET_LAST_COMMAND',
+                command: { type: CMD_TYPES.DELETE_TO_FIRST_NONWS, count: 1 },
+              });
+              dispatch({ type: 'CLEAR_COUNT' });
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+              return true;
+            }
+            // Check if this is part of a change command (c^)
+            if (state.pendingOperator === 'c') {
+              buffer.vimChangeToFirstNonWhitespace();
+              dispatch({
+                type: 'SET_LAST_COMMAND',
+                command: { type: CMD_TYPES.CHANGE_TO_FIRST_NONWS, count: 1 },
+              });
+              dispatch({ type: 'CLEAR_COUNT' });
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+              updateMode('INSERT');
+              return true;
+            }
+
             // Move to first non-whitespace character
             buffer.vimMoveToFirstNonWhitespace();
             dispatch({ type: 'CLEAR_COUNT' });
@@ -712,19 +916,94 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
           }
 
           case 'g': {
-            if (state.pendingOperator === 'g') {
-              // Second 'g' - go to first line (gg command)
-              buffer.vimMoveToFirstLine();
+            if (state.pendingOperator === 'd') {
+              // 'dg' - need another 'g' for 'dgg' command
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: 'dg' });
+              return true;
+            }
+            if (state.pendingOperator === 'c') {
+              // 'cg' - need another 'g' for 'cgg' command
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: 'cg' });
+              return true;
+            }
+            if (state.pendingOperator === 'dg') {
+              // 'dgg' command - delete from first line (or line N) to current line
+              // Pass state.count directly (0 means first line, N means line N)
+              buffer.vimDeleteToFirstLine(state.count);
+              dispatch({
+                type: 'SET_LAST_COMMAND',
+                command: {
+                  type: CMD_TYPES.DELETE_TO_FIRST_LINE,
+                  count: state.count,
+                },
+              });
               dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+              dispatch({ type: 'CLEAR_COUNT' });
+              return true;
+            }
+            if (state.pendingOperator === 'cg') {
+              // 'cgg' command - change from first line (or line N) to current line
+              buffer.vimDeleteToFirstLine(state.count);
+              dispatch({
+                type: 'SET_LAST_COMMAND',
+                command: {
+                  type: CMD_TYPES.CHANGE_TO_FIRST_LINE,
+                  count: state.count,
+                },
+              });
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+              dispatch({ type: 'CLEAR_COUNT' });
+              updateMode('INSERT');
+              return true;
+            }
+            if (state.pendingOperator === 'g') {
+              // Second 'g' - go to line N (gg command), or first line if no count
+              if (state.count > 0) {
+                buffer.vimMoveToLine(state.count);
+              } else {
+                buffer.vimMoveToFirstLine();
+              }
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+              dispatch({ type: 'CLEAR_COUNT' });
             } else {
-              // First 'g' - wait for second g
+              // First 'g' - wait for second g (don't clear count yet)
               dispatch({ type: 'SET_PENDING_OPERATOR', operator: 'g' });
             }
-            dispatch({ type: 'CLEAR_COUNT' });
             return true;
           }
 
           case 'G': {
+            // Check if this is part of a delete command (dG)
+            if (state.pendingOperator === 'd') {
+              // Pass state.count directly (0 means last line, N means line N)
+              buffer.vimDeleteToLastLine(state.count);
+              dispatch({
+                type: 'SET_LAST_COMMAND',
+                command: {
+                  type: CMD_TYPES.DELETE_TO_LAST_LINE,
+                  count: state.count,
+                },
+              });
+              dispatch({ type: 'CLEAR_COUNT' });
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+              return true;
+            }
+            // Check if this is part of a change command (cG)
+            if (state.pendingOperator === 'c') {
+              buffer.vimDeleteToLastLine(state.count);
+              dispatch({
+                type: 'SET_LAST_COMMAND',
+                command: {
+                  type: CMD_TYPES.CHANGE_TO_LAST_LINE,
+                  count: state.count,
+                },
+              });
+              dispatch({ type: 'CLEAR_COUNT' });
+              dispatch({ type: 'SET_PENDING_OPERATOR', operator: null });
+              updateMode('INSERT');
+              return true;
+            }
+
             if (state.count > 0) {
               // Go to specific line number (1-based) when a count was provided
               buffer.vimMoveToLine(state.count);
@@ -789,34 +1068,44 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
           }
 
           case 'D': {
-            // Delete from cursor to end of line (equivalent to d$)
-            executeCommand(CMD_TYPES.DELETE_TO_EOL, 1);
+            // Delete from cursor to end of line (with count, delete to end of N lines)
+            executeCommand(CMD_TYPES.DELETE_TO_EOL, repeatCount);
             dispatch({
               type: 'SET_LAST_COMMAND',
-              command: { type: CMD_TYPES.DELETE_TO_EOL, count: 1 },
+              command: { type: CMD_TYPES.DELETE_TO_EOL, count: repeatCount },
             });
             dispatch({ type: 'CLEAR_COUNT' });
             return true;
           }
 
           case 'C': {
-            // Change from cursor to end of line (equivalent to c$)
-            executeCommand(CMD_TYPES.CHANGE_TO_EOL, 1);
+            // Change from cursor to end of line (with count, change to end of N lines)
+            executeCommand(CMD_TYPES.CHANGE_TO_EOL, repeatCount);
             dispatch({
               type: 'SET_LAST_COMMAND',
-              command: { type: CMD_TYPES.CHANGE_TO_EOL, count: 1 },
+              command: { type: CMD_TYPES.CHANGE_TO_EOL, count: repeatCount },
             });
             dispatch({ type: 'CLEAR_COUNT' });
             return true;
           }
 
+          case 'u': {
+            // Undo last change
+            for (let i = 0; i < repeatCount; i++) {
+              buffer.undo();
+            }
+            dispatch({ type: 'CLEAR_COUNT' });
+            return true;
+          }
+
           case '.': {
-            // Repeat last command
+            // Repeat last command (use current count if provided, otherwise use original count)
             if (state.lastCommand) {
               const cmdData = state.lastCommand;
+              const count = state.count > 0 ? state.count : cmdData.count;
 
               // All repeatable commands are now handled by executeCommand
-              executeCommand(cmdData.type, cmdData.count);
+              executeCommand(cmdData.type, count);
             }
 
             dispatch({ type: 'CLEAR_COUNT' });
@@ -827,6 +1116,9 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
             // Check for arrow keys (they have different sequences but known names)
             if (normalizedKey.name === 'left') {
               // Left arrow - same as 'h'
+              if (state.pendingOperator === 'd') {
+                return handleDeleteMovement('h');
+              }
               if (state.pendingOperator === 'c') {
                 return handleChangeMovement('h');
               }
@@ -839,6 +1131,9 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
 
             if (normalizedKey.name === 'down') {
               // Down arrow - same as 'j'
+              if (state.pendingOperator === 'd') {
+                return handleDeleteMovement('j');
+              }
               if (state.pendingOperator === 'c') {
                 return handleChangeMovement('j');
               }
@@ -851,6 +1146,9 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
 
             if (normalizedKey.name === 'up') {
               // Up arrow - same as 'k'
+              if (state.pendingOperator === 'd') {
+                return handleDeleteMovement('k');
+              }
               if (state.pendingOperator === 'c') {
                 return handleChangeMovement('k');
               }
@@ -863,6 +1161,9 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
 
             if (normalizedKey.name === 'right') {
               // Right arrow - same as 'l'
+              if (state.pendingOperator === 'd') {
+                return handleDeleteMovement('l');
+              }
               if (state.pendingOperator === 'c') {
                 return handleChangeMovement('l');
               }
@@ -895,6 +1196,7 @@ export function useVim(buffer: TextBuffer, onSubmit?: (value: string) => void) {
       dispatch,
       getCurrentCount,
       handleChangeMovement,
+      handleDeleteMovement,
       handleOperatorMotion,
       buffer,
       executeCommand,

From 696198be87274be71fdd7b49d10a5299d188754a Mon Sep 17 00:00:00 2001
From: Allen Hutchison <adh@google.com>
Date: Thu, 12 Feb 2026 16:25:23 -0800
Subject: [PATCH 36/44] feat(policy): add --policy flag for user defined
 policies (#18500)

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
---
 docs/get-started/configuration.md             |   7 +
 packages/cli/src/config/config.test.ts        |  24 +++
 packages/cli/src/config/config.ts             |  17 ++
 packages/cli/src/config/policy.ts             |   1 +
 packages/cli/src/config/settingsSchema.ts     |  12 ++
 packages/cli/src/gemini.test.tsx              |   1 +
 .../src/ui/noninteractive/nonInteractiveUi.ts |  13 +-
 packages/core/src/policy/config.test.ts       | 150 +++++++++++++++++-
 packages/core/src/policy/config.ts            |  60 +++++--
 packages/core/src/policy/toml-loader.test.ts  |  31 +++-
 packages/core/src/policy/toml-loader.ts       |  48 +++---
 packages/core/src/policy/types.ts             |   1 +
 schemas/settings.schema.json                  |  10 ++
 13 files changed, 326 insertions(+), 49 deletions(-)

diff --git a/docs/get-started/configuration.md b/docs/get-started/configuration.md
index 32c0bf30b1..afbdac94a6 100644
--- a/docs/get-started/configuration.md
+++ b/docs/get-started/configuration.md
@@ -96,6 +96,13 @@ their corresponding top-level category object in your `settings.json` file.
 
 <!-- SETTINGS-AUTOGEN:START -->
 
+#### `policyPaths`
+
+- **`policyPaths`** (array):
+  - **Description:** Additional policy files or directories to load.
+  - **Default:** `[]`
+  - **Requires restart:** Yes
+
 #### `general`
 
 - **`general.preferredEditor`** (string):
diff --git a/packages/cli/src/config/config.test.ts b/packages/cli/src/config/config.test.ts
index 6614fe2af0..8c3cd9900c 100644
--- a/packages/cli/src/config/config.test.ts
+++ b/packages/cli/src/config/config.test.ts
@@ -141,6 +141,10 @@ vi.mock('@google/gemini-cli-core', async () => {
       defaultDecision: ServerConfig.PolicyDecision.ASK_USER,
       approvalMode: ServerConfig.ApprovalMode.DEFAULT,
     })),
+    getAdminErrorMessage: vi.fn(
+      (_feature) =>
+        `YOLO mode is disabled by your administrator. To enable it, please request an update to the settings at: https://goo.gle/manage-gemini-cli`,
+    ),
     isHeadlessMode: vi.fn((opts) => {
       if (process.env['VITEST'] === 'true') {
         return (
@@ -3192,6 +3196,26 @@ describe('Policy Engine Integration in loadCliConfig', () => {
       expect.anything(),
     );
   });
+
+  it('should pass user-provided policy paths from --policy flag to createPolicyEngineConfig', async () => {
+    process.argv = [
+      'node',
+      'script.js',
+      '--policy',
+      '/path/to/policy1.toml,/path/to/policy2.toml',
+    ];
+    const settings = createTestMergedSettings();
+    const argv = await parseArguments(settings);
+
+    await loadCliConfig(settings, 'test-session', argv);
+
+    expect(ServerConfig.createPolicyEngineConfig).toHaveBeenCalledWith(
+      expect.objectContaining({
+        policyPaths: ['/path/to/policy1.toml', '/path/to/policy2.toml'],
+      }),
+      expect.anything(),
+    );
+  });
 });
 
 describe('loadCliConfig disableYoloMode', () => {
diff --git a/packages/cli/src/config/config.ts b/packages/cli/src/config/config.ts
index ea7d6f72a5..b7b5dfc7d9 100755
--- a/packages/cli/src/config/config.ts
+++ b/packages/cli/src/config/config.ts
@@ -75,6 +75,7 @@ export interface CliArgs {
 
   yolo: boolean | undefined;
   approvalMode: string | undefined;
+  policy: string[] | undefined;
   allowedMcpServerNames: string[] | undefined;
   allowedTools: string[] | undefined;
   experimentalAcp: boolean | undefined;
@@ -158,6 +159,21 @@ export async function parseArguments(
           description:
             'Set the approval mode: default (prompt for approval), auto_edit (auto-approve edit tools), yolo (auto-approve all tools), plan (read-only mode)',
         })
+        .option('policy', {
+          type: 'array',
+          string: true,
+          nargs: 1,
+          description:
+            'Additional policy files or directories to load (comma-separated or multiple --policy)',
+          coerce: (policies: string[]) =>
+            // Handle comma-separated values
+            policies.flatMap((p) =>
+              p
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean),
+            ),
+        })
         .option('experimental-acp', {
           type: 'boolean',
           description: 'Starts the agent in ACP mode',
@@ -670,6 +686,7 @@ export async function loadCliConfig(
       ...settings.mcp,
       allowed: argv.allowedMcpServerNames ?? settings.mcp?.allowed,
     },
+    policyPaths: argv.policy,
   };
 
   const policyEngineConfig = await createPolicyEngineConfig(
diff --git a/packages/cli/src/config/policy.ts b/packages/cli/src/config/policy.ts
index e9f19f43db..70536070eb 100644
--- a/packages/cli/src/config/policy.ts
+++ b/packages/cli/src/config/policy.ts
@@ -25,6 +25,7 @@ export async function createPolicyEngineConfig(
     mcp: settings.mcp,
     tools: settings.tools,
     mcpServers: settings.mcpServers,
+    policyPaths: settings.policyPaths,
   };
 
   return createCorePolicyEngineConfig(policySettings, approvalMode);
diff --git a/packages/cli/src/config/settingsSchema.ts b/packages/cli/src/config/settingsSchema.ts
index 07d2faec49..b486956211 100644
--- a/packages/cli/src/config/settingsSchema.ts
+++ b/packages/cli/src/config/settingsSchema.ts
@@ -152,6 +152,18 @@ const SETTINGS_SCHEMA = {
     },
   },
 
+  policyPaths: {
+    type: 'array',
+    label: 'Policy Paths',
+    category: 'Advanced',
+    requiresRestart: true,
+    default: [] as string[],
+    description: 'Additional policy files or directories to load.',
+    showInDialog: false,
+    items: { type: 'string' },
+    mergeStrategy: MergeStrategy.UNION,
+  },
+
   general: {
     type: 'object',
     label: 'General',
diff --git a/packages/cli/src/gemini.test.tsx b/packages/cli/src/gemini.test.tsx
index 2e55c9b25d..9dac908a97 100644
--- a/packages/cli/src/gemini.test.tsx
+++ b/packages/cli/src/gemini.test.tsx
@@ -464,6 +464,7 @@ describe('gemini.tsx main function kitty protocol', () => {
       query: undefined,
       yolo: undefined,
       approvalMode: undefined,
+      policy: undefined,
       allowedMcpServerNames: undefined,
       allowedTools: undefined,
       experimentalAcp: undefined,
diff --git a/packages/cli/src/ui/noninteractive/nonInteractiveUi.ts b/packages/cli/src/ui/noninteractive/nonInteractiveUi.ts
index 8daa3a8a0a..00efd3f7fc 100644
--- a/packages/cli/src/ui/noninteractive/nonInteractiveUi.ts
+++ b/packages/cli/src/ui/noninteractive/nonInteractiveUi.ts
@@ -14,7 +14,18 @@ import type { ExtensionUpdateAction } from '../state/extensions.js';
  */
 export function createNonInteractiveUI(): CommandContext['ui'] {
   return {
-    addItem: (_item, _timestamp) => 0,
+    addItem: (item, _timestamp) => {
+      if ('text' in item && item.text) {
+        if (item.type === 'error') {
+          process.stderr.write(`Error: ${item.text}\n`);
+        } else if (item.type === 'warning') {
+          process.stderr.write(`Warning: ${item.text}\n`);
+        } else if (item.type === 'info') {
+          process.stdout.write(`${item.text}\n`);
+        }
+      }
+      return 0;
+    },
     clear: () => {},
     setDebugMessage: (_message) => {},
     loadHistory: (_newHistory) => {},
diff --git a/packages/core/src/policy/config.test.ts b/packages/core/src/policy/config.test.ts
index 620cdd8500..32a5287113 100644
--- a/packages/core/src/policy/config.test.ts
+++ b/packages/core/src/policy/config.test.ts
@@ -463,6 +463,21 @@ describe('createPolicyEngineConfig', () => {
       }
       return [];
     });
+    const mockStat = vi.fn(async (p) => {
+      if (typeof p === 'string' && p.includes('/tmp/mock/default/policies')) {
+        return {
+          isDirectory: () => true,
+          isFile: () => false,
+        } as unknown as Awaited<ReturnType<typeof actualFs.stat>>;
+      }
+      if (typeof p === 'string' && p.includes('default.toml')) {
+        return {
+          isDirectory: () => false,
+          isFile: () => true,
+        } as unknown as Awaited<ReturnType<typeof actualFs.stat>>;
+      }
+      return actualFs.stat(p);
+    });
     const mockReadFile = vi.fn(async (p, _o) => {
       if (typeof p === 'string' && p.includes('default.toml')) {
         return '[[rule]]\ntoolName = "glob"\ndecision = "allow"\npriority = 50\n';
@@ -471,9 +486,15 @@ describe('createPolicyEngineConfig', () => {
     });
     vi.doMock('node:fs/promises', () => ({
       ...actualFs,
-      default: { ...actualFs, readdir: mockReaddir, readFile: mockReadFile },
+      default: {
+        ...actualFs,
+        readdir: mockReaddir,
+        readFile: mockReadFile,
+        stat: mockStat,
+      },
       readdir: mockReaddir,
       readFile: mockReadFile,
+      stat: mockStat,
     }));
     vi.resetModules();
     const { createPolicyEngineConfig: createConfig } = await import(
@@ -663,11 +684,37 @@ priority = 150
       },
     );
 
+    const mockStat = vi.fn(
+      async (
+        path: Parameters<typeof actualFs.stat>[0],
+        options?: Parameters<typeof actualFs.stat>[1],
+      ) => {
+        if (
+          typeof path === 'string' &&
+          nodePath
+            .normalize(path)
+            .includes(nodePath.normalize('.gemini/policies'))
+        ) {
+          return {
+            isDirectory: () => true,
+            isFile: () => false,
+          } as unknown as Awaited<ReturnType<typeof actualFs.stat>>;
+        }
+        return actualFs.stat(path, options);
+      },
+    );
+
     vi.doMock('node:fs/promises', () => ({
       ...actualFs,
-      default: { ...actualFs, readFile: mockReadFile, readdir: mockReaddir },
+      default: {
+        ...actualFs,
+        readFile: mockReadFile,
+        readdir: mockReaddir,
+        stat: mockStat,
+      },
       readFile: mockReadFile,
       readdir: mockReaddir,
+      stat: mockStat,
     }));
 
     vi.resetModules();
@@ -766,11 +813,37 @@ required_context = ["environment"]
       },
     );
 
+    const mockStat = vi.fn(
+      async (
+        path: Parameters<typeof actualFs.stat>[0],
+        options?: Parameters<typeof actualFs.stat>[1],
+      ) => {
+        if (
+          typeof path === 'string' &&
+          nodePath
+            .normalize(path)
+            .includes(nodePath.normalize('.gemini/policies'))
+        ) {
+          return {
+            isDirectory: () => true,
+            isFile: () => false,
+          } as unknown as Awaited<ReturnType<typeof actualFs.stat>>;
+        }
+        return actualFs.stat(path, options);
+      },
+    );
+
     vi.doMock('node:fs/promises', () => ({
       ...actualFs,
-      default: { ...actualFs, readFile: mockReadFile, readdir: mockReaddir },
+      default: {
+        ...actualFs,
+        readFile: mockReadFile,
+        readdir: mockReaddir,
+        stat: mockStat,
+      },
       readFile: mockReadFile,
       readdir: mockReaddir,
+      stat: mockStat,
     }));
 
     vi.resetModules();
@@ -862,11 +935,37 @@ name = "invalid-name"
       },
     );
 
+    const mockStat = vi.fn(
+      async (
+        path: Parameters<typeof actualFs.stat>[0],
+        options?: Parameters<typeof actualFs.stat>[1],
+      ) => {
+        if (
+          typeof path === 'string' &&
+          nodePath
+            .normalize(path)
+            .includes(nodePath.normalize('.gemini/policies'))
+        ) {
+          return {
+            isDirectory: () => true,
+            isFile: () => false,
+          } as unknown as Awaited<ReturnType<typeof actualFs.stat>>;
+        }
+        return actualFs.stat(path, options);
+      },
+    );
+
     vi.doMock('node:fs/promises', () => ({
       ...actualFs,
-      default: { ...actualFs, readFile: mockReadFile, readdir: mockReaddir },
+      default: {
+        ...actualFs,
+        readFile: mockReadFile,
+        readdir: mockReaddir,
+        stat: mockStat,
+      },
       readFile: mockReadFile,
       readdir: mockReaddir,
+      stat: mockStat,
     }));
 
     vi.resetModules();
@@ -964,7 +1063,7 @@ name = "invalid-name"
         options?: Parameters<typeof actualFs.readdir>[1],
       ) => {
         const normalizedPath = nodePath.normalize(path.toString());
-        if (normalizedPath.includes(nodePath.normalize('.gemini/policies'))) {
+        if (normalizedPath.includes('gemini-cli-test/user/policies')) {
           return [
             {
               name: 'user-plan.toml',
@@ -980,6 +1079,22 @@ name = "invalid-name"
       },
     );
 
+    const mockStat = vi.fn(
+      async (
+        path: Parameters<typeof actualFs.stat>[0],
+        options?: Parameters<typeof actualFs.stat>[1],
+      ) => {
+        const normalizedPath = nodePath.normalize(path.toString());
+        if (normalizedPath.includes('gemini-cli-test/user/policies')) {
+          return {
+            isDirectory: () => true,
+            isFile: () => false,
+          } as unknown as Awaited<ReturnType<typeof actualFs.stat>>;
+        }
+        return actualFs.stat(path, options);
+      },
+    );
+
     const mockReadFile = vi.fn(
       async (
         path: Parameters<typeof actualFs.readFile>[0],
@@ -1008,12 +1123,35 @@ modes = ["plan"]
 
     vi.doMock('node:fs/promises', () => ({
       ...actualFs,
-      default: { ...actualFs, readFile: mockReadFile, readdir: mockReaddir },
+      default: {
+        ...actualFs,
+        readFile: mockReadFile,
+        readdir: mockReaddir,
+        stat: mockStat,
+      },
       readFile: mockReadFile,
       readdir: mockReaddir,
+      stat: mockStat,
     }));
 
     vi.resetModules();
+
+    // Robustly mock Storage using doMock to ensure it persists through imports in config.js
+    vi.doMock('../config/storage.js', async () => {
+      const actual = await vi.importActual<
+        typeof import('../config/storage.js')
+      >('../config/storage.js');
+      class MockStorage extends actual.Storage {
+        static override getUserPoliciesDir() {
+          return '/tmp/gemini-cli-test/user/policies';
+        }
+        static override getSystemPoliciesDir() {
+          return '/tmp/gemini-cli-test/system/policies';
+        }
+      }
+      return { ...actual, Storage: MockStorage };
+    });
+
     const { createPolicyEngineConfig } = await import('./config.js');
 
     const settings: PolicySettings = {};
diff --git a/packages/core/src/policy/config.ts b/packages/core/src/policy/config.ts
index ca641d09ea..efa5083504 100644
--- a/packages/core/src/policy/config.ts
+++ b/packages/core/src/policy/config.ts
@@ -42,26 +42,33 @@ export const USER_POLICY_TIER = 2;
 export const ADMIN_POLICY_TIER = 3;
 
 /**
- * Gets the list of directories to search for policy files, in order of increasing priority
- * (Default -> User -> Admin).
+ * Gets the list of directories to search for policy files, in order of decreasing priority
+ * (Admin -> User -> Default).
  *
  * @param defaultPoliciesDir Optional path to a directory containing default policies.
+ * @param policyPaths Optional user-provided policy paths (from --policy flag).
+ *   When provided, these replace the default user policies directory.
  */
-export function getPolicyDirectories(defaultPoliciesDir?: string): string[] {
-  const dirs = [];
+export function getPolicyDirectories(
+  defaultPoliciesDir?: string,
+  policyPaths?: string[],
+): string[] {
+  const dirs: string[] = [];
 
-  if (defaultPoliciesDir) {
-    dirs.push(defaultPoliciesDir);
+  // Default tier (lowest priority)
+  dirs.push(defaultPoliciesDir ?? DEFAULT_CORE_POLICIES_DIR);
+
+  // User tier (middle priority)
+  if (policyPaths && policyPaths.length > 0) {
+    dirs.push(...policyPaths);
   } else {
-    dirs.push(DEFAULT_CORE_POLICIES_DIR);
+    dirs.push(Storage.getUserPoliciesDir());
   }
 
-  dirs.push(Storage.getUserPoliciesDir());
+  // Admin tier (highest priority)
   dirs.push(Storage.getSystemPoliciesDir());
 
-  // Reverse so highest priority (Admin) is first for loading order if needed,
-  // though loadPoliciesFromToml might want them in a specific order.
-  // CLI implementation reversed them: [DEFAULT, USER, ADMIN].reverse() -> [ADMIN, USER, DEFAULT]
+  // Reverse so highest priority (Admin) is first
   return dirs.reverse();
 }
 
@@ -147,17 +154,40 @@ export async function createPolicyEngineConfig(
   approvalMode: ApprovalMode,
   defaultPoliciesDir?: string,
 ): Promise<PolicyEngineConfig> {
-  const policyDirs = getPolicyDirectories(defaultPoliciesDir);
+  const policyDirs = getPolicyDirectories(
+    defaultPoliciesDir,
+    settings.policyPaths,
+  );
+
   const securePolicyDirs = await filterSecurePolicyDirectories(policyDirs);
 
+  const normalizedAdminPoliciesDir = path.resolve(
+    Storage.getSystemPoliciesDir(),
+  );
+
   // Load policies from TOML files
   const {
     rules: tomlRules,
     checkers: tomlCheckers,
     errors,
-  } = await loadPoliciesFromToml(securePolicyDirs, (dir) =>
-    getPolicyTier(dir, defaultPoliciesDir),
-  );
+  } = await loadPoliciesFromToml(securePolicyDirs, (p) => {
+    const tier = getPolicyTier(p, defaultPoliciesDir);
+
+    // If it's a user-provided path that isn't already categorized as ADMIN,
+    // treat it as USER tier.
+    if (
+      settings.policyPaths?.some(
+        (userPath) => path.resolve(userPath) === path.resolve(p),
+      )
+    ) {
+      const normalizedPath = path.resolve(p);
+      if (normalizedPath !== normalizedAdminPoliciesDir) {
+        return USER_POLICY_TIER;
+      }
+    }
+
+    return tier;
+  });
 
   // Emit any errors encountered during TOML loading to the UI
   // coreEvents has a buffer that will display these once the UI is ready
diff --git a/packages/core/src/policy/toml-loader.test.ts b/packages/core/src/policy/toml-loader.test.ts
index 9938efa950..f46e474442 100644
--- a/packages/core/src/policy/toml-loader.test.ts
+++ b/packages/core/src/policy/toml-loader.test.ts
@@ -495,18 +495,33 @@ priority = 100
       expect(error.message).toBe('Invalid regex pattern');
     });
 
-    it('should return a file_read error if readdir fails', async () => {
-      // Create a file and pass it as a directory to trigger ENOTDIR
-      const filePath = path.join(tempDir, 'not-a-dir');
-      await fs.writeFile(filePath, 'content');
+    it('should load an individual policy file', async () => {
+      const filePath = path.join(tempDir, 'single-rule.toml');
+      await fs.writeFile(
+        filePath,
+        '[[rule]]\ntoolName = "test-tool"\ndecision = "allow"\npriority = 500\n',
+      );
 
       const getPolicyTier = (_dir: string) => 1;
       const result = await loadPoliciesFromToml([filePath], getPolicyTier);
 
-      expect(result.errors).toHaveLength(1);
-      const error = result.errors[0];
-      expect(error.errorType).toBe('file_read');
-      expect(error.message).toContain('Failed to read policy directory');
+      expect(result.errors).toHaveLength(0);
+      expect(result.rules).toHaveLength(1);
+      expect(result.rules[0].toolName).toBe('test-tool');
+      expect(result.rules[0].decision).toBe(PolicyDecision.ALLOW);
+    });
+
+    it('should return a file_read error if stat fails with something other than ENOENT', async () => {
+      // We can't easily trigger a stat error other than ENOENT without mocks,
+      // but we can test that it handles it.
+      // For this test, we'll just check that it handles a non-existent file gracefully (no error)
+      const filePath = path.join(tempDir, 'non-existent.toml');
+
+      const getPolicyTier = (_dir: string) => 1;
+      const result = await loadPoliciesFromToml([filePath], getPolicyTier);
+
+      expect(result.errors).toHaveLength(0);
+      expect(result.rules).toHaveLength(0);
     });
   });
 
diff --git a/packages/core/src/policy/toml-loader.ts b/packages/core/src/policy/toml-loader.ts
index 67fcacce75..a627064d41 100644
--- a/packages/core/src/policy/toml-loader.ts
+++ b/packages/core/src/policy/toml-loader.ts
@@ -202,57 +202,67 @@ function transformPriority(priority: number, tier: number): number {
 }
 
 /**
- * Loads and parses policies from TOML files in the specified directories.
+ * Loads and parses policies from TOML files in the specified paths (directories or individual files).
  *
  * This function:
- * 1. Scans directories for .toml files
+ * 1. Scans paths for .toml files (if directory) or processes individual files
  * 2. Parses and validates each file
  * 3. Transforms rules (commandPrefix, arrays, mcpName, priorities)
  * 4. Collects detailed error information for any failures
  *
- * @param policyDirs Array of directory paths to scan for policy files
- * @param getPolicyTier Function to determine tier (1-3) for a directory
+ * @param policyPaths Array of paths (directories or files) to scan for policy files
+ * @param getPolicyTier Function to determine tier (1-3) for a path
  * @returns Object containing successfully parsed rules and any errors encountered
  */
 export async function loadPoliciesFromToml(
-  policyDirs: string[],
-  getPolicyTier: (dir: string) => number,
+  policyPaths: string[],
+  getPolicyTier: (path: string) => number,
 ): Promise<PolicyLoadResult> {
   const rules: PolicyRule[] = [];
   const checkers: SafetyCheckerRule[] = [];
   const errors: PolicyFileError[] = [];
 
-  for (const dir of policyDirs) {
-    const tier = getPolicyTier(dir);
+  for (const p of policyPaths) {
+    const tier = getPolicyTier(p);
     const tierName = getTierName(tier);
 
-    // Scan directory for all .toml files
-    let filesToLoad: string[];
+    let filesToLoad: string[] = [];
+    let baseDir = '';
+
     try {
-      const dirEntries = await fs.readdir(dir, { withFileTypes: true });
-      filesToLoad = dirEntries
-        .filter((entry) => entry.isFile() && entry.name.endsWith('.toml'))
-        .map((entry) => entry.name);
+      const stats = await fs.stat(p);
+      if (stats.isDirectory()) {
+        baseDir = p;
+        const dirEntries = await fs.readdir(p, { withFileTypes: true });
+        filesToLoad = dirEntries
+          .filter((entry) => entry.isFile() && entry.name.endsWith('.toml'))
+          .map((entry) => entry.name);
+      } else if (stats.isFile() && p.endsWith('.toml')) {
+        baseDir = path.dirname(p);
+        filesToLoad = [path.basename(p)];
+      }
+      // Other file types or non-.toml files are silently ignored
+      // for consistency with directory scanning behavior.
     } catch (e) {
       // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
       const error = e as NodeJS.ErrnoException;
       if (error.code === 'ENOENT') {
-        // Directory doesn't exist, skip it (not an error)
+        // Path doesn't exist, skip it (not an error)
         continue;
       }
       errors.push({
-        filePath: dir,
-        fileName: path.basename(dir),
+        filePath: p,
+        fileName: path.basename(p),
         tier: tierName,
         errorType: 'file_read',
-        message: `Failed to read policy directory`,
+        message: `Failed to read policy path`,
         details: error.message,
       });
       continue;
     }
 
     for (const file of filesToLoad) {
-      const filePath = path.join(dir, file);
+      const filePath = path.join(baseDir, file);
 
       try {
         // Read file
diff --git a/packages/core/src/policy/types.ts b/packages/core/src/policy/types.ts
index e758aaf417..2e672fff26 100644
--- a/packages/core/src/policy/types.ts
+++ b/packages/core/src/policy/types.ts
@@ -272,6 +272,7 @@ export interface PolicySettings {
     allowed?: string[];
   };
   mcpServers?: Record<string, { trust?: boolean }>;
+  policyPaths?: string[];
 }
 
 export interface CheckResult {
diff --git a/schemas/settings.schema.json b/schemas/settings.schema.json
index 06ad037929..c965c0f339 100644
--- a/schemas/settings.schema.json
+++ b/schemas/settings.schema.json
@@ -22,6 +22,16 @@
         "$ref": "#/$defs/MCPServerConfig"
       }
     },
+    "policyPaths": {
+      "title": "Policy Paths",
+      "description": "Additional policy files or directories to load.",
+      "markdownDescription": "Additional policy files or directories to load.\n\n- Category: `Advanced`\n- Requires restart: `yes`\n- Default: `[]`",
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
     "general": {
       "title": "General",
       "description": "General application settings.",

From ca374dcf47f4af0b9c0eca6b765c8561010bccc5 Mon Sep 17 00:00:00 2001
From: g-samroberts <158088236+g-samroberts@users.noreply.github.com>
Date: Thu, 12 Feb 2026 17:21:10 -0800
Subject: [PATCH 37/44] Update installation guide (#18823)

---
 README.md                        |   7 +-
 docs/get-started/installation.md | 191 ++++++++++++++++++-------------
 2 files changed, 115 insertions(+), 83 deletions(-)

diff --git a/README.md b/README.md
index 22e258e289..6e9b1da146 100644
--- a/README.md
+++ b/README.md
@@ -29,10 +29,9 @@ Learn all about Gemini CLI in our [documentation](https://geminicli.com/docs/).
 
 ## 📦 Installation
 
-### Pre-requisites before installation
-
-- Node.js version 20 or higher
-- macOS, Linux, or Windows
+See
+[Gemini CLI installation, execution, and releases](./docs/get-started/installation.md)
+for recommended system specifications and a detailed installation guide.
 
 ### Quick Install
 
diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md
index ef1d6b0ec8..1acf497659 100644
--- a/docs/get-started/installation.md
+++ b/docs/get-started/installation.md
@@ -1,43 +1,98 @@
-# Gemini CLI installation, execution, and deployment
+# Gemini CLI installation, execution, and releases
 
-Install and run Gemini CLI. This document provides an overview of Gemini CLI's
-installation methods and deployment architecture.
+This document provides an overview of Gemini CLI's sytem requriements,
+installation methods, and release types.
 
-## How to install and/or run Gemini CLI
+## Recommended system specifications
 
-There are several ways to run Gemini CLI. The recommended option depends on how
-you intend to use Gemini CLI.
+- **Operating System:**
+  - macOS 15+
+  - Windows 11 24H2+
+  - Ubuntu 20.04+
+- **Hardware:**
+  - "Casual" usage: 4GB+ RAM (short sessions, common tasks and edits)
+  - "Power" usage: 16GB+ RAM (long sessions, large codebases, deep context)
+- **Runtime:** Node.js 20.0.0+
+- **Shell:** Bash or Zsh
+- **Location:**
+  [Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas)
+- **Internet connection required**
 
-- As a standard installation. This is the most straightforward method of using
-  Gemini CLI.
+## Install Gemini CLI
+
+We recommend most users install Gemini CLI using one of the following
+installation methods:
+
+- npm
+- Homebrew
+- MacPorts
+- Anaconda
+
+Note that Gemini CLI comes pre-installed on
+[**Cloud Shell**](https://docs.cloud.google.com/shell/docs) and
+[**Cloud Workstations**](https://cloud.google.com/workstations).
+
+### Install globally with npm
+
+```bash
+npm install -g @google/gemini-cli
+```
+
+### Install globally with Homebrew (macOS/Linux)
+
+```bash
+brew install gemini-cli
+```
+
+### Install globally with MacPorts (macOS)
+
+```bash
+sudo port install gemini-cli
+```
+
+### Install with Anaconda (for restricted environments)
+
+```bash
+# Create and activate a new environment
+conda create -y -n gemini_env -c conda-forge nodejs
+conda activate gemini_env
+
+# Install Gemini CLI globally via npm (inside the environment)
+npm install -g @google/gemini-cli
+```
+
+## Run Gemini CLI
+
+For most users, we recommend running Gemini CLI with the `gemini` command:
+
+```bash
+gemini
+```
+
+For a list of options and additional commands, see the
+[CLI cheatsheet](/docs/cli/cli-reference.md).
+
+You can also run Gemini CLI using one of the following advanced methods:
+
+- Run instantly with npx. You can run Gemini CLI without permanent installation.
 - In a sandbox. This method offers increased security and isolation.
 - From the source. This is recommended for contributors to the project.
 
-### 1. Standard installation (recommended for standard users)
+### Run instantly with npx
 
-This is the recommended way for end-users to install Gemini CLI. It involves
-downloading the Gemini CLI package from the NPM registry.
+```bash
+# Using npx (no installation required)
+npx @google/gemini-cli
+```
 
-- **Global install:**
+You can also execute the CLI directly from the main branch on GitHub, which is
+helpful for testing features still in development:
 
-  ```bash
-  npm install -g @google/gemini-cli
-  ```
+```bash
+npx https://github.com/google-gemini/gemini-cli
+```
 
-  Then, run the CLI from anywhere:
-
-  ```bash
-  gemini
-  ```
-
-- **NPX execution:**
-
-  ```bash
-  # Execute the latest version from NPM without a global install
-  npx @google/gemini-cli
-  ```
-
-### 2. Run in a sandbox (Docker/Podman)
+### Run in a sandbox (Docker/Podman)
 
 For security and isolation, Gemini CLI can be run inside a container. This is
 the default way that the CLI executes tools that might have side effects.
@@ -56,7 +111,7 @@ the default way that the CLI executes tools that might have side effects.
   gemini --sandbox -y -p "your prompt here"
   ```
 
-### 3. Run from source (recommended for Gemini CLI contributors)
+### Run from source (recommended for Gemini CLI contributors)
 
 Contributors to the project will want to run the CLI directly from the source
 code.
@@ -79,63 +134,41 @@ code.
   gemini
   ```
 
----
+## Releases
 
-### 4. Running the latest Gemini CLI commit from GitHub
+Gemini CLI has three release channels: nightly, preview, and stable. For most
+users, we recommend the stable release, which is the default installation.
 
-You can run the most recently committed version of Gemini CLI directly from the
-GitHub repository. This is useful for testing features still in development.
+### Stable
+
+New stable releases are published each week. The stable release is the promotion
+of last week's `preview` release along with any bug fixes. The stable release
+uses `latest` tag, but omitting the tag also installs the latest stable release
+by default:
 
 ```bash
-# Execute the CLI directly from the main branch on GitHub
-npx https://github.com/google-gemini/gemini-cli
+# Both commands install the latest stable release.
+npm install -g @google/gemini-cli
+npm install -g @google/gemini-cli@latest
 ```
 
-## Deployment architecture
+### Preview
 
-The execution methods described above are made possible by the following
-architectural components and processes:
+New preview releases will be published each week. These releases are not fully
+vetted and may contain regressions or other outstanding issues. Try out the
+preview release by using the `preview` tag:
 
-**NPM packages**
+```bash
+npm install -g @google/gemini-cli@preview
+```
 
-Gemini CLI project is a monorepo that publishes two core packages to the NPM
-registry:
+### Nightly
 
-- `@google/gemini-cli-core`: The backend, handling logic and tool execution.
-- `@google/gemini-cli`: The user-facing frontend.
+Nightly releases are published every day. The nightly release includes all
+changes from the main branch at time of release. It should be assumed there are
+pending validations and issues. You can help test the latest changes by
+installing with the `nightly` tag:
 
-These packages are used when performing the standard installation and when
-running Gemini CLI from the source.
-
-**Build and packaging processes**
-
-There are two distinct build processes used, depending on the distribution
-channel:
-
-- **NPM publication:** For publishing to the NPM registry, the TypeScript source
-  code in `@google/gemini-cli-core` and `@google/gemini-cli` is transpiled into
-  standard JavaScript using the TypeScript Compiler (`tsc`). The resulting
-  `dist/` directory is what gets published in the NPM package. This is a
-  standard approach for TypeScript libraries.
-
-- **GitHub `npx` execution:** When running the latest version of Gemini CLI
-  directly from GitHub, a different process is triggered by the `prepare` script
-  in `package.json`. This script uses `esbuild` to bundle the entire application
-  and its dependencies into a single, self-contained JavaScript file. This
-  bundle is created on-the-fly on the user's machine and is not checked into the
-  repository.
-
-**Docker sandbox image**
-
-The Docker-based execution method is supported by the `gemini-cli-sandbox`
-container image. This image is published to a container registry and contains a
-pre-installed, global version of Gemini CLI.
-
-## Release process
-
-The release process is automated through GitHub Actions. The release workflow
-performs the following actions:
-
-1.  Build the NPM packages using `tsc`.
-2.  Publish the NPM packages to the artifact registry.
-3.  Create GitHub releases with bundled assets.
+```bash
+npm install -g @google/gemini-cli@nightly
+```

From b62c6566be245fe2e2609005266f0a2d6f795ec8 Mon Sep 17 00:00:00 2001
From: Aishanee Shah <aishaneeshah@gmail.com>
Date: Thu, 12 Feb 2026 21:05:33 -0500
Subject: [PATCH 38/44] refactor(core): centralize tool definitions (Group 1:
 replace, search, grep) (#18944)

---
 .../coreToolsModelSnapshots.test.ts.snap      | 308 ++++++++++++++++++
 .../core/src/tools/definitions/coreTools.ts   | 176 ++++++++++
 .../coreToolsModelSnapshots.test.ts           |   6 +
 packages/core/src/tools/edit.ts               |  64 +---
 packages/core/src/tools/ripGrep.ts            |  84 +----
 packages/core/src/tools/tool-names.ts         |   6 +-
 packages/core/src/tools/web-search.ts         |  19 +-
 7 files changed, 518 insertions(+), 145 deletions(-)

diff --git a/packages/core/src/tools/definitions/__snapshots__/coreToolsModelSnapshots.test.ts.snap b/packages/core/src/tools/definitions/__snapshots__/coreToolsModelSnapshots.test.ts.snap
index 038e200835..5ec7724a98 100644
--- a/packages/core/src/tools/definitions/__snapshots__/coreToolsModelSnapshots.test.ts.snap
+++ b/packages/core/src/tools/definitions/__snapshots__/coreToolsModelSnapshots.test.ts.snap
@@ -35,6 +35,25 @@ exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snaps
 }
 `;
 
+exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snapshot for tool: google_web_search 1`] = `
+{
+  "description": "Performs a web search using Google Search (via the Gemini API) and returns the results. This tool is useful for finding information on the internet based on a query.",
+  "name": "google_web_search",
+  "parametersJsonSchema": {
+    "properties": {
+      "query": {
+        "description": "The search query to find information on the web.",
+        "type": "string",
+      },
+    },
+    "required": [
+      "query",
+    ],
+    "type": "object",
+  },
+}
+`;
+
 exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snapshot for tool: grep_search 1`] = `
 {
   "description": "Searches for a regular expression pattern within file contents. Max 100 matches.",
@@ -80,6 +99,77 @@ exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snaps
 }
 `;
 
+exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snapshot for tool: grep_search_ripgrep 1`] = `
+{
+  "description": "Searches for a regular expression pattern within file contents.",
+  "name": "grep_search",
+  "parametersJsonSchema": {
+    "properties": {
+      "after": {
+        "description": "Show this many lines after each match (equivalent to grep -A). Defaults to 0 if omitted.",
+        "minimum": 0,
+        "type": "integer",
+      },
+      "before": {
+        "description": "Show this many lines before each match (equivalent to grep -B). Defaults to 0 if omitted.",
+        "minimum": 0,
+        "type": "integer",
+      },
+      "case_sensitive": {
+        "description": "If true, search is case-sensitive. Defaults to false (ignore case) if omitted.",
+        "type": "boolean",
+      },
+      "context": {
+        "description": "Show this many lines of context around each match (equivalent to grep -C). Defaults to 0 if omitted.",
+        "type": "integer",
+      },
+      "dir_path": {
+        "description": "Directory or file to search. Directories are searched recursively. Relative paths are resolved against current working directory. Defaults to current working directory ('.') if omitted.",
+        "type": "string",
+      },
+      "exclude_pattern": {
+        "description": "Optional: A regular expression pattern to exclude from the search results. If a line matches both the pattern and the exclude_pattern, it will be omitted.",
+        "type": "string",
+      },
+      "fixed_strings": {
+        "description": "If true, treats the \`pattern\` as a literal string instead of a regular expression. Defaults to false (basic regex) if omitted.",
+        "type": "boolean",
+      },
+      "include": {
+        "description": "Glob pattern to filter files (e.g., '*.ts', 'src/**'). Recommended for large repositories to reduce noise. Defaults to all files if omitted.",
+        "type": "string",
+      },
+      "max_matches_per_file": {
+        "description": "Optional: Maximum number of matches to return per file. Use this to prevent being overwhelmed by repetitive matches in large files.",
+        "minimum": 1,
+        "type": "integer",
+      },
+      "names_only": {
+        "description": "Optional: If true, only the file paths of the matches will be returned, without the line content or line numbers. This is useful for gathering a list of files.",
+        "type": "boolean",
+      },
+      "no_ignore": {
+        "description": "If true, searches all files including those usually ignored (like in .gitignore, build/, dist/, etc). Defaults to false if omitted.",
+        "type": "boolean",
+      },
+      "pattern": {
+        "description": "The pattern to search for. By default, treated as a Rust-flavored regular expression. Use '\\b' for precise symbol matching (e.g., '\\bMatchMe\\b').",
+        "type": "string",
+      },
+      "total_max_matches": {
+        "description": "Optional: Maximum number of total matches to return. Use this to limit the overall size of the response. Defaults to 100 if omitted.",
+        "minimum": 1,
+        "type": "integer",
+      },
+    },
+    "required": [
+      "pattern",
+    ],
+    "type": "object",
+  },
+}
+`;
+
 exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snapshot for tool: list_directory 1`] = `
 {
   "description": "Lists the names of files and subdirectories directly within a specified directory path. Can optionally ignore entries matching provided glob patterns.",
@@ -147,6 +237,70 @@ exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snaps
 }
 `;
 
+exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snapshot for tool: replace 1`] = `
+{
+  "description": "Replaces text within a file. By default, replaces a single occurrence, but can replace multiple occurrences when \`expected_replacements\` is specified. This tool requires providing significant context around the change to ensure precise targeting. Always use the read_file tool to examine the file's current content before attempting a text replacement.
+      
+      The user has the ability to modify the \`new_string\` content. If modified, this will be stated in the response.
+      
+      Expectation for required parameters:
+      1. \`old_string\` MUST be the exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code etc.).
+      2. \`new_string\` MUST be the exact literal text to replace \`old_string\` with (also including all whitespace, indentation, newlines, and surrounding code etc.). Ensure the resulting code is correct and idiomatic and that \`old_string\` and \`new_string\` are different.
+      3. \`instruction\` is the detailed instruction of what needs to be changed. It is important to Make it specific and detailed so developers or large language models can understand what needs to be changed and perform the changes on their own if necessary. 
+      4. NEVER escape \`old_string\` or \`new_string\`, that would break the exact literal text requirement.
+      **Important:** If ANY of the above are not satisfied, the tool will fail. CRITICAL for \`old_string\`: Must uniquely identify the single instance to change. Include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string matches multiple locations, or does not match exactly, the tool will fail.
+      5. Prefer to break down complex and long changes into multiple smaller atomic calls to this tool. Always check the content of the file after changes or not finding a string to match.
+      **Multiple replacements:** Set \`expected_replacements\` to the number of occurrences you want to replace. The tool will replace ALL occurrences that match \`old_string\` exactly. Ensure the number of replacements matches your expectation.",
+  "name": "replace",
+  "parametersJsonSchema": {
+    "properties": {
+      "expected_replacements": {
+        "description": "Number of replacements expected. Defaults to 1 if not specified. Use when you want to replace multiple occurrences.",
+        "minimum": 1,
+        "type": "number",
+      },
+      "file_path": {
+        "description": "The path to the file to modify.",
+        "type": "string",
+      },
+      "instruction": {
+        "description": "A clear, semantic instruction for the code change, acting as a high-quality prompt for an expert LLM assistant. It must be self-contained and explain the goal of the change.
+
+A good instruction should concisely answer:
+1.  WHY is the change needed? (e.g., "To fix a bug where users can be null...")
+2.  WHERE should the change happen? (e.g., "...in the 'renderUserProfile' function...")
+3.  WHAT is the high-level change? (e.g., "...add a null check for the 'user' object...")
+4.  WHAT is the desired outcome? (e.g., "...so that it displays a loading spinner instead of crashing.")
+
+**GOOD Example:** "In the 'calculateTotal' function, correct the sales tax calculation by updating the 'taxRate' constant from 0.05 to 0.075 to reflect the new regional tax laws."
+
+**BAD Examples:**
+- "Change the text." (Too vague)
+- "Fix the bug." (Doesn't explain the bug or the fix)
+- "Replace the line with this new line." (Brittle, just repeats the other parameters)
+",
+        "type": "string",
+      },
+      "new_string": {
+        "description": "The exact literal text to replace \`old_string\` with, preferably unescaped. Provide the EXACT text. Ensure the resulting code is correct and idiomatic.",
+        "type": "string",
+      },
+      "old_string": {
+        "description": "The exact literal text to replace, preferably unescaped. For single replacements (default), include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string is not the exact literal text (i.e. you escaped it) or does not match exactly, the tool will fail.",
+        "type": "string",
+      },
+    },
+    "required": [
+      "file_path",
+      "instruction",
+      "old_string",
+      "new_string",
+    ],
+    "type": "object",
+  },
+}
+`;
+
 exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snapshot for tool: run_shell_command 1`] = `
 {
   "description": "This tool executes a given shell command as \`bash -c <command>\`. To run a command in the background, set the \`is_background\` parameter to true. Do NOT use \`&\` to background commands. Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.
@@ -252,6 +406,25 @@ exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview >
 }
 `;
 
+exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview > snapshot for tool: google_web_search 1`] = `
+{
+  "description": "Performs a web search using Google Search (via the Gemini API) and returns the results. This tool is useful for finding information on the internet based on a query.",
+  "name": "google_web_search",
+  "parametersJsonSchema": {
+    "properties": {
+      "query": {
+        "description": "The search query to find information on the web.",
+        "type": "string",
+      },
+    },
+    "required": [
+      "query",
+    ],
+    "type": "object",
+  },
+}
+`;
+
 exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview > snapshot for tool: grep_search 1`] = `
 {
   "description": "Searches for a regular expression pattern within file contents. Max 100 matches.",
@@ -297,6 +470,77 @@ exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview >
 }
 `;
 
+exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview > snapshot for tool: grep_search_ripgrep 1`] = `
+{
+  "description": "Searches for a regular expression pattern within file contents.",
+  "name": "grep_search",
+  "parametersJsonSchema": {
+    "properties": {
+      "after": {
+        "description": "Show this many lines after each match (equivalent to grep -A). Defaults to 0 if omitted.",
+        "minimum": 0,
+        "type": "integer",
+      },
+      "before": {
+        "description": "Show this many lines before each match (equivalent to grep -B). Defaults to 0 if omitted.",
+        "minimum": 0,
+        "type": "integer",
+      },
+      "case_sensitive": {
+        "description": "If true, search is case-sensitive. Defaults to false (ignore case) if omitted.",
+        "type": "boolean",
+      },
+      "context": {
+        "description": "Show this many lines of context around each match (equivalent to grep -C). Defaults to 0 if omitted.",
+        "type": "integer",
+      },
+      "dir_path": {
+        "description": "Directory or file to search. Directories are searched recursively. Relative paths are resolved against current working directory. Defaults to current working directory ('.') if omitted.",
+        "type": "string",
+      },
+      "exclude_pattern": {
+        "description": "Optional: A regular expression pattern to exclude from the search results. If a line matches both the pattern and the exclude_pattern, it will be omitted.",
+        "type": "string",
+      },
+      "fixed_strings": {
+        "description": "If true, treats the \`pattern\` as a literal string instead of a regular expression. Defaults to false (basic regex) if omitted.",
+        "type": "boolean",
+      },
+      "include": {
+        "description": "Glob pattern to filter files (e.g., '*.ts', 'src/**'). Recommended for large repositories to reduce noise. Defaults to all files if omitted.",
+        "type": "string",
+      },
+      "max_matches_per_file": {
+        "description": "Optional: Maximum number of matches to return per file. Use this to prevent being overwhelmed by repetitive matches in large files.",
+        "minimum": 1,
+        "type": "integer",
+      },
+      "names_only": {
+        "description": "Optional: If true, only the file paths of the matches will be returned, without the line content or line numbers. This is useful for gathering a list of files.",
+        "type": "boolean",
+      },
+      "no_ignore": {
+        "description": "If true, searches all files including those usually ignored (like in .gitignore, build/, dist/, etc). Defaults to false if omitted.",
+        "type": "boolean",
+      },
+      "pattern": {
+        "description": "The pattern to search for. By default, treated as a Rust-flavored regular expression. Use '\\b' for precise symbol matching (e.g., '\\bMatchMe\\b').",
+        "type": "string",
+      },
+      "total_max_matches": {
+        "description": "Optional: Maximum number of total matches to return. Use this to limit the overall size of the response. Defaults to 100 if omitted.",
+        "minimum": 1,
+        "type": "integer",
+      },
+    },
+    "required": [
+      "pattern",
+    ],
+    "type": "object",
+  },
+}
+`;
+
 exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview > snapshot for tool: list_directory 1`] = `
 {
   "description": "Lists the names of files and subdirectories directly within a specified directory path. Can optionally ignore entries matching provided glob patterns.",
@@ -364,6 +608,70 @@ exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview >
 }
 `;
 
+exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview > snapshot for tool: replace 1`] = `
+{
+  "description": "Replaces text within a file. By default, replaces a single occurrence, but can replace multiple occurrences when \`expected_replacements\` is specified. This tool requires providing significant context around the change to ensure precise targeting. Always use the read_file tool to examine the file's current content before attempting a text replacement.
+      
+      The user has the ability to modify the \`new_string\` content. If modified, this will be stated in the response.
+      
+      Expectation for required parameters:
+      1. \`old_string\` MUST be the exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code etc.).
+      2. \`new_string\` MUST be the exact literal text to replace \`old_string\` with (also including all whitespace, indentation, newlines, and surrounding code etc.). Ensure the resulting code is correct and idiomatic and that \`old_string\` and \`new_string\` are different.
+      3. \`instruction\` is the detailed instruction of what needs to be changed. It is important to Make it specific and detailed so developers or large language models can understand what needs to be changed and perform the changes on their own if necessary. 
+      4. NEVER escape \`old_string\` or \`new_string\`, that would break the exact literal text requirement.
+      **Important:** If ANY of the above are not satisfied, the tool will fail. CRITICAL for \`old_string\`: Must uniquely identify the single instance to change. Include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string matches multiple locations, or does not match exactly, the tool will fail.
+      5. Prefer to break down complex and long changes into multiple smaller atomic calls to this tool. Always check the content of the file after changes or not finding a string to match.
+      **Multiple replacements:** Set \`expected_replacements\` to the number of occurrences you want to replace. The tool will replace ALL occurrences that match \`old_string\` exactly. Ensure the number of replacements matches your expectation.",
+  "name": "replace",
+  "parametersJsonSchema": {
+    "properties": {
+      "expected_replacements": {
+        "description": "Number of replacements expected. Defaults to 1 if not specified. Use when you want to replace multiple occurrences.",
+        "minimum": 1,
+        "type": "number",
+      },
+      "file_path": {
+        "description": "The path to the file to modify.",
+        "type": "string",
+      },
+      "instruction": {
+        "description": "A clear, semantic instruction for the code change, acting as a high-quality prompt for an expert LLM assistant. It must be self-contained and explain the goal of the change.
+
+A good instruction should concisely answer:
+1.  WHY is the change needed? (e.g., "To fix a bug where users can be null...")
+2.  WHERE should the change happen? (e.g., "...in the 'renderUserProfile' function...")
+3.  WHAT is the high-level change? (e.g., "...add a null check for the 'user' object...")
+4.  WHAT is the desired outcome? (e.g., "...so that it displays a loading spinner instead of crashing.")
+
+**GOOD Example:** "In the 'calculateTotal' function, correct the sales tax calculation by updating the 'taxRate' constant from 0.05 to 0.075 to reflect the new regional tax laws."
+
+**BAD Examples:**
+- "Change the text." (Too vague)
+- "Fix the bug." (Doesn't explain the bug or the fix)
+- "Replace the line with this new line." (Brittle, just repeats the other parameters)
+",
+        "type": "string",
+      },
+      "new_string": {
+        "description": "The exact literal text to replace \`old_string\` with, preferably unescaped. Provide the EXACT text. Ensure the resulting code is correct and idiomatic.",
+        "type": "string",
+      },
+      "old_string": {
+        "description": "The exact literal text to replace, preferably unescaped. For single replacements (default), include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string is not the exact literal text (i.e. you escaped it) or does not match exactly, the tool will fail.",
+        "type": "string",
+      },
+    },
+    "required": [
+      "file_path",
+      "instruction",
+      "old_string",
+      "new_string",
+    ],
+    "type": "object",
+  },
+}
+`;
+
 exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview > snapshot for tool: run_shell_command 1`] = `
 {
   "description": "This tool executes a given shell command as \`bash -c <command>\`. To run a command in the background, set the \`is_background\` parameter to true. Do NOT use \`&\` to background commands. Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.
diff --git a/packages/core/src/tools/definitions/coreTools.ts b/packages/core/src/tools/definitions/coreTools.ts
index 9cab2019b1..908127f203 100644
--- a/packages/core/src/tools/definitions/coreTools.ts
+++ b/packages/core/src/tools/definitions/coreTools.ts
@@ -14,6 +14,8 @@ export const LS_TOOL_NAME = 'list_directory';
 export const READ_FILE_TOOL_NAME = 'read_file';
 export const SHELL_TOOL_NAME = 'run_shell_command';
 export const WRITE_FILE_TOOL_NAME = 'write_file';
+export const EDIT_TOOL_NAME = 'replace';
+export const WEB_SEARCH_TOOL_NAME = 'google_web_search';
 
 // ============================================================================
 // READ_FILE TOOL
@@ -126,6 +128,180 @@ export const GREP_DEFINITION: ToolDefinition = {
   },
 };
 
+// ============================================================================
+// RIP_GREP TOOL
+// ============================================================================
+
+export const RIP_GREP_DEFINITION: ToolDefinition = {
+  base: {
+    name: GREP_TOOL_NAME,
+    description:
+      'Searches for a regular expression pattern within file contents.',
+    parametersJsonSchema: {
+      type: 'object',
+      properties: {
+        pattern: {
+          description: `The pattern to search for. By default, treated as a Rust-flavored regular expression. Use '\\b' for precise symbol matching (e.g., '\\bMatchMe\\b').`,
+          type: 'string',
+        },
+        dir_path: {
+          description:
+            "Directory or file to search. Directories are searched recursively. Relative paths are resolved against current working directory. Defaults to current working directory ('.') if omitted.",
+          type: 'string',
+        },
+        include: {
+          description:
+            "Glob pattern to filter files (e.g., '*.ts', 'src/**'). Recommended for large repositories to reduce noise. Defaults to all files if omitted.",
+          type: 'string',
+        },
+        exclude_pattern: {
+          description:
+            'Optional: A regular expression pattern to exclude from the search results. If a line matches both the pattern and the exclude_pattern, it will be omitted.',
+          type: 'string',
+        },
+        names_only: {
+          description:
+            'Optional: If true, only the file paths of the matches will be returned, without the line content or line numbers. This is useful for gathering a list of files.',
+          type: 'boolean',
+        },
+        case_sensitive: {
+          description:
+            'If true, search is case-sensitive. Defaults to false (ignore case) if omitted.',
+          type: 'boolean',
+        },
+        fixed_strings: {
+          description:
+            'If true, treats the `pattern` as a literal string instead of a regular expression. Defaults to false (basic regex) if omitted.',
+          type: 'boolean',
+        },
+        context: {
+          description:
+            'Show this many lines of context around each match (equivalent to grep -C). Defaults to 0 if omitted.',
+          type: 'integer',
+        },
+        after: {
+          description:
+            'Show this many lines after each match (equivalent to grep -A). Defaults to 0 if omitted.',
+          type: 'integer',
+          minimum: 0,
+        },
+        before: {
+          description:
+            'Show this many lines before each match (equivalent to grep -B). Defaults to 0 if omitted.',
+          type: 'integer',
+          minimum: 0,
+        },
+        no_ignore: {
+          description:
+            'If true, searches all files including those usually ignored (like in .gitignore, build/, dist/, etc). Defaults to false if omitted.',
+          type: 'boolean',
+        },
+        max_matches_per_file: {
+          description:
+            'Optional: Maximum number of matches to return per file. Use this to prevent being overwhelmed by repetitive matches in large files.',
+          type: 'integer',
+          minimum: 1,
+        },
+        total_max_matches: {
+          description:
+            'Optional: Maximum number of total matches to return. Use this to limit the overall size of the response. Defaults to 100 if omitted.',
+          type: 'integer',
+          minimum: 1,
+        },
+      },
+      required: ['pattern'],
+    },
+  },
+};
+
+// ============================================================================
+// WEB_SEARCH TOOL
+// ============================================================================
+
+export const WEB_SEARCH_DEFINITION: ToolDefinition = {
+  base: {
+    name: WEB_SEARCH_TOOL_NAME,
+    description:
+      'Performs a web search using Google Search (via the Gemini API) and returns the results. This tool is useful for finding information on the internet based on a query.',
+    parametersJsonSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'The search query to find information on the web.',
+        },
+      },
+      required: ['query'],
+    },
+  },
+};
+
+// ============================================================================
+// EDIT TOOL
+// ============================================================================
+
+export const EDIT_DEFINITION: ToolDefinition = {
+  base: {
+    name: EDIT_TOOL_NAME,
+    description: `Replaces text within a file. By default, replaces a single occurrence, but can replace multiple occurrences when \`expected_replacements\` is specified. This tool requires providing significant context around the change to ensure precise targeting. Always use the ${READ_FILE_TOOL_NAME} tool to examine the file's current content before attempting a text replacement.
+      
+      The user has the ability to modify the \`new_string\` content. If modified, this will be stated in the response.
+      
+      Expectation for required parameters:
+      1. \`old_string\` MUST be the exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code etc.).
+      2. \`new_string\` MUST be the exact literal text to replace \`old_string\` with (also including all whitespace, indentation, newlines, and surrounding code etc.). Ensure the resulting code is correct and idiomatic and that \`old_string\` and \`new_string\` are different.
+      3. \`instruction\` is the detailed instruction of what needs to be changed. It is important to Make it specific and detailed so developers or large language models can understand what needs to be changed and perform the changes on their own if necessary. 
+      4. NEVER escape \`old_string\` or \`new_string\`, that would break the exact literal text requirement.
+      **Important:** If ANY of the above are not satisfied, the tool will fail. CRITICAL for \`old_string\`: Must uniquely identify the single instance to change. Include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string matches multiple locations, or does not match exactly, the tool will fail.
+      5. Prefer to break down complex and long changes into multiple smaller atomic calls to this tool. Always check the content of the file after changes or not finding a string to match.
+      **Multiple replacements:** Set \`expected_replacements\` to the number of occurrences you want to replace. The tool will replace ALL occurrences that match \`old_string\` exactly. Ensure the number of replacements matches your expectation.`,
+    parametersJsonSchema: {
+      type: 'object',
+      properties: {
+        file_path: {
+          description: 'The path to the file to modify.',
+          type: 'string',
+        },
+        instruction: {
+          description: `A clear, semantic instruction for the code change, acting as a high-quality prompt for an expert LLM assistant. It must be self-contained and explain the goal of the change.
+
+A good instruction should concisely answer:
+1.  WHY is the change needed? (e.g., "To fix a bug where users can be null...")
+2.  WHERE should the change happen? (e.g., "...in the 'renderUserProfile' function...")
+3.  WHAT is the high-level change? (e.g., "...add a null check for the 'user' object...")
+4.  WHAT is the desired outcome? (e.g., "...so that it displays a loading spinner instead of crashing.")
+
+**GOOD Example:** "In the 'calculateTotal' function, correct the sales tax calculation by updating the 'taxRate' constant from 0.05 to 0.075 to reflect the new regional tax laws."
+
+**BAD Examples:**
+- "Change the text." (Too vague)
+- "Fix the bug." (Doesn't explain the bug or the fix)
+- "Replace the line with this new line." (Brittle, just repeats the other parameters)
+`,
+          type: 'string',
+        },
+        old_string: {
+          description:
+            'The exact literal text to replace, preferably unescaped. For single replacements (default), include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string is not the exact literal text (i.e. you escaped it) or does not match exactly, the tool will fail.',
+          type: 'string',
+        },
+        new_string: {
+          description:
+            'The exact literal text to replace `old_string` with, preferably unescaped. Provide the EXACT text. Ensure the resulting code is correct and idiomatic.',
+          type: 'string',
+        },
+        expected_replacements: {
+          type: 'number',
+          description:
+            'Number of replacements expected. Defaults to 1 if not specified. Use when you want to replace multiple occurrences.',
+          minimum: 1,
+        },
+      },
+      required: ['file_path', 'instruction', 'old_string', 'new_string'],
+    },
+  },
+};
+
 // ============================================================================
 // GLOB TOOL
 // ============================================================================
diff --git a/packages/core/src/tools/definitions/coreToolsModelSnapshots.test.ts b/packages/core/src/tools/definitions/coreToolsModelSnapshots.test.ts
index c723f70071..f3f362d244 100644
--- a/packages/core/src/tools/definitions/coreToolsModelSnapshots.test.ts
+++ b/packages/core/src/tools/definitions/coreToolsModelSnapshots.test.ts
@@ -20,9 +20,12 @@ import {
   READ_FILE_DEFINITION,
   WRITE_FILE_DEFINITION,
   GREP_DEFINITION,
+  RIP_GREP_DEFINITION,
   GLOB_DEFINITION,
   LS_DEFINITION,
   getShellDefinition,
+  EDIT_DEFINITION,
+  WEB_SEARCH_DEFINITION,
 } from './coreTools.js';
 
 describe('coreTools snapshots for specific models', () => {
@@ -52,12 +55,15 @@ describe('coreTools snapshots for specific models', () => {
     { name: 'read_file', definition: READ_FILE_DEFINITION },
     { name: 'write_file', definition: WRITE_FILE_DEFINITION },
     { name: 'grep_search', definition: GREP_DEFINITION },
+    { name: 'grep_search_ripgrep', definition: RIP_GREP_DEFINITION },
     { name: 'glob', definition: GLOB_DEFINITION },
     { name: 'list_directory', definition: LS_DEFINITION },
     {
       name: 'run_shell_command',
       definition: getShellDefinition(true, true),
     },
+    { name: 'replace', definition: EDIT_DEFINITION },
+    { name: 'google_web_search', definition: WEB_SEARCH_DEFINITION },
   ];
 
   for (const modelId of modelIds) {
diff --git a/packages/core/src/tools/edit.ts b/packages/core/src/tools/edit.ts
index d7c8973a91..032e9bee74 100644
--- a/packages/core/src/tools/edit.ts
+++ b/packages/core/src/tools/edit.ts
@@ -44,6 +44,8 @@ import { logEditCorrectionEvent } from '../telemetry/loggers.js';
 import { correctPath } from '../utils/pathCorrector.js';
 import { EDIT_TOOL_NAME, READ_FILE_TOOL_NAME } from './tool-names.js';
 import { debugLogger } from '../utils/debugLogger.js';
+import { EDIT_DEFINITION } from './definitions/coreTools.js';
+import { resolveToolDeclaration } from './definitions/resolver.js';
 interface ReplacementContext {
   params: EditToolParams;
   currentContent: string;
@@ -906,63 +908,9 @@ export class EditTool
     super(
       EditTool.Name,
       'Edit',
-      `Replaces text within a file. By default, replaces a single occurrence, but can replace multiple occurrences when \`expected_replacements\` is specified. This tool requires providing significant context around the change to ensure precise targeting. Always use the ${READ_FILE_TOOL_NAME} tool to examine the file's current content before attempting a text replacement.
-      
-      The user has the ability to modify the \`new_string\` content. If modified, this will be stated in the response.
-      
-      Expectation for required parameters:
-      1. \`old_string\` MUST be the exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code etc.).
-      2. \`new_string\` MUST be the exact literal text to replace \`old_string\` with (also including all whitespace, indentation, newlines, and surrounding code etc.). Ensure the resulting code is correct and idiomatic and that \`old_string\` and \`new_string\` are different.
-      3. \`instruction\` is the detailed instruction of what needs to be changed. It is important to Make it specific and detailed so developers or large language models can understand what needs to be changed and perform the changes on their own if necessary. 
-      4. NEVER escape \`old_string\` or \`new_string\`, that would break the exact literal text requirement.
-      **Important:** If ANY of the above are not satisfied, the tool will fail. CRITICAL for \`old_string\`: Must uniquely identify the single instance to change. Include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string matches multiple locations, or does not match exactly, the tool will fail.
-      5. Prefer to break down complex and long changes into multiple smaller atomic calls to this tool. Always check the content of the file after changes or not finding a string to match.
-      **Multiple replacements:** Set \`expected_replacements\` to the number of occurrences you want to replace. The tool will replace ALL occurrences that match \`old_string\` exactly. Ensure the number of replacements matches your expectation.`,
+      EDIT_DEFINITION.base.description!,
       Kind.Edit,
-      {
-        properties: {
-          file_path: {
-            description: 'The path to the file to modify.',
-            type: 'string',
-          },
-          instruction: {
-            description: `A clear, semantic instruction for the code change, acting as a high-quality prompt for an expert LLM assistant. It must be self-contained and explain the goal of the change.
-
-A good instruction should concisely answer:
-1.  WHY is the change needed? (e.g., "To fix a bug where users can be null...")
-2.  WHERE should the change happen? (e.g., "...in the 'renderUserProfile' function...")
-3.  WHAT is the high-level change? (e.g., "...add a null check for the 'user' object...")
-4.  WHAT is the desired outcome? (e.g., "...so that it displays a loading spinner instead of crashing.")
-
-**GOOD Example:** "In the 'calculateTotal' function, correct the sales tax calculation by updating the 'taxRate' constant from 0.05 to 0.075 to reflect the new regional tax laws."
-
-**BAD Examples:**
-- "Change the text." (Too vague)
-- "Fix the bug." (Doesn't explain the bug or the fix)
-- "Replace the line with this new line." (Brittle, just repeats the other parameters)
-`,
-            type: 'string',
-          },
-          old_string: {
-            description:
-              'The exact literal text to replace, preferably unescaped. For single replacements (default), include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string is not the exact literal text (i.e. you escaped it) or does not match exactly, the tool will fail.',
-            type: 'string',
-          },
-          new_string: {
-            description:
-              'The exact literal text to replace `old_string` with, preferably unescaped. Provide the EXACT text. Ensure the resulting code is correct and idiomatic.',
-            type: 'string',
-          },
-          expected_replacements: {
-            type: 'number',
-            description:
-              'Number of replacements expected. Defaults to 1 if not specified. Use when you want to replace multiple occurrences.',
-            minimum: 1,
-          },
-        },
-        required: ['file_path', 'instruction', 'old_string', 'new_string'],
-        type: 'object',
-      },
+      EDIT_DEFINITION.base.parametersJsonSchema,
       messageBus,
       true, // isOutputMarkdown
       false, // canUpdateOutput
@@ -1008,6 +956,10 @@ A good instruction should concisely answer:
     );
   }
 
+  override getSchema(modelId?: string) {
+    return resolveToolDeclaration(EDIT_DEFINITION, modelId);
+  }
+
   getModifyContext(_: AbortSignal): ModifyContext<EditToolParams> {
     return {
       getFilePath: (params: EditToolParams) => params.file_path,
diff --git a/packages/core/src/tools/ripGrep.ts b/packages/core/src/tools/ripGrep.ts
index c7855c2808..d4478fffee 100644
--- a/packages/core/src/tools/ripGrep.ts
+++ b/packages/core/src/tools/ripGrep.ts
@@ -29,6 +29,8 @@ import {
   DEFAULT_TOTAL_MAX_MATCHES,
   DEFAULT_SEARCH_TIMEOUT_MS,
 } from './constants.js';
+import { RIP_GREP_DEFINITION } from './definitions/coreTools.js';
+import { resolveToolDeclaration } from './definitions/resolver.js';
 
 function getRgCandidateFilenames(): readonly string[] {
   return process.platform === 'win32' ? ['rg.exe', 'rg'] : ['rg'];
@@ -559,83 +561,9 @@ export class RipGrepTool extends BaseDeclarativeTool<
     super(
       RipGrepTool.Name,
       'SearchText',
-      'Searches for a regular expression pattern within file contents.',
+      RIP_GREP_DEFINITION.base.description!,
       Kind.Search,
-      {
-        properties: {
-          pattern: {
-            description:
-              "The pattern to search for. By default, treated as a Rust-flavored regular expression. Use '\\b' for precise symbol matching (e.g., '\\bMatchMe\\b').",
-            type: 'string',
-          },
-          dir_path: {
-            description:
-              "Directory or file to search. Directories are searched recursively. Relative paths are resolved against current working directory. Defaults to current working directory ('.') if omitted.",
-            type: 'string',
-          },
-          include: {
-            description:
-              "Glob pattern to filter files (e.g., '*.ts', 'src/**'). Recommended for large repositories to reduce noise. Defaults to all files if omitted.",
-            type: 'string',
-          },
-          exclude_pattern: {
-            description:
-              'Optional: A regular expression pattern to exclude from the search results. If a line matches both the pattern and the exclude_pattern, it will be omitted.',
-            type: 'string',
-          },
-          names_only: {
-            description:
-              'Optional: If true, only the file paths of the matches will be returned, without the line content or line numbers. This is useful for gathering a list of files.',
-            type: 'boolean',
-          },
-          case_sensitive: {
-            description:
-              'If true, search is case-sensitive. Defaults to false (ignore case) if omitted.',
-            type: 'boolean',
-          },
-          fixed_strings: {
-            description:
-              'If true, treats the `pattern` as a literal string instead of a regular expression. Defaults to false (basic regex) if omitted.',
-            type: 'boolean',
-          },
-          context: {
-            description:
-              'Show this many lines of context around each match (equivalent to grep -C). Defaults to 0 if omitted.',
-            type: 'integer',
-          },
-          after: {
-            description:
-              'Show this many lines after each match (equivalent to grep -A). Defaults to 0 if omitted.',
-            type: 'integer',
-            minimum: 0,
-          },
-          before: {
-            description:
-              'Show this many lines before each match (equivalent to grep -B). Defaults to 0 if omitted.',
-            type: 'integer',
-            minimum: 0,
-          },
-          no_ignore: {
-            description:
-              'If true, searches all files including those usually ignored (like in .gitignore, build/, dist/, etc). Defaults to false if omitted.',
-            type: 'boolean',
-          },
-          max_matches_per_file: {
-            description:
-              'Optional: Maximum number of matches to return per file. Use this to prevent being overwhelmed by repetitive matches in large files.',
-            type: 'integer',
-            minimum: 1,
-          },
-          total_max_matches: {
-            description:
-              'Optional: Maximum number of total matches to return. Use this to limit the overall size of the response. Defaults to 100 if omitted.',
-            type: 'integer',
-            minimum: 1,
-          },
-        },
-        required: ['pattern'],
-        type: 'object',
-      },
+      RIP_GREP_DEFINITION.base.parametersJsonSchema,
       messageBus,
       true, // isOutputMarkdown
       false, // canUpdateOutput
@@ -730,4 +658,8 @@ export class RipGrepTool extends BaseDeclarativeTool<
       _toolDisplayName,
     );
   }
+
+  override getSchema(modelId?: string) {
+    return resolveToolDeclaration(RIP_GREP_DEFINITION, modelId);
+  }
 }
diff --git a/packages/core/src/tools/tool-names.ts b/packages/core/src/tools/tool-names.ts
index f837edbe29..88041ec7fe 100644
--- a/packages/core/src/tools/tool-names.ts
+++ b/packages/core/src/tools/tool-names.ts
@@ -5,11 +5,13 @@
  */
 
 import {
+  EDIT_TOOL_NAME,
   GLOB_TOOL_NAME,
   GREP_TOOL_NAME,
   LS_TOOL_NAME,
   READ_FILE_TOOL_NAME,
   SHELL_TOOL_NAME,
+  WEB_SEARCH_TOOL_NAME,
   WRITE_FILE_TOOL_NAME,
 } from './definitions/coreTools.js';
 
@@ -18,18 +20,18 @@ import {
 // need to reference a tool's name without importing the tool's implementation.
 
 export {
+  EDIT_TOOL_NAME,
   GLOB_TOOL_NAME,
   GREP_TOOL_NAME,
   LS_TOOL_NAME,
   READ_FILE_TOOL_NAME,
   SHELL_TOOL_NAME,
+  WEB_SEARCH_TOOL_NAME,
   WRITE_FILE_TOOL_NAME,
 };
 
 export const WRITE_TODOS_TOOL_NAME = 'write_todos';
-export const WEB_SEARCH_TOOL_NAME = 'google_web_search';
 export const WEB_FETCH_TOOL_NAME = 'web_fetch';
-export const EDIT_TOOL_NAME = 'replace';
 export const READ_MANY_FILES_TOOL_NAME = 'read_many_files';
 export const LS_TOOL_NAME_LEGACY = 'list_directory'; // Just to be safe if anything used the old exported name directly
 
diff --git a/packages/core/src/tools/web-search.ts b/packages/core/src/tools/web-search.ts
index 4a1a6d0ae8..b4a064c768 100644
--- a/packages/core/src/tools/web-search.ts
+++ b/packages/core/src/tools/web-search.ts
@@ -15,6 +15,8 @@ import { getErrorMessage } from '../utils/errors.js';
 import { type Config } from '../config/config.js';
 import { getResponseText } from '../utils/partUtils.js';
 import { debugLogger } from '../utils/debugLogger.js';
+import { WEB_SEARCH_DEFINITION } from './definitions/coreTools.js';
+import { resolveToolDeclaration } from './definitions/resolver.js';
 
 interface GroundingChunkWeb {
   uri?: string;
@@ -198,18 +200,9 @@ export class WebSearchTool extends BaseDeclarativeTool<
     super(
       WebSearchTool.Name,
       'GoogleSearch',
-      'Performs a web search using Google Search (via the Gemini API) and returns the results. This tool is useful for finding information on the internet based on a query.',
+      WEB_SEARCH_DEFINITION.base.description!,
       Kind.Search,
-      {
-        type: 'object',
-        properties: {
-          query: {
-            type: 'string',
-            description: 'The search query to find information on the web.',
-          },
-        },
-        required: ['query'],
-      },
+      WEB_SEARCH_DEFINITION.base.parametersJsonSchema,
       messageBus,
       true, // isOutputMarkdown
       false, // canUpdateOutput
@@ -244,4 +237,8 @@ export class WebSearchTool extends BaseDeclarativeTool<
       _toolDisplayName,
     );
   }
+
+  override getSchema(modelId?: string) {
+    return resolveToolDeclaration(WEB_SEARCH_DEFINITION, modelId);
+  }
 }

From 00f73b73bc9ea7f86780fc2dd5b2d90c6e8aff26 Mon Sep 17 00:00:00 2001
From: Abhi <43648792+abhipatel12@users.noreply.github.com>
Date: Fri, 13 Feb 2026 11:14:35 +0900
Subject: [PATCH 39/44] refactor(cli): finalize event-driven transition and
 remove interaction bridge (#18569)

---
 .../AlternateBufferQuittingDisplay.test.tsx   |   1 -
 .../ui/components/HistoryItemDisplay.test.tsx |   1 -
 .../components/ToolConfirmationQueue.test.tsx |   6 +-
 .../messages/RedirectionConfirmation.test.tsx |   7 +-
 .../messages/ToolConfirmationMessage.test.tsx |  29 ++-
 .../messages/ToolConfirmationMessage.tsx      |   5 +-
 .../messages/ToolGroupMessage.test.tsx        |   1 -
 .../ui/contexts/ToolActionsContext.test.tsx   |  53 +-----
 .../src/ui/contexts/ToolActionsContext.tsx    |  19 +-
 packages/cli/src/ui/hooks/toolMapping.ts      |   7 +-
 .../cli/src/ui/hooks/useGeminiStream.test.tsx | 170 ++++++------------
 packages/cli/src/ui/hooks/useGeminiStream.ts  |  14 +-
 .../cli/src/ui/hooks/useToolScheduler.test.ts | 118 ------------
 packages/cli/src/ui/hooks/useToolScheduler.ts |  42 +----
 packages/cli/src/ui/types.ts                  |  11 +-
 packages/cli/src/ui/utils/textUtils.test.ts   |  17 +-
 16 files changed, 104 insertions(+), 397 deletions(-)

diff --git a/packages/cli/src/ui/components/AlternateBufferQuittingDisplay.test.tsx b/packages/cli/src/ui/components/AlternateBufferQuittingDisplay.test.tsx
index 68b662df7b..4edd41d66c 100644
--- a/packages/cli/src/ui/components/AlternateBufferQuittingDisplay.test.tsx
+++ b/packages/cli/src/ui/components/AlternateBufferQuittingDisplay.test.tsx
@@ -182,7 +182,6 @@ describe('AlternateBufferQuittingDisplay', () => {
               type: 'info',
               title: 'Confirm Tool',
               prompt: 'Confirm this action?',
-              onConfirm: async () => {},
             },
           },
         ],
diff --git a/packages/cli/src/ui/components/HistoryItemDisplay.test.tsx b/packages/cli/src/ui/components/HistoryItemDisplay.test.tsx
index b232ff948a..089140d1ff 100644
--- a/packages/cli/src/ui/components/HistoryItemDisplay.test.tsx
+++ b/packages/cli/src/ui/components/HistoryItemDisplay.test.tsx
@@ -210,7 +210,6 @@ describe('<HistoryItemDisplay />', () => {
             command: 'echo "\u001b[31mhello\u001b[0m"',
             rootCommand: 'echo',
             rootCommands: ['echo'],
-            onConfirm: async () => {},
           },
         },
       ],
diff --git a/packages/cli/src/ui/components/ToolConfirmationQueue.test.tsx b/packages/cli/src/ui/components/ToolConfirmationQueue.test.tsx
index 6df45442c1..8ddbcbce4d 100644
--- a/packages/cli/src/ui/components/ToolConfirmationQueue.test.tsx
+++ b/packages/cli/src/ui/components/ToolConfirmationQueue.test.tsx
@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect } from 'vitest';
 import { Box } from 'ink';
 import { ToolConfirmationQueue } from './ToolConfirmationQueue.js';
 import { ToolCallStatus, StreamingState } from '../types.js';
@@ -70,7 +70,6 @@ describe('ToolConfirmationQueue', () => {
           command: 'ls',
           rootCommand: 'ls',
           rootCommands: ['ls'],
-          onConfirm: vi.fn(),
         },
       },
       index: 1,
@@ -144,7 +143,6 @@ describe('ToolConfirmationQueue', () => {
           fileDiff: longDiff,
           originalContent: 'old',
           newContent: 'new',
-          onConfirm: vi.fn(),
         },
       },
       index: 1,
@@ -192,7 +190,6 @@ describe('ToolConfirmationQueue', () => {
           fileDiff: longDiff,
           originalContent: 'old',
           newContent: 'new',
-          onConfirm: vi.fn(),
         },
       },
       index: 1,
@@ -242,7 +239,6 @@ describe('ToolConfirmationQueue', () => {
           fileDiff: longDiff,
           originalContent: 'old',
           newContent: 'new',
-          onConfirm: vi.fn(),
         },
       },
       index: 1,
diff --git a/packages/cli/src/ui/components/messages/RedirectionConfirmation.test.tsx b/packages/cli/src/ui/components/messages/RedirectionConfirmation.test.tsx
index a1159d4658..807a173778 100644
--- a/packages/cli/src/ui/components/messages/RedirectionConfirmation.test.tsx
+++ b/packages/cli/src/ui/components/messages/RedirectionConfirmation.test.tsx
@@ -4,10 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { describe, it, expect, beforeAll } from 'vitest';
 import { ToolConfirmationMessage } from './ToolConfirmationMessage.js';
 import type {
-  ToolCallConfirmationDetails,
+  SerializableConfirmationDetails,
   Config,
 } from '@google/gemini-cli-core';
 import { initializeShellParsers } from '@google/gemini-cli-core';
@@ -24,13 +24,12 @@ describe('ToolConfirmationMessage Redirection', () => {
   } as unknown as Config;
 
   it('should display redirection warning and tip for redirected commands', () => {
-    const confirmationDetails: ToolCallConfirmationDetails = {
+    const confirmationDetails: SerializableConfirmationDetails = {
       type: 'exec',
       title: 'Confirm Shell Command',
       command: 'echo "hello" > test.txt',
       rootCommand: 'echo, redirection (>)',
       rootCommands: ['echo'],
-      onConfirm: vi.fn(),
     };
 
     const { lastFrame } = renderWithProviders(
diff --git a/packages/cli/src/ui/components/messages/ToolConfirmationMessage.test.tsx b/packages/cli/src/ui/components/messages/ToolConfirmationMessage.test.tsx
index 283a24843f..3d0afc4ec8 100644
--- a/packages/cli/src/ui/components/messages/ToolConfirmationMessage.test.tsx
+++ b/packages/cli/src/ui/components/messages/ToolConfirmationMessage.test.tsx
@@ -7,7 +7,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { ToolConfirmationMessage } from './ToolConfirmationMessage.js';
 import type {
-  ToolCallConfirmationDetails,
+  SerializableConfirmationDetails,
   Config,
 } from '@google/gemini-cli-core';
 import { renderWithProviders } from '../../../test-utils/render.js';
@@ -39,12 +39,11 @@ describe('ToolConfirmationMessage', () => {
   } as unknown as Config;
 
   it('should not display urls if prompt and url are the same', () => {
-    const confirmationDetails: ToolCallConfirmationDetails = {
+    const confirmationDetails: SerializableConfirmationDetails = {
       type: 'info',
       title: 'Confirm Web Fetch',
       prompt: 'https://example.com',
       urls: ['https://example.com'],
-      onConfirm: vi.fn(),
     };
 
     const { lastFrame } = renderWithProviders(
@@ -61,7 +60,7 @@ describe('ToolConfirmationMessage', () => {
   });
 
   it('should display urls if prompt and url are different', () => {
-    const confirmationDetails: ToolCallConfirmationDetails = {
+    const confirmationDetails: SerializableConfirmationDetails = {
       type: 'info',
       title: 'Confirm Web Fetch',
       prompt:
@@ -69,7 +68,6 @@ describe('ToolConfirmationMessage', () => {
       urls: [
         'https://raw.githubusercontent.com/google/gemini-react/main/README.md',
       ],
-      onConfirm: vi.fn(),
     };
 
     const { lastFrame } = renderWithProviders(
@@ -86,14 +84,13 @@ describe('ToolConfirmationMessage', () => {
   });
 
   it('should display multiple commands for exec type when provided', () => {
-    const confirmationDetails: ToolCallConfirmationDetails = {
+    const confirmationDetails: SerializableConfirmationDetails = {
       type: 'exec',
       title: 'Confirm Multiple Commands',
       command: 'echo "hello"', // Primary command
       rootCommand: 'echo',
       rootCommands: ['echo'],
       commands: ['echo "hello"', 'ls -la', 'whoami'], // Multi-command list
-      onConfirm: vi.fn(),
     };
 
     const { lastFrame } = renderWithProviders(
@@ -114,7 +111,7 @@ describe('ToolConfirmationMessage', () => {
   });
 
   describe('with folder trust', () => {
-    const editConfirmationDetails: ToolCallConfirmationDetails = {
+    const editConfirmationDetails: SerializableConfirmationDetails = {
       type: 'edit',
       title: 'Confirm Edit',
       fileName: 'test.txt',
@@ -122,33 +119,29 @@ describe('ToolConfirmationMessage', () => {
       fileDiff: '...diff...',
       originalContent: 'a',
       newContent: 'b',
-      onConfirm: vi.fn(),
     };
 
-    const execConfirmationDetails: ToolCallConfirmationDetails = {
+    const execConfirmationDetails: SerializableConfirmationDetails = {
       type: 'exec',
       title: 'Confirm Execution',
       command: 'echo "hello"',
       rootCommand: 'echo',
       rootCommands: ['echo'],
-      onConfirm: vi.fn(),
     };
 
-    const infoConfirmationDetails: ToolCallConfirmationDetails = {
+    const infoConfirmationDetails: SerializableConfirmationDetails = {
       type: 'info',
       title: 'Confirm Web Fetch',
       prompt: 'https://example.com',
       urls: ['https://example.com'],
-      onConfirm: vi.fn(),
     };
 
-    const mcpConfirmationDetails: ToolCallConfirmationDetails = {
+    const mcpConfirmationDetails: SerializableConfirmationDetails = {
       type: 'mcp',
       title: 'Confirm MCP Tool',
       serverName: 'test-server',
       toolName: 'test-tool',
       toolDisplayName: 'Test Tool',
-      onConfirm: vi.fn(),
     };
 
     describe.each([
@@ -214,7 +207,7 @@ describe('ToolConfirmationMessage', () => {
   });
 
   describe('enablePermanentToolApproval setting', () => {
-    const editConfirmationDetails: ToolCallConfirmationDetails = {
+    const editConfirmationDetails: SerializableConfirmationDetails = {
       type: 'edit',
       title: 'Confirm Edit',
       fileName: 'test.txt',
@@ -222,7 +215,6 @@ describe('ToolConfirmationMessage', () => {
       fileDiff: '...diff...',
       originalContent: 'a',
       newContent: 'b',
-      onConfirm: vi.fn(),
     };
 
     it('should NOT show "Allow for all future sessions" when setting is false (default)', () => {
@@ -275,7 +267,7 @@ describe('ToolConfirmationMessage', () => {
   });
 
   describe('Modify with external editor option', () => {
-    const editConfirmationDetails: ToolCallConfirmationDetails = {
+    const editConfirmationDetails: SerializableConfirmationDetails = {
       type: 'edit',
       title: 'Confirm Edit',
       fileName: 'test.txt',
@@ -283,7 +275,6 @@ describe('ToolConfirmationMessage', () => {
       fileDiff: '...diff...',
       originalContent: 'a',
       newContent: 'b',
-      onConfirm: vi.fn(),
     };
 
     it('should show "Modify with external editor" when NOT in IDE mode', () => {
diff --git a/packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx b/packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx
index a527c13314..13feb1682f 100644
--- a/packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx
+++ b/packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx
@@ -11,7 +11,6 @@ import { DiffRenderer } from './DiffRenderer.js';
 import { RenderInline } from '../../utils/InlineMarkdownRenderer.js';
 import {
   type SerializableConfirmationDetails,
-  type ToolCallConfirmationDetails,
   type Config,
   type ToolConfirmationPayload,
   ToolConfirmationOutcome,
@@ -38,9 +37,7 @@ import { ExitPlanModeDialog } from '../ExitPlanModeDialog.js';
 
 export interface ToolConfirmationMessageProps {
   callId: string;
-  confirmationDetails:
-    | ToolCallConfirmationDetails
-    | SerializableConfirmationDetails;
+  confirmationDetails: SerializableConfirmationDetails;
   config: Config;
   isFocused?: boolean;
   availableTerminalHeight?: number;
diff --git a/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx b/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx
index d2ada4d659..3ce4fc54eb 100644
--- a/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx
+++ b/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx
@@ -70,7 +70,6 @@ describe('<ToolGroupMessage />', () => {
             type: 'info',
             title: 'Confirm tool',
             prompt: 'Do you want to proceed?',
-            onConfirm: vi.fn(),
           },
         }),
       ];
diff --git a/packages/cli/src/ui/contexts/ToolActionsContext.test.tsx b/packages/cli/src/ui/contexts/ToolActionsContext.test.tsx
index 3260ff3f0f..5a0cb5143e 100644
--- a/packages/cli/src/ui/contexts/ToolActionsContext.test.tsx
+++ b/packages/cli/src/ui/contexts/ToolActionsContext.test.tsx
@@ -14,7 +14,6 @@ import {
   ToolConfirmationOutcome,
   MessageBusType,
   IdeClient,
-  type ToolCallConfirmationDetails,
 } from '@google/gemini-cli-core';
 import { ToolCallStatus, type IndividualToolCallDisplay } from '../types.js';
 
@@ -50,21 +49,9 @@ describe('ToolActionsContext', () => {
       resultDisplay: undefined,
       confirmationDetails: { type: 'info', title: 'title', prompt: 'prompt' },
     },
-    {
-      callId: 'legacy-call',
-      name: 'legacy-tool',
-      description: 'desc',
-      status: ToolCallStatus.Confirming,
-      resultDisplay: undefined,
-      confirmationDetails: {
-        type: 'info',
-        title: 'legacy',
-        prompt: 'prompt',
-        onConfirm: vi.fn(),
-      } as ToolCallConfirmationDetails,
-    },
     {
       callId: 'edit-call',
+      correlationId: 'corr-edit',
       name: 'edit-tool',
       description: 'desc',
       status: ToolCallStatus.Confirming,
@@ -77,8 +64,7 @@ describe('ToolActionsContext', () => {
         fileDiff: 'diff',
         originalContent: 'old',
         newContent: 'new',
-        onConfirm: vi.fn(),
-      } as ToolCallConfirmationDetails,
+      },
     },
   ];
 
@@ -92,7 +78,7 @@ describe('ToolActionsContext', () => {
     </ToolActionsProvider>
   );
 
-  it('publishes to MessageBus for tools with correlationId (Modern Path)', async () => {
+  it('publishes to MessageBus for tools with correlationId', async () => {
     const { result } = renderHook(() => useToolActions(), { wrapper });
 
     await result.current.confirm(
@@ -110,27 +96,6 @@ describe('ToolActionsContext', () => {
     });
   });
 
-  it('calls onConfirm for legacy tools (Legacy Path)', async () => {
-    const { result } = renderHook(() => useToolActions(), { wrapper });
-    const legacyDetails = mockToolCalls[1]
-      .confirmationDetails as ToolCallConfirmationDetails;
-
-    await result.current.confirm(
-      'legacy-call',
-      ToolConfirmationOutcome.ProceedOnce,
-    );
-
-    if (legacyDetails && 'onConfirm' in legacyDetails) {
-      expect(legacyDetails.onConfirm).toHaveBeenCalledWith(
-        ToolConfirmationOutcome.ProceedOnce,
-        undefined,
-      );
-    } else {
-      throw new Error('Expected onConfirm to be present');
-    }
-    expect(mockMessageBus.publish).not.toHaveBeenCalled();
-  });
-
   it('handles cancel by calling confirm with Cancel outcome', async () => {
     const { result } = renderHook(() => useToolActions(), { wrapper });
 
@@ -170,13 +135,11 @@ describe('ToolActionsContext', () => {
       '/f.txt',
       'accepted',
     );
-    const editDetails = mockToolCalls[2]
-      .confirmationDetails as ToolCallConfirmationDetails;
-    if (editDetails && 'onConfirm' in editDetails) {
-      expect(editDetails.onConfirm).toHaveBeenCalled();
-    } else {
-      throw new Error('Expected onConfirm to be present');
-    }
+    expect(mockMessageBus.publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        correlationId: 'corr-edit',
+      }),
+    );
   });
 
   it('updates isDiffingEnabled when IdeClient status changes', async () => {
diff --git a/packages/cli/src/ui/contexts/ToolActionsContext.tsx b/packages/cli/src/ui/contexts/ToolActionsContext.tsx
index b0b67ebf38..d2d4f4322a 100644
--- a/packages/cli/src/ui/contexts/ToolActionsContext.tsx
+++ b/packages/cli/src/ui/contexts/ToolActionsContext.tsx
@@ -18,7 +18,6 @@ import {
   MessageBusType,
   type Config,
   type ToolConfirmationPayload,
-  type ToolCallConfirmationDetails,
   debugLogger,
 } from '@google/gemini-cli-core';
 import type { IndividualToolCallDisplay } from '../types.js';
@@ -113,8 +112,7 @@ export const ToolActionsProvider: React.FC<ToolActionsProviderProps> = (
         await ideClient?.resolveDiffFromCli(details.filePath, cliOutcome);
       }
 
-      // 2. Dispatch
-      // PATH A: Event Bus (Modern)
+      // 2. Dispatch via Event Bus
       if (tool.correlationId) {
         await config.getMessageBus().publish({
           type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
@@ -127,20 +125,7 @@ export const ToolActionsProvider: React.FC<ToolActionsProviderProps> = (
         return;
       }
 
-      // PATH B: Legacy Callback (Adapter or Old Scheduler)
-      if (
-        details &&
-        'onConfirm' in details &&
-        typeof details.onConfirm === 'function'
-      ) {
-        await (details as ToolCallConfirmationDetails).onConfirm(
-          outcome,
-          payload,
-        );
-        return;
-      }
-
-      debugLogger.warn(`ToolActions: No confirmation mechanism for ${callId}`);
+      debugLogger.warn(`ToolActions: No correlationId for ${callId}`);
     },
     [config, ideClient, toolCalls, isDiffingEnabled],
   );
diff --git a/packages/cli/src/ui/hooks/toolMapping.ts b/packages/cli/src/ui/hooks/toolMapping.ts
index e83fb583bf..00072b3d14 100644
--- a/packages/cli/src/ui/hooks/toolMapping.ts
+++ b/packages/cli/src/ui/hooks/toolMapping.ts
@@ -7,7 +7,6 @@
 import {
   type ToolCall,
   type Status as CoreStatus,
-  type ToolCallConfirmationDetails,
   type SerializableConfirmationDetails,
   type ToolResultDisplay,
   debugLogger,
@@ -76,10 +75,8 @@ export function mapToDisplay(
     };
 
     let resultDisplay: ToolResultDisplay | undefined = undefined;
-    let confirmationDetails:
-      | ToolCallConfirmationDetails
-      | SerializableConfirmationDetails
-      | undefined = undefined;
+    let confirmationDetails: SerializableConfirmationDetails | undefined =
+      undefined;
     let outputFile: string | undefined = undefined;
     let ptyId: number | undefined = undefined;
     let correlationId: string | undefined = undefined;
diff --git a/packages/cli/src/ui/hooks/useGeminiStream.test.tsx b/packages/cli/src/ui/hooks/useGeminiStream.test.tsx
index ed7168667a..3130ee6365 100644
--- a/packages/cli/src/ui/hooks/useGeminiStream.test.tsx
+++ b/packages/cli/src/ui/hooks/useGeminiStream.test.tsx
@@ -32,6 +32,7 @@ import {
   GeminiEventType as ServerGeminiEventType,
   ToolErrorType,
   ToolConfirmationOutcome,
+  MessageBusType,
   tokenLimit,
   debugLogger,
   coreEvents,
@@ -49,6 +50,11 @@ const mockSendMessageStream = vi
   .fn()
   .mockReturnValue((async function* () {})());
 const mockStartChat = vi.fn();
+const mockMessageBus = {
+  publish: vi.fn(),
+  subscribe: vi.fn(),
+  unsubscribe: vi.fn(),
+};
 
 const MockedGeminiClientClass = vi.hoisted(() =>
   vi.fn().mockImplementation(function (this: any, _config: any) {
@@ -250,6 +256,7 @@ describe('useGeminiStream', () => {
     isJitContextEnabled: vi.fn(() => false),
     getGlobalMemory: vi.fn(() => ''),
     getUserMemory: vi.fn(() => ''),
+    getMessageBus: vi.fn(() => mockMessageBus),
     getIdeMode: vi.fn(() => false),
     getEnableHooks: vi.fn(() => false),
   } as unknown as Config;
@@ -399,7 +406,6 @@ describe('useGeminiStream', () => {
     toolName: string,
     callId: string,
     confirmationType: 'edit' | 'info',
-    mockOnConfirm: Mock,
     status: TrackedToolCall['status'] = 'awaiting_approval',
   ): TrackedWaitingToolCall => ({
     request: {
@@ -416,7 +422,6 @@ describe('useGeminiStream', () => {
         ? {
             type: 'edit',
             title: 'Confirm Edit',
-            onConfirm: mockOnConfirm,
             fileName: 'file.txt',
             filePath: '/test/file.txt',
             fileDiff: 'fake diff',
@@ -426,7 +431,6 @@ describe('useGeminiStream', () => {
         : {
             type: 'info',
             title: `${toolName} confirmation`,
-            onConfirm: mockOnConfirm,
             prompt: `Execute ${toolName}?`,
           },
     tool: {
@@ -438,6 +442,7 @@ describe('useGeminiStream', () => {
     invocation: {
       getDescription: () => 'Mock description',
     } as unknown as AnyToolInvocation,
+    correlationId: `corr-${callId}`,
   });
 
   // Helper to render hook with default parameters - reduces boilerplate
@@ -1763,10 +1768,9 @@ describe('useGeminiStream', () => {
 
   describe('handleApprovalModeChange', () => {
     it('should auto-approve all pending tool calls when switching to YOLO mode', async () => {
-      const mockOnConfirm = vi.fn().mockResolvedValue(undefined);
       const awaitingApprovalToolCalls: TrackedToolCall[] = [
-        createMockToolCall('replace', 'call1', 'edit', mockOnConfirm),
-        createMockToolCall('read_file', 'call2', 'info', mockOnConfirm),
+        createMockToolCall('replace', 'call1', 'edit'),
+        createMockToolCall('read_file', 'call2', 'info'),
       ];
 
       const { result } = renderTestHook(awaitingApprovalToolCalls);
@@ -1776,21 +1780,27 @@ describe('useGeminiStream', () => {
       });
 
       // Both tool calls should be auto-approved
-      expect(mockOnConfirm).toHaveBeenCalledTimes(2);
-      expect(mockOnConfirm).toHaveBeenCalledWith(
-        ToolConfirmationOutcome.ProceedOnce,
+      expect(mockMessageBus.publish).toHaveBeenCalledTimes(2);
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: 'corr-call1',
+          outcome: ToolConfirmationOutcome.ProceedOnce,
+        }),
+      );
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({
+          correlationId: 'corr-call2',
+          outcome: ToolConfirmationOutcome.ProceedOnce,
+        }),
       );
     });
 
     it('should only auto-approve edit tools when switching to AUTO_EDIT mode', async () => {
-      const mockOnConfirmReplace = vi.fn().mockResolvedValue(undefined);
-      const mockOnConfirmWrite = vi.fn().mockResolvedValue(undefined);
-      const mockOnConfirmRead = vi.fn().mockResolvedValue(undefined);
-
       const awaitingApprovalToolCalls: TrackedToolCall[] = [
-        createMockToolCall('replace', 'call1', 'edit', mockOnConfirmReplace),
-        createMockToolCall('write_file', 'call2', 'edit', mockOnConfirmWrite),
-        createMockToolCall('read_file', 'call3', 'info', mockOnConfirmRead),
+        createMockToolCall('replace', 'call1', 'edit'),
+        createMockToolCall('write_file', 'call2', 'edit'),
+        createMockToolCall('read_file', 'call3', 'info'),
       ];
 
       const { result } = renderTestHook(awaitingApprovalToolCalls);
@@ -1800,21 +1810,21 @@ describe('useGeminiStream', () => {
       });
 
       // Only replace and write_file should be auto-approved
-      expect(mockOnConfirmReplace).toHaveBeenCalledWith(
-        ToolConfirmationOutcome.ProceedOnce,
+      expect(mockMessageBus.publish).toHaveBeenCalledTimes(2);
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({ correlationId: 'corr-call1' }),
       );
-      expect(mockOnConfirmWrite).toHaveBeenCalledWith(
-        ToolConfirmationOutcome.ProceedOnce,
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({ correlationId: 'corr-call2' }),
+      );
+      expect(mockMessageBus.publish).not.toHaveBeenCalledWith(
+        expect.objectContaining({ correlationId: 'corr-call3' }),
       );
-
-      // read_file should not be auto-approved
-      expect(mockOnConfirmRead).not.toHaveBeenCalled();
     });
 
     it('should not auto-approve any tools when switching to REQUIRE_CONFIRMATION mode', async () => {
-      const mockOnConfirm = vi.fn().mockResolvedValue(undefined);
       const awaitingApprovalToolCalls: TrackedToolCall[] = [
-        createMockToolCall('replace', 'call1', 'edit', mockOnConfirm),
+        createMockToolCall('replace', 'call1', 'edit'),
       ];
 
       const { result } = renderTestHook(awaitingApprovalToolCalls);
@@ -1824,21 +1834,19 @@ describe('useGeminiStream', () => {
       });
 
       // No tools should be auto-approved
-      expect(mockOnConfirm).not.toHaveBeenCalled();
+      expect(mockMessageBus.publish).not.toHaveBeenCalled();
     });
 
     it('should handle errors gracefully when auto-approving tool calls', async () => {
       const debuggerSpy = vi
         .spyOn(debugLogger, 'warn')
         .mockImplementation(() => {});
-      const mockOnConfirmSuccess = vi.fn().mockResolvedValue(undefined);
-      const mockOnConfirmError = vi
-        .fn()
-        .mockRejectedValue(new Error('Approval failed'));
+
+      mockMessageBus.publish.mockRejectedValueOnce(new Error('Bus error'));
 
       const awaitingApprovalToolCalls: TrackedToolCall[] = [
-        createMockToolCall('replace', 'call1', 'edit', mockOnConfirmSuccess),
-        createMockToolCall('write_file', 'call2', 'edit', mockOnConfirmError),
+        createMockToolCall('replace', 'call1', 'edit'),
+        createMockToolCall('write_file', 'call2', 'edit'),
       ];
 
       const { result } = renderTestHook(awaitingApprovalToolCalls);
@@ -1847,13 +1855,10 @@ describe('useGeminiStream', () => {
         await result.current.handleApprovalModeChange(ApprovalMode.YOLO);
       });
 
-      // Both confirmation methods should be called
-      expect(mockOnConfirmSuccess).toHaveBeenCalled();
-      expect(mockOnConfirmError).toHaveBeenCalled();
-
-      // Error should be logged
+      // Both should be attempted despite first error
+      expect(mockMessageBus.publish).toHaveBeenCalledTimes(2);
       expect(debuggerSpy).toHaveBeenCalledWith(
-        'Failed to auto-approve tool call call2:',
+        'Failed to auto-approve tool call call1:',
         expect.any(Error),
       );
 
@@ -1882,6 +1887,7 @@ describe('useGeminiStream', () => {
           invocation: {
             getDescription: () => 'Mock description',
           } as unknown as AnyToolInvocation,
+          correlationId: 'corr-1',
         } as unknown as TrackedWaitingToolCall,
       ];
 
@@ -1893,83 +1899,9 @@ describe('useGeminiStream', () => {
       });
     });
 
-    it('should skip tool calls without onConfirm method in confirmationDetails', async () => {
-      const awaitingApprovalToolCalls: TrackedToolCall[] = [
-        {
-          request: {
-            callId: 'call1',
-            name: 'replace',
-            args: { old_string: 'old', new_string: 'new' },
-            isClientInitiated: false,
-            prompt_id: 'prompt-id-1',
-          },
-          status: 'awaiting_approval',
-          responseSubmittedToGemini: false,
-          confirmationDetails: {
-            type: 'edit',
-            title: 'Confirm Edit',
-            // No onConfirm method
-            fileName: 'file.txt',
-            filePath: '/test/file.txt',
-            fileDiff: 'fake diff',
-            originalContent: 'old',
-            newContent: 'new',
-          } as any,
-          tool: {
-            name: 'replace',
-            displayName: 'replace',
-            description: 'Replace text',
-            build: vi.fn(),
-          } as any,
-          invocation: {
-            getDescription: () => 'Mock description',
-          } as unknown as AnyToolInvocation,
-        } as TrackedWaitingToolCall,
-      ];
-
-      const { result } = renderTestHook(awaitingApprovalToolCalls);
-
-      // Should not throw an error
-      await act(async () => {
-        await result.current.handleApprovalModeChange(ApprovalMode.YOLO);
-      });
-    });
-
     it('should only process tool calls with awaiting_approval status', async () => {
-      const mockOnConfirmAwaiting = vi.fn().mockResolvedValue(undefined);
-      const mockOnConfirmExecuting = vi.fn().mockResolvedValue(undefined);
-
       const mixedStatusToolCalls: TrackedToolCall[] = [
-        {
-          request: {
-            callId: 'call1',
-            name: 'replace',
-            args: { old_string: 'old', new_string: 'new' },
-            isClientInitiated: false,
-            prompt_id: 'prompt-id-1',
-          },
-          status: 'awaiting_approval',
-          responseSubmittedToGemini: false,
-          confirmationDetails: {
-            type: 'edit',
-            title: 'Confirm Edit',
-            onConfirm: mockOnConfirmAwaiting,
-            fileName: 'file.txt',
-            filePath: '/test/file.txt',
-            fileDiff: 'fake diff',
-            originalContent: 'old',
-            newContent: 'new',
-          },
-          tool: {
-            name: 'replace',
-            displayName: 'replace',
-            description: 'Replace text',
-            build: vi.fn(),
-          } as any,
-          invocation: {
-            getDescription: () => 'Mock description',
-          } as unknown as AnyToolInvocation,
-        } as TrackedWaitingToolCall,
+        createMockToolCall('replace', 'call1', 'edit'),
         {
           request: {
             callId: 'call2',
@@ -1991,6 +1923,7 @@ describe('useGeminiStream', () => {
           } as unknown as AnyToolInvocation,
           startTime: Date.now(),
           liveOutput: 'Writing...',
+          correlationId: 'corr-call2',
         } as TrackedExecutingToolCall,
       ];
 
@@ -2000,9 +1933,14 @@ describe('useGeminiStream', () => {
         await result.current.handleApprovalModeChange(ApprovalMode.YOLO);
       });
 
-      // Only the awaiting_approval tool should be processed
-      expect(mockOnConfirmAwaiting).toHaveBeenCalledTimes(1);
-      expect(mockOnConfirmExecuting).not.toHaveBeenCalled();
+      // Only the awaiting_approval tool should be processed.
+      expect(mockMessageBus.publish).toHaveBeenCalledTimes(1);
+      expect(mockMessageBus.publish).toHaveBeenCalledWith(
+        expect.objectContaining({ correlationId: 'corr-call1' }),
+      );
+      expect(mockMessageBus.publish).not.toHaveBeenCalledWith(
+        expect.objectContaining({ correlationId: 'corr-call2' }),
+      );
     });
   });
 
diff --git a/packages/cli/src/ui/hooks/useGeminiStream.ts b/packages/cli/src/ui/hooks/useGeminiStream.ts
index bba6977ffa..13f6d8cf70 100644
--- a/packages/cli/src/ui/hooks/useGeminiStream.ts
+++ b/packages/cli/src/ui/hooks/useGeminiStream.ts
@@ -20,6 +20,7 @@ import {
   ApprovalMode,
   parseAndFormatApiError,
   ToolConfirmationOutcome,
+  MessageBusType,
   promptIdContext,
   tokenLimit,
   debugLogger,
@@ -1408,10 +1409,15 @@ export const useGeminiStream = (
 
         // Process pending tool calls sequentially to reduce UI chaos
         for (const call of awaitingApprovalCalls) {
-          const details = call.confirmationDetails;
-          if (details && 'onConfirm' in details) {
+          if (call.correlationId) {
             try {
-              await details.onConfirm(ToolConfirmationOutcome.ProceedOnce);
+              await config.getMessageBus().publish({
+                type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+                correlationId: call.correlationId,
+                confirmed: true,
+                requiresUserConfirmation: false,
+                outcome: ToolConfirmationOutcome.ProceedOnce,
+              });
             } catch (error) {
               debugLogger.warn(
                 `Failed to auto-approve tool call ${call.request.callId}:`,
@@ -1422,7 +1428,7 @@ export const useGeminiStream = (
         }
       }
     },
-    [toolCalls],
+    [config, toolCalls],
   );
 
   const handleCompletedTools = useCallback(
diff --git a/packages/cli/src/ui/hooks/useToolScheduler.test.ts b/packages/cli/src/ui/hooks/useToolScheduler.test.ts
index 4a04d6225c..8ebf439630 100644
--- a/packages/cli/src/ui/hooks/useToolScheduler.test.ts
+++ b/packages/cli/src/ui/hooks/useToolScheduler.test.ts
@@ -10,12 +10,10 @@ import { renderHook } from '../../test-utils/render.js';
 import { useToolScheduler } from './useToolScheduler.js';
 import {
   MessageBusType,
-  ToolConfirmationOutcome,
   Scheduler,
   type Config,
   type MessageBus,
   type CompletedToolCall,
-  type ToolCallConfirmationDetails,
   type ToolCallsUpdateMessage,
   type AnyDeclarativeTool,
   type AnyToolInvocation,
@@ -132,122 +130,6 @@ describe('useToolScheduler', () => {
     });
   });
 
-  it('injects onConfirm callback for awaiting_approval tools (Adapter Pattern)', async () => {
-    const { result } = renderHook(() =>
-      useToolScheduler(
-        vi.fn().mockResolvedValue(undefined),
-        mockConfig,
-        () => undefined,
-      ),
-    );
-
-    const mockToolCall = {
-      status: 'awaiting_approval' as const,
-      request: {
-        callId: 'call-1',
-        name: 'test_tool',
-        args: {},
-        isClientInitiated: false,
-        prompt_id: 'p1',
-      },
-      tool: createMockTool(),
-      invocation: createMockInvocation({
-        getDescription: () => 'Confirming test tool',
-      }),
-      confirmationDetails: { type: 'info', title: 'Confirm', prompt: 'Sure?' },
-      correlationId: 'corr-123',
-    };
-
-    act(() => {
-      void mockMessageBus.publish({
-        type: MessageBusType.TOOL_CALLS_UPDATE,
-        toolCalls: [mockToolCall],
-        schedulerId: ROOT_SCHEDULER_ID,
-      } as ToolCallsUpdateMessage);
-    });
-
-    const [toolCalls] = result.current;
-    const call = toolCalls[0];
-    if (call.status !== 'awaiting_approval') {
-      throw new Error('Expected status to be awaiting_approval');
-    }
-    const confirmationDetails =
-      call.confirmationDetails as ToolCallConfirmationDetails;
-
-    expect(confirmationDetails).toBeDefined();
-    expect(typeof confirmationDetails.onConfirm).toBe('function');
-
-    // Test that onConfirm publishes to MessageBus
-    const publishSpy = vi.spyOn(mockMessageBus, 'publish');
-    await confirmationDetails.onConfirm(ToolConfirmationOutcome.ProceedOnce);
-
-    expect(publishSpy).toHaveBeenCalledWith({
-      type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
-      correlationId: 'corr-123',
-      confirmed: true,
-      requiresUserConfirmation: false,
-      outcome: ToolConfirmationOutcome.ProceedOnce,
-      payload: undefined,
-    });
-  });
-
-  it('injects onConfirm with payload (Inline Edit support)', async () => {
-    const { result } = renderHook(() =>
-      useToolScheduler(
-        vi.fn().mockResolvedValue(undefined),
-        mockConfig,
-        () => undefined,
-      ),
-    );
-
-    const mockToolCall = {
-      status: 'awaiting_approval' as const,
-      request: {
-        callId: 'call-1',
-        name: 'test_tool',
-        args: {},
-        isClientInitiated: false,
-        prompt_id: 'p1',
-      },
-      tool: createMockTool(),
-      invocation: createMockInvocation(),
-      confirmationDetails: { type: 'edit', title: 'Edit', filePath: 'test.ts' },
-      correlationId: 'corr-edit',
-    };
-
-    act(() => {
-      void mockMessageBus.publish({
-        type: MessageBusType.TOOL_CALLS_UPDATE,
-        toolCalls: [mockToolCall],
-        schedulerId: ROOT_SCHEDULER_ID,
-      } as ToolCallsUpdateMessage);
-    });
-
-    const [toolCalls] = result.current;
-    const call = toolCalls[0];
-    if (call.status !== 'awaiting_approval') {
-      throw new Error('Expected awaiting_approval');
-    }
-    const confirmationDetails =
-      call.confirmationDetails as ToolCallConfirmationDetails;
-
-    const publishSpy = vi.spyOn(mockMessageBus, 'publish');
-    const mockPayload = { newContent: 'updated code' };
-    await confirmationDetails.onConfirm(
-      ToolConfirmationOutcome.ProceedOnce,
-      mockPayload,
-    );
-
-    expect(publishSpy).toHaveBeenCalledWith({
-      type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
-      correlationId: 'corr-edit',
-      confirmed: true,
-      requiresUserConfirmation: false,
-      outcome: ToolConfirmationOutcome.ProceedOnce,
-      payload: mockPayload,
-    });
-  });
-
   it('preserves responseSubmittedToGemini flag across updates', () => {
     const { result } = renderHook(() =>
       useToolScheduler(
diff --git a/packages/cli/src/ui/hooks/useToolScheduler.ts b/packages/cli/src/ui/hooks/useToolScheduler.ts
index b50ed1b717..89bee14342 100644
--- a/packages/cli/src/ui/hooks/useToolScheduler.ts
+++ b/packages/cli/src/ui/hooks/useToolScheduler.ts
@@ -6,21 +6,18 @@
 
 import {
   type Config,
-  type MessageBus,
   type ToolCallRequestInfo,
   type ToolCall,
   type CompletedToolCall,
-  type ToolConfirmationPayload,
   MessageBusType,
-  ToolConfirmationOutcome,
+  ROOT_SCHEDULER_ID,
   Scheduler,
   type EditorType,
   type ToolCallsUpdateMessage,
-  ROOT_SCHEDULER_ID,
 } from '@google/gemini-cli-core';
 import { useCallback, useState, useMemo, useEffect, useRef } from 'react';
 
-// Re-exporting types compatible with legacy hook expectations
+// Re-exporting types compatible with hook expectations
 export type ScheduleFn = (
   request: ToolCallRequestInfo | ToolCallRequestInfo[],
   signal: AbortSignal,
@@ -109,8 +106,8 @@ export function useToolScheduler(
 
   const internalAdaptToolCalls = useCallback(
     (coreCalls: ToolCall[], prevTracked: TrackedToolCall[]) =>
-      adaptToolCalls(coreCalls, prevTracked, messageBus),
-    [messageBus],
+      adaptToolCalls(coreCalls, prevTracked),
+    [],
   );
 
   useEffect(() => {
@@ -227,12 +224,11 @@ export function useToolScheduler(
 }
 
 /**
- * ADAPTER: Merges UI metadata (submitted flag) and injects legacy callbacks.
+ * ADAPTER: Merges UI metadata (submitted flag).
  */
 function adaptToolCalls(
   coreCalls: ToolCall[],
   prevTracked: TrackedToolCall[],
-  messageBus: MessageBus,
 ): TrackedToolCall[] {
   const prevMap = new Map(prevTracked.map((t) => [t.request.callId, t]));
 
@@ -240,34 +236,6 @@ function adaptToolCalls(
     const prev = prevMap.get(coreCall.request.callId);
     const responseSubmittedToGemini = prev?.responseSubmittedToGemini ?? false;
 
-    // Inject onConfirm adapter for tools awaiting approval.
-    // The Core provides data-only (serializable) confirmationDetails. We must
-    // inject the legacy callback function that proxies responses back to the
-    // MessageBus.
-    if (coreCall.status === 'awaiting_approval' && coreCall.correlationId) {
-      const correlationId = coreCall.correlationId;
-      return {
-        ...coreCall,
-        confirmationDetails: {
-          ...coreCall.confirmationDetails,
-          onConfirm: async (
-            outcome: ToolConfirmationOutcome,
-            payload?: ToolConfirmationPayload,
-          ) => {
-            await messageBus.publish({
-              type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
-              correlationId,
-              confirmed: outcome !== ToolConfirmationOutcome.Cancel,
-              requiresUserConfirmation: false,
-              outcome,
-              payload,
-            });
-          },
-        },
-        responseSubmittedToGemini,
-      };
-    }
-
     return {
       ...coreCall,
       responseSubmittedToGemini,
diff --git a/packages/cli/src/ui/types.ts b/packages/cli/src/ui/types.ts
index c48b81bf9c..ca9a992f80 100644
--- a/packages/cli/src/ui/types.ts
+++ b/packages/cli/src/ui/types.ts
@@ -9,7 +9,6 @@ import type {
   GeminiCLIExtension,
   MCPServerConfig,
   ThoughtSummary,
-  ToolCallConfirmationDetails,
   SerializableConfirmationDetails,
   ToolResultDisplay,
   RetrieveUserQuotaResponse,
@@ -64,10 +63,7 @@ export interface ToolCallEvent {
   name: string;
   args: Record<string, never>;
   resultDisplay: ToolResultDisplay | undefined;
-  confirmationDetails:
-    | ToolCallConfirmationDetails
-    | SerializableConfirmationDetails
-    | undefined;
+  confirmationDetails: SerializableConfirmationDetails | undefined;
   correlationId?: string;
 }
 
@@ -77,10 +73,7 @@ export interface IndividualToolCallDisplay {
   description: string;
   resultDisplay: ToolResultDisplay | undefined;
   status: ToolCallStatus;
-  confirmationDetails:
-    | ToolCallConfirmationDetails
-    | SerializableConfirmationDetails
-    | undefined;
+  confirmationDetails: SerializableConfirmationDetails | undefined;
   renderOutputAsMarkdown?: boolean;
   ptyId?: number;
   outputFile?: string;
diff --git a/packages/cli/src/ui/utils/textUtils.test.ts b/packages/cli/src/ui/utils/textUtils.test.ts
index 0f9b2fcd39..be7f69d9f6 100644
--- a/packages/cli/src/ui/utils/textUtils.test.ts
+++ b/packages/cli/src/ui/utils/textUtils.test.ts
@@ -6,7 +6,7 @@
 
 import { describe, it, expect } from 'vitest';
 import type {
-  ToolCallConfirmationDetails,
+  SerializableConfirmationDetails,
   ToolEditConfirmationDetails,
 } from '@google/gemini-cli-core';
 import {
@@ -366,13 +366,12 @@ describe('textUtils', () => {
 
       describe('toolConfirmationDetails case study', () => {
         it('should sanitize command and rootCommand for exec type', () => {
-          const details: ToolCallConfirmationDetails = {
+          const details: SerializableConfirmationDetails = {
             title: '\u001b[34mfake-title\u001b[0m',
             type: 'exec',
             command: '\u001b[31mmls -l\u001b[0m',
             rootCommand: '\u001b[32msudo apt-get update\u001b[0m',
             rootCommands: ['sudo'],
-            onConfirm: async () => {},
           };
 
           const sanitized = escapeAnsiCtrlCodes(details);
@@ -387,14 +386,13 @@ describe('textUtils', () => {
         });
 
         it('should sanitize properties for edit type', () => {
-          const details: ToolCallConfirmationDetails = {
+          const details: SerializableConfirmationDetails = {
             type: 'edit',
             title: '\u001b[34mEdit File\u001b[0m',
             fileName: '\u001b[31mfile.txt\u001b[0m',
             filePath: '/path/to/\u001b[32mfile.txt\u001b[0m',
             fileDiff:
               'diff --git a/file.txt b/file.txt\n--- a/\u001b[33mfile.txt\u001b[0m\n+++ b/file.txt',
-            onConfirm: async () => {},
           } as unknown as ToolEditConfirmationDetails;
 
           const sanitized = escapeAnsiCtrlCodes(details);
@@ -412,13 +410,12 @@ describe('textUtils', () => {
         });
 
         it('should sanitize properties for mcp type', () => {
-          const details: ToolCallConfirmationDetails = {
+          const details: SerializableConfirmationDetails = {
             type: 'mcp',
             title: '\u001b[34mCloud Run\u001b[0m',
             serverName: '\u001b[31mmy-server\u001b[0m',
             toolName: '\u001b[32mdeploy\u001b[0m',
             toolDisplayName: '\u001b[33mDeploy Service\u001b[0m',
-            onConfirm: async () => {},
           };
 
           const sanitized = escapeAnsiCtrlCodes(details);
@@ -434,12 +431,11 @@ describe('textUtils', () => {
         });
 
         it('should sanitize properties for info type', () => {
-          const details: ToolCallConfirmationDetails = {
+          const details: SerializableConfirmationDetails = {
             type: 'info',
             title: '\u001b[34mWeb Search\u001b[0m',
             prompt: '\u001b[31mSearch for cats\u001b[0m',
             urls: ['https://\u001b[32mgoogle.com\u001b[0m'],
-            onConfirm: async () => {},
           };
 
           const sanitized = escapeAnsiCtrlCodes(details);
@@ -457,12 +453,11 @@ describe('textUtils', () => {
       });
 
       it('should not change the object if no sanitization is needed', () => {
-        const details: ToolCallConfirmationDetails = {
+        const details: SerializableConfirmationDetails = {
           type: 'info',
           title: 'Web Search',
           prompt: 'Search for cats',
           urls: ['https://google.com'],
-          onConfirm: async () => {},
         };
 
         const sanitized = escapeAnsiCtrlCodes(details);

From d82f66973fa0eeea0a09d19ce1ec08bb69a96449 Mon Sep 17 00:00:00 2001
From: Tommaso Sciortino <sciortino@gmail.com>
Date: Thu, 12 Feb 2026 18:27:56 -0800
Subject: [PATCH 40/44] Fix drag and drop escaping (#18965)

---
 .../ui/components/shared/text-buffer.test.ts  |  32 +-
 .../src/ui/components/shared/text-buffer.ts   |  10 +-
 .../src/ui/hooks/atCommandProcessor.test.ts   |  41 +++
 .../cli/src/ui/hooks/atCommandProcessor.ts    |  13 +-
 .../cli/src/ui/utils/clipboardUtils.test.ts   | 327 ++++++++++--------
 packages/cli/src/ui/utils/clipboardUtils.ts   | 127 ++++---
 packages/core/src/utils/paths.test.ts         | 273 +++++++--------
 packages/core/src/utils/paths.ts              |  68 ++--
 8 files changed, 492 insertions(+), 399 deletions(-)

diff --git a/packages/cli/src/ui/components/shared/text-buffer.test.ts b/packages/cli/src/ui/components/shared/text-buffer.test.ts
index 50a7fe795b..85754f9f62 100644
--- a/packages/cli/src/ui/components/shared/text-buffer.test.ts
+++ b/packages/cli/src/ui/components/shared/text-buffer.test.ts
@@ -41,6 +41,7 @@ import {
   getTransformedImagePath,
 } from './text-buffer.js';
 import { cpLen } from '../../utils/textUtils.js';
+import { escapePath } from '@google/gemini-cli-core';
 
 const defaultVisualLayout: VisualLayout = {
   visualLines: [''],
@@ -1077,14 +1078,16 @@ describe('useTextBuffer', () => {
         useTextBuffer({ viewport, escapePastedPaths: true }),
       );
       // Construct escaped path string: "/path/to/my\ file.txt /path/to/other.txt"
-      const escapedFile1 = file1.replace(/ /g, '\\ ');
-      const filePaths = `${escapedFile1} ${file2}`;
+
+      const filePaths = `${escapePath(file1)} ${file2}`;
 
       act(() => result.current.insert(filePaths, { paste: true }));
-      expect(getBufferState(result).text).toBe(`@${escapedFile1} @${file2} `);
+      expect(getBufferState(result).text).toBe(
+        `@${escapePath(file1)} @${file2} `,
+      );
     });
 
-    it('should only prepend @ to valid paths in multi-path paste', () => {
+    it('should not prepend @ unless all paths are valid', () => {
       const validFile = path.join(tempDir, 'valid.txt');
       const invalidFile = path.join(tempDir, 'invalid.jpg');
       fs.writeFileSync(validFile, '');
@@ -1098,7 +1101,7 @@ describe('useTextBuffer', () => {
       );
       const filePaths = `${validFile} ${invalidFile}`;
       act(() => result.current.insert(filePaths, { paste: true }));
-      expect(getBufferState(result).text).toBe(`@${validFile} ${invalidFile} `);
+      expect(getBufferState(result).text).toBe(`${validFile} ${invalidFile}`);
     });
   });
 
@@ -2869,12 +2872,26 @@ describe('Unicode helper functions', () => {
   });
 });
 
+const mockPlatform = (platform: string) => {
+  vi.stubGlobal(
+    'process',
+    Object.create(process, {
+      platform: {
+        get: () => platform,
+      },
+    }),
+  );
+};
+
 describe('Transformation Utilities', () => {
   afterEach(() => {
     vi.restoreAllMocks();
+    vi.unstubAllGlobals();
   });
 
   describe('getTransformedImagePath', () => {
+    beforeEach(() => mockPlatform('linux'));
+
     it('should transform a simple image path', () => {
       expect(getTransformedImagePath('@test.png')).toBe('[Image test.png]');
     });
@@ -2905,11 +2922,6 @@ describe('Transformation Utilities', () => {
       expect(getTransformedImagePath(input)).toBe('[Image image2x.png]');
     });
 
-    it('should handle Windows-style backslash paths on any platform', () => {
-      const input = '@C:\\Users\\foo\\screenshots\\image2x.png';
-      expect(getTransformedImagePath(input)).toBe('[Image image2x.png]');
-    });
-
     it('should handle escaped spaces in paths', () => {
       const input = '@path/to/my\\ file.png';
       expect(getTransformedImagePath(input)).toBe('[Image my file.png]');
diff --git a/packages/cli/src/ui/components/shared/text-buffer.ts b/packages/cli/src/ui/components/shared/text-buffer.ts
index d0f425129b..e641633e97 100644
--- a/packages/cli/src/ui/components/shared/text-buffer.ts
+++ b/packages/cli/src/ui/components/shared/text-buffer.ts
@@ -2814,15 +2814,7 @@ export function useTextBuffer({
         paste &&
         escapePastedPaths
       ) {
-        let potentialPath = ch.trim();
-        const quoteMatch = potentialPath.match(/^'(.*)'$/);
-        if (quoteMatch) {
-          potentialPath = quoteMatch[1];
-        }
-
-        potentialPath = potentialPath.trim();
-
-        const processed = parsePastedPaths(potentialPath);
+        const processed = parsePastedPaths(ch.trim());
         if (processed) {
           textToInsert = processed;
         }
diff --git a/packages/cli/src/ui/hooks/atCommandProcessor.test.ts b/packages/cli/src/ui/hooks/atCommandProcessor.test.ts
index 7a9601a4c6..76848ea821 100644
--- a/packages/cli/src/ui/hooks/atCommandProcessor.test.ts
+++ b/packages/cli/src/ui/hooks/atCommandProcessor.test.ts
@@ -145,6 +145,7 @@ describe('handleAtCommand', () => {
   afterEach(async () => {
     abortController.abort();
     await fsPromises.rm(testRootDir, { recursive: true, force: true });
+    vi.unstubAllGlobals();
   });
 
   it('should pass through query if no @ command is present', async () => {
@@ -319,6 +320,46 @@ describe('handleAtCommand', () => {
     );
   }, 10000);
 
+  it('should correctly handle double-quoted paths with spaces', async () => {
+    // Mock platform to win32 so unescapePath strips quotes
+    vi.stubGlobal(
+      'process',
+      Object.create(process, {
+        platform: {
+          get: () => 'win32',
+        },
+      }),
+    );
+
+    const fileContent = 'Content of file with spaces';
+    const filePath = await createTestFile(
+      path.join(testRootDir, 'my folder', 'my file.txt'),
+      fileContent,
+    );
+    // On Windows, the user might provide: @"path/to/my file.txt"
+    const query = `@"${filePath}"`;
+
+    const result = await handleAtCommand({
+      query,
+      config: mockConfig,
+      addItem: mockAddItem,
+      onDebugMessage: mockOnDebugMessage,
+      messageId: 126,
+      signal: abortController.signal,
+    });
+
+    const relativePath = getRelativePath(filePath);
+    expect(result).toEqual({
+      processedQuery: [
+        { text: `@${relativePath}` },
+        { text: '\n--- Content from referenced files ---' },
+        { text: `\nContent from @${relativePath}:\n` },
+        { text: fileContent },
+        { text: '\n--- End of content ---' },
+      ],
+    });
+  });
+
   it('should correctly handle file paths with narrow non-breaking space (NNBSP)', async () => {
     const nnbsp = '\u202F';
     const fileContent = 'NNBSP file content.';
diff --git a/packages/cli/src/ui/hooks/atCommandProcessor.ts b/packages/cli/src/ui/hooks/atCommandProcessor.ts
index 18dcf9a0de..e30f9abbc9 100644
--- a/packages/cli/src/ui/hooks/atCommandProcessor.ts
+++ b/packages/cli/src/ui/hooks/atCommandProcessor.ts
@@ -31,12 +31,13 @@ const REF_CONTENT_FOOTER = `\n${REFERENCE_CONTENT_END}`;
  * Regex source for the path/command part of an @ reference.
  * It uses strict ASCII whitespace delimiters to allow Unicode characters like NNBSP in filenames.
  *
- * 1. \\. matches any escaped character (e.g., \ ).
- * 2. [^ \t\n\r,;!?()\[\]{}.] matches any character that is NOT a delimiter and NOT a period.
- * 3. \.(?!$|[ \t\n\r]) matches a period ONLY if it is NOT followed by whitespace or end-of-string.
+ * 1. "(?:[^"]*)" matches a double-quoted string (for Windows paths with spaces).
+ * 2. \\. matches any escaped character (e.g., \ ).
+ * 3. [^ \t\n\r,;!?()\[\]{}.] matches any character that is NOT a delimiter and NOT a period.
+ * 4. \.(?!$|[ \t\n\r]) matches a period ONLY if it is NOT followed by whitespace or end-of-string.
  */
 export const AT_COMMAND_PATH_REGEX_SOURCE =
-  '(?:\\\\.|[^ \\t\\n\\r,;!?()\\[\\]{}.]|\\.(?!$|[ \\t\\n\\r]))+';
+  '(?:(?:"(?:[^"]*)")|(?:\\\\.|[^ \\t\\n\\r,;!?()\\[\\]{}.]|\\.(?!$|[ \\t\\n\\r])))+';
 
 interface HandleAtCommandParams {
   query: string;
@@ -85,8 +86,8 @@ function parseAllAtCommands(query: string): AtCommandPart[] {
       });
     }
 
-    // unescapePath expects the @ symbol to be present, and will handle it.
-    const atPath = unescapePath(fullMatch);
+    // We strip the @ before unescaping so that unescapePath can handle quoted paths correctly on Windows.
+    const atPath = '@' + unescapePath(fullMatch.substring(1));
     parts.push({ type: 'atPath', content: atPath });
 
     lastIndex = matchIndex + fullMatch.length;
diff --git a/packages/cli/src/ui/utils/clipboardUtils.test.ts b/packages/cli/src/ui/utils/clipboardUtils.test.ts
index 5b2df637c3..cfd9f115ba 100644
--- a/packages/cli/src/ui/utils/clipboardUtils.test.ts
+++ b/packages/cli/src/ui/utils/clipboardUtils.test.ts
@@ -62,15 +62,25 @@ import { spawnAsync } from '@google/gemini-cli-core';
 // Keep static imports for stateless functions
 import {
   cleanupOldClipboardImages,
-  splitEscapedPaths,
+  splitDragAndDropPaths,
   parsePastedPaths,
 } from './clipboardUtils.js';
 
+const mockPlatform = (platform: string) => {
+  vi.stubGlobal(
+    'process',
+    Object.create(process, {
+      platform: {
+        get: () => platform,
+      },
+    }),
+  );
+};
+
 // Define the type for the module to use in tests
 type ClipboardUtilsModule = typeof import('./clipboardUtils.js');
 
 describe('clipboardUtils', () => {
-  let originalPlatform: string;
   let originalEnv: NodeJS.ProcessEnv;
   // Dynamic module instance for stateful functions
   let clipboardUtils: ClipboardUtilsModule;
@@ -83,7 +93,6 @@ describe('clipboardUtils', () => {
 
   beforeEach(async () => {
     vi.resetAllMocks();
-    originalPlatform = process.platform;
     originalEnv = process.env;
     process.env = { ...originalEnv };
 
@@ -94,22 +103,13 @@ describe('clipboardUtils', () => {
   });
 
   afterEach(() => {
-    Object.defineProperty(process, 'platform', {
-      value: originalPlatform,
-    });
-    process.env = originalEnv;
+    vi.unstubAllGlobals();
     vi.restoreAllMocks();
   });
 
-  const setPlatform = (platform: string) => {
-    Object.defineProperty(process, 'platform', {
-      value: platform,
-    });
-  };
-
   describe('clipboardHasImage (Linux)', () => {
     it('should return true when wl-paste shows image type (Wayland)', async () => {
-      setPlatform('linux');
+      mockPlatform('linux');
       process.env['XDG_SESSION_TYPE'] = 'wayland';
       vi.mocked(execSync).mockReturnValue(Buffer.from('')); // command -v succeeds
       vi.mocked(spawnAsync).mockResolvedValueOnce({
@@ -128,7 +128,7 @@ describe('clipboardUtils', () => {
     });
 
     it('should return true when xclip shows image type (X11)', async () => {
-      setPlatform('linux');
+      mockPlatform('linux');
       process.env['XDG_SESSION_TYPE'] = 'x11';
       vi.mocked(execSync).mockReturnValue(Buffer.from('')); // command -v succeeds
       vi.mocked(spawnAsync).mockResolvedValueOnce({
@@ -153,7 +153,7 @@ describe('clipboardUtils', () => {
     });
 
     it('should return false if tool fails', async () => {
-      setPlatform('linux');
+      mockPlatform('linux');
       process.env['XDG_SESSION_TYPE'] = 'wayland';
       vi.mocked(execSync).mockReturnValue(Buffer.from(''));
       vi.mocked(spawnAsync).mockRejectedValueOnce(new Error('wl-paste failed'));
@@ -164,7 +164,7 @@ describe('clipboardUtils', () => {
     });
 
     it('should return false if no image type is found', async () => {
-      setPlatform('linux');
+      mockPlatform('linux');
       process.env['XDG_SESSION_TYPE'] = 'wayland';
       vi.mocked(execSync).mockReturnValue(Buffer.from(''));
       vi.mocked(spawnAsync).mockResolvedValueOnce({
@@ -178,7 +178,7 @@ describe('clipboardUtils', () => {
     });
 
     it('should return false if tool not found', async () => {
-      setPlatform('linux');
+      mockPlatform('linux');
       process.env['XDG_SESSION_TYPE'] = 'wayland';
       vi.mocked(execSync).mockImplementation(() => {
         throw new Error('Command not found');
@@ -195,7 +195,7 @@ describe('clipboardUtils', () => {
     const mockTempDir = path.join('/tmp/global', 'images');
 
     beforeEach(() => {
-      setPlatform('linux');
+      mockPlatform('linux');
       vi.mocked(fs.mkdir).mockResolvedValue(undefined);
       vi.mocked(fs.unlink).mockResolvedValue(undefined);
     });
@@ -363,65 +363,86 @@ describe('clipboardUtils', () => {
     });
   });
 
-  describe('splitEscapedPaths', () => {
-    it('should return single path when no spaces', () => {
-      expect(splitEscapedPaths('/path/to/image.png')).toEqual([
-        '/path/to/image.png',
-      ]);
+  describe('splitDragAndDropPaths', () => {
+    describe('in posix', () => {
+      beforeEach(() => mockPlatform('linux'));
+
+      it.each([
+        ['empty string', '', []],
+        ['single path no spaces', '/path/to/image.png', ['/path/to/image.png']],
+        [
+          'simple space-separated paths',
+          '/img1.png /img2.png',
+          ['/img1.png', '/img2.png'],
+        ],
+        [
+          'three paths',
+          '/a.png /b.jpg /c.heic',
+          ['/a.png', '/b.jpg', '/c.heic'],
+        ],
+        ['escaped spaces', '/my\\ image.png', ['/my image.png']],
+        [
+          'multiple paths with escaped spaces',
+          '/my\\ img1.png /my\\ img2.png',
+          ['/my img1.png', '/my img2.png'],
+        ],
+        [
+          'multiple escaped spaces',
+          '/path/to/my\\ cool\\ image.png',
+          ['/path/to/my cool image.png'],
+        ],
+        [
+          'consecutive spaces',
+          '/img1.png   /img2.png',
+          ['/img1.png', '/img2.png'],
+        ],
+        [
+          'trailing/leading whitespace',
+          '  /img1.png /img2.png  ',
+          ['/img1.png', '/img2.png'],
+        ],
+        ['whitespace only', '   ', []],
+        ['quoted path with spaces', '"/my image.png"', ['/my image.png']],
+        [
+          'mixed quoted and unquoted',
+          '"/my img1.png" /my\\ img2.png',
+          ['/my img1.png', '/my img2.png'],
+        ],
+        [
+          'quoted with escaped quotes',
+          "'/derp/my '\\''cool'\\'' image.png'",
+          ["/derp/my 'cool' image.png"],
+        ],
+      ])('should escape %s', (_, input, expected) => {
+        expect([...splitDragAndDropPaths(input)]).toEqual(expected);
+      });
     });
 
-    it('should split simple space-separated paths', () => {
-      expect(splitEscapedPaths('/img1.png /img2.png')).toEqual([
-        '/img1.png',
-        '/img2.png',
-      ]);
-    });
+    describe('in windows', () => {
+      beforeEach(() => mockPlatform('win32'));
 
-    it('should split three paths', () => {
-      expect(splitEscapedPaths('/a.png /b.jpg /c.heic')).toEqual([
-        '/a.png',
-        '/b.jpg',
-        '/c.heic',
-      ]);
-    });
-
-    it('should preserve escaped spaces within filenames', () => {
-      expect(splitEscapedPaths('/my\\ image.png')).toEqual(['/my\\ image.png']);
-    });
-
-    it('should handle multiple paths with escaped spaces', () => {
-      expect(splitEscapedPaths('/my\\ img1.png /my\\ img2.png')).toEqual([
-        '/my\\ img1.png',
-        '/my\\ img2.png',
-      ]);
-    });
-
-    it('should handle path with multiple escaped spaces', () => {
-      expect(splitEscapedPaths('/path/to/my\\ cool\\ image.png')).toEqual([
-        '/path/to/my\\ cool\\ image.png',
-      ]);
-    });
-
-    it('should handle multiple consecutive spaces between paths', () => {
-      expect(splitEscapedPaths('/img1.png   /img2.png')).toEqual([
-        '/img1.png',
-        '/img2.png',
-      ]);
-    });
-
-    it('should handle trailing and leading whitespace', () => {
-      expect(splitEscapedPaths('  /img1.png /img2.png  ')).toEqual([
-        '/img1.png',
-        '/img2.png',
-      ]);
-    });
-
-    it('should return empty array for empty string', () => {
-      expect(splitEscapedPaths('')).toEqual([]);
-    });
-
-    it('should return empty array for whitespace only', () => {
-      expect(splitEscapedPaths('   ')).toEqual([]);
+      it.each([
+        ['double quoted path', '"C:\\my image.png"', ['C:\\my image.png']],
+        [
+          'multiple double quoted paths',
+          '"C:\\img 1.png" "D:\\img 2.png"',
+          ['C:\\img 1.png', 'D:\\img 2.png'],
+        ],
+        ['unquoted path', 'C:\\img.png', ['C:\\img.png']],
+        [
+          'mixed quoted and unquoted',
+          '"C:\\img 1.png" D:\\img2.png',
+          ['C:\\img 1.png', 'D:\\img2.png'],
+        ],
+        ['single quoted path', "'C:\\my image.png'", ['C:\\my image.png']],
+        [
+          'mixed single and double quoted',
+          '"C:\\img 1.png" \'D:\\img 2.png\'',
+          ['C:\\img 1.png', 'D:\\img 2.png'],
+        ],
+      ])('should split %s', (_, input, expected) => {
+        expect([...splitDragAndDropPaths(input)]).toEqual(expected);
+      });
     });
   });
 
@@ -455,14 +476,14 @@ describe('clipboardUtils', () => {
       expect(result).toBe('@/path/to/file1.txt @/path/to/file2.txt ');
     });
 
-    it('should only add @ prefix to valid paths', () => {
+    it('should return null if any path is invalid', () => {
       vi.mocked(existsSync).mockImplementation((p) =>
         (p as string).endsWith('.txt'),
       );
       vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
 
       const result = parsePastedPaths('/valid/file.txt /invalid/file.jpg');
-      expect(result).toBe('@/valid/file.txt /invalid/file.jpg ');
+      expect(result).toBe(null);
     });
 
     it('should return null if no paths are valid', () => {
@@ -471,76 +492,110 @@ describe('clipboardUtils', () => {
       expect(result).toBe(null);
     });
 
-    it('should handle paths with escaped spaces', () => {
-      const validPaths = new Set(['/path/to/my file.txt', '/other/path.txt']);
-      vi.mocked(existsSync).mockImplementation((p) =>
-        validPaths.has(p as string),
-      );
-      vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
-
-      const result = parsePastedPaths('/path/to/my\\ file.txt /other/path.txt');
-      expect(result).toBe('@/path/to/my\\ file.txt @/other/path.txt ');
-    });
-
-    it('should unescape paths before validation', () => {
-      const validPaths = new Set(['/my file.txt', '/other.txt']);
-      const validatedPaths: string[] = [];
-      vi.mocked(existsSync).mockImplementation((p) => {
-        validatedPaths.push(p as string);
-        return validPaths.has(p as string);
+    describe('in posix', () => {
+      beforeEach(() => {
+        mockPlatform('linux');
       });
-      vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
 
-      parsePastedPaths('/my\\ file.txt /other.txt');
-      // First checks entire string, then individual unescaped segments
-      expect(validatedPaths).toEqual([
-        '/my\\ file.txt /other.txt',
-        '/my file.txt',
-        '/other.txt',
-      ]);
+      it('should handle paths with escaped spaces', () => {
+        const validPaths = new Set(['/path/to/my file.txt', '/other/path.txt']);
+        vi.mocked(existsSync).mockImplementation((p) =>
+          validPaths.has(p as string),
+        );
+        vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
+
+        const result = parsePastedPaths(
+          '/path/to/my\\ file.txt /other/path.txt',
+        );
+        expect(result).toBe('@/path/to/my\\ file.txt @/other/path.txt ');
+      });
+
+      it('should unescape paths before validation', () => {
+        const validPaths = new Set(['/my file.txt', '/other.txt']);
+        const validatedPaths: string[] = [];
+        vi.mocked(existsSync).mockImplementation((p) => {
+          validatedPaths.push(p as string);
+          return validPaths.has(p as string);
+        });
+        vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
+
+        parsePastedPaths('/my\\ file.txt /other.txt');
+        // First checks entire string, then individual unescaped segments
+        expect(validatedPaths).toEqual([
+          '/my\\ file.txt /other.txt',
+          '/my file.txt',
+          '/other.txt',
+        ]);
+      });
+
+      it('should handle single path with unescaped spaces from copy-paste', () => {
+        vi.mocked(existsSync).mockReturnValue(true);
+        vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
+
+        const result = parsePastedPaths('/path/to/my file.txt');
+        expect(result).toBe('@/path/to/my\\ file.txt ');
+      });
+
+      it('should handle single-quoted with escaped quote', () => {
+        const validPaths = new Set([
+          "/usr/test/my file with 'single quotes'.txt",
+        ]);
+        const validatedPaths: string[] = [];
+        vi.mocked(existsSync).mockImplementation((p) => {
+          validatedPaths.push(p as string);
+          return validPaths.has(p as string);
+        });
+        vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
+
+        const result = parsePastedPaths(
+          "'/usr/test/my file with '\\''single quotes'\\''.txt'",
+        );
+        expect(result).toBe(
+          "@/usr/test/my\\ file\\ with\\ \\'single\\ quotes\\'.txt ",
+        );
+
+        expect(validatedPaths).toEqual([
+          "/usr/test/my file with 'single quotes'.txt",
+        ]);
+      });
     });
 
-    it('should handle single path with unescaped spaces from copy-paste', () => {
-      vi.mocked(existsSync).mockReturnValue(true);
-      vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
+    describe('in windows', () => {
+      beforeEach(() => mockPlatform('win32'));
 
-      const result = parsePastedPaths('/path/to/my file.txt');
-      expect(result).toBe('@/path/to/my\\ file.txt ');
-    });
+      it('should handle Windows path', () => {
+        vi.mocked(existsSync).mockReturnValue(true);
+        vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
 
-    it('should handle Windows path', () => {
-      vi.mocked(existsSync).mockReturnValue(true);
-      vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
+        const result = parsePastedPaths('C:\\Users\\file.txt');
+        expect(result).toBe('@C:\\Users\\file.txt ');
+      });
 
-      const result = parsePastedPaths('C:\\Users\\file.txt');
-      expect(result).toBe('@C:\\Users\\file.txt ');
-    });
+      it('should handle Windows path with unescaped spaces', () => {
+        vi.mocked(existsSync).mockReturnValue(true);
+        vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
 
-    it('should handle Windows path with unescaped spaces', () => {
-      vi.mocked(existsSync).mockReturnValue(true);
-      vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
+        const result = parsePastedPaths('C:\\My Documents\\file.txt');
+        expect(result).toBe('@"C:\\My Documents\\file.txt" ');
+      });
+      it('should handle multiple Windows paths', () => {
+        const validPaths = new Set(['C:\\file1.txt', 'D:\\file2.txt']);
+        vi.mocked(existsSync).mockImplementation((p) =>
+          validPaths.has(p as string),
+        );
+        vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
 
-      const result = parsePastedPaths('C:\\My Documents\\file.txt');
-      expect(result).toBe('@C:\\My\\ Documents\\file.txt ');
-    });
+        const result = parsePastedPaths('C:\\file1.txt D:\\file2.txt');
+        expect(result).toBe('@C:\\file1.txt @D:\\file2.txt ');
+      });
 
-    it('should handle multiple Windows paths', () => {
-      const validPaths = new Set(['C:\\file1.txt', 'D:\\file2.txt']);
-      vi.mocked(existsSync).mockImplementation((p) =>
-        validPaths.has(p as string),
-      );
-      vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
+      it('should handle Windows UNC path', () => {
+        vi.mocked(existsSync).mockReturnValue(true);
+        vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
 
-      const result = parsePastedPaths('C:\\file1.txt D:\\file2.txt');
-      expect(result).toBe('@C:\\file1.txt @D:\\file2.txt ');
-    });
-
-    it('should handle Windows UNC path', () => {
-      vi.mocked(existsSync).mockReturnValue(true);
-      vi.mocked(statSync).mockReturnValue(MOCK_FILE_STATS);
-
-      const result = parsePastedPaths('\\\\server\\share\\file.txt');
-      expect(result).toBe('@\\\\server\\share\\file.txt ');
+        const result = parsePastedPaths('\\\\server\\share\\file.txt');
+        expect(result).toBe('@\\\\server\\share\\file.txt ');
+      });
     });
   });
 });
diff --git a/packages/cli/src/ui/utils/clipboardUtils.ts b/packages/cli/src/ui/utils/clipboardUtils.ts
index a6a7b485cd..fd46a2c749 100644
--- a/packages/cli/src/ui/utils/clipboardUtils.ts
+++ b/packages/cli/src/ui/utils/clipboardUtils.ts
@@ -11,7 +11,6 @@ import * as path from 'node:path';
 import {
   debugLogger,
   spawnAsync,
-  unescapePath,
   escapePath,
   Storage,
 } from '@google/gemini-cli-core';
@@ -418,48 +417,77 @@ export async function cleanupOldClipboardImages(
     debugLogger.debug('Failed to clean up old clipboard images:', e);
   }
 }
-
 /**
- * Splits text into individual path segments, respecting escaped spaces.
- * Unescaped spaces act as separators between paths, while "\ " is preserved
- * as part of a filename.
+ * Splits a pasted text block up into escaped path segements if it's a legal
+ * drag-and-drop string.
  *
- * Example: "/img1.png /path/my\ image.png" → ["/img1.png", "/path/my\ image.png"]
+ * There are multiple ways drag-and-drop paths might be escaped:
+ *  - Bare (only if there are no special chars): /path/to/myfile.png
+ *  - Wrapped in double quotes (Windows only): "/path/to/my file~!.png"
+ *  - Escaped with backslashes (POSIX only): /path/to/my\ file~!.png
+ *  - Wrapped in single quotes: '/path/to/my file~!.png'
  *
- * @param text The text to split
- * @returns Array of path segments (still escaped)
+ * When wrapped in single quotes, actual single quotes in the filename are
+ * escaped with "'\''". For example: '/path/to/my '\''fancy file'\''.png'
+ *
+ * When wrapped in double quotes, actual double quotes are not an issue becuase
+ * windows doesn't allow them in filenames.
+ *
+ * On all systems, a single drag-and-drop may include both wrapped and bare
+ * paths, so we need to handle both simultaneously.
+ *
+ * @param text
+ * @returns An iterable of escaped paths
  */
-export function splitEscapedPaths(text: string): string[] {
-  const paths: string[] = [];
+export function* splitDragAndDropPaths(text: string): Generator<string> {
   let current = '';
-  let i = 0;
+  let mode: 'NORMAL' | 'DOUBLE' | 'SINGLE' = 'NORMAL';
+  const isWindows = process.platform === 'win32';
 
+  let i = 0;
   while (i < text.length) {
     const char = text[i];
 
-    if (char === '\\' && i + 1 < text.length && text[i + 1] === ' ') {
-      // Escaped space - part of filename, preserve the escape sequence
-      current += '\\ ';
-      i += 2;
-    } else if (char === ' ') {
-      // Unescaped space - path separator
-      if (current.trim()) {
-        paths.push(current.trim());
+    if (mode === 'NORMAL') {
+      if (char === ' ') {
+        if (current.length > 0) {
+          yield current;
+          current = '';
+        }
+      } else if (char === '"') {
+        mode = 'DOUBLE';
+      } else if (char === "'") {
+        mode = 'SINGLE';
+      } else if (char === '\\' && !isWindows) {
+        // POSIX escape in normal mode
+        if (i + 1 < text.length) {
+          const next = text[i + 1];
+          current += next;
+          i++;
+        }
+      } else {
+        current += char;
+      }
+    } else if (mode === 'DOUBLE') {
+      if (char === '"') {
+        mode = 'NORMAL';
+      } else {
+        current += char;
+      }
+    } else if (mode === 'SINGLE') {
+      if (char === "'") {
+        mode = 'NORMAL';
+      } else {
+        current += char;
       }
-      current = '';
-      i++;
-    } else {
-      current += char;
-      i++;
     }
+
+    i++;
   }
 
-  // Don't forget the last segment
-  if (current.trim()) {
-    paths.push(current.trim());
+  if (current.length > 0) {
+    yield current;
   }
-
-  return paths;
 }
 
 /**
@@ -467,44 +495,35 @@ export function splitEscapedPaths(text: string): string[] {
  */
 function isValidFilePath(p: string): boolean {
   try {
-    return existsSync(p) && statSync(p).isFile();
+    return PATH_PREFIX_PATTERN.test(p) && existsSync(p) && statSync(p).isFile();
   } catch {
     return false;
   }
 }
 
 /**
- * Processes pasted text containing file paths, adding @ prefix to valid paths.
- * Handles both single and multiple space-separated paths.
+ * Processes pasted text containing file paths (like those from drag and drop),
+ * adding @ prefix to valid paths and escaping them in a standard way.
  *
- * @param text The pasted text (potentially space-separated paths)
- * @returns Processed string with @ prefixes on valid paths, or null if no valid paths
+ * @param text The pasted text
+ * @returns Processed string with @ prefixes or null if any paths are invalid
  */
 export function parsePastedPaths(text: string): string | null {
   // First, check if the entire text is a single valid path
-  if (PATH_PREFIX_PATTERN.test(text) && isValidFilePath(text)) {
+  if (isValidFilePath(text)) {
     return `@${escapePath(text)} `;
   }
 
-  // Otherwise, try splitting on unescaped spaces
-  const segments = splitEscapedPaths(text);
-  if (segments.length === 0) {
+  const validPaths = [];
+  for (const segment of splitDragAndDropPaths(text)) {
+    if (isValidFilePath(segment)) {
+      validPaths.push(`@${escapePath(segment)}`);
+    } else {
+      return null; // If any segment is invalid, return null for the whole string
+    }
+  }
+  if (validPaths.length === 0) {
     return null;
   }
-
-  let anyValidPath = false;
-  const processedPaths = segments.map((segment) => {
-    // Quick rejection: skip segments that can't be paths
-    if (!PATH_PREFIX_PATTERN.test(segment)) {
-      return segment;
-    }
-    const unescaped = unescapePath(segment);
-    if (isValidFilePath(unescaped)) {
-      anyValidPath = true;
-      return `@${segment}`;
-    }
-    return segment;
-  });
-
-  return anyValidPath ? processedPaths.join(' ') + ' ' : null;
+  return validPaths.join(' ') + ' ';
 }
diff --git a/packages/core/src/utils/paths.test.ts b/packages/core/src/utils/paths.test.ts
index 64e4e94ddc..bfca3763e2 100644
--- a/packages/core/src/utils/paths.test.ts
+++ b/packages/core/src/utils/paths.test.ts
@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import * as fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -24,131 +24,118 @@ vi.mock('node:fs', async (importOriginal) => {
   };
 });
 
+const mockPlatform = (platform: string) => {
+  vi.stubGlobal(
+    'process',
+    Object.create(process, {
+      platform: {
+        get: () => platform,
+      },
+    }),
+  );
+};
+
 describe('escapePath', () => {
-  it.each([
-    ['spaces', 'my file.txt', 'my\\ file.txt'],
-    ['tabs', 'file\twith\ttabs.txt', 'file\\\twith\\\ttabs.txt'],
-    ['parentheses', 'file(1).txt', 'file\\(1\\).txt'],
-    ['square brackets', 'file[backup].txt', 'file\\[backup\\].txt'],
-    ['curly braces', 'file{temp}.txt', 'file\\{temp\\}.txt'],
-    ['semicolons', 'file;name.txt', 'file\\;name.txt'],
-    ['ampersands', 'file&name.txt', 'file\\&name.txt'],
-    ['pipes', 'file|name.txt', 'file\\|name.txt'],
-    ['asterisks', 'file*.txt', 'file\\*.txt'],
-    ['question marks', 'file?.txt', 'file\\?.txt'],
-    ['dollar signs', 'file$name.txt', 'file\\$name.txt'],
-    ['backticks', 'file`name.txt', 'file\\`name.txt'],
-    ['single quotes', "file'name.txt", "file\\'name.txt"],
-    ['double quotes', 'file"name.txt', 'file\\"name.txt'],
-    ['hash symbols', 'file#name.txt', 'file\\#name.txt'],
-    ['exclamation marks', 'file!name.txt', 'file\\!name.txt'],
-    [
-      'tildes',
-      'file~name.txt',
-      process.platform === 'win32' ? 'file~name.txt' : 'file\\~name.txt',
-    ],
-    [
-      'less than and greater than signs',
-      'file<name>.txt',
-      'file\\<name\\>.txt',
-    ],
-  ])('should escape %s', (_, input, expected) => {
-    expect(escapePath(input)).toBe(expected);
+  afterEach(() => vi.unstubAllGlobals());
+
+  describe('in posix', () => {
+    beforeEach(() => mockPlatform('linux'));
+
+    it.each([
+      ['spaces', 'my file.txt', 'my\\ file.txt'],
+      ['tabs', 'file\twith\ttabs.txt', 'file\\\twith\\\ttabs.txt'],
+      ['parentheses', 'file(1).txt', 'file\\(1\\).txt'],
+      ['square brackets', 'file[backup].txt', 'file\\[backup\\].txt'],
+      ['curly braces', 'file{temp}.txt', 'file\\{temp\\}.txt'],
+      ['semicolons', 'file;name.txt', 'file\\;name.txt'],
+      ['ampersands', 'file&name.txt', 'file\\&name.txt'],
+      ['pipes', 'file|name.txt', 'file\\|name.txt'],
+      ['asterisks', 'file*.txt', 'file\\*.txt'],
+      ['question marks', 'file?.txt', 'file\\?.txt'],
+      ['dollar signs', 'file$name.txt', 'file\\$name.txt'],
+      ['backticks', 'file`name.txt', 'file\\`name.txt'],
+      ['single quotes', "file'name.txt", "file\\'name.txt"],
+      ['double quotes', 'file"name.txt', 'file\\"name.txt'],
+      ['hash symbols', 'file#name.txt', 'file\\#name.txt'],
+      ['exclamation marks', 'file!name.txt', 'file\\!name.txt'],
+      ['tildes', 'file~name.txt', 'file\\~name.txt'],
+      [
+        'less than and greater than signs',
+        'file<name>.txt',
+        'file\\<name\\>.txt',
+      ],
+      [
+        'multiple special characters',
+        'my file (backup) [v1.2].txt',
+        'my\\ file\\ \\(backup\\)\\ \\[v1.2\\].txt',
+      ],
+      ['normal file', 'normalfile.txt', 'normalfile.txt'],
+      ['normal path', 'path/to/normalfile.txt', 'path/to/normalfile.txt'],
+      [
+        'real world example 1',
+        'My Documents/Project (2024)/file [backup].txt',
+        'My\\ Documents/Project\\ \\(2024\\)/file\\ \\[backup\\].txt',
+      ],
+      [
+        'real world example 2',
+        'file with $special &chars!.txt',
+        'file\\ with\\ \\$special\\ \\&chars\\!.txt',
+      ],
+      ['empty string', '', ''],
+      [
+        'all special chars',
+        ' ()[]{};&|*?$`\'"#!<>',
+        '\\ \\(\\)\\[\\]\\{\\}\\;\\&\\|\\*\\?\\$\\`\\\'\\"\\#\\!\\<\\>',
+      ],
+    ])('should escape %s', (_, input, expected) => {
+      expect(escapePath(input)).toBe(expected);
+    });
   });
 
-  it('should handle multiple special characters', () => {
-    expect(escapePath('my file (backup) [v1.2].txt')).toBe(
-      'my\\ file\\ \\(backup\\)\\ \\[v1.2\\].txt',
-    );
-  });
+  describe('in windows', () => {
+    beforeEach(() => mockPlatform('win32'));
 
-  it('should not double-escape already escaped characters', () => {
-    expect(escapePath('my\\ file.txt')).toBe('my\\ file.txt');
-    expect(escapePath('file\\(name\\).txt')).toBe('file\\(name\\).txt');
-  });
-
-  it('should handle escaped backslashes correctly', () => {
-    // Double backslash (escaped backslash) followed by space should escape the space
-    expect(escapePath('path\\\\ file.txt')).toBe('path\\\\\\ file.txt');
-    // Triple backslash (escaped backslash + escaping backslash) followed by space should not double-escape
-    expect(escapePath('path\\\\\\ file.txt')).toBe('path\\\\\\ file.txt');
-    // Quadruple backslash (two escaped backslashes) followed by space should escape the space
-    expect(escapePath('path\\\\\\\\ file.txt')).toBe('path\\\\\\\\\\ file.txt');
-  });
-
-  it('should handle complex escaped backslash scenarios', () => {
-    // Escaped backslash before special character that needs escaping
-    expect(escapePath('file\\\\(test).txt')).toBe('file\\\\\\(test\\).txt');
-    // Multiple escaped backslashes
-    expect(escapePath('path\\\\\\\\with space.txt')).toBe(
-      'path\\\\\\\\with\\ space.txt',
-    );
-  });
-
-  it('should handle paths without special characters', () => {
-    expect(escapePath('normalfile.txt')).toBe('normalfile.txt');
-    expect(escapePath('path/to/normalfile.txt')).toBe('path/to/normalfile.txt');
-  });
-
-  it('should handle complex real-world examples', () => {
-    expect(escapePath('My Documents/Project (2024)/file [backup].txt')).toBe(
-      'My\\ Documents/Project\\ \\(2024\\)/file\\ \\[backup\\].txt',
-    );
-    expect(escapePath('file with $special &chars!.txt')).toBe(
-      'file\\ with\\ \\$special\\ \\&chars\\!.txt',
-    );
-  });
-
-  it('should handle empty strings', () => {
-    expect(escapePath('')).toBe('');
-  });
-
-  it('should handle paths with multiple special characters', () => {
-    expect(escapePath(' ()[]{};&|*?$`\'"#!<>')).toBe(
-      '\\ \\(\\)\\[\\]\\{\\}\\;\\&\\|\\*\\?\\$\\`\\\'\\"\\#\\!\\<\\>',
-    );
-  });
-
-  it('should handle tildes based on platform', () => {
-    const expected = process.platform === 'win32' ? '~' : '\\~';
-    expect(escapePath('~')).toBe(expected);
+    it.each([
+      [
+        'spaces',
+        'C:\\path with spaces\\file.txt',
+        '"C:\\path with spaces\\file.txt"',
+      ],
+      ['parentheses', 'file(1).txt', '"file(1).txt"'],
+      ['special chars', 'file&name.txt', '"file&name.txt"'],
+      ['caret', 'file^name.txt', '"file^name.txt"'],
+      ['normal path', 'C:\\path\\to\\file.txt', 'C:\\path\\to\\file.txt'],
+    ])('should escape %s', (_, input, expected) => {
+      expect(escapePath(input)).toBe(expected);
+    });
   });
 });
 
 describe('unescapePath', () => {
-  it.each([
-    ['spaces', 'my\\ file.txt', 'my file.txt'],
-    ['tabs', 'file\\\twith\\\ttabs.txt', 'file\twith\ttabs.txt'],
-    ['parentheses', 'file\\(1\\).txt', 'file(1).txt'],
-    ['square brackets', 'file\\[backup\\].txt', 'file[backup].txt'],
-    ['curly braces', 'file\\{temp\\}.txt', 'file{temp}.txt'],
-  ])('should unescape %s', (_, input, expected) => {
-    expect(unescapePath(input)).toBe(expected);
-  });
+  afterEach(() => vi.unstubAllGlobals());
 
-  it('should unescape multiple special characters', () => {
-    expect(unescapePath('my\\ file\\ \\(backup\\)\\ \\[v1.2\\].txt')).toBe(
-      'my file (backup) [v1.2].txt',
-    );
-  });
+  describe('in posix', () => {
+    beforeEach(() => mockPlatform('linux'));
 
-  it('should handle paths without escaped characters', () => {
-    expect(unescapePath('normalfile.txt')).toBe('normalfile.txt');
-    expect(unescapePath('path/to/normalfile.txt')).toBe(
-      'path/to/normalfile.txt',
-    );
-  });
+    it.each([
+      ['spaces', 'my\\ file.txt', 'my file.txt'],
+      ['tabs', 'file\\\twith\\\ttabs.txt', 'file\twith\ttabs.txt'],
+      ['parentheses', 'file\\(1\\).txt', 'file(1).txt'],
+      ['square brackets', 'file\\[backup\\].txt', 'file[backup].txt'],
+      ['curly braces', 'file\\{temp\\}.txt', 'file{temp}.txt'],
+      [
+        'multiple special characters',
+        'my\\ file\\ \\(backup\\)\\ \\[v1.2\\].txt',
+        'my file (backup) [v1.2].txt',
+      ],
+      ['normal file', 'normalfile.txt', 'normalfile.txt'],
+      ['normal path', 'path/to/normalfile.txt', 'path/to/normalfile.txt'],
+      ['empty string', '', ''],
+    ])('should unescape %s', (_, input, expected) => {
+      expect(unescapePath(input)).toBe(expected);
+    });
 
-  it('should handle all special characters but tilda', () => {
-    expect(
-      unescapePath(
-        '\\ \\(\\)\\[\\]\\{\\}\\;\\&\\|\\*\\?\\$\\`\\\'\\"\\#\\!\\<\\>',
-      ),
-    ).toBe(' ()[]{};&|*?$`\'"#!<>');
-  });
-
-  it('should be the inverse of escapePath', () => {
-    const testCases = [
+    it.each([
       'my file.txt',
       'file(1).txt',
       'file[backup].txt',
@@ -156,29 +143,35 @@ describe('unescapePath', () => {
       'file with $special &chars!.txt',
       ' ()[]{};&|*?$`\'"#!~<>',
       'file\twith\ttabs.txt',
-    ];
-
-    testCases.forEach((testCase) => {
-      expect(unescapePath(escapePath(testCase))).toBe(testCase);
+    ])('should unescape escaped %s', (input) => {
+      expect(unescapePath(escapePath(input))).toBe(input);
     });
   });
 
-  it('should handle empty strings', () => {
-    expect(unescapePath('')).toBe('');
-  });
+  describe('in windows', () => {
+    beforeEach(() => mockPlatform('win32'));
 
-  it('should not affect backslashes not followed by special characters', () => {
-    expect(unescapePath('file\\name.txt')).toBe('file\\name.txt');
-    expect(unescapePath('path\\to\\file.txt')).toBe('path\\to\\file.txt');
-  });
+    it.each([
+      [
+        'quoted path',
+        '"C:\\path with spaces\\file.txt"',
+        'C:\\path with spaces\\file.txt',
+      ],
+      ['unquoted path', 'C:\\path\\to\\file.txt', 'C:\\path\\to\\file.txt'],
+      ['partially quoted', '"C:\\path', '"C:\\path'],
+      ['empty string', '', ''],
+    ])('should unescape %s', (_, input, expected) => {
+      expect(unescapePath(input)).toBe(expected);
+    });
 
-  it('should handle escaped backslashes in unescaping', () => {
-    // Should correctly unescape when there are escaped backslashes
-    expect(unescapePath('path\\\\\\ file.txt')).toBe('path\\\\ file.txt');
-    expect(unescapePath('path\\\\\\\\\\ file.txt')).toBe(
-      'path\\\\\\\\ file.txt',
-    );
-    expect(unescapePath('file\\\\\\(test\\).txt')).toBe('file\\\\(test).txt');
+    it.each([
+      'C:\\path\\to\\file.txt',
+      'C:\\path with spaces\\file.txt',
+      'file(1).txt',
+      'file&name.txt',
+    ])('should unescape escaped %s', (input) => {
+      expect(unescapePath(escapePath(input))).toBe(input);
+    });
   });
 });
 
@@ -222,19 +215,9 @@ describe('isSubpath', () => {
 });
 
 describe('isSubpath on Windows', () => {
-  const originalPlatform = process.platform;
+  afterEach(() => vi.unstubAllGlobals());
 
-  beforeAll(() => {
-    Object.defineProperty(process, 'platform', {
-      value: 'win32',
-    });
-  });
-
-  afterAll(() => {
-    Object.defineProperty(process, 'platform', {
-      value: originalPlatform,
-    });
-  });
+  beforeEach(() => mockPlatform('win32'));
 
   it('should return true for a direct subpath on Windows', () => {
     expect(isSubpath('C:\\Users\\Test', 'C:\\Users\\Test\\file.txt')).toBe(
diff --git a/packages/core/src/utils/paths.ts b/packages/core/src/utils/paths.ts
index e2b6a72b64..6c3236606d 100644
--- a/packages/core/src/utils/paths.ts
+++ b/packages/core/src/utils/paths.ts
@@ -6,7 +6,6 @@
 
 import path from 'node:path';
 import os from 'node:os';
-import process from 'node:process';
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -14,15 +13,6 @@ import { fileURLToPath } from 'node:url';
 export const GEMINI_DIR = '.gemini';
 export const GOOGLE_ACCOUNTS_FILENAME = 'google_accounts.json';
 
-/**
- * Special characters that need to be escaped in file paths for shell compatibility.
- * Note that windows doesn't escape tilda.
- */
-export const SHELL_SPECIAL_CHARS =
-  process.platform === 'win32'
-    ? /[ \t()[\]{};|*?$`'"#&<>!]/
-    : /[ \t()[\]{};|*?$`'"#&<>!~]/;
-
 /**
  * Returns the home directory.
  * If GEMINI_CLI_HOME environment variable is set, it returns its value.
@@ -280,43 +270,43 @@ export function makeRelative(
 }
 
 /**
- * Escapes special characters in a file path like macOS terminal does.
- * Escapes: spaces, parentheses, brackets, braces, semicolons, ampersands, pipes,
- * asterisks, question marks, dollar signs, backticks, quotes, hash, and other shell metacharacters.
+ * Escape paths for at-commands.
+ *
+ *  - Windows: double quoted if they contain special chars, otherwise bare
+ *  - POSIX: backslash-escaped
  */
 export function escapePath(filePath: string): string {
-  let result = '';
-  for (let i = 0; i < filePath.length; i++) {
-    const char = filePath[i];
-
-    // Count consecutive backslashes before this character
-    let backslashCount = 0;
-    for (let j = i - 1; j >= 0 && filePath[j] === '\\'; j--) {
-      backslashCount++;
-    }
-
-    // Character is already escaped if there's an odd number of backslashes before it
-    const isAlreadyEscaped = backslashCount % 2 === 1;
-
-    // Only escape if not already escaped
-    if (!isAlreadyEscaped && SHELL_SPECIAL_CHARS.test(char)) {
-      result += '\\' + char;
-    } else {
-      result += char;
+  if (process.platform === 'win32') {
+    // Windows: Double quote if it contains space or special chars
+    if (/[\s()[\]{};|&^$!@%`'~]/.test(filePath)) {
+      return `"${filePath}"`;
     }
+    return filePath;
+  } else {
+    // POSIX: Backslash escape
+    return filePath.replace(/([ \t()[\]{};|*?$`'"#&<>!~\\])/g, '\\$1');
   }
-  return result;
 }
 
 /**
- * Unescapes special characters in a file path.
- * Removes backslash escaping from shell metacharacters.
+ * Unescapes paths for at-commands.
+ *
+ *  - Windows: double quoted if they contain special chars, otherwise bare
+ *  - POSIX: backslash-escaped
  */
 export function unescapePath(filePath: string): string {
-  return filePath.replace(
-    new RegExp(`\\\\([${SHELL_SPECIAL_CHARS.source.slice(1, -1)}])`, 'g'),
-    '$1',
-  );
+  if (process.platform === 'win32') {
+    if (
+      filePath.length >= 2 &&
+      filePath.startsWith('"') &&
+      filePath.endsWith('"')
+    ) {
+      return filePath.slice(1, -1);
+    }
+    return filePath;
+  } else {
+    return filePath.replace(/\\(.)/g, '$1');
+  }
 }
 
 /**
@@ -345,7 +335,7 @@ export function normalizePath(p: string): string {
  * @returns True if childPath is a subpath of parentPath, false otherwise.
  */
 export function isSubpath(parentPath: string, childPath: string): boolean {
-  const isWindows = os.platform() === 'win32';
+  const isWindows = process.platform === 'win32';
   const pathModule = isWindows ? path.win32 : path;
 
   // On Windows, path.relative is case-insensitive. On POSIX, it's case-sensitive.

From bed3eae0e160aa85cf1f06a841bc015fc59d4d2c Mon Sep 17 00:00:00 2001
From: Michael Bleigh <mbleigh@mbleigh.com>
Date: Thu, 12 Feb 2026 22:08:27 -0800
Subject: [PATCH 41/44] feat(sdk): initial package bootstrap for SDK (#18861)

---
 eslint.config.js                              |  12 ++
 package-lock.json                             |  21 +++
 .../cli/src/validateNonInterActiveAuth.ts     |  17 +--
 packages/core/src/core/contentGenerator.ts    |  21 +++
 packages/core/src/index.ts                    |   1 +
 packages/sdk/README.md                        |  36 +++++
 packages/sdk/examples/simple.ts               |  38 +++++
 packages/sdk/index.ts                         |   7 +
 packages/sdk/package.json                     |  36 +++++
 packages/sdk/src/agent.ts                     | 130 ++++++++++++++++++
 packages/sdk/src/index.ts                     |   8 ++
 packages/sdk/src/tool.ts                      | 113 +++++++++++++++
 packages/sdk/tsconfig.json                    |  12 ++
 packages/sdk/vitest.config.ts                 |  14 ++
 14 files changed, 451 insertions(+), 15 deletions(-)
 create mode 100644 packages/sdk/README.md
 create mode 100644 packages/sdk/examples/simple.ts
 create mode 100644 packages/sdk/index.ts
 create mode 100644 packages/sdk/package.json
 create mode 100644 packages/sdk/src/agent.ts
 create mode 100644 packages/sdk/src/index.ts
 create mode 100644 packages/sdk/src/tool.ts
 create mode 100644 packages/sdk/tsconfig.json
 create mode 100644 packages/sdk/vitest.config.ts

diff --git a/eslint.config.js b/eslint.config.js
index 7839ae78f6..48af3775f2 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -239,6 +239,18 @@ export default tseslint.config(
       ],
     },
   },
+  {
+    files: ['packages/sdk/src/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          name: '@google/gemini-cli-sdk',
+          message: 'Please use relative imports within the @google/gemini-cli-sdk package.',
+        },
+      ],
+    },
+  },
   {
     files: ['packages/*/src/**/*.test.{ts,tsx}'],
     plugins: {
diff --git a/package-lock.json b/package-lock.json
index c457eb7d55..6450eced3d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1389,6 +1389,10 @@
       "resolved": "packages/core",
       "link": true
     },
+    "node_modules/@google/gemini-cli-sdk": {
+      "resolved": "packages/sdk",
+      "link": true
+    },
     "node_modules/@google/gemini-cli-test-utils": {
       "resolved": "packages/test-utils",
       "link": true
@@ -17557,6 +17561,23 @@
         "uuid": "dist-node/bin/uuid"
       }
     },
+    "packages/sdk": {
+      "name": "@google/gemini-cli-sdk",
+      "version": "0.29.0-nightly.20260203.71f46f116",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@google/gemini-cli-core": "file:../core",
+        "zod": "^3.23.8",
+        "zod-to-json-schema": "^3.23.1"
+      },
+      "devDependencies": {
+        "typescript": "^5.3.3",
+        "vitest": "^3.1.1"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "packages/test-utils": {
       "name": "@google/gemini-cli-test-utils",
       "version": "0.30.0-nightly.20260210.a2174751d",
diff --git a/packages/cli/src/validateNonInterActiveAuth.ts b/packages/cli/src/validateNonInterActiveAuth.ts
index 668d0390de..a9a6bf6035 100644
--- a/packages/cli/src/validateNonInterActiveAuth.ts
+++ b/packages/cli/src/validateNonInterActiveAuth.ts
@@ -4,12 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { Config } from '@google/gemini-cli-core';
+import type { Config, AuthType } from '@google/gemini-cli-core';
 import {
-  AuthType,
   debugLogger,
   OutputFormat,
   ExitCodes,
+  getAuthTypeFromEnv,
 } from '@google/gemini-cli-core';
 import { USER_SETTINGS_PATH } from './config/settings.js';
 import { validateAuthMethod } from './config/auth.js';
@@ -17,19 +17,6 @@ import { type LoadedSettings } from './config/settings.js';
 import { handleError } from './utils/errors.js';
 import { runExitCleanup } from './utils/cleanup.js';
 
-function getAuthTypeFromEnv(): AuthType | undefined {
-  if (process.env['GOOGLE_GENAI_USE_GCA'] === 'true') {
-    return AuthType.LOGIN_WITH_GOOGLE;
-  }
-  if (process.env['GOOGLE_GENAI_USE_VERTEXAI'] === 'true') {
-    return AuthType.USE_VERTEX_AI;
-  }
-  if (process.env['GEMINI_API_KEY']) {
-    return AuthType.USE_GEMINI;
-  }
-  return undefined;
-}
-
 export async function validateNonInteractiveAuth(
   configuredAuthType: AuthType | undefined,
   useExternalAuth: boolean | undefined,
diff --git a/packages/core/src/core/contentGenerator.ts b/packages/core/src/core/contentGenerator.ts
index c0bb4909a1..0c9b36634e 100644
--- a/packages/core/src/core/contentGenerator.ts
+++ b/packages/core/src/core/contentGenerator.ts
@@ -56,6 +56,27 @@ export enum AuthType {
   COMPUTE_ADC = 'compute-default-credentials',
 }
 
+/**
+ * Detects the best authentication type based on environment variables.
+ *
+ * Checks in order:
+ * 1. GOOGLE_GENAI_USE_GCA=true -> LOGIN_WITH_GOOGLE
+ * 2. GOOGLE_GENAI_USE_VERTEXAI=true -> USE_VERTEX_AI
+ * 3. GEMINI_API_KEY -> USE_GEMINI
+ */
+export function getAuthTypeFromEnv(): AuthType | undefined {
+  if (process.env['GOOGLE_GENAI_USE_GCA'] === 'true') {
+    return AuthType.LOGIN_WITH_GOOGLE;
+  }
+  if (process.env['GOOGLE_GENAI_USE_VERTEXAI'] === 'true') {
+    return AuthType.USE_VERTEX_AI;
+  }
+  if (process.env['GEMINI_API_KEY']) {
+    return AuthType.USE_GEMINI;
+  }
+  return undefined;
+}
+
 export type ContentGeneratorConfig = {
   apiKey?: string;
   vertexai?: boolean;
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 448e555df4..c8ba601cbb 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -140,6 +140,7 @@ export * from './prompts/mcp-prompts.js';
 export * from './agents/types.js';
 export * from './agents/agentLoader.js';
 export * from './agents/local-executor.js';
+export * from './agents/agent-scheduler.js';
 
 // Export specific tool logic
 export * from './tools/read-file.js';
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
new file mode 100644
index 0000000000..5500abc5ff
--- /dev/null
+++ b/packages/sdk/README.md
@@ -0,0 +1,36 @@
+# @google/gemini-cli-sdk
+
+The Gemini CLI SDK provides a programmatic interface to interact with Gemini
+models and tools.
+
+## Installation
+
+```bash
+npm install @google/gemini-cli-sdk
+```
+
+## Usage
+
+```typescript
+import { GeminiCliAgent } from '@google/gemini-cli-sdk';
+
+async function main() {
+  const agent = new GeminiCliAgent({
+    instructions: 'You are a helpful assistant.',
+  });
+
+  const controller = new AbortController();
+  const signal = controller.signal;
+
+  // Stream responses from the agent
+  const stream = agent.sendStream('Why is the sky blue?', signal);
+
+  for await (const chunk of stream) {
+    if (chunk.type === 'content') {
+      process.stdout.write(chunk.value.text || '');
+    }
+  }
+}
+
+main().catch(console.error);
+```
diff --git a/packages/sdk/examples/simple.ts b/packages/sdk/examples/simple.ts
new file mode 100644
index 0000000000..6c2773b0c8
--- /dev/null
+++ b/packages/sdk/examples/simple.ts
@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { GeminiCliAgent, tool, z } from '../src/index.js';
+
+async function main() {
+  const myTool = tool(
+    {
+      name: 'add',
+      description: 'Add two numbers.',
+      inputSchema: z.object({
+        a: z.number().describe('the first number'),
+        b: z.number().describe('the second number'),
+      }),
+    },
+    async ({ a, b }) => {
+      console.log(`Tool 'add' called with a=${a}, b=${b}`);
+      return { result: a + b };
+    },
+  );
+
+  const agent = new GeminiCliAgent({
+    instructions: 'Make sure to always talk like a pirate.',
+    tools: [myTool],
+  });
+
+  console.log("Sending prompt: 'add 5 + 6'");
+  for await (const chunk of agent.sendStream(
+    'add 5 + 6 and tell me a story involving the result',
+  )) {
+    console.log(JSON.stringify(chunk, null, 2));
+  }
+}
+
+main().catch(console.error);
diff --git a/packages/sdk/index.ts b/packages/sdk/index.ts
new file mode 100644
index 0000000000..75f5121413
--- /dev/null
+++ b/packages/sdk/index.ts
@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from './src/index.js';
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
new file mode 100644
index 0000000000..19c85ed58a
--- /dev/null
+++ b/packages/sdk/package.json
@@ -0,0 +1,36 @@
+{
+  "name": "@google/gemini-cli-sdk",
+  "version": "0.29.0-nightly.20260203.71f46f116",
+  "description": "Gemini CLI SDK",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/google-gemini/gemini-cli.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "node ../../scripts/build_package.js",
+    "lint": "eslint . --ext .ts,.tsx",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:ci": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@google/gemini-cli-core": "file:../core",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}
diff --git a/packages/sdk/src/agent.ts b/packages/sdk/src/agent.ts
new file mode 100644
index 0000000000..b2ac5a1872
--- /dev/null
+++ b/packages/sdk/src/agent.ts
@@ -0,0 +1,130 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  Config,
+  type ConfigParameters,
+  PREVIEW_GEMINI_MODEL_AUTO,
+  GeminiEventType,
+  type ToolCallRequestInfo,
+  type ServerGeminiStreamEvent,
+  type GeminiClient,
+  scheduleAgentTools,
+  getAuthTypeFromEnv,
+  AuthType,
+} from '@google/gemini-cli-core';
+
+import { type Tool, SdkTool, type z } from './tool.js';
+
+export interface GeminiCliAgentOptions {
+  instructions: string;
+  tools?: Array<Tool<z.ZodType>>;
+  model?: string;
+  cwd?: string;
+  debug?: boolean;
+}
+
+export class GeminiCliAgent {
+  private readonly config: Config;
+  private readonly tools: Array<Tool<z.ZodType>>;
+
+  constructor(options: GeminiCliAgentOptions) {
+    const cwd = options.cwd || process.cwd();
+    this.tools = options.tools || [];
+
+    const configParams: ConfigParameters = {
+      sessionId: `sdk-${Date.now()}`,
+      targetDir: cwd,
+      cwd,
+      debugMode: options.debug ?? false,
+      model: options.model || PREVIEW_GEMINI_MODEL_AUTO,
+      userMemory: options.instructions,
+      // Minimal config
+      enableHooks: false,
+      mcpEnabled: false,
+      extensionsEnabled: false,
+    };
+
+    this.config = new Config(configParams);
+  }
+
+  async *sendStream(
+    prompt: string,
+    signal?: AbortSignal,
+  ): AsyncGenerator<ServerGeminiStreamEvent> {
+    // Lazy initialization of auth and client
+    if (!this.config.getContentGenerator()) {
+      const authType = getAuthTypeFromEnv() || AuthType.COMPUTE_ADC;
+
+      await this.config.refreshAuth(authType);
+      await this.config.initialize();
+
+      // Register tools now that registry exists
+      const registry = this.config.getToolRegistry();
+      const messageBus = this.config.getMessageBus();
+
+      for (const toolDef of this.tools) {
+        const sdkTool = new SdkTool(toolDef, messageBus);
+        registry.registerTool(sdkTool);
+      }
+    }
+
+    const client = this.config.getGeminiClient();
+
+    let request: Parameters<GeminiClient['sendMessageStream']>[0] = [
+      { text: prompt },
+    ];
+    const abortSignal = signal ?? new AbortController().signal;
+    const sessionId = this.config.getSessionId();
+
+    while (true) {
+      // sendMessageStream returns AsyncGenerator<ServerGeminiStreamEvent, Turn>
+      const stream = client.sendMessageStream(request, abortSignal, sessionId);
+
+      const toolCallsToSchedule: ToolCallRequestInfo[] = [];
+
+      for await (const event of stream) {
+        yield event;
+        if (event.type === GeminiEventType.ToolCallRequest) {
+          const toolCall = event.value;
+          let args = toolCall.args;
+          if (typeof args === 'string') {
+            args = JSON.parse(args);
+          }
+          toolCallsToSchedule.push({
+            ...toolCall,
+            args,
+            isClientInitiated: false,
+            prompt_id: sessionId,
+          });
+        }
+      }
+
+      if (toolCallsToSchedule.length === 0) {
+        break;
+      }
+
+      const completedCalls = await scheduleAgentTools(
+        this.config,
+        toolCallsToSchedule,
+        {
+          schedulerId: sessionId,
+          toolRegistry: this.config.getToolRegistry(),
+          signal: abortSignal,
+        },
+      );
+
+      const functionResponses = completedCalls.flatMap(
+        (call) => call.response.responseParts,
+      );
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      request = functionResponses as unknown as Parameters<
+        GeminiClient['sendMessageStream']
+      >[0];
+    }
+  }
+}
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
new file mode 100644
index 0000000000..0ad940d7b2
--- /dev/null
+++ b/packages/sdk/src/index.ts
@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from './agent.js';
+export * from './tool.js';
diff --git a/packages/sdk/src/tool.ts b/packages/sdk/src/tool.ts
new file mode 100644
index 0000000000..00cd3802de
--- /dev/null
+++ b/packages/sdk/src/tool.ts
@@ -0,0 +1,113 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import {
+  BaseDeclarativeTool,
+  BaseToolInvocation,
+  type ToolResult,
+  type ToolInvocation,
+  Kind,
+  type MessageBus,
+} from '@google/gemini-cli-core';
+
+export { z };
+
+export interface ToolDefinition<T extends z.ZodType> {
+  name: string;
+  description: string;
+  inputSchema: T;
+}
+
+export interface Tool<T extends z.ZodType> extends ToolDefinition<T> {
+  action: (params: z.infer<T>) => Promise<unknown>;
+}
+
+class SdkToolInvocation<T extends z.ZodType> extends BaseToolInvocation<
+  z.infer<T>,
+  ToolResult
+> {
+  constructor(
+    params: z.infer<T>,
+    messageBus: MessageBus,
+    private readonly action: (params: z.infer<T>) => Promise<unknown>,
+    toolName: string,
+  ) {
+    super(params, messageBus, toolName);
+  }
+
+  getDescription(): string {
+    return `Executing ${this._toolName}...`;
+  }
+
+  async execute(
+    _signal: AbortSignal,
+    _updateOutput?: (output: string) => void,
+  ): Promise<ToolResult> {
+    try {
+      const result = await this.action(this.params);
+      const output =
+        typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+      return {
+        llmContent: output,
+        returnDisplay: output,
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      return {
+        llmContent: `Error: ${errorMessage}`,
+        returnDisplay: `Error: ${errorMessage}`,
+        error: {
+          message: errorMessage,
+        },
+      };
+    }
+  }
+}
+
+export class SdkTool<T extends z.ZodType> extends BaseDeclarativeTool<
+  z.infer<T>,
+  ToolResult
+> {
+  constructor(
+    private readonly definition: Tool<T>,
+    messageBus: MessageBus,
+  ) {
+    super(
+      definition.name,
+      definition.name,
+      definition.description,
+      Kind.Other,
+      zodToJsonSchema(definition.inputSchema),
+      messageBus,
+    );
+  }
+
+  protected createInvocation(
+    params: z.infer<T>,
+    messageBus: MessageBus,
+    toolName?: string,
+  ): ToolInvocation<z.infer<T>, ToolResult> {
+    return new SdkToolInvocation(
+      params,
+      messageBus,
+      this.definition.action,
+      toolName || this.name,
+    );
+  }
+}
+
+export function tool<T extends z.ZodType>(
+  definition: ToolDefinition<T>,
+  action: (params: z.infer<T>) => Promise<unknown>,
+): Tool<T> {
+  return {
+    ...definition,
+    action,
+  };
+}
diff --git a/packages/sdk/tsconfig.json b/packages/sdk/tsconfig.json
new file mode 100644
index 0000000000..2cd4d6ea73
--- /dev/null
+++ b/packages/sdk/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "composite": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2023"],
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["index.ts", "src/**/*.ts", "package.json"],
+  "exclude": ["node_modules", "dist"],
+  "references": [{ "path": "../core" }]
+}
diff --git a/packages/sdk/vitest.config.ts b/packages/sdk/vitest.config.ts
new file mode 100644
index 0000000000..08cdff095c
--- /dev/null
+++ b/packages/sdk/vitest.config.ts
@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+  },
+});

From b61a123da861f14a0d83739fe9190a287b4181ca Mon Sep 17 00:00:00 2001
From: Michael Bleigh <mbleigh@mbleigh.com>
Date: Thu, 12 Feb 2026 23:28:48 -0800
Subject: [PATCH 42/44] feat(sdk): implements SessionContext for SDK tool calls
 (#18862)

---
 .prettierignore                               |   1 +
 packages/core/src/index.ts                    |   3 +
 packages/sdk/SDK_DESIGN.md                    | 279 ++++++++++++++++++
 packages/sdk/examples/session-context.ts      |  73 +++++
 packages/sdk/src/agent.ts                     |  55 +++-
 packages/sdk/src/fs.ts                        |  35 +++
 packages/sdk/src/index.ts                     |   1 +
 packages/sdk/src/shell.ts                     |  69 +++++
 packages/sdk/src/tool.integration.test.ts     | 147 +++++++++
 packages/sdk/src/tool.test.ts                 | 143 +++++++++
 packages/sdk/src/tool.ts                      |  77 +++--
 packages/sdk/src/types.ts                     |  41 +++
 .../sdk/test-data/tool-catchall-error.json    |   2 +
 .../sdk/test-data/tool-error-recovery.json    |   2 +
 packages/sdk/test-data/tool-success.json      |   2 +
 15 files changed, 903 insertions(+), 27 deletions(-)
 create mode 100644 packages/sdk/SDK_DESIGN.md
 create mode 100644 packages/sdk/examples/session-context.ts
 create mode 100644 packages/sdk/src/fs.ts
 create mode 100644 packages/sdk/src/shell.ts
 create mode 100644 packages/sdk/src/tool.integration.test.ts
 create mode 100644 packages/sdk/src/tool.test.ts
 create mode 100644 packages/sdk/src/types.ts
 create mode 100644 packages/sdk/test-data/tool-catchall-error.json
 create mode 100644 packages/sdk/test-data/tool-error-recovery.json
 create mode 100644 packages/sdk/test-data/tool-success.json

diff --git a/.prettierignore b/.prettierignore
index e8f035ad74..9009498d8d 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -21,3 +21,4 @@ junit.xml
 Thumbs.db
 .pytest_cache
 **/SKILL.md
+packages/sdk/test-data/*.json
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index c8ba601cbb..1802e590cd 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -192,3 +192,6 @@ export * from './agents/types.js';
 // Export stdio utils
 export * from './utils/stdio.js';
 export * from './utils/terminal.js';
+
+// Export types from @google/genai
+export type { Content, Part, FunctionCall } from '@google/genai';
diff --git a/packages/sdk/SDK_DESIGN.md b/packages/sdk/SDK_DESIGN.md
new file mode 100644
index 0000000000..8daf6a4bb7
--- /dev/null
+++ b/packages/sdk/SDK_DESIGN.md
@@ -0,0 +1,279 @@
+# `Gemini CLI SDK`
+
+# `Examples`
+
+## `Simple Example`
+
+Equivalent to `gemini -p "what does this project do?"`. Loads all workspace and
+user settings.
+
+```ts
+import { GeminiCliAgent } from '@google/gemini-cli-sdk';
+
+const simpleAgent = new GeminiCliAgent({
+  cwd: '/path/to/some/dir',
+});
+
+for await (const chunk of simpleAgent.sendStream(
+  'what does this project do?',
+)) {
+  console.log(chunk); // equivalent to JSON streaming chunks (probably?) for now
+}
+```
+
+Validation:
+
+- Model receives call containing "what does this project do?" text.
+
+## `System Instructions`
+
+System instructions can be provided by a static string OR dynamically via a
+function:
+
+```ts
+import { GeminiCliAgent } from "@google/gemini-cli-sdk";
+
+const agent = new GeminiCliAgent({
+  instructions: "This is a static string instruction"; // this is valid
+  instructions: (ctx) => `The current time is ${new Date().toISOString()} in session ${ctx.sessionId}.`
+});
+```
+
+Validation:
+
+- Static string instructions show up where GEMINI.md content normally would in
+  model call
+- Dynamic instructions show up and contain dynamic content.
+
+## `Custom Tools`
+
+```ts
+import { GeminiCliAgent, tool, z } from "@google/gemini-cli-sdk";
+
+const addTool = tool({
+  name: 'add',
+  description: 'add two numbers',
+  inputSchema: z.object({
+    a: z.number().describe('first number to add'),
+    b: z.number().describe('second number to add'),
+  }),
+}, (({a, b}) => ({result: a + b}),);
+
+const toolAgent = new GeminiCliAgent({
+  tools: [addTool],
+});
+
+const result = await toolAgent.send("what is 23 + 79?");
+console.log(result.text);
+```
+
+Validation:
+
+- Model receives tool definition in prompt
+- Model receives tool response after returning tool
+
+## `Custom Hooks`
+
+SDK users can provide programmatic custom hooks
+
+```ts
+import { GeminiCliAgent, hook, z } from '@google/gemini-cli-sdk';
+import { reformat } from './reformat.js';
+
+const myHook = hook(
+  {
+    event: 'AfterTool',
+    name: 'reformat',
+    matcher: 'write_file',
+  },
+  (hook, ctx) => {
+    const filePath = hook.toolInput.path;
+
+    // void return is a no-op
+    if (!filePath.endsWith('.ts')) return;
+
+    // ctx.fs gives us a filesystem interface that obeys Gemini CLI permissions/sandbox
+    const reformatted = await reformat(await ctx.fs.read(filePath));
+    await ctx.fs.write(filePath, reformatted);
+
+    // hooks return a payload instructing the agent how to proceed
+    return {
+      hookSpecificOutput: {
+        additionalContext: `Reformatted file ${filePath}, read again before modifying further.`,
+      },
+    };
+  },
+);
+```
+
+SDK Hooks can also run as standalone scripts to implement userland "command"
+style hooks:
+
+```ts
+import { hook } from "@google/gemini-cli-sdk";
+
+// define a hook as above
+const myHook = hook({...}, (hook) => {...});
+// calling runAsCommand parses stdin, calls action, uses appropriate exit code
+// with output, but you get nice strong typings to guide your impl
+myHook.runAsCommand();
+```
+
+Validation (these are probably hardest to validate):
+
+- Test each type of hook and check that model api receives injected content
+- Check global halt scenarios
+- Check specific return types for each type of hook
+
+## `Custom Skills`
+
+Custom skills can be referenced by individual directories or by "skill roots"
+(directories containing many skills).
+
+```ts
+import { GeminiCliAgent, skillDir, skillRoot } from '@google/gemini-cli-sdk';
+
+const agent = new GeminiCliAgent({
+  skills: [skillDir('/path/to/single/skill'), skillRoot('/path/to/skills/dir')],
+});
+```
+
+**NOTE:** I would like to support fully in-memory skills (including reference
+files); however, it seems like that would currently require a pretty significant
+refactor so we'll focus on filesystem skills for now. In an ideal future state,
+we could do something like:
+
+```ts
+import { GeminiCliAgent, skill } from '@google/gemini-cli-sdk';
+
+const mySkill = skill({
+  name: 'my-skill',
+  description: 'description of when my skill should be used',
+  content: 'This is the SKILL.md content',
+  // it can also be a function
+  content: (ctx) => `This is dynamic content.`,
+});
+```
+
+## `Subagents`
+
+```ts
+import { GeminiCliAgent, subagent } from "@google/gemini-cli";
+
+const mySubagent = subagent({
+  name: "my-subagent",
+  description: "when the subagent should be used",
+
+  // simple prompt agent with static string or dynamic string
+  instructions: "the instructions",
+  instructions (prompt, ctx) => `can also be dynamic with context`,
+
+  // OR (in an ideal world)...
+
+  // pass a full standalone agent
+  agent: new GeminiCliAgent(...);
+});
+
+const agent = new GeminiCliAgent({
+  subagents: [mySubagent]
+});
+```
+
+## `Extensions`
+
+Potentially the most important feature of the Gemini CLI SDK is support for
+extensions, which modularly encapsulate all of the primitives listed above:
+
+```ts
+import { GeminiCliAgent, extension } from "@google/gemini-cli-sdk";
+
+const myExtension = extension({
+  name: "my-extension",
+  description: "...",
+  instructions: "THESE ARE CONCATENATED WITH OTHER AGENT
+INSTRUCTIONS",
+  tools: [...],
+  skills: [...],
+  hooks: [...],
+  subagents: [...],
+});
+```
+
+## `ACP Mode`
+
+The SDK will include a wrapper utility to interact with the agent via ACP
+instead of the SDK's natural API.
+
+```ts
+import { GeminiCliAgent } from "@google/gemini-cli-sdk";
+import { GeminiCliAcpServer } from "@google/gemini-cli-sdk/acp";
+
+const server = new GeminiCliAcpServer(new GeminiCliAgent({...}));
+server.start(); // calling start runs a stdio ACP server
+
+const client = server.connect({
+  onMessage: (message) => { /* updates etc received here */ },
+});
+client.send({...clientMessage}); // e.g. a "session/prompt" message
+```
+
+## `Approvals / Policies`
+
+TODO
+
+# `Implementation Guidance`
+
+## `Session Context`
+
+Whenever executing a tool, hook, command, or skill, a SessionContext object
+should be passed as an additional argument after the arguments/payload. The
+interface should look something like:
+
+```ts
+export interface SessionContext {
+  // translations of existing common hook payload info
+  sessionId: string;
+  transcript: Message[];
+  cwd: string;
+  timestamp: string;
+
+  // helpers to access files and run shell commands while adhering to policies/validation
+  fs: AgentFilesystem;
+  shell: AgentShell;
+  // the agent itself is passed as context
+  agent: GeminiCliAgent;
+}
+
+export interface AgentFilesystem {
+  readFile(path: string): Promise<string | null>
+  writeFile(path: string, content: string): Promise<void>
+  // consider others including delete, globbing, etc but read/write are bare minimum}
+
+export interface AgentShell {
+  // simple promise-based execution that blocks until complete
+  exec(cmd: string, options?: AgentShellOptions): Promise<{exitCode: number, output: string, stdout: string, stderr: string}>
+  start(cmd: string, options?: AgentShellOptions): AgentShellProcess;
+}
+
+export interface AgentShellOptions {
+  env?: Record<string,string>;
+  timeoutSeconds?: number;
+}
+
+export interface AgentShellProcess {
+  // figure out how to have a streaming shell process here that supports stdin too
+  // investigate how Gemini CLI already does this
+}
+```
+
+# `Notes`
+
+- To validate the SDK, it would be useful to have a robust way to mock the
+  underlying model API so that the tests could be closer to end-to-end but still
+  deterministic.
+- Need to work in both Gemini-CLI-triggered approvals and optional
+  developer-initiated user prompts / HITL stuff.
+- Need to think about how subagents inherit message context \- e.g. do they have
+  the same session id?
+- Presumably the transcript is kept updated in memory and also persisted to disk
+  by default?
diff --git a/packages/sdk/examples/session-context.ts b/packages/sdk/examples/session-context.ts
new file mode 100644
index 0000000000..704353efe0
--- /dev/null
+++ b/packages/sdk/examples/session-context.ts
@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { GeminiCliAgent, tool, z } from '../src/index.js';
+
+async function main() {
+  const getContextTool = tool(
+    {
+      name: 'get_context',
+      description: 'Get information about the current session context.',
+      inputSchema: z.object({}),
+    },
+    async (_params, context) => {
+      if (!context) {
+        return { error: 'Context not available' };
+      }
+
+      console.log('Session Context Accessed:');
+      console.log(`- Session ID: ${context.sessionId}`);
+      console.log(`- CWD: ${context.cwd}`);
+      console.log(`- Timestamp: ${context.timestamp}`);
+
+      let fileContent = null;
+      try {
+        // Try to read a file (e.g., package.json in the CWD)
+        // Note: This relies on the agent running in a directory with package.json
+        fileContent = await context.fs.readFile('package.json');
+      } catch (e) {
+        console.log(`- Could not read package.json: ${e}`);
+      }
+
+      let shellOutput = null;
+      try {
+        // Try to run a simple shell command
+        const result = await context.shell.exec('echo "Hello from SDK Shell"');
+        shellOutput = result.output.trim();
+      } catch (e) {
+        console.log(`- Could not run shell command: ${e}`);
+      }
+
+      return {
+        sessionId: context.sessionId,
+        cwd: context.cwd,
+        hasFsAccess: !!context.fs,
+        hasShellAccess: !!context.shell,
+        packageJsonExists: !!fileContent,
+        shellEcho: shellOutput,
+      };
+    },
+  );
+
+  const agent = new GeminiCliAgent({
+    instructions:
+      'You are a helpful assistant. Use the get_context tool to tell me about my environment.',
+    tools: [getContextTool],
+    // Set CWD to the package root so package.json exists
+    cwd: process.cwd(),
+  });
+
+  console.log("Sending prompt: 'What is my current session context?'");
+  for await (const chunk of agent.sendStream(
+    'What is my current session context?',
+  )) {
+    if (chunk.type === 'content') {
+      process.stdout.write(chunk.value || '');
+    }
+  }
+}
+
+main().catch(console.error);
diff --git a/packages/sdk/src/agent.ts b/packages/sdk/src/agent.ts
index b2ac5a1872..21defe1ab6 100644
--- a/packages/sdk/src/agent.ts
+++ b/packages/sdk/src/agent.ts
@@ -7,29 +7,38 @@
 import {
   Config,
   type ConfigParameters,
+  AuthType,
   PREVIEW_GEMINI_MODEL_AUTO,
   GeminiEventType,
   type ToolCallRequestInfo,
   type ServerGeminiStreamEvent,
   type GeminiClient,
+  type Content,
   scheduleAgentTools,
   getAuthTypeFromEnv,
-  AuthType,
+  type ToolRegistry,
 } from '@google/gemini-cli-core';
 
-import { type Tool, SdkTool, type z } from './tool.js';
+import { type Tool, SdkTool } from './tool.js';
+import { SdkAgentFilesystem } from './fs.js';
+import { SdkAgentShell } from './shell.js';
+import type { SessionContext } from './types.js';
 
 export interface GeminiCliAgentOptions {
   instructions: string;
-  tools?: Array<Tool<z.ZodType>>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tools?: Array<Tool<any>>;
   model?: string;
   cwd?: string;
   debug?: boolean;
+  recordResponses?: string;
+  fakeResponses?: string;
 }
 
 export class GeminiCliAgent {
-  private readonly config: Config;
-  private readonly tools: Array<Tool<z.ZodType>>;
+  private config: Config;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private tools: Array<Tool<any>>;
 
   constructor(options: GeminiCliAgentOptions) {
     const cwd = options.cwd || process.cwd();
@@ -46,6 +55,8 @@ export class GeminiCliAgent {
       enableHooks: false,
       mcpEnabled: false,
       extensionsEnabled: false,
+      recordResponses: options.recordResponses,
+      fakeResponses: options.fakeResponses,
     };
 
     this.config = new Config(configParams);
@@ -67,18 +78,21 @@ export class GeminiCliAgent {
       const messageBus = this.config.getMessageBus();
 
       for (const toolDef of this.tools) {
-        const sdkTool = new SdkTool(toolDef, messageBus);
+        const sdkTool = new SdkTool(toolDef, messageBus, this);
         registry.registerTool(sdkTool);
       }
     }
 
     const client = this.config.getGeminiClient();
+    const abortSignal = signal ?? new AbortController().signal;
+    const sessionId = this.config.getSessionId();
+
+    const fs = new SdkAgentFilesystem(this.config);
+    const shell = new SdkAgentShell(this.config);
 
     let request: Parameters<GeminiClient['sendMessageStream']>[0] = [
       { text: prompt },
     ];
-    const abortSignal = signal ?? new AbortController().signal;
-    const sessionId = this.config.getSessionId();
 
     while (true) {
       // sendMessageStream returns AsyncGenerator<ServerGeminiStreamEvent, Turn>
@@ -107,12 +121,35 @@ export class GeminiCliAgent {
         break;
       }
 
+      // Prepare SessionContext
+      const transcript: Content[] = client.getHistory();
+      const context: SessionContext = {
+        sessionId,
+        transcript,
+        cwd: this.config.getWorkingDir(),
+        timestamp: new Date().toISOString(),
+        fs,
+        shell,
+        agent: this,
+      };
+
+      // Create a scoped registry for this turn to bind context safely
+      const originalRegistry = this.config.getToolRegistry();
+      const scopedRegistry: ToolRegistry = Object.create(originalRegistry);
+      scopedRegistry.getTool = (name: string) => {
+        const tool = originalRegistry.getTool(name);
+        if (tool instanceof SdkTool) {
+          return tool.bindContext(context);
+        }
+        return tool;
+      };
+
       const completedCalls = await scheduleAgentTools(
         this.config,
         toolCallsToSchedule,
         {
           schedulerId: sessionId,
-          toolRegistry: this.config.getToolRegistry(),
+          toolRegistry: scopedRegistry,
           signal: abortSignal,
         },
       );
diff --git a/packages/sdk/src/fs.ts b/packages/sdk/src/fs.ts
new file mode 100644
index 0000000000..afdb92acff
--- /dev/null
+++ b/packages/sdk/src/fs.ts
@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Config as CoreConfig } from '@google/gemini-cli-core';
+import type { AgentFilesystem } from './types.js';
+import fs from 'node:fs/promises';
+
+export class SdkAgentFilesystem implements AgentFilesystem {
+  constructor(private readonly config: CoreConfig) {}
+
+  async readFile(path: string): Promise<string | null> {
+    const error = this.config.validatePathAccess(path, 'read');
+    if (error) {
+      // For now, if access is denied, we can either throw or return null.
+      // Returning null makes sense for "file not found or readable".
+      return null;
+    }
+    try {
+      return await fs.readFile(path, 'utf-8');
+    } catch {
+      return null;
+    }
+  }
+
+  async writeFile(path: string, content: string): Promise<void> {
+    const error = this.config.validatePathAccess(path, 'write');
+    if (error) {
+      throw new Error(error);
+    }
+    await fs.writeFile(path, content, 'utf-8');
+  }
+}
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index 0ad940d7b2..36a4c7711d 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -6,3 +6,4 @@
 
 export * from './agent.js';
 export * from './tool.js';
+export * from './types.js';
diff --git a/packages/sdk/src/shell.ts b/packages/sdk/src/shell.ts
new file mode 100644
index 0000000000..30b9979594
--- /dev/null
+++ b/packages/sdk/src/shell.ts
@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Config as CoreConfig } from '@google/gemini-cli-core';
+import { ShellExecutionService, ShellTool } from '@google/gemini-cli-core';
+import type {
+  AgentShell,
+  AgentShellResult,
+  AgentShellOptions,
+} from './types.js';
+
+export class SdkAgentShell implements AgentShell {
+  constructor(private readonly config: CoreConfig) {}
+
+  async exec(
+    command: string,
+    options?: AgentShellOptions,
+  ): Promise<AgentShellResult> {
+    const cwd = options?.cwd || this.config.getWorkingDir();
+    const abortController = new AbortController();
+
+    // Use ShellTool to check policy
+    const shellTool = new ShellTool(this.config, this.config.getMessageBus());
+    try {
+      const invocation = shellTool.build({
+        command,
+        dir_path: cwd,
+      });
+
+      const confirmation = await invocation.shouldConfirmExecute(
+        abortController.signal,
+      );
+      if (confirmation) {
+        throw new Error(
+          'Command execution requires confirmation but no interactive session is available.',
+        );
+      }
+    } catch (error) {
+      return {
+        output: '',
+        stdout: '',
+        stderr: '',
+        exitCode: 1,
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+
+    const handle = await ShellExecutionService.execute(
+      command,
+      cwd,
+      () => {}, // No-op output event handler for now
+      abortController.signal,
+      false, // shouldUseNodePty: false for headless execution
+      this.config.getShellExecutionConfig(),
+    );
+
+    const result = await handle.result;
+
+    return {
+      output: result.output,
+      stdout: result.output, // ShellExecutionService combines stdout/stderr usually
+      stderr: '', // ShellExecutionService currently combines, so stderr is empty or mixed
+      exitCode: result.exitCode,
+    };
+  }
+}
diff --git a/packages/sdk/src/tool.integration.test.ts b/packages/sdk/src/tool.integration.test.ts
new file mode 100644
index 0000000000..1ec9d73abd
--- /dev/null
+++ b/packages/sdk/src/tool.integration.test.ts
@@ -0,0 +1,147 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { GeminiCliAgent } from './agent.js';
+import * as path from 'node:path';
+import { z } from 'zod';
+import { tool, ModelVisibleError } from './tool.js';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Set this to true locally when you need to update snapshots
+const RECORD_MODE = process.env['RECORD_NEW_RESPONSES'] === 'true';
+
+const getGoldenPath = (name: string) =>
+  path.resolve(__dirname, '../test-data', `${name}.json`);
+
+describe('GeminiCliAgent Tool Integration', () => {
+  it('handles tool execution success', async () => {
+    const goldenFile = getGoldenPath('tool-success');
+
+    const agent = new GeminiCliAgent({
+      instructions: 'You are a helpful assistant.',
+      // If recording, use real model + record path.
+      // If testing, use auto model + fake path.
+      model: RECORD_MODE ? 'gemini-2.0-flash' : undefined,
+      recordResponses: RECORD_MODE ? goldenFile : undefined,
+      fakeResponses: RECORD_MODE ? undefined : goldenFile,
+      tools: [
+        tool(
+          {
+            name: 'add',
+            description: 'Adds two numbers',
+            inputSchema: z.object({ a: z.number(), b: z.number() }),
+          },
+          async ({ a, b }) => a + b,
+        ),
+      ],
+    });
+
+    const events = [];
+    const stream = agent.sendStream('What is 5 + 3?');
+
+    for await (const event of stream) {
+      events.push(event);
+    }
+
+    const textEvents = events.filter((e) => e.type === 'content');
+    const responseText = textEvents
+      .map((e) => (typeof e.value === 'string' ? e.value : ''))
+      .join('');
+
+    expect(responseText).toContain('8');
+  });
+
+  it('handles ModelVisibleError correctly', async () => {
+    const goldenFile = getGoldenPath('tool-error-recovery');
+
+    const agent = new GeminiCliAgent({
+      instructions: 'You are a helpful assistant.',
+      model: RECORD_MODE ? 'gemini-2.0-flash' : undefined,
+      recordResponses: RECORD_MODE ? goldenFile : undefined,
+      fakeResponses: RECORD_MODE ? undefined : goldenFile,
+      tools: [
+        tool(
+          {
+            name: 'failVisible',
+            description: 'Fails with a visible error if input is "fail"',
+            inputSchema: z.object({ input: z.string() }),
+          },
+          async ({ input }) => {
+            if (input === 'fail') {
+              throw new ModelVisibleError('Tool failed visibly');
+            }
+            return 'Success';
+          },
+        ),
+      ],
+    });
+
+    const events = [];
+    // Force the model to trigger the error first, then hopefully recover or at least acknowledge it.
+    // The prompt is crafted to make the model try 'fail' first.
+    const stream = agent.sendStream(
+      'Call the tool with "fail". If it fails, tell me the error message.',
+    );
+
+    for await (const event of stream) {
+      events.push(event);
+    }
+
+    const textEvents = events.filter((e) => e.type === 'content');
+    const responseText = textEvents
+      .map((e) => (typeof e.value === 'string' ? e.value : ''))
+      .join('');
+
+    // The model should see the error "Tool failed visibly" and report it back.
+    expect(responseText).toContain('Tool failed visibly');
+  });
+
+  it('handles sendErrorsToModel: true correctly', async () => {
+    const goldenFile = getGoldenPath('tool-catchall-error');
+
+    const agent = new GeminiCliAgent({
+      instructions: 'You are a helpful assistant.',
+      model: RECORD_MODE ? 'gemini-2.0-flash' : undefined,
+      recordResponses: RECORD_MODE ? goldenFile : undefined,
+      fakeResponses: RECORD_MODE ? undefined : goldenFile,
+      tools: [
+        tool(
+          {
+            name: 'checkSystemStatus',
+            description: 'Checks the current system status',
+            inputSchema: z.object({}),
+            sendErrorsToModel: true,
+          },
+          async () => {
+            throw new Error('Standard error caught');
+          },
+        ),
+      ],
+    });
+
+    const events = [];
+    const stream = agent.sendStream(
+      'Check the system status and report any errors.',
+    );
+
+    for await (const event of stream) {
+      events.push(event);
+    }
+
+    const textEvents = events.filter((e) => e.type === 'content');
+    const responseText = textEvents
+      .map((e) => (typeof e.value === 'string' ? e.value : ''))
+      .join('');
+
+    // The model should report the caught standard error.
+    expect(responseText.toLowerCase()).toContain('error');
+  });
+});
diff --git a/packages/sdk/src/tool.test.ts b/packages/sdk/src/tool.test.ts
new file mode 100644
index 0000000000..819177c3b9
--- /dev/null
+++ b/packages/sdk/src/tool.test.ts
@@ -0,0 +1,143 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { SdkTool, tool, ModelVisibleError } from './tool.js';
+import type { MessageBus } from '@google/gemini-cli-core';
+
+// Mock MessageBus
+const mockMessageBus = {} as unknown as MessageBus;
+
+describe('tool()', () => {
+  it('creates a tool definition with defaults', () => {
+    const definition = tool(
+      {
+        name: 'testTool',
+        description: 'A test tool',
+        inputSchema: z.object({ foo: z.string() }),
+      },
+      async () => 'result',
+    );
+
+    expect(definition.name).toBe('testTool');
+    expect(definition.description).toBe('A test tool');
+    expect(definition.sendErrorsToModel).toBeUndefined();
+  });
+
+  it('creates a tool definition with explicit configuration', () => {
+    const definition = tool(
+      {
+        name: 'testTool',
+        description: 'A test tool',
+        inputSchema: z.object({ foo: z.string() }),
+        sendErrorsToModel: true,
+      },
+      async () => 'result',
+    );
+
+    expect(definition.sendErrorsToModel).toBe(true);
+  });
+});
+
+describe('SdkTool Execution', () => {
+  it('executes successfully', async () => {
+    const definition = tool(
+      {
+        name: 'successTool',
+        description: 'Always succeeds',
+        inputSchema: z.object({ val: z.string() }),
+      },
+      async ({ val }) => `Success: ${val}`,
+    );
+
+    const sdkTool = new SdkTool(definition, mockMessageBus);
+    const invocation = sdkTool.createInvocationWithContext(
+      { val: 'test' },
+      mockMessageBus,
+      undefined,
+    );
+    const result = await invocation.execute(new AbortController().signal);
+
+    expect(result.llmContent).toBe('Success: test');
+    expect(result.error).toBeUndefined();
+  });
+
+  it('throws standard Error by default', async () => {
+    const definition = tool(
+      {
+        name: 'failTool',
+        description: 'Always fails',
+        inputSchema: z.object({}),
+      },
+      async () => {
+        throw new Error('Standard error');
+      },
+    );
+
+    const sdkTool = new SdkTool(definition, mockMessageBus);
+    const invocation = sdkTool.createInvocationWithContext(
+      {},
+      mockMessageBus,
+      undefined,
+    );
+
+    await expect(
+      invocation.execute(new AbortController().signal),
+    ).rejects.toThrow('Standard error');
+  });
+
+  it('catches ModelVisibleError and returns ToolResult error', async () => {
+    const definition = tool(
+      {
+        name: 'visibleErrorTool',
+        description: 'Fails with visible error',
+        inputSchema: z.object({}),
+      },
+      async () => {
+        throw new ModelVisibleError('Visible error');
+      },
+    );
+
+    const sdkTool = new SdkTool(definition, mockMessageBus);
+    const invocation = sdkTool.createInvocationWithContext(
+      {},
+      mockMessageBus,
+      undefined,
+    );
+    const result = await invocation.execute(new AbortController().signal);
+
+    expect(result.error).toBeDefined();
+    expect(result.error?.message).toBe('Visible error');
+    expect(result.llmContent).toContain('Error: Visible error');
+  });
+
+  it('catches standard Error when sendErrorsToModel is true', async () => {
+    const definition = tool(
+      {
+        name: 'catchAllTool',
+        description: 'Catches all errors',
+        inputSchema: z.object({}),
+        sendErrorsToModel: true,
+      },
+      async () => {
+        throw new Error('Standard error');
+      },
+    );
+
+    const sdkTool = new SdkTool(definition, mockMessageBus);
+    const invocation = sdkTool.createInvocationWithContext(
+      {},
+      mockMessageBus,
+      undefined,
+    );
+    const result = await invocation.execute(new AbortController().signal);
+
+    expect(result.error).toBeDefined();
+    expect(result.error?.message).toBe('Standard error');
+    expect(result.llmContent).toContain('Error: Standard error');
+  });
+});
diff --git a/packages/sdk/src/tool.ts b/packages/sdk/src/tool.ts
index 00cd3802de..ce6bbfc05b 100644
--- a/packages/sdk/src/tool.ts
+++ b/packages/sdk/src/tool.ts
@@ -14,28 +14,42 @@ import {
   Kind,
   type MessageBus,
 } from '@google/gemini-cli-core';
+import type { SessionContext } from './types.js';
 
 export { z };
 
-export interface ToolDefinition<T extends z.ZodType> {
+export class ModelVisibleError extends Error {
+  constructor(message: string | Error) {
+    super(message instanceof Error ? message.message : message);
+    this.name = 'ModelVisibleError';
+  }
+}
+
+export interface ToolDefinition<T extends z.ZodTypeAny> {
   name: string;
   description: string;
   inputSchema: T;
+  sendErrorsToModel?: boolean;
 }
 
-export interface Tool<T extends z.ZodType> extends ToolDefinition<T> {
-  action: (params: z.infer<T>) => Promise<unknown>;
+export interface Tool<T extends z.ZodTypeAny> extends ToolDefinition<T> {
+  action: (params: z.infer<T>, context?: SessionContext) => Promise<unknown>;
 }
 
-class SdkToolInvocation<T extends z.ZodType> extends BaseToolInvocation<
+class SdkToolInvocation<T extends z.ZodTypeAny> extends BaseToolInvocation<
   z.infer<T>,
   ToolResult
 > {
   constructor(
     params: z.infer<T>,
     messageBus: MessageBus,
-    private readonly action: (params: z.infer<T>) => Promise<unknown>,
+    private readonly action: (
+      params: z.infer<T>,
+      context?: SessionContext,
+    ) => Promise<unknown>,
+    private readonly context: SessionContext | undefined,
     toolName: string,
+    private readonly sendErrorsToModel: boolean = false,
   ) {
     super(params, messageBus, toolName);
   }
@@ -49,7 +63,7 @@ class SdkToolInvocation<T extends z.ZodType> extends BaseToolInvocation<
     _updateOutput?: (output: string) => void,
   ): Promise<ToolResult> {
     try {
-      const result = await this.action(this.params);
+      const result = await this.action(this.params, this.context);
       const output =
         typeof result === 'string' ? result : JSON.stringify(result, null, 2);
       return {
@@ -57,26 +71,31 @@ class SdkToolInvocation<T extends z.ZodType> extends BaseToolInvocation<
         returnDisplay: output,
       };
     } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
-      return {
-        llmContent: `Error: ${errorMessage}`,
-        returnDisplay: `Error: ${errorMessage}`,
-        error: {
-          message: errorMessage,
-        },
-      };
+      if (this.sendErrorsToModel || error instanceof ModelVisibleError) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        return {
+          llmContent: `Error: ${errorMessage}`,
+          returnDisplay: `Error: ${errorMessage}`,
+          error: {
+            message: errorMessage,
+          },
+        };
+      }
+      throw error;
     }
   }
 }
 
-export class SdkTool<T extends z.ZodType> extends BaseDeclarativeTool<
+export class SdkTool<T extends z.ZodTypeAny> extends BaseDeclarativeTool<
   z.infer<T>,
   ToolResult
 > {
   constructor(
     private readonly definition: Tool<T>,
     messageBus: MessageBus,
+    _agent?: unknown,
+    private readonly context?: SessionContext,
   ) {
     super(
       definition.name,
@@ -88,6 +107,26 @@ export class SdkTool<T extends z.ZodType> extends BaseDeclarativeTool<
     );
   }
 
+  bindContext(context: SessionContext): SdkTool<T> {
+    return new SdkTool(this.definition, this.messageBus, undefined, context);
+  }
+
+  createInvocationWithContext(
+    params: z.infer<T>,
+    messageBus: MessageBus,
+    context: SessionContext | undefined,
+    toolName?: string,
+  ): ToolInvocation<z.infer<T>, ToolResult> {
+    return new SdkToolInvocation(
+      params,
+      messageBus,
+      this.definition.action,
+      context || this.context,
+      toolName || this.name,
+      this.definition.sendErrorsToModel,
+    );
+  }
+
   protected createInvocation(
     params: z.infer<T>,
     messageBus: MessageBus,
@@ -97,14 +136,16 @@ export class SdkTool<T extends z.ZodType> extends BaseDeclarativeTool<
       params,
       messageBus,
       this.definition.action,
+      this.context,
       toolName || this.name,
+      this.definition.sendErrorsToModel,
     );
   }
 }
 
-export function tool<T extends z.ZodType>(
+export function tool<T extends z.ZodTypeAny>(
   definition: ToolDefinition<T>,
-  action: (params: z.infer<T>) => Promise<unknown>,
+  action: (params: z.infer<T>, context?: SessionContext) => Promise<unknown>,
 ): Tool<T> {
   return {
     ...definition,
diff --git a/packages/sdk/src/types.ts b/packages/sdk/src/types.ts
new file mode 100644
index 0000000000..d7e013d66c
--- /dev/null
+++ b/packages/sdk/src/types.ts
@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Content } from '@google/gemini-cli-core';
+import type { GeminiCliAgent } from './agent.js';
+
+export interface AgentFilesystem {
+  readFile(path: string): Promise<string | null>;
+  writeFile(path: string, content: string): Promise<void>;
+}
+
+export interface AgentShellOptions {
+  env?: Record<string, string>;
+  timeoutSeconds?: number;
+  cwd?: string;
+}
+
+export interface AgentShellResult {
+  exitCode: number | null;
+  output: string;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+}
+
+export interface AgentShell {
+  exec(cmd: string, options?: AgentShellOptions): Promise<AgentShellResult>;
+}
+
+export interface SessionContext {
+  sessionId: string;
+  transcript: Content[];
+  cwd: string;
+  timestamp: string;
+  fs: AgentFilesystem;
+  shell: AgentShell;
+  agent: GeminiCliAgent;
+}
diff --git a/packages/sdk/test-data/tool-catchall-error.json b/packages/sdk/test-data/tool-catchall-error.json
new file mode 100644
index 0000000000..43c3b44d8b
--- /dev/null
+++ b/packages/sdk/test-data/tool-catchall-error.json
@@ -0,0 +1,2 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"checkSystemStatus","args":{}}}],"role":"model"},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":7070,"candidatesTokenCount":3,"totalTokenCount":7073,"promptTokensDetails":[{"modality":"TEXT","tokenCount":7070}],"candidatesTokensDetails":[{"modality":"TEXT","tokenCount":3}]}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"The system status check"}],"role":"model"}}],"usageMetadata":{"promptTokenCount":9850,"totalTokenCount":9850,"promptTokensDetails":[{"modality":"TEXT","tokenCount":9850}]}},{"candidates":[{"content":{"parts":[{"text":" returned an error. It says `Error: Standard error caught`."}],"role":"model"},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":7082,"candidatesTokenCount":17,"totalTokenCount":7099,"promptTokensDetails":[{"modality":"TEXT","tokenCount":7082}],"candidatesTokensDetails":[{"modality":"TEXT","tokenCount":17}]}}]}
diff --git a/packages/sdk/test-data/tool-error-recovery.json b/packages/sdk/test-data/tool-error-recovery.json
new file mode 100644
index 0000000000..4e36d24aa7
--- /dev/null
+++ b/packages/sdk/test-data/tool-error-recovery.json
@@ -0,0 +1,2 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"failVisible","args":{"input":"fail"}}}],"role":"model"},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":7073,"candidatesTokenCount":4,"totalTokenCount":7077,"promptTokensDetails":[{"modality":"TEXT","tokenCount":7073}],"candidatesTokensDetails":[{"modality":"TEXT","tokenCount":4}]}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"The"}],"role":"model"}}],"usageMetadata":{"promptTokenCount":9867,"totalTokenCount":9867,"promptTokensDetails":[{"modality":"TEXT","tokenCount":9867}]}},{"candidates":[{"content":{"parts":[{"text":" tool failed visibly with the error message: \"Error: Tool failed visibly\"."}],"role":"model"},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":7085,"candidatesTokenCount":16,"totalTokenCount":7101,"promptTokensDetails":[{"modality":"TEXT","tokenCount":7085}],"candidatesTokensDetails":[{"modality":"TEXT","tokenCount":16}]}}]}
diff --git a/packages/sdk/test-data/tool-success.json b/packages/sdk/test-data/tool-success.json
new file mode 100644
index 0000000000..1b17993fe4
--- /dev/null
+++ b/packages/sdk/test-data/tool-success.json
@@ -0,0 +1,2 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"add","args":{"a":5,"b":3}}}],"role":"model"},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":7045,"candidatesTokenCount":5,"totalTokenCount":7050,"promptTokensDetails":[{"modality":"TEXT","tokenCount":7045}],"candidatesTokensDetails":[{"modality":"TEXT","tokenCount":5}]}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"8"}],"role":"model"}}],"usageMetadata":{"promptTokenCount":9849,"totalTokenCount":9849,"promptTokensDetails":[{"modality":"TEXT","tokenCount":9849}]}},{"candidates":[{"content":{"parts":[{"text":""}],"role":"model"},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":7053,"candidatesTokenCount":1,"totalTokenCount":7054,"promptTokensDetails":[{"modality":"TEXT","tokenCount":7053}],"candidatesTokensDetails":[{"modality":"TEXT","tokenCount":1}]}}]}

From d5dfae6bbf7e94bd2a1d912489f470d188e0e346 Mon Sep 17 00:00:00 2001
From: Adib234 <30782825+Adib234@users.noreply.github.com>
Date: Fri, 13 Feb 2026 10:03:52 -0500
Subject: [PATCH 43/44] fix(plan): make question type required in AskUser tool
 (#18959)

---
 .../src/ui/components/AskUserDialog.test.tsx  | 31 ++++++++++
 .../ui/components/BubblingRegression.test.tsx |  3 +-
 packages/core/src/confirmation-bus/types.ts   |  6 +-
 packages/core/src/tools/ask-user.test.ts      | 56 ++++++++++++-------
 packages/core/src/tools/ask-user.ts           | 10 ++--
 5 files changed, 77 insertions(+), 29 deletions(-)

diff --git a/packages/cli/src/ui/components/AskUserDialog.test.tsx b/packages/cli/src/ui/components/AskUserDialog.test.tsx
index b93db2a2af..b03f375f71 100644
--- a/packages/cli/src/ui/components/AskUserDialog.test.tsx
+++ b/packages/cli/src/ui/components/AskUserDialog.test.tsx
@@ -37,6 +37,7 @@ describe('AskUserDialog', () => {
     {
       question: 'Which authentication method should we use?',
       header: 'Auth',
+      type: QuestionType.CHOICE,
       options: [
         { label: 'OAuth 2.0', description: 'Industry standard, supports SSO' },
         { label: 'JWT tokens', description: 'Stateless, good for APIs' },
@@ -74,6 +75,7 @@ describe('AskUserDialog', () => {
         {
           question: 'Which features?',
           header: 'Features',
+          type: QuestionType.CHOICE,
           options: [
             { label: 'TypeScript', description: '' },
             { label: 'ESLint', description: '' },
@@ -171,6 +173,7 @@ describe('AskUserDialog', () => {
       {
         question: 'Which authentication method?',
         header: 'Auth',
+        type: QuestionType.CHOICE,
         options: [{ label: 'OAuth 2.0', description: '' }],
         multiSelect: false,
       },
@@ -228,6 +231,7 @@ describe('AskUserDialog', () => {
           {
             question: 'Choose an option',
             header: 'Scroll Test',
+            type: QuestionType.CHOICE,
             options: Array.from({ length: 15 }, (_, i) => ({
               label: `Option ${i + 1}`,
               description: `Description ${i + 1}`,
@@ -296,6 +300,7 @@ describe('AskUserDialog', () => {
       {
         question: 'Which database should we use?',
         header: 'Database',
+        type: QuestionType.CHOICE,
         options: [
           { label: 'PostgreSQL', description: 'Relational database' },
           { label: 'MongoDB', description: 'Document database' },
@@ -305,6 +310,7 @@ describe('AskUserDialog', () => {
       {
         question: 'Which ORM do you prefer?',
         header: 'ORM',
+        type: QuestionType.CHOICE,
         options: [
           { label: 'Prisma', description: 'Type-safe ORM' },
           { label: 'Drizzle', description: 'Lightweight ORM' },
@@ -359,12 +365,14 @@ describe('AskUserDialog', () => {
       {
         question: 'Which testing framework?',
         header: 'Testing',
+        type: QuestionType.CHOICE,
         options: [{ label: 'Vitest', description: 'Fast unit testing' }],
         multiSelect: false,
       },
       {
         question: 'Which CI provider?',
         header: 'CI',
+        type: QuestionType.CHOICE,
         options: [
           { label: 'GitHub Actions', description: 'Built into GitHub' },
         ],
@@ -402,12 +410,14 @@ describe('AskUserDialog', () => {
       {
         question: 'Which package manager?',
         header: 'Package',
+        type: QuestionType.CHOICE,
         options: [{ label: 'pnpm', description: 'Fast, disk efficient' }],
         multiSelect: false,
       },
       {
         question: 'Which bundler?',
         header: 'Bundler',
+        type: QuestionType.CHOICE,
         options: [{ label: 'Vite', description: 'Next generation bundler' }],
         multiSelect: false,
       },
@@ -465,6 +475,7 @@ describe('AskUserDialog', () => {
       {
         question: 'Which framework?',
         header: 'Framework',
+        type: QuestionType.CHOICE,
         options: [
           { label: 'React', description: 'Component library' },
           { label: 'Vue', description: 'Progressive framework' },
@@ -474,6 +485,7 @@ describe('AskUserDialog', () => {
       {
         question: 'Which styling?',
         header: 'Styling',
+        type: QuestionType.CHOICE,
         options: [
           { label: 'Tailwind', description: 'Utility-first CSS' },
           { label: 'CSS Modules', description: 'Scoped styles' },
@@ -500,12 +512,14 @@ describe('AskUserDialog', () => {
       {
         question: 'Create tests?',
         header: 'Tests',
+        type: QuestionType.CHOICE,
         options: [{ label: 'Yes', description: 'Generate test files' }],
         multiSelect: false,
       },
       {
         question: 'Add documentation?',
         header: 'Docs',
+        type: QuestionType.CHOICE,
         options: [{ label: 'Yes', description: 'Generate JSDoc comments' }],
         multiSelect: false,
       },
@@ -545,12 +559,14 @@ describe('AskUserDialog', () => {
       {
         question: 'Which license?',
         header: 'License',
+        type: QuestionType.CHOICE,
         options: [{ label: 'MIT', description: 'Permissive license' }],
         multiSelect: false,
       },
       {
         question: 'Include README?',
         header: 'README',
+        type: QuestionType.CHOICE,
         options: [{ label: 'Yes', description: 'Generate README.md' }],
         multiSelect: false,
       },
@@ -580,12 +596,14 @@ describe('AskUserDialog', () => {
       {
         question: 'Target Node version?',
         header: 'Node',
+        type: QuestionType.CHOICE,
         options: [{ label: 'Node 20', description: 'LTS version' }],
         multiSelect: false,
       },
       {
         question: 'Enable strict mode?',
         header: 'Strict',
+        type: QuestionType.CHOICE,
         options: [{ label: 'Yes', description: 'Strict TypeScript' }],
         multiSelect: false,
       },
@@ -727,6 +745,7 @@ describe('AskUserDialog', () => {
         {
           question: 'Should it be async?',
           header: 'Async',
+          type: QuestionType.CHOICE,
           options: [
             { label: 'Yes', description: 'Use async/await' },
             { label: 'No', description: 'Synchronous hook' },
@@ -773,6 +792,7 @@ describe('AskUserDialog', () => {
         {
           question: 'Which styling approach?',
           header: 'Style',
+          type: QuestionType.CHOICE,
           options: [
             { label: 'CSS Modules', description: 'Scoped CSS' },
             { label: 'Tailwind', description: 'Utility classes' },
@@ -895,6 +915,7 @@ describe('AskUserDialog', () => {
         {
           question: 'Choice Q?',
           header: 'Choice',
+          type: QuestionType.CHOICE,
           options: [{ label: 'Option 1', description: '' }],
           multiSelect: false,
         },
@@ -952,12 +973,14 @@ describe('AskUserDialog', () => {
         {
           question: 'Question 1?',
           header: 'Q1',
+          type: QuestionType.CHOICE,
           options: [{ label: 'A1', description: '' }],
           multiSelect: false,
         },
         {
           question: 'Question 2?',
           header: 'Q2',
+          type: QuestionType.CHOICE,
           options: [{ label: 'A2', description: '' }],
           multiSelect: false,
         },
@@ -1008,6 +1031,7 @@ describe('AskUserDialog', () => {
         {
           question: 'Which option do you prefer?',
           header: 'Test',
+          type: QuestionType.CHOICE,
           options: [{ label: 'Yes', description: '' }],
           multiSelect: false,
         },
@@ -1036,6 +1060,7 @@ describe('AskUserDialog', () => {
         {
           question: 'Is **this** working?',
           header: 'Test',
+          type: QuestionType.CHOICE,
           options: [{ label: 'Yes', description: '' }],
           multiSelect: false,
         },
@@ -1067,6 +1092,7 @@ describe('AskUserDialog', () => {
         {
           question: 'Is **this** working?',
           header: 'Test',
+          type: QuestionType.CHOICE,
           options: [{ label: 'Yes', description: '' }],
           multiSelect: false,
         },
@@ -1096,6 +1122,7 @@ describe('AskUserDialog', () => {
         {
           question: 'Run `npm start`?',
           header: 'Test',
+          type: QuestionType.CHOICE,
           options: [{ label: 'Yes', description: '' }],
           multiSelect: false,
         },
@@ -1126,6 +1153,7 @@ describe('AskUserDialog', () => {
       {
         question: 'Choose an option',
         header: 'Context Test',
+        type: QuestionType.CHOICE,
         options: Array.from({ length: 10 }, (_, i) => ({
           label: `Option ${i + 1}`,
           description: `Description ${i + 1}`,
@@ -1162,6 +1190,7 @@ describe('AskUserDialog', () => {
       {
         question: longQuestion,
         header: 'Alternate Buffer Test',
+        type: QuestionType.CHOICE,
         options: [{ label: 'Option 1', description: 'Desc 1' }],
         multiSelect: false,
       },
@@ -1195,6 +1224,7 @@ describe('AskUserDialog', () => {
         {
           question: 'Select your preferred language:',
           header: 'Language',
+          type: QuestionType.CHOICE,
           options: [
             { label: 'TypeScript', description: '' },
             { label: 'JavaScript', description: '' },
@@ -1228,6 +1258,7 @@ describe('AskUserDialog', () => {
         {
           question: 'Select your preferred language:',
           header: 'Language',
+          type: QuestionType.CHOICE,
           options: [
             { label: 'TypeScript', description: '' },
             { label: 'JavaScript', description: '' },
diff --git a/packages/cli/src/ui/components/BubblingRegression.test.tsx b/packages/cli/src/ui/components/BubblingRegression.test.tsx
index f91f6fe2dc..b91943b019 100644
--- a/packages/cli/src/ui/components/BubblingRegression.test.tsx
+++ b/packages/cli/src/ui/components/BubblingRegression.test.tsx
@@ -9,7 +9,7 @@ import { act } from 'react';
 import { renderWithProviders } from '../../test-utils/render.js';
 import { waitFor } from '../../test-utils/async.js';
 import { AskUserDialog } from './AskUserDialog.js';
-import type { Question } from '@google/gemini-cli-core';
+import { QuestionType, type Question } from '@google/gemini-cli-core';
 
 describe('Key Bubbling Regression', () => {
   afterEach(() => {
@@ -20,6 +20,7 @@ describe('Key Bubbling Regression', () => {
     {
       question: 'Choice Q?',
       header: 'Choice',
+      type: QuestionType.CHOICE,
       options: [
         { label: 'Option 1', description: '' },
         { label: 'Option 2', description: '' },
diff --git a/packages/core/src/confirmation-bus/types.ts b/packages/core/src/confirmation-bus/types.ts
index 8aa21f8ca1..69aa98832e 100644
--- a/packages/core/src/confirmation-bus/types.ts
+++ b/packages/core/src/confirmation-bus/types.ts
@@ -147,9 +147,9 @@ export enum QuestionType {
 export interface Question {
   question: string;
   header: string;
-  /** Question type: 'choice' renders selectable options, 'text' renders free-form input, 'yesno' renders a binary Yes/No choice. Defaults to 'choice'. */
-  type?: QuestionType;
-  /** Selectable choices. REQUIRED when type='choice' or omitted. IGNORED for 'text' and 'yesno'. */
+  /** Question type: 'choice' renders selectable options, 'text' renders free-form input, 'yesno' renders a binary Yes/No choice. */
+  type: QuestionType;
+  /** Selectable choices. REQUIRED when type='choice'. IGNORED for 'text' and 'yesno'. */
   options?: QuestionOption[];
   /** Allow multiple selections. Only applies when type='choice'. */
   multiSelect?: boolean;
diff --git a/packages/core/src/tools/ask-user.test.ts b/packages/core/src/tools/ask-user.test.ts
index 19c98fbc6b..0273e2fc0d 100644
--- a/packages/core/src/tools/ask-user.test.ts
+++ b/packages/core/src/tools/ask-user.test.ts
@@ -131,6 +131,7 @@ describe('AskUserTool', () => {
       const questions = Array(5).fill({
         question: 'Test?',
         header: 'Test',
+        type: QuestionType.CHOICE,
         options: [
           { label: 'A', description: 'A' },
           { label: 'B', description: 'B' },
@@ -156,7 +157,13 @@ describe('AskUserTool', () => {
 
     it('should return error if header exceeds max length', () => {
       const result = tool.validateToolParams({
-        questions: [{ question: 'Test?', header: 'This is way too long' }],
+        questions: [
+          {
+            question: 'Test?',
+            header: 'This is way too long',
+            type: QuestionType.CHOICE,
+          },
+        ],
       });
       expect(result).toContain('must NOT have more than 16 characters');
     });
@@ -167,6 +174,7 @@ describe('AskUserTool', () => {
           {
             question: 'Test?',
             header: 'Test',
+            type: QuestionType.CHOICE,
             options: [{ label: 'A', description: 'A' }],
           },
         ],
@@ -182,6 +190,7 @@ describe('AskUserTool', () => {
           {
             question: 'Test?',
             header: 'Test',
+            type: QuestionType.CHOICE,
             options: [
               { label: 'A', description: 'A' },
               { label: 'B', description: 'B' },
@@ -201,6 +210,7 @@ describe('AskUserTool', () => {
           {
             question: 'Which approach?',
             header: 'Approach',
+            type: QuestionType.CHOICE,
             options: [
               { label: 'A', description: 'Option A' },
               { label: 'B', description: 'Option B' },
@@ -224,18 +234,16 @@ describe('AskUserTool', () => {
       expect(result).toContain("type='choice' requires 'options'");
     });
 
-    it('should return error if type is omitted and options missing (defaults to choice)', () => {
+    it('should return error if type is missing', () => {
       const result = tool.validateToolParams({
         questions: [
           {
             question: 'Pick one?',
             header: 'Choice',
-            // type omitted, defaults to 'choice'
-            // options missing
-          },
+          } as unknown as Question,
         ],
       });
-      expect(result).toContain("type='choice' requires 'options'");
+      expect(result).toContain("must have required property 'type'");
     });
 
     it('should accept text type without options', () => {
@@ -288,6 +296,7 @@ describe('AskUserTool', () => {
           {
             question: 'Pick one?',
             header: 'Choice',
+            type: QuestionType.CHOICE,
             options: [
               { label: '', description: 'Empty label' },
               { label: 'B', description: 'Option B' },
@@ -304,6 +313,7 @@ describe('AskUserTool', () => {
           {
             question: 'Pick one?',
             header: 'Choice',
+            type: QuestionType.CHOICE,
             options: [
               { label: 'A' } as { label: string; description: string },
               { label: 'B', description: 'Option B' },
@@ -318,7 +328,13 @@ describe('AskUserTool', () => {
   describe('validateBuildAndExecute', () => {
     it('should hide validation errors from returnDisplay', async () => {
       const params = {
-        questions: [{ question: 'Test?', header: 'This is way too long' }],
+        questions: [
+          {
+            question: 'Test?',
+            header: 'This is way too long',
+            type: QuestionType.TEXT,
+          },
+        ],
       };
 
       const result = await tool.validateBuildAndExecute(
@@ -337,7 +353,9 @@ describe('AskUserTool', () => {
         .mockReturnValue(null);
 
       const params = {
-        questions: [{ question: 'Valid?', header: 'Valid' }],
+        questions: [
+          { question: 'Valid?', header: 'Valid', type: QuestionType.TEXT },
+        ],
       };
 
       const mockInvocation = {
@@ -366,10 +384,11 @@ describe('AskUserTool', () => {
 
   describe('shouldConfirmExecute', () => {
     it('should return confirmation details with normalized questions', async () => {
-      const questions = [
+      const questions: Question[] = [
         {
           question: 'How should we proceed with this task?',
           header: 'Approach',
+          type: QuestionType.CHOICE,
           options: [
             {
               label: 'Quick fix (Recommended)',
@@ -394,12 +413,7 @@ describe('AskUserTool', () => {
       expect(details).not.toBe(false);
       if (details && details.type === 'ask_user') {
         expect(details.title).toBe('Ask User');
-        expect(details.questions).toEqual(
-          questions.map((q) => ({
-            ...q,
-            type: QuestionType.CHOICE,
-          })),
-        );
+        expect(details.questions).toEqual(questions);
         expect(typeof details.onConfirm).toBe('function');
       } else {
         // Type guard for TypeScript
@@ -407,11 +421,12 @@ describe('AskUserTool', () => {
       }
     });
 
-    it('should normalize question type to CHOICE when omitted', async () => {
-      const questions = [
+    it('should use provided question type', async () => {
+      const questions: Question[] = [
         {
           question: 'Which approach?',
           header: 'Approach',
+          type: QuestionType.CHOICE,
           options: [
             { label: 'Option A', description: 'First option' },
             { label: 'Option B', description: 'Second option' },
@@ -432,10 +447,11 @@ describe('AskUserTool', () => {
 
   describe('execute', () => {
     it('should return user answers after confirmation', async () => {
-      const questions = [
+      const questions: Question[] = [
         {
           question: 'How should we proceed with this task?',
           header: 'Approach',
+          type: QuestionType.CHOICE,
           options: [
             {
               label: 'Quick fix (Recommended)',
@@ -484,10 +500,11 @@ describe('AskUserTool', () => {
     });
 
     it('should display message when user submits without answering', async () => {
-      const questions = [
+      const questions: Question[] = [
         {
           question: 'Which approach?',
           header: 'Approach',
+          type: QuestionType.CHOICE,
           options: [
             { label: 'Option A', description: 'First option' },
             { label: 'Option B', description: 'Second option' },
@@ -528,6 +545,7 @@ describe('AskUserTool', () => {
           {
             question: 'Which sections of the documentation should be updated?',
             header: 'Docs',
+            type: QuestionType.CHOICE,
             options: [
               {
                 label: 'User Guide',
diff --git a/packages/core/src/tools/ask-user.ts b/packages/core/src/tools/ask-user.ts
index 951094d9ad..f941af5d4c 100644
--- a/packages/core/src/tools/ask-user.ts
+++ b/packages/core/src/tools/ask-user.ts
@@ -42,7 +42,7 @@ export class AskUserTool extends BaseDeclarativeTool<
             maxItems: 4,
             items: {
               type: 'object',
-              required: ['question', 'header'],
+              required: ['question', 'header', 'type'],
               properties: {
                 question: {
                   type: 'string',
@@ -111,7 +111,7 @@ export class AskUserTool extends BaseDeclarativeTool<
 
     for (let i = 0; i < params.questions.length; i++) {
       const q = params.questions[i];
-      const questionType = q.type ?? QuestionType.CHOICE;
+      const questionType = q.type;
 
       // Validate that 'choice' type has options
       if (questionType === QuestionType.CHOICE) {
@@ -186,7 +186,7 @@ export class AskUserInvocation extends BaseToolInvocation<
   ): Promise<ToolAskUserConfirmationDetails | false> {
     const normalizedQuestions = this.params.questions.map((q) => ({
       ...q,
-      type: q.type ?? QuestionType.CHOICE,
+      type: q.type,
     }));
 
     return {
@@ -210,9 +210,7 @@ export class AskUserInvocation extends BaseToolInvocation<
   }
 
   async execute(_signal: AbortSignal): Promise<ToolResult> {
-    const questionTypes = this.params.questions.map(
-      (q) => q.type ?? QuestionType.CHOICE,
-    );
+    const questionTypes = this.params.questions.map((q) => q.type);
 
     if (this.confirmationOutcome === ToolConfirmationOutcome.Cancel) {
       return {

From d0c6a56c65556fc4e1d03b680d38cadb28aa01ec Mon Sep 17 00:00:00 2001
From: "N. Taylor Mullen" <ntaylormullen@google.com>
Date: Fri, 13 Feb 2026 07:43:50 -0800
Subject: [PATCH 44/44] fix(core): ensure --yolo does not force headless mode
 (#18976)

---
 packages/core/src/utils/headless.test.ts | 6 +++---
 packages/core/src/utils/headless.ts      | 7 ++-----
 2 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/packages/core/src/utils/headless.test.ts b/packages/core/src/utils/headless.test.ts
index 4708c79969..3350b75a30 100644
--- a/packages/core/src/utils/headless.test.ts
+++ b/packages/core/src/utils/headless.test.ts
@@ -120,18 +120,18 @@ describe('isHeadlessMode', () => {
     }
   });
 
-  it('should return true if -y or --yolo is in process.argv as a fallback', () => {
+  it('should return false if -y or --yolo is in process.argv as a fallback', () => {
     const originalArgv = process.argv;
     process.argv = ['node', 'index.js', '-y'];
     try {
-      expect(isHeadlessMode()).toBe(true);
+      expect(isHeadlessMode()).toBe(false);
     } finally {
       process.argv = originalArgv;
     }
 
     process.argv = ['node', 'index.js', '--yolo'];
     try {
-      expect(isHeadlessMode()).toBe(true);
+      expect(isHeadlessMode()).toBe(false);
     } finally {
       process.argv = originalArgv;
     }
diff --git a/packages/core/src/utils/headless.ts b/packages/core/src/utils/headless.ts
index 5a46b90d6d..eca7ce6814 100644
--- a/packages/core/src/utils/headless.ts
+++ b/packages/core/src/utils/headless.ts
@@ -44,9 +44,6 @@ export function isHeadlessMode(options?: HeadlessModeOptions): boolean {
     return true;
   }
 
-  // Fallback: check process.argv for flags that imply headless or auto-approve mode.
-  return process.argv.some(
-    (arg) =>
-      arg === '-p' || arg === '--prompt' || arg === '-y' || arg === '--yolo',
-  );
+  // Fallback: check process.argv for flags that imply headless mode.
+  return process.argv.some((arg) => arg === '-p' || arg === '--prompt');
 }