instar 1.3.30 → 1.3.32

package/dist/core/instarSettingsHooks.d.ts

@@ -0,0 +1,95 @@
+/**
+ * instarSettingsHooks.ts — the single source of truth for the instar
+ * PreToolUse hook ENTRIES written into `.claude/settings.json`.
+ *
+ * Why this module exists (the dark-guardrail migration gap, 2026-05-27):
+ * `init.ts` wired a full set of PreToolUse Bash hooks for NEW agents, but the
+ * existing-agent path (`PostUpdateMigrator.migrateSettings`) only ever ensured
+ * two of them (slopcheck-guard + the MCP gate). So four guardrails —
+ * grounding-before-messaging, deferral-detector (the false-blocker pre-filter),
+ * external-communication-guard, post-action-reflection — shipped to disk on
+ * every existing agent but were never switched on in settings. They looked
+ * installed and did nothing. Root cause: the "what hooks does an agent get"
+ * list lived in two places that drifted.
+ *
+ * Both the new-agent path (init.ts) and the existing-agent path
+ * (PostUpdateMigrator.ensureInstarPreToolUseBashHooks) now import these
+ * constants, so the two can never drift again — add a hook here and both
+ * paths get it. An anti-drift unit test locks the canonical filename set.
+ *
+ * NOTE: the objects here are written verbatim into settings.json, so their
+ * shape (type/command/blocking/timeout) must stay byte-stable. Presence
+ * detection during migration derives the script filename from the command
+ * via `instarHookFilename()` — never add a `filename` field to these objects,
+ * or new agents' settings would gain a stray key.
+ *
+ * Scope: the Claude-Code `Bash` and `mcp__.*` PreToolUse matchers only.
+ * slopcheck-guard keeps its own dedicated ensure-block in migrateSettings
+ * (it is intentionally NOT in this set — it is added by that block for both
+ * new and existing agents). Codex hooks (installCodexHooks.ts, `.*` matcher)
+ * are a separate path and are not governed by this module.
+ */
+export interface InstarSettingsHookEntry {
+    type: 'command';
+    command: string;
+    blocking?: boolean;
+    timeout?: number;
+}
+/**
+ * The canonical instar PreToolUse `Bash`-matcher hook entries, in canonical
+ * order. Mirrors (and is consumed by) init.ts's former `instarBashHooks`.
+ */
+export declare const INSTAR_BASH_PRETOOLUSE_HOOKS: ReadonlyArray<InstarSettingsHookEntry>;
+/**
+ * The canonical instar PreToolUse `mcp__.*`-matcher hook entries.
+ * Mirrors (and is consumed by) init.ts's former `instarMcpHooks`.
+ */
+export declare const INSTAR_MCP_PRETOOLUSE_HOOKS: ReadonlyArray<InstarSettingsHookEntry>;
+/**
+ * The canonical script filenames for the Bash set, in order. Used by the
+ * anti-drift test and as the documented contract. Derived once from the
+ * command strings so it can never silently disagree with the entries above.
+ */
+export declare const INSTAR_BASH_PRETOOLUSE_FILENAMES: ReadonlyArray<string>;
+/**
+ * Extract the instar hook script filename from a settings hook command, e.g.
+ * `node ${CLAUDE_PROJECT_DIR}/.instar/hooks/instar/deferral-detector.js` ->
+ * `deferral-detector.js`. Returns null if the command does not reference an
+ * instar hook script. Used for idempotent presence detection during migration
+ * (substring/filename match is robust to ${CLAUDE_PROJECT_DIR} vs absolute
+ * path variations, unlike an exact-command compare).
+ */
+export declare function instarHookFilename(command: string): string | null;
+/** Minimal structural shape of a settings PreToolUse matcher entry. */
+export interface SettingsMatcherEntry {
+    matcher?: string;
+    hooks?: Array<{
+        command?: string;
+        type?: string;
+        blocking?: boolean;
+        timeout?: number;
+    }>;
+}
+/**
+ * Idempotently ensure every canonical instar Bash PreToolUse hook is present
+ * in an existing agent's settings. Mirrors init.ts (both consume
+ * INSTAR_BASH_PRETOOLUSE_HOOKS), closing the dark-guardrail migration gap.
+ *
+ * Behavior:
+ * - Finds the `Bash` matcher (creates one if absent).
+ * - For each canonical hook, adds it ONLY IF no existing hook command already
+ *   references that script filename (filename/substring match — robust to
+ *   ${CLAUDE_PROJECT_DIR} vs absolute path; prevents duplicates).
+ * - APPENDS missing hooks in canonical order; never reorders or removes
+ *   existing entries (hand-curated settings are preserved).
+ * - Pushes fresh copies of the canonical entries (never the shared objects).
+ *
+ * Returns the list of filenames that were added (empty array == no-op, so the
+ * caller can decide whether to flag the settings file as patched). Safe to run
+ * repeatedly: once every hook is present, every subsequent call returns [].
+ *
+ * Does NOT touch slopcheck-guard (its own dedicated ensure-block owns it) or
+ * any non-Bash matcher.
+ */
+export declare function ensureInstarBashPreToolUseHooks(preToolUse: SettingsMatcherEntry[]): string[];
+//# sourceMappingURL=instarSettingsHooks.d.ts.map

