@devrik-tools/claude-gates 0.7.2 → 0.9.0

package/plugins/gates/hooks/gates/protected-paths/index.mjs

@@ -1,22 +1,18 @@
-// protected-paths — denies writes and mutating shell commands that target a path
-// containing one of the project's protected fragments (.env, lockfiles, the harness
-// itself). Migrated from ~/.claude/hooks/guard-protected-paths.mjs: that guard protected
-// hardcoded "code directories" (src, tests) to force delegation through a Leader role.
-// This gate keeps only the path-protection mechanism — sensitive files no write should
-// ever touch — and drops the Leader-role/delegation policy, which is a different concern.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   protectedPaths     path fragments (case-insensitive) that no write or mutating
-//                       command may target. Replaces the built-in list wholesale.
-//   mutatingCommands    shell command names treated as mutating, so a merely-reading
-//                       command that mentions a protected path (echo, cat, grep) is
-//                       never denied. Replaces the built-in list wholesale.
-// The defaults live here, in the source, so a project reads them and knows exactly what
-// its override replaces.
-
+// protected-paths — denies a write, a shell redirection or a mutating shell command that
+// targets a protected path (.env files, lockfiles, the harness's own hooks). Deliberate
+// semantics: a fragment without a slash names a file by its exact basename (`.env` is not
+// `.env.example`), a fragment ending in a slash names a contiguous directory sequence
+// (`.claude/hooks/` is not `src/hooks/`). Only the command segment that RUNS a mutating
+// command is judged, so `npm install; cat .env` reads and is allowed. A path built from a
+// variable is not resolved.
+
+import { posix } from 'node:path';
 import {
-  runGate,
+  compileRegexList,
   deny,
+  runGate,
+  shellCommandOf,
+  shellWrittenPaths,
   toolInGroups,
   writtenPathOf,
 } from '../../lib/hook-io.mjs';
@@ -26,94 +22,145 @@ const CONFIG_KEY = 'blockWritesToProtectedPaths';
 
 const DEFAULT_PROTECTED_PATHS = [
   '.env',
+  '.env.local',
+  '.env.production',
+  '.env.development',
   'package-lock.json',
   'yarn.lock',
   'pnpm-lock.yaml',
-  'hooks/',
+  '.claude/hooks/',
 ];
 
+// Regex sources matched at the start of a command segment. A command is mutating when its
+// ARGUMENTS name the protected path; redirections are covered separately by shellWrittenPaths.
 const DEFAULT_MUTATING_COMMANDS = [
   'touch',
   'rm',
   'cp',
   'mv',
-  'sed\\s+-i',
+  String.raw`sed\s+(?:-i|--in-place)`,
   'tee',
   'install',
   'chmod',
   'chown',
   'truncate',
+  'unlink',
+  'dd',
+  String.raw`perl\s+-\w*i`,
+  String.raw`git\s+checkout\s+--`,
+  String.raw`git\s+restore`,
+  'Set-Content',
+  'Add-Content',
+  'Out-File',
+  'Remove-Item',
+  'del',
+  'erase',
+  'Copy-Item',
+  'Move-Item',
+  'New-Item',
+  'Rename-Item',
+  'copy',
+  'move',
+  'ren',
 ];
 
