@devrik-tools/claude-gates 0.8.0 → 0.9.0

package/plugins/gates/hooks/gates/circuit-breaker/track.mjs

@@ -0,0 +1,285 @@
+// circuit-breaker PostToolUse tracker — records a delegation attempt AFTER it was allowed
+// by all PreToolUse hooks (including this gate's own). A delegation rejected by another
+// gate (intent-flow, brief-before-delegate, etc.) never reaches PostToolUse, so it does
+// not inflate the retry counter. Without this split, the PreToolUse gate counted rejected
+// delegations as retries and tripped the breaker on the corrected second attempt.
+
+import { createHash } from 'node:crypto';
+import { isGateEnabled } from '../../lib/config.mjs';
+import {
+  allow,
+  delegationPromptOf,
+  readHookPayload,
+  sessionIdOf,
+  toolInputOf,
+  toolNameOf,
+  toolInGroups,
+} from '../../lib/hook-io.mjs';
+import {
+  readSessionState,
+  writeSessionState,
+} from '../../lib/session-state.mjs';
+
+const GATE_ID = 'circuit-breaker';
+const CONFIG_KEY = 'requireCircuitBreakerOnDelegation';
+
+const MAX_ENTRIES_PER_KEY = 12;
+const MIN_TOKEN_LENGTH = 2;
+
+const SECTION_HEADING_NAMES = [
+  'scope',
+  'steps',
+  'haceres',
+  'output',
+  'criteria',
+  'criterio',
+  'handoff',
+  'out of scope',
+  'in scope',
+  'que no',
+  'que si',
+  'que sí',
+  'edge cases',
+  'casos borde',
+];
+
+function headingNamePattern(name) {
+  return new RegExp(
+    name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/ /g, '\\s+'),
+    'i',
+  );
+}
+
+const HEADING_NAME_PATTERNS = SECTION_HEADING_NAMES.map(headingNamePattern);
+
+function indexOfSectionMarker(text) {
+  let earliest = -1;
+  for (const namePattern of HEADING_NAME_PATTERNS) {
+    const match = namePattern.exec(text);
+    if (!match) continue;
+    const after = text.slice(match.index + match[0].length);
+    if (!/^\s*:/.test(after)) continue;
+    if (earliest === -1 || match.index < earliest) earliest = match.index;
+  }
+  return earliest;
+}
+
+const LEVEL_LINE_PATTERNS = [
+  new RegExp('^level\\s*:?$', 'i'),
+  new RegExp('^nivel\\s*:?$', 'i'),
+];
+
+function stripLeadingMarkup(line) {
+  return line
+    .trim()
+    .replace(/^#{1,4}\s*/, '')
+    .replace(/^[-*]\s*/, '')
+    .replace(/^\*\*/, '');
+}
+
+function isScaffoldingLine(line) {
+  const stripped = stripLeadingMarkup(line);
+  if (LEVEL_LINE_PATTERNS.some((pattern) => pattern.test(stripped)))
+    return true;
+  return HEADING_NAME_PATTERNS.some((namePattern) => {
+    const match = namePattern.exec(stripped);
+    return (
+      match &&
+      match.index === 0 &&
+      /^\s*:?$/.test(stripped.slice(match[0].length))
+    );
+  });
+}
+
+const GOAL_HEADING_PATTERN = /^(objetivo|goal|meta):(.*)$/i;
+const IN_SCOPE_HEADING_PATTERN = /^(que\s+s[ií]|in\s+scope|lo\s+pedido)\b/i;
+
+function isEndOfInScope(line) {
+  const stripped = stripLeadingMarkup(line);
+  return HEADING_NAME_PATTERNS.some((namePattern) => {
+    const match = namePattern.exec(stripped);
+    return match && match.index === 0;
+  });
+}
+
+function contentAfterHeading(line) {
+  const colon = line.indexOf(':');
+  return colon === -1 ? '' : line.slice(colon + 1).trim();
+}
+
+const STOP_WORDS = new Set(
+  (
+    'de la el los las un una unos unas y o a en del al lo que se su sus por para con como es son ser este esta ' +
+    'esto ese esa eso mas si no ni pero cuando donde cual cuales hay hace hacer debe deben debes puede pueden ' +
+    'the of to and in for on with a an is are be it its this that'
+  ).split(' '),
+);
+
+function stripDiacritics(text) {
+  return text.normalize('NFD').replace(/\p{M}/gu, '');
+}
+
+function tokenize(text) {
+  return stripDiacritics(String(text).toLowerCase())
+    .split(/[^a-z0-9]+/)
+    .filter(
+      (token) => token.length >= MIN_TOKEN_LENGTH && !STOP_WORDS.has(token),
+    );
+}
+
+const WINDOWS_DRIVE_PATH_PATTERN = /[A-Za-z]:[\\/][^\s"'`,;)\]]+/g;
+const KNOWN_EXTENSIONS = [
+  'mjs',
+  'cjs',
+  'json',
+  'jsx',
+  'js',
+  'mts',
+  'cts',
+  'tsx',
+  'ts',
+  'vue',
+  'md',
+  'py',
+  'sh',
+  'ps1',
+  'yaml',
+  'yml',
+  'toml',
+  'sql',
+  'css',
+  'html',
+];
+const KNOWN_EXTENSION_FILENAME_PATTERN = new RegExp(
+  `[\\w-]+\\.(?:${KNOWN_EXTENSIONS.join('|')})\\b`,
+  'g',
+);
+const PATH_LIKE_RUN_PATTERN = /[\w./\\-]+/g;
+const TRAILING_PUNCTUATION = new Set(['.', ',', ';', ':', ')', ']']);
+
+function looksLikeRelativePath(run) {
+  return /[\\/]/.test(run) && !/^[\\/]+$/.test(run);
+}
+
+function stripTrailingPunctuation(text) {
+  let end = text.length;
+  while (end > 0 && TRAILING_PUNCTUATION.has(text[end - 1])) end -= 1;
+  return text.slice(0, end);
+}
+
+function mentionedPaths(prompt) {
+  const found = new Set();
+  const text = String(prompt);
+  const fixedShapeMatches = [
+    WINDOWS_DRIVE_PATH_PATTERN,
+    KNOWN_EXTENSION_FILENAME_PATTERN,
+  ].flatMap((pattern) => text.match(pattern) ?? []);
+  const relativePathMatches = (text.match(PATH_LIKE_RUN_PATTERN) ?? []).filter(
+    looksLikeRelativePath,
+  );
+  for (const raw of [...fixedShapeMatches, ...relativePathMatches]) {
+    const normalized = stripTrailingPunctuation(
+      stripDiacritics(raw.toLowerCase()).replace(/\\/g, '/'),
+    );
+    const base = normalized.split('/').filter(Boolean).pop();
+    if (base && /[a-z0-9]/.test(base)) found.add(base);
+  }
+  return [...found].sort();
+}
+
+function identityText(prompt) {
+  const lines = String(prompt).split(/\r?\n/);
+  const parts = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const strippedLine = stripLeadingMarkup(lines[index])
+      .replace(/\*\*\s*/g, '')
+      .replace(' :', ':');
+    const goal = strippedLine.match(GOAL_HEADING_PATTERN);
+    if (goal) {
+      const goalText = goal[2].trim();
+      const cut = indexOfSectionMarker(goalText);
+      parts.push(cut > 0 ? goalText.slice(0, cut) : goalText);
+      continue;
+    }
+    if (IN_SCOPE_HEADING_PATTERN.test(strippedLine)) {
+      parts.push(contentAfterHeading(strippedLine));
+      for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+        if (isEndOfInScope(lines[cursor])) break;
+        parts.push(lines[cursor]);
+      }
+    }
+  }
+  return parts.join(' ').trim();
+}
+
+function textWithoutScaffolding(prompt) {
+  return String(prompt)
+    .split(/\r?\n/)
+    .filter((line) => !isScaffoldingLine(line))
+    .join(' ')
+    .trim();
+}
+
+function identitySignature(prompt) {
+  const identity =
+    identityText(prompt) || textWithoutScaffolding(prompt) || String(prompt);
+  const tokens = tokenize(identity);
+  const features = [];
+  if (tokens.length >= 2) {
+    for (let index = 0; index < tokens.length - 1; index += 1)
+      features.push(`${tokens[index]} ${tokens[index + 1]}`);
+  } else {
+    features.push(...tokens);
+  }
+  for (const path of mentionedPaths(prompt))
+    features.push(`path:${path}`, `path:${path}`);
+  return features;
+}
+
+function identityKey(signature) {
+  return createHash('sha256').update(signature.join(' ')).digest('hex');
+}
+
+function occurrencesFor(state, key) {
+  const value = state[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry) => entry && Array.isArray(entry.signature));
+}
+
+function main() {
+  const rawPayload = readHookPayload();
+  if (rawPayload === null) allow();
+  const toolName = toolNameOf(rawPayload) ?? '';
+  if (!toolInGroups(toolName, ['delegation'])) allow();
+
+  const cwd = process.cwd();
+  if (!isGateEnabled(CONFIG_KEY, false, cwd)) allow();
+
+  const toolInput = toolInputOf(rawPayload);
+  const prompt = delegationPromptOf(toolInput);
+  if (!prompt.trim()) allow();
+
+  const sessionId = sessionIdOf(rawPayload);
+  const stateOptions = { cwd };
+  const state = readSessionState(GATE_ID, sessionId, {}, stateOptions);
+  const signature = identitySignature(prompt);
+  const key = identityKey(signature);
+
+  const occurrences = [
+    ...occurrencesFor(state, key),
+    { signature, seenAt: Date.now() },
+  ].slice(-MAX_ENTRIES_PER_KEY);
+  writeSessionState(
+    GATE_ID,
+    sessionId,
+    { ...state, [key]: occurrences },
+    stateOptions,
+  );
+  allow();
+}
+
+try {
+  main();
+} catch {
+  allow();
+}

