@devrik-tools/claude-gates 0.8.0 → 0.9.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/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": [
@@ -362,7 +382,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 +410,29 @@
             "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": "WebSearch|WebFetch|mcp__.*",
         "hooks": [

package/plugins/gates/hooks/lib/hook-io.mjs

@@ -58,6 +58,8 @@ export const TOOL_GROUPS = Object.freeze({
   ],
   // Research surfaces: the web and documentation lookups the research gates sequence.
   research: ['WebSearch', 'WebFetch'],
+  // Observation tool for background processes.
+  monitor: ['Monitor'],
 });
 
 /** Every concrete tool name a set of groups expands to, de-duplicated. */
@@ -91,6 +93,7 @@ const MCP_GROUP_SIGNALS = Object.freeze({
   execution:
     /(?:write|edit|create|append|patch|replace|insert|modify|save|update|shell|bash|exec|run|command|terminal|process|spawn|cmd|powershell|sh)/i,
   research: /(?:search|fetch|browse|docs|documentation|library|lookup|query)/i,
+  monitor: /(?:monitor|observe|watch|stream|tail|follow|subscribe)/i,
 });
 
 const MCP_TOOL_PREFIX = 'mcp__';
@@ -560,10 +563,10 @@ export function allow() {
 /** A Stop-hook block: makes the agent continue instead of ending the turn. */
 export function block(label, reason) {
   record(DECISIONS.BLOCK, reason);
-  process.stdout.write(
+  process.stderr.write(
     JSON.stringify({ decision: 'block', reason: `[${label}] ${reason}` }),
   );
-  process.exit(0);
+  process.exit(2);
 }
 
 export const SEVERITY = Object.freeze({ DENY: 'deny', WARN: 'warn' });

package/plugins/gates/hooks/lib/testing.mjs

@@ -53,7 +53,7 @@ export function runGateProcess(
   } = {},
 ) {
   const root = project ?? makeProject({ config, files });
-  const out = execFileSync(process.execPath, [gatePath], {
+  const options = {
     input: typeof payload === 'string' ? payload : JSON.stringify(payload),
     encoding: 'utf8',
     cwd: cwd ?? root,
@@ -65,9 +65,20 @@ export function runGateProcess(
       ...environment,
     },
     timeout,
-  });
-  const trimmed = out.trim();
-  return trimmed ? JSON.parse(trimmed) : null;
+  };
+  try {
+    const out = execFileSync(process.execPath, [gatePath], options);
+    const trimmed = out.trim();
+    return trimmed ? JSON.parse(trimmed) : null;
+  } catch (error) {
+    if (error.status === 2) {
+      const stderr = String(error.stderr ?? '').trim();
+      const stdout = String(error.stdout ?? '').trim();
+      const source = stderr || stdout;
+      return source ? JSON.parse(source) : null;
+    }
+    throw error;
+  }
 }
 
 /** 'deny' | 'warn' | 'block' | null from a gate's parsed output. */

package/plugins/tasks/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tasks",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Deterministic task tracking for Claude Code: persists tasks the model registers via the CLI, reminds of open tasks on a message counter, and lists active tasks on session start.",
   "author": {
     "name": "Devrik"

package/plugins/tasks/hooks/lib/task-store.mjs

@@ -170,6 +170,12 @@ export function openTaskStore(startDirectory) {
       writeCollection(activePath, collection);
       return task;
     },
+    /** Active sub-tasks whose parentId equals the given id. */
+    childrenOf(id) {
+      return readCollection(activePath).tasks.filter(
+        (task) => task.parentId === id,
+      );
+    },
     /** Merges fields into the active task with matching id. Null if not found. */
     update(id, fields) {
       const collection = readCollection(activePath);

package/plugins/tasks/hooks/register-requests.mjs

@@ -77,17 +77,44 @@ function readPayload() {
 
 // Asked on every message. The hook does not classify — it asks the model to, and the
 // model is the one that persists (via the CLI, which enforces the store's own rules,
-// e.g. evidence on close). This is legitimate: the hook is not depending on the model to
-// make something OCCUR deterministically; it is depending on the model's judgment for a
-// judgment call (whether this message describes a new task), same shape as ask-adoption.
+// e.g. evidence on close). Default to registering: the USER defines what is a task, not
+// the model. The model must not use judgment to skip what the user considers actionable.
 const CLASSIFY_PROMPT =
-  '[tasks] MANDATORY before you respond: judge whether the message you just received describes ' +
-  'a new actionable task (not a question, not small talk, not a follow-up on an already-registered ' +
-  'task). If it does, you MUST register it now, before writing your reply — run ' +
-  '`claude-gates task add "<title>" [--description <text>] [--size <size>]` from the project root ' +
-  "(or the CLI's absolute path if `claude-gates` is not on PATH). Do not defer this, do not decide " +
-  'to register it "later", do not silently skip it because the answer seems obvious. If it is not a ' +
-  'new task, skip registration — do not fabricate one.';
+  "[tasks] MANDATORY — before writing your reply, you MUST register the user's message as a " +
+  'task unless it is UNAMBIGUOUSLY one of these: (a) pure small talk with no request ("hello", ' +
+  '"thanks"), (b) a yes/no answer to a question YOU asked, (c) a message that says only "continue" ' +
+  'or "go ahead". Everything else is a task — including questions that require research, review ' +
+  'requests, error reports, follow-ups that add scope, corrections, and messages with multiple ' +
+  'requests (register one task per distinct request). DEFAULT TO REGISTERING: when in doubt, ' +
+  'register.\n\n' +
+  'VERIFICATION REQUIRED: every task MUST include a deterministic verification criterion. Use ' +
+  'one of these:\n' +
+  '  --verify-command "<shell command>" [--verify-expect <text>]  (command must exit 0 when done)\n' +
+  '  --verify-path <file-or-dir> [--verify-contains <text>]       (must exist when done)\n' +
+  'Examples:\n' +
+  '  claude-gates task add "Fix login bug" --verify-command "npm test -- --grep login" --verify-expect "passing"\n' +
+  '  claude-gates task add "Add config file" --verify-path "src/config.ts" --verify-contains "export"\n' +
+  'Pick the criterion that a machine can check: a test that passes, a file that exists, a grep ' +
+  'that matches. If the task is a question/research, use --verify-path for the file where the ' +
+  'answer will be written, or --verify-command "claude-gates task list" --verify-expect "done".\n\n' +
+  'SPLITTING (Depth Tree): tasks with size medium or larger MUST be split into sub-tasks before ' +
+  'implementation. SCOPE FIRST: if the task description is vague or you are unsure what files or ' +
+  'modules are affected, ASK THE USER to clarify the scope before splitting — do not guess. ' +
+  'Once scope is clear:\n' +
+  '  1. Each sub-task OWNS specific files (state in --description "OWNS: <paths>") — no overlap\n' +
+  '  2. Each sub-task is --size small and independently verifiable\n' +
+  '  3. Split at natural boundaries: one module, one function, one test file\n' +
+  '  4. Register parent first, then sub-tasks with --parent <parent-id>\n' +
+  'Example:\n' +
+  '  claude-gates task add "Refactor auth" --size large --verify-command "npm test" --verify-expect "passing"\n' +
+  '  claude-gates task add "Extract token validation" --parent <id> --size small ' +
+  '--verify-path "src/auth/validate.ts" --description "OWNS: src/auth/validate.ts"\n' +
+  '  claude-gates task add "Add token refresh" --parent <id> --size small ' +
+  '--verify-command "npm test -- --grep refresh" --description "OWNS: src/auth/refresh.ts"\n\n' +
+  'Run `claude-gates task add "<title>" [--description <text>] [--size <size>] --verify-command|--verify-path ...` ' +
+  "from the project root (or the CLI's absolute path if `claude-gates` is not on PATH). Do not defer " +
+  'this, do not decide to register it "later", do not silently skip it because the answer seems ' +
+  "obvious. The user's flow takes priority over your judgment of what deserves tracking.";
 
 function formatReminder(tasks) {
   const shown = tasks.slice(0, MAX_TASKS_SHOWN);

package/registry.json

@@ -110,6 +110,22 @@
               "description": "Comment marker that authorizes a justified wait as an escape hatch."
             }
           ]
+        },
+        {
+          "id": "require-monitor",
+          "configKey": "requireMonitorForBackground",
+          "default": true,
+          "event": "PreToolUse",
+          "tools": ["shell", "execution", "monitor"],
+          "description": "Enforces that every background command (run_in_background: true) has an associated Monitor. Phase 1: denies background without MONITOR-PLANNED: marker. Phase 2: denies any execution tool while unmonitored backgrounds exist.",
+          "script": "gates/require-monitor/index.mjs",
+          "params": [
+            {
+              "name": "monitorPlannedMarker",
+              "type": "string",
+              "description": "Marker the command must carry to declare its Monitor plan. Default MONITOR-PLANNED:."
+            }
+          ]
         }
       ]
     },
