@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/hooks/agent-tracker.mjs

@@ -3,10 +3,12 @@
  * lib/hooks/agent-tracker.mjs — Agent task lifecycle hook — tracks task start, completion, and handoffs.
  *
  * Runs as PostToolUse after Agent tool calls. Records agent invocations and their outcomes to ~/.cx/agent-log.json for telemetry and performance review.
+ * Also records observations for learning system to identify patterns/anti-patterns.
+ *
+ * @p95ms 10
+ * @maxBlockingScope none (PostToolUse, non-blocking)
  */
-// PostToolUse(Task) — records the last dispatched subagent to ~/.cx/last-agent.json.
-// stop-notify.mjs reads this to attribute per-turn token costs to the dispatching agent.
-import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
@@ -17,7 +19,7 @@ const toolName = input?.tool_name || '';
 if (toolName !== 'Task') process.exit(0);
 
 const toolInput = input?.tool_input || {};
-const cwd = input?.cwd || process.cwd();
+const toolResult = input?.tool_result || {};
 
 // Extract agent identity from the Task tool input.
 // Claude Code passes subagent_type or description in tool_input.
@@ -31,20 +33,175 @@ if (!agentName) {
   agentName = descMatch ? descMatch[1].toLowerCase() : 'subagent';
 }
 
-// Load active task key from workflow
-let taskKey = null;
-try {
-  const wf = JSON.parse(readFileSync(join(cwd, '.cx', 'workflow.json'), 'utf8'));
-  taskKey = wf.currentTaskKey || null;
-} catch { /* no workflow */ }
+// Extract success/failure indicators from result
+const resultText = toolResult?.result || '';
+const successIndicators = ['success', 'completed', 'finished', 'done', '✅', '✔'];
+const errorIndicators = ['error', 'failed', 'failure', '❌', '✗', 'exception', 'timed out'];
+const warningIndicators = ['warning', 'warn', '⚠', 'note:', 'attention'];
 
