@devrik-tools/claude-gates 0.1.0

package/plugins/gates/hooks/gates/never-assume/test.mjs

@@ -0,0 +1,78 @@
+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(), 'never-assume-'));
+  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,
+    // Isolate from the user's real global config: point homedir() at the temp
+    // project so the global-config fallback finds nothing (registry default).
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function write(content) {
+  return {
+    tool_name: 'Write',
+    tool_input: { file_path: '/repo/src/x.js', content },
+  };
+}
+function isWarn(result) {
+  return result?.hookSpecificOutput?.additionalContext !== undefined;
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+const ENABLE = {
+  config: { gates: { requireVerificationBeforeAssuming: true } },
+};
+
+test('warns on conjecture phrasing', () => {
+  assert.ok(isWarn(runGate(write('// i assume the timezone is UTC'), ENABLE)));
+  assert.ok(isWarn(runGate(write('// probably fine to skip this'), ENABLE)));
+});
+
+test('never denies, only warns', () => {
+  const result = runGate(write('// i assume this works'), ENABLE);
+  assert.ok(isWarn(result));
+  assert.ok(!isDeny(result));
+});
+
+test('allows content without conjecture phrasing', () => {
+  assert.equal(runGate(write('const x = 1;'), ENABLE), null);
+});
+
+test('disabled by default (registry default is false)', () => {
+  assert.equal(runGate(write('// i assume this works')), null);
+});
+
+test('project conjecturePatterns override replaces the built-in list', () => {
+  const config = {
+    gates: {
+      requireVerificationBeforeAssuming: {
+        enabled: true,
+        conjecturePatterns: ['totally made up'],
+      },
+    },
+  };
+  assert.equal(runGate(write('// i assume this works'), { config }), null);
+  assert.ok(
+    isWarn(runGate(write('// totally made up value here'), { config })),
+  );
+});

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

@@ -0,0 +1,142 @@
+// 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.',
+        );
+      }
+    }
+  },
+);

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

