@geraldmaron/construct 1.0.11 → 1.0.14

package/lib/hooks/audit-reads.mjs

@@ -1,41 +1,56 @@
 #!/usr/bin/env node
 /**
- * lib/hooks/audit-reads.mjs — opt-in tamper-evident log of every Read tool call.
+ * lib/hooks/audit-reads.mjs — post-Read state tracker.
  *
- * 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:
+ * Two responsibilities on every Read tool call:
  *
- *   - 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)
+ *   1. ALWAYS — upsert a file-hash entry in ~/.cx/file-hashes.json keyed by
+ *      absolute path, with the current sha256 + size + iso timestamp.
+ *      Edit-guard reads the store to detect staleness on a subsequent Edit:
+ *      mismatched on-disk content versus the stored hash means the Edit
+ *      target needs a fresh Read. A read-tracker delta is recorded for the
+ *      efficiency snapshot in the same pass.
  *
- * 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).
+ *   2. OPT-IN — when `CONSTRUCT_AUDIT_READS=1`, write a single JSONL line
+ *      to <project>/.cx/audit-reads.jsonl (falls back to ~/.cx/ outside a
+ *      project) with timestamp, session_id, agent, cwd, target, bytes,
+ *      content_hash, and prev_line_hash. The prev_line_hash chain makes
+ *      after-the-fact reordering or deletion detectable by simple replay
+ *      (symmetric counterpart to audit-trail.mjs for mutations). Bounded
+ *      via the `audit-reads` channel.
+ *
+ * Reads happen far more often than writes, so the audit log is opt-in.
+ * The hash store is always-on because edit-guard depends on it for
+ * correctness, not telemetry.
  *
  * @p95ms 8
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Read
+ * @exits 0 = pass
  */
-import { readFileSync, appendFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { join, resolve } from 'node:path';
+import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { logHookFailure } from './_lib/log.mjs';
+import { appendBounded, readLastLineAcrossSegments } from '../logging/rotate.mjs';
+import { resolveProjectScopedPath } from '../project-root.mjs';
+import { flushReadTrackerDeltas, recordReadDelta } from '../read-tracker-store.mjs';
 
 const CX_DIR = join(homedir(), '.cx');
-const AUDIT_FILE = join(CX_DIR, 'audit-reads.jsonl');
+// audit-reads.jsonl is PROJECT-SCOPED — reads happen in a specific project,
+// not across the user's whole machine. resolveProjectScopedPath returns
+// <project>/.cx/audit-reads.jsonl when the hook fires from inside a
+// Construct project, falling back to the legacy ~/.cx path otherwise so
+// existing standalone invocations keep working.
+
+const AUDIT_FILE = resolveProjectScopedPath('audit-reads.jsonl', { ensureDir: false });
+const HASH_STORE = join(CX_DIR, 'file-hashes.json');
 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);
+const HASH_RETENTION_MS = 2 * 60 * 60 * 1000;
 
 function sha256(input) { return createHash('sha256').update(input).digest('hex'); }
 
@@ -48,14 +63,9 @@ function readLastAgent() {
 
 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]);
+    const lastLine = readLastLineAcrossSegments(AUDIT_FILE);
+    if (lastLine === null) return null;
+    return sha256(lastLine);
   } catch { return null; }
 }
 
@@ -71,22 +81,53 @@ if (!filePath) process.exit(0);
 
 const absPath = filePath.startsWith('/') ? filePath : resolve(cwd, filePath);
 
+// Stage 1 — always-on hash store update for edit-guard staleness detection.
+
+let fullContent = null;
 let bytes = null;
-let contentHash = null;
+let prefixHash = 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);
+    fullContent = readFileSync(absPath, 'utf8');
+    bytes = Buffer.byteLength(fullContent, 'utf8');
+    const prefix = Buffer.from(fullContent, 'utf8').slice(0, HASH_PREFIX_BYTES);
+    prefixHash = sha256(prefix).slice(0, 32);
+
+    const edgeHash = createHash('sha256').update(fullContent).digest('hex').slice(0, 16);
+    const nowIso = new Date().toISOString();
+    const requestedLimit = Number(input?.tool_input?.limit || 0);
+    const effectiveLimit = requestedLimit > 0 ? requestedLimit : 2000;
+
+    mkdirSync(CX_DIR, { recursive: true });
+    let store = {};
+    try { store = JSON.parse(readFileSync(HASH_STORE, 'utf8')); } catch { /* fresh store */ }
+    store[absPath] = { hash: edgeHash, ts: nowIso, size: fullContent.length };
+
+    const cutoff = Date.now() - HASH_RETENTION_MS;
+    for (const [k, v] of Object.entries(store)) {
+      if (new Date(v.ts).getTime() < cutoff) delete store[k];
+    }
+    writeFileSync(HASH_STORE, JSON.stringify(store, null, 2));
+
+    recordReadDelta({
+      path: absPath,
+      size: fullContent.length,
+      limit: effectiveLimit,
+      ts: nowIso,
+    }, process.env);
+
+    if (process.env.CONSTRUCT_READ_TRACKER_FLUSH === '1') {
+      flushReadTrackerDeltas({ nowIso, env: process.env });
+    }
   }
 } catch (err) {
-  logHookFailure({ hook: 'audit-reads', err, phase: 'hash', input: { filePath: absPath } });
+  logHookFailure({ hook: 'audit-reads', err, phase: 'hash-store', input: { filePath: absPath } });
 }
 
