Merge branch 'main' into feat/browser-allowed-domain

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