@devrik-tools/claude-gates 0.1.2 → 0.2.0

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

@@ -1,142 +1,148 @@
-// 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.
-
-import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'no-blocking';
-const CONFIG_KEY = 'blockWaitingCommands';
-
-const SHELL_TOOLS = new Set(TOOL_GROUPS.shell);
-const DELEGATION_TOOLS = new Set(TOOL_GROUPS.delegation);
-
-const DEFAULT_WAIT_JUSTIFIED_MARKER = 'WAIT-JUSTIFIED:';
-
-// 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';
-
-/** Blocking rules as `[regexSource, reason]`, matched case-insensitively. */
-const DEFAULT_BLOCKING_PATTERNS = [
-  [
-    String.raw`(^|[|;&]\s*|\bthen\s+|\bdo\s+)(sleep|timeout)\s+\d`,
-    '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.',
-  ],
-  [
-    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`,
-    '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(''),
-    '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+`,
-    "'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`,
-    '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`,
-    '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.',
-  ],
-];
-
-/** Marks that a command will not take the turn: backgrounded, detached, or bounded. */
-const NOT_TAKING_THE_TURN =
-  /(&\s*$|\bnohup\b|\bstart\s+\/b\b|--detach\b|-d\b|\brun_in_background\b)/i;
-
-function compile(source) {
-  return new RegExp(source, 'i');
-}
-
-/** The text to inspect: a real command's command line, or the delegation prompt. */
-function commandTextFrom(toolName, toolInput) {
-  if (SHELL_TOOLS.has(toolName)) {
-    return String(toolInput.CommandLine ?? toolInput.command ?? '');
-  }
-  return String(toolInput.prompt ?? toolInput.description ?? '');
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: false,
-    defaultParams: {
-      blockingPatterns: DEFAULT_BLOCKING_PATTERNS,
-      waitJustifiedMarker: DEFAULT_WAIT_JUSTIFIED_MARKER,
-    },
-  },
-  ({ toolName, toolInput, parameters }) => {
-    const isShell = SHELL_TOOLS.has(toolName);
-    const isDelegation = DELEGATION_TOOLS.has(toolName);
-    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 (toolInput.run_in_background === true) return;
-    if (NOT_TAKING_THE_TURN.test(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;
-    }
-
-    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(
-          GATE_ID,
-          `${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.',
-        );
-      }
-    }
-  },
-);
+// 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.
+
+import {
+  runGate,
+  deny,
+  toolInGroups,
+  delegationPromptOf,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'no-blocking';
+const CONFIG_KEY = 'blockWaitingCommands';
+
+const DEFAULT_WAIT_JUSTIFIED_MARKER = 'WAIT-JUSTIFIED:';
+
+// 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';
+
+/** Blocking rules as `[regexSource, reason]`, matched case-insensitively. */
+const DEFAULT_BLOCKING_PATTERNS = [
+  [
+    String.raw`(^|[|;&]\s*|\bthen\s+|\bdo\s+)(sleep|timeout)\s+\d`,
+    '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.',
+  ],
+  [
+    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`,
+    '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(''),
+    '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+`,
+    "'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`,
+    '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`,
+    '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.',
+  ],
+];
+
+// 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.
+const NOT_TAKING_THE_TURN =
+  /(&\s*$|\bnohup\b|\bstart\s+\/b\b|--detach\b|\b-d(?=\s*($|[|;&]))|\bStart-Job\b|\bStart-Process\b[^|;\n]*-NoNewWindow\b|\brun_in_background\b)/i;
+
+function compile(source) {
+  return new RegExp(source, 'i');
+}
+
+/** 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 ?? '');
+  }
+  return delegationPromptOf(toolInput);
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      blockingPatterns: DEFAULT_BLOCKING_PATTERNS,
+      waitJustifiedMarker: DEFAULT_WAIT_JUSTIFIED_MARKER,
+    },
+  },
+  ({ 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 (toolInput.run_in_background === true) return;
+    if (NOT_TAKING_THE_TURN.test(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;
+    }
+
+    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(
+          GATE_ID,
+          `${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.',
+        );
+      }
+    }
+  },
+);

package/plugins/gates/hooks/gates/no-blocking/no-blocking.edge.test.mjs

@@ -0,0 +1,109 @@
+// Edge-case audit for no-blocking: bypasses and false positives.
+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(), 'no-blocking-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;
+}
+
+const ENABLED = { gates: { blockWaitingCommands: true } };
+
+function bash(command, extra = {}) {
+  return { tool_name: 'Bash', tool_input: { command, ...extra } };
+}
+function mcpTool(name, input) {
+  return { tool_name: name, tool_input: input };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+// ── BUG: MCP shell-equivalent tools are not in TOOL_GROUPS.shell/delegation.
+test('FIXED: an mcp shell-equivalent tool running "sleep 30" is now recognized', () => {
+  const result = runGate(mcpTool('mcp__shell__run', { command: 'sleep 30' }), {
+    config: ENABLED,
+  });
+  assert.ok(isDeny(result)); // toolInGroups classifies mcp__shell__run into the shell group
+});
+
+// ── BUG (false positive / evasion pairing): the WAIT-JUSTIFIED marker escape requires
+// NO reason validation beyond "two more tokens exist after the marker" — the reason text
+// itself is never checked for plausibility, so trivially defeats the intent of a
+// "declared, justified wait": any two words work as an unchecked excuse.
+test('BUG (weak justification check): any two-word text after the marker escapes the block regardless of content', () => {
+  const result = runGate(
+    bash('sleep 9999 # WAIT-JUSTIFIED: because yes'),
+    { config: ENABLED },
+  );
+  assert.equal(result, null); // allowed: marker escape has no semantic validation, only shape
+});
+
+// ── BUG candidate: `timeout 30 someserver` is matched by the sleep|timeout pattern
+// requiring the command to START the line or follow |;&/then/do. A background-launched
+// dev server that is piped through `| cat` first, e.g. `npm run dev | cat`, should still
+// match \b(npm|pnpm|yarn|bun)\s+(run\s+)?(dev|start|serve|watch)\b since that's a
+// substring test with no anchoring requirement (unlike sleep/timeout). Confirm no bypass.
+test('OK: piping a dev server through another command does not bypass the dev-server pattern', () => {
+  assert.ok(
+    isDeny(runGate(bash('npm run dev | cat'), { config: ENABLED })),
+  );
+});
+
+// ── BUG: `NOT_TAKING_THE_TURN` includes `-d\b` as a generic "detached" flag marker. This
+// is dangerously broad: ANY command containing a standalone `-d` token — including one
+// completely unrelated to backgrounding — escapes every blocking pattern. E.g. `sleep 30
+// -d` (nonsensical flag for sleep, but matches) or more realistically a docker/curl
+// command with an unrelated `-d` (data) flag combined with a blocking pattern.
+test('FIXED: an unrelated "-d" flag (curl -d) no longer escapes the blocking check', () => {
+  // curl -d is "data", not detach. The bare -d escape was removed, so a genuinely foreground
+  // sleep on the same command line is now denied despite the unrelated -d flag.
+  const result = runGate(bash('sleep 30; curl -d "payload" http://x'), {
+    config: ENABLED,
+  });
+  assert.ok(isDeny(result));
+});
+
+// ── BUG candidate: `npm run dev &` (trailing background operator with a space before
+// EOL, e.g. training whitespace) — NOT_TAKING_THE_TURN requires `&\s*$`. A trailing
+// newline in the JSON string (unlikely from a real shell, but a delegation prompt or a
+// tool that appends '\n') would still satisfy `\s*$` since \s includes \n. Not pursued
+// further as a distinct bug; documenting as checked.
+test('OK: trailing background operator followed by trailing whitespace still escapes correctly (not a bug)', () => {
+  assert.equal(
+    runGate(bash('npm run dev &  '), { config: ENABLED }),
+    null,
+  );
+});
+
+// ── BUG candidate: PowerShell `Start-Job` / `Start-Process ... -NoNewWindow` background
+// forms are not recognized by NOT_TAKING_THE_TURN, but that only matters if the command
+// is ALSO caught by a blocking pattern in the first place. `Start-Sleep` alone, run as
+// `Start-Job { Start-Sleep 30 }` (already backgrounded via Start-Job) is still matched by
+// \bStart-Sleep\b and NOT recognized as non-blocking, causing a FALSE POSITIVE: a
+// genuinely backgrounded PowerShell job gets denied because its "backgrounded" wrapper
+// (Start-Job) is not in NOT_TAKING_THE_TURN.
+test('FIXED: Start-Sleep inside a Start-Job background wrapper is now allowed', () => {
+  const result = runGate(bash('Start-Job { Start-Sleep 30 }'), {
+    config: ENABLED,
+  });
+  assert.equal(result, null); // Start-Job is now recognized as a backgrounding mechanism
+});