Agent provided prompt suggestions.

evals/frugalReads.eval.ts

@@ -0,0 +1,270 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect } from 'vitest';
+import { evalTest } from './test-helper.js';
+import { READ_FILE_TOOL_NAME, EDIT_TOOL_NAME } from '@google/gemini-cli-core';
+
+describe('Frugal reads eval', () => {
+  /**
+   * Ensures that the agent is frugal in its use of context by relying
+   * primarily on ranged reads when the line number is known, and combining
+   * nearby ranges into a single contiguous read to save tool calls.
+   */
+  evalTest('ALWAYS_PASSES', {
+    name: 'should use ranged read when nearby lines are targeted',
+    files: {
+      'package.json': JSON.stringify({
+        name: 'test-project',
+        version: '1.0.0',
+        type: 'module',
+      }),
+      'eslint.config.mjs': `export default [
+        {
+          files: ["**/*.ts"],
+          rules: {
+            "no-var": "error"
+          }
+        }
+      ];`,
+      'linter_mess.ts': (() => {
+        const lines = [];
+        for (let i = 0; i < 1000; i++) {
+          if (i === 500 || i === 510 || i === 520) {
+            lines.push(`var oldVar${i} = "needs fix";`);
+          } else {
+            lines.push(`const goodVar${i} = "clean";`);
+          }
+        }
+        return lines.join('\n');
+      })(),
+    },
+    prompt:
+      'Fix all linter errors in linter_mess.ts manually by editing the file. Run eslint directly (using "npx --yes eslint") to find them. Do not run the file.',
+    assert: async (rig) => {
+      const logs = rig.readToolLogs();
+
+      // Check if the agent read the whole file
+      const readCalls = logs.filter(
+        (log) => log.toolRequest?.name === READ_FILE_TOOL_NAME,
+      );
+
+      const targetFileReads = readCalls.filter((call) => {
+        const args = JSON.parse(call.toolRequest.args);
+        return args.file_path.includes('linter_mess.ts');
+      });
+
+      expect(
+        targetFileReads.length,
+        'Agent should have used read_file to check context',
+      ).toBeGreaterThan(0);
+
+      // We expect a single contiguous range covering all errors since they are near each other.
+      // Some models re-verify or read more than once, so we allow up to 4.
+      expect(
+        targetFileReads.length,
+        'Agent should have been efficient with ranged reads for near errors',
+      ).toEqual(1);
+
+      let totalLinesRead = 0;
+      const readRanges: { offset: number; limit: number }[] = [];
+
+      for (const call of targetFileReads) {
+        const args = JSON.parse(call.toolRequest.args);
+
+        expect(
+          args.limit,
+          'Agent read the entire file (missing limit) instead of using ranged read',
+        ).toBeDefined();
+
+        const limit = args.limit;
+        const offset = args.offset ?? 0;
+        totalLinesRead += limit;
+        readRanges.push({ offset, limit });
+
+        expect(args.limit, 'Agent read too many lines at once').toBeLessThan(
+          1001,
+        );
+      }
+
+      // Ranged read shoud be frugal and just enough to satisfy the task at hand.
+      expect(
+        totalLinesRead,
+        'Agent read more of the file than expected',
+      ).toBeLessThan(1000);
+
+      // Check that we read around the error lines
+      const errorLines = [500, 510, 520];
+      for (const line of errorLines) {
+        const covered = readRanges.some(
+          (range) => line >= range.offset && line < range.offset + range.limit,
+        );
+        expect(covered, `Agent should have read around line ${line}`).toBe(
+          true,
+        );
+      }
+
+      const editCalls = logs.filter(
+        (log) => log.toolRequest?.name === EDIT_TOOL_NAME,
+      );
+      const targetEditCalls = editCalls.filter((call) => {
+        const args = JSON.parse(call.toolRequest.args);
+        return args.file_path.includes('linter_mess.ts');
+      });
+      expect(
+        targetEditCalls.length,
+        'Agent should have made replacement calls on the target file',
+      ).toBeGreaterThanOrEqual(3);
+    },
+  });
+
+  /**
+   * Ensures the agent uses multiple ranged reads when the targets are far
+   * apart to avoid the need to read the whole file.
+   */
+  evalTest('ALWAYS_PASSES', {
+    name: 'should use ranged read when targets are far apart',
+    files: {
+      'package.json': JSON.stringify({
+        name: 'test-project',
+        version: '1.0.0',
+        type: 'module',
+      }),
+      'eslint.config.mjs': `export default [
+        {
+          files: ["**/*.ts"],
+          rules: {
+            "no-var": "error"
+          }
+        }
+      ];`,
+      'far_mess.ts': (() => {
+        const lines = [];
+        for (let i = 0; i < 1000; i++) {
+          if (i === 100 || i === 900) {
+            lines.push(`var oldVar${i} = "needs fix";`);
+          } else {
+            lines.push(`const goodVar${i} = "clean";`);
+          }
+        }
+        return lines.join('\n');
+      })(),
+    },
+    prompt:
+      'Fix all linter errors in far_mess.ts manually by editing the file. Run eslint directly (using "npx --yes eslint") to find them. Do not run the file.',
+    assert: async (rig) => {
+      const logs = rig.readToolLogs();
+
+      const readCalls = logs.filter(
+        (log) => log.toolRequest?.name === READ_FILE_TOOL_NAME,
+      );
+
+      const targetFileReads = readCalls.filter((call) => {
+        const args = JSON.parse(call.toolRequest.args);
+        return args.file_path.includes('far_mess.ts');
+      });
+
+      // The agent should use ranged reads to be frugal with context tokens,
+      // even if it requires multiple calls for far-apart errors.
+      expect(
+        targetFileReads.length,
+        'Agent should have used read_file to check context',
+      ).toBeGreaterThan(0);
+
+      // We allow multiple calls since the errors are far apart.
+      expect(
+        targetFileReads.length,
+        'Agent should have used separate reads for far apart errors',
+      ).toBeLessThanOrEqual(4);
+
+      for (const call of targetFileReads) {
+        const args = JSON.parse(call.toolRequest.args);
+        expect(
+          args.limit,
+          'Agent should have used ranged read (limit) to save tokens',
+        ).toBeDefined();
+      }
+    },
+  });
+
+  /**
+   * Validates that the agent reads the entire file if there are lots of matches
+   * (e.g.: 10), as it's more efficient than many small ranged reads.
+   */
+  evalTest('ALWAYS_PASSES', {
+    name: 'should read the entire file when there are many matches',
+    files: {
+      'package.json': JSON.stringify({
+        name: 'test-project',
+        version: '1.0.0',
+        type: 'module',
+      }),
+      'eslint.config.mjs': `export default [
+        {
+          files: ["**/*.ts"],
+          rules: {
+            "no-var": "error"
+          }
+        }
+      ];`,
+      'many_mess.ts': (() => {
+        const lines = [];
+        for (let i = 0; i < 1000; i++) {
+          if (i % 100 === 0) {
+            lines.push(`var oldVar${i} = "needs fix";`);
+          } else {
+            lines.push(`const goodVar${i} = "clean";`);
+          }
+        }
+        return lines.join('\n');
+      })(),
+    },
+    prompt:
+      'Fix all linter errors in many_mess.ts manually by editing the file. Run eslint directly (using "npx --yes eslint") to find them. Do not run the file.',
+    assert: async (rig) => {
+      const logs = rig.readToolLogs();
+
+      const readCalls = logs.filter(
+        (log) => log.toolRequest?.name === READ_FILE_TOOL_NAME,
+      );
+
+      const targetFileReads = readCalls.filter((call) => {
+        const args = JSON.parse(call.toolRequest.args);
+        return args.file_path.includes('many_mess.ts');
+      });
+
+      expect(
+        targetFileReads.length,
+        'Agent should have used read_file to check context',
+      ).toBeGreaterThan(0);
+
+      // In this case, we expect the agent to realize there are many scattered errors
+      // and just read the whole file to be efficient with tool calls.
+      const readEntireFile = targetFileReads.some((call) => {
+        const args = JSON.parse(call.toolRequest.args);
+        return args.limit === undefined;
+      });
+
+      expect(
+        readEntireFile,
+        'Agent should have read the entire file because of the high number of scattered matches',
+      ).toBe(true);
+
+      // Check that the agent actually fixed the errors
+      const editCalls = logs.filter(
+        (log) => log.toolRequest?.name === EDIT_TOOL_NAME,
+      );
+      const targetEditCalls = editCalls.filter((call) => {
+        const args = JSON.parse(call.toolRequest.args);
+        return args.file_path.includes('many_mess.ts');
+      });
+      expect(
+        targetEditCalls.length,
+        'Agent should have made replacement calls on the target file',
+      ).toBeGreaterThanOrEqual(1);
+    },
+  });
+});

