agy-context-saver 1.6.1 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.7.0] - 2026-10-13
+
+### Added
+- **Subagent Artifact Directory Write Guard (`subagent_brief`)**: Added automated path analysis in `formatSingleBrief` that detects when an objective or instruction references a foreign `brain/<uuid>/` directory. Warns subagents proactively to prevent Antigravity's fatal `write_to_file` error ("files must reside within the designated artifact directory").
+- **Pointer-Over-Wire (POW) File Delivery Clarification**: Codified explicit two-option guidance for subagent deliverables:
+  - *Option A (Workspace `scratch/` — Recommended)*: Write to `<workspace>/scratch/<task>_findings.md` and omit `ArtifactMetadata`.
+  - *Option B (Own Brain `scratch/`)*: Write to `<your-Artifact-Directory-Path>/scratch/...` using the subagent's own `<user_information>` block and include `ArtifactMetadata: { Summary, UserFacing: false, RequestFeedback: false }`.
+- **Bounded Slice Reading Safe Harbor (`view_file`)**: Prioritized `view_file` with bounded slices (`StartLine` and `EndLine`, max 150 lines) over `rtk read` across `rules/AGENTS.md`, `skills/context-governance/SKILL.md`, and `mcp/instructions.md` to preserve exact 1-indexed line numbers without stdout buffer truncation.
+- **Subagent Delegation Trial 4 (`tests/test-subagent-trials.mjs`)**: Added automated trial verifying `subagent_brief` emits the artifact directory write guard, bounded slice guidance, and Option A/Option B file delivery rules.
+
+---
+
 ## [1.6.1] - 2026-10-12
 
 ### Added
@@ -162,6 +174,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Antigravity Model Context Protocol (MCP) server.
 - Background task lifecycle governance and reactive wakeup enforcement.
 
+[1.7.0]: https://github.com/paragon-ux/agy-context-saver/compare/v1.6.1...v1.7.0
 [1.6.1]: https://github.com/paragon-ux/agy-context-saver/compare/v1.6.0...v1.6.1
 [1.6.0]: https://github.com/paragon-ux/agy-context-saver/compare/v1.5.1...v1.6.0
 [1.5.1]: https://github.com/paragon-ux/agy-context-saver/compare/v1.5.0...v1.5.1

package/mcp/index.js

