@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/plugins/gates/hooks/gates/diagnosis-before-patch/diagnosis-before-patch.edge.test.mjs

@@ -0,0 +1,68 @@
+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(), 'diagnosis-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;
+}
+
+function isWarn(result) {
+  return result?.hookSpecificOutput?.additionalContext !== undefined;
+}
+
+// FIXED: extractText() now gates on toolInGroups(toolName, ['write']) and reads through
+// writtenContentOf() (lib/hook-io.mjs), which covers NotebookEdit's new_source field.
+test('FIXED: NotebookEdit changing a timeout value is detected', () => {
+  const payload = {
+    tool_name: 'NotebookEdit',
+    tool_input: {
+      notebook_path: '/repo/notebook.ipynb',
+      cell_id: 'abc',
+      new_source: 'REQUEST_TIMEOUT_MS = 30000',
+      cell_type: 'code',
+    },
+  };
+  assert.ok(isWarn(runGate(payload)), 'gate now detects a timeout change via NotebookEdit');
+});
+
+// FIXED: replace_file_content is recognized by toolInGroups(toolName, ['write']) (native
+// name in TOOL_GROUPS.write) and its `content` field is read through writtenContentOf().
+test('FIXED: replace_file_content changing a timeout value is detected', () => {
+  const payload = {
+    tool_name: 'replace_file_content',
+    tool_input: {
+      file_path: '/repo/src/config.js',
+      content: 'const REQUEST_TIMEOUT_MS = 30000;',
+    },
+  };
+  assert.ok(isWarn(runGate(payload)), 'gate now detects a timeout change via replace_file_content');
+});
+
+// EDGE CASE: confirm severity really is warn-only, never deny, for a real match (per WARN
+// family classification). This should hold given index.mjs only calls warn(), never deny.
+test('OK: matched content produces warn, never deny', () => {
+  const result = runGate({
+    tool_name: 'Write',
+    tool_input: { file_path: '/repo/src/config.js', content: 'const REQUEST_TIMEOUT_MS = 30000;' },
+  });
+  assert.ok(isWarn(result));
+  assert.notEqual(result?.hookSpecificOutput?.permissionDecision, 'deny');
+});

package/plugins/gates/hooks/gates/diagnosis-before-patch/index.mjs

