merge(read-exp): Reconcile 'afw/read-exp-v3' with 'main'

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

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

@@ -10,6 +10,9 @@ exports[`Core System Prompt (prompts.ts) > ApprovalMode in System Prompt > Appro
 - **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.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -123,6 +126,20 @@ When writing the plan file, you MUST include the following structure:
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -162,6 +179,9 @@ exports[`Core System Prompt (prompts.ts) > ApprovalMode in System Prompt > Appro
 - **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.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -281,6 +301,20 @@ An approved plan is available for this task at \`/tmp/plans/feature-x.md\`.
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -352,7 +386,7 @@ For example:
 ## Software Engineering Tasks
 When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
 1. **Understand:** Think about the user's request and the relevant codebase context. Use 'grep_search' and 'glob' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
-Use 'read_file' to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to 'read_file'.
+Use 'grep_search' with context or 'read_file' with precise ranges to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to these tools.
 2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. If the user's request implies a change but does not explicitly state it, **YOU MUST ASK** for confirmation before modifying code. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process. As part of the plan, you should use an iterative development process that includes writing unit tests to verify your changes. Use output logs or debug statements as part of this process to arrive at a solution.
 3. **Implement:** Use the available tools (e.g., 'replace', 'write_file' 'run_shell_command' ...) to act on the plan. Strictly adhere to the project's established conventions (detailed under 'Core Mandates'). Before making manual code changes, check if an ecosystem tool (like 'eslint --fix', 'prettier --write', 'go fmt', 'cargo fmt') is available in the project to perform the task automatically.
 4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. Identify the correct test commands and frameworks by examining 'README' files, build/package configuration (e.g., 'package.json'), or existing test execution patterns. NEVER assume standard test commands. When executing test commands, prefer "run once" or "CI" modes to ensure the command terminates after completion.
@@ -420,7 +454,7 @@ IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
 You are running outside of a sandbox container, directly on the user's system. For critical commands that are particularly likely to modify the user's system outside of the project directory or system temp directory, as you explain the command to the user (per the Explain Critical Commands rule above), also remind the user to consider enabling sandboxing.
 
 # Final Reminder
-Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use 'read_file' to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
+Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use appropriate search and extraction tools to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
 `;
 
 exports[`Core System Prompt (prompts.ts) > ApprovalMode in System Prompt > should include PLAN mode instructions 1`] = `
@@ -433,6 +467,9 @@ exports[`Core System Prompt (prompts.ts) > ApprovalMode in System Prompt > shoul
 - **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.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -546,6 +583,20 @@ When writing the plan file, you MUST include the following structure:
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -585,6 +636,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -657,7 +711,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -685,6 +739,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -741,6 +809,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -797,7 +868,7 @@ Use the following guidelines to optimize your search and read patterns.
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery when the task involves **complex refactoring, codebase exploration or system-wide analysis**. For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), use \`grep_search\` or \`glob\` directly in parallel. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery when the task involves **complex refactoring, codebase exploration or system-wide analysis**. For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), use \`grep_search\` or \`glob\` directly in parallel. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -824,6 +895,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -863,6 +948,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -919,7 +1007,7 @@ Use the following guidelines to optimize your search and read patterns.
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -946,6 +1034,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -1017,7 +1119,7 @@ For example:
 ## Software Engineering Tasks
 When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
 1. **Understand:** Think about the user's request and the relevant codebase context. Use 'grep_search' and 'glob' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
-Use 'read_file' to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to 'read_file'.
+Use 'grep_search' with context or 'read_file' with precise ranges to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to these tools.
 2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. If the user's request implies a change but does not explicitly state it, **YOU MUST ASK** for confirmation before modifying code. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process. As part of the plan, you should use an iterative development process that includes writing unit tests to verify your changes. Use output logs or debug statements as part of this process to arrive at a solution.
 3. **Implement:** Use the available tools (e.g., 'replace', 'write_file' 'run_shell_command' ...) to act on the plan. Strictly adhere to the project's established conventions (detailed under 'Core Mandates'). Before making manual code changes, check if an ecosystem tool (like 'eslint --fix', 'prettier --write', 'go fmt', 'cargo fmt') is available in the project to perform the task automatically.
 4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. Identify the correct test commands and frameworks by examining 'README' files, build/package configuration (e.g., 'package.json'), or existing test execution patterns. NEVER assume standard test commands. When executing test commands, prefer "run once" or "CI" modes to ensure the command terminates after completion.
@@ -1085,7 +1187,7 @@ IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
 You are running outside of a sandbox container, directly on the user's system. For critical commands that are particularly likely to modify the user's system outside of the project directory or system temp directory, as you explain the command to the user (per the Explain Critical Commands rule above), also remind the user to consider enabling sandboxing.
 
 # Final Reminder
-Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use 'read_file' to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
+Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use appropriate search and extraction tools to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
 `;
 
 exports[`Core System Prompt (prompts.ts) > should handle git instructions when isGitRepository=true 1`] = `
@@ -1130,7 +1232,7 @@ For example:
 ## Software Engineering Tasks
 When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
 1. **Understand:** Think about the user's request and the relevant codebase context. Use 'grep_search' and 'glob' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
-Use 'read_file' to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to 'read_file'.
+Use 'grep_search' with context or 'read_file' with precise ranges to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to these tools.
 2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. If the user's request implies a change but does not explicitly state it, **YOU MUST ASK** for confirmation before modifying code. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process. As part of the plan, you should use an iterative development process that includes writing unit tests to verify your changes. Use output logs or debug statements as part of this process to arrive at a solution.
 3. **Implement:** Use the available tools (e.g., 'replace', 'write_file' 'run_shell_command' ...) to act on the plan. Strictly adhere to the project's established conventions (detailed under 'Core Mandates'). Before making manual code changes, check if an ecosystem tool (like 'eslint --fix', 'prettier --write', 'go fmt', 'cargo fmt') is available in the project to perform the task automatically.
 4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. Identify the correct test commands and frameworks by examining 'README' files, build/package configuration (e.g., 'package.json'), or existing test execution patterns. NEVER assume standard test commands. When executing test commands, prefer "run once" or "CI" modes to ensure the command terminates after completion.
@@ -1216,7 +1318,7 @@ You are running outside of a sandbox container, directly on the user's system. F
 - Never push changes to a remote repository without being asked explicitly by the user.
 
 # Final Reminder
-Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use 'read_file' to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
+Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use appropriate search and extraction tools to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
 `;
 
 exports[`Core System Prompt (prompts.ts) > should include approved plan instructions when approvedPlanPath is set 1`] = `
@@ -1261,7 +1363,7 @@ For example:
 ## Software Engineering Tasks
 When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
 1. **Understand:** Think about the user's request and the relevant codebase context. Use 'grep_search' and 'glob' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
-Use 'read_file' to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to 'read_file'.
+Use 'grep_search' with context or 'read_file' with precise ranges to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to these tools.
 2. **Plan:** An approved plan is available for this task. Use this file as a guide for your implementation. You MUST read this file before proceeding. If you discover new requirements or need to change the approach, confirm with the user and update this plan file to reflect the updated design decisions or discovered requirements.
 3. **Implement:** Use the available tools (e.g., 'replace', 'write_file' 'run_shell_command' ...) to act on the plan. Strictly adhere to the project's established conventions (detailed under 'Core Mandates'). Before making manual code changes, check if an ecosystem tool (like 'eslint --fix', 'prettier --write', 'go fmt', 'cargo fmt') is available in the project to perform the task automatically.
 4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. Identify the correct test commands and frameworks by examining 'README' files, build/package configuration (e.g., 'package.json'), or existing test execution patterns. NEVER assume standard test commands. When executing test commands, prefer "run once" or "CI" modes to ensure the command terminates after completion.
@@ -1319,7 +1421,7 @@ IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
 You are running outside of a sandbox container, directly on the user's system. For critical commands that are particularly likely to modify the user's system outside of the project directory or system temp directory, as you explain the command to the user (per the Explain Critical Commands rule above), also remind the user to consider enabling sandboxing.
 
 # Final Reminder
-Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use 'read_file' to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
+Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use appropriate search and extraction tools to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
 `;
 
 exports[`Core System Prompt (prompts.ts) > should include available_skills when provided in config 1`] = `
@@ -1377,7 +1479,7 @@ You have access to the following specialized skills. To activate a skill and rec
 ## Software Engineering Tasks
 When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
 1. **Understand:** Think about the user's request and the relevant codebase context. Use 'grep_search' and 'glob' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
-Use 'read_file' to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to 'read_file'.
+Use 'grep_search' with context or 'read_file' with precise ranges to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to these tools.
 2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. If the user's request implies a change but does not explicitly state it, **YOU MUST ASK** for confirmation before modifying code. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process. As part of the plan, you should use an iterative development process that includes writing unit tests to verify your changes. Use output logs or debug statements as part of this process to arrive at a solution.
 3. **Implement:** Use the available tools (e.g., 'replace', 'write_file' 'run_shell_command' ...) to act on the plan. Strictly adhere to the project's established conventions (detailed under 'Core Mandates'). Before making manual code changes, check if an ecosystem tool (like 'eslint --fix', 'prettier --write', 'go fmt', 'cargo fmt') is available in the project to perform the task automatically.
 4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. Identify the correct test commands and frameworks by examining 'README' files, build/package configuration (e.g., 'package.json'), or existing test execution patterns. NEVER assume standard test commands. When executing test commands, prefer "run once" or "CI" modes to ensure the command terminates after completion.
@@ -1445,7 +1547,7 @@ IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
 You are running outside of a sandbox container, directly on the user's system. For critical commands that are particularly likely to modify the user's system outside of the project directory or system temp directory, as you explain the command to the user (per the Explain Critical Commands rule above), also remind the user to consider enabling sandboxing.
 
 # Final Reminder
-Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use 'read_file' to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
+Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use appropriate search and extraction tools to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
 `;
 
 exports[`Core System Prompt (prompts.ts) > should include available_skills with updated verbiage for preview models 1`] = `
@@ -1458,6 +1560,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -1543,7 +1648,7 @@ You have access to the following specialized skills. To activate a skill and rec
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -1571,6 +1676,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -1610,6 +1729,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -1682,7 +1804,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -1710,6 +1832,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -1753,6 +1889,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -1825,7 +1964,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -1853,6 +1992,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -1896,6 +2049,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -1968,7 +2124,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -1996,6 +2152,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -2035,6 +2205,9 @@ exports[`Core System Prompt (prompts.ts) > should include mandate to distinguish
 - **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.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -2107,7 +2280,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -2135,6 +2308,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -2174,6 +2361,9 @@ exports[`Core System Prompt (prompts.ts) > should include modern approved plan i
 - **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.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -2246,7 +2436,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** An approved plan is available for this task. Treat this file as your single source of truth. You MUST read this file before proceeding. If you discover new requirements or need to change the approach, confirm with the user and update this plan file to reflect the updated design decisions or discovered requirements. Once all implementation and verification steps are finished, provide a **final summary** of the work completed against the plan and offer clear **next steps** to the user (e.g., 'Open a pull request').
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -2266,6 +2456,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -2305,6 +2509,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -2404,6 +2611,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -2443,6 +2664,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -2515,7 +2739,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -2543,6 +2767,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -2614,7 +2852,7 @@ For example:
 ## Software Engineering Tasks
 When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
 1. **Understand:** Think about the user's request and the relevant codebase context. Use 'grep_search' and 'glob' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
-Use 'read_file' to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to 'read_file'.
+Use 'grep_search' with context or 'read_file' with precise ranges to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to these tools.
 2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. If the user's request implies a change but does not explicitly state it, **YOU MUST ASK** for confirmation before modifying code. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process. As part of the plan, you should use an iterative development process that includes writing unit tests to verify your changes. Use output logs or debug statements as part of this process to arrive at a solution.
 3. **Implement:** Use the available tools (e.g., 'replace', 'write_file' 'run_shell_command' ...) to act on the plan. Strictly adhere to the project's established conventions (detailed under 'Core Mandates'). Before making manual code changes, check if an ecosystem tool (like 'eslint --fix', 'prettier --write', 'go fmt', 'cargo fmt') is available in the project to perform the task automatically.
 4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. Identify the correct test commands and frameworks by examining 'README' files, build/package configuration (e.g., 'package.json'), or existing test execution patterns. NEVER assume standard test commands. When executing test commands, prefer "run once" or "CI" modes to ensure the command terminates after completion.
@@ -2682,7 +2920,7 @@ IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
 You are running outside of a sandbox container, directly on the user's system. For critical commands that are particularly likely to modify the user's system outside of the project directory or system temp directory, as you explain the command to the user (per the Explain Critical Commands rule above), also remind the user to consider enabling sandboxing.
 
 # Final Reminder
-Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use 'read_file' to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
+Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use appropriate search and extraction tools to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
 `;
 
 exports[`Core System Prompt (prompts.ts) > should render hierarchical memory with XML tags 1`] = `
@@ -2728,7 +2966,7 @@ For example:
 ## Software Engineering Tasks
 When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
 1. **Understand:** Think about the user's request and the relevant codebase context. Use 'grep_search' and 'glob' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
-Use 'read_file' to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to 'read_file'.
+Use 'grep_search' with context or 'read_file' with precise ranges to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to these tools.
 2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. If the user's request implies a change but does not explicitly state it, **YOU MUST ASK** for confirmation before modifying code. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process. As part of the plan, you should use an iterative development process that includes writing unit tests to verify your changes. Use output logs or debug statements as part of this process to arrive at a solution.
 3. **Implement:** Use the available tools (e.g., 'replace', 'write_file' 'run_shell_command' ...) to act on the plan. Strictly adhere to the project's established conventions (detailed under 'Core Mandates'). Before making manual code changes, check if an ecosystem tool (like 'eslint --fix', 'prettier --write', 'go fmt', 'cargo fmt') is available in the project to perform the task automatically.
 4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. Identify the correct test commands and frameworks by examining 'README' files, build/package configuration (e.g., 'package.json'), or existing test execution patterns. NEVER assume standard test commands. When executing test commands, prefer "run once" or "CI" modes to ensure the command terminates after completion.
@@ -2796,7 +3034,7 @@ IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
 You are running outside of a sandbox container, directly on the user's system. For critical commands that are particularly likely to modify the user's system outside of the project directory or system temp directory, as you explain the command to the user (per the Explain Critical Commands rule above), also remind the user to consider enabling sandboxing.
 
 # Final Reminder
-Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use 'read_file' to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved.
+Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use appropriate search and extraction tools to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved.
 
 ---
 
@@ -2823,6 +3061,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -2895,7 +3136,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -2923,6 +3164,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -2962,6 +3217,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -3034,7 +3292,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -3062,6 +3320,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -3134,7 +3406,7 @@ For example:
 ## Software Engineering Tasks
 When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
 1. **Understand:** Think about the user's request and the relevant codebase context. Use 'grep_search' and 'glob' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
-Use 'read_file' to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to 'read_file'.
+Use 'grep_search' with context or 'read_file' with precise ranges to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to these tools.
 2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. If the user's request implies a change but does not explicitly state it, **YOU MUST ASK** for confirmation before modifying code. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process. As part of the plan, you should use an iterative development process that includes writing unit tests to verify your changes. Use output logs or debug statements as part of this process to arrive at a solution.
 3. **Implement:** Use the available tools (e.g., 'replace', 'write_file' 'run_shell_command' ...) to act on the plan. Strictly adhere to the project's established conventions (detailed under 'Core Mandates'). Before making manual code changes, check if an ecosystem tool (like 'eslint --fix', 'prettier --write', 'go fmt', 'cargo fmt') is available in the project to perform the task automatically.
 4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. Identify the correct test commands and frameworks by examining 'README' files, build/package configuration (e.g., 'package.json'), or existing test execution patterns. NEVER assume standard test commands. When executing test commands, prefer "run once" or "CI" modes to ensure the command terminates after completion.
@@ -3200,7 +3472,7 @@ IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
 You are running outside of a sandbox container, directly on the user's system. For critical commands that are particularly likely to modify the user's system outside of the project directory or system temp directory, as you explain the command to the user (per the Explain Critical Commands rule above), also remind the user to consider enabling sandboxing.
 
 # Final Reminder
-Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use 'read_file' to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
+Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use appropriate search and extraction tools to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
 `;
 
 exports[`Core System Prompt (prompts.ts) > should use chatty system prompt for preview flash model 1`] = `
@@ -3213,6 +3485,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -3285,7 +3560,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -3313,6 +3588,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -3352,6 +3641,9 @@ 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.
+- For broad discovery, use names_only=true or max_matches_per_file=1 to identify files without retrieving their context.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -3424,7 +3716,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`grep_search\` with context or \`read_file\` with precise ranges to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -3452,6 +3744,20 @@ Operate using a **Research -> Strategy -> Execution** lifecycle. For the Executi
 
 # Operational Guidelines
 
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using \`run_shell_command\`.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') using commands like 'grep', 'tail', 'head'. Remove the temp files when done.
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like \`grep_search\` with context or \`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -3523,7 +3829,7 @@ For example:
 ## Software Engineering Tasks
 When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
 1. **Understand:** Think about the user's request and the relevant codebase context. Use 'grep_search' and 'glob' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
-Use 'read_file' to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to 'read_file'.
+Use 'grep_search' with context or 'read_file' with precise ranges to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to these tools.
 2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. If the user's request implies a change but does not explicitly state it, **YOU MUST ASK** for confirmation before modifying code. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process. As part of the plan, you should use an iterative development process that includes writing unit tests to verify your changes. Use output logs or debug statements as part of this process to arrive at a solution.
 3. **Implement:** Use the available tools (e.g., 'replace', 'write_file' 'run_shell_command' ...) to act on the plan. Strictly adhere to the project's established conventions (detailed under 'Core Mandates'). Before making manual code changes, check if an ecosystem tool (like 'eslint --fix', 'prettier --write', 'go fmt', 'cargo fmt') is available in the project to perform the task automatically.
 4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. Identify the correct test commands and frameworks by examining 'README' files, build/package configuration (e.g., 'package.json'), or existing test execution patterns. NEVER assume standard test commands. When executing test commands, prefer "run once" or "CI" modes to ensure the command terminates after completion.
@@ -3591,5 +3897,5 @@ IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
 You are running outside of a sandbox container, directly on the user's system. For critical commands that are particularly likely to modify the user's system outside of the project directory or system temp directory, as you explain the command to the user (per the Explain Critical Commands rule above), also remind the user to consider enabling sandboxing.
 
 # Final Reminder
-Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use 'read_file' to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
+Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use appropriate search and extraction tools to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved."
 `;

packages/core/src/prompts/promptProvider.ts

@@ -119,6 +119,7 @@ export class PromptProvider {
         })),
         coreMandates: this.withSection('coreMandates', () => ({
           interactive: interactiveMode,
+          isGemini3: isModernModel,
           hasSkills: skills.length > 0,
           hasHierarchicalMemory,
           contextFilenames,

packages/core/src/prompts/snippets.legacy.ts

@@ -341,7 +341,7 @@ export function renderFinalReminder(options?: FinalReminderOptions): string {
   if (!options) return '';
   return `
 # Final Reminder
-Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use '${options.readFileToolName}' to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved.`.trim();
+Your core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use appropriate search and extraction tools to ensure you aren't making broad assumptions. Finally, you are an agent - please keep going until the user's query is completely resolved.`.trim();
 }
 
 export function renderUserMemory(memory?: string | HierarchicalMemory): string {
@@ -487,10 +487,10 @@ function mandateContinueWork(interactive: boolean): string {
 
 function workflowStepUnderstand(options: PrimaryWorkflowsOptions): string {
   if (options.enableCodebaseInvestigator) {
-    return `1. **Understand & Strategize:** Think about the user's request and the relevant codebase context. When the task involves **complex refactoring, codebase exploration or system-wide analysis**, your **first and primary action** must be to delegate to the 'codebase_investigator' agent using the 'codebase_investigator' tool. Use it to build a comprehensive understanding of the code, its structure, and dependencies. For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), you should use '${GREP_TOOL_NAME}' or '${GLOB_TOOL_NAME}' directly.`;
+    return `1. **Understand & Strategize:** Think about the user's request and the relevant codebase context. When the task involves **complex refactoring, codebase exploration or system-wide analysis**, your **first and primary action** must be to delegate to the 'codebase_investigator' agent using the 'codebase_investigator' tool. Use it to build a comprehensive understanding of the code, its structure, and dependencies. For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), you should use '${GREP_TOOL_NAME}' or '${GLOB_TOOL_NAME}' directly. Use '${GREP_TOOL_NAME}' with context or '${READ_FILE_TOOL_NAME}' with precise ranges to validate any assumptions you may have.`;
   }
   return `1. **Understand:** Think about the user's request and the relevant codebase context. Use '${GREP_TOOL_NAME}' and '${GLOB_TOOL_NAME}' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
-Use '${READ_FILE_TOOL_NAME}' to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to '${READ_FILE_TOOL_NAME}'.`;
+Use '${GREP_TOOL_NAME}' with context or '${READ_FILE_TOOL_NAME}' with precise ranges to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to these tools.`;
 }
 
 function workflowStepPlan(options: PrimaryWorkflowsOptions): string {

packages/core/src/prompts/snippets.ts

@@ -35,6 +35,7 @@ export interface SystemPromptOptions {
   sandbox?: SandboxMode;
   interactiveYoloMode?: boolean;
   gitRepo?: GitRepoOptions;
+  finalReminder?: FinalReminderOptions;
 }
 
 export interface PreambleOptions {
@@ -60,6 +61,7 @@ export interface PrimaryWorkflowsOptions {
 
 export interface OperationalGuidelinesOptions {
   interactive: boolean;
+  enableShellEfficiency: boolean;
   interactiveShellEnabled: boolean;
 }
 
@@ -69,6 +71,10 @@ export interface GitRepoOptions {
   interactive: boolean;
 }
 
+export interface FinalReminderOptions {
+  readFileToolName: string;
+}
+
 export interface PlanningWorkflowOptions {
   planModeToolsList: string;
   plansDir: string;
@@ -96,7 +102,7 @@ export function getCoreSystemPrompt(options: SystemPromptOptions): string {
   return `
 ${renderPreamble(options.preamble)}
 
-${renderCoreMandates(options.coreMandates)}
+${renderCoreMandates(options.coreMandates, options.primaryWorkflows)}
 
 ${renderSubAgents(options.subAgents)}
 
@@ -110,7 +116,10 @@ ${
     : renderPrimaryWorkflows(options.primaryWorkflows)
 }
 
-${renderOperationalGuidelines(options.operationalGuidelines)}
+${renderOperationalGuidelines(
+  options.operationalGuidelines,
+  options.primaryWorkflows,
+)}
 
 ${renderInteractiveYoloMode(options.interactiveYoloMode)}
 
@@ -144,7 +153,10 @@ export function renderPreamble(options?: PreambleOptions): string {
     : 'You are Gemini CLI, an autonomous CLI agent specializing in software engineering tasks. Your primary goal is to help users safely and effectively.';
 }
 
-export function renderCoreMandates(options?: CoreMandatesOptions): string {
+function renderCoreMandates(
+  options?: CoreMandatesOptions,
+  _primaryWorkflowsOptions?: PrimaryWorkflowsOptions,
+): string {
   if (!options) return '';
   const filenames = options.contextFilenames ?? [DEFAULT_CONTEXT_FILENAME];
   const formattedFilenames =
@@ -167,6 +179,9 @@ export function renderCoreMandates(options?: CoreMandatesOptions): string {
 - **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.
+
 Be strategic in your use of the available tools to minimize unnecessary context usage while still
 providing the best answer that you can.
 
@@ -299,13 +314,24 @@ ${newApplicationSteps(options)}
 `.trim();
 }
 
-export function renderOperationalGuidelines(
+function renderOperationalGuidelines(
   options?: OperationalGuidelinesOptions,
+  primaryWorkflowsOptions?: PrimaryWorkflowsOptions,
 ): string {
   if (!options) return '';
+
+  const grepContext = primaryWorkflowsOptions?.enableGrep
+    ? `\`${GREP_TOOL_NAME}\` with context or `
+    : '';
+
   return `
 # Operational Guidelines
 
+${shellEfficiencyGuidelines(options.enableShellEfficiency)}
+
+## Token Efficiency
+- **Be Token-Frugal:** Every line of code or long tool output you pull into the conversation history increases the complexity and cost of the entire session. **Context persists.** Prefer surgical extraction tools (like ${grepContext}\`sed\`) over broad file reads.
+
 ## Tone and Style
 
 - **Role:** A senior software engineer and collaborative peer programmer.
@@ -529,11 +555,16 @@ function mandateContinueWork(interactive: boolean): string {
 function workflowStepResearch(options: PrimaryWorkflowsOptions): string {
   let suggestion = '';
   if (options.enableEnterPlanModeTool) {
-    suggestion = ` If the request is ambiguous, broad in scope, or involves creating a new feature/application, you MUST use the ${formatToolName(ENTER_PLAN_MODE_TOOL_NAME)} tool to design your approach before making changes. Do NOT use Plan Mode for straightforward bug fixes, answering questions, or simple inquiries.`;
+    suggestion = ` If the request is ambiguous, broad in scope, or involves creating a new feature/application, you MUST use the ${formatToolName(
+      ENTER_PLAN_MODE_TOOL_NAME,
+    )} tool to design your approach before making changes. Do NOT use Plan Mode for straightforward bug fixes, answering questions, or simple inquiries.`;
   }
 
+  const grepName = formatToolName(GREP_TOOL_NAME);
+  const readFileName = formatToolName(READ_FILE_TOOL_NAME);
+
   const searchTools: string[] = [];
-  if (options.enableGrep) searchTools.push(formatToolName(GREP_TOOL_NAME));
+  if (options.enableGrep) searchTools.push(grepName);
   if (options.enableGlob) searchTools.push(formatToolName(GLOB_TOOL_NAME));
 
   let searchSentence =
@@ -544,17 +575,21 @@ function workflowStepResearch(options: PrimaryWorkflowsOptions): string {
     searchSentence = ` Use ${toolsStr} search ${toolOrTools} extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.`;
   }
 
+  const validationClause = options.enableGrep
+    ? `Use ${grepName} with context or ${readFileName} with precise ranges to validate all assumptions.`
+    : `Use ${readFileName} to validate all assumptions.`;
+
   if (options.enableCodebaseInvestigator) {
     let subAgentSearch = '';
     if (searchTools.length > 0) {
       const toolsStr = searchTools.join(' or ');
-      subAgentSearch = ` For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), use ${toolsStr} directly in parallel.`;
+      subAgentSearch = `For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), use ${toolsStr} directly in parallel. `;
     }
 
-    return `1. **Research:** Systematically map the codebase and validate assumptions. Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery when the task involves **complex refactoring, codebase exploration or system-wide analysis**.${subAgentSearch} Use ${formatToolName(READ_FILE_TOOL_NAME)} to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;
+    return `1. **Research:** Systematically map the codebase and validate assumptions. Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery when the task involves **complex refactoring, codebase exploration or system-wide analysis**. ${subAgentSearch}${validationClause} **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;
   }
 
-  return `1. **Research:** Systematically map the codebase and validate assumptions.${searchSentence} Use ${formatToolName(READ_FILE_TOOL_NAME)} to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;
+  return `1. **Research:** Systematically map the codebase and validate assumptions.${searchSentence} ${validationClause} **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;
 }
 
 function workflowStepStrategy(options: PrimaryWorkflowsOptions): string {
@@ -638,6 +673,27 @@ function newApplicationSteps(options: PrimaryWorkflowsOptions): string {
 4. **Verify:** Review work against the original request. Fix bugs and deviations. **Build the application and ensure there are no compile errors.**`.trim();
 }
 
+function shellEfficiencyGuidelines(enabled: boolean): string {
+  if (!enabled) return '';
+  const isWindows = process.platform === 'win32';
+  const inspectExample = isWindows
+    ? "using commands like 'type' or 'findstr' (on CMD) and 'Get-Content' or 'Select-String' (on PowerShell)"
+    : "using commands like 'grep', 'tail', 'head'";
+  return `
+## Shell tool output token efficiency:
+
+IT IS CRITICAL TO FOLLOW THESE GUIDELINES TO AVOID EXCESSIVE TOKEN CONSUMPTION.
+
+- Always prefer command flags that reduce output verbosity when using ${formatToolName(
+    SHELL_TOOL_NAME,
+  )}.
+- 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'.
+- After the command runs, inspect the temp files (e.g. '<temp_dir>/out.log' and '<temp_dir>/err.log') ${inspectExample}. Remove the temp files when done.`;
+}
+
 function toolUsageInteractive(
   interactive: boolean,
   interactiveShellEnabled: boolean,

packages/core/src/tools/__snapshots__/read-file.test.ts.snap

@@ -1,5 +1,5 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`ReadFileTool > getSchema > should return the base schema when no modelId is provided 1`] = `"Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC, OGG, FLAC), and PDF files. For text files, it can read specific line ranges."`;
+exports[`ReadFileTool > getSchema > should return the base schema when no modelId is provided 1`] = `"Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. Handles text, images, audio, and PDF files. For text files, it can read specific line ranges."`;
 
-exports[`ReadFileTool > getSchema > should return the schema from the resolver when modelId is provided 1`] = `"Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC, OGG, FLAC), and PDF files. For text files, it can read specific line ranges."`;
+exports[`ReadFileTool > getSchema > should return the schema from the resolver when modelId is provided 1`] = `"Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. Handles text, images, audio, and PDF files. For text files, it can read specific line ranges."`;

packages/core/src/tools/__snapshots__/shell.test.ts.snap

@@ -3,10 +3,6 @@
 exports[`ShellTool > getDescription > should return the non-windows description when not on windows 1`] = `
 "This tool executes a given shell command as \`bash -c <command>\`. Command can start background processes using \`&\`. Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.
 
-      Efficiency Guidelines:
-      - Quiet Flags: Always prefer silent or quiet flags (e.g., \`npm install --silent\`, \`git --no-pager\`) to reduce output volume while still capturing necessary information.
-      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\`).
-
       The following information is returned:
 
       Output: Combined stdout/stderr. Can be \`(empty)\` or partial on error and for any unwaited background processes.
@@ -14,16 +10,17 @@ exports[`ShellTool > getDescription > should return the non-windows description
       Error: Only included if a process-level error occurred (e.g., spawn failure).
       Signal: Only included if process was terminated by a signal.
       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.
+
+      Efficiency Guidelines:
+      - Quiet Flags: Always prefer silent or quiet flags (e.g., \`npm install --silent\`, \`git --no-pager\`) to reduce output volume while still capturing necessary information.
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\`)."
 `;
 
 exports[`ShellTool > getDescription > should return the windows description when on windows 1`] = `
 "This tool executes a given shell command as \`powershell.exe -NoProfile -Command <command>\`. Command can start background processes using PowerShell constructs such as \`Start-Process -NoNewWindow\` or \`Start-Job\`.
 
-      Efficiency Guidelines:
-      - Quiet Flags: Always prefer silent or quiet flags (e.g., \`npm install --silent\`, \`git --no-pager\`) to reduce output volume while still capturing necessary information.
-      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\`).
-
       The following information is returned:
 
       Output: Combined stdout/stderr. Can be \`(empty)\` or partial on error and for any unwaited background processes.
@@ -31,16 +28,17 @@ exports[`ShellTool > getDescription > should return the windows description when
       Error: Only included if a process-level error occurred (e.g., spawn failure).
       Signal: Only included if process was terminated by a signal.
       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.
+
+      Efficiency Guidelines:
+      - Quiet Flags: Always prefer silent or quiet flags (e.g., \`npm install --silent\`, \`git --no-pager\`) to reduce output volume while still capturing necessary information.
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\`)."
 `;
 
 exports[`ShellTool > getSchema > should return the base schema when no modelId is provided 1`] = `
 "This tool executes a given shell command as \`bash -c <command>\`. Command can start background processes using \`&\`. Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.
 
-      Efficiency Guidelines:
-      - Quiet Flags: Always prefer silent or quiet flags (e.g., \`npm install --silent\`, \`git --no-pager\`) to reduce output volume while still capturing necessary information.
-      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\`).
-
       The following information is returned:
 
       Output: Combined stdout/stderr. Can be \`(empty)\` or partial on error and for any unwaited background processes.
@@ -48,16 +46,17 @@ exports[`ShellTool > getSchema > should return the base schema when no modelId i
       Error: Only included if a process-level error occurred (e.g., spawn failure).
       Signal: Only included if process was terminated by a signal.
       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.
+
+      Efficiency Guidelines:
+      - Quiet Flags: Always prefer silent or quiet flags (e.g., \`npm install --silent\`, \`git --no-pager\`) to reduce output volume while still capturing necessary information.
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\`)."
 `;
 
 exports[`ShellTool > getSchema > should return the schema from the resolver when modelId is provided 1`] = `
 "This tool executes a given shell command as \`bash -c <command>\`. Command can start background processes using \`&\`. Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.
 
-      Efficiency Guidelines:
-      - Quiet Flags: Always prefer silent or quiet flags (e.g., \`npm install --silent\`, \`git --no-pager\`) to reduce output volume while still capturing necessary information.
-      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\`).
-
       The following information is returned:
 
       Output: Combined stdout/stderr. Can be \`(empty)\` or partial on error and for any unwaited background processes.
@@ -65,5 +64,10 @@ exports[`ShellTool > getSchema > should return the schema from the resolver when
       Error: Only included if a process-level error occurred (e.g., spawn failure).
       Signal: Only included if process was terminated by a signal.
       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.
+
+      Efficiency Guidelines:
+      - Quiet Flags: Always prefer silent or quiet flags (e.g., \`npm install --silent\`, \`git --no-pager\`) to reduce output volume while still capturing necessary information.
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\`)."
 `;

packages/core/src/tools/definitions/__snapshots__/coreToolsModelSnapshots.test.ts.snap

@@ -200,7 +200,7 @@ exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snaps
 
 exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snapshot for tool: glob 1`] = `
 {
-  "description": "Efficiently finds files matching specific glob patterns (e.g., \`src/**/*.ts\`, \`**/*.md\`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases.",
+  "description": "Efficiently finds files matching specific glob patterns (e.g., \`src/**/*.ts\`, \`**/*.md\`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases. **Avoid using this tool just to list files before reading them;** if you know the symbols you need, use \`grep_search\` directly.",
   "name": "glob",
   "parametersJsonSchema": {
     "properties": {
@@ -254,7 +254,7 @@ exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snaps
 
 exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snapshot for tool: grep_search 1`] = `
 {
-  "description": "Searches for a regular expression pattern within file contents. Max 100 matches.",
+  "description": "FAST regular expression search. This is the **primary discovery tool** for locating code. Use context parameters (\`context\`, \`after\`, \`before\`) to read code surrounding matches in a single turn, often eliminating the need for a separate \`read_file\` call. (max 100 matches).",
   "name": "grep_search",
   "parametersJsonSchema": {
     "properties": {
@@ -410,7 +410,7 @@ exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snaps
 
 exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snapshot for tool: read_file 1`] = `
 {
-  "description": "Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC, OGG, FLAC), and PDF files. For text files, it can read specific line ranges.",
+  "description": "Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. **Important:** For high token efficiency, avoid reading large files in their entirety. Use 'grep_search' to find symbols or 'run_shell_command' with 'sed' for surgical block extraction instead of broad file reads. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC, OGG, FLAC), and PDF files. For text files, it can read specific line ranges.",
   "name": "read_file",
   "parametersJsonSchema": {
     "properties": {
@@ -579,7 +579,8 @@ exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snaps
       Error: Only included if a process-level error occurred (e.g., spawn failure).
       Signal: Only included if process was terminated by a signal.
       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.",
   "name": "run_shell_command",
   "parametersJsonSchema": {
     "properties": {
@@ -987,7 +988,7 @@ exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview >
 
 exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview > snapshot for tool: glob 1`] = `
 {
-  "description": "Efficiently finds files matching specific glob patterns (e.g., \`src/**/*.ts\`, \`**/*.md\`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases.",
+  "description": "Efficiently finds files matching specific glob patterns (e.g., \`src/**/*.ts\`, \`**/*.md\`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases. **Avoid using this tool just to list files before reading them;** if you know the symbols you need, use \`grep_search\` directly.",
   "name": "glob",
   "parametersJsonSchema": {
     "properties": {
@@ -1041,7 +1042,7 @@ exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview >
 
 exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview > snapshot for tool: grep_search 1`] = `
 {
-  "description": "Searches for a regular expression pattern within file contents. Max 100 matches.",
+  "description": "FAST regular expression search. This is the **primary discovery tool** for locating code. Use context parameters (\`context\`, \`after\`, \`before\`) to read code surrounding matches in a single turn, often eliminating the need for a separate \`read_file\` call. (max 100 matches).",
   "name": "grep_search",
   "parametersJsonSchema": {
     "properties": {
@@ -1197,7 +1198,7 @@ exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview >
 
 exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview > snapshot for tool: read_file 1`] = `
 {
-  "description": "Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC, OGG, FLAC), and PDF files. For text files, it can read specific line ranges.",
+  "description": "Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. **Important:** For high token efficiency, avoid reading large files in their entirety. Use 'grep_search' to find symbols or 'run_shell_command' with 'sed' for surgical block extraction instead of broad file reads. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC, OGG, FLAC), and PDF files. For text files, it can read specific line ranges.",
   "name": "read_file",
   "parametersJsonSchema": {
     "properties": {
@@ -1342,7 +1343,8 @@ exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview >
       Error: Only included if a process-level error occurred (e.g., spawn failure).
       Signal: Only included if process was terminated by a signal.
       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.",
   "name": "run_shell_command",
   "parametersJsonSchema": {
     "properties": {

packages/core/src/tools/definitions/dynamic-declaration-helpers.ts

@@ -45,16 +45,19 @@ export function getShellToolDescription(
       Background PIDs: Only included if background processes were started.
       Process Group PGID: Only included if available.`;
 
+  const surgicalExtractionGuidance = `
+      **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.`;
+
   if (os.platform() === 'win32') {
     const backgroundInstructions = enableInteractiveShell
       ? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use PowerShell background constructs.'
       : 'Command can start background processes using PowerShell constructs such as `Start-Process -NoNewWindow` or `Start-Job`.';
-    return `This tool executes a given shell command as \`powershell.exe -NoProfile -Command <command>\`. ${backgroundInstructions}${efficiencyGuidelines}${returnedInfo}`;
+    return `This tool executes a given shell command as \`powershell.exe -NoProfile -Command <command>\`. ${backgroundInstructions}${efficiencyGuidelines}${returnedInfo}${surgicalExtractionGuidance}`;
   } else {
     const backgroundInstructions = enableInteractiveShell
       ? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use `&` to background commands.'
       : 'Command can start background processes using `&`.';
-    return `This tool executes a given shell command as \`bash -c <command>\`. ${backgroundInstructions} Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.${efficiencyGuidelines}${returnedInfo}`;
+    return `This tool executes a given shell command as \`bash -c <command>\`. ${backgroundInstructions} Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.${efficiencyGuidelines}${returnedInfo}${surgicalExtractionGuidance}`;
   }
 }
 

packages/core/src/tools/definitions/model-family-sets/default-legacy.ts

@@ -35,7 +35,7 @@ import {
 export const DEFAULT_LEGACY_SET: CoreToolSet = {
   read_file: {
     name: READ_FILE_TOOL_NAME,
-    description: `Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC, OGG, FLAC), and PDF files. For text files, it can read specific line ranges.`,
+    description: `Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. **Important:** For high token efficiency, avoid reading large files in their entirety. Use 'grep_search' to find symbols or 'run_shell_command' with 'sed' for surgical block extraction instead of broad file reads. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC, OGG, FLAC), and PDF files. For text files, it can read specific line ranges.`,
     parametersJsonSchema: {
       type: 'object',
       properties: {
@@ -83,7 +83,7 @@ export const DEFAULT_LEGACY_SET: CoreToolSet = {
   grep_search: {
     name: GREP_TOOL_NAME,
     description:
-      'Searches for a regular expression pattern within file contents. Max 100 matches.',
+      'FAST regular expression search. This is the **primary discovery tool** for locating code. Use context parameters (`context`, `after`, `before`) to read code surrounding matches in a single turn, often eliminating the need for a separate `read_file` call. (max 100 matches).',
     parametersJsonSchema: {
       type: 'object',
       properties: {
@@ -210,7 +210,7 @@ export const DEFAULT_LEGACY_SET: CoreToolSet = {
   glob: {
     name: GLOB_TOOL_NAME,
     description:
-      'Efficiently finds files matching specific glob patterns (e.g., `src/**/*.ts`, `**/*.md`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases.',
+      'Efficiently finds files matching specific glob patterns (e.g., `src/**/*.ts`, `**/*.md`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases. **Avoid using this tool just to list files before reading them;** if you know the symbols you need, use `grep_search` directly.',
     parametersJsonSchema: {
       type: 'object',
       properties: {

packages/core/src/tools/definitions/model-family-sets/gemini-3.ts

@@ -38,7 +38,7 @@ import {
 export const GEMINI_3_SET: CoreToolSet = {
   read_file: {
     name: READ_FILE_TOOL_NAME,
-    description: `Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC, OGG, FLAC), and PDF files. For text files, it can read specific line ranges.`,
+    description: `Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. **Important:** For high token efficiency, avoid reading large files in their entirety. Use 'grep_search' to find symbols or 'run_shell_command' with 'sed' for surgical block extraction instead of broad file reads. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC, OGG, FLAC), and PDF files. For text files, it can read specific line ranges.`,
     parametersJsonSchema: {
       type: 'object',
       properties: {
@@ -84,7 +84,7 @@ export const GEMINI_3_SET: CoreToolSet = {
   grep_search: {
     name: GREP_TOOL_NAME,
     description:
-      'Searches for a regular expression pattern within file contents. Max 100 matches.',
+      'FAST regular expression search. This is the **primary discovery tool** for locating code. Use context parameters (`context`, `after`, `before`) to read code surrounding matches in a single turn, often eliminating the need for a separate `read_file` call. (max 100 matches).',
     parametersJsonSchema: {
       type: 'object',
       properties: {
@@ -211,7 +211,7 @@ export const GEMINI_3_SET: CoreToolSet = {
   glob: {
     name: GLOB_TOOL_NAME,
     description:
-      'Efficiently finds files matching specific glob patterns (e.g., `src/**/*.ts`, `**/*.md`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases.',
+      'Efficiently finds files matching specific glob patterns (e.g., `src/**/*.ts`, `**/*.md`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases. **Avoid using this tool just to list files before reading them;** if you know the symbols you need, use `grep_search` directly.',
     parametersJsonSchema: {
       type: 'object',
       properties: {

packages/core/src/tools/read-file.test.ts

@@ -40,6 +40,7 @@ describe('ReadFileTool', () => {
       getFileSystemService: () => new StandardFileSystemService(),
       getTargetDir: () => tempRootDir,
       getWorkspaceContext: () => createMockWorkspaceContext(tempRootDir),
+      getActiveModel: vi.fn().mockReturnValue('gemini-2.5-pro'),
       getFileFilteringOptions: () => ({
         respectGitIgnore: true,
         respectGeminiIgnore: true,
@@ -77,6 +78,33 @@ describe('ReadFileTool', () => {
     }
   });
 
+  describe('schema', () => {
+    it('should include line range parameters for all models', () => {
+      vi.mocked(tool['config'].getActiveModel).mockReturnValue(
+        'gemini-2.5-pro',
+      );
+      const schema = tool.schema;
+      const properties = (
+        schema.parametersJsonSchema as {
+          properties: Record<string, unknown>;
+        }
+      ).properties;
+      expect(properties).toHaveProperty('start_line');
+      expect(properties).toHaveProperty('end_line');
+      expect(properties).not.toHaveProperty('offset');
+      expect(properties).not.toHaveProperty('limit');
+    });
+
+    it('should include surgical guidance in description for Gemini 3', () => {
+      vi.mocked(tool['config'].getActiveModel).mockReturnValue(
+        'gemini-3-pro-preview',
+      );
+      const schema = tool.schema;
+      expect(schema.description).toContain('grep_search');
+      expect(schema.description).toContain('sed');
+    });
+  });
+
   describe('build', () => {
     it('should return an invocation for valid params (absolute path within root)', () => {
       const params: ReadFileToolParams = {
@@ -401,15 +429,15 @@ describe('ReadFileTool', () => {
     });
 
     it('should support start_line and end_line for text files', async () => {
-      const filePath = path.join(tempRootDir, 'paginated.txt');
+      const filePath = path.join(tempRootDir, 'lines.txt');
       const lines = Array.from({ length: 20 }, (_, i) => `Line ${i + 1}`);
       const fileContent = lines.join('\n');
       await fsp.writeFile(filePath, fileContent, 'utf-8');
 
       const params: ReadFileToolParams = {
         file_path: filePath,
-        start_line: 6,
-        end_line: 8,
+        start_line: 5,
+        end_line: 10,
       };
       const invocation = tool.build(params);
 
@@ -418,14 +446,31 @@ describe('ReadFileTool', () => {
         'IMPORTANT: The file content has been truncated',
       );
       expect(result.llmContent).toContain(
-        'Status: Showing lines 6-8 of 20 total lines',
+        'Status: Showing lines 5-10 of 20 total lines',
       );
-      expect(result.llmContent).toContain('Line 6');
-      expect(result.llmContent).toContain('Line 7');
-      expect(result.llmContent).toContain('Line 8');
-      expect(result.returnDisplay).toBe(
-        'Read lines 6-8 of 20 from paginated.txt',
+      expect(result.llmContent).toContain('Line 5');
+      expect(result.llmContent).toContain('Line 10');
+      expect(result.returnDisplay).toBe('Read lines 5-10 of 20 from lines.txt');
+    });
+
+    it('should use first-2000-lines truncation and shell-tool guidance for Gemini 3', async () => {
+      vi.mocked(tool['config'].getActiveModel).mockReturnValue(
+        'gemini-3-pro-preview',
       );
+      const filePath = path.join(tempRootDir, 'large.txt');
+      const lines = Array.from({ length: 2500 }, (_, i) => `Line ${i + 1}`);
+      await fsp.writeFile(filePath, lines.join('\n'), 'utf-8');
+
+      const params: ReadFileToolParams = {
+        file_path: filePath,
+      };
+      const invocation = tool.build(params);
+
+      const result = await invocation.execute(abortSignal);
+      expect(result.llmContent).toContain('Showing lines 1-2000');
+      expect(result.llmContent).toContain("use the 'grep_search' tool");
+      expect(result.llmContent).toContain('Line 1');
+      expect(result.llmContent).not.toContain('Line 2001');
     });
 
     it('should successfully read files from project temp directory', async () => {
@@ -454,6 +499,7 @@ describe('ReadFileTool', () => {
           getFileSystemService: () => new StandardFileSystemService(),
           getTargetDir: () => tempRootDir,
           getWorkspaceContext: () => new WorkspaceContext(tempRootDir),
+          getActiveModel: () => 'gemini-2.5-pro',
           getFileFilteringOptions: () => ({
             respectGitIgnore: true,
             respectGeminiIgnore: true,
@@ -527,6 +573,7 @@ describe('ReadFileTool', () => {
           getFileSystemService: () => new StandardFileSystemService(),
           getTargetDir: () => tempRootDir,
           getWorkspaceContext: () => new WorkspaceContext(tempRootDir),
+          getActiveModel: () => 'gemini-2.5-pro',
           getFileFilteringOptions: () => ({
             respectGitIgnore: true,
             respectGeminiIgnore: false,

packages/core/src/tools/read-file.ts

@@ -10,11 +10,11 @@ import { makeRelative, shortenPath } from '../utils/paths.js';
 import type { ToolInvocation, ToolLocation, ToolResult } from './tools.js';
 import { BaseDeclarativeTool, BaseToolInvocation, Kind } from './tools.js';
 import { ToolErrorType } from './tool-error.js';
-
-import type { PartUnion } from '@google/genai';
+import type { FunctionDeclaration, PartUnion } from '@google/genai';
 import {
   processSingleFileContent,
   getSpecificMimeType,
+  DEFAULT_MAX_LINES_TEXT_FILE,
 } from '../utils/fileUtils.js';
 import type { Config } from '../config/config.js';
 import { FileOperation } from '../telemetry/metrics.js';
@@ -23,8 +23,11 @@ import { logFileOperation } from '../telemetry/loggers.js';
 import { FileOperationEvent } from '../telemetry/types.js';
 import { READ_FILE_TOOL_NAME, READ_FILE_DISPLAY_NAME } from './tool-names.js';
 import { FileDiscoveryService } from '../services/fileDiscoveryService.js';
+import {
+  isPreviewModel,
+  supportsMultimodalFunctionResponse,
+} from '../config/models.js';
 import { READ_FILE_DEFINITION } from './definitions/coreTools.js';
-import { resolveToolDeclaration } from './definitions/resolver.js';
 
 /**
  * Parameters for the ReadFile tool
@@ -83,6 +86,11 @@ class ReadFileToolInvocation extends BaseToolInvocation<
   }
 
   async execute(): Promise<ToolResult> {
+    const activeModel = this.config.getActiveModel();
+    const isGemini3 =
+      supportsMultimodalFunctionResponse(activeModel) ||
+      isPreviewModel(activeModel);
+
     const validationError = this.config.validatePathAccess(
       this.resolvedPath,
       'read',
@@ -122,13 +130,26 @@ class ReadFileToolInvocation extends BaseToolInvocation<
       const [start, end] = result.linesShown!;
       const total = result.originalLineCount!;
 
-      llmContent = `
+      if (isGemini3) {
+        llmContent = `
+IMPORTANT: The file content has been truncated.
+Status: Showing lines ${start}-${end} of ${total} total lines.
+Action: 
+- To find specific patterns, use the 'grep_search' tool.
+- For surgical extraction of code blocks (especially ranges larger than 2,000 lines), prefer 'run_shell_command' with 'sed'. For example: 'sed -n "500,600p" ${this.params.file_path}'.
+- You can also use other Unix utilities like 'awk', 'head', or 'tail' via 'run_shell_command'.
+
+--- FILE CONTENT (truncated) ---
+${result.llmContent}`;
+      } else {
+        llmContent = `
 IMPORTANT: The file content has been truncated.
 Status: Showing lines ${start}-${end} of ${total} total lines.
 Action: To read more of the file, you can use the 'start_line' and 'end_line' parameters in a subsequent 'read_file' call. For example, to read the next section of the file, use start_line: ${end + 1}.
 
 --- FILE CONTENT (truncated) ---
 ${result.llmContent}`;
+      }
     } else {
       llmContent = result.llmContent || '';
     }
@@ -190,6 +211,41 @@ export class ReadFileTool extends BaseDeclarativeTool<
     );
   }
 
+  override getSchema(modelId?: string): FunctionDeclaration {
+    const activeModel = modelId ?? this.config.getActiveModel();
+    const isGemini3 =
+      supportsMultimodalFunctionResponse(activeModel) ||
+      isPreviewModel(activeModel);
+
+    const properties: Record<string, unknown> = {
+      file_path: {
+        description: 'The path to the file to read.',
+        type: 'string',
+      },
+      start_line: {
+        description: 'Optional: The 1-based line number to start reading from.',
+        type: 'number',
+      },
+      end_line: {
+        description:
+          'Optional: The 1-based line number to end reading at (inclusive).',
+        type: 'number',
+      },
+    };
+
+    return {
+      name: this.name,
+      description: isGemini3
+        ? `Reads a specific range of a file (up to ${DEFAULT_MAX_LINES_TEXT_FILE} lines). **Important:** For high token efficiency, avoid reading large files in their entirety. Use 'grep_search' to find symbols or 'run_shell_command' with 'sed' for surgical block extraction instead of broad file reads. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio (MP3, WAV, AIFF, AAC, OGG, FLAC), and PDF files.`
+        : `Reads and returns the content of a specified file. If the file is large, the content will be truncated. The tool's response will clearly indicate if truncation has occurred and will provide details on how to read more of the file using the 'start_line' and 'end_line' parameters. Handles text, images, audio, and PDF files. For text files, it can read specific line ranges.`,
+      parametersJsonSchema: {
+        properties,
+        required: ['file_path'],
+        type: 'object',
+      },
+    };
+  }
+
   protected override validateToolParamValues(
     params: ReadFileToolParams,
   ): string | null {
@@ -251,8 +307,4 @@ export class ReadFileTool extends BaseDeclarativeTool<
       _toolDisplayName,
     );
   }
-
-  override getSchema(modelId?: string) {
-    return resolveToolDeclaration(READ_FILE_DEFINITION, modelId);
-  }
 }

packages/core/src/utils/fileUtils.test.ts

@@ -20,7 +20,7 @@ import fsPromises from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
-// eslint-disable-next-line import/no-internal-modules
+ 
 import mime from 'mime/lite';
 
 import {
@@ -950,6 +950,26 @@ describe('fileUtils', () => {
       expect(result.linesShown).toEqual([6, 10]);
     });
 
+    it('should support startLine and endLine for text files', async () => {
+      const lines = Array.from({ length: 20 }, (_, i) => `Line ${i + 1}`);
+      actualNodeFs.writeFileSync(testTextFilePath, lines.join('\n'));
+
+      const result = await processSingleFileContent(
+        testTextFilePath,
+        tempRootDir,
+        new StandardFileSystemService(),
+        5,
+        10,
+      ); // Read lines 5-10 (1-based)
+      const expectedContent = lines.slice(4, 10).join('\n');
+
+      expect(result.llmContent).toBe(expectedContent);
+      expect(result.returnDisplay).toBe('Read lines 5-10 of 20 from test.txt');
+      expect(result.isTruncated).toBe(true);
+      expect(result.originalLineCount).toBe(20);
+      expect(result.linesShown).toEqual([5, 10]);
+    });
+
     it('should identify truncation when reading the end of a file', async () => {
       const lines = Array.from({ length: 20 }, (_, i) => `Line ${i + 1}`);
       actualNodeFs.writeFileSync(testTextFilePath, lines.join('\n'));

packages/core/src/utils/fileUtils.ts

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import fsPromises from 'node:fs/promises';
 import path from 'node:path';
 import type { PartUnion } from '@google/genai';
-// eslint-disable-next-line import/no-internal-modules
+ 
 import mime from 'mime/lite';
 import type { FileSystemService } from '../services/fileSystemService.js';
 import { ToolErrorType } from '../tools/tool-error.js';

packages/core/src/utils/schemaValidator.ts

@@ -6,7 +6,7 @@
 
 import AjvPkg, { type AnySchema, type Ajv } from 'ajv';
 // Ajv2020 is the documented way to use draft-2020-12: https://ajv.js.org/json-schema.html#draft-2020-12
-// eslint-disable-next-line import/no-internal-modules
+ 
 import Ajv2020Pkg from 'ajv/dist/2020.js';
 import * as addFormats from 'ajv-formats';
 import { debugLogger } from './debugLogger.js';