package/dist/core/instarSettingsHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instarSettingsHooks.d.ts","sourceRoot":"","sources":["../../src/core/instarSettingsHooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,aAAa,CAAC,uBAAuB,CA0B/E,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EAAE,aAAa,CAAC,uBAAuB,CAO9E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,EAAE,aAAa,CAAC,MAAM,CACW,CAAC;AAE/E;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGjE;AAED,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,+BAA+B,CAAC,UAAU,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,CAmB5F"}

package/dist/core/instarSettingsHooks.js

@@ -0,0 +1,136 @@
+/**
+ * instarSettingsHooks.ts — the single source of truth for the instar
+ * PreToolUse hook ENTRIES written into `.claude/settings.json`.
+ *
+ * Why this module exists (the dark-guardrail migration gap, 2026-05-27):
+ * `init.ts` wired a full set of PreToolUse Bash hooks for NEW agents, but the
+ * existing-agent path (`PostUpdateMigrator.migrateSettings`) only ever ensured
+ * two of them (slopcheck-guard + the MCP gate). So four guardrails —
+ * grounding-before-messaging, deferral-detector (the false-blocker pre-filter),
+ * external-communication-guard, post-action-reflection — shipped to disk on
+ * every existing agent but were never switched on in settings. They looked
+ * installed and did nothing. Root cause: the "what hooks does an agent get"
+ * list lived in two places that drifted.
+ *
+ * Both the new-agent path (init.ts) and the existing-agent path
+ * (PostUpdateMigrator.ensureInstarPreToolUseBashHooks) now import these
+ * constants, so the two can never drift again — add a hook here and both
+ * paths get it. An anti-drift unit test locks the canonical filename set.
+ *
+ * NOTE: the objects here are written verbatim into settings.json, so their
+ * shape (type/command/blocking/timeout) must stay byte-stable. Presence
+ * detection during migration derives the script filename from the command
+ * via `instarHookFilename()` — never add a `filename` field to these objects,
+ * or new agents' settings would gain a stray key.
+ *
+ * Scope: the Claude-Code `Bash` and `mcp__.*` PreToolUse matchers only.
+ * slopcheck-guard keeps its own dedicated ensure-block in migrateSettings
+ * (it is intentionally NOT in this set — it is added by that block for both
+ * new and existing agents). Codex hooks (installCodexHooks.ts, `.*` matcher)
+ * are a separate path and are not governed by this module.
+ */
+const PD = '${CLAUDE_PROJECT_DIR}';
+/**
+ * The canonical instar PreToolUse `Bash`-matcher hook entries, in canonical
+ * order. Mirrors (and is consumed by) init.ts's former `instarBashHooks`.
+ */
+export const INSTAR_BASH_PRETOOLUSE_HOOKS = [
+    {
+        type: 'command',
+        command: `bash ${PD}/.instar/hooks/instar/dangerous-command-guard.sh "$TOOL_INPUT"`,
+        blocking: true,
+    },
+    {
+        type: 'command',
+        command: `bash ${PD}/.instar/hooks/instar/grounding-before-messaging.sh "$TOOL_INPUT"`,
+        blocking: false,
+    },
+    {
+        type: 'command',
+        command: `node ${PD}/.instar/hooks/instar/deferral-detector.js`,
+        timeout: 5000,
+    },
+    {
+        type: 'command',
+        command: `node ${PD}/.instar/hooks/instar/external-communication-guard.js`,
+        timeout: 5000,
+    },
+    {
+        type: 'command',
+        command: `node ${PD}/.instar/hooks/instar/post-action-reflection.js`,
+        timeout: 5000,
+    },
+];
+/**
+ * The canonical instar PreToolUse `mcp__.*`-matcher hook entries.
+ * Mirrors (and is consumed by) init.ts's former `instarMcpHooks`.
+ */
+export const INSTAR_MCP_PRETOOLUSE_HOOKS = [
+    {
+        type: 'command',
+        command: `node ${PD}/.instar/hooks/instar/external-operation-gate.js`,
+        blocking: true,
+        timeout: 5000,
+    },
+];
+/**
+ * The canonical script filenames for the Bash set, in order. Used by the
+ * anti-drift test and as the documented contract. Derived once from the
+ * command strings so it can never silently disagree with the entries above.
+ */
+export const INSTAR_BASH_PRETOOLUSE_FILENAMES = INSTAR_BASH_PRETOOLUSE_HOOKS.map((h) => instarHookFilename(h.command) ?? '');
+/**
+ * Extract the instar hook script filename from a settings hook command, e.g.
+ * `node ${CLAUDE_PROJECT_DIR}/.instar/hooks/instar/deferral-detector.js` ->
+ * `deferral-detector.js`. Returns null if the command does not reference an
+ * instar hook script. Used for idempotent presence detection during migration
+ * (substring/filename match is robust to ${CLAUDE_PROJECT_DIR} vs absolute
+ * path variations, unlike an exact-command compare).
+ */
+export function instarHookFilename(command) {
+    const m = command.match(/\/\.instar\/hooks\/instar\/([\w.-]+\.(?:sh|js|mjs|cjs))/);
+    return m ? m[1] : null;
+}
+/**
+ * Idempotently ensure every canonical instar Bash PreToolUse hook is present
+ * in an existing agent's settings. Mirrors init.ts (both consume
+ * INSTAR_BASH_PRETOOLUSE_HOOKS), closing the dark-guardrail migration gap.
+ *
+ * Behavior:
+ * - Finds the `Bash` matcher (creates one if absent).
+ * - For each canonical hook, adds it ONLY IF no existing hook command already
+ *   references that script filename (filename/substring match — robust to
+ *   ${CLAUDE_PROJECT_DIR} vs absolute path; prevents duplicates).
+ * - APPENDS missing hooks in canonical order; never reorders or removes
+ *   existing entries (hand-curated settings are preserved).
+ * - Pushes fresh copies of the canonical entries (never the shared objects).
+ *
+ * Returns the list of filenames that were added (empty array == no-op, so the
+ * caller can decide whether to flag the settings file as patched). Safe to run
+ * repeatedly: once every hook is present, every subsequent call returns [].
+ *
+ * Does NOT touch slopcheck-guard (its own dedicated ensure-block owns it) or
+ * any non-Bash matcher.
+ */
+export function ensureInstarBashPreToolUseHooks(preToolUse) {
+    const added = [];
+    let bashEntry = preToolUse.find((e) => e.matcher === 'Bash');
+    if (!bashEntry) {
+        bashEntry = { matcher: 'Bash', hooks: [] };
+        preToolUse.push(bashEntry);
+    }
+    if (!bashEntry.hooks)
+        bashEntry.hooks = [];
+    for (const canonical of INSTAR_BASH_PRETOOLUSE_HOOKS) {
+        const fname = instarHookFilename(canonical.command);
+        if (!fname)
+            continue;
+        const present = bashEntry.hooks.some((h) => typeof h.command === 'string' && h.command.includes(fname));
+        if (!present) {
+            bashEntry.hooks.push({ ...canonical });
+            added.push(fname);
+        }
+    }
+    return added;
+}
+//# sourceMappingURL=instarSettingsHooks.js.map

