@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/plugins/gates/hooks/doctor.mjs

@@ -0,0 +1,207 @@
+// doctor — SessionStart hook. Validates the environment claude-gates needs and speaks
+// ONLY on failure: node's version (node:sqlite and other built-ins the plugin relies on
+// need >=22.5.0, read from this package's own engines.node when reachable, else a
+// hard-coded fallback) and that every gate script the registry declares actually exists
+// on disk (a plugin installed half — e.g. copied without a file, or a stale global
+// install) fails silently otherwise: hooks.json references a script that is not there,
+// and Claude Code just skips it without telling anyone).
+//
+// justification: no existing tool covers this. wiring-check.mjs (same family) checks
+// registry vs hooks.json vs disk cross-consistency; doctor.mjs checks the runtime
+// environment itself (node version) plus the same "script exists" fact from the angle
+// of "can this plugin even run", so a broken environment is caught before any gate is
+// invoked and blocks something for the wrong reason.
+//
+// Fail-safe: every check is wrapped so a doctor bug never blocks a session from
+// starting — worst case it silently skips a check rather than throwing.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const STDIN_FILE_DESCRIPTOR = 0;
+const SESSION_START_EVENT = 'SessionStart';
+const CONFIG_KEY = 'validateEnvironmentOnStart';
+const DEFAULT_MIN_NODE_VERSION = '22.5.0';
+
+const HOOKS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const REPOSITORY_ROOT = join(HOOKS_DIRECTORY, '..', '..', '..');
+const PACKAGE_JSON_PATH = join(REPOSITORY_ROOT, 'package.json');
+const REGISTRY_PATH = join(REPOSITORY_ROOT, 'registry.json');
+
+// Same config lookup as the other session hooks (see session-tasks.mjs / register-requests.mjs):
+// kept local and dependency-free so this plugin works standalone.
+const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
+const PROJECT_CONFIG = join('.ai', 'config.json');
+const GLOBAL_CONFIG = join('.claude', 'claude-gates', 'config.json');
+
+const BOM_CHAR_CODE = 0xfeff;
+
+/** Strips a UTF-8 BOM a Windows editor/tool may have written before the JSON. */
+function stripBom(text) {
+  return text.charCodeAt(0) === BOM_CHAR_CODE ? text.slice(1) : text;
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(stripBom(readFileSync(path, 'utf8')));
+  } catch {
+    return null;
+  }
+}
+
+function projectRootOf(startDirectory) {
+  let current = startDirectory;
+  while (true) {
+    if (
+      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
+    ) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** The doctor gate config entry (project overrides global), or null. */
+function doctorConfig(startDirectory) {
+  const root = projectRootOf(startDirectory);
+  const projectData = root ? readJson(join(root, PROJECT_CONFIG)) : null;
+  const globalData = readJson(join(homedir(), GLOBAL_CONFIG));
+  const layer = projectData?.gates ?? globalData?.gates ?? {};
+  const entry = layer[CONFIG_KEY];
+  if (typeof entry === 'boolean') return { enabled: entry };
+  if (entry && typeof entry === 'object') return entry;
+  return null;
+}
+
+function readPayload() {
+  try {
+    return JSON.parse(readFileSync(STDIN_FILE_DESCRIPTOR, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+const VERSION_SEGMENT_COUNT = 3; // major, minor, patch
+
+/** Parses "22.5.0" (or "v22.5.0") into [22, 5, 0]; null when unparseable. */
+function parseVersion(raw) {
+  const withoutPrefix = String(raw ?? '').replace(/^v/, '');
+  const segments = withoutPrefix.split('.').slice(0, VERSION_SEGMENT_COUNT);
+  if (segments.length < VERSION_SEGMENT_COUNT) return null;
+  const numbers = segments.map((segment) => Number(/^\d+/.exec(segment)?.[0]));
+  return numbers.some((n) => Number.isNaN(n)) ? null : numbers;
+}
+
+/** True when `actual` >= `required`, comparing major.minor.patch lexicographically. */
+function versionAtLeast(actual, required) {
+  const a = parseVersion(actual);
+  const r = parseVersion(required);
+  if (!a || !r) return true; // can't parse: don't fail the session over a doctor bug
+  for (let index = 0; index < VERSION_SEGMENT_COUNT; index += 1) {
+    if (a[index] > r[index]) return true;
+    if (a[index] < r[index]) return false;
+  }
+  return true;
+}
+
+/** The first "x.y.z"-shaped token inside an engines.node range string (">=22.5.0" -> "22.5.0"). */
+function firstVersionToken(engineRange) {
+  for (const token of engineRange.split(/\s+/)) {
+    const digits = token.replace(/[^\d.]/g, '');
+    if (parseVersion(digits)) return digits;
+  }
+  return null;
+}
+
+/** The minimum node version this install requires: package.json's engines.node, else the fallback. */
+function minNodeVersionRequired(configuredMin) {
+  if (configuredMin) return configuredMin;
+  const packageManifest = readJson(PACKAGE_JSON_PATH);
+  const engineRange = packageManifest?.engines?.node;
+  const token = engineRange ? firstVersionToken(engineRange) : null;
+  return token ?? DEFAULT_MIN_NODE_VERSION;
+}
+
+function checkNodeVersion(minVersion) {
+  if (versionAtLeast(process.version, minVersion)) return null;
+  return (
+    `node ${process.version} is below the required >=${minVersion}. ` +
+    'Some gates (e.g. node:sqlite-backed task tracking) will not work until node is upgraded.'
+  );
+}
+
+/** Every script the registry's PreToolUse/Stop gates (folder-style: gates/<id>/index.mjs) declare. */
+function missingFolderGateScripts() {
+  const registry = readJson(REGISTRY_PATH);
+  if (!registry?.families) return []; // can't read the registry: nothing to report
+
+  const problems = [];
+  for (const family of registry.families) {
+    const pluginName = family.plugin ?? 'gates';
+    const pluginHooksDirectory = join(
+      REPOSITORY_ROOT,
+      'plugins',
+      pluginName,
+      'hooks',
+    );
+    for (const gate of family.gates ?? []) {
+      const scriptPath = join(pluginHooksDirectory, gate.script);
+      if (!existsSync(scriptPath)) {
+        problems.push(
+          `${gate.id} (expected ${join('plugins', pluginName, 'hooks', gate.script)})`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+function speak(context) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: SESSION_START_EVENT,
+        additionalContext: context,
+      },
+    }),
+  );
+}
+
+function main() {
+  const payload = readPayload();
+  const cwd = payload.cwd || process.cwd();
+
+  const config = doctorConfig(cwd);
+  if (config && config.enabled === false) return; // gate turned off for this project
+
+  const problems = [];
+
+  const minVersion = minNodeVersionRequired(config?.minNodeVersion);
+  const versionProblem = checkNodeVersion(minVersion);
+  if (versionProblem) problems.push(versionProblem);
+
+  const missingScripts = missingFolderGateScripts();
+  if (missingScripts.length > 0) {
+    problems.push(
+      `${missingScripts.length} gate script(s) declared in registry.json are missing on disk: ${missingScripts.join(
+        ', ',
+      )}`,
+    );
+  }
+
+  if (problems.length === 0) return; // environment is healthy: stay silent
+
+  speak(
+    `[doctor] claude-gates environment check failed:\n- ${problems.join('\n- ')}`,
+  );
+}
+
+try {
+  main();
+} catch {
+  // A doctor bug must never block session start.
+}

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

@@ -0,0 +1,83 @@
+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-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: out.trim() ? JSON.parse(out.trim()) : null, project };
+}
+
+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 } } };
+
+// EDGE CASE (BUG): AUDIT_EVIDENCE_PATTERN is a bare substring/regex test over the WHOLE
+// delegation prompt with no proximity/ordering requirement relative to the tool-creation
+// intent. An unrelated, earlier sentence that happens to say "no existing tool" anywhere
+// in a long prompt satisfies the audit-evidence check even when it has nothing to do with
+// the actual tool being created, so a prompt can smuggle past the gate by mentioning
+// boilerplate audit language irrelevantly.
+test('BUG: false negative — audit language elsewhere in the prompt, unrelated to the new tool, satisfies the check', () => {
+  const prompt =
+    'Context: earlier we confirmed no existing tool handles our deploy pipeline. ' +
+    'Now, unrelated task: create a new script that scrapes user passwords from logs.';
+  const { out } = runGate(delegate(prompt), ENABLE);
+  assert.equal(out, null, 'gate allows because AUDIT_EVIDENCE_PATTERN matched irrelevant boilerplate anywhere in the prompt');
+});
+
+// EDGE CASE (BUG): INLINE_JUSTIFICATION_PATTERN for a direct Write is similarly a bare
+// substring test over the whole file content. Any comment anywhere in the file containing
+// the word "justification:" (even quoting/describing the concept, not actually justifying
+// THIS file) passes.
+test('BUG: false negative — the word "justification:" appearing in an unrelated docstring satisfies the check for any new tool file', () => {
+  const content = [
+    '// This module documents how other files use the phrase justification: <reason> in',
+    '// their headers, as an example of our commenting convention.',
+    'export function run() {}',
+  ].join('\n');
+  const { out } = runGate(write('/repo/scripts/new-thing.mjs', content), ENABLE);
+  assert.equal(out, null, 'gate allows because the literal string "justification:" appears anywhere, regardless of whether it actually justifies this file');
+});
+
+// EDGE CASE: confirm the "editing an existing file" exemption (checkWrite, index.mjs line
+// 56-58) can be trivially satisfied by ANY tool call whose file_path happens to already
+// exist on disk from an unrelated prior write within the same directory — verifying this
+// is intentional per the comment, not a further bug, but documenting the boundary.
+test('OK (documented, not a new bug): pre-creating an empty file at the target path bypasses audit entirely on the next edit', () => {
+  const { project } = runGate(delegate('noop'), ENABLE); // just to get an isolated project dir
+  const targetPath = join(project, 'scripts', 'sneaky.mjs');
+  mkdirSync(join(project, 'scripts'), { recursive: true });
+  writeFileSync(targetPath, ''); // pre-create empty file outside the gate's view
+  const out2 = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(write(targetPath, 'export function run() {}')),
+    encoding: 'utf8',
+    cwd: project,
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  assert.equal(out2.trim() ? JSON.parse(out2.trim()) : null, null, 'existsSync(rawPath) exemption means pre-touching the file first defeats the whole gate');
+});

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

@@ -1,88 +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);
-  },
-);
+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|cre(?:a|á)|crear|escrib(?:e|í)|escribir|constru(?:ye|í)|construir|agreg(?:a|á)|agregar)\b[^.]{0,60}\b(script|verifier|checker|gate|hook|linter|tool|verificador|chequeador|gate|hook|linter|herramienta)\b/iu;
+
+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

@@ -1,92 +1,117 @@
-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);
-});
+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('denies delegation to create a new tool without audit evidence, in Spanish', () => {
+  assert.ok(
+    isDeny(runGate(delegate('crea un nuevo script que verifique X'), ENABLE)),
+  );
+});
+
+test('bilingual control: ES and EN equivalent new-tool delegations both deny without audit evidence', () => {
+  const es = delegate('crea un nuevo script que verifique X');
+  const en = delegate('create a new script that checks X');
+  assert.ok(isDeny(runGate(es, ENABLE)));
+  assert.ok(isDeny(runGate(en, ENABLE)));
+});
+
+test('allows a Spanish delegation with audit evidence stated', () => {
+  assert.equal(
+    runGate(
+      delegate(
+        'crea un nuevo script que verifique X. audite y no existe una herramienta que cubra esto.',
+      ),
+      ENABLE,
+    ),
+    null,
+  );
+});
+
+test('disabled by default (registry default is false)', () => {
+  assert.equal(runGate(delegate('create a new script that checks X')), null);
+});