mirror-mind 0.34.0 → 0.36.0

package/ts/src/guards/claudePlugin.ts

@@ -178,6 +178,88 @@ export function marketplaceJson(): string {
   return `${JSON.stringify(buildMarketplace(), null, 2)}\n`;
 }
 
+// --- the agy-native layer (CV21.DS7.US1) -------------------------------------
+//
+// Antigravity treats a directory as a NATIVE plugin only when a root
+// `plugin.json` marks it (or `.antigravity-plugin/`/`.gemini-plugin/`).
+// Without the marker, `agy plugin install` converts the Claude surfaces as an
+// extension and OVERWRITES a shipped root `hooks.json` with Claude's — the
+// probe on agy 1.4.2 showed both behaviors (evidence in the US1 story
+// package). With the marker, validation passes, our root `hooks.json`
+// survives staging, `mcpServers: 1 processed`, and the 25 skills ride along.
+//
+// The layer is four generated files at agy's documented paths: the marker,
+// the hooks skeleton (TS2 adds injection, TS3 adds logging), the MCP map
+// (DERIVED from the manifest's entry — one locator, every carrier), and
+// `rules/AGENTS.md` (agy merges `rules/` into the active rule set; the guard
+// comparing committed to generated bytes is the sync with `AGENTS.md`).
+//
+// The marker is also what GROK reads (CV21.DS10.US1). Grok accepts a root
+// `plugin.json` and the `.claude-plugin/` equivalent, and takes the root one
+// first and alone: with a name-only marker, `grok plugin validate` dropped
+// "MCP servers" from the components it had listed on 1.0.52, `plugin list`
+// reported `version: null`, and no shape of install offered the MCP server
+// (probe on grok 1.0.62, 2026-10-18, story package). So the marker carries
+// the manifest's `version` and `mcpServers`, from the same source; agy 1.4.2
+// warns `unknown field "mcpServers" is ignored` and stages the same tree.
+// Hooks stay out of it: agy reads the root `hooks.json` beside it.
+
+/** The native-plugin marker: agy's detection, and the manifest Grok reads. */
+export function buildAgyPluginMarker(version: string): Record<string, unknown> {
+  return {
+    name: PLUGIN_NAME,
+    description: PLUGIN_DESCRIPTION,
+    version,
+    mcpServers: {
+      [PLUGIN_NAME]: { command: MCP_ENTRY.command, args: [...MCP_ENTRY.args] },
+    },
+  };
+}
+
+export function agyPluginMarkerJson(version: string): string {
+  return `${JSON.stringify(buildAgyPluginMarker(version), null, 2)}\n`;
+}
+
+/**
+ * The named hook with its handlers (CV21.DS7.TS2). Commands are relative:
+ * agy sets a handler's cwd to the directory holding `hooks.json`, and the
+ * wrappers live beside it in `agy/` (generated agy-form; the pre-invocation
+ * wrapper gates on stdin before Node is ever resolved, because
+ * `PreInvocation` fires before every model call and blocks the agent loop).
+ * Timeouts are explicit and small: the fast path is shell-instant, the slow
+ * path is one `mirror load`, and a hang here freezes the agent — which a
+ * user reads as "Antigravity broke", not "Mirror hung". `Stop` is TS3's.
+ */
+export function buildAgyHooks(): Record<string, unknown> {
+  return {
+    [PLUGIN_NAME]: {
+      enabled: true,
+      SessionStart: [{ type: "command", command: "agy/session-start.sh", timeout: 60 }],
+      PreInvocation: [{ type: "command", command: "agy/pre-invocation.sh", timeout: 15 }],
+      // CV21.DS7.TS3: Stop fires at each turn's end (agy has no SessionEnd);
+      // the handler reads the transcript and logs the turn as antigravity.
+      Stop: [{ type: "command", command: "agy/stop.sh", timeout: 30 }],
+    },
+  };
+}
+
+export function agyHooksJson(): string {
+  return `${JSON.stringify(buildAgyHooks(), null, 2)}\n`;
+}
+
+/** agy's `mcp_config.json`: the same `mcpServers` map the manifest carries. */
+export function buildAgyMcpConfig(): Record<string, unknown> {
+  return {
+    mcpServers: {
+      [PLUGIN_NAME]: { command: MCP_ENTRY.command, args: [...MCP_ENTRY.args] },
+    },
+  };
+}
+
+export function agyMcpConfigJson(): string {
+  return `${JSON.stringify(buildAgyMcpConfig(), null, 2)}\n`;
+}
+
 /**
  * The skill markdown file, matching `skill.md` case-insensitively.
  *
@@ -269,6 +351,15 @@ export function planGeneratedFiles(repoRoot: string): GeneratedFile[] {
       content: manifestJson(version),
     },
     { relativePath: MARKETPLACE_PATH, content: marketplaceJson() },
+    // The agy-native layer (CV21.DS7.US1).
+    { relativePath: join(PLUGIN_DIR, "plugin.json"), content: agyPluginMarkerJson(version) },
+    { relativePath: join(PLUGIN_DIR, "hooks.json"), content: agyHooksJson() },
+    { relativePath: join(PLUGIN_DIR, "mcp_config.json"), content: agyMcpConfigJson() },
+    {
+      relativePath: join(PLUGIN_DIR, "rules", "AGENTS.md"),
+      content: readFileSync(join(repoRoot, "AGENTS.md"), "utf8"),
+      source: "AGENTS.md",
+    },
     ...claudeCopies.values(),
     ...[...pluginSkills].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, file]) => file),
   ];

package/ts/src/guards/packContents.ts

@@ -26,7 +26,6 @@ export const ALLOWED_PREFIXES: readonly string[] = [
   ".pi/extensions/",
   ".pi/skills/",
   ".claude/hooks/",
-  ".gemini/hooks/",
   "plugins/mirror-mind/",
 ];
 
@@ -56,8 +55,10 @@ export const REQUIRED_FILES: readonly string[] = [
   ".pi/extensions/mirror-logger.ts",
   ".pi/skills/mm-mirror/SKILL.md",
   ".claude/hooks/session-start.sh",
-  ".gemini/hooks/session-start.sh",
   "plugins/mirror-mind/hooks/hooks.json",
+  // CV21.DS7.US1: the agy-native layer's hooks file. A tarball cannot ship
+  // the skills without the layer Antigravity runs them beside.
+  "plugins/mirror-mind/hooks.json",
   ".agents/plugins/marketplace.json",
 ];
 

package/ts/src/guards/piSourcedSkills.ts

@@ -1,7 +1,7 @@
 // Skills with one body in every runtime (CR102).
 //
 // Most Mirror skills have two authored bodies. `.pi/skills/` serves Pi, and
-// through the `.agents/skills/` links Codex and Gemini CLI too. `.claude/skills/`
+// through the `.agents/skills/` links Codex too. `.claude/skills/`
 // serves Claude Code, and `claudePlugin.ts` copies it into the plugin. CR071
 // kept the two apart on purpose: Usage sections, example language, and in
 // `mm-soul` and `mm-mirror` whole lines that are true for one runtime only.

package/ts/src/guards/retiredSurfaces.ts

@@ -514,6 +514,37 @@ export const RETIRED: readonly RetiredSurface[] = [
     residueScope: ["ts/src/", "ts/scripts/"],
     exemptions: {},
   },
+  {
+    surfaceId: "gemini-cli",
+    story: "CV21.DS8.US1",
+    // The Gemini CLI integration: four generated wrappers under `.gemini/hooks`,
+    // the `gemini:*` hook family behind them, the two `mirror init` steps, and
+    // the Gemini smoke. Retired once DS7.US4 measured Antigravity at L4 on agy
+    // 1.4.2 -- a Gemini CLI user loses nothing by moving. `.gemini/` is an
+    // absent path and not merely an unallowed one because `mirror init` told
+    // users to write absolute paths into that directory into their
+    // `~/.gemini/settings.json`: a standing instruction to execute whatever a
+    // later release might ship there. This row is what keeps that from
+    // happening.
+    absentPaths: [".gemini/", "ts/src/hooks/gemini.ts", "scripts/smoke_gemini_cli.sh"],
+    // File and route names, never vocabulary: "gemini" is a living word (the
+    // extraction and consult models, Antigravity's own `~/.gemini/` home, the
+    // `gemini_cli` label on conversations already logged). The row landed in
+    // two steps: US1 carried the names only code and CI used, and
+    // CV21.DS8.US2 added the doc-facing ones when it cleared the runtime-facing
+    // docs, so no exemption was ever staged. Not `.gemini/settings.json` and
+    // not `~/.gemini`: that directory is Antigravity's home too, and the
+    // cutoff note names the file a Gemini CLI user edits.
+    forbiddenPatterns: [
+      "smoke_gemini_cli",
+      "geminiHooksSettings",
+      "hooks/gemini\\.ts",
+      "\\.gemini/hooks",
+      "gemini:(session-start|session-end|log-user|log-assistant)",
+      "gemini skills link",
+    ],
+    exemptions: {},
+  },
 ];
 
 export interface SurfaceProblem {

package/ts/src/hooks/agy.ts

@@ -0,0 +1,229 @@
+// Antigravity hook entries (CV21.DS7.TS2).
+//
+// agy runs the plugin's `hooks.json` handlers with camelCase protojson on
+// stdin and reads JSON from stdout (`injectSteps`; a `systemMessage` step
+// nests its text, an `ephemeralMessage` is a plain string). The contracts
+// are committed bytes in CV21.DS7.US1's `evidence/` (agy 1.4.2).
+//
+// Two handlers:
+//
+//   * `agy:session-start` — turn conversation logging on, the posture every
+//     runtime's session-start shares, and answer `{}`. The Operating
+//     Instructions are NOT delivered here: `rules/AGENTS.md` carries them
+//     (US1), unless TS2's live route shows otherwise — the measured
+//     fallback would add an `injectSteps` `systemMessage` in this handler.
+//
+//   * `agy:pre-invocation` — inject Mirror Mode context once per user turn.
+//     `PreInvocation` fires before EVERY model call (32 times over two
+//     turns, DS12.TS3 L2), with `invocationNum` resetting to 0 at each user
+//     turn; protojson omits zero-valued fields, so an ABSENT invocationNum
+//     is 0. The generated wrapper already gates on this before Node is
+//     spawned; the gate here is defense in depth. The injection is an
+//     `ephemeralMessage` — dropped after the turn — for two reasons: the
+//     adapter re-injects per turn, so a persistent step would accumulate;
+//     and the content is identity and memory, so ephemeral is the
+//     data-minimizing choice against agy's stored trajectory.
+//
+// agy payloads carry no prompt or reply text (L7): there is no `--query`,
+// and the explicit Mirror form reaches the model through the skill (L4),
+// never through these hooks. The quiet session — a `conversationId` no
+// runtime session binds (every session until TS3 lands), or one bound with
+// Mirror Mode off — answers `{}`: Mirror on agy is invisible until invoked.
+//
+// Payload fields stay inert: `conversationId` flows only through array
+// argv, never a shell, and failures recorded in hooks.log are facts, never
+// payload text.
+
+import { readAgyTurns } from "#conversation/agyTranscript.ts";
+import { isCommandTurn } from "#conversation/commandTurn.ts";
+import { logAssistantMessage, logUserMessage } from "#conversation/logger.ts";
+import { resolveDbPath } from "#frontDoor/dbPath.ts";
+import { openLiveWriteDatabase } from "#frontDoor/liveBackup.ts";
+import { decodeMetadata, getRuntimeSession, upsertRuntimeSession } from "#mirror/runtimeSession.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+import { readMirrorState } from "./mirrorState.ts";
+import { noteHookFailure, runFrontDoor, runFrontDoorQuietly } from "./runtime.ts";
+
+/** agy's empty answer, which every path that injects nothing must print. */
+const EMPTY = "{}\n";
+
+interface AgyPayload {
+  readonly conversationId: string;
+  readonly invocationNum: number;
+  readonly transcriptPath: string;
+}
+
+/** The key under which the Stop handler stores its high-water step_index. */
+const HIGH_WATER_KEY = "agy_last_step_index";
+
+/**
+ * Parse agy's camelCase protojson payload. Anything malformed reads as the
+ * empty payload: a hook never fails the turn over stdin it did not write.
+ */
+export function parseAgyPayload(stdin: string): AgyPayload {
+  try {
+    const raw: unknown = JSON.parse(stdin);
+    if (typeof raw !== "object" || raw === null) {
+      return { conversationId: "", invocationNum: 0, transcriptPath: "" };
+    }
+    const record = raw as Record<string, unknown>;
+    return {
+      conversationId: typeof record.conversationId === "string" ? record.conversationId : "",
+      // protojson omits zero-valued fields: absent IS 0.
+      invocationNum: typeof record.invocationNum === "number" ? record.invocationNum : 0,
+      transcriptPath: typeof record.transcriptPath === "string" ? record.transcriptPath : "",
+    };
+  } catch {
+    return { conversationId: "", invocationNum: 0, transcriptPath: "" };
+  }
+}
+
+/**
+ * `SessionStart`: logging on, activate Mirror Mode for the session, answer
+ * the contract.
+ *
+ * Mirror Mode activation (CV21.DS7.US4 scope change). agy's `PreInvocation`
+ * carries no prompt text (DS12.TS3 L7), so the injection hook cannot detect
+ * the Mirror form to self-activate, and the `/mirror-mind:mm:*` skill runs
+ * `mirror load` as an agent command that cannot bind the agy session id. So
+ * SessionStart — the one hook that carries the `conversationId` at the start
+ * of the session — sets `mirror_active`, and the per-turn `PreInvocation`
+ * injection (built in TS2, gated on that flag) fires from then on. This
+ * matches Gemini CLI's always-on per-turn injection, the runtime Antigravity
+ * replaces; a session that never ran SessionStart stays quiet, which the
+ * negative probe pins.
+ */
+export async function agySessionStart(stdin: string): Promise<number> {
+  await runFrontDoorQuietly("agy:session-start", ["conversation-logger", "session-start"]);
+
+  const conversationId = parseAgyPayload(stdin).conversationId;
+  if (conversationId) {
+    try {
+      const dbPath = resolveDbPath([], process.env);
+      const db = openLiveWriteDatabase(dbPath);
+      try {
+        upsertRuntimeSession(
+          db,
+          conversationId,
+          { interface: "antigravity", mirrorActive: true },
+          nowIso(),
+        );
+      } finally {
+        db.close();
+      }
+    } catch (error) {
+      noteHookFailure("agy:session-start", error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  process.stdout.write(EMPTY);
+  return 0;
+}
+
+/**
+ * `Stop`: fires at the end of each user turn (agy has no SessionEnd hook).
+ * Read the transcript, append the turns past the stored high-water
+ * `step_index` as `antigravity`, and leave the conversation open — session
+ * maintenance closes it as a stale orphan, the path Codex uses (Shape A).
+ *
+ * A re-fired Stop, or a grown transcript whose turns are all logged, adds
+ * nothing: the high-water mark is the idempotency key. A skill turn is
+ * skipped, the one-home rule. Any failure is recorded in hooks.log, never
+ * fails the turn, and the handler always answers agy's contract.
+ */
+export async function agyStop(stdin: string): Promise<number> {
+  const payload = parseAgyPayload(stdin);
+  if (!payload.conversationId || !payload.transcriptPath) {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  const turns = readAgyTurns(payload.transcriptPath);
+  if (turns.length === 0) {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  let dbPath: string;
+  try {
+    dbPath = resolveDbPath([], process.env);
+  } catch {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  try {
+    const db = openLiveWriteDatabase(dbPath);
+    try {
+      const sessionId = payload.conversationId;
+      const existing = getRuntimeSession(db, sessionId);
+      const stored = decodeMetadata(existing?.metadata ?? null);
+      const highWater =
+        typeof stored[HIGH_WATER_KEY] === "number" ? (stored[HIGH_WATER_KEY] as number) : -1;
+      const deps = { newId, nowIso };
+      const options = { interface: "antigravity" };
+
+      let newHighWater = highWater;
+      for (const turn of turns) {
+        if (turn.lastStepIndex <= highWater) continue;
+        if (!isCommandTurn(turn.userText)) {
+          logUserMessage(db, sessionId, turn.userText, options, deps);
+          logAssistantMessage(db, sessionId, turn.replyText, options, deps);
+        }
+        if (turn.lastStepIndex > newHighWater) newHighWater = turn.lastStepIndex;
+      }
+
+      if (newHighWater !== highWater) {
+        const current = getRuntimeSession(db, sessionId);
+        const metadata = decodeMetadata(current?.metadata ?? null);
+        metadata[HIGH_WATER_KEY] = newHighWater;
+        upsertRuntimeSession(db, sessionId, { metadata: JSON.stringify(metadata) }, nowIso());
+      }
+    } finally {
+      db.close();
+    }
+  } catch (error) {
+    noteHookFailure("agy:stop", error instanceof Error ? error.message : String(error));
+  }
+
+  process.stdout.write(EMPTY);
+  return 0;
+}
+
+/** `PreInvocation`: one ephemeral context step per user turn, when owed. */
+export async function agyPreInvocation(stdin: string): Promise<number> {
+  const payload = parseAgyPayload(stdin);
+
+  // Defense in depth behind the wrapper's shell gate: only the turn's first
+  // invocation injects; the other ~30 answer instantly.
+  if (payload.invocationNum !== 0 || !payload.conversationId) {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  let dbPath: string;
+  try {
+    dbPath = resolveDbPath([], process.env);
+  } catch {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  // The quiet session: unbound, or bound with Mirror Mode off.
+  const state = readMirrorState(dbPath, payload.conversationId);
+  if (!state.active) {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  const argv = ["mirror", "load", "--context-only", "--session-id", payload.conversationId];
+  if (state.persona) argv.push("--persona", state.persona);
+  if (state.journey) argv.push("--journey", state.journey);
+
+  const result = await runFrontDoor(argv);
+  const context = result.stdout.trim() ? result.stdout : "";
+  process.stdout.write(
+    context ? `${JSON.stringify({ injectSteps: [{ ephemeralMessage: context }] })}\n` : EMPTY,
+  );
+  return 0;
+}

package/ts/src/hooks/claude.ts

@@ -11,6 +11,7 @@
 // for every prompt and the logger decides), a missing session id still fails
 // loud, and every failure is still non-fatal to the user's turn.
 
+import { runtimeReadsPromptContext } from "#conversation/runtimePolicy.ts";
 import { resolveDbPath } from "#frontDoor/dbPath.ts";
 import { openLiveWriteDatabase } from "#frontDoor/liveBackup.ts";
 import { mirrorForm } from "#mirror/mirrorForm.ts";
@@ -124,6 +125,11 @@ export async function claudeSessionEnd(stdin: string): Promise<number> {
  */
 export async function claudeInject(stdin: string): Promise<number> {
   const payload = parseHookPayload(stdin);
+  // CR143: on a runtime that discards what this hook returns (Grok), neither
+  // case is worth its load — nor the state read below, nor the "injected"
+  // mark, which would say the model received what it did not. Detected the
+  // way the sibling hooks detect it, from the payload and the environment.
+  if (!runtimeReadsPromptContext(detectHookRuntime(payload.raw))) return 0;
   const sessionId = payload.sessionId;
 
   // Case 1: the explicit invocation.

package/ts/src/hooks/main.ts

@@ -4,7 +4,8 @@
 //
 // CV22.DS10.TS5 plateau 1, decision D4. Twelve shell scripts across four
 // runtimes each spawned the interpreter one to five times per event. They now
-// run one Node process and name which hook they are:
+// run one Node process and name which hook they are (the Gemini CLI family,
+// `gemini:*`, retired with CV21.DS8.US1; Antigravity is its successor):
 //
 //     node ts/src/hooks/main.ts claude:inject
 //
@@ -34,14 +35,10 @@
 // why this file must exit 0: the wrappers read any other exit as Node failing.
 
 import { pathToFileURL } from "node:url";
+import { exitQuietlyOnBrokenPipe } from "#runtime/brokenPipe.ts";
 import { loadConfiguration, silenceExperimentalWarnings } from "#runtime/config.ts";
+import { agyPreInvocation, agySessionStart, agyStop } from "./agy.ts";
 import { claudeHook } from "./claude.ts";
-import {
-  geminiLogAssistant,
-  geminiLogUser,
-  geminiSessionEnd,
-  geminiSessionStart,
-} from "./gemini.ts";
 import { readStdin } from "./payload.ts";
 import { noteHookFailure } from "./runtime.ts";
 
@@ -51,16 +48,16 @@ async function dispatch(name: string): Promise<number> {
   switch (runtime) {
     case "claude":
       return claudeHook(hook ?? "");
-    case "gemini":
+    case "agy":
+      // The Antigravity plugin's handlers (CV21.DS7.TS2), called through the
+      // generated agy-form wrappers in `plugins/mirror-mind/agy/`.
       switch (hook) {
-        case "log-user":
-          return geminiLogUser(readStdin());
-        case "log-assistant":
-          return geminiLogAssistant(readStdin());
-        case "session-end":
-          return geminiSessionEnd(readStdin());
         case "session-start":
-          return geminiSessionStart();
+          return agySessionStart(readStdin());
+        case "pre-invocation":
+          return agyPreInvocation(readStdin());
+        case "stop":
+          return agyStop(readStdin());
         default:
           break;
       }
@@ -81,8 +78,18 @@ async function dispatch(name: string): Promise<number> {
  */
 export async function runAsEntry(rawArgv = process.argv.slice(2)): Promise<number> {
   silenceExperimentalWarnings();
-  loadConfiguration({ entryPath: import.meta.filename });
   const name = rawArgv[0] ?? "";
+  // The try/catch below is the last line of defense, and it has one hole: a
+  // stream's `error` event is not a throw in that `await` chain. A runtime
+  // that gives up on a hook closes its pipe, and until CR148 the hook answered
+  // the next write with an unhandled EPIPE, a stack trace into the host's log,
+  // and exit 1 -- the one exit code this entry promises never to return. One
+  // line in `hooks.log`, then the quiet exit the contract requires.
+  exitQuietlyOnBrokenPipe((code) => {
+    noteHookFailure(name || "hooks", "stdout closed early");
+    process.exit(code);
+  });
+  loadConfiguration({ entryPath: import.meta.filename });
   try {
     return await dispatch(name);
   } catch (error) {

package/ts/src/hooks/payload.ts

@@ -1,8 +1,8 @@
 // Reading a runtime's hook payload from stdin.
 //
 // Replaces the Python hook module `extract_prompt` (25 lines) and the four
-// inline interpreter one-liners the Claude and Gemini hooks used to parse the
-// same JSON. None of them was a command, so none was in
+// inline interpreter one-liners the Claude and Gemini CLI hooks used to parse
+// the same JSON (the Gemini CLI hooks retired with CV21.DS8.US1). None of them was a command, so none was in
 // DS7's denominator of 29 -- which is why TS5's inventory had to find them by
 // reading the hooks rather than by counting commands.
 //
@@ -23,17 +23,11 @@ export interface HookPayload {
   readonly prompt: string;
   /** The runtime's session id (`session_id`, or Grok's `sessionId`), or "". */
   readonly sessionId: string;
-  /** The assistant's response text (Gemini's `prompt_response`), or "". */
-  readonly response: string;
-  /** Everything else, for hooks that need a field these three do not cover. */
+  /** Everything else, for hooks that need a field these two do not cover. */
   readonly raw: HookPayloadObject;
 }
 
-const EMPTY: HookPayload = { prompt: "", sessionId: "", response: "", raw: {} };
-
-function text(value: unknown): string {
-  return typeof value === "string" ? value : "";
-}
+const EMPTY: HookPayload = { prompt: "", sessionId: "", raw: {} };
 
 /**
  * Parse a hook payload. Never throws: an unparseable payload is empty.
@@ -47,11 +41,10 @@ export function parseHookPayload(input: string): HookPayload {
   return {
     prompt: promptOf(raw),
     sessionId: sessionIdOf(raw),
-    // Gemini's AfterAgent payload names it `prompt_response`, and that is the
-    // field the Python hook read. The first port read three guessed names
-    // instead and dropped every Gemini assistant turn in silence until
-    // `smoke_gemini_cli.sh` caught it (CV22.DS10.TS5 plateau 3).
-    response: text(raw.prompt_response),
+    // A `response` field read Gemini CLI's `prompt_response` here until
+    // CV21.DS8.US1; no living runtime hands the reply to a hook payload by
+    // name (Claude-family hooks read the transcript, agy's Stop reads its
+    // JSONL), so the field went with its only reader.
     raw,
   };
 }

package/ts/src/hooks/runtime.ts

@@ -61,11 +61,11 @@ export function noteHookFailure(hook: string, reason: string, env = process.env)
  * The Operating Instructions a SessionStart hook should hand its runtime, or
  * null when the project already carries this same file.
  *
- * CV22.DS10.US3, decision D13. An installed package reaches Claude Code and
- * Gemini CLI through hooks, skills, and an MCP server; none of those reads a
- * CLAUDE.md or GEMINI.md, so a session wired to the package would answer
- * `/mm-mirror` and still route no mode, sign no persona, and hold no Builder
- * boundary. Both runtimes read SessionStart's
+ * CV22.DS10.US3, decision D13. An installed package reaches Claude Code (and
+ * reached Gemini CLI, until CV21.DS8.US1) through hooks, skills, and an MCP
+ * server; none of those reads a CLAUDE.md, so a session wired to the package
+ * would answer `/mm-mirror` and still route no mode, sign no persona, and hold
+ * no Builder boundary. The runtime reads SessionStart's
  * `hookSpecificOutput.additionalContext`, so the session-start hook returns
  * `AGENTS.md` from the tree THIS code runs from -- the instructions always
  * match the core they ship with -- unless the project the session opened in
@@ -92,8 +92,9 @@ export function operatingInstructionsFor(
 }
 
 /**
- * The SessionStart answer both runtimes read: context as JSON, or `nothing`
- * -- what each runtime's hook printed before D13 (Gemini `{}`, Claude none).
+ * The SessionStart answer the runtime reads: context as JSON, or `nothing`
+ * -- what the runtime's hook printed before D13 (Claude none; Gemini CLI's
+ * `{}`, until CV21.DS8.US1 retired it).
  */
 export function sessionStartOutput(instructions: string | null, nothing = ""): string {
   if (instructions === null) return nothing;
@@ -148,9 +149,9 @@ export async function runFrontDoor(
 /**
  * The command a failure line may name: the family and its subcommand, never
  * the arguments. Arguments are where hooks put what the user said and what the
- * model answered -- the Gemini logger passes the prompt and the response as
- * argv -- and the first version of the failure line printed all of them (TS5
- * handoff review, finding P1).
+ * model answered -- the Gemini CLI logger, retired by CV21.DS8.US1, passed the
+ * prompt and the response as argv -- and the first version of the failure
+ * line printed all of them (TS5 handoff review, finding P1).
  */
 function commandName(argv: readonly string[]): string {
   return argv.slice(0, 2).join(" ");

package/ts/src/runtime/brokenPipe.ts

@@ -0,0 +1,52 @@
+// A closed stdout or stderr ends the command quietly (CR148).
+//
+// `mirror ext <id> | head -1` is a shell idiom, not an error: `head`, `tail`,
+// a pager that quit, a `grep -q` that matched -- every one of them closes its
+// read end on purpose. Node ignores SIGPIPE and surfaces the next write as an
+// `error` event on the stream, and with nobody listening that event is an
+// uncaught exception: `Unhandled 'error' event`, `Error: write EPIPE`, a
+// stack, exit 1. Nothing of ours failed; the reader asked us to stop.
+//
+// One listener at each entry (`frontDoor/cli.ts`, `hooks/main.ts`), nothing
+// per route. On EPIPE: exit 0 and write nothing. The exit status follows
+// `npm`, `cargo`, and `kubectl`, not git's 141: under `set -o pipefail`, 141
+// fails a pipeline the person wrote on purpose, and the fix they reach for is
+// `|| true`, which then hides the real failures too.
+//
+// Stop means stop. The exit happens at the next write after the reader
+// closes, and work the command had not done by then -- a commit after a
+// progress line, a log after an `await` -- is abandoned, exactly as SIGPIPE
+// abandons git's. That is the shell's contract, recorded in the CR.
+//
+// Anything that is not EPIPE is rethrown: a real stream failure keeps the
+// trace it had before. On Linux pipes are synchronous and on macOS
+// asynchronous; in both the failure arrives as this event, never as a throw
+// from `write()`. libuv maps ERROR_BROKEN_PIPE to EPIPE on Windows.
+
+type Exit = (code: number) => void;
+
+/**
+ * Install the handler. `exit` is `process.exit` for the CLI; the hook passes
+ * one that leaves a line in `hooks.log` first, because the hook's promise
+ * that every path returns 0 cannot be kept by its try/catch -- a stream's
+ * `error` event is not a throw in that `await` chain.
+ *
+ * Called once per process by `runAsEntry`; no guard against a second call,
+ * because there is no second call, and no test runs an entry in-process.
+ */
+export function exitQuietlyOnBrokenPipe(
+  exit: Exit,
+  streams: readonly NodeJS.WritableStream[] = [process.stdout, process.stderr],
+): void {
+  let exiting = false;
+  for (const stream of streams) {
+    stream.on("error", (error: NodeJS.ErrnoException) => {
+      if (error.code !== "EPIPE") throw error;
+      // Both streams on one pipe (`2>&1 | head`) fail together. A real
+      // `process.exit` never returns; an injected one must still count once.
+      if (exiting) return;
+      exiting = true;
+      exit(0);
+    });
+  }
+}