@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/plugins/gates/hooks/gates/forge-flow/forge-flow.edge.test.mjs

@@ -0,0 +1,155 @@
+// Edge audit for forge-flow: fail-open vs fail-closed behavior, and the MCP write/shell
+// matcher hole (same structural gap as autonomous-mode's question hole, applied here to
+// ACTING_TOOLS = TOOL_GROUPS.write + TOOL_GROUPS.shell).
+
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const GATE = join(dirname(fileURLToPath(import.meta.url)), 'index.mjs');
+
+function adoptedProject() {
+  const project = mkdtempSync(join(tmpdir(), 'forge-edge-'));
+  mkdirSync(join(project, '.git'));
+  mkdirSync(join(project, '.ai'));
+  writeFileSync(join(project, '.ai', 'forge.json'), '{}');
+  return project;
+}
+
+function writeConfig(project, forgeDatabasePath, enabled = true) {
+  const gateEntry = { enabled };
+  if (forgeDatabasePath) gateEntry.forgeDatabasePath = forgeDatabasePath;
+  writeFileSync(
+    join(project, '.ai', 'config.json'),
+    JSON.stringify({ gates: { requireForgeRunToEdit: gateEntry } }),
+  );
+}
+
+function runGate(payload, project) {
+  const out = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    cwd: project,
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+function isWarn(result) {
+  const output = result?.hookSpecificOutput;
+  return Boolean(output?.additionalContext) && output.permissionDecision !== 'deny';
+}
+
+function makeForgeDatabase(directory, activeCwd) {
+  const databasePath = join(directory, 'forge.db');
+  const database = new DatabaseSync(databasePath);
+  database.exec(
+    'CREATE TABLE runs (id TEXT, cwd TEXT, current_phase TEXT, status TEXT)',
+  );
+  if (activeCwd) {
+    database
+      .prepare('INSERT INTO runs (id, cwd, current_phase, status) VALUES (?,?,?,?)')
+      .run('r1', activeCwd, 'build', 'active');
+  }
+  database.close();
+  return databasePath;
+}
+
+test('DEGRADED-WARN: a corrupt (non-SQLite) DB file allows the write but WARNS visibly', () => {
+  const project = adoptedProject();
+  const home = mkdtempSync(join(tmpdir(), 'forge-db-'));
+  const databasePath = join(home, 'forge.db');
+  writeFileSync(databasePath, 'this is not a sqlite file at all');
+  writeConfig(project, databasePath);
+  const result = runGate(
+    { tool_name: 'Write', tool_input: { file_path: 'x.js', content: 'x' } },
+    project,
+  );
+  // The catch-all no longer returns a silent "run present". A DB that cannot be read yields
+  // state 'unknown' -> the gate ALLOWS (a broken lookup must not freeze all work) but emits a
+  // warn, so degraded enforcement is never invisible. This is the fix for the old silent
+  // fail-open that disabled the whole gate with no trace.
+  assert.ok(isWarn(result), 'corrupt DB must allow-with-warning, not allow silently');
+});
+
+test('DEGRADED-WARN: DB exists but "runs" table is missing/wrong schema warns visibly', () => {
+  const project = adoptedProject();
+  const home = mkdtempSync(join(tmpdir(), 'forge-db-'));
+  const databasePath = join(home, 'forge.db');
+  const database = new DatabaseSync(databasePath);
+  database.exec('CREATE TABLE not_runs (id TEXT)');
+  database.close();
+  writeConfig(project, databasePath);
+  const result = runGate(
+    { tool_name: 'Write', tool_input: { file_path: 'x.js', content: 'x' } },
+    project,
+  );
+  assert.ok(isWarn(result), 'schema drift must allow-with-warning, not allow silently');
+});
+
+test('FAIL-CLOSED (deny): DB file plainly absent at the configured path denies the write', () => {
+  const project = adoptedProject();
+  writeConfig(project, join(tmpdir(), 'definitely-does-not-exist-' + Date.now(), 'forge.db'));
+  const result = runGate(
+    { tool_name: 'Write', tool_input: { file_path: 'x.js', content: 'x' } },
+    project,
+  );
+  // existsSync(forgeDatabasePath) is false -> hasActiveForgeRun returns false directly
+  // (line 72: "no DB yet -> no runs at all -> deny") -- this is the ONE path that is
+  // fail-closed; every other failure mode (corrupt file, missing table, locked file,
+  // node:sqlite unavailable) is fail-open via the catch block.
+  assert.ok(isDeny(result), 'FALLA(ok): absent DB is the sole fail-closed path');
+});
+
+test('FIXED: an MCP filesystem write tool is now gated (denied with no active run)', () => {
+  const project = adoptedProject();
+  const home = mkdtempSync(join(tmpdir(), 'forge-db-'));
+  const databasePath = makeForgeDatabase(home); // no active run: a real Write would be denied
+  writeConfig(project, databasePath);
+  const result = runGate(
+    {
+      tool_name: 'mcp__filesystem__write_file',
+      tool_input: { path: 'x.js', content: 'x' },
+    },
+    project,
+  );
+  // ACTING_GROUPS = ['execution'] and toolInGroups matches mcp__*__write_file via the write
+  // signal, so an MCP filesystem write is now subject to the active-run requirement exactly
+  // like a native Write. No active run -> deny.
+  assert.ok(isDeny(result), 'MCP write tool must now be gated like a native Write');
+});
+
+test('control: the same DB/config DOES deny a native Write (proves the MCP case above is a real gap, not a config issue)', () => {
+  const project = adoptedProject();
+  const home = mkdtempSync(join(tmpdir(), 'forge-db-'));
+  const databasePath = makeForgeDatabase(home); // no active run
+  writeConfig(project, databasePath);
+  const result = runGate(
+    { tool_name: 'Write', tool_input: { file_path: 'x.js', content: 'x' } },
+    project,
+  );
+  assert.ok(isDeny(result), 'FALLA(ok): native Write is correctly denied under identical setup');
+});
+
+test('FIXED: an MCP shell/exec tool (mcp__ide__executeCode) is now gated', () => {
+  const project = adoptedProject();
+  const home = mkdtempSync(join(tmpdir(), 'forge-db-'));
+  const databasePath = makeForgeDatabase(home); // no active run
+  writeConfig(project, databasePath);
+  const result = runGate(
+    { tool_name: 'mcp__ide__executeCode', tool_input: { code: 'require("fs").writeFileSync("x.js","x")' } },
+    project,
+  );
+  // forge-flow now consumes the 'execution' group, which includes mcp__ide__executeCode and,
+  // via toolInGroups, any mcp__* exec/run surface. No active run -> deny.
+  assert.ok(isDeny(result), 'mcp__ide__executeCode must now be gated by forge-flow');
+});

package/plugins/gates/hooks/gates/forge-flow/index.mjs

@@ -1,112 +1,134 @@
-// forge-flow — the enforcer forge cannot be. A forge MCP directs a pipeline but cannot
-// intercept Edit/Write/Bash, so nothing makes you actually use it. This gate closes that
-// hole: in a project that ADOPTED forge, a code-mutating action is denied unless there is
-// an active forge run for this project — so every change goes through the pipeline and you
-// always know which phase you are in.
-//
-// justification: no existing tool covers this. A forge MCP audit (see memory
-// forge-mcp-auditoria-flujo) confirmed the structural hole: an MCP cannot gate other tools;
-// only a Claude Code PreToolUse hook can. This is that hook.
-//
-// ── When it acts (never surprises you) ──────────────────────────────────────────────
-// Only when the project adopted forge — a marker on disk (.ai/forge.json, or `forge: true`
-// in .ai/config.json). In any other project it stays silent. Off by default in the
-// registry, so it never fires unless a project turns it on.
-//
-// ── How it checks (deterministic, no judgment) ──────────────────────────────────────
-// forge persists its runs in a SQLite DB (global by default). This gate reads that DB with
-// node:sqlite (a Node built-in — no npm, contract intact) and looks for an active run whose
-// cwd matches this project. Absent → deny with an actionable message. The DB unreadable or
-// node:sqlite unavailable → allow (fail open: a broken lookup must not block all work).
-
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'forge-flow';
-const CONFIG_KEY = 'requireForgeRunToEdit';
-
-const ACTING_TOOLS = new Set([...TOOL_GROUPS.write, ...TOOL_GROUPS.shell]);
-const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
-const DEFAULT_FORGE_DB = join('.forge', 'forge-mcp.db');
-const FORGE_MARKER_FILE = join('.ai', 'forge.json');
-const PROJECT_CONFIG_FILE = join('.ai', 'config.json');
-
-function projectRootOf(startDirectory) {
-  let current = startDirectory;
-  while (true) {
-    if (
-      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
-    ) {
-      return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
-function readJson(path) {
-  try {
-    return JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/** True when this project opted into forge: a marker file, or forge:true in .ai/config.json. */
-function projectAdoptedForge(root) {
-  if (existsSync(join(root, FORGE_MARKER_FILE))) return true;
-  const config = readJson(join(root, PROJECT_CONFIG_FILE));
-  return config?.forge === true;
-}
-
-/**
- * True when forge has an active run whose cwd is this project. Reads forge's SQLite DB with
- * node:sqlite (imported dynamically so an older Node without it degrades instead of
- * throwing). Any failure — module missing, DB absent, locked, unreadable, schema drift —
- * returns true: the gate must fail OPEN, since a broken lookup must never block every edit.
- */
-async function hasActiveForgeRun(root, forgeDatabasePath) {
-  if (!existsSync(forgeDatabasePath)) return false; // no DB yet → no runs at all → deny
-  try {
-    const { DatabaseSync } = await import('node:sqlite');
-    const database = new DatabaseSync(forgeDatabasePath, { readOnly: true });
-    const rows = database
-      .prepare("SELECT cwd FROM runs WHERE status = 'active'")
-      .all();
-    database.close();
-    return rows.some((row) => String(row.cwd) === root);
-  } catch {
-    return true; // node:sqlite missing, or DB locked/unreadable → fail open
-  }
-}
-
-const DENY_MESSAGE =
-  'This project uses forge, but there is no active forge run for it. Every change should ' +
-  'go through the pipeline so the next step is always clear. Start or resume a run ' +
-  '(forge_start / forge_next) before editing — that is how forge tells you which phase ' +
-  'you are in. To work outside the pipeline, turn this gate off in .ai/config.json.';
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: false,
-    defaultParams: { forgeDatabasePath: join(homedir(), DEFAULT_FORGE_DB) },
-  },
-  async ({ toolName, parameters }) => {
-    if (!ACTING_TOOLS.has(toolName)) return;
-
-    const root = projectRootOf(process.cwd());
-    if (!root) return; // no project
-    if (!projectAdoptedForge(root)) return; // project did not opt into forge
-
-    const forgeDatabasePath =
-      parameters.forgeDatabasePath ?? join(homedir(), DEFAULT_FORGE_DB);
-    if (await hasActiveForgeRun(root, forgeDatabasePath)) return;
-
-    deny(GATE_ID, DENY_MESSAGE);
-  },
-);
+// forge-flow — the enforcer forge cannot be. A forge MCP directs a pipeline but cannot
+// intercept Edit/Write/Bash, so nothing makes you actually use it. This gate closes that
+// hole: in a project that ADOPTED forge, a code-mutating action is denied unless there is
+// an active forge run for this project — so every change goes through the pipeline and you
+// always know which phase you are in.
+//
+// justification: no existing tool covers this. A forge MCP audit (see memory
+// forge-mcp-auditoria-flujo) confirmed the structural hole: an MCP cannot gate other tools;
+// only a Claude Code PreToolUse hook can. This is that hook.
+//
+// ── When it acts (never surprises you) ──────────────────────────────────────────────
+// Only when the project adopted forge — a marker on disk (.ai/forge.json, or `forge: true`
+// in .ai/config.json). In any other project it stays silent. Off by default in the
+// registry, so it never fires unless a project turns it on.
+//
+// ── How it checks (deterministic, no judgment) ──────────────────────────────────────
+// forge persists its runs in a SQLite DB (global by default). This gate reads that DB with
+// node:sqlite (a Node built-in — no npm, contract intact) and looks for an active run whose
+// cwd matches this project. Absent → deny with an actionable message. The DB unreadable or
+// node:sqlite unavailable → allow (fail open: a broken lookup must not block all work).
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { runGate, deny, warn, toolInGroups } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'forge-flow';
+const CONFIG_KEY = 'requireForgeRunToEdit';
+
+// Any code-mutating surface: native write/shell AND their MCP equivalents. `execution`
+// already unions write+shell+mcp__ide__executeCode, and toolInGroups adds the mcp__* signal
+// match — so an MCP filesystem-write or shell-exec tool no longer slips past the enforcer.
+const ACTING_GROUPS = ['execution'];
+const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
+const DEFAULT_FORGE_DB = join('.forge', 'forge-mcp.db');
+const FORGE_MARKER_FILE = join('.ai', 'forge.json');
+const PROJECT_CONFIG_FILE = join('.ai', 'config.json');
+
+function projectRootOf(startDirectory) {
+  let current = startDirectory;
+  while (true) {
+    if (
+      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
+    ) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** True when this project opted into forge: a marker file, or forge:true in .ai/config.json. */
+function projectAdoptedForge(root) {
+  if (existsSync(join(root, FORGE_MARKER_FILE))) return true;
+  const config = readJson(join(root, PROJECT_CONFIG_FILE));
+  return config?.forge === true;
+}
+
+/**
+ * True when forge has an active run whose cwd is this project. Reads forge's SQLite DB with
+ * node:sqlite (imported dynamically so an older Node without it degrades instead of
+ * throwing). Any failure — module missing, DB absent, locked, unreadable, schema drift —
+ * returns true: the gate must fail OPEN, since a broken lookup must never block every edit.
+ */
+// Returns one of three verdicts, so a broken lookup no longer masquerades as "run present":
+//   { state: 'active' }   → a run for this project exists; allow.
+//   { state: 'none' }     → DB readable, no active run for this project; deny.
+//   { state: 'unknown', reason } → DB absent/locked/corrupt/schema-drift, or node:sqlite
+//                                   missing; we cannot tell. Warn (visible) but allow, so a
+//                                   broken DB never blocks all work AND never disables the
+//                                   enforcer silently — the earlier code returned true here,
+//                                   which looked identical to "run present".
+async function forgeRunState(root, forgeDatabasePath) {
+  if (!existsSync(forgeDatabasePath)) return { state: 'none' }; // no DB yet → no runs → deny
+  try {
+    const { DatabaseSync } = await import('node:sqlite');
+    const database = new DatabaseSync(forgeDatabasePath, { readOnly: true });
+    const rows = database
+      .prepare("SELECT cwd FROM runs WHERE status = 'active'")
+      .all();
+    database.close();
+    return rows.some((row) => String(row.cwd) === root)
+      ? { state: 'active' }
+      : { state: 'none' };
+  } catch (error) {
+    return { state: 'unknown', reason: error?.message ?? String(error) };
+  }
+}
+
+const DENY_MESSAGE =
+  'This project uses forge, but there is no active forge run for it. Every change should ' +
+  'go through the pipeline so the next step is always clear. Start or resume a run ' +
+  '(forge_start / forge_next) before editing — that is how forge tells you which phase ' +
+  'you are in. To work outside the pipeline, turn this gate off in .ai/config.json.';
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: { forgeDatabasePath: join(homedir(), DEFAULT_FORGE_DB) },
+  },
+  async ({ toolName, parameters }) => {
+    if (!toolInGroups(toolName, ACTING_GROUPS)) return;
+
+    const root = projectRootOf(process.cwd());
+    if (!root) return; // no project
+    if (!projectAdoptedForge(root)) return; // project did not opt into forge
+
+    const forgeDatabasePath =
+      parameters.forgeDatabasePath ?? join(homedir(), DEFAULT_FORGE_DB);
+    const result = await forgeRunState(root, forgeDatabasePath);
+
+    if (result.state === 'active') return; // pipeline is running → allow
+    if (result.state === 'none') deny(GATE_ID, DENY_MESSAGE); // no run → block
+    // state 'unknown': the DB could not be read. Allow so a broken lookup never freezes work,
+    // but surface it loudly — a silent allow here would disable the enforcer without a trace.
+    warn(
+      GATE_ID,
+      `forge enforcement is degraded: the forge DB could not be read (${result.reason}). ` +
+        'Allowing this action, but the pipeline is NOT being enforced. Check that forge is ' +
+        `installed and ${forgeDatabasePath} is readable, or turn this gate off if intended.`,
+    );
+  },
+);

package/plugins/gates/hooks/gates/implementation-pipeline/edge.edge.test.mjs

@@ -0,0 +1,66 @@
+// Edge-case probe for implementation-pipeline. Previously the prompt was read only
+// from toolInput.prompt/Prompt/task, so a Task delegation carrying its brief in
+// `description` bypassed the pipeline check entirely. Migrated to
+// delegationPromptOf() (hook-io.mjs), which also reads description/instructions/
+// message/input, so this is now caught.
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const GATE = join(dirname(fileURLToPath(import.meta.url)), 'index.mjs');
+
+function runGate(payload, { config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'implementation-pipeline-edge-'));
+  mkdirSync(join(project, '.git'));
+  if (config) {
+    mkdirSync(join(project, '.ai'));
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  const out = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    cwd: project,
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+function enabledConfig() {
+  return { gates: { requireImplementationPipeline: true } };
+}
+
+test('FIXED: a Task delegation carrying its brief in `description` is now checked', () => {
+  const payload = {
+    tool_name: 'Task',
+    tool_input: {
+      description: 'Nivel: STANDARD\nImplementá el checkout.',
+      subagent_type: 'backend',
+    },
+  };
+  assert.ok(
+    isDeny(runGate(payload, { config: enabledConfig() })),
+    'delegationPromptOf reads description and the missing-pipeline-stages deny fires',
+  );
+});
+
+test('OK: the equivalent payload using `prompt` IS caught (control)', () => {
+  const payload = {
+    tool_name: 'Task',
+    tool_input: {
+      prompt: 'Nivel: STANDARD\nImplementá el checkout.',
+      subagent_type: 'backend',
+    },
+  };
+  assert.ok(
+    isDeny(runGate(payload, { config: enabledConfig() })),
+    'control failed',
+  );
+});