From 6d3437badb7caa12d387c4bdd21b4cd1da36fe13 Mon Sep 17 00:00:00 2001 From: Jerop Kipruto Date: Wed, 25 Mar 2026 15:37:48 -0400 Subject: [PATCH] docs: clarify policy requirement for `general.plan.directory` in settings schema (#23784) --- docs/cli/settings.md | 2 +- docs/reference/configuration.md | 3 ++- packages/cli/src/config/settingsSchema.ts | 2 +- schemas/settings.schema.json | 4 ++-- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/cli/settings.md b/docs/cli/settings.md index 2a4b5963ce..2792606959 100644 --- a/docs/cli/settings.md +++ b/docs/cli/settings.md @@ -30,7 +30,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 mode (auto-approve all actions) can only be enabled via command line (--yolo or --approval-mode=yolo). | `"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` | +| Plan Directory | `general.plan.directory` | The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory. A custom directory requires a policy to allow write access in Plan Mode. | `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` | | Retry Fetch Errors | `general.retryFetchErrors` | Retry on "exception TypeError: fetch failed sending request" errors. | `true` | | Max Chat Model Attempts | `general.maxAttempts` | Maximum number of attempts for requests to the main chat model. Cannot exceed 10. | `10` | diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 869b8a0e21..5c4ef25544 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -143,7 +143,8 @@ their corresponding top-level category object in your `settings.json` file. - **`general.plan.directory`** (string): - **Description:** The directory where planning artifacts are stored. If not - specified, defaults to the system temporary directory. + specified, defaults to the system temporary directory. A custom directory + requires a policy to allow write access in Plan Mode. - **Default:** `undefined` - **Requires restart:** Yes diff --git a/packages/cli/src/config/settingsSchema.ts b/packages/cli/src/config/settingsSchema.ts index c0f2395110..891e383bc9 100644 --- a/packages/cli/src/config/settingsSchema.ts +++ b/packages/cli/src/config/settingsSchema.ts @@ -300,7 +300,7 @@ const SETTINGS_SCHEMA = { requiresRestart: true, default: undefined as string | undefined, description: - 'The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory.', + 'The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory. A custom directory requires a policy to allow write access in Plan Mode.', showInDialog: true, }, modelRouting: { diff --git a/schemas/settings.schema.json b/schemas/settings.schema.json index f023d17dd7..b84e660262 100644 --- a/schemas/settings.schema.json +++ b/schemas/settings.schema.json @@ -124,8 +124,8 @@ "properties": { "directory": { "title": "Plan Directory", - "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`", + "description": "The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory. A custom directory requires a policy to allow write access in Plan Mode.", + "markdownDescription": "The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory. A custom directory requires a policy to allow write access in Plan Mode.\n\n- Category: `General`\n- Requires restart: `yes`", "type": "string" }, "modelRouting": {