@@ -187,8 +203,15 @@
           "default": false,
           "event": "PreToolUse",
           "tools": ["delegation"],
-          "description": "Cuts a delegation retried without substantial change: the attempt count is recomputed from stored signatures across the session (Dice >= similarityThreshold); retryThreshold below 2 is treated as 2.",
+          "description": "Cuts a delegation retried without substantial change: the attempt count is recomputed from stored signatures across the session (Dice >= similarityThreshold); retryThreshold below 2 is treated as 2. Only delegations that actually launched (allowed by all gates) count as attempts.",
           "script": "gates/circuit-breaker/index.mjs",
+          "extraScripts": [
+            {
+              "event": "PostToolUse",
+              "script": "gates/circuit-breaker/track.mjs",
+              "tools": ["delegation"]
+            }
+          ],
           "params": [
             {
               "name": "retryThreshold",
@@ -226,10 +249,10 @@
         {
           "id": "force-parallel",
           "configKey": "warnSequentialDelegations",
-          "default": false,
+          "default": true,
           "event": "PreToolUse",
           "tools": ["delegation"],
-          "description": "Warns after N consecutive sequential delegations within a time window, suggesting they be launched together instead.",
+          "description": "Denies the Nth consecutive sequential delegation within a time window, requiring independent delegations to be launched together in one message. Escape hatch: SEQUENTIAL-JUSTIFIED in the prompt declares a genuine dependency.",
           "script": "gates/force-parallel/index.mjs",
           "params": [
             {
@@ -736,6 +759,16 @@
               "description": "Substring inside a comment that allows it once (a documented exception). Default comment-ok:."
             }
           ]
+        },
+        {
+          "id": "no-trivial-scripts",
+          "configKey": "blockTrivialInlineScripts",
+          "default": true,
+          "event": "PreToolUse",
+          "tools": ["shell"],
+          "description": "Denies inline interpreter scripts (node -e, python -c, sed -i, perl -i, PowerShell Set-Content/Add-Content) when they perform file operations that the Edit or Write tool handles directly. Legitimate computation scripts are not caught.",
+          "script": "gates/no-trivial-scripts/index.mjs",
+          "params": []
         }
       ]
     },
