@devrik-tools/claude-gates 0.8.0 → 1.0.0

package/plugins/gates/hooks/gates/require-monitor/index.mjs

@@ -0,0 +1,126 @@
+// require-monitor — enforces that every background command has an associated Monitor.
+// Two-phase enforcement:
+//   1. PreToolUse on shell: a command with run_in_background: true MUST carry the marker
+//      MONITOR-PLANNED: <reason>. Without it, the background is denied.
+//   2. PreToolUse on execution+monitor: if the session has pending unmonitored backgrounds
+//      and the current tool is NOT Monitor, deny — forcing the agent to create a Monitor
+//      before doing anything else. When the current tool IS Monitor, the pending background
+//      is cleared.
+//
+// The marker is deterministic: no model judgment required. The pending-check is deterministic
+// too: state is on disk, the check is a read + compare, and the deny is unconditional.
+
+import {
+  deny,
+  runGate,
+  shellCommandOf,
+  toolInGroups,
+} from '../../lib/hook-io.mjs';
+import {
+  readSessionState,
+  writeSessionState,
+} from '../../lib/session-state.mjs';
+
+const GATE_ID = 'require-monitor';
+const CONFIG_KEY = 'requireMonitorForBackground';
+
+const DEFAULT_MARKER = 'MONITOR-PLANNED:';
+const MARKER_REASON_PATTERN = /\S\s\S/;
+const MAX_PENDING = 20;
+const MAX_COMMAND_PREVIEW_LENGTH = 200;
+
+function hasMarker(command, marker) {
+  if (!marker) return false;
+  const markerIndex = command.indexOf(marker);
+  if (markerIndex === -1) return false;
+  const afterMarker = command.slice(markerIndex + marker.length);
+  return MARKER_REASON_PATTERN.test(afterMarker);
+}
+
+function pendingBackgrounds(state) {
+  return Array.isArray(state.pending) ? state.pending : [];
+}
+
+function addPending(state, entry) {
+  const pending = [...pendingBackgrounds(state), entry].slice(-MAX_PENDING);
+  return { ...state, pending };
+}
+
+function clearOldestPending(state) {
+  const pending = pendingBackgrounds(state);
+  if (pending.length === 0) return state;
+  return { ...state, pending: pending.slice(1) };
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      monitorPlannedMarker: DEFAULT_MARKER,
+    },
+  },
+  ({ toolName, toolInput, sessionId, parameters, cwd }) => {
+    const isShell = toolInGroups(toolName, ['shell']);
+    const isMonitor = toolInGroups(toolName, ['monitor']);
+    const isExecution = toolInGroups(toolName, ['execution']);
+
+    if (!isShell && !isMonitor && !isExecution) return;
+
+    const stateOptions = { cwd };
+    const state = readSessionState(GATE_ID, sessionId, {}, stateOptions);
+    const marker = String(parameters.monitorPlannedMarker ?? DEFAULT_MARKER);
+
+    // Phase 2: if Monitor tool, clear oldest pending and allow.
+    if (isMonitor) {
+      const pending = pendingBackgrounds(state);
+      if (pending.length > 0) {
+        writeSessionState(
+          GATE_ID,
+          sessionId,
+          clearOldestPending(state),
+          stateOptions,
+        );
+      }
+      return;
+    }
+
+    // Phase 1: shell with run_in_background requires the marker.
+    if (isShell && toolInput.run_in_background === true) {
+      const command = shellCommandOf(toolInput);
+      if (!hasMarker(command, marker)) {
+        deny(
+          CONFIG_KEY,
+          `A background command MUST declare its Monitor plan. Add "${marker} <what the ` +
+            'Monitor will watch for>" to the command. Every background process needs a ' +
+            'Monitor — an unmonitored background is invisible work that can hang or fail ' +
+            'silently. The marker is a commitment to create a Monitor immediately after.',
+        );
+      }
+      writeSessionState(
+        GATE_ID,
+        sessionId,
+        addPending(state, {
+          command: command.slice(0, MAX_COMMAND_PREVIEW_LENGTH),
+          startedAt: Date.now(),
+        }),
+        stateOptions,
+      );
+      return;
+    }
+
+    // Phase 2: any execution/shell tool while backgrounds are unmonitored.
+    const pending = pendingBackgrounds(state);
+    if (pending.length > 0) {
+      const oldest = pending[0];
+      deny(
+        CONFIG_KEY,
+        `There are ${pending.length} background command(s) without a Monitor. Create a ` +
+          `Monitor for the pending background before doing anything else. Oldest pending: ` +
+          `"${oldest.command ?? '(unknown)'}". Use the Monitor tool to observe it, then ` +
+          'proceed with your next action.',
+      );
+    }
+  },
+);

