klypix-mcp 1.80.0 → 1.81.0

package/README.md

@@ -669,7 +669,7 @@ keep lazy first-use indexing instead.
   file paths involved). The scope is versioned: an older metadata-only grant does not authorize note
   text and must be granted again. No current consent, no frames.
 - **`install` writes to your home directory:** `~/.claude/project-brain` (engine + runtime),
-  `~/.claude/settings.json` (four hooks — written even if Claude Code is not installed),
+  `~/.claude/settings.json` (five hooks — written even if Claude Code is not installed),
   `~/.codex/AGENTS.md` (guidance block), and with `--codex-hooks`, `~/.codex/hooks.json`. It also
   writes `<cwd>/.codex/config.toml` **inside the project** you run it in, and removes any KLYPIX
   entry from the global `~/.codex/config.toml`. **`link` writes 14 files inside the project** you

package/bin/klypix-install.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // klypix-install — lay the project-brain down into ~/.claude/project-brain from THIS
-// package and wire the 4 Claude Code hooks into ~/.claude/settings.json. This makes
+// package and wire the 5 Claude Code hooks into ~/.claude/settings.json. This makes
 // npm the SINGLE delivery for the WHOLE brain (hook + engine + local MCP/A2A
 // servers), so one `gh release create` (OIDC auto-publish) + `npx klypix-mcp install`
 // updates every brain on a machine — the global ~/.claude/project-brain copy serves
@@ -427,7 +427,7 @@ try {
         type: 'module',
     }, null, 2));
 
-    // 5) wire the 4 hooks into settings.json (refuse on invalid JSON; back up;
+    // 5) wire the 5 hooks into settings.json (refuse on invalid JSON; back up;
     // atomic). A background runtime-only update refreshes the scripts while
     // deliberately preserving every host/project config byte.
     const brainCmd = (arg) => `node "${fwd(path.join(BRAIN_DIR, 'global-brain-hook.mjs'))}"${arg ? ' ' + arg : ''}`;
@@ -436,6 +436,10 @@ try {
         ['UserPromptSubmit', { hooks: [{ type: 'command', command: brainCmd('--prompt'), timeout: 10 }] }],
         ['Stop', { hooks: [{ type: 'command', command: brainCmd('--capture') }] }],
         ['PostToolUse', { matcher: 'Bash|PowerShell|Edit|Write', hooks: [{ type: 'command', command: brainCmd('--live'), timeout: 10 }] }],
+        // Guard cards (2026-08-24): pre-action lane. Fast path — reads only the
+        // compiled guard sidecar; 'warn' injects context, 'block' denies with
+        // the card's message. Absent guards = stat + one tiny read, then no-op.
+        ['PreToolUse', { matcher: 'Bash|PowerShell|Edit|Write', hooks: [{ type: 'command', command: brainCmd('--guard'), timeout: 10 }] }],
     ];
     const stripOurs = (arr) => (Array.isArray(arr) ? arr : [])
         .map(g => (g && Array.isArray(g.hooks)) ? { ...g, hooks: g.hooks.filter(h => !(typeof h?.command === 'string' && h.command.includes(HOOK_MARK))) } : g)
