feat(plan): support configuring custom plans storage directory (#19577)

Author: jerop

docs/cli/plan-mode.md

@@ -127,6 +127,47 @@ To use a skill in Plan Mode, you can explicitly ask the agent to "use the
 [skill-name] skill to plan..." or the agent may autonomously activate it based
 on the task description.
 
+### Custom Plan Directory and Policies
+
+By default, planning artifacts are stored in a managed temporary directory
+outside your project: `~/.gemini/tmp/<project>/<session-id>/plans/`.
+
+You can configure a custom directory for plans in your `settings.json`. For
+example, to store plans in a `.gemini/plans` directory within your project:
+
+```json
+{
+  "general": {
+    "plan": {
+      "directory": ".gemini/plans"
+    }
+  }
+}
+```
+
+To maintain the safety of Plan Mode, user-configured paths for the plans
+directory are restricted to the project root. This ensures that custom planning
+locations defined within a project's workspace cannot be used to escape and
+overwrite sensitive files elsewhere. Any user-configured directory must reside
+within the project boundary.
+
+Because Plan Mode is read-only by default, using a custom directory requires
+updating your [Policy Engine] configurations to allow `write_file` and `replace`
+in that specific location. For example, to allow writing to the `.gemini/plans`
+directory within your project, create a policy file at
+`~/.gemini/policies/plan-custom-directory.toml`:
+
+```toml
+[[rule]]
+toolName = ["write_file", "replace"]
+decision = "allow"
+priority = 100
+modes = ["plan"]
+# Adjust the pattern to match your custom directory.
+# This example matches any .md file in a .gemini/plans directory within the project.
+argsPattern = "\"file_path\":\".*\\\\.gemini/plans/.*\\\\.md\""
+```
+
 ### Customizing Policies
 
 Plan Mode is designed to be read-only by default to ensure safety during the

docs/cli/settings.md

@@ -28,6 +28,7 @@ they appear in the UI.
 | Default Approval Mode    | `general.defaultApprovalMode`      | The default approval mode for tool execution. 'default' prompts for approval, 'auto_edit' auto-approves edit tools, and 'plan' is read-only mode. 'yolo' is not supported yet. | `"default"` |
 | 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` |
 | Enable Prompt Completion | `general.enablePromptCompletion`   | Enable AI-powered prompt completion suggestions while typing.                                                                                                                  | `false`     |
 | 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/get-started/configuration.md

@@ -131,6 +131,12 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `false`
   - **Requires restart:** Yes
 
+- **`general.plan.directory`** (string):
+  - **Description:** The directory where planning artifacts are stored. If not
+    specified, defaults to the system temporary directory.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
 - **`general.enablePromptCompletion`** (boolean):
   - **Description:** Enable AI-powered prompt completion suggestions while
     typing.

packages/cli/src/config/config.test.ts

@@ -21,7 +21,11 @@ import {
   type MCPServerConfig,
 } from '@google/gemini-cli-core';
 import { loadCliConfig, parseArguments, type CliArgs } from './config.js';
-import { type Settings, createTestMergedSettings } from './settings.js';
+import {
+  type Settings,
+  type MergedSettings,
+  createTestMergedSettings,
+} from './settings.js';
 import * as ServerConfig from '@google/gemini-cli-core';
 
 import { isWorkspaceTrusted } from './trustedFolders.js';
@@ -2599,6 +2603,21 @@ describe('loadCliConfig approval mode', () => {
     expect(config.getApprovalMode()).toBe(ApprovalMode.DEFAULT);
   });
 
+  it('should pass planSettings.directory from settings to config', async () => {
+    process.argv = ['node', 'script.js'];
+    const settings = createTestMergedSettings({
+      general: {
+        plan: {
+          directory: '.custom-plans',
+        },
+      },
+    } as unknown as MergedSettings);
+    const argv = await parseArguments(settings);
+    const config = await loadCliConfig(settings, 'test-session', argv);
+    const plansDir = config.storage.getPlansDir();
+    expect(plansDir).toContain('.custom-plans');
+  });
+
   // --- Untrusted Folder Scenarios ---
   describe('when folder is NOT trusted', () => {
     beforeEach(() => {

packages/cli/src/config/config.ts

@@ -814,6 +814,7 @@ export async function loadCliConfig(
     enableExtensionReloading: settings.experimental?.extensionReloading,
     enableAgents: settings.experimental?.enableAgents,
     plan: settings.experimental?.plan,
+    planSettings: settings.general.plan,
     enableEventDrivenScheduler: true,
     skillsSupport: settings.skills?.enabled ?? true,
     disabledSkills: settings.skills?.disabled,

packages/cli/src/config/settingsSchema.test.ts

@@ -107,6 +107,16 @@ describe('SettingsSchema', () => {
       ).toBe('boolean');
     });
 
+    it('should have plan nested properties', () => {
+      expect(
+        getSettingsSchema().general?.properties?.plan?.properties?.directory,
+      ).toBeDefined();
+      expect(
+        getSettingsSchema().general?.properties?.plan?.properties?.directory
+          .type,
+      ).toBe('string');
+    });
+
     it('should have fileFiltering nested properties', () => {
       expect(
         getSettingsSchema().context.properties.fileFiltering.properties

packages/cli/src/config/settingsSchema.ts

@@ -266,6 +266,27 @@ const SETTINGS_SCHEMA = {
           },
         },
       },
+      plan: {
+        type: 'object',
+        label: 'Plan',
+        category: 'General',
+        requiresRestart: true,
+        default: {},
+        description: 'Planning features configuration.',
+        showInDialog: false,
+        properties: {
+          directory: {
+            type: 'string',
+            label: 'Plan Directory',
+            category: 'General',
+            requiresRestart: true,
+            default: undefined as string | undefined,
+            description:
+              'The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory.',
+            showInDialog: true,
+          },
+        },
+      },
       enablePromptCompletion: {
         type: 'boolean',
         label: 'Enable Prompt Completion',
@@ -1313,6 +1334,7 @@ const SETTINGS_SCHEMA = {
       },
     },
   },
+
   useWriteTodos: {
     type: 'boolean',
     label: 'Use WriteTodos',

packages/cli/src/ui/commands/planCommand.test.ts

@@ -51,7 +51,7 @@ describe('planCommand', () => {
           getApprovalMode: vi.fn(),
           getFileSystemService: vi.fn(),
           storage: {
-            getProjectTempPlansDir: vi.fn().mockReturnValue('/mock/plans/dir'),
+            getPlansDir: vi.fn().mockReturnValue('/mock/plans/dir'),
           },
         },
       },

packages/cli/src/ui/commands/planCommand.ts

@@ -43,7 +43,7 @@ export const planCommand: SlashCommand = {
     try {
       const content = await processSingleFileContent(
         approvedPlanPath,
-        config.storage.getProjectTempPlansDir(),
+        config.storage.getPlansDir(),
         config.getFileSystemService(),
       );
       const fileName = path.basename(approvedPlanPath);

packages/cli/src/ui/components/ExitPlanModeDialog.test.tsx

@@ -154,7 +154,7 @@ Implement a comprehensive authentication system with multiple providers.
           getIdeMode: () => false,
           isTrustedFolder: () => true,
           storage: {
-            getProjectTempPlansDir: () => mockPlansDir,
+            getPlansDir: () => mockPlansDir,
           },
           getFileSystemService: (): FileSystemService => ({
             readTextFile: vi.fn(),
@@ -429,7 +429,7 @@ Implement a comprehensive authentication system with multiple providers.
               getIdeMode: () => false,
               isTrustedFolder: () => true,
               storage: {
-                getProjectTempPlansDir: () => mockPlansDir,
+                getPlansDir: () => mockPlansDir,
               },
               getFileSystemService: (): FileSystemService => ({
                 readTextFile: vi.fn(),