evals/frugalSearch.eval.ts

@@ -25,7 +25,7 @@ describe('Frugal Search', () => {
     return args;
   };
 
-  evalTest('USUALLY_PASSES', {
+  evalTest('ALWAYS_PASSES', {
     name: 'should use targeted search with limit',
     prompt: 'find me a sample usage of path.resolve() in the codebase',
     files: {
@@ -128,17 +128,79 @@ describe('Frugal Search', () => {
           grepParams.map((p) => p.total_max_matches),
         )}`,
       ).toBe(true);
+    },
+  });
+
+  /**
+   * Ensure that the agent makes use of either grep or ranged reads in fulfilling this task.
+   * The task is specifically phrased to not evoke "view" or "search" specifically because
+   * the model implicitly understands that such tasks are searches. This covers the case of
+   * an unexpectedly large file benefitting from frugal approaches to viewing, like grep, or
+   * ranged reads.
+   */
+  evalTest('ALWAYS_PASSES', {
+    name: 'should use grep or ranged read for large files',
+    prompt: 'What year was legacy_processor.ts written?',
+    files: {
+      'src/utils.ts': 'export const add = (a, b) => a + b;',
+      'src/types.ts': 'export type ID = string;',
+      'src/legacy_processor.ts': [
+        '// Copyright 2005 Legacy Systems Inc.',
+        ...Array.from(
+          { length: 5000 },
+          (_, i) =>
+            `// Legacy code block ${i} - strictly preserved for backward compatibility`,
+        ),
+      ].join('\\n'),
+      'README.md': '# Project documentation',
+    },
+    assert: async (rig) => {
+      const toolCalls = rig.readToolLogs();
+      const getParams = (call: any) => {
+        let args = call.toolRequest.args;
+        if (typeof args === 'string') {
+          try {
+            args = JSON.parse(args);
+          } catch (e) {
+            // Ignore parse errors
+          }
+        }
+        return args;
+      };
+
+      // Check for wasteful full file reads
+      const fullReads = toolCalls.filter((call) => {
+        if (call.toolRequest.name !== 'read_file') return false;
+        const args = getParams(call);
+        return (
+          args.file_path === 'src/legacy_processor.ts' &&
+          (args.limit === undefined || args.limit === null)
+        );
+      });
 
-      const hasMaxMatchesPerFileLimit = grepParams.some(
-        (p) =>
-          p.max_matches_per_file !== undefined && p.max_matches_per_file <= 5,
-      );
       expect(
-        hasMaxMatchesPerFileLimit,
-        `Expected agent to use a small max_matches_per_file (<= 5) for a sample usage request. Actual values: ${JSON.stringify(
-          grepParams.map((p) => p.max_matches_per_file),
-        )}`,
-      ).toBe(true);
+        fullReads.length,
+        'Agent should not attempt to read the entire large file at once',
+      ).toBe(0);
+
+      // Check that it actually tried to find it using appropriate tools
+      const validAttempts = toolCalls.filter((call) => {
+        const args = getParams(call);
+        if (call.toolRequest.name === 'grep_search') {
+          return true;
+        }
+
+        if (
+          call.toolRequest.name === 'read_file' &&
+          args.file_path === 'src/legacy_processor.ts' &&
+          args.limit !== undefined
+        ) {
+          return true;
+        }
+        return false;
+      });
+
+      expect(validAttempts.length).toBeGreaterThan(0);
     },
   });
 });

