@devrik-tools/claude-gates 0.7.2 → 0.9.0

package/plugins/gates/hooks/gates/no-blocking/index.mjs

@@ -1,117 +1,179 @@
-// no-blocking — denies syntactic forms of waiting in the foreground (sleeping, polling
-// loops, following unbounded output, foreground dev servers) on a real shell command and
-// on a delegation prompt (a subagent can be told "wait with sleep" in prose). Migrated
-// from ~/.claude/hooks/guard-no-blocking.mjs. Off by default: a project opts in, because
-// many legitimate workflows still need a bounded wait the project accepts as normal.
-//
-// This gate only recognizes SYNTACTIC forms of waiting — it never judges whether other
-// work was available meanwhile, because that is judgment, not a fact a regex can read.
-// A gate that misfires on the legitimate case gets disabled, taking every real catch
-// down with it.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   blockingPatterns      regex sources (matched case-insensitively) of blocking/waiting
-//                         forms to deny. Replaces the built-in list wholesale.
-//   waitJustifiedMarker   a marker token that, present in the command with a reason,
-//                         escapes the block — a declared wait is a decision, not an
-//                         oversight. Replaces the built-in marker wholesale.
-// The defaults live here, in the source, so a project reads them and knows exactly what
-// its override replaces.
+// no-blocking — denies syntactic forms of waiting in the foreground (sleeping, polling loops,
+// following unbounded output, foreground dev servers, Windows pauses) on a real shell command
+// and on a delegation prompt that orders one. Off by default: a project opts in. Deliberate
+// limits: only SYNTACTIC waiting is recognized, never whether other work was available
+// meanwhile; each command segment is judged on its own, so a detach form (`&`, nohup,
+// Start-Job, --detach) exempts only the segment it is in, and only the real
+// `run_in_background: true` flag exempts the whole call — the words in the command do not.
 
+import { hasRealCommandIntent } from '../../lib/delegation.mjs';
 import {
-  runGate,
+  compileRegex,
+  delegationPromptOf,
   deny,
+  escapeRegExp,
+  normalizeRulePairs,
+  runGate,
+  shellCommandOf,
   toolInGroups,
-  delegationPromptOf,
 } from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'no-blocking';
 const CONFIG_KEY = 'blockWaitingCommands';
 
 const DEFAULT_WAIT_JUSTIFIED_MARKER = 'WAIT-JUSTIFIED:';
+const DEFAULT_REASON = 'Blocking/waiting command is not allowed.';
 
-// systemd's log-follow command, assembled from fragments so the spell checker does not
-// read it as prose (the project keeps an empty dictionary by policy).
-const SYSTEMD_LOG_COMMAND = 'journal' + 'ctl';
+// Where a command may begin inside a segment or a sentence: the start, after a control word,
+// or after a separator a prompt may still carry.
+const COMMAND_START = String.raw`(?:^|[|;&(]\s*|\b(?:then|do|else)\s+)`;
+const FOLLOW_COMMANDS =
+  '(?:tail|journalctl|kubectl\\s+logs|docker(?:-compose|\\s+compose)?\\s+logs)';
 
