@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/hooks/comment-lint.mjs

@@ -1,16 +1,35 @@
+#!/usr/bin/env node
 /**
- * lib/hooks/comment-lint.mjs — PostToolUse hook: check edited files against comment policy.
+ * lib/hooks/comment-lint.mjs — PostToolUse hook: enforce the comment policy at write time.
  *
- * Runs after Write/Edit on scoped paths. Emits warnings for missing headers and
- * banned patterns so violations are caught at authoring time, not at CI.
- * Non-blocking: exits 0 even on warnings so it never halts a write.
+ * Runs after Write/Edit/MultiEdit on scoped paths. Blocks the edit (exit 2)
+ * if the file violates the policy — missing required header, banned patterns,
+ * narrative voice, point-in-time notes, noise sentinels. The agent sees the
+ * block reason and is expected to fix the comment before continuing.
+ *
+ * Bypass: set CONSTRUCT_SKIP_COMMENT_LINT=1 in the environment.
+ *
+ * Input: reads tool_input.file_path from either the legacy TOOL_INPUT_FILE_PATH
+ * env var or modern stdin JSON ({ tool_input: { file_path } }).
+ *
+ * @p95ms 60
+ * @maxBlockingScope PostToolUse
  */
 
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { lintFile, formatResults } from '../comment-lint.mjs';
 
-const filePath = process.env.TOOL_INPUT_FILE_PATH;
+if (process.env.CONSTRUCT_SKIP_COMMENT_LINT === '1') process.exit(0);
+
+let filePath = process.env.TOOL_INPUT_FILE_PATH;
+if (!filePath) {
+  try {
+    const input = JSON.parse(readFileSync(0, 'utf8'));
+    filePath = input?.tool_input?.file_path || input?.tool_input?.path;
+  } catch {}
+}
 if (!filePath) process.exit(0);
 
 const ext = path.extname(filePath).toLowerCase();
@@ -22,5 +41,8 @@ const result = lintFile(filePath, { rootDir });
 if (!result.errors.length && !result.warnings.length) process.exit(0);
 
 const { output } = formatResults([result]);
-process.stdout.write(output);
-process.exit(0);
+process.stderr.write(output);
+process.stderr.write(
+  '\nComment policy blocked this edit. Remove the violations or set CONSTRUCT_SKIP_COMMENT_LINT=1.\n',
+);
+process.exit(2);

package/lib/hooks/config-protection.mjs

@@ -1,14 +1,28 @@
 #!/usr/bin/env node
 /**
- * lib/hooks/config-protection.mjs — Config protection hook — prevents edits to protected runtime config files.
+ * lib/hooks/config-protection.mjs — protects code-quality config from being weakened.
  *
- * Runs as PreToolUse on Edit/Write. Blocks modifications to ~/.construct/config.env, settings.template.json, and other protected config paths. Exits 2 to block.
+ * Runs as PreToolUse on Edit|Write|MultiEdit. Blocks edits to eslint /
+ * prettier / tsconfig / biome / stylelint configs. Those rules are a contract
+ * with the codebase; weakening them is almost always a bug fix in disguise.
+ *
+ * Meta-system files (hooks, registry, settings template, install.sh) are
+ * audited but NOT blocked. Editing them is normal development work on
+ * Construct itself. The previous block-with-CX_ALLOW_META_EDIT pattern was a
+ * sticky env-var toggle: friction the first time, zero protection thereafter
+ * because it stayed on. Layers that actually work for self-modification
+ * accidents: CLAUDE.md guidance, Claude Code's auto-classifier (intent-aware),
+ * and the role-event audit log this hook still writes.
+ *
+ * @p95ms 5
+ * @maxBlockingScope PreToolUse
  */
 import { readFileSync } from 'fs';
+import { logHookFailure } from './_lib/log.mjs';
 
 const filePath = process.env.TOOL_INPUT_FILE_PATH || (() => {
   try { return JSON.parse(readFileSync(0, 'utf8'))?.tool_input?.file_path || ''; }
-  catch { return ''; }
+  catch (err) { logHookFailure({ hook: 'config-protection', err, phase: 'parse' }); return ''; }
 })();
 
 if (!filePath) process.exit(0);