+// Stage 2 — opt-in tamper-evident audit log.
+
+if (process.env.CONSTRUCT_AUDIT_READS !== '1') process.exit(0);
+
 const record = {
   ts: new Date().toISOString(),
   session_id: input?.session_id || null,
@@ -95,13 +136,13 @@ const record = {
   cwd,
   target: filePath,
   bytes,
-  content_hash: contentHash,
+  content_hash: prefixHash,
   prev_line_hash: readPrevLineHash(),
 };
 
 try {
-  mkdirSync(CX_DIR, { recursive: true });
-  appendFileSync(AUDIT_FILE, JSON.stringify(record) + '\n', 'utf8');
+  mkdirSync(dirname(AUDIT_FILE), { recursive: true });
+  appendBounded('audit-reads', AUDIT_FILE, JSON.stringify(record) + '\n');
 } catch (err) {
   logHookFailure({ hook: 'audit-reads', err, phase: 'append' });
 }

package/lib/hooks/audit-trail.mjs

@@ -7,7 +7,9 @@
  * 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:
+ * Each record is a single JSONL line written to
+ * <project>/.cx/audit-trail.jsonl (falls back to ~/.cx/audit-trail.jsonl
+ * when the hook fires outside a Construct project) with:
  *   - timestamp ISO
  *   - session_id (from hook input when available)
  *   - tool_name
@@ -21,18 +23,26 @@
  *   - 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.
+ * breaks the chain and is detectable by a simple replay. Bounded via the
+ * `audit-trail` channel registered in lib/logging/rotate.mjs LIMITS.
  *
  * @p95ms 15
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Edit|Write|MultiEdit|NotebookEdit|Bash
+ * @exits 0 = pass
  */
-import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { join, resolve } from 'node:path';
+import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
+import { appendBounded, readLastLineAcrossSegments } from '../logging/rotate.mjs';
+import { resolveProjectScopedPath } from '../project-root.mjs';
+import { logHookFailure } from './_lib/log.mjs';
 
 const CX_DIR = join(homedir(), '.cx');
-const AUDIT_FILE = join(CX_DIR, 'audit-trail.jsonl');
+const AUDIT_FILE = resolveProjectScopedPath('audit-trail.jsonl', { ensureDir: false });
 const LAST_AGENT = join(CX_DIR, 'last-agent.json');
 const MUTATING_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Bash']);
 
@@ -69,14 +79,9 @@ function readLastAgent() {
 
 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]);
+    const lastLine = readLastLineAcrossSegments(AUDIT_FILE);
+    if (lastLine === null) return null;
+    return sha256(lastLine);
   } catch {
     return null;
   }
@@ -89,7 +94,8 @@ function truncateSnippet(s, limit = 280) {
 }
 
 let input = {};
-try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+try { input = JSON.parse(readFileSync(0, 'utf8')); }
+catch (err) { logHookFailure({ hook: 'audit-trail', err, phase: 'parse' }); process.exit(0); }
 
 const toolName = input?.tool_name || '';
 if (!MUTATING_TOOLS.has(toolName)) process.exit(0);
@@ -129,7 +135,9 @@ if (toolName !== 'Bash' && target) {
     if (existsSync(absPath)) {
       contentHash = sha256(readFileSync(absPath, 'utf8')).slice(0, 32);
     }
-  } catch { /* best effort */ }
+  } catch (err) {
+    logHookFailure({ hook: 'audit-trail', err, phase: 'hash', input: { target: absPath } });
+  }
 }
 
 const record = {
@@ -146,8 +154,10 @@ const record = {
 };
 
 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 */ }
+  mkdirSync(dirname(AUDIT_FILE), { recursive: true });
+  appendBounded('audit-trail', AUDIT_FILE, JSON.stringify(record) + '\n');
+} catch (err) {
+  logHookFailure({ hook: 'audit-trail', err, phase: 'append' });
+}
 
 process.exit(0);

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

@@ -14,10 +14,15 @@
  *
  * @p95ms 20
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Bash
+ * @exits 0 = pass
  */
