feat(plan): document and validate Plan Mode policy overrides

[jerop]

• Added instructions and examples for overriding Plan Mode policies to the Plan Mode guide.
• Updated policy engine documentation to include 'plan' mode and link to override examples.
• Added a unit test to verify that user-tier policies correctly take precedence in Plan Mode.

Closes #18589
Closes #18200

[gemini-code-assist]

Summary of Changes

Hello @jerop, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the flexibility and clarity of Plan Mode by introducing comprehensive documentation and validation for policy overrides. Users can now understand how to safely customize tool access within Plan Mode, allowing for more tailored research workflows while ensuring that user-defined policies correctly supersede default restrictions.

Highlights

• Plan Mode Policy Overrides Documentation: Instructions and examples for overriding Plan Mode policies were added to the Plan Mode guide.
• Policy Engine Documentation Update: The policy engine documentation was updated to include 'plan' mode and link to override examples.
• Policy Precedence Unit Test: A unit test was added to verify that user-tier policies correctly take precedence in Plan Mode.

Changelog

• docs/cli/plan-mode.md
  • Added a new section "Customizing Policies" to the table of contents.
  • Included detailed explanations and TOML examples for overriding Plan Mode's default read-only restrictions, specifically for git status, git diff, and codebase_investigator.
  • Added a security caution regarding overriding policies and a tip for agents.
  • Linked to the Policy Engine Guide for more information.
• docs/core/policy-engine.md
  • Updated the "Approval modes" section to explicitly list and describe the plan mode as a strict, read-only environment.
  • Provided definitions for default, autoEdit, plan, and yolo modes.
• packages/core/src/policy/config.test.ts
  • Introduced a new unit test to confirm that user-tier policies can successfully override built-in Plan Mode restrictions.
  • The test specifically verifies that run_shell_command for git status and git diff, and codebase_investigator can be allowed in plan mode via user policies.

Activity

• No specific human activity (comments, reviews, etc.) has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds valuable documentation on overriding Plan Mode policies and includes a solid unit test to ensure the override mechanism works as expected. The documentation in docs/cli/plan-mode.md and docs/core/policy-engine.md is clear, with helpful examples. The new test in packages/core/src/policy/config.test.ts effectively validates that user-defined policies correctly take precedence over default Plan Mode restrictions. Overall, these changes are well-executed and enhance the functionality and test coverage of the policy engine.

[github-actions]

Size Change: -2 B (0%)

Total Size: 24.3 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	24.3 MB	-2 B (0%)
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B

_{compressed-size-action}