feat(core): rename search_file_content tool to grep_search and add legacy alias

[SandyTao520]

Summary

This PR renames the search_file_content tool to grep_search and introduces a legacy aliasing mechanism to ensure backward compatibility for existing security policies, skills, and user configurations.

Details

• Tool Renaming: The primary name for the grep tool has been updated from search_file_content to grep_search across the codebase, including tool definitions, documentation, and policy files.
• Backward Compatibility: Added search_file_content as a legacy alias for grep_search in tool-names.ts. This allows the ToolRegistry and PolicyEngine to resolve the tool using its old name, preventing breakages in existing .toml policies or custom skills.
• Documentation Updates: Updated docs/tools/file-system.md and docs/core/subagents.md to reflect the new naming convention.
• Policy Updates: Migrated built-in policies (plan.toml, read-only.toml) to use the new grep_search name.
• Test Coverage: Updated prompts.test.ts and regenerated snapshots to verify that the system prompt correctly references grep_search.

Related Issues

Related to #17263
Closes #17974

How to Validate

1. Unit Tests: Run npm test -w @google/gemini-cli-core to ensure all core logic and aliasing tests pass.
2. Policy Verification: Create a local policy using the old name search_file_content (e.g., in a .toml file) and verify that it is correctly applied to the grep_search tool.
3. Prompt Verification: Check the system prompt (e.g., via /debug prompt) to ensure it instructs the model to use grep_search.

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-cli]

Hi @SandyTao520, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[gemini-code-assist]

Summary of Changes

Hello @SandyTao520, 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 focuses on a significant refactoring effort to rename the search_file_content tool to grep_search, enhancing the clarity and consistency of tool identification within the system. A core aspect of this change is the implementation of a robust backward compatibility layer through legacy aliasing, ensuring that existing configurations and integrations are not disrupted. The update also includes comprehensive adjustments to documentation, policy files, and test suites to fully integrate the new naming convention while maintaining system stability.

Highlights

• Tool Renaming: The search_file_content tool has been officially renamed to grep_search for improved clarity and consistency across the codebase.
• Backward Compatibility: A new legacy aliasing mechanism has been introduced, mapping search_file_content to grep_search. This ensures that existing security policies, skills, and user configurations continue to function without requiring immediate updates.
• Policy Engine Enhancements: The PolicyEngine has been updated to recognize and correctly resolve tool calls made using either the current grep_search name or its legacy alias, search_file_content.
• Documentation and Policy Updates: All relevant documentation (docs/core/subagents.md, docs/tools/file-system.md) and built-in policies (plan.toml, read-only.toml) have been migrated to reflect the new grep_search name.
• Test Coverage: Unit tests have been added and updated to validate the renaming, the functionality of the new aliasing system, and the correct behavior of the policy engine with both current and legacy tool names. System prompt snapshots were also regenerated.

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. ↩

[chrstnb]

Build failed: Build process failed (no specific link errors found). Check logs for details.

[github-actions]

Size Change: +1.16 kB (0%)

Total Size: 23.6 MB

Filename	Size	Change
./bundle/gemini.js	23.6 MB	+1.16 kB (0%)

ℹ️ 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}

[gemini-code-assist]

Code Review

This pull request renames the search_file_content tool to grep_search and implements a backward-compatibility layer using legacy aliases, affecting documentation, policies, and tests. A critical security vulnerability has been identified where the aliasing logic in getToolAliases is incomplete, only handling unqualified tool names. This could allow policies defined with fully qualified legacy names (e.g., for MCP tools) to be bypassed when the tool is called by its new name. A recommendation has been provided to address this by making the aliasing logic aware of the server prefix in qualified names. Additionally, test quality needs improvement, specifically in tool-names.test.ts where tests validate a mock instead of the actual implementation, and in policy-engine.test.ts due to a fragile mock duplicating implementation logic.