@@ -0,0 +1,108 @@
+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');
+
+// Runs the gate as its own process (it calls process.exit), feeding a payload on stdin
+// from inside a temp project so the gate's config lookup is isolated. Returns the parsed
+// stdout, or null when the gate allowed (no output).
+function runGate(payload, { config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'no-blocking-'));
+  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,
+    // Isolate from the user's real global config: point homedir() at the temp
+    // project so the global-config fallback finds nothing (registry default).
+    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 delegate(prompt) {
+  return { tool_name: 'Agent', tool_input: { prompt } };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+test('denies sleep in foreground, a dev server, and a polling loop', () => {
+  assert.ok(isDeny(runGate(bash('sleep 30'), { config: ENABLED })));
+  assert.ok(isDeny(runGate(bash('npm run dev'), { config: ENABLED })));
+  assert.ok(
+    isDeny(
+      runGate(bash('until curl -sf localhost:3000; do sleep 2; done'), {
+        config: ENABLED,
+      }),
+    ),
+  );
+});
+
+test('allows an innocuous command and a backgrounded long-runner', () => {
+  assert.equal(runGate(bash('git status'), { config: ENABLED }), null);
+  assert.equal(
+    runGate(bash('npm run dev', { run_in_background: true }), {
+      config: ENABLED,
+    }),
+    null,
+  );
+  assert.equal(runGate(bash('sleep 30 &'), { config: ENABLED }), null);
+});
+
+test('disabled by default: the gate does not run without opting in', () => {
+  assert.equal(runGate(bash('sleep 30')), null);
+});
+
+test('a delegation prompt telling the subagent to sleep-wait is denied', () => {
+  assert.ok(
+    isDeny(
+      runGate(
+        delegate('Please then sleep 60 seconds until the server is ready.'),
+        {
+          config: ENABLED,
+        },
+      ),
+    ),
+  );
+});
+
+test('the wait-justified marker with a reason escapes the block', () => {
+  assert.equal(
+    runGate(
+      bash('sleep 30 # WAIT-JUSTIFIED: waiting for migration lock release'),
+      {
+        config: ENABLED,
+      },
+    ),
+    null,
+  );
+});
+
+test('project blockingPatterns replaces the built-in list', () => {
+  const config = {
+    gates: {
+      blockWaitingCommands: {
+        enabled: true,
+        blockingPatterns: [String.raw`\bcustom-block\b`],
+      },
+    },
+  };
+  // sleep no longer denied under the override
+  assert.equal(runGate(bash('sleep 30'), { config }), null);
+  assert.ok(isDeny(runGate(bash('custom-block now'), { config })));
+});

package/plugins/gates/hooks/gates/no-memory-dependency/index.mjs

@@ -0,0 +1,120 @@
+// no-memory-dependency — warns (never denies) when a delegation prompt leans on the
+// subagent "remembering" something said earlier in conversation instead of carrying
+// the data itself. A fresh subagent has no access to the delegator's conversation
+// history: if the data matters, it must travel IN the prompt, in a file the subagent
+// reads, or in an already-persisted decision.
+//
+// ── Two stages, same pattern as intent-flow ─────────────────────────────────────────
+// Stage 1 (cheap): does any memory-dependency phrase appear anywhere? If not, allow.
+// Stage 2 (confirmation, only on candidates): strip quoted text, then discard a phrase
+// that has a deterministic persistence instruction nearby (a file, flag, env var, gate)
+// — "remember to save this to notes.md" does not depend on model memory, it depends on
+// a real file. This is a soft signal (warn), not a hard block: whether the brief truly
+// needs the data or is just referencing prior agreement needs judgment this gate can't
+// supply on its own.
+
+import { runGate, warn, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'no-memory-dependency';
+const CONFIG_KEY = 'warnMemoryDependencyInBrief';
+
+const DELEGATION_TOOLS = new Set(TOOL_GROUPS.delegation);
+
+const DEFAULT_MEMORY_DEPENDENCY_PATTERNS = [
+  'acordate de|acu[eé]rdate de',
+  'no olvides|no te olvides',
+  'record[aá] que|ten[eé] en cuenta que',
+  'como te dije|como ya te dije|ya te dije|te lo dije antes|ya te ped[ií]',
+  "remember to|don'?t forget|keep in mind",
+];
+
+// Split into two simpler alternations (tested with plain OR at call time) instead of
+// one large regex: each half stays well under the complexity/backtracking budget a
+// single combined pattern would hit.
+const PERSISTENCE_NOUN_PATTERN =
+  /archivo|file|flag|variable de entorno|env var|gate determinista|deterministic gate|\.md|\.json/i;
+// Kept deliberately flat (no nested optional groups) to stay under the regex-complexity
+// budget: a handful of plain alternatives rather than one clever pattern with backtracking.
+const PERSISTENCE_VERB_PATTERN =
+  /guardal[oa]|guarda|guardá esto|persisti|persiste|persistir|persistido|escribil[oa] en|escribi en|save it in|save this in|save it to|save this to/i;
+
+const PERSISTENCE_WINDOW = 80;
+
+function withUnicodeWordBoundary(alternatives) {
+  return new RegExp(
+    `(?<![\\p{L}\\p{N}_])(${alternatives})(?![\\p{L}\\p{N}_])`,
+    'iu',
+  );
+}
+
+function stripQuoted(text) {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/"[^"\n]{0,300}"/g, ' ')
+    .replace(/'[^'\n]{0,300}'/g, ' ');
+}
+
+function allMatches(pattern, text) {
+  const flags = pattern.flags.includes('g')
+    ? pattern.flags
+    : `${pattern.flags}g`;
+  return [...text.matchAll(new RegExp(pattern.source, flags))];
+}
+
+function hasPersistenceInstructionNearby(text, match) {
+  const from = Math.max(0, match.index - PERSISTENCE_WINDOW);
+  const to = Math.min(
+    text.length,
+    match.index + match[0].length + PERSISTENCE_WINDOW,
+  );
+  const window = text.slice(from, to);
+  return (
+    PERSISTENCE_NOUN_PATTERN.test(window) ||
+    PERSISTENCE_VERB_PATTERN.test(window)
+  );
+}
+
+function unresolvedMemoryPhrases(prompt, memoryPattern) {
+  if (!memoryPattern.test(prompt)) return []; // stage 1: no candidate, allow cheap
+
+  const text = stripQuoted(prompt); // stage 2(a)
+  const matches = allMatches(memoryPattern, text);
+
+  return matches
+    .filter((match) => !hasPersistenceInstructionNearby(text, match))
+    .map((match) => match[0].trim());
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      memoryDependencyPatterns: DEFAULT_MEMORY_DEPENDENCY_PATTERNS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!DELEGATION_TOOLS.has(toolName)) return;
+
+    const prompt = String(
+      toolInput.prompt ?? toolInput.description ?? toolInput.task ?? '',
+    );
+    if (!prompt.trim()) return;
+
+    const memoryPattern = withUnicodeWordBoundary(
+      (parameters.memoryDependencyPatterns ?? []).join('|'),
+    );
+
+    const phrases = unresolvedMemoryPhrases(prompt, memoryPattern);
+    if (phrases.length === 0) return;
+
+    const quotedPhrases = phrases.map((phrase) => `"${phrase}"`).join(', ');
+    warn(
+      GATE_ID,
+      `This delegation depends on the model remembering something (${quotedPhrases}). ` +
+        'If it matters, it should live in a file, a flag, an environment variable, or a deterministic gate — ' +
+        "not in the model's memory.",
+    );
+  },
+);