package/plugins/gates/hooks/gates/require-task-split/index.mjs

@@ -0,0 +1,88 @@
+// require-task-split — denies writes and execution when the active task is too large
+// to implement without sub-tasks. Deterministic: reads active.json, checks size and
+// children count, denies unconditionally when the criteria are not met.
+//
+// Inspired by the Depth Tree method (unlazy): each sub-task must own specific files
+// (OWNS), carry its own verification gate, and be independently completable. If the
+// task's scope is ambiguous or the description is too vague to split confidently, the
+// model must ask the user to clarify before registering sub-tasks.
+//
+// Sizes that require splitting: medium, large, unspecified (anything that is not
+// explicitly small or trivial). A task that already has sub-tasks (children with
+// matching parentId) passes. A project with no tasks also passes (nothing to enforce).
+
+import { join } from 'node:path';
+import { projectRootOf, readJsonOrNull } from '../../lib/config.mjs';
+import { deny, runGate, toolInGroups } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'require-task-split';
+const CONFIG_KEY = 'requireTaskSplitBeforeImplementing';
+
+const ACTIVE_TASKS_FILE = join('.ai', 'tasks', 'active.json');
+const SIZES_EXEMPT_FROM_SPLIT = new Set(['small', 'trivial']);
+const IMPLEMENTATION_STATUSES = new Set(['open', 'in_forge']);
+
+function readActiveTasks(root) {
+  const parsed = readJsonOrNull(join(root, ACTIVE_TASKS_FILE));
+  const tasks = Array.isArray(parsed?.tasks) ? parsed.tasks : [];
+  return tasks.filter((task) => task && typeof task === 'object');
+}
+
+function hasChildren(tasks, parentId) {
+  return tasks.some((task) => task.parentId === parentId);
+}
+
+function unsplitLargeTasks(tasks) {
+  return tasks.filter((task) => {
+    if (!IMPLEMENTATION_STATUSES.has(task.status)) return false;
+    if (task.parentId) return false;
+    if (SIZES_EXEMPT_FROM_SPLIT.has(task.size)) return false;
+    return !hasChildren(tasks, task.id);
+  });
+}
+
+const DENY_MESSAGE_TEMPLATE = (count, lines) =>
+  `${count} task(s) need splitting before implementation:\n${lines}\n\n` +
+  'BEFORE SPLITTING — check scope clarity:\n' +
+  '  If the task description is vague or you are unsure what files/modules are affected,\n' +
+  '  ASK THE USER to clarify the scope before registering sub-tasks. Do not guess.\n\n' +
+  'SPLITTING RULES (Depth Tree method):\n' +
+  '  1. Each sub-task must be small and independently verifiable\n' +
+  '  2. Each sub-task should OWN specific files — no two sub-tasks modify the same file\n' +
+  '  3. Each sub-task carries its own verification gate (--verify-command or --verify-path)\n' +
+  '  4. Split at natural boundaries: one module, one function, one test file\n' +
+  '  5. If the task has unclear scope, ask the user — do not split blindly\n\n' +
+  'Register sub-tasks:\n' +
+  '  claude-gates task add "<what this sub-task delivers>" --parent <parent-id> --size small \\\n' +
+  '    --verify-command "<check>" [--verify-expect <text>] \\\n' +
+  '    --description "OWNS: <file1>, <file2>"\n\n' +
+  'Only after sub-tasks are registered can you proceed with writes and execution.';
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {},
+  },
+  ({ toolName, cwd }) => {
+    const isWrite = toolInGroups(toolName, ['write']);
+    const isExecution = toolInGroups(toolName, ['execution']);
+    if (!isWrite && !isExecution) return;
+
+    const root = projectRootOf(cwd) ?? cwd;
+    const tasks = readActiveTasks(root);
+    if (tasks.length === 0) return;
+
+    const unsplit = unsplitLargeTasks(tasks);
+    if (unsplit.length === 0) return;
+
+    const lines = unsplit
+      .map(
+        (task) =>
+          `  - [${task.status}] ${task.id}: ${task.title} (size: ${task.size ?? 'unspecified'})`,
+      )
+      .join('\n');
+    deny(CONFIG_KEY, DENY_MESSAGE_TEMPLATE(unsplit.length, lines));
+  },
+);