+let outcome = 'unknown';
+let success = null;
+
+const lowerResult = resultText.toLowerCase();
+if (errorIndicators.some(ind => lowerResult.includes(ind))) {
+  outcome = 'error';
+  success = false;
+} else if (warningIndicators.some(ind => lowerResult.includes(ind))) {
+  outcome = 'warning';
+  success = null;
+} else if (successIndicators.some(ind => lowerResult.includes(ind))) {
+  outcome = 'success';
+  success = true;
+}
+
+// Record agent invocation
 try {
   const home = homedir();
-  mkdirSync(join(home, '.cx'), { recursive: true });
+  const cxDir = join(home, '.cx');
+  mkdirSync(cxDir, { recursive: true });
+  
+  // Update last-agent file for coordination
   writeFileSync(
-    join(home, '.cx', 'last-agent.json'),
-    JSON.stringify({ agent: agentName, taskKey, ts: new Date().toISOString() }),
+    join(cxDir, 'last-agent.json'),
+    JSON.stringify({ 
+      agent: agentName, 
+      coordination: 'tracker-plus-plan', 
+      ts: new Date().toISOString(),
+      outcome,
+      description: description.slice(0, 200)
+    }),
+  );
+  
+  // Append to agent log for telemetry
+  const agentLogFile = join(cxDir, 'agent-log.jsonl');
+  const logEntry = {
+    timestamp: new Date().toISOString(),
+    agent: agentName,
+    outcome,
+    success,
+    description: description.slice(0, 500),
+    resultLength: resultText.length,
+    toolInputKeys: Object.keys(toolInput).filter(k => !k.includes('secret') && !k.includes('password') && !k.includes('token'))
+  };
+  
+  appendFileSync(agentLogFile, JSON.stringify(logEntry) + '\n');
+  
+  // Record observation for pattern learning (only if we have meaningful outcome)
+  if (outcome !== 'unknown' && description.length > 10) {
+    const observationsDir = join(cxDir, 'observations', 'agent-outcomes');
+    mkdirSync(observationsDir, { recursive: true });
+    
+    const observationFile = join(observationsDir, `${Date.now()}-${agentName}.json`);
+    
+    // Categorize as pattern or anti-pattern based on outcome
+    const category = success === true ? 'pattern' : 
+                    success === false ? 'anti-pattern' : 'observation';
+    
+    const summary = success === true 
+      ? `${agentName} successfully completed: ${description.slice(0, 100)}`
+      : success === false
+      ? `${agentName} failed: ${description.slice(0, 100)}`
+      : `${agentName} executed with warnings: ${description.slice(0, 100)}`;
+    
+    const observation = {
+      role: 'agent-tracker',
+      category,
+      summary,
+      content: `${agentName} was invoked with description: "${description.slice(0, 500)}"\n\nOutcome: ${outcome}\nResult length: ${resultText.length} chars`,
+      tags: ['agent-invocation', agentName, outcome],
+      confidence: 0.8,
+      timestamp: new Date().toISOString()
+    };
+    
+    writeFileSync(observationFile, JSON.stringify(observation, null, 2) + '\n');
+    
+    // Also record in vector-ready format for learning system
+    if (success !== null) {
+      const learningDir = join(cxDir, 'learning', agentName);
+      mkdirSync(learningDir, { recursive: true });
+      
+      const learningFile = join(learningDir, `${Date.now()}-${success ? 'success' : 'failure'}.json`);
+      const learningEntry = {
+        agent: agentName,
+        success,
+        description,
+        outcome,
+        timestamp: new Date().toISOString(),
+        // Extract potential patterns from description
+        keywords: extractKeywords(description),
+        taskType: classifyTaskType(description)
+      };
+      
+      writeFileSync(learningFile, JSON.stringify(learningEntry, null, 2) + '\n');
+    }
+  }
+  
+} catch (error) {
+  // Non-critical - best effort tracking
+  console.error(`Agent tracker error: ${error.message}`);
+}
+
+// Auto-enqueue handoff when a completing persona's result references
+// `next:cx-<role>` and the target persona is onboarded in the role framework.
+// The next session-start will pick up the queued entry and dispatch via Task.
+
+try {
+  if (process.env.CONSTRUCT_ROLES !== 'off' && agentName && /^cx-/.test(agentName)) {
+    const matches = [...resultText.matchAll(/\bnext:cx-([a-z][a-z-]+)\b/g)].map((m) => m[1]);
+    const unique = [...new Set(matches)];
+    if (unique.length > 0) {
+      const { isOnboarded, loadManifest } = await import('../roles/manifest.mjs');
+      const pendingPath = join(homedir(), '.cx', 'role-pending.jsonl');
+      const bdMatch = /\b(construct-[a-z0-9]+)\b/i.exec(resultText) || [];
+      const bdIssueId = bdMatch[1] || null;
+      for (const targetId of unique) {
+        if (!isOnboarded(targetId)) continue;
+        const manifest = loadManifest(targetId);
+        const entry = {
+          ts: Date.now(),
+          personaId: targetId,
+          cxId: `cx-${targetId}`,
+          bdIssueId,
+          fingerprint: `handoff-${agentName}-${targetId}-${Date.now().toString(36)}`,
+          eventType: 'handoff.received',
+          summary: `Handoff from ${agentName}${bdIssueId ? ` (re ${bdIssueId})` : ''}`,
+          killSwitchEnv: manifest?.killSwitchEnv || '',
+          handoffFrom: agentName,
+        };
+        appendFileSync(pendingPath, JSON.stringify(entry) + '\n');
+      }
+    }
+  }
+} catch { /* best effort — handoff enqueue never blocks */ }
+
+// Helper functions for learning system
+function extractKeywords(text) {
+  const commonStop = ['the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'of', 'with', 'by'];
+  const words = text.toLowerCase().split(/[\s\.,;!?]+/).filter(word => 
+    word.length > 2 && !commonStop.includes(word) && /^[a-z]+$/.test(word)
   );
-} catch { /* best effort */ }
+  
+  // Count frequency
+  const freq = {};
+  words.forEach(word => freq[word] = (freq[word] || 0) + 1);
+  
+  // Return top 5 keywords
+  return Object.entries(freq)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([word]) => word);
+}
+
+function classifyTaskType(description) {
+  const lower = description.toLowerCase();
+  if (lower.includes('fix') || lower.includes('bug') || lower.includes('error')) return 'bug-fix';
+  if (lower.includes('implement') || lower.includes('create') || lower.includes('add')) return 'implementation';
+  if (lower.includes('refactor') || lower.includes('improve') || lower.includes('optimize')) return 'refactoring';
+  if (lower.includes('review') || lower.includes('audit') || lower.includes('check')) return 'review';
+  if (lower.includes('test') || lower.includes('verify') || lower.includes('validate')) return 'testing';
+  if (lower.includes('document') || lower.includes('write') || lower.includes('readme')) return 'documentation';
+  if (lower.includes('research') || lower.includes('analyze') || lower.includes('investigate')) return 'research';
+  return 'other';
+}
 
 process.exit(0);

