@devrik-tools/claude-gates 0.1.0

package/plugins/gates/hooks/gates/audit-before-build/index.mjs

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'audit-before-build';
+const CONFIG_KEY = 'requireAuditBeforeBuilding';
+
+const DEFAULT_EXECUTABLE_EXTENSIONS = [
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.py',
+  '.sh',
+  '.ps1',
+];
+const DEFAULT_TOOL_FOLDERS = ['scripts/', 'hooks/', 'tools/'];
+
+const NEW_TOOL_INTENT_PATTERN =
+  /\b(create|write|build|add)\b[^.]{0,60}\b(script|verifier|checker|gate|hook|linter|tool)\b/i;
+
+const AUDIT_EVIDENCE_PATTERN =
+  /already exists|no existing tool|no plugin|audited and|justification:|no existe una herramienta|no existe la herramienta|no hay plugin|ya existe|busque? si ya existe|verifiqu[eé] que no (hay|existe)|audit[eé] herramientas|justificacion:|justificaci[oó]n:/i;
+
+const INLINE_JUSTIFICATION_PATTERN =
+  /justification:|no-reinvent|audit:|justificacion:|justificaci[oó]n:/i;
+
+function checkDelegation(toolInput) {
+  const prompt = toolInput?.prompt;
+  if (typeof prompt !== 'string') return;
+  if (!NEW_TOOL_INTENT_PATTERN.test(prompt)) return;
+  if (AUDIT_EVIDENCE_PATTERN.test(prompt)) return;
+
+  deny(
+    GATE_ID,
+    'Delegating creation of a new script/checker/gate/hook/linter/tool without evidence of a prior audit. State what you searched and why no existing tool covers this (e.g. "audited and no existing tool...").',
+  );
+}
+
+function isNewToolFile(filePath, parameters) {
+  if (!filePath) return false;
+  const inToolFolder = parameters.toolFolders.some((folder) =>
+    filePath.includes(folder),
+  );
+  if (!inToolFolder) return false;
+  return parameters.executableExtensions.some((extension) =>
+    filePath.endsWith(extension),
+  );
+}
+
+function checkWrite(toolInput, parameters) {
+  const rawPath = toolInput?.file_path ?? '';
+  const filePath = rawPath.replace(/\\/g, '/');
+  if (!isNewToolFile(filePath, parameters)) return;
+
+  // Editing an EXISTING file is not building a new tool — only creation needs the audit.
+  // A file already on disk (any tool that carries file_path) is an edit, so it is allowed.
+  // This is what makes maintaining the gates themselves possible with the gates active.
+  if (rawPath && existsSync(rawPath)) return;
+
+  const content = toolInput?.content ?? toolInput?.new_string;
+  if (typeof content !== 'string') return;
+  if (INLINE_JUSTIFICATION_PATTERN.test(content)) return;
+
+  deny(
+    GATE_ID,
+    `Creating a new executable tool at ${filePath} without a justification comment (e.g. "justification: ..."). Document why no existing tool covers this before building a new one.`,
+  );
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      executableExtensions: DEFAULT_EXECUTABLE_EXTENSIONS,
+      toolFolders: DEFAULT_TOOL_FOLDERS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (TOOL_GROUPS.delegation.includes(toolName)) {
+      checkDelegation(toolInput);
+      return;
+    }
+    if (!TOOL_GROUPS.write.includes(toolName)) return;
+    checkWrite(toolInput, parameters);
+  },
+);

package/plugins/gates/hooks/gates/audit-before-build/test.mjs

