Repository navigation
feat(tools): implement tactful extraction for token efficiency - #18924
adamfweidman wants to merge 10 commits into
Conversation
- Use dynamic schema to hide offset/limit for 3.0 models. - Update truncation guidance for 3.0 models to encourage shell tools. - Maintain legacy behavior for 2.5 models. - Add TODO for signature cleanup in fileUtils.ts.
- Restore precision to read_file with 1-based start_line and end_line for Gemini 3. - Update tool descriptions to establish extraction hierarchy (rg > shell/sed > read_file). - Codify 'Be Token-Frugal' mandate in system prompt snippets. - Refine research workflow to allow context-based validation via search tools. - Update unit tests and verified build integrity.
- Centralized tool definitions in coreTools.ts with improved surgical extraction guidance. - Resolved conflicts in read-file.ts, shell.ts, glob.ts, and ripGrep.ts. - Merged Search Frugality instructions from main with our Token Frugality mandate. - Updated unit tests and snapshots.
This PR optimizes how the agent explores and reads code by providing precision extraction tools and mandating token frugality. Key Changes: - Restore precision to read_file with 1-based start_line and end_line for Gemini 3. - Update tool descriptions to establish extraction hierarchy (rg > shell/sed > read_file). - Codify 'Be Token-Frugal' mandate in system prompt snippets. - Refine research workflow to allow context-based validation via search tools. - Merge latest main improvements including Search Frugality parameters. - Update unit tests and verified build integrity.
|
Hi @adamfweidman, 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! |
|
Size Change: +7.48 kB (+0.03%) Total Size: 24.3 MB
ℹ️ View Unchanged
|
Summary of ChangesHello @adamfweidman, I'm Gemini Code Assist1! 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 'Tactful Extraction' rework aimed at optimizing token efficiency by shifting from broad file reads to more surgical and targeted data exploration. The changes involve refining existing tools and updating system prompts to guide models towards more frugal token consumption, ultimately leading to substantial cost savings and reduced context size without compromising performance. Highlights
Changelog
Activity
Using Gemini Code AssistThe 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
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 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
|
![gemini-code-assist[bot]](/web-api/iframe-proxy?url=https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a "Tactful Extraction" rework to improve token efficiency, which is a great initiative. The changes are well-aligned with this goal, promoting more surgical use of tools like grep_search and run_shell_command with sed, and updating the read_file tool to support 1-based line ranges for newer models. The system prompts have been updated effectively to guide the model towards more token-frugal behavior. The comment regarding a minor regression in the detail of a tool description is valid and should be addressed. Overall, this is a solid improvement.
gemini-cli
Bot
added
area/agent
|
|
||
| IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION. | ||
|
|
||
| - Always prefer command flags that reduce output verbosity when using ${formatToolName( |
There was a problem hiding this comment.
It'd be great to test these lines independently. I wonder how much of the context savings is just this line, for example, particularly if it's reducing the size of build output.
| )}. | ||
| - Aim to minimize tool output tokens while still capturing necessary information. | ||
| - If a command is expected to produce a lot of output, use quiet or silent flags where available and appropriate. | ||
| - Always consider the trade-off between output verbosity and the need for information. If a command's full output is essential for understanding the result, avoid overly aggressive quieting that might obscure important details. |
There was a problem hiding this comment.
Consider adding a behavioral eval test that demonstrates the effectiveness of lines like this. The hope is this keeps our prompt focused and minimal.
| - Aim to minimize tool output tokens while still capturing necessary information. | ||
| - If a command is expected to produce a lot of output, use quiet or silent flags where available and appropriate. | ||
| - Always consider the trade-off between output verbosity and the need for information. If a command's full output is essential for understanding the result, avoid overly aggressive quieting that might obscure important details. | ||
| - If a command does not have quiet/silent flags or for commands with potentially long output that may not be useful, redirect stdout and stderr to temp files in the project's temporary directory. For example: 'command > <temp_dir>/out.log 2> <temp_dir>/err.log'. |
There was a problem hiding this comment.
I think there's a general feature being implemented that redirects shell outputs that are too long. Is it preferable to use that? I think by redirecting in the shell we lose the ability to have live updates in the UX.
| Background PIDs: Only included if background processes were started. | ||
| Process Group PGID: Only included if available." | ||
| Process Group PGID: Only included if available. | ||
| **This is the preferred tool for surgical extraction of code blocks.** Use \`sed -n '50,100p' file\` for ranges, or \`sed -n '/class X/,/^}/p' file\` for semantic blocks. Avoid 'cat' on large files to prevent context bloat. Output is limited to the last 2,000 lines. |
There was a problem hiding this comment.
This is another one that'd be great to test in isolation. I also wonder if we can achieve the same result without causing more approval prompts by exposing params to do the equivalent on a tool.
| "Optional: For text files, maximum number of lines to read. Use with 'offset' to paginate through large files. If omitted, reads the entire file (if feasible, up to a default limit).", | ||
| type: 'number', | ||
| }, | ||
| start_line: { |
There was a problem hiding this comment.
Let's just rename these for Gemini 3 models.
- Integrate model-specific tool optimizations (isGemini3) into read-file and snippets. - Reconcile prompt snippets with main's Context Efficiency mandates and experiment's discovery guidelines. - Adopt main's refactored tool definition structure while retaining experiment's surgical extraction guidance. - Resolve pagination and truncation logic in file utilities. - Update snapshots and verify with full test suite. - Fix ESLint errors in prompt provider and snippets.
- Integrate model-specific tool optimizations (isGemini3) into read-file and snippets. - Reconcile prompt snippets with main's Context Efficiency mandates and experiment's discovery guidelines. - Adopt main's refactored tool definition structure while retaining experiment's surgical extraction guidance. - Resolve pagination and truncation logic in file utilities. - Update snapshots and verify with full test suite. - Align prompt provider and snippets with main's code style and linting patterns.
3 participants
Summary
This PR implements the "Tactful Extraction" rework, designed to optimize token efficiency. By moving away from broad "firehose" file reads toward surgical, targeted exploration, we successfully reduced overall token consumption by 6.9% while matching the main branch resolution baseline.
Details
1. Tool & API Rework
read_file(Precision API): Swapped to a 1-basedstart_line/end_lineAPI for Gemini 3 models. This removes the 0-based offset mental math and aligns with standard Unix output (e.g.,grep -n).run_shell_command(The Scalpel): Explicitly framed as the preferred tool for surgical extraction. Centralized guidance incoreTools.tsnow includes specificsedregex examples for semantic block extraction (e.g., class/function boundaries).grep_search(Primary Discovery): Re-framed as the primary scout. Encouraged using context flags (before/after) to "find and read" in a single turn, reducing the need for follow-upread_filecalls.2. System Prompt & Efficiency Mandate
snippets.tsexplaining that context persists and that unnecessary early-trial bloat carries a permanent "tax" on every turn.ResearchandUnderstandlifecycle steps to favor context-based search and precise range reads over broad, assumption-based reads.3. Integrated Frugal Search
main(PR Update prompt and grep tool definition to limit context size #18780), combining the newexclude_pattern,names_only, andmax_matches_per_fileparameters with our surgical extraction guidance.📊 Performance Impact (vs.
main)mainbaseline resolution.Related Issues
Fixes #17545
Fixes #17542
How to Validate
npm test -w @google/gemini-cli-coreto verify 1-based range logic and snapshot accuracy.npm run buildto verify full workspace integrity.sed -n '/pattern1/,/pattern2/p'for semantic block extraction.Pre-Merge Checklist