package/lib/hooks/audit-reads.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/audit-reads.mjs — opt-in tamper-evident log of every Read tool call.
+ *
+ * Symmetric counterpart to audit-trail.mjs (which records mutations). Reads
+ * are off by default because they happen much more often than writes; enable
+ * with `CONSTRUCT_AUDIT_READS=1`. When enabled, every Read tool call writes
+ * a single JSONL line to ~/.cx/audit-reads.jsonl with:
+ *
+ *   - timestamp ISO
+ *   - session_id (when supplied by the harness)
+ *   - tool_name (always Read)
+ *   - agent (from ~/.cx/last-agent.json — falls back to "construct")
+ *   - cwd
+ *   - target (the file_path read)
+ *   - bytes (size of the file at read time)
+ *   - content_hash (sha256 of the file's first 64KiB at read time, truncated)
+ *   - prev_line_hash (chained tamper-evidence — hash of previous JSONL line)
+ *
+ * The prev_line_hash chain means any after-the-fact reordering or deletion
+ * breaks the chain and is detectable by a simple replay (same approach as
+ * the mutation audit).
+ *
+ * @p95ms 8
+ * @maxBlockingScope none (PostToolUse, non-blocking)
+ */
+import { readFileSync, appendFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { logHookFailure } from './_lib/log.mjs';
+
+const CX_DIR = join(homedir(), '.cx');
+const AUDIT_FILE = join(CX_DIR, 'audit-reads.jsonl');
+const LAST_AGENT = join(CX_DIR, 'last-agent.json');
+const HASH_PREFIX_BYTES = 64 * 1024;
+
+if (process.env.CONSTRUCT_AUDIT_READS !== '1') process.exit(0);
+
+function sha256(input) { return createHash('sha256').update(input).digest('hex'); }
+
+function readLastAgent() {
+  try {
+    const data = JSON.parse(readFileSync(LAST_AGENT, 'utf8'));
+    return data?.agent || data?.name || 'construct';
+  } catch { return 'construct'; }
+}
+
+function readPrevLineHash() {
+  try {
+    if (!existsSync(AUDIT_FILE)) return null;
+    const size = statSync(AUDIT_FILE).size;
+    if (size === 0) return null;
+    const readFrom = Math.max(0, size - 2048);
+    const tail = readFileSync(AUDIT_FILE, 'utf8').slice(readFrom);
+    const lines = tail.split('\n').filter(Boolean);
+    if (lines.length === 0) return null;
+    return sha256(lines[lines.length - 1]);
+  } catch { return null; }
+}
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); }
+catch (err) { logHookFailure({ hook: 'audit-reads', err, phase: 'parse' }); process.exit(0); }
+
+if ((input?.tool_name || '') !== 'Read') process.exit(0);
+
+const cwd = input?.cwd || process.cwd();
+const filePath = input?.tool_input?.file_path;
+if (!filePath) process.exit(0);
+
+const absPath = filePath.startsWith('/') ? filePath : resolve(cwd, filePath);
+
+let bytes = null;
+let contentHash = null;
+try {
+  if (existsSync(absPath)) {
+    bytes = statSync(absPath).size;
+    const buf = Buffer.alloc(Math.min(bytes, HASH_PREFIX_BYTES));
+    const fd = await import('node:fs').then((m) => m.openSync(absPath, 'r'));
+    const fsModule = await import('node:fs');
+    fsModule.readSync(fd, buf, 0, buf.length, 0);
+    fsModule.closeSync(fd);
+    contentHash = sha256(buf).slice(0, 32);
+  }
+} catch (err) {
+  logHookFailure({ hook: 'audit-reads', err, phase: 'hash', input: { filePath: absPath } });
+}
+
+const record = {
+  ts: new Date().toISOString(),
+  session_id: input?.session_id || null,
+  tool: 'Read',
+  agent: readLastAgent(),
+  cwd,
+  target: filePath,
+  bytes,
+  content_hash: contentHash,
+  prev_line_hash: readPrevLineHash(),
+};
+
+try {
+  mkdirSync(CX_DIR, { recursive: true });
+  appendFileSync(AUDIT_FILE, JSON.stringify(record) + '\n', 'utf8');
+} catch (err) {
+  logHookFailure({ hook: 'audit-reads', err, phase: 'append' });
+}
+
+process.exit(0);