package/plugins/gates/hooks/gates/force-parallel/index.mjs

@@ -1,6 +1,6 @@
-// force-parallel — warns when delegations keep arriving one turn at a time instead of as a
-// batch. Advisory only: a PreToolUse hook sees one call at a time and cannot prove the
-// delegations were independent, so it nudges the NEXT delegation and never denies.
+// force-parallel — denies delegations that keep arriving one turn at a time instead of as a
+// batch. Deterministic: when the sequential count hits the threshold, the delegation is
+// blocked outright — the agent must collect independent delegations and send them together.
 //
 // Decisions: delegations landing within BATCH_GAP_MS of each other are ONE batch (a parallel
 // launch in a single message) and do not raise the sequential count; only a gap between the
@@ -10,7 +10,7 @@
 
 import {
   runGate,
-  warn,
+  deny,
   toolInGroups,
   delegationPromptOf,
 } from '../../lib/hook-io.mjs';
@@ -51,8 +51,7 @@ runGate(
   {
     id: GATE_ID,
     configKey: CONFIG_KEY,
-    enabledByDefault: false,
-    severity: 'warn',
+    enabledByDefault: true,
     defaultParams: {
       sequentialThreshold: DEFAULT_SEQUENTIAL_THRESHOLD,
       sequentialWindowMs: DEFAULT_SEQUENTIAL_WINDOW_MS,
@@ -81,13 +80,13 @@ runGate(
     const windowSeconds = Math.round(
       parameters.sequentialWindowMs / MS_PER_SECOND,
     );
-    warn(
+    deny(
       CONFIG_KEY,
-      `This is the ${ordinal(count)} delegation sent one-by-one within ${windowSeconds}s. If the ` +
-        'remaining work is independent, launch the next batch together in a single message ' +
-        '(multiple tool calls) instead of one delegation per turn. If this delegation ' +
-        'genuinely depends on a prior result, ignore this and mark the prompt with ' +
-        `"${marker || DEFAULT_JUSTIFIED_MARKER}" to skip the warning next time.`,
+      `This is the ${ordinal(count)} delegation sent one-by-one within ${windowSeconds}s. ` +
+        'Independent delegations MUST be launched together in a single message (multiple tool ' +
+        'calls in one response). Collect the remaining independent delegations and send them as ' +
+        'a batch. If this delegation genuinely depends on a prior result, add ' +
+        `"${marker || DEFAULT_JUSTIFIED_MARKER}" to the prompt to declare the dependency.`,
     );
   },
 );

package/plugins/gates/hooks/gates/library-docs/index.mjs

@@ -5,6 +5,8 @@ import { projectRootOf } from '../../lib/config.mjs';
 import {
   deny,
   runGate,
+  shellCommandOf,
+  shellWrittenPaths,
   toolInGroups,
   writtenContentOf,
   writtenPathOf,
@@ -190,6 +192,33 @@ export function knowledgeStatus(state, name) {
   };
 }
 
+const HEREDOC_START_PATTERN = /<<-?\s*['"]?(\w+)['"]?(?:\s*>{1,2}\s*\S+)?$/;
+
+function extractHeredocBodies(command) {
+  const lines = String(command).split(/\r?\n/);
+  const bodies = [];
+  let collecting = null;
+  let body = [];
+  for (const line of lines) {
+    if (collecting) {
+      if (line.trim() === collecting) {
+        bodies.push(body.join('\n'));
+        collecting = null;
+        body = [];
+      } else {
+        body.push(line);
+      }
+      continue;
+    }
+    const match = HEREDOC_START_PATTERN.exec(line.trimEnd());
+    if (match) {
+      collecting = match[1];
+      body = [];
+    }
+  }
+  return bodies;
+}
+
 function remedyFor(name, status) {
   const steps = [];
   if (!status.searched && !status.documentation)
@@ -217,46 +246,93 @@ runGate(
     },
   },
   ({ toolName, toolInput, sessionId, parameters, cwd }) => {
-    if (!toolInGroups(toolName, ['write'])) return;
-    const writtenPath = writtenPathOf(toolInput);
-    if (
-      !writtenPath ||
-      !parameters.codeExtensions.includes(extname(writtenPath).toLowerCase())
-    )
-      return;
+    const isWrite = toolInGroups(toolName, ['write']);
+    const isShell = toolInGroups(toolName, ['shell']);
+    if (!isWrite && !isShell) return;
+
     const root = projectRootOf(cwd) ?? cwd;
-    const absolutePath = isAbsolute(writtenPath)
-      ? writtenPath
-      : join(root, writtenPath);
     const ignored = new Set(
       parameters.ignoredPackages.map((name) => String(name).toLowerCase()),
     );
-    const already = existingImports(absolutePath);
-    const candidates = importedPackagesOf(
-      writtenContentOf(toolInput),
-      writtenPath,
-    ).filter((name) => !already.has(name) && !ignored.has(name.toLowerCase()));
-    if (candidates.length === 0) return;
-    const usedElsewhere = packagesUsedElsewhere(
-      root,
-      absolutePath,
-      parameters.codeExtensions,
-      parameters.maxScanFiles,
-    );
-    const unknown = candidates.filter((name) => !usedElsewhere.has(name));
-    if (unknown.length === 0) return;
+
+    // Collect { path, content } pairs to check.
+    const targets = [];
+
+    if (isWrite) {
+      const writtenPath = writtenPathOf(toolInput);
+      if (
+        writtenPath &&
+        parameters.codeExtensions.includes(extname(writtenPath).toLowerCase())
+      ) {
+        targets.push({
+          path: writtenPath,
+          content: writtenContentOf(toolInput),
+        });
+      }
+    }
+
+    if (isShell) {
+      const command = shellCommandOf(toolInput);
+      const writtenPaths = shellWrittenPaths(command).filter((path) =>
+        parameters.codeExtensions.includes(extname(path).toLowerCase()),
+      );
+      if (writtenPaths.length > 0) {
+        const heredocBodies = extractHeredocBodies(command);
+        const allContent = heredocBodies.join('\n');
+        for (const path of writtenPaths) {
+          targets.push({ path, content: allContent || null });
+        }
+      }
+    }
+
+    if (targets.length === 0) return;
+
+    const allBlocked = [];
     const state = readSessionState(GATE_ID, sessionId, {}, { cwd });
-    const blocked = unknown
-      .map((name) => ({ name, status: knowledgeStatus(state, name) }))
-      .filter((entry) => !entry.status.known);
-    if (blocked.length === 0) return;
-    const lines = blocked.map(
+
+    for (const { path, content } of targets) {
+      const absolutePath = isAbsolute(path) ? path : join(root, path);
+
+      if (content === null) {
+        // Shell command writes a code file but content cannot be inspected (no heredoc).
+        deny(
+          CONFIG_KEY,
+          `This shell command writes to ${path} (a code file) via redirection. Use the Write ` +
+            'tool for code files so library usage can be verified. Heredocs are extractable ' +
+            'but plain redirections are opaque to this gate.',
+        );
+      }
+
+      const already = existingImports(absolutePath);
+      const candidates = importedPackagesOf(content, path).filter(
+        (name) => !already.has(name) && !ignored.has(name.toLowerCase()),
+      );
+      if (candidates.length === 0) continue;
+
+      const usedElsewhere = packagesUsedElsewhere(
+        root,
+        absolutePath,
+        parameters.codeExtensions,
+        parameters.maxScanFiles,
+      );
+      const unknown = candidates.filter((name) => !usedElsewhere.has(name));
+      if (unknown.length === 0) continue;
+
+      const blocked = unknown
+        .map((name) => ({ name, status: knowledgeStatus(state, name) }))
+        .filter((entry) => !entry.status.known);
+      allBlocked.push(...blocked);
+    }
+
+    if (allBlocked.length === 0) return;
+    const lines = allBlocked.map(
       (entry) => `${entry.name}: ${remedyFor(entry.name, entry.status)}`,
     );
     deny(
       CONFIG_KEY,
-      `This write introduces ${blocked.length} package(s) this project does not use anywhere yet, and nothing ` +
-        `in this session shows how to use them. Do not guess an API. ${lines.join(' | ')}. Then retry the write.`,
+      `This ${isShell ? 'shell command' : 'write'} introduces ${allBlocked.length} package(s) this project does not use ` +
+        `anywhere yet, and nothing in this session shows how to use them. Do not guess an API. ` +
+        `${lines.join(' | ')}. Then retry${isShell ? ' using the Write tool' : ''}.`,
     );
   },
 );

package/plugins/gates/hooks/gates/no-trivial-scripts/index.mjs

@@ -0,0 +1,114 @@
+// no-trivial-scripts — denies inline interpreter scripts (node -e, python -c, sed -i,
+// perl -e, PowerShell one-liners with [IO.File]/Set-Content/Add-Content) when they perform
+// file operations that the Edit or Write tool would handle directly: inserting a line,
+// replacing text, creating a file, appending content. Legitimate uses of inline scripts
+// (JSON processing, running a test harness, computing a value) are not caught because they
+// don't touch the filesystem.
+//
+// Deterministic: pattern match on the command, unconditional deny. No model judgment.
+
+import {
+  deny,
+  runGate,
+  shellCommandOf,
+  toolInGroups,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'no-trivial-scripts';
+const CONFIG_KEY = 'blockTrivialInlineScripts';
+
+// Node/Deno/Bun inline eval doing file operations
+const NODE_EVAL_PATTERN =
+  /\b(?:node|deno|bun)\b(?:\s+-\S+)*?\s+(?:-e|--eval|-p|--print)\b/i;
+const NODE_FILE_OPS =
+  /\b(?:writeFileSync|appendFileSync|mkdirSync|unlinkSync|renameSync|copyFileSync|fs\.writeFile|fs\.appendFile|fs\.unlink|fs\.rename|fs\.mkdir|fs\.copyFile|createWriteStream)\b/;
+
+// Python inline doing file operations
+const PYTHON_EVAL_PATTERN = /\bpython3?\b(?:\s+-\S+)*?\s+-c\b/i;
+const PYTHON_OPEN_FOR_WRITING = /\bopen\s*\([^)]*,\s*['"][wax]/;
+const PYTHON_FILE_OPS =
+  /\.write\s*\(|\bshutil\.|\bos\.(?:rename|remove|unlink|makedirs)\b|\bpathlib\.Path\b[^)]*\.write_text/;
+
+// sed/awk/perl inline edits — these are always file edits
+const SED_INLINE_PATTERN = /\bsed\s+(?:-[^;\s]*\s+)*-i/;
+const PERL_INLINE_PATTERN = /\bperl\s+(?:-[^;\s]*\s+)*-[ip]/;
+const AWK_INLINE_PATTERN = /\bawk\s+(?:-[^;\s]*\s+)*-i\s+inplace\b/;
+
+// PowerShell file manipulation one-liners
+const PS_FILE_OPS_PATTERN =
+  /\b(?:Set-Content|Add-Content|Out-File|\[System\.IO\.File\]::(?:WriteAll|AppendAll)|New-Item\s[^|;]*-ItemType\s+File)\b/i;
+
+const REMEDY =
+  'This command uses an inline script for a file operation that the Edit or Write tool ' +
+  'handles directly. Use Edit to modify existing files (insert, replace, delete lines) ' +
+  'or Write to create new files. Inline scripts are for computation, not file manipulation.';
+
+function checkCommand(command) {
+  if (!command) return;
+
+  // Node/Deno/Bun -e with file operations
+  const nodeMatch = NODE_EVAL_PATTERN.exec(command);
+  if (nodeMatch) {
+    const afterEval = command.slice(nodeMatch.index + nodeMatch[0].length);
+    if (NODE_FILE_OPS.test(afterEval)) {
+      deny(CONFIG_KEY, `${REMEDY} (detected: inline Node.js file operation)`);
+    }
+  }
+
+  // Python -c with file operations
+  const pythonMatch = PYTHON_EVAL_PATTERN.exec(command);
+  if (pythonMatch) {
+    const afterEval = command.slice(pythonMatch.index + pythonMatch[0].length);
+    if (
+      PYTHON_OPEN_FOR_WRITING.test(afterEval) ||
+      PYTHON_FILE_OPS.test(afterEval)
+    ) {
+      deny(CONFIG_KEY, `${REMEDY} (detected: inline Python file operation)`);
+    }
+  }
+
+  // sed -i is always an in-place file edit
+  if (SED_INLINE_PATTERN.test(command)) {
+    deny(
+      CONFIG_KEY,
+      `${REMEDY} (detected: sed -i in-place edit — use Edit tool instead)`,
+    );
+  }
+
+  // perl -i/-p is always an in-place file edit
+  if (PERL_INLINE_PATTERN.test(command)) {
+    deny(
+      CONFIG_KEY,
+      `${REMEDY} (detected: perl -i/-p in-place edit — use Edit tool instead)`,
+    );
+  }
+
+  // awk -i inplace
+  if (AWK_INLINE_PATTERN.test(command)) {
+    deny(
+      CONFIG_KEY,
+      `${REMEDY} (detected: awk -i inplace — use Edit tool instead)`,
+    );
+  }
+
+  // PowerShell file write one-liners
+  if (PS_FILE_OPS_PATTERN.test(command)) {
+    deny(
+      CONFIG_KEY,
+      `${REMEDY} (detected: PowerShell file write cmdlet — use Edit or Write tool instead)`,
+    );
+  }
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {},
+  },
+  ({ toolName, toolInput }) => {
+    if (!toolInGroups(toolName, ['shell'])) return;
+    checkCommand(shellCommandOf(toolInput));
+  },
+);