package/dist/core/instarSettingsHooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instarSettingsHooks.js","sourceRoot":"","sources":["../../src/core/instarSettingsHooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AASH,MAAM,EAAE,GAAG,uBAAuB,CAAC;AAEnC;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAA2C;IAClF;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,QAAQ,EAAE,gEAAgE;QACnF,QAAQ,EAAE,IAAI;KACf;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,QAAQ,EAAE,mEAAmE;QACtF,QAAQ,EAAE,KAAK;KAChB;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,QAAQ,EAAE,4CAA4C;QAC/D,OAAO,EAAE,IAAI;KACd;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,QAAQ,EAAE,uDAAuD;QAC1E,OAAO,EAAE,IAAI;KACd;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,QAAQ,EAAE,iDAAiD;QACpE,OAAO,EAAE,IAAI;KACd;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAA2C;IACjF;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,QAAQ,EAAE,kDAAkD;QACrE,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,IAAI;KACd;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAC3C,4BAA4B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AAE/E;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,yDAAyD,CAAC,CAAC;IACnF,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACzB,CAAC;AAQD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,+BAA+B,CAAC,UAAkC;IAChF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC;IAC7D,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAC3C,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,KAAK;QAAE,SAAS,CAAC,KAAK,GAAG,EAAE,CAAC;IAE3C,KAAK,MAAM,SAAS,IAAI,4BAA4B,EAAE,CAAC;QACrD,MAAM,KAAK,GAAG,kBAAkB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;QACxG,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.30",
+  "version": "1.3.32",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-27T21:58:29.713Z",
-  "instarVersion": "1.3.30",
+  "generatedAt": "2026-05-27T22:28:16.266Z",
+  "instarVersion": "1.3.32",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1481,7 +1481,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "d7515c04edc8ced2590d4f8d671ba8f6e3a9ec2142b3fc77bf54cf5ac8a67d4d",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.31.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Notify-on-stop, Layer A: when an autonomous run reaches a terminal exit — it completed, ran out of its time budget, or was emergency-stopped — the agent now sends one plain-English Telegram to the run's topic explaining why it stopped. Previously these reasons were only written to stderr (the terminal the user can't see), so an autonomous run could end in silence unless the agent remembered to send a wrap-up. This bakes the "a session either keeps going OR tells you why it stopped" guarantee into the stop hook itself.
+
+The notice is best-effort and non-blocking (a delivery hiccup never blocks the exit), fires at most once per run, and reuses the existing Telegram reply transport + the run's existing topic (no new topic is ever created).
+
+Existing agents receive the notify-enabled hook automatically: the autonomous-stop-hook capability marker is bumped, so the marker+fingerprint migration re-deploys the updated hook to stock installs on update (customized hooks are left untouched).
+
+## What to Tell Your User
+
+- When one of my autonomous runs finishes (or times out, or is stopped), you now get a short heads-up explaining why — no more silent endings.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Autonomous-run terminal exits send a Telegram explaining why | Automatic; one message per run to the run's topic |
+
+## Evidence
+
+- Hook: `.claude/skills/autonomous/hooks/autonomous-stop-hook.sh` (`notify_terminal_stop` at all 6 terminal exits).
+- Migration: `src/core/PostUpdateMigrator.ts` (capability marker → `notify_terminal_stop`).
+- Tests: `tests/unit/autonomous-stop-hook-notify.test.ts` (9 — static wiring, functional delivery via the real extracted helper, migration).
+- Spec: `docs/specs/NOTIFY-ON-STOP-SPEC.md` (approved) + `.eli16.md`. Side-effects: `upgrades/side-effects/notify-on-stop-layer-a.md`.
+- Layer B (watchdog-caught mid-task stalls) ships separately under the same spec.