package/plugins/gates/hooks/gates/skill-first/index.mjs

@@ -0,0 +1,138 @@
+// skill-first — the READ half of the capability pair, and the deterministic counterpart to
+// capability-map. capability-map tells the model what it has; nothing made the model act on
+// it. Its catalog is injected at UserPromptSubmit, throttled, carrying an advisory line —
+// so a turn that writes forty files gets one soft reminder at the top and none at the
+// moment each action is actually taken. This gate closes that half: before an action that
+// a listed skill plausibly covers, it requires evidence the question was asked.
+//
+// The pair mirrors reuse-before-build/tool-map: one shared definition of the catalog
+// (lib/capabilities.mjs), a write half that records, a read half that judges.
+//
+// Deliberately narrow, because relevance here is a lexical heuristic and a false deny is
+// expensive. It only speaks when ALL of these hold:
+//   · the action carries enough text to judge (`minTextChars`);
+//   · a skill is plausibly relevant — the action NAMES it, or shares `minTokenOverlap`
+//     distinctive tokens with its description;
+//   · the session shows no sign the question was already asked.
+// Everything else is the silent path.
+//
+// Three ways to clear it, all cheap and none requiring filesystem exploration:
+//   1. invoke the relevant skill (the Skill tool; recorded by this gate's track.mjs);
+//   2. state the decision in the content/prompt ("using the dataviz skill", "no skill
+//      covers this") — the same escape-hatch shape reuse-before-build uses;
+//   3. turn the gate off for the project.
+//
+// Off by default: it rests on a heuristic, and a gate that guesses must be opted into.
+
+import {
+  entriesForKind,
+  hasSkillAuditEvidence,
+  relevantCapabilities,
+} from '../../lib/capabilities.mjs';
+import { projectRootOf } from '../../lib/config.mjs';
+import {
+  delegationPromptOf,
+  deny,
+  runGate,
+  shellCommandOf,
+  toolInGroups,
+  writtenContentOf,
+  writtenPathOf,
+} from '../../lib/hook-io.mjs';
+import { readSessionState } from '../../lib/session-state.mjs';
+
+export const GATE_ID = 'skill-first';
+export const CONFIG_KEY = 'requireSkillCheckBeforeActing';
+
+// How many of the shared tokens the deny message shows: enough to make the match
+// legible, few enough to keep the line short.
+const SHOWN_SHARED_TOKENS = 4;
+
+const DEFAULT_PARAMS = {
+  kinds: ['skills'],
+  minTokenOverlap: 3,
+  maxMatches: 3,
+  minTextChars: 40,
+  extraSkillsDirs: [],
+  extraAgentsDirs: [],
+  extraCommandsDirs: [],
+};
+
+/** The text that describes what this action is about to do, per tool shape. */
+function actionTextOf(toolName, toolInput) {
+  if (toolInGroups(toolName, ['delegation']))
+    return delegationPromptOf(toolInput);
+  if (toolInGroups(toolName, ['write'])) {
+    return `${writtenPathOf(toolInput)}\n${writtenContentOf(toolInput)}`;
+  }
+  if (toolInGroups(toolName, ['shell'])) return shellCommandOf(toolInput);
+  return '';
+}
+
+function catalogEntries(root, parameters) {
+  const entries = [];
+  for (const kind of parameters.kinds) {
+    entries.push(...entriesForKind(String(kind), root, parameters));
+  }
+  return entries;
+}
+
+/** Skills this session already loaded, as recorded by track.mjs. */
+function invokedSkills(sessionId, cwd) {
+  const state = readSessionState(GATE_ID, sessionId, {}, { cwd });
+  const names = Array.isArray(state.skillsInvoked) ? state.skillsInvoked : [];
+  return new Set(names.map((name) => String(name).toLowerCase()));
+}
+
+function describeMatch(match) {
+  if (match.named) return `${match.name} (named in this action)`;
+  const shared = match.shared.slice(0, SHOWN_SHARED_TOKENS).join(', ');
+  return `${match.name} (matches on: ${shared})`;
+}
+
+function denyMessage(matches, isDelegation) {
+  const target = isDelegation ? "this delegation's prompt" : 'the content';
+  return (
+    `Blocked: ${matches.length} available skill(s) look relevant to this action, and nothing ` +
+    `shows they were considered:\n  ${matches.map(describeMatch).join('\n  ')}\n` +
+    'Pick ONE, then retry the same action:\n' +
+    `  1. The skill covers this — load it (the Skill tool) and follow it instead of improvising.\n` +
+    `  2. It does not fit — add ONE line to ${target} saying so, e.g. "no skill covers this", ` +
+    'or name the one you are following, e.g. "using the <name> skill".\n' +
+    'No filesystem exploration is required: the catalog was read for you, and the audit is ' +
+    'one sentence.'
+  );
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: DEFAULT_PARAMS,
+  },
+  ({ toolName, toolInput, sessionId, parameters, cwd }) => {
+    const isDelegation = toolInGroups(toolName, ['delegation']);
+    if (!isDelegation && !toolInGroups(toolName, ['execution'])) return;
+
+    const text = actionTextOf(toolName, toolInput);
+    if (text.trim().length < parameters.minTextChars) return;
+    if (hasSkillAuditEvidence(text)) return;
+
+    const root = projectRootOf(cwd) ?? cwd;
+    const matches = relevantCapabilities(
+      text,
+      catalogEntries(root, parameters),
+      {
+        minTokenOverlap: parameters.minTokenOverlap,
+        maxMatches: parameters.maxMatches,
+      },
+    );
+    if (matches.length === 0) return;
+
+    const invoked = invokedSkills(sessionId, cwd);
+    if (matches.some((match) => invoked.has(match.name.toLowerCase()))) return;
+
+    deny(CONFIG_KEY, denyMessage(matches, isDelegation));
+  },
+);

