@devrik-tools/claude-gates 0.9.0 → 1.0.0

package/cli/install.mjs

@@ -5,11 +5,19 @@
 
 import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { SCOPES } from './config.mjs';
 import { MARKETPLACE_PATH, REPOSITORY_ROOT } from './constants.mjs';
+import { compareVersions, parsePluginList } from './doctor.mjs';
 
 const CLAUDE_BIN = 'claude';
 
+/** The version of THIS package — what an install is expected to leave behind. */
+function packageVersion() {
+  return JSON.parse(readFileSync(join(REPOSITORY_ROOT, 'package.json'), 'utf8'))
+    .version;
+}
+
 // Config scope decides where the plugin is installed: a project selection stays local to
 // this project (its .claude/settings.json); a global selection installs for every project.
 const PLUGIN_SCOPE = Object.freeze({
@@ -198,6 +206,47 @@ function removePreviousInstalls(targets, scope, runClaude) {
   }
 }
 
+/**
+ * Whether the install ACTUALLY took, described as a problem string (null when it did).
+ *
+ * `claude plugin install` exiting 0 is not evidence that anything changed: a marketplace
+ * still serving a stale path, a plugin that resolves but is never enabled, or an update
+ * that silently no-ops all exit 0 too. Reporting success on the exit code alone is what
+ * produced the "it says it worked but nothing updated" failure — the installer claimed a
+ * result it had not checked, and only `doctor`, run separately and later, ever noticed.
+ *
+ * So the post-condition is read back from Claude Code itself: the plugin must now appear
+ * in `plugin list`, at a version not older than this package's. Reuses doctor's parser
+ * rather than a second one, so what install verifies and what doctor reports can never
+ * disagree. A verification that cannot run (no `claude` on PATH, unparseable output) is
+ * NOT treated as failure — that would turn a working install into a false alarm; only a
+ * definite mismatch is reported.
+ */
+function installationProblem(runClaude, plugin) {
+  let listed;
+  try {
+    listed = parsePluginList(runClaude(['plugin', 'list']));
+  } catch {
+    return null;
+  }
+  if (listed.length === 0) return null;
+
+  const found = listed.filter((entry) => entry.plugin === plugin);
+  if (found.length === 0)
+    return 'the install reported success but the plugin is not in `claude plugin list`';
+
+  const expected = packageVersion();
+  const stale = found.filter(
+    (entry) => entry.version && compareVersions(entry.version, expected) < 0,
+  );
+  if (stale.length === found.length)
+    return (
+      `still running ${stale[0].version} after installing ${expected} — the marketplace is ` +
+      'serving a stale copy. Run `claude plugin marketplace remove`, then re-run init from this package.'
+    );
+  return null;
+}
+
 /**
  * Registers the marketplace (idempotent: a second add just reports it already exists, which
  * is not fatal) once, then installs EVERY plugin the manifest declares at the scope matching
@@ -259,10 +308,13 @@ export function installPlugin(
         '--scope',
         scope,
       ]);
-      return { plugin, installed: true };
     } catch (error) {
       return { plugin, installed: false, reason: reasonFor(error) };
     }
+    const problem = installationProblem(runClaude, plugin);
+    return problem
+      ? { plugin, installed: false, reason: problem }
+      : { plugin, installed: true };
   });
 
   const installed = results.every((result) => result.installed);

package/cli/registry.mjs

@@ -22,6 +22,7 @@ export const TOOL_GROUPS = [
   'question',
   'research',
   'monitor',
+  'skill',
 ];
 
 /** The kinds of value a gate param can take, so the CLI can describe and validate it. */

package/cli/selection.mjs

@@ -10,8 +10,25 @@ export const MODES = Object.freeze({
   GRANULAR: 'granular',
   DEFAULTS: 'defaults',
   NONE: 'none',
+  /**
+   * Only what this config has never decided about. Resolves exactly like GRANULAR — by the
+   * time picks arrive the user has already chosen from a list narrowed to the new gates —
+   * but the caller builds that list with `newGatesFor`, so an upgrade can adopt what a
+   * release added without re-answering, or silently flipping, anything already in the file.
+   */
+  NEW: 'new',
 });
 
+/**
+ * The gates a config has never decided about: no entry under `gates` for their configKey.
+ * An entry set to `false` counts as DECIDED — the user turned it off on purpose, and
+ * offering it again as "new" would be how a deliberate opt-out gets undone by an upgrade.
+ */
+export function newGatesFor(registry, existingGates = {}) {
+  const decided = new Set(Object.keys(existingGates ?? {}));
+  return allGates(registry).filter((gate) => !decided.has(gate.configKey));
+}
+
 function assertKnown(chosen, known, kind) {
   const unknown = [...chosen].filter((id) => !known.has(id));
   if (unknown.length > 0)
@@ -35,6 +52,11 @@ const STRATEGIES = {
       gates.filter((gate) => chosen.has(gate.family)).map((gate) => gate.id),
     );
   },
+  [MODES.NEW]: (gates, _registry, picks) => {
+    const chosen = new Set(picks.gates ?? []);
+    assertKnown(chosen, new Set(gates.map((gate) => gate.id)), 'gate');
+    return chosen;
+  },
   [MODES.GRANULAR]: (gates, _registry, picks) => {
     const chosen = new Set(picks.gates ?? []);
     assertKnown(chosen, new Set(gates.map((gate) => gate.id)), 'gate');
@@ -93,7 +115,7 @@ export function namedGatesFor(registry, mode, picks = {}) {
     const chosen = new Set(picks.families ?? []);
     return keysOf((gate) => chosen.has(gate.family));
   }
-  if (mode === MODES.GRANULAR) {
+  if (mode === MODES.GRANULAR || mode === MODES.NEW) {
     const chosen = new Set(picks.gates ?? []);
     return keysOf((gate) => chosen.has(gate.id));
   }

package/cli/smoke-fixtures.json

@@ -413,6 +413,14 @@
       "needsState": true,
       "note": "side-effect only: records to .ai/tool-map.json, never denies/warns."
     },
+    {
+      "id": "skill-first",
+      "configKey": "requireSkillCheckBeforeActing",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": null,
+      "needsState": true
+    },
     {
       "id": "forge-flow",
       "configKey": "requireForgeRunToEdit",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrik-tools/claude-gates",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "description": "49 installable, deterministic gates (hooks) for Claude Code: block destructive commands and protected paths, enforce delegation/spec/quality/research rules, and track tasks that only close with verified evidence. Configurable per project.",
   "keywords": [
     "claude-code",
@@ -75,4 +75,4 @@
     "globals": "^17.11.0",
     "prettier": "^3.9.6"
   }
-}
+}

package/plugins/gates/hooks/gates/capability-map/index.mjs

@@ -9,17 +9,21 @@
 // ~/.claude/blurb-overrides.json and <project>/<blurbOverridesFile> (project wins per key).
 // `.agents/skills` and `.ai/skills` (home and project) are scanned as skill-only roots:
 // other installers write there. Never blocks; any failure injects nothing.
+//
+// Discovery itself lives in lib/capabilities.mjs, shared with skill-first (the PreToolUse
+// half that judges whether an action has a skill covering it): one catalog definition, so
+// what the model is TOLD it has and what a gate CHECKS it has can never disagree.
 
 import { createHash } from 'node:crypto';
-import {
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, extname, isAbsolute, join } from 'node:path';
+import { dirname, join } from 'node:path';
+import {
+  buildRawCatalog,
+  firstClause,
+  mtimeMsOf,
+  truncateAtWordBoundary,
+} from '../../lib/capabilities.mjs';
 import {
   loadGateConfig,
   projectRootOf,
@@ -30,6 +34,7 @@ import {
   readSessionState,
   writeSessionState,
 } from '../../lib/session-state.mjs';
+import { workNatureOf } from '../../lib/signals.mjs';
 
 const STDIN_FILE_DESCRIPTOR = 0;
 const GATE_ID = 'capability-map';
@@ -48,13 +53,9 @@ const DEFAULT_PARAMS = Object.freeze({
   mapFile: join('.ai', 'capability-map.json'),
   blurbOverridesFile: join('.ai', 'blurb-overrides.json'),
   injectEveryMessages: 10,
+  reinjectOnWorkNatureChange: true,
 });
 
-const KIND_EXTENSIONS = {
-  agents: ['.md'],
-  commands: ['.md', '.toml'],
-};
-
 function readPayload() {
   try {
     return JSON.parse(readFileSync(STDIN_FILE_DESCRIPTOR, 'utf8'));
@@ -63,193 +64,6 @@ function readPayload() {
   }
 }
 
-function isDirectory(path) {
-  try {
-    return statSync(path).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-function mtimeMsOf(path) {
-  try {
-    return statSync(path).mtimeMs;
-  } catch {
-    return null;
-  }
-}
-
-// ── Front matter ────────────────────────────────────────────────────────────────────
-// A bare block-scalar indicator (`>`, `>-`, `|`, `|-`) means the value is on the following
-// indented lines; without this the blurb rendered as ">".
-const BLOCK_SCALAR_INDICATOR_PATTERN = /^[|>][+-]?\d*$/;
-
-function readBlockScalarValue(lines, startIndex) {
-  const parts = [];
-  for (let index = startIndex; index < lines.length; index += 1) {
-    const line = lines[index];
-    if (line.trim() === '---') break;
-    if (!/^[ \t]+\S/.test(line)) break;
-    parts.push(line.trim());
-  }
-  return parts.join(' ');
-}
-
-// Parsed line by line (no multi-line regex) so a large body can never backtrack.
-function parseFrontMatter(fileText) {
-  const lines = fileText.split(/\r?\n/);
-  if (lines[0]?.trim() !== '---') return { name: '', description: '' };
-  let name = '';
-  let description = '';
-  for (let index = 1; index < lines.length; index += 1) {
-    const line = lines[index];
-    if (line.trim() === '---') break;
-    const separator = line.indexOf(':');
-    if (separator < 0) continue;
-    const key = line.slice(0, separator).trim();
-    let value = line
-      .slice(separator + 1)
-      .trim()
-      .replace(/^["']|["']$/g, '');
-    if (BLOCK_SCALAR_INDICATOR_PATTERN.test(value)) {
-      value = readBlockScalarValue(lines, index + 1);
-    }
-    if (key === 'name') name = value;
-    else if (key === 'description') description = value;
-  }
-  return { name, description };
-}
-
-function truncateAtWordBoundary(text, maxChars) {
-  if (text.length <= maxChars) return text;
-  const budget = text.slice(0, maxChars - 1);
-  const lastSpace = budget.lastIndexOf(' ');
-  const cut = lastSpace > 0 ? budget.slice(0, lastSpace) : budget;
-  return `${cut.trimEnd()}…`;
-}
-
-function firstClause(description, maxClauseChars) {
-  if (!description) return '';
-  const sentenceEnd = description.indexOf('. ');
-  const clause =
-    sentenceEnd > 0 ? description.slice(0, sentenceEnd) : description;
-  return truncateAtWordBoundary(clause, maxClauseChars);
-}
-
-// ── Discovery ───────────────────────────────────────────────────────────────────────
-function filesUnder(directory, extensions) {
-  let names;
-  try {
-    names = readdirSync(directory);
-  } catch {
-    return [];
-  }
-  const files = [];
-  for (const name of names) {
-    const full = join(directory, name);
-    if (isDirectory(full)) files.push(...filesUnder(full, extensions));
-    else if (extensions.includes(extname(name).toLowerCase())) files.push(full);
-  }
-  return files;
-}
-
-function entryFor(file, fallbackName) {
-  const mtimeMs = mtimeMsOf(file);
-  if (mtimeMs === null) return null;
-  let content;
-  try {
-    content = readFileSync(file, 'utf8');
-  } catch {
-    return null;
-  }
-  const { name, description } = parseFrontMatter(content);
-  return {
-    name: name || fallbackName,
-    description,
-    stamp: `${file}:${mtimeMs}`,
-  };
-}
-
-function skillEntriesUnder(skillsRoot) {
-  let names;
-  try {
-    names = readdirSync(skillsRoot);
-  } catch {
-    return [];
-  }
-  return names
-    .filter((name) => isDirectory(join(skillsRoot, name)))
-    .map((name) => entryFor(join(skillsRoot, name, 'SKILL.md'), name))
-    .filter(Boolean);
-}
-
-function fileEntriesUnder(directory, extensions) {
-  return filesUnder(directory, extensions)
-    .map((file) => entryFor(file, basename(file, extname(file))))
-    .filter(Boolean);
-}
-
-function resolveExtra(root, directory) {
-  return isAbsolute(directory) ? directory : join(root, directory);
-}
-
-function skillRootsFor(root, extraDirectories) {
-  return [
-    join(root, '.claude', 'skills'),
-    join(root, '.agents', 'skills'),
-    join(root, '.ai', 'skills'),
-    join(homedir(), '.claude', 'skills'),
-    join(homedir(), '.agents', 'skills'),
-    join(homedir(), '.ai', 'skills'),
-    ...extraDirectories.map((directory) => resolveExtra(root, directory)),
-  ];
-}
-
-function fileRootsFor(root, kind, extraDirectories) {
-  return [
-    join(root, '.claude', kind),
-    join(homedir(), '.claude', kind),
-    ...extraDirectories.map((directory) => resolveExtra(root, directory)),
-  ];
-}
-
-function collectKind(kind, root, settings) {
-  if (kind === 'skills') {
-    return skillRootsFor(root, settings.extraSkillsDirs).flatMap(
-      skillEntriesUnder,
-    );
-  }
-  const extensions = KIND_EXTENSIONS[kind];
-  if (!extensions) return [];
-  const extra =
-    kind === 'agents' ? settings.extraAgentsDirs : settings.extraCommandsDirs;
-  return fileRootsFor(root, kind, extra).flatMap((directory) =>
-    fileEntriesUnder(directory, extensions),
-  );
-}
-
-// First occurrence wins, and project roots come first: a project capability shadows a
-// global one of the same name.
-function entriesForKind(kind, root, settings) {
-  const seen = new Set();
-  const unique = [];
-  for (const entry of collectKind(kind, root, settings)) {
-    if (seen.has(entry.name)) continue;
-    seen.add(entry.name);
-    unique.push(entry);
-  }
-  return unique.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-function buildRawCatalog(root, settings) {
-  const catalog = {};
-  for (const kind of settings.kinds) {
-    const entries = entriesForKind(kind, root, settings);
-    if (entries.length > 0) catalog[kind] = entries;
-  }
-  return catalog;
-}
-
 // ── Blurbs, overrides and the fingerprint ───────────────────────────────────────────
 function blurbOverridePathsFor(root, blurbOverridesFile) {
   return [
@@ -355,12 +169,20 @@ function renderCatalog(catalog, kinds) {
   return `[capabilities] available (check before improvising something one of these covers):\n${sections.join('\n')}\n`;
 }
 
-// A changed catalog (or the first message of a session) injects immediately; otherwise
-// every Nth message.
-function injectionDecision(session, fingerprint, injectEveryMessages) {
+// Three reasons to inject, then the throttle. The catalog changing on disk was the only
+// content-driven trigger the gate had, which left the case the reminder is actually for:
+// the session PIVOTING to a different kind of work (debugging → designing → releasing)
+// with a catalog that never moved, so the model kept whatever the throttle last emitted
+// and the skills that matter for the new nature were never re-surfaced. The nature is a
+// coarse lexical read of the prompt (lib/signals.mjs), and being wrong costs one extra
+// injection of a never-blocking catalog — cheap enough to prefer over staying silent.
+function injectionDecision(session, fingerprint, nature, settings) {
   const changed = session.fingerprint !== fingerprint;
+  const pivoted =
+    settings.reinjectOnWorkNatureChange && session.workNature !== nature;
   const nextCount = (Number(session.messageCount) || 0) + 1;
-  const shouldInject = changed || nextCount >= injectEveryMessages;
+  const shouldInject =
+    changed || pivoted || nextCount >= settings.injectEveryMessages;
   return { shouldInject, messageCount: shouldInject ? 0 : nextCount };
 }
 
@@ -417,22 +239,28 @@ function syncMap(mapPath, rawCatalog, fingerprint, root, settings) {
   return catalog;
 }
 
-function shouldInjectNow(sessionId, root, fingerprint, injectEveryMessages) {
+function shouldInjectNow(sessionId, root, fingerprint, nature, settings) {
   const session = readSessionState(GATE_ID, sessionId, {}, { cwd: root });
   const { shouldInject, messageCount } = injectionDecision(
     session,
     fingerprint,
-    injectEveryMessages,
+    nature,
+    settings,
   );
   writeSessionState(
     GATE_ID,
     sessionId,
-    { fingerprint, messageCount },
+    { fingerprint, messageCount, workNature: nature },
     { cwd: root },
   );
   return shouldInject;
 }
 
+function promptOf(payload) {
+  const prompt = payload?.prompt ?? payload?.user_prompt ?? payload?.message;
+  return typeof prompt === 'string' ? prompt : '';
+}
+
 function run() {
   const payload = readPayload();
   const cwd = cwdOf(payload);
@@ -455,7 +283,8 @@ function run() {
     payload.session_id ?? null,
     root,
     fingerprint,
-    settings.injectEveryMessages,
+    workNatureOf(promptOf(payload)),
+    settings,
   );
   if (inject) process.stdout.write(renderCatalog(catalog, settings.kinds));
 }

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();
+}