feat(core): migrate read_file to 1-based start_line/end_line parameters

[adamfweidman]

Summary

Migrates the read_file tool from 0-based offset/limit parameters to 1-based start_line/end_line parameters. This improves precision and aligns the API with how Large Language Models naturally reason about line ranges.

Details

• API Update: Replaced offset (0-based) and limit with start_line (1-based) and end_line (1-based, inclusive) in ReadFileToolParams.
• Core Logic: Updated processSingleFileContent in fileUtils.ts to correctly handle 1-based ranges, converting them to 0-based array indices internally.
• Model Alignment: Updated tool definitions in default-legacy.ts and gemini-3.ts with revised descriptions and schemas.
• Prompting: Updated snippets.ts to guide models toward using the new parameters for large files.
• Validation: Added checks to ensure start_line >= 1, end_line >= 1, and start_line <= end_line.
• Refactoring: Removed redundant Math.max calls in utility logic and corrected minor typos in system prompts.
• Tests: Fully migrated read-file.test.ts and fileUtils.test.ts, updated snapshots, and resolved ESLint no-explicit-any violations.

Related Issues

Fixes #17542

How to Validate

1. Run core unit tests:

   npm test -w @google/gemini-cli-core -- src/tools/read-file.test.ts src/utils/fileUtils.test.ts

2. Verify all 119 tests pass and snapshots are correct.

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 @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!

[gemini-code-assist]

Summary of Changes

Hello @adamfweidman, 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 read_file tool to use 1-based start_line and end_line parameters instead of the previous 0-based offset and limit. This change aims to enhance the tool's precision and better align its API with how Large Language Models typically reason about line ranges, making it more intuitive for AI agents to interact with. The update involves modifications across tool definitions, core file processing logic, prompting instructions, and comprehensive test coverage to ensure robustness and correctness.

Highlights

• API Parameter Migration: Migrated the read_file tool's parameters from 0-based offset/limit to 1-based start_line/end_line for enhanced precision and better alignment with Large Language Model reasoning.
• Core Logic Update: Updated the processSingleFileContent function in fileUtils.ts to correctly handle the new 1-based line ranges by converting them to 0-based array indices internally.
• Tool Definition Alignment: Revised tool definitions and their schemas in default-legacy.ts and gemini-3.ts to reflect the new start_line and end_line parameters.
• Prompting Guidance Adjustment: Adjusted prompting instructions in snippets.ts to guide models toward using the new start_line and end_line parameters when reading large files.
• Input Validation: Implemented new validation checks to ensure start_line and end_line are at least 1 and that start_line does not exceed end_line.
• Testing and Refactoring: Migrated and updated all relevant unit tests (read-file.test.ts, fileUtils.test.ts) and snapshots, and performed minor refactoring by removing redundant Math.max calls and correcting typos.

Changelog

• packages/core/src/prompts/snippets.ts
  • Updated guidance for handling large files to reference start_line and end_line instead of offset and limit.
• packages/core/src/tools/snapshots/read-file.test.ts.snap
  • Updated snapshot descriptions to reflect the change from offset/limit to start_line/end_line parameters.
• packages/core/src/tools/definitions/model-family-sets/default-legacy.ts
  • Modified the read_file tool's description and parameter schema to use start_line and end_line (1-based) instead of offset and limit (0-based).
• packages/core/src/tools/definitions/model-family-sets/gemini-3.ts
  • Modified the read_file tool's description and parameter schema to use start_line and end_line (1-based) instead of offset and limit (0-based).
• packages/core/src/tools/read-file.test.ts
  • Updated tests to validate new start_line and end_line parameters, including checks for invalid input (e.g., start_line < 1, end_line < 1, start_line > end_line).
  • Migrated pagination tests to use the new 1-based line parameters.
  • Added an assertion to ensure the offset property is no longer present in the schema.
• packages/core/src/tools/read-file.ts
  • Updated ReadFileToolParams interface to use start_line and end_line instead of offset and limit.
  • Modified toolLocations to use start_line.
  • Adjusted the execute method to pass start_line and end_line to processSingleFileContent.
  • Updated truncation messages to refer to start_line and end_line.
  • Implemented new validation logic for start_line and end_line in validateParams.
• packages/core/src/utils/fileUtils.test.ts
  • Updated pagination tests to use startLine and endLine (1-based).
  • Adjusted truncation tests to reflect the new 1-based indexing and default limit behavior.
  • Corrected test descriptions to match the new parameter names.
• packages/core/src/utils/fileUtils.ts
  • Exported DEFAULT_MAX_LINES_TEXT_FILE.
  • Updated processSingleFileContent function signature to accept startLine and endLine.
  • Refactored line slicing logic to correctly handle 1-based startLine and endLine parameters, converting them to 0-based array indices.
  • Adjusted truncation detection and display messages to align with the new 1-based line numbering.

Activity

• The author provided a detailed summary of changes, including API updates, core logic modifications, model alignment, prompting adjustments, validation, refactoring, and test migration.
• The author included a 'How to Validate' section with specific test commands for read-file.test.ts and fileUtils.test.ts.
• The author completed the pre-merge checklist, indicating tests were added/updated and breaking changes were noted.
• The author 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. ↩

[github-actions]

Size Change: +83 B (0%)

Total Size: 24.5 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	24.5 MB	+83 B (0%)
./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}

[gemini-code-assist]

Code Review

The pull request successfully migrates the read_file tool to use 1-based start_line and end_line parameters, which improves alignment with how Large Language Models naturally reason about line ranges. The core logic in fileUtils.ts and the tool definitions have been updated correctly to handle these new parameters. However, a regression was identified in the line-slicing logic where the default safety limit is no longer applied if start_line is provided without an accompanying end_line. Additionally, the truncation message in the tool output has lost its helpful example for pagination, which should be restored to assist the model in subsequent calls.

[abhipatel12]

LGTM