feat(core): add enter_plan_mode tool

[jerop]

Summary

Adds the enter_plan_mode tool, allowing the agent to switch to a restricted "Plan Mode" for researching and designing complex changes before implementation. In the initial version, we require user confirmation before switching to plan mode and we use the standard tool confirmation for this.

Details

• Implements EnterPlanModeTool in packages/core.
• Sets ApprovalMode.PLAN in the config when executed.
• Updates config.ts to register the new tool when experimental.plan is enabled.

Related Issues

Closes #16622

How to Validate

1. Enable experimental.plan in settings.
2. Trigger the tool by asking an ambiguous question or stating a need to plan (e.g., "I want to plan a new database schema").
3. Verify Confirmation Options:
   • No: Deny the request and verify the agent does not enter Plan Mode (e.g., check that implementation tools are still available).
   • Allow once: Approve the request once. Verify the agent enters Plan Mode ("Switching to Plan mode").
   • Allow for this session: Approve for the session. Verify subsequent entries into Plan Mode (if re-triggered) do not prompt again.
4. Verify that once in Plan Mode, the agent recognizes the restriction to read-only tools.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS

[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 introduces a significant enhancement by adding an enter_plan_mode tool, which allows the agent to switch into a specialized 'Plan Mode'. This mode is designed to facilitate safer and more structured problem-solving by limiting the agent's actions to read-only operations, ideal for researching and designing solutions without immediate implementation. The tool's availability is controlled by an experimental feature flag, and its activation includes a user confirmation step to ensure intentional transitions.

Highlights

• New Tool Introduction: Introduced the enter_plan_mode tool, enabling agents to transition into a dedicated 'Plan Mode' for complex tasks.
• Restricted Agent Behavior: When activated, Plan Mode restricts the agent to read-only tools, ensuring a safe environment for research and design before implementation.
• Configuration Integration: The new tool is registered and becomes available when the experimental.plan feature flag is enabled in the application's configuration.
• User Confirmation Workflow: A confirmation flow is implemented for entering Plan Mode, allowing users to approve, deny, or cancel the transition, providing explicit control.

Changelog

• packages/core/src/config/config.ts
  • Added an import statement for the new EnterPlanModeTool.
  • Registered EnterPlanModeTool to be available within the configuration when the experimental.plan feature is enabled.
• packages/core/src/tools/enter-plan-mode.test.ts
  • New file added, containing comprehensive unit tests for the EnterPlanModeTool.
  • Tests cover the shouldConfirmExecute method's behavior, verifying responses based on policy decisions (ASK_USER, ALLOW, DENY).
  • Tests validate the execute method's functionality, including setting ApprovalMode.PLAN and handling user cancellation scenarios.
• packages/core/src/tools/enter-plan-mode.ts
  • New file added, defining the EnterPlanModeTool and its associated EnterPlanModeInvocation logic.
  • The tool's core function is to switch the agent into ApprovalMode.PLAN, which restricts its operations to read-only actions.
  • Includes a shouldConfirmExecute method to prompt the user for confirmation before the agent enters Plan Mode.
• packages/core/src/tools/tool-names.ts
  • Added the ENTER_PLAN_MODE_TOOL_NAME constant to centralize the name of the new tool.

Activity

• The author has added/updated tests to ensure the new functionality works as expected.
• Validation of the changes has been performed on MacOS.

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 introduces the enter_plan_mode tool, a valuable feature for enabling a safer, read-only planning phase for the agent. The implementation is well-structured, follows existing patterns within the codebase, and is accompanied by thorough tests. The tool is also correctly gated behind the experimental.plan feature flag. I have one suggestion to improve the consistency and security of the content returned to the LLM, which will enhance predictability and prevent prompt injection.

[github-actions]

Size Change: +2.98 kB (+0.01%)

Total Size: 23.7 MB

Filename	Size	Change
./bundle/gemini.js	23.7 MB	+2.98 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB

_{compressed-size-action}

[abhipatel12]

LGTM with a few questions