agy-context-saver 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to `Agy-Context-Saver` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2026-10-08
+
+### Added (Output Inspection Governance & Forensic Dereferencing - LH-12)
+- **Folded Surgical Step Dereferencing in `query_transcript` (NFF-05)**: Added optional `stepIndex` (number) and `field` (string) parameters to `query_transcript`, allowing surgical single-step extraction from `transcript_full.jsonl` without creating redundant tools. Recovers un-truncated subagent messages and arguments with zero surrounding context bloat.
+- **Safe-Harbor `rtk read` for Step Output Spillovers (NFF-01 & NFF-02)**: Provided a safe harbor in `execution-guard-hook.mjs` allowing `rtk read` on runtime step output spillovers (`.system_generated/steps/<step>/output.txt`). Native `view_file` and shell `cat` invocations are automatically routed to `rtk read <path>`, leveraging `rtk read`'s built-in line clamping, head/tail windowing, and token truncation.
+- **Lifecycle-Gated Task Output Inspection (NFF-03)**: Added lifecycle governance for background task logs (`tasks/<taskId>.log`) in `execution-guard-hook.mjs`. Invocations are strictly **denied** under Proportional Backoff while tasks are `RUNNING` to stop polling loops, but allowed via `rtk read` once `COMPLETED` / `TERMINATED` for bounded stack trace and failure inspection.
+- **Pointer-Over-Wire (POW) Subagent Contract (NFF-06)**: Integrated the POW protocol into `subagent_brief`. Research findings $>1\text{ KB}$ are written to workspace artifacts (`scratch/...`), while `send_message` transmits only executive summaries and clickable file links, preventing message bus truncations.
+- **Output Governance Test Suite**: Added `tests/test-output-governance.mjs` verifying spillover safe-harbor access, task output lifecycle gating, forensic step extraction, and hook routing.
+
+### Changed
+- **Streamlined Tool Architecture (0 New Tools)**: Eliminated tool proliferation by consolidating capabilities into existing tools and hooks, maintaining strictly the 6 core canonical MCP tools (zero prompt token bloat, zero tool-selection ambiguity).
+- **Typed Argument Descriptors (NFF-04)**: Replaced blind `JSON.stringify().slice(0, 80)` in `formatTranscriptItem()` with typed argument descriptors (`[14.2 KB String]`, `[Array(5)]`, `{Object(3 keys)}`), preserving JSON payload integrity and transcript legibility.
+
+---
+
+## [1.3.2] - 2026-10-07
+
+### Governance & Command Semantics (LH-11 Hardening)
+- **Opt-In Fail-Fast Semantics**: Reverted forced `-x -q` parameter injection on bare test runner invocations to preserve native command semantics. Fail-fast (`-x`, `--maxfail=1`) remains strictly opt-in, preventing the "whack-a-mole" repair loop and preserving complete failure blast radius visibility across multi-module test suites.
+- **Architectural Separation**: Replaced forced command mutation with the **Coordinated Watchdog Protocol** and **Mandatory Pre-Yield Status Cards** in `rules/AGENTS.md`, ensuring visibility during multi-minute full-repository sweeps without distorting test results.
+- **Loophole Ledger Synchronization**: Updated `LEDGER.md` (LH-11) documenting the trade-offs of fail-fast injection vs native command semantics.
+
+---
+
+## [1.3.1] - 2026-10-07
+
+### Governance & Asynchronous Execution Observability (LH-11)
+- **Fail-Fast Auto-Injection on Bare Test Sweeps**: `execution-guard-hook.mjs` transparently normalizes bare `pytest` and `python -m pytest` invocations to include `-x -q` (fail-fast, quiet mode). In large codebases (e.g. 900+ tests), this prevents multi-minute unconstrained sweeps by stopping execution immediately at the first failure.
+- **Coordinated Watchdog Protocol Codification**: Updated `rules/AGENTS.md` to explicitly train agents on the Coordinated Watchdog Protocol: when launching heavy background operations ($> 15\text{s}$), agents must schedule a coordinated watchdog timer (`schedule(DurationSeconds=45, ...)`) to prevent silent yielding into unmonitored execution black holes.
+- **Mandatory Pre-Yield Status Cards**: Codified in `rules/AGENTS.md` that agents launching background tasks must output a structured markdown status card (command, scope, estimated duration, watchdog tier) before yielding their turn, eliminating user uncertainty during prolonged runs.
+- **Loophole Ledger LH-11 Addition**: Formally documented LH-11 (Silent Background Deadlock & Bare Sweep Exhaustion) from Incident `07b0f8d8` in `LEDGER.md`.
+
+---
+
 ## [1.3.0] - 2026-10-07
 
 ### Governance & Loophole Elimination

package/README.md

@@ -103,6 +103,33 @@ npm run status
 
 ---
 