@@ -1,49 +1,43 @@
-import { runGate, warn } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'diagnosis-before-patch';
-const CONFIG_KEY = 'warnTimeoutChangeWithoutDiagnosis';
-
-const DEFAULT_TIMEOUT_PATTERNS = [
-  String.raw`\b[A-Z_]*TIMEOUT[A-Z_]*\s*[:=]\s*['"]?\d`,
-  String.raw`\b[A-Z_]*DEADLINE[A-Z_]*\s*[:=]\s*['"]?\d`,
-  String.raw`\b[A-Z_]*IDLE[A-Z_]*\s*[:=]\s*['"]?\d`,
-  String.raw`\b(max_?retry|retries|backoff)\b\s*[:=]\s*['"]?\d`,
-  String.raw`\b(query_?timeout|hard_?deadline)\b`,
-];
-
-function extractText(toolName, toolInput) {
-  if (toolName === 'Write') return String(toolInput?.content ?? '');
-  if (toolName === 'Edit') return String(toolInput?.new_string ?? '');
-  if (toolName === 'MultiEdit' && Array.isArray(toolInput?.edits)) {
-    return toolInput.edits
-      .map((edit) => String(edit?.new_string ?? ''))
-      .join('\n');
-  }
-  return '';
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: true,
-    defaultParams: {
-      timeoutPatterns: DEFAULT_TIMEOUT_PATTERNS,
-    },
-  },
-  ({ toolName, toolInput, parameters }) => {
-    const text = extractText(toolName, toolInput);
-    if (!text) return;
-
-    const patterns = parameters.timeoutPatterns.map(
-      (source) => new RegExp(source, 'i'),
-    );
-    const touchesTimeout = patterns.some((pattern) => pattern.test(text));
-    if (!touchesTimeout) return;
-
-    warn(
-      GATE_ID,
-      'Diagnosis before patch: you are adjusting a timeout/deadline/retry value. Before changing a value to fix a symptom ("X is slow/fails"), confirm you read the evidence that proves the cause (a log line from the failing provider/process, not a hypothesis). A timeout should measure inactivity, not total time: a process that is progressing should not be cut off.',
-    );
-  },
-);
+import { runGate, warn, toolInGroups, writtenContentOf } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'diagnosis-before-patch';
+const CONFIG_KEY = 'warnTimeoutChangeWithoutDiagnosis';
+
+const DEFAULT_TIMEOUT_PATTERNS = [
+  String.raw`\b[A-Z_]*TIMEOUT[A-Z_]*\s*[:=]\s*['"]?\d`,
+  String.raw`\b[A-Z_]*DEADLINE[A-Z_]*\s*[:=]\s*['"]?\d`,
+  String.raw`\b[A-Z_]*IDLE[A-Z_]*\s*[:=]\s*['"]?\d`,
+  String.raw`\b(max_?retry|retries|backoff)\b\s*[:=]\s*['"]?\d`,
+  String.raw`\b(query_?timeout|hard_?deadline)\b`,
+];
+
+function extractText(toolName, toolInput) {
+  if (!toolInGroups(toolName, ['write'])) return '';
+  return writtenContentOf(toolInput);
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      timeoutPatterns: DEFAULT_TIMEOUT_PATTERNS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const text = extractText(toolName, toolInput);
+    if (!text) return;
+
+    const patterns = parameters.timeoutPatterns.map(
+      (source) => new RegExp(source, 'i'),
+    );
+    const touchesTimeout = patterns.some((pattern) => pattern.test(text));
+    if (!touchesTimeout) return;
+
+    warn(
+      GATE_ID,
+      'Diagnosis before patch: you are adjusting a timeout/deadline/retry value. Before changing a value to fix a symptom ("X is slow/fails"), confirm you read the evidence that proves the cause (a log line from the failing provider/process, not a hypothesis). A timeout should measure inactivity, not total time: a process that is progressing should not be cut off.',
+    );
+  },
+);

package/plugins/gates/hooks/gates/feature-catalog/edge.edge.test.mjs

@@ -0,0 +1,83 @@
+// Edge-case probes for feature-catalog. Previously an Edit (new_string) writing
+// status:done or an in_progress overrun to the catalog bypassed this gate because
+// writeContentFrom() read only CodeContent/ReplacementContent/content, never
+// new_string. Migrated to writtenContentOf()/writtenPathOf() (hook-io.mjs), which read
+// through every known field shape, so these are now caught the same as a Write.
+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) {
+  const project = mkdtempSync(join(tmpdir(), 'feature-catalog-edge-'));
+  mkdirSync(join(project, '.git'));
+  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;
+}
+
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+test('FIXED: an Edit (new_string) writing status:done to the catalog is now detected', () => {
+  const payload = {
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: 'feature_list.json',
+      old_string: 'x',
+      new_string: JSON.stringify({
+        features: [{ name: 'checkout', status: 'done' }],
+      }),
+    },
+  };
+  assert.ok(
+    isDeny(runGate(payload)),
+    'writtenContentOf reads new_string and catches status:done via Edit',
+  );
+});
+
+test('FIXED: an Edit (new_string) exceeding maxInProgress is now detected', () => {
+  const payload = {
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: 'feature_list.json',
+      old_string: 'x',
+      new_string: JSON.stringify({
+        features: [
+          { name: 'a', status: 'in_progress' },
+          { name: 'b', status: 'in_progress' },
+        ],
+      }),
+    },
+  };
+  assert.ok(
+    isDeny(runGate(payload)),
+    'writtenContentOf reads new_string and catches the maxInProgress overrun via Edit',
+  );
+});
+
+test('OK: the equivalent Write-tool payload IS caught (control)', () => {
+  const payload = {
+    tool_name: 'Write',
+    tool_input: {
+      file_path: 'feature_list.json',
+      content: JSON.stringify({
+        features: [{ name: 'checkout', status: 'done' }],
+      }),
+    },
+  };
+  assert.ok(
+    isDeny(runGate(payload)),
+    'control failed: Write-tool status:done should be denied',
+  );
+});

