docs: Add Plan Mode documentation (#18582)

docs/cli/index.md

@@ -23,6 +23,8 @@ overview of Gemini CLI, see the [main documentation page](../index.md).
 
 ## Advanced features
 
+- **[Plan mode (experimental)](./plan-mode.md):** Use a safe, read-only mode for
+  planning complex changes.
 - **[Checkpointing](./checkpointing.md):** Automatically save and restore
   snapshots of your session and files.
 - **[Enterprise configuration](./enterprise.md):** Deploy and manage Gemini CLI

docs/cli/plan-mode.md

@@ -0,0 +1,106 @@
+# Plan Mode (experimental) <!-- omit in toc -->
+
+Plan Mode is a safe, read-only mode for researching and designing complex
+changes. It prevents modifications while you research, design and plan an
+implementation strategy.
+
+> **Note: Plan Mode is currently an experimental feature.**
+>
+> Experimental features are subject to change. To use Plan Mode, enable it via
+> `/settings` (search for `Plan`) or add the following to your `settings.json`:
+>
+> ```json
+> {
+>   "experimental": {
+>     "plan": true
+>   }
+> }
+> ```
+>
+> Your feedback is invaluable as we refine this feature. If you have ideas,
+> suggestions, or encounter issues:
+>
+> - Use the `/bug` command within the CLI to file an issue.
+> - [Open an issue](https://github.com/google-gemini/gemini-cli/issues) on
+>   GitHub.
+
+- [Starting in Plan Mode](#starting-in-plan-mode)
+- [How to use Plan Mode](#how-to-use-plan-mode)
+  - [Entering Plan Mode](#entering-plan-mode)
+  - [The Planning Workflow](#the-planning-workflow)
+  - [Exiting Plan Mode](#exiting-plan-mode)
+- [Tool Restrictions](#tool-restrictions)
+
+## Starting in Plan Mode
+
+You can configure Gemini CLI to start directly in Plan Mode by default:
+
+1.  Type `/settings` in the CLI.
+2.  Search for `Approval Mode`.
+3.  Set the value to `Plan`.
+
+Other ways to start in Plan Mode:
+
+- **CLI Flag:** `gemini --approval-mode=plan`
+- **Manual Settings:** Manually update your `settings.json`:
+
+  ```json
+  {
+    "tools": {
+      "approvalMode": "plan"
+    }
+  }
+  ```
+
+## How to use Plan Mode
+
+### Entering Plan Mode
+
+You can enter Plan Mode in three ways:
+
+1.  **Keyboard Shortcut:** Press `Shift+Tab` to cycle through approval modes
+    (`Default` -> `Plan` -> `Auto-Edit`).
+2.  **Command:** Type `/plan` in the input box.
+3.  **Natural Language:** Ask the agent to "start a plan for...".
+
+### The Planning Workflow
+
+1.  **Requirements:** The agent clarifies goals using `ask_user`.
+2.  **Exploration:** The agent uses read-only tools (like [`read_file`]) to map
+    the codebase and validate assumptions.
+3.  **Planning:** A detailed plan is written to a temporary Markdown file.
+4.  **Review:** You review the plan.
+    - **Approve:** Exit Plan Mode and start implementation (switching to
+      Auto-Edit or Default approval mode).
+    - **Iterate:** Provide feedback to refine the plan.
+
+### Exiting Plan Mode
+
+To exit Plan Mode:
+
+1. **Keyboard Shortcut:** Press `Shift+Tab` to cycle to the desired mode.
+1. **Tool:** The agent calls the `exit_plan_mode` tool to present the finalized
+   plan for your approval.
+
+## Tool Restrictions
+
+Plan Mode enforces strict safety policies to prevent accidental changes.
+
+These are the only allowed tools:
+
+- **FileSystem (Read):** [`read_file`], [`list_directory`], [`glob`]
+- **Search:** [`grep_search`], [`google_web_search`]
+- **Interaction:** `ask_user`
+- **MCP Tools (Read):** Read-only [MCP tools] (e.g., `github_read_issue`,
+  `postgres_read_schema`) are allowed.
+- **Planning (Write):** [`write_file`] and [`replace`] ONLY allowed for `.md`
+  files in the `~/.gemini/tmp/<project>/plans/` directory.
+
+[`list_directory`]: ../tools/file-system.md#1-list_directory-readfolder
+[`read_file`]: ../tools/file-system.md#2-read_file-readfile
+[`grep_search`]: ../tools/file-system.md#5-grep_search-searchtext
+[`write_file`]: ../tools/file-system.md#3-write_file-writefile
+[`glob`]: ../tools/file-system.md#4-glob-findfiles
+[`google_web_search`]: ../tools/web-search.md
+[`replace`]: ../tools/file-system.md#6-replace-edit
+[MCP tools]: ../tools/mcp-server.md

docs/sidebar.json

@@ -20,6 +20,7 @@
       { "label": "Project context (GEMINI.md)", "slug": "docs/cli/gemini-md" },
       { "label": "Shell commands", "slug": "docs/tools/shell" },
       { "label": "Session management", "slug": "docs/cli/session-management" },
+      { "label": "Plan mode (experimental)", "slug": "docs/cli/plan-mode" },
       { "label": "Todos", "slug": "docs/tools/todos" },
       { "label": "Web search and fetch", "slug": "docs/tools/web-search" }
     ]

evals/test-helper.ts

@@ -49,7 +49,7 @@ export function evalTest(policy: EvalPolicy, evalCase: EvalCase) {
       // bootstrap test projects.
       const rootNodeModules = path.join(process.cwd(), 'node_modules');
       const testNodeModules = path.join(rig.testDir || '', 'node_modules');
-      if (fs.existsSync(rootNodeModules)) {
+      if (fs.existsSync(rootNodeModules) && !fs.existsSync(testNodeModules)) {
         fs.symlinkSync(rootNodeModules, testNodeModules, 'dir');
       }
 
@@ -162,7 +162,7 @@ export function evalTest(policy: EvalPolicy, evalCase: EvalCase) {
   if (policy === 'USUALLY_PASSES' && !process.env['RUN_EVALS']) {
     it.skip(evalCase.name, fn);
   } else {
-    it(evalCase.name, fn);
+    it(evalCase.name, fn, evalCase.timeout);
   }
 }
 

evals/validation_fidelity.eval.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect } from 'vitest';
+import { evalTest } from './test-helper.js';
+
+describe('validation_fidelity', () => {
+  evalTest('ALWAYS_PASSES', {
+    name: 'should perform exhaustive validation autonomously when guided by system instructions',
+    files: {
+      'src/types.ts': `
+export interface LogEntry {
+  level: 'info' | 'warn' | 'error';
+  message: string;
+}
+`,
+      'src/logger.ts': `
+import { LogEntry } from './types.js';
+
+export function formatLog(entry: LogEntry): string {
+  return \`[\${entry.level.toUpperCase()}] \${entry.message}\`;
+}
+`,
+      'src/logger.test.ts': `
+import { expect, test } from 'vitest';
+import { formatLog } from './logger.js';
+import { LogEntry } from './types.js';
+
+test('formats log correctly', () => {
+  const entry: LogEntry = { level: 'info', message: 'test message' };
+  expect(formatLog(entry)).toBe('[INFO] test message');
+});
+`,
+      'package.json': JSON.stringify({
+        name: 'test-project',
+        type: 'module',
+        scripts: {
+          test: 'vitest run',
+          build: 'tsc --noEmit',
+        },
+      }),
+      'tsconfig.json': JSON.stringify({
+        compilerOptions: {
+          target: 'ESNext',
+          module: 'ESNext',
+          moduleResolution: 'node',
+          strict: true,
+          esModuleInterop: true,
+          skipLibCheck: true,
+          forceConsistentCasingInFileNames: true,
+        },
+      }),
+    },
+    prompt:
+      "Refactor the 'LogEntry' interface in 'src/types.ts' to rename the 'message' field to 'payload'.",
+    timeout: 600000,
+    assert: async (rig) => {
+      // The goal of this eval is to see if the agent realizes it needs to update usages
+      // AND run 'npm run build' or 'tsc' autonomously to ensure project-wide structural integrity.
+
+      const toolLogs = rig.readToolLogs();
+      const shellCalls = toolLogs.filter(
+        (log) => log.toolRequest.name === 'run_shell_command',
+      );
+
+      const hasBuildOrTsc = shellCalls.some((log) => {
+        const cmd = JSON.parse(log.toolRequest.args).command.toLowerCase();
+        return (
+          cmd.includes('npm run build') ||
+          cmd.includes('tsc') ||
+          cmd.includes('typecheck') ||
+          cmd.includes('npm run verify')
+        );
+      });
+
+      expect(
+        hasBuildOrTsc,
+        'Expected the agent to autonomously run a build or type-check command to verify the refactoring',
+      ).toBe(true);
+    },
+  });
+});

evals/validation_fidelity_pre_existing_errors.eval.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect } from 'vitest';
+import { evalTest } from './test-helper.js';
+
+describe('validation_fidelity_pre_existing_errors', () => {
+  evalTest('ALWAYS_PASSES', {
+    name: 'should handle pre-existing project errors gracefully during validation',
+    files: {
+      'src/math.ts': `
+export function add(a: number, b: number): number {
+  return a + b;
+}
+`,
+      'src/index.ts': `
+import { add } from './math.js';
+console.log(add(1, 2));
+`,
+      'src/utils.ts': `
+export function multiply(a: number, b: number): number {
+  return a * c; // 'c' is not defined - PRE-EXISTING ERROR
+}
+`,
+      'package.json': JSON.stringify({
+        name: 'test-project',
+        type: 'module',
+        scripts: {
+          test: 'vitest run',
+          build: 'tsc --noEmit',
+        },
+      }),
+      'tsconfig.json': JSON.stringify({
+        compilerOptions: {
+          target: 'ESNext',
+          module: 'ESNext',
+          moduleResolution: 'node',
+          strict: true,
+          esModuleInterop: true,
+          skipLibCheck: true,
+          forceConsistentCasingInFileNames: true,
+        },
+      }),
+    },
+    prompt: "In src/math.ts, rename the 'add' function to 'sum'.",
+    timeout: 600000,
+    assert: async (rig) => {
+      const toolLogs = rig.readToolLogs();
+      const replaceCalls = toolLogs.filter(
+        (log) => log.toolRequest.name === 'replace',
+      );
+
+      // Verify it did the work in math.ts
+      const mathRefactor = replaceCalls.some((log) => {
+        const args = JSON.parse(log.toolRequest.args);
+        return (
+          args.file_path.endsWith('src/math.ts') &&
+          args.new_string.includes('sum')
+        );
+      });
+      expect(mathRefactor, 'Agent should have refactored math.ts').toBe(true);
+
+      const shellCalls = toolLogs.filter(
+        (log) => log.toolRequest.name === 'run_shell_command',
+      );
+      const ranValidation = shellCalls.some((log) => {
+        const cmd = JSON.parse(log.toolRequest.args).command.toLowerCase();
+        return cmd.includes('build') || cmd.includes('tsc');
+      });
+
+      expect(ranValidation, 'Agent should have attempted validation').toBe(
+        true,
+      );
+    },
+  });
+});