@@ -24,29 +38,36 @@ const PROTECTED = [
   /stylelint\.config(\.[a-z]+)?$/i,
 ];
 
+const META_FILES = [
+  /(?:^|\/)agents\/registry\.json$/,
+  /(?:^|\/)install\.sh$/,
+  /(?:^|\/)claude\/settings\.template\.json$/,
+  /(?:^|\/)lib\/hooks\/[^/]+\.mjs$/,
+];
+
+async function emitEvent(type, category, summary) {
+  try {
+    const { emitRoleEvent } = await import('../roles/hook-emit.mjs');
+    emitRoleEvent({
+      type,
+      summary,
+      hookInput: {},
+      context: { filePath, category },
+    });
+  } catch { /* best effort */ }
+}
+
 const base = filePath.split('/').pop();
 if (PROTECTED.some(r => r.test(base))) {
   process.stderr.write(
     `[config-protection] The code quality rules are protected. Fix the code to meet the existing standards — don't weaken the rules.\nFile: ${filePath}\n`
   );
+  await emitEvent('config.protection.violation', 'code-quality-config', `Blocked edit to code-quality-config: ${filePath}`);
   process.exit(2);
 }
 
-// Meta-system protection: block edits to Construct's own critical files unless CX_ALLOW_META_EDIT=1
-if (process.env.CX_ALLOW_META_EDIT !== '1') {
-  const META_FILES = [
-    /(?:^|\/)agents\/registry\.json$/,
-    /(?:^|\/)install\.sh$/,
-    /(?:^|\/)claude\/settings\.template\.json$/,
-    /(?:^|\/)lib\/hooks\/[^/]+\.mjs$/,
-  ];
-
-  if (META_FILES.some(r => r.test(filePath))) {
-    process.stderr.write(
-      `[config-protection] This file is part of the Construct meta-system. Editing it affects all agent sessions and platforms. Set CX_ALLOW_META_EDIT=1 to proceed if you know what you're doing.\nFile: ${filePath}\n`
-    );
-    process.exit(2);
-  }
+if (META_FILES.some(r => r.test(filePath))) {
+  await emitEvent('meta.edit', 'meta-system', `Meta-system edit: ${filePath}`);
 }
 
 process.exit(0);

package/lib/hooks/context-watch.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/context-watch.mjs — monitors cumulative token usage and injects
+ * a compaction recommendation when thresholds are crossed.
+ *
+ * Runs as UserPromptSubmit. Reads ~/.cx/session-cost.jsonl, takes the most
+ * recent turn's cache-read + cache-creation + processed input tokens,
+ * resolves the active model's context window, and compares against
+ * percentage-of-window thresholds.
+ *
+ * Window resolution (resolveContextWindow):
+ *   1. observedMaxTokens — largest input ever seen this session (authoritative:
+ *      if the API accepted N tokens, the window is >= N)
+ *   2. catalog maxInputTokens — from LiteLLM live data or static fallback
+ *   3. 200k Anthropic baseline
+ * The ladder lets a 1M-tier session self-promote once a turn exceeds 200k
+ * tokens, without requiring the user to declare their tier anywhere.
+ *
+ * Thresholds are policy ratios, not absolute numbers:
+ *   - 60% of window: gentle nudge to distill + summarize
+ *   - 80% of window: stronger push to compact now
+ *
+ * Only fires once per threshold per session to avoid spam. State is in
+ * ~/.cx/context-watch-state.json, reset when the session (by start timestamp
+ * in session-efficiency.json) rolls.
+ *
+ * @p95ms 20
+ * @maxBlockingScope UserPromptSubmit
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { resolveContextWindow } from '../telemetry/model-pricing-catalog.mjs';
+
+const CX_DIR = join(homedir(), '.cx');
+const COST_LOG = join(CX_DIR, 'session-cost.jsonl');
+const EFFICIENCY = join(CX_DIR, 'session-efficiency.json');
+const STATE = join(CX_DIR, 'context-watch-state.json');
+
+const WARN_RATIO = 0.60;
+const URGENT_RATIO = 0.80;
+
+function readSessionStart() {
+  try {
+    const e = JSON.parse(readFileSync(EFFICIENCY, 'utf8'));
+    return e?.sessionStartedAt || null;
+  } catch {
+    return null;
+  }
+}
+
+function readCurrentContextSize(sessionStart) {
+  // Use the MOST RECENT turn's tokens — that approximates current context
+  // size (what the model saw on its last request). Summing across turns
+  // double-counts cached content since each turn re-reads the same cache.
+  try {
+    if (!existsSync(COST_LOG)) return { total: 0, model: null };
+    const lines = readFileSync(COST_LOG, 'utf8').split('\n').filter(Boolean);
+    const cutoff = sessionStart ? new Date(sessionStart).getTime() : 0;
+    let latest = null;
+    for (const line of lines) {
+      try {
+        const row = JSON.parse(line);
+        const rowTs = new Date(row.ts).getTime();
+        if (rowTs < cutoff) continue;
+        if (!latest || rowTs > new Date(latest.ts).getTime()) latest = row;
+      } catch { /* skip malformed line */ }
+    }
+    if (!latest) return { total: 0, model: null };
+    const total =
+      Number(latest.cache_read_input_tokens || 0) +
+      Number(latest.cache_creation_input_tokens || 0) +
+      Number(latest.input_tokens || 0);
+    return { total, model: latest.model || null };
+  } catch {
+    return { total: 0, model: null };
+  }
+}
+
+function loadState() {
+  try {
+    return JSON.parse(readFileSync(STATE, 'utf8'));
+  } catch {
+    return { sessionStart: null, warnedAt: null, urgentAt: null, observedMaxTokens: 0 };
+  }
+}
+
+function saveState(state) {
+  try {
+    mkdirSync(CX_DIR, { recursive: true });
+    writeFileSync(STATE, JSON.stringify(state, null, 2));
+  } catch { /* best effort */ }
+}
+
+const sessionStart = readSessionStart();
+const { total, model } = readCurrentContextSize(sessionStart);
+
+let state = loadState();
+if (state.sessionStart !== sessionStart) {
+  state = { sessionStart, warnedAt: null, urgentAt: null, observedMaxTokens: 0 };
+}
+
+state.observedMaxTokens = Math.max(Number(state.observedMaxTokens) || 0, total);
+
+const contextWindow = resolveContextWindow(model, state.observedMaxTokens);
+const WARN_AT = Math.floor(contextWindow * WARN_RATIO);
+const URGENT_AT = Math.floor(contextWindow * URGENT_RATIO);
+
+let message = null;
+
+if (total >= URGENT_AT && !state.urgentAt) {
+  message =
+    `Context at ~${Math.round(total / 1000)}k of ~${Math.round(contextWindow / 1000)}k tokens — above the 80% urgent threshold. ` +
+    `Stop broad exploration. Save the salient state to .cx/context.md (current task, ` +
+    `decisions, open questions, files changed), then run /compact. Continuing without ` +
+    `compaction risks degraded responses and higher cost per turn.`;
+  state.urgentAt = new Date().toISOString();
+} else if (total >= WARN_AT && !state.warnedAt) {
+  message =
+    `Context at ~${Math.round(total / 1000)}k of ~${Math.round(contextWindow / 1000)}k tokens — past the 60% nudge threshold. ` +
+    `Consider running \`construct distill --query "<focus>"\` before more broad reads, ` +
+    `and summarize the active task to .cx/context.md so /compact has something to preserve.`;
+  state.warnedAt = new Date().toISOString();
+}
+
+saveState(state);
+
+if (message) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: `[context-watch] ${message}`,
+    },
+  }));
+}
+
+process.exit(0);