+## Comprehensive Documentation
+
+For complete technical references, architectural specifications, and governance rules, visit our **[Zensical Documentation Site](https://paragon-ux.github.io/agy-context-saver/)**:
+
+- 📖 **[Getting Started & Installation](docs/installation.md)**: Zero-delay setup, native plugin linking, hooks registration, and verification matrix.
+- 🏗️ **[Architecture & Internals](docs/architecture.md)**: Closed Execution Topology, RTK separation of concerns, and the Four Non-Fragile Architectural Pillars.
+- 🛡️ **[Lifecycle Governance & Hooks](docs/governance.md)**: Proportional Backoff curve, Reactive Wakeup invariants, and the 5-strike circuit breaker.
+- 🧰 **[MCP Tools & CLI Reference](docs/tools.md)**: Complete specifications for all 6 canonical autonomous MCP tools, slash commands, and diagnostic utilities.
+- 🔬 **[Forensic & Output Inspection](LEDGER_OUTPUT_FIXES.md)**: Ephemeral tool spillover resolution, post-mortem task retrieval, and Pointer-Over-Wire (POW) contracts.
+- 🚀 **[Publishing & Verification Playbook](docs/publishing.md)**: Clean-room test runs, release procedures, and multi-suite verification matrix.
+
+---
+
+## Local Documentation Server
+
+Build or serve the documentation locally using **Zensical**:
+
+```bash
+# Build static documentation site
+py -3.11 -m zensical build
+
+# Serve live preview server
+py -3.11 -m zensical serve
+```
+
+---
+
 ## Zero-Guesswork Testing & Verification Playbook
 
 To cleanly test every layer of the framework without guesswork or interactive stalls:
@@ -160,12 +187,16 @@ node tests/test-lifecycle-rollback.mjs
   - `/mcp:agy-context-saver:context_shield`: Injects 3-layer governance rules and RTK standards into any session with one click. *(MCP Prompts appear in your chat autocomplete menu; MCP Tools are called autonomously by the agent).*
 * **Agent MCP Tools**:
   1. `check_context_health`: Diagnoses conversation transcript turn budgets, payload size, RTK status, and polling loops.
-  2. `subagent_brief`: Formulates scope-isolated prompts for delegated subagents.
+  2. `subagent_brief`: Formulates scope-isolated prompts for delegated subagents with Pointer-Over-Wire (POW) delivery contract.
   3. `read_transcript`: Reads recent conversation history in clean Markdown format (compact/full).
-  4. `query_transcript`: Forensic filtering and regex search engine for conversation logs.
+  4. `query_transcript`: Forensic filtering, regex search engine, and surgical single-step dereferencing (`stepIndex`, `field`) from full transcripts.
   5. `get_installation_status`: Inspects live Antigravity plugin link, hook, MCP server, tool schemas, and RTK binary.
   6. `sync_installation`: Re-verifies and repairs all integration layers in ~25ms.
 
+* **Streamlined Output Inspection (0 New Tools)**:
+  - **Runtime Step Spillovers** (`.system_generated/steps/<step>/output.txt`): Inspected via canonical `rtk read <path>` (safe-harbored in the PreToolUse hook; native `view_file` calls automatically route to `rtk read`).
+  - **Completed Background Task Logs**: Inspected via `rtk read tasks/<taskId>.log` (lifecycle-gated in the PreToolUse hook; strictly blocked under Proportional Backoff while running, allowed once completed).
+
 ---
 
 ## License

package/mcp/index.js

@@ -98,7 +98,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rulesPath = path.resolve(__dirname, "../rules/AGENTS.md");
 
 const SERVER_NAME = "agy-context-saver";
-const SERVER_VERSION = "1.3.0";
+const SERVER_VERSION = "1.4.0";
 
 // --- Tools Specification ---
 const TOOLS = [
@@ -243,6 +243,14 @@ const TOOLS = [
         summaryOnly: {
           type: "boolean",
           description: "If true, returns high-density 1-line step summaries instead of full message blocks to minimize UI card height (default: false)."
+        },
+        stepIndex: {
+          type: "number",
+          description: "Optional step_index to surgically retrieve full un-truncated content for a single step from transcript_full.jsonl."
+        },
+        field: {
+          type: "string",
+          description: "Optional specific field to extract when stepIndex is provided (e.g. 'content', 'thinking', 'tool_calls', 'tool_args', or 'tool_args:Message'). Defaults to full step."
         }
       },
       required: ["conversationId"]
@@ -379,12 +387,17 @@ function handleSubagentBrief({ objective, scopeFiles = [], expectedDeliverable =
     `ROLE: Scope-Isolated Deep Research Subagent`,
     `OBJECTIVE: ${objective}${scopeStr}`,
     ``,
-    `CRITICAL CONTEXT GOVERNANCE INSTRUCTIONS:`,
-    `1. You are running in an isolated subagent sandbox. Do all necessary multi-file exploration, searches, and analysis here.`,
-    `2. DO NOT dump raw file contents or massive grep outputs in your final response.`,
-    `3. Deliver strictly the high-signal findings in the following format:`,
-    `   ${expectedDeliverable}`,
-    `4. Keep your final response concise, structured, and cite exact file:line references.`
+    `CRITICAL CONTEXT GOVERNANCE INSTRUCTIONS (POINTER-OVER-WIRE):`,
+    `1. Isolated Workspace: Do all necessary multi-file exploration, searches, and analysis in this subagent sandbox.`,
+    `2. Pointer-Over-Wire (POW) Protocol: In-band messaging channels (send_message) have strict transport payload limits (~16-20 KB). If your findings or deliverable exceed 1 KB:`,
+    `   a. Write the full comprehensive deliverable or raw output to a file in the workspace (e.g., 'scratch/<task>_findings.md' or an artifact).`,
+    `   b. In 'send_message', transmit ONLY:`,
+    `      - Executive Summary (3-5 high-signal sentences)`,
+    `      - Verdict / Scoreboard Table`,
+    `      - Clickable File Link: [Full Deliverable](file:///absolute/path/to/findings.md)`,
+    `3. Fast Turn Termination: Once 'send_message' is dispatched, stop calling tools and conclude your turn immediately so the parent agent wakes up without latency.`,
+    `4. Format: ${expectedDeliverable}`,
+    `5. Citation Mandate: Keep your final response concise, structured, and cite exact file:line references.`
   ].join("\n");
 
   return { content: [{ type: "text", text: prompt }] };
@@ -393,12 +406,13 @@ function handleSubagentBrief({ objective, scopeFiles = [], expectedDeliverable =
 function handleGetInstallationStatus() {
   const existing = detectExistingInstallation();
   const rtkInfo = findExistingRtk();
+  const schemaText = existing.details.schemas.exists ? "ALL 6 SCHEMAS PRESENT" : "MISSING";
   const report = [
     `### Agy-Context-Saver Installation Status: ${existing.isComplete ? "HEALTHY & ACTIVE 🛡️" : existing.isInstalled ? "PARTIAL INSTALLATION ⚠️" : "NOT INSTALLED ❌"}`,
     `- Native Plugin Link: ${existing.details.plugin.exists ? `ACTIVE (${existing.details.plugin.target})` : "NOT LINKED"}`,
     `- Governor Lifecycle Hook: ${existing.details.hook.registered ? "REGISTERED in hooks.json" : "NOT REGISTERED"} (Script: ${existing.details.hook.scriptExists ? "Present" : "Missing"})`,
     `- Universal MCP Server: ${existing.details.mcp.registered ? "CONFIGURED in mcp_config.json" : "NOT CONFIGURED"}`,
-    `- Antigravity Tool Schemas: ${existing.details.schemas.exists ? "ALL 6 SCHEMAS PRESENT" : "MISSING"} (${existing.details.schemas.dir})`,
+    `- Antigravity Tool Schemas: ${schemaText} (${existing.details.schemas.dir})`,
     `- RTK Binary: ${rtkInfo ? `INSTALLED (${rtkInfo.version})` : "MISSING"}`,
     `- RTK Hook Optimization: ${existing.details.hook.registered ? "ACTIVE (via PreToolUse)" : "INACTIVE"}`,
     "",
@@ -555,6 +569,28 @@ function cleanMessageContent(content, maxChars = MAX_TURN_CHARS) {
   return text;
 }
 
+function formatArgumentDescriptor(k, v) {
+  if (typeof v === "string") {
+    if (v.length <= 80 && !v.includes("\n")) {
+      return `${k}=${JSON.stringify(v)}`;
+    }
+    const preview = v.replace(/[\r\n\t]+/g, " ").slice(0, 50).trim();
+    const sizeKb = (Buffer.byteLength(v, "utf8") / 1024).toFixed(1);
+    return `${k}="${preview}..." [${sizeKb} KB]`;
+  }
+  if (typeof v === "number" || typeof v === "boolean" || v === null) {
+    return `${k}=${v}`;
+  }
+  if (Array.isArray(v)) {
+    return `${k}=[Array(${v.length})]`;
+  }
+  if (typeof v === "object") {
+    const keys = Object.keys(v);
+    return `${k}={Object(${keys.length} keys)}`;
+  }
+  return `${k}=${String(v).slice(0, 60)}`;
+}
+
 function formatTranscriptItem(item, options = {}) {
   const { includeThinking = false, includeToolCalls = false, maxContentChars = MAX_TURN_CHARS } = options;
   const stepIdx = item.step_index !== undefined ? item.step_index : "?";
@@ -583,7 +619,7 @@ function formatTranscriptItem(item, options = {}) {
       const name = tc.name || tc.tool_name || "unknown_tool";
       const args = tc.args || tc.arguments || {};
       const compactArgs = Object.entries(args)
-        .map(([k, v]) => `${k}=${JSON.stringify(v).slice(0, 80)}`)
+        .map(([k, v]) => formatArgumentDescriptor(k, v))
         .join(", ");
       return `- \`${name}(${compactArgs})\``;
     });
@@ -745,9 +781,106 @@ async function handleQueryTranscript(args = {}) {
     includeThinking = false,
     includeToolCalls = false,
     maxResults = 5,
-    summaryOnly = false
+    summaryOnly = false,
+    stepIndex,
+    field
   } = args;
 
+  // Surgical single-step dereferencing (folded from get_step_detail)
+  if (stepIndex !== undefined && stepIndex !== null) {
+    const numIndex = Number(stepIndex);
+    if (isNaN(numIndex)) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Error: 'stepIndex' must be a number (received: ${stepIndex}).` }]
+      };
+    }
+
+    const resolvedFull = resolveTranscriptPath(conversationId, "full");
+    let step = null;
+    if (resolvedFull && resolvedFull.filePath && fs.existsSync(resolvedFull.filePath)) {
+      step = await findFullStep(resolvedFull.filePath, numIndex);
+    }
+
+    if (!step) {
+      const resolvedCompact = resolveTranscriptPath(conversationId, "compact");
+      if (resolvedCompact && resolvedCompact.filePath && fs.existsSync(resolvedCompact.filePath)) {
+        step = await findFullStep(resolvedCompact.filePath, numIndex);
+      }
+    }
+
+    if (!step) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Step index ${numIndex} not found in transcript.` }]
+      };
+    }
+
+    const MAX_FIELD_CHARS = 24000;
+
+    if (field) {
+      const f = String(field).trim();
+      if (f === "content") {
+        const val = step.content || "(No content in step)";
+        return {
+          content: [{ type: "text", text: `### Step ${numIndex} Content\n\n${val.slice(0, MAX_FIELD_CHARS)}` }]
+        };
+      }
+      if (f === "thinking") {
+        const val = step.thinking || "(No thinking block in step)";
+        return {
+          content: [{ type: "text", text: `### Step ${numIndex} Thinking\n\n${val.slice(0, MAX_FIELD_CHARS)}` }]
+        };
+      }
+      if (f === "tool_calls") {
+        const val = JSON.stringify(step.tool_calls || [], null, 2);
+        return {
+          content: [{ type: "text", text: `### Step ${numIndex} Tool Calls\n\`\`\`json\n${val.slice(0, MAX_FIELD_CHARS)}\n\`\`\`` }]
+        };
+      }
+      if (f === "tool_args" || f.startsWith("tool_args:")) {
+        const argName = f.includes(":") ? f.split(":")[1].trim() : null;
+        const tc = Array.isArray(step.tool_calls) && step.tool_calls.length > 0 ? step.tool_calls[0] : null;
+        if (!tc) {
+          return {
+            content: [{ type: "text", text: `Step ${numIndex} contains no tool calls.` }]
+          };
+        }
+        const tcArgs = tc.args || tc.arguments || {};
+        if (argName) {
+          const argVal = tcArgs[argName];
+          const displayVal = typeof argVal === "string" ? argVal : JSON.stringify(argVal, null, 2);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `### Step ${numIndex} Argument: \`${argName}\`\n\n${String(displayVal).slice(0, MAX_FIELD_CHARS)}`
+              }
+            ]
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `### Step ${numIndex} Tool Arguments\n\`\`\`json\n${JSON.stringify(tcArgs, null, 2).slice(0, MAX_FIELD_CHARS)}\n\`\`\``
+            }
+          ]
+        };
+      }
+    }
+
+    const formatted = formatTranscriptItem(step, {
+      includeThinking: true,
+      includeToolCalls: true,
+      maxContentChars: MAX_FIELD_CHARS
+    });
+
+    return {
+      content: [{ type: "text", text: formatted }]
+    };
+  }
+
   const resolved = resolveTranscriptPath(conversationId, mode === "full" ? "full" : "compact");
   if (resolved.error) {
     return { isError: true, content: [{ type: "text", text: resolved.error }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-context-saver",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Universal Model Context Protocol (MCP) server & lifecycle governor purpose-built for Google Antigravity",
   "main": "mcp/index.js",
   "bin": {
@@ -12,7 +12,7 @@
     "setup": "node scripts/install-register.mjs",
     "uninstall": "node scripts/install-register.mjs --uninstall",
     "status": "node scripts/install-register.mjs --status",
-    "test": "node tests/test-hook.mjs && node tests/test-mcp.mjs && node tests/test-e2e-probes.mjs && node tests/test-performance-probes.mjs && node tests/test-installed-verification.mjs && node tests/test-lifecycle-rollback.mjs"
+    "test": "node tests/test-hook.mjs && node tests/test-mcp.mjs && node tests/test-output-governance.mjs && node tests/test-e2e-probes.mjs && node tests/test-performance-probes.mjs && node tests/test-installed-verification.mjs && node tests/test-lifecycle-rollback.mjs"
   },
   "keywords": [
     "antigravity",

package/rules/AGENTS.md

@@ -6,11 +6,27 @@
 
 ---
 
-## Layer 1: Background Tasks & Polling Ban (Reactive Wakeup SSOT)
-- **Zero-Tolerance on Task Polling**: Do NOT call `manage_task(Action='status')` or `schedule` timers in a loop to wait for running background tasks. Background tasks execute asynchronously and automatically resume the agent via **Reactive Wakeup** (`<SYSTEM_MESSAGE>`).
-- **Yield Turn Immediately**: When a process moves to the background, stop calling tools, output a concise status message, and yield the turn.
-- **No Keyword or Timer Exemptions**: Words like "debug", "timeout", "diagnose", or "stuck" do NOT exempt an agent from lifecycle governance. Timers with `duration >= 120` are NOT exempt.
-- **Circuit Breaker**: Repeated polling calls across any tasks in a session trigger an escalating circuit breaker. At 5 cumulative denials, autonomous execution is frozen via `force_ask`.
+## Layer 1: Background Tasks & Proportional Backoff Protocol (Reactive Wakeup SSOT)
+- **Zero-Tolerance on Busy-Polling**: Do NOT call `manage_task(Action='status')` in tight loops or schedule rapid timers to wait for running background tasks. Background tasks execute asynchronously and automatically resume the agent via **Reactive Wakeup** (`<SYSTEM_MESSAGE>`).
+- **Proportional Backoff Protocol**: Diagnostic inspections scale along an exponential backoff curve:
+  $\text{Cooldown} = \min(600, \text{round}(30 \times 2.5^{\text{pollCount} - 1})) \quad [0\text{s} \to 30\text{s} \to 75\text{s} \to 188\text{s} \to 469\text{s} \to 600\text{s}]$
+  - Check #1 (Immediate upon launch): Permitted ($0\text{s}$).
+  - Premature status checks within an active backoff window are denied. 5 consecutive premature checks trigger the `force_ask` circuit breaker.
+  - Silent/hung background tasks: Once the backoff window elapses, a single diagnostic check is permitted to inspect logs, detect deadlocks, and issue `manage_task(Action='kill')` if needed.
+- **Coordinated Watchdog Protocol (`schedule`)**: For long-running operations (builds, migrations, test suites) expected to take $> 15\text{s}$:
+  - Schedule a coordinated watchdog timer: `schedule(DurationSeconds=45, Prompt="Check status of background task-X", TimerCondition="task-X")`.
+  - Watchdog timers must satisfy `DurationSeconds >= Math.max(30, requiredBackoffSec)`. Short timers are denied.
+  - If the task completes early, Reactive Wakeup auto-cancels the timer and resumes the agent immediately.
+  - If the task is still running when the watchdog fires, perform a legal diagnostic check (`manage_task(status)`) and post a live progress update in chat for the user.
+- **Mandatory Pre-Yield Status Card**: When a command moves to the background, NEVER yield with a silent or generic one-liner. Output a structured Markdown card so the user is never left wondering if the IDE has stalled:
+  ```markdown
+  ### ⏳ Background Execution Started
+  - **Command**: `<cmd>`
+  - **Scope / Target**: `<scope>`
+  - **Estimated Duration**: `~X minutes`
+  - **Watchdog Active**: Coordinated check scheduled in 45s via Reactive Wakeup.
+  ```
+- **Kill & Stdin Immediate Exemption**: `manage_task(Action='kill')` and `manage_task(Action='send_input')` are ALWAYS permitted immediately ($0\text{s}$ backoff, zero penalties).
 
 ---
 
@@ -34,7 +50,11 @@
 
 ## Layer 3: Synchronous Execution & Subagent Delegation
 - **Maximum Synchronous Window**: Non-daemon `run_command` calls are automatically set to `WaitMsBeforeAsync: 10000` to complete synchronously and prevent unnecessary background detachment.
-- **Targeted Test Execution**: Avoid massive multi-minute test sweeps in interactive turns. Run targeted, quiet, fail-fast commands (e.g. `pytest tests/test_core.py -q -x`).
+- **Targeted Test Execution & Opt-In Fail-Fast (LH-11)**:
+  - **Targeted Invocations**: In interactive turns, prefer targeting specific test files or directories (e.g. `pytest tests/test_core.py`) rather than running full multi-minute repository sweeps.
+  - **Fail-Fast Flags are Opt-In**: Fail-fast flags (`-x`, `--maxfail=1`) are opt-in. Use them when quickly debugging a localized failure, but omit them when assessing the full blast radius across the codebase to avoid the "whack-a-mole" loop.
+  - **Coordinated Watchdog Mandatory for Full Sweeps**: When running full multi-minute test sweeps without `-x`, agents **MUST** pair execution with the **Coordinated Watchdog Protocol** (`schedule(DurationSeconds=45, ...)`) and output a **Pre-Yield Status Card**. Never yield silently.
+  - **Subagent Delegation for Deep Audits**: When a comprehensive repository-wide test audit is required, delegate the sweep to a subagent (`invoke_subagent`) to keep the main thread responsive.
 - **Subagent Delegation**: Delegate heavy multi-file exploration and exploratory research to subagents (`invoke_subagent`). Subagents absorb intermediate steps and return high-signal summaries.
 - **Benchmark / Evaluator Integrity**: Never mutate benchmark definitions, prompt templates, or scoring artifacts during an active evaluation without explicit user confirmation.
 

package/scripts/execution-guard-hook.mjs

@@ -184,6 +184,168 @@ function isProtectedBenchmarkPath(targetPath) {
   );
 }
 
+/**
+ * Checks if target path references runtime step output spillover file.
+ */
+function isStepSpilloverPath(targetPath) {
+  if (!targetPath || typeof targetPath !== "string") return false;
+  const normalized = targetPath.replace(/\\/g, "/");
+  return (
+    /\.system_generated[/\\]steps[/\\]\d+[/\\]output\.txt/i.test(normalized) ||
+    (normalized.includes("/.system_generated/steps/") && normalized.endsWith("output.txt"))
+  );
+}
+
+/**
+ * Extracts task ID from target path or command if targeting a task output log.
+ */
+function getTaskLogMatch(targetPath) {
+  if (!targetPath || typeof targetPath !== "string") return null;
+  const normalized = targetPath.replace(/\\/g, "/");
+  const match = normalized.match(/(?:^|[\s"'/])(?:\.system_generated\/)?tasks\/(?:task-)?([a-zA-Z0-9_-]+)\.log/i);
+  return match ? match[1] : null;
+}
+
+/**
+ * Resolves full path to a task log on disk.
+ */
+function resolveTaskLogFile(taskId, convId) {
+  if (taskId && typeof taskId === "string") {
+    if (fs.existsSync(taskId)) {
+      const cleanId = String(taskId).replace(/^.*[\/\\]/, "").replace(/\.log$/i, "");
+      return { logPath: taskId, convId: convId || "global", cleanId };
+    }
+    if (taskId.includes("/") || taskId.includes("\\")) {
+      const cleanId = String(taskId).replace(/^.*[\/\\]/, "").replace(/\.log$/i, "");
+      return { logPath: null, convId: convId || "global", cleanId };
+    }
+  }
+
+  const cleanId = String(taskId).replace(/^.*[\/\\]/, "").replace(/\.log$/i, "");
+  const baseTaskName = cleanId.startsWith("task-") ? cleanId : `task-${cleanId}`;
+
+  const home = os.homedir();
+  const brainDir = path.join(home, ".gemini", "antigravity", "brain");
+
+  if (convId && convId !== "global") {
+    const candidate = path.join(brainDir, convId, ".system_generated", "tasks", `${baseTaskName}.log`);
+    if (fs.existsSync(candidate)) {
+      return { logPath: candidate, convId, cleanId: baseTaskName };
+    }
+  }
+
+  return { logPath: null, convId: convId || "global", cleanId: baseTaskName };
+}
+
+/**
+ * Determines whether a background task is verified completed / terminated.
+ */
+function isTaskCompleted(taskId, convId, rawPath) {
+  const candidatePath = (rawPath && fs.existsSync(rawPath)) ? rawPath : null;
+  const resolved = resolveTaskLogFile(candidatePath || taskId, convId);
+  const logPath = resolved.logPath || candidatePath;
+  const cleanId = resolved.cleanId;
+
+  // 1. Session state check
+  const safeId = String(resolved.convId || convId || "global").replace(/[^a-zA-Z0-9_-]/g, "_");
+  const sessionPath = path.join(os.tmpdir(), `agy-session-${safeId}.json`);
+  if (fs.existsSync(sessionPath)) {
+    try {
+      const sess = JSON.parse(fs.readFileSync(sessionPath, "utf-8"));
+      if (sess && sess.tasks && sess.tasks[cleanId]) {
+        if (sess.tasks[cleanId].state === "TERMINATED" || sess.tasks[cleanId].state === "COMPLETED") return true;
+        if (sess.tasks[cleanId].state === "RUNNING") return false;
+      }
+    } catch {}
+  }
+
+  // 2. Transcript check
+  if (resolved.convId && resolved.convId !== "global") {
+    const home = os.homedir();
+    const candidateTrans = path.join(home, ".gemini", "antigravity", "brain", resolved.convId, ".system_generated", "logs", "transcript.jsonl");
+    if (fs.existsSync(candidateTrans)) {
+      try {
+        const content = fs.readFileSync(candidateTrans, "utf-8");
+        const taskRegex = new RegExp(`Task id [^"]*${cleanId}[^"]* finished`, "i");
+        if (taskRegex.test(content)) return true;
+      } catch {}
+    }
+  }
+
+  // 3. File exists on disk and age check (>15s and not marked live)
+  if (logPath && fs.existsSync(logPath)) {
+    if (cleanId.includes("live") || cleanId.includes("running")) {
+      return false;
+    }
+    try {
+      const stats = fs.statSync(logPath);
+      const mtimeAgeMs = Date.now() - stats.mtimeMs;
+      if (mtimeAgeMs > 15000) {
+        return true;
+      }
+    } catch {}
+  }
+
+  return false;
+}
+
+/**
+ * Determines whether a background task is actively running.
+ */
+function isTaskRunning(taskId, convId, rawPath) {
+  const candidatePath = (rawPath && fs.existsSync(rawPath)) ? rawPath : null;
+  const { logPath: resolvedPath, convId: resolvedConvId, cleanId } = resolveTaskLogFile(candidatePath || taskId, convId);
+  const logPath = resolvedPath || candidatePath;
+
+  // 1. Session state ledger check
+  const safeId = String(resolvedConvId || convId || "global").replace(/[^a-zA-Z0-9_-]/g, "_");
+  const sessionPath = path.join(os.tmpdir(), `agy-session-${safeId}.json`);
+  if (fs.existsSync(sessionPath)) {
+    try {
+      const sess = JSON.parse(fs.readFileSync(sessionPath, "utf-8"));
+      if (sess && sess.tasks && sess.tasks[cleanId]) {
+        if (sess.tasks[cleanId].state === "RUNNING") return true;
+        if (sess.tasks[cleanId].state === "TERMINATED" || sess.tasks[cleanId].state === "COMPLETED") return false;
+      }
+    } catch {}
+  }
+
+  // 2. Transcript check for completion notice
+  if (resolvedConvId && resolvedConvId !== "global") {
+    const home = os.homedir();
+    const candidateTrans = path.join(home, ".gemini", "antigravity", "brain", resolvedConvId, ".system_generated", "logs", "transcript.jsonl");
+    if (fs.existsSync(candidateTrans)) {
+      try {
+        const content = fs.readFileSync(candidateTrans, "utf-8");
+        const taskRegex = new RegExp(`Task id [^"]*${cleanId}[^"]* finished`, "i");
+        if (taskRegex.test(content)) {
+          return false; // completed!
+        }
+      } catch {}
+    }
+  }
+
+  // 3. File modification age check
+  if (logPath && fs.existsSync(logPath)) {
+    try {
+      const stats = fs.statSync(logPath);
+      const mtimeAgeMs = Date.now() - stats.mtimeMs;
+      if (mtimeAgeMs > 15000) {
+        return false; // Inactive for >15s -> terminated!
+      }
+      return true; // Modified within 15s and not marked finished -> RUNNING!
+    } catch {}
+  }
+
+  // 4. Test environment / naming convention
+  if (cleanId.includes("live") || cleanId.includes("running")) {
+    return true;
+  }
+
+  return false;
+}
+
+
 let resolvedRtkPath = null;
 function getRtkBinary() {
   if (resolvedRtkPath) return resolvedRtkPath;
@@ -290,7 +452,7 @@ function rewriteCommandWithRtk(rawCmd) {
     return trimmed;
   }
 
-  // Fast-path bypass for shell builtins, non-rewritable binaries, and powershell cmdlets
+    // 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) ||
@@ -389,17 +551,6 @@ try {
       });
     }
 
-    // LH-02-B: Direct shell access to internal Antigravity execution state (.system_generated)
-    if (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."
-      });
-    }
-
     // LH-09-B: Shell command mutation of protected benchmark artifacts
     if (
       (rawCmd.includes(">") || /\b(?:rm|del|Remove-Item)\b/i.test(rawCmd)) &&
@@ -413,6 +564,72 @@ try {
     }
 
     const rewritten = rewriteCommandWithRtk(rawCmd);
+    const effectiveCmd = rewritten;
+
+    // Check 1: Step Output Spillover Safe Harbor (0 New Tools)
+    if (isStepSpilloverPath(rawCmd) || isStepSpilloverPath(effectiveCmd)) {
+      if (/^rtk(?:\.exe)?\s+read\b/i.test(effectiveCmd)) {
+        // Safe harbor: rtk read already provides line clamping and token windowing
+      } else {
+        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."
+        });
+      }
+    } else {
+      // Check 2: Task Log Inspection (Lifecycle-Gated, 0 New Tools)
+      const taskLogId = getTaskLogMatch(rawCmd) || getTaskLogMatch(effectiveCmd);
+      if (taskLogId) {
+        if (isTaskRunning(taskLogId, convId, rawCmd)) {
+          // Task actively running: Deny with Proportional Backoff
+          const session = getSessionState(convId);
+          session.denials++;
+          saveSessionState(convId, session);
+
+          if (session.denials >= 5) {
+            respond({
+              decision: "force_ask",
+              reason: `[CIRCUIT BREAKER ACTIVATED] Autonomous loop suspended: reading task log '${taskLogId}' attempted prematurely ${session.denials} times during active backoff window. Stop calling tools and yield the turn for native Reactive Wakeup (<SYSTEM_MESSAGE>). User confirmation required to proceed.`
+            });
+          }
+
+          const requiredBackoffSec = Math.max(30, getRequiredBackoffSeconds(session.pollCount));
+          const requiredBackoffMs = requiredBackoffSec * 1000;
+          const elapsedMs = session.lastPollTime ? (Date.now() - session.lastPollTime) : Infinity;
+          const elapsedSec = Math.floor(elapsedMs / 1000);
+          const remainingSec = Math.max(1, Math.ceil((requiredBackoffMs - elapsedMs) / 1000));
+
+          respond({
+            decision: "deny",
+            reason: `Antigravity Execution Governance: Task '${taskLogId}' is actively RUNNING. Reading task logs in .system_generated during execution is strictly prohibited to prevent polling loops. Diagnostic check #${session.pollCount + 1} requires at least ${requiredBackoffSec}s elapsed (${elapsedSec}s elapsed, ${remainingSec}s remaining). Tasks execute asynchronously and notify you automatically via native Reactive Wakeup (<SYSTEM_MESSAGE>) upon completion. Stop calling tools and yield your turn now.`
+          });
+        }
+
+        // Task is TERMINATED / COMPLETED: allow rtk read
+        if (/^rtk(?:\.exe)?\s+read\b/i.test(effectiveCmd)) {
+          // Allowed under lifecycle governance
+        } else {
+          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` +
+              "- If actively running, yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>)."
+          });
+        }
+      } else if (isProtectedInternalState(rawCmd) || isProtectedInternalState(effectiveCmd)) {
+        // Check 3: Other protected internal state (transcripts, scheduler, progress)
+        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."
+        });
+      }
+    }
+
     const isDaemon = args.IsDaemon === true || args.isDaemon === true;
     const waitMs = args.WaitMsBeforeAsync !== undefined ? args.WaitMsBeforeAsync : args.waitMsBeforeAsync;
     const targetMaxWait = Number(process.env.AGY_MAX_WAIT_MS) || 10000;
@@ -456,7 +673,58 @@ try {
       "";
     const target = String(rawTarget).trim();
 
-    // 2a. Internal State Protection by Root (LH-02)
+    // 2a. Step Output Spillover Safe Harbor (hard-route to rtk read)
+    if (isStepSpilloverPath(target)) {
+      respond({
+        decision: "deny",
+        reason: `Antigravity Governance: Native file inspection via '${toolName}' bypasses token optimization. Run 'rtk read ${target}' via run_command instead.`
+      });
+    }
+
+    // 2b. Task Log Inspection (Lifecycle-Gated)
+    const taskLogId = getTaskLogMatch(target);
+    if (taskLogId) {
+      if (isTaskRunning(taskLogId, convId, target)) {
+        const session = getSessionState(convId);
+        session.denials++;
+        saveSessionState(convId, session);
+
+        if (session.denials >= 5) {
+          respond({
+            decision: "force_ask",
+            reason: `[CIRCUIT BREAKER ACTIVATED] Autonomous loop suspended: reading task log '${taskLogId}' attempted prematurely ${session.denials} times during active backoff window. Stop calling tools and yield the turn for native Reactive Wakeup (<SYSTEM_MESSAGE>). User confirmation required to proceed.`
+          });
+        }
+
+        const requiredBackoffSec = Math.max(30, getRequiredBackoffSeconds(session.pollCount));
+        const requiredBackoffMs = requiredBackoffSec * 1000;
+        const elapsedMs = session.lastPollTime ? (Date.now() - session.lastPollTime) : Infinity;
+        const elapsedSec = Math.floor(elapsedMs / 1000);
+        const remainingSec = Math.max(1, Math.ceil((requiredBackoffMs - elapsedMs) / 1000));
+
+        respond({
+          decision: "deny",
+          reason: `Antigravity Execution Governance: Task '${taskLogId}' is actively RUNNING. Reading task logs in .system_generated during execution is strictly prohibited to prevent polling loops. Diagnostic check #${session.pollCount + 1} requires at least ${requiredBackoffSec}s elapsed (${elapsedSec}s elapsed, ${remainingSec}s remaining). Tasks execute asynchronously and notify you automatically via native Reactive Wakeup (<SYSTEM_MESSAGE>) upon completion. Stop calling tools and yield your turn now.`
+        });
+      }
+
+      if (isTaskCompleted(taskLogId, convId, target)) {
+        // 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."
+      });
+    }
+
+    // 2c. Other Internal State Protection by Root (LH-02)
     if (isProtectedInternalState(target) || isProtectedInternalState(JSON.stringify(args))) {
       respond({
         decision: "deny",
@@ -467,7 +735,7 @@ try {
       });
     }
 
-    // 2b. Allow Antigravity Special Files (SKILL.md, brain artifacts, configs)
+    // 2d. Allow Antigravity Special Files (SKILL.md, brain artifacts, configs)
     if (isAntigravitySpecialFile(target)) {
       respond({ decision: "allow" });
     }

package/scripts/install-register.mjs

@@ -280,13 +280,21 @@ export async function runInstall(options = {}) {
   // 5. Mirror Antigravity Tool Schemas in parallel
   await fsPromises.mkdir(antigravityMcpDir, { recursive: true });
 
-  // Clean up legacy safe_command schema if present
-  const legacySafeCommandPath = path.join(antigravityMcpDir, "safe_command.json");
-  if (fs.existsSync(legacySafeCommandPath)) {
-    try {
-      await fsPromises.unlink(legacySafeCommandPath);
-      log(`[OK] Cleaned up legacy safe_command schema from: ${legacySafeCommandPath}`);
-    } catch {}
+  // Clean up retired schemas if present
+  const retiredSchemas = [
+    "safe_command.json",
+    "get_spillover_content.json",
+    "read_task_output.json",
+    "get_step_detail.json"
+  ];
+  for (const s of retiredSchemas) {
+    const sPath = path.join(antigravityMcpDir, s);
+    if (fs.existsSync(sPath)) {
+      try {
+        await fsPromises.unlink(sPath);
+        log(`[OK] Cleaned up retired schema from: ${sPath}`);
+      } catch {}
+    }
   }
 
   const instructionsContent = `# Agy-Context-Saver MCP Server Instructions
@@ -302,15 +310,17 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
 2. **Never Read Internal State Directly**:
    - Access to \`.system_generated/\` via \`view_file\` is strictly denied to prevent transcript explosion.
    - Use \`read_transcript\` or \`query_transcript\` to inspect conversation history cleanly.
-3. **Platform-Aware Codebase Inspection**:
+3. **Inspect Output Files Directly with RTK**:
+   - Runtime step output spillovers (\`.system_generated/steps/<step>/output.txt\`) and completed background task logs (\`tasks/<taskId>.log\`) are read directly via \`rtk read <path>\` under hook governance.
+4. **Platform-Aware Codebase Inspection**:
    - **Windows**: Use \`rtk read <file>\`, \`rtk find <path>\`, and \`rtk rg "<pattern>" .\` (the trailing \`.\` is required to avoid stdin stalls).
    - **POSIX**: Use \`rtk read <file>\`, \`rtk ls <path>\`, and \`rtk grep "<pattern>"\` or \`rtk rg "<pattern>"\`.
 
 ## Available MCP Tools
 - \`check_context_health\`: Diagnoses transcript turn counts, byte payload, and polling loops. Accepts \`transcriptPath\` or \`conversationId\`.
-- \`subagent_brief\`: Generates scope-isolated instructions for delegated subagents to prevent parent context bloat.
+- \`subagent_brief\`: Generates scope-isolated instructions for delegated subagents with Pointer-Over-Wire delivery contract.
 - \`read_transcript\`: Streams recent turns from \`transcript.jsonl\` or \`transcript_full.jsonl\` formatted as clean Markdown.
-- \`query_transcript\`: Forensic regex search and filtering engine across transcript steps with optional \`summaryOnly: true\`.
+- \`query_transcript\`: Forensic regex search and filtering engine across transcript steps with optional \`summaryOnly: true\`, and surgical step extraction via \`stepIndex\` and \`field\`.
 - \`get_installation_status\`: Audits live health of the plugin link, hook, MCP server, tool schemas, and RTK.
 - \`sync_installation\`: Synchronizes and repairs all 4 integration layers in ~25ms.
 
@@ -457,6 +467,14 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
         summaryOnly: {
           type: "boolean",
           description: "If true, returns high-density 1-line step summaries instead of full message blocks to minimize UI card height (default: false)."
+        },
+        stepIndex: {
+          type: "number",
+          description: "Optional step_index to surgically retrieve full un-truncated content for a single step from transcript_full.jsonl."
+        },
+        field: {
+          type: "string",
+          description: "Optional specific field to extract when stepIndex is provided (e.g. 'content', 'thinking', 'tool_calls', 'tool_args', or 'tool_args:Message'). Defaults to full step."
         }
       },
       required: ["conversationId"]