-function escapeRegExp(fragment) {
-  return fragment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// ── Path matching ───────────────────────────────────────────────────────────────────
+function pathSegmentsOf(path) {
+  const normalized = posix.normalize(String(path).replace(/\\/g, '/'));
+  return normalized.toLowerCase().split('/').filter(Boolean);
 }
 
-// Windows delivers absolute paths with backslashes ('C:\repo\hooks\gates\x.mjs'), but a
-// protected fragment like 'hooks/' is written with a forward slash. Normalizing the
-// separator before comparing means the fragment matches regardless of which OS produced
-// the path, without weakening the existing case-insensitive comparison.
-function toForwardSlashes(path) {
-  return path.replace(/\\/g, '/');
+function fragmentRule(fragment) {
+  const segments = pathSegmentsOf(fragment);
+  return {
+    fragment,
+    segments,
+    anchoredAtEnd: !String(fragment).endsWith('/'),
+  };
 }
 
-function isProtectedPath(path, protectedPaths) {
-  const normalized = toForwardSlashes(path).toLowerCase();
-  return protectedPaths.some((fragment) =>
-    normalized.includes(fragment.toLowerCase()),
+function segmentsMatchAt(pathSegments, ruleSegments, offset) {
+  return ruleSegments.every(
+    (segment, index) => pathSegments[offset + index] === segment,
   );
 }
 
-function buildCommandPatterns(protectedPaths, mutatingCommands) {
-  const pathAlternation = protectedPaths.map(escapeRegExp).join('|');
-  const mutatingAlternation = mutatingCommands.join('|');
-  const wordBoundary = String.raw`\b`;
-  const redirectPrefix = String.raw`>>?\s*\S*`;
-  return {
-    mutatingCommand: new RegExp(
-      `${wordBoundary}(${mutatingAlternation})${wordBoundary}`,
-      'i',
-    ),
-    protectedTarget: new RegExp(`(${pathAlternation})`, 'i'),
-    redirectToProtected: new RegExp(
-      `${redirectPrefix}(${pathAlternation})`,
-      'i',
-    ),
-  };
+function ruleMatches(rule, pathSegments) {
+  const { segments, anchoredAtEnd } = rule;
+  if (segments.length === 0 || pathSegments.length < segments.length)
+    return false;
+  if (anchoredAtEnd) {
+    return segmentsMatchAt(
+      pathSegments,
+      segments,
+      pathSegments.length - segments.length,
+    );
+  }
+  const lastOffset = pathSegments.length - segments.length;
+  for (let offset = 0; offset <= lastOffset; offset += 1) {
+    if (segmentsMatchAt(pathSegments, segments, offset)) return true;
+  }
+  return false;
 }
 
-/** The write-tool branch: deny when the target path matches a protected fragment. */
-function checkWrite(toolInput, protectedPaths) {
-  const target = writtenPathOf(toolInput);
-  if (target && isProtectedPath(target, protectedPaths)) {
-    deny(
-      CONFIG_KEY,
-      `Writing to '${target}' is not allowed: it matches a protected path (${protectedPaths.join(', ')}).`,
-    );
+function protectedFragmentOf(path, rules) {
+  const pathSegments = pathSegmentsOf(path);
+  return rules.find((rule) => ruleMatches(rule, pathSegments))?.fragment;
+}
+
+// ── Shell command arguments ─────────────────────────────────────────────────────────
+const SEGMENT_SEPARATOR = /;|&&|\|\||\||\n/;
+const ARGUMENT_PATTERN = /"([^"]*)"|'([^']*)'|(\S+)/g;
+const KEY_VALUE_PREFIX = /^-{0,2}[\w-]+=/;
+
+function stripLeadingWrappers(segment) {
+  const tokens = segment.trim().split(/\s+/);
+  while (tokens.length > 0 && /^(?:sudo|command|env|\w+=\S*)$/i.test(tokens[0]))
+    tokens.shift();
+  return tokens.join(' ');
+}
+
+function argumentsOf(text) {
+  const found = [];
+  for (const match of text.matchAll(ARGUMENT_PATTERN)) {
+    const token =
+      match[1] ?? match[2] ?? match[3].replace(KEY_VALUE_PREFIX, '');
+    if (token && !/[$`%]/.test(token)) found.push(token);
   }
+  return found;
 }
 
-/** The shell-tool branch: deny a mutating command whose target matches a protected path. */
-function checkShellCommand(toolInput, protectedPaths, mutatingCommands) {
-  const rawCommand = String(toolInput.CommandLine ?? toolInput.command ?? '');
-  if (!rawCommand.trim()) return;
-  // Same separator normalization as the write branch: a command embedding a Windows
-  // path ('rm C:\repo\hooks\gates\evil.mjs') must still match a 'hooks/' fragment.
-  const command = toForwardSlashes(rawCommand);
-
-  const { mutatingCommand, protectedTarget, redirectToProtected } =
-    buildCommandPatterns(protectedPaths, mutatingCommands);
-
-  const targetsProtected =
-    redirectToProtected.test(command) ||
-    (mutatingCommand.test(command) && protectedTarget.test(command));
-
-  if (targetsProtected) {
-    deny(
-      CONFIG_KEY,
-      `This command targets a protected path (${protectedPaths.join(', ')}) with a mutating operation. ` +
-        'Reading (echo/cat/grep) is fine; modifying it is not.',
-    );
+function mutatingCommandPatterns(sources) {
+  return compileRegexList(
+    sources.map((source) => String.raw`^(?:${source})(?=\s|$)`),
+  ).patterns;
+}
+
+function mutatedArguments(command, patterns) {
+  const found = [];
+  for (const rawSegment of String(command).split(SEGMENT_SEPARATOR)) {
+    const segment = stripLeadingWrappers(rawSegment);
+    const matched = patterns
+      .map((pattern) => pattern.exec(segment))
+      .find(Boolean);
+    if (matched) found.push(...argumentsOf(segment.slice(matched[0].length)));
+  }
+  return found;
+}
+
+function denyProtected(target, fragment) {
+  deny(
+    CONFIG_KEY,
+    `Writing to '${target}' is not allowed: it matches the protected path '${fragment}'. ` +
+      'Reading it is fine; to change it, ask the user, or edit protectedPaths under ' +
+      `${CONFIG_KEY} in .ai/config.json.`,
+  );
+}
+
+function checkTargets(targets, rules) {
+  for (const target of targets) {
+    const fragment = protectedFragmentOf(target, rules);
+    if (fragment) denyProtected(target, fragment);
   }
 }
 
@@ -128,22 +175,22 @@ runGate(
     },
   },
   ({ toolName, toolInput, parameters }) => {
-    const isWrite = toolInGroups(toolName, ['write']);
-    const isShell = toolInGroups(toolName, ['shell']);
-    if (!isWrite && !isShell) return;
+    const rules = parameters.protectedPaths
+      .map(fragmentRule)
+      .filter((rule) => rule.segments.length > 0);
+    if (rules.length === 0) return;
 
-    const protectedPaths = parameters.protectedPaths ?? [];
-    if (protectedPaths.length === 0) return;
-
-    if (isWrite) {
-      checkWrite(toolInput, protectedPaths);
+    if (toolInGroups(toolName, ['write'])) {
+      checkTargets([writtenPathOf(toolInput)].filter(Boolean), rules);
       return;
     }
-
-    checkShellCommand(
-      toolInput,
-      protectedPaths,
-      parameters.mutatingCommands ?? [],
-    );
+    if (!toolInGroups(toolName, ['shell'])) return;
+
+    const command = shellCommandOf(toolInput);
+    if (!command.trim()) return;
+    checkTargets(shellWrittenPaths(command), rules);
+    const patterns = mutatingCommandPatterns(parameters.mutatingCommands);
+    if (patterns.length > 0)
+      checkTargets(mutatedArguments(command, patterns), rules);
   },
 );

package/plugins/gates/hooks/gates/recurrence-lock/index.mjs

@@ -1,66 +1,108 @@
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { runGate, deny, toolInGroups } from '../../lib/hook-io.mjs';
+// recurrence-lock — while a registered defect class is open and at/above the threshold,
+// mutating work is denied until its root cause is closed. Whatever is needed to CLOSE the
+// class stays allowed (editing the recurrence file, read-only inspection, read-only
+// delegation), otherwise the lock would deadlock on its own remedy.
+
+import { basename, join } from 'node:path';
+import { projectRootOf, readJsonOrNull } from '../../lib/config.mjs';
+import { isExemptQuery } from '../../lib/delegation.mjs';
+import {
+  runGate,
+  deny,
+  toolInGroups,
+  writtenPathOf,
+  shellCommandOf,
+  shellWrittenPaths,
+  delegationPromptOf,
+} from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'recurrence-lock';
 const CONFIG_KEY = 'blockRegisteredRecurrences';
 
-/**
- * De-duplicates occurrences before counting them against the threshold. An occurrence is
- * identified by its `id`/`hash` field when present (the intended identity for a logged
- * occurrence); a bare-scalar entry (number/string, as in the plain fixture shape used by
- * tests) is deduplicated by its own value instead, since it carries no other identity.
- * Without this, the same occurrence logged twice (a race or a bug in the writer) inflates
- * the count and trips the lock as if two distinct occurrences had happened.
- */
+const RECURRENCES_FILE = 'reincidencias.json';
+const RECURRENCES_RELATIVE_PATH = join('.ai', RECURRENCES_FILE);
+const DEFAULT_THRESHOLD = 2;
+
+const READ_ONLY_COMMANDS = [
+  'git status',
+  'git log',
+  'git diff',
+  'git show',
+  'git branch',
+  'cat',
+  'ls',
+  'dir',
+  'pwd',
+  'echo',
+  'grep',
+  'rg',
+  'find',
+  'head',
+  'tail',
+  'wc',
+  'type',
+  'get-content',
+  'get-childitem',
+  'node --test',
+  'npm test',
+  'npm run lint',
+];
+const SEGMENT_SEPARATOR = /&&|\|\||[;|\n]/;
+
+function segmentIsReadOnly(segment) {
+  const words = segment.trim().toLowerCase().split(/\s+/);
+  return READ_ONLY_COMMANDS.some((command) => {
+    const expected = command.split(' ');
+    return expected.every((word, index) => words[index] === word);
+  });
+}
+
+function isReadOnlyCommand(command) {
+  if (!command.trim()) return false;
+  if (shellWrittenPaths(command).length > 0) return false;
+  return command.split(SEGMENT_SEPARATOR).every(segmentIsReadOnly);
+}
+
+function isExemptCall(toolName, toolInput) {
+  if (toolInGroups(toolName, ['write']))
+    return basename(writtenPathOf(toolInput)) === RECURRENCES_FILE;
+  if (toolInGroups(toolName, ['shell']))
+    return isReadOnlyCommand(shellCommandOf(toolInput));
+  if (toolInGroups(toolName, ['delegation']))
+    return isExemptQuery(delegationPromptOf(toolInput));
+  return false;
+}
+
+// Identity is id/hash when present, else the value itself: the same occurrence logged
+// twice must not count as two.
 function dedupOccurrences(occurrences) {
   const seen = new Set();
-  const deduped = [];
-  for (const occurrence of occurrences) {
+  return occurrences.filter((occurrence) => {
     const identity =
       occurrence && typeof occurrence === 'object'
         ? String(occurrence.id ?? occurrence.hash ?? JSON.stringify(occurrence))
         : String(occurrence);
-    if (seen.has(identity)) continue;
+    if (seen.has(identity)) return false;
     seen.add(identity);
-    deduped.push(occurrence);
-  }
-  return deduped;
+    return true;
+  });
 }
 
-// The source guard (guard-reincidence-lock.mjs) reads pending recurrences
-// from a full tracking module (../scripts/memory/recurrences.mjs) with
-// close/decide/pending subcommands. That infrastructure belongs to another
-// project and does not exist here. This gate only reads a plain state file
-// at .ai/reincidencias.json if present, with the shape:
-//   { classes: [{ class, occurrences: [...], status }] }
-// If neither the module nor the file exists, it allows silently — there is
-// nothing to enforce without a recurrence record.
-function loadOpenRecurrences(projectRoot, thresholdAppearances) {
-  const filePath = join(projectRoot, '.ai', 'reincidencias.json');
-  if (!existsSync(filePath)) return [];
-
-  let parsed;
-  try {
-    parsed = JSON.parse(readFileSync(filePath, 'utf8'));
-  } catch {
-    return [];
-  }
+function isClosed(entry) {
+  const status = String(entry?.status ?? '')
+    .trim()
+    .toLowerCase();
+  return status === 'closed' || status === 'cerrada';
+}
 
+function loadOpenRecurrences(root, thresholdAppearances) {
+  const parsed = readJsonOrNull(join(root, RECURRENCES_RELATIVE_PATH));
   const classes = Array.isArray(parsed?.classes) ? parsed.classes : [];
   return classes.filter((entry) => {
     const occurrences = Array.isArray(entry?.occurrences)
       ? dedupOccurrences(entry.occurrences)
       : [];
-    const occurrenceCount = occurrences.length;
-    // Trim before lowercasing so a padded status ("Closed ", "cerrada\n") is recognized —
-    // a status compared without trimming left a validly-closed (but padded) recurrence
-    // stuck as still-open, blocking unrelated work indefinitely.
-    const status = String(entry?.status ?? '')
-      .trim()
-      .toLowerCase();
-    const isClosed = status === 'closed' || status === 'cerrada';
-    return occurrenceCount >= thresholdAppearances && !isClosed;
+    return occurrences.length >= thresholdAppearances && !isClosed(entry);
   });
 }
 
@@ -70,15 +112,16 @@ runGate(
     configKey: CONFIG_KEY,
     enabledByDefault: true,
     defaultParams: {
-      thresholdAppearances: 2,
+      thresholdAppearances: DEFAULT_THRESHOLD,
     },
   },
-  ({ toolName, parameters }) => {
+  ({ toolName, toolInput, parameters, cwd }) => {
     if (!toolInGroups(toolName, ['execution', 'delegation'])) return;
+    if (isExemptCall(toolName, toolInput)) return;
 
-    const recurrencesFile = join('.ai', 'reincidencias.json');
+    const root = projectRootOf(cwd) ?? cwd;
     const openRecurrences = loadOpenRecurrences(
-      process.cwd(),
+      root,
       parameters.thresholdAppearances,
     );
     if (openRecurrences.length === 0) return;
@@ -88,9 +131,10 @@ runGate(
       CONFIG_KEY,
       `Registered recurring issue class(es) still open and at/above the ` +
         `${parameters.thresholdAppearances}-occurrence threshold: ${names}. Fix the root ` +
-        `cause of the class (not this one instance), then in ${recurrencesFile} set that ` +
-        'class\'s "status" to "closed" (or "cerrada") before proceeding — no other file to ' +
-        'find, this is the only source this gate reads.',
+        `cause of the class (not this one instance), then in ${RECURRENCES_RELATIVE_PATH} set that ` +
+        'class\'s "status" to "closed" (or "cerrada") before proceeding — editing that file, ' +
+        'read-only commands (git status/log/diff, cat, grep, tests) and read-only delegations ' +
+        'stay allowed so you can do exactly that.',
     );
   },
 );

package/plugins/gates/hooks/gates/require-monitor/index.mjs

@@ -0,0 +1,126 @@
+// require-monitor — enforces that every background command has an associated Monitor.
+// Two-phase enforcement:
+//   1. PreToolUse on shell: a command with run_in_background: true MUST carry the marker
+//      MONITOR-PLANNED: <reason>. Without it, the background is denied.
+//   2. PreToolUse on execution+monitor: if the session has pending unmonitored backgrounds
+//      and the current tool is NOT Monitor, deny — forcing the agent to create a Monitor
+//      before doing anything else. When the current tool IS Monitor, the pending background
+//      is cleared.
+//
+// The marker is deterministic: no model judgment required. The pending-check is deterministic
+// too: state is on disk, the check is a read + compare, and the deny is unconditional.
+
+import {
+  deny,
+  runGate,
+  shellCommandOf,
+  toolInGroups,
+} from '../../lib/hook-io.mjs';
+import {
+  readSessionState,
+  writeSessionState,
+} from '../../lib/session-state.mjs';
+
+const GATE_ID = 'require-monitor';
+const CONFIG_KEY = 'requireMonitorForBackground';
+
+const DEFAULT_MARKER = 'MONITOR-PLANNED:';
+const MARKER_REASON_PATTERN = /\S\s\S/;
+const MAX_PENDING = 20;
+const MAX_COMMAND_PREVIEW_LENGTH = 200;
+
+function hasMarker(command, marker) {
+  if (!marker) return false;
+  const markerIndex = command.indexOf(marker);
+  if (markerIndex === -1) return false;
+  const afterMarker = command.slice(markerIndex + marker.length);
+  return MARKER_REASON_PATTERN.test(afterMarker);
+}
+
+function pendingBackgrounds(state) {
+  return Array.isArray(state.pending) ? state.pending : [];
+}
+
+function addPending(state, entry) {
+  const pending = [...pendingBackgrounds(state), entry].slice(-MAX_PENDING);
+  return { ...state, pending };
+}
+
+function clearOldestPending(state) {
+  const pending = pendingBackgrounds(state);
+  if (pending.length === 0) return state;
+  return { ...state, pending: pending.slice(1) };
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      monitorPlannedMarker: DEFAULT_MARKER,
+    },
+  },
+  ({ toolName, toolInput, sessionId, parameters, cwd }) => {
+    const isShell = toolInGroups(toolName, ['shell']);
+    const isMonitor = toolInGroups(toolName, ['monitor']);
+    const isExecution = toolInGroups(toolName, ['execution']);
+
+    if (!isShell && !isMonitor && !isExecution) return;
+
+    const stateOptions = { cwd };
+    const state = readSessionState(GATE_ID, sessionId, {}, stateOptions);
+    const marker = String(parameters.monitorPlannedMarker ?? DEFAULT_MARKER);
+
+    // Phase 2: if Monitor tool, clear oldest pending and allow.
+    if (isMonitor) {
+      const pending = pendingBackgrounds(state);
+      if (pending.length > 0) {
+        writeSessionState(
+          GATE_ID,
+          sessionId,
+          clearOldestPending(state),
+          stateOptions,
+        );
+      }
+      return;
+    }
+
+    // Phase 1: shell with run_in_background requires the marker.
+    if (isShell && toolInput.run_in_background === true) {
+      const command = shellCommandOf(toolInput);
+      if (!hasMarker(command, marker)) {
+        deny(
+          CONFIG_KEY,
+          `A background command MUST declare its Monitor plan. Add "${marker} <what the ` +
+            'Monitor will watch for>" to the command. Every background process needs a ' +
+            'Monitor — an unmonitored background is invisible work that can hang or fail ' +
+            'silently. The marker is a commitment to create a Monitor immediately after.',
+        );
+      }
+      writeSessionState(
+        GATE_ID,
+        sessionId,
+        addPending(state, {
+          command: command.slice(0, MAX_COMMAND_PREVIEW_LENGTH),
+          startedAt: Date.now(),
+        }),
+        stateOptions,
+      );
+      return;
+    }
+
+    // Phase 2: any execution/shell tool while backgrounds are unmonitored.
+    const pending = pendingBackgrounds(state);
+    if (pending.length > 0) {
+      const oldest = pending[0];
+      deny(
+        CONFIG_KEY,
+        `There are ${pending.length} background command(s) without a Monitor. Create a ` +
+          `Monitor for the pending background before doing anything else. Oldest pending: ` +
+          `"${oldest.command ?? '(unknown)'}". Use the Monitor tool to observe it, then ` +
+          'proceed with your next action.',
+      );
+    }
+  },
+);