package/lib/hooks/context-window-recovery.mjs

@@ -3,11 +3,13 @@
  * lib/hooks/context-window-recovery.mjs — Context window recovery hook — detects near-limit context and suggests compaction.
  *
  * Runs as PostToolUse. Reads context usage from the hook input and emits a compaction suggestion when the context window is above 80%. Non-blocking.
+ *
+ * @p95ms 10
+ * @maxBlockingScope none (PostToolUse, non-blocking)
  */
 import { readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
-import { loadWorkflow, summarizeWorkflow } from '../workflow-state.mjs';
 import { readContextState, writeContextState } from '../context-state.mjs';
 
 const CONTEXT_LIMIT_PATTERNS = [
@@ -42,23 +44,6 @@ try { writeFileSync(STATE_PATH, JSON.stringify({ lastTriggeredAt: now })); } cat
 
 const cwd = input?.cwd || process.cwd();
 
-const workflowLines = [];
-try {
-  const workflow = loadWorkflow(cwd);
-  if (workflow) {
-    const summary = summarizeWorkflow(workflow);
-    workflowLines.push('## Active Workflow', summary, '');
-    const pending = (workflow.tasks || []).filter(t => t.status === 'in-progress' || t.status === 'todo');
-    if (pending.length) {
-      workflowLines.push('## Pending Tasks');
-      for (const t of pending.slice(0, 10)) {
-        workflowLines.push(`- [${t.key}] ${t.title} (${t.status}, owner: ${t.owner})`);
-      }
-      workflowLines.push('');
-    }
-  }
-} catch { /* best effort */ }
-
 let existingContext = '';
 try {
   const state = readContextState(cwd) || readContextState(homedir());
@@ -71,7 +56,6 @@ const recoveryContext = [
   `# Session Context`,
   `Last saved: ${date} (context-window-recovery)`,
   '',
-  ...workflowLines,
   existingContext ? `## Prior Context\n${existingContext}` : '',
 ].join('\n') + '\n';
 
@@ -83,7 +67,7 @@ try { writeContextState(homedir(), { source: 'context-window-recovery', recovery
 process.stdout.write([
   ``,
   `⚠ Context window limit hit. Session state saved to .cx/context.md.`,
-  `Resume by reading .cx/context.md and .cx/workflow.json, then continue from where you left off.`,
+  `Resume by reading .cx/context.md, AGENTS.md, and plan.md, then continue from where you left off.`,
   ``,
 ].join('\n'));
 

package/lib/hooks/dep-audit.mjs

@@ -5,6 +5,9 @@
  * After editing a dependency manifest, runs the appropriate audit tool and
  * appends critical/high vulnerabilities to ~/.cx/warn-flags.txt.
  * Silent when nothing is wrong. Runs async so it never blocks editing.
+ *
+ * @p95ms 5000
+ * @maxBlockingScope none (PostToolUse, async, non-blocking)
  */
 import { readFileSync, writeFileSync, existsSync, appendFileSync } from 'fs';
 import { execSync } from 'child_process';
@@ -27,6 +30,19 @@ const warnFlagsPath = join(homedir(), '.cx', 'warn-flags.txt');
 function appendWarn(msg) {
   try { appendFileSync(warnFlagsPath, msg + '\n'); } catch { /* best effort */ }
   process.stderr.write(`[dep-audit] ${msg}\n`);
+  emitVulnerability(msg);
+}
+
+async function emitVulnerability(msg) {
+  try {
+    const { emitRoleEvent } = await import('../roles/hook-emit.mjs');
+    emitRoleEvent({
+      type: 'dep.cve',
+      summary: msg,
+      hookInput: { cwd: projectDir },
+      context: { manifest: filePath },
+    });
+  } catch { /* best effort */ }
 }
 
 // ── npm / yarn / pnpm ─────────────────────────────────────────────────────────

package/lib/hooks/doc-coupling-check.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/doc-coupling-check.mjs — PostToolUse hook: nudge when code edits aren't paired with doc updates.
+ *
+ * Maintains a session-scoped counter of code-file edits (lib/, bin/, src/, app/)
+ * since the last documentation touch (CHANGELOG.md, docs/**, .cx/context.*).
+ * Emits an advisory to stderr at thresholds 3, 5, 10 so the agent observation
+ * surfaces the coupling reminder during the run rather than at commit time
+ * (where the hard gate in .beads/hooks/pre-commit will refuse to commit).
+ *
+ * Non-blocking by design — this is the soft predecessor to the commit gate.
+ *
+ * @p95ms 15
+ * @maxBlockingScope none (PostToolUse, non-blocking)
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+const STATE_PATH = join(homedir(), '.cx', 'doc-coupling.json');
+const CODE_RE = /^(lib|bin|src|app)\/.*\.(?:m?js|jsx?|tsx?|cjs)$/;
+const DOC_RE = /^(?:CHANGELOG\.md|docs\/.+\.md|\.cx\/context\.(?:md|json))$/;
+const THRESHOLDS = [3, 5, 10];
+
+let filePath = process.env.TOOL_INPUT_FILE_PATH;
+let cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+if (!filePath) {
+  try {
+    const input = JSON.parse(readFileSync(0, 'utf8'));
+    filePath = input?.tool_input?.file_path || input?.tool_input?.path;
+    if (input?.cwd) cwd = input.cwd;
+  } catch {}
+}
+if (!filePath) process.exit(0);
+
+const rel = filePath.startsWith(cwd) ? filePath.slice(cwd.length).replace(/^\/+/, '') : filePath;
+
+function readState() {
+  try { return JSON.parse(readFileSync(STATE_PATH, 'utf8')); }
+  catch { return { codeEdits: 0, notified: [] }; }
+}
+
+function writeState(state) {
+  try {
+    mkdirSync(dirname(STATE_PATH), { recursive: true });
+    writeFileSync(STATE_PATH, JSON.stringify(state));
+  } catch {}
+}
+
+const state = readState();
+
+if (DOC_RE.test(rel)) {
+  writeState({ codeEdits: 0, notified: [] });
+  process.exit(0);
+}
+
+if (!CODE_RE.test(rel)) process.exit(0);
+
+state.codeEdits = (state.codeEdits || 0) + 1;
+const notified = new Set(state.notified || []);
+
+let advisory = null;
+for (const t of THRESHOLDS) {
+  if (state.codeEdits >= t && !notified.has(t)) {
+    notified.add(t);
+    advisory = t;
+  }
+}
+
+state.notified = [...notified];
+writeState(state);
+
+if (advisory != null) {
+  process.stderr.write(
+    `[doc-coupling] ${state.codeEdits} code file edit(s) this session under lib/|bin/|src/|app/; CHANGELOG.md / docs / .cx/context still not touched. Update docs before the next commit (the pre-commit gate will block otherwise; bypass: CONSTRUCT_SKIP_DOCS=1).\n`,
+  );
+}
+
+process.exit(0);

package/lib/hooks/edit-accumulator.mjs

@@ -3,6 +3,9 @@
  * lib/hooks/edit-accumulator.mjs — Edit accumulator hook — batches and summarizes recent file edits for context.
  *
  * Runs as PostToolUse after Edit/Write. Maintains a rolling log of recent edits in ~/.cx/edit-log.json for use by other hooks and efficiency reporting.
+ *
+ * @p95ms 10
+ * @maxBlockingScope none (PostToolUse, non-blocking)
  */
 import { appendFileSync, readFileSync, writeFileSync, existsSync } from 'fs';
 import { homedir } from 'os';

package/lib/hooks/edit-error-recovery.mjs

@@ -3,6 +3,9 @@
  * lib/hooks/edit-error-recovery.mjs — Edit error recovery hook — recovers from failed edit attempts and suggests fixes.
  *
  * Runs as PostToolUse when Edit tool returns an error. Reads the error and provides a targeted fix suggestion based on the error type (e.g., old_string not found).
+ *
+ * @p95ms 10
+ * @maxBlockingScope none (PostToolUse, non-blocking)
  */
 import { readFileSync } from 'fs';
 

package/lib/hooks/edit-guard.mjs

@@ -3,14 +3,15 @@
  * lib/hooks/edit-guard.mjs — Edit guard hook — validates old_string exists in target file before allowing edits.
  *
  * Runs as PreToolUse on Edit. Re-reads the target file and checks that old_string is present to prevent no-op or mismatched edits. Exits 2 (block) when not found.
+ *
+ * @p95ms 20
+ * @maxBlockingScope PreToolUse
  */
-// PreToolUse(Edit|MultiEdit|Write) — hash-anchored edit verification
-// Blocks Edit/MultiEdit when old_string is not found verbatim in the file.
-// Warns (non-blocking) on hash staleness when file changed since last Read.
 import { readFileSync, existsSync } from 'fs';
 import { createHash } from 'crypto';
 import { join, resolve } from 'path';
 import { homedir } from 'os';
+import { logHookFailure } from './_lib/log.mjs';
 
 const HASH_STORE = join(homedir(), '.cx', 'file-hashes.json');
 
@@ -26,7 +27,8 @@ function fileHash(content) {
 }
 
 let input = {};
-try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+try { input = JSON.parse(readFileSync(0, 'utf8')); }
+catch (err) { logHookFailure({ hook: 'edit-guard', err, phase: 'parse' }); process.exit(0); }
 
 const toolName = input?.tool_name || '';
 const ti = input?.tool_input || {};
@@ -34,6 +36,45 @@ const cwd = input?.cwd || process.cwd();
 
 function absOf(p) { return p.startsWith('/') ? p : resolve(cwd, p); }
 
+// Role-fence check: if the most recently dispatched persona is one we manage
+// (cx-sre, cx-qa, cx-security, cx-docs-keeper) and the dispatch is fresh,
+// emit an advisory stderr warning when the edit target is outside the fence.
+// Hard-block only when the fence returns "outside-fence" (default-deny case);
+// "needs-approval" routes to existing commit-approval flow.
+
+if ((toolName === 'Edit' || toolName === 'Write' || toolName === 'MultiEdit') && process.env.CONSTRUCT_ROLES !== 'off') {
+  try {
+    const lastAgentPath = join(homedir(), '.cx', 'last-agent.json');
+    if (existsSync(lastAgentPath)) {
+      const last = JSON.parse(readFileSync(lastAgentPath, 'utf8'));
+      const lastTs = last?.ts ? Date.parse(last.ts) : 0;
+      const fresh = lastTs && (Date.now() - lastTs) < 10 * 60 * 1000;
+      const id = String(last?.agent || '').replace(/^cx-/, '');
+      const ONBOARDED = new Set(['sre', 'qa', 'security', 'docs-keeper']);
+      const targetPath = ti.file_path || ti.path || '';
+      if (fresh && ONBOARDED.has(id) && targetPath) {
+        const { checkAction } = await import('../roles/fence.mjs');
+        const rel = targetPath.startsWith(cwd + '/') ? targetPath.slice(cwd.length + 1) : targetPath;
+        const verdict = checkAction({ personaId: id, action: 'edit', target: rel });
+        if (!verdict.allowed && verdict.reason === 'outside-fence') {
+          process.stderr.write(
+            `[fence] cx-${id} cannot edit ${rel} — outside declared fence.\n` +
+            `Allowed paths: see agents/role-manifests.json → ${id} → fence.allowedPaths.\n`
+          );
+          process.exit(2);
+        }
+        if (!verdict.allowed && verdict.approval) {
+          process.stderr.write(
+            `[fence] cx-${id} editing ${rel} requires user approval (outside fence, approval-required class).\n`
+          );
+          const { recordApprovalRequest } = await import('../roles/approval-surface.mjs');
+          await recordApprovalRequest({ personaId: id, action: 'edit', target: rel, reason: verdict.reason || 'needs-approval' });
+        }
+      }
+    }
+  } catch { /* best effort — fence check never blocks for internal errors */ }
+}
+
 if (toolName === 'Edit') {
   const { file_path, old_string } = ti;
   if (!file_path || !old_string) process.exit(0);

package/lib/hooks/env-check.mjs

@@ -5,6 +5,9 @@
  * Reads .env.example from the project root, compares against .env and
  * process.env, and writes missing required vars to stdout so Claude sees
  * them at session open. Silent when everything is in order.
+ *
+ * @p95ms 20
+ * @maxBlockingScope SessionStart
  */
 import { readFileSync, existsSync, realpathSync } from 'fs';
 import { fileURLToPath } from 'url';

package/lib/hooks/guard-bash.mjs

@@ -3,8 +3,15 @@
  * lib/hooks/guard-bash.mjs — Guard bash hook — blocks dangerous shell commands from running unreviewed.
  *
  * Runs as PreToolUse on Bash. Scans the command against a blocklist of destructive patterns (rm -rf, force push to main, etc.) and exits 2 to block matches.
+ *
+ * @p95ms 5
+ * @maxBlockingScope PreToolUse
  */
 import { createInterface } from 'readline';
+import { readFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { logHookFailure } from './_lib/log.mjs';
 
 const BLOCK_PATTERNS = [
   {
@@ -56,7 +63,8 @@ async function getCommand() {
       try {
         const parsed = JSON.parse(data);
         resolve(parsed?.tool_input?.command ?? parsed?.command ?? '');
-      } catch {
+      } catch (err) {
+        logHookFailure({ hook: 'guard-bash', err, phase: 'parse' });
         resolve('');
       }
     });
@@ -80,4 +88,53 @@ for (const { pattern, reason } of WARN_PATTERNS) {
   }
 }
 
+// Role-fence check: if the most recently dispatched persona is one we manage
+// and the dispatch is fresh, evaluate the command against the persona's
+// fence. git commit/push are always commit/push actions; bd ... maps to
+// allowedCommands prefix-match; everything else is the bash action.
+
+if (process.env.CONSTRUCT_ROLES !== 'off') {
+  try {
+    const lastAgentPath = join(homedir(), '.cx', 'last-agent.json');
+    if (existsSync(lastAgentPath)) {
+      const last = JSON.parse(readFileSync(lastAgentPath, 'utf8'));
+      const lastTs = last?.ts ? Date.parse(last.ts) : 0;
+      const fresh = lastTs && (Date.now() - lastTs) < 10 * 60 * 1000;
+      const id = String(last?.agent || '').replace(/^cx-/, '');
+      if (fresh && id) {
+        const { isOnboarded } = await import('../roles/manifest.mjs');
+        if (isOnboarded(id)) {
+          const { checkAction } = await import('../roles/fence.mjs');
+          const trimmed = command.trim();
+          let verdict;
+          if (/^git\s+commit\b/.test(trimmed)) {
+            verdict = checkAction({ personaId: id, action: 'commit', target: '' });
+          } else if (/^git\s+push\b/.test(trimmed)) {
+            verdict = checkAction({ personaId: id, action: 'push', target: '' });
+          } else {
+            verdict = checkAction({ personaId: id, action: 'bash', target: trimmed });
+          }
+          if (!verdict.allowed && verdict.reason === 'outside-fence') {
+            process.stderr.write(
+              `[fence] cx-${id} cannot run this command — outside declared fence.\n` +
+              `Command: ${trimmed.slice(0, 200)}\n` +
+              `Allowed commands prefix list: see agents/role-manifests.json → ${id} → fence.allowedCommands.\n`
+            );
+            process.exit(2);
+          }
+          if (!verdict.allowed && verdict.approval) {
+            process.stderr.write(
+              `[fence] cx-${id} running this requires user approval (${verdict.reason}).\n` +
+              `Command: ${trimmed.slice(0, 200)}\n`
+            );
+            const { recordApprovalRequest } = await import('../roles/approval-surface.mjs');
+            const actionLabel = /^git\s+commit\b/.test(trimmed) ? 'commit' : /^git\s+push\b/.test(trimmed) ? 'push' : 'bash';
+            await recordApprovalRequest({ personaId: id, action: actionLabel, target: trimmed, reason: verdict.reason || 'needs-approval' });
+          }
+        }
+      }
+    }
+  } catch { /* best effort */ }
+}
+
 process.exit(0);