-/** Blocking rules as `[regexSource, reason]`, matched case-insensitively. */
 const DEFAULT_BLOCKING_PATTERNS = [
   [
-    String.raw`(^|[|;&]\s*|\bthen\s+|\bdo\s+)(sleep|timeout)\s+\d`,
+    `${COMMAND_START}sleep\\s`,
     'Sleeping in the foreground spends the turn doing nothing. If waiting for something ' +
       'to finish, launch it in the background and move on to something else; if waiting ' +
       'on an external condition, use a monitor.',
   ],
+  [
+    `${COMMAND_START}timeout(?:\\.exe)?\\s+(?:/t\\s+)?\\d+(?:\\s+/nobreak)?\\s*$`,
+    "'timeout N' with no command is a sleep. Wrap a real command (timeout 120 npm test) " +
+      'or launch the wait in the background.',
+  ],
   [
     String.raw`\bStart-Sleep\b`,
     'Start-Sleep freezes the turn. Launch the work in the background and continue with ' +
       'whatever does not depend on it.',
   ],
   [
-    String.raw`(^|[|;&]\s*)wait\b|--wait\b|\bWait-Process\b|\bWait-Job\b`,
+    String.raw`${COMMAND_START}wait\b|\s--wait\b|\bWait-Process\b|\bWait-Job\b|\bStart-Process\b[^|;\n]*\s-Wait\b`,
     'Waiting for another process to finish blocks the whole turn. Launch it in the ' +
       'background and consume the result when it arrives, not before.',
   ],
   [
-    [
-      String.raw`\b(tail|`,
-      SYSTEMD_LOG_COMMAND,
-      String.raw`|kubectl\s+logs|docker\s+logs)\b[^|;&]*\s-{1,2}f\b`,
-    ].join(''),
+    String.raw`\b${FOLLOW_COMMANDS}\b[^|;&\n]*\s(?:-[a-z]*f[a-z]*|--follow)(?=\s|$)`,
     'Following live output never returns and takes the turn with it. Read the file once, ' +
       'or leave the following to a background process.',
   ],
   [
-    String.raw`(^|[|;&]\s*)watch\s+`,
+    `${COMMAND_START}watch\\s+`,
     "'watch' repeats forever and blocks. Run the command once; if a change genuinely " +
       'needs watching, use a monitor that does not take the turn.',
   ],
   [
-    String.raw`\b(until|while)\b[^\n]{0,80}\bdo\b[^\n]{0,80}\bsleep\b`,
+    String.raw`\b(?:until|while)\b[\s\S]{0,80}\bdo\b[\s\S]{0,80}\bsleep\b`,
     'A loop that sleeps waiting for something to change is foreground polling: it blocks ' +
       'and it spins. Use a monitor with the condition, or launch the work in the ' +
       'background and wait for its notification.',
   ],
   [
-    String.raw`\b(npm|pnpm|yarn|bun)\s+(run\s+)?(dev|start|serve|watch)\b`,
+    String.raw`\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start|serve|watch)(?=\s|$)`,
     'A dev server does not end on its own: in the foreground it takes the turn until ' +
       'something kills it. Launch it in the background and keep working while it comes up.',
   ],
+  [
+    String.raw`${COMMAND_START}ping\b[^|;&\n]*\s-n\s+\d{2,}\b|${COMMAND_START}pause\b|\bRead-Host\b`,
+    'A ping loop, pause or Read-Host waits on the clock or on a keyboard nobody is at. ' +
+      'Remove the wait; if something must be awaited, do it in the background.',
+  ],
 ];
 
-// Marks that a command will not take the turn: backgrounded, detached, or bounded. The bare
-// `-d` token was removed: it matched any -d flag (e.g. `curl -d payload`), letting an
-// unrelated flag whitelist a genuine foreground `sleep`. Detached forms are now matched
-// explicitly (--detach, docker/compose -d at a word boundary before end/pipe), and PowerShell's
-// Start-Job / Start-Process -NoNewWindow backgrounding is recognized.
-// One big alternation trips the linter's regex-complexity check, so each background form is
-// its own short regex tested with `.some()` — matching EXACTLY what the combined pattern did
-// (verified case-by-case). Order does not matter: any one match means the command detaches.
-const NOT_TAKING_THE_TURN_FORMS = [
-  /&\s*$/i,
+// ── Shell segments ──────────────────────────────────────────────────────────────────
+// A lone `&` backgrounds the segment before it; `>&` and `&>` are redirections, not separators.
+const SEPARATOR_PATTERN = /(\|\||&&|\||;|\n|(?<!>)&(?![&>]))/;
+const SHELL_WRAPPER_PATTERN =
+  /^(?:sh|bash|zsh|dash|ksh)\s+(-\w+)\s+(?:"([^"]*)"|'([^']*)')/i;
+const DETACHED_SEGMENT_FORMS = [
   /\bnohup\b/i,
   /\bstart\s+\/b\b/i,
   /--detach\b/i,
-  /\b-d(?=\s*($|[|;&]))/i,
+  /^docker(?:-compose|\s+compose)?\b[^|;\n]*\s-d(?=\s|$)/i,
   /\bStart-Job\b/i,
-  /\bStart-Process\b[^|;\n]*-NoNewWindow\b/i,
-  /\brun_in_background\b/i,
 ];
 