@@ -869,7 +902,7 @@
           "configKey": "requireDocsBeforeUsingNewLibrary",
           "default": true,
           "event": "PreToolUse",
-          "tools": ["write"],
+          "tools": ["write", "shell"],
           "script": "gates/library-docs/index.mjs",
           "extraScripts": [
             {
@@ -878,7 +911,7 @@
               "tools": ["research"]
             }
           ],
-          "description": "Denies a write that imports a package the project does not use anywhere yet unless this session looked it up: an engram hit about it, or context7 docs followed by a mem_save. Never guess a library API.",
+          "description": "Denies a write or shell command that imports a package the project does not use anywhere yet unless this session looked it up: an engram hit about it, or context7 docs followed by a mem_save. Shell heredocs are inspected; opaque redirections to code files are denied outright. Never guess a library API.",
           "params": [
             {
               "name": "codeExtensions",
@@ -964,6 +997,16 @@
               "description": "When true (default), a task with status 'blocked' does not prevent stop; only open/in_forge do."
             }
           ]
+        },
+        {
+          "id": "require-task-split",
+          "configKey": "requireTaskSplitBeforeImplementing",
+          "default": true,
+          "event": "PreToolUse",
+          "tools": ["write", "execution"],
+          "description": "Denies writes and execution when an active task has size > small/trivial and no sub-tasks registered. Forces splitting into smaller, independently verifiable sub-tasks before implementation begins.",
+          "script": "gates/require-task-split/index.mjs",
+          "params": []
         }
       ]
     },