Stronger tilth guidance.

packages/core/src/agents/codebase-investigator.ts

@@ -133,7 +133,7 @@ export const CodebaseInvestigatorAgent = (
       systemPrompt: `You are **Codebase Investigator**, a hyper-specialized AI agent and an expert in reverse-engineering complex software projects. You are a sub-agent within a larger development system.
 Your **SOLE PURPOSE** is to build a complete mental model of the code relevant to a given investigation. You must identify all relevant files, understand their roles, and foresee the direct architectural consequences of potential changes.
 You are a sub-agent in a larger system. Your only responsibility is to provide deep, actionable context.
-- **DO:** Use \`tilth\` (via the \`run_shell_command\` tool) for initial codebase mapping (\`tilth --map\`) and AST-aware outlines of large files (\`tilth <path>\`).
+- **DO:** Use \`tilth\` (via the \`run_shell_command\` tool) for initial codebase mapping (\`tilth --map\`), symbol discovery (\`tilth <symbol>\`), and AST-aware outlines of large files (\`tilth <path>\`). Use \`--budget <tokens>\` to manage context and \`--scope <dir>\` to narrow your search.
 - **DO:** Find the key modules, classes, and functions that are part of the problem and its solution.
 - **DO:** Understand *why* the code is written the way it is. Question everything.
 - **DO:** Foresee the ripple effects of a change. If \`function A\` is modified, you must check its callers. If a data structure is altered, you must identify where its type definitions need to be updated.

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

@@ -22,27 +22,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -199,27 +195,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -495,27 +487,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -672,27 +660,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -752,7 +736,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -849,27 +833,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -899,7 +879,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 the \`tilth\` CLI command or \`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 symbol, file path, glob, or text), use the \`tilth\` CLI command or \`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.**
 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.**
@@ -978,27 +958,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -1028,7 +1004,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -1580,27 +1556,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -1673,7 +1645,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -1753,27 +1725,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -1833,7 +1801,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -1917,27 +1885,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -1997,7 +1961,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -2081,27 +2045,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -2161,7 +2121,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -2241,27 +2201,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -2321,7 +2277,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -2401,27 +2357,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -2481,7 +2433,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -2553,27 +2505,22 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -2712,27 +2659,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -2792,7 +2735,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -2996,27 +2939,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -3076,7 +3015,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -3408,27 +3347,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -3488,7 +3423,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -3568,27 +3503,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -3648,7 +3579,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -3840,27 +3771,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -3920,7 +3847,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**
@@ -4000,27 +3927,23 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
-- read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls. Use context (\`context\`, etc.) with \`grep_search\` to avoid a separate \`read_file\` turn before editing.
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`run_shell_command\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`read_file\` or \`grep_search\` outputs enough context to make \`old_string\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
-- **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`run_shell_command\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.
+- **Grep & Edit:** Use \`grep_search\` with context to skip \`read_file\` before an edit.
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -4080,7 +4003,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 the \`tilth\` CLI command (for structural maps and symbol discovery), \`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 the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), \`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.**
 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.**

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

@@ -457,7 +457,7 @@ describe('Core System Prompt (prompts.ts)', () => {
           `Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery`,
         );
         expect(prompt).toContain(
-          'Use the `tilth` CLI command (for structural maps and symbol discovery), `grep_search` and `glob` search tools extensively',
+          'Use the `tilth` CLI command (for structural maps, symbol discovery, and AST-aware outlines), `grep_search` and `glob` search tools extensively',
         );
       }
       expect(prompt).toMatchSnapshot();
@@ -554,6 +554,9 @@ describe('Core System Prompt (prompts.ts)', () => {
       vi.mocked(mockConfig.toolRegistry.getAllTools).mockReturnValue(
         subsetTools,
       );
+      vi.mocked(mockConfig.toolRegistry.getAllToolNames).mockReturnValue(
+        subsetTools.map((t) => t.name),
+      );
 
       const prompt = getCoreSystemPrompt(mockConfig);
 

packages/core/src/prompts/promptProvider.ts

@@ -55,7 +55,7 @@ export class PromptProvider {
     const isPlanMode = approvalMode === ApprovalMode.PLAN;
     const isYoloMode = approvalMode === ApprovalMode.YOLO;
     const skills = context.config.getSkillManager().getSkills();
-    const toolNames = context.toolRegistry.getAllToolNames();
+    const toolNames = context.toolRegistry.getAllToolNames?.() ?? [];
     const enabledToolNames = new Set(toolNames);
     const approvedPlanPath = context.config.getApprovedPlanPath();
 
@@ -73,7 +73,7 @@ export class PromptProvider {
     // --- Context Gathering ---
     let planModeToolsList = '';
     if (isPlanMode) {
-      const allTools = context.toolRegistry.getAllTools();
+      const allTools = context.toolRegistry.getAllTools?.() ?? [];
       planModeToolsList = allTools
         .map((t) => {
           if (t instanceof DiscoveredMCPTool) {
@@ -128,6 +128,8 @@ export class PromptProvider {
           hasHierarchicalMemory,
           contextFilenames,
           topicUpdateNarration: context.config.isTopicUpdateNarrationEnabled(),
+          enableGrep: enabledToolNames.has(GREP_TOOL_NAME),
+          enableGlob: enabledToolNames.has(GLOB_TOOL_NAME),
         })),
         subAgents: this.withSection('agentContexts', () =>
           context.config

packages/core/src/prompts/snippets.ts

@@ -17,12 +17,7 @@ import {
   SHELL_TOOL_NAME,
   WRITE_FILE_TOOL_NAME,
   WRITE_TODOS_TOOL_NAME,
-  GREP_PARAM_TOTAL_MAX_MATCHES,
-  GREP_PARAM_INCLUDE_PATTERN,
-  GREP_PARAM_EXCLUDE_PATTERN,
   GREP_PARAM_CONTEXT,
-  GREP_PARAM_BEFORE,
-  GREP_PARAM_AFTER,
   SHELL_PARAM_IS_BACKGROUND,
   EDIT_PARAM_OLD_STRING,
   TRACKER_CREATE_TASK_TOOL_NAME,
@@ -59,6 +54,8 @@ export interface CoreMandatesOptions {
   hasHierarchicalMemory: boolean;
   contextFilenames?: string[];
   topicUpdateNarration: boolean;
+  enableGrep: boolean;
+  enableGlob: boolean;
 }
 
 export interface PrimaryWorkflowsOptions {
@@ -175,6 +172,16 @@ export function renderCoreMandates(options?: CoreMandatesOptions): string {
           .join(', ') + ` or \`${filenames[filenames.length - 1]}\``
       : `\`${filenames[0]}\``;
 
+  const grepMention = options.enableGrep
+    ? ` Use context (\`${GREP_PARAM_CONTEXT}\`, etc.) with \`${GREP_TOOL_NAME}\` to avoid a separate \`${READ_FILE_TOOL_NAME}\` turn before editing.`
+    : '';
+  const grepEditExample = options.enableGrep
+    ? `\n- **Grep & Edit:** Use \`${GREP_TOOL_NAME}\` with context to skip \`${READ_FILE_TOOL_NAME}\` before an edit.`
+    : '';
+  const unambiguousEditsGrep = options.enableGrep
+    ? ` or \`${GREP_TOOL_NAME}\``
+    : '';
+
   // ⚠️ IMPORTANT: the Context Efficiency changes strike a delicate balance that encourages
   // the agent to minimize response sizes while also taking care to avoid extra turns. You
   // must run the major benchmarks, such as SWEBench, prior to committing any changes to
@@ -199,27 +206,22 @@ Consider the following when estimating the cost of your approach:
 
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
-- Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to ${GREP_TOOL_NAME}, to enable you to skip using an extra turn reading the file.
-- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`${SHELL_TOOL_NAME}\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
-- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
-- **Avoid Redundancy:** DO NOT use \`${READ_FILE_TOOL_NAME}\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
-- **AST-Aware Outlines:** Use \`tilth <path>\` via \`${SHELL_TOOL_NAME}\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
-- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
-- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
-- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like ${READ_FILE_TOOL_NAME} and ${GREP_TOOL_NAME}.
-- ${READ_FILE_TOOL_NAME} fails if ${EDIT_PARAM_OLD_STRING} is ambiguous, causing extra turns. Take care to read enough with ${READ_FILE_TOOL_NAME} and ${GREP_TOOL_NAME} to make the edit unambiguous.
-- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
-- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
+- **Combine Turns:** Parallelize independent tool calls.${grepMention}
+- **Tilth (Primary Tool):** Prefer \`tilth\` (via \`${SHELL_TOOL_NAME}\`) for discovery AND understanding. It is AST-aware and recursive.
+  - \`tilth <query>\`: Find symbols, paths, globs, or text with structural context.
+  - \`tilth <path>\`: See a "smart view" skeleton (imports, types, signatures) or use \`--section\`/\`--full\` for targeted/complete reads.
+  - \`tilth --map\`: Build a "big picture" structural map of the codebase.
+- **Token Management:** Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) and \`--scope <dir>\` to avoid context bloat. DO NOT re-read files if \`tilth\` already showed the content.
+- **Unambiguous Edits:** Ensure \`${READ_FILE_TOOL_NAME}\`${unambiguousEditsGrep} outputs enough context to make \`${EDIT_PARAM_OLD_STRING}\` unique, avoiding failures and wasted turns.
+- **Quality over Speed:** Technical integrity is paramount; efficiency is essential but secondary to correctness.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`${SHELL_TOOL_NAME}\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
-- **Symbol Exploration:** Use \`${SHELL_TOOL_NAME}\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
-- **Searching:** utilize search tools like ${GREP_TOOL_NAME} and ${GLOB_TOOL_NAME} with a conservative result count (\`${GREP_PARAM_TOTAL_MAX_MATCHES}\`) and a narrow scope (\`${GREP_PARAM_INCLUDE_PATTERN}\` and \`${GREP_PARAM_EXCLUDE_PATTERN}\` parameters).
-- **Searching and editing:** utilize search tools like ${GREP_TOOL_NAME} with a conservative result count and a narrow scope. Use \`${GREP_PARAM_CONTEXT}\`, \`${GREP_PARAM_BEFORE}\`, and/or \`${GREP_PARAM_AFTER}\` to request enough context to avoid the need to read the file before editing matches.
-- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** Use \`${SHELL_TOOL_NAME}\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
-- **Navigating:** read the minimum required to not require additional turns spent reading the file.
+- **Initial Discovery:** \`${SHELL_TOOL_NAME}\` to run \`tilth --map --budget 2000\` for a structural overview of the project.
+- **Symbol Exploration:** \`tilth <symbol> --budget 1500\` to find definitions/usages with structural context in one turn.
+- **File Skeleton:** \`tilth <path> --budget 1500\` to see a file's skeleton before targeted reads.${grepEditExample}
+- **Large Files:** Use \`tilth <path> --section 45-89\` or \`--section "## Architecture"\` for precise, budgeted reads.
+- **Complete Read:** \`tilth <path> --full\` when the entire file is needed and fits in context.
 </examples>
 
 ## Engineering Standards
@@ -660,14 +662,14 @@ function workflowStepResearch(options: PrimaryWorkflowsOptions): string {
   if (searchTools.length > 0) {
     const toolsStr = searchTools.join(' and ');
     const toolOrTools = searchTools.length > 1 ? 'tools' : 'tool';
-    searchSentence = ` Use the \`tilth\` CLI command (for structural maps and symbol discovery), ${toolsStr} search ${toolOrTools} extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.`;
+    searchSentence = ` Use the \`tilth\` CLI command (for structural maps, symbol discovery, and AST-aware outlines), ${toolsStr} search ${toolOrTools} extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.`;
   }
 
   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 the \`tilth\` CLI command or ${toolsStr} directly in parallel.`;
