mirror-mind 0.34.0 → 0.35.0

package/.pi/skills/mm-build/SKILL.md

@@ -10,7 +10,7 @@ Activates Builder Mode for a specific journey. Loads identity context and projec
 
 ## Usage
 
-Pi and Gemini CLI:
+Pi:
 
 ```
 /mm-build <journey-slug>

package/.pi/skills/mm-explore/SKILL.md

@@ -14,7 +14,7 @@ attractors, experiment proposals, and Builder handoff.
 
 ## Usage
 
-Pi and Gemini CLI:
+Pi:
 
 ```text
 /mm-explore <journey-slug>

package/.pi/skills/mm-help/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: "mm-help"
-description: Shows available Mirror Mind commands on Pi and Gemini CLI
+description: Shows available Mirror Mind commands on Pi
 user-invocable: true
 ---
 
 # Help
 
-Show the user the available commands (same on Pi and Gemini CLI):
+Show the user the available commands:
 
 ## Operating Modes
 

package/.pi/skills/mm-soul/SKILL.md

@@ -13,7 +13,7 @@ surface and the question: "how is your day going today?"
 
 ## Usage
 
-Pi and Gemini CLI:
+Pi:
 
 ```text
 /mm-soul [journey-slug]

package/AGENTS.md

@@ -1,9 +1,10 @@
 # Mirror Mind — Operating Instructions
 
 <!-- This file ships in the mirror-mind package and is read by every runtime:
-     Pi and Codex read it from the project root natively, Claude Code and
-     Gemini CLI through the @AGENTS.md import in CLAUDE.md, and an installed
-     package's Pi session receives it from the extension (CV22.DS10.US3, D13).
+     Pi and Codex read it from the project root natively, Claude Code through
+     the @AGENTS.md import in CLAUDE.md, Antigravity as the plugin's rules, and
+     an installed package's Pi session receives it from the extension
+     (CV22.DS10.US3, D13).
      It holds nothing about this repository; that is CLAUDE.md's part. -->
 
 ---
@@ -17,9 +18,9 @@ Applies to all sessions, regardless of project.
 The mirror operates in four modes, chosen automatically based on context:
 Mirror, Builder, Explorer, and Soul.
 
-Each skill below is named three ways: `/mm-<skill>` in Pi and Gemini CLI,
-`$mm-<skill>` in Codex, `/mm:<skill>` in Claude Code. A **plugin** install
-prefixes the plugin's name — `/mirror-mind:mm:<skill>` in Claude Code's menu,
+Each skill below is named three ways: `/mm-<skill>` in Pi, `$mm-<skill>` in
+Codex, `/mm:<skill>` in Claude Code. A **plugin** install prefixes the plugin's
+name — `/mirror-mind:mm:<skill>` in Claude Code's menu and in Antigravity,
 `$mirror-mind:mm:<skill>` in Codex, `mirror-mind:mm-<skill>` as the skill's own
 name — and the forms below refer to the same skill.
 

package/README.md

@@ -60,8 +60,8 @@ This is not a chatbot with memory. This is a mirror — and yours.
 
 ## How It Works
 
-Local-first. SQLite. Four supported runtimes: Pi, Gemini CLI, Codex, Claude
-Code. One TypeScript core, run by Node.js. Jungian architecture: Self, Ego,
+Local-first. SQLite. Four supported runtimes: Pi, Claude Code, Codex,
+Antigravity. One TypeScript core, run by Node.js. Jungian architecture: Self, Ego,
 Personas, Shadow.
 Context-activated modes — Mirror, Builder, Explorer, and Soul. The identity lives
 in your machine, not a server.
@@ -79,9 +79,8 @@ in your machine, not a server.
 - [OpenRouter](https://openrouter.ai) account with at least $5 in credits —
   embeddings, memory extraction, and multi-LLM
 - An AI runtime subscription:
-  [Codex Plus](https://openai.com/codex/) (recommended),
-  [Claude Code Pro](https://code.claude.com/docs), or
-  [Gemini AI Pro](https://geminicli.com/)
+  [Codex Plus](https://openai.com/codex/) (recommended) or
+  [Claude Code Pro](https://code.claude.com/docs)
 - [Pi](https://github.com/earendil-works/pi/tree/main/packages/coding-agent)
   — recommended harness (multi-model, not locked to one provider)
 
@@ -111,7 +110,7 @@ this repository, turning a personal experiment into a reusable framework:
 
 - **English** — full migration from Portuguese across code, CLI, schema, identity, and docs
 - **Framework/user separation** — user identity and memory live privately under `~/.mirror/<user>/`, outside the repository
-- **Multi-runtime** — from Claude Code only to four runtimes: Pi, Gemini CLI, Codex, and Claude Code
+- **Multi-runtime** — from Claude Code only to Pi, Claude Code, Codex, and Antigravity
 - **Multi-user** — independent mirrors for multiple users on the same machine
 - **Multi-session** — concurrent sessions tracked safely in a database-backed session registry
 - **Intelligence depth** — hybrid semantic and lexical search, honest reinforcement, two-pass extraction, memory consolidation, and shadow cultivation

package/docs/releases/index.md

@@ -12,6 +12,7 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [v0.35.0 — Four Runtimes, One Successor](v0.35.0.md) — minor release closing CV21.DS8: the Gemini CLI integration no longer ships and Antigravity stands in its place, the gate met by DS7's live L4 on agy 1.4.2. Four runtimes — Pi, Claude Code, Codex, Antigravity — named everywhere; the cutoff recorded in full, with the four hook entries a Gemini CLI user deletes and v0.34.0 as the last release that carries the integration; a retired-surface guard keeps it removed. No migration.
 - [v0.34.0 — Codex Through the Canonical Plugin](v0.34.0.md) — minor release closing CV21.DS4: Codex runs Mirror through the canonical plugin, installed in two commands from a marketplace the package ships, measured live at L4 on Codex 0.163.0. The v0.32.1 wrapper wiring no longer ships; `runtime diagnose` and `runtime update` say when Codex's cached plugin copy is behind and name the re-add that brings it level. No migration.
 - [v0.33.4 — A Name Is a Key](v0.33.4.md) — patch release of three first-run corrections: two from a contributor's PR #43 and CR141, which its review opened. `init --help` created a home named `--help`, `init ../escaped` created one outside `.mirror-minds`, and `init "My User"` put a space into `MIRROR_USER`; a user name is now a kebab-case key like a journey slug or a persona id, refused otherwise with a name that would work and nothing created. `identity edit` on Windows opens Notepad when no editor is named. Existing homes untouched. No migration.
 - [v0.33.3 — Mirror Finds Itself Under Any Path](v0.33.3.md) — patch release of one Change Request, CR140, carried by a contributor's PR #42: Mirror read its own install path from `URL.pathname`, so a checkout or package under a path with a space or a non-ASCII character read as `Install: unknown`, the welcome card showed no update, and `runtime update` refused. The path is now a filesystem path, a guard keeps the idiom out, and an `unknown` install names the path it looked up from. On Windows, npm's global layout is recognized and npm runs with no shell, verified on Windows in CI for the two files they touch; there is still no Windows product. Affected installs update once by hand. No migration.

package/docs/releases/v0.35.0.md

@@ -0,0 +1,199 @@
+---
+digest: >
+  v0.35.0 is a minor release closing CV21.DS8: the Gemini CLI integration no
+  longer ships, and Antigravity stands in its place. Mirror Mind supports four
+  runtimes — Pi, Claude Code, Codex, Antigravity — and every document says so.
+  The removal waited for its gate: DS7 measured Antigravity at L4 on agy 1.4.2,
+  all five bar items, so a Gemini CLI user who moves loses nothing and gains
+  MCP. The cutoff is recorded here in full — what no longer exists, why, what
+  to do instead, what still works, and what a user who does nothing will see —
+  with the four hook entries to delete named, and v0.34.0 named as the last
+  release that carries the integration. A retired-surface guard keeps the
+  removal removed. No migration: homes, memories, journeys, and the
+  conversations logged as gemini_cli are untouched.
+---
+
+# v0.35.0 — Four Runtimes, One Successor
+
+**Date:** 2026-10-18
+
+## Highlights
+
+- **Gemini CLI is no longer a Mirror runtime; Antigravity is its successor**
+  ([decision](../project/decisions.md#gemini-cli-is-retired-and-antigravity-is-its-successor)).
+  The four `.gemini/hooks` wrappers, the `gemini:*` hook family, the two
+  Gemini CLI steps `mirror init` printed, and the Gemini smoke no longer ship
+  (CV21.DS8.US1). The package's description and keywords, and every
+  runtime-facing document, name Pi, Claude Code, Codex, and Antigravity
+  (CV21.DS8.US2).
+- **The gate was met first.** v0.33.0 gave notice that the integration would
+  be removed "only once Antigravity gives a Gemini CLI user what they have
+  now". CV21.DS7.US4 measured that on agy 1.4.2, live: all of Mirror's
+  skills, the Operating Instructions at session start, Mirror Mode context
+  injected once per user turn, every turn logged and the conversation closed,
+  setup in one step against Gemini CLI's two — and MCP reachable, which the
+  Gemini CLI wiring never had.
+- **The cutoff is written where a user reads it before it happens to them**:
+  the section below, the Antigravity section of
+  [Getting Started](../getting-started.md#antigravity), and a
+  [troubleshooting entry](../process/troubleshooting.md#gemini-cli-runs-a-mirror-hook-that-no-longer-exists)
+  for the symptom a Gemini CLI user would meet.
+- **A retired-surface guard keeps the removal removed.** `.gemini/` can never
+  ship again from this package: the row is enforced on every push and by the
+  release tripwire. That matters because `mirror init` once told users to
+  write absolute paths into that directory into their settings — a standing
+  instruction to execute whatever a later release might put there.
+
+## Where We Started
+
+v0.32.1 shipped Gemini CLI as one of four supported runtimes, at L4 parity,
+wired by two documented steps. On 2026-09-25 the Navigator retired it —
+Google had set a deprecation date for the Gemini Code Assist backend for
+individuals, and Antigravity, which imports Claude-format plugins, was the
+successor — but the call lived in one story's notes while the release kept
+advertising the runtime. The decision was recorded on 2026-10-13, with a
+condition: the integration goes only behind a documented cutoff, and only
+once Antigravity meets the bar a Gemini CLI user already had. DS7 built the
+agy-native layer and measured the bar. DS8 is the cutoff.
+
+## What Changed
+
+**The integration is gone from the package.** No `.gemini/hooks`, no `gemini`
+entry in the wiring `mirror init` prints, no `gemini:*` hook names — an
+unknown name is noted in `hooks.log` and the turn proceeds, as any unknown
+name does. The Gemini smoke and the npm smoke's Gemini section retired with
+it; the hook payload reader dropped the one field only Gemini CLI supplied.
+
+**The docs say what ships.** Twenty files: README, Getting Started,
+REFERENCE, the Operating Instructions and their plugin copy, the
+runtime-interface spec, the welcome spec, the architecture, and the skills
+that said "Pi and Gemini CLI". Where a runtime list, a wiring step, or a
+parity table had Gemini CLI, it has Antigravity. Where a lesson says what
+Gemini CLI taught — the payload-shape bug its smoke caught, the one-JSON-
+object rule its hook entries kept — the lesson stays, in the past tense.
+Getting Started's subscription table no longer carries a Gemini AI Pro row
+and invents no Antigravity row: what Antigravity requires is Google's to
+say, and Mirror needs only the `agy` command on your PATH.
+
+**Antigravity's own documentation is unchanged** beyond taking Gemini CLI's
+place: DS7 wrote it and measured it.
+
+## The Cutoff: Gemini CLI
+
+**What you keep.** Everything that is yours. Your `~/.mirror-minds/<user>`
+home, your identity, your memories, your journeys, and every conversation
+you logged — including the ones labelled `gemini_cli`, which stay readable
+in `mm-conversations` and `mm-recall` and are never migrated or relabelled.
+Only the runtime that reads them changes.
+
+**Removed.** The four `.gemini/hooks` wrappers (`session-start.sh`,
+`log-user.sh`, `log-assistant.sh`, `session-end.sh`) and the `gemini:*` hook
+family behind them; the two Gemini CLI steps `mirror init` printed (the
+skills link, the four hooks merged into `~/.gemini/settings.json`); the
+Gemini smoke; the runtime from the package's description and keywords and
+from every runtime-facing document.
+
+**Why.** Google deprecated the Gemini Code Assist backend for individuals
+(2026-06-18). Antigravity is its successor and imports Claude-format
+plugins — the one plugin Mirror already ships. The removal waited for
+DS7.US4's measurement on agy 1.4.2: all five items of the bar DS12.TS3 set
+PASS, with per-turn injection — the cost the decision feared losing —
+carried by agy's `PreInvocation` hook. The one difference that did
+materialize: agy has no session-end signal, so a conversation closes when
+your next session starts rather than at exit (as Codex's does); logging
+parity holds, and memories extract after the close.
+
+**What to do instead.** Install Antigravity, then the one step `mirror init`
+prints when it finds `agy` on your PATH:
+
+```bash
+agy plugin install "<pkg>/plugins/mirror-mind"    # <pkg> = $(npm root -g)/mirror-mind
+```
+
+Your home carries over unchanged — nothing to export, nothing to re-seed.
+Same home, same memory, different door. The skills carry the plugin's name:
+`/mirror-mind:mm:mirror`, `/mirror-mind:mm:journeys`, and so on.
+
+**What still works.** Gemini *models*. Memory extraction runs on
+`google/gemini-2.5-flash-lite` through OpenRouter, and `consult` reaches the
+`gemini` family as before. Those are model choices, not the runtime.
+
+**If you do nothing.** After the update, the four `mirror-*` hook commands in
+your `~/.gemini/settings.json` point at files that no longer exist, while the
+links in `~/.gemini/skills/` still resolve — `.pi/skills` keeps shipping. So
+Gemini CLI keeps Mirror's skills and loses logging and Mirror Mode injection.
+Said plainly: your Gemini CLI sessions stop being logged and Mirror Mode
+stops being injected, and nothing on screen says so. Measured on Gemini CLI
+0.61.0 in headless mode (`gemini -p`), 2026-10-18: a registered hook whose
+command is missing is skipped silently; the session proceeds. The entries to
+delete, in `~/.gemini/settings.json`: `mirror-session-start` (under
+`SessionStart`), `mirror-log-user` (`BeforeAgent`), `mirror-log-assistant`
+(`AfterAgent`), `mirror-session-end` (`SessionEnd`); and the `mm-*` links in
+`~/.gemini/skills/`. Mirror never wrote those files and does not edit them.
+Whether Antigravity also reads `~/.gemini/skills/` — which would show a
+migrated user the stale links as duplicate skills — was not measured;
+remove the links either way.
+
+**To stay on Gemini CLI a while longer.** `npm install -g mirror-mind@0.34.0`
+is the last release that carries the integration. The welcome card and
+`runtime update` will keep offering the newer version every session; the pin
+is a choice to make knowingly, not a quiet state.
+
+## Upgrading
+
+```bash
+npm install -g mirror-mind@latest    # or: mirror runtime update
+```
+
+**If you used Gemini CLI:** read the cutoff above; the steps are in Getting
+Started's Antigravity section. **Every other runtime:** nothing to do. No
+migration. Existing homes, sessions, and memories are untouched.
+
+## Also In This Release
+
+- **Typecheck is green on `main` again.** DS7.TS3 left one early return in
+  `hooks/agy.ts` without the field it had just added; `tsc --noEmit`, a CI
+  gate, refused since. Found by DS8.US1's validation, paid in its own commit.
+- **The docs link check is green again.** The plugin's byte copy of the
+  Operating Instructions carries a root-relative link that cannot resolve
+  under `rules/`; the checker reported it on every `.md` push since DS7.US1.
+  The copy's links now resolve where the source lives — not skipped: a link
+  the source cannot resolve still fails through the copy.
+- **The P1 redaction invariant outlives the runtime it was written against.**
+  "A failed hook never writes the prompt or the reply to `hooks.log`" was
+  tested through the Gemini CLI hooks; it now runs through the Claude-family
+  hooks every plugin runtime shares.
+
+## Conscious Exclusions
+
+- **No second cutoff document.** CV22 needed `pending-cutoffs.md` for eleven
+  cutoffs in one release; DS8 has one, and this note is its record.
+- **Mirror does not edit `~/.gemini/settings.json` or `~/.gemini/skills/`.**
+  It never wrote them. The note and the guidance name what to remove.
+- **The Claude plugin smoke's negative probe** still cannot run on a machine
+  with a globally installed `mirror-hook` (CR142, D-031): pre-existing,
+  local-only, carried.
+- **DS5, DS10, DS11** — user extensions on every runtime, Grok through the
+  plugin, the contract and docs refresh — are CV21's remaining stories, not
+  this release's.
+
+## What We Learned
+
+A retirement that lives in a decision while the release advertises the
+runtime has not happened; it happened here in three stories, in order:
+remove, then make the tree say so, then tell the user — and the guard that
+proves each step split by story, so nothing went red between them. The
+sweep found what the inventory missed (a spec line, a history link), which
+is what a guard is for. And the one fact this note most needed — what a
+user who does nothing will see — turned out to be *nothing*: Gemini CLI
+skips a missing hook in silence. That is the strongest reason the cutoff is
+written where the user looks, not only here.
+
+## Next Horizon
+
+DS8 closes with this release, and with it the runtime set CV21 set out to
+reach: the canonical plugin on Claude Code, Codex, and Antigravity, Pi
+through its extension. What remains in CV21 is pulled deliberately from the
+CV21 index: user extensions on every runtime (DS5), Grok through the plugin
+(DS10), and the contract and docs refresh that folds all of it into one
+account (DS11).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mirror-mind",
-  "version": "0.34.0",
-  "description": "Mirror Mind: a local-first memory and identity framework for agentic AI runtimes (Pi, Claude Code, Gemini CLI, Codex)",
+  "version": "0.35.0",
+  "description": "Mirror Mind: a local-first memory and identity framework for agentic AI runtimes (Pi, Claude Code, Codex, Antigravity)",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -15,7 +15,6 @@
     "agent",
     "pi-package",
     "claude-code",
-    "gemini-cli",
     "codex",
     "sqlite",
     "local-first"
@@ -36,7 +35,6 @@
     ".pi/extensions",
     ".pi/skills",
     ".claude/hooks",
-    ".gemini/hooks",
     "plugins/mirror-mind",
     ".agents/plugins",
     "AGENTS.md",

package/plugins/mirror-mind/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
   "author": {
     "name": "Mirror Mind"

package/plugins/mirror-mind/agy/pre-invocation.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Mirror Mind hook wrapper — GENERATED by scripts/generate_hook_wrappers.sh.
+# Edit the generator, never this file: every agy wrapper shares these bytes
+# and differs only in the hook name and its stdin gate (CV21.DS7.TS2).
+set -uo pipefail
+HOOK="agy:pre-invocation"
+GATE='"invocationNum"[[:space:]]*:[[:space:]]*-?[0-9]*[1-9]'
+
+# agy sends the payload on stdin and blocks its agent loop on this process.
+# Read the payload once; when the gate says this invocation is not ours,
+# answer the empty object without resolving Node at all.
+PAYLOAD="$(cat 2>/dev/null || true)"
+if [ -n "$GATE" ] && printf '%s' "$PAYLOAD" | grep -qE "$GATE"; then
+  printf '{}\n'
+  exit 0
+fi
+
+# This wrapper is the Claude plugin's, and a plugin is copied into Claude
+# Code's own cache: no relative path from here reaches the Mirror tree. It
+# runs the installed `mirror-hook` bin instead, and reads no tree .env.
+REPO_ROOT=""
+
+# A hook never fails the user's turn, and never fails in silence: when it
+# cannot do its job it appends ONE line to <mirror home>/hooks.log and exits
+# 0 — after answering agy's contract, so the agent loop never stalls.
+env_file_value() {
+  [ -f "$2" ] || return 0
+  sed -n -E "s/^[[:space:]]*(export[[:space:]]+)?$1[[:space:]]*=[[:space:]]*//p" "$2" \
+    | tail -n 1 | tr -d "\"'\r"
+}
+env_value() {
+  local value=""
+  if [ -n "${!1+set}" ]; then printf '%s' "${!1}"; return; fi
+  [ -z "$REPO_ROOT" ] || value="$(env_file_value "$1" "$REPO_ROOT/.env")"
+  [ -n "$value" ] || value="$(env_file_value "$1" "${XDG_CONFIG_HOME:-$HOME/.config}/mirror/env")"
+  printf '%s' "$value"
+}
+note() {
+  local home user
+  home="$(env_value MIRROR_HOME)"
+  user="$(env_value MIRROR_USER)"
+  if [ -n "$home" ]; then
+    home="${home/#\~/$HOME}"
+  elif [ -n "$user" ]; then
+    home="$HOME/.mirror-minds/$user"
+    [ -d "$home" ] || [ ! -d "$HOME/.mirror/$user" ] || home="$HOME/.mirror/$user"
+  else
+    return 0
+  fi
+  mkdir -p "$home" 2>/dev/null \
+    && printf '%s %s: %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$HOOK" "$1" >> "$home/hooks.log" 2>/dev/null
+}
+
+# Find the bin. MIRROR_BIN names the directory holding `mirror` and
+# `mirror-hook` (`$(npm prefix -g)/bin`), the same trust class as MIRROR_NODE;
+# then the PATH; then the global bin directories a GUI launch leaves off it.
+ENTRY=""
+[ -n "${MIRROR_BIN:-}" ] && [ -x "$MIRROR_BIN/mirror-hook" ] && ENTRY="$MIRROR_BIN/mirror-hook"
+[ -n "$ENTRY" ] || ENTRY="$(command -v mirror-hook 2>/dev/null || true)"
+for candidate in "$HOME/.nvm/current/bin" /opt/homebrew/bin /usr/local/bin; do
+  [ -n "$ENTRY" ] && break
+  [ -x "$candidate/mirror-hook" ] && ENTRY="$candidate/mirror-hook"
+done
+
+if [ -z "$ENTRY" ]; then
+  note "mirror-hook not found on PATH; hook skipped. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory."
+  exit 0
+fi
+
+NODE="${MIRROR_NODE:-}"
+if [ -z "$NODE" ] || [ ! -x "$NODE" ]; then
+  NODE="$(command -v node 2>/dev/null || true)"
+fi
+for candidate in "$(dirname "$ENTRY")/node" "$HOME/.nvm/current/bin/node" /opt/homebrew/bin/node /usr/local/bin/node; do
+  [ -n "$NODE" ] && break
+  [ -x "$candidate" ] && NODE="$candidate"
+done
+
+if [ -z "$NODE" ]; then
+  printf '{}\n'
+  note "node not found on PATH; hook skipped. Set MIRROR_NODE."
+  exit 0
+fi
+
+# The payload was consumed by the gate read; re-feed it to the entry.
+printf '%s' "$PAYLOAD" | "$NODE" "$ENTRY" "$HOOK" "$@"
+status=$?
+if [ "$status" -ne 0 ]; then
+  printf '{}\n'
+  note "node exited $status before the hook finished ($NODE, $("$NODE" --version 2>/dev/null || echo 'version unknown')); Mirror needs Node 24 or later. Set MIRROR_NODE."
+fi
+exit 0

package/plugins/mirror-mind/agy/session-start.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Mirror Mind hook wrapper — GENERATED by scripts/generate_hook_wrappers.sh.
+# Edit the generator, never this file: every agy wrapper shares these bytes
+# and differs only in the hook name and its stdin gate (CV21.DS7.TS2).
+set -uo pipefail
+HOOK="agy:session-start"
+GATE=''
+
+# agy sends the payload on stdin and blocks its agent loop on this process.
+# Read the payload once; when the gate says this invocation is not ours,
+# answer the empty object without resolving Node at all.
+PAYLOAD="$(cat 2>/dev/null || true)"
+if [ -n "$GATE" ] && printf '%s' "$PAYLOAD" | grep -qE "$GATE"; then
+  printf '{}\n'
+  exit 0
+fi
+
+# This wrapper is the Claude plugin's, and a plugin is copied into Claude
+# Code's own cache: no relative path from here reaches the Mirror tree. It
+# runs the installed `mirror-hook` bin instead, and reads no tree .env.
+REPO_ROOT=""
+
+# A hook never fails the user's turn, and never fails in silence: when it
+# cannot do its job it appends ONE line to <mirror home>/hooks.log and exits
+# 0 — after answering agy's contract, so the agent loop never stalls.
+env_file_value() {
+  [ -f "$2" ] || return 0
+  sed -n -E "s/^[[:space:]]*(export[[:space:]]+)?$1[[:space:]]*=[[:space:]]*//p" "$2" \
+    | tail -n 1 | tr -d "\"'\r"
+}
+env_value() {
+  local value=""
+  if [ -n "${!1+set}" ]; then printf '%s' "${!1}"; return; fi
+  [ -z "$REPO_ROOT" ] || value="$(env_file_value "$1" "$REPO_ROOT/.env")"
+  [ -n "$value" ] || value="$(env_file_value "$1" "${XDG_CONFIG_HOME:-$HOME/.config}/mirror/env")"
+  printf '%s' "$value"
+}
+note() {
+  local home user
+  home="$(env_value MIRROR_HOME)"
+  user="$(env_value MIRROR_USER)"
+  if [ -n "$home" ]; then
+    home="${home/#\~/$HOME}"
+  elif [ -n "$user" ]; then
+    home="$HOME/.mirror-minds/$user"
+    [ -d "$home" ] || [ ! -d "$HOME/.mirror/$user" ] || home="$HOME/.mirror/$user"
+  else
+    return 0
+  fi
+  mkdir -p "$home" 2>/dev/null \
+    && printf '%s %s: %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$HOOK" "$1" >> "$home/hooks.log" 2>/dev/null
+}
+
+# Find the bin. MIRROR_BIN names the directory holding `mirror` and
+# `mirror-hook` (`$(npm prefix -g)/bin`), the same trust class as MIRROR_NODE;
+# then the PATH; then the global bin directories a GUI launch leaves off it.
+ENTRY=""
+[ -n "${MIRROR_BIN:-}" ] && [ -x "$MIRROR_BIN/mirror-hook" ] && ENTRY="$MIRROR_BIN/mirror-hook"
+[ -n "$ENTRY" ] || ENTRY="$(command -v mirror-hook 2>/dev/null || true)"
+for candidate in "$HOME/.nvm/current/bin" /opt/homebrew/bin /usr/local/bin; do
+  [ -n "$ENTRY" ] && break
+  [ -x "$candidate/mirror-hook" ] && ENTRY="$candidate/mirror-hook"
+done
+
+if [ -z "$ENTRY" ]; then
+  note "mirror-hook not found on PATH; hook skipped. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory."
+  exit 0
+fi
+
+NODE="${MIRROR_NODE:-}"
+if [ -z "$NODE" ] || [ ! -x "$NODE" ]; then
+  NODE="$(command -v node 2>/dev/null || true)"
+fi
+for candidate in "$(dirname "$ENTRY")/node" "$HOME/.nvm/current/bin/node" /opt/homebrew/bin/node /usr/local/bin/node; do
+  [ -n "$NODE" ] && break
+  [ -x "$candidate" ] && NODE="$candidate"
+done
+
+if [ -z "$NODE" ]; then
+  printf '{}\n'
+  note "node not found on PATH; hook skipped. Set MIRROR_NODE."
+  exit 0
+fi
+
+# The payload was consumed by the gate read; re-feed it to the entry.
+printf '%s' "$PAYLOAD" | "$NODE" "$ENTRY" "$HOOK" "$@"
+status=$?
+if [ "$status" -ne 0 ]; then
+  printf '{}\n'
+  note "node exited $status before the hook finished ($NODE, $("$NODE" --version 2>/dev/null || echo 'version unknown')); Mirror needs Node 24 or later. Set MIRROR_NODE."
+fi
+exit 0

package/plugins/mirror-mind/agy/stop.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Mirror Mind hook wrapper — GENERATED by scripts/generate_hook_wrappers.sh.
+# Edit the generator, never this file: every agy wrapper shares these bytes
+# and differs only in the hook name and its stdin gate (CV21.DS7.TS2).
+set -uo pipefail
+HOOK="agy:stop"
+GATE=''
+
+# agy sends the payload on stdin and blocks its agent loop on this process.
+# Read the payload once; when the gate says this invocation is not ours,
+# answer the empty object without resolving Node at all.
+PAYLOAD="$(cat 2>/dev/null || true)"
+if [ -n "$GATE" ] && printf '%s' "$PAYLOAD" | grep -qE "$GATE"; then
+  printf '{}\n'
+  exit 0
+fi
+
+# This wrapper is the Claude plugin's, and a plugin is copied into Claude
+# Code's own cache: no relative path from here reaches the Mirror tree. It
+# runs the installed `mirror-hook` bin instead, and reads no tree .env.
+REPO_ROOT=""
+
+# A hook never fails the user's turn, and never fails in silence: when it
+# cannot do its job it appends ONE line to <mirror home>/hooks.log and exits
+# 0 — after answering agy's contract, so the agent loop never stalls.
+env_file_value() {
+  [ -f "$2" ] || return 0
+  sed -n -E "s/^[[:space:]]*(export[[:space:]]+)?$1[[:space:]]*=[[:space:]]*//p" "$2" \
+    | tail -n 1 | tr -d "\"'\r"
+}
+env_value() {
+  local value=""
+  if [ -n "${!1+set}" ]; then printf '%s' "${!1}"; return; fi
+  [ -z "$REPO_ROOT" ] || value="$(env_file_value "$1" "$REPO_ROOT/.env")"
+  [ -n "$value" ] || value="$(env_file_value "$1" "${XDG_CONFIG_HOME:-$HOME/.config}/mirror/env")"
+  printf '%s' "$value"
+}
+note() {
+  local home user
+  home="$(env_value MIRROR_HOME)"
+  user="$(env_value MIRROR_USER)"
+  if [ -n "$home" ]; then
+    home="${home/#\~/$HOME}"
+  elif [ -n "$user" ]; then
+    home="$HOME/.mirror-minds/$user"
+    [ -d "$home" ] || [ ! -d "$HOME/.mirror/$user" ] || home="$HOME/.mirror/$user"
+  else
+    return 0
+  fi
+  mkdir -p "$home" 2>/dev/null \
+    && printf '%s %s: %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$HOOK" "$1" >> "$home/hooks.log" 2>/dev/null
+}
+
+# Find the bin. MIRROR_BIN names the directory holding `mirror` and
+# `mirror-hook` (`$(npm prefix -g)/bin`), the same trust class as MIRROR_NODE;
+# then the PATH; then the global bin directories a GUI launch leaves off it.
+ENTRY=""
+[ -n "${MIRROR_BIN:-}" ] && [ -x "$MIRROR_BIN/mirror-hook" ] && ENTRY="$MIRROR_BIN/mirror-hook"
+[ -n "$ENTRY" ] || ENTRY="$(command -v mirror-hook 2>/dev/null || true)"
+for candidate in "$HOME/.nvm/current/bin" /opt/homebrew/bin /usr/local/bin; do
+  [ -n "$ENTRY" ] && break
+  [ -x "$candidate/mirror-hook" ] && ENTRY="$candidate/mirror-hook"
+done
+
+if [ -z "$ENTRY" ]; then
+  note "mirror-hook not found on PATH; hook skipped. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory."
+  exit 0
+fi
+
+NODE="${MIRROR_NODE:-}"
+if [ -z "$NODE" ] || [ ! -x "$NODE" ]; then
+  NODE="$(command -v node 2>/dev/null || true)"
+fi
+for candidate in "$(dirname "$ENTRY")/node" "$HOME/.nvm/current/bin/node" /opt/homebrew/bin/node /usr/local/bin/node; do
+  [ -n "$NODE" ] && break
+  [ -x "$candidate" ] && NODE="$candidate"
+done
+
+if [ -z "$NODE" ]; then
+  printf '{}\n'
+  note "node not found on PATH; hook skipped. Set MIRROR_NODE."
+  exit 0
+fi
+
+# The payload was consumed by the gate read; re-feed it to the entry.
+printf '%s' "$PAYLOAD" | "$NODE" "$ENTRY" "$HOOK" "$@"
+status=$?
+if [ "$status" -ne 0 ]; then
+  printf '{}\n'
+  note "node exited $status before the hook finished ($NODE, $("$NODE" --version 2>/dev/null || echo 'version unknown')); Mirror needs Node 24 or later. Set MIRROR_NODE."
+fi
+exit 0

package/plugins/mirror-mind/hooks.json

@@ -0,0 +1,26 @@
+{
+  "mirror-mind": {
+    "enabled": true,
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "agy/session-start.sh",
+        "timeout": 60
+      }
+    ],
+    "PreInvocation": [
+      {
+        "type": "command",
+        "command": "agy/pre-invocation.sh",
+        "timeout": 15
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "agy/stop.sh",
+        "timeout": 30
+      }
+    ]
+  }
+}