package/plugins/gates/hooks/gates/feature-catalog/index.mjs

@@ -1,100 +1,83 @@
-// feature-catalog — enforces the machine-readable feature catalog's own invariants on
-// a write to that file: at most one feature `in_progress` at a time, and `done` is
-// never written directly (only a review/QA process closes a feature). Migrated from
-// ~/.claude/hooks/guard-feature-catalog.mjs.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   catalogFileName   basename of the catalog file this gate watches for (default
-//                      feature_list.json). A write to any other file is ignored.
-//   maxInProgress     how many features may be `in_progress` simultaneously.
-// The defaults live here, in the source, so a project reads them and knows exactly what
-// its override replaces.
-//
-// ── Auto-off when the project never adopted the catalog ────────────────────────────
-// This gate only inspects the CONTENT being written to a file named `catalogFileName`.
-// A project that never uses that file never triggers it — there is nothing to disable
-// separately, the check is inert by construction rather than by a discovery pass.
-//
-// ── What is NOT configurable (base, non-negotiable) ─────────────────────────────────
-// Writing `status: done` directly is always denied, regardless of `maxInProgress`: only
-// a review/QA subagent or a validated automated process may close a feature, and this
-// gate has no way to tell who is writing, so it blocks the write itself.
-
-import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'feature-catalog';
-const CONFIG_KEY = 'requireFeatureCatalog';
-
-const WRITE_TOOLS = new Set(TOOL_GROUPS.write);
-
-const DEFAULT_CATALOG_FILE_NAME = 'feature_list.json';
-const DEFAULT_MAX_IN_PROGRESS = 1;
-
-const DONE_STATUS_PATTERN = /"status"\s*:\s*"done"|status\s*:\s*['"]done['"]/i;
-const IN_PROGRESS_STATUS_PATTERN = /"status"\s*:\s*"in_progress"/g;
-
-/** The path a write tool targets, across the field names different tools use. */
-function writeTargetFrom(toolInput) {
-  return String(
-    toolInput.TargetFile ??
-      toolInput.target_file ??
-      toolInput.file_path ??
-      toolInput.path ??
-      '',
-  );
-}
-
-/** The content a write tool is about to write, across the field names tools use. */
-function writeContentFrom(toolInput) {
-  return String(
-    toolInput.CodeContent ??
-      toolInput.ReplacementContent ??
-      toolInput.content ??
-      '',
-  );
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: true,
-    defaultParams: {
-      catalogFileName: DEFAULT_CATALOG_FILE_NAME,
-      maxInProgress: DEFAULT_MAX_IN_PROGRESS,
-    },
-  },
-  ({ toolName, toolInput, parameters }) => {
-    if (!WRITE_TOOLS.has(toolName)) return;
-
-    const target = writeTargetFrom(toolInput);
-    const catalogFileName = String(
-      parameters.catalogFileName ?? DEFAULT_CATALOG_FILE_NAME,
-    );
-    if (!target.includes(catalogFileName)) return;
-
-    const content = writeContentFrom(toolInput);
-
-    // Base, non-negotiable: `done` is never written directly to the catalog.
-    if (DONE_STATUS_PATTERN.test(content)) {
-      deny(
-        GATE_ID,
-        `Writing 'status: done' directly to ${catalogFileName} is not allowed. ` +
-          'Only a review/QA subagent or a validated automated process may close a feature.',
-      );
-    }
-
-    const maxInProgress = Number(
-      parameters.maxInProgress ?? DEFAULT_MAX_IN_PROGRESS,
-    );
-    const inProgressCount = (content.match(IN_PROGRESS_STATUS_PATTERN) ?? [])
-      .length;
-    if (inProgressCount > maxInProgress) {
-      deny(
-        GATE_ID,
-        `${catalogFileName} would have ${inProgressCount} features 'in_progress'; ` +
-          `the maximum allowed is ${maxInProgress}.`,
-      );
-    }
-  },
-);
+// feature-catalog — enforces the machine-readable feature catalog's own invariants on
+// a write to that file: at most one feature `in_progress` at a time, and `done` is
+// never written directly (only a review/QA process closes a feature). Migrated from
+// ~/.claude/hooks/guard-feature-catalog.mjs.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   catalogFileName   basename of the catalog file this gate watches for (default
+//                      feature_list.json). A write to any other file is ignored.
+//   maxInProgress     how many features may be `in_progress` simultaneously.
+// The defaults live here, in the source, so a project reads them and knows exactly what
+// its override replaces.
+//
+// ── Auto-off when the project never adopted the catalog ────────────────────────────
+// This gate only inspects the CONTENT being written to a file named `catalogFileName`.
+// A project that never uses that file never triggers it — there is nothing to disable
+// separately, the check is inert by construction rather than by a discovery pass.
+//
+// ── What is NOT configurable (base, non-negotiable) ─────────────────────────────────
+// Writing `status: done` directly is always denied, regardless of `maxInProgress`: only
+// a review/QA subagent or a validated automated process may close a feature, and this
+// gate has no way to tell who is writing, so it blocks the write itself.
+
+import {
+  runGate,
+  deny,
+  toolInGroups,
+  writtenContentOf,
+  writtenPathOf,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'feature-catalog';
+const CONFIG_KEY = 'requireFeatureCatalog';
+
+const DEFAULT_CATALOG_FILE_NAME = 'feature_list.json';
+const DEFAULT_MAX_IN_PROGRESS = 1;
+
+const DONE_STATUS_PATTERN = /"status"\s*:\s*"done"|status\s*:\s*['"]done['"]/i;
+const IN_PROGRESS_STATUS_PATTERN = /"status"\s*:\s*"in_progress"/g;
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      catalogFileName: DEFAULT_CATALOG_FILE_NAME,
+      maxInProgress: DEFAULT_MAX_IN_PROGRESS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!toolInGroups(toolName, ['write'])) return;
+
+    const target = writtenPathOf(toolInput);
+    const catalogFileName = String(
+      parameters.catalogFileName ?? DEFAULT_CATALOG_FILE_NAME,
+    );
+    if (!target.includes(catalogFileName)) return;
+
+    const content = writtenContentOf(toolInput);
+
+    // Base, non-negotiable: `done` is never written directly to the catalog.
+    if (DONE_STATUS_PATTERN.test(content)) {
+      deny(
+        GATE_ID,
+        `Writing 'status: done' directly to ${catalogFileName} is not allowed. ` +
+          'Only a review/QA subagent or a validated automated process may close a feature.',
+      );
+    }
+
+    const maxInProgress = Number(
+      parameters.maxInProgress ?? DEFAULT_MAX_IN_PROGRESS,
+    );
+    const inProgressCount = (content.match(IN_PROGRESS_STATUS_PATTERN) ?? [])
+      .length;
+    if (inProgressCount > maxInProgress) {
+      deny(
+        GATE_ID,
+        `${catalogFileName} would have ${inProgressCount} features 'in_progress'; ` +
+          `the maximum allowed is ${maxInProgress}.`,
+      );
+    }
+  },
+);