package/plugins/gates/hooks/gates/no-memory-dependency/test.mjs

@@ -0,0 +1,106 @@
+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-memory-dependency-'));
+  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,
+    // Isolate from the user's real global config: point homedir() at the temp
+    // project so the global-config fallback finds nothing (registry default).
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function delegate(prompt) {
+  return { tool_name: 'Agent', tool_input: { prompt } };
+}
+function isWarn(result) {
+  return typeof result?.hookSpecificOutput?.additionalContext === 'string';
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+const ENABLED = { config: { gates: { warnMemoryDependencyInBrief: true } } };
+
+test('warns (never denies) when the brief leans on remembered context', () => {
+  const result = runGate(
+    delegate('Acordate de lo que hablamos antes y aplica el mismo criterio.'),
+    ENABLED,
+  );
+  assert.ok(isWarn(result));
+  assert.ok(!isDeny(result));
+});
+
+test('allows a brief with no memory-dependency phrase', () => {
+  assert.equal(
+    runGate(
+      delegate('Implementa el endpoint de login segun el contrato adjunto.'),
+      ENABLED,
+    ),
+    null,
+  );
+});
+
+test('allows a memory phrase paired with a deterministic persistence instruction', () => {
+  assert.equal(
+    runGate(
+      delegate(
+        'No te olvides de guardar la decision en .ai/decision.md antes de continuar.',
+      ),
+      ENABLED,
+    ),
+    null,
+  );
+});
+
+test('disabled by config: the gate does not run', () => {
+  assert.equal(
+    runGate(
+      delegate('Acordate de lo que hablamos antes y aplica el mismo criterio.'),
+      {
+        config: { gates: { warnMemoryDependencyInBrief: false } },
+      },
+    ),
+    null,
+  );
+});
+
+test('project memoryDependencyPatterns override replaces the built-in list', () => {
+  const config = {
+    gates: {
+      warnMemoryDependencyInBrief: {
+        enabled: true,
+        memoryDependencyPatterns: ['como quedamos'],
+      },
+    },
+  };
+  // No longer matches the built-in "acordate de" phrase.
+  assert.equal(
+    runGate(
+      delegate('Acordate de lo que hablamos antes y aplica el mismo criterio.'),
+      { config },
+    ),
+    null,
+  );
+  assert.ok(
+    isWarn(
+      runGate(delegate('Hacelo como quedamos la ultima vez.'), { config }),
+    ),
+  );
+});