feat: move shell efficiency guidelines to tool description

[NTaylorMullen]

Summary

Moves shell efficiency guidelines from the general system prompt to the run_shell_command tool description for modern models (Gemini 3.0+). This ensures instructions are provided contextually when the model considers tool use and addresses naming inconsistencies.

Details

• Relocates "Quiet Flags" and "Pagination" instructions to ShellTool description.
• Guidelines are conditionally included based on tools.shell.enableShellOutputEfficiency setting.
• Retains instructions in snippets.legacy.ts for Gemini 2.5 compatibility.
• Adds a new behavioral evaluation suite to verify efficiency best practices.

Related Issues

N/A

How to Validate

1. Run unit tests for core: npm test -w @google/gemini-cli-core
2. Run new behavioral evaluations: RUN_EVALS=1 npx vitest run -c evals/vitest.config.ts evals/shell-efficiency.eval.ts
3. Verify tool description in prompt by running with GEMINI_DEBUG=true and inspecting the generated system prompt for the Shell tool.

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 @NTaylorMullen, 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 refactors the delivery mechanism for shell command efficiency guidelines within the system. Instead of being part of the general prompt, these instructions are now embedded directly within the run_shell_command tool's description. This change aims to make the guidance more relevant and timely for the model when it's about to execute a shell command, improving the model's adherence to best practices for output efficiency while ensuring compatibility across different model versions and configurable behavior.

Highlights

• Contextual Shell Efficiency Guidelines: Shell efficiency guidelines (e.g., quiet flags, pagination) have been moved from the general system prompt to the specific run_shell_command tool description. This ensures these instructions are provided contextually when the model considers using the shell tool, particularly for modern models (Gemini 3.0+).
• Conditional Inclusion: The inclusion of these efficiency guidelines is now conditional, based on the tools.shell.enableShellOutputEfficiency setting, allowing for greater control over prompt content.
• Legacy Compatibility: Instructions for older models (Gemini 2.5) are retained in snippets.legacy.ts to maintain backward compatibility.
• New Behavioral Evaluations: A new suite of behavioral evaluations (evals/shell-efficiency.eval.ts) has been added to verify that the agent correctly applies efficiency best practices (like using --silent for npm install or --no-pager for git) and correctly omits them when the feature is disabled.

Changelog

• evals/shell-efficiency.eval.ts
  • Added a new file containing behavioral evaluation tests for shell efficiency. These tests verify that the agent uses appropriate flags like --silent or --quiet for package installations and --no-pager for git commands, and also confirms that these flags are not used when the efficiency setting is disabled.
• packages/core/src/core/snapshots/prompts.test.ts.snap
  • Removed shell efficiency guidelines from various prompt snapshots, reflecting their relocation from the general system prompt.
• packages/core/src/core/prompts.test.ts
  • Removed tests that previously checked for platform-specific shell efficiency commands within the core system prompt, as these guidelines are no longer part of the general prompt.
• packages/core/src/prompts/snippets.legacy.ts
  • Adjusted formatting within renderOperationalGuidelines to ensure shellEfficiencyGuidelines are still correctly rendered for legacy prompt snippets, preserving Gemini 2.5 compatibility.
• packages/core/src/prompts/snippets.ts
  • Removed the enableShellEfficiency property from the OperationalGuidelinesOptions interface.
  • Removed the shellEfficiencyGuidelines function and its invocation from the renderOperationalGuidelines function, as these guidelines are now managed directly within the shell tool's description.
• packages/core/src/tools/snapshots/shell.test.ts.snap
  • Updated snapshots to include the new 'Efficiency Guidelines' section within the ShellTool description for both non-Windows and Windows environments.
• packages/core/src/tools/shell.test.ts
  • Updated the mock configuration to include getEnableShellOutputEfficiency.
  • Added a new test case to verify that efficiency guidelines are correctly omitted from the ShellTool description when enableShellOutputEfficiency is set to false.
• packages/core/src/tools/shell.ts
  • Modified the getShellToolDescription function to accept an additional enableEfficiency boolean parameter.
  • Implemented conditional rendering of 'Efficiency Guidelines' within the shell tool's description based on the enableEfficiency parameter.
  • Updated the ShellTool constructor to pass the result of config.getEnableShellOutputEfficiency() to the getShellToolDescription function.

Activity

• NTaylorMullen initiated this pull request to improve how shell efficiency guidelines are provided to models.
• The PR includes a detailed summary and specific changes, indicating a thorough approach to the refactoring.
• Validation steps are provided, including running core unit tests and new behavioral evaluations, suggesting a focus on correctness and functionality.
• The pre-merge checklist shows that relevant documentation and tests have been updated, and validation 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 effectively moves the shell efficiency guidelines from the general system prompt to the run_shell_command tool description, which is a sensible change for providing contextual instructions to the model. The addition of a new behavioral evaluation suite to verify these efficiency best practices is a great way to ensure the change has the intended effect. The implementation looks solid. I've left one comment regarding code duplication in the new test file to improve its maintainability and ensure consistent handling of toolRequest.args.

[github-actions]

Size Change: +57 B (0%)

Total Size: 23.9 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	23.8 MB	+57 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}

[abhipatel12]

LGTM! One question about following up with xml normalization