package/plugins/gates/hooks/gates/force-parallel/index.mjs

@@ -0,0 +1,119 @@
+// force-parallel — nudges toward parallelizing independent delegations. WARN-only: it
+// never denies, because a PreToolUse hook sees one tool call at a time and has no way to
+// know whether the delegations it observed COULD have been sent together — only that they
+// arrived one after another.
+//
+// justification: no existing tool covers this. brief-before-delegate/intent-flow/risk-level
+// gate the CONTENT of a single delegation prompt; none of them look across delegations in
+// the same session to notice a sequential pattern.
+//
+// ── Honest limitation (read before trusting this gate) ──────────────────────────────
+// A PreToolUse hook fires once per tool call, synchronously, with no visibility into what
+// the model is "thinking" or whether independent work existed to batch. This gate can only
+// count consecutive delegation calls that land close together in wall-clock time and warn
+// after a threshold — it cannot prove they were independent, and it cannot force the model
+// to have sent them in one message (Claude Code's own turn structure decides that, not a
+// hook). Treat the warning as a nudge for the NEXT delegation, never as proof of a missed
+// opportunity on the ones already sent.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   sequentialThreshold      consecutive delegations (within the window) before warning.
+//   sequentialWindowMs       how close in time two delegations must land to count as the
+//                            same sequential run; a gap resets the count.
+//   sequentialJustifiedMarker  a marker token in the delegation prompt that escapes the
+//                            warning — a declared reason not to parallelize is a decision.
+// The defaults live here, in the source, so a project reads them and knows exactly what
+// its override replaces.
+//
+// ── State ─────────────────────────────────────────────────────────────────────────────
+// Per-session count + last-delegation timestamp, persisted at
+// os.tmpdir()/claude-gates/force-parallel/<sessionId>/state.json — process-local state
+// would not survive across the separate process each hook invocation spawns.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runGate, warn, toolInGroups, delegationPromptOf } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'force-parallel';
+const CONFIG_KEY = 'warnSequentialDelegations';
+
+const DELEGATION_GROUPS = ['delegation'];
+const DEFAULT_SEQUENTIAL_THRESHOLD = 3;
+const DEFAULT_SEQUENTIAL_WINDOW_MS = 120000;
+const DEFAULT_JUSTIFIED_MARKER = 'SEQUENTIAL-JUSTIFIED';
+
+const STATE_ROOT = join(tmpdir(), 'claude-gates', 'force-parallel');
+const STATE_FILE = 'state.json';
+const UNKNOWN_SESSION = 'unknown-session';
+
+function statePathFor(sessionId) {
+  const safeSessionId = String(sessionId || UNKNOWN_SESSION).replace(/[^\w-]/g, '_');
+  return join(STATE_ROOT, safeSessionId, STATE_FILE);
+}
+
+function readState(path) {
+  if (!existsSync(path)) return { count: 0, lastAt: 0 };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return {
+      count: Number(parsed.count) || 0,
+      lastAt: Number(parsed.lastAt) || 0,
+    };
+  } catch {
+    return { count: 0, lastAt: 0 };
+  }
+}
+
+function writeState(path, state) {
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, JSON.stringify(state), 'utf8');
+}
+
+const WARN_MESSAGE =
+  'This is the {count}th delegation sent one-by-one within {windowSeconds}s. If the ' +
+  'remaining work is independent, launch the next batch together in a single message ' +
+  '(multiple tool calls) instead of one delegation per turn. If this delegation ' +
+  'genuinely depends on a prior result, ignore this and mark the prompt with ' +
+  '"{marker}" to skip the warning next time.';
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      sequentialThreshold: DEFAULT_SEQUENTIAL_THRESHOLD,
+      sequentialWindowMs: DEFAULT_SEQUENTIAL_WINDOW_MS,
+      sequentialJustifiedMarker: DEFAULT_JUSTIFIED_MARKER,
+    },
+  },
+  ({ toolName, toolInput, sessionId, parameters }) => {
+    if (!toolInGroups(toolName, DELEGATION_GROUPS)) return;
+
+    const marker = parameters.sequentialJustifiedMarker ?? DEFAULT_JUSTIFIED_MARKER;
+    const prompt = delegationPromptOf(toolInput);
+    if (prompt.includes(marker)) return; // declared reason not to parallelize: no warning
+
+    const threshold = parameters.sequentialThreshold ?? DEFAULT_SEQUENTIAL_THRESHOLD;
+    const windowMs = parameters.sequentialWindowMs ?? DEFAULT_SEQUENTIAL_WINDOW_MS;
+
+    const statePath = statePathFor(sessionId);
+    const state = readState(statePath);
+    const now = Date.now();
+
+    const withinWindow = now - state.lastAt <= windowMs;
+    const nextCount = withinWindow ? state.count + 1 : 1;
+
+    writeState(statePath, { count: nextCount, lastAt: now });
+
+    if (nextCount < threshold) return;
+
+    warn(
+      GATE_ID,
+      WARN_MESSAGE.replace('{count}', String(nextCount))
+        .replace('{windowSeconds}', String(Math.round(windowMs / 1000)))
+        .replace('{marker}', marker),
+    );
+  },
+);

