agy-context-saver 1.8.1 → 2.0.1

package/scripts/execution-guard-hook.mjs

@@ -1,31 +1,31 @@
 #!/usr/bin/env node
 
 /**
- * Agy-Context-Saver: Intelligent Execution Governor Hook for Antigravity
+ * Agy-Context-Saver: Intelligent Execution Governor Hook for Antigravity (v2.0.0)
  *
  * Closed Execution Topology & Governance Invariants:
  * 1. RTK Transparent Command Optimization:
- *    - Offloads 100% of command output reduction to RTK (Rust Token Killer).
- *    - Intercepts native run_command and calls `rtk rewrite <cmd>`.
- *    - Non-daemon commands maintain WaitMsBeforeAsync=10000 for synchronous completion.
+ *    - Delegates command rewriting to `rtk hook antigravity` (>= 1.1.0) via stdin JSON.
+ *    - Reverts lossy `rtk wc` / `rtk ls` / `rtk diff` rewrites unless explicitly requested.
+ *    - Never emits `rtk rg` when `rg` is absent on PATH (maps safe invocations to `rtk grep`
+ *      with explicit path, or strips `rtk ` when rg-only flags are used).
+ *    - Sets WaitMsBeforeAsync=10000 only when `!isDaemon && waitMs === undefined`.
  * 2. Hard-Routed Native File/Search Inspection (LH-07):
- *    - 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 find` (Win) or `rtk ls` / `rtk tree` (POSIX).
- *    - Safe Harbor: Documented Antigravity special files (SKILL.md, brain artifacts, configs) are allowed.
+ *    - read_file & view_file -> Symmetrical Safe Harbor + Hybrid Slice (<= 150 lines, or
+ *      explicit full-file StartLine=1..EndLine=TotalLines when <= 800 lines & <= 45 KiB);
+ *      bounded read_file (<= 150 lines) allowed on `.system_generated/steps/<n>/output.txt`.
+ *    - read_many_files, grep_search, find_by_name, list_dir -> Hard-routed to RTK CLI.
  * 3. Root-Based Antigravity Internal State Protection (LH-02):
- *    - Hard denial for any inspection of `.system_generated/` (transcripts, task logs, progress).
- *    - Directed to Agy MCP tools `read_transcript` / `query_transcript`.
+ *    - Quote/heredoc-aware shell parser (`splitShellSegments`) protects `.system_generated/`
+ *      without false-blocking heredoc prose, `echo`/`printf`, or literal search patterns.
+ *    - Allows strictly single unchained `rtk read <spillover|completed task log>` and
+ *      `agy-context transcript (read|query|step|health) ...` within `<brainDir>`.
  * 4. Closed Lifecycle Governance (LH-03, LH-04, LH-05, LH-06):
- *    - Session-wide ledger without cooldown resets, task-ID resets, or duration exemptions.
- *    - Enforces native Reactive Wakeup (<SYSTEM_MESSAGE>) for background tasks.
- *    - Circuit Breaker: 5 cumulative denials trigger `force_ask` to halt runaway autonomous loops.
+ *    - Session-wide ledger with proportional backoff and 5-denial `force_ask` circuit breaker.
  * 5. Benchmark & Evaluator Mutation Protection (LH-09):
- *    - Requires user approval before mutating benchmark definitions, evaluators, or scoring files.
- * 6. Fail-Closed on Governed Operations (LH-10):
- *    - Governed tool failures deny instead of silently allowing.
+ *    - Requires user approval (`force_ask`) for `edit_file`, `write_file`,
+ *      `replace_file_content`, `write_to_file`, and destructive shell commands.
+ * 6. Fail-Closed on Governed Operations (LH-10).
  */
 
 import fs from "node:fs";
@@ -35,7 +35,38 @@ import process from "node:process";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+const HOOK_DEDUP_TTL_MS = 5000;
+const HOOK_SAME_ARG_CROSS_SCRIPT_MS = 500;
+let dedupRecordCtx = null;
+
 function respond(obj) {
+  if (dedupRecordCtx && dedupRecordCtx.convId) {
+    try {
+      const latest = getSessionState(dedupRecordCtx.convId);
+      const now = Date.now();
+      let outSig = dedupRecordCtx.rawSig;
+      if (obj && obj.overwrite && typeof obj.overwrite === "object") {
+        try {
+          const parsedRaw = JSON.parse(dedupRecordCtx.rawSig);
+          outSig = JSON.stringify({ ...parsedRaw, ...obj.overwrite });
+        } catch {}
+      }
+      const prevList = Array.isArray(latest.recentHookCalls) ? latest.recentHookCalls : [];
+      const freshList = prevList.filter((e) => e && typeof e.ts === "number" && (now - e.ts) < HOOK_DEDUP_TTL_MS);
+      freshList.push({
+        ts: now,
+        callId: dedupRecordCtx.callId || "",
+        stepIdx: dedupRecordCtx.stepIdx !== undefined ? dedupRecordCtx.stepIdx : null,
+        toolName: dedupRecordCtx.toolName,
+        scriptPath: dedupRecordCtx.scriptPath,
+        rawSig: dedupRecordCtx.rawSig,
+        outSig,
+        response: obj
+      });
+      latest.recentHookCalls = freshList.slice(-8);
+      saveSessionState(dedupRecordCtx.convId, latest, { updatePollTime: false });
+    } catch {}
+  }
   process.stdout.write(JSON.stringify(obj) + "\n");
   process.exit(0);
 }
@@ -51,7 +82,9 @@ const GOVERNED_TOOLS = new Set([
   "find_by_name",
   "list_dir",
   "replace_file_content",
-  "write_to_file"
+  "write_to_file",
+  "write_file",
+  "edit_file"
 ]);
 
 const STATE_TTL_MS = 3600000; // 1 hour TTL
@@ -91,19 +124,23 @@ function getSessionState(convId = "global") {
     const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
     const entry = (parsed && typeof parsed.pollCount === "number") ? parsed : (parsed && parsed[convId]);
     const now = Date.now();
-    if (entry && typeof entry.lastPollTime === "number" && (now - entry.lastPollTime) < STATE_TTL_MS) {
+    const activityTime = Math.max(entry?.lastPollTime || 0, entry?.lastSeenTime || 0);
+    if (entry && activityTime > 0 && (now - activityTime) < STATE_TTL_MS) {
       return entry;
     }
   } catch {}
-  return { pollCount: 0, denials: 0, taskIds: [], lastPollTime: 0 };
+  return { pollCount: 0, denials: 0, taskIds: [], lastPollTime: 0, lastSeenTime: 0, recentHookCalls: [] };
 }
 