package/upgrades/1.3.32.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Closes a fleet-wide "dark guardrail" migration gap. `instar init` wires a full set of PreToolUse `Bash` guardrail hooks for new agents, but the existing-agent update path (`PostUpdateMigrator.migrateSettings`) only ever switched on two of them. So four guardrails — `deferral-detector.js` (the false-blocker / anti-deferral pre-filter), `grounding-before-messaging.sh`, `external-communication-guard.js`, and `post-action-reflection.js` — were copied to disk on every existing agent but never wired into `.claude/settings.json`, leaving them installed-but-inert. Same failure class as the 2026-05-27 silent-stall incident.
+
+This release introduces a single source of truth for the canonical instar PreToolUse hook set (`src/core/instarSettingsHooks.ts`), consumed by BOTH the new-agent path (`init.ts`) and the existing-agent path, so the two can never drift again. `migrateSettings` now idempotently ensures every canonical Bash guardrail is present (appends only the missing ones; never reorders or removes; leaves custom hooks alone).
+
+## What to Tell Your User
+
+- Four guardrail hooks that were quietly switched off on existing agents — including the "false blocker" catcher that stops the agent handing a doable task back to you — come on at this update. New agents already had them; no action needed.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Existing agents get the full instar PreToolUse guardrail set on update | Automatic on update; no action needed |
+| Anti-drift: new-agent + existing-agent hook lists share one constant | Adding a hook to `INSTAR_BASH_PRETOOLUSE_HOOKS` wires both paths; a unit test locks the set |
+
+## Evidence
+
+- New module + tests: `src/core/instarSettingsHooks.ts`, `tests/unit/instar-settings-hooks.test.ts` (16), `tests/unit/PostUpdateMigrator-pretooluse-parity.test.ts` (3, real migrateSettings).
+- Spec: `docs/specs/EXISTING-AGENT-PRETOOLUSE-HOOK-PARITY-SPEC.md` (approved)
+- ELI16: `docs/specs/EXISTING-AGENT-PRETOOLUSE-HOOK-PARITY-SPEC.eli16.md`
+- Side-effects review: `upgrades/side-effects/existing-agent-pretooluse-hook-parity.md`
+- Context: Task 3 of the 2026-05-27 silent-stalls postmortem.