package/plugins/gates/hooks/gates/force-parallel/test.mjs

@@ -0,0 +1,88 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const GATE = join(dirname(fileURLToPath(import.meta.url)), 'index.mjs');
+const STATE_ROOT = join(tmpdir(), 'claude-gates', 'force-parallel');
+
+function delegationPayload(sessionId, prompt = 'do work') {
+  return {
+    tool_name: 'Task',
+    session_id: sessionId,
+    tool_input: { prompt },
+  };
+}
+
+function isWarn(result) {
+  return typeof result?.hookSpecificOutput?.additionalContext === 'string';
+}
+
+function runGate(project, payload) {
+  mkdirSync(join(project, '.git'), { recursive: true });
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  writeFileSync(
+    join(project, '.ai', 'config.json'),
+    JSON.stringify({ gates: { warnSequentialDelegations: { enabled: true } } }),
+  );
+  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;
+}
+
+test('3 sequential delegations in the same session: the 3rd warns', () => {
+  const project = mkdtempSync(join(tmpdir(), 'force-parallel-'));
+  const sessionId = `test-${randomUUID()}`;
+  rmSync(join(STATE_ROOT, sessionId), { recursive: true, force: true });
+
+  const first = runGate(project, delegationPayload(sessionId));
+  const second = runGate(project, delegationPayload(sessionId));
+  const third = runGate(project, delegationPayload(sessionId));
+
+  assert.equal(first, null, 'first delegation should not warn');
+  assert.equal(second, null, 'second delegation should not warn');
+  assert.ok(isWarn(third), 'third consecutive delegation should warn');
+  assert.match(third.hookSpecificOutput.additionalContext, /force-parallel/);
+
+  rmSync(join(STATE_ROOT, sessionId), { recursive: true, force: true });
+});
+
+test('a marked SEQUENTIAL-JUSTIFIED prompt never warns, even at count 3', () => {
+  const project = mkdtempSync(join(tmpdir(), 'force-parallel-'));
+  const sessionId = `test-${randomUUID()}`;
+  rmSync(join(STATE_ROOT, sessionId), { recursive: true, force: true });
+
+  runGate(project, delegationPayload(sessionId));
+  runGate(project, delegationPayload(sessionId));
+  const third = runGate(
+    project,
+    delegationPayload(sessionId, 'needs prior result SEQUENTIAL-JUSTIFIED'),
+  );
+
+  assert.equal(third, null);
+
+  rmSync(join(STATE_ROOT, sessionId), { recursive: true, force: true });
+});
+
+test('a non-delegation tool is never warned', () => {
+  const project = mkdtempSync(join(tmpdir(), 'force-parallel-'));
+  const sessionId = `test-${randomUUID()}`;
+  rmSync(join(STATE_ROOT, sessionId), { recursive: true, force: true });
+
+  const result = runGate(project, {
+    tool_name: 'Bash',
+    session_id: sessionId,
+    tool_input: { command: 'ls' },
+  });
+  assert.equal(result, null);
+
+  rmSync(join(STATE_ROOT, sessionId), { recursive: true, force: true });
+});