@@ -72,7 +72,7 @@ if (checkFlag) {
 
 function printHelp() {
   console.log(`
-Agy-Context-Saver 🛡️ (v1.6.1)
+Agy-Context-Saver 🛡️ (v1.7.0)
 Universal MCP Server & Lifecycle Governor for Google Antigravity (Powered by RTK)
 
 Usage:
@@ -119,7 +119,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.6.1";
+const SERVER_VERSION = "1.7.0";
 
 // --- Tools Specification ---
 const TOOLS = [
@@ -472,14 +472,20 @@ function formatSingleBrief({
 } = {}) {
   const scopeStr = scopeFiles && scopeFiles.length ? `\n\nTarget files:\n${scopeFiles.map(f => `- ${f}`).join("\n")}` : "";
   const instrStr = instructions && instructions.trim() ? `\n\nSPECIFIC INSTRUCTIONS:\n${instructions.trim()}` : "";
+  const hasBrainUuidPath = /[/\\]\.gemini[/\\]antigravity[/\\]brain[/\\][0-9a-f-]{36}/i.test(`${objective}\n${instructions}\n${expectedDeliverable}`);
+  const brainPathWarning = hasBrainUuidPath
+    ? `\n\n⚠️ ARTIFACT DIRECTORY WRITE GUARD: Any 'brain/<uuid>/' path referenced above belongs to another conversation. You may READ from it via 'view_file', but when calling 'write_to_file' or 'replace_file_content', you MUST either write to workspace '<workspace>/scratch/...' (OMIT ArtifactMetadata) or substitute YOUR OWN Artifact Directory Path from <user_information> (INCLUDE ArtifactMetadata).`
+    : "";
   return [
     `ROLE: ${role}`,
-    `OBJECTIVE: ${objective}${scopeStr}${instrStr}`,
+    `OBJECTIVE: ${objective}${scopeStr}${instrStr}${brainPathWarning}`,
     ``,
     `CRITICAL CONTEXT GOVERNANCE INSTRUCTIONS (POINTER-OVER-WIRE):`,
-    `1. Isolated Workspace: Do all necessary multi-file exploration, searches, and analysis in this subagent sandbox.`,
+    `1. Isolated Workspace & Bounded File Slices: Do all multi-file exploration in this subagent sandbox. Prefer 'view_file' with bounded slices (StartLine and EndLine, max 150 lines) over 'rtk read' so line numbers are preserved and terminal buffers never truncate file headers.`,
     `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).`,
+    `   a. Write the full comprehensive deliverable using 'write_to_file' following Antigravity's strict path rules:`,
+    `      - Option A (Workspace 'scratch/' — Recommended): Set TargetFile to '<workspace>/scratch/<task>_findings.md' and OMIT ArtifactMetadata completely (passing ArtifactMetadata on a workspace path throws "files must be written to the correct artifact directory").`,
+    `      - Option B (Your Own Brain 'scratch/'): Set TargetFile to '<your-Artifact-Directory-Path>/scratch/<task>_findings.md' using the exact Artifact Directory Path from YOUR <user_information> block (NEVER a parent's brain/<other-uuid>/ path) and INCLUDE ArtifactMetadata: { Summary: "...", UserFacing: false, RequestFeedback: false }.`,
     `   b. In 'send_message', transmit ONLY:`,
     `      - Executive Summary (3-5 high-signal sentences)`,
     `      - Verdict / Scoreboard Table`,

package/mcp/instructions.md

@@ -12,8 +12,9 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
    - 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**:
-   - **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>"`.
+   - **File Reading**: Prefer `view_file` with bounded slices (`StartLine` and `EndLine`, max 150 lines) to preserve line numbers and avoid terminal truncation.
+   - **Windows Search/Listing**: Use `rtk find <path>` and `rtk rg "<pattern>" .` (the trailing `.` is required to avoid stdin stalls).
+   - **POSIX Search/Listing**: Use `rtk ls <path>` and `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
 
 ## Available MCP Tools
 - `check_context_health`: Diagnoses transcript turn counts, byte payload, and polling loops. Accepts `transcriptPath` or `conversationId`.

package/package.json

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

package/plugin.json

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

package/rules/AGENTS.md

@@ -32,8 +32,8 @@
 
 ## Layer 2: Transparent Shell Execution & Codebase Inspection via RTK
 - **Native Shell Commands**: Run shell commands normally using `run_command`. The PreToolUse hook transparently rewrites supported commands via RTK (`git`, `pytest`, `cargo`, `npm`, etc.) to produce ultra-compact outputs.
-- **Canonical Codebase Inspection**: Native file and search inspection tools (`view_file`, `grep_search`, `find_by_name`, `list_dir`) that bypass RTK are blocked for workspace files. Use RTK's canonical CLI interfaces via `run_command`:
-  - `rtk read <file>`: Read file with intelligent token filtering and line ranges.
+- **Canonical Codebase Inspection**: Unbounded full-file reads and unoptimized search tools (`grep_search`, `find_by_name`, `list_dir`) are blocked for workspace files. Use bounded slices and RTK's canonical CLI interfaces:
+  - `view_file` with bounded slices (`StartLine` and `EndLine`, max 150 lines): **Preferred for reading files**—preserves 1-indexed line numbers and avoids terminal stdout truncation. Pair with `waymark_ask` to locate exact symbol line ranges first.
   - `rtk find <path>`: Compact file search tree and directory listings (cross-platform, works on Windows & POSIX).
   - Search commands by platform:
     - **Windows**: Use `rtk rg "<pattern>" .` (explicit target `.` is required to prevent stdin pipe hanging) or `rg "<pattern>" .`.
@@ -43,7 +43,7 @@
     - **POSIX / Linux / macOS**: Use `rtk ls <path>` or `rtk tree`.
   - `rtk err <cmd>`: Run command and show only errors/warnings.
   - `rtk summary <cmd>`: Run command and produce a 2-line heuristic summary.
-- **Antigravity Special Files Safe Harbor**: Documented Antigravity special files (`SKILL.md`, brain artifacts, `.gemini/config/` configs) are permitted via `view_file`.
+- **Antigravity Special Files Safe Harbor**: Documented Antigravity special files (`SKILL.md`, brain artifacts, `.gemini/config/` configs) are permitted via `view_file` without slice bounds.
 - **Protected Internal State**: Direct native inspection of `.system_generated/` (transcripts, task logs, progress files) is strictly forbidden. Use Agy MCP tools `read_transcript` and `query_transcript`.
 
 ---
@@ -57,7 +57,7 @@
   - **Subagent Delegation for Deep Audits**: When a comprehensive repository-wide test audit is required, delegate the sweep to a subagent (`invoke_subagent`) to keep the main thread responsive.
 - **Subagent Delegation & Pointer-Over-Wire (POW)**:
   - Delegate heavy multi-file exploration, deep research, and repo sweeps to subagents (`invoke_subagent`). Subagents absorb intermediate steps and return high-signal summaries.
-  - **POW Protocol**: Payloads or deliverables exceeding 1 KB must be written to workspace scratch files (e.g. `scratch/<task>_findings.md` or artifacts). Transmit **ONLY** an Executive Summary (3–5 sentences), a Scoreboard / Verdict table, and a clickable file link (`file:///...`) in `send_message` to prevent transport truncation and parent context bloat.
+  - **POW Protocol & `write_to_file` Isolation**: Payloads or deliverables exceeding 1 KB must be written either to workspace scratch files (`<workspace>/scratch/<task>_findings.md` with `ArtifactMetadata` **omitted**) or to the **subagent's own** `<Artifact Directory Path>/scratch/<task>_findings.md` (with `ArtifactMetadata: { Summary, UserFacing: false, RequestFeedback: false }`). Never instruct a subagent to `write_to_file` into the parent conversation's `brain/<parent-uuid>/` directory, as Antigravity enforces per-conversation `brain/<uuid>` write isolation. Transmit **ONLY** an Executive Summary (3–5 sentences), a Scoreboard / Verdict table, and a clickable file link (`file:///...`) in `send_message` to prevent transport truncation and parent context bloat.
 - **Benchmark / Evaluator Integrity**: Never mutate benchmark definitions, prompt templates, or scoring artifacts during an active evaluation without explicit user confirmation.
 
 ---

package/skills/context-governance/SKILL.md

@@ -18,9 +18,9 @@ Agy-Context-Saver and RTK protect session transcript health and LLM attention by
 
 ## Codebase Inspection via RTK
 
-Native Antigravity file and search tools (`view_file`, `grep_search`, `find_by_name`, `list_dir`) bypass token compression and are hard-routed to RTK shell commands:
+Unbounded full-file `view_file` calls and unoptimized search tools (`grep_search`, `find_by_name`, `list_dir`) bypass token compression and are guarded:
 
-- `rtk read <file>`: Reads file with intelligent token filtering and line ranges.
+- `view_file` with bounded slices (`StartLine` and `EndLine`, max 150 lines): **Preferred for reading files**—returns exact 1-indexed line numbers without terminal stdout truncation.
 - `rtk find <path>`: Compact file search tree and directory listings (cross-platform, works on Windows & POSIX).
 - Search commands by platform:
   - **Windows**: Use `rtk rg "<pattern>" .` (explicit target `.` is required to avoid child process stdin pipe stalls) or `rg "<pattern>" .`.
@@ -31,7 +31,7 @@ Native Antigravity file and search tools (`view_file`, `grep_search`, `find_by_n
 - `rtk err <cmd>`: Runs command and displays only errors/warnings.
 - `rtk summary <cmd>`: Runs command and produces a 2-line technical summary.
 
-*Safe Harbor*: Documented Antigravity special files (`SKILL.md`, brain artifacts, `.gemini/config/`) may be viewed directly via `view_file`.
+*Safe Harbor*: Documented Antigravity special files (`SKILL.md`, brain artifacts, `.gemini/config/`) may be viewed directly via `view_file` without slice bounds.
 
 ---