package/upgrades/side-effects/existing-agent-pretooluse-hook-parity.md

@@ -0,0 +1,39 @@
+# Side-Effects Review — Existing-Agent PreToolUse Hook Parity
+
+**Spec:** docs/specs/EXISTING-AGENT-PRETOOLUSE-HOOK-PARITY-SPEC.md (approved: true, internal-adversarial review 2026-05-27)
+
+Closes the dark-guardrail migration gap: `init.ts` wired a full instar Bash PreToolUse hook set for NEW agents, but `PostUpdateMigrator.migrateSettings` only ensured slopcheck-guard + the MCP gate for EXISTING agents — so `deferral-detector.js` (the false-blocker pre-filter; this is Task 3 of the silent-stalls postmortem), `grounding-before-messaging.sh`, `external-communication-guard.js`, and `post-action-reflection.js` shipped to disk on every existing agent but were never switched on in settings. Same failure class as the 2026-05-27 silent-stall incident (looks installed, does nothing).
+
+## What changed
+- `src/core/instarSettingsHooks.ts` — NEW. Single source of truth for the canonical instar `Bash` and `mcp__.*` PreToolUse hook ENTRIES (`INSTAR_BASH_PRETOOLUSE_HOOKS`, `INSTAR_MCP_PRETOOLUSE_HOOKS`), a `instarHookFilename()` helper, and the idempotent `ensureInstarBashPreToolUseHooks()`.
+- `src/commands/init.ts` — refactored the inline `instarBashHooks` / `instarMcpHooks` literals to consume the shared constants (fresh copies via `.map(h => ({...h}))`). Behavior-preserving: byte-identical settings output for new agents (verified by the existing `hook-installation.test.ts`, all green).
+- `src/core/PostUpdateMigrator.ts` — `migrateSettings` now calls `ensureInstarBashPreToolUseHooks(preToolUse)` before the slopcheck block; appends only missing canonical hooks, idempotently, reporting each as a `dark-guardrail wiring` upgrade.
+- Tests: `tests/unit/instar-settings-hooks.test.ts` (16) + `tests/unit/PostUpdateMigrator-pretooluse-parity.test.ts` (3).
+
+## Over-block / under-block
+- UNDER: a custom hook with the same script filename would be treated as "present" and not re-added. Acceptable — that's the intent (don't duplicate). Custom hooks under `.claude/hooks/custom/` have different filenames, so they're never matched/displaced.
+- OVER: none. The function only APPENDS missing canonical hooks; it never reorders or removes existing entries, and it touches only the `Bash` matcher. Slopcheck-guard and all non-Bash matchers are untouched.
+
+## Signal vs authority
+N/A for blocking — this wires guardrail hooks into settings. Within the false-blocker design, `deferral-detector` is the SIGNAL (non-blocking checklist injection); `MessagingToneGate` B17 is the AUTHORITY (already live). This change lights up the signal layer on existing agents; it adds no new blocking authority.
+
+## Idempotency / migration parity
+- IS a migration-parity fix. New-agent path (init.ts) and existing-agent path (migrateSettings) now consume the SAME constant — drift is impossible by construction; an anti-drift unit test locks the canonical filename set.
+- `ensureInstarBashPreToolUseHooks` is idempotent (filename-substring presence check, robust to `${CLAUDE_PROJECT_DIR}` vs absolute path); re-runs are no-ops (verified).
+- No config or CLAUDE.md change. No new hook scripts (all four already ship + are ESM-safe).
+
+## Interactions
+- Runs before the existing slopcheck ensure-block; since it creates the `Bash` matcher when absent, slopcheck's "no Bash matcher" branch becomes a no-op while its "add slopcheck" branch still fires. Both end states verified together in the parity test.
+- Codex hooks (`installCodexHooks.ts`, `.*` matcher) are a separate path, intentionally not governed by this module.
+
+## Rollback
+Revert the migrator call + the init refactor + delete the shared module (3 files) and the 2 test files. Worst case: existing agents return to the dark-guardrail state.
+
+## Tests
+- `tests/unit/instar-settings-hooks.test.ts` (16) — anti-drift contract, filename extraction, add/idempotent/preserve/no-matcher/no-dup/fresh-copy, init-imports-the-constant.
+- `tests/unit/PostUpdateMigrator-pretooluse-parity.test.ts` (3) — real `migrateSettings` against a stale agent home: wires the four, idempotent, reports each.
+- Regression-safety: `hook-installation.test.ts`, `installCodexHooks.test.ts`, `codexHookContractCanary.test.ts`, `autonomous-skill-deployment.test.ts`, `capabilities-discoverability.test.ts` all green post-refactor.
+
+## NOT in this commit (tracked)
+- Notify-on-stop (Task 2 — separate PR/spec).
+- Self-propagation harness (Task 4).