@@ -506,12 +510,12 @@ try {
     // Codex needs native MCP tools, conditional guidance, and lifecycle presence.
     const codex = RUNTIME_ONLY ? null : wireCodex();
 
-    // 8) READINESS check — re-read what we just wrote and confirm all 4 hooks actually
+    // 8) READINESS check — re-read what we just wrote and confirm all 5 hooks actually
     //    took (a malformed pre-existing group, a partial merge, or a later hand-edit can
     //    leave the brain LIVE but not LEARNING — liveness ≠ readiness). Warn, don't fail.
     const verify = RUNTIME_ONLY ? null : (() => { try { return JSON.parse(fs.readFileSync(SETTINGS, 'utf8')); } catch { return null; } })();
     const wiredFor = (evt) => Array.isArray(verify?.hooks?.[evt]) && verify.hooks[evt].some(g => Array.isArray(g?.hooks) && g.hooks.some(h => typeof h?.command === 'string' && h.command.includes(HOOK_MARK)));
-    const notWired = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse'].filter(e => !wiredFor(e));
+    const notWired = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse', 'PreToolUse'].filter(e => !wiredFor(e));
 
     releaseInstallLockSync(installLock);
     // Users who already enabled the optional local semantic runtime should not
@@ -538,13 +542,13 @@ try {
     if (!RUNTIME_ONLY) reportCodex(codex);
     console.log(`✓ installed klypix brain v${VERSION} → ${BRAIN_DIR}  (${n} scripts, ${deps} dep packages)`);
     if (RUNTIME_ONLY) console.log('✓ runtime-only update: host settings and project files were preserved');
-    else if (!notWired.length) console.log('✓ wired 4 hooks: SessionStart · UserPromptSubmit (--prompt) · Stop (--capture) · PostToolUse (--live) → settings.json');
+    else if (!notWired.length) console.log('✓ wired 5 hooks: SessionStart · UserPromptSubmit (--prompt) · Stop (--capture) · PostToolUse (--live) · PreToolUse (--guard) → settings.json');
     else console.error(`⚠ readiness: ${notWired.length} hook(s) did NOT take (${notWired.join(', ')}) — the brain will read but not capture/sync. Re-run \`npx klypix-mcp install --force\` or check ${SETTINGS}.`);
     console.log(`✓ MCP supervisor runs from the local bundle (node ${fwd(path.join(BRAIN_DIR, 'klypix-mcp-server.mjs'))}) — compatible core updates activate without restarting the host.`);
     if (migrated) console.log(`✓ migrated ${migrated.file} klypix-canvas server: ${migrated.from} → ${migrated.to} (backup: .mcp.json.klypix-bak). Reconnect (/mcp) or restart to pick it up.`);
     if (!RUNTIME_ONLY) {
         console.log('  Claude Code keeps its existing auto-brief/capture hooks; Codex gets the brain_sync Context Gateway (compact task memory + clean peers + proactive/guaranteed conflict alerts) with no hook trust prompt.');
-        console.log('  Enhanced Codex auto-context + pre-edit overlap guard: re-run with `--codex-hooks`, then approve/review KLYPIX once in a Codex surface that supports hook trust.');
+        console.log('  Enhanced Codex auto-context + pre-edit overlap warning: re-run with `--codex-hooks`, then approve/review KLYPIX once in a Codex surface that supports hook trust.');
     }
     console.log('  Compatible brain-core updates hot-swap behind the same MCP connection. Only the one-time legacy→supervisor migration, a supervisor change, or an intentionally breaking tool/protocol change needs reconnect.');
 

package/bin/klypix-worker.mjs

@@ -103,7 +103,7 @@ await runVerb('install', './klypix-install.mjs');
 await runVerb('link', './klypix-link.mjs');
 
 // `npx klypix-mcp doctor` — the brain's READ-ONLY self-check: is this machine's brain
-// current, are the 4 hooks wired, what verbs does it expose, who's live, is the harness
+// current, are the 5 hooks wired, what verbs does it expose, who's live, is the harness
 // projection in sync? One verdict, one reconcile block. Exits 1 on drift (CI gate).
 await runVerb('doctor', './klypix-doctor.mjs');
 
@@ -683,12 +683,23 @@ server.registerTool('brain_note', {
     marker: z.enum(['', '?', '!', '+', '✓', '~']).optional().describe('(none)=decision · ?=open question · !=milestone · +=🛠️ skill (reusable how-to/gotcha; always resurfaces, never ages out) · ✓=resolve+archive the best-matching card · ~=update the matching card in place. Default: decision.'),
     area: z.string().optional().describe('Area/topic — routes the card into that titled container and becomes a #tag (e.g. "Auth", "Release").'),
     closes: z.string().optional().describe('Title or [[wikilink]] of a strategy/question card this note fulfils — resolves+archives it and draws a "closed by" arrow.'),
+    guard: z.object({
+      when: z.object({
+        tool: z.string().max(200).optional().describe('Regex matched against the tool name (e.g. "Bash", "Edit|Write").'),
+        command: z.string().max(200).optional().describe('Regex matched against the command string, for shell tools (e.g. "\\\\bgit\\\\s+stash\\\\b"). Anchor deliberately — an unanchored pattern also matches the words inside echo/commit-message text.'),
+        paths: z.array(z.string().max(200)).max(20).optional().describe('Path PREFIXES (forward-slash, project-relative) — the guard fires when the session\'s touched files match one. Prefixes, not regexes.'),
+        multiWorktree: z.literal(true).optional().describe('Fire only when the repo has more than one git worktree (probed live when the guard is in play).'),
+      }).optional().describe('When to interrupt — triggers are AND-ed; at least one required.'),
+      severity: z.enum(['warn', 'block']).optional().describe("warn (default) injects the message as context and the call proceeds; block DENIES the tool call with the message. 'block' is for irreversible actions and HUMAN-DIRECTED authoring only — never author block without explicit user instruction."),
+      message: z.string().max(500).optional().describe('What the interrupted session reads — say the trap and the safe alternative. Required unless remove:true.'),
+      remove: z.literal(true).optional().describe("Disarm: pass exactly { remove: true } with marker '~' matching the card to delete its machine trigger while keeping the prose rule."),
+    }).optional().describe("GUARD CARDS: make this '+' skill fire BEFORE a matching tool call runs (Claude Code PreToolUse denies on severity block; other hosts warn), not just resurface in briefs. The card stays a normal 🛠️ rule — ✓-resolving it retires the guard, ~ with {remove:true} disarms it."),
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
   },
-}, async ({ text, marker, area, closes, canvas }, extra) => {
+}, async ({ text, marker, area, closes, guard, canvas }, extra) => {
   // Both 1.77 and 1.78 ride this call: the enrichment question (the asker's
   // vocabulary for retrieval) AND the per-session capture receipt below.
-  const result = await opBrainNote({ vault: mcpPresence.vault, canvas: boundBrainCanvas(canvas), text, area, marker: marker || '', closes, via: extra.klypixClientName, enrichmentQuestion: mcpPresence.declaredIntent });
+  const result = await opBrainNote({ vault: mcpPresence.vault, canvas: boundBrainCanvas(canvas), text, area, marker: marker || '', closes, guard, via: extra.klypixClientName, enrichmentQuestion: mcpPresence.declaredIntent });
   // Per-session capture receipt — this is what stops the uncaptured-work nudge
   // from firing at a session that DID record its reasoning, just through MCP
   // rather than a 🧠 marker. The Stop hook and this server share one session-id
@@ -1019,7 +1030,7 @@ server.registerTool('brain_sync', {
 
 server.registerTool('brain_doctor', {
   title: 'Brain doctor — is this brain current, wired, and in sync?',
-  description: 'Read-only self-check of the installed klypix brain, as ONE verdict: VERSION (deployed brain-core + optional npm currency), CLAUDE (existing 4-hook capture readiness), CODEX (automatic MCP presence plus optional enhanced-hook status), TOOLS (discoverable MCP verbs), SESSIONS (all active presence-adapter sessions across hosts, never recent-chat history), and HARNESS (projection drift). Use to answer "is my brain current, correctly installed, in sync, and who is actually live?" without file-spelunking. Never writes. SCOPE: only CLAUDE and CODEX get behavioural verdicts. HARNESS classifies the projected config/rules FILES on disk — a project can read fully ok while no other host has ever actually loaded them, so do not report a clean HARNESS as "Cursor/Cline/Windsurf/Copilot is working". The MCP-callable twin of `npx klypix-mcp doctor`.',
+  description: 'Read-only self-check of the installed klypix brain, as ONE verdict: VERSION (deployed brain-core + optional npm currency), CLAUDE (existing 5-hook capture readiness), CODEX (automatic MCP presence plus optional enhanced-hook status), TOOLS (discoverable MCP verbs), SESSIONS (all active presence-adapter sessions across hosts, never recent-chat history), and HARNESS (projection drift). Use to answer "is my brain current, correctly installed, in sync, and who is actually live?" without file-spelunking. Never writes. SCOPE: only CLAUDE and CODEX get behavioural verdicts. HARNESS classifies the projected config/rules FILES on disk — a project can read fully ok while no other host has ever actually loaded them, so do not report a clean HARNESS as "Cursor/Cline/Windsurf/Copilot is working". The MCP-callable twin of `npx klypix-mcp doctor`.',
   inputSchema: {
     project: z.string().optional().describe('Project dir to audit harness + peers for. Defaults to the server\'s working directory.'),
     check_npm: z.boolean().optional().describe('Also fetch npm latest to flag a stale brain (default false — this one does a network `npm view`).'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.80.0",
+  "version": "1.81.0",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
   "license": "Apache-2.0",
@@ -83,7 +83,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/plan-fulfillment.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/enrichment.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/publish-verdict.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/plan-fulfillment.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/enrichment.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"

package/src/brain-doctor.mjs

@@ -68,7 +68,7 @@ const readText = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { ret
 const cmpSemver = (a, b) => { const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0), pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0); for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); } return 0; };
 
 const HOOK_MARK = 'global-brain-hook';
-const HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse'];
+const HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse', 'PreToolUse'];
 // Liveness windows imported from the canonical rule; literals are the LAST
 // RESORT for a bundle whose agent-presence predates the exports.
 const SESSION_FRESH_MS = Number(presenceLib?.SESSION_FRESH_MS) > 0
@@ -568,7 +568,14 @@ export function inspect(opts = {}) {
     autoUpdate: !autoUpdate.enabled
       ? 'off'
       : (autoUpdate.result === 'failed' || Number(autoUpdate.harness?.failed || 0) > 0 ? 'warning' : 'ok'),
-    hooks: !hooks.settingsPresent ? 'absent' : (hooks.missing.length ? 'drift' : 'ok'),
+    // Grace for the 1.81 hook addition (adversarial review 2026-08-24): a
+    // machine whose only missing event is the NEW PreToolUse guard lane is a
+    // valid pre-guard install, not a drifted one — hard-failing every existing
+    // machine the day the event ships teaches people to ignore the doctor.
+    // Any OTHER missing event still reads as drift.
+    hooks: !hooks.settingsPresent ? 'absent'
+      : (hooks.missing.some((e) => e !== 'PreToolUse') ? 'drift'
+        : (hooks.missing.length ? 'warning' : 'ok')),
     // Codex MCP presence is the automatic baseline. Hooks are an OPTIONAL
     // enrichment layer, so off/unverified must never make the brain "drifted".
     codexHooks: codexHooks.error
@@ -767,8 +774,9 @@ export function render(r, opts = {}) {
   // Host adapters
   const hmark = r.layers.hooks === 'ok' ? ok : warn;
   if (!r.hooks.settingsPresent) L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   no ~/.claude/settings.json found`);
+  else if (r.hooks.missing.length === 1 && r.hooks.missing[0] === 'PreToolUse') L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   capture path intact; ${c.yel}guard lane not wired yet${c.rst} — \`npx klypix-mcp install\` adds the PreToolUse hook (guard cards)`);
   else if (r.hooks.missing.length) L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   half-wired — missing: ${c.yel}${r.hooks.missing.join(', ')}${c.rst}  ${c.dim}(liveness up, readiness no)${c.rst}`);
-  else L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   existing 4-hook capture path intact: ${r.hooks.wired.join(', ')}`);
+  else L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   existing 5-hook capture path intact: ${r.hooks.wired.join(', ')}`);
   const chmark = r.layers.codexHooks === 'warning' ? warn : ok;
   const smart = r.codexSmart?.globalInstructions
     ? 'approval-free Context Gateway active (task memory + clean peers + proactive/guaranteed alerts)'
@@ -781,7 +789,7 @@ export function render(r, opts = {}) {
     L.push(`${chmark} ${c.bold}CODEX${c.rst}    automatic MCP presence + ${smart} · ${c.yel}native hooks configured but execution not verified${c.rst}`);
     L.push(`        ${c.dim}Context Gateway memory/coordination already works. Once trusted, native hooks auto-inject task memory and warn before exact overlapping edits.${c.rst}`);
   } else {
-    L.push(`${chmark} ${c.bold}CODEX${c.rst}    automatic MCP presence + ${smart} · native auto-context + pre-edit guard active ${c.dim}(last observed ${r.codexHooks.lastExecutedAt})${c.rst}`);
+    L.push(`${chmark} ${c.bold}CODEX${c.rst}    automatic MCP presence + ${smart} · native auto-context + pre-edit overlap warning active ${c.dim}(last observed ${r.codexHooks.lastExecutedAt})${c.rst}`);
   }
   // Commit-capture git hook — per-repo, informational (auto-installed at
   // session start where safe; foreign hooks are never edited automatically).

package/src/codex-brain-hook.mjs

@@ -236,8 +236,12 @@ function formatConflictWarning(conflicts, event, sessions = []) {
   // Grow each shown id (floor 12) until unique — same-window UUIDv7 peers
   // otherwise render as one ambiguous prefix.
   const shortId = (id) => shortestUniqueSessionPrefix(sessions, id, 12) || String(id).slice(0, 12);
+  // Claims discipline (2026-08-24 audit): this hook is ADVISORY — the output
+  // envelope hardcodes `continue: true` and never denies a tool call — so the
+  // banner must say WARNING, never BLOCKING. Urgency comes from the imperative
+  // closing line, not from claiming a mechanism that does not exist.
   return [
-    `KLYPIX BLOCKING exact-file overlap detected ${moment}:`,
+    `KLYPIX ⚠️ WARNING — exact-file overlap detected ${moment}:`,
     ...conflicts.map((peer) => {
       // Observed/declared distinction (1.70.0): a `*` marks a path whose claim
       // was adopted from live edits, not declared — real overlap, unconfirmed
@@ -249,6 +253,43 @@ function formatConflictWarning(conflicts, event, sessions = []) {
   ].join('\n');
 }
 
+// Guard cards, Codex advisory tier (2026-08-24): read the compiled sidecar the
+// Claude-side lanes build (one keying rule — brainFormat.guardSidecarPathFor)
+// and evaluate against this tool event. Typeof-guarded so a bundle whose
+// klypix-format predates guards degrades to silence, never a throw. This lane
+// only ever WARNS: block-severity guards are named as such so the model treats
+// them as a hard stop, but no mechanism here denies anything.
+async function guardWarnings(projectDir, brainPath, input) {
+  try {
+    if (typeof brainFormat.evaluateGuards !== 'function'
+      || typeof brainFormat.ensureGuardSidecar !== 'function') return '';
+    // ensureGuardSidecar is currency-checked and BUILDS when absent — on a
+    // Codex-only machine no Claude lane ever compiles the sidecar, and before
+    // this the advisory tier was silently dead there (review 2026-08-24). This
+    // hook already pays the heavy import, so the occasional rebuild is fine.
+    const ensured = await brainFormat.ensureGuardSidecar(brainPath);
+    const guards = Array.isArray(ensured.guards) ? ensured.guards : [];
+    if (!guards.length) return '';
+    const files = touchedFiles(input, projectDir);
+    const cmd = toolInput(input).command;
+    const needWt = guards.some((g) => g?.when?.multiWorktree);
+    const fired = brainFormat.evaluateGuards(guards, {
+      toolName: toolName(input),
+      command: typeof cmd === 'string' ? cmd : '',
+      files: files.length ? files : null,
+      worktreeCount: needWt && typeof brainFormat.probeWorktreeCount === 'function'
+        ? brainFormat.probeWorktreeCount(projectDir) : null,
+    });
+    if (!fired.length) return '';
+    const lines = fired.map((f) => {
+      const hard = f.guard.severity === 'block' ? ' (BLOCK-severity rule — this host cannot enforce it; treat as a hard stop)' : '';
+      const note = f.unverified.length ? ` (could not verify: ${f.unverified.join(', ')})` : '';
+      return `- [${f.guard.area || 'brain'}]${hard} ${f.guard.message}${note}`;
+    });
+    return `🛡️ KLYPIX guard — a standing rule matches this action:\n${lines.join('\n')}\nApply the rule, or proceed deliberately if it does not fit this case.`;
+  } catch { return ''; }
+}
+
 function queueConflictAlerts({ brainPath, sessionId, intent, conflicts, turnId, sessions = [] }) {
   const queued = [];
   const selfShortId = shortestUniqueSessionPrefix(sessions, sessionId, 12) || String(sessionId).slice(0, 12);
@@ -401,6 +442,11 @@ async function main() {
   if (event === 'PreToolUse' || event === 'PostToolUse') {
     emitSystemMessage([
       formatConflictWarning(conflicts, event, sessions),
+      // Guard cards, advisory tier (2026-08-24): this host cannot deny a tool
+      // call — Codex hook output is `continue: true` by design — so a matching
+      // guard renders as a warning; a block-severity guard says it should be
+      // treated as a hard stop, without claiming a mechanism this lane lacks.
+      ...(event === 'PreToolUse' ? [await guardWarnings(projectDir, brainPath, input)] : []),
       stampReceivedMessages(messages, Date.now(), undefined, sessionId),
     ], event);
     return;

package/src/global-brain-hook.mjs

@@ -3165,11 +3165,188 @@ function pruneCacheDir(keep = 40) {
 // mtime-keyed parse cache so we don't unzip the brain on every prompt.
 async function cachedStruct(lib) {
     let mtimeMs = 0; try { mtimeMs = fs.statSync(BRAIN).mtimeMs; } catch { /* */ }
-    try { const c = JSON.parse(fs.readFileSync(CACHE, 'utf8')); if (c && c.mtimeMs === mtimeMs && c.struct) return c.struct; } catch { /* miss */ }
+    try {
+        const c = JSON.parse(fs.readFileSync(CACHE, 'utf8'));
+        if (c && c.mtimeMs === mtimeMs && c.struct) { refreshGuardSidecar(lib, c.struct, mtimeMs); return c.struct; }
+    } catch { /* miss */ }
     const { struct } = await lib.parseKlypix(fs.readFileSync(BRAIN));
     try { fs.writeFileSync(CACHE, JSON.stringify({ mtimeMs, struct })); pruneCacheDir(); } catch { /* cache is best-effort */ }
+    refreshGuardSidecar(lib, struct, mtimeMs);
     return struct;
 }
+// ── Guard cards: sidecar compiler (2026-08-24) ───────────────────────────────
+// The PreToolUse --guard lane avoids parsing the brain (~1s measured on the
+// live brain) on its COMMON path — guards are COMPILED into a tiny per-brain
+// sidecar wherever the struct is already warm: every lane that goes through
+// cachedStruct (--prompt retrieval, status queries) plus the Stop capture lane
+// (wired in main() — the brain just changed there). The fast path adds a
+// currency stat: a stale/missing sidecar pays ONE rebuild via the shared
+// lib.ensureGuardSidecar, so a ✓-resolved guard stops firing on the very next
+// call, not at the next lucky prompt. worktreeCount stored here is a snapshot
+// fallback only — guardCheck probes LIVE when a multiWorktree guard is in play.
+// Key derivation MUST byte-match klypix-format.guardSidecarPathFor (asserted
+// by test/guard-cards.mjs G5): win32 folds the WHOLE path — hosts reach one
+// brain through differently-cased CWDs and a case-split key half-blinds them.
+const guardKeyNorm = (p) => (process.platform === 'win32'
+    ? String(p).replace(/\\/g, '/').toLowerCase()
+    : normBrainPath(p));
+const GUARDS_SIDECAR = path.join(os.homedir(), '.claude', 'project-brain', `.guards-${sha(guardKeyNorm(BRAIN))}.json`);
+const GUARDS_SEEN = path.join(os.homedir(), '.claude', 'project-brain', `.guards-seen-${sha(guardKeyNorm(BRAIN))}.json`);
+function refreshGuardSidecar(lib, struct, mtimeMs) {
+    try {
+        if (typeof lib.compileGuards !== 'function') return;           // version-skew: older format lib
+        try {
+            const cur = JSON.parse(fs.readFileSync(GUARDS_SIDECAR, 'utf8'));
+            if (cur && cur.mtimeMs === mtimeMs) return;                 // current — nothing to do
+        } catch { /* absent/stale → rebuild */ }
+        const guards = lib.compileGuards(struct);
+        let worktreeCount = null;
+        if (guards.some((g) => g.when && g.when.multiWorktree)) {
+            try {
+                const out = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+                    cwd: CWD, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500,
+                });
+                worktreeCount = out.split('\n').filter((l) => l.startsWith('worktree ')).length;
+            } catch { worktreeCount = null; }                           // unknown, never 0/1
+        }
+        fs.mkdirSync(path.dirname(GUARDS_SIDECAR), { recursive: true });
+        // Atomic (tmp+rename): several sessions' hooks read this concurrently —
+        // a torn half-write must never be readable as an empty guard set.
+        const tmp = `${GUARDS_SIDECAR}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify({ v: 1, mtimeMs, builtAt: Date.now(), brainPath: BRAIN, worktreeCount, guards }));
+        fs.renameSync(tmp, GUARDS_SIDECAR);
+    } catch { /* best-effort here — guardCheck's own currency check rebuilds via ensureGuardSidecar when this lane failed */ }
+}
+// --guard (PreToolUse): the fast path. Budget discipline: stat + one tiny JSON
+// read on the common no-guards case; the heavy klypix-format import is paid
+// ONLY when a compiled guard's tool pattern could match this call. Never
+// throws, never blocks on its own failure (the harness is fail-open on hook
+// errors anyway — only a deliberate deny blocks).
+async function guardCheck() {
+    try {
+        const input = readHookInput();
+        const toolName = String(input.tool_name || '');
+        if (!toolName) return;
+        // CURRENCY FIRST (adversarial review 2026-08-24, both criticals): a
+        // sidecar that predates the brain's mtime may be denying from a card
+        // the user already ✓-resolved — the advertised recovery loop was
+        // impossible while this lane trusted stale compiled state. One statSync
+        // (~0.03ms) keeps the common current-path fast; a mismatch (or missing
+        // sidecar) pays ONE rebuild via the shared ensureGuardSidecar, after
+        // which this brain is fast again until its next edit.
+        let brainMtime = 0;
+        try { brainMtime = fs.statSync(BRAIN).mtimeMs; } catch { return; }
+        let sidecar = null;
+        try { sidecar = JSON.parse(fs.readFileSync(GUARDS_SIDECAR, 'utf8')); } catch { sidecar = null; }
+        let guards = (sidecar && sidecar.mtimeMs === brainMtime && Array.isArray(sidecar.guards)) ? sidecar.guards : null;
+        let sidecarUnverifiable = false;
+        if (!guards) {
+            const lib = await import('./klypix-format.mjs');
+            if (typeof lib.ensureGuardSidecar !== 'function') return;    // version-skew: older format lib
+            const ensured = await lib.ensureGuardSidecar(BRAIN);
+            if (ensured.guards) { guards = ensured.guards; sidecar = ensured; }
+            else if (sidecar && Array.isArray(sidecar.guards)) {
+                // Rebuild failed but stale guards exist: they are UNVERIFIABLE
+                // as current — blocks degrade to warn (refuse-not-exempt), and
+                // warns still fire (a stale warn is at worst noise).
+                guards = sidecar.guards; sidecarUnverifiable = true;
+            } else return;                                               // no guards ever compiled and rebuild failed → silent
+        }
+        if (!guards.length) return;
+        // Inline tool prefilter (regex compile is cheap; the LIB import is
+        // not). A pattern that fails to COMPILE stays in — the evaluator
+        // reports it unverifiable rather than this filter silently dropping it.
+        const might = guards.filter((g) => {
+            const t = g?.when?.tool;
+            if (!t) return true;
+            try { return new RegExp(String(t).slice(0, 200), 'i').test(toolName); } catch { return true; }
+        });
+        if (!might.length) return;
+        const lib = await import('./klypix-format.mjs');
+        if (typeof lib.evaluateGuards !== 'function') return;
+        const ti = input.tool_input && typeof input.tool_input === 'object' ? input.tool_input : {};
+        const command = typeof ti.command === 'string' ? ti.command : '';
+        // paths input: the direct target for file tools; this session's
+        // observed/declared scope (the live lane row) for shell commands —
+        // `git push` names no paths, but the session's touched files do.
+        // null = COULD NOT DETERMINE (out-of-project target, empty/absent lane
+        // row): an empty list must never read as verified-no-match (review
+        // 2026-08-24 — files:[] silently exempted paths guards).
+        let files = null;
+        const direct = [ti.file_path, ti.path, ti.notebook_path].find((v) => typeof v === 'string' && v);
+        if (direct) { const rel = projRelPath(direct); files = rel ? [rel] : null; }
+        else {
+            try {
+                const me = readSessions().find((s) => s.id === input.session_id);
+                if (me && Array.isArray(me.files) && me.files.length) files = me.files;
+            } catch { files = null; }
+        }
+        // multiWorktree is probed LIVE when a candidate needs it — the count
+        // changes independently of the brain, so a snapshot both false-denies
+        // (worktree removed since compile) and silently exempts (added since).
+        // Rare path: only pays the bounded git spawn when such a guard survived
+        // the tool prefilter. Probe failure → null → unverified → degrade.
+        const worktreeCount = might.some((g) => g?.when?.multiWorktree)
+            ? (typeof lib.probeWorktreeCount === 'function' ? lib.probeWorktreeCount(CWD) : null)
+            : null;
+        let fired = lib.evaluateGuards(might, { toolName, command, files, worktreeCount });
+        if (sidecarUnverifiable) fired = fired.map((f) => ({ ...f, unverified: [...new Set([...f.unverified, 'sidecarCurrency'])] }));
+        if (!fired.length) return;
+        // A verified block denies. An UNVERIFIED block (an input was
+        // unavailable) degrades to warn and says so — never silently exempt,
+        // never false-block.
+        const blocks = fired.filter((f) => f.guard.severity === 'block' && !f.unverified.length);
+        if (blocks.length) {
+            const b = blocks[0].guard;
+            const title = String(b.title || '').slice(0, 80);
+            process.stdout.write(JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: `🛡️ KLYPIX guard [${b.area || 'brain'}]: ${b.message} (standing rule${title ? ` “${title}”` : ''} — if this block is wrong, retire it with brain_note marker '✓'${title ? ` text "${title}"` : ''}, or disarm with marker '~' and guard {remove:true}; the change takes effect on the next call)`,
+                },
+            }));
+            return;
+        }
+        // Once-per-session dedup applies ONLY to plain warns. A degraded BLOCK
+        // is standing in for a deny — it must keep firing on every matching
+        // call, or the second dangerous command sails through in silence
+        // (review 2026-08-24).
+        const degraded = fired.filter((f) => f.guard.severity === 'block');
+        const plainWarns = fired.filter((f) => f.guard.severity !== 'block');
+        const sid = String(input.session_id || '');
+        let seen = {};
+        try { seen = JSON.parse(fs.readFileSync(GUARDS_SEEN, 'utf8')) || {}; } catch { seen = {}; }
+        const mine = (seen[sid] && typeof seen[sid] === 'object') ? seen[sid] : {};
+        const freshWarns = plainWarns.filter((f) => !mine[f.guard.id]);
+        const show = [...degraded, ...freshWarns];
+        if (!show.length) return;
+        const lines = show.map((f) => {
+            const note = f.unverified.length
+                ? (f.guard.severity === 'block'
+                    ? ` (BLOCK-severity rule degraded to a warning — could not verify: ${f.unverified.join(', ')}; treat as a hard stop)`
+                    : ` (could not verify: ${f.unverified.join(', ')})`)
+                : '';
+            return `- [${f.guard.area || 'brain'}] ${f.guard.message}${note}`;
+        });
+        try {
+            const now = Date.now();
+            for (const f of freshWarns) mine[f.guard.id] = now;
+            const pruned = {};                                          // drop sessions idle >24h
+            for (const [k, v] of Object.entries({ ...seen, [sid]: mine })) {
+                const newest = Math.max(0, ...Object.values(v && typeof v === 'object' ? v : {}));
+                if (now - newest < 24 * 60 * 60 * 1000) pruned[k] = v;
+            }
+            fs.writeFileSync(GUARDS_SEEN, JSON.stringify(pruned));
+        } catch { /* dedup is best-effort — worst case a warn repeats */ }
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                additionalContext: `🛡️ KLYPIX guard — a standing rule matches what you are about to do:\n${lines.join('\n')}\nApply the rule, or proceed deliberately if it does not fit this case.`,
+            },
+        }));
+    } catch { /* never throw — the guard lane must not be able to break a tool call by failing */ }
+}
 // Generic directory names anchor to a huge fraction of the brain, so they drown
 // out the prompt's real intent — keep precise basenames, drop the generic dirs.
 const GENERIC_DIRS = new Set(['src', 'app', 'lib', 'components', 'component', 'canvas', 'scripts', 'dist', 'build', 'public', 'tabs', 'interaction', 'items', 'hooks', 'utils', 'dashboard', 'core', 'api', 'test', 'tests', 'assets', 'styles', 'types', 'electron']);