-function saveSessionState(convId = "global", entry) {
+function saveSessionState(convId = "global", entry, { updatePollTime = true } = {}) {
   const file = getStateFilePath(convId);
   ensureStateDir();
   try {
     const now = Date.now();
-    entry.lastPollTime = now;
+    entry.lastSeenTime = now;
+    if (updatePollTime) {
+      entry.lastPollTime = now;
+    }
     let toWrite;
     if (!convId || convId === "global") {
       let state = {};
@@ -117,8 +154,11 @@ function saveSessionState(convId = "global", entry) {
 
       // Prune stale entries
       const entries = Object.entries(state)
-        .filter(([_, v]) => v && typeof v.lastPollTime === "number" && (now - v.lastPollTime) < STATE_TTL_MS)
-        .sort((a, b) => (b[1].lastPollTime || 0) - (a[1].lastPollTime || 0))
+        .filter(([_, v]) => {
+          const ts = Math.max(v?.lastPollTime || 0, v?.lastSeenTime || 0);
+          return v && ts > 0 && (now - ts) < STATE_TTL_MS;
+        })
+        .sort((a, b) => Math.max(b[1].lastPollTime || 0, b[1].lastSeenTime || 0) - Math.max(a[1].lastPollTime || 0, a[1].lastSeenTime || 0))
         .slice(0, MAX_STATE_ENTRIES);
 
       toWrite = JSON.stringify(Object.fromEntries(entries));
@@ -137,12 +177,150 @@ function saveSessionState(convId = "global", entry) {
   } catch {}
 }
 
+function matchesRawProtectedInternalState(targetPath) {
+  if (!targetPath || typeof targetPath !== "string") return false;
+  if (/\.system_generated(?:$|[\/\\])/i.test(targetPath)) return true;
+  if (/(?:^|[\/\\'"`\s=:])\.system_gen/i.test(targetPath)) return true;
+  if (/['"]\.system_['"]\s*(?:[+.]\s*)?['"]gen/i.test(targetPath)) return true;
+  if (/(?:^|[^a-zA-Z0-9_-])system_generated\b/i.test(targetPath)) return true;
+  if (/\btranscript(?:_full)?\.jsonl\b/i.test(targetPath)) return true;
+  if (/\.gemini[\/\\]+antigravity[\/\\]+brain[\/\\]+.*(?:\$|logs[\/\\]|tasks[\/\\]|steps[\/\\])/i.test(targetPath)) {
+    return true;
+  }
+  // Block hidden segments (e.g. .s*/*/*, .*) or wildcard globs directly under brain/<convId>/ (allowing .agents/)
+  if (/\.gemini[\/\\]+antigravity[\/\\]+brain[\/\\]+(?:[^\/\\\s'"]+[\/\\]+)?(?:\.(?!agents(?:$|[\/\\]))|[*?\[])/i.test(targetPath)) {
+    return true;
+  }
+  // Protect Agy-Context-Saver state directory and session/policy JSON files
+  if (/\b(?:transcript-access|agy-session-governance-state|agy-rtk-rewrite-cache)\.json\b/i.test(targetPath)) return true;
+  if (/\bagy-session-[a-zA-Z0-9_-]+\.json\b/i.test(targetPath)) return true;
+  if (/[\/\\]\.local[\/\\]+state[\/\\]+agy-context-saver(?:$|[\/\\'"`\s])/i.test(targetPath)) return true;
+  if (/[\/\\]AppData[\/\\]+Local[\/\\]+agy-context-saver(?:$|[\/\\'"`\s])/i.test(targetPath)) return true;
+  try {
+    const stateDirNorm = getStateDir().replace(/\\/g, "/");
+    const targetNorm = targetPath.replace(/\\/g, "/");
+    if (stateDirNorm && targetNorm.includes(stateDirNorm)) return true;
+  } catch {}
+  if (/\bbase64\b[\s\S]*\|\s*(?:[^\s|]+\/)?(?:ba|z|da|a)?sh\b/i.test(targetPath)) return true;
+  return false;
+}
+
+function isProtectedShellOrScriptOperation(text) {
+  if (!text || typeof text !== "string") return false;
+  if (isProtectedInternalState(text)) return true;
+
+  // Non-canonical or wrapped agy-context transcript invocations that did not pass checkAgyContextTranscriptCommand
+  if (/(?:^|[\s;|&('"\/\\])agy-context(?:-saver)?(?:\.m?js)?['"]?\s+(?:-[^\s;|&'"]+\s+)*transcript(?:\s|$|['";|&)])/i.test(text)) {
+    return true;
+  }
+
+  // Inline interpreter or script execution importing/spawning transcript-core.mjs, bin/agy-context.mjs, or mcp/index.js
+  if (
+    /(?:\b(?:import|require|spawn|spawnSync|exec|execSync|execFile|execFileSync|popen|system|subprocess)\b|(?:^|[\s;|&(])(?:node|python[23]?|perl|ruby|php|bash|sh|zsh|dash)\b[^\n;|&]*?(?:\s-[a-z]*[ec]\b|<<))[\s\S]*?(?:\btranscript-core(?:\.m?js)?\b|(?:bin[\/\\]+|\b)agy-context(?:-saver)?\.m?js\b|\bmcp[\/\\]+index\.js\b)/i.test(
+      text
+    )
+  ) {
+    return true;
+  }
+
+  // Block environment variable redirection of governance state or brain roots inside shell commands/scripts
+  if (/(?:^|[\s;|&(])(?:AGY_TEST_PROFILE_DIR|AGY_BRAIN_DIR|XDG_STATE_HOME|LOCALAPPDATA|GEMINI_CONVERSATION_ID)=/i.test(text)) {
+    return true;
+  }
+  if (
+    /(?:process\.env|os\.environ)\s*(?:\.\s*(?:AGY_TEST_PROFILE_DIR|AGY_BRAIN_DIR|XDG_STATE_HOME|LOCALAPPDATA|GEMINI_CONVERSATION_ID)\b|\[\s*['"](?:AGY_TEST_PROFILE_DIR|AGY_BRAIN_DIR|XDG_STATE_HOME|LOCALAPPDATA|GEMINI_CONVERSATION_ID)['"]\s*\])/i.test(
+      text
+    )
+  ) {
+    return true;
+  }
+
+  // Block symlinks, bulk copies/archives, file reads, or directory enumeration of <brainDir>/<convId> outside /scratch/, /browser_sandbox/, or .agents/ (in either order)
+  const hasUnprotectedBrainRef =
+    /\.gemini[\/\\]+antigravity[\/\\]+brain[\/\\]+(?![^\s'"]*[\/\\](?:scratch|browser_sandbox|\.agents)(?:$|[\/\\])|[^\s'"]*\.(?:md|txt|json|png|jpg|jpeg|svg|html|css|webp|pdf)\b)/i.test(
+      text
+    );
+  if (
+    hasUnprotectedBrainRef &&
+    /\b(?:ln|cp|mv|rsync|tar|zip|find|readdir|readdirSync|scandir|listdir|walk|glob|iglob|readFile|readFileSync|createReadStream|open|openSync)\b/i.test(
+      text
+    )
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
 /**
- * Checks if target path references Antigravity internal state by root directory.
+ * Checks if target path or shell operand references Antigravity internal state or obfuscated smuggling
+ * (including runtime Base64, URL-safe Base64, Hex, escape, or char-code path decoding).
  */
 function isProtectedInternalState(targetPath) {
   if (!targetPath || typeof targetPath !== "string") return false;
-  return /\.system_generated(?:$|[\/\\])/i.test(targetPath);
+  if (matchesRawProtectedInternalState(targetPath)) return true;
+
+  // Decode candidate Base64 / URL-safe Base64 substrings (length >= 16) to block runtime path decoding
+  // e.g. python3 b64decode(...), node Buffer.from(..., 'base64'), $(echo <b64> | base64 -d)
+  const b64Matches = targetPath.match(/[A-Za-z0-9+/_-]{16,}={0,2}/g);
+  if (b64Matches) {
+    for (const rawTok of b64Matches) {
+      const norm = rawTok.replace(/-/g, "+").replace(/_/g, "/");
+      for (const offset of [0, 1, 2]) {
+        const slice = norm.slice(offset);
+        if (slice.length < 16) continue;
+        try {
+          const decoded = Buffer.from(slice, "base64").toString("utf-8");
+          if (
+            matchesRawProtectedInternalState(decoded) ||
+            /\.system_gen|transcript(?:_full)?\.jsonl/i.test(decoded)
+          ) {
+            return true;
+          }
+        } catch {}
+      }
+    }
+  }
+
+  // Decode candidate Hex substrings (length >= 24) to block Buffer.from(..., 'hex') / bytes.fromhex(...) / xxd -r
+  const hexMatches = targetPath.match(/[0-9a-fA-F]{24,}/g);
+  if (hexMatches) {
+    for (const rawHex of hexMatches) {
+      for (const offset of [0, 1]) {
+        const slice = rawHex.slice(offset);
+        const evenSlice = slice.length % 2 === 0 ? slice : slice.slice(0, -1);
+        if (evenSlice.length < 24) continue;
+        try {
+          const decoded = Buffer.from(evenSlice, "hex").toString("utf-8");
+          if (
+            matchesRawProtectedInternalState(decoded) ||
+            /\.system_gen|transcript(?:_full)?\.jsonl/i.test(decoded)
+          ) {
+            return true;
+          }
+        } catch {}
+      }
+    }
+  }
+
+  // Decode \xNN hex escapes or String.fromCharCode / chr() integer sequences
+  if (/\\x[0-9a-fA-F]{2}/.test(targetPath)) {
+    const unescaped = targetPath.replace(/\\x([0-9a-fA-F]{2})/g, (_, h) => String.fromCharCode(parseInt(h, 16)));
+    if (matchesRawProtectedInternalState(unescaped) || /\.system_gen|transcript(?:_full)?\.jsonl/i.test(unescaped)) {
+      return true;
+    }
+  }
+  if (/(?:fromCharCode|\bchr\s*\(|\bbytes\s*\(\s*\[)/i.test(targetPath)) {
+    const nums = targetPath.match(/\b(?:3[2-9]|[4-9]\d|1[01]\d|12[0-6])\b/g);
+    if (nums && nums.length >= 10) {
+      const decoded = nums.map((n) => String.fromCharCode(Number(n))).join("");
+      if (matchesRawProtectedInternalState(decoded) || /\.system_gen|transcript(?:_full)?\.jsonl/i.test(decoded)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
 }
 
 /**
@@ -193,35 +371,41 @@ function isProtectedBenchmarkPath(targetPath) {
   if (!targetPath || typeof targetPath !== "string") return false;
   const normalized = targetPath.replace(/\\/g, "/");
   return (
-    /\/(?:benchmarks?|evaluators?|evaluation|scoring|ground_truth|prompt_templates)\//i.test(normalized) ||
-    /\/(?:eval_[^\/]+\.(?:py|json|toml)|bench_[^\/]+\.(?:py|json|toml))$/i.test(normalized)
+    /(?:^|\/)(?:benchmarks?|evaluators?|evaluation|scoring|ground_truth|prompt_templates)\//i.test(normalized) ||
+    /(?:^|\/)(?:eval_[^\/]+\.(?:py|json|toml)|bench_[^\/]+\.(?:py|json|toml))$/i.test(normalized)
   );
 }
 
-
 /**
- * Checks if target path references runtime step output spillover file.
+ * Checks if target path strictly matches runtime step output spillover:
+ * `<prefix>/.system_generated/steps/<digits>/output.txt` (or relative `.system_generated/steps/<digits>/output.txt`).
  */
 function isStepSpilloverPath(targetPath) {
   if (!targetPath || typeof targetPath !== "string") return false;
-  if (!isProtectedInternalState(targetPath)) return false; // cheap precheck
-  const normalized = targetPath.replace(/\\/g, "/");
-  return (
-    /\.system_generated[/\\]steps[/\\]\d+[/\\]output\.txt/i.test(normalized) ||
-    (normalized.includes("/.system_generated/steps/") && normalized.endsWith("output.txt"))
-  );
+  const normalized = targetPath.trim().replace(/\\/g, "/");
+  return /(?:^|\/)\.system_generated\/steps\/\d+\/output\.txt$/i.test(normalized);
+}
+
+/**
+ * Checks whether any path token in a command string strictly contains a step spillover path.
+ */
+function findStepSpilloverToken(tokens) {
+  for (const tok of tokens) {
+    const clean = tok.replace(/^file:\/\//i, "");
+    if (isStepSpilloverPath(clean)) return clean;
+  }
+  return null;
 }
 
 /**
  * Extracts the task-log reference from a target path or command, or null.
- * Returns { id, token }: `id` is the bare task id; `token` is the matched path text
- * (relative "tasks/task-1.log" or absolute ".../.system_generated/tasks/task-1.log").
+ * Returns { id, token }: `id` is the bare task id; `token` is the matched path text.
  */
 function getTaskLogMatch(text) {
   if (!text || typeof text !== "string" || !text.includes(".log")) return null;
   const normalized = text.replace(/\\/g, "/");
   if (!normalized.includes("tasks/")) return null;
-  const m = normalized.match(/(?:^|[\s"'])((?:[^\s"']*\/)?tasks\/(?:task-)?([a-zA-Z0-9_-]+)\.log)/i);
+  const m = normalized.match(/(?:^|[\s"'])((?:[^\s"']*\/)?tasks\/(?:task-)?([a-zA-Z0-9_-]+)\.log)(?=$|[\s"'])/i);
   if (!m) return null;
   let token = m[1].replace(/^file:\/\//i, "");
   if (/^\/[A-Za-z]:/.test(token)) token = token.slice(1);
@@ -239,7 +423,6 @@ function getBrainDir() {
   return process.env.AGY_BRAIN_DIR || path.join(getProfileHomeDir(), ".gemini", "antigravity", "brain");
 }
 
-/** Reads the last `bytes` of a file. Returns { text, whole } or null. */
 function readTail(file, bytes) {
   let fd;
   try {
@@ -256,22 +439,12 @@ function readTail(file, bytes) {
   }
 }
 
-/**
- * Looks for the finish / start notices of `taskName` in transcript text using literal needles
- * (JSON-escaped and raw variants). Finish: `<conv>/task-N" finished with result`.
- * Start: `<conv>/task-N` followed by a newline and "Task Description" or "Task logs".
- * Returns "COMPLETED", "RUNNING" or null.
- */
 function scanTaskMarkers(text, taskName) {
   if (text.includes(`/${taskName}\\" finished`) || text.includes(`/${taskName}" finished`)) return "COMPLETED";
   if (text.includes(`/${taskName}\\nTask `) || text.includes(`/${taskName}\nTask `)) return "RUNNING";
   return null;
 }
 
-/**
- * Resolves a background task's lifecycle state: "RUNNING", "COMPLETED" or "UNKNOWN".
- * Authority order: transcript notices (tail first, full file only if needed), then log mtime.
- */
 function getTaskState(match, convId) {
   const taskName = `task-${match.id}`;
   const token = match.token;
@@ -308,13 +481,38 @@ function getTaskState(match, convId) {
   return "UNKNOWN";
 }
 
+// ============================================================================
+// RTK Resolution & `rtk hook antigravity` Delegation
+// ============================================================================
+
 function isCompatibleRtkVersion(versionStr) {
   if (!versionStr || typeof versionStr !== "string") return false;
   const match = versionStr.match(/(\d+)\.(\d+)\.(\d+)/);
   if (!match) return false;
   const major = parseInt(match[1], 10);
   const minor = parseInt(match[2], 10);
-  return major === 0 && (minor === 50 || minor === 51);
+  return major > 1 || (major === 1 && minor >= 1);
+}
+
+function findExecutableOnPath(baseName) {
+  const pathEnv = process.env.PATH || process.env.Path || "";
+  const dirs = pathEnv.split(path.delimiter).filter(Boolean);
+  const isWin = os.platform() === "win32";
+  const exts = isWin ? [".exe", ".cmd", ".bat"] : [""];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, `${baseName}${ext}`);
+      try {
+        const stat = fs.statSync(candidate);
+        if (!stat.isFile()) continue;
+        if (!isWin) {
+          fs.accessSync(candidate, fs.constants.X_OK);
+        }
+        return candidate;
+      } catch {}
+    }
+  }
+  return "";
 }
 
 function getLocalRtkCandidate() {
@@ -331,241 +529,2534 @@ function getLocalRtkCandidate() {
   return "";
 }
 
-function findFirstRtkOnPath() {
-  const pathEnv = process.env.PATH || process.env.Path || "";
-  const dirs = pathEnv.split(path.delimiter).filter(Boolean);
-  const exts = os.platform() === "win32" ? [".exe", ".cmd", ".bat"] : [""];
-  for (const dir of dirs) {
-    for (const ext of exts) {
-      const candidate = path.join(dir, `rtk${ext}`);
-      try {
-        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
-          return candidate;
-        }
-      } catch {}
-    }
-  }
-  return "";
-}
-
 function spawnRtk(bin, args, opts) {
   if (!bin) return { error: Object.assign(new Error("ENOENT"), { code: "ENOENT" }), status: null, stdout: "", stderr: "" };
   if (os.platform() === "win32" && /\.(cmd|bat)$/i.test(bin)) {
+    const comspec =
+      process.env.ComSpec ||
+      process.env.COMSPEC ||
+      path.join(process.env.SystemRoot || process.env.windir || "C:\\Windows", "System32", "cmd.exe");
     const quotedBin = /\s/.test(bin) ? `"${bin}"` : bin;
     const quotedArgs = args.map((a) => (/\s|["&|<>^]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)).join(" ");
-    return spawnSync("cmd.exe", ["/d", "/s", "/c", `"${quotedBin} ${quotedArgs}"`], { ...opts, windowsVerbatimArguments: true });
+    return spawnSync(comspec, ["/d", "/s", "/c", `"${quotedBin} ${quotedArgs}"`], { ...opts, windowsVerbatimArguments: true });
   }
   return spawnSync(bin, args, opts);
 }
 
-const NON_REWRITABLE_BINARIES = new Set([
-  "node", "node.exe",
-  "powershell", "powershell.exe",
-  "pwsh", "pwsh.exe",
-  "cmd", "cmd.exe",
-  "dir",
-  "echo",
-  "cd",
-  "del",
-  "mkdir",
-  "rmdir",
-  "copy",
-  "move",
-  "type",
-  "cls",
-  "clear",
-  "set",
-  "export"
+let cachedRtkKey = null;
+let cachedRtkValue = undefined;
+
+function resolveCompatibleRtk() {
+  const localCandidate = getLocalRtkCandidate();
+  const pathCandidate = findExecutableOnPath("rtk");
+  const key = `${pathCandidate}::${localCandidate}`;
+  if (cachedRtkKey === key && cachedRtkValue !== undefined) {
+    return cachedRtkValue;
+  }
+
+  const opts = { encoding: "utf-8", timeout: 2000, windowsHide: true };
+  let resolved = null;
+
+  // Prefer PATH rtk (>= 1.1.0) before local binaries
+  if (pathCandidate) {
+    const pathRes = spawnRtk(pathCandidate, ["--version"], opts);
+    if (!pathRes.error && pathRes.status === 0 && isCompatibleRtkVersion(pathRes.stdout)) {
+      resolved = { exe: pathCandidate, prefix: "rtk" };
+    }
+  }
+
+  if (!resolved && localCandidate) {
+    const localRes = spawnRtk(localCandidate, ["--version"], opts);
+    if (!localRes.error && localRes.status === 0 && isCompatibleRtkVersion(localRes.stdout)) {
+      const normalizedLocal = localCandidate.replace(/\\/g, "/");
+      const prefix = /\s/.test(normalizedLocal) ? `"${normalizedLocal}"` : normalizedLocal;
+      resolved = { exe: localCandidate, prefix };
+    }
+  }
+
+  cachedRtkKey = key;
+  cachedRtkValue = resolved;
+  return resolved;
+}
+
+// ============================================================================
+// Quote- & Heredoc-Aware Shell Segment Parser & Tokenizer
+// ============================================================================
+
+const SHELL_ESCAPE_CHARS = new Set([" ", "\t", "\n", "\r", ";", "|", "&", "<", ">", "(", ")", '"', "'", "\\", "$", "`"]);
+
+function parseHeredocTag(cmd, pos) {
+  // Assumes cmd[pos] === '<' && cmd[pos + 1] === '<' && cmd[pos + 2] !== '<'
+  let i = pos + 2;
+  let stripTabs = false;
+  if (cmd[i] === "-") {
+    stripTabs = true;
+    i++;
+  }
+  while (i < cmd.length && (cmd[i] === " " || cmd[i] === "\t")) i++;
+  if (i >= cmd.length) return null;
+
+  let delim = "";
+  let quoted = false;
+  const ch = cmd[i];
+  if (ch === "'" || ch === '"') {
+    quoted = true;
+    const q = ch;
+    i++;
+    while (i < cmd.length && cmd[i] !== q && cmd[i] !== "\n" && cmd[i] !== "\r") {
+      if (q === '"' && cmd[i] === "\\" && i + 1 < cmd.length) {
+        i++;
+      }
+      delim += cmd[i++];
+    }
+    if (i < cmd.length && cmd[i] === q) i++;
+  } else {
+    while (i < cmd.length && !/[\s;|&<>()"']/.test(cmd[i])) {
+      if (cmd[i] === "\\" && i + 1 < cmd.length) {
+        quoted = true;
+        i++;
+      }
+      delim += cmd[i++];
+    }
+  }
+
+  if (!delim) return null;
+  return { delim, stripTabs, quoted, endIndex: i };
+}
+
+function readBalancedSubshell(cmd, startPos) {
+  // startPos points right after "$("
+  let i = startPos;
+  let depth = 1;
+  let inSingle = false;
+  let inDouble = false;
+
+  while (i < cmd.length && depth > 0) {
+    const c = cmd[i];
+    if (inSingle) {
+      if (c === "'") inSingle = false;
+      i++;
+      continue;
+    }
+    if (inDouble) {
+      if (c === "\\" && i + 1 < cmd.length) {
+        i += 2;
+        continue;
+      }
+      if (c === '"') inDouble = false;
+      else if (c === "$" && cmd[i + 1] === "(") {
+        depth++;
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (c === "\\" && i + 1 < cmd.length && SHELL_ESCAPE_CHARS.has(cmd[i + 1])) {
+      i += 2;
+      continue;
+    }
+    if (c === "'") {
+      inSingle = true;
+      i++;
+    } else if (c === '"') {
+      inDouble = true;
+      i++;
+    } else if (c === "(") {
+      depth++;
+      i++;
+    } else if (c === ")") {
+      depth--;
+      i++;
+    } else {
+      i++;
+    }
+  }
+
+  const endInner = depth === 0 ? i - 1 : i;
+  return { inner: cmd.slice(startPos, endInner), nextIndex: i };
+}
+
+function readBacktickSubshell(cmd, startPos) {
+  // startPos points right after opening "`"
+  let i = startPos;
+  let inner = "";
+  while (i < cmd.length) {
+    const c = cmd[i];
+    if (c === "\\" && i + 1 < cmd.length) {
+      inner += cmd[i + 1];
+      i += 2;
+      continue;
+    }
+    if (c === "`") {
+      return { inner, nextIndex: i + 1 };
+    }
+    inner += c;
+    i++;
+  }
+  return { inner, nextIndex: i };
+}
+
+/**
+ * Splits a shell command string into segments while respecting single/double quotes,
+ * backslash escapes, `$()` / backtick subshells, process substitutions, and `<<DELIM ... DELIM`
+ * heredoc bodies.
+ */
+function splitShellSegments(command) {
+  if (!command || typeof command !== "string") return [];
+
+  const segments = [];
+  const pendingHeredocs = [];
+  let inSingle = false;
+  let inDouble = false;
+
+  let segStart = 0;
+  let leadingSep = "";
+  let hasRedirect = false;
+  let hasWriteRedirect = false;
+  let hasHeredoc = false;
+  let hasSubshell = false;
+  let subshells = [];
+  let heredocBodies = [];
+  let firstHeredocSegIdx = -1;
+
+  const pushSegment = (endOffset) => {
+    const raw = command.slice(segStart, endOffset);
+    const trimmed = raw.trim();
+    if (trimmed || hasHeredoc) {
+      const leadWS = raw.length - raw.trimStart().length;
+      const trailWS = raw.length - raw.trimEnd().length;
+      segments.push({
+        text: trimmed,
+        raw,
+        start: segStart + leadWS,
+        end: Math.max(segStart + leadWS, endOffset - trailWS),
+        leadingSep,
+        hasRedirect,
+        hasWriteRedirect,
+        hasHeredoc,
+        heredocBodies,
+        hasSubshell,
+        subshells
+      });
+      if (hasHeredoc && firstHeredocSegIdx === -1) {
+        firstHeredocSegIdx = segments.length - 1;
+      }
+    }
+    leadingSep = "";
+    hasRedirect = false;
+    hasWriteRedirect = false;
+    hasHeredoc = false;
+    hasSubshell = false;
+    subshells = [];
+    heredocBodies = [];
+  };
+
+  let i = 0;
+  while (i < command.length) {
+    const c = command[i];
+    const next = command[i + 1];
+
+    if (inSingle) {
+      if (c === "'") inSingle = false;
+      i++;
+      continue;
+    }
+
+    if (inDouble) {
+      if (c === "\\" && i + 1 < command.length) {
+        i += 2;
+        continue;
+      }
+      if (c === '"') {
+        inDouble = false;
+        i++;
+      } else if (c === "$" && next === "(") {
+        hasSubshell = true;
+        const sub = readBalancedSubshell(command, i + 2);
+        subshells.push(sub.inner);
+        i = sub.nextIndex;
+      } else if (c === "`") {
+        hasSubshell = true;
+        const sub = readBacktickSubshell(command, i + 1);
+        subshells.push(sub.inner);
+        i = sub.nextIndex;
+      } else {
+        i++;
+      }
+      continue;
+    }
+
+    // Backslash escape outside quotes (preserve Windows paths like C:\Users\...)
+    if (c === "\\") {
+      if (next === "\r" && command[i + 2] === "\n") {
+        i += 3;
+        continue;
+      }
+      if (next !== undefined && SHELL_ESCAPE_CHARS.has(next)) {
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+
+    if (c === "'") {
+      inSingle = true;
+      i++;
+      continue;
+    }
+
+    if (c === '"') {
+      inDouble = true;
+      i++;
+      continue;
+    }
+
+    // Comments (# at start of segment or after whitespace)
+    if (c === "#" && (i === 0 || /\s/.test(command[i - 1]))) {
+      while (i < command.length && command[i] !== "\n") i++;
+      continue;
+    }
+
+    // Subshells & process substitutions
+    if ((c === "$" || c === "<" || c === ">") && next === "(") {
+      hasSubshell = true;
+      if (c === "<" || c === ">") hasRedirect = true;
+      const sub = readBalancedSubshell(command, i + 2);
+      subshells.push(sub.inner);
+      i = sub.nextIndex;
+      continue;
+    }
+
+    if (c === "(") {
+      hasSubshell = true;
+      const sub = readBalancedSubshell(command, i + 1);
+      subshells.push(sub.inner);
+      i = sub.nextIndex;
+      continue;
+    }
+
+    if (c === "`") {
+      hasSubshell = true;
+      const sub = readBacktickSubshell(command, i + 1);
+      subshells.push(sub.inner);
+      i = sub.nextIndex;
+      continue;
+    }
+
+    // Heredocs << / <<- vs here-string <<< vs input redirect <
+    if (c === "<") {
+      if (next === "<" && command[i + 2] !== "<") {
+        const tag = parseHeredocTag(command, i);
+        if (tag) {
+          hasHeredoc = true;
+          pendingHeredocs.push(tag);
+          i = tag.endIndex;
+          continue;
+        }
+      }
+      hasRedirect = true;
+      i += next === "<" ? (command[i + 2] === "<" ? 3 : 2) : 1;
+      continue;
+    }
+
+    if (c === ">") {
+      hasRedirect = true;
+      hasWriteRedirect = true;
+      i += next === ">" ? 2 : 1;
+      continue;
+    }
+
+    // Newline: flush current segment, then consume any pending heredoc bodies
+    if (c === "\n" || (c === "\r" && next === "\n")) {
+      const nlLen = c === "\r" ? 2 : 1;
+      pushSegment(i);
+      i += nlLen;
+
+      if (pendingHeredocs.length > 0) {
+        const targetIdx = firstHeredocSegIdx !== -1 ? firstHeredocSegIdx : segments.length - 1;
+        while (pendingHeredocs.length > 0) {
+          const hd = pendingHeredocs.shift();
+          const bodyLines = [];
+          while (i < command.length) {
+            const nlPos = command.indexOf("\n", i);
+            const lineEnd = nlPos === -1 ? command.length : nlPos;
+            const rawLine = command.slice(i, lineEnd).replace(/\r$/, "");
+            const checkLine = hd.stripTabs ? rawLine.replace(/^\t+/, "") : rawLine;
+            i = nlPos === -1 ? command.length : nlPos + 1;
+            if (checkLine === hd.delim) {
+              break;
+            }
+            bodyLines.push(rawLine);
+          }
+          if (targetIdx >= 0 && segments[targetIdx]) {
+            segments[targetIdx].heredocBodies.push(bodyLines.join("\n"));
+          }
+        }
+        firstHeredocSegIdx = -1;
+      }
+
+      segStart = i;
+      leadingSep = "\n";
+      continue;
+    }
+
+    // Operators: &&, ||, |&, |, ;, &
+    if (c === "&" && next === "&") {
+      pushSegment(i);
+      i += 2;
+      segStart = i;
+      leadingSep = "&&";
+      continue;
+    }
+    if (c === "|" && next === "|") {
+      pushSegment(i);
+      i += 2;
+      segStart = i;
+      leadingSep = "||";
+      continue;
+    }
+    if (c === "|" && next === "&") {
+      pushSegment(i);
+      i += 2;
+      segStart = i;
+      leadingSep = "|&";
+      continue;
+    }
+    if (c === "|") {
+      pushSegment(i);
+      i += 1;
+      segStart = i;
+      leadingSep = "|";
+      continue;
+    }
+    if (c === ";") {
+      pushSegment(i);
+      i += 1;
+      segStart = i;
+      leadingSep = ";";
+      continue;
+    }
+    if (c === "&") {
+      // Exclude fd redirects like >&2, 2>&1, <&0, &>file
+      const prevChar = i > 0 ? command[i - 1] : "";
+      if (prevChar === ">" || prevChar === "<") {
+        hasRedirect = true;
+        i++;
+        continue;
+      }
+      if (next === ">") {
+        hasRedirect = true;
+        hasWriteRedirect = true;
+        i += 2;
+        continue;
+      }
+      pushSegment(i);
+      i += 1;
+      segStart = i;
+      leadingSep = "&";
+      continue;
+    }
+
+    i++;
+  }
+
+  pushSegment(command.length);
+  return segments;
+}
+
+/**
+ * Tokenizes a single shell segment into words (preserving raw token text & unquoted value).
+ */
+const REDIRECT_OP_REGEX = /^(?:&>>?|(?:\d+)?(?:>>?|<<<?|<<-|<&|>&|>\||<>))$/;
+const REDIRECT_ATTACHED_REGEX = /^(?:\d+)?(?:>>?|<<?)(.+)$/;
+
+function tokenizeShellWordsDetailed(text) {
+  const tokens = [];
+  let i = 0;
+
+  while (i < text.length) {
+    while (i < text.length && /\s/.test(text[i])) i++;
+    if (i >= text.length) break;
+
+    const start = i;
+    let value = "";
+    let quoted = false;
+
+    while (i < text.length && !/\s/.test(text[i])) {
+      const c = text[i];
+      if (c === ">" || c === "<") {
+        if (i > start) {
+          const prefixRaw = text.slice(start, i);
+          const isFdOrAmpPrefix = !quoted && (/^\d+$/.test(prefixRaw) || (c === ">" && prefixRaw === "&"));
+          if (!isFdOrAmpPrefix) {
+            break;
+          }
+        }
+        i++;
+        if (i < text.length && (text[i] === c || text[i] === "&" || (c === ">" && text[i] === "|") || (c === "<" && text[i] === ">"))) {
+          i++;
+          if (i < text.length && (text[i] === "<" || text[i] === ">" || text[i] === "-")) {
+            i++;
+          }
+        }
+        value = text.slice(start, i);
+        break;
+      } else if (c === "&" && i + 1 < text.length && text[i + 1] === ">" && i === start) {
+        i += 2;
+        if (i < text.length && text[i] === ">") i++;
+        value = text.slice(start, i);
+        break;
+      } else if (c === "'") {
+        quoted = true;
+        i++;
+        while (i < text.length && text[i] !== "'") {
+          value += text[i++];
+        }
+        if (i < text.length && text[i] === "'") i++;
+      } else if (c === '"') {
+        quoted = true;
+        i++;
+        while (i < text.length && text[i] !== '"') {
+          if (text[i] === "\\" && i + 1 < text.length && (text[i + 1] === '"' || text[i + 1] === "\\" || text[i + 1] === "$" || text[i + 1] === "`")) {
+            value += text[i + 1];
+            i += 2;
+          } else {
+            value += text[i++];
+          }
+        }
+        if (i < text.length && text[i] === '"') i++;
+      } else if (c === "\\" && i + 1 < text.length && SHELL_ESCAPE_CHARS.has(text[i + 1])) {
+        value += text[i + 1];
+        i += 2;
+      } else {
+        value += c;
+        i++;
+      }
+    }
+
+    tokens.push({ raw: text.slice(start, i), value, quoted, start, end: i });
+  }
+
+  return tokens;
+}
+
+const ENV_VALUE_FLAGS = new Set(["-u", "--unset", "-C", "--chdir", "-S", "--split-string"]);
+
+function splitEnvPrefix(text) {
+  const tokens = tokenizeShellWordsDetailed(text);
+  let idx = 0;
+
+  while (idx < tokens.length) {
+    const tok = tokens[idx];
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tok.raw)) {
+      idx++;
+      continue;
+    }
+    if (normalizeCmdName(tok.value) === "env") {
+      idx++;
+      while (idx < tokens.length) {
+        const sub = tokens[idx];
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(sub.raw)) {
+          idx++;
+          continue;
+        }
+        if (sub.value.startsWith("-") && sub.value !== "-") {
+          idx++;
+          if (ENV_VALUE_FLAGS.has(sub.value) && idx < tokens.length) {
+            idx++;
+          }
+          continue;
+        }
+        break;
+      }
+      continue;
+    }
+    break;
+  }
+
+  if (idx === 0) return { prefix: "", body: text };
+  if (idx >= tokens.length) return { prefix: text, body: "" };
+  return {
+    prefix: text.slice(0, tokens[idx].start),
+    body: text.slice(tokens[idx].start)
+  };
+}
+
+function tokenizeShellWords(text) {
+  return tokenizeShellWordsDetailed(text).map((t) => t.value);
+}
+
+function hasDotDotTraversal(str) {
+  if (!str || typeof str !== "string") return false;
+  return /(?:^|[\/\\])\.\.(?:$|[\/\\])/.test(str);
+}
+
+function tryRealpath(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    try {
+      const parent = path.dirname(p);
+      const base = path.basename(p);
+      return path.join(fs.realpathSync(parent), base);
+    } catch {
+      return path.resolve(p);
+    }
+  }
+}
+
+function isPathInsideDir(candidatePath, baseDir) {
+  const norm = (p) => (os.platform() === "win32" ? p.toLowerCase() : p);
+  const resolvedCandidate = norm(tryRealpath(path.resolve(candidatePath)));
+  const resolvedBase = norm(tryRealpath(path.resolve(baseDir)));
+  const prefix = resolvedBase.endsWith(path.sep) ? resolvedBase : resolvedBase + path.sep;
+  return resolvedCandidate.startsWith(prefix);
+}
+
+function normalizeCmdName(token) {
+  const base = path.basename(token.replace(/\\/g, "/")).toLowerCase();
+  return base.replace(/\.(exe|cmd|bat|mjs|cjs|js)$/i, "");
+}
+
+// ============================================================================
+// Internal State & `agy-context transcript` Governance
+// ============================================================================
+
+const TRANSCRIPT_READ_SUBCOMMANDS = new Set([
+  "read",
+  "query",
+  "step",
+  "health",
+  "list",
+  "ls",
+  "grep",
+  "search",
+  "find",
+  "stats",
+  "info",
+  "tools",
+  "outline",
+  "summary"
+]);
+const TRANSCRIPT_HELP_SUBCOMMANDS = new Set(["help", "--help", "-h"]);
+const TRANSCRIPT_ADMIN_SUBCOMMANDS = new Set(["access", "policy"]);
+const COMMAND_WRAPPERS = new Set([
+  "command",
+  "builtin",
+  "exec",
+  "nohup",
+  "time",
+  "nice",
+  "timeout",
+  "stdbuf",
+  "setsid",
+  "chrt",
+  "ionice",
+  "taskset",
+  "xargs"
 ]);
 
-const REWRITE_CACHE_FILE = path.join(getStateDir(), "agy-rtk-rewrite-cache.json");
-const REWRITE_CACHE_MAX = 100;
-let inMemoryRewriteCache = null;
+function isAllowedAgyContextScriptPath(scriptToken) {
+  if (!scriptToken || hasDotDotTraversal(scriptToken)) return false;
+  const normalized = scriptToken.replace(/\\/g, "/");
+  if (!normalized.endsWith("/bin/agy-context.mjs") && normalized !== "bin/agy-context.mjs") {
+    return false;
+  }
+
+  const hookDir = path.dirname(fileURLToPath(import.meta.url));
+  const repoOrPluginRoot = path.resolve(hookDir, "..");
+  const installedPluginRoot = path.join(getProfileHomeDir(), ".gemini", "config", "plugins", "agy-context-saver");
+  const allowedTargets = new Set([
+    tryRealpath(path.join(repoOrPluginRoot, "bin", "agy-context.mjs")),
+    tryRealpath(path.join(installedPluginRoot, "bin", "agy-context.mjs"))
+  ]);
+  const resolvedArg = tryRealpath(path.resolve(scriptToken));
+  if (allowedTargets.has(resolvedArg)) return true;
+
+  // Also allow relative "bin/agy-context.mjs" when invoked from repo/plugin root
+  if (normalized === "bin/agy-context.mjs") return true;
+  return false;
+}
+
+function isAllowedAgyContextBinaryToken(binToken) {
+  if (!binToken || hasDotDotTraversal(binToken)) return false;
+  const normalized = binToken.replace(/\\/g, "/");
+  if (!normalized.includes("/")) {
+    const base = normalizeCmdName(normalized);
+    return base === "agy-context" || base === "agy-context-saver";
+  }
+  if (isAllowedAgyContextScriptPath(binToken)) return true;
+  if (/\/\.gemini\/antigravity\/bin\/agy-context(?:-saver)?(?:\.(?:exe|cmd|bat))?$/i.test(normalized)) {
+    return true;
+  }
+  return false;
+}
+
+function extractWrappedScriptInfo(segText) {
+  const trimmed = (segText || "").trim();
+  if (!trimmed) return null;
+
+  // Unpack `env -S "..."` or `env --split-string="..."`
+  const rawTokens = tokenizeShellWordsDetailed(trimmed);
+  for (let i = 0; i < rawTokens.length; i++) {
+    const tok = rawTokens[i];
+    if (normalizeCmdName(tok.value) === "env") {
+      for (let j = i + 1; j < rawTokens.length; j++) {
+        const sub = rawTokens[j].value;
+        if ((sub === "-S" || sub === "--split-string") && rawTokens[j + 1]) {
+          const restAfter = rawTokens.slice(j + 2).map((t) => t.value).join(" ");
+          return {
+            hadEnvPrefix: true,
+            innerScript: `${rawTokens[j + 1].value}${restAfter ? " " + restAfter : ""}`.trim()
+          };
+        }
+        if (sub.startsWith("-S") && sub.length > 2) {
+          const restAfter = rawTokens.slice(j + 1).map((t) => t.value).join(" ");
+          return {
+            hadEnvPrefix: true,
+            innerScript: `${sub.slice(2)}${restAfter ? " " + restAfter : ""}`.trim()
+          };
+        }
+        if (sub.startsWith("--split-string=")) {
+          const restAfter = rawTokens.slice(j + 1).map((t) => t.value).join(" ");
+          return {
+            hadEnvPrefix: true,
+            innerScript: `${sub.slice("--split-string=".length)}${restAfter ? " " + restAfter : ""}`.trim()
+          };
+        }
+      }
+    }
+  }
+
+  const { prefix: envPrefix, body } = splitEnvPrefix(trimmed);
+  const effective = (body || trimmed).trim();
+  const detailed = tokenizeShellWordsDetailed(effective);
+  if (detailed.length === 0) return null;
+  const cmd0 = normalizeCmdName(detailed[0].value);
+  if (cmd0 === "eval" && detailed.length >= 2) {
+    return {
+      hadEnvPrefix: Boolean(envPrefix.trim()),
+      innerScript: detailed.slice(1).map((t) => t.value).join(" ")
+    };
+  }
+  if ((cmd0 === "bash" || cmd0 === "sh" || cmd0 === "zsh" || cmd0 === "dash") && detailed.length >= 3) {
+    for (let i = 1; i < detailed.length - 1; i++) {
+      const flag = detailed[i].value;
+      if (flag === "--") break;
+      if (/^-[a-z]*c$/i.test(flag)) {
+        return {
+          hadEnvPrefix: Boolean(envPrefix.trim()),
+          innerScript: detailed[i + 1].value
+        };
+      }
+    }
+  }
+  if (COMMAND_WRAPPERS.has(cmd0) && detailed.length >= 2) {
+    let subStart = 1;
+    while (subStart < detailed.length && detailed[subStart].value.startsWith("-")) {
+      const fl = detailed[subStart].value;
+      subStart++;
+      if ((cmd0 === "nice" && fl === "-n") || (cmd0 === "timeout" && (fl === "-k" || fl === "-s"))) {
+        if (subStart < detailed.length) subStart++;
+      }
+    }
+    if (cmd0 === "timeout" && subStart < detailed.length && /^\d/.test(detailed[subStart].value)) {
+      subStart++;
+    }
+    if (subStart < detailed.length) {
+      return {
+        hadEnvPrefix: true,
+        innerScript: detailed.slice(subStart).map((t) => t.value).join(" ")
+      };
+    }
+  }
+  return null;
+}
+
+function parseAgyContextTranscriptTokens(tokens) {
+  if (!Array.isArray(tokens) || tokens.length === 0) return null;
+  const cmd0 = normalizeCmdName(tokens[0]);
+  let subOffset = -1;
+  let hasNodeFlags = false;
+  let invalidBinaryPath = false;
+
+  if ((cmd0 === "agy-context" || cmd0 === "agy-context-saver") && tokens[1] === "transcript") {
+    subOffset = 2;
+    if (!isAllowedAgyContextBinaryToken(tokens[0])) {
+      invalidBinaryPath = true;
+    }
+  } else if (cmd0 === "node" && tokens.length >= 3) {
+    for (let i = 1; i < tokens.length - 1; i++) {
+      const tok = tokens[i];
+      if (
+        (isAllowedAgyContextScriptPath(tok) || normalizeCmdName(tok) === "agy-context" || normalizeCmdName(tok) === "agy-context-saver") &&
+        tokens[i + 1] === "transcript"
+      ) {
+        subOffset = i + 2;
+        hasNodeFlags = i !== 1;
+        if (!isAllowedAgyContextScriptPath(tok)) {
+          invalidBinaryPath = true;
+        }
+        break;
+      }
+    }
+  }
+
+  if (subOffset === -1) return null;
+  const rawSub = tokens[subOffset];
+  const subcommand = rawSub !== undefined ? String(rawSub).trim() : "help";
+  const isReadSub = TRANSCRIPT_READ_SUBCOMMANDS.has(subcommand);
+  const isHelpSub = TRANSCRIPT_HELP_SUBCOMMANDS.has(subcommand);
+  const isAdminSub = TRANSCRIPT_ADMIN_SUBCOMMANDS.has(subcommand);
+  const isKnownSubcommand = isReadSub || isHelpSub || isAdminSub;
+
+  return {
+    subOffset,
+    subcommand,
+    isReadSub,
+    isHelpSub,
+    isAdminSub,
+    isKnownSubcommand,
+    hasNodeFlags,
+    invalidBinaryPath,
+    tokens
+  };
+}
+
+function findAgyContextTranscriptUsage(segments, depth = 0) {
+  if (depth > 4) return null;
+  for (let idx = 0; idx < segments.length; idx++) {
+    const seg = segments[idx];
+    let text = (seg.text || "").trim();
+    let wrappedInSubshell = false;
+    while (text.startsWith("(") && text.endsWith(")")) {
+      wrappedInSubshell = true;
+      text = text.slice(1, -1).trim();
+    }
+    const { prefix: envPrefix, body } = splitEnvPrefix(text);
+    const hadWrapper = wrappedInSubshell || Boolean(envPrefix.trim());
+    const directTokens = tokenizeShellWords(body || text);
+    const parsedDirect = parseAgyContextTranscriptTokens(directTokens);
+    if (parsedDirect) {
+      return { ...parsedDirect, seg, segIndex: idx, totalSegs: segments.length, hadWrapper };
+    }
+    const wrapped = extractWrappedScriptInfo(text);
+    if (wrapped && wrapped.innerScript) {
+      const innerMatch = findAgyContextTranscriptUsage(splitShellSegments(wrapped.innerScript), depth + 1);
+      if (innerMatch) {
+        return { ...innerMatch, hadWrapper: true, totalSegs: Math.max(segments.length, innerMatch.totalSegs) };
+      }
+    }
+    if (Array.isArray(seg.subshells)) {
+      for (const sub of seg.subshells) {
+        const subMatch = findAgyContextTranscriptUsage(splitShellSegments(sub), depth + 1);
+        if (subMatch) {
+          return { ...subMatch, hadWrapper: true, totalSegs: Math.max(segments.length, 2) };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// ============================================================================
+// Transcript Access Policy & Lineage Engine (Refined Approach D)
+// ============================================================================
+
+const HOOK_GRANT_TTL_MS = 10000;
+const STANDALONE_DIRECTIVE_LINE_RE = /^(?:@[a-zA-Z0-9_-]+\s+)?\[agy-transcript-access:\s*(deny|self-only|allow)\]\s*$/i;
+
+function getTranscriptAccessPolicyPath() {
+  return path.join(getStateDir(), "transcript-access.json");
+}
+
+function normalizePatternList(rawList) {
+  if (!rawList) return [];
+  const arr = Array.isArray(rawList)
+    ? rawList
+    : String(rawList)
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+  return Array.from(new Set(arr.map((s) => String(s).trim()).filter(Boolean)));
+}
+
+function readTranscriptAccessStore() {
+  const filePath = getTranscriptAccessPolicyPath();
+  const now = Date.now();
+  const baseStore = {
+    version: 1,
+    activeOwnerId: null,
+    policies: {},
+    lastHookGrant: null,
+    lastAccessMutationGrant: null
+  };
+  try {
+    if (!fs.existsSync(filePath)) return baseStore;
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    if (!parsed || typeof parsed !== "object") return baseStore;
+
+    const policies = {};
+    const rawPolicies = parsed.policies && typeof parsed.policies === "object" ? parsed.policies : {};
+    for (const [ownerId, pol] of Object.entries(rawPolicies)) {
+      if (!pol || typeof pol !== "object") continue;
+      const updatedAt = Number(pol.updatedAt || pol.createdAt || 0);
+      const ttlMs = Number(pol.ttlMs) > 0 ? Number(pol.ttlMs) : STATE_TTL_MS;
+      if (updatedAt > 0 && (now - updatedAt) < ttlMs) {
+        policies[ownerId] = {
+          ownerId: String(pol.ownerId || ownerId),
+          mode: ["open", "allowlist", "self-only", "deny"].includes(pol.mode) ? pol.mode : "open",
+          allow: normalizePatternList(pol.allow),
+          deny: normalizePatternList(pol.deny),
+          createdAt: Number(pol.createdAt || updatedAt),
+          updatedAt,
+          ttlMs
+        };
+      }
+    }
+
+    let activeOwnerId = parsed.activeOwnerId && policies[parsed.activeOwnerId] ? parsed.activeOwnerId : null;
+    if (!activeOwnerId) {
+      const sortedOwners = Object.values(policies).sort((a, b) => b.updatedAt - a.updatedAt);
+      if (sortedOwners.length > 0) activeOwnerId = sortedOwners[0].ownerId;
+    }
+
+    const lastHookGrant =
+      parsed.lastHookGrant &&
+      typeof parsed.lastHookGrant === "object" &&
+      typeof parsed.lastHookGrant.ts === "number" &&
+      (now - parsed.lastHookGrant.ts) < HOOK_GRANT_TTL_MS
+        ? parsed.lastHookGrant
+        : null;
+
+    const lastAccessMutationGrant =
+      parsed.lastAccessMutationGrant &&
+      typeof parsed.lastAccessMutationGrant === "object" &&
+      typeof parsed.lastAccessMutationGrant.ts === "number" &&
+      (now - parsed.lastAccessMutationGrant.ts) < HOOK_GRANT_TTL_MS
+        ? parsed.lastAccessMutationGrant
+        : null;
+
+    return {
+      version: 1,
+      activeOwnerId,
+      policies,
+      lastHookGrant,
+      lastAccessMutationGrant
+    };
+  } catch {
+    return baseStore;
+  }
+}
+
+function writeTranscriptAccessStore(store) {
+  ensureStateDir();
+  const filePath = getTranscriptAccessPolicyPath();
+  try {
+    const payload = JSON.stringify(
+      {
+        version: 1,
+        activeOwnerId: store.activeOwnerId || null,
+        policies: store.policies || {},
+        lastHookGrant: store.lastHookGrant || null,
+        lastAccessMutationGrant: store.lastAccessMutationGrant || null
+      },
+      null,
+      2
+    );
+    const tmpFile = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    fs.writeFileSync(tmpFile, payload, "utf-8");
+    try {
+      fs.renameSync(tmpFile, filePath);
+    } catch {
+      fs.writeFileSync(filePath, payload, "utf-8");
+      try { fs.unlinkSync(tmpFile); } catch {}
+    }
+  } catch {}
+}
+
+function recordTranscriptHookGrant({
+  callerConvId = "global",
+  subcommand = "read",
+  targetConvId = null,
+  mode = "open",
+  isMutation = false
+} = {}) {
+  const store = readTranscriptAccessStore();
+  const now = Date.now();
+  if (isMutation) {
+    store.lastAccessMutationGrant = {
+      callerConvId,
+      ts: now
+    };
+  } else {
+    store.lastHookGrant = {
+      callerConvId,
+      subcommand,
+      targetConvId,
+      mode,
+      ts: now
+    };
+  }
+  writeTranscriptAccessStore(store);
+}
+
+function extractFirstLineDirective(bodyText) {
+  if (!bodyText || typeof bodyText !== "string") return null;
+  let cleaned = bodyText.replace(/<\/SYSTEM_MESSAGE>[\s\S]*$/i, "");
+  cleaned = cleaned.replace(/^\s*<USER_REQUEST>\s*/i, "");
+  const lines = cleaned.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const m = trimmed.match(STANDALONE_DIRECTIVE_LINE_RE);
+    return m ? m[1].toLowerCase() : null;
+  }
+  return null;
+}
+
+/**
+ * Inspects Steps 0–2 of `<brainDir>/<convId>/.system_generated/logs/transcript.jsonl`
+ * to deterministically classify top-level user chats vs. `/swarm` workers vs. subagents,
+ * extract `parentConvId` and `@rosterName`, and parse any first-line `[agy-transcript-access: ...]` directive.
+ */
+function getCallerLineage(convId) {
+  if (!convId || convId === "global") {
+    return {
+      transcriptFound: false,
+      isTopLevelUserSession: false,
+      isChildSession: false,
+      isSwarmChild: false,
+      parentConvId: null,
+      rosterName: null,
+      launchDirective: null,
+      birthTimeMs: 0
+    };
+  }
+
+  const session = getSessionState(convId);
+  if (session.lineage && session.lineage.transcriptFound) {
+    return session.lineage;
+  }
+
+  const brainDir = getBrainDir();
+  const compactPath = path.join(brainDir, convId, ".system_generated", "logs", "transcript.jsonl");
+  const fullPath = path.join(brainDir, convId, ".system_generated", "logs", "transcript_full.jsonl");
+  const targetFile = fs.existsSync(compactPath) ? compactPath : (fs.existsSync(fullPath) ? fullPath : null);
+
+  if (!targetFile) {
+    return {
+      transcriptFound: false,
+      isTopLevelUserSession: false,
+      isChildSession: false,
+      isSwarmChild: false,
+      parentConvId: null,
+      rosterName: null,
+      launchDirective: null,
+      birthTimeMs: 0
+    };
+  }
+
+  let birthTimeMs = Date.now();
+  let headStr = "";
+  try {
+    const st = fs.statSync(targetFile);
+    const candidates = [st.birthtimeMs, st.ctimeMs, st.mtimeMs].filter((n) => Number.isFinite(n) && n > 0);
+    if (candidates.length > 0) birthTimeMs = Math.min(...candidates);
+
+    const fd = fs.openSync(targetFile, "r");
+    try {
+      const buf = Buffer.alloc(16384);
+      const bytesRead = fs.readSync(fd, buf, 0, buf.length, 0);
+      headStr = buf.toString("utf-8", 0, bytesRead);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {}
+
+  let isTopLevelUserSession = false;
+  let isChildSession = false;
+  let isSwarmChild = false;
+  let parentConvId = null;
+  let rosterName = null;
+  let launchDirective = null;
+
+  const lines = headStr.split(/\r?\n/).filter((l) => l.trim()).slice(0, 4);
+  for (let i = 0; i < lines.length; i++) {
+    let item = null;
+    try {
+      item = JSON.parse(lines[i]);
+    } catch {
+      continue;
+    }
+    const content = typeof item?.content === "string" ? item.content : "";
+    if (i === 0 && (item?.type === "USER_INPUT" || item?.source === "USER_EXPLICIT")) {
+      isTopLevelUserSession = true;
+      launchDirective = extractFirstLineDirective(content);
+      break;
+    }
+
+    if (item?.type === "SYSTEM_MESSAGE" || item?.source === "SYSTEM") {
+      const senderMatch = content.match(/\[Message\][^\n]*\bsender=([a-zA-Z0-9_-]{4,})\b/);
+      if (senderMatch) {
+        isChildSession = true;
+        if (!parentConvId) parentConvId = senderMatch[1];
+      }
+
+      const swarmAssignMatch = content.match(
+        /Your assignment \(recorded on the board as #\d+ for @([a-zA-Z0-9_-]+)\):([\s\S]*)$/
+      );
+      if (swarmAssignMatch) {
+        isChildSession = true;
+        isSwarmChild = true;
+        rosterName = swarmAssignMatch[1];
+        const dir = extractFirstLineDirective(swarmAssignMatch[2]);
+        if (dir) launchDirective = dir;
+        break;
+      }
+
+      if (senderMatch && i === 0 && !content.includes("content=[swarm] new board message")) {
+        const msgBodyMatch = content.match(/\bpriority=MESSAGE_PRIORITY_[A-Z_]+\s+content=([\s\S]*)$/);
+        if (msgBodyMatch) {
+          const dir = extractFirstLineDirective(msgBodyMatch[1]);
+          if (dir) launchDirective = dir;
+        }
+      }
+    }
+  }
+
+  const lineage = {
+    transcriptFound: lines.length > 0,
+    isTopLevelUserSession,
+    isChildSession,
+    isSwarmChild,
+    parentConvId,
+    rosterName,
+    launchDirective,
+    birthTimeMs
+  };
+
+  if (lineage.transcriptFound) {
+    session.lineage = lineage;
+    saveSessionState(convId, session, { updatePollTime: false });
+  }
+  return lineage;
+}
+
+function matchesAgentPattern(pattern, callerConvId, rosterName) {
+  if (!pattern) return false;
+  const rawPat = String(pattern).trim().toLowerCase();
+  if (!rawPat) return false;
+  const isRosterPat = rawPat.startsWith("@");
+  const cleanPat = isRosterPat ? rawPat.slice(1) : rawPat;
+  const isGlob = cleanPat.endsWith("*");
+  const prefix = isGlob ? cleanPat.slice(0, -1) : cleanPat;
+
+  if (rosterName) {
+    const cleanRoster = String(rosterName).trim().toLowerCase().replace(/^@/, "");
+    if (isGlob ? cleanRoster.startsWith(prefix) : cleanRoster === cleanPat) {
+      return true;
+    }
+  }
+  if (!isRosterPat && callerConvId) {
+    const cleanId = String(callerConvId).trim().toLowerCase();
+    if (isGlob ? cleanId.startsWith(prefix) : cleanId === cleanPat) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function matchesAgentList(list, callerConvId, rosterName) {
+  if (!Array.isArray(list) || list.length === 0) return false;
+  return list.some((pat) => matchesAgentPattern(pat, callerConvId, rosterName));
+}
+
+function findGoverningPolicyForCaller(store, convId, lineage) {
+  const policies = store?.policies || {};
+  const policyList = Object.values(policies).sort((a, b) => b.updatedAt - a.updatedAt);
+  if (policyList.length === 0) return null;
+
+  // 1. If caller is an owner itself, return its own policy
+  if (convId && policies[convId]) {
+    return policies[convId];
+  }
+
+  // 2. If caller is explicitly listed in any active policy's deny or allow list
+  for (const pol of policyList) {
+    if (matchesAgentList(pol.deny, convId, lineage.rosterName) || matchesAgentList(pol.allow, convId, lineage.rosterName)) {
+      return pol;
+    }
+  }
+
+  // 3. Verified top-level user conversation (`USER_INPUT` at Step 0) is NEVER subject to another session's child lock
+  if (lineage.isTopLevelUserSession && !lineage.isChildSession) {
+    return null;
+  }
+
+  // 4. Child session with explicit `sender=<parentConvId>` in Step 0/1
+  if (lineage.isChildSession && lineage.parentConvId) {
+    return policies[lineage.parentConvId] || policies["local-operator"] || policies["global"] || null;
+  }
+
+  // 5. Fallback for synthetic test conversationIds (when transcript file does not exist on disk)
+  if (!lineage.transcriptFound) {
+    return (store.activeOwnerId && policies[store.activeOwnerId]) || policyList[0] || null;
+  }
+
+  return null;
+}
+
+function evaluateCallerTranscriptAccess(convId) {
+  const lineage = getCallerLineage(convId);
+  const store = readTranscriptAccessStore();
+  const policy = findGoverningPolicyForCaller(store, convId, lineage);
+
+  // Tier 1: Policy owner
+  if (policy && convId && policy.ownerId === convId) {
+    return {
+      allowed: true,
+      mode: "open",
+      source: "owner",
+      isOwner: true,
+      isRestrictedChild: false,
+      rosterName: lineage.rosterName,
+      ownerId: policy.ownerId
+    };
+  }
+
+  // Tier 2: Explicit CLI --deny match
+  if (policy && matchesAgentList(policy.deny, convId, lineage.rosterName)) {
+    return {
+      allowed: false,
+      mode: "deny",
+      source: "cli-deny-list",
+      isOwner: false,
+      isRestrictedChild: true,
+      rosterName: lineage.rosterName,
+      ownerId: policy.ownerId
+    };
+  }
+
+  // Tier 3: Explicit CLI --allow match
+  if (policy && matchesAgentList(policy.allow, convId, lineage.rosterName)) {
+    return {
+      allowed: true,
+      mode: "open",
+      source: "cli-allow-list",
+      isOwner: false,
+      isRestrictedChild: false,
+      rosterName: lineage.rosterName,
+      ownerId: policy.ownerId
+    };
+  }
+
+  // Tier 4: First-line launch directive (`[agy-transcript-access: allow|self-only|deny]`)
+  if (lineage.launchDirective) {
+    if (lineage.launchDirective === "deny") {
+      return {
+        allowed: false,
+        mode: "deny",
+        source: "launch-directive",
+        isOwner: false,
+        isRestrictedChild: true,
+        rosterName: lineage.rosterName,
+        ownerId: policy ? policy.ownerId : lineage.parentConvId
+      };
+    }
+    // If parent updated policy to deny/allowlist AFTER child launch, parent mid-session lock overrides
+    const parentOverrodeMidSession =
+      Boolean(policy) &&
+      (policy.mode === "deny" || policy.mode === "allowlist") &&
+      lineage.birthTimeMs > 0 &&
+      policy.updatedAt > lineage.birthTimeMs + 1000;
+
+    if (parentOverrodeMidSession) {
+      return {
+        allowed: false,
+        mode: policy.mode,
+        source: "cli-policy-override",
+        isOwner: false,
+        isRestrictedChild: true,
+        rosterName: lineage.rosterName,
+        ownerId: policy.ownerId
+      };
+    }
+
+    if (lineage.launchDirective === "self-only") {
+      return {
+        allowed: true,
+        mode: "self-only",
+        source: "launch-directive",
+        isOwner: false,
+        isRestrictedChild: true,
+        rosterName: lineage.rosterName,
+        ownerId: policy ? policy.ownerId : lineage.parentConvId
+      };
+    }
+    if (lineage.launchDirective === "allow") {
+      return {
+        allowed: true,
+        mode: "open",
+        source: "launch-directive",
+        isOwner: false,
+        isRestrictedChild: false,
+        rosterName: lineage.rosterName,
+        ownerId: policy ? policy.ownerId : lineage.parentConvId
+      };
+    }
+  }
+
+  // Tier 5: Cohort default mode from governing parent policy
+  if (policy) {
+    if (policy.mode === "deny" || policy.mode === "allowlist") {
+      return {
+        allowed: false,
+        mode: policy.mode,
+        source: "cli-policy",
+        isOwner: false,
+        isRestrictedChild: true,
+        rosterName: lineage.rosterName,
+        ownerId: policy.ownerId
+      };
+    }
+    if (policy.mode === "self-only") {
+      return {
+        allowed: true,
+        mode: "self-only",
+        source: "cli-policy",
+        isOwner: false,
+        isRestrictedChild: true,
+        rosterName: lineage.rosterName,
+        ownerId: policy.ownerId
+      };
+    }
+  }
+
+  return {
+    allowed: true,
+    mode: "open",
+    source: "default",
+    isOwner: !lineage.isChildSession,
+    isRestrictedChild: false,
+    rosterName: lineage.rosterName,
+    ownerId: policy ? policy.ownerId : null
+  };
+}
+
+function canCallerMutateTranscriptAccess(convId) {
+  const lineage = getCallerLineage(convId);
+  if (lineage.isChildSession || lineage.isSwarmChild) {
+    return false;
+  }
+  if (lineage.launchDirective === "deny" || lineage.launchDirective === "self-only") {
+    return false;
+  }
+  const store = readTranscriptAccessStore();
+  const policy = findGoverningPolicyForCaller(store, convId, lineage);
+  if (policy && convId && policy.ownerId !== convId && !lineage.isTopLevelUserSession) {
+    return false;
+  }
+  return true;
+}
+
+function extractTargetConvIdFromTranscriptTokens(subcommand, restTokens) {
+  const READ_VALUE_FLAGS = new Set(["id", "mode", "last-turns", "last", "tail", "offset", "limit", "start", "end", "file"]);
+  const QUERY_VALUE_FLAGS = new Set([
+    "id",
+    "query",
+    "roles",
+    "mode",
+    "start",
+    "end",
+    "last-turns",
+    "last",
+    "tail",
+    "limit",
+    "field",
+    "file"
+  ]);
+  const STEP_VALUE_FLAGS = new Set([
+    "id",
+    "step",
+    "start",
+    "end",
+    "field",
+    "mode",
+    "tail",
+    "tail-lines",
+    "head",
+    "head-lines",
+    "file"
+  ]);
+  const HEALTH_VALUE_FLAGS = new Set(["id", "file"]);
+
+  let valueFlags = READ_VALUE_FLAGS;
+  if (subcommand === "query" || subcommand === "grep" || subcommand === "search" || subcommand === "find" || subcommand === "tools") {
+    valueFlags = QUERY_VALUE_FLAGS;
+  } else if (subcommand === "step") {
+    valueFlags = STEP_VALUE_FLAGS;
+  } else if (subcommand === "health" || subcommand === "stats" || subcommand === "info") {
+    valueFlags = HEALTH_VALUE_FLAGS;
+  }
+
+  const opts = {};
+  const positionals = [];
+  for (let i = 0; i < restTokens.length; i++) {
+    const tok = restTokens[i];
+    if (!tok.startsWith("-") || tok === "-") {
+      positionals.push(tok);
+      continue;
+    }
+    if (!tok.startsWith("--")) continue;
+    const eqIdx = tok.indexOf("=");
+    const key = eqIdx === -1 ? tok.slice(2) : tok.slice(2, eqIdx);
+    const inlineVal = eqIdx === -1 ? null : tok.slice(eqIdx + 1);
+    if (valueFlags.has(key)) {
+      if (inlineVal !== null) {
+        opts[key] = inlineVal;
+      } else if (i + 1 < restTokens.length) {
+        opts[key] = restTokens[++i];
+      }
+    }
+  }
+
+  const posCopy = [...positionals];
+  if (subcommand === "query" || subcommand === "grep" || subcommand === "search" || subcommand === "find" || subcommand === "tools") {
+    if (opts.query === undefined && posCopy.length >= 1) {
+      opts.query = posCopy.shift();
+    }
+    if (opts.id === undefined && posCopy.length >= 1) {
+      opts.id = posCopy.shift();
+    }
+  } else if (subcommand === "step") {
+    if (opts.step === undefined && posCopy.length >= 1) {
+      opts.step = posCopy.shift();
+    }
+    if (opts.id === undefined && posCopy.length >= 1) {
+      opts.id = posCopy.shift();
+    }
+  } else if (
+    subcommand === "read" ||
+    subcommand === "outline" ||
+    subcommand === "summary" ||
+    subcommand === "health" ||
+    subcommand === "stats" ||
+    subcommand === "info"
+  ) {
+    if (opts.id === undefined && posCopy.length >= 1) {
+      opts.id = posCopy.shift();
+    }
+  }
+
+  if (posCopy.length > 0) {
+    return {
+      error: `Antigravity Execution Governance: Unexpected positional arguments '${posCopy.join(" ")}' for 'agy-context transcript ${subcommand}'.`
+    };
+  }
+
+  return {
+    targetId: opts.id ? String(opts.id).trim() : null,
+    explicitFile: opts.file ? String(opts.file).trim() : null
+  };
+}
+
+function buildTranscriptAccessDenial({ subcommand, mode, source, callerConvId, rosterName, detail }) {
+  const label = rosterName ? `@${rosterName} (${callerConvId})` : callerConvId;
+  const extra = detail ? ` ${detail}` : "";
+  return (
+    `Antigravity Execution Governance: 'agy-context transcript ${subcommand}' is restricted for this session (${label}) by parent governance [mode=${mode}, source=${source}].${extra} ` +
+    `Do NOT retry transcript inspection commands or attempt direct '.system_generated' file/shell reads; proceed with your assigned task using your workspace files and task brief.`
+  );
+}
+
+/**
+ * Checks if a command is a valid, strictly single, unchained `agy-context transcript ...` invocation
+ * and enforces parent-scoped transcript access governance.
+ */
+function checkAgyContextTranscriptCommand(segments, convId = "global") {
+  if (segments.length === 0) return { matched: false, allowed: false };
+  const match = findAgyContextTranscriptUsage(segments);
+  if (!match) {
+    return { matched: false, allowed: false };
+  }
+
+  const {
+    seg,
+    segIndex,
+    totalSegs,
+    hadWrapper,
+    subOffset,
+    subcommand,
+    isReadSub,
+    isHelpSub,
+    isAdminSub,
+    isKnownSubcommand,
+    hasNodeFlags,
+    invalidBinaryPath,
+    tokens
+  } = match;
+
+  // Must be strictly single segment at index 0, unchained, unwrapped, no redirects/heredocs/subshells/node-flags
+  if (
+    totalSegs !== 1 ||
+    segIndex !== 0 ||
+    hadWrapper ||
+    hasNodeFlags ||
+    invalidBinaryPath ||
+    seg.hasRedirect ||
+    seg.hasHeredoc ||
+    seg.hasSubshell
+  ) {
+    return {
+      matched: true,
+      allowed: false,
+      reason:
+        "Antigravity Execution Governance: 'agy-context transcript' access to .system_generated must be strictly single and unchained (no chaining, wrappers, env prefixes, node flags, redirects, heredocs, or subshells)."
+    };
+  }
+
+  if (!isKnownSubcommand) {
+    return {
+      matched: true,
+      allowed: false,
+      reason: `Antigravity Execution Governance: Unknown 'agy-context transcript' subcommand '${subcommand}'. Expected read, query, step, health, list, or access.`
+    };
+  }
+
+  // Validate flags: disallow `..` traversal and `--file` outside <brainDir>
+  for (let i = subOffset + 1; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (tok === "--file") {
+      const val = tokens[i + 1];
+      if (!val || hasDotDotTraversal(val) || !isPathInsideDir(val, getBrainDir())) {
+        return {
+          matched: true,
+          allowed: false,
+          reason: `Antigravity Execution Governance: '--file' in 'agy-context transcript' must stay inside '${getBrainDir()}' without '..' path traversal.`
+        };
+      }
+      i++;
+      continue;
+    }
+    if (tok.startsWith("--file=")) {
+      const val = tok.slice("--file=".length);
+      if (!val || hasDotDotTraversal(val) || !isPathInsideDir(val, getBrainDir())) {
+        return {
+          matched: true,
+          allowed: false,
+          reason: `Antigravity Execution Governance: '--file' in 'agy-context transcript' must stay inside '${getBrainDir()}' without '..' path traversal.`
+        };
+      }
+      continue;
+    }
+    if (hasDotDotTraversal(tok)) {
+      return {
+        matched: true,
+        allowed: false,
+        reason: "Antigravity Execution Governance: Path traversal ('..') is prohibited in 'agy-context transcript' commands."
+      };
+    }
+  }
+
+  if (isHelpSub) {
+    return { matched: true, allowed: true, subcommand, mode: "open", needsReadGrant: false };
+  }
+
+  const restTokens = tokens.slice(subOffset + 1);
+  if (restTokens.length === 1 && (restTokens[0] === "--help" || restTokens[0] === "-h")) {
+    return { matched: true, allowed: true, subcommand, mode: "open", needsReadGrant: false };
+  }
+
+  if (isAdminSub) {
+    const hasMutationToken = restTokens.some((t) => {
+      const low = String(t).toLowerCase();
+      return (
+        low === "--off" ||
+        low === "--deny-children" ||
+        low === "--on" ||
+        low === "--reset" ||
+        low === "--self-only" ||
+        low === "--mode" ||
+        low.startsWith("--mode=") ||
+        low === "--allow" ||
+        low.startsWith("--allow=") ||
+        low === "--deny" ||
+        low.startsWith("--deny=") ||
+        low === "--ttl" ||
+        low.startsWith("--ttl=") ||
+        low === "off" ||
+        low === "deny" ||
+        low === "lock" ||
+        low === "on" ||
+        low === "open" ||
+        low === "reset" ||
+        low === "unlock" ||
+        low === "self-only"
+      );
+    });
+
+    if (hasMutationToken && !canCallerMutateTranscriptAccess(convId)) {
+      return {
+        matched: true,
+        allowed: false,
+        isAccessDenial: true,
+        reason:
+          "Antigravity Execution Governance: Only the parent/coordinator session may modify 'agy-context transcript access' policy. Child sessions cannot unlock or alter transcript governance."
+      };
+    }
+
+    return {
+      matched: true,
+      allowed: true,
+      subcommand,
+      mode: "open",
+      needsReadGrant: false,
+      isAccessMutation: hasMutationToken
+    };
+  }
+
+  if (isReadSub) {
+    const accessEval = evaluateCallerTranscriptAccess(convId);
+    if (!accessEval.allowed) {
+      return {
+        matched: true,
+        allowed: false,
+        isAccessDenial: true,
+        reason: buildTranscriptAccessDenial({
+          subcommand,
+          mode: accessEval.mode,
+          source: accessEval.source,
+          callerConvId: convId,
+          rosterName: accessEval.rosterName
+        })
+      };
+    }
+
+    const targetInfo = extractTargetConvIdFromTranscriptTokens(subcommand, restTokens);
+    if (targetInfo.error) {
+      return {
+        matched: true,
+        allowed: false,
+        reason: targetInfo.error
+      };
+    }
+
+    if (accessEval.mode === "self-only") {
+      if (subcommand === "list" || subcommand === "ls") {
+        return {
+          matched: true,
+          allowed: false,
+          isAccessDenial: true,
+          reason: buildTranscriptAccessDenial({
+            subcommand,
+            mode: "self-only",
+            source: accessEval.source,
+            callerConvId: convId,
+            rosterName: accessEval.rosterName,
+            detail: "'list'/'ls' across sessions is disabled in self-only mode."
+          })
+        };
+      }
+
+      if (targetInfo.explicitFile) {
+        const selfBrainDir = path.join(getBrainDir(), convId);
+        if (!isPathInsideDir(targetInfo.explicitFile, selfBrainDir)) {
+          return {
+            matched: true,
+            allowed: false,
+            isAccessDenial: true,
+            reason: buildTranscriptAccessDenial({
+              subcommand,
+              mode: "self-only",
+              source: accessEval.source,
+              callerConvId: convId,
+              rosterName: accessEval.rosterName,
+              detail: `Cross-session '--file' access outside '${convId}' is disabled in self-only mode.`
+            })
+          };
+        }
+      }
+
+      if (targetInfo.targetId && targetInfo.targetId.toLowerCase() !== "current" && targetInfo.targetId !== convId) {
+        return {
+          matched: true,
+          allowed: false,
+          isAccessDenial: true,
+          reason: buildTranscriptAccessDenial({
+            subcommand,
+            mode: "self-only",
+            source: accessEval.source,
+            callerConvId: convId,
+            rosterName: accessEval.rosterName,
+            detail: `Cross-session inspection of '${targetInfo.targetId}' is disabled in self-only mode (you may only inspect your own session '${convId}').`
+          })
+        };
+      }
+
+      const needsSelfIdInjection =
+        !targetInfo.explicitFile &&
+        (!targetInfo.targetId || targetInfo.targetId.toLowerCase() === "current") &&
+        Boolean(convId && convId !== "global");
+
+      return {
+        matched: true,
+        allowed: true,
+        subcommand,
+        mode: "self-only",
+        targetConvId: convId,
+        needsReadGrant: true,
+        injectSelfId: needsSelfIdInjection ? convId : null
+      };
+    }
+
+    let resolvedTargetConvId = targetInfo.targetId || null;
+    if (targetInfo.explicitFile) {
+      if (accessEval.ownerId && !accessEval.isOwner && !isPathInsideDir(targetInfo.explicitFile, getBrainDir())) {
+        return {
+          matched: true,
+          allowed: false,
+          isAccessDenial: true,
+          reason: buildTranscriptAccessDenial({
+            subcommand,
+            mode: accessEval.mode,
+            source: accessEval.source,
+            callerConvId: convId,
+            rosterName: accessEval.rosterName,
+            detail: `'--file' paths outside '${getBrainDir()}' are disabled while a parent transcript access policy is active.`
+          })
+        };
+      }
+      if (isPathInsideDir(targetInfo.explicitFile, getBrainDir())) {
+        const rel = path.relative(
+          tryRealpath(path.resolve(getBrainDir())),
+          tryRealpath(path.resolve(targetInfo.explicitFile))
+        );
+        const firstSeg = rel.split(path.sep)[0];
+        if (firstSeg && firstSeg !== "." && firstSeg !== "..") {
+          resolvedTargetConvId = firstSeg;
+        }
+      }
+    }
+
+    return {
+      matched: true,
+      allowed: true,
+      subcommand,
+      mode: "open",
+      needsReadGrant: true,
+      targetConvId: resolvedTargetConvId
+    };
+  }
+
+  return { matched: true, allowed: true, subcommand, mode: "open", needsReadGrant: false };
+}
+
+/**
+ * Extracts redirect target paths from a segment's unquoted tokens.
+ */
+function extractRedirectTargets(tokens) {
+  const targets = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (!tok.quoted && REDIRECT_OP_REGEX.test(tok.raw)) {
+      if (tokens[i + 1]) targets.push(tokens[i + 1].value);
+      continue;
+    }
+    const attached = tok.raw.match(REDIRECT_ATTACHED_REGEX);
+    if (attached && !tok.quoted) {
+      targets.push(attached[1].replace(/^["']|["']$/g, ""));
+    }
+  }
+  return targets;
+}
+
+const SEARCH_COMMANDS = new Set(["grep", "egrep", "fgrep", "rg", "ripgrep", "ag", "ack", "select-string"]);
+const SEARCH_VALUE_FLAGS = new Set([
+  "-e", "--regexp", "-f", "--file", "-m", "--max-count",
+  "-A", "--after-context", "-B", "--before-context", "-C", "--context",
+  "-t", "--type", "-T", "--type-not", "-g", "--glob", "--iglob",
+  "-M", "--max-columns", "--max-filesize", "--color", "-j", "--threads",
+  "-r", "--replace", "--sort", "--sortr"
+]);
+
+/**
+ * Extracts inspectable path tokens for a segment, ignoring benign echo/printf text
+ * and ignoring literal search patterns on grep/rg commands (inspecting only target paths).
+ */
+function getInspectableTextForSegment(seg, opts = {}) {
+  const { body } = splitEnvPrefix(seg.text);
+  const allTokens = tokenizeShellWordsDetailed(seg.text);
+  const detailed = body ? tokenizeShellWordsDetailed(body) : allTokens;
+  if (detailed.length === 0) return "";
+
+  const cmd0 = normalizeCmdName(detailed[0].value);
+  const cmd1 = detailed[1] ? normalizeCmdName(detailed[1].value) : "";
+
+  // Benign standalone echo / printf: only inspect redirect targets (never printed prose),
+  // UNLESS piped into a downstream command (e.g. `echo <b64> | base64 -d | xargs head`)
+  if (!opts.hasDownstreamPipe && (cmd0 === "echo" || cmd0 === "printf" || cmd0 === "write-output")) {
+    const redirects = extractRedirectTargets(allTokens);
+    return redirects.join(" ");
+  }
+
+  // Search commands: skip pattern argument and inspect only target paths / -f files / redirects
+  let argStart = -1;
+  if (SEARCH_COMMANDS.has(cmd0)) {
+    argStart = 1;
+  } else if ((cmd0 === "rtk" && (cmd1 === "grep" || cmd1 === "rg")) || (cmd0 === "git" && cmd1 === "grep")) {
+    argStart = 2;
+  }
+
+  if (argStart !== -1) {
+    const targets = extractRedirectTargets(allTokens);
+    let hasExplicitPattern = false;
+    let afterDoubleDash = false;
+    const positionals = [];
+
+    for (let i = argStart; i < detailed.length; i++) {
+      const tok = detailed[i];
+      if (!tok.quoted && REDIRECT_OP_REGEX.test(tok.raw)) {
+        i++; // skip redirect target (already in targets)
+        continue;
+      }
+      if (!tok.quoted && REDIRECT_ATTACHED_REGEX.test(tok.raw)) {
+        continue;
+      }
+      const val = tok.value;
+      if (!afterDoubleDash && val === "--") {
+        afterDoubleDash = true;
+        continue;
+      }
+      if (!afterDoubleDash && val.startsWith("-") && val !== "-") {
+        if (val === "--regexp" || val.startsWith("--regexp=")) {
+          hasExplicitPattern = true;
+          if (val === "--regexp" && i + 1 < detailed.length) i++;
+          continue;
+        }
+        if (val === "-f" || val === "--file" || (!val.startsWith("--") && /^-[^-]*f$/.test(val))) {
+          if (detailed[i + 1]) targets.push(detailed[i + 1].value);
+          i++;
+          hasExplicitPattern = true;
+          continue;
+        }
+        if (!val.startsWith("--") && /^-([^-]*)f(.+)$/.test(val)) {
+          const fIdx = val.indexOf("f");
+          targets.push(val.slice(fIdx + 1));
+          hasExplicitPattern = true;
+          continue;
+        }
+        if (val.startsWith("--file=")) {
+          targets.push(val.slice("--file=".length));
+          hasExplicitPattern = true;
+          continue;
+        }
+        if (!val.startsWith("--") && /^-[^-]*e/.test(val)) {
+          hasExplicitPattern = true;
+          if (/^-[^-]*e$/.test(val) && i + 1 < detailed.length) i++;
+          continue;
+        }
+        if (SEARCH_VALUE_FLAGS.has(val) && i + 1 < detailed.length) {
+          i++;
+        }
+        continue;
+      }
+      positionals.push(val);
+    }
+
+    // First positional is the pattern unless -e / -f was provided
+    const filePositionals = hasExplicitPattern ? positionals : positionals.slice(1);
+    targets.push(...filePositionals);
+    return targets.join(" ");
+  }
+
+  const unquotedJoined = allTokens.map((t) => t.value).join(" ");
+  return unquotedJoined && unquotedJoined !== seg.text ? `${seg.text}\n${unquotedJoined}` : seg.text;
+}
+
+const SHELL_INTERPRETERS = new Set(["bash", "sh", "zsh", "dash", "ksh", "eval"]);
+const CODE_INTERPRETERS = new Set(["python", "python2", "python3", "node", "perl", "ruby", "php", "pwsh", "powershell"]);
+const CODE_FILE_ACCESS_REGEX = /\b(?:open|read|readFile|readFileSync|createReadStream|readdir|listdir|scandir|walk|glob|iglob|readlines|Path|subprocess|popen|system|exec|spawn|eval|require|import|from\s+\w+\s+import|__import__|getattr|b64decode|atob|fs\.|os\.|io\.|path\.)\b|Buffer\.from/i;
+
+function getSegmentCmdName(seg) {
+  const { body } = splitEnvPrefix(seg.text || "");
+  const tokens = tokenizeShellWords(body || seg.text || "");
+  return tokens.length > 0 ? normalizeCmdName(tokens[0]) : "";
+}
+
+/**
+ * Recursively collects inspectable command texts (main segment, unquoted forms,
+ * bash/sh/eval inner scripts, nested subshells, and interpreter/xargs heredoc bodies).
+ * Plain documentation heredocs (e.g. `cat > file <<'EOF'`) and non-code prompt text remain exempt.
+ */
+function collectInspectableTexts(segments, depth = 0, options = {}) {
+  if (depth > 4) return [];
+  const texts = [];
+  const isRestrictedChild = Boolean(options.isRestrictedChild);
+  const osTmpNorm = os.tmpdir().replace(/\\/g, "/");
+
+  for (let idx = 0; idx < segments.length; idx++) {
+    const seg = segments[idx];
+    const segCmd = getSegmentCmdName(seg);
+    const pipelineCmds = [segCmd];
+    for (let j = idx + 1; j < segments.length; j++) {
+      const nextSeg = segments[j];
+      if (nextSeg.leadingSep !== "|" && nextSeg.leadingSep !== "|&") break;
+      pipelineCmds.push(getSegmentCmdName(nextSeg));
+    }
+    const downstreamCmds = pipelineCmds.slice(1);
+
+    const inspectable = getInspectableTextForSegment(seg, { hasDownstreamPipe: downstreamCmds.length > 0 });
+    if (inspectable) texts.push(inspectable);
+
+    const wrapped = extractWrappedScriptInfo(seg.text);
+    if (wrapped && wrapped.innerScript) {
+      texts.push(...collectInspectableTexts(splitShellSegments(wrapped.innerScript), depth + 1, options));
+    }
+
+    if (Array.isArray(seg.subshells)) {
+      for (const sub of seg.subshells) {
+        const subSegs = splitShellSegments(sub);
+        texts.push(...collectInspectableTexts(subSegs, depth + 1, options));
+      }
+    }
+
+    if (segCmd === "base64" && downstreamCmds.some((c) => SHELL_INTERPRETERS.has(c) || CODE_INTERPRETERS.has(c))) {
+      texts.push("base64 | sh");
+    }
+
+    // Inspect on-disk script files executed by shell/code interpreters (when in /tmp, /scratch, non-script extension, or restricted child)
+    if (SHELL_INTERPRETERS.has(segCmd) || CODE_INTERPRETERS.has(segCmd)) {
+      const segTokens = tokenizeShellWords(seg.text || "");
+      for (let tIdx = 1; tIdx < segTokens.length; tIdx++) {
+        let tok = String(segTokens[tIdx] || "").trim();
+        if (!tok || tok.startsWith("-")) continue;
+        if (tok.startsWith("<")) tok = tok.slice(1).trim();
+        if (!tok || isAllowedAgyContextScriptPath(tok)) continue;
+        try {
+          const resolvedFile = path.resolve(tok);
+          const normFile = resolvedFile.replace(/\\/g, "/");
+          const isTmpOrScratchFile =
+            normFile.startsWith("/tmp/") ||
+            normFile.startsWith("/var/tmp/") ||
+            normFile.startsWith(osTmpNorm + "/") ||
+            normFile.includes("/scratch/");
+          const isNonScriptExt = !isExecutableScriptPath(normFile);
+          if (isTmpOrScratchFile || isNonScriptExt || isRestrictedChild) {
+            if (fs.existsSync(resolvedFile)) {
+              const st = fs.statSync(resolvedFile);
+              if (st.isFile() && st.size > 0 && st.size <= 131072) {
+                texts.push(fs.readFileSync(resolvedFile, "utf-8"));
+              }
+            }
+          }
+        } catch {}
+      }
+    }
+
+    if (Array.isArray(seg.heredocBodies) && seg.heredocBodies.length > 0) {
+      const hasShellConsumer = pipelineCmds.some((c) => SHELL_INTERPRETERS.has(c));
+      const hasXargsConsumer = pipelineCmds.some((c) => c === "xargs");
+      const hasCodeConsumer = !seg.hasWriteRedirect && pipelineCmds.some((c) => CODE_INTERPRETERS.has(c));
+      let writesExecutableOrTmpScript = false;
+      if (seg.hasWriteRedirect) {
+        const redirectTargets = extractRedirectTargets(tokenizeShellWordsDetailed(seg.text || ""));
+        writesExecutableOrTmpScript = redirectTargets.some((t) => {
+          const normT = String(t || "").replace(/\\/g, "/");
+          return (
+            isExecutableScriptPath(normT) ||
+            normT.startsWith("/tmp/") ||
+            normT.startsWith("/var/tmp/") ||
+            normT.startsWith(osTmpNorm + "/")
+          );
+        });
+      }
+
+      for (const hdBody of seg.heredocBodies) {
+        if (!hdBody) continue;
+        if (hasShellConsumer) {
+          texts.push(...collectInspectableTexts(splitShellSegments(hdBody), depth + 1, options));
+        } else if (hasXargsConsumer) {
+          texts.push(hdBody);
+        } else if (hasCodeConsumer && CODE_FILE_ACCESS_REGEX.test(hdBody)) {
+          texts.push(hdBody);
+        } else if (writesExecutableOrTmpScript || /^\s*#!/.test(hdBody)) {
+          texts.push(hdBody);
+        }
+      }
+    }
+  }
+  return texts;
+}
+
+function isRtkReadCommand(cmd) {
+  const tokens = tokenizeShellWords(cmd);
+  return tokens.length >= 2 && normalizeCmdName(tokens[0]) === "rtk" && tokens[1].toLowerCase() === "read";
+}
+
+function isSingleUnchainedShellCmd(segments) {
+  if (segments.length !== 1) return false;
+  const seg = segments[0];
+  return !seg.hasRedirect && !seg.hasHeredoc && !seg.hasSubshell && !hasDotDotTraversal(seg.text);
+}
+
+// ============================================================================
+// RTK Post-Processing (wc/ls/diff revert & rg -> rtk grep fallback)
+// ============================================================================
+
+const RG_GREP_ZERO_ARG_FLAGS = new Map([
+  ["-i", "-i"], ["--ignore-case", "-i"],
+  ["-n", "-n"], ["--line-number", "-n"],
+  ["-l", "-l"], ["--files-with-matches", "-l"],
+  ["-c", "-c"], ["--count", "-c"],
+  ["-v", "-v"], ["--invert-match", "-v"],
+  ["-w", "-w"], ["--word-regexp", "-w"],
+  ["-x", "-x"], ["--line-regexp", "-x"],
+  ["-F", "-F"], ["--fixed-strings", "-F"],
+  ["-E", "-E"], ["--extended-regexp", "-E"],
+  ["-P", "-P"], ["--pcre2", "-P"],
+  ["-a", "-a"], ["--text", "-a"],
+  ["-0", "-Z"], ["--null", "-Z"],
+  ["-H", "-H"], ["--with-filename", "-H"],
+  ["-h", "-h"], ["--no-filename", "-h"], ["-I", "-h"],
+  ["-q", "-q"], ["--quiet", "-q"],
+  ["-s", "-s"], ["--no-messages", "-s"],
+  ["-o", "-o"], ["--only-matching", "-o"]
+]);
+
+const RG_NOOP_FLAGS = new Set([
+  "--no-heading", "--heading", "-p", "--pretty", "--line-buffered",
+  "-U", "--multiline", "--multiline-dotall",
+  "-u", "-uu", "-uuu", "--unrestricted",
+  "--no-ignore", "--no-ignore-vcs", "--no-ignore-parent", "--no-ignore-global",
+  "--hidden", "-.", "--column", "--vimgrep", "--stats", "--json",
+  "--passthru", "--passthrough", "--no-config", "--one-file-system", "--sort-files"
+]);
+
+const RG_GREP_VALUE_FLAGS = new Map([
+  ["-m", "-m"], ["--max-count", "--max-count"],
+  ["-A", "-A"], ["--after-context", "-A"],
+  ["-B", "-B"], ["--before-context", "-B"],
+  ["-C", "-C"], ["--context", "-C"],
+  ["-e", "-e"], ["--regexp", "-e"]
+]);
+
+function hasPcreOnlyPattern(pattern) {
+  if (!pattern) return false;
+  return /\\[dDsSwW]|\(\?[=!<:#]|\\[pP]\{/.test(pattern);
+}
+
+const RG_TYPE_INCLUDE_MAP = {
+  js: ["*.js", "*.mjs", "*.cjs", "*.jsx"],
+  mjs: ["*.mjs"],
+  cjs: ["*.cjs"],
+  ts: ["*.ts", "*.mts", "*.cts", "*.tsx"],
+  py: ["*.py", "*.pyi"],
+  json: ["*.json"],
+  md: ["*.md"],
+  sh: ["*.sh", "*.bash"],
+  yaml: ["*.yml", "*.yaml"],
+  yml: ["*.yml", "*.yaml"],
+  txt: ["*.txt"],
+  css: ["*.css"],
+  html: ["*.html", "*.htm"],
+  rs: ["*.rs"],
+  go: ["*.go"]
+};
+
+function quotePosixGrepFlagVal(val) {
+  if (/^[A-Za-z0-9_.*?,/-]+$/.test(val)) return val;
+  return `'${val.replace(/'/g, "'\\''")}'`;
+}
+
+function rewriteRtkRgSegment(rtkPrefixWord, restAfterRtk, { inPipeline = false } = {}) {
+  const afterRgMatch = restAfterRtk.match(/^rg(?:\.exe)?\s+([\s\S]+)$/i);
+  if (!afterRgMatch) return restAfterRtk;
+
+  const tokens = tokenizeShellWordsDetailed(afterRgMatch[1]);
+  const grepFlags = [];
+  const positionals = [];
+  const patterns = [];
+  let hasExtended = false;
+  let hasFixed = false;
+  let hasSmartCase = false;
+  let hasIgnoreCase = false;
+  let hasFollow = false;
+  let filesOnly = false;
+  let hasExplicitPattern = false;
+  let afterDoubleDash = false;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    const val = tok.value;
+
+    if (!afterDoubleDash && val === "--") {
+      afterDoubleDash = true;
+      continue;
+    }
+
+    if (!afterDoubleDash && val.startsWith("-") && val !== "-") {
+      if (val === "--files") {
+        filesOnly = true;
+        continue;
+      }
+      if (val === "-S" || val === "--smart-case") {
+        hasSmartCase = true;
+        continue;
+      }
+      if (val === "-L" || val === "--follow") {
+        hasFollow = true;
+        continue;
+      }
+      if (RG_NOOP_FLAGS.has(val)) {
+        continue;
+      }
+      if (RG_GREP_ZERO_ARG_FLAGS.has(val)) {
+        const mapped = RG_GREP_ZERO_ARG_FLAGS.get(val);
+        if (mapped === "-i") hasIgnoreCase = true;
+        if (mapped === "-E" || mapped === "-P") hasExtended = true;
+        if (mapped === "-F") hasFixed = true;
+        grepFlags.push(mapped);
+        continue;
+      }
+
+      if (RG_GREP_VALUE_FLAGS.has(val)) {
+        if (i + 1 >= tokens.length) return restAfterRtk;
+        const nextTok = tokens[++i];
+        const mapped = RG_GREP_VALUE_FLAGS.get(val);
+        if (mapped === "-e") {
+          hasExplicitPattern = true;
+          patterns.push(nextTok.value);
+        }
+        grepFlags.push(mapped, nextTok.raw);
+        continue;
+      }
+
+      if (val === "-g" || val === "--glob" || val.startsWith("--glob=")) {
+        let globVal;
+        if (val.startsWith("--glob=")) {
+          globVal = val.slice("--glob=".length);
+        } else {
+          if (i + 1 >= tokens.length) return restAfterRtk;
+          globVal = tokens[++i].value;
+        }
+        if (globVal.startsWith("!")) {
+          grepFlags.push(`--exclude=${quotePosixGrepFlagVal(globVal.slice(1))}`);
+        } else {
+          grepFlags.push(`--include=${quotePosixGrepFlagVal(globVal)}`);
+        }
+        continue;
+      }
+
+      if (val === "-t" || val === "--type" || val.startsWith("--type=") || val === "-T" || val === "--type-not" || val.startsWith("--type-not=")) {
+        const isNot = val === "-T" || val.startsWith("--type-not");
+        let typeVal;
+        if (val.includes("=")) {
+          typeVal = val.slice(val.indexOf("=") + 1).toLowerCase();
+        } else {
+          if (i + 1 >= tokens.length) return restAfterRtk;
+          typeVal = tokens[++i].value.toLowerCase();
+        }
+        const exts = RG_TYPE_INCLUDE_MAP[typeVal];
+        if (!exts) return restAfterRtk;
+        for (const ext of exts) {
+          grepFlags.push(`${isNot ? "--exclude" : "--include"}=${ext}`);
+        }
+        continue;
+      }
+
+      // Attached short flags like -in, -ni, -lw, -nS, -nU (exclude -r which is --replace in rg!)
+      if (/^-[inlcvwxFEHhqsoSLPaUup]+$/.test(val)) {
+        let clean = "-";
+        for (const ch of val.slice(1)) {
+          if (ch === "S") {
+            hasSmartCase = true;
+            continue;
+          }
+          if (ch === "L") {
+            hasFollow = true;
+            continue;
+          }
+          if (ch === "U" || ch === "u" || ch === "p") {
+            continue;
+          }
+          if (ch === "i") hasIgnoreCase = true;
+          if (ch === "E" || ch === "P") hasExtended = true;
+          if (ch === "F") hasFixed = true;
+          clean += ch;
+        }
+        if (clean.length > 1) grepFlags.push(clean);
+        continue;
+      }
+
+      const eqIdx = val.indexOf("=");
+      if (eqIdx !== -1) {
+        const flagName = val.slice(0, eqIdx);
+        const flagVal = val.slice(eqIdx + 1);
+        if (RG_GREP_VALUE_FLAGS.has(flagName)) {
+          if (flagName === "--regexp") {
+            hasExplicitPattern = true;
+            patterns.push(flagVal);
+          }
+          grepFlags.push(tok.raw);
+          continue;
+        }
+        if (flagName === "--color") {
+          grepFlags.push(tok.raw);
+          continue;
+        }
+      }
+
+      return restAfterRtk;
+    }
+
+    positionals.push(tok);
+  }
+
+  if (filesOnly) {
+    const findTargets = positionals.map((p) => p.raw).join(" ") || ".";
+    return `${rtkPrefixWord}find ${findTargets}`;
+  }
+
+  if (!hasExplicitPattern) {
+    if (positionals.length === 0) return restAfterRtk;
+    patterns.push(positionals[0].value);
+  }
+
+  const needsPcre = !hasFixed && patterns.some(hasPcreOnlyPattern);
+  if (needsPcre && os.platform() !== "linux") {
+    return restAfterRtk;
+  }
+
+  const outArgs = [];
+  if (!inPipeline) {
+    outArgs.push(hasFollow ? "-R" : "-r");
+  }
+  if (hasSmartCase && !hasIgnoreCase && !patterns.some((p) => /[A-Z]/.test(p))) {
+    outArgs.push("-i");
+  }
+  if (needsPcre) {
+    outArgs.push("-P");
+  } else if (!hasFixed && !hasExtended) {
+    outArgs.push("-E");
+  }
+  outArgs.push(...grepFlags);
+
+  if (afterDoubleDash) {
+    outArgs.push("--");
+  }
+
+  for (const p of positionals) {
+    outArgs.push(p.raw);
+  }
+
+  const hasExplicitPath = hasExplicitPattern ? positionals.length > 0 : positionals.length > 1;
+  if (!inPipeline && !hasExplicitPath) {
+    outArgs.push(".");
+  }
+
+  return `${rtkPrefixWord}grep ${outArgs.join(" ")}`;
+}
+
+const GREP_VALUE_FLAGS = new Set([
+  "-e", "--regexp", "-f", "--file", "-m", "--max-count",
+  "-A", "--after-context", "-B", "--before-context", "-C", "--context",
+  "-d", "--directories", "--include", "--exclude", "--exclude-dir", "--color", "-D", "--devices"
+]);
+
+/**
+ * Normalizes `rtk grep` when host `rg` is absent so GNU `grep` receives `-r` (when targeting dirs/omitted)
+ * and `-E` (for alternation/quantifiers like `a|b`) instead of failing with exit 2 ("Is a directory")
+ * or exit 1 (BRE literal `|`).
+ */
+function rewriteRtkGrepSegment(rtkPrefixWord, restAfterRtk, { inPipeline = false } = {}) {
+  const afterGrepMatch = restAfterRtk.match(/^grep(?:\.exe)?\s+([\s\S]+)$/i);
+  if (!afterGrepMatch) return `${rtkPrefixWord}${restAfterRtk}`;
+
+  const tokens = tokenizeShellWordsDetailed(afterGrepMatch[1]);
+  let hasRecursive = false;
+  let hasRegexMode = false;
+  let hasExplicitPattern = false;
+  let afterDoubleDash = false;
+  const positionals = [];
+  const patterns = [];
+
+  for (let i = 0; i < tokens.length; i++) {
+    const val = tokens[i].value;
+    if (!afterDoubleDash && val === "--") {
+      afterDoubleDash = true;
+      continue;
+    }
+    if (!afterDoubleDash && val.startsWith("-") && val !== "-") {
+      if (val === "--recursive" || val === "--dereference-recursive" || val === "--directories" || val.startsWith("--directories=")) {
+        hasRecursive = true;
+      }
+      if (
+        val === "--extended-regexp" ||
+        val === "--fixed-strings" ||
+        val === "--basic-regexp" ||
+        val === "--perl-regexp"
+      ) {
+        hasRegexMode = true;
+      }
+      if (val === "--regexp" || val.startsWith("--regexp=") || val === "--file" || val.startsWith("--file=")) {
+        hasExplicitPattern = true;
+        if (val.startsWith("--regexp=")) patterns.push(val.slice("--regexp=".length));
+      }
+      if (!val.startsWith("--")) {
+        if (/[rR]/.test(val.slice(1))) hasRecursive = true;
+        if (/[EFGP]/.test(val.slice(1))) hasRegexMode = true;
+        if (/[ef]/.test(val.slice(1))) hasExplicitPattern = true;
+        const lastCh = val[val.length - 1];
+        if ((lastCh === "e" || lastCh === "f" || lastCh === "m" || lastCh === "A" || lastCh === "B" || lastCh === "C" || lastCh === "d" || lastCh === "D") && i + 1 < tokens.length) {
+          if (lastCh === "e") patterns.push(tokens[i + 1].value);
+          i++;
+          continue;
+        }
+      } else if (GREP_VALUE_FLAGS.has(val) && i + 1 < tokens.length) {
+        if (val === "--regexp") patterns.push(tokens[i + 1].value);
+        i++;
+      }
+      continue;
+    }
+    positionals.push(tokens[i]);
+  }
+
+  if (!hasExplicitPattern && positionals.length > 0) {
+    patterns.push(positionals[0].value);
+  }
+  if (patterns.length === 0) {
+    return `${rtkPrefixWord}${restAfterRtk}`;
+  }
+
+  const pathPositionals = hasExplicitPattern ? positionals : positionals.slice(1);
+  const needsExplicitDot = !inPipeline && pathPositionals.length === 0;
+  let allExistingRegularFiles = false;
+  if (!inPipeline && pathPositionals.length > 0) {
+    allExistingRegularFiles = pathPositionals.every((p) => {
+      try {
+        return fs.statSync(p.value).isFile();
+      } catch {
+        return false;
+      }
+    });
+  }
+
+  const injectFlags = [];
+  if (!inPipeline && !hasRecursive && !allExistingRegularFiles) {
+    injectFlags.push("-r");
+  }
+  if (!hasRegexMode) {
+    if (os.platform() === "linux" && patterns.some(hasPcreOnlyPattern)) {
+      injectFlags.push("-P");
+    } else {
+      injectFlags.push("-E");
+    }
+  }
+
+  if (injectFlags.length === 0 && !needsExplicitDot) {
+    return `${rtkPrefixWord}${restAfterRtk}`;
+  }
 
-function readRewriteCacheFile() {
-  try {
-    const data = JSON.parse(fs.readFileSync(REWRITE_CACHE_FILE, "utf-8"));
-    if (data && typeof data === "object" && !Array.isArray(data)) return data;
-  } catch {}
-  return {};
+  const flagPrefix = injectFlags.length > 0 ? `${injectFlags.join(" ")} ` : "";
+  const dotSuffix = needsExplicitDot ? " ." : "";
+  return `${rtkPrefixWord}grep ${flagPrefix}${afterGrepMatch[1]}${dotSuffix}`;
 }
 
-function loadRewriteCache() {
-  if (!inMemoryRewriteCache) inMemoryRewriteCache = readRewriteCacheFile();
-  return inMemoryRewriteCache;
+function unwrapShellWrapper(segText) {
+  const m = segText.match(
+    /^((?:cmd(?:\.exe)?\s+\/[cC]|(?:powershell|pwsh)(?:\.exe)?\s+(?:-Command|-c)|(?:bash|sh)\s+-c)\s+)(["'])([\s\S]*)\2$/i
+  );
+  if (!m) return null;
+  return { prefix: m[1], quote: m[2], inner: m[3] };
 }
 
-function resolveCompatibleRtk() {
-  const localCandidate = getLocalRtkCandidate();
-  const pathCandidate = findFirstRtkOnPath();
-  const envSig = `${pathCandidate}::${localCandidate}`;
-  const cache = loadRewriteCache();
-  if (cache.__envSig === envSig && cache.__rtkResolved !== undefined) {
-    return cache.__rtkResolved;
+function postProcessSegmentText(rawSegText, effSegText, { rgAvailable, inPipeline, rtkPrefix }) {
+  const trimmedEff = effSegText.trim();
+  const trimmedRaw = (rawSegText || "").trim();
+
+  // Recursively handle shell wrappers (e.g., bash -c "rtk wc -l foo")
+  const effWrap = unwrapShellWrapper(trimmedEff);
+  if (effWrap) {
+    const rawWrap = unwrapShellWrapper(trimmedRaw);
+    const processedInner = postProcessCommand(
+      rawWrap ? rawWrap.inner : effWrap.inner,
+      effWrap.inner,
+      { rgAvailable, rtkPrefix }
+    );
+    return `${effWrap.prefix}${effWrap.quote}${processedInner}${effWrap.quote}`;
   }
 
-  for (const k of Object.keys(cache)) delete cache[k];
-
-  const opts = { encoding: "utf-8", timeout: 2000, windowsHide: true };
-  let resolved = null;
-
-  const pathRes = pathCandidate ? spawnRtk(pathCandidate, ["--version"], opts) : { status: 1, stdout: "" };
-  const pathCompatible = !pathRes.error && pathRes.status === 0 && isCompatibleRtkVersion(pathRes.stdout);
-
-  if (pathCompatible) {
-    resolved = { exe: pathCandidate, prefix: "rtk" };
-  } else if (localCandidate) {
-    const localRes = spawnRtk(localCandidate, ["--version"], opts);
-    const localCompatible = !localRes.error && localRes.status === 0 && isCompatibleRtkVersion(localRes.stdout);
-    if (localCompatible) {
-      const normalizedLocal = localCandidate.replace(/\\/g, "/");
-      const prefix = /\s/.test(normalizedLocal) ? `"${normalizedLocal}"` : normalizedLocal;
-      resolved = { exe: localCandidate, prefix };
+  const { prefix: effEnvPrefix, body: effBody } = splitEnvPrefix(trimmedEff);
+  const { body: rawBody } = splitEnvPrefix(trimmedRaw);
+  const effMatchTarget = effBody || trimmedEff;
+  const rawMatchTarget = rawBody || trimmedRaw;
+
+  const rtkMatch = effMatchTarget.match(/^((?:["']?[^\s"']*[/\\])?rtk(?:\.exe|\.cmd|\.bat)?["']?\s+)([\s\S]+)$/i);
+  if (!rtkMatch) {
+    // When host `rg` is absent, also rewrite bare `rg` in pipelines or `bash -c` subshells to `grep`/`find`
+    if (!rgAvailable && /^rg(?:\.exe)?(?=\s|$)/i.test(effMatchTarget)) {
+      const mapped = rewriteRtkRgSegment("", effMatchTarget, { inPipeline });
+      if (mapped !== effMatchTarget) {
+        return `${effEnvPrefix}${mapped}`;
+      }
     }
+    return trimmedEff;
   }
 
-  cache.__envSig = envSig;
-  cache.__rtkResolved = resolved;
-  ensureStateDir();
-  try {
-    const tmp = `${REWRITE_CACHE_FILE}.${process.pid}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(cache), "utf-8");
-    try {
-      fs.renameSync(tmp, REWRITE_CACHE_FILE);
-    } catch {
-      fs.writeFileSync(REWRITE_CACHE_FILE, JSON.stringify(cache), "utf-8");
-      try { fs.unlinkSync(tmp); } catch {}
-    }
-  } catch {}
-
-  return resolved;
-}
-
-function runRtkRewrite(cmd, resolvedRtk) {
-  const rtk = resolvedRtk || resolveCompatibleRtk();
-  if (!rtk) return { status: 1, stdout: "", stderr: "No compatible RTK binary available" };
-  const opts = { encoding: "utf-8", timeout: 2000, windowsHide: true };
-  return spawnRtk(rtk.exe, ["rewrite", cmd], opts);
-}
+  const rtkWord = rtkMatch[1];
+  const rest = rtkMatch[2];
+  const subcmd = (rest.match(/^([^\s"']+)/)?.[1] || "").toLowerCase();
 
-/**
- * Persists one rewrite result. Re-reads the file first so concurrent hook processes merge instead
- * of overwriting each other, trims to the newest entries, and writes atomically (temp + rename).
- */
-function rememberRewrite(cmd, rewritten) {
-  const cache = loadRewriteCache();
-  cache[cmd] = rewritten;
-  try {
-    const disk = readRewriteCacheFile();
-    const envSig = cache.__envSig ?? disk.__envSig;
-    const rtkResolved = cache.__rtkResolved ?? disk.__rtkResolved;
-    delete disk.__envSig;
-    delete disk.__rtkResolved;
-    delete disk[cmd];
-    disk[cmd] = rewritten;
-    const keys = Object.keys(disk);
-    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 {
-      fs.renameSync(tmp, REWRITE_CACHE_FILE);
-    } catch {
-      fs.writeFileSync(REWRITE_CACHE_FILE, JSON.stringify(disk), "utf-8");
-      try { fs.unlinkSync(tmp); } catch {}
+  // Revert lossy `rtk wc` / `rtk ls` / `rtk diff` back to raw unless caller explicitly typed it
+  if (subcmd === "wc" || subcmd === "ls" || subcmd === "diff") {
+    const explicitPattern = new RegExp(`^(?:["']?[^\\s"']*[/\\\\])?rtk(?:\\.exe|\\.cmd|\\.bat)?["']?\\s+${subcmd}\\b`, "i");
+    if (!explicitPattern.test(rawMatchTarget)) {
+      return `${effEnvPrefix}${rest}`;
     }
-  } catch {}
-}
-
-/**
- * Rewrite raw shell command using RTK (Rust Token Killer).
- */
-function rewriteCommandWithRtk(rawCmd) {
-  if (!rawCmd || typeof rawCmd !== "string") return rawCmd;
-  const trimmed = rawCmd.trim();
-  if (!trimmed) return rawCmd;
+  }
 
-  // Already prefixed with rtk
-  if (/^rtk(?:\.exe)?(?=\s|$)/i.test(trimmed)) {
-    const rtk = resolveCompatibleRtk();
-    if (rtk && rtk.prefix !== "rtk") {
-      return trimmed.replace(/^rtk(?:\.exe)?(?=\s|$)/i, rtk.prefix);
+  // Never emit `rtk rg` when `rg` is absent on PATH
+  if ((subcmd === "rg" || subcmd === "rg.exe") && !rgAvailable) {
+    let mapped = rewriteRtkRgSegment(rtkWord, rest, { inPipeline });
+    if (mapped !== rest && rtkPrefix && rtkPrefix !== "rtk" && /^rtk\s+/i.test(mapped)) {
+      mapped = mapped.replace(/^rtk(?=\s)/i, rtkPrefix);
     }
-    return trimmed;
+    return `${effEnvPrefix}${mapped}`;
   }
 
-  // Unwrap shell wrappers (e.g. cmd /c "...", powershell -Command "...", bash -c "...") (LH-01-B)
-  const shellWrapperMatch = trimmed.match(
-    /^(cmd(?:\.exe)?\s+\/[cC]|(?:powershell|pwsh)(?:\.exe)?\s+(?:-Command|-c)|(?:bash|sh)\s+-c)\s+["']?(.+?)["']?$/i
-  );
-  if (shellWrapperMatch) {
-    const wrapperPrefix = shellWrapperMatch[1];
-    const innerCmd = shellWrapperMatch[2].trim();
-    const rewrittenInner = rewriteCommandWithRtk(innerCmd);
-    if (rewrittenInner !== innerCmd) {
-      return `${wrapperPrefix} "${rewrittenInner}"`;
+  // Normalize `rtk grep` when host `rg` is absent so directories & `a|b` alternation work reliably
+  if ((subcmd === "grep" || subcmd === "grep.exe") && !rgAvailable) {
+    let mapped = rewriteRtkGrepSegment(rtkWord, rest, { inPipeline });
+    if (rtkPrefix && rtkPrefix !== "rtk" && /^rtk\s+/i.test(mapped)) {
+      mapped = mapped.replace(/^rtk(?=\s)/i, rtkPrefix);
     }
-    return trimmed;
+    return `${effEnvPrefix}${mapped}`;
   }
 
-  // Fast-path bypass for shell builtins, non-rewritable binaries, and powershell cmdlets
-  const firstWord = (trimmed.match(/^[^\s"']+/)?.[0] || "").toLowerCase();
-  if (
-    NON_REWRITABLE_BINARIES.has(firstWord) ||
-    firstWord.startsWith("get-") ||
-    firstWord.startsWith("set-") ||
-    firstWord.startsWith("start-") ||
-    firstWord.startsWith("stop-") ||
-    firstWord.startsWith("new-") ||
-    firstWord.startsWith("remove-") ||
-    firstWord.startsWith("test-")
-  ) {
-    return trimmed;
+  // If RTK came from a local binary not on PATH, rewrite bare `rtk ` prefix to explicit path
+  if (rtkPrefix && rtkPrefix !== "rtk" && /^rtk\s+/i.test(effMatchTarget) && !/^rtk\s+/i.test(rawMatchTarget)) {
+    return `${effEnvPrefix}${effMatchTarget.replace(/^rtk(?=\s)/i, rtkPrefix)}`;
   }
 
-  const rtk = resolveCompatibleRtk();
-  if (!rtk) return trimmed;
+  return trimmedEff;
+}
 
-  // Check persistent cache
-  const cache = loadRewriteCache();
-  if (cache[trimmed] !== undefined) {
-    return cache[trimmed];
+function postProcessCommand(rawCmd, effCmd, opts) {
+  const rawSegs = splitShellSegments(rawCmd);
+  const effSegs = splitShellSegments(effCmd);
+  if (effSegs.length === 0) return effCmd;
+
+  const sameCount = rawSegs.length === effSegs.length;
+  let result = effCmd;
+
+  // Splice from end to start so earlier offsets remain valid
+  for (let i = effSegs.length - 1; i >= 0; i--) {
+    const seg = effSegs[i];
+    const rawSegText = sameCount ? rawSegs[i].text : rawCmd;
+    const inPipeline = seg.leadingSep === "|" || seg.leadingSep === "|&";
+    const replacement = postProcessSegmentText(rawSegText, seg.text, {
+      ...opts,
+      inPipeline
+    });
+    if (replacement !== seg.text) {
+      result = result.slice(0, seg.start) + replacement + result.slice(seg.end);
+    }
   }
 
-  let rewritten = trimmed;
-  let cacheable = false;
-  try {
-    const res = runRtkRewrite(trimmed, rtk);
-    // Never cache timeouts, spawn errors or signals: a transient failure must not pin a command
-    // to "no rewrite" for the lifetime of the cache.
-    cacheable = !res.error && !res.signal && typeof res.status === "number" && res.status >= 0 && res.status <= 3;
+  return result;
+}
 
-    // RTK exits 0 or 3 when rewritten, with new command on stdout
-    if ((res.status === 0 || res.status === 3) && res.stdout && res.stdout.trim()) {
-      rewritten = res.stdout.trim();
-      if (rtk.prefix !== "rtk") {
-        rewritten = rewritten.replace(/^rtk(?:\.exe)?(?=\s|$)/i, rtk.prefix);
+function delegateRewriteToRtk(rawCmd, rtk) {
+  const opts = {
+    input: JSON.stringify({
+      toolCall: {
+        name: "run_command",
+        args: { CommandLine: rawCmd }
       }
+    }),
+    encoding: "utf-8",
+    timeout: 2000,
+    windowsHide: true
+  };
+  const res = spawnRtk(rtk.exe, ["hook", "antigravity"], opts);
+  if (res.error || res.status !== 0 || !res.stdout) {
+    return { decision: "allow", commandLine: rawCmd };
+  }
+  try {
+    const parsed = JSON.parse(res.stdout.trim());
+    if (parsed && (parsed.decision === "deny" || parsed.decision === "force_ask")) {
+      return {
+        decision: parsed.decision,
+        reason: parsed.reason || "Denied by RTK hook."
+      };
     }
-  } catch {}
-
-  if (cacheable) rememberRewrite(trimmed, rewritten);
-  return rewritten;
+    const rewritten = parsed?.overwrite?.CommandLine;
+    return {
+      decision: "allow",
+      commandLine: typeof rewritten === "string" && rewritten.trim() ? rewritten : rawCmd
+    };
+  } catch {
+    return { decision: "allow", commandLine: rawCmd };
+  }
 }
 
+// ============================================================================
+// Proportional Backoff & Strict Task-Polling Schedule Detection
+// ============================================================================
+
 /**
  * Calculates the required minimum cooldown interval (in seconds)
  * proportional to the number of diagnostic status inspections already performed.
  * Formula: Math.min(600, Math.round(30 * Math.pow(2.5, Math.max(0, pollCount - 1))))
  * Levels: Level 0 -> 0s (baseline), Level 1 -> 30s, Level 2 -> 75s, Level 3 -> 188s, Level 4 -> 469s, Level 5+ -> 600s
+ * Keep identical to lib/transcript-core.mjs `getRequiredBackoffSeconds`.
  */
 function getRequiredBackoffSeconds(pollCount) {
   if (pollCount <= 0) return 0;
   return Math.min(600, Math.round(30 * Math.pow(2.5, Math.max(0, pollCount - 1))));
 }
 
+/**
+ * Strict task-polling detection for `schedule` tool calls.
+ * Keep identical to lib/transcript-core.mjs `isTaskPollSchedule`.
+ */
+function isTaskPollSchedule(args = {}) {
+  const prompt = String(args.Prompt || args.prompt || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
+  const cond = String(args.TimerCondition || args.timerCondition || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
+  return (
+    cond.startsWith("task-") ||
+    cond.includes("task") ||
+    prompt.includes("check on") ||
+    prompt.includes("check task") ||
+    prompt.includes("background task") ||
+    prompt.includes("still running") ||
+    prompt.includes("test suite") ||
+    ((prompt.includes("check") || prompt.includes("status") || prompt.includes("poll") || prompt.includes("monitor") || prompt.includes("wait")) &&
+      (prompt.includes("task") || prompt.includes("process") || prompt.includes("job") || prompt.includes("test") || prompt.includes("command") || prompt.includes("suite")))
+  );
+}
+
+/**
+ * Detects one-shot `schedule` timers used to poll a `/swarm` or subagent instead of
+ * relying on `swarm_wait` or native Reactive Wakeup.
+ * Exempts the dedicated `swarm_monitor` daemon cron (`CronExpression` + `IsDaemon: true`).
+ */
+function isSwarmPollSchedule(args = {}) {
+  const isDaemon = args.IsDaemon === true || args.isDaemon === true;
+  const cron = String(args.CronExpression || args.cronExpression || "").trim();
+  if (isDaemon && cron) return false;
+
+  const prompt = String(args.Prompt || args.prompt || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
+  const cond = String(args.TimerCondition || args.timerCondition || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
+  return (
+    /\b(?:swarm|subagent|subagents|squad|board)\b/i.test(prompt) ||
+    (cond === "any" && /\b(?:check|status|poll|monitor|wait|worker|lead|auditor)\b/i.test(prompt))
+  );
+}
+
 /**
  * Denies reading the log of an actively RUNNING task: records the denial, trips the circuit
  * breaker at 5 cumulative denials, otherwise answers with the Proportional Backoff message.
@@ -594,6 +3085,140 @@ function denyRunningTask(taskId, convId) {
   });
 }
 
+// ============================================================================
+// Denial Helpers & File Metrics
+// ============================================================================
+
+function buildInternalStateShellDenial(convId = "global") {
+  const accessEval = evaluateCallerTranscriptAccess(convId);
+  if (!accessEval.allowed) {
+    return (
+      "Antigravity Execution Governance: Direct shell access to internal Antigravity execution state (.system_generated and governance state) is strictly prohibited.\n" +
+      "- Transcript inspection ('agy-context transcript' and '.system_generated/logs/') is DISABLED for this session by parent governance (L6 Transcript Isolation). Do NOT retry transcript commands or alternative file/shell reads; proceed using only your assigned workspace files and task brief.\n" +
+      "- To inspect background tasks: Yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>). Do not read internal task logs."
+    );
+  }
+  if (accessEval.mode === "self-only") {
+    return (
+      "Antigravity Execution Governance: Direct shell access to internal Antigravity execution state (.system_generated and governance state) is strictly prohibited.\n" +
+      `- Cross-session transcript inspection is DISABLED for this session (mode: self-only). You may only inspect your own transcript via 'agy-context transcript read --id ${convId} --mode compact' via run_command.\n` +
+      "- To inspect background tasks: Yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>). Do not read internal task logs."
+    );
+  }
+  return (
+    "Antigravity Execution Governance: Direct shell access to internal Antigravity execution state (.system_generated) is strictly prohibited to prevent transcript bloat and polling loops.\n" +
+    "- To inspect conversation transcripts: Run 'agy-context transcript read --id <uuid> --mode compact' or 'agy-context transcript query --id <uuid> --query \"<pattern>\" --summary' via run_command.\n" +
+    "- To inspect background tasks: Yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>). Do not read internal task logs."
+  );
+}
+
+function buildInternalStateToolDenial(convId = "global") {
+  const accessEval = evaluateCallerTranscriptAccess(convId);
+  if (!accessEval.allowed) {
+    return (
+      "Antigravity Execution Governance: Direct access to internal Antigravity execution state (.system_generated and governance state) is strictly prohibited.\n" +
+      "- Transcript inspection ('agy-context transcript' and '.system_generated/logs/') is DISABLED for this session by parent governance (L6 Transcript Isolation). Do NOT retry transcript commands or alternative file/shell reads; proceed using only your assigned workspace files and task brief.\n" +
+      "- To inspect background tasks: Yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>). Do not read internal task logs."
+    );
+  }
+  if (accessEval.mode === "self-only") {
+    return (
+      "Antigravity Execution Governance: Direct access to internal Antigravity execution state (.system_generated and governance state) is strictly prohibited.\n" +
+      `- Cross-session transcript inspection is DISABLED for this session (mode: self-only). You may only inspect your own transcript via 'agy-context transcript read --id ${convId} --mode compact' via run_command.\n` +
+      "- To inspect background tasks: Yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>). Do not read internal task logs."
+    );
+  }
+  return (
+    "Antigravity Execution Governance: Direct access to internal Antigravity execution state (.system_generated) is strictly prohibited to prevent transcript bloat and polling loops.\n" +
+    "- To inspect conversation transcripts: Run 'agy-context transcript read --id <uuid> --mode compact' or 'agy-context transcript query --id <uuid> --query \"<pattern>\" --summary' via run_command.\n" +
+    "- To inspect background tasks: Yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>). Do not read internal task logs."
+  );
+}
+
+function isProtectedGovernanceFileMutation(targetPath, convId = "global") {
+  if (!targetPath || typeof targetPath !== "string") return false;
+  const norm = targetPath.replace(/\\/g, "/");
+  // Installed hook, plugin, & hooks.json in ~/.gemini/config are always protected from direct agent edit/rm
+  if (
+    /\/\.gemini\/(?:config|antigravity)\/hooks\.json(?:\.bak)?$/i.test(norm) ||
+    /\/\.gemini\/config\/scripts\/execution-guard-hook\.mjs$/i.test(norm) ||
+    /\/\.gemini\/config\/plugins\/agy-context-saver(?:$|[\/\\])/i.test(norm) ||
+    /\/\.gemini\/antigravity\/bin\/agy-context(?:-saver)?(?:\.(?:cmd|exe|bat))?$/i.test(norm)
+  ) {
+    return true;
+  }
+  // When caller is a restricted child session, also block mutating repo governance source files
+  const accessEval = evaluateCallerTranscriptAccess(convId);
+  if (accessEval.isRestrictedChild) {
+    if (
+      /(?:^|[\/\\])(?:execution-guard-hook\.mjs|transcript-core\.mjs|agy-context\.mjs|state-dir\.mjs|install-register\.mjs|hooks\.json)$/i.test(
+        norm
+      )
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function hasGovernanceMutationInText(text, convId = "global") {
+  if (!text || typeof text !== "string") return false;
+  const norm = text.replace(/\\/g, "/");
+  const hasMutationOp =
+    /\b(?:rm|del|remove-item|mv|cp|tee|truncate|shred|install|sed|perl|chmod|chown|ln|dd|patch|writeFile|writeFileSync|appendFile|appendFileSync|unlink|unlinkSync|rmSync|rmdir|rmdirSync|rename|renameSync|truncateSync|chmodSync|copyFile|copyFileSync|WriteAllText|Delete|Remove)\b|>/i.test(
+      norm
+    );
+  if (!hasMutationOp) return false;
+
+  if (
+    /\/\.gemini\/(?:config|antigravity)\/hooks\.json(?:\.bak)?\b/i.test(norm) ||
+    /\/\.gemini\/config\/scripts\/execution-guard-hook\.mjs\b/i.test(norm) ||
+    /\/\.gemini\/config\/plugins\/agy-context-saver(?:$|[\/\\\s'"])/i.test(norm) ||
+    /\/\.gemini\/antigravity\/bin\/agy-context(?:-saver)?(?:\.(?:cmd|exe|bat))?\b/i.test(norm)
+  ) {
+    return true;
+  }
+
+  if (evaluateCallerTranscriptAccess(convId).isRestrictedChild) {
+    if (
+      /\b(?:execution-guard-hook\.mjs|transcript-core\.mjs|agy-context\.mjs|state-dir\.mjs|install-register\.mjs|hooks\.json)\b/i.test(
+        norm
+      )
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isExecutableScriptPath(targetPath) {
+  if (!targetPath || typeof targetPath !== "string") return false;
+  return /\.(?:m?js|cjs|ts|mts|cts|py|sh|bash|zsh|pl|rb|php|ps1|cmd|bat)$/i.test(targetPath.trim());
+}
+
+function escapeDoubleQuotedArg(str) {
+  return String(str).replace(/["\\$`]/g, "\\$&");
+}
+
+function 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;
+  }
+}
+
 // --- Main Hook Entrypoint ---
 let isGovernedTool = false;
 
@@ -616,7 +3241,10 @@ try {
     respond({ decision: "allow" });
   }
 
-  isGovernedTool = true;
+  // Only pre-classify as governed before JSON.parse when the tool name field itself matches a governed tool
+  isGovernedTool = /"(?:name|tool_name)"\s*:\s*"(?:run_command|read_file|view_file|read_many_files|grep_search|find_by_name|list_dir|manage_task|schedule|replace_file_content|write_to_file|write_file|edit_file)"/i.test(
+    inputRaw
+  );
   const payload = JSON.parse(inputRaw);
   const toolCall = payload.toolCall || payload.tool_call || {};
   const toolName = String(toolCall.name || toolCall.tool_name || "").trim().toLowerCase();
@@ -629,8 +3257,50 @@ try {
 
   isGovernedTool = true;
 
+  // Dual-hook idempotency deduplication when payload.conversationId is present (coordinator plugin + global hooks.json)
+  if (payload.conversationId) {
+    const callId = String(toolCall.id || payload.toolUseId || payload.tool_use_id || "").trim();
+    const stepIdx = payload.stepIdx !== undefined ? payload.stepIdx : payload.step_index;
+    const inSig = JSON.stringify(args || {});
+    let currentScriptPath = "";
+    try {
+      currentScriptPath = tryRealpath(fileURLToPath(import.meta.url));
+    } catch {}
+    const now = Date.now();
+    const prevState = getSessionState(convId);
+    const recent = Array.isArray(prevState.recentHookCalls) ? prevState.recentHookCalls : [];
+    const matchedCall = recent.find((e) => {
+      if (!e || typeof e.ts !== "number" || (now - e.ts) >= HOOK_DEDUP_TTL_MS) return false;
+      if (callId && e.callId && e.callId === callId) return true;
+      const argMatch = inSig === e.rawSig || inSig === e.outSig;
+      if (!argMatch || e.toolName !== toolName) return false;
+      if (stepIdx !== undefined && stepIdx !== null && e.stepIdx === stepIdx) return true;
+      if (currentScriptPath && e.scriptPath && e.scriptPath !== currentScriptPath && (now - e.ts) < HOOK_SAME_ARG_CROSS_SCRIPT_MS) {
+        return true;
+      }
+      return false;
+    });
+    if (matchedCall && matchedCall.response) {
+      const replay =
+        inSig === matchedCall.outSig &&
+        matchedCall.rawSig !== matchedCall.outSig &&
+        matchedCall.response.decision === "allow"
+          ? { decision: "allow" }
+          : matchedCall.response;
+      respond(replay);
+    }
+    dedupRecordCtx = {
+      convId,
+      callId,
+      stepIdx: stepIdx !== undefined ? stepIdx : null,
+      toolName,
+      scriptPath: currentScriptPath,
+      rawSig: inSig
+    };
+  }
+
   // =========================================================================
-  // 1. run_command: Transparent RTK Command Optimization & Synchronous Wait
+  // 1. run_command: Raw Safety Gates + `rtk hook antigravity` Delegation
   // =========================================================================
   if (toolName === "run_command") {
     const rawCmd = args.CommandLine !== undefined ? args.CommandLine : args.command;
@@ -641,73 +3311,240 @@ try {
       });
     }
 
+    const segments = splitShellSegments(rawCmd);
+
+    // LH-09-B: Shell command mutation of protected benchmark & governance artifacts
+    const SHELL_MUTATION_VERBS = new Set([
+      "rm",
+      "del",
+      "remove-item",
+      "mv",
+      "cp",
+      "tee",
+      "truncate",
+      "shred",
+      "install",
+      "sed",
+      "perl",
+      "chmod",
+      "chown",
+      "ln",
+      "dd",
+      "patch"
+    ]);
+    for (const seg of segments) {
+      const segTexts = [seg.text, ...(seg.subshells || [])];
+      for (const st of segTexts) {
+        const detailed = tokenizeShellWordsDetailed(st);
+        if (detailed.length === 0) continue;
+        let cmdIdx = 0;
+        while (
+          cmdIdx < detailed.length &&
+          (/^[A-Za-z_][A-Za-z0-9_]*=/.test(detailed[cmdIdx].value) ||
+            detailed[cmdIdx].value === "env" ||
+            detailed[cmdIdx].value === "sudo")
+        ) {
+          cmdIdx++;
+        }
+        const verb = cmdIdx < detailed.length ? normalizeCmdName(detailed[cmdIdx].value) : "";
+        const isMutatingVerb = SHELL_MUTATION_VERBS.has(verb);
+        if (seg.hasWriteRedirect || isMutatingVerb) {
+          const redirectTargets = extractRedirectTargets(detailed);
+          const argCandidates = isMutatingVerb
+            ? detailed.slice(cmdIdx + 1).map((t) => t.value).filter((v) => !v.includes("\n"))
+            : [];
+          const candidateTokens = [...redirectTargets, ...argCandidates];
+          if (candidateTokens.some((tok) => isProtectedGovernanceFileMutation(tok, convId))) {
+            respond({
+              decision: "deny",
+              reason:
+                "Antigravity Execution Governance: Shell mutation of protected Antigravity hook, shim, or governance source files is strictly prohibited."
+            });
+          }
+          if (candidateTokens.some((tok) => isProtectedBenchmarkPath(tok))) {
+            respond({
+              decision: "force_ask",
+              reason:
+                "[BENCHMARK MUTATION DETECTED] Shell command mutation of protected evaluator/benchmark artifact requires explicit user confirmation to prevent benchmark contamination."
+            });
+          }
+        }
+      }
+    }
 
-    // LH-09-B: Shell command mutation of protected benchmark artifacts
-    if (
-      (rawCmd.includes(">") || /\b(?:rm|del|Remove-Item)\b/i.test(rawCmd)) &&
-      isProtectedBenchmarkPath(rawCmd)
-    ) {
+    // Check agy-context transcript CLI exemption & parent-scoped access governance
+    const agyTranscriptCheck = checkAgyContextTranscriptCommand(segments, convId);
+    if (agyTranscriptCheck.matched && !agyTranscriptCheck.allowed) {
+      if (agyTranscriptCheck.isAccessDenial) {
+        const session = getSessionState(convId);
+        session.transcriptDenials = (session.transcriptDenials || 0) + 1;
+        saveSessionState(convId, session, { updatePollTime: false });
+        if (session.transcriptDenials >= 5) {
+          respond({
+            decision: "force_ask",
+            reason: `[CIRCUIT BREAKER ACTIVATED] Autonomous loop suspended: restricted session '${convId}' attempted forbidden 'agy-context transcript' access ${session.transcriptDenials} times. ${agyTranscriptCheck.reason}`
+          });
+        }
+      }
       respond({
-        decision: "force_ask",
-        reason:
-          "[BENCHMARK MUTATION DETECTED] Shell command mutation of protected evaluator/benchmark artifact requires explicit user confirmation to prevent benchmark contamination."
+        decision: "deny",
+        reason: agyTranscriptCheck.reason
       });
     }
 
-    // Raw-command governance gates are pure string/fs checks: run them BEFORE the rtk rewrite
-    // spawn so denied commands never pay for a subprocess.
-    const isSpillover = isStepSpilloverPath(rawCmd);
-    const taskMatch = isSpillover ? null : getTaskLogMatch(rawCmd);
+    // Raw-command internal state checks (skipping heredoc bodies, echo/printf text, and grep patterns)
+    let isSpillover = false;
+    let taskMatch = null;
+    if (!agyTranscriptCheck.allowed) {
+      const callerAccess = evaluateCallerTranscriptAccess(convId);
+      const inspectableTexts = collectInspectableTexts(segments, 0, {
+        isRestrictedChild: callerAccess.isRestrictedChild
+      });
+      const inspectableCombined = inspectableTexts.join("\n");
+      const singleTokens = segments.length === 1 ? tokenizeShellWords(segments[0].text) : [];
+      const spilloverTok = findStepSpilloverToken(singleTokens);
+      isSpillover = Boolean(spilloverTok);
+      taskMatch = getTaskLogMatch(inspectableCombined);
+
+      // Block unwrapped shell/interpreter mutations of governance/hook files
+      if (hasGovernanceMutationInText(inspectableCombined, convId)) {
+        respond({
+          decision: "deny",
+          reason:
+            "Antigravity Execution Governance: Shell mutation of protected Antigravity hook, shim, or governance source files is strictly prohibited."
+        });
+      }
 
-    // Check 1: Other protected internal state (transcripts, scheduler, progress)
-    if (!isSpillover && !taskMatch && isProtectedInternalState(rawCmd)) {
-      respond({
-        decision: "deny",
-        reason:
-          "Antigravity Execution Governance: Direct shell access to internal Antigravity execution state (.system_generated) is strictly prohibited to prevent transcript bloat and polling loops.\n" +
-          "- To inspect conversation transcripts: Call MCP tool read_transcript(conversationId=\"...\", mode=\"compact\") or query_transcript(...).\n" +
-          "- To inspect background tasks: Yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>). Do not read internal task logs."
+      // Block restricted child sessions from running setup/install/uninstall/restore-backups lifecycle commands
+      if (
+        /\bagy-context(?:-saver)?(?:\.m?js)?\s+(?:--?(?:setup|install|uninstall|restore-backups)|setup|install|uninstall|restore-backups)\b|\bnpm\s+run\s+(?:setup|uninstall)\b|\binstall-register\.mjs\b/i.test(
+          inspectableCombined
+        ) &&
+        callerAccess.isRestrictedChild
+      ) {
+        respond({
+          decision: "deny",
+          reason:
+            "Antigravity Execution Governance: Restricted child sessions cannot execute plugin lifecycle setup or uninstall commands."
+        });
+      }
+
+      // Check 1: Other protected internal state (transcripts, governance state, non-canonical agy-context transcript, interpreter imports)
+      if (!isSpillover && !taskMatch && isProtectedShellOrScriptOperation(inspectableCombined)) {
+        respond({
+          decision: "deny",
+          reason: buildInternalStateShellDenial(convId)
+        });
+      }
+
+      // If spillover or task log is chained, redirected, uses heredocs, subshells, or `..` traversal -> DENY
+      if ((isSpillover || taskMatch) && !isSingleUnchainedShellCmd(segments)) {
+        respond({
+          decision: "deny",
+          reason: isSpillover
+            ? "Antigravity Execution Governance: Runtime step output spillover files must be inspected using a single unchained 'rtk read <path>' command (no chaining, redirects, subshells, or '..' traversal)."
+            : buildInternalStateShellDenial(convId)
+        });
+      }
+
+      // Check 2: Task Log Inspection (Lifecycle-Gated): RUNNING => Proportional Backoff
+      if (taskMatch && getTaskState(taskMatch, convId) === "RUNNING") {
+        denyRunningTask(taskMatch.id, convId);
+      }
+    }
+
+    if (agyTranscriptCheck.allowed && (agyTranscriptCheck.needsReadGrant || agyTranscriptCheck.isAccessMutation)) {
+      recordTranscriptHookGrant({
+        callerConvId: convId,
+        subcommand: agyTranscriptCheck.subcommand,
+        targetConvId: agyTranscriptCheck.targetConvId || null,
+        mode: agyTranscriptCheck.mode || "open",
+        isMutation: Boolean(agyTranscriptCheck.isAccessMutation)
+      });
+    }
+
+    // Delegate command rewriting to `rtk hook antigravity` (>= 1.1.0)
+    const rtk = resolveCompatibleRtk();
+    const rgAvailable = Boolean(findExecutableOnPath("rg"));
+    let effectiveCmd = rawCmd;
+
+    if (rtk) {
+      const delegated = delegateRewriteToRtk(rawCmd, rtk);
+      if (delegated.decision !== "allow") {
+        respond({ decision: delegated.decision, reason: delegated.reason });
+      }
+      effectiveCmd = postProcessCommand(rawCmd, delegated.commandLine, {
+        rgAvailable,
+        rtkPrefix: rtk.prefix
+      });
+    } else if (!rgAvailable) {
+      effectiveCmd = postProcessCommand(rawCmd, rawCmd, {
+        rgAvailable: false,
+        rtkPrefix: "rtk"
       });
     }
 
-    // Check 2: Task Log Inspection (Lifecycle-Gated, 0 New Tools): RUNNING => Proportional Backoff
-    if (taskMatch && getTaskState(taskMatch, convId) === "RUNNING") {
-      denyRunningTask(taskMatch.id, convId);
+    // In self-only mode, deterministically inject --id <convId> when --id and --file were omitted (or --id current / positional current)
+    if (agyTranscriptCheck.allowed && agyTranscriptCheck.injectSelfId) {
+      if (/--id(?:=|\s+)["']?current["']?\b/i.test(effectiveCmd)) {
+        effectiveCmd = effectiveCmd.replace(/--id(?:=|\s+)["']?current["']?\b/i, `--id ${agyTranscriptCheck.injectSelfId}`);
+      } else if (/\s+["']?current["']?\s*$/i.test(effectiveCmd)) {
+        effectiveCmd = effectiveCmd.replace(/\s+["']?current["']?\s*$/i, ` --id ${agyTranscriptCheck.injectSelfId}`);
+      } else {
+        effectiveCmd = `${effectiveCmd.trim()} --id ${agyTranscriptCheck.injectSelfId}`;
+      }
     }
 
-    const rewritten = rewriteCommandWithRtk(rawCmd);
-    const effectiveCmd = rewritten;
-    const isRtkRead = /^(?:["']?[^\s"']*[/\\])?rtk(?:\.exe|\.cmd|\.bat)?["']?\s+read\b/i.test(effectiveCmd);
+    const isRtkRead = isRtkReadCommand(effectiveCmd);
+    const isExplicitRtkRead = isRtkReadCommand(rawCmd) && isRtkRead;
 
-    // Check 3: Step Output Spillover Safe Harbor (rtk read only; it clamps + windows output)
+    // Check 3: Step Output Spillover Safe Harbor (strictly single unchained `rtk read` only)
     if (isSpillover && !isRtkRead) {
       respond({
         decision: "deny",
         reason:
-          "Antigravity Execution Governance: Runtime step output spillover files must be inspected using 'rtk read <path>' via run_command to prevent context blowouts."
+          "Antigravity Execution Governance: Runtime step output spillover files must be inspected using 'rtk read <path>' via run_command (or bounded 'read_file' <= 150 lines) to prevent context blowouts."
       });
     }
 
-    // Check 4: Terminated / unknown-state task log: allow only through rtk read
-    if (taskMatch && !isRtkRead) {
+    // Check 4: Completed / unknown-state task log: allow only through strictly single unchained `rtk read`
+    if (taskMatch && !isExplicitRtkRead) {
       respond({
         decision: "deny",
         reason:
           "Antigravity Execution Governance: Direct shell access to internal Antigravity execution state (.system_generated) is strictly prohibited to prevent transcript bloat and polling loops.\n" +
-          `- Once completed, inspect output using 'rtk read <path>' via run_command.\n` +
+          "- Once completed, inspect output using 'rtk read <path>' via run_command.\n" +
           "- If actively running, yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>)."
       });
     }
 
+    // Prevent cascading secondary spillover when `rtk read` is invoked without line bounds on a >45 KiB spillover/task log
+    if (isRtkRead && (isSpillover || taskMatch)) {
+      const hasLineBoundFlag = /(?:^|\s)(?:--head-lines|--tail-lines|--max-lines|-m|--level|-l)(?:=|\s|$)/.test(effectiveCmd);
+      if (!hasLineBoundFlag) {
+        const rtkTokens = tokenizeShellWords(effectiveCmd);
+        const pathTok = rtkTokens.slice(2).find((t) => !t.startsWith("-"));
+        if (pathTok) {
+          try {
+            const st = fs.statSync(pathTok);
+            if (st.isFile() && st.size > 46080) {
+              effectiveCmd = effectiveCmd.replace(/^(\S+\s+read\b)/i, "$1 --tail-lines 150");
+            }
+          } catch {}
+        }
+      }
+    }
+
     const isDaemon = args.IsDaemon === true || args.isDaemon === true;
-    const waitMs = args.WaitMsBeforeAsync !== undefined ? args.WaitMsBeforeAsync : args.waitMsBeforeAsync;
+    const rawWaitMs = args.WaitMsBeforeAsync !== undefined ? args.WaitMsBeforeAsync : args.waitMsBeforeAsync;
+    const waitMs = rawWaitMs === null ? undefined : rawWaitMs;
     const targetMaxWait = Number(process.env.AGY_MAX_WAIT_MS) || 10000;
 
     const overwrite = {};
-    if (rewritten !== rawCmd) {
-      overwrite.CommandLine = rewritten;
+    if (effectiveCmd !== rawCmd) {
+      overwrite.CommandLine = effectiveCmd;
     }
-    if (!isDaemon && (waitMs === undefined || waitMs < targetMaxWait)) {
+    if (!isDaemon && waitMs === undefined) {
       overwrite.WaitMsBeforeAsync = targetMaxWait;
     }
 
@@ -718,7 +3555,7 @@ try {
   }
 
   // =========================================================================
-  // 2. Native File & Inspection Tools: Root Protection & RTK Hard-Routing
+  // 2. Native File & Inspection Tools: Root Protection, Hybrid Slice & RTK
   // =========================================================================
   const INSPECTION_TOOLS = new Set([
     "view_file",
@@ -731,22 +3568,48 @@ try {
 
   if (INSPECTION_TOOLS.has(toolName)) {
     const rawTarget =
+      args.Path ||
+      args.path ||
       args.AbsolutePath ||
       args.absolutePath ||
+      args.TargetFile ||
       args.targetFile ||
       args.target_file ||
-      args.path ||
       args.dirPath ||
       args.dir_path ||
       args.directory ||
+      args.SearchPath ||
+      args.searchPath ||
       "";
     const target = String(rawTarget).trim();
 
-    // 2a. Step Output Spillover Safe Harbor (hard-route to rtk read)
+    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 rawStart = args.StartLine !== undefined ? args.StartLine : (args.startLine !== undefined ? args.startLine : args.start_line);
+    const rawEnd = args.EndLine !== undefined ? args.EndLine : (args.endLine !== undefined ? args.endLine : args.end_line);
+    const hasByteOffset = args.ByteOffset !== undefined || args.byteOffset !== undefined || args.byte_offset !== undefined;
+    const hasSliceParams = rawStart !== undefined || rawEnd !== undefined;
+
+    // 2a. Step Output Spillover Safe Harbor: bounded read_file (<= 150 lines) allowed; else route to rtk read / bounded read_file
     if (isStepSpilloverPath(target)) {
+      if (toolName === "read_file" && rawStart !== undefined && rawEnd !== undefined) {
+        const startLine = Number(rawStart);
+        const endLine = Number(rawEnd);
+        if (
+          Number.isInteger(startLine) &&
+          Number.isInteger(endLine) &&
+          startLine > 0 &&
+          endLine >= startLine &&
+          (endLine - startLine + 1) <= MAX_SAFE_SLICE_LINES
+        ) {
+          respond({ decision: "allow" });
+        }
+      }
       respond({
         decision: "deny",
-        reason: `Antigravity Governance: Native file inspection via '${toolName}' bypasses token optimization. Run 'rtk read ${target}' via run_command instead.`
+        reason: `Antigravity Governance: Unbounded inspection of step spillover via '${toolName}' is denied. Pass a bounded slice ('StartLine' and 'EndLine', max ${MAX_SAFE_SLICE_LINES} lines) to 'read_file' or run 'rtk read ${target}' via run_command instead.`
       });
     }
 
@@ -757,20 +3620,16 @@ try {
       if (state === "RUNNING") {
         denyRunningTask(taskMatch.id, convId);
       }
-
       if (state === "COMPLETED") {
-        // If terminated / completed, route to rtk read:
         respond({
           decision: "deny",
           reason: `Antigravity Governance: Native file inspection via '${toolName}' bypasses token optimization. Run 'rtk read ${target}' via run_command instead.`
         });
       }
-
-      // If not verified completed (or does not exist):
       respond({
         decision: "deny",
         reason:
-          "Antigravity Execution Governance: Direct access to internal Antigravity execution state (.system_generated/tasks) is strictly prohibited to prevent polling loops. rely on native Reactive Wakeup (<SYSTEM_MESSAGE>) upon completion."
+          "Antigravity Execution Governance: Direct access to internal Antigravity execution state (.system_generated/tasks) is strictly prohibited to prevent polling loops. Rely on native Reactive Wakeup (<SYSTEM_MESSAGE>) upon completion."
       });
     }
 
@@ -778,79 +3637,35 @@ try {
     if (isProtectedInternalState(target) || isProtectedInternalState(JSON.stringify(args))) {
       respond({
         decision: "deny",
-        reason:
-          "Antigravity Execution Governance: Direct access to internal Antigravity execution state (.system_generated) is strictly prohibited to prevent transcript bloat and polling loops.\n" +
-          "- To inspect conversation transcripts: Call MCP tool read_transcript(conversationId=\"...\", mode=\"compact\") or query_transcript(...).\n" +
-          "- To inspect background tasks: Yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>). Do not read internal task logs."
+        reason: buildInternalStateToolDenial(convId)
       });
     }
 
-    // 2d. Allow Antigravity Special Files (SKILL.md, brain artifacts, configs)
+    // 2d. Allow Antigravity Special Files (SKILL.md, brain artifacts, configs) symmetrically for read_file & view_file
     if (isAntigravitySpecialFile(target)) {
       respond({ decision: "allow" });
     }
 
-    // 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`;
+    // 2e. Symmetrical Hybrid Slice & Guarded Full-File Policy for `read_file` and `view_file`
+    if (toolName === "read_file" || toolName === "view_file") {
+      const rgAvailable = Boolean(findExecutableOnPath("rg"));
+      const searchHint = rgAvailable ? "rtk rg" : "rtk grep -rnE";
+      const discoveryGuidance = `Locate the target symbol, heading, or config key first with '${searchHint}' via run_command and pass a precise bounded slice ('StartLine' and 'EndLine', max ${MAX_SAFE_SLICE_LINES} lines) to '${toolName}', 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";
+      if (hasByteOffset && !hasSliceParams) {
+        respond({
+          decision: "deny",
+          reason: `Antigravity Governance: Unbounded 'ByteOffset'-only read via '${toolName}' is denied. ${discoveryGuidance}.`
+        });
+      }
 
       if (hasSliceParams) {
         const startLine = Number(rawStart);
         const endLine = Number(rawEnd);
 
         if (
-          typeof rawStart !== "undefined" &&
-          typeof rawEnd !== "undefined" &&
+          rawStart !== undefined &&
+          rawEnd !== undefined &&
           Number.isInteger(startLine) &&
           Number.isInteger(endLine) &&
           startLine > 0 &&
@@ -861,7 +3676,7 @@ try {
             respond({ decision: "allow" });
           }
 
-          const metrics = startLine === 1 ? getFileMetrics(target) : null;
+          const metrics = startLine === 1 && !hasByteOffset ? getFileMetrics(target) : null;
           const isExplicitFullFile = Boolean(
             metrics &&
               startLine === 1 &&
@@ -875,19 +3690,19 @@ try {
             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}.`
+              reason: `Antigravity Governance: Explicit full-file read via '${toolName}' (${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 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}.`
+            reason: `Antigravity Governance: Oversized partial file slice via '${toolName}' (${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. ${discoveryGuidance}.`
+          reason: `Antigravity Governance: Invalid slice range via '${toolName}'. Ensure StartLine and EndLine are positive integers with EndLine >= StartLine. ${discoveryGuidance}.`
         });
       }
 
@@ -898,13 +3713,6 @@ try {
     }
 
     // 2f. Hard-Route Other Native File/Search Tools (LH-07)
-    if (toolName === "read_file") {
-      respond({
-        decision: "deny",
-        reason: `Antigravity Governance: Native file inspection via 'read_file' bypasses token optimization. Run 'rtk read ${target || "<file>"}' via run_command instead.`
-      });
-    }
-
     if (toolName === "read_many_files") {
       respond({
         decision: "deny",
@@ -913,9 +3721,13 @@ try {
     }
 
     if (toolName === "grep_search") {
-      const pattern = args.query || args.pattern || "";
-      const isWin = os.platform() === "win32";
-      const cmdHint = isWin ? `rtk rg "${pattern}" .` : `rtk grep "${pattern}"`;
+      const pattern = String(args.Query || args.query || args.Pattern || args.pattern || "").trim();
+      const searchTarget = String(args.SearchPath || args.searchPath || args.path || ".").trim() || ".";
+      const safePattern = pattern ? escapeDoubleQuotedArg(pattern) : "<pattern>";
+      const rgAvailable = Boolean(findExecutableOnPath("rg"));
+      const cmdHint = rgAvailable
+        ? `rtk rg -- "${safePattern}" ${searchTarget}`
+        : `rtk grep -rnE "${safePattern}" ${searchTarget}`;
       respond({
         decision: "deny",
         reason: `Antigravity Governance: Native grep inspection via 'grep_search' bypasses token optimization. Run '${cmdHint}' via run_command instead.`
@@ -923,7 +3735,7 @@ try {
     }
 
     if (toolName === "find_by_name") {
-      const searchTarget = args.query || args.pattern || target || ".";
+      const searchTarget = args.Pattern || args.pattern || args.query || target || ".";
       respond({
         decision: "deny",
         reason: `Antigravity Governance: Native file search via 'find_by_name' bypasses token optimization. Run 'rtk find ${searchTarget}' via run_command instead.`
@@ -932,7 +3744,7 @@ try {
 
     if (toolName === "list_dir") {
       const isWin = os.platform() === "win32";
-      const cmdHint = isWin ? `rtk find ${target || "."}` : `rtk ls ${target || ""}`;
+      const cmdHint = isWin ? `rtk find ${target || "."}` : `rtk ls ${target || "."}`;
       respond({
         decision: "deny",
         reason: `Antigravity Governance: Native directory listing via 'list_dir' bypasses token optimization. Run '${cmdHint}' via run_command instead.`
@@ -993,22 +3805,22 @@ try {
   }
 
   if (toolName === "schedule") {
-    const prompt = String(args.Prompt || args.prompt || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
-    const cond = String(args.TimerCondition || args.timerCondition || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
     const duration = Number(args.DurationSeconds || args.durationSeconds || args.duration || 0);
 
-    const isTaskPoll =
-      cond.startsWith("task-") ||
-      cond.includes("task") ||
-      prompt.includes("check on") ||
-      prompt.includes("check task") ||
-      prompt.includes("background task") ||
-      prompt.includes("still running") ||
-      prompt.includes("test suite") ||
-      ((prompt.includes("check") || prompt.includes("status") || prompt.includes("poll") || prompt.includes("monitor") || prompt.includes("wait")) &&
-       (prompt.includes("task") || prompt.includes("process") || prompt.includes("job") || prompt.includes("test") || prompt.includes("command") || prompt.includes("suite")));
-
-    if (isTaskPoll) {
+    if (isSwarmPollSchedule(args)) {
+      const session = getSessionState(convId);
+      session.denials++;
+      saveSessionState(convId, session);
+      respond({
+        decision: "deny",
+        reason:
+          "Antigravity Execution Governance: Using one-shot 'schedule' timers to poll a swarm or subagent is strictly prohibited. " +
+          "For '/swarm', call 'swarm_wait' directly without a 'schedule' timer (it sleeps at zero token cost and wakes immediately when any board message arrives, while the dedicated 'swarm_monitor' daemon cron checks for stalls). " +
+          "For subagents, stop calling tools and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>)."
+      });
+    }
+
+    if (isTaskPollSchedule(args)) {
       const session = getSessionState(convId);
       const requiredBackoffSec = Math.max(30, getRequiredBackoffSeconds(session.pollCount));
 
@@ -1030,7 +3842,12 @@ try {
         });
       }
 
-      // If duration >= requiredBackoffSec, watchdog timer is permitted!
+      // If duration >= requiredBackoffSec, watchdog timer is permitted AND advances backoff level
+      // so repeated 45s/60s timers without exponential backoff are blocked on subsequent turns:
+      session.pollCount = Math.max(1, session.pollCount) + 1;
+      session.lastPollTime = Date.now();
+      session.denials = 0;
+      saveSessionState(convId, session);
       respond({ decision: "allow" });
     }
 
@@ -1039,10 +3856,57 @@ try {
   }
 
   // =========================================================================
-  // 4. Benchmark & Evaluator Mutation Protection (LH-09)
+  // 4. Benchmark, Governance & Evaluator Mutation Protection (LH-09 & LH-02)
   // =========================================================================
-  if (toolName === "replace_file_content" || toolName === "write_to_file") {
-    const targetFile = String(args.TargetFile || args.targetFile || args.path || "").trim();
+  if (
+    toolName === "replace_file_content" ||
+    toolName === "write_to_file" ||
+    toolName === "write_file" ||
+    toolName === "edit_file"
+  ) {
+    const targetFile = String(args.Path || args.path || args.TargetFile || args.targetFile || "").trim();
+    if (isProtectedInternalState(targetFile)) {
+      respond({
+        decision: "deny",
+        reason: buildInternalStateToolDenial(convId)
+      });
+    }
+    if (isProtectedGovernanceFileMutation(targetFile, convId)) {
+      respond({
+        decision: "deny",
+        reason:
+          "Antigravity Execution Governance: Direct mutation of protected Antigravity hook, shim, or governance source files is strictly prohibited."
+      });
+    }
+
+    const bodyContent = String(
+      args.Content ||
+        args.content ||
+        args.file_content ||
+        args.Replacement ||
+        args.replacement ||
+        args.new_string ||
+        ""
+    );
+    const normTarget = targetFile.replace(/\\/g, "/");
+    const isTmpOrScratch =
+      normTarget.startsWith("/tmp/") ||
+      normTarget.startsWith("/var/tmp/") ||
+      normTarget.includes("/scratch/") ||
+      normTarget.startsWith("scratch/") ||
+      normTarget.startsWith(os.tmpdir().replace(/\\/g, "/") + "/");
+    const isScript = isExecutableScriptPath(targetFile) || /^\s*#!/.test(bodyContent);
+    const callerAccess = evaluateCallerTranscriptAccess(convId);
+
+    if (isScript && bodyContent && (callerAccess.isRestrictedChild || isTmpOrScratch)) {
+      if (isProtectedShellOrScriptOperation(bodyContent)) {
+        respond({
+          decision: "deny",
+          reason: buildInternalStateShellDenial(convId)
+        });
+      }
+    }
+
     if (isProtectedBenchmarkPath(targetFile)) {
       respond({
         decision: "force_ask",