packages/core/src/core/__snapshots__/prompts.test.ts.snap

@@ -520,8 +520,10 @@ exports[`Core System Prompt (prompts.ts) > should append userMemory with separat
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -651,8 +653,10 @@ exports[`Core System Prompt (prompts.ts) > should handle CodebaseInvestigator wi
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -747,8 +751,10 @@ exports[`Core System Prompt (prompts.ts) > should handle CodebaseInvestigator wi
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1312,8 +1318,10 @@ exports[`Core System Prompt (prompts.ts) > should include available_skills with
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1439,8 +1447,10 @@ exports[`Core System Prompt (prompts.ts) > should include correct sandbox instru
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1557,8 +1567,10 @@ exports[`Core System Prompt (prompts.ts) > should include correct sandbox instru
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1675,8 +1687,10 @@ exports[`Core System Prompt (prompts.ts) > should include correct sandbox instru
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1789,8 +1803,10 @@ exports[`Core System Prompt (prompts.ts) > should include planning phase suggest
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -1903,8 +1919,10 @@ exports[`Core System Prompt (prompts.ts) > should include sub-agents in XML for
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -2256,8 +2274,10 @@ exports[`Core System Prompt (prompts.ts) > should return the base prompt when us
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -2370,8 +2390,10 @@ exports[`Core System Prompt (prompts.ts) > should return the base prompt when us
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -2595,8 +2617,10 @@ exports[`Core System Prompt (prompts.ts) > should use chatty system prompt for p
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.
@@ -2709,8 +2733,10 @@ exports[`Core System Prompt (prompts.ts) > should use chatty system prompt for p
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
 ## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
+- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results by explicitly setting \`total_max_matches\` or \`max_matches_per_file\`, especially during the research phase.
 - For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+- Limit unnecessary context consumption from file reads by using grep_search (configured with \`max_matches_per_file\`) to search large files (> 1kb) or read_file with the desired offset and limit.
+- If the file is small, prefer reading the whole thing over "scrolling" through it by reading ranges repeatedly.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in \`GEMINI.md\` files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.

packages/core/src/prompts/snippets.ts

@@ -164,9 +164,15 @@ export function renderCoreMandates(options?: CoreMandatesOptions): string {
 - **Credential Protection:** Never log, print, or commit secrets, API keys, or sensitive credentials. Rigorously protect \`.env\` files, \`.git\`, and system configuration folders.
 - **Source Control:** Do not stage or commit changes unless specifically requested by the user.
 
-## Context Efficiency:
-- Always scope and limit your searches to avoid context window exhaustion and ensure high-signal results. Use include to target relevant files and strictly limit results using total_max_matches and max_matches_per_file, especially during the research phase.
-- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+## Context Efficiency & Research Decisiveness:
+  - **Primary Discovery:** Utilize \`grep_search\` as your primary investigative tool to pinpoint specific lines and anchor points before using \`read_file\`.
+  - **Single-Turn Synthesis:** Aim to gather all necessary context for a file in a single, well-scoped \`read_file\` call. Consolidating your research needs into one turn is the most efficient path to a solution.
+  - **Range Consolidation:** If you identify multiple relevant sections, calculate a single range that encompasses them all. Consolidating into one wide read (typically under 300 lines) is more effective than "paging" through a file
+     turn-by-turn.
+  - **Strategic Buffering:** When preparing an edit, request a range that provides approximately 10-15 lines of context above and below your target. This ensures the \`replace\` tool has the stable, unique markers required to succeed in one
+     attempt.
+  - **Edit Confirmation:** Rely on the "Success" output of your editing tools. Proceed directly to behavioral validation (running tests) after a successful modification, as test results provide the most accurate verification of the file's
+     state.
 
 ## Engineering Standards
 - **Contextual Precedence:** Instructions found in ${formattedFilenames} files are foundational mandates. They take absolute precedence over the general workflows and tool defaults described in this system prompt.

packages/core/src/tools/ls.test.ts

@@ -235,8 +235,8 @@ describe('LSTool', () => {
 
       expect(entries[0]).toBe('[DIR] x-dir');
       expect(entries[1]).toBe('[DIR] y-dir');
-      expect(entries[2]).toBe('a-file.txt');
-      expect(entries[3]).toBe('b-file.txt');
+      expect(entries[2]).toBe('a-file.txt (8 bytes)');
+      expect(entries[3]).toBe('b-file.txt (8 bytes)');
     });
 
     it('should handle permission errors gracefully', async () => {

packages/core/src/tools/ls.ts

@@ -241,7 +241,12 @@ class LSToolInvocation extends BaseToolInvocation<LSToolParams, ToolResult> {
 
       // Create formatted content for LLM
       const directoryContent = entries
-        .map((entry) => `${entry.isDirectory ? '[DIR] ' : ''}${entry.name}`)
+        .map((entry) => {
+          if (entry.isDirectory) {
+            return `[DIR] ${entry.name}`;
+          }
+          return `${entry.name} (${entry.size} bytes)`;
+        })
         .join('\n');
 
       let resultMessage = `Directory listing for ${resolvedDirPath}:\n${directoryContent}`;