Stronger tilth guidance.

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

@@ -11,6 +11,7 @@ import {
   GREP_TOOL_NAME,
   LS_TOOL_NAME,
   READ_FILE_TOOL_NAME,
+  SHELL_TOOL_NAME,
 } from '../tools/tool-names.js';
 import { DEFAULT_GEMINI_MODEL } from '../config/models.js';
 import { makeFakeConfig } from '../test-utils/config.js';
@@ -50,6 +51,7 @@ describe('CodebaseInvestigatorAgent', () => {
       READ_FILE_TOOL_NAME,
       GLOB_TOOL_NAME,
       GREP_TOOL_NAME,
+      SHELL_TOOL_NAME,
     ]);
   });
 

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

@@ -10,6 +10,7 @@ import {
   GREP_TOOL_NAME,
   LS_TOOL_NAME,
   READ_FILE_TOOL_NAME,
+  SHELL_TOOL_NAME,
 } from '../tools/tool-names.js';
 import {
   DEFAULT_THINKING_MODE,
@@ -114,12 +115,13 @@ export const CodebaseInvestigatorAgent = (
     },
 
     toolConfig: {
-      // Grant access only to read-only tools.
+      // Grant access only to read-only tools and the shell for structural analysis.
       tools: [
         LS_TOOL_NAME,
         READ_FILE_TOOL_NAME,
         GLOB_TOOL_NAME,
         GREP_TOOL_NAME,
+        SHELL_TOOL_NAME,
       ],
     },
 
@@ -131,6 +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\`), 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.
@@ -141,7 +144,7 @@ You operate in a non-interactive loop and must reason based on the information p
 ---
 ## Core Directives
 <RULES>
-1.  **DEEP ANALYSIS, NOT JUST FILE FINDING:** Your goal is to understand the *why* behind the code. Don't just list files; explain their purpose and the role of their key components. Your final report should empower another agent to make a correct and complete fix.
+1.  **DEEP ANALYSIS, NOT JUST FILE FINDING:** Your goal is to understand the *why* behind the code. Don't just list files; explain their purpose and the role of their key components. Use \`tilth\` for structural awareness and to find definitions quickly. Your final report should empower another agent to make a correct and complete fix.
 2.  **SYSTEMATIC & CURIOUS EXPLORATION:** Start with high-value clues (like tracebacks or ticket numbers) and broaden your search as needed. Think like a senior engineer doing a code review. An initial file contains clues (imports, function calls, puzzling logic). **If you find something you don't understand, you MUST prioritize investigating it until it is clear.** Treat confusion as a signal to dig deeper.
 3.  **HOLISTIC & PRECISE:** Your goal is to find the complete and minimal set of locations that need to be understood or changed. Do not stop until you are confident you have considered the side effects of a potential fix (e.g., type errors, breaking changes to callers, opportunities for code reuse).
 4.  **Web Search:** You are allowed to use the \`web_fetch\` tool to research libraries, language features, or concepts you don't understand (e.g., "what does gettext.translation do with localedir=None?").
@@ -167,7 +170,8 @@ When you are finished, you **MUST** call the \`complete_task\` tool. The \`repor
 {
   "SummaryOfFindings": "The core issue is a race condition in the \`updateUser\` function. The function reads the user's state, performs an asynchronous operation, and then writes the state back. If another request modifies the user state during the async operation, that change will be overwritten. The fix requires implementing a transactional read-modify-write pattern, potentially using a database lock or a versioning system.",
   "ExplorationTrace": [
-    "Used \`grep\` to search for \`updateUser\` to locate the primary function.",
+    "Used \`tilth --map\` to understand the overall project structure.",
+    "Used \`tilth updateUser\` to locate the primary function definition.",
     "Read the file \`src/controllers/userController.js\` to understand the function's logic.",
     "Used ${listCommand} to look for related files, such as services or database models.",
     "Read \`src/services/userService.js\` and \`src/models/User.js\` to understand the data flow and how state is managed."

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

@@ -22,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -193,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -483,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -654,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -728,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 \`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.**
@@ -825,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -869,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 \`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.**
@@ -948,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -992,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 \`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.**
@@ -1544,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -1631,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 \`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.**
@@ -1711,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -1785,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 \`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.**
@@ -1869,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -1943,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 \`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.**
@@ -2027,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -2101,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 \`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.**
@@ -2181,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -2255,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 \`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.**
@@ -2335,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -2409,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 \`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.**
@@ -2481,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -2634,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -2708,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 \`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.**
@@ -2912,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -2986,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 \`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.**
@@ -3318,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -3392,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 \`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.**
@@ -3472,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -3546,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 \`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.**
@@ -3738,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -3812,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 \`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.**
@@ -3892,21 +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.
-- Prefer using tools like grep_search to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -3966,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 \`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 `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,14 +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,
-  READ_FILE_PARAM_START_LINE,
-  READ_FILE_PARAM_END_LINE,
   SHELL_PARAM_IS_BACKGROUND,
   EDIT_PARAM_OLD_STRING,
   TRACKER_CREATE_TASK_TOOL_NAME,
@@ -61,6 +54,8 @@ export interface CoreMandatesOptions {
   hasHierarchicalMemory: boolean;
   contextFilenames?: string[];
   topicUpdateNarration: boolean;
+  enableGrep: boolean;
+  enableGlob: boolean;
 }
 
 export interface PrimaryWorkflowsOptions {
@@ -177,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
@@ -201,21 +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.
-- Prefer using tools like ${GREP_TOOL_NAME} to identify points of interest instead of reading lots of files individually.
-- 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>
-- **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:** utilize search tools like ${GREP_TOOL_NAME} and/or ${READ_FILE_TOOL_NAME} called in parallel with '${READ_FILE_PARAM_START_LINE}' and '${READ_FILE_PARAM_END_LINE}' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
-- **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
@@ -656,17 +662,17 @@ function workflowStepResearch(options: PrimaryWorkflowsOptions): string {
   if (searchTools.length > 0) {
     const toolsStr = searchTools.join(' and ');
     const toolOrTools = searchTools.length > 1 ? 'tools' : 'tool';
-    searchSentence = ` Use ${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 ${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}`;
+    return `1. **Research:** Systematically map the codebase and validate assumptions. Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery when the task involves **complex refactoring, codebase exploration or system-wide analysis**. ${subAgentSearch} Use ${formatToolName(READ_FILE_TOOL_NAME)} to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;
   }
 
   return `1. **Research:** Systematically map the codebase and validate assumptions.${searchSentence} 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,