@euanmsm/preflight 0.1.0 → 0.2.1

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,11 +62,40 @@ 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.
+
+## Subagents
+
+A subagent or workflow agent must load the skills itself. The gate checks the
+calling agent's own transcript, so skills the main session loaded do not count
+for its subagents. That is deliberate: a subagent never sees the main session's
+context, so it has not read those conventions either.
+
 ## When it does not block
 
-The gate fails open. A missing map, an unreadable transcript, a file outside the
-repository or a malformed payload all allow the edit rather than halting work on
-a tool that cannot do its job. `PREFLIGHT=off` disables it for one command.
+The gate fails open. A missing map, an unreadable transcript, a subagent
+transcript it cannot find, a file outside the repository or a malformed payload
+all allow the edit rather than halting work on a tool that cannot do its job.
+`PREFLIGHT=off` disables it for one command.
 
 Deliberate: a gate that breaks your session when its own config has a typo is a
 gate you will remove within the week.

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.1",
+  "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,12 +2,14 @@
 // 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 by the agent making it — by the tool's name when a tool rule matches,
+// otherwise by the path of the file it writes. A subagent is checked against
+// its own transcript, not its parent's. Fails open on any error.
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, relative } from 'node:path';
+import { basename, dirname, join, relative } from 'node:path';
 
 import { compile, loadConfig, repoRoot } from '@euanmsm/devkit-core';
 
@@ -18,7 +20,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({
@@ -33,12 +39,26 @@ function deny(reason) {
 }
 
 /**
- * Locates the session transcript the hook payload belongs to.
+ * Locates the transcript of the agent making the tool call.
  *
  * @param input - The hook payload
  * @returns Path to the transcript, or null when it cannot be found
  */
 export function findTranscript(input) {
+  const session = findSessionTranscript(input);
+  if (!session || !input.agent_id) return session;
+
+  return findAgentTranscript(session, input.agent_id);
+}
+
+/**
+ * Locates the main session's transcript, which the payload names even when a
+ * subagent makes the call.
+ *
+ * @param input - The hook payload
+ * @returns Path to the transcript, or null when it cannot be found
+ */
+function findSessionTranscript(input) {
   if (input.transcript_path && existsSync(input.transcript_path))
     return input.transcript_path;
 
@@ -53,6 +73,30 @@ export function findTranscript(input) {
   return null;
 }
 
+/**
+ * Locates a subagent's transcript beside its session's.
+ *
+ * @param sessionTranscript - Path to the main session's transcript
+ * @param agentId - The subagent's id from the hook payload
+ * @returns Path to the transcript, or null when it cannot be found
+ */
+export function findAgentTranscript(sessionTranscript, agentId) {
+  const subagents = join(
+    dirname(sessionTranscript),
+    basename(sessionTranscript, '.jsonl'),
+    'subagents',
+  );
+  if (!existsSync(subagents)) return null;
+
+  // Workflow agents sit one level down, under workflows/<run>/.
+  const name = `agent-${agentId}.jsonl`;
+  const hit = readdirSync(subagents, { recursive: true }).find(
+    (entry) => basename(entry) === name,
+  );
+
+  return hit ? join(subagents, hit) : null;
+}
+
 /**
  * Reads every skill loaded in a transcript.
  *
@@ -95,7 +139,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 +192,38 @@ 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');
+  const scope = input.agent_id
+    ? `Skills loaded by the parent session do not count here — load them yourself.\n\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` +
+      scope +
+      `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}.`,
   );
 }