instar 1.3.31 → 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.31",
+  "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-27T22:20:26.590Z",
-  "instarVersion": "1.3.31",
+  "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "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": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1481,7 +1481,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "7860b92b9c569b83a8f970a14bb1ffcaa5a95e1aa88d0b57814ae739ef535b38",
+      "contentHash": "7df6ffd4a8d6e5e8c98e888bed89fffec63347268d0a26819b8de60ab32cd347",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

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).