-function detachesFromTurn(command) {
-  return NOT_TAKING_THE_TURN_FORMS.some((pattern) => pattern.test(command));
+function stripGrouping(text) {
+  let stripped = text.trim();
+  while (stripped.startsWith('(') || stripped.startsWith('$('))
+    stripped = stripped.replace(/^\$?\(/, '').trim();
+  while (stripped.endsWith(')')) stripped = stripped.slice(0, -1).trimEnd();
+  return stripped;
+}
+
+function shellSegments(command) {
+  const parts = String(command).split(SEPARATOR_PATTERN);
+  const segments = [];
+  for (let index = 0; index < parts.length; index += 2) {
+    const text = stripGrouping(parts[index]);
+    if (!text) continue;
+    const sentToBackground = parts[index + 1] === '&';
+    const wrapped = SHELL_WRAPPER_PATTERN.exec(text);
+    if (wrapped && wrapped[1].includes('c')) {
+      for (const inner of shellSegments(wrapped[2] ?? wrapped[3]))
+        segments.push({
+          text: inner.text,
+          detached: sentToBackground || inner.detached,
+        });
+      continue;
+    }
+    const detached =
+      sentToBackground ||
+      DETACHED_SEGMENT_FORMS.some((form) => form.test(text));
+    segments.push({ text, detached });
+  }
+  return segments;
+}
+
+// ── Rules ───────────────────────────────────────────────────────────────────────────
+function blockingRules(parameters) {
+  return normalizeRulePairs(parameters.blockingPatterns, DEFAULT_REASON)
+    .map(({ source, reason }) => ({ pattern: compileRegex(source), reason }))
+    .filter((rule) => rule.pattern !== null);
+}
+
+function isJustified(text, marker) {
+  if (!marker) return false;
+  const reasonAfterMarker = String.raw`\s*\S+\s+\S+`;
+  return new RegExp(`${escapeRegExp(marker)}${reasonAfterMarker}`, 'i').test(
+    text,
+  );
+}
+
+function denyBlocking(reason, marker, matched) {
+  deny(
+    CONFIG_KEY,
+    `${reason} (matched: "${matched.trim()}") Launch it with run_in_background: true, or ` +
+      `if this wait is genuinely justified add "${marker} <concrete reason>" to the command. ` +
+      'A declared wait is a decision; a silent one is an oversight.',
+  );
 }
 
-function compile(source) {
-  return new RegExp(source, 'i');
+function checkShellCommand(command, parameters, marker) {
+  const foreground = shellSegments(command)
+    .filter((segment) => !segment.detached)
+    .map((segment) => segment.text);
+  if (foreground.length === 0) return;
+  // The joined text lets a rule see a loop whose body sits in another segment.
+  const candidates =
+    foreground.length > 1 ? [...foreground, foreground.join('\n')] : foreground;
+  for (const { pattern, reason } of blockingRules(parameters)) {
+    for (const candidate of candidates) {
+      const match = pattern.exec(candidate);
+      if (match) denyBlocking(reason, marker, match[0]);
+    }
+  }
 }
 
-/** The text to inspect: a real command's command line, or the delegation prompt. */
-function commandTextFrom(toolName, toolInput) {
-  if (toolInGroups(toolName, ['shell'])) {
-    return String(toolInput.CommandLine ?? toolInput.command ?? '');
+function checkDelegationPrompt(prompt, parameters, marker) {
+  for (const { pattern, reason } of blockingRules(parameters)) {
+    if (hasRealCommandIntent(prompt, pattern))
+      denyBlocking(
+        `${reason} The delegation prompt orders the wait; a subagent must not do it either.`,
+        marker,
+        pattern.exec(prompt)?.[0] ?? '',
+      );
   }
-  return delegationPromptOf(toolInput);
 }
 
 runGate(
@@ -126,38 +188,17 @@ runGate(
   },
   ({ toolName, toolInput, parameters }) => {
     const isShell = toolInGroups(toolName, ['shell']);
-    const isDelegation = toolInGroups(toolName, ['delegation']);
-    if (!isShell && !isDelegation) return;
-
-    const command = commandTextFrom(toolName, toolInput);
-    if (!command.trim()) return;
-
-    // Already declared in the background: the turn stays free, which is all that matters.
+    if (!isShell && !toolInGroups(toolName, ['delegation'])) return;
+    const text = isShell
+      ? shellCommandOf(toolInput)
+      : delegationPromptOf(toolInput);
+    if (!text.trim()) return;
     if (toolInput.run_in_background === true) return;
-    if (detachesFromTurn(command)) return;
 
-    // A declared wait with its reason is a decision, not an oversight.
     const marker = String(parameters.waitJustifiedMarker ?? '');
-    if (marker) {
-      const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      const reasonAfterMarker = String.raw`\s*\S+\s+\S+`;
-      const justified = new RegExp(`${escapedMarker}${reasonAfterMarker}`, 'i');
-      if (justified.test(command)) return;
-    }
+    if (isJustified(text, marker)) return;
 
-    const blockingPairs = (parameters.blockingPatterns ?? []).map((entry) =>
-      Array.isArray(entry)
-        ? entry
-        : [entry, 'Blocking/waiting command is not allowed.'],
-    );
-    for (const [source, reason] of blockingPairs) {
-      if (compile(source).test(command)) {
-        deny(
-          CONFIG_KEY,
-          `${reason} If this wait is genuinely justified, add "${marker} <concrete reason>" ` +
-            'to the command and try again. A declared wait is a decision; a silent one is an oversight.',
-        );
-      }
-    }
+    if (isShell) checkShellCommand(text, parameters, marker);
+    else checkDelegationPrompt(text, parameters, marker);
   },
 );

package/plugins/gates/hooks/gates/no-coauthor/index.mjs

@@ -1,98 +1,116 @@
-// no-coauthor — denies a `git commit` that carries an AI/agent attribution trailer
-// (Co-Authored-By, "Generated with", "Claude-Session", and the like). The defect is fully
-// visible in the command text the tool is about to run, so this is a deterministic deny with
-// an escape hatch, never a prose reminder: the offending trailer is right there to point at.
-//
-// justification: no existing gate covers this. bash-commands denies destructive commands and
-// block-remote-publish denies pushes; neither inspects the commit MESSAGE for attribution.
-// lint-commit runs the linter on a commit but never reads the message text. This is the first
-// gate that reads what a commit says, not just that it is a commit.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   attributionPatterns  regex sources (matched case-insensitively) of trailers/phrases
-//                        that must not appear in a commit message. Replaces the built-in
-//                        list wholesale, so a project that wants a different policy states
-//                        its full list.
-//   escapeHatch          a substring the author can put in the command to bypass this gate
-//                        for one legitimate commit (e.g. importing external history that
-//                        genuinely carries a co-author). Default '[allow-coauthor]'.
-//
-// ── How it detects a commit and reads its message ────────────────────────────────────
-// Reuses lint-commit's git-global-option normalization so `git -C /repo -c x=y commit` is
-// recognized as a commit. It then scans the WHOLE command text (which contains the -m value
-// or the heredoc body) for any attribution pattern — this over-includes on purpose (a match
-// inside an unrelated string is a rare false block the author clears with the escape hatch)
-// rather than under-includes (a real trailer slipping through in a shape we did not parse).
-//
-// ── Fail-safe shape ──────────────────────────────────────────────────────────────────
-// Not a commit: allow (silent). A commit with no attribution pattern: allow. A commit whose
-// text matches a pattern and does NOT contain the escape hatch: deny, naming the match.
+// no-coauthor — denies a `git commit` whose MESSAGE carries an AI/agent attribution
+// (Co-Authored-By, Claude-Session, "Generated with Claude"), and a delegation prompt that
+// orders one. The message is what the commit will record: -m values, a heredoc body,
+// --trailer values and a -F file read from the project. Only a command segment that RUNS git
+// commit counts (a `git log | grep Co-Authored-By` is not one). Deliberate limit: a message
+// built from a substitution (`-m "$(cat msg)"`) cannot be read without running it.
 
-import { runGate, deny, toolInGroups } from '../../lib/hook-io.mjs';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { projectRootOf } from '../../lib/config.mjs';
+import { hasRealCommandIntent } from '../../lib/delegation.mjs';
+import {
+  commitMessageOf,
+  isDryRunCommit,
+  isGitCommit,
+  normalizeGitCommand,
+} from '../../lib/git.mjs';
+import {
+  compileRegexList,
+  delegationPromptOf,
+  deny,
+  runGate,
+  shellCommandOf,
+  toolInGroups,
+} from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'no-coauthor';
 const CONFIG_KEY = 'blockCoauthorTrailers';
 
-const SHELL_GROUPS = ['shell', 'delegation'];
-
-// Attribution trailers/phrases an AI agent tends to append. Sources, compiled case-insensitively.
+// Narrow on purpose: "generated by vitest" or "usage with Claude Code" in a subject line is
+// not an attribution; a trailer or a "generated with/by <an agent>" phrase is.
 const DEFAULT_ATTRIBUTION_PATTERNS = [
-  String.raw`co-authored-by:`,
-  String.raw`generated with`,
-  String.raw`generated by`,
-  String.raw`🤖 generated`,
+  String.raw`co-authored-by\s*[:=]`,
   String.raw`claude-session:`,
   String.raw`assisted-by:`,
   String.raw`authored-with:`,
-  String.raw`with claude code`,
+  String.raw`generated (?:with|by) (?:claude|ai|copilot|codex|cursor|gemini|chatgpt|an? (?:ai|llm|assistant)|a (?:bot|model))\b`,
+  String.raw`🤖 generated`,
 ];
 
 const DEFAULT_ESCAPE_HATCH = '[allow-coauthor]';
 
-// One global git option at a time, stripped repeatedly — same normalization lint-commit and
-// bash-commands use, so `git -C /repo -c x=y commit` reduces to `git commit` before matching.
-const GIT_OPTION_WITH_VALUE = String.raw`(?:-[Cc]|--git-dir|--work-tree|--namespace|--exec-path|--config-env)(?:\s+|=)\S+`;
-const GIT_FLAG_OPTION = String.raw`--(?:paginate|no-pager|bare|no-optional-locks)|-p`;
-const GIT_GLOBAL_OPTION_PATTERN = new RegExp(
-  String.raw`\bgit\s+(?:${GIT_OPTION_WITH_VALUE}|${GIT_FLAG_OPTION})\s+`,
-  'i',
-);
-const GIT_COMMIT_PATTERN = /\bgit\s+commit\b/i;
+// ── The commit segment ──────────────────────────────────────────────────────────────
+const SEGMENT_SEPARATOR = /;|&&|\|\||\||\n/;
+const ARGUMENT_PATTERN = /"([^"]*)"|'([^']*)'|(\S+)/g;
+const GIT_BINARY_TOKEN = /(?:^|[\\/])git(?:\.exe)?$/i;
+const WRAPPER_TOKEN = /^(?:\w+=\S*|command|sudo|env)$/i;
 
-function normalizeGitOptions(command) {
-  let previous;
-  let normalized = command;
-  do {
-    previous = normalized;
-    normalized = normalized.replace(GIT_GLOBAL_OPTION_PATTERN, 'git ');
-  } while (normalized !== previous);
-  return normalized;
+function runsGit(segment) {
+  const tokens = [];
+  for (const match of segment.matchAll(ARGUMENT_PATTERN))
+    tokens.push(match[1] ?? match[2] ?? match[3]);
+  while (tokens.length > 0 && WRAPPER_TOKEN.test(tokens[0])) tokens.shift();
+  return tokens.length > 0 && GIT_BINARY_TOKEN.test(tokens[0]);
 }
 
-function isGitCommit(command) {
-  return GIT_COMMIT_PATTERN.test(normalizeGitOptions(command));
+// A heredoc body spans lines, so the command is split only after the segment that opens it
+// has been recognized on its first line.
+function runsRealCommit(command) {
+  return String(command)
+    .split(SEGMENT_SEPARATOR)
+    .some((segment) => {
+      if (!runsGit(segment)) return false;
+      const normalized = normalizeGitCommand(segment);
+      return isGitCommit(normalized) && !isDryRunCommit(normalized);
+    });
 }
 
-function commandTextFrom(toolInput) {
-  return String(toolInput.CommandLine ?? toolInput.command ?? '');
-}
-
-/** The first attribution pattern the command text matches, or null when none does. */
-function matchedAttribution(command, attributionPatterns) {
-  for (const source of attributionPatterns) {
-    let pattern;
+function fileReader(root) {
+  return (path) => {
+    const resolved = resolve(root, path);
     try {
-      pattern = new RegExp(source, 'i');
+      return existsSync(resolved) ? readFileSync(resolved, 'utf8') : '';
     } catch {
-      // A malformed override pattern is skipped rather than crashing the gate; the rest of
-      // the list still protects.
-      continue;
+      return '';
     }
-    if (pattern.test(command)) return source;
+  };
+}
+
+function firstMatch(text, patterns) {
+  for (const pattern of patterns) {
+    const match = pattern.exec(text);
+    if (match) return match[0];
   }
   return null;
 }
 
+function denyAttribution(matched, escapeHatch) {
+  deny(
+    CONFIG_KEY,
+    `This commit message carries an AI/agent attribution ("${matched}"). Remove it — no ` +
+      'Co-Authored-By, no "Generated with", no session trailer. If this commit legitimately ' +
+      `must keep a co-author (e.g. importing external history), add "${escapeHatch}" to the ` +
+      `command to allow it once, or set attributionPatterns under ${CONFIG_KEY} in .ai/config.json.`,
+  );
+}
+
+function checkDelegationPrompt(prompt, patterns, escapeHatch) {
+  if (escapeHatch && prompt.includes(escapeHatch)) return;
+  const ordered = patterns.find((pattern) =>
+    hasRealCommandIntent(prompt, pattern),
+  );
+  if (ordered) denyAttribution(ordered.exec(prompt)[0], escapeHatch);
+}
+
+function checkShellCommand(command, patterns, escapeHatch, root) {
+  if (!runsRealCommit(command)) return;
+  if (escapeHatch && command.includes(escapeHatch)) return;
+  const message = commitMessageOf(command, { readFile: fileReader(root) });
+  const matched = firstMatch(message, patterns);
+  if (matched) denyAttribution(matched, escapeHatch);
+}
+
 runGate(
   {
     id: GATE_ID,
@@ -103,25 +121,27 @@ runGate(
       escapeHatch: DEFAULT_ESCAPE_HATCH,
     },
   },
-  ({ toolName, toolInput, parameters }) => {
-    if (!toolInGroups(toolName, SHELL_GROUPS)) return;
-
-    const command = commandTextFrom(toolInput);
-    if (!isGitCommit(command)) return;
+  ({ toolName, toolInput, parameters, cwd }) => {
+    const isShell = toolInGroups(toolName, ['shell']);
+    if (!isShell && !toolInGroups(toolName, ['delegation'])) return;
 
-    const escapeHatch = parameters.escapeHatch ?? DEFAULT_ESCAPE_HATCH;
-    if (escapeHatch && command.includes(escapeHatch)) return;
+    const escapeHatch = String(parameters.escapeHatch ?? '');
+    const { patterns } = compileRegexList(parameters.attributionPatterns);
+    if (patterns.length === 0) return;
 
-    const match = matchedAttribution(command, parameters.attributionPatterns);
-    if (!match) return;
-
-    deny(
-      CONFIG_KEY,
-      `This commit message carries an AI/agent attribution trailer (matched "${match}"). ` +
-        'Remove it — no Co-Authored-By, no "Generated with", no session trailer. If this ' +
-        `commit legitimately must keep a co-author (e.g. importing external history), add ` +
-        `"${escapeHatch}" to the command to allow it once, or set attributionPatterns/` +
-        'blockCoauthorTrailers in .ai/config.json.',
-    );
+    if (isShell) {
+      checkShellCommand(
+        shellCommandOf(toolInput),
+        patterns,
+        escapeHatch,
+        projectRootOf(cwd) ?? cwd,
+      );
+    } else {
+      checkDelegationPrompt(
+        delegationPromptOf(toolInput),
+        patterns,
+        escapeHatch,
+      );
+    }
   },
 );