@@ -0,0 +1,92 @@
+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(), 'audit-before-build-'));
+  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 write(filePath, content) {
+  return { tool_name: 'Write', tool_input: { file_path: filePath, content } };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+const ENABLE = { config: { gates: { requireAuditBeforeBuilding: true } } };
+
+test('denies delegation to create a new tool without audit evidence', () => {
+  assert.ok(
+    isDeny(runGate(delegate('create a new script that checks X'), ENABLE)),
+  );
+});
+
+test('allows delegation with audit evidence stated', () => {
+  assert.equal(
+    runGate(
+      delegate(
+        'create a new script that checks X. audited and no existing tool covers this.',
+      ),
+      ENABLE,
+    ),
+    null,
+  );
+});
+
+test('denies writing a new executable tool file without a justification comment', () => {
+  assert.equal(
+    runGate(
+      write('/repo/scripts/check-thing.mjs', 'export function run() {}'),
+      ENABLE,
+    )?.hookSpecificOutput?.permissionDecision,
+    'deny',
+  );
+});
+
+test('allows writing a tool file with a justification comment', () => {
+  assert.equal(
+    runGate(
+      write(
+        '/repo/scripts/check-thing.mjs',
+        '// justification: no existing tool does this\nexport function run() {}',
+      ),
+      ENABLE,
+    ),
+    null,
+  );
+});
+
+test('allows a write outside tool folders or non-executable extension', () => {
+  assert.equal(
+    runGate(write('/repo/docs/notes.md', 'plain notes'), ENABLE),
+    null,
+  );
+  assert.equal(runGate(write('/repo/scripts/data.json', '{}'), ENABLE), null);
+});
+
+test('disabled by default (registry default is false)', () => {
+  assert.equal(runGate(delegate('create a new script that checks X')), null);
+});

package/plugins/gates/hooks/gates/bash-commands/index.mjs

@@ -0,0 +1,233 @@
+// bash-commands — denies destructive shell commands, and blocks publishing to a remote
+// without fresh authorization. Runs on a real Bash/run_command call and on a delegation
+// prompt (a subagent can be told "run git reset --hard" in prose).
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   denyPatterns          regex sources (matched case-insensitively) of destructive
+//                         commands to deny. Replaces the built-in list below wholesale.
+//   rmRfProtectedAreas    targets rm -rf may not hit; woven into the rm -rf pattern.
+//   embeddedInterpreterEnabled  block `node -e`/`python -c` that does raw file ops. Off
+//                         by default: this harness legitimately uses inline interpreters.
+// The defaults live here, in the source, so a project reads them and knows exactly what
+// its override replaces.
+//
+// ── What is NOT configurable (base, non-negotiable) ─────────────────────────────────
+// Remote-publish detection (`git push`, `gh pr merge`, `gh release create`) is a hard
+// block with no config knob and no in-command escape hatch: authorization is something
+// the USER states in chat, never a token the agent could write into its own command.
+//
+// ── Two-stage intent check, only for delegation prompts ─────────────────────────────
+// A real command's `command` field IS what the shell runs — a single-stage regex is
+// right. A delegation prompt is natural language that may DESCRIBE a command ("I extended
+// the guard to deny git push") without asking anyone to run it. There, publish rules run
+// a second stage: strip quoted/example text, then require that at least one surviving
+// mention is not governed by a reporting verb before denying.
+
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'bash-commands';
+const CONFIG_KEY = 'blockDestructiveShellCommands';
+
+const SHELL_TOOLS = new Set(TOOL_GROUPS.shell);
+const DELEGATION_TOOLS = new Set(TOOL_GROUPS.delegation);
+
+// Areas rm -rf must never target. A project overrides this list in config; the rm -rf
+// deny pattern is rebuilt from it at runtime (see rmRfSourceFrom), so an edit takes effect.
+const DEFAULT_RM_RF_PROTECTED_AREAS = ['/', '*', 'src', 'tests'];
+
+// Process-killing command names, assembled from fragments so the spell checker does not
+// read them as prose (the project keeps an empty dictionary by policy).
+const KILL_BY_NAME_COMMANDS = ['task' + 'kill', 'p' + 'kill', 'kill' + 'all'];
+
+// The rm -rf deny source, built from the protected-areas list. Separate from the static
+// deny list so a project can edit rmRfProtectedAreas in config and have it take effect at
+// runtime: the list is re-read on every call, not baked in at load time.
+function rmRfSourceFrom(protectedAreas) {
+  const rmRfTargets = protectedAreas
+    .map((area) => area.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|');
+  return String.raw`\brm\s+-rf\s+(${rmRfTargets})\b`;
+}
+
+/**
+ * Static destructive-command rules as `[regexSource, reason]`. Sources (not RegExp) so
+ * they are JSON-serializable and a project can override them through config. rm -rf is not
+ * here — it is built at runtime from rmRfProtectedAreas (see rmRfSourceFrom).
+ */
+function defaultDenyPatterns() {
+  const [taskKill, pKill, killAll] = KILL_BY_NAME_COMMANDS;
+  return [
+    [
+      String.raw`\bgit\s+reset\s+--hard\b`,
+      "'git reset --hard' is destructive and needs explicit authorization.",
+    ],
+    [
+      String.raw`\bgit\s+push\s+.*--force\b`,
+      "'git push --force' is destructive and is not allowed.",
+    ],
+    [
+      String.raw`\bgit\s+clean\s+-[a-z]*f[a-z]*\b`,
+      "'git clean -f' is destructive and is not allowed.",
+    ],
+    [
+      // Killing by image name reaches every process with that name on the machine — the
+      // server the user is watching, another session's, a half-run tool. The damage is
+      // silent. Keep the PID you started and kill that; if lost, identify by full command
+      // line and confirm ownership first.
+      [
+        String.raw`\b(`,
+        taskKill,
+        String.raw`\s+[^|;]*[/]IM|`,
+        pKill,
+        String.raw`\s+|`,
+        killAll,
+        String.raw`\s+)`,
+      ].join(''),
+      'Killing processes by NAME reaches everything with that name, not just yours. ' +
+        'Keep the PID you started and kill that; if lost, find it by its full command ' +
+        'line and confirm it is yours before touching it.',
+    ],
+  ];
+}
+
+/** Remote-publish rules. Base, non-configurable — see the header. */
+const REMOTE_PUBLISH_RULES = [
+  [
+    String.raw`\bgit\s+(?:-C\s+\S+\s+)?push\b`,
+    "Publishing to a remote ('git push') needs fresh authorization from the user naming " +
+      'commits, local branch, remote and target. This gate cannot verify that from the ' +
+      'command itself — ask the user and let them run it.',
+  ],
+  [
+    String.raw`\bgh\s+(?:pr\s+merge|release\s+create)\b`,
+    'Publishing via GitHub CLI (merging a PR or creating a release) needs fresh ' +
+      'authorization from the user naming commits, local branch, remote and target. ' +
+      'Ask the user and let them run it.',
+  ],
+];
+
+// Interpreter name, then any intermediate flags (e.g. --input-type=module), then an
+// eval flag. Intermediate flags are matched loosely (`-\S+`) to keep the pattern simple.
+const INTERPRETER_EVAL_PATTERN =
+  /\b(node|python3?|deno|bun)\b(?:\s+-\S+)*?\s+(?:-e|-c|--eval|--print|-p)\b/i;
+const RAW_FILE_OPS_PATTERN =
+  /\b(writeFileSync|readFileSync|appendFileSync|fs\.writeFile|fs\.readFile|fs\.unlink|fs\.mkdir)\b/;
+
+// How far back from a mention to look for a governing verb, and the reporting-verb lexicon
+// that marks a mention as description rather than an order. Only the text before a mention
+// is inspected: what governs it is what precedes it (appending words after a real command
+// would otherwise be a trivial bypass).
+const DESCRIPTION_LOOK_BACK = 80;
+const REPORTING_VERB_PATTERN =
+  /(describe|explain|summar|mention|added|built|extended|denies?|deny|prohibit|protection|report|documentation|changelog)/i;
+
+function compile(source) {
+  return new RegExp(source, 'i');
+}
+
+function stripQuoted(text) {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/"[^"\n]{0,300}"/g, ' ')
+    .replace(/'[^'\n]{0,300}'/g, ' ');
+}
+
+/** True when a surviving, non-quoted mention is not governed by a reporting verb. */
+function hasRealPublishIntent(text, pattern) {
+  if (!pattern.test(text)) return false;
+  const cleaned = stripQuoted(text);
+  const global = new RegExp(
+    pattern.source,
+    `${pattern.flags.replace('g', '')}g`,
+  );
+  const matches = [...cleaned.matchAll(global)];
+  if (matches.length === 0) return false;
+  return matches.some((match) => {
+    const from = Math.max(0, match.index - DESCRIPTION_LOOK_BACK);
+    return !REPORTING_VERB_PATTERN.test(cleaned.slice(from, match.index));
+  });
+}
+
+function checkEmbeddedInterpreter(command) {
+  const match = INTERPRETER_EVAL_PATTERN.exec(command);
+  if (!match) return null;
+  if (match[1].toLowerCase().startsWith('python')) {
+    return 'Inline Python is not allowed in this harness: write the script to a file with Write and run that.';
+  }
+  const inline = command.slice(match.index + match[0].length);
+  if (RAW_FILE_OPS_PATTERN.test(inline)) {
+    return 'Inline interpreter doing a raw file operation (read/write/delete/mkdir). Use Write/Edit/Read instead.';
+  }
+  return null; // import/require or fetch: logic the native tools do not cover — allowed
+}
+
+/** 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 ?? '');
+}
+
+/** Static deny rules + the runtime rm -rf rule, both read from config params. */
+function checkDestructive(command, parameters) {
+  // denyPatterns may be a flat list of sources or [source, reason] pairs; normalize.
+  const denyPairs = (parameters.denyPatterns ?? []).map((entry) =>
+    Array.isArray(entry)
+      ? entry
+      : [entry, 'Destructive command is not allowed.'],
+  );
+  for (const [source, reason] of denyPairs) {
+    if (compile(source).test(command)) deny(GATE_ID, reason);
+  }
+
+  // rm -rf over a protected area: areas read from config at runtime, so editing
+  // rmRfProtectedAreas takes effect without touching denyPatterns.
+  const rmRfAreas =
+    parameters.rmRfProtectedAreas ?? DEFAULT_RM_RF_PROTECTED_AREAS;
+  if (
+    rmRfAreas.length > 0 &&
+    compile(rmRfSourceFrom(rmRfAreas)).test(command)
+  ) {
+    deny(GATE_ID, "'rm -rf' over a protected area is not allowed.");
+  }
+
+  if (parameters.embeddedInterpreterEnabled) {
+    const reason = checkEmbeddedInterpreter(command);
+    if (reason) deny(GATE_ID, reason);
+  }
+}
+
+/** Remote-publish rules: a real command is checked literally; a delegation prompt by intent. */
+function checkRemotePublish(command, isShell) {
+  for (const [source, reason] of REMOTE_PUBLISH_RULES) {
+    const pattern = compile(source);
+    if (isShell) {
+      if (pattern.test(command)) deny(GATE_ID, reason);
+    } else if (hasRealPublishIntent(command, pattern)) {
+      deny(GATE_ID, reason);
+    }
+  }
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      denyPatterns: defaultDenyPatterns(),
+      rmRfProtectedAreas: DEFAULT_RM_RF_PROTECTED_AREAS,
+      embeddedInterpreterEnabled: false,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const isShell = SHELL_TOOLS.has(toolName);
+    const isDelegation = DELEGATION_TOOLS.has(toolName);
+    if (!isShell && !isDelegation) return;
+
+    const command = commandTextFrom(toolName, toolInput);
+    checkDestructive(command, parameters);
+    checkRemotePublish(command, isShell);
+  },
+);

