agy-context-saver 1.8.0 → 1.8.1

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to `Agy-Context-Saver` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.8.1] - 2026-10-16
+
+### Added
+- **Hybrid `view_file` Slice Governance (`scripts/execution-guard-hook.mjs`)**: Retains the 150-line default slice ceiling (`1–150` lines allowed; partial slices of `151–800` lines denied) while adding a guarded full-file audit exception: explicit `StartLine: 1, EndLine: <TotalFileLines>` reads are permitted when the file on disk is $\le 800$ lines and $\le 45\text{ KiB}$ (`46,080` bytes). `.system_generated/` protections continue to take unconditional precedence.
+- **Waymark-First Denial Routing**: When `waymark-engine` is installed, `view_file` hook denials now recommend `waymark_ask(..., plain: true)` across all 23 supported formats followed by a bounded `view_file(StartLine, EndLine)` slice, falling back to `rtk read` when Waymark is unavailable.
+
+### Changed
+- **Single-Source-of-Truth MCP Instructions (`scripts/install-register.mjs`)**: Replaced the hardcoded pre-v1.7 `instructions.md` template in `install-register.mjs` with a direct read of `mcp/instructions.md`, eliminating the split-brain discrepancy between repository docs and `~/.gemini/antigravity/mcp/agy-context-saver/instructions.md`.
+- **Unified 3-Tier Inspection Documentation**: Reconciled `README.md`, `mcp/instructions.md`, `rules/AGENTS.md`, `skills/context-governance/SKILL.md`, `mcp/index.js`, and `docs/*.md` around the 3-tier hierarchy (`waymark_ask(..., plain: true)` $\to$ hybrid `view_file` $\to$ `rtk` for spillovers, task logs, and directory/prose search) and standardized references to all 10 automated test files.
+
+### Fixed
+- **Inline `read_transcript` Payload Cap (`mcp/index.js`)**: Bounded `compact` mode transcript output to `3,800` characters (`< 4 KB`) and clamped intermediate non-dialogue step bodies so `read_transcript(mode: "compact")` never triggers an Antigravity host spillover file.
+- **Complete `query_transcript` Role Schema**: Documented `'subagent'` in the `roles` filter description across `mcp/index.js`, `scripts/install-register.mjs`, `skills/context-governance/SKILL.md`, and `docs/tools.md`.
+
+---
+
 ## [1.8.0] - 2026-10-15
 
 ### Removed

package/README.md

@@ -18,7 +18,7 @@ It permanently eliminates session degradation, memory bloat, and context window
 | Metric / Capability | Without Governor | With Agy-Context-Saver + RTK |
 | :--- | :--- | :--- |
 | **Command Output Bloat** | Unlimited raw test dots, ANSI dumps | RTK transparent reduction (60–90% token savings) |
-| **Workspace File Inspection** | Massive uncompressed view_file dumps | Compact `rtk read`, `rtk grep`, `rtk find` |
+| **Workspace File Inspection** | Massive uncompressed `view_file` dumps | `waymark_ask(..., plain: true)` $\to$ bounded `view_file` slices ($\le 150$ lines) + `rtk find` / `rtk rg` |
 | **Long Command Execution** | Detached after 5s $\to$ busy-wait loop | Synchronous window expanded to 10s $\to$ finishes in-turn |
 | **Background Task Monitoring** | Repetitive busy-polling loops | Enforced Reactive Wakeup with 5-strike circuit breaker |
 | **Configuration Safety** | Risk of third-party config clobber | Non-destructive preservation of foreign hooks/MCP with `.bak` backups |
@@ -30,7 +30,7 @@ It permanently eliminates session degradation, memory bloat, and context window
 ## Canonical 3-Layer Governance Architecture
 
 1. **Layer 1: Reactive Lifecycle & Polling Immunity**: Replaces destructive busy-polling loops with native Antigravity **Reactive Wakeup**, governed by an exponential Proportional Backoff curve and a 5-strike circuit breaker.