package/plugins/gates/hooks/gates/skill-first/track.mjs

@@ -0,0 +1,66 @@
+// skill-first/track.mjs — PostToolUse. Records which skills this session actually loaded,
+// so the gate can tell "the model reached for a skill" from "the model never asked". This
+// is the strongest of the three ways to clear skill-first, and the only one that is not
+// the model's own assertion: it is the runtime observing a real Skill call.
+//
+// Never blocks and never speaks; a failure here only costs the session that one signal.
+
+import {
+  allow,
+  mcpActionSegment,
+  readHookPayload,
+  sessionIdOf,
+  toolInGroups,
+  toolInputOf,
+  toolNameOf,
+} from '../../lib/hook-io.mjs';
+import { updateSessionState } from '../../lib/session-state.mjs';
+
+const GATE_ID = 'skill-first';
+const MAX_ENTRIES = 60;
+const MAX_ENTRY_LENGTH = 120;
+
+const NAME_FIELDS = ['skill', 'skill_name', 'skillName', 'name', 'id'];
+
+/** The skill a Skill-style call names, across native and MCP field shapes. */
+function skillNameOf(toolInput, toolName) {
+  for (const field of NAME_FIELDS) {
+    const value = toolInput?.[field];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  // An MCP server may encode the skill in the action segment instead of an argument.
+  return mcpActionSegment(String(toolName)) || null;
+}
+
+// A plugin skill arrives as `plugin:skill`, a directory-scoped one as `path/to:skill`;
+// the catalog knows it by the bare name, so both spellings are recorded.
+function spellingsOf(name) {
+  const bare = name.includes(':') ? name.split(':').at(-1) : name;
+  return [...new Set([name, bare])]
+    .filter(Boolean)
+    .map((entry) => entry.slice(0, MAX_ENTRY_LENGTH));
+}
+
+function main() {
+  const rawPayload = readHookPayload();
+  if (rawPayload === null) allow();
+  const toolName = toolNameOf(rawPayload) ?? '';
+  if (!toolInGroups(toolName, ['skill'])) allow();
+
+  const name = skillNameOf(toolInputOf(rawPayload), toolName);
+  if (!name) allow();
+
+  updateSessionState(GATE_ID, sessionIdOf(rawPayload), {}, (state) => ({
+    ...state,
+    skillsInvoked: [...(state.skillsInvoked ?? []), ...spellingsOf(name)].slice(
+      -MAX_ENTRIES,
+    ),
+  }));
+  allow();
+}
+
+try {
+  main();
+} catch {
+  allow();
+}

package/plugins/gates/hooks/hooks.json

@@ -51,6 +51,16 @@
           }
         ]
       },
