@euanmsm/preflight 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,8 @@
 # @euanmsm/preflight
 
 A Claude Code hook that blocks an edit until the agent has read the conventions
-governing the file it is about to change.
+governing the file it is about to change — or blocks any other tool call, such
+as an MCP write, until it has read the conventions for that tool.
 
 The problem it solves: an agent that has not opened your conventions writes code
 from memory of how code is usually written, not how _your_ code is written. You
@@ -25,12 +26,20 @@ Then register it as a `PreToolUse` hook in `.claude/settings.json`:
       {
         "matcher": "Edit|Write",
         "hooks": [{ "type": "command", "command": "npx preflight" }]
+      },
+      {
+        "matcher": "mcp__.*[Ll]inear.*__save_(issue|comment|document|project)",
+        "hooks": [{ "type": "command", "command": "npx preflight" }]
       }
     ]
   }
 }
 ```
 
+The second entry is only needed for `tools` rules. The hook only runs for tools
+its `matcher` lets through, so a `tools` rule for a tool no matcher covers never
+fires. Keep the matcher and the rule's pattern in step.
+
 ## The map
 
 `.devkit/preflight.json` says which skills each path needs. Patterns are regular
@@ -53,6 +62,27 @@ round. `universal` rules always add on top of whichever primary rule matched.
 
 A path no rule names requires nothing, so the gate is opt-in per directory.
 
+### Gating a tool by name
+
+`tools` rules match the tool name instead of a path, so they can gate calls that
+write no file at all:
+
+```json
+{
+  "tools": [
+    {
+      "pattern": "^mcp__.*[Ll]inear.*__save_(issue|comment|document|project)$",
+      "skills": ["linear"]
+    }
+  ]
+}
+```
+
+`tools` is first match wins, like `primary`. When a tool rule matches, its
+skills are the only ones the call needs — path rules are not checked for that
+call. The deny message names the tool when a tool rule matched and the file when
+a path rule did.
+
 ## When it does not block
 
 The gate fails open. A missing map, an unreadable transcript, a file outside the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@euanmsm/preflight",
-  "version": "0.1.0",
-  "description": "Claude Code PreToolUse hook that blocks an edit until the file's governing convention skill has been loaded",
+  "version": "0.2.0",
+  "description": "Claude Code PreToolUse hook that blocks an edit or tool call until its governing convention skill has been loaded",
   "type": "module",
   "license": "MIT",
   "repository": {

package/preflight.example.json

@@ -1,5 +1,12 @@
 {
-  "_readme": "Path-to-skill map. Patterns are JS regexes tested against the repo-relative path. `primary` is first-match-wins, so order matters — most specific first. `universal` rules always add on top.",
+  "_readme": "Skill map. `tools` patterns are JS regexes tested against the tool name, and a match gates the call whatever file it touches. Every other pattern is tested against the repo-relative path. `tools` and `primary` are first-match-wins, so order matters — most specific first. `universal` rules always add on top.",
+
+  "tools": [
+    {
+      "pattern": "^mcp__.*[Ll]inear.*__save_(issue|comment|document|project)$",
+      "skills": ["linear"]
+    }
+  ],
 
   "exclude": [
     "node_modules/",

package/src/gate.mjs

@@ -2,8 +2,9 @@
 // Skill Gate
 // ============================================================================
 //
-// PreToolUse hook on Edit and Write. Blocks the edit until the file's required
-// convention skills have been loaded this session. Fails open on any error.
+// PreToolUse hook. Blocks a tool call until the skills it needs have been
+// loaded this session — by the tool's name when a tool rule matches, otherwise
+// by the path of the file it writes. Fails open on any error.
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -18,7 +19,11 @@ function allow() {
   process.exit(0);
 }
 
-/** Blocks the tool call, showing the agent which skills to load. */
+/**
+ * Blocks the tool call, showing the agent which skills to load.
+ *
+ * @param reason - Which skills the edit needs first
+ */
 function deny(reason) {
   process.stdout.write(
     JSON.stringify({
@@ -95,7 +100,50 @@ export function requiredFor(rel, map) {
   return [...required];
 }
 
-/** True when a pattern compiles and matches, false when it does neither. */
+/**
+ * Names the skills a tool requires, whatever file it touches.
+ *
+ * @param tool - The tool name from the hook payload
+ * @param map - Parsed skill map
+ * @returns Required skill names, empty when no tool rule matches
+ */
+export function requiredForTool(tool, map) {
+  // First match wins, like primary.
+  const hit = (map.tools ?? []).find((rule) => matches(rule.pattern, tool));
+  return hit ? [...hit.skills] : [];
+}
+
+/**
+ * Finds what a tool call needs and what to call it in the deny message.
+ *
+ * @param input - The hook payload
+ * @param map - Parsed skill map
+ * @param root - Repository root
+ * @returns The tool name or path, and its skills; null when nothing governs it
+ */
+function gateFor(input, map, root) {
+  const tool = input?.tool_name ?? '';
+  const toolSkills = requiredForTool(tool, map);
+  if (toolSkills.length > 0) return { subject: tool, skills: toolSkills };
+
+  const filePath = input?.tool_input?.file_path;
+  if (!filePath) return null;
+
+  const rel = relative(root, filePath);
+
+  // A file in another checkout is not this repo's to govern.
+  if (rel.startsWith('..')) return null;
+
+  return { subject: rel, skills: requiredFor(rel, map) };
+}
+
+/**
+ * Tests one path against one pattern.
+ *
+ * @param pattern - A regex from the config
+ * @param rel - Repo-relative path
+ * @returns Whether it matches, and false when the pattern will not compile
+ */
 function matches(pattern, rel) {
   return compile([pattern]).some((p) => p.test(rel));
 }
@@ -105,34 +153,34 @@ export function main() {
   if (process.env.PREFLIGHT === 'off') allow();
 
   const input = JSON.parse(readFileSync(0, 'utf8'));
-  const filePath = input?.tool_input?.file_path;
-  if (!filePath) allow();
 
-  const root = repoRoot();
-  const rel = relative(root, filePath);
-
-  // A file in another checkout is not this repo's to govern.
-  if (rel.startsWith('..')) allow();
+  // Outside a repository there is no map to read, so nothing is governed.
+  let root;
+  try {
+    root = repoRoot();
+  } catch {
+    allow();
+  }
 
   const map = loadConfig(CONFIG_NAME, null, root);
   if (!map) allow();
 
-  const required = requiredFor(rel, map);
-  if (required.length === 0) allow();
+  const gate = gateFor(input, map, root);
+  if (!gate || gate.skills.length === 0) allow();
 
   const transcript = findTranscript(input);
   if (!transcript) allow();
 
   const loaded = loadedSkills(transcript);
-  const missing = required.filter((s) => !loaded.has(s));
+  const missing = gate.skills.filter((s) => !loaded.has(s));
   if (missing.length === 0) allow();
 
   const calls = missing.map((s) => `  Skill(skill: "${s}")`).join('\n');
 
   deny(
-    `BLOCKED — ${rel} is governed by convention skills you have not loaded this session.\n\n` +
-      `Load them, then make this edit again:\n${calls}\n\n` +
-      `These skills hold the conventions this file must follow. Do not work around this by ` +
+    `BLOCKED — ${gate.subject} is governed by convention skills you have not loaded this session.\n\n` +
+      `Load them, then make this call again:\n${calls}\n\n` +
+      `These skills hold the conventions this call must follow. Do not work around this by ` +
       `writing from memory. The mapping lives in .devkit/${CONFIG_NAME}.`,
   );
 }