From a6b95897ad1af1f2cc66997c3915855a5f4ee73e Mon Sep 17 00:00:00 2001 From: Jerop Kipruto Date: Tue, 10 Mar 2026 09:10:17 -0400 Subject: [PATCH] docs: clarify global policy rules application in plan mode (#21864) --- docs/cli/plan-mode.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/cli/plan-mode.md b/docs/cli/plan-mode.md index 617f8492fb..c7a2f4bd4e 100644 --- a/docs/cli/plan-mode.md +++ b/docs/cli/plan-mode.md @@ -150,6 +150,27 @@ Plan Mode's default tool restrictions are managed by the but you can customize these rules by creating your own policies in your `~/.gemini/policies/` directory (Tier 2). +#### Global vs. mode-specific rules + +As described in the +[policy engine documentation](../reference/policy-engine.md#approval-modes), any +rule that does not explicitly specify `modes` is considered "always active" and +will apply to Plan Mode as well. + +If you want a rule to apply to other modes but _not_ to Plan Mode, you must +explicitly specify the target modes. For example, to allow `npm test` in default +and Auto-Edit modes but not in Plan Mode: + +```toml +[[rule]] +toolName = "run_shell_command" +commandPrefix = "npm test" +decision = "allow" +priority = 100 +# By omitting "plan", this rule will not be active in Plan Mode. +modes = ["default", "autoEdit"] +``` + #### Example: Automatically approve read-only MCP tools By default, read-only MCP tools require user confirmation in Plan Mode. You can