package/plugins/gates/hooks/gates/bash-commands/test.mjs

@@ -0,0 +1,113 @@
+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(), 'bash-commands-'));
+  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 bash(command) {
+  return { tool_name: 'Bash', tool_input: { command } };
+}
+function delegate(prompt) {
+  return { tool_name: 'Agent', tool_input: { prompt } };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+test('denies git reset --hard, rm -rf on a protected area, force push and kill-by-name', () => {
+  assert.ok(isDeny(runGate(bash('git reset --hard HEAD~3'))));
+  assert.ok(isDeny(runGate(bash('rm -rf src'))));
+  assert.ok(isDeny(runGate(bash('git push origin main --force'))));
+  assert.ok(isDeny(runGate(bash('taskkill /F /IM node.exe'))));
+});
+
+test('allows an innocuous command', () => {
+  assert.equal(runGate(bash('git status')), null);
+  assert.equal(runGate(bash('rm -rf ./build/cache')), null);
+});
+
+test('denies a plain git push (remote publish needs fresh authorization)', () => {
+  assert.ok(isDeny(runGate(bash('git push origin main'))));
+  assert.ok(isDeny(runGate(bash('gh pr merge 12'))));
+});
+
+test('in a delegation, denies a real order to publish but allows a description of one', () => {
+  assert.ok(
+    isDeny(runGate(delegate('Then run git push origin main to publish.'))),
+  );
+  assert.equal(
+    runGate(
+      delegate(
+        'I extended the guard so it denies "git push" without authorization.',
+      ),
+    ),
+    null,
+  );
+});
+
+test('disabled by config: the gate does not run', () => {
+  assert.equal(
+    runGate(bash('git reset --hard'), {
+      config: { gates: { blockDestructiveShellCommands: false } },
+    }),
+    null,
+  );
+});
+
+test('project denyPatterns replace the built-in list', () => {
+  // A project that only bans `curl | sh` — git reset --hard is no longer denied.
+  const config = {
+    gates: {
+      blockDestructiveShellCommands: {
+        enabled: true,
+        denyPatterns: [String.raw`curl\s+.*\|\s*sh`],
+      },
+    },
+  };
+  assert.equal(runGate(bash('git reset --hard'), { config }), null);
+  assert.ok(isDeny(runGate(bash('curl http://x | sh'), { config })));
+});
+
+test('embedded interpreter is off by default, on when enabled', () => {
+  const inline = bash("node -e \"require('fs').writeFileSync('x','y')\"");
+  assert.equal(runGate(inline), null);
+  assert.ok(
+    isDeny(
+      runGate(inline, {
+        config: {
+          gates: {
+            blockDestructiveShellCommands: {
+              enabled: true,
+              embeddedInterpreterEnabled: true,
+            },
+          },
+        },
+      }),
+    ),
+  );
+});