agy-context-saver 1.7.0 → 1.8.1

package/rules/AGENTS.md

@@ -30,34 +30,32 @@
 
 ---
 
-## 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 task outputs or conversation context.
 
 ---
 
-## Layer 3: Synchronous Execution & Subagent Delegation
+## Layer 3: Synchronous Execution
 - **Maximum Synchronous Window**: Non-daemon `run_command` calls are automatically set to `WaitMsBeforeAsync: 10000` to complete synchronously and prevent unnecessary background detachment.
 - **Targeted Test Execution & Opt-In Fail-Fast (LH-11)**:
   - **Targeted Invocations**: In interactive turns, prefer targeting specific test files or directories (e.g. `pytest tests/test_core.py`) rather than running full multi-minute repository sweeps.
   - **Fail-Fast Flags are Opt-In**: Fail-fast flags (`-x`, `--maxfail=1`) are opt-in. Use them when quickly debugging a localized failure, but omit them when assessing the full blast radius across the codebase to avoid the "whack-a-mole" loop.
   - **Coordinated Watchdog Mandatory for Full Sweeps**: When running full multi-minute test sweeps without `-x`, agents **MUST** pair execution with the **Coordinated Watchdog Protocol** (`schedule(DurationSeconds=45, ...)`) and output a **Pre-Yield Status Card**. Never yield silently.
-  - **Subagent Delegation for Deep Audits**: When a comprehensive repository-wide test audit is required, delegate the sweep to a subagent (`invoke_subagent`) to keep the main thread responsive.
-- **Subagent Delegation & Pointer-Over-Wire (POW)**:
-  - Delegate heavy multi-file exploration, deep research, and repo sweeps to subagents (`invoke_subagent`). Subagents absorb intermediate steps and return high-signal summaries.
-  - **POW Protocol & `write_to_file` Isolation**: Payloads or deliverables exceeding 1 KB must be written either to workspace scratch files (`<workspace>/scratch/<task>_findings.md` with `ArtifactMetadata` **omitted**) or to the **subagent's own** `<Artifact Directory Path>/scratch/<task>_findings.md` (with `ArtifactMetadata: { Summary, UserFacing: false, RequestFeedback: false }`). Never instruct a subagent to `write_to_file` into the parent conversation's `brain/<parent-uuid>/` directory, as Antigravity enforces per-conversation `brain/<uuid>` write isolation. Transmit **ONLY** an Executive Summary (3–5 sentences), a Scoreboard / Verdict table, and a clickable file link (`file:///...`) in `send_message` to prevent transport truncation and parent context bloat.
 - **Benchmark / Evaluator Integrity**: Never mutate benchmark definitions, prompt templates, or scoring artifacts during an active evaluation without explicit user confirmation.
 
 ---
@@ -77,7 +75,7 @@ When an agent or developer tests this framework, follow this exact sequence with
    ```bash
    npm test
    ```
-   *Expected*: All 8 test suites pass (Hook unit tests, MCP protocol tests, output governance, E2E probes, performance probes, live system validation, lifecycle rollback, subagent trials).
+   *Expected*: All 10 test suites pass (hook unit tests, MCP protocol tests, output governance, E2E probes, performance probes, live system validation, lifecycle rollback, check-only read-only safety, malformed config preservation, RTK ledger fresh install).
 
 3. **Verify Individual Layers On-Demand**:
    - Governance Hook: `node tests/test-hook.mjs`
@@ -87,14 +85,12 @@ When an agent or developer tests this framework, follow this exact sequence with
    - Performance Probes: `node tests/test-performance-probes.mjs`
    - Live System Checks: `node tests/test-installed-verification.mjs`
    - Lifecycle & Rollback: `node tests/test-lifecycle-rollback.mjs`
-   - Subagent Delegation Trials: `node tests/test-subagent-trials.mjs`
 
 4. **Verify MCP Tools in Antigravity**:
    - `get_installation_status`: Inspect live integration layers.
    - `check_context_health`: Pass `{ "transcriptPath": "<path-to-transcript.jsonl>" }`.
    - `read_transcript`: Pass `{ "conversationId": "<uuid>", "lastTurns": 3, "mode": "compact" }`.
    - `query_transcript`: Pass `{ "conversationId": "<uuid>", "query": "<pattern>", "summaryOnly": true }`.