+      {
+        "matcher": "Bash|run_command|PowerShell|Write|Edit|MultiEdit|NotebookEdit|write_to_file|replace_file_content|mcp__ide__executeCode|Monitor|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gates/require-monitor/index.mjs\"",
+            "timeout": 30
+          }
+        ]
+      },
       {
         "matcher": "Agent|Task|invoke_subagent|mcp__.*",
         "hooks": [
@@ -331,6 +341,16 @@
           }
         ]
       },
+      {
+        "matcher": "Bash|run_command|PowerShell|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gates/no-trivial-scripts/index.mjs\"",
+            "timeout": 30
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit|MultiEdit|NotebookEdit|write_to_file|replace_file_content|Agent|Task|invoke_subagent|mcp__.*",
         "hooks": [
@@ -351,6 +371,16 @@
           }
         ]
       },
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|write_to_file|replace_file_content|Bash|run_command|PowerShell|mcp__ide__executeCode|Agent|Task|invoke_subagent|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gates/skill-first/index.mjs\"",
+            "timeout": 30
+          }
+        ]
+      },
       {
         "matcher": "WebSearch|WebFetch|mcp__.*",
         "hooks": [
@@ -362,7 +392,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit|MultiEdit|NotebookEdit|write_to_file|replace_file_content|mcp__.*",
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|write_to_file|replace_file_content|Bash|run_command|PowerShell|mcp__.*",
         "hooks": [
           {
             "type": "command",
@@ -390,9 +420,39 @@
             "timeout": 30
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|write_to_file|replace_file_content|Bash|run_command|PowerShell|mcp__ide__executeCode|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gates/require-task-split/index.mjs\"",
+            "timeout": 30
+          }
+        ]
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Agent|Task|invoke_subagent|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gates/circuit-breaker/track.mjs\"",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "Skill|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gates/skill-first/track.mjs\"",
+            "timeout": 30
+          }
+        ]
+      },
       {
         "matcher": "WebSearch|WebFetch|mcp__.*",
         "hooks": [