-2. **Layer 2: Transparent CLI & Codebase Streamlining**: Intercepts shell execution via PreToolUse hooks, transparently rewriting commands to RTK (`rtk git`, `rtk pytest`), hard-routing workspace searches to `rtk read`/`find`/`rg`, and shielding internal `.system_generated` state.
+2. **Layer 2: Transparent CLI & Codebase Streamlining**: Intercepts shell execution via PreToolUse hooks, transparently rewriting commands to RTK (`rtk git`, `rtk pytest`), enforcing bounded `view_file` slices paired with `waymark_ask(..., plain: true)`, routing spillovers/task logs to `rtk read` and directory/prose searches to `rtk find`/`rg`, and shielding internal `.system_generated` state.
 3. **Layer 3: Synchronous Execution**: Expands synchronous execution windows to 10s so routine commands finish in-turn instead of detaching.
 
 > **Subagent tools moved.** `subagent_brief` and squad dispatch now live in the separate [Agy-Squad](https://github.com/paragon-ux/agy-squad) package (under construction). Agy-Context-Saver is complete without them, and the two will install side by side.
@@ -107,24 +107,27 @@ npm run status
 1. **The Polling Trap**: When shell tasks detach to background jobs (`task-XYZ`), agents waste tokens repeatedly polling `manage_task(Action='status')` or scheduling artificial timers. Agy enforces native **Reactive Wakeup** (`<SYSTEM_MESSAGE>`).
 2. **The Terminal Bloat Trap**: Routine test runs and git operations dump hundreds of lines of noise into context. RTK compresses these outputs natively before they enter model context.
 3. **The Raw Transcript Trap**: Reading `transcript.jsonl` dumps megabytes of raw JSON into context. Agy blocks direct reads of `.system_generated` and provides high-density Markdown streaming tools.
-4. **Native Inspection Bypass**: Native inspection tools (`view_file`, `grep_search`, `find_by_name`, `list_dir`) bypass token reduction. Agy hard-routes workspace inspection to RTK's canonical CLI (`rtk read`, `rtk grep`, `rtk find`, `rtk ls`).
+4. **Native Inspection Bypass**: Unbounded native inspection tools (`view_file` without slices, `grep_search`, `find_by_name`, `list_dir`) bypass token reduction. Agy enforces bounded `view_file` slices (`StartLine` / `EndLine <= 150`, paired with `waymark_ask(..., plain: true)`) and routes directory/prose search and spillover reads to RTK's canonical CLI (`rtk find`, `rtk rg`, `rtk grep`, `rtk read`).
 
 ---
 
 ## Key Capabilities
 
 - **Transparent RTK Rewriting**: Native `run_command` calls are automatically rewritten (e.g. `pytest` $\to$ `rtk pytest`) via Antigravity PreToolUse hooks.
-- **Canonical Codebase Inspection**:
-  - `rtk read <file>`: Read file with intelligent token filtering and line ranges.
-  - `rtk find <path>`: Compact file search tree and directory listing (cross-platform, works on Windows & POSIX).
-  - Search by platform:
-    - **Windows**: `rtk rg "<pattern>" .` (explicit target `.` prevents child process stdin stalls) or `rg "<pattern>" .`.
-    - **POSIX / Linux / macOS**: `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
-  - Directory listing by platform:
-    - **Windows**: `rtk find <path>` or PowerShell `dir` / `Get-ChildItem`. (Avoid `rtk ls` / `rtk tree` on Windows as they rely on POSIX binaries/flags).
-    - **POSIX / Linux / macOS**: `rtk ls <path>` or `rtk tree`.
-  - `rtk err <cmd>`: Run command and show only errors/warnings.
-  - `rtk summary <cmd>`: Run command and produce a 2-line heuristic summary.
+- **Unified 3-Tier Codebase & File Inspection**:
+  1. **Tier 1 — Structural Discovery (`waymark_ask(..., plain: true)`)**: Locate exact `[StartLine, EndLine]` coordinates across all 23 supported formats (code ASTs + `markdown`, `yaml`, `json`, `toml`, `bash`) in ~19–466 tokens.
+  2. **Tier 2 — Precision Workspace Reading (`view_file` Hybrid Slice Policy)**: Pass `StartLine` and `EndLine` (`1–150` lines default; or explicit `StartLine: 1, EndLine: <TotalLines>` full-file audit when $\le 800$ lines and $\le 45\text{ KiB}$) into `view_file` to preserve 1-indexed line numbers for `replace_file_content` without terminal stdout truncation.
+  3. **Tier 3 — RTK CLI Boundaries**:
+     - `rtk read <path>`: Inspect runtime step spillovers (`.system_generated/steps/<step>/output.txt`) and completed background task logs (`tasks/<taskId>.log`) with `--head-lines` / `--tail-lines`.
+     - `rtk find <path>`: Compact file search tree and directory listing (cross-platform, works on Windows & POSIX).
+     - Prose / Regex Search (when symbol, heading, or config key is unknown):
+       - **Windows**: `rtk rg "<pattern>" .` (explicit target `.` prevents child process stdin stalls) or `rg "<pattern>" .`.
+       - **POSIX / Linux / macOS**: `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
+     - Directory listing by platform:
+       - **Windows**: `rtk find <path>` or PowerShell `dir` / `Get-ChildItem`. (Avoid `rtk ls` / `rtk tree` on Windows as they rely on POSIX binaries/flags).
+       - **POSIX / Linux / macOS**: `rtk ls <path>` or `rtk tree`.
+     - `rtk err <cmd>`: Run command and show only errors/warnings.
+     - `rtk summary <cmd>`: Run command and produce a 2-line heuristic summary.
 - **Antigravity Special Files Safe Harbor**: Direct `view_file` access to `SKILL.md`, brain artifacts, and config files is preserved.
 - **Protected Internal State**: Root-based guard prevents reading `.system_generated/` (transcripts, task logs, progress).
 - **Session-Wide Lifecycle Ledger**: Polling checks are tracked globally per session; changing task IDs or waiting does not reset governance.

package/mcp/index.js

@@ -80,7 +80,7 @@ if (isEntryPoint) {
 
 function printHelp() {
   console.log(`
-Agy-Context-Saver 🛡️ (v1.8.0)
+Agy-Context-Saver 🛡️ (v1.8.1)
 Universal MCP Server & Lifecycle Governor for Google Antigravity (Powered by RTK)
 
 Usage:
@@ -107,19 +107,17 @@ MCP Server Stdio Mode:
 
 Testing & Verification Playbook:
   npm run status               Verify live 4-layer integration status
-  npm test                     Run complete 5-suite automated test suite
-  node tests/test-hook.mjs     Run 28 closed-topology governance rule tests
+  npm test                     Run complete 10-suite automated test suite
+  node tests/test-hook.mjs     Run 27 closed-topology governance rule tests
   node tests/test-mcp.mjs      Run MCP protocol, method, and schema tests
 
-Platform-Aware Inspection Directives (RTK):
-  Windows:
-    - Search:     rtk rg "<pattern>" .   (trailing dot is required to prevent stdin pipe stalls)
-    - Read:       rtk read <file>
-    - Directory:  rtk find <path>        (cross-platform; avoids missing ls.exe)
-  POSIX (macOS/Linux):
-    - Search:     rtk grep "<pattern>"  or  rtk rg "<pattern>"
-    - Read:       rtk read <file>
-    - Directory:  rtk ls <path>         or  rtk tree
+Unified 3-Tier Inspection Directives (Waymark + Hybrid view_file + RTK):
+  Tier 1 (Structure):  waymark_ask(..., plain: true) across all 23 supported formats
+  Tier 2 (Read/Edit):  view_file(StartLine, EndLine) (1-150L default; or explicit 1..TotalLines full-file audit <= 800L & <= 45 KiB)
+  Tier 3 (RTK CLI):
+    - Spillovers/Logs: rtk read <path> (--head-lines / --tail-lines)
+    - Directory:       rtk find <path> (Windows & POSIX) or rtk ls <path> (POSIX)
+    - Prose Search:    rtk rg "<pattern>" . (Windows trailing dot required) or rtk grep "<pattern>" (POSIX)
 `);
 }
 
@@ -127,7 +125,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rulesPath = path.resolve(__dirname, "../rules/AGENTS.md");
 
 const SERVER_NAME = "agy-context-saver";
-const SERVER_VERSION = "1.8.0";
+const SERVER_VERSION = "1.8.1";
 
 // --- Tools Specification ---
 const TOOLS = [
@@ -200,7 +198,7 @@ const TOOLS = [
   },
   {
     name: "query_transcript",
-    description: "Granular query and forensic filtering engine for Antigravity conversation transcripts. Searches by keyword or regex, filters by role (user, assistant, tool, error), slices step ranges, and automatically dereferences full content when truncated.",
+    description: "Granular query and forensic filtering engine for Antigravity conversation transcripts. Searches by keyword or regex, filters by role (user, assistant, subagent, tool, error), slices step ranges, and automatically dereferences full content when truncated.",
     inputSchema: {
       type: "object",
       properties: {
@@ -215,7 +213,7 @@ const TOOLS = [
         roles: {
           type: "array",
           items: { type: "string" },
-          description: "Filter steps by role/source: 'user', 'assistant', 'tool', 'error', or 'all' (default: ['user', 'assistant'])."
+          description: "Filter steps by role/source: 'user', 'assistant', 'subagent', 'tool', 'error', or 'all' (default: ['user', 'assistant'])."
         },
         mode: {
           type: "string",
@@ -811,13 +809,20 @@ async function handleReadTranscript({ conversationId, mode = "compact", lastTurn
   const formattedBlocks = [];
   let currentLength = header.length;
   let clamped = false;
+  const maxWindowChars = mode === "compact" ? 3800 : MAX_OUTPUT_CHARS;
 
   for (let i = selected.length - 1; i >= 0; i--) {
-    const block = formatTranscriptItem(selected[i], {
+    const item = selected[i];
+    const isDialogueTurn =
+      item.type === "USER_INPUT" ||
+      item.type === "PLANNER_RESPONSE" ||
+      item.type === "SUBAGENT_RESPONSE";
+    const block = formatTranscriptItem(item, {
       includeThinking,
-      includeToolCalls: true
+      includeToolCalls: true,
+      maxContentChars: mode === "compact" && !isDialogueTurn ? 300 : MAX_TURN_CHARS
     });
-    if (currentLength + block.length + 6 > MAX_OUTPUT_CHARS) {
+    if (currentLength + block.length + 6 > maxWindowChars && formattedBlocks.length > 0) {
       clamped = true;
       break;
     }
@@ -827,7 +832,8 @@ async function handleReadTranscript({ conversationId, mode = "compact", lastTurn
 
   let fullOutput = header + formattedBlocks.join("\n\n---\n\n");
   if (clamped) {
-    fullOutput += "\n\n... [Transcript display clamped at 24 KB safety ceiling] ...";
+    const ceilingLabel = mode === "compact" ? "3.8 KB inline" : "24 KB";
+    fullOutput += `\n\n... [Transcript display clamped at ${ceilingLabel} safety ceiling; use query_transcript(stepIndex: N) for specific steps] ...`;
   }
 
   return { content: [{ type: "text", text: fullOutput }] };

package/mcp/instructions.md

@@ -11,15 +11,18 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
 2. **Never Read Internal State Directly**:
    - Access to `.system_generated/` via `view_file` is strictly denied to prevent transcript explosion.
    - Use `read_transcript` or `query_transcript` to inspect conversation history cleanly.
-3. **Platform-Aware Codebase Inspection**:
-   - **File Reading**: Prefer `view_file` with bounded slices (`StartLine` and `EndLine`, max 150 lines) to preserve line numbers and avoid terminal truncation.
-   - **Windows Search/Listing**: Use `rtk find <path>` and `rtk rg "<pattern>" .` (the trailing `.` is required to avoid stdin stalls).
-   - **POSIX Search/Listing**: Use `rtk ls <path>` and `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
+3. **Unified 3-Tier Codebase & File Inspection**:
+   - **Tier 1 — Structural Discovery (`waymark_ask` with `plain: true`)**: First locate exact `[StartLine, EndLine]` coordinates via `waymark_ask(..., plain: true)` across all 23 supported formats (code ASTs + `markdown`, `yaml`, `json`, `toml`, `bash`). Always set `plain: true` (~19–466 tokens, zero shell quoting or stdin hazards).
+   - **Tier 2 — Precision Workspace File Reading (`view_file` Hybrid Slice Policy)**: Pass the `StartLine` and `EndLine` span from `waymark_ask` into `view_file` (bounded slices of `1–150` lines) to preserve 1-indexed line coordinates for `replace_file_content` and avoid terminal stdout truncation. Partial slices of `151–800` lines are denied; an explicit one-pass full-file audit (`StartLine: 1, EndLine: <TotalLines>`) is permitted only when the file on disk is $\le 800$ lines and $\le 45\text{ KiB}$ (`46,080` bytes).
+   - **Tier 3 — RTK Boundaries (`rtk read`, `rtk find`, `rtk rg`)**:
+     - **Spillovers & Task Logs**: Read `.system_generated/steps/<step>/output.txt` spillovers and completed `tasks/<taskId>.log` files via `rtk read <path>` (with `--head-lines` / `--tail-lines`). Never use `rtk read -l minimal|aggressive` or `-m` to derive line numbers for edits.
+     - **Directory/File Discovery**: Use `rtk find <path>` (Windows & POSIX) or `rtk ls <path>` (POSIX).
+     - **Prose / Regex Search**: Use `rtk rg "<pattern>" <path>` (explicit `<path>` required on Windows to avoid stdin stalls) strictly for free-text/regex searches inside body prose or string values when the symbol, heading, or config key name is unknown.
 
 ## Available MCP Tools
 - `check_context_health`: Diagnoses transcript turn counts, byte payload, and polling loops. Accepts `transcriptPath` or `conversationId`.
 - `read_transcript`: Streams recent turns from `transcript.jsonl` or `transcript_full.jsonl` formatted as clean Markdown.
-- `query_transcript`: Forensic regex search and filtering engine across transcript steps with optional `summaryOnly: true`.
+- `query_transcript`: Forensic regex search and filtering engine across transcript steps with optional `summaryOnly: true`, plus surgical step extraction via `stepIndex` and `field`.
 - `get_installation_status`: Audits live health of the plugin link, hook, MCP server, tool schemas, and RTK.
 - `sync_installation`: Synchronizes and repairs all 4 integration layers in ~25ms.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-context-saver",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Universal Model Context Protocol (MCP) server & lifecycle governor purpose-built for Google Antigravity",
   "main": "mcp/index.js",
   "bin": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agy-context-saver",
   "displayName": "Antigravity Context Shield & Governor",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Deterministic background polling governor, RTK terminal optimizer, and transcript context shield for Antigravity.",
   "logo": "assets/logo.svg",
   "suggestedPrompts": [

package/rules/AGENTS.md

@@ -30,22 +30,23 @@
 
 ---
 
-## Layer 2: Transparent Shell Execution & Codebase Inspection via RTK
+## Layer 2: Transparent Shell Execution & Unified 3-Tier Codebase Inspection
 - **Native Shell Commands**: Run shell commands normally using `run_command`. The PreToolUse hook transparently rewrites supported commands via RTK (`git`, `pytest`, `cargo`, `npm`, etc.) to produce ultra-compact outputs.
-- **Canonical Codebase Inspection**: Unbounded full-file reads and unoptimized search tools (`grep_search`, `find_by_name`, `list_dir`) are blocked for workspace files. Use bounded slices and RTK's canonical CLI interfaces:
-  - `view_file` with bounded slices (`StartLine` and `EndLine`, max 150 lines): **Preferred for reading files**—preserves 1-indexed line numbers and avoids terminal stdout truncation. Pair with `waymark_ask` to locate exact symbol line ranges first.
-  - `rtk find <path>`: Compact file search tree and directory listings (cross-platform, works on Windows & POSIX).
-  - Search commands by platform:
-    - **Windows**: Use `rtk rg "<pattern>" .` (explicit target `.` is required to prevent stdin pipe hanging) or `rg "<pattern>" .`.
-    - **POSIX / Linux / macOS**: Use `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
-  - Directory listing by platform:
-    - **Windows**: Use `rtk find <path>` or PowerShell `dir` / `Get-ChildItem`. (Avoid `rtk ls` or `rtk tree` on Windows as they rely on POSIX binaries/flags).
-    - **POSIX / Linux / macOS**: Use `rtk ls <path>` or `rtk tree`.
-  - `rtk err <cmd>`: Run command and show only errors/warnings.
-  - `rtk summary <cmd>`: Run command and produce a 2-line heuristic summary.
+- **Canonical 3-Tier Codebase & File Inspection**: Unbounded full-file reads and unoptimized search tools (`grep_search`, `find_by_name`, `list_dir`) are blocked for workspace files. Follow the 3-tier hierarchy:
+  1. **Tier 1 — Structural Discovery (`waymark_ask` with `plain: true`)**: Locate exact `[StartLine, EndLine]` coordinates via `waymark_ask(..., plain: true)` across all 23 supported formats (code ASTs + `markdown`, `yaml`, `json`, `toml`, `bash`). Always pass `plain: true` (~19–466 tokens, zero shell quoting or stdin hazards).
+  2. **Tier 2 — Precision Workspace File Reading (`view_file` Hybrid Slice Policy)**: Pass the exact `StartLine` and `EndLine` from `waymark_ask` into `view_file` (bounded slices of `1–150` lines) to preserve 1-indexed line numbers for `replace_file_content` and avoid terminal stdout truncation. Partial slices of `151–800` lines are denied; an explicit one-pass full-file audit (`StartLine: 1, EndLine: <TotalLines>`) is permitted only when the file on disk is $\le 800$ lines and $\le 45\text{ KiB}$ (`46,080` bytes).
+  3. **Tier 3 — RTK Boundaries (`rtk read`, `rtk find`, `rtk rg`, `rtk err`, `rtk summary`)**:
+     - **Spillovers & Task Logs**: Read `.system_generated/steps/<step>/output.txt` spillovers and completed `tasks/<taskId>.log` files via `rtk read <path>` (with `--head-lines` / `--tail-lines`). Never use `rtk read -l minimal|aggressive` or `-m` to derive line numbers for edits.
+     - **Directory / File Discovery**:
+       - **Windows**: Use `rtk find <path>` or PowerShell `dir` / `Get-ChildItem`. (Avoid `rtk ls` or `rtk tree` on Windows as they rely on POSIX binaries/flags).
+       - **POSIX / Linux / macOS**: Use `rtk find <path>`, `rtk ls <path>`, or `rtk tree`.
+     - **Prose / Regex Search (when symbol, heading, or config key is unknown)**:
+       - **Windows**: Use `rtk rg "<pattern>" .` (explicit target `.` is required to prevent stdin pipe hanging) or `rg "<pattern>" .`.
+       - **POSIX / Linux / macOS**: Use `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
+     - **Command Diagnostics**: `rtk err <cmd>` (errors/warnings only) and `rtk summary <cmd>` (2-line heuristic summary).
 - **Antigravity Special Files Safe Harbor**: Documented Antigravity special files (`SKILL.md`, brain artifacts, `.gemini/config/` configs) are permitted via `view_file` without slice bounds.
 - **Protected Internal State**: Direct native inspection of `.system_generated/` (transcripts, task logs, progress files) is strictly forbidden. Use Agy MCP tools `read_transcript` and `query_transcript`.
-- **Git CRLF/LF Warning Hygiene**: Git's line-ending conversion notices (`warning: LF will be replaced by CRLF the next time Git touches it` / `warning: CRLF will be replaced by LF...`) are non-actionable diagnostic noise. Suppress them during repo operations (via `git -c core.safecrlf=false` or `git config --global core.safecrlf false`) and do not propagate them into subagent briefs, task outputs, or conversation context.
+- **Git CRLF/LF Warning Hygiene**: Git's line-ending conversion notices (`warning: LF will be replaced by CRLF the next time Git touches it` / `warning: CRLF will be replaced by LF...`) are non-actionable diagnostic noise. Suppress them during repo operations (via `git -c core.safecrlf=false` or `git config --global core.safecrlf false`) and do not propagate them into task outputs or conversation context.
 
 ---
 

package/scripts/execution-guard-hook.mjs

@@ -9,10 +9,11 @@
  *    - Intercepts native run_command and calls `rtk rewrite <cmd>`.
  *    - Non-daemon commands maintain WaitMsBeforeAsync=10000 for synchronous completion.
  * 2. Hard-Routed Native File/Search Inspection (LH-07):
- *    - view_file, read_file, read_many_files -> Deny and route to `rtk read <file>`.
- *    - grep_search -> Deny and route to `rtk grep <pattern>`.
+ *    - view_file -> Allow bounded slices (<= 150 lines, paired with waymark_ask); deny unbounded dumps.
+ *    - read_file, read_many_files -> Deny and route to bounded view_file or `rtk read <file>`.
+ *    - grep_search -> Deny and route to `rtk rg "<pattern>" .` / `rtk grep <pattern>`.
  *    - find_by_name -> Deny and route to `rtk find <path>`.
- *    - list_dir -> Deny and route to `rtk ls` or `rtk tree`.
+ *    - list_dir -> Deny and route to `rtk find` (Win) or `rtk ls` / `rtk tree` (POSIX).
  *    - Safe Harbor: Documented Antigravity special files (SKILL.md, brain artifacts, configs) are allowed.
  * 3. Root-Based Antigravity Internal State Protection (LH-02):
  *    - Hard denial for any inspection of `.system_generated/` (transcripts, task logs, progress).
@@ -789,9 +790,56 @@ try {
       respond({ decision: "allow" });
     }
 
-    // 2e. Bounded Slice Safe Harbor for view_file
-    // Allow view_file IF AND ONLY IF it is a bounded slice inspection (StartLine and EndLine <= 150 lines)
+    // 2e. Hybrid Slice & Guarded Full-File Policy for view_file
+    // - 1..150 line slice -> ALLOW
+    // - Explicit full-file read (StartLine=1, EndLine=actualFileLines) of an existing file <= 800 lines AND <= 45 KiB -> ALLOW
+    // - Partial slice of 151..800+ lines -> DENY (discover target with waymark_ask and narrow the slice)
+    // - Explicit full-file read exceeding 800 lines or 45 KiB -> DENY
+    // - Unbounded view_file (missing StartLine/EndLine) -> DENY
     if (toolName === "view_file") {
+      const MAX_SAFE_SLICE_LINES = 150;
+      const MAX_FULL_FILE_LINES = 800;
+      const MAX_FULL_FILE_BYTES = 45 * 1024; // 45 KiB (46,080 bytes)
+
+      const waymarkAvailable = (() => {
+        if (process.env.AGY_FORCE_WAYMARK === "0") return false;
+        if (process.env.AGY_FORCE_WAYMARK === "1") return true;
+        try {
+          const home = process.env.AGY_TEST_PROFILE_DIR || os.homedir();
+          const schemaPath = path.join(home, ".gemini", "antigravity", "mcp", "waymark-engine", "waymark_ask.json");
+          if (fs.existsSync(schemaPath)) return true;
+          const mcpConfigPath = path.join(home, ".gemini", "config", "mcp_config.json");
+          if (fs.existsSync(mcpConfigPath)) {
+            const raw = fs.readFileSync(mcpConfigPath, "utf-8");
+            if (raw.includes('"waymark-engine"')) return true;
+          }
+        } catch {}
+        return false;
+      })();
+
+      const getFileMetrics = (filePath) => {
+        if (!filePath || typeof filePath !== "string") return null;
+        try {
+          if (!fs.existsSync(filePath)) return null;
+          const stat = fs.statSync(filePath);
+          if (!stat.isFile()) return null;
+          const bytes = stat.size;
+          const content = fs.readFileSync(filePath, "utf-8");
+          if (content.length === 0) {
+            return { bytes: 0, lineCount: 0, rawSplitCount: 1 };
+          }
+          const rawSplitCount = content.split(/\r?\n/).length;
+          const lineCount = /\r?\n$/.test(content) ? Math.max(1, rawSplitCount - 1) : rawSplitCount;
+          return { bytes, lineCount, rawSplitCount };
+        } catch {
+          return null;
+        }
+      };
+
+      const discoveryGuidance = waymarkAvailable
+        ? `Locate the target symbol, heading, or config key first with 'waymark_ask(..., plain: true)' and pass a precise bounded slice ('StartLine' and 'EndLine', max ${MAX_SAFE_SLICE_LINES} lines) to 'view_file'`
+        : `Provide bounded slices ('StartLine' and 'EndLine', max ${MAX_SAFE_SLICE_LINES} lines) via 'view_file', or run 'rtk read ${target || "<file>"}' via run_command instead`;
+
       const rawStart = args.StartLine !== undefined ? args.StartLine : args.start_line;
       const rawEnd = args.EndLine !== undefined ? args.EndLine : args.end_line;
       const hasSliceParams = typeof rawStart !== "undefined" || typeof rawEnd !== "undefined";
@@ -809,30 +857,47 @@ try {
           endLine >= startLine
         ) {
           const span = endLine - startLine + 1;
-          const MAX_SAFE_SLICE_LINES = 150;
           if (span <= MAX_SAFE_SLICE_LINES) {
             respond({ decision: "allow" });
           }
+
+          const metrics = startLine === 1 ? getFileMetrics(target) : null;
+          const isExplicitFullFile = Boolean(
+            metrics &&
+              startLine === 1 &&
+              (endLine === metrics.lineCount || endLine === metrics.rawSplitCount)
+          );
+
+          if (isExplicitFullFile) {
+            if (metrics.lineCount <= MAX_FULL_FILE_LINES && metrics.bytes <= MAX_FULL_FILE_BYTES) {
+              respond({ decision: "allow" });
+            }
+            const kib = (metrics.bytes / 1024).toFixed(1);
+            respond({
+              decision: "deny",
+              reason: `Antigravity Governance: Explicit full-file read via 'view_file' (${metrics.lineCount} lines, ${kib} KiB) exceeds the full-file audit ceiling (max ${MAX_FULL_FILE_LINES} lines and 45 KiB). ${discoveryGuidance}.`
+            });
+          }
+
           respond({
             decision: "deny",
-            reason: `Antigravity Governance: Oversized file slice via 'view_file' (${span} lines > ${MAX_SAFE_SLICE_LINES} lines max safe window). Reduce line range or run 'rtk read ${target || "<file>"}' via run_command instead.`
+            reason: `Antigravity Governance: Oversized partial file slice via 'view_file' (${span} lines > ${MAX_SAFE_SLICE_LINES} lines max safe slice window). Partial slices above ${MAX_SAFE_SLICE_LINES} lines are denied; full-file reads are only permitted when explicitly covering line 1 through the actual end of a file <= ${MAX_FULL_FILE_LINES} lines and <= 45 KiB. ${discoveryGuidance}.`
           });
         }
 
         respond({
           decision: "deny",
-          reason: `Antigravity Governance: Invalid slice range via 'view_file'. Ensure StartLine and EndLine are positive integers with EndLine >= StartLine (max 150 lines), or run 'rtk read ${target || "<file>"}' via run_command instead.`
+          reason: `Antigravity Governance: Invalid slice range via 'view_file'. Ensure StartLine and EndLine are positive integers with EndLine >= StartLine. ${discoveryGuidance}.`
         });
       }
 
-      // Default when no slice attempted: guide agent/subagent to use bounded slices or rtk read
       respond({
         decision: "deny",
-        reason: `Antigravity Governance: Full-file inspection via '${toolName}' bypasses token optimization. Provide bounded slices ('StartLine' and 'EndLine', max 150 lines) via 'view_file' to view code with line numbers, or Run 'rtk read ${target || "<file>"}' via run_command instead.`
+        reason: `Antigravity Governance: Full-file inspection via '${toolName}' without explicit bounds is denied. ${discoveryGuidance} (or pass explicit StartLine=1, EndLine=<TotalLines> for a one-pass audit when the file is <= ${MAX_FULL_FILE_LINES} lines and <= 45 KiB).`
       });
     }
 
-    // 2f. Hard-Route Full-File / Other Workspace Code Inspection to Canonical RTK Commands (LH-07)
+    // 2f. Hard-Route Other Native File/Search Tools (LH-07)
     if (toolName === "read_file") {
       respond({
         decision: "deny",

package/scripts/install-register.mjs

@@ -358,38 +358,8 @@ export async function runInstall(options = {}) {
     log(`[OK] Removed legacy temp-folder state: ${legacy}`);
   }
 
-  const instructionsContent = `# Agy-Context-Saver MCP Server Instructions
-
-## Overview
-Agy-Context-Saver is the universal Model Context Protocol server and lifecycle governor for Google Antigravity, paired with RTK (Rust Token Killer) for transparent CLI output reduction.
-
-## Core Rules for Antigravity Agents
-1. **Reactive Wakeup (Zero Task Polling)**:
-   - When background tasks run, DO NOT call \`manage_task(Action='status')\` or \`schedule\` polling timers.
-   - Stop calling tools and yield the turn. The system notifies you automatically via \`<SYSTEM_MESSAGE>\`.
-   - Repeated polling triggers an escalating circuit breaker (frozen at 5 denials).
-2. **Never Read Internal State Directly**:
-   - Access to \`.system_generated/\` via \`view_file\` is strictly denied to prevent transcript explosion.
-   - Use \`read_transcript\` or \`query_transcript\` to inspect conversation history cleanly.
-3. **Inspect Output Files Directly with RTK**:
-   - Runtime step output spillovers (\`.system_generated/steps/<step>/output.txt\`) and completed background task logs (\`tasks/<taskId>.log\`) are read directly via \`rtk read <path>\` under hook governance.
-4. **Platform-Aware Codebase Inspection**:
-   - **Windows**: Use \`rtk read <file>\`, \`rtk find <path>\`, and \`rtk rg "<pattern>" .\` (the trailing \`.\` is required to avoid stdin stalls).
-   - **POSIX**: Use \`rtk read <file>\`, \`rtk ls <path>\`, and \`rtk grep "<pattern>"\` or \`rtk rg "<pattern>"\`.
-
-## Available MCP Tools
-- \`check_context_health\`: Diagnoses transcript turn counts, byte payload, and polling loops. Accepts \`transcriptPath\` or \`conversationId\`.
-- \`read_transcript\`: Streams recent turns from \`transcript.jsonl\` or \`transcript_full.jsonl\` formatted as clean Markdown.
-- \`query_transcript\`: Forensic regex search and filtering engine across transcript steps with optional \`summaryOnly: true\`, and surgical step extraction via \`stepIndex\` and \`field\`.
-- \`get_installation_status\`: Audits live health of the plugin link, hook, MCP server, tool schemas, and RTK.
-- \`sync_installation\`: Synchronizes and repairs all 4 integration layers in ~25ms.
-
-## Diagnostic & CLI Playbook
-- Audit Status: \`npm run status\` or \`node mcp/index.js status\`
-- Run Test Suite: \`npm test\`
-- CLI Help: \`node mcp/index.js --help\`
-- ⚠️ Warning: Do not run \`npm start\` or \`node mcp/index.js\` without subcommands interactively (it is a stdio JSON-RPC server).
-`;
+  const instructionsSourcePath = path.join(repoRoot, "mcp", "instructions.md");
+  const instructionsContent = await fsPromises.readFile(instructionsSourcePath, "utf-8");
 
   const checkHealthSchema = {
     name: "check_context_health",
@@ -464,7 +434,7 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
 
   const queryTranscriptSchema = {
     name: "query_transcript",
-    description: "Granular query and forensic filtering engine for Antigravity conversation transcripts. Searches by keyword or regex, filters by role (user, assistant, tool, error), slices step ranges, and automatically dereferences full content when truncated.",
+    description: "Granular query and forensic filtering engine for Antigravity conversation transcripts. Searches by keyword or regex, filters by role (user, assistant, subagent, tool, error), slices step ranges, and automatically dereferences full content when truncated.",
     parameters: {
       type: "object",
       properties: {
@@ -479,7 +449,7 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
         roles: {
           type: "array",
           items: { type: "string" },
-          description: "Filter steps by role/source: 'user', 'assistant', 'tool', 'error', or 'all' (default: ['user', 'assistant'])."
+          description: "Filter steps by role/source: 'user', 'assistant', 'subagent', 'tool', 'error', or 'all' (default: ['user', 'assistant'])."
         },
         mode: {
           type: "string",

package/skills/context-governance/SKILL.md

@@ -16,20 +16,24 @@ Agy-Context-Saver and RTK protect session transcript health and LLM attention by
 
 ---
 
-## Codebase Inspection via RTK
+## Unified 3-Tier Codebase & File Inspection
 
 Unbounded full-file `view_file` calls and unoptimized search tools (`grep_search`, `find_by_name`, `list_dir`) bypass token compression and are guarded:
 
-- `view_file` with bounded slices (`StartLine` and `EndLine`, max 150 lines): **Preferred for reading files**—returns exact 1-indexed line numbers without terminal stdout truncation.
-- `rtk find <path>`: Compact file search tree and directory listings (cross-platform, works on Windows & POSIX).
-- Search commands by platform:
-  - **Windows**: Use `rtk rg "<pattern>" .` (explicit target `.` is required to avoid child process stdin pipe stalls) or `rg "<pattern>" .`.
-  - **POSIX / Linux / macOS**: Use `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
-- Directory listing by platform:
-  - **Windows**: Use `rtk find <path>` or PowerShell `dir` / `Get-ChildItem`. (Avoid `rtk ls` or `rtk tree` on Windows as they rely on POSIX binaries/flags).
-  - **POSIX / Linux / macOS**: Use `rtk ls <path>` or `rtk tree`.
-- `rtk err <cmd>`: Runs command and displays only errors/warnings.
-- `rtk summary <cmd>`: Runs command and produces a 2-line technical summary.
+1. **Tier 1 — Structural Discovery (`waymark_ask` with `plain: true`)**:
+   - Locate exact `[StartLine, EndLine]` coordinates via `waymark_ask(..., plain: true)` across all 23 supported formats (code ASTs + `markdown`, `yaml`, `json`, `toml`, `bash`). Always set `plain: true` (~19–466 tokens, zero shell quoting or stdin hazards).
+2. **Tier 2 — Precision Workspace File Reading (`view_file` Hybrid Slice Policy)**:
+   - Pass `StartLine` and `EndLine` from `waymark_ask` into `view_file` (bounded slices of `1–150` lines) to preserve exact 1-indexed line numbers for `replace_file_content` without terminal stdout truncation. Partial slices of `151–800` lines are denied; an explicit one-pass full-file audit (`StartLine: 1, EndLine: <TotalLines>`) is permitted only when the file on disk is $\le 800$ lines and $\le 45\text{ KiB}$ (`46,080` bytes).
+3. **Tier 3 — RTK Boundaries (`rtk read`, `rtk find`, `rtk rg`, `rtk err`, `rtk summary`)**:
+   - **Spillovers & Task Logs**: Read `.system_generated/steps/<step>/output.txt` spillovers and completed `tasks/<taskId>.log` files via `rtk read <path>` (`--head-lines` / `--tail-lines`). Never use `rtk read -l minimal|aggressive` or `-m` to derive line numbers for edits.
+   - **Directory / File Discovery**:
+     - **Windows**: Use `rtk find <path>` or PowerShell `dir` / `Get-ChildItem`. (Avoid `rtk ls` or `rtk tree` on Windows as they rely on POSIX binaries/flags).
+     - **POSIX / Linux / macOS**: Use `rtk find <path>`, `rtk ls <path>`, or `rtk tree`.
+   - **Prose / Regex Search (when symbol, heading, or config key is unknown)**:
+     - **Windows**: Use `rtk rg "<pattern>" .` (explicit target `.` is required to avoid child process stdin pipe stalls) or `rg "<pattern>" .`.
+     - **POSIX / Linux / macOS**: Use `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
+   - `rtk err <cmd>`: Runs command and displays only errors/warnings.
+   - `rtk summary <cmd>`: Runs command and produces a 2-line technical summary.
 
 *Safe Harbor*: Documented Antigravity special files (`SKILL.md`, brain artifacts, `.gemini/config/`) may be viewed directly via `view_file` without slice bounds.
 
@@ -54,7 +58,7 @@ Granular query and forensic filtering engine for transcripts with keyword/regex
 - **Parameters**:
   - `conversationId` (string, required): Conversation UUID or path.
   - `query` (string, optional): Search keyword or regex.
-  - `roles` (array, default: ["user", "assistant"]): Filter by role.
+  - `roles` (array, default: ["user", "assistant"]): Filter by role (`"user"`, `"assistant"`, `"subagent"`, `"tool"`, `"error"`, `"all"`).
   - `stepIndex` (number, optional): Specific step to dereference from `transcript_full.jsonl`.
   - `field` (string, optional): Field projection (`"content"`, `"thinking"`, `"tool_calls"`).
 
@@ -79,7 +83,7 @@ Re-verifies, repairs, and synchronizes the installation and tool schemas in ~25m
 
 2. **Layer 2: Transparent CLI & Codebase Streamlining**:
    - Shell commands transparently rewrite via RTK (`rtk git`, `rtk pytest`, `rtk cargo`, etc.).
-   - Codebase inspection is hard-routed to `rtk read`, `rtk find`, and `rtk rg "<pattern>" .`.
+   - Workspace file inspection follows `waymark_ask(..., plain: true)` $\to$ bounded `view_file(StartLine, EndLine)`, while `rtk read` handles step spillovers and completed task logs, and `rtk find` / `rtk rg "<pattern>" .` handle directory and free-text search.
    - Direct access to `.system_generated/` is strictly denied; use `read_transcript` and `query_transcript`.
    - **Log Hygiene (Git CRLF/LF Notice Stripping)**: Repetitive Git line-ending notices (`warning: LF will be replaced by CRLF` / `warning: CRLF will be replaced by LF...`) are non-actionable environment noise. Agy-Context-Saver automatically strips these warning lines across forensic transcript parsers, and agents suppress them at the source (`git -c core.safecrlf=false`) to protect context window tokens.