-import { readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { appendBounded } from '../logging/rotate.mjs';
 
 const SIZE_THRESHOLD_CHARS = 4000;
 const LOG_DIR = join(homedir(), '.cx', 'bash-logs');
@@ -61,7 +66,8 @@ try {
   );
 
   try {
-    appendFileSync(
+    appendBounded(
+      'bash-warn-flags',
       WARN_FLAGS,
       `Bash output ${kb} KB saved to ${logPath} — prefer grepping the log over re-running.\n`,
     );

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

@@ -12,6 +12,10 @@
  *
  * @p95ms 5
  * @maxBlockingScope PreToolUse
+ *
+ * @lifecycle PreToolUse
+ * @matcher  Bash
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync } from 'node:fs';
 

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

@@ -14,6 +14,10 @@
  *
  * @p95ms 4000
  * @maxBlockingScope none (UserPromptSubmit, non-blocking)
+ *
+ * @lifecycle UserPromptSubmit
+ * @matcher  *
+ * @exits 0 = pass
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'node:fs';

package/lib/hooks/comment-lint.mjs

@@ -7,13 +7,17 @@
  * 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.
+ * No bypass. If the policy fires on a legitimate comment, the policy is wrong
+ * — fix the policy in lib/comment-lint.mjs, not the call site.
  *
  * Input: reads tool_input.file_path from either the legacy TOOL_INPUT_FILE_PATH
  * env var or modern stdin JSON ({ tool_input: { file_path } }).
  *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit|MultiEdit
  * @p95ms 60
  * @maxBlockingScope PostToolUse
+ * @exits 0 = pass | 2 = block tool call
  */
 
 import { readFileSync } from 'node:fs';
@@ -21,8 +25,6 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { lintFile, formatResults } from '../comment-lint.mjs';
 
-if (process.env.CONSTRUCT_SKIP_COMMENT_LINT === '1') process.exit(0);
-
 let filePath = process.env.TOOL_INPUT_FILE_PATH;
 if (!filePath) {
   try {
@@ -59,6 +61,6 @@ if (artifactOnly) {
 }
 
 process.stderr.write(
-  '\nComment policy blocked this edit. Remove the violations or set CONSTRUCT_SKIP_COMMENT_LINT=1.\n',
+  '\nComment policy blocked this edit. Remove the violations before continuing.\n',
 );
 process.exit(2);

package/lib/hooks/config-protection.mjs

@@ -16,6 +16,10 @@
  *
  * @p95ms 5
  * @maxBlockingScope PreToolUse
+ *
+ * @lifecycle PreToolUse
+ * @matcher  Write|Edit|MultiEdit
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync } from 'fs';
 import { logHookFailure } from './_lib/log.mjs';

package/lib/hooks/context-watch.mjs

@@ -26,6 +26,10 @@
  *
  * @p95ms 20
  * @maxBlockingScope UserPromptSubmit
+ *
+ * @lifecycle UserPromptSubmit
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';

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

@@ -6,6 +6,10 @@
  *
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUseFailure
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { homedir } from 'os';

package/lib/hooks/dep-audit.mjs

@@ -8,11 +8,17 @@
  *
  * @p95ms 5000
  * @maxBlockingScope none (PostToolUse, async, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit
+ * @exits 0 = pass
  */
-import { readFileSync, writeFileSync, existsSync, appendFileSync } from 'fs';
-import { execSync } from 'child_process';
-import { homedir } from 'os';
-import { join, dirname, basename } from 'path';
+import { readFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, dirname, basename } from 'node:path';
+import { appendBounded } from '../logging/rotate.mjs';
+import { logHookFailure } from './_lib/log.mjs';
 
 const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
 if (!filePath) process.exit(0);
@@ -28,7 +34,8 @@ const projectDir = dirname(filePath);
 const warnFlagsPath = join(homedir(), '.cx', 'warn-flags.txt');
 
 function appendWarn(msg) {
-  try { appendFileSync(warnFlagsPath, msg + '\n'); } catch { /* best effort */ }
+  try { appendBounded('bash-warn-flags', warnFlagsPath, msg + '\n'); }
+  catch (err) { logHookFailure({ hook: 'dep-audit', err, phase: 'append' }); }
   process.stderr.write(`[dep-audit] ${msg}\n`);
   emitVulnerability(msg);
 }

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

@@ -12,6 +12,10 @@
  *
  * @p95ms 15
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit|MultiEdit
+ * @exits 0 = pass
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
@@ -73,7 +77,7 @@ 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`,
+    `[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).\n`,
   );
 }
 

package/lib/hooks/edit-accumulator.mjs

@@ -1,39 +1,54 @@
 #!/usr/bin/env node
 /**
- * lib/hooks/edit-accumulator.mjs — Edit accumulator hook — batches and summarizes recent file edits for context.
+ * lib/hooks/edit-accumulator.mjs — accumulates edited paths for the next
+ * typecheck batch.
  *
- * 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.
+ * Runs as PostToolUse after Edit/Write. Maintains two pieces of session
+ * state at ~/.cx/: a total edit counter for surface-area summaries and a
+ * deduped queue of TS/JS files awaiting typecheck. The typecheck queue is
+ * bounded via the `edit-accumulator` channel in lib/logging/rotate.mjs.
  *
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit|MultiEdit
+ * @exits 0 = pass
  */
-import { appendFileSync, readFileSync, writeFileSync, existsSync } from 'fs';
-import { homedir } from 'os';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { appendBounded } from '../logging/rotate.mjs';
+import { logHookFailure } from './_lib/log.mjs';
 
 const TS_EXTS = new Set(['.ts','.tsx','.js','.mjs','.jsx','.cjs']);
 const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
 
 if (!filePath) process.exit(0);
 
-const ext = '.' + filePath.split('.').pop();
+const ext = path.extname(filePath);
 const home = homedir();
-const countPath = `${home}/.cx/files-changed-count.txt`;
+const countPath = path.join(home, '.cx', 'files-changed-count.txt');
 
 // Always increment the total files-changed counter for notify
 try {
   const current = existsSync(countPath) ? parseInt(readFileSync(countPath, 'utf8').trim() || '0', 10) : 0;
   writeFileSync(countPath, String(current + 1));
-} catch { /* best effort */ }
+} catch (err) {
+  logHookFailure({ hook: 'edit-accumulator', err, phase: 'count' });
+}
 
 // Only accumulate TS/JS files for typecheck
 if (!TS_EXTS.has(ext)) process.exit(0);
 
-const tcPath = `${home}/.cx/pending-typecheck.txt`;
+const tcPath = path.join(home, '.cx', 'pending-typecheck.txt');
 try {
   const existing = existsSync(tcPath) ? readFileSync(tcPath, 'utf8').split('\n').filter(Boolean) : [];
   if (!existing.includes(filePath)) {
-    appendFileSync(tcPath, filePath + '\n');
+    appendBounded('edit-accumulator', tcPath, filePath + '\n');
   }
-} catch { /* best effort */ }
+} catch (err) {
+  logHookFailure({ hook: 'edit-accumulator', err, phase: 'append' });
+}
 
 process.exit(0);

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

@@ -6,6 +6,10 @@
  *
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUseFailure
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync } from 'fs';
 

package/lib/hooks/edit-guard.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 20
  * @maxBlockingScope PreToolUse
+ *
+ * @lifecycle PreToolUse
+ * @matcher  Edit|MultiEdit|Write
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync, existsSync } from 'fs';
 import { createHash } from 'crypto';

package/lib/hooks/guard-bash.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 5
  * @maxBlockingScope PreToolUse
+ *
+ * @lifecycle PreToolUse
+ * @matcher  Bash
+ * @exits 0 = pass | 2 = block tool call
  */
 import { createInterface } from 'readline';
 import { readFileSync, existsSync } from 'fs';

package/lib/hooks/mcp-audit.mjs

@@ -7,6 +7,10 @@
  *
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  mcp__.*
+ * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';

package/lib/hooks/mcp-health-check.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 51
  * @maxBlockingScope none (PreToolUse, warn-only)
+ *
+ * @lifecycle PreToolUse
+ * @matcher  mcp__.*
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { homedir } from 'os';

package/lib/hooks/model-fallback.mjs

@@ -15,8 +15,12 @@
  *
  * @p95ms 150
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUseFailure
+ * @matcher  *
+ * @exits 0 = pass
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -27,20 +31,12 @@ import {
   selectFallbackModel,
   writeProviderCooldown,
 } from '../model-router.mjs';
+import { readHookInput } from './_lib/input.mjs';
 
 const cooldownPath = join(homedir(), '.cx', 'provider-cooldowns.json');
 const envPath = join(process.cwd(), '.env');
 
-function readInput() {
-  try {
-    const raw = readFileSync(0, 'utf8');
-    return raw ? JSON.parse(raw) : {};
-  } catch {
-    return {};
-  }
-}
-
-const input = readInput();
+const input = readHookInput();
 
 const classified = classifyProviderFailure(input);
 if (!classified || !classified.retryable) process.exit(0);

package/lib/hooks/policy-engine.mjs

@@ -15,6 +15,10 @@
  *
  * @p95ms 80
  * @maxBlockingScope PreToolUse, Stop, UserPromptSubmit
+ *
+ * @lifecycle PreToolUse
+ * @matcher  Write|Edit|MultiEdit|NotebookEdit|TodoWrite|Read|Grep|Glob|LS|NotebookRead
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';

package/lib/hooks/post-merge-docs-check.mjs

@@ -10,6 +10,10 @@
  *
  * @p95ms 1500
  * @maxBlockingScope none (async, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Bash
+ * @exits 0 = pass
  */
 
 import { readFileSync } from 'node:fs';