+      subAgentSearch = ` For **simple, targeted searches** (like finding a specific symbol, file path, glob, or text), use the \`tilth\` CLI command or ${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}`;

packages/core/src/services/shellExecutionService.ts

@@ -398,8 +398,8 @@ export class ShellExecutionService {
         [GEMINI_CLI_IDENTIFICATION_ENV_VAR]:
           GEMINI_CLI_IDENTIFICATION_ENV_VAR_VALUE,
         TERM: 'xterm-256color',
-        PAGER: 'cat',
-        GIT_PAGER: 'cat',
+        PAGER: isWindows ? 'cat' : 'sh -c "cat" sh',
+        GIT_PAGER: isWindows ? 'cat' : 'sh -c "cat" sh',
       };
 
       const {
@@ -737,12 +737,15 @@ export class ShellExecutionService {
       const guardedCommand = ensurePromptvarsDisabled(commandToExecute, shell);
       const args = [...argsPrefix, guardedCommand];
 
+      const isWindows = os.platform() === 'win32';
       const env = {
         ...process.env,
         GEMINI_CLI: '1',
         TERM: 'xterm-256color',
-        PAGER: shellExecutionConfig.pager ?? 'cat',
-        GIT_PAGER: shellExecutionConfig.pager ?? 'cat',
+        PAGER:
+          shellExecutionConfig.pager ?? (isWindows ? 'cat' : 'sh -c "cat" sh'),
+        GIT_PAGER:
+          shellExecutionConfig.pager ?? (isWindows ? 'cat' : 'sh -c "cat" sh'),
       };
 
       // Specifically allow GIT_CONFIG_* variables to pass through sanitization

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

@@ -5,7 +5,7 @@ exports[`ShellTool > getDescription > should return the non-windows description
 
       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\`).
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\` on Windows or \`PAGER='sh -c "cat" sh'\` on other platforms).
 
       The following information is returned:
 
@@ -22,7 +22,7 @@ exports[`ShellTool > getDescription > should return the windows description when
 
       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\`).
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\` on Windows or \`PAGER='sh -c "cat" sh'\` on other platforms).
 
       The following information is returned:
 
@@ -39,7 +39,7 @@ exports[`ShellTool > getSchema > should return the base schema when no modelId i
 
       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\`).
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\` on Windows or \`PAGER='sh -c "cat" sh'\` on other platforms).
 
       The following information is returned:
 
@@ -56,7 +56,7 @@ exports[`ShellTool > getSchema > should return the schema from the resolver when
 
       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\`).
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\` on Windows or \`PAGER='sh -c "cat" sh'\` on other platforms).
 
       The following information is returned:
 

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

@@ -570,7 +570,7 @@ exports[`coreTools snapshots for specific models > Model: gemini-2.5-pro > snaps
 
       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\`).
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\` on Windows or \`PAGER='sh -c "cat" sh'\` on other platforms).
 
       The following information is returned:
 
@@ -1335,7 +1335,7 @@ exports[`coreTools snapshots for specific models > Model: gemini-3-pro-preview >
 
       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\`).
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\` on Windows or \`PAGER='sh -c "cat" sh'\` on other platforms).
 
       The following information is returned:
 

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

@@ -37,7 +37,7 @@ export function getShellToolDescription(
 
       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\`).`
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\` on Windows or \`PAGER='sh -c "cat" sh'\` on other platforms).`
     : '';
 
   const returnedInfo = `

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

@@ -284,7 +284,7 @@ describe('ShellTool', () => {
         expect.any(AbortSignal),
         false,
         expect.objectContaining({
-          pager: 'cat',
+          pager: os.platform() === 'win32' ? 'cat' : 'sh -c "cat" sh',
           sanitizationConfig: {},
           sandboxManager: expect.any(Object),
         }),
@@ -313,7 +313,7 @@ describe('ShellTool', () => {
         expect.any(AbortSignal),
         false,
         expect.objectContaining({
-          pager: 'cat',
+          pager: os.platform() === 'win32' ? 'cat' : 'sh -c "cat" sh',
           sanitizationConfig: {},
           sandboxManager: expect.any(Object),
         }),
@@ -338,7 +338,7 @@ describe('ShellTool', () => {
         expect.any(AbortSignal),
         false,
         expect.objectContaining({
-          pager: 'cat',
+          pager: os.platform() === 'win32' ? 'cat' : 'sh -c "cat" sh',
           sanitizationConfig: {},
           sandboxManager: expect.any(Object),
         }),
@@ -388,7 +388,7 @@ describe('ShellTool', () => {
           expect.any(AbortSignal),
           false,
           {
-            pager: 'cat',
+            pager: os.platform() === 'win32' ? 'cat' : 'sh -c "cat" sh',
             sanitizationConfig: {},
             sandboxManager: new NoopSandboxManager(),
           },

packages/core/src/tools/shell.ts

@@ -274,7 +274,7 @@ export class ShellToolInvocation extends BaseToolInvocation<
           this.context.config.getEnableInteractiveShell(),
           {
             ...shellExecutionConfig,
-            pager: 'cat',
+            pager: os.platform() === 'win32' ? 'cat' : 'sh -c "cat" sh',
             sanitizationConfig:
               shellExecutionConfig?.sanitizationConfig ??
               this.context.config.sanitizationConfig,