remove read tools and related SI for eval

Co-authored-by: Vedant Mahajan <Vedant.04.mahajan@gmail.com>

.gemini/skills/pr-address-comments/scripts/fetch-pr-info.js

@@ -20,8 +20,7 @@ async function run(cmd) {
       stdio: ['pipe', 'pipe', 'ignore'],
     });
     return stdout.trim();
-  } catch (_e) {
-    // eslint-disable-line @typescript-eslint/no-unused-vars
+  } catch {
     return null;
   }
 }

README.md

@@ -382,7 +382,7 @@ See the [Uninstall Guide](docs/cli/uninstall.md) for removal instructions.
 ## 📄 Legal
 
 - **License**: [Apache License 2.0](LICENSE)
-- **Terms of Service**: [Terms & Privacy](./docs/tos-privacy.md)
+- **Terms of Service**: [Terms & Privacy](./docs/resources/tos-privacy.md)
 - **Security**: [Security Policy](SECURITY.md)
 
 ---

docs/cli/plan-mode.md

@@ -27,6 +27,7 @@ implementation. It allows you to:
     - [Example: Allow git commands in Plan Mode](#example-allow-git-commands-in-plan-mode)
     - [Example: Enable research subagents in Plan Mode](#example-enable-research-subagents-in-plan-mode)
   - [Custom Plan Directory and Policies](#custom-plan-directory-and-policies)
+- [Automatic Model Routing](#automatic-model-routing)
 
 ## Enabling Plan Mode
 
@@ -242,6 +243,32 @@ modes = ["plan"]
 argsPattern = "\"file_path\":\"[^\"]+[\\\\/]+\\.gemini[\\\\/]+plans[\\\\/]+[\\w-]+\\.md\""
 ```
 
+## Automatic Model Routing
+
+When using an [**auto model**], Gemini CLI automatically optimizes [**model
+routing**] based on the current phase of your task:
+
+1.  **Planning Phase:** While in Plan Mode, the CLI routes requests to a
+    high-reasoning **Pro** model to ensure robust architectural decisions and
+    high-quality plans.
+2.  **Implementation Phase:** Once a plan is approved and you exit Plan Mode,
+    the CLI detects the existence of the approved plan and automatically
+    switches to a high-speed **Flash** model. This provides a faster, more
+    responsive experience during the implementation of the plan.
+
+This behavior is enabled by default to provide the best balance of quality and
+performance. You can disable this automatic switching in your settings:
+
+```json
+{
+  "general": {
+    "plan": {
+      "modelRouting": false
+    }
+  }
+}
+```
+
 [`list_directory`]: /docs/tools/file-system.md#1-list_directory-readfolder
 [`read_file`]: /docs/tools/file-system.md#2-read_file-readfile
 [`grep_search`]: /docs/tools/file-system.md#5-grep_search-searchtext
@@ -259,3 +286,5 @@ argsPattern = "\"file_path\":\"[^\"]+[\\\\/]+\\.gemini[\\\\/]+plans[\\\\/]+[\\w-
 [YOLO mode]: /docs/reference/configuration.md#command-line-arguments
 [`plan.toml`]:
   https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/policies/plan.toml
+[auto model]: /docs/reference/configuration.md#model-settings
+[model routing]: /docs/cli/telemetry.md#model-routing

docs/cli/settings.md

@@ -29,6 +29,7 @@ they appear in the UI.
 | Enable Auto Update      | `general.enableAutoUpdate`         | Enable automatic updates.                                                                                                                                                      | `true`      |
 | Enable Notifications    | `general.enableNotifications`      | Enable run-event notifications for action-required prompts and session completion. Currently macOS only.                                                                       | `false`     |
 | Plan Directory          | `general.plan.directory`           | The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory.                                                               | `undefined` |
+| Plan Model Routing      | `general.plan.modelRouting`        | Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pro for the planning phase and Flash for the implementation phase.                           | `true`      |
 | Max Chat Model Attempts | `general.maxAttempts`              | Maximum number of attempts for requests to the main chat model. Cannot exceed 10.                                                                                              | `10`        |
 | Debug Keystroke Logging | `general.debugKeystrokeLogging`    | Enable debug logging of keystrokes to the console.                                                                                                                             | `false`     |
 | Enable Session Cleanup  | `general.sessionRetention.enabled` | Enable automatic session cleanup                                                                                                                                               | `false`     |

docs/cli/telemetry.md

@@ -487,6 +487,7 @@ Captures Gemini API requests, responses, and errors.
     - `reasoning` (string, optional)
     - `failed` (boolean)
     - `error_message` (string, optional)
+    - `approval_mode` (string)
 
 #### Chat and streaming
 
@@ -711,12 +712,14 @@ Routing latency/failures and slash-command selections.
   - **Attributes**:
     - `routing.decision_model` (string)
     - `routing.decision_source` (string)
+    - `routing.approval_mode` (string)
 
 - `gemini_cli.model_routing.failure.count` (Counter, Int): Counts model routing
   failures.
   - **Attributes**:
     - `routing.decision_source` (string)
     - `routing.error_message` (string)
+    - `routing.approval_mode` (string)
 
 ##### Agent runs
 

docs/index.md

@@ -21,8 +21,10 @@ Jump in to Gemini CLI.
   personal and enterprise accounts.
 - **[Examples](./get-started/examples.md):** Practical examples of Gemini CLI in
   action.
-- **[Cheatsheet](./cli/cli-reference.md):** A quick reference for common
+- **[CLI cheatsheet](./cli/cli-reference.md):** A quick reference for common
   commands and options.
+- **[Gemini 3 on Gemini CLI](./get-started/gemini-3.md):** Learn about Gemini 3
+  support in Gemini CLI.
 
 ## Use Gemini CLI
 
@@ -50,33 +52,29 @@ User-focused guides and tutorials for daily development workflows.
 
 Technical documentation for each capability of Gemini CLI.
 
-- **[Activate skill (tool)](./tools/activate-skill.md):** Internal mechanism for
-  loading expert procedures.
-- **[Ask user (tool)](./tools/ask-user.md):** Internal dialog system for
-  clarification.
-- **[Checkpointing](./cli/checkpointing.md):** Automatic session snapshots.
-- **[File system (tool)](./tools/file-system.md):** Technical details for local
-  file operations.
-- **[Headless mode](./cli/headless.md):** Programmatic and scripting interface.
-- **[Internal documentation (tool)](./tools/internal-docs.md):** Technical
-  lookup for CLI features.
-- **[Memory (tool)](./tools/memory.md):** Storage details for persistent facts.
-- **[Model routing](./cli/model-routing.md):** Automatic fallback resilience.
-- **[Plan mode 🧪](./cli/plan-mode.md):** Use a safe, read-only mode for
-  planning complex changes.
-- **[Subagents 🧪](./core/subagents.md):** Using specialized agents for specific
+- **[Extensions](./extensions/index.md):** Extend Gemini CLI with new tools and
+  capabilities.
+- **[Agent Skills](./cli/skills.md):** Use specialized agents for specific
   tasks.
-- **[Remote subagents 🧪](./core/remote-agents.md):** Connecting to and using
+- **[Checkpointing](./cli/checkpointing.md):** Automatic session snapshots.
+- **[Headless mode](./cli/headless.md):** Programmatic and scripting interface.
+- **[Hooks](./hooks/index.md):** Customize Gemini CLI behavior with scripts.
+- **[IDE integration](./ide-integration/index.md):** Integrate Gemini CLI with
+  your favorite IDE.
+- **[MCP servers](./tools/mcp-server.md):** Connect to and use remote agents.
+- **[Model routing](./cli/model-routing.md):** Automatic fallback resilience.
+- **[Model selection](./cli/model.md):** Choose the best model for your needs.
+- **[Plan mode 🔬](./cli/plan-mode.md):** Use a safe, read-only mode for
+  planning complex changes.
+- **[Subagents 🔬](./core/subagents.md):** Using specialized agents for specific
+  tasks.
+- **[Remote subagents 🔬](./core/remote-agents.md):** Connecting to and using
   remote agents.
+- **[Rewind](./cli/rewind.md):** Rewind and replay sessions.
 - **[Sandboxing](./cli/sandbox.md):** Isolate tool execution.
-- **[Shell (tool)](./tools/shell.md):** Detailed system execution parameters.
+- **[Settings](./cli/settings.md):** Full configuration reference.
 - **[Telemetry](./cli/telemetry.md):** Usage and performance metric details.
-- **[Todo (tool)](./tools/todos.md):** Progress tracking specification.
 - **[Token caching](./cli/token-caching.md):** Performance optimization.
-- **[Web fetch (tool)](./tools/web-fetch.md):** URL retrieval and extraction
-  details.
-- **[Web search (tool)](./tools/web-search.md):** Google Search integration
-  technicals.
 
 ## Configuration
 
@@ -91,7 +89,6 @@ Settings and customization options for Gemini CLI.
   parameters like temperature and thinking budget.
 - **[Project context (GEMINI.md)](./cli/gemini-md.md):** Technical hierarchy of
   context files.
-- **[Settings](./cli/settings.md):** Full configuration reference.
 - **[System prompt override](./cli/system-prompt.md):** Instruction replacement
   logic.
 - **[Themes](./cli/themes.md):** UI personalization technical guide.
@@ -119,11 +116,13 @@ Deep technical documentation and API specifications.
 Support, release history, and legal information.
 
 - **[FAQ](./resources/faq.md):** Answers to frequently asked questions.
-- **[Changelogs](./changelogs/index.md):** Highlights and notable changes.
 - **[Quota and pricing](./resources/quota-and-pricing.md):** Limits and billing
   details.
 - **[Terms and privacy](./resources/tos-privacy.md):** Official notices and
   terms.
+- **[Troubleshooting](./resources/troubleshooting.md):** Common issues and
+  solutions.
+- **[Uninstall](./resources/uninstall.md):** How to uninstall Gemini CLI.
 
 ## Development
 

docs/reference/configuration.md

@@ -137,6 +137,12 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `undefined`
   - **Requires restart:** Yes
 
+- **`general.plan.modelRouting`** (boolean):
+  - **Description:** Automatically switch between Pro and Flash models based on
+    Plan Mode status. Uses Pro for the planning phase and Flash for the
+    implementation phase.
+  - **Default:** `true`
+
 - **`general.retryFetchErrors`** (boolean):
   - **Description:** Retry on "exception TypeError: fetch failed sending
     request" errors.

docs/sidebar.json

@@ -61,31 +61,53 @@
       {
         "label": "Features",
         "items": [
-          { "label": "Agent Skills", "slug": "docs/cli/skills" },
-          {
-            "label": "Authentication",
-            "slug": "docs/get-started/authentication"
-          },
-          { "label": "Checkpointing", "slug": "docs/cli/checkpointing" },
           {
             "label": "Extensions",
-            "slug": "docs/extensions/index"
+            "collapsed": true,
+            "items": [
+              {
+                "label": "Overview",
+                "slug": "docs/extensions"
+              },
+              {
+                "label": "User guide: Install and manage",
+                "link": "/docs/extensions/#manage-extensions"
+              },
+              {
+                "label": "Developer guide: Build extensions",
+                "slug": "docs/extensions/writing-extensions"
+              },
+              {
+                "label": "Developer guide: Best practices",
+                "slug": "docs/extensions/best-practices"
+              },
+              {
+                "label": "Developer guide: Releasing",
+                "slug": "docs/extensions/releasing"
+              },
+              {
+                "label": "Developer guide: Reference",
+                "slug": "docs/extensions/reference"
+              }
+            ]
           },
+          { "label": "Agent Skills", "slug": "docs/cli/skills" },
+          { "label": "Checkpointing", "slug": "docs/cli/checkpointing" },
           { "label": "Headless mode", "slug": "docs/cli/headless" },
           { "label": "Hooks", "slug": "docs/hooks" },
           { "label": "IDE integration", "slug": "docs/ide-integration" },
           { "label": "MCP servers", "slug": "docs/tools/mcp-server" },
           { "label": "Model routing", "slug": "docs/cli/model-routing" },
           { "label": "Model selection", "slug": "docs/cli/model" },
-          { "label": "Plan mode", "badge": "🧪", "slug": "docs/cli/plan-mode" },
+          { "label": "Plan mode", "badge": "🔬", "slug": "docs/cli/plan-mode" },
           {
             "label": "Subagents",
-            "badge": "🧪",
+            "badge": "🔬",
             "slug": "docs/core/subagents"
           },
           {
             "label": "Remote subagents",
-            "badge": "🧪",
+            "badge": "🔬",
             "slug": "docs/core/remote-agents"
           },
           { "label": "Rewind", "slug": "docs/cli/rewind" },
@@ -124,35 +146,6 @@
           { "label": "Trusted folders", "slug": "docs/cli/trusted-folders" }
         ]
       },
-      {
-        "label": "Extensions",
-        "items": [
-          {
-            "label": "Overview",
-            "slug": "docs/extensions"
-          },
-          {
-            "label": "User guide: Install and manage",
-            "link": "/docs/extensions/#manage-extensions"
-          },
-          {
-            "label": "Developer guide: Build extensions",
-            "slug": "docs/extensions/writing-extensions"
-          },
-          {
-            "label": "Developer guide: Best practices",
-            "slug": "docs/extensions/best-practices"
-          },
-          {
-            "label": "Developer guide: Releasing",
-            "slug": "docs/extensions/releasing"
-          },
-          {
-            "label": "Developer guide: Reference",
-            "slug": "docs/extensions/reference"
-          }
-        ]
-      },
       {
         "label": "Development",
         "items": [

esbuild.config.js

@@ -82,7 +82,7 @@ const commonAliases = {
 const cliConfig = {
   ...baseConfig,
   banner: {
-    js: `import { createRequire } from 'module'; const require = createRequire(import.meta.url); globalThis.__filename = require('url').fileURLToPath(import.meta.url); globalThis.__dirname = require('path').dirname(globalThis.__filename);`,
+    js: `const require = (await import('node:module')).createRequire(import.meta.url); globalThis.__filename = (await import('node:url')).fileURLToPath(import.meta.url); globalThis.__dirname = (await import('node:path')).dirname(globalThis.__filename);`,
   },
   entryPoints: ['packages/cli/index.ts'],
   outfile: 'bundle/gemini.js',
@@ -100,7 +100,7 @@ const cliConfig = {
 const a2aServerConfig = {
   ...baseConfig,
   banner: {
-    js: `const require = (await import('module')).createRequire(import.meta.url); globalThis.__filename = require('url').fileURLToPath(import.meta.url); globalThis.__dirname = require('path').dirname(globalThis.__filename);`,
+    js: `const require = (await import('node:module')).createRequire(import.meta.url); globalThis.__filename = (await import('node:url')).fileURLToPath(import.meta.url); globalThis.__dirname = (await import('node:path')).dirname(globalThis.__filename);`,
   },
   entryPoints: ['packages/a2a-server/src/http/server.ts'],
   outfile: 'packages/a2a-server/dist/a2a-server.mjs',

eslint.config.js

@@ -128,17 +128,7 @@ export default tseslint.config(
       ],
       // Prevent async errors from bypassing catch handlers
       '@typescript-eslint/return-await': ['error', 'in-try-catch'],
-      'import/no-internal-modules': [
-        'error',
-        {
-          allow: [
-            'react-dom/test-utils',
-            'memfs/lib/volume.js',
-            'yargs/**',
-            'msw/node',
-          ],
-        },
-      ],
+      'import/no-internal-modules': 'off',
       'import/no-relative-packages': 'error',
       'no-cond-assign': 'error',
       'no-debugger': 'error',

integration-tests/plan-mode.test.ts

@@ -0,0 +1,143 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { TestRig, checkModelOutputContent } from './test-helper.js';
+
+describe('Plan Mode', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
+  it('should allow read-only tools but deny write tools in plan mode', async () => {
+    await rig.setup(
+      'should allow read-only tools but deny write tools in plan mode',
+      {
+        settings: {
+          experimental: { plan: true },
+          tools: {
+            core: [
+              'run_shell_command',
+              'list_directory',
+              'write_file',
+              'read_file',
+            ],
+          },
+        },
+      },
+    );
+
+    // We use a prompt that asks for both a read-only action and a write action.
+    // "List files" (read-only) followed by "touch denied.txt" (write).
+    const result = await rig.run({
+      approvalMode: 'plan',
+      stdin:
+        'Please list the files in the current directory, and then attempt to create a new file named "denied.txt" using a shell command.',
+    });
+
+    const lsCallFound = await rig.waitForToolCall('list_directory');
+    expect(lsCallFound, 'Expected list_directory to be called').toBe(true);
+
+    const shellCallFound = await rig.waitForToolCall('run_shell_command');
+    expect(shellCallFound, 'Expected run_shell_command to fail').toBe(false);
+
+    const toolLogs = rig.readToolLogs();
+    const lsLog = toolLogs.find((l) => l.toolRequest.name === 'list_directory');
+    expect(
+      toolLogs.find((l) => l.toolRequest.name === 'run_shell_command'),
+    ).toBeUndefined();
+
+    expect(lsLog?.toolRequest.success).toBe(true);
+
+    checkModelOutputContent(result, {
+      expectedContent: ['Plan Mode', 'read-only'],
+      testName: 'Plan Mode restrictions test',
+    });
+  });
+
+  it('should allow write_file only in the plans directory in plan mode', async () => {
+    await rig.setup(
+      'should allow write_file only in the plans directory in plan mode',
+      {
+        settings: {
+          experimental: { plan: true },
+          tools: {
+            core: ['write_file', 'read_file', 'list_directory'],
+            allowed: ['write_file'],
+          },
+          general: { defaultApprovalMode: 'plan' },
+        },
+      },
+    );
+
+    // We ask the agent to create a plan for a feature, which should trigger a write_file in the plans directory.
+    // Verify that write_file outside of plan directory fails
+    await rig.run({
+      approvalMode: 'plan',
+      stdin:
+        'Create a file called plan.md in the plans directory. Then create a file called hello.txt in the current directory',
+    });
+
+    const toolLogs = rig.readToolLogs();
+    const writeLogs = toolLogs.filter(
+      (l) => l.toolRequest.name === 'write_file',
+    );
+
+    const planWrite = writeLogs.find(
+      (l) =>
+        l.toolRequest.args.includes('plans') &&
+        l.toolRequest.args.includes('plan.md'),
+    );
+
+    const blockedWrite = writeLogs.find((l) =>
+      l.toolRequest.args.includes('hello.txt'),
+    );
+
+    // Model is undeterministic, sometimes a blocked write appears in tool logs and sometimes it doesn't
+    if (blockedWrite) {
+      expect(blockedWrite?.toolRequest.success).toBe(false);
+    }
+
+    expect(planWrite?.toolRequest.success).toBe(true);
+  });
+
+  it('should be able to enter plan mode from default mode', async () => {
+    await rig.setup('should be able to enter plan mode from default mode', {
+      settings: {
+        experimental: { plan: true },
+        tools: {
+          core: ['enter_plan_mode'],
+          allowed: ['enter_plan_mode'],
+        },
+      },
+    });
+
+    // Start in default mode and ask to enter plan mode.
+    await rig.run({
+      approvalMode: 'default',
+      stdin:
+        'I want to perform a complex refactoring. Please enter plan mode so we can design it first.',
+    });
+
+    const enterPlanCallFound = await rig.waitForToolCall(
+      'enter_plan_mode',
+      10000,
+    );
+    expect(enterPlanCallFound, 'Expected enter_plan_mode to be called').toBe(
+      true,
+    );
+
+    const toolLogs = rig.readToolLogs();
+    const enterLog = toolLogs.find(
+      (l) => l.toolRequest.name === 'enter_plan_mode',
+    );
+    expect(enterLog?.toolRequest.success).toBe(true);
+  });
+});

package.json

@@ -71,7 +71,9 @@
     },
     "glob": "^12.0.0",
     "node-domexception": "npm:empty@^0.10.1",
-    "prebuild-install": "npm:nop@1.0.0"
+    "prebuild-install": "npm:nop@1.0.0",
+    "cross-spawn": "^7.0.6",
+    "minimatch": "^10.2.2"
   },
   "bin": {
     "gemini": "bundle/gemini.js"
@@ -104,7 +106,7 @@
     "eslint": "^9.24.0",
     "eslint-config-prettier": "^10.1.2",
     "eslint-plugin-headers": "^1.3.3",
-    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
     "glob": "^12.0.0",

packages/cli/src/config/extension-manager-hydration.test.ts

@@ -9,7 +9,11 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { ExtensionManager } from './extension-manager.js';
-import { debugLogger, coreEvents } from '@google/gemini-cli-core';
+import {
+  debugLogger,
+  coreEvents,
+  type CommandHookConfig,
+} from '@google/gemini-cli-core';
 import { createTestMergedSettings } from './settings.js';
 import { createExtension } from '../test-utils/createExtension.js';
 import { EXTENSIONS_DIRECTORY_NAME } from './extensions/variables.js';
@@ -248,9 +252,11 @@ System using model: \${MODEL_NAME}
 
     expect(extension.hooks).toBeDefined();
     expect(extension.hooks?.BeforeTool).toHaveLength(1);
-    expect(extension.hooks?.BeforeTool![0].hooks[0].env?.['HOOK_CMD']).toBe(
-      'hello-world',
-    );
+    expect(
+      (extension.hooks?.BeforeTool![0].hooks[0] as CommandHookConfig).env?.[
+        'HOOK_CMD'
+      ],
+    ).toBe('hello-world');
   });
 
   it('should pick up new settings after restartExtension', async () => {

packages/cli/src/config/extension-manager.ts

@@ -52,6 +52,7 @@ import {
   applyAdminAllowlist,
   getAdminBlockedMcpServersMessage,
   CoreToolCallStatus,
+  HookType,
 } from '@google/gemini-cli-core';
 import { maybeRequestConsentOrFail } from './extensions/consent.js';
 import { resolveEnvVarsInObject } from '../utils/envVarResolver.js';
@@ -735,8 +736,10 @@ Would you like to attempt to install via "git clone" instead?`,
             if (eventHooks) {
               for (const definition of eventHooks) {
                 for (const hook of definition.hooks) {
-                  // Merge existing env with new env vars, giving extension settings precedence.
-                  hook.env = { ...hook.env, ...hookEnv };
+                  if (hook.type === HookType.Command) {
+                    // Merge existing env with new env vars, giving extension settings precedence.
+                    hook.env = { ...hook.env, ...hookEnv };
+                  }
                 }
               }
             }

packages/cli/src/config/settings-validation.test.ts

@@ -324,7 +324,7 @@ describe('settings-validation', () => {
         expect(formatted).toContain('Expected: string, but received: object');
         expect(formatted).toContain('Please fix the configuration.');
         expect(formatted).toContain(
-          'https://github.com/google-gemini/gemini-cli',
+          'https://geminicli.com/docs/reference/configuration/',
         );
       }
     });
@@ -364,9 +364,8 @@ describe('settings-validation', () => {
         const formatted = formatValidationError(result.error, 'test.json');
 
         expect(formatted).toContain(
-          'https://github.com/google-gemini/gemini-cli',
+          'https://geminicli.com/docs/reference/configuration/',
         );
-        expect(formatted).toContain('configuration.md');
       }
     });
 

packages/cli/src/config/settings-validation.ts

@@ -327,9 +327,7 @@ export function formatValidationError(
   }
 
   lines.push('Please fix the configuration.');
-  lines.push(
-    'See: https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/configuration.md',
-  );
+  lines.push('See: https://geminicli.com/docs/reference/configuration/');
 
   return lines.join('\n');
 }

packages/cli/src/config/settingsSchema.ts

@@ -285,6 +285,16 @@ const SETTINGS_SCHEMA = {
               'The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory.',
             showInDialog: true,
           },
+          modelRouting: {
+            type: 'boolean',
+            label: 'Plan Model Routing',
+            category: 'General',
+            requiresRestart: false,
+            default: true,
+            description:
+              'Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pro for the planning phase and Flash for the implementation phase.',
+            showInDialog: true,
+          },
         },
       },
       retryFetchErrors: {

packages/cli/src/test-utils/mockConfig.ts

@@ -47,6 +47,8 @@ export const createMockConfig = (overrides: Partial<Config> = {}): Config =>
     setRemoteAdminSettings: vi.fn(),
     isYoloModeDisabled: vi.fn(() => false),
     isPlanEnabled: vi.fn(() => false),
+    getPlanModeRoutingEnabled: vi.fn().mockResolvedValue(true),
+    getApprovedPlanPath: vi.fn(() => undefined),
     getCoreTools: vi.fn(() => []),
     getAllowedTools: vi.fn(() => []),
     getApprovalMode: vi.fn(() => 'default'),

packages/cli/src/ui/AppContainer.tsx

@@ -150,6 +150,7 @@ import { useSettings } from './contexts/SettingsContext.js';
 import { terminalCapabilityManager } from './utils/terminalCapabilityManager.js';
 import { useInputHistoryStore } from './hooks/useInputHistoryStore.js';
 import { useBanner } from './hooks/useBanner.js';
+import { useTerminalSetupPrompt } from './utils/terminalSetup.js';
 import { useHookDisplayState } from './hooks/useHookDisplayState.js';
 import { useBackgroundShellManager } from './hooks/useBackgroundShellManager.js';
 import {
@@ -606,6 +607,12 @@ export const AppContainer = (props: AppContainerProps) => {
     initializeFromLogger(logger);
   }, [logger, initializeFromLogger]);
 
+  // One-time prompt to suggest running /terminal-setup when it would help.
+  useTerminalSetupPrompt({
+    addConfirmUpdateExtensionRequest,
+    addItem: historyManager.addItem,
+  });
+
   const refreshStatic = useCallback(() => {
     if (!isAlternateBuffer) {
       stdout.write(ansiEscapes.clearTerminal);

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

@@ -250,9 +250,7 @@ export function AuthDialog({
         </Box>
         <Box marginTop={1}>
           <Text color={theme.text.link}>
-            {
-              'https://github.com/google-gemini/gemini-cli/blob/main/docs/tos-privacy.md'
-            }
+            {'https://geminicli.com/docs/resources/tos-privacy/'}
           </Text>
         </Box>
       </Box>

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

@@ -15,7 +15,7 @@ exports[`AuthDialog > Snapshots > renders correctly with auth error 1`] = `
 │                                                                                                  │
 │   Terms of Services and Privacy Notice for Gemini CLI                                            │
 │                                                                                                  │
-│   https://github.com/google-gemini/gemini-cli/blob/main/docs/tos-privacy.md                      │
+│   https://geminicli.com/docs/resources/tos-privacy/                                              │
 │                                                                                                  │
 ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
 "
@@ -34,7 +34,7 @@ exports[`AuthDialog > Snapshots > renders correctly with default props 1`] = `
 │                                                                                                  │
 │   Terms of Services and Privacy Notice for Gemini CLI                                            │
 │                                                                                                  │
-│   https://github.com/google-gemini/gemini-cli/blob/main/docs/tos-privacy.md                      │
+│   https://geminicli.com/docs/resources/tos-privacy/                                              │
 │                                                                                                  │
 ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
 "
@@ -53,7 +53,7 @@ exports[`AuthDialog > Snapshots > renders correctly with enforced auth type 1`]
 │                                                                                                  │
 │   Terms of Services and Privacy Notice for Gemini CLI                                            │
 │                                                                                                  │
-│   https://github.com/google-gemini/gemini-cli/blob/main/docs/tos-privacy.md                      │
+│   https://geminicli.com/docs/resources/tos-privacy/                                              │
 │                                                                                                  │
 ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
 "

packages/cli/src/ui/components/__snapshots__/SettingsDialog.test.tsx.snap

@@ -25,15 +25,15 @@ exports[`SettingsDialog > Initial Rendering > should render settings list with v
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
 │                                                                                                  │
+│    Plan Model Routing                                                                      true  │
+│    Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pr…         │
+│                                                                                                  │
 │    Max Chat Model Attempts                                                                   10  │
 │    Maximum number of attempts for requests to the main chat model. Cannot exceed 10.             │
 │                                                                                                  │
 │    Debug Keystroke Logging                                                                false  │
 │    Enable debug logging of keystrokes to the console.                                            │
 │                                                                                                  │
-│    Enable Session Cleanup                                                                 false  │
-│    Enable automatic session cleanup                                                              │
-│                                                                                                  │
 │  ▼                                                                                               │
 │                                                                                                  │
 │    Apply To                                                                                      │
@@ -72,15 +72,15 @@ exports[`SettingsDialog > Snapshot Tests > should render 'accessibility settings
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
 │                                                                                                  │
+│    Plan Model Routing                                                                      true  │
+│    Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pr…         │
+│                                                                                                  │
 │    Max Chat Model Attempts                                                                   10  │
 │    Maximum number of attempts for requests to the main chat model. Cannot exceed 10.             │
 │                                                                                                  │
 │    Debug Keystroke Logging                                                                false  │
 │    Enable debug logging of keystrokes to the console.                                            │
 │                                                                                                  │
-│    Enable Session Cleanup                                                                 false  │
-│    Enable automatic session cleanup                                                              │
-│                                                                                                  │
 │  ▼                                                                                               │
 │                                                                                                  │
 │    Apply To                                                                                      │
@@ -119,15 +119,15 @@ exports[`SettingsDialog > Snapshot Tests > should render 'all boolean settings d
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
 │                                                                                                  │
+│    Plan Model Routing                                                                      true  │
+│    Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pr…         │
+│                                                                                                  │
 │    Max Chat Model Attempts                                                                   10  │
 │    Maximum number of attempts for requests to the main chat model. Cannot exceed 10.             │
 │                                                                                                  │
 │    Debug Keystroke Logging                                                               false*  │
 │    Enable debug logging of keystrokes to the console.                                            │
 │                                                                                                  │
-│    Enable Session Cleanup                                                                 false  │
-│    Enable automatic session cleanup                                                              │
-│                                                                                                  │
 │  ▼                                                                                               │
 │                                                                                                  │
 │    Apply To                                                                                      │
@@ -166,15 +166,15 @@ exports[`SettingsDialog > Snapshot Tests > should render 'default state' correct
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
 │                                                                                                  │
+│    Plan Model Routing                                                                      true  │
+│    Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pr…         │
+│                                                                                                  │
 │    Max Chat Model Attempts                                                                   10  │
 │    Maximum number of attempts for requests to the main chat model. Cannot exceed 10.             │
 │                                                                                                  │
 │    Debug Keystroke Logging                                                                false  │
 │    Enable debug logging of keystrokes to the console.                                            │
 │                                                                                                  │
-│    Enable Session Cleanup                                                                 false  │
-│    Enable automatic session cleanup                                                              │
-│                                                                                                  │
 │  ▼                                                                                               │
 │                                                                                                  │
 │    Apply To                                                                                      │
@@ -213,15 +213,15 @@ exports[`SettingsDialog > Snapshot Tests > should render 'file filtering setting
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
 │                                                                                                  │
+│    Plan Model Routing                                                                      true  │
+│    Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pr…         │
+│                                                                                                  │
 │    Max Chat Model Attempts                                                                   10  │
 │    Maximum number of attempts for requests to the main chat model. Cannot exceed 10.             │
 │                                                                                                  │
 │    Debug Keystroke Logging                                                                false  │
 │    Enable debug logging of keystrokes to the console.                                            │
 │                                                                                                  │
-│    Enable Session Cleanup                                                                 false  │
-│    Enable automatic session cleanup                                                              │
-│                                                                                                  │
 │  ▼                                                                                               │
 │                                                                                                  │
 │    Apply To                                                                                      │
@@ -260,15 +260,15 @@ exports[`SettingsDialog > Snapshot Tests > should render 'focused on scope selec
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
 │                                                                                                  │
+│    Plan Model Routing                                                                      true  │
+│    Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pr…         │
+│                                                                                                  │
 │    Max Chat Model Attempts                                                                   10  │
 │    Maximum number of attempts for requests to the main chat model. Cannot exceed 10.             │
 │                                                                                                  │
 │    Debug Keystroke Logging                                                                false  │
 │    Enable debug logging of keystrokes to the console.                                            │
 │                                                                                                  │
-│    Enable Session Cleanup                                                                 false  │
-│    Enable automatic session cleanup                                                              │
-│                                                                                                  │
 │  ▼                                                                                               │
 │                                                                                                  │
 │  > Apply To                                                                                      │
@@ -307,15 +307,15 @@ exports[`SettingsDialog > Snapshot Tests > should render 'mixed boolean and numb
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
 │                                                                                                  │
+│    Plan Model Routing                                                                      true  │
+│    Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pr…         │
+│                                                                                                  │
 │    Max Chat Model Attempts                                                                   10  │
 │    Maximum number of attempts for requests to the main chat model. Cannot exceed 10.             │
 │                                                                                                  │
 │    Debug Keystroke Logging                                                                false  │
 │    Enable debug logging of keystrokes to the console.                                            │
 │                                                                                                  │
-│    Enable Session Cleanup                                                                 false  │
-│    Enable automatic session cleanup                                                              │
-│                                                                                                  │
 │  ▼                                                                                               │
 │                                                                                                  │
 │    Apply To                                                                                      │
@@ -354,15 +354,15 @@ exports[`SettingsDialog > Snapshot Tests > should render 'tools and security set
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
 │                                                                                                  │
+│    Plan Model Routing                                                                      true  │
+│    Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pr…         │
+│                                                                                                  │
 │    Max Chat Model Attempts                                                                   10  │
 │    Maximum number of attempts for requests to the main chat model. Cannot exceed 10.             │
 │                                                                                                  │
 │    Debug Keystroke Logging                                                                false  │
 │    Enable debug logging of keystrokes to the console.                                            │
 │                                                                                                  │
-│    Enable Session Cleanup                                                                 false  │
-│    Enable automatic session cleanup                                                              │
-│                                                                                                  │
 │  ▼                                                                                               │
 │                                                                                                  │
 │    Apply To                                                                                      │
@@ -401,15 +401,15 @@ exports[`SettingsDialog > Snapshot Tests > should render 'various boolean settin
 │    Plan Directory                                                                     undefined  │
 │    The directory where planning artifacts are stored. If not specified, defaults t…              │
 │                                                                                                  │
+│    Plan Model Routing                                                                      true  │
+│    Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pr…         │
+│                                                                                                  │
 │    Max Chat Model Attempts                                                                   10  │
 │    Maximum number of attempts for requests to the main chat model. Cannot exceed 10.             │
 │                                                                                                  │
 │    Debug Keystroke Logging                                                                true*  │
 │    Enable debug logging of keystrokes to the console.                                            │
 │                                                                                                  │
-│    Enable Session Cleanup                                                                 false  │
-│    Enable automatic session cleanup                                                              │
-│                                                                                                  │
 │  ▼                                                                                               │
 │                                                                                                  │
 │    Apply To                                                                                      │

packages/cli/src/ui/utils/terminalSetup.test.ts

@@ -5,7 +5,12 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { terminalSetup, VSCODE_SHIFT_ENTER_SEQUENCE } from './terminalSetup.js';
+import {
+  terminalSetup,
+  VSCODE_SHIFT_ENTER_SEQUENCE,
+  shouldPromptForTerminalSetup,
+} from './terminalSetup.js';
+import { terminalCapabilityManager } from './terminalCapabilityManager.js';
 
 // Mock dependencies
 const mocks = vi.hoisted(() => ({
@@ -195,4 +200,51 @@ describe('terminalSetup', () => {
       expect(mocks.writeFile).toHaveBeenCalled();
     });
   });
+
+  describe('shouldPromptForTerminalSetup', () => {
+    it('should return false when kitty protocol is already enabled', async () => {
+      vi.mocked(
+        terminalCapabilityManager.isKittyProtocolEnabled,
+      ).mockReturnValue(true);
+
+      const result = await shouldPromptForTerminalSetup();
+      expect(result).toBe(false);
+    });
+
+    it('should return false when both Shift+Enter and Ctrl+Enter bindings already exist', async () => {
+      vi.mocked(
+        terminalCapabilityManager.isKittyProtocolEnabled,
+      ).mockReturnValue(false);
+      process.env['TERM_PROGRAM'] = 'vscode';
+
+      const existingBindings = [
+        {
+          key: 'shift+enter',
+          command: 'workbench.action.terminal.sendSequence',
+          args: { text: VSCODE_SHIFT_ENTER_SEQUENCE },
+        },
+        {
+          key: 'ctrl+enter',
+          command: 'workbench.action.terminal.sendSequence',
+          args: { text: VSCODE_SHIFT_ENTER_SEQUENCE },
+        },
+      ];
+      mocks.readFile.mockResolvedValue(JSON.stringify(existingBindings));
+
+      const result = await shouldPromptForTerminalSetup();
+      expect(result).toBe(false);
+    });
+
+    it('should return true when keybindings file does not exist', async () => {
+      vi.mocked(
+        terminalCapabilityManager.isKittyProtocolEnabled,
+      ).mockReturnValue(false);
+      process.env['TERM_PROGRAM'] = 'vscode';
+
+      mocks.readFile.mockRejectedValue(new Error('ENOENT'));
+
+      const result = await shouldPromptForTerminalSetup();
+      expect(result).toBe(true);
+    });
+  });
 });

packages/cli/src/ui/utils/terminalSetup.ts

@@ -32,6 +32,13 @@ import { promisify } from 'node:util';
 import { terminalCapabilityManager } from './terminalCapabilityManager.js';
 
 import { debugLogger, homedir } from '@google/gemini-cli-core';
+import { useEffect } from 'react';
+import { persistentState } from '../../utils/persistentState.js';
+import { requestConsentInteractive } from '../../config/extensions/consent.js';
+import type { ConfirmationRequest } from '../types.js';
+import type { UseHistoryManagerReturn } from '../hooks/useHistoryManager.js';
+
+type AddItemFn = UseHistoryManagerReturn['addItem'];
 
 export const VSCODE_SHIFT_ENTER_SEQUENCE = '\\\r\n';
 
@@ -54,6 +61,56 @@ export interface TerminalSetupResult {
 
 type SupportedTerminal = 'vscode' | 'cursor' | 'windsurf' | 'antigravity';
 
+/**
+ * Terminal metadata used for configuration.
+ */
+interface TerminalData {
+  terminalName: string;
+  appName: string;
+}
+const TERMINAL_DATA: Record<SupportedTerminal, TerminalData> = {
+  vscode: { terminalName: 'VS Code', appName: 'Code' },
+  cursor: { terminalName: 'Cursor', appName: 'Cursor' },
+  windsurf: { terminalName: 'Windsurf', appName: 'Windsurf' },
+  antigravity: { terminalName: 'Antigravity', appName: 'Antigravity' },
+};
+
+/**
+ * Maps a supported terminal ID to its display name and config folder name.
+ */
+function getSupportedTerminalData(
+  terminal: SupportedTerminal,
+): TerminalData | null {
+  return TERMINAL_DATA[terminal] || null;
+}
+
+type Keybinding = {
+  key?: string;
+  command?: string;
+  args?: { text?: string };
+};
+
+function isKeybinding(kb: unknown): kb is Keybinding {
+  return typeof kb === 'object' && kb !== null;
+}
+
+/**
+ * Checks if a keybindings array contains our specific binding for a given key.
+ */
+function hasOurBinding(
+  keybindings: unknown[],
+  key: 'shift+enter' | 'ctrl+enter',
+): boolean {
+  return keybindings.some((kb) => {
+    if (!isKeybinding(kb)) return false;
+    return (
+      kb.key === key &&
+      kb.command === 'workbench.action.terminal.sendSequence' &&
+      kb.args?.text === VSCODE_SHIFT_ENTER_SEQUENCE
+    );
+  });
+}
+
 export function getTerminalProgram(): SupportedTerminal | null {
   const termProgram = process.env['TERM_PROGRAM'];
 
@@ -246,23 +303,17 @@ async function configureVSCodeStyle(
 
     const results = targetBindings.map((target) => {
       const hasOurBinding = keybindings.some((kb) => {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-        const binding = kb as {
-          command?: string;
-          args?: { text?: string };
-          key?: string;
-        };
+        if (!isKeybinding(kb)) return false;
         return (
-          binding.key === target.key &&
-          binding.command === target.command &&
-          binding.args?.text === target.args.text
+          kb.key === target.key &&
+          kb.command === target.command &&
+          kb.args?.text === target.args.text
         );
       });
 
       const existingBinding = keybindings.find((kb) => {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-        const binding = kb as { key?: string };
-        return binding.key === target.key;
+        if (!isKeybinding(kb)) return false;
+        return kb.key === target.key;
       });
 
       return {
@@ -316,22 +367,57 @@ async function configureVSCodeStyle(
   }
 }
 
-// Terminal-specific configuration functions
+/**
+ * Determines whether it is useful to prompt the user to run /terminal-setup
+ * in the current environment.
+ *
+ * Returns true when:
+ * - Kitty/modifyOtherKeys keyboard protocol is not already enabled, and
+ * - We're running inside a supported terminal (VS Code, Cursor, Windsurf, Antigravity), and
+ * - The keybindings file either does not exist or does not already contain both
+ *   of our Shift+Enter and Ctrl+Enter bindings.
+ */
+export async function shouldPromptForTerminalSetup(): Promise<boolean> {
+  if (terminalCapabilityManager.isKittyProtocolEnabled()) {
+    return false;
+  }
 
-async function configureVSCode(): Promise<TerminalSetupResult> {
-  return configureVSCodeStyle('VS Code', 'Code');
-}
+  const terminal = await detectTerminal();
+  if (!terminal) {
+    return false;
+  }
 
-async function configureCursor(): Promise<TerminalSetupResult> {
-  return configureVSCodeStyle('Cursor', 'Cursor');
-}
+  const terminalData = getSupportedTerminalData(terminal);
+  if (!terminalData) {
+    return false;
+  }
 
-async function configureWindsurf(): Promise<TerminalSetupResult> {
-  return configureVSCodeStyle('Windsurf', 'Windsurf');
-}
+  const configDir = getVSCodeStyleConfigDir(terminalData.appName);
+  if (!configDir) {
+    return false;
+  }
 
-async function configureAntigravity(): Promise<TerminalSetupResult> {
-  return configureVSCodeStyle('Antigravity', 'Antigravity');
+  const keybindingsFile = path.join(configDir, 'keybindings.json');
+
+  try {
+    const content = await fs.readFile(keybindingsFile, 'utf8');
+    const cleanContent = stripJsonComments(content);
+    const parsedContent: unknown = JSON.parse(cleanContent) as unknown;
+
+    if (!Array.isArray(parsedContent)) {
+      return true;
+    }
+
+    const hasOurShiftEnter = hasOurBinding(parsedContent, 'shift+enter');
+    const hasOurCtrlEnter = hasOurBinding(parsedContent, 'ctrl+enter');
+
+    return !(hasOurShiftEnter && hasOurCtrlEnter);
+  } catch (error) {
+    debugLogger.debug(
+      `Failed to read or parse keybindings, assuming prompt is needed: ${error}`,
+    );
+    return true;
+  }
 }
 
 /**
@@ -373,19 +459,79 @@ export async function terminalSetup(): Promise<TerminalSetupResult> {
     };
   }
 
-  switch (terminal) {
-    case 'vscode':
-      return configureVSCode();
-    case 'cursor':
-      return configureCursor();
-    case 'windsurf':
-      return configureWindsurf();
-    case 'antigravity':
-      return configureAntigravity();
-    default:
-      return {
-        success: false,
-        message: `Terminal "${terminal}" is not supported yet.`,
-      };
+  const terminalData = getSupportedTerminalData(terminal);
+  if (!terminalData) {
+    return {
+      success: false,
+      message: `Terminal "${terminal}" is not supported yet.`,
+    };
   }
+
+  return configureVSCodeStyle(terminalData.terminalName, terminalData.appName);
+}
+
+export const TERMINAL_SETUP_CONSENT_MESSAGE =
+  'Gemini CLI works best with Shift+Enter/Ctrl+Enter for multiline input. ' +
+  'Would you like to automatically configure your terminal keybindings?';
+
+export function formatTerminalSetupResultMessage(
+  result: TerminalSetupResult,
+): string {
+  let content = result.message;
+  if (result.requiresRestart) {
+    content +=
+      '\n\nPlease restart your terminal for the changes to take effect.';
+  }
+  return content;
+}
+
+interface UseTerminalSetupPromptParams {
+  addConfirmUpdateExtensionRequest: (request: ConfirmationRequest) => void;
+  addItem: AddItemFn;
+}
+
+/**
+ * Hook that shows a one-time prompt to run /terminal-setup when it would help.
+ */
+export function useTerminalSetupPrompt({
+  addConfirmUpdateExtensionRequest,
+  addItem,
+}: UseTerminalSetupPromptParams): void {
+  useEffect(() => {
+    const hasBeenPrompted = persistentState.get('terminalSetupPromptShown');
+    if (hasBeenPrompted) {
+      return;
+    }
+
+    let cancelled = false;
+
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    (async () => {
+      const shouldPrompt = await shouldPromptForTerminalSetup();
+      if (!shouldPrompt || cancelled) return;
+
+      persistentState.set('terminalSetupPromptShown', true);
+
+      const confirmed = await requestConsentInteractive(
+        TERMINAL_SETUP_CONSENT_MESSAGE,
+        addConfirmUpdateExtensionRequest,
+      );
+
+      if (!confirmed || cancelled) return;
+
+      const result = await terminalSetup();
+      if (cancelled) return;
+      addItem(
+        {
+          type: result.success ? 'info' : 'error',
+          text: formatTerminalSetupResultMessage(result),
+        },
+        Date.now(),
+      );
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [addConfirmUpdateExtensionRequest, addItem]);
 }

packages/cli/src/ui/utils/textUtils.test.ts

@@ -48,12 +48,12 @@ describe('textUtils', () => {
     it('should handle unicode characters that crash string-width', () => {
       // U+0602 caused string-width to crash (see #16418)
       const char = '؂';
-      expect(getCachedStringWidth(char)).toBe(1);
+      expect(getCachedStringWidth(char)).toBe(0);
     });
 
     it('should handle unicode characters that crash string-width with ANSI codes', () => {
       const charWithAnsi = '\u001b[31m' + '؂' + '\u001b[0m';
-      expect(getCachedStringWidth(charWithAnsi)).toBe(1);
+      expect(getCachedStringWidth(charWithAnsi)).toBe(0);
     });
   });
 

packages/cli/src/utils/persistentState.ts

@@ -12,6 +12,7 @@ const STATE_FILENAME = 'state.json';
 
 interface PersistentStateData {
   defaultBannerShownCount?: Record<string, number>;
+  terminalSetupPromptShown?: boolean;
   tipsShown?: number;
   hasSeenScreenReaderNudge?: boolean;
   focusUiEnabled?: boolean;

packages/cli/src/zed-integration/zedIntegration.test.ts

@@ -177,6 +177,14 @@ describe('GeminiAgent', () => {
 
     expect(response.protocolVersion).toBe(acp.PROTOCOL_VERSION);
     expect(response.authMethods).toHaveLength(3);
+    const geminiAuth = response.authMethods?.find(
+      (m) => m.id === AuthType.USE_GEMINI,
+    );
+    expect(geminiAuth?._meta).toEqual({
+      'api-key': {
+        provider: 'google',
+      },
+    });
     expect(response.agentCapabilities?.loadSession).toBe(true);
   });
 
@@ -187,6 +195,7 @@ describe('GeminiAgent', () => {
 
     expect(mockConfig.refreshAuth).toHaveBeenCalledWith(
       AuthType.LOGIN_WITH_GOOGLE,
+      undefined,
     );
     expect(mockSettings.setValue).toHaveBeenCalledWith(
       SettingScope.User,
@@ -195,6 +204,25 @@ describe('GeminiAgent', () => {
     );
   });
 
+  it('should authenticate correctly with api-key in _meta', async () => {
+    await agent.authenticate({
+      methodId: AuthType.USE_GEMINI,
+      _meta: {
+        'api-key': 'test-api-key',
+      },
+    } as unknown as acp.AuthenticateRequest);
+
+    expect(mockConfig.refreshAuth).toHaveBeenCalledWith(
+      AuthType.USE_GEMINI,
+      'test-api-key',
+    );
+    expect(mockSettings.setValue).toHaveBeenCalledWith(
+      SettingScope.User,
+      'security.auth.selectedType',
+      AuthType.USE_GEMINI,
+    );
+  });
+
   it('should create a new session', async () => {
     mockConfig.getContentGeneratorConfig = vi.fn().mockReturnValue({
       apiKey: 'test-key',

packages/cli/src/zed-integration/zedIntegration.ts

@@ -37,12 +37,17 @@ import {
   partListUnionToString,
   LlmRole,
   ApprovalMode,
+  getVersion,
   convertSessionToClientHistory,
 } from '@google/gemini-cli-core';
 import * as acp from '@agentclientprotocol/sdk';
 import { AcpFileSystemService } from './fileSystemService.js';
 import { getAcpErrorMessage } from './acpErrors.js';
 import { Readable, Writable } from 'node:stream';
+
+function hasMeta(obj: unknown): obj is { _meta?: Record<string, unknown> } {
+  return typeof obj === 'object' && obj !== null && '_meta' in obj;
+}
 import type { Content, Part, FunctionCall } from '@google/genai';
 import type { LoadedSettings } from '../config/settings.js';
 import { SettingScope, loadSettings } from '../config/settings.js';
@@ -81,6 +86,7 @@ export async function runZedIntegration(
 export class GeminiAgent {
   private sessions: Map<string, Session> = new Map();
   private clientCapabilities: acp.ClientCapabilities | undefined;
+  private apiKey: string | undefined;
 
   constructor(
     private config: Config,
@@ -97,25 +103,35 @@ export class GeminiAgent {
       {
         id: AuthType.LOGIN_WITH_GOOGLE,
         name: 'Log in with Google',
-        description: null,
+        description: 'Log in with your Google account',
       },
       {
         id: AuthType.USE_GEMINI,
-        name: 'Use Gemini API key',
-        description:
-          'Requires setting the `GEMINI_API_KEY` environment variable',
+        name: 'Gemini API key',
+        description: 'Use an API key with Gemini Developer API',
+        _meta: {
+          'api-key': {
+            provider: 'google',
+          },
+        },
       },
       {
         id: AuthType.USE_VERTEX_AI,
         name: 'Vertex AI',
-        description: null,
+        description: 'Use an API key with Vertex AI GenAI API',
       },
     ];
 
     await this.config.initialize();
+    const version = await getVersion();
     return {
       protocolVersion: acp.PROTOCOL_VERSION,
       authMethods,
+      agentInfo: {
+        name: 'gemini-cli',
+        title: 'Gemini CLI',
+        version,
+      },
       agentCapabilities: {
         loadSession: true,
         promptCapabilities: {
@@ -131,7 +147,8 @@ export class GeminiAgent {
     };
   }
 
-  async authenticate({ methodId }: acp.AuthenticateRequest): Promise<void> {
+  async authenticate(req: acp.AuthenticateRequest): Promise<void> {
+    const { methodId } = req;
     const method = z.nativeEnum(AuthType).parse(methodId);
     const selectedAuthType = this.settings.merged.security.auth.selectedType;
 
@@ -139,17 +156,21 @@ export class GeminiAgent {
     if (selectedAuthType && selectedAuthType !== method) {
       await clearCachedCredentialFile();
     }
+    // Check for api-key in _meta
+    const meta = hasMeta(req) ? req._meta : undefined;
+    const apiKey =
+      typeof meta?.['api-key'] === 'string' ? meta['api-key'] : undefined;
 
     // Refresh auth with the requested method
     // This will reuse existing credentials if they're valid,
     // or perform new authentication if needed
     try {
-      await this.config.refreshAuth(method);
+      if (apiKey) {
+        this.apiKey = apiKey;
+      }
+      await this.config.refreshAuth(method, apiKey ?? this.apiKey);
     } catch (e) {
-      throw new acp.RequestError(
-        getErrorStatus(e) || 401,
-        getAcpErrorMessage(e),
-      );
+      throw new acp.RequestError(-32000, getAcpErrorMessage(e));
     }
     this.settings.setValue(
       SettingScope.User,
@@ -177,7 +198,7 @@ export class GeminiAgent {
     let isAuthenticated = false;
     let authErrorMessage = '';
     try {
-      await config.refreshAuth(authType);
+      await config.refreshAuth(authType, this.apiKey);
       isAuthenticated = true;
 
       // Extra validation for Gemini API key
@@ -199,7 +220,7 @@ export class GeminiAgent {
 
     if (!isAuthenticated) {
       throw new acp.RequestError(
-        401,
+        -32000,
         authErrorMessage || 'Authentication required.',
       );
     }
@@ -302,7 +323,7 @@ export class GeminiAgent {
     // This satisfies the security requirement to verify the user before executing
     // potentially unsafe server definitions.
     try {
-      await config.refreshAuth(selectedAuthType);
+      await config.refreshAuth(selectedAuthType, this.apiKey);
     } catch (e) {
       debugLogger.error(`Authentication failed: ${e}`);
       throw acp.RequestError.authRequired();

packages/core/src/code_assist/oauth2.test.ts

@@ -95,6 +95,7 @@ const mockConfig = {
   getNoBrowser: () => false,
   getProxy: () => 'http://test.proxy.com:8080',
   isBrowserLaunchSuppressed: () => false,
+  getExperimentalZedIntegration: () => false,
 } as unknown as Config;
 
 // Mock fetch globally

packages/core/src/code_assist/oauth2.ts

@@ -271,9 +271,12 @@ async function initOauthClient(
 
     await triggerPostAuthCallbacks(client.credentials);
   } else {
-    const userConsent = await getConsentForOauth('');
-    if (!userConsent) {
-      throw new FatalCancellationError('Authentication cancelled by user.');
+    // In Zed integration, we skip the interactive consent and directly open the browser
+    if (!config.getExperimentalZedIntegration()) {
+      const userConsent = await getConsentForOauth('');
+      if (!userConsent) {
+        throw new FatalCancellationError('Authentication cancelled by user.');
+      }
     }
 
     const webLogin = await authWithWeb(client);

packages/core/src/config/config.test.ts

@@ -499,6 +499,7 @@ describe('Server Config (config.ts)', () => {
       expect(createContentGeneratorConfig).toHaveBeenCalledWith(
         config,
         authType,
+        undefined,
       );
       // Verify that contentGeneratorConfig is updated
       expect(config.getContentGeneratorConfig()).toEqual(mockContentConfig);
@@ -1928,7 +1929,7 @@ describe('Config getHooks', () => {
     const mockHooks = {
       BeforeTool: [
         {
-          hooks: [{ type: HookType.Command, command: 'echo 1' }],
+          hooks: [{ type: HookType.Command, command: 'echo 1' } as const],
         },
       ],
     };
@@ -2235,7 +2236,7 @@ describe('Hooks configuration', () => {
     const initialHooks = {
       BeforeAgent: [
         {
-          hooks: [{ type: HookType.Command, command: 'initial' }],
+          hooks: [{ type: HookType.Command as const, command: 'initial' }],
         },
       ],
     };
@@ -2533,6 +2534,29 @@ describe('Config Quota & Preview Model Access', () => {
       expect(config.isPlanEnabled()).toBe(false);
     });
   });
+
+  describe('getPlanModeRoutingEnabled', () => {
+    it('should default to true when not provided', async () => {
+      const config = new Config(baseParams);
+      expect(await config.getPlanModeRoutingEnabled()).toBe(true);
+    });
+
+    it('should return true when explicitly enabled in planSettings', async () => {
+      const config = new Config({
+        ...baseParams,
+        planSettings: { modelRouting: true },
+      });
+      expect(await config.getPlanModeRoutingEnabled()).toBe(true);
+    });
+
+    it('should return false when explicitly disabled in planSettings', async () => {
+      const config = new Config({
+        ...baseParams,
+        planSettings: { modelRouting: false },
+      });
+      expect(await config.getPlanModeRoutingEnabled()).toBe(false);
+    });
+  });
 });
 
 describe('Config JIT Initialization', () => {

packages/core/src/config/config.ts

@@ -21,11 +21,6 @@ import {
 import { PromptRegistry } from '../prompts/prompt-registry.js';
 import { ResourceRegistry } from '../resources/resource-registry.js';
 import { ToolRegistry } from '../tools/tool-registry.js';
-import { LSTool } from '../tools/ls.js';
-import { ReadFileTool } from '../tools/read-file.js';
-import { GrepTool } from '../tools/grep.js';
-import { canUseRipgrep, RipGrepTool } from '../tools/ripGrep.js';
-import { GlobTool } from '../tools/glob.js';
 import { ActivateSkillTool } from '../tools/activate-skill.js';
 import { EditTool } from '../tools/edit.js';
 import { ShellTool } from '../tools/shell.js';
@@ -69,13 +64,11 @@ import { WriteTodosTool } from '../tools/write-todos.js';
 import type { FileSystemService } from '../services/fileSystemService.js';
 import { StandardFileSystemService } from '../services/fileSystemService.js';
 import {
-  logRipgrepFallback,
   logFlashFallback,
   logApprovalModeSwitch,
   logApprovalModeDuration,
 } from '../telemetry/loggers.js';
 import {
-  RipgrepFallbackEvent,
   FlashFallbackEvent,
   ApprovalModeSwitchEvent,
   ApprovalModeDurationEvent,
@@ -153,6 +146,7 @@ export interface SummarizeToolOutputSettings {
 
 export interface PlanSettings {
   directory?: string;
+  modelRouting?: boolean;
 }
 
 export interface TelemetrySettings {
@@ -734,6 +728,7 @@ export class Config {
   private readonly experimentalJitContext: boolean;
   private readonly disableLLMCorrection: boolean;
   private readonly planEnabled: boolean;
+  private readonly planModeRoutingEnabled: boolean;
   private readonly modelSteering: boolean;
   private contextManager?: ContextManager;
   private terminalBackground: string | undefined = undefined;
@@ -823,6 +818,7 @@ export class Config {
     this.agents = params.agents ?? {};
     this.disableLLMCorrection = params.disableLLMCorrection ?? true;
     this.planEnabled = params.plan ?? false;
+    this.planModeRoutingEnabled = params.planSettings?.modelRouting ?? true;
     this.enableEventDrivenScheduler = params.enableEventDrivenScheduler ?? true;
     this.skillsSupport = params.skillsSupport ?? true;
     this.disabledSkills = params.disabledSkills ?? [];
@@ -1123,7 +1119,7 @@ export class Config {
     return this.contentGenerator;
   }
 
-  async refreshAuth(authMethod: AuthType) {
+  async refreshAuth(authMethod: AuthType, apiKey?: string) {
     // Reset availability service when switching auth
     this.modelAvailabilityService.reset();
 
@@ -1149,6 +1145,7 @@ export class Config {
     const newContentGeneratorConfig = await createContentGeneratorConfig(
       this,
       authMethod,
+      apiKey,
     );
     this.contentGenerator = await createContentGenerator(
       newContentGeneratorConfig,
@@ -2318,6 +2315,10 @@ export class Config {
     return this.experiments?.flags[ExperimentFlags.USER_CACHING]?.boolValue;
   }
 
+  async getPlanModeRoutingEnabled(): Promise<boolean> {
+    return this.planModeRoutingEnabled;
+  }
+
   async getNumericalRoutingEnabled(): Promise<boolean> {
     await this.ensureExperimentsLoaded();
 
@@ -2632,6 +2633,7 @@ export class Config {
       }
     };
 
+    /*
     maybeRegister(LSTool, () =>
       registry.registerTool(new LSTool(this, this.messageBus)),
     );
@@ -2666,6 +2668,7 @@ export class Config {
     maybeRegister(GlobTool, () =>
       registry.registerTool(new GlobTool(this, this.messageBus)),
     );
+    */
     maybeRegister(ActivateSkillTool, () =>
       registry.registerTool(new ActivateSkillTool(this, this.messageBus)),
     );

packages/core/src/core/contentGenerator.ts

@@ -90,9 +90,13 @@ export type ContentGeneratorConfig = {
 export async function createContentGeneratorConfig(
   config: Config,
   authType: AuthType | undefined,
+  apiKey?: string,
 ): Promise<ContentGeneratorConfig> {
   const geminiApiKey =
-    process.env['GEMINI_API_KEY'] || (await loadApiKey()) || undefined;
+    apiKey ||
+    process.env['GEMINI_API_KEY'] ||
+    (await loadApiKey()) ||
+    undefined;
   const googleApiKey = process.env['GOOGLE_API_KEY'] || undefined;
   const googleCloudProject =
     process.env['GOOGLE_CLOUD_PROJECT'] ||

packages/core/src/core/loggingContentGenerator.test.ts

@@ -24,11 +24,16 @@ vi.mock('../telemetry/trace.js', () => ({
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import type {
+  Content,
+  GenerateContentConfig,
   GenerateContentResponse,
   EmbedContentResponse,
 } from '@google/genai';
 import type { ContentGenerator } from './contentGenerator.js';
-import { LoggingContentGenerator } from './loggingContentGenerator.js';
+import {
+  LoggingContentGenerator,
+  estimateContextBreakdown,
+} from './loggingContentGenerator.js';
 import type { Config } from '../config/config.js';
 import { UserTierId } from '../code_assist/types.js';
 import { ApiRequestEvent, LlmRole } from '../telemetry/types.js';
@@ -346,3 +351,280 @@ describe('LoggingContentGenerator', () => {
     });
   });
 });
+
+describe('estimateContextBreakdown', () => {
+  it('should return zeros for empty contents and no config', () => {
+    const result = estimateContextBreakdown([], undefined);
+    expect(result).toEqual({
+      system_instructions: 0,
+      tool_definitions: 0,
+      history: 0,
+      tool_calls: {},
+      mcp_servers: 0,
+    });
+  });
+
+  it('should estimate system instruction tokens', () => {
+    const config = {
+      systemInstruction: 'You are a helpful assistant.',
+    } as GenerateContentConfig;
+    const result = estimateContextBreakdown([], config);
+    expect(result.system_instructions).toBeGreaterThan(0);
+    expect(result.tool_definitions).toBe(0);
+    expect(result.history).toBe(0);
+  });
+
+  it('should estimate non-MCP tool definition tokens', () => {
+    const config = {
+      tools: [
+        {
+          functionDeclarations: [
+            { name: 'read_file', description: 'Reads a file', parameters: {} },
+          ],
+        },
+      ],
+    } as unknown as GenerateContentConfig;
+    const result = estimateContextBreakdown([], config);
+    expect(result.tool_definitions).toBeGreaterThan(0);
+    expect(result.mcp_servers).toBe(0);
+  });
+
+  it('should classify MCP tool definitions into mcp_servers, not tool_definitions', () => {
+    const config = {
+      tools: [
+        {
+          functionDeclarations: [
+            {
+              name: 'myserver__search',
+              description: 'Search via MCP',
+              parameters: {},
+            },
+            {
+              name: 'read_file',
+              description: 'Reads a file',
+              parameters: {},
+            },
+          ],
+        },
+      ],
+    } as unknown as GenerateContentConfig;
+    const result = estimateContextBreakdown([], config);
+    expect(result.mcp_servers).toBeGreaterThan(0);
+    expect(result.tool_definitions).toBeGreaterThan(0);
+    // MCP tokens should not be in tool_definitions
+    const configOnlyBuiltin = {
+      tools: [
+        {
+          functionDeclarations: [
+            {
+              name: 'read_file',
+              description: 'Reads a file',
+              parameters: {},
+            },
+          ],
+        },
+      ],
+    } as unknown as GenerateContentConfig;
+    const builtinOnly = estimateContextBreakdown([], configOnlyBuiltin);
+    // tool_definitions should be smaller when MCP tools are separated out
+    expect(result.tool_definitions).toBeLessThan(
+      result.tool_definitions + result.mcp_servers,
+    );
+    expect(builtinOnly.mcp_servers).toBe(0);
+  });
+
+  it('should not classify tools with __ in the middle of a segment as MCP', () => {
+    // "__" at start or end (not a valid server__tool pattern) should not be MCP
+    const config = {
+      tools: [
+        {
+          functionDeclarations: [
+            { name: '__leading', description: 'test', parameters: {} },
+            { name: 'trailing__', description: 'test', parameters: {} },
+            {
+              name: 'a__b__c',
+              description: 'three parts - not valid MCP',
+              parameters: {},
+            },
+          ],
+        },
+      ],
+    } as unknown as GenerateContentConfig;
+    const result = estimateContextBreakdown([], config);
+    expect(result.mcp_servers).toBe(0);
+  });
+
+  it('should estimate history tokens excluding tool call/response parts', () => {
+    const contents: Content[] = [
+      { role: 'user', parts: [{ text: 'Hello world' }] },
+      { role: 'model', parts: [{ text: 'Hi there!' }] },
+    ];
+    const result = estimateContextBreakdown(contents);
+    expect(result.history).toBeGreaterThan(0);
+    expect(result.tool_calls).toEqual({});
+  });
+
+  it('should separate tool call tokens from history', () => {
+    const contents: Content[] = [
+      {
+        role: 'model',
+        parts: [
+          {
+            functionCall: {
+              name: 'read_file',
+              args: { path: '/tmp/test.txt' },
+            },
+          },
+        ],
+      },
+      {
+        role: 'function',
+        parts: [
+          {
+            functionResponse: {
+              name: 'read_file',
+              response: { content: 'file contents here' },
+            },
+          },
+        ],
+      },
+    ];
+    const result = estimateContextBreakdown(contents);
+    expect(result.tool_calls['read_file']).toBeGreaterThan(0);
+    // history should be zero since all parts are tool calls
+    expect(result.history).toBe(0);
+  });
+
+  it('should produce additive (non-overlapping) fields', () => {
+    const contents: Content[] = [
+      { role: 'user', parts: [{ text: 'Hello' }] },
+      {
+        role: 'model',
+        parts: [
+          {
+            functionCall: {
+              name: 'read_file',
+              args: { path: '/tmp/test.txt' },
+            },
+          },
+        ],
+      },
+      {
+        role: 'function',
+        parts: [
+          {
+            functionResponse: {
+              name: 'read_file',
+              response: { content: 'data' },
+            },
+          },
+        ],
+      },
+    ];
+    const config = {
+      systemInstruction: 'Be helpful.',
+      tools: [
+        {
+          functionDeclarations: [
+            { name: 'read_file', description: 'Read', parameters: {} },
+            {
+              name: 'myserver__search',
+              description: 'MCP search',
+              parameters: {},
+            },
+          ],
+        },
+      ],
+    } as unknown as GenerateContentConfig;
+    const result = estimateContextBreakdown(contents, config);
+
+    // All fields should be non-overlapping
+    expect(result.system_instructions).toBeGreaterThan(0);
+    expect(result.tool_definitions).toBeGreaterThan(0);
+    expect(result.history).toBeGreaterThan(0);
+    // tool_calls should only contain non-MCP tools
+    expect(result.tool_calls['read_file']).toBeGreaterThan(0);
+    expect(result.tool_calls['myserver__search']).toBeUndefined();
+    // MCP tokens are only in mcp_servers
+    expect(result.mcp_servers).toBeGreaterThan(0);
+  });
+
+  it('should classify MCP tool calls into mcp_servers only, not tool_calls', () => {
+    const contents: Content[] = [
+      {
+        role: 'model',
+        parts: [
+          {
+            functionCall: {
+              name: 'myserver__search',
+              args: { query: 'test' },
+            },
+          },
+        ],
+      },
+      {
+        role: 'function',
+        parts: [
+          {
+            functionResponse: {
+              name: 'myserver__search',
+              response: { results: [] },
+            },
+          },
+        ],
+      },
+    ];
+    const result = estimateContextBreakdown(contents);
+    // MCP tool calls should NOT appear in tool_calls
+    expect(result.tool_calls['myserver__search']).toBeUndefined();
+    // MCP call tokens should only be counted in mcp_servers
+    expect(result.mcp_servers).toBeGreaterThan(0);
+  });
+
+  it('should handle mixed MCP and non-MCP tool calls', () => {
+    const contents: Content[] = [
+      {
+        role: 'model',
+        parts: [
+          {
+            functionCall: {
+              name: 'read_file',
+              args: { path: '/test' },
+            },
+          },
+          {
+            functionCall: {
+              name: 'myserver__search',
+              args: { q: 'hello' },
+            },
+          },
+        ],
+      },
+    ];
+    const result = estimateContextBreakdown(contents);
+    // Non-MCP tools should be in tool_calls
+    expect(result.tool_calls['read_file']).toBeGreaterThan(0);
+    // MCP tools should NOT be in tool_calls
+    expect(result.tool_calls['myserver__search']).toBeUndefined();
+    // MCP tool calls should only be in mcp_servers
+    expect(result.mcp_servers).toBeGreaterThan(0);
+  });
+
+  it('should use "unknown" for tool calls without a name', () => {
+    const contents: Content[] = [
+      {
+        role: 'model',
+        parts: [
+          {
+            functionCall: {
+              name: undefined as unknown as string,
+              args: { x: 1 },
+            },
+          },
+        ],
+      },
+    ];
+    const result = estimateContextBreakdown(contents);
+    expect(result.tool_calls['unknown']).toBeGreaterThan(0);
+  });
+});

packages/core/src/core/loggingContentGenerator.ts

@@ -16,7 +16,7 @@ import type {
   GenerateContentResponseUsageMetadata,
   GenerateContentResponse,
 } from '@google/genai';
-import type { ServerDetails } from '../telemetry/types.js';
+import type { ServerDetails, ContextBreakdown } from '../telemetry/types.js';
 import {
   ApiRequestEvent,
   ApiResponseEvent,
@@ -37,14 +37,104 @@ import { isStructuredError } from '../utils/quotaErrorDetection.js';
 import { runInDevTraceSpan, type SpanMetadata } from '../telemetry/trace.js';
 import { debugLogger } from '../utils/debugLogger.js';
 import { getErrorType } from '../utils/errors.js';
+import { isMcpToolName } from '../tools/mcp-tool.js';
+import { estimateTokenCountSync } from '../utils/tokenCalculation.js';
 
 interface StructuredError {
   status: number;
 }
 
 /**
- * A decorator that wraps a ContentGenerator to add logging to API calls.
+ * Rough token estimate for non-Part config objects (tool definitions, etc.)
+ * where estimateTokenCountSync cannot be used directly.
  */
+function estimateConfigTokens(value: unknown): number {
+  return Math.floor(JSON.stringify(value).length / 4);
+}
+
+/**
+ * Estimates the context breakdown for telemetry. All returned fields are
+ * additive (non-overlapping), so their sum approximates the total context size.
+ *
+ * - system_instructions: tokens from system instruction config
+ * - tool_definitions: tokens from non-MCP tool definitions
+ * - history: tokens from conversation history, excluding tool call/response parts
+ * - tool_calls: per-tool token counts for non-MCP function call + response parts
+ * - mcp_servers: tokens from MCP tool definitions + MCP tool call/response parts
+ *
+ * MCP tool calls are excluded from tool_calls and counted only in mcp_servers
+ * to keep fields non-overlapping and avoid leaking MCP server names in telemetry.
+ */
+export function estimateContextBreakdown(
+  contents: Content[],
+  config?: GenerateContentConfig,
+): ContextBreakdown {
+  let systemInstructions = 0;
+  let toolDefinitions = 0;
+  let history = 0;
+  let mcpServers = 0;
+  const toolCalls: Record<string, number> = {};
+
+  if (config?.systemInstruction) {
+    systemInstructions += estimateConfigTokens(config.systemInstruction);
+  }
+
+  if (config?.tools) {
+    for (const tool of config.tools) {
+      const toolTokens = estimateConfigTokens(tool);
+      if (
+        tool &&
+        typeof tool === 'object' &&
+        'functionDeclarations' in tool &&
+        tool.functionDeclarations
+      ) {
+        let mcpTokensInTool = 0;
+        for (const func of tool.functionDeclarations) {
+          if (func.name && isMcpToolName(func.name)) {
+            mcpTokensInTool += estimateConfigTokens(func);
+          }
+        }
+        mcpServers += mcpTokensInTool;
+        toolDefinitions += toolTokens - mcpTokensInTool;
+      } else {
+        toolDefinitions += toolTokens;
+      }
+    }
+  }
+
+  for (const content of contents) {
+    for (const part of content.parts || []) {
+      if (part.functionCall) {
+        const name = part.functionCall.name || 'unknown';
+        const tokens = estimateTokenCountSync([part]);
+        if (isMcpToolName(name)) {
+          mcpServers += tokens;
+        } else {
+          toolCalls[name] = (toolCalls[name] || 0) + tokens;
+        }
+      } else if (part.functionResponse) {
+        const name = part.functionResponse.name || 'unknown';
+        const tokens = estimateTokenCountSync([part]);
+        if (isMcpToolName(name)) {
+          mcpServers += tokens;
+        } else {
+          toolCalls[name] = (toolCalls[name] || 0) + tokens;
+        }
+      } else {
+        history += estimateTokenCountSync([part]);
+      }
+    }
+  }
+
+  return {
+    system_instructions: systemInstructions,
+    tool_definitions: toolDefinitions,
+    history,
+    tool_calls: toolCalls,
+    mcp_servers: mcpServers,
+  };
+}
+
 export class LoggingContentGenerator implements ContentGenerator {
   constructor(
     private readonly wrapped: ContentGenerator,
@@ -134,27 +224,40 @@ export class LoggingContentGenerator implements ContentGenerator {
     generationConfig?: GenerateContentConfig,
     serverDetails?: ServerDetails,
   ): void {
-    logApiResponse(
-      this.config,
-      new ApiResponseEvent(
-        model,
-        durationMs,
-        {
-          prompt_id,
-          contents: requestContents,
-          generate_content_config: generationConfig,
-          server: serverDetails,
-        },
-        {
-          candidates: responseCandidates,
-          response_id: responseId,
-        },
-        this.config.getContentGeneratorConfig()?.authType,
-        usageMetadata,
-        responseText,
-        role,
-      ),
+    const event = new ApiResponseEvent(
+      model,
+      durationMs,
+      {
+        prompt_id,
+        contents: requestContents,
+        generate_content_config: generationConfig,
+        server: serverDetails,
+      },
+      {
+        candidates: responseCandidates,
+        response_id: responseId,
+      },
+      this.config.getContentGeneratorConfig()?.authType,
+      usageMetadata,
+      responseText,
+      role,
     );
+
+    // Only compute context breakdown for turn-ending responses (when the user
+    // gets back control to type). If the response contains function calls, the
+    // model is in a tool-use loop and will make more API calls — skip to avoid
+    // emitting redundant cumulative snapshots for every intermediate step.
+    const hasToolCalls = responseCandidates?.some((c) =>
+      c.content?.parts?.some((p) => p.functionCall),
+    );
+    if (!hasToolCalls) {
+      event.usage.context_breakdown = estimateContextBreakdown(
+        requestContents,
+        generationConfig,
+      );
+    }
+
+    logApiResponse(this.config, event);
   }
 
   private _logApiError(

packages/core/src/hooks/hookEventHandler.ts

@@ -8,7 +8,7 @@ import type { Config } from '../config/config.js';
 import type { HookPlanner, HookEventContext } from './hookPlanner.js';
 import type { HookRunner } from './hookRunner.js';
 import type { HookAggregator, AggregatedHookResult } from './hookAggregator.js';
-import { HookEventName } from './types.js';
+import { HookEventName, HookType } from './types.js';
 import type {
   HookConfig,
   HookInput,
@@ -500,7 +500,10 @@ export class HookEventHandler {
    * Get hook name from config for display or telemetry
    */
   private getHookName(config: HookConfig): string {
-    return config.name || config.command || 'unknown-command';
+    if (config.type === HookType.Command) {
+      return config.name || config.command || 'unknown-command';
+    }
+    return config.name || 'unknown-hook';
   }
 
   /**
@@ -513,7 +516,7 @@ export class HookEventHandler {
   /**
    * Get hook type from execution result for telemetry
    */
-  private getHookTypeFromResult(result: HookExecutionResult): 'command' {
+  private getHookTypeFromResult(result: HookExecutionResult): HookType {
     return result.hookConfig.type;
   }
 }

packages/core/src/hooks/hookRegistry.test.ts

@@ -13,9 +13,10 @@ import {
   HookEventName,
   HookType,
   HOOKS_CONFIG_FIELDS,
+  type CommandHookConfig,
+  type HookDefinition,
 } from './types.js';
 import type { Config } from '../config/config.js';
-import type { HookDefinition } from './types.js';
 
 // Mock fs
 vi.mock('fs', () => ({
@@ -153,7 +154,9 @@ describe('HookRegistry', () => {
       expect(hooks).toHaveLength(1);
       expect(hooks[0].eventName).toBe(HookEventName.BeforeTool);
       expect(hooks[0].config.type).toBe(HookType.Command);
-      expect(hooks[0].config.command).toBe('./hooks/check_style.sh');
+      expect((hooks[0].config as CommandHookConfig).command).toBe(
+        './hooks/check_style.sh',
+      );
       expect(hooks[0].matcher).toBe('EditTool');
       expect(hooks[0].source).toBe(ConfigSource.Project);
     });
@@ -186,7 +189,9 @@ describe('HookRegistry', () => {
       expect(hooks).toHaveLength(1);
       expect(hooks[0].eventName).toBe(HookEventName.AfterTool);
       expect(hooks[0].config.type).toBe(HookType.Command);
-      expect(hooks[0].config.command).toBe('./hooks/after-tool.sh');
+      expect((hooks[0].config as CommandHookConfig).command).toBe(
+        './hooks/after-tool.sh',
+      );
     });
 
     it('should handle invalid configuration gracefully', async () => {
@@ -632,7 +637,9 @@ describe('HookRegistry', () => {
       // Should only load the valid hook
       const hooks = hookRegistry.getAllHooks();
       expect(hooks).toHaveLength(1);
-      expect(hooks[0].config.command).toBe('./valid-hook.sh');
+      expect((hooks[0].config as CommandHookConfig).command).toBe(
+        './valid-hook.sh',
+      );
 
       // Verify the warnings for invalid configurations
       // 1st warning: non-object hookConfig ('invalid-string')

packages/core/src/hooks/hookRegistry.ts

@@ -34,11 +34,40 @@ export class HookRegistry {
     this.config = config;
   }
 
+  /**
+   * Register a new hook programmatically
+   */
+  registerHook(
+    config: HookConfig,
+    eventName: HookEventName,
+    options?: { matcher?: string; sequential?: boolean; source?: ConfigSource },
+  ): void {
+    const source = options?.source ?? ConfigSource.Runtime;
+
+    if (!this.validateHookConfig(config, eventName, source)) {
+      throw new Error(
+        `Invalid hook configuration for ${eventName} from ${source}`,
+      );
+    }
+
+    this.entries.push({
+      config,
+      source,
+      eventName,
+      matcher: options?.matcher,
+      sequential: options?.sequential,
+      enabled: true,
+    });
+  }
+
   /**
    * Initialize the registry by processing hooks from config
    */
   async initialize(): Promise<void> {
-    this.entries = [];
+    const runtimeHooks = this.entries.filter(
+      (entry) => entry.source === ConfigSource.Runtime,
+    );
+    this.entries = [...runtimeHooks];
     this.processHooksFromConfig();
 
     debugLogger.debug(
@@ -93,7 +122,10 @@ export class HookRegistry {
   private getHookName(
     entry: HookRegistryEntry | { config: HookConfig },
   ): string {
-    return entry.config.name || entry.config.command || 'unknown-command';
+    if (entry.config.type === 'command') {
+      return entry.config.name || entry.config.command || 'unknown-command';
+    }
+    return entry.config.name || 'unknown-hook';
   }
 
   /**
@@ -261,7 +293,10 @@ please review the project settings (.gemini/settings.json) and remove them.`;
     eventName: HookEventName,
     source: ConfigSource,
   ): boolean {
-    if (!config.type || !['command', 'plugin'].includes(config.type)) {
+    if (
+      !config.type ||
+      !['command', 'plugin', 'runtime'].includes(config.type)
+    ) {
       debugLogger.warn(
         `Invalid hook ${eventName} from ${source} type: ${config.type}`,
       );
@@ -275,6 +310,13 @@ please review the project settings (.gemini/settings.json) and remove them.`;
       return false;
     }
 
+    if (config.type === 'runtime' && !config.name) {
+      debugLogger.warn(
+        `Runtime hook ${eventName} from ${source} missing name field`,
+      );
+      return false;
+    }
+
     return true;
   }
 
@@ -292,6 +334,8 @@ please review the project settings (.gemini/settings.json) and remove them.`;
    */
   private getSourcePriority(source: ConfigSource): number {
     switch (source) {
+      case ConfigSource.Runtime:
+        return 0; // Highest
       case ConfigSource.Project:
         return 1;
       case ConfigSource.User:

packages/core/src/hooks/hookRunner.ts

@@ -7,6 +7,8 @@
 import { spawn } from 'node:child_process';
 import type {
   HookConfig,
+  CommandHookConfig,
+  RuntimeHookConfig,
   HookInput,
   HookOutput,
   HookExecutionResult,
@@ -15,7 +17,7 @@ import type {
   BeforeModelOutput,
   BeforeToolInput,
 } from './types.js';
-import { HookEventName, ConfigSource } from './types.js';
+import { HookEventName, ConfigSource, HookType } from './types.js';
 import type { Config } from '../config/config.js';
 import type { LLMRequest } from './hookTranslator.js';
 import { debugLogger } from '../utils/debugLogger.js';
@@ -75,6 +77,15 @@ export class HookRunner {
     }
 
     try {
+      if (hookConfig.type === HookType.Runtime) {
+        return await this.executeRuntimeHook(
+          hookConfig,
+          eventName,
+          input,
+          startTime,
+        );
+      }
+
       return await this.executeCommandHook(
         hookConfig,
         eventName,
@@ -83,7 +94,10 @@ export class HookRunner {
       );
     } catch (error) {
       const duration = Date.now() - startTime;
-      const hookId = hookConfig.name || hookConfig.command || 'unknown';
+      const hookId =
+        hookConfig.name ||
+        (hookConfig.type === HookType.Command ? hookConfig.command : '') ||
+        'unknown';
       const errorMessage = `Hook execution failed for event '${eventName}' (hook: ${hookId}): ${error}`;
       debugLogger.warn(`Hook execution error (non-fatal): ${errorMessage}`);
 
@@ -230,11 +244,66 @@ export class HookRunner {
     return modifiedInput;
   }
 
+  /**
+   * Execute a runtime hook
+   */
+  private async executeRuntimeHook(
+    hookConfig: RuntimeHookConfig,
+    eventName: HookEventName,
+    input: HookInput,
+    startTime: number,
+  ): Promise<HookExecutionResult> {
+    const timeout = hookConfig.timeout ?? DEFAULT_HOOK_TIMEOUT;
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    const controller = new AbortController();
+
+    try {
+      // Create a promise that rejects after timeout
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        timeoutHandle = setTimeout(
+          () => reject(new Error(`Hook timed out after ${timeout}ms`)),
+          timeout,
+        );
+      });
+
+      // Execute action with timeout race
+      const result = await Promise.race([
+        hookConfig.action(input, { signal: controller.signal }),
+        timeoutPromise,
+      ]);
+
+      const output =
+        result === null || result === undefined ? undefined : result;
+
+      return {
+        hookConfig,
+        eventName,
+        success: true,
+        output,
+        duration: Date.now() - startTime,
+      };
+    } catch (error) {
+      // Abort the ongoing hook action if it timed out or errored
+      controller.abort();
+      return {
+        hookConfig,
+        eventName,
+        success: false,
+        error: error instanceof Error ? error : new Error(String(error)),
+        duration: Date.now() - startTime,
+      };
+    } finally {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+    }
+  }
+
   /**
    * Execute a command hook
    */
   private async executeCommandHook(
-    hookConfig: HookConfig,
+    hookConfig: CommandHookConfig,
     eventName: HookEventName,
     input: HookInput,
     startTime: number,

packages/core/src/hooks/hookSystem.test.ts

@@ -77,7 +77,7 @@ describe('HookSystem Integration', () => {
             matcher: 'TestTool',
             hooks: [
               {
-                type: HookType.Command,
+                type: HookType.Command as const,
                 command: 'echo',
                 timeout: 5000,
               },
@@ -164,7 +164,8 @@ describe('HookSystem Integration', () => {
                 {
                   type: 'invalid-type' as HookType, // Invalid hook type for testing
                   command: './test.sh',
-                },
+                  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                } as any,
               ],
             },
           ],
@@ -279,12 +280,12 @@ describe('HookSystem Integration', () => {
               matcher: 'TestTool',
               hooks: [
                 {
-                  type: HookType.Command,
+                  type: HookType.Command as const,
                   command: 'echo "enabled-hook"',
                   timeout: 5000,
                 },
                 {
-                  type: HookType.Command,
+                  type: HookType.Command as const,
                   command: 'echo "disabled-hook"',
                   timeout: 5000,
                 },
@@ -350,7 +351,7 @@ describe('HookSystem Integration', () => {
               matcher: 'TestTool',
               hooks: [
                 {
-                  type: HookType.Command,
+                  type: HookType.Command as const,
                   command: 'echo "will-be-disabled"',
                   timeout: 5000,
                 },

packages/core/src/hooks/hookSystem.ts

@@ -21,6 +21,9 @@ import type {
   AfterModelHookOutput,
   BeforeToolSelectionHookOutput,
   McpToolContext,
+  HookConfig,
+  HookEventName,
+  ConfigSource,
 } from './types.js';
 import { NotificationType } from './types.js';
 import type { AggregatedHookResult } from './hookAggregator.js';
@@ -202,6 +205,17 @@ export class HookSystem {
     return this.hookRegistry.getAllHooks();
   }
 
+  /**
+   * Register a new hook programmatically
+   */
+  registerHook(
+    config: HookConfig,
+    eventName: HookEventName,
+    options?: { matcher?: string; sequential?: boolean; source?: ConfigSource },
+  ): void {
+    this.hookRegistry.registerHook(config, eventName, options);
+  }
+
   /**
    * Fire hook events directly
    */

packages/core/src/hooks/runtimeHooks.test.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { HookSystem } from './hookSystem.js';
+import { Config } from '../config/config.js';
+import { HookType, HookEventName, ConfigSource } from './types.js';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+
+// Mock console methods
+vi.stubGlobal('console', {
+  log: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  debug: vi.fn(),
+});
+
+describe('Runtime Hooks', () => {
+  let hookSystem: HookSystem;
+  let config: Config;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    const testDir = path.join(os.tmpdir(), 'test-runtime-hooks');
+    fs.mkdirSync(testDir, { recursive: true });
+
+    config = new Config({
+      model: 'gemini-3-flash-preview',
+      targetDir: testDir,
+      sessionId: 'test-session',
+      debugMode: false,
+      cwd: testDir,
+    });
+
+    // Stub getMessageBus
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (config as any).getMessageBus = () => undefined;
+
+    hookSystem = new HookSystem(config);
+  });
+
+  it('should register a runtime hook', async () => {
+    await hookSystem.initialize();
+
+    const action = vi.fn().mockResolvedValue(undefined);
+    hookSystem.registerHook(
+      {
+        type: HookType.Runtime,
+        name: 'test-hook',
+        action,
+      },
+      HookEventName.BeforeTool,
+      { matcher: 'TestTool' },
+    );
+
+    const hooks = hookSystem.getAllHooks();
+    expect(hooks).toHaveLength(1);
+    expect(hooks[0].config.name).toBe('test-hook');
+    expect(hooks[0].source).toBe(ConfigSource.Runtime);
+  });
+
+  it('should execute a runtime hook', async () => {
+    await hookSystem.initialize();
+
+    const action = vi.fn().mockImplementation(async () => ({
+      decision: 'allow',
+      systemMessage: 'Hook ran',
+    }));
+
+    hookSystem.registerHook(
+      {
+        type: HookType.Runtime,
+        name: 'test-hook',
+        action,
+      },
+      HookEventName.BeforeTool,
+      { matcher: 'TestTool' },
+    );
+
+    const result = await hookSystem
+      .getEventHandler()
+      .fireBeforeToolEvent('TestTool', { foo: 'bar' });
+
+    expect(action).toHaveBeenCalled();
+    expect(action.mock.calls[0][0]).toMatchObject({
+      tool_name: 'TestTool',
+      tool_input: { foo: 'bar' },
+      hook_event_name: 'BeforeTool',
+    });
+
+    expect(result.finalOutput?.systemMessage).toBe('Hook ran');
+  });
+
+  it('should handle runtime hook errors', async () => {
+    await hookSystem.initialize();
+
+    const action = vi.fn().mockRejectedValue(new Error('Hook failed'));
+
+    hookSystem.registerHook(
+      {
+        type: HookType.Runtime,
+        name: 'fail-hook',
+        action,
+      },
+      HookEventName.BeforeTool,
+      { matcher: 'TestTool' },
+    );
+
+    // Should not throw, but handle error gracefully
+    await hookSystem.getEventHandler().fireBeforeToolEvent('TestTool', {});
+
+    expect(action).toHaveBeenCalled();
+  });
+
+  it('should preserve runtime hooks across re-initialization', async () => {
+    await hookSystem.initialize();
+
+    hookSystem.registerHook(
+      {
+        type: HookType.Runtime,
+        name: 'persist-hook',
+        action: async () => {},
+      },
+      HookEventName.BeforeTool,
+      { matcher: 'TestTool' },
+    );
+
+    expect(hookSystem.getAllHooks()).toHaveLength(1);
+
+    // Re-initialize
+    await hookSystem.initialize();
+
+    expect(hookSystem.getAllHooks()).toHaveLength(1);
+    expect(hookSystem.getAllHooks()[0].config.name).toBe('persist-hook');
+  });
+});

packages/core/src/hooks/trustedHooks.test.ts

@@ -8,7 +8,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import * as fs from 'node:fs';
 import { TrustedHooksManager } from './trustedHooks.js';
 import { Storage } from '../config/storage.js';
-import { HookEventName, HookType } from './types.js';
+import { HookEventName, HookType, type HookDefinition } from './types.js';
 
 vi.mock('node:fs');
 vi.mock('../config/storage.js');
@@ -72,8 +72,16 @@ describe('TrustedHooksManager', () => {
         [HookEventName.BeforeTool]: [
           {
             hooks: [
-              { name: 'trusted-hook', type: HookType.Command, command: 'cmd1' },
-              { name: 'new-hook', type: HookType.Command, command: 'cmd2' },
+              {
+                name: 'trusted-hook',
+                type: HookType.Command,
+                command: 'cmd1',
+              } as const,
+              {
+                name: 'new-hook',
+                type: HookType.Command,
+                command: 'cmd2',
+              } as const,
             ],
           },
         ],
@@ -90,7 +98,11 @@ describe('TrustedHooksManager', () => {
         [HookEventName.BeforeTool]: [
           {
             hooks: [
-              { name: 'trusted-hook', type: HookType.Command, command: 'cmd1' },
+              {
+                name: 'trusted-hook',
+                type: HookType.Command,
+                command: 'cmd1',
+              } as const,
             ],
           },
         ],
@@ -114,9 +126,12 @@ describe('TrustedHooksManager', () => {
         ],
       };
 
-      expect(manager.getUntrustedHooks('/project', projectHooks)).toEqual([
-        './script.sh',
-      ]);
+      expect(
+        manager.getUntrustedHooks(
+          '/project',
+          projectHooks as Partial<Record<HookEventName, HookDefinition[]>>,
+        ),
+      ).toEqual(['./script.sh']);
     });
 
     it('should detect change in command as untrusted', () => {
@@ -142,11 +157,17 @@ describe('TrustedHooksManager', () => {
         ],
       };
 
-      manager.trustHooks('/project', originalHook);
+      manager.trustHooks(
+        '/project',
+        originalHook as Partial<Record<HookEventName, HookDefinition[]>>,
+      );
 
-      expect(manager.getUntrustedHooks('/project', updatedHook)).toEqual([
-        'my-hook',
-      ]);
+      expect(
+        manager.getUntrustedHooks(
+          '/project',
+          updatedHook as Partial<Record<HookEventName, HookDefinition[]>>,
+        ),
+      ).toEqual(['my-hook']);
     });
   });
 

packages/core/src/hooks/trustedHooks.ts

@@ -9,6 +9,7 @@ import * as path from 'node:path';
 import { Storage } from '../config/storage.js';
 import {
   getHookKey,
+  HookType,
   type HookDefinition,
   type HookEventName,
 } from './types.js';
@@ -79,6 +80,7 @@ export class TrustedHooksManager {
       for (const def of definitions) {
         if (!def || !Array.isArray(def.hooks)) continue;
         for (const hook of def.hooks) {
+          if (hook.type === HookType.Runtime) continue;
           const key = getHookKey(hook);
           if (!trustedKeys.has(key)) {
             // Return friendly name or command
@@ -108,6 +110,7 @@ export class TrustedHooksManager {
       for (const def of definitions) {
         if (!def || !Array.isArray(def.hooks)) continue;
         for (const hook of def.hooks) {
+          if (hook.type === HookType.Runtime) continue;
           currentTrusted.add(getHookKey(hook));
         }
       }

packages/core/src/hooks/types.ts

@@ -21,6 +21,7 @@ import { defaultHookTranslator } from './hookTranslator.js';
  * Configuration source levels in precedence order (highest to lowest)
  */
 export enum ConfigSource {
+  Runtime = 'runtime',
   Project = 'project',
   User = 'user',
   System = 'system',
@@ -50,11 +51,43 @@ export enum HookEventName {
 export const HOOKS_CONFIG_FIELDS = ['enabled', 'disabled', 'notifications'];
 
 /**
- * Hook configuration entry
+ * Hook implementation types
+ */
+export enum HookType {
+  Command = 'command',
+  Runtime = 'runtime',
+}
+
+/**
+ * Hook action function
+ */
+export type HookAction = (
+  input: HookInput,
+  options?: { signal: AbortSignal },
+) => Promise<HookOutput | void | null>;
+
+/**
+ * Runtime hook configuration
+ */
+export interface RuntimeHookConfig {
+  type: HookType.Runtime;
+  /** Unique name for the runtime hook */
+  name: string;
+  /** Function to execute when the hook is triggered */
+  action: HookAction;
+  command?: never;
+  source?: ConfigSource;
+  /** Maximum time allowed for hook execution in milliseconds */
+  timeout?: number;
+}
+
+/**
+ * Command hook configuration entry
  */
 export interface CommandHookConfig {
   type: HookType.Command;
   command: string;
+  action?: never;
   name?: string;
   description?: string;
   timeout?: number;
@@ -62,7 +95,7 @@ export interface CommandHookConfig {
   env?: Record<string, string>;
 }
 
-export type HookConfig = CommandHookConfig;
+export type HookConfig = CommandHookConfig | RuntimeHookConfig;
 
 /**
  * Hook definition with matcher
@@ -73,19 +106,12 @@ export interface HookDefinition {
   hooks: HookConfig[];
 }
 
-/**
- * Hook implementation types
- */
-export enum HookType {
-  Command = 'command',
-}
-
 /**
  * Generate a unique key for a hook configuration
  */
 export function getHookKey(hook: HookConfig): string {
   const name = hook.name || '';
-  const command = hook.command || '';
+  const command = hook.type === HookType.Command ? hook.command : '';
   return `${name}:${command}`;
 }
 

packages/core/src/prompts/snippets.ts

@@ -10,10 +10,7 @@ import {
   EDIT_TOOL_NAME,
   ENTER_PLAN_MODE_TOOL_NAME,
   EXIT_PLAN_MODE_TOOL_NAME,
-  GLOB_TOOL_NAME,
-  GREP_TOOL_NAME,
   MEMORY_TOOL_NAME,
-  READ_FILE_TOOL_NAME,
   SHELL_TOOL_NAME,
   WRITE_FILE_TOOL_NAME,
   WRITE_TODOS_TOOL_NAME,
@@ -179,20 +176,20 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to ${GREP_TOOL_NAME}, to enable you to skip using an extra turn reading the file.
-- Prefer using tools like ${GREP_TOOL_NAME} to identify points of interest instead of reading lots of files individually.
+- Combine turns whenever possible by utilizing parallel searching and reading. When searching, request enough context (e.g., using context, before, or after flags) to enable you to skip using an extra turn reading the file.
+- Prefer using search to identify points of interest instead of reading lots of files individually.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like ${READ_FILE_TOOL_NAME} and ${GREP_TOOL_NAME}.
-- ${READ_FILE_TOOL_NAME} fails if old_string is ambiguous, causing extra turns. Take care to read enough with ${READ_FILE_TOOL_NAME} and ${GREP_TOOL_NAME} to make the edit unambiguous.
+- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes.
+- Ensure you have read enough context to make edits unambiguous. Ambiguity in the target text for an edit causes extra turns.
 - You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
 - Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
 </guidelines>
 
 <examples>
-- **Searching:** utilize search tools like ${GREP_TOOL_NAME} and ${GLOB_TOOL_NAME} with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include\` and \`exclude\` parameters).
-- **Searching and editing:** utilize search tools like ${GREP_TOOL_NAME} with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
+- **Searching:** utilize search tools with a conservative result count and a narrow scope.
+- **Searching and editing:** utilize search tools with a conservative result count and a narrow scope. Request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize search tools like ${GREP_TOOL_NAME} and/or ${READ_FILE_TOOL_NAME} called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **Large files:** utilize search tools and/or file reading tools called in parallel with line ranges to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -495,7 +492,7 @@ function renderApprovedPlanSection(approvedPlanPath?: string): string {
   if (!approvedPlanPath) return '';
   return `## Approved Plan
 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.
+- **Read First:** You MUST read this file 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".
 `;
@@ -529,32 +526,21 @@ function mandateContinueWork(interactive: boolean): string {
 function workflowStepResearch(options: PrimaryWorkflowsOptions): string {
   let suggestion = '';
   if (options.enableEnterPlanModeTool) {
-    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.`;
+    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[] = [];
-  if (options.enableGrep) searchTools.push(formatToolName(GREP_TOOL_NAME));
-  if (options.enableGlob) searchTools.push(formatToolName(GLOB_TOOL_NAME));
-
-  let searchSentence =
-    ' Use search tools extensively to understand file structures, existing code patterns, and conventions.';
-  if (searchTools.length > 0) {
-    const toolsStr = searchTools.join(' and ');
-    const toolOrTools = searchTools.length > 1 ? 'tools' : 'tool';
-    searchSentence = ` Use ${toolsStr} search ${toolOrTools} extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.`;
-  }
+  const searchSentence =
+    ' Use search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.';
 
   if (options.enableCodebaseInvestigator) {
-    let subAgentSearch = '';
-    if (searchTools.length > 0) {
-      const toolsStr = searchTools.join(' or ');
-      subAgentSearch = ` For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), use ${toolsStr} directly in parallel.`;
-    }
+    const subAgentSearch = ` For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), use search tools directly in parallel.`;
 
-    return `1. **Research:** Systematically map the codebase and validate assumptions. Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery when the task involves **complex refactoring, codebase exploration or system-wide analysis**.${subAgentSearch} Use ${formatToolName(READ_FILE_TOOL_NAME)} to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;
+    return `1. **Research:** Systematically map the codebase and validate assumptions. Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery when the task involves **complex refactoring, codebase exploration or system-wide analysis**.${subAgentSearch} Use read tools to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;
   }
 
-  return `1. **Research:** Systematically map the codebase and validate assumptions.${searchSentence} Use ${formatToolName(READ_FILE_TOOL_NAME)} to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;
+  return `1. **Research:** Systematically map the codebase and validate assumptions.${searchSentence} Use read tools to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;
 }
 
 function workflowStepStrategy(options: PrimaryWorkflowsOptions): string {

packages/core/src/routing/modelRouterService.test.ts

@@ -14,10 +14,12 @@ import { DefaultStrategy } from './strategies/defaultStrategy.js';
 import { CompositeStrategy } from './strategies/compositeStrategy.js';
 import { FallbackStrategy } from './strategies/fallbackStrategy.js';
 import { OverrideStrategy } from './strategies/overrideStrategy.js';
+import { ApprovalModeStrategy } from './strategies/approvalModeStrategy.js';
 import { ClassifierStrategy } from './strategies/classifierStrategy.js';
 import { NumericalClassifierStrategy } from './strategies/numericalClassifierStrategy.js';
 import { logModelRouting } from '../telemetry/loggers.js';
 import { ModelRoutingEvent } from '../telemetry/types.js';
+import { ApprovalMode } from '../policy/types.js';
 
 vi.mock('../config/config.js');
 vi.mock('../core/baseLlmClient.js');
@@ -25,6 +27,7 @@ vi.mock('./strategies/defaultStrategy.js');
 vi.mock('./strategies/compositeStrategy.js');
 vi.mock('./strategies/fallbackStrategy.js');
 vi.mock('./strategies/overrideStrategy.js');
+vi.mock('./strategies/approvalModeStrategy.js');
 vi.mock('./strategies/classifierStrategy.js');
 vi.mock('./strategies/numericalClassifierStrategy.js');
 vi.mock('../telemetry/loggers.js');
@@ -45,11 +48,15 @@ describe('ModelRouterService', () => {
     vi.spyOn(mockConfig, 'getBaseLlmClient').mockReturnValue(mockBaseLlmClient);
     vi.spyOn(mockConfig, 'getNumericalRoutingEnabled').mockResolvedValue(false);
     vi.spyOn(mockConfig, 'getClassifierThreshold').mockResolvedValue(undefined);
+    vi.spyOn(mockConfig, 'getApprovalMode').mockReturnValue(
+      ApprovalMode.DEFAULT,
+    );
 
     mockCompositeStrategy = new CompositeStrategy(
       [
         new FallbackStrategy(),
         new OverrideStrategy(),
+        new ApprovalModeStrategy(),
         new ClassifierStrategy(),
         new NumericalClassifierStrategy(),
         new DefaultStrategy(),
@@ -79,12 +86,13 @@ describe('ModelRouterService', () => {
     const compositeStrategyArgs = vi.mocked(CompositeStrategy).mock.calls[0];
     const childStrategies = compositeStrategyArgs[0];
 
-    expect(childStrategies.length).toBe(5);
+    expect(childStrategies.length).toBe(6);
     expect(childStrategies[0]).toBeInstanceOf(FallbackStrategy);
     expect(childStrategies[1]).toBeInstanceOf(OverrideStrategy);
-    expect(childStrategies[2]).toBeInstanceOf(ClassifierStrategy);
-    expect(childStrategies[3]).toBeInstanceOf(NumericalClassifierStrategy);
-    expect(childStrategies[4]).toBeInstanceOf(DefaultStrategy);
+    expect(childStrategies[2]).toBeInstanceOf(ApprovalModeStrategy);
+    expect(childStrategies[3]).toBeInstanceOf(ClassifierStrategy);
+    expect(childStrategies[4]).toBeInstanceOf(NumericalClassifierStrategy);
+    expect(childStrategies[5]).toBeInstanceOf(DefaultStrategy);
     expect(compositeStrategyArgs[1]).toBe('agent-router');
   });
 
@@ -127,6 +135,7 @@ describe('ModelRouterService', () => {
         'Strategy reasoning',
         false,
         undefined,
+        ApprovalMode.DEFAULT,
         false,
         undefined,
       );
@@ -153,6 +162,7 @@ describe('ModelRouterService', () => {
         'An exception occurred during routing.',
         true,
         'Strategy failed',
+        ApprovalMode.DEFAULT,
         false,
         undefined,
       );

packages/core/src/routing/modelRouterService.ts

@@ -16,6 +16,7 @@ import { NumericalClassifierStrategy } from './strategies/numericalClassifierStr
 import { CompositeStrategy } from './strategies/compositeStrategy.js';
 import { FallbackStrategy } from './strategies/fallbackStrategy.js';
 import { OverrideStrategy } from './strategies/overrideStrategy.js';
+import { ApprovalModeStrategy } from './strategies/approvalModeStrategy.js';
 
 import { logModelRouting } from '../telemetry/loggers.js';
 import { ModelRoutingEvent } from '../telemetry/types.js';
@@ -40,6 +41,7 @@ export class ModelRouterService {
       [
         new FallbackStrategy(),
         new OverrideStrategy(),
+        new ApprovalModeStrategy(),
         new ClassifierStrategy(),
         new NumericalClassifierStrategy(),
         new DefaultStrategy(),
@@ -105,6 +107,7 @@ export class ModelRouterService {
         decision!.metadata.reasoning,
         failed,
         error_message,
+        this.config.getApprovalMode(),
         enableNumericalRouting,
         classifierThreshold,
       );

packages/core/src/routing/strategies/approvalModeStrategy.test.ts

@@ -0,0 +1,187 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ApprovalModeStrategy } from './approvalModeStrategy.js';
+import type { RoutingContext } from '../routingStrategy.js';
+import type { Config } from '../../config/config.js';
+import {
+  DEFAULT_GEMINI_MODEL,
+  DEFAULT_GEMINI_FLASH_MODEL,
+  PREVIEW_GEMINI_MODEL,
+  PREVIEW_GEMINI_FLASH_MODEL,
+  DEFAULT_GEMINI_MODEL_AUTO,
+  PREVIEW_GEMINI_MODEL_AUTO,
+} from '../../config/models.js';
+import { ApprovalMode } from '../../policy/types.js';
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+
+describe('ApprovalModeStrategy', () => {
+  let strategy: ApprovalModeStrategy;
+  let mockContext: RoutingContext;
+  let mockConfig: Config;
+  let mockBaseLlmClient: BaseLlmClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    strategy = new ApprovalModeStrategy();
+    mockContext = {
+      history: [],
+      request: [{ text: 'test' }],
+      signal: new AbortController().signal,
+    };
+
+    mockConfig = {
+      getModel: vi.fn().mockReturnValue(DEFAULT_GEMINI_MODEL_AUTO),
+      getApprovalMode: vi.fn().mockReturnValue(ApprovalMode.DEFAULT),
+      getApprovedPlanPath: vi.fn().mockReturnValue(undefined),
+      getPlanModeRoutingEnabled: vi.fn().mockResolvedValue(true),
+    } as unknown as Config;
+
+    mockBaseLlmClient = {} as BaseLlmClient;
+  });
+
+  it('should return null if the model is not an auto model', async () => {
+    vi.mocked(mockConfig.getModel).mockReturnValue(DEFAULT_GEMINI_MODEL);
+
+    const decision = await strategy.route(
+      mockContext,
+      mockConfig,
+      mockBaseLlmClient,
+    );
+
+    expect(decision).toBeNull();
+  });
+
+  it('should return null if plan mode routing is disabled', async () => {
+    vi.mocked(mockConfig.getPlanModeRoutingEnabled).mockResolvedValue(false);
+    vi.mocked(mockConfig.getApprovalMode).mockReturnValue(ApprovalMode.PLAN);
+
+    const decision = await strategy.route(
+      mockContext,
+      mockConfig,
+      mockBaseLlmClient,
+    );
+
+    expect(decision).toBeNull();
+  });
+
+  it('should route to PRO model if ApprovalMode is PLAN (Gemini 2.5)', async () => {
+    vi.mocked(mockConfig.getModel).mockReturnValue(DEFAULT_GEMINI_MODEL_AUTO);
+    vi.mocked(mockConfig.getApprovalMode).mockReturnValue(ApprovalMode.PLAN);
+
+    const decision = await strategy.route(
+      mockContext,
+      mockConfig,
+      mockBaseLlmClient,
+    );
+
+    expect(decision).toEqual({
+      model: DEFAULT_GEMINI_MODEL,
+      metadata: {
+        source: 'approval-mode',
+        latencyMs: expect.any(Number),
+        reasoning: 'Routing to Pro model because ApprovalMode is PLAN.',
+      },
+    });
+  });
+
+  it('should route to PRO model if ApprovalMode is PLAN (Gemini 3)', async () => {
+    vi.mocked(mockConfig.getModel).mockReturnValue(PREVIEW_GEMINI_MODEL_AUTO);
+    vi.mocked(mockConfig.getApprovalMode).mockReturnValue(ApprovalMode.PLAN);
+
+    const decision = await strategy.route(
+      mockContext,
+      mockConfig,
+      mockBaseLlmClient,
+    );
+
+    expect(decision).toEqual({
+      model: PREVIEW_GEMINI_MODEL,
+      metadata: {
+        source: 'approval-mode',
+        latencyMs: expect.any(Number),
+        reasoning: 'Routing to Pro model because ApprovalMode is PLAN.',
+      },
+    });
+  });
+
+  it('should route to FLASH model if an approved plan exists (Gemini 2.5)', async () => {
+    vi.mocked(mockConfig.getModel).mockReturnValue(DEFAULT_GEMINI_MODEL_AUTO);
+    vi.mocked(mockConfig.getApprovalMode).mockReturnValue(ApprovalMode.DEFAULT);
+    vi.mocked(mockConfig.getApprovedPlanPath).mockReturnValue(
+      '/path/to/plan.md',
+    );
+
+    const decision = await strategy.route(
+      mockContext,
+      mockConfig,
+      mockBaseLlmClient,
+    );
+
+    expect(decision).toEqual({
+      model: DEFAULT_GEMINI_FLASH_MODEL,
+      metadata: {
+        source: 'approval-mode',
+        latencyMs: expect.any(Number),
+        reasoning:
+          'Routing to Flash model because an approved plan exists at /path/to/plan.md.',
+      },
+    });
+  });
+
+  it('should route to FLASH model if an approved plan exists (Gemini 3)', async () => {
+    vi.mocked(mockConfig.getModel).mockReturnValue(PREVIEW_GEMINI_MODEL_AUTO);
+    vi.mocked(mockConfig.getApprovalMode).mockReturnValue(ApprovalMode.DEFAULT);
+    vi.mocked(mockConfig.getApprovedPlanPath).mockReturnValue(
+      '/path/to/plan.md',
+    );
+
+    const decision = await strategy.route(
+      mockContext,
+      mockConfig,
+      mockBaseLlmClient,
+    );
+
+    expect(decision).toEqual({
+      model: PREVIEW_GEMINI_FLASH_MODEL,
+      metadata: {
+        source: 'approval-mode',
+        latencyMs: expect.any(Number),
+        reasoning:
+          'Routing to Flash model because an approved plan exists at /path/to/plan.md.',
+      },
+    });
+  });
+
+  it('should return null if not in PLAN mode and no approved plan exists', async () => {
+    vi.mocked(mockConfig.getApprovalMode).mockReturnValue(ApprovalMode.DEFAULT);
+    vi.mocked(mockConfig.getApprovedPlanPath).mockReturnValue(undefined);
+
+    const decision = await strategy.route(
+      mockContext,
+      mockConfig,
+      mockBaseLlmClient,
+    );
+
+    expect(decision).toBeNull();
+  });
+
+  it('should prioritize requestedModel over config model if it is an auto model', async () => {
+    mockContext.requestedModel = PREVIEW_GEMINI_MODEL_AUTO;
+    vi.mocked(mockConfig.getModel).mockReturnValue(DEFAULT_GEMINI_MODEL_AUTO);
+    vi.mocked(mockConfig.getApprovalMode).mockReturnValue(ApprovalMode.PLAN);
+
+    const decision = await strategy.route(
+      mockContext,
+      mockConfig,
+      mockBaseLlmClient,
+    );
+
+    expect(decision?.model).toBe(PREVIEW_GEMINI_MODEL);
+  });
+});

packages/core/src/routing/strategies/approvalModeStrategy.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Config } from '../../config/config.js';
+import {
+  DEFAULT_GEMINI_MODEL,
+  DEFAULT_GEMINI_FLASH_MODEL,
+  PREVIEW_GEMINI_MODEL,
+  PREVIEW_GEMINI_FLASH_MODEL,
+  isAutoModel,
+  isPreviewModel,
+} from '../../config/models.js';
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+import { ApprovalMode } from '../../policy/types.js';
+import type {
+  RoutingContext,
+  RoutingDecision,
+  RoutingStrategy,
+} from '../routingStrategy.js';
+
+/**
+ * A strategy that routes based on the current ApprovalMode and plan status.
+ *
+ * - In PLAN mode: Routes to the PRO model for high-quality planning.
+ * - In other modes with an approved plan: Routes to the FLASH model for efficient implementation.
+ */
+export class ApprovalModeStrategy implements RoutingStrategy {
+  readonly name = 'approval-mode';
+
+  async route(
+    context: RoutingContext,
+    config: Config,
+    _baseLlmClient: BaseLlmClient,
+  ): Promise<RoutingDecision | null> {
+    const model = context.requestedModel ?? config.getModel();
+
+    // This strategy only applies to "auto" models.
+    if (!isAutoModel(model)) {
+      return null;
+    }
+
+    if (!(await config.getPlanModeRoutingEnabled())) {
+      return null;
+    }
+
+    const startTime = Date.now();
+    const approvalMode = config.getApprovalMode();
+    const approvedPlanPath = config.getApprovedPlanPath();
+
+    const isPreview = isPreviewModel(model);
+
+    // 1. Planning Phase: If ApprovalMode === PLAN, explicitly route to the Pro model.
+    if (approvalMode === ApprovalMode.PLAN) {
+      const proModel = isPreview ? PREVIEW_GEMINI_MODEL : DEFAULT_GEMINI_MODEL;
+      return {
+        model: proModel,
+        metadata: {
+          source: this.name,
+          latencyMs: Date.now() - startTime,
+          reasoning: 'Routing to Pro model because ApprovalMode is PLAN.',
+        },
+      };
+    } else if (approvedPlanPath) {
+      // 2. Implementation Phase: If ApprovalMode !== PLAN AND an approved plan path is set, prefer the Flash model.
+      const flashModel = isPreview
+        ? PREVIEW_GEMINI_FLASH_MODEL
+        : DEFAULT_GEMINI_FLASH_MODEL;
+      return {
+        model: flashModel,
+        metadata: {
+          source: this.name,
+          latencyMs: Date.now() - startTime,
+          reasoning: `Routing to Flash model because an approved plan exists at ${approvedPlanPath}.`,
+        },
+      };
+    }
+
+    return null;
+  }
+}

packages/core/src/telemetry/clearcut-logger/clearcut-logger.test.ts

@@ -35,7 +35,9 @@ import {
   WebFetchFallbackAttemptEvent,
   HookCallEvent,
 } from '../types.js';
+import { HookType } from '../../hooks/types.js';
 import { AgentTerminateMode } from '../../agents/types.js';
+import { ApprovalMode } from '../../policy/types.js';
 import { GIT_COMMIT_INFO, CLI_VERSION } from '../../generated/git-commit.js';
 import { UserAccountManager } from '../../utils/userAccountManager.js';
 import { InstallationManager } from '../../utils/installationManager.js';
@@ -904,6 +906,7 @@ describe('ClearcutLogger', () => {
         'some reasoning',
         false,
         undefined,
+        ApprovalMode.DEFAULT,
       );
 
       logger?.logModelRoutingEvent(event);
@@ -938,6 +941,7 @@ describe('ClearcutLogger', () => {
         'some reasoning',
         true,
         'Something went wrong',
+        ApprovalMode.DEFAULT,
       );
 
       logger?.logModelRoutingEvent(event);
@@ -976,6 +980,7 @@ describe('ClearcutLogger', () => {
         '[Score: 90 / Threshold: 80] reasoning',
         false,
         undefined,
+        ApprovalMode.DEFAULT,
         true,
         '80',
       );
@@ -1401,7 +1406,7 @@ describe('ClearcutLogger', () => {
 
       const event = new HookCallEvent(
         'before-tool',
-        'command',
+        HookType.Command,
         hookName,
         {}, // input
         150, // duration

packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts

@@ -846,6 +846,40 @@ export class ClearcutLogger {
           EventMetadataKey.GEMINI_CLI_API_RESPONSE_TOOL_TOKEN_COUNT,
         value: JSON.stringify(event.usage.tool_token_count),
       },
+      // Context breakdown fields are only populated on turn-ending responses
+      // (when the user gets back control), not during intermediate tool-use
+      // loops. Values still grow across turns as conversation history
+      // accumulates, so downstream consumers should use the last event per
+      // session (MAX) rather than summing across events.
+      {
+        gemini_cli_key:
+          EventMetadataKey.GEMINI_CLI_API_RESPONSE_CONTEXT_BREAKDOWN_SYSTEM_INSTRUCTIONS,
+        value: JSON.stringify(
+          event.usage.context_breakdown?.system_instructions ?? 0,
+        ),
+      },
+      {
+        gemini_cli_key:
+          EventMetadataKey.GEMINI_CLI_API_RESPONSE_CONTEXT_BREAKDOWN_TOOL_DEFINITIONS,
+        value: JSON.stringify(
+          event.usage.context_breakdown?.tool_definitions ?? 0,
+        ),
+      },
+      {
+        gemini_cli_key:
+          EventMetadataKey.GEMINI_CLI_API_RESPONSE_CONTEXT_BREAKDOWN_HISTORY,
+        value: JSON.stringify(event.usage.context_breakdown?.history ?? 0),
+      },
+      {
+        gemini_cli_key:
+          EventMetadataKey.GEMINI_CLI_API_RESPONSE_CONTEXT_BREAKDOWN_TOOL_CALLS,
+        value: JSON.stringify(event.usage.context_breakdown?.tool_calls ?? {}),
+      },
+      {
+        gemini_cli_key:
+          EventMetadataKey.GEMINI_CLI_API_RESPONSE_CONTEXT_BREAKDOWN_MCP_SERVERS,
+        value: JSON.stringify(event.usage.context_breakdown?.mcp_servers ?? 0),
+      },
     ];
 
     this.enqueueLogEvent(this.createLogEvent(EventNames.API_RESPONSE, data));

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: 167
+  // Next ID: 172
 
   GEMINI_CLI_KEY_UNKNOWN = 0,
 
@@ -137,6 +137,21 @@ export enum EventMetadataKey {
   // Logs the tool use token count of the API call.
   GEMINI_CLI_API_RESPONSE_TOOL_TOKEN_COUNT = 29,
 
+  // Logs the token count for system instructions.
+  GEMINI_CLI_API_RESPONSE_CONTEXT_BREAKDOWN_SYSTEM_INSTRUCTIONS = 167,
+
+  // Logs the token count for tool definitions.
+  GEMINI_CLI_API_RESPONSE_CONTEXT_BREAKDOWN_TOOL_DEFINITIONS = 168,
+
+  // Logs the token count for conversation history.
+  GEMINI_CLI_API_RESPONSE_CONTEXT_BREAKDOWN_HISTORY = 169,
+
+  // Logs the token count for tool calls (JSON map of tool name to tokens).
+  GEMINI_CLI_API_RESPONSE_CONTEXT_BREAKDOWN_TOOL_CALLS = 170,
+
+  // Logs the token count from MCP servers (tool definitions + tool inputs/outputs).
+  GEMINI_CLI_API_RESPONSE_CONTEXT_BREAKDOWN_MCP_SERVERS = 171,
+
   // ==========================================================================
   // GenAI API Error Event Keys
   // ===========================================================================

packages/core/src/telemetry/loggers.test.ts

@@ -24,6 +24,7 @@ import {
 import { OutputFormat } from '../output/types.js';
 import { logs } from '@opentelemetry/api-logs';
 import type { Config, GeminiCLIExtension } from '../config/config.js';
+import { ApprovalMode } from '../policy/types.js';
 import {
   logApiError,
   logApiRequest,
@@ -95,6 +96,7 @@ import {
   EVENT_HOOK_CALL,
   LlmRole,
 } from './types.js';
+import { HookType } from '../hooks/types.js';
 import * as metrics from './metrics.js';
 import { FileOperation } from './metrics.js';
 import * as sdk from './sdk.js';
@@ -1855,6 +1857,7 @@ describe('loggers', () => {
         'test-reason',
         false,
         undefined,
+        ApprovalMode.DEFAULT,
       );
 
       logModelRouting(mockConfig, event);
@@ -1889,6 +1892,7 @@ describe('loggers', () => {
         '[Score: 90 / Threshold: 80] reasoning',
         false,
         undefined,
+        ApprovalMode.DEFAULT,
         true,
         '80',
       );
@@ -1922,6 +1926,7 @@ describe('loggers', () => {
         'test-reason',
         false,
         undefined,
+        ApprovalMode.DEFAULT,
       );
 
       logModelRouting(mockConfig, event);
@@ -2327,7 +2332,7 @@ describe('loggers', () => {
     it('should log hook call event to Clearcut and OTEL', () => {
       const event = new HookCallEvent(
         'before-tool',
-        'command',
+        HookType.Command,
         '/path/to/script.sh',
         { arg: 'val' },
         150,

packages/core/src/telemetry/metrics.test.ts

@@ -27,6 +27,7 @@ import {
   TokenStorageInitializationEvent,
 } from './types.js';
 import { AgentTerminateMode } from '../agents/types.js';
+import { ApprovalMode } from '../policy/types.js';
 
 const mockCounterAddFn: Mock<
   (value: number, attributes?: Attributes, context?: Context) => void
@@ -490,6 +491,7 @@ describe('Telemetry Metrics', () => {
         'test-reason',
         false,
         undefined,
+        ApprovalMode.DEFAULT,
       );
       recordModelRoutingMetricsModule(mockConfig, event);
       expect(mockHistogramRecordFn).not.toHaveBeenCalled();
@@ -505,6 +507,7 @@ describe('Telemetry Metrics', () => {
         'test-reason',
         false,
         undefined,
+        ApprovalMode.DEFAULT,
       );
       recordModelRoutingMetricsModule(mockConfig, event);
 
@@ -516,6 +519,7 @@ describe('Telemetry Metrics', () => {
         'routing.decision_source': 'default',
         'routing.failed': false,
         'routing.reasoning': 'test-reason',
+        'routing.approval_mode': ApprovalMode.DEFAULT,
       });
       // The session counter is called once on init
       expect(mockCounterAddFn).toHaveBeenCalledTimes(1);
@@ -530,6 +534,7 @@ describe('Telemetry Metrics', () => {
         'test-reason',
         true,
         'test-error',
+        ApprovalMode.DEFAULT,
       );
       recordModelRoutingMetricsModule(mockConfig, event);
 
@@ -541,6 +546,7 @@ describe('Telemetry Metrics', () => {
         'routing.decision_source': 'Classifier',
         'routing.failed': true,
         'routing.reasoning': 'test-reason',
+        'routing.approval_mode': ApprovalMode.DEFAULT,
       });
 
       expect(mockCounterAddFn).toHaveBeenCalledTimes(2);
@@ -552,6 +558,7 @@ describe('Telemetry Metrics', () => {
         'routing.decision_source': 'Classifier',
         'routing.failed': true,
         'routing.reasoning': 'test-reason',
+        'routing.approval_mode': ApprovalMode.DEFAULT,
         'routing.error_message': 'test-error',
       });
     });

packages/core/src/telemetry/metrics.ts

@@ -863,6 +863,7 @@ export function recordModelRoutingMetrics(
     'routing.decision_model': event.decision_model,
     'routing.decision_source': event.decision_source,
     'routing.failed': event.failed,
+    'routing.approval_mode': event.approval_mode,
   };
 
   if (event.reasoning) {

packages/core/src/telemetry/sanitize.test.ts

@@ -14,6 +14,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { HookCallEvent, EVENT_HOOK_CALL } from './types.js';
+import { HookType } from '../hooks/types.js';
 import type { Config } from '../config/config.js';
 
 /**
@@ -40,7 +41,7 @@ describe('Telemetry Sanitization', () => {
       it('should create an event with all fields', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           'test-hook',
           { tool_name: 'ReadFile' },
           100,
@@ -69,7 +70,7 @@ describe('Telemetry Sanitization', () => {
       it('should create an event with minimal fields', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           'test-hook',
           { tool_name: 'ReadFile' },
           100,
@@ -90,7 +91,7 @@ describe('Telemetry Sanitization', () => {
       it('should include all fields when logPrompts is enabled', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           '/path/to/.gemini/hooks/check-secrets.sh --api-key=abc123',
           { tool_name: 'ReadFile', args: { file: 'secret.txt' } },
           100,
@@ -123,7 +124,7 @@ describe('Telemetry Sanitization', () => {
       it('should include hook_input and hook_output as JSON strings', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           'test-hook',
           { tool_name: 'ReadFile', args: { file: 'test.txt' } },
           100,
@@ -154,7 +155,7 @@ describe('Telemetry Sanitization', () => {
       it('should exclude PII-sensitive fields when logPrompts is disabled', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           '/path/to/.gemini/hooks/check-secrets.sh --api-key=abc123',
           { tool_name: 'ReadFile', args: { file: 'secret.txt' } },
           100,
@@ -232,7 +233,7 @@ describe('Telemetry Sanitization', () => {
         for (const testCase of testCases) {
           const event = new HookCallEvent(
             'BeforeTool',
-            'command',
+            HookType.Command,
             testCase.input,
             { tool_name: 'ReadFile' },
             100,
@@ -248,7 +249,7 @@ describe('Telemetry Sanitization', () => {
       it('should still include error field even when logPrompts is disabled', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           'test-hook',
           { tool_name: 'ReadFile' },
           100,
@@ -276,7 +277,7 @@ describe('Telemetry Sanitization', () => {
       it('should handle commands with multiple spaces', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           'python   script.py   --arg1   --arg2',
           {},
           100,
@@ -290,7 +291,7 @@ describe('Telemetry Sanitization', () => {
       it('should handle mixed path separators', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           '/path/to\\mixed\\separators.sh',
           {},
           100,
@@ -304,7 +305,7 @@ describe('Telemetry Sanitization', () => {
       it('should handle trailing slashes', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           '/path/to/directory/',
           {},
           100,
@@ -320,7 +321,7 @@ describe('Telemetry Sanitization', () => {
       it('should format success message correctly', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           'test-hook',
           {},
           150,
@@ -335,7 +336,7 @@ describe('Telemetry Sanitization', () => {
       it('should format failure message correctly', () => {
         const event = new HookCallEvent(
           'AfterTool',
-          'command',
+          HookType.Command,
           'validation-hook',
           {},
           75,
@@ -354,7 +355,7 @@ describe('Telemetry Sanitization', () => {
 
         const event = new HookCallEvent(
           'BeforeModel',
-          'command',
+          HookType.Command,
           '$GEMINI_PROJECT_DIR/.gemini/hooks/add-context.sh',
           {
             llm_request: {
@@ -394,7 +395,7 @@ describe('Telemetry Sanitization', () => {
 
         const event = new HookCallEvent(
           'BeforeModel',
-          'command',
+          HookType.Command,
           '$GEMINI_PROJECT_DIR/.gemini/hooks/add-context.sh',
           {
             llm_request: {
@@ -438,7 +439,7 @@ describe('Telemetry Sanitization', () => {
       it('should sanitize commands with API keys', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           'curl https://api.example.com -H "Authorization: Bearer sk-abc123xyz"',
           {},
           100,
@@ -452,7 +453,7 @@ describe('Telemetry Sanitization', () => {
       it('should sanitize commands with database credentials', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           'psql postgresql://user:password@localhost/db',
           {},
           100,
@@ -466,7 +467,7 @@ describe('Telemetry Sanitization', () => {
       it('should sanitize commands with environment variables containing secrets', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           'AWS_SECRET_KEY=abc123 aws s3 ls',
           {},
           100,
@@ -480,7 +481,7 @@ describe('Telemetry Sanitization', () => {
       it('should sanitize Python scripts with file paths', () => {
         const event = new HookCallEvent(
           'BeforeTool',
-          'command',
+          HookType.Command,
           'python /home/john.doe/projects/secret-scanner/scan.py --config=/etc/secrets.yml',
           {},
           100,

packages/core/src/telemetry/types.ts

@@ -43,6 +43,7 @@ import { sanitizeHookName } from './sanitize.js';
 import { getFileDiffFromResultDisplay } from '../utils/fileDiffUtils.js';
 import { LlmRole } from './llmRole.js';
 export { LlmRole };
+import type { HookType } from '../hooks/types.js';
 
 export interface BaseTelemetryEvent {
   'event.name': string;
@@ -568,6 +569,14 @@ export interface GenAIResponseDetails {
   candidates?: Candidate[];
 }
 
+export interface ContextBreakdown {
+  system_instructions: number;
+  tool_definitions: number;
+  history: number;
+  tool_calls: Record<string, number>;
+  mcp_servers: number;
+}
+
 export interface GenAIUsageDetails {
   input_token_count: number;
   output_token_count: number;
@@ -575,6 +584,7 @@ export interface GenAIUsageDetails {
   thoughts_token_count: number;
   tool_token_count: number;
   total_token_count: number;
+  context_breakdown?: ContextBreakdown;
 }
 
 export const EVENT_API_RESPONSE = 'gemini_cli.api_response';
@@ -1360,6 +1370,7 @@ export class ModelRoutingEvent implements BaseTelemetryEvent {
   error_message?: string;
   enable_numerical_routing?: boolean;
   classifier_threshold?: string;
+  approval_mode: ApprovalMode;
 
   constructor(
     decision_model: string,
@@ -1368,6 +1379,7 @@ export class ModelRoutingEvent implements BaseTelemetryEvent {
     reasoning: string | undefined,
     failed: boolean,
     error_message: string | undefined,
+    approval_mode: ApprovalMode,
     enable_numerical_routing?: boolean,
     classifier_threshold?: string,
   ) {
@@ -1379,6 +1391,7 @@ export class ModelRoutingEvent implements BaseTelemetryEvent {
     this.reasoning = reasoning;
     this.failed = failed;
     this.error_message = error_message;
+    this.approval_mode = approval_mode;
     this.enable_numerical_routing = enable_numerical_routing;
     this.classifier_threshold = classifier_threshold;
   }
@@ -1392,6 +1405,7 @@ export class ModelRoutingEvent implements BaseTelemetryEvent {
       decision_source: this.decision_source,
       routing_latency_ms: this.routing_latency_ms,
       failed: this.failed,
+      approval_mode: this.approval_mode,
     };
 
     if (this.reasoning) {
@@ -2166,7 +2180,7 @@ export class HookCallEvent implements BaseTelemetryEvent {
   'event.name': string;
   'event.timestamp': string;
   hook_event_name: string;
-  hook_type: 'command';
+  hook_type: HookType;
   hook_name: string;
   hook_input: Record<string, unknown>;
   hook_output?: Record<string, unknown>;
@@ -2179,7 +2193,7 @@ export class HookCallEvent implements BaseTelemetryEvent {
 
   constructor(
     hookEventName: string,
-    hookType: 'command',
+    hookType: HookType,
     hookName: string,
     hookInput: Record<string, unknown>,
     durationMs: number,

packages/core/src/tools/mcp-tool.ts

@@ -29,6 +29,16 @@ import type { MessageBus } from '../confirmation-bus/message-bus.js';
  */
 export const MCP_QUALIFIED_NAME_SEPARATOR = '__';
 
+/**
+ * Returns true if `name` matches the MCP qualified name format: "server__tool",
+ * i.e. exactly two non-empty parts separated by the MCP_QUALIFIED_NAME_SEPARATOR.
+ */
+export function isMcpToolName(name: string): boolean {
+  if (!name.includes(MCP_QUALIFIED_NAME_SEPARATOR)) return false;
+  const parts = name.split(MCP_QUALIFIED_NAME_SEPARATOR);
+  return parts.length === 2 && parts[0].length > 0 && parts[1].length > 0;
+}
+
 type ToolParams = Record<string, unknown>;
 
 // Discriminated union for MCP Content Blocks to ensure type safety.

packages/vscode-ide-companion/NOTICES.txt

@@ -2129,6 +2129,33 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 
+============================================================
+path-to-regexp@6.3.0
+(https://github.com/pillarjs/path-to-regexp.git)
+
+The MIT License (MIT)
+
+Copyright (c) 2014 Blake Embrey (hello@blakeembrey.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
 ============================================================
 send@1.2.1
 (No repository found)

packages/vscode-ide-companion/README.md

@@ -31,4 +31,4 @@ To use this extension, you'll need:
 # Terms of Service and Privacy Notice
 
 By installing this extension, you agree to the
-[Terms of Service](https://github.com/google-gemini/gemini-cli/blob/main/docs/tos-privacy.md).
+[Terms of Service](https://geminicli.com/docs/resources/tos-privacy/).

schemas/settings.schema.json

@@ -117,6 +117,13 @@
               "description": "The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory.",
               "markdownDescription": "The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory.\n\n- Category: `General`\n- Requires restart: `yes`",
               "type": "string"
+            },
+            "modelRouting": {
+              "title": "Plan Model Routing",
+              "description": "Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pro for the planning phase and Flash for the implementation phase.",
+              "markdownDescription": "Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pro for the planning phase and Flash for the implementation phase.\n\n- Category: `General`\n- Requires restart: `no`\n- Default: `true`",
+              "default": true,
+              "type": "boolean"
             }
           },
           "additionalProperties": false