-   - `subagent_brief`: Pass `{ "objective": "<goal>", "role": "<role>", "scopeFiles": ["..."] }` or pass multiple via `{ "subagents": [...] }` to generate ready-to-use `invoke_subagent` JSON payloads.
 
 5. **Operational Anti-Patterns (What NOT to do)**:
    - ❌ **Do NOT run `npm start` or `node mcp/index.js` interactively**: It starts the stdio JSON-RPC daemon and waits indefinitely on stdin.

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).
@@ -56,12 +57,32 @@ const GOVERNED_TOOLS = new Set([
 const STATE_TTL_MS = 3600000; // 1 hour TTL
 const MAX_STATE_ENTRIES = 50;
 
+// Per-user state folder, never the shared os.tmpdir(). Keep identical to scripts/state-dir.mjs:
+// this hook is mirrored as a standalone file, so it can't import it.
+function getStateDir() {
+  const profileHome = process.env.AGY_TEST_PROFILE_DIR;
+  if (os.platform() === "win32") {
+    const localAppData = profileHome
+      ? path.join(profileHome, "AppData", "Local")
+      : (process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"));
+    return path.join(localAppData, "agy-context-saver");
+  }
+  const stateHome = profileHome
+    ? path.join(profileHome, ".local", "state")
+    : (process.env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state"));
+  return path.join(stateHome, "agy-context-saver");
+}
+
+function ensureStateDir() {
+  try { fs.mkdirSync(getStateDir(), { recursive: true }); } catch {}
+}
+
 function getStateFilePath(convId = "global") {
   if (!convId || convId === "global") {
-    return path.join(os.tmpdir(), "agy-session-governance-state.json");
+    return path.join(getStateDir(), "agy-session-governance-state.json");
   }
   const safeId = String(convId).replace(/[^a-zA-Z0-9_-]/g, "_");
-  return path.join(os.tmpdir(), `agy-session-${safeId}.json`);
+  return path.join(getStateDir(), `agy-session-${safeId}.json`);
 }
 
 function getSessionState(convId = "global") {
@@ -79,6 +100,7 @@ function getSessionState(convId = "global") {
 
 function saveSessionState(convId = "global", entry) {
   const file = getStateFilePath(convId);
+  ensureStateDir();
   try {
     const now = Date.now();
     entry.lastPollTime = now;
@@ -176,6 +198,7 @@ function isProtectedBenchmarkPath(targetPath) {
   );
 }
 
+
 /**
  * Checks if target path references runtime step output spillover file.
  */
@@ -355,7 +378,7 @@ const NON_REWRITABLE_BINARIES = new Set([
   "export"
 ]);
 
-const REWRITE_CACHE_FILE = path.join(os.tmpdir(), "agy-rtk-rewrite-cache.json");
+const REWRITE_CACHE_FILE = path.join(getStateDir(), "agy-rtk-rewrite-cache.json");
 const REWRITE_CACHE_MAX = 100;
 let inMemoryRewriteCache = null;
 
@@ -403,6 +426,7 @@ function resolveCompatibleRtk() {
 
   cache.__envSig = envSig;
   cache.__rtkResolved = resolved;
+  ensureStateDir();
   try {
     const tmp = `${REWRITE_CACHE_FILE}.${process.pid}.tmp`;
     fs.writeFileSync(tmp, JSON.stringify(cache), "utf-8");
@@ -443,6 +467,7 @@ function rememberRewrite(cmd, rewritten) {
     for (const k of keys.slice(0, Math.max(0, keys.length - REWRITE_CACHE_MAX))) delete disk[k];
     if (envSig !== undefined) disk.__envSig = envSig;
     if (rtkResolved !== undefined) disk.__rtkResolved = rtkResolved;
+    ensureStateDir();
     const tmp = `${REWRITE_CACHE_FILE}.${process.pid}.tmp`;
     fs.writeFileSync(tmp, JSON.stringify(disk), "utf-8");
     try {
@@ -616,6 +641,7 @@ try {
       });
     }
 
+
     // LH-09-B: Shell command mutation of protected benchmark artifacts
     if (
       (rawCmd.includes(">") || /\b(?:rm|del|Remove-Item)\b/i.test(rawCmd)) &&
@@ -764,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";
@@ -784,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: keep hook identical to original behavior (zero slice advertisement)
       respond({
         decision: "deny",
-        reason: `Antigravity Governance: Native file inspection via '${toolName}' bypasses token optimization. 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

@@ -17,6 +17,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { ensureRtkInstalled, findExistingRtk } from "./provision-rtk.mjs";
+import { getStateDir, removeLegacyTmpState } from "./state-dir.mjs";
 
 const fsPromises = fs.promises;
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -115,7 +116,6 @@ export function detectExistingInstallation() {
   const scriptExists = fs.existsSync(destHook);
   const schemasExist =
     fs.existsSync(path.join(antigravityMcpDir, "check_context_health.json")) &&
-    fs.existsSync(path.join(antigravityMcpDir, "subagent_brief.json")) &&
     fs.existsSync(path.join(antigravityMcpDir, "get_installation_status.json")) &&
     fs.existsSync(path.join(antigravityMcpDir, "sync_installation.json")) &&
     fs.existsSync(path.join(antigravityMcpDir, "read_transcript.json")) &&
@@ -338,7 +338,10 @@ export async function runInstall(options = {}) {
     "safe_command.json",
     "get_spillover_content.json",
     "read_task_output.json",
-    "get_step_detail.json"
+    "get_step_detail.json",
+    // Subagent tools moved to the separate Agy-Squad package (2026-10-15)
+    "subagent_brief.json",
+    "dispatch_squad.json"
   ];
   for (const s of retiredSchemas) {
     const sPath = path.join(antigravityMcpDir, s);
@@ -350,39 +353,13 @@ export async function runInstall(options = {}) {
     }
   }
 
-  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\`.
-- \`subagent_brief\`: Formulates scope-isolated prompts and ready-to-use invoke_subagent JSON payloads for single or multiple delegated subagents with Pointer-Over-Wire delivery contract.
-- \`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).
-`;
+  // Versions up to 1.7.0 kept hook state in the shared temp folder; it now lives in getStateDir()
+  for (const legacy of removeLegacyTmpState()) {
+    log(`[OK] Removed legacy temp-folder state: ${legacy}`);
+  }
+
+  const instructionsSourcePath = path.join(repoRoot, "mcp", "instructions.md");
+  const instructionsContent = await fsPromises.readFile(instructionsSourcePath, "utf-8");
 
   const checkHealthSchema = {
     name: "check_context_health",
@@ -402,42 +379,6 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
     }
   };
 
-  const subagentBriefSchema = {
-    name: "subagent_brief",
-    description: "Generates scope-isolated, anti-bloat prompts and ready-to-use invoke_subagent JSON payloads for single or multiple delegated subagents. Instructs subagents to absorb intermediate file reads/searches and return only high-signal findings.",
-    parameters: {
-      type: "object",
-      properties: {
-        objective: { type: "string", description: "The core research or investigative objective (for single subagent)." },
-        role: { type: "string", description: "2-5 word role description (e.g. 'Comprehensive Test Engineer', 'Codebase Security Auditor'). Defaults to 'Scope-Isolated Deep Research Subagent'." },
-        instructions: { type: "string", description: "Optional step-by-step instructions or specialized directives." },
-        scopeFiles: { type: "array", items: { type: "string" }, description: "List of files or directories to investigate." },
-        expectedDeliverable: { type: "string", description: "The concise format expected back by the parent agent." },
-        typeName: { type: "string", description: "Subagent type name: 'self' (default, inherits parent tools/prompt/model) or 'research' (read-only)." },
-        model: { type: "string", enum: ["inherit", "flash_lite", "flash", "pro"], description: "Model tier: 'inherit' (default), 'flash_lite', 'flash', or 'pro'." },
-        workspace: { type: "string", enum: ["inherit", "branch", "share"], description: "Workspace isolation: 'inherit' (default), 'branch', or 'share'." },
-        subagents: {
-          type: "array",
-          description: "Optional array of subagent configurations to formulate multiple subagents at once.",
-          items: {
-            type: "object",
-            properties: {
-              role: { type: "string", description: "2-5 word role description." },
-              objective: { type: "string", description: "The core objective for this subagent." },
-              instructions: { type: "string", description: "Optional step-by-step instructions." },
-              scopeFiles: { type: "array", items: { type: "string" }, description: "Files/directories to investigate." },
-              expectedDeliverable: { type: "string", description: "Expected deliverable format." },
-              typeName: { type: "string", description: "Subagent type name: 'self' or 'research'." },
-              model: { type: "string", enum: ["inherit", "flash_lite", "flash", "pro"], description: "Model tier." },
-              workspace: { type: "string", enum: ["inherit", "branch", "share"], description: "Workspace isolation." }
-            },
-            required: ["objective"]
-          }
-        }
-      }
-    }
-  };
-
   const getInstallationStatusSchema = {
     name: "get_installation_status",
     description: "Inspect the live installation status of Agy-Context-Saver across all Antigravity integration points (Native Plugin Link, Governor Hook, MCP Server, and Tool Schemas).",
@@ -493,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: {
@@ -508,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",
@@ -559,7 +500,6 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
   await Promise.all([
     safeWriteFileIfChanged(path.join(antigravityMcpDir, "instructions.md"), instructionsContent),
     safeWriteFileIfChanged(path.join(antigravityMcpDir, "check_context_health.json"), JSON.stringify(checkHealthSchema, null, 2)),
-    safeWriteFileIfChanged(path.join(antigravityMcpDir, "subagent_brief.json"), JSON.stringify(subagentBriefSchema, null, 2)),
     safeWriteFileIfChanged(path.join(antigravityMcpDir, "get_installation_status.json"), JSON.stringify(getInstallationStatusSchema, null, 2)),
     safeWriteFileIfChanged(path.join(antigravityMcpDir, "sync_installation.json"), JSON.stringify(syncInstallationSchema, null, 2)),
     safeWriteFileIfChanged(path.join(antigravityMcpDir, "read_transcript.json"), JSON.stringify(readTranscriptSchema, null, 2)),
@@ -631,7 +571,21 @@ export async function runUninstall(options = {}) {
     }
   }
 
-  // 6. Optional: Restore configuration files from backups if requested
+  // 6. Remove hook state: the per-user state folder and anything older versions left in the temp folder
+  const stateDir = getStateDir();
+  if (fs.existsSync(stateDir)) {
+    try {
+      await fsPromises.rm(stateDir, { recursive: true, force: true });
+      log(`[OK] Removed hook state folder: ${stateDir}`);
+    } catch (err) {
+      warn(`[WARN] Could not remove hook state folder: ${err.message}`);
+    }
+  }
+  for (const legacy of removeLegacyTmpState()) {
+    log(`[OK] Removed legacy temp-folder state: ${legacy}`);
+  }
+
+  // 7. Optional: Restore configuration files from backups if requested
   if (options.restoreBackups) {
     await runRestoreBackups(options);
   }
@@ -678,7 +632,7 @@ export function runStatus(options = {}) {
   log(`- Native Plugin Link: ${existing.details.plugin.exists ? "ACTIVE (" + pluginDest + ")" : "NOT LINKED"}`);
   log(`- Execution Governor Hook: ${existing.details.hook.registered ? "REGISTERED in hooks.json" : "NOT REGISTERED"}`);
   log(`- Universal MCP Server: ${existing.details.mcp.registered ? "CONFIGURED in mcp_config.json" : "NOT CONFIGURED"}`);
-  log(`- Antigravity Tool Schemas: ${existing.details.schemas.exists ? "PRESENT (6 Schemas)" : "MISSING"}`);
+  log(`- Antigravity Tool Schemas: ${existing.details.schemas.exists ? "PRESENT (5 Schemas)" : "MISSING"}`);
   log(`- RTK Command Optimizer: ${existing.details.rtk ? "INSTALLED (" + existing.details.rtk.version + ")" : "MISSING"}`);
 
   log(`\nOverall Status: ${existing.isComplete ? "HEALTHY & ACTIVE 🛡️" : existing.isInstalled ? "PARTIAL INSTALLATION" : "NOT INSTALLED"}\n`);

package/scripts/provision-rtk.mjs

@@ -92,6 +92,7 @@ export async function ensureRtkInstalled(options = {}) {
   const log = options.silent ? () => {} : console.log;
   const existing = options.existingRtk || findExistingRtk(options);
   if (existing) {
+    ensureRtkConfigured(options);
     log(`✓ RTK is already installed and verified: ${existing.version} (${existing.path})`);
     return existing;
   }
@@ -160,10 +161,75 @@ export async function ensureRtkInstalled(options = {}) {
     throw new Error(`RTK installation verification failed: could not run ${targetExe}`);
   }
 
+  ensureRtkConfigured(options);
+
   log(`✓ Successfully installed and verified RTK: ${verified.version} at ${verified.path}`);
   return verified;
 }
 
+export function getRtkConfigPath() {
+  const profileHome = process.env.AGY_TEST_PROFILE_DIR;
+  if (profileHome) {
+    if (os.platform() === "win32") {
+      return path.join(profileHome, "AppData", "Roaming", "rtk", "config.toml");
+    }
+    return path.join(profileHome, ".config", "rtk", "config.toml");
+  }
+  if (os.platform() === "win32") {
+    const appData = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    return path.join(appData, "rtk", "config.toml");
+  }
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(configHome, "rtk", "config.toml");
+}
+
+export function ensureRtkConfigured(options = {}) {
+  const log = options.silent ? () => {} : console.log;
+  const configPath = getRtkConfigPath();
+  const configDir = path.dirname(configPath);
+
+  try {
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+
+    if (!fs.existsSync(configPath)) {
+      const defaultContent = `[hooks]\nsuppress_hook_warning = true\n`;
+      fs.writeFileSync(configPath, defaultContent, "utf-8");
+      log(`✓ Initialized RTK configuration with suppress_hook_warning = true at ${configPath}`);
+    } else {
+      let content = fs.readFileSync(configPath, "utf-8");
+      if (/suppress_hook_warning\s*=\s*false/i.test(content)) {
+        content = content.replace(/suppress_hook_warning\s*=\s*false/i, "suppress_hook_warning = true");
+        fs.writeFileSync(configPath, content, "utf-8");
+        log(`✓ Updated RTK configuration to suppress_hook_warning = true in ${configPath}`);
+      } else if (!/suppress_hook_warning/i.test(content)) {
+        if (/\[hooks\]/i.test(content)) {
+          content = content.replace(/\[hooks\]/i, "[hooks]\nsuppress_hook_warning = true");
+        } else {
+          content = (content.trim() + "\n\n[hooks]\nsuppress_hook_warning = true\n").trimStart();
+        }
+        fs.writeFileSync(configPath, content, "utf-8");
+        log(`✓ Configured suppress_hook_warning = true in ${configPath}`);
+      }
+    }
+  } catch (err) {
+    if (!options.silent) {
+      console.warn(`[WARN] Could not standardize RTK config: ${err.message}`);
+    }
+  }
+
+  ensureGitLineEndingConfigured(options);
+}
+
+export function ensureGitLineEndingConfigured(options = {}) {
+  const log = options.silent ? () => {} : console.log;
+  try {
+    execSync("git config --global core.safecrlf false", { windowsHide: true, stdio: "ignore" });
+    log("✓ Standardized git core.safecrlf = false to suppress line-ending warning noise");
+  } catch {}
+}
+
 // Auto-run if executed directly
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   ensureRtkInstalled().catch((err) => {

package/scripts/state-dir.mjs

@@ -0,0 +1,51 @@
+/**
+ * Per-user state location for Agy-Context-Saver (governance ledger, RTK rewrite cache).
+ *
+ * State lives in a folder owned by this user, never in the shared os.tmpdir():
+ *   Windows: %LOCALAPPDATA%\agy-context-saver
+ *   POSIX:   $XDG_STATE_HOME/agy-context-saver (default ~/.local/state/agy-context-saver)
+ * Under AGY_TEST_PROFILE_DIR the same layout is rooted in the test profile.
+ *
+ * The hook is mirrored into ~/.gemini/config/scripts as a standalone file, so it keeps an
+ * identical inline copy of getStateDir(). tests/test-hook.mjs checks that the two agree.
+ * No side effects on import.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export function getStateDir() {
+  const profileHome = process.env.AGY_TEST_PROFILE_DIR;
+  if (os.platform() === "win32") {
+    const localAppData = profileHome
+      ? path.join(profileHome, "AppData", "Local")
+      : (process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"));
+    return path.join(localAppData, "agy-context-saver");
+  }
+  const stateHome = profileHome
+    ? path.join(profileHome, ".local", "state")
+    : (process.env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state"));
+  return path.join(stateHome, "agy-context-saver");
+}
+
+// Files that versions up to 1.7.0 left in the shared temp folder, plus their atomic-write temps.
+const LEGACY_TMP_STATE = /^(agy-session-.+\.json|agy-rtk-rewrite-cache\.json)(\..+\.tmp)?$/;
+
+/** Removes state files that older versions wrote to os.tmpdir(). Returns the paths removed. */
+export function removeLegacyTmpState() {
+  const removed = [];
+  const tmp = os.tmpdir();
+  let names = [];
+  try { names = fs.readdirSync(tmp); } catch { return removed; }
+  for (const name of names) {
+    if (!LEGACY_TMP_STATE.test(name)) continue;
+    const p = path.join(tmp, name);
+    try {
+      if (fs.lstatSync(p).isFile()) {
+        fs.unlinkSync(p);
+        removed.push(p);
+      }
+    } catch {}
+  }
+  return removed;
+}