feat(plan): enable built-in research subagents in plan mode

[Adib234]

Summary

Enables built-in research subagents (codebase_investigator and cli_help) in Plan Mode by default. This allows the agent to use these specialized tools for exploration and documentation lookup during the planning phase without requiring manual policy overrides.

Details

• Modified packages/core/src/policy/policies/plan.toml to include codebase_investigator and cli_help in the allowed tools list for Plan Mode.
• Updated packages/core/src/policy/toml-loader.test.ts to verify that built-in research subagents are allowed while unknown subagents remain blocked.
• Updated packages/core/src/policy/policy-engine.test.ts to use a generic subagent name in the regression test.
• Updated docs/cli/plan-mode.md to reflect that these subagents are now enabled by default and updated the example to show how to enable custom subagents.

Related Issues

Fixes #20436

How to Validate

1. Enter Plan Mode: /plan
2. Ask a question about the codebase: "Analyze how the policy engine is initialized."
3. Ask a question about Gemini CLI: "How do I configure a custom plans directory?"
4. Verify that the agent uses codebase_investigator and cli_help respectively without being blocked.
5. Run tests: npm test -w @google/gemini-cli-core -- src/policy/toml-loader.test.ts src/policy/policy-engine.test.ts

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
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello, 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 integrates built-in research subagents, codebase_investigator and cli_help, into Plan Mode by default. This change allows the agent to leverage these specialized tools for code exploration and documentation lookup during the planning phase, streamlining the process and reducing the need for manual policy adjustments. The update includes modifications to the core policy configuration, relevant documentation, and corresponding test cases to ensure proper functionality and policy enforcement.

Highlights

• Plan Mode Subagents: Enabled codebase_investigator and cli_help research subagents by default in Plan Mode to enhance planning capabilities.
• Policy Configuration: Updated packages/core/src/policy/policies/plan.toml to explicitly allow the new subagents.
• Documentation Updates: Modified docs/cli/plan-mode.md to reflect the default enablement of these subagents and clarify how to enable custom subagents.
• Test Enhancements: Adjusted packages/core/src/policy/toml-loader.test.ts and packages/core/src/policy/policy-engine.test.ts to verify correct policy behavior for both built-in and unknown subagents.

Changelog

• docs/cli/plan-mode.md
  • Added "Research Subagents" to the list of allowed tools in Plan Mode.
  • Updated the example section title from "Enable research subagents in Plan Mode" to "Enable custom subagents in Plan Mode".
  • Revised the example text to state that built-in research subagents are now enabled by default and to show how to enable custom subagents.
  • Added link definitions for codebase_investigator, cli_help, and custom subagents.
• packages/core/src/policy/policies/plan.toml
  • Added codebase_investigator and cli_help to the toolName array in the [[rule]] section for Plan Mode, explicitly allowing them.
• packages/core/src/policy/policy-engine.test.ts
  • Replaced codebase_investigator with unknown_subagent in a test case to ensure that unknown subagents are still subject to policy rules.
• packages/core/src/policy/toml-loader.test.ts
  • Updated the description of a test case to clarify it's for "unknown subagents".
  • Replaced codebase_investigator with unknown_subagent in a test setup to simulate an unknown subagent.
  • Added new assertions to verify that codebase_investigator and cli_help are explicitly allowed in Plan Mode.

Activity

• The author, Adib234, has updated the documentation and added/updated tests as part of the pre-merge checklist.
• The author has validated the changes on MacOS using npm run.

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 enables the codebase_investigator and cli_help subagents by default when in Plan Mode. The changes correctly update the plan.toml policy file to allow these tools. The associated tests have been updated to reflect this new default behavior, ensuring that unknown subagents are still correctly blocked while the newly enabled ones are permitted. The documentation has also been updated to match the new functionality. The changes are consistent and well-implemented, and I have no concerns.

[github-actions]

Size Change: -2 B (0%)

Total Size: 25.8 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	25.3 MB	-2 B (0%)
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B	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-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B

_{compressed-size-action}