package/lib/hooks/audit-trail.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/audit-trail.mjs — append-only audit log of every mutation Construct
+ * (or any subagent it dispatches) makes.
+ *
+ * Runs as PostToolUse on Edit | Write | MultiEdit | NotebookEdit | Bash.
+ * For Bash, only records commands that mutate state (git/npm/docker/cargo etc.
+ * write operations, rm, mv, chmod). Read-only commands are skipped.
+ *
+ * Each record is a single JSONL line written to ~/.cx/audit-trail.jsonl with:
+ *   - timestamp ISO
+ *   - session_id (from hook input when available)
+ *   - tool_name
+ *   - agent (from ~/.cx/last-agent.json, falls back to "construct")
+ *   - task metadata (from the last-agent hint when available)
+ *   - cwd
+ *   - target (file_path for edits/writes, command for Bash)
+ *   - detail (old_string prefix + new_string prefix for Edit; truncated diff
+ *             for Write; command summary for Bash)
+ *   - content_hash (sha256 of post-change file for edits, null for Bash)
+ *   - prev_line_hash (chained tamper-evidence — hash of previous JSONL line)
+ *
+ * The prev_line_hash chain means any after-the-fact reordering or deletion
+ * breaks the chain and is detectable by a simple replay.
+ *
+ * @p95ms 15
+ * @maxBlockingScope none (PostToolUse, non-blocking)
+ */
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+const CX_DIR = join(homedir(), '.cx');
+const AUDIT_FILE = join(CX_DIR, 'audit-trail.jsonl');
+const LAST_AGENT = join(CX_DIR, 'last-agent.json');
+const MUTATING_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Bash']);
+
+const BASH_MUTATING_PATTERNS = [
+  /^\s*git\s+(add|commit|push|rebase|merge|reset|checkout\s+-b|branch\s+-D|tag|cherry-pick|stash\s+(?:push|drop))/,
+  /^\s*(rm|mv|cp|chmod|chown|ln|mkdir|rmdir|touch|install)\b/,
+  /^\s*(npm|pnpm|yarn|bun|pip|pip3|poetry|cargo|go|brew)\s+(install|add|remove|update|upgrade|uninstall|publish|link)/,
+  /^\s*docker\s+(run|build|rm|rmi|push|tag|stop|kill|exec)/,
+  /^\s*kubectl\s+(apply|delete|create|replace|scale|rollout)/,
+  /^\s*terraform\s+(apply|destroy)/,
+  /^\s*psql\b|^\s*sqlite3\b|\bINSERT\s+INTO\b|\bUPDATE\s+\w+\s+SET\b|\bDELETE\s+FROM\b/i,
+  /^\s*construct\s+(sync|setup|mcp\s+(add|remove)|init|init-docs)/,
+  />\s*[^|&]|>>\s*[^|&]/, // shell redirection that writes
+];
+
+function isMutatingBash(command) {
+  if (!command) return false;
+  return BASH_MUTATING_PATTERNS.some((re) => re.test(command));
+}
+
+function sha256(input) {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+function readLastAgent() {
+  try {
+    const raw = readFileSync(LAST_AGENT, 'utf8');
+    const data = JSON.parse(raw);
+    return data?.agent || data?.name || 'construct';
+  } catch {
+    return 'construct';
+  }
+}
+
+function readPrevLineHash() {
+  try {
+    if (!existsSync(AUDIT_FILE)) return null;
+    const size = statSync(AUDIT_FILE).size;
+    if (size === 0) return null;
+    const readFrom = Math.max(0, size - 2048);
+    const fs = readFileSync(AUDIT_FILE, 'utf8').slice(readFrom);
+    const lines = fs.split('\n').filter(Boolean);
+    if (lines.length === 0) return null;
+    return sha256(lines[lines.length - 1]);
+  } catch {
+    return null;
+  }
+}
+
+function truncateSnippet(s, limit = 280) {
+  if (!s) return '';
+  const str = String(s);
+  return str.length <= limit ? str : str.slice(0, limit) + '…';
+}
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const toolName = input?.tool_name || '';
+if (!MUTATING_TOOLS.has(toolName)) process.exit(0);
+
+const cwd = input?.cwd || process.cwd();
+const toolInput = input?.tool_input || {};
+
+let target = null;
+let detail = null;
+let contentHash = null;
+
+if (toolName === 'Bash') {
+  const command = String(toolInput?.command || '');
+  if (!isMutatingBash(command)) process.exit(0);
+  target = 'bash';
+  detail = truncateSnippet(command, 400);
+} else if (toolName === 'Edit') {
+  target = toolInput.file_path || null;
+  detail = `-- ${truncateSnippet(toolInput.old_string, 140)}\n++ ${truncateSnippet(toolInput.new_string, 140)}`;
+} else if (toolName === 'Write') {
+  target = toolInput.file_path || null;
+  detail = `WRITE ${String(toolInput.content || '').length} chars`;
+} else if (toolName === 'MultiEdit') {
+  target = toolInput.file_path || null;
+  const editsCount = Array.isArray(toolInput.edits) ? toolInput.edits.length : 0;
+  detail = `MultiEdit ${editsCount} edits`;
+} else if (toolName === 'NotebookEdit') {
+  target = toolInput.notebook_path || null;
+  detail = `NotebookEdit cell ${toolInput.cell_number ?? '?'}`;
+}
+
+if (!target) process.exit(0);
+
+if (toolName !== 'Bash' && target) {
+  const absPath = target.startsWith('/') ? target : resolve(cwd, target);
+  try {
+    if (existsSync(absPath)) {
+      contentHash = sha256(readFileSync(absPath, 'utf8')).slice(0, 32);
+    }
+  } catch { /* best effort */ }
+}
+
+const record = {
+  ts: new Date().toISOString(),
+  session_id: input?.session_id || null,
+  tool: toolName,
+  agent: readLastAgent(),
+  task: null,
+  cwd,
+  target,
+  detail,
+  content_hash: contentHash,
+  prev_line_hash: readPrevLineHash(),
+};
+
+try {
+  mkdirSync(CX_DIR, { recursive: true });
+  appendFileSync(AUDIT_FILE, JSON.stringify(record) + '\n', 'utf8');
+} catch { /* best effort — audit failure must not block the user's work */ }
+
+process.exit(0);

package/lib/hooks/bash-output-logger.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/bash-output-logger.mjs — persists long Bash outputs to disk and nudges
+ * the model to reference the log instead of re-running the command.
+ *
+ * Runs as PostToolUse on Bash. If stdout exceeds a threshold, writes the full
+ * output to ~/.cx/bash-logs/ and emits a short stderr note that Claude sees in
+ * the next turn. The current turn's conversation still contains the full output
+ * (hooks cannot retroactively edit past tool outputs), but subsequent turns are
+ * steered toward disk-backed references instead of re-running the same command.
+ *
+ * Threshold chosen conservatively at 4000 chars (~100 lines). Below that, the
+ * hook is a no-op.
+ *
+ * @p95ms 20
+ * @maxBlockingScope none (PostToolUse, non-blocking)
+ */
+import { readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const SIZE_THRESHOLD_CHARS = 4000;
+const LOG_DIR = join(homedir(), '.cx', 'bash-logs');
+const WARN_FLAGS = join(homedir(), '.cx', 'warn-flags.txt');
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+if ((input?.tool_name || '') !== 'Bash') process.exit(0);
+
+const stdout = String(input?.tool_response?.stdout ?? '');
+const stderr = String(input?.tool_response?.stderr ?? '');
+const command = String(input?.tool_input?.command ?? '');
+const totalSize = stdout.length + stderr.length;
+
+if (totalSize < SIZE_THRESHOLD_CHARS) process.exit(0);
+
+try {
+  mkdirSync(LOG_DIR, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const logPath = join(LOG_DIR, `bash-${ts}.log`);
+  const payload = [
+    `# Command`,
+    command,
+    ``,
+    `# Stdout (${stdout.length} chars)`,
+    stdout,
+    ``,
+    `# Stderr (${stderr.length} chars)`,
+    stderr,
+  ].join('\n');
+  writeFileSync(logPath, payload, 'utf8');
+
+  const approxLines = stdout.split('\n').length;
+  const kb = Math.round(totalSize / 1024);
+  process.stderr.write(
+    `[bash-output-logger] Output was ${approxLines} lines (${kb} KB). ` +
+    `Full log saved to ${logPath}. ` +
+    `Before re-running this command, reference the log with: grep/sed/head on ${logPath}. ` +
+    `Prefer \`| head -N\` or \`| tail -N\` on future runs to keep context lean.\n`
+  );
+
+  try {
+    appendFileSync(
+      WARN_FLAGS,
+      `Bash output ${kb} KB saved to ${logPath} — prefer grepping the log over re-running.\n`,
+    );
+  } catch { /* best effort */ }
+} catch { /* best effort */ }
+
+process.exit(0);

package/lib/hooks/block-no-verify.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/block-no-verify.mjs — refuse `git commit/push/merge --no-verify`.
+ *
+ * Runs as PreToolUse on Bash. Pre-commit / pre-push hooks exist to keep red
+ * code from landing; --no-verify bypasses them entirely. If a hook is
+ * failing, fix the underlying issue.
+ *
+ * Vendored from block-no-verify@1.1.2 (Elastic-2.0) to drop the per-Bash-call
+ * npx cold-start tax and remove the third-party dependency for ~30 lines of
+ * logic that we already maintain comment + audit policy for.
+ *
+ * @p95ms 5
+ * @maxBlockingScope PreToolUse
+ */
+import { readFileSync } from 'node:fs';
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const command = String(input?.tool_input?.command || '').trim();
+if (!command) process.exit(0);
+
+const isGitCommit = /^git\s+commit\b/.test(command);
+const isGitPushMergeEtc = /^git\s+(push|merge|am|rebase|cherry-pick|notes|revert|tag)\b/.test(command);
+
+if (!isGitCommit && !isGitPushMergeEtc) process.exit(0);
+
+const hasLongFlag = /(?:^|\s)--no-verify(?:\s|=|$)/.test(command);
+const hasShortN = isGitCommit && /(?:^|\s)-n(?:\s|$)/.test(command);
+
+if (hasLongFlag || hasShortN) {
+  process.stderr.write(
+    `[block-no-verify] BLOCKED: --no-verify bypasses pre-commit / pre-push hooks.\n` +
+    `Command: ${command.slice(0, 200)}\n` +
+    `If a hook is failing, fix the underlying issue instead of skipping it.\n`,
+  );
+  process.exit(2);
+}
+
+process.exit(0);

package/lib/hooks/ci-status-check.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/ci-status-check.mjs — UserPromptSubmit hook: inject remote CI status into agent context.
+ *
+ * Queries `gh run list --branch=<current> --limit=1` once per user prompt and,
+ * if the last run on the current branch failed, prints a stderr line that the
+ * agent will see in its next observation. Without this, an agent has no way
+ * to know remote CI is red without explicitly running gh — which means failed
+ * jobs go unnoticed until the user catches them. Non-blocking.
+ *
+ * Cached on disk for 60s so frequent prompts don't spam the gh API.
+ * Skipped silently if gh is not installed, not authenticated, or the dir is
+ * not a git repo.
+ *
+ * @p95ms 4000
+ * @maxBlockingScope none (UserPromptSubmit, non-blocking)
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+const CACHE_PATH = join(homedir(), '.cx', 'ci-status-cache.json');
+const CACHE_TTL_MS = 60_000;
+
+let cwd = process.cwd();
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  if (input?.cwd) cwd = input.cwd;
+} catch {}
+
+function safeExec(cmd, opts = {}) {
+  try { return execSync(cmd, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000, ...opts }).toString().trim(); }
+  catch { return null; }
+}
+
+const branch = safeExec('git branch --show-current');
+if (!branch) process.exit(0);
+
+const cacheKey = `${cwd}::${branch}`;
+let cache = {};
+try { cache = JSON.parse(readFileSync(CACHE_PATH, 'utf8')); } catch {}
+const cached = cache[cacheKey];
+const now = Date.now();
+
+let conclusion = null;
+let runId = null;
+let runUrl = null;
+
+if (cached && (now - cached.fetchedAt) < CACHE_TTL_MS) {
+  conclusion = cached.conclusion;
+  runId = cached.runId;
+  runUrl = cached.runUrl;
+} else {
+  const json = safeExec(
+    `gh run list --branch=${JSON.stringify(branch)} --limit=1 --json conclusion,databaseId,url`,
+    { timeout: 4000 },
+  );
+  if (!json) process.exit(0);
+  try {
+    const [run] = JSON.parse(json);
+    if (run) {
+      conclusion = run.conclusion;
+      runId = run.databaseId;
+      runUrl = run.url;
+      cache[cacheKey] = { conclusion, runId, runUrl, fetchedAt: now };
+      try {
+        mkdirSync(dirname(CACHE_PATH), { recursive: true });
+        writeFileSync(CACHE_PATH, JSON.stringify(cache));
+      } catch {}
+    }
+  } catch {}
+}
+
+if (conclusion === 'failure') {
+  process.stderr.write(
+    `[ci] Last CI run on branch '${branch}' FAILED (run ${runId}).\n  ${runUrl || ''}\n  Investigate with: gh run view ${runId} --log-failed\n  Do not stop the session until the failure is fixed or explicitly acknowledged (CONSTRUCT_STOP_OK_RED_CI=1).\n`,
+  );
+}
+
+process.exit(0);