@@ -3710,7 +3887,7 @@ function doctorFooter() {
             return Array.isArray(groups) && groups.some(g => Array.isArray(g?.hooks)
                 && g.hooks.some(h => typeof h?.command === 'string' && h.command.includes('global-brain-hook')));
         };
-        const missing = [['UserPromptSubmit', 'per-prompt recall'], ['Stop', 'decision capture'], ['PostToolUse', 'live sync']]
+        const missing = [['UserPromptSubmit', 'per-prompt recall'], ['Stop', 'decision capture'], ['PostToolUse', 'live sync'], ['PreToolUse', 'guard cards (pre-action warnings)']]
             .filter(([evt]) => !wiredFor(evt));
         if (!missing.length) return '';
         return '\n\n---\n## ⚠️ Brain half-wired — readiness\n'
@@ -4035,6 +4212,10 @@ async function main() {
     // one tiny locked append. It must NOT pay the lazy klypix-format import, so it
     // runs BEFORE everything else and returns. (Fires on Bash|PowerShell|Edit|Write.)
     if (process.argv.includes('--live')) { liveCapture(); return; }
+    // --guard (PreToolUse) is the second fast path: stat + sidecar read on the
+    // common case; it lazy-imports the lib itself only when a compiled guard's
+    // tool pattern could match this call. Runs before the unconditional import.
+    if (process.argv.includes('--guard')) { await guardCheck(); return; }
     const lib = await import('./klypix-format.mjs');    // lazy: only when a brain exists
     // Per-prompt retrieval runs on EVERY prompt — skip the registry write and
     // go straight to the (mtime-cached) ranked lookup to keep it cheap.
@@ -4046,6 +4227,11 @@ async function main() {
         // try/finally so the clear runs across capture()'s early returns AND a throw
         // (on throw, ship/milestone re-capture next Stop; a version is on disk — no loss).
         try { await capture(lib); } finally { clearLiveLedgerForSession(readHookInput().session_id); }
+        // The capture just changed the brain — recompile the guard sidecar now
+        // (off the critical path) so the next PreToolUse reads current state
+        // without paying the rebuild itself. Best-effort; guardCheck's currency
+        // stat is the backstop.
+        try { if (typeof lib.ensureGuardSidecar === 'function') await lib.ensureGuardSidecar(BRAIN); } catch { /* backstopped */ }
         // Ambient version-currency: piggyback the post-session Stop hook to refresh the
         // npm-latest cache (≤ once/day, best-effort, failure-silent) so the next
         // SessionStart footer can surface a stale install with ZERO network. Awaited so
@@ -4064,7 +4250,7 @@ if (!process.env.KLYPIX_BRAIN_NO_MAIN) {
         // here. Now it leaves a breadcrumb — without breaking the never-throw,
         // always-exit-0 contract.
         try {
-            const mode = process.argv.includes('--prompt') ? 'prompt' : process.argv.includes('--capture') ? 'capture' : 'read';
+            const mode = process.argv.includes('--prompt') ? 'prompt' : process.argv.includes('--capture') ? 'capture' : process.argv.includes('--guard') ? 'guard' : 'read';
             appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode, ok: false, err: String((e && e.message) || e).slice(0, 200) }, 500);
         } catch { /* even the breadcrumb is best-effort */ }
     }).finally(() => process.exit(EXIT_CODE));