package/upgrades/side-effects/notify-on-stop-layer-a.md

@@ -0,0 +1,31 @@
+# Side-Effects Review — Notify-on-Stop, Layer A (autonomous-run-ended notice)
+
+**Spec:** docs/specs/NOTIFY-ON-STOP-SPEC.md (approved: true) — Layer A of two. Layer B (gate-fed unjustified-stop notice) ships as a separate PR.
+
+Closes the primary silent-stall scenario: an autonomous run reaching a terminal exit (completion / duration-expiry / emergency-stop) previously only echoed the reason to stderr — the terminal the user can't see — so the run could end in silence unless the agent *remembered* to send a final report (willpower, not structure). Justin's standing requirement: a session either keeps going OR tells you why it stopped.
+
+## What changed
+- `.claude/skills/autonomous/hooks/autonomous-stop-hook.sh` — added two helpers (`goal_snippet`, `notify_terminal_stop`) and a `notify_terminal_stop "<plain message>"` call before EACH of the six terminal exits (native-mode emergency + duration; legacy duration, emergency, completion-condition, completion-promise). Each sends ONE plain-English Telegram to the run's `report_topic` via `telegram-reply.sh` — the same transport the existing restart-resume recovery note uses.
+- `src/core/PostUpdateMigrator.ts` — bumped the autonomous-stop-hook capability marker from `Native /goal delegation` to `notify_terminal_stop` so existing agents on a prior stock hook receive the notify-enabled version on update (the marker+fingerprint mechanism; customized hooks left untouched).
+- `tests/unit/autonomous-stop-hook-notify.test.ts` — static wiring (helper defined + called at all 6 exits), functional delivery (runs the REAL extracted helper against a stub telegram-reply.sh; both no-op gates), and migration (a stock pre-notify hook gains `notify_terminal_stop`).
+
+## Behavior / safety
+- **Best-effort, non-blocking:** `notify_terminal_stop` ends every path with `|| true` and returns early if there's no report topic or the channel isn't telegram. A delivery failure NEVER changes the hook's exit code or blocks the terminal exit.
+- **Fires at most once per run:** every terminal branch removes the state file immediately after, so the hook can't re-enter and re-notify.
+- **No new transport / topic:** reuses `telegram-reply.sh` to the run's existing report topic. No new Telegram topic is ever created.
+
+## Over/under-notify
+- OVER: at completion, the agent's own final report (if it sent one) plus Layer A's brief "run finished" backstop = a possible second short message. Accepted — the structural guarantee that *something* is sent outweighs minor redundancy; the backstop is one line.
+- UNDER: a heavily-customized hook (no stock fingerprint) won't receive the migration — same accepted limit as every autonomous-hook migration. Channel != telegram → no send (Layer A is telegram-scoped; other channels await Channel Parity).
+
+## Near-silent compliance
+An autonomous run ending is an action-relevant, once-per-run event — exactly the kind the user asked to be told about. Not routine churn. No throttling needed (one message per terminal exit, max once per run).
+
+## Migration parity
+`migrateAutonomousStopHookTopicKeyed` (marker bump) ships the updated hook to existing agents; new agents get it via the bundled file at init. Verified by the migration test.
+
+## Rollback
+Revert the hook edits + the marker bump (2 files) + the test. Worst case: terminal exits go back to stderr-only.
+
+## NOT in this PR (tracked)
+- Layer B: gate-fed unjustified-mid-task-stop notice via the stop-gate evaluate route + a StopNotifier reusing SentinelNotifier's coalescing sink. Separate PR under the same spec.