package/src/klypix-core.mjs

@@ -32,7 +32,7 @@ import {
   brainLensData, lensToMarkdown, deathDateOfCard,
   statusContextToMarkdown, findFulfillmentCandidates,
   splitQueryTokens, scoreCardsAgainstQuery, correctionOverlaysFor,
-  isFastDecayCard, isUnresolvedOpenCard, isSkillCard, DECAY_STALE_MS, formatDecayAge,
+  isFastDecayCard, isUnresolvedOpenCard, isSkillCard, validateGuard, guardSidecarPathFor, ensureGuardSidecar, DECAY_STALE_MS, formatDecayAge,
   isPlanCard, planFulfillmentFor, PLAN_PAIR_SIM_BRAIN, isAgconfTwinId,
   readPendingShips, clearPendingShips, pendingShipCards, formatCaptureReceipts,
 } from './klypix-format.mjs';
@@ -1222,14 +1222,25 @@ export async function opAddToCanvas({ vault, canvas, cards, connections, via })
 // open file any agent reads AND writes": a hookless client (Cursor/Cline/Desktop)
 // can now record a decision, ask an open question, mark a milestone, resolve a card,
 // or correct one — with the full lifecycle, not just a flat append.
-export async function opBrainNote({ vault, canvas, text: noteText, area, marker = '', closes, via, enrichmentQuestion = '' }) {
+export async function opBrainNote({ vault, canvas, text: noteText, area, marker = '', closes, via, guard = null, enrichmentQuestion = '' }) {
   const t = brainTarget(vault, canvas);
   if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
   if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>".`);
   const file = t.file;
   if (!noteText || !String(noteText).trim()) return err('brain_note needs a non-empty text.');
   if (!['', '?', '!', '✓', '~', '+'].includes(marker)) return err(`Invalid marker "${marker}" — use: (none)=decision · ?=open question · !=milestone · +=skill (reusable how-to) · ✓=resolve a matching card · ~=update a matching card.`);
-  const input = noteToCaptureInput({ text: noteText, area, marker, closes: closes || '', createdVia: via || 'mcp' });
+  // Guard cards (2026-08-24): a guard is authored on a '+' skill (or amended
+  // via '~'). Validation is FAIL-LOUD — a malformed guard is an error naming
+  // the defect, never a silently-dropped field (the exact bug class this
+  // subsystem's audit found in the evidence/verify plumbing).
+  let guardField = null;
+  if (guard !== null && guard !== undefined) {
+    if (marker !== '+' && marker !== '~') return err("guard rides a '+' skill card (or a '~' amendment of one) — pass marker: '+' with the guard.");
+    const v = validateGuard(guard);
+    if (!v.ok) return err(`Invalid guard: ${v.reason}`);
+    guardField = v.guard;
+  }
+  const input = noteToCaptureInput({ text: noteText, area, marker, closes: closes || '', guard: guardField, createdVia: via || 'mcp' });
   // Deliver any queued out-of-session ship observations on THIS write. The
   // Claude Stop hook is not the only writer — an MCP-only or Codex-driven
   // project would otherwise queue observations that never drain (2026-07-29
@@ -1281,6 +1292,14 @@ export async function opBrainNote({ vault, canvas, text: noteText, area, marker
     // write-side ⏳/⚠️ nudges existed only on one host brand.
     const receipts = formatCaptureReceipts(s);
     const rc = receipts.length ? `\n${receipts.join('\n')}` : '';
+    // Guard sidecar refresh (2026-08-24 review): this verb is the surface that
+    // AUTHORS and RETIRES guards, and on a hookless machine (Codex/Cursor-only)
+    // nothing else ever compiles them. Refresh when a guard was passed OR a
+    // sidecar already exists for this brain (a guard system is in use — a
+    // ✓/~ note may have just retired one). Guard-less projects pay nothing.
+    try {
+      if (guardField || fs.existsSync(guardSidecarPathFor(file))) await ensureGuardSidecar(file);
+    } catch { /* best-effort — the hook's currency check is the backstop */ }
     return { blocks: [text(`✓ brain_note → ${path.basename(file)} (via ${t.how}) · ${bits.join(' · ')}. Reopen the brain in the KLYPIX app to see it.${corr}${rc}`)] };
   } catch (e) {
     return err(`brain_note failed (brain unchanged): ${e.message}`);

package/src/klypix-format.mjs

@@ -10,6 +10,7 @@ import JSZip from 'jszip';
 import path from 'path';
 import fs from 'fs';
 import os from 'os';
+import crypto from 'crypto';
 import { execFileSync } from 'child_process';
 import { generateKeyBetween } from 'fractional-indexing';
 
@@ -381,6 +382,9 @@ export async function parseKlypix(buffer) {
             // else parsed from prose so non-hook-authored cards count too.
             verify: (typeof it.verify === 'string' && it.verify.trim()) ? it.verify.trim()
                 : (it.type === 'text' ? parseVerifySuffix(it.content) : null),
+            // Guard trigger (guard cards, 2026-08-24) — additive machine field;
+            // exposed so compileGuards can read it off the parsed struct.
+            ...(it.guard && typeof it.guard === 'object' ? { guard: it.guard } : {}),
             // Machine death-date (epoch ms) written by the gardener at
             // consolidation — the prose "⤵ consolidated" stamp's reliable twin,
             // so as_of time-travel never depends on parsing prose.
@@ -515,6 +519,12 @@ export async function buildKlypix(spec) {
         if (card.type === 'text') {
             return {
                 type: 'text', locked: false, createdAt: now, createdBy: 'agent', ...authorField(),
+                // Machine-field parity with the other writers (2026-08-24) —
+                // additive, ignored by older readers.
+                ...(card.createdVia ? { createdVia: String(card.createdVia) } : {}),
+                ...(Array.isArray(card.evidence) && card.evidence.length ? { evidence: card.evidence } : {}),
+                ...(typeof card.verify === 'string' && card.verify.trim() ? { verify: card.verify.trim() } : {}),
+                ...(card.guard && typeof card.guard === 'object' ? { guard: card.guard } : {}),
                 content: String(card.text ?? ''), fontSize: FONT,
                 // PLAIN text (no border) renders at max-content width unless
                 // authoredWidth pins the wrap — without it a long single line
@@ -613,6 +623,7 @@ export async function appendToKlypix(buffer, addition) {
         zip.file(`items/${shard(a.id)}/${a.id}.json`, JSON.stringify({
             type: 'text', locked: false, createdAt: now, createdBy: 'agent', ...authorField(),
             ...(a.card.createdVia ? { createdVia: String(a.card.createdVia) } : {}),
+            ...(a.card.guard && typeof a.card.guard === 'object' ? { guard: a.card.guard } : {}),
             content: String(a.card.text), fontSize: FONT,
             color: a.card.color || '#1a1a1f', border: !!a.card.border, borderColor: '#1e1e2e',
             heading: !!a.card.heading, fontFamily: 'Thmanyah Sans',
@@ -793,6 +804,8 @@ export async function appendIntoContainers(buffer, addition) {
             ...(Array.isArray(card.evidence) && card.evidence.length ? { evidence: card.evidence } : {}),
             // Live-probe command for a fast-decay claim — additive, ignored by older readers.
             ...(typeof card.verify === 'string' && card.verify.trim() ? { verify: card.verify.trim() } : {}),
+            // Guard trigger — additive, ignored by older readers (guard cards).
+            ...(card.guard && typeof card.guard === 'object' ? { guard: card.guard } : {}),
             content: wrapped, fontSize: G.FONT,
             color: card.color || '#e8e8ed', border: true, borderColor: card.borderColor || card.color || 'rgba(16,185,129,0.45)',
             fillColor: 'rgba(18,18,26,0.85)', heading: !!card.heading, fontFamily: 'Thmanyah Sans',
@@ -1404,6 +1417,31 @@ export async function arrangeBrain(buffer, opts = {}) {
         canvas.connections = conns;
 
         // 4. Physically remove the losers (item file + position + order slot).
+        // 3.5 Machine-field rescue (adversarial review 2026-08-24): a loser
+        // twin can be the ONLY carrier of guard/evidence/verify — a ~ amendment
+        // bumps createdAt and the survivor tiebreak prefers OLDEST, so the
+        // amended, guard-carrying copy is exactly the copy that loses. The
+        // lossless post-verify checks TEXTS, not machine fields, so this loss
+        // shipped green. Merge absent machine fields onto the survivor before
+        // the loser's bytes are deleted; prose is untouched.
+        const readItemJson = async (id) => {
+            const f = zip.file(`items/${shard(id)}/${id}.json`);
+            if (!f) return null;
+            try { return JSON.parse(await f.async('string')); } catch { return null; }
+        };
+        for (const loser of removed) {
+            const sid = resolve(loser);
+            if (!byId.has(sid) || removed.has(sid)) continue;
+            const li = await readItemJson(loser);
+            if (!li || (!li.guard && !li.evidence && !li.verify)) continue;
+            const si = await readItemJson(sid);
+            if (!si) continue;
+            let changed = false;
+            if (li.guard && typeof li.guard === 'object' && !si.guard) { si.guard = li.guard; changed = true; }
+            if (Array.isArray(li.evidence) && li.evidence.length && !si.evidence) { si.evidence = li.evidence; changed = true; }
+            if (typeof li.verify === 'string' && li.verify.trim() && !si.verify) { si.verify = li.verify; changed = true; }
+            if (changed) zip.file(`items/${shard(sid)}/${sid}.json`, JSON.stringify(si));
+        }
         for (const id of removed) {
             delete canvas.positions[id];
             try { zip.remove(`items/${shard(id)}/${id}.json`); } catch { /* */ }
@@ -4082,7 +4120,13 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             const cands = [];
             for (const c of liveTextCards()) {
                 if (r.area && (c.area || '').toLowerCase() !== r.area.toLowerCase()) continue;
-                if (/🛠/.test(c.text)) continue; // skills are standing reference — a ✓ must never archive one (mirror the supersede guard)
+                // Skills are standing reference — a ✓ must never archive one
+                // (mirror the supersede guard). EXCEPTION (2026-08-24): a card
+                // carrying a machine guard documents "✓-resolve retires the
+                // guard" as its lifecycle contract, and the deny message sends
+                // agents here — without this carve-out the advertised remedy
+                // was impossible and the unmatched ✓ minted a junk 🏁 fallback.
+                if (/🛠/.test(c.text) && !c.guard) continue;
                 // A ✓ closes opens/claims, never a pure milestone — without this
                 // a ✓ for a fulfilled claim could near-tie the very 🏁 that
                 // fulfilled it (item text ⊆ milestone) and archive the milestone
@@ -4190,13 +4234,28 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
                     // verifiedAt), so confirming/correcting a drifted fact marks it ✅.
                     if (Array.isArray(u.evidence) && u.evidence.length) j.evidence = u.evidence;
                     if (typeof u.verify === 'string' && u.verify.trim()) j.verify = u.verify.trim();
+                    // guard: replace, DISARM ({remove:true} deletes the machine
+                    // field — the only authorable off-switch), or preserve.
+                    if (u.guard && typeof u.guard === 'object') {
+                        if (u.guard.remove === true) delete j.guard; else j.guard = u.guard;
+                    }
+                    // A surviving/incoming guard must keep its 🛠 glyph — an
+                    // amendment that dropped it demoted the card out of every
+                    // skill-card lifecycle shield while it kept guarding
+                    // (gardener consolidation would then kill it silently).
+                    if (j.guard && !/🛠/.test(j.content)) j.content = `🛠️ ${j.content}`;
                 });
                 best.text = isTerseConfirm ? `${best.text}\n(re-affirmed ${today}: ${u.text})` : u.text;
                 stats.updated++;
             } else if (!nearDupExists(u.text)) {
                 // ~ fallback add is guarded like ✓'s: an unmatched ~ re-harvested
                 // from the transcript tail must not stack a copy every turn.
-                cards.push({ text: (u.area ? `${u.area}: ` : '') + u.text + (u.area ? `\n#${u.area.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : ''), area: u.area, createdVia: u.createdVia, ...(Array.isArray(u.evidence) && u.evidence.length ? { evidence: u.evidence } : {}), ...(typeof u.verify === 'string' && u.verify.trim() ? { verify: u.verify.trim() } : {}) });
+                // A ~ fallback that carries a live guard mints a SKILL card —
+                // the 🛠 glyph is what grants gardener/supersede immunity, and
+                // a glyph-less guard card was silently consolidatable while
+                // still enforcing (review 2026-08-24). remove-sentinels add no
+                // glyph and no field: an unmatched disarm is inert by design.
+                cards.push({ text: (u.area ? `${u.area}: ` : '') + (u.guard && u.guard.remove !== true && !/🛠/.test(u.text) ? '🛠️ ' : '') + u.text + (u.area ? `\n#${u.area.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : ''), area: u.area, createdVia: u.createdVia, ...(Array.isArray(u.evidence) && u.evidence.length ? { evidence: u.evidence } : {}), ...(typeof u.verify === 'string' && u.verify.trim() ? { verify: u.verify.trim() } : {}), ...(u.guard && typeof u.guard === 'object' && u.guard.remove !== true ? { guard: u.guard } : {}) });
             }
         }
 
@@ -4222,6 +4281,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
                     if (card.createdVia) j.createdVia = String(card.createdVia);
                     if (Array.isArray(card.evidence) && card.evidence.length) j.evidence = card.evidence;
                     if (typeof card.verify === 'string' && card.verify.trim()) j.verify = card.verify.trim();
+                    if (card.guard && typeof card.guard === 'object') j.guard = card.guard;
                 });
                 best.text = String(card.text);
                 cards.splice(i, 1);
@@ -5530,17 +5590,240 @@ export function findOverdueOpenCards(struct, { now = Date.now() } = {}) {
 // (milestone) | '✓' (resolve+archive a match) | '~' (update a match in place) |
 // '+' (skill — a REUSABLE how-to/gotcha/procedure, standing reference that always
 // surfaces and never ages out, distinct from a point-in-time decision).
-export function noteToCaptureInput({ text = '', area = '', marker = '', closes = '', evidence = null, verify = null, createdVia = 'mcp' } = {}) {
+// ── Guard cards (2026-08-24, founder go after the 13-agent audit) ────────────
+// A guard is a standing 🛠️ card that also declares WHEN it should interrupt a
+// tool call: { when: {tool?, command?, paths?, multiWorktree?}, severity, message }.
+// The card's prose is the human render; this structured field is the machine
+// half. Everything here is PURE — validation, compilation from a parsed
+// struct, and evaluation against one tool event — so the PreToolUse hook can
+// stay a stat+sidecar+regex fast path (never parses the brain, never spawns
+// git; measured brain parse is ~1s on the live brain, far over any hook budget).
+//
+// Trigger grammar is DELIBERATELY the honest expressible surface only
+// (audit §5): tool/command regexes, path PREFIXES, and one cached repo
+// predicate (multiWorktree). Staleness detection, response-shape checks and
+// semantic intent are NOT expressible here and must not be pretended in.
+//
+// Severity contract: 'warn' injects context; 'block' denies the call with the
+// card's message. Authoring 'block' is a deliberate human-directed act — an
+// agent must never author severity 'block' without explicit user instruction
+// (the deny names the card id, so a wrong block is corrected by ✓-resolving
+// or ~-amending that card).
+const GUARD_RE_MAX = 200;
+const GUARD_MSG_MAX = 500;
+const GUARD_PATHS_MAX = 20;
+// ONE keying rule for the compiled-guard sidecar, shared by every consumer
+// (the Claude --guard fast path, the Codex advisory lane, tests). The formula
+// mirrors global-brain-hook.mjs's cache keying (sha1-16 of the normalized
+// brain path) — test/guard-cards.mjs asserts the two derivations agree.
+export function guardSidecarPathFor(brainPath, home = os.homedir()) {
+    // On Windows the WHOLE path is case-folded, not just the drive letter —
+    // hosts reach the same brain through differently-cased CWDs (e:/ vs E:/,
+    // observed live in this project's own doctor output), and a case-split key
+    // would give each host its own half-blind sidecar (review 2026-08-24).
+    // POSIX paths keep their case: there, distinct casings ARE distinct files.
+    let norm = String(brainPath).replace(/\\/g, '/');
+    norm = process.platform === 'win32' ? norm.toLowerCase() : norm.replace(/^[a-zA-Z]:/, (m) => m.toLowerCase());
+    const key = crypto.createHash('sha1').update(norm).digest('hex').slice(0, 16);
+    return path.join(home, '.claude', 'project-brain', `.guards-${key}.json`);
+}
+const compileGuardRegex = (source) => {
+    const s = String(source || '').trim();
+    if (!s || s.length > GUARD_RE_MAX) return null;
+    try { return new RegExp(s, 'i'); } catch { return null; }
+};
+export function validateGuard(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return { ok: false, reason: 'guard must be an object: { when: {…}, severity?, message } — or { remove: true } to disarm' };
+    }
+    // Disarm sentinel (adversarial review 2026-08-24): a plain ~ amendment
+    // rewrites prose but PRESERVES the machine field, so without this there was
+    // no authorable way to switch a guard off short of archiving the card.
+    if (value.remove === true) {
+        const extra = Object.keys(value).filter((k) => k !== 'remove');
+        if (extra.length) return { ok: false, reason: 'guard.remove takes no other fields — pass exactly { remove: true } to disarm, or a full guard to replace' };
+        return { ok: true, guard: { remove: true } };
+    }
+    const when = value.when;
+    if (!when || typeof when !== 'object' || Array.isArray(when)) {
+        return { ok: false, reason: 'guard.when must be an object with at least one trigger (tool, command, paths, multiWorktree)' };
+    }
+    const out = { when: {}, severity: 'warn', message: '' };
+    if (when.tool !== undefined) {
+        if (typeof when.tool !== 'string' || !compileGuardRegex(when.tool)) {
+            return { ok: false, reason: `guard.when.tool must be a valid regex source string (≤${GUARD_RE_MAX} chars)` };
+        }
+        out.when.tool = when.tool.trim();
+    }
+    if (when.command !== undefined) {
+        if (typeof when.command !== 'string' || !compileGuardRegex(when.command)) {
+            return { ok: false, reason: `guard.when.command must be a valid regex source string (≤${GUARD_RE_MAX} chars)` };
+        }
+        out.when.command = when.command.trim();
+    }
+    if (when.paths !== undefined) {
+        if (!Array.isArray(when.paths) || !when.paths.length || when.paths.length > GUARD_PATHS_MAX
+            || !when.paths.every((p) => typeof p === 'string' && p.trim() && p.length <= GUARD_RE_MAX)) {
+            return { ok: false, reason: `guard.when.paths must be 1–${GUARD_PATHS_MAX} non-empty path-prefix strings (≤${GUARD_RE_MAX} chars each) — prefixes, not regexes` };
+        }
+        out.when.paths = when.paths.map((p) => p.trim().replace(/\\/g, '/'));
+    }
+    if (when.multiWorktree !== undefined) {
+        if (when.multiWorktree !== true) return { ok: false, reason: 'guard.when.multiWorktree accepts only true (omit it otherwise)' };
+        out.when.multiWorktree = true;
+    }
+    if (!Object.keys(out.when).length) {
+        return { ok: false, reason: 'guard.when needs at least one trigger: tool, command, paths, or multiWorktree' };
+    }
+    if (value.severity !== undefined && value.severity !== 'warn' && value.severity !== 'block') {
+        return { ok: false, reason: "guard.severity must be 'warn' or 'block' (default warn). 'block' is for irreversible actions and human-directed authoring only" };
+    }
+    if (value.severity === 'block') out.severity = 'block';
+    const msg = String(value.message || '').trim();
+    if (!msg || msg.length > GUARD_MSG_MAX) {
+        return { ok: false, reason: `guard.message is required (≤${GUARD_MSG_MAX} chars) — it is what the interrupted session reads` };
+    }
+    out.message = msg;
+    return { ok: true, guard: out };
+}
+// Live cards carrying a VALID guard field → the compiled list the sidecar
+// stores. Invalid guards are skipped (they still exist as prose cards); a
+// resolved/superseded/archived card stops guarding without any extra step.
+export function compileGuards(struct) {
+    if (!struct || !Array.isArray(struct.cards)) return [];
+    const out = [];
+    for (const c of struct.cards) {
+        if (c.type === 'container' || !c.guard) continue;
+        if (c.guard.remove === true) continue;              // disarmed via ~ amendment
+        if (/^archive$/i.test(c.area || '')) continue;
+        // Retirement test uses the ANCHORED stamp shapes, never a bare glyph
+        // scan — a live guard whose prose merely mentions ✅ must keep guarding
+        // (the glyph-in-prose trap this file already defends against elsewhere;
+        // adversarial review 2026-08-24 caught the bare /↩|✅|⤵/ version).
+        if (hasRetirementStamp(c.text)) continue;
+        const v = validateGuard(c.guard);
+        if (!v.ok) continue;
+        out.push({ id: c.id, area: c.area || null, title: c.title || null, ...v.guard });
+    }
+    return out;
+}
+// Evaluate compiled guards against ONE tool event. Pure; every regex test is
+// try/caught and inputs are sliced so a hostile pattern or a huge command can
+// never hang the hook. Verdict per guard:
+//   fired:false                        — a verifiable trigger said no
+//   fired:true, unverified:[]          — fire at the declared severity
+//   fired:true, unverified:['paths']   — verifiable triggers passed but an
+//     input was unavailable. Per the 2026-08-18 field rule ("a probe that
+//     fails must refuse, never exempt") this NEVER silently exempts — but a
+//     deny on unverified input would false-block, so the caller degrades
+//     block→warn and SAYS what could not be verified.
+export function evaluateGuards(guards, { toolName = '', command = '', files = null, worktreeCount = null } = {}) {
+    const results = [];
+    const CMD_CAP = 16384;
+    const raw = String(command || '');
+    const cmd = raw.slice(0, CMD_CAP);
+    const cmdTruncated = raw.length > CMD_CAP;
+    const tool = String(toolName || '').slice(0, 200);
+    for (const g of Array.isArray(guards) ? guards : []) {
+        try {
+            const unverified = [];
+            let fired = true;
+            // A trigger whose stored pattern fails to COMPILE at eval time
+            // (hand-edited sidecar, corrupt entry) is an UNVERIFIABLE trigger,
+            // never a silent drop — three review layers collapsed cannot-check
+            // into checked-and-clear before this (2026-08-24).
+            if (g.when.tool) {
+                const re = compileGuardRegex(g.when.tool);
+                if (!re) unverified.push('tool-pattern');
+                else if (!re.test(tool)) fired = false;
+            }
+            if (fired && g.when.command) {
+                const re = compileGuardRegex(g.when.command);
+                if (!re) unverified.push('command-pattern');
+                // A match on the truncated prefix is a real match; a NO-match on
+                // a truncated command proves nothing — report it unverifiable
+                // rather than letting truncation become exemption.
+                else if (!re.test(cmd)) {
+                    if (cmdTruncated) unverified.push('command-truncated');
+                    else fired = false;
+                }
+            }
+            if (fired && g.when.paths) {
+                if (!Array.isArray(files)) unverified.push('paths');
+                else if (!files.some((f) => {
+                    const file = String(f || '').replace(/\\/g, '/').toLowerCase();
+                    return g.when.paths.some((p) => file.startsWith(p.toLowerCase()));
+                })) fired = false;
+            }
+            if (fired && g.when.multiWorktree) {
+                if (!Number.isFinite(worktreeCount)) unverified.push('worktreeCount');
+                else if (worktreeCount <= 1) fired = false;
+            }
+            if (fired) results.push({ guard: g, unverified });
+        } catch { /* one bad guard never breaks the rest */ }
+    }
+    return results;
+}
+
+// Live worktree probe — bounded, call-time. The count changes independently of
+// the brain, so a compiled snapshot can false-deny (worktree removed) or
+// silently exempt (worktree added); callers probe AT the moment a
+// multiWorktree guard is actually in play. null = could not verify.
+export function probeWorktreeCount(dir) {
+    try {
+        const out = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+            cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500,
+        });
+        return out.split('\n').filter((l) => l.startsWith('worktree ')).length;
+    } catch { return null; }
+}
+// ONE currency-checked reader/rebuilder for the compiled-guard sidecar, shared
+// by every enforcement surface (Claude --guard, Codex advisory, brain_note's
+// post-write refresh). The adversarial review's two criticals were both "the
+// sidecar never learns the brain changed": a resolved guard kept denying with
+// a recovery message that could not work. This closes it at the read site —
+// stale (mtime mismatch) or missing ⇒ parse + recompile + ATOMIC write.
+//   returns { guards, worktreeCount, mtimeMs, rebuilt } on success
+//   returns { guards: null, stale: true } when the brain exists but the
+//     rebuild failed — the caller must treat every guard as UNVERIFIABLE
+//     (degrade block→warn), never as absent.
+//   returns { guards: [] } when the brain itself is gone.
+export async function ensureGuardSidecar(brainPath, { home = os.homedir(), buildIfMissing = true } = {}) {
+    const sidecarPath = guardSidecarPathFor(brainPath, home);
+    let mtimeMs = 0;
+    try { mtimeMs = fs.statSync(brainPath).mtimeMs; } catch { return { guards: [], worktreeCount: null, mtimeMs: 0, rebuilt: false }; }
+    try {
+        const cur = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+        if (cur && cur.mtimeMs === mtimeMs && Array.isArray(cur.guards)) {
+            return { guards: cur.guards, worktreeCount: Number.isFinite(cur.worktreeCount) ? cur.worktreeCount : null, mtimeMs, rebuilt: false };
+        }
+    } catch { /* absent or unreadable → rebuild below */ }
+    if (!buildIfMissing) return { guards: null, stale: true };
+    try {
+        const { struct } = await parseKlypix(fs.readFileSync(brainPath));
+        const guards = compileGuards(struct);
+        const worktreeCount = guards.some((g) => g.when && g.when.multiWorktree)
+            ? probeWorktreeCount(path.dirname(brainPath)) : null;
+        const payload = JSON.stringify({ v: 1, mtimeMs, builtAt: Date.now(), brainPath, worktreeCount, guards });
+        fs.mkdirSync(path.dirname(sidecarPath), { recursive: true });
+        const tmp = `${sidecarPath}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, payload);
+        fs.renameSync(tmp, sidecarPath);
+        return { guards, worktreeCount, mtimeMs, rebuilt: true };
+    } catch { return { guards: null, stale: true }; }
+}
+
+export function noteToCaptureInput({ text = '', area = '', marker = '', closes = '', evidence = null, verify = null, guard = null, createdVia = 'mcp' } = {}) {
     const body = String(text).trim();
     if (!body) return { cards: [], resolutions: [], updates: [] };
     const a = String(area || '').trim();
     if (marker === '✓') return { cards: [], resolutions: [{ area: a, text: body }], updates: [] };
-    if (marker === '~') return { cards: [], resolutions: [], updates: [{ area: a, text: body, createdVia, ...(evidence ? { evidence } : {}), ...(verify ? { verify } : {}) }] };
+    if (marker === '~') return { cards: [], resolutions: [], updates: [{ area: a, text: body, createdVia, ...(evidence ? { evidence } : {}), ...(verify ? { verify } : {}), ...(guard ? { guard } : {}) }] };
     const prefix = marker === '?' ? '❓ ' : marker === '!' ? '🏁 ' : marker === '+' ? '🛠️ ' : '';
     const borderColor = marker === '?' ? 'rgba(245,166,35,0.8)' : marker === '!' ? 'rgba(59,130,246,0.8)' : marker === '+' ? 'rgba(139,92,246,0.85)' : 'rgba(16,185,129,0.6)';
     const tag = a ? `\n#${a.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : '';
     const cardText = (a ? `${a}: ${prefix}${body}` : `${prefix}${body}`) + tag;
-    return { cards: [{ text: cardText, area: a, color: '#e8e8ed', borderColor, createdVia, ...(closes ? { closes } : {}), ...(evidence ? { evidence } : {}), ...(verify ? { verify } : {}) }], resolutions: [], updates: [] };
+    return { cards: [{ text: cardText, area: a, color: '#e8e8ed', borderColor, createdVia, ...(closes ? { closes } : {}), ...(evidence ? { evidence } : {}), ...(verify ? { verify } : {}), ...(guard ? { guard } : {}) }], resolutions: [], updates: [] };
 }
 
 /**
@@ -5624,6 +5907,8 @@ export async function buildKlypixMap(spec) {
             const h = measured[ci];
             items[id] = {
                 type: 'text', locked: false, createdAt: now, createdBy: 'agent', ...authorField(),
+                // Guard trigger — additive machine field (guard cards, 2026-08-24).
+                ...(c.guard && typeof c.guard === 'object' ? { guard: c.guard } : {}),
                 content: String(c.text), fontSize: FONT,
                 color: c.color || '#e8e8ed', border: true,
                 borderColor: c.color || 'rgba(16,185,129,0.35)',

package/src/uninstall.mjs

@@ -309,7 +309,7 @@ export function planUnlink(projectDir, { sidecars = false } = {}) {
 }
 
 /**
- * MACHINE-GLOBAL plan — the engine bundle, the 4 Claude Code hooks, and the
+ * MACHINE-GLOBAL plan — the engine bundle, the 5 Claude Code hooks, and the
  * three Codex host files. Zero writes.
  */
 export function planUninstall({ home = os.homedir(), installDir, keepRegistry = false, keepSemantic = false } = {}) {