@devrik-tools/claude-gates 0.7.2 → 0.8.0

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

@@ -1,86 +1,17 @@
-// capability-map — UserPromptSubmit hook. Surfaces the REAL, current catalog of the project's
-// AI capabilities — skills, agents/subagents, and commands — as compact data ("caveman"
-// format: `name — first clause`, one line each, grouped by kind). It also PERSISTS that
-// catalog to .ai/capability-map.json so the map is easy to follow and read the same way the
-// tool map (.ai/tool-map.json) is, and so another tool or a human can consult it without
-// re-scanning. Autosynced by construction: add or remove a skill/agent/command file and the
-// next message reflects it (a removed capability's entry disappears with it — the catalog is
-// derived from what is on disk NOW, never a stale copy of what used to be there), because the
-// catalog IS the directory listing. Re-deriving blurbs (the only non-trivial per-entry work)
-// is skipped when disk is provably unchanged since the last scan — see fingerprintOf below.
-//
-// It does NOT tell the model to obey a reminder — that would be prose the model may ignore,
-// the exact antipattern guard-no-model-reliance forbids. It injects a fact (which capabilities
-// exist) and lets the assistant decide to use them.
-//
-// justification: no existing gate covers this. rule-skill-autodiscovery EXECUTES sub-gate
-// scripts found under skills; dependency-skills cross-checks package.json deps against skill
-// dirs; tool-map records built TOOLS (scripts) into .ai/tool-map.json. None enumerate the
-// skill/agent/command catalog or inject it as context. This is the read+inject counterpart to
-// tool-map for the capability catalog.
-//
-// A UserPromptSubmit hook's stdout is appended to the assistant's context as plain text, so
-// the catalog is simply written to stdout (no PreToolUse JSON shape). Self-contained: Node
-// built-ins only.
-//
-// ── What it discovers (every root: ~/.claude and <project>/.claude, plus config extras) ──
-//   skills    <root>/skills/<name>/SKILL.md   front matter name + description
-//   agents    <root>/agents/*.md              front matter name (falls back to file basename)
-//                                             + description; subagents nested deeper too
-//   commands  <root>/commands/*.{md,toml}     front matter description; name is the basename
-// Each injected line is `name — first clause` (up to the first '. ' or a hard char cap), so
-// the whole catalog stays cheap even at dozens of entries.
-//
-// ── Blurb overrides for descriptions that don't fit ─────────────────────────────────────
-// When a description's first clause is longer than `maxClauseChars`, mechanical truncation
-// (even at a word boundary) loses the point of a dense one-liner (e.g. "Referencia normativa
-// completa de accesibilidad web (WCAG 2.2, ARIA, teclado, lectores de…" tells you nothing).
-// Writing an actual summary needs judgment a Node hook does not have — so instead this gate
-// reads a human/assistant-authored override by capability name from `~/.claude/blurb-
-// overrides.json` and `<project>/<blurbOverridesFile>` (project wins per-key) and uses it
-// verbatim (still capped at maxClauseChars, in case an override itself runs long). A
-// capability with no override falls back to the mechanical truncation — never blocked on
-// someone writing every override up front.
-//
-// ── Throttled injection, not every message ──────────────────────────────────────────────
-// Injecting the full catalog on every UserPromptSubmit burns context on every turn for a
-// catalog that rarely changes turn-to-turn. `injectEveryMessages` (default 10, same shape as
-// tasks' remindEveryMessages) counts messages via a small persisted counter next to the map
-// file and only injects on the Nth. The persisted .ai/capability-map.json is still refreshed
-// from disk on EVERY message regardless of the counter — persistence is cheap (a file write,
-// not context) and staying accurate matters even between injections.
-//
-// ── Skills also scanned outside the .claude layout, unconditionally ────────────────────
-// `~/.agents/skills`, `<project>/.agents/skills`, `~/.ai/skills`, `<project>/.ai/skills` are
-// scanned as skill roots by default (no config needed) alongside `.claude/skills` — these
-// are skill directories other installers are known to use (`.agents/skills` is what the
-// `skills` CLI several installers shell out to writes when run without its `-g` flag: a
-// project-local skill tree, not `~/.claude`). Agents/commands are NOT looked for under these
-// roots — only `.claude` is known to lay those out as siblings of `skills`.
-//
-// ── What a project can configure (params) — everything is customizable ───────────────
-//   kinds              which capability kinds to include, e.g. ["skills","agents","commands"].
-//                      Drop one to stop scanning it entirely.
-//   maxClauseChars     hard cap on each entry's one-line blurb (default 120).
-//   extraSkillsDirs / extraAgentsDirs / extraCommandsDirs   additional roots per kind
-//                      (relative to project or absolute), added on top of the built-in ones.
-//   persist            whether to write .ai/capability-map.json (default true).
-//   mapFile            path to the persisted map, relative to project root. Default
-//                      .ai/capability-map.json.
-//   injectEveryMessages   inject the rendered catalog only every Nth message (default 10);
-//                      the persisted map file still refreshes every message regardless.
-//   blurbOverridesFile   path to the overrides JSON, relative to project root. Default
-//                      .ai/blurb-overrides.json.
-//
-// ── Fail-safe shape ──────────────────────────────────────────────────────────────────
-// Nothing found anywhere, gate disabled, or unreadable input: inject nothing (silent, no
-// wasted context) — and never write an empty map over a good one. Persistence failure is
-// swallowed: the injection is the job, the file is a convenience. Never blocks —
-// UserPromptSubmit cannot deny; it only adds context.
+// capability-map — UserPromptSubmit hook. Injects the REAL, current catalog of the project's
+// AI capabilities (skills, agents, commands) as compact data — `name — first clause`, one
+// line each, grouped by kind — and persists it to .ai/capability-map.json. The catalog IS
+// the directory listing, so it is autosynced by construction. Injection is throttled
+// (every Nth message, or immediately when the catalog changed), with the counter kept in
+// session state so the map file is rewritten only when the catalog itself changed.
+// Project roots are scanned BEFORE ~/.claude so a project skill shadows a global one.
+// A description whose first clause runs long is replaced by a hand-written override from
+// ~/.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.
 
 import { createHash } from 'node:crypto';
 import {
-  existsSync,
   mkdirSync,
   readFileSync,
   readdirSync,
@@ -89,124 +20,97 @@ import {
 } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, extname, isAbsolute, join } from 'node:path';
+import {
+  loadGateConfig,
+  projectRootOf,
+  readJsonOrNull,
+} from '../../lib/config.mjs';
+import { coerceParameters } from '../../lib/hook-io.mjs';
+import {
+  readSessionState,
+  writeSessionState,
+} from '../../lib/session-state.mjs';
 
 const STDIN_FILE_DESCRIPTOR = 0;
+const GATE_ID = 'capability-map';
 const CONFIG_KEY = 'injectCapabilityMap';
 const DUMP_ENV = 'CLAUDE_GATES_DUMP_DEFAULTS';
-// The registry default this gate is shipped with. Kept here (not only in dumpDefaults) so
-// main() and dumpDefaults agree by construction — a value duplicated in two places is
-// exactly the desync that let a gate silently miss its own registry default before (see
-// the project's default-desync incident: registry.json and the gate's own hardcoded
-// enabledByDefault drifting apart across a version bump).
 const ENABLED_BY_DEFAULT = true;
-const DEFAULT_MAX_CLAUSE_CHARS = 120;
-const DEFAULT_KINDS = ['skills', 'agents', 'commands'];
-const DEFAULT_MAP_FILE = join('.ai', 'capability-map.json');
-const DEFAULT_BLURB_OVERRIDES_FILE = join('.ai', 'blurb-overrides.json');
-const DEFAULT_INJECT_EVERY_MESSAGES = 10;
 const JSON_INDENT = 2;
 
-// Config lookup mirrors config.mjs (project → global), kept local so a gate stays runnable on
-// its own alongside the other event-scripts (doctor, wiring-check).
-const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
-const PROJECT_CONFIG = join('.ai', 'config.json');
-const GLOBAL_CONFIG = join('.claude', 'claude-gates', 'config.json');
+const DEFAULT_PARAMS = Object.freeze({
+  kinds: ['skills', 'agents', 'commands'],
+  maxClauseChars: 120,
+  extraSkillsDirs: [],
+  extraAgentsDirs: [],
+  extraCommandsDirs: [],
+  persist: true,
+  mapFile: join('.ai', 'capability-map.json'),
+  blurbOverridesFile: join('.ai', 'blurb-overrides.json'),
+  injectEveryMessages: 10,
+});
+
+const KIND_EXTENSIONS = {
+  agents: ['.md'],
+  commands: ['.md', '.toml'],
+};
 
-function readJson(path) {
+function readPayload() {
   try {
-    return JSON.parse(readFileSync(path, 'utf8').replace(/^\uFEFF/, ''));
+    return JSON.parse(readFileSync(STDIN_FILE_DESCRIPTOR, 'utf8'));
   } catch {
-    return null;
+    return {};
   }
 }
 
-function projectRootOf(startDirectory) {
-  let current = startDirectory;
-  while (true) {
-    if (
-      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
-    ) {
-      return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
   }
 }
 
-/** The capability-map gate config entry (project overrides global). `enabled` is `true`/
- * `false` only when a project or global config explicitly declared it — absent (undefined)
- * means "nothing was declared, fall back to the registry default", the same three-state
- * shape config.mjs's isGateEnabled uses for every other gate. Distinguishing "never
- * declared" from "explicitly false" matters once ENABLED_BY_DEFAULT is true: without it, a
- * project that never touched this gate's config would look identical to one that turned it
- * off, and the registry default could never take effect. */
-function gateConfig(startDirectory) {
-  const root = projectRootOf(startDirectory);
-  const projectData = root ? readJson(join(root, PROJECT_CONFIG)) : null;
-  const globalData = readJson(join(homedir(), GLOBAL_CONFIG));
-  const layer = projectData?.gates ?? globalData?.gates ?? {};
-  const entry = layer[CONFIG_KEY];
-  if (typeof entry === 'boolean') return { enabled: entry };
-  if (entry && typeof entry === 'object') return entry;
-  return {};
-}
-
-function readPayload() {
+function mtimeMsOf(path) {
   try {
-    return JSON.parse(readFileSync(STDIN_FILE_DESCRIPTOR, 'utf8'));
+    return statSync(path).mtimeMs;
   } catch {
-    return {};
+    return null;
   }
 }
 
-// A YAML folded/literal block scalar indicator with nothing else on the line
-// (`description: >`, `description: >-`, `description: |`, `description: |-`): the real
-// value is every following indented line, not this one. Seen across `.agents/skills`
-// SKILL.md files (e.g. api-architect, babysit, branch-pr) — without this, the parser took
-// the bare indicator itself as the description, rendering blurbs like `">"` or `">-"`.
+// ── 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*$/;
 
-/** Every following line indented relative to the block's own indentation, joined with a
- * single space (folded-scalar semantics — good enough for a one-line blurb; literal `|`
- * blocks are folded too, which only affects a display detail this gate strips anyway via
- * firstClause). Stops at the first line that is blank or not indented (front matter end,
- * or a sibling key). */
 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; // not indented: block scalar ended
+    if (!/^[ \t]+\S/.test(line)) break;
     parts.push(line.trim());
   }
   return parts.join(' ');
 }
 
-/**
- * The `name` and `description` from a markdown-style front matter block (skills, agents,
- * commands all use `---`-fenced YAML-ish front matter). Parsed line-by-line (no multi-line
- * regex) so a large file body can never trigger catastrophic backtracking. Handles a plain
- * scalar value on the `key:` line itself, and a YAML folded/literal block scalar (`>`, `>-`,
- * `|`, `|-`) whose value lives on the following indented lines. Returns { name, description }
- * with either possibly ''.
- */
+// 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; // end of front matter
+    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, ''); // toml/yaml quoting around the value
+      .replace(/^["']|["']$/g, '');
     if (BLOCK_SCALAR_INDICATOR_PATTERN.test(value)) {
       value = readBlockScalarValue(lines, index + 1);
     }
@@ -216,10 +120,6 @@ function parseFrontMatter(fileText) {
   return { name, description };
 }
 
-/** Truncates text to at most maxChars, breaking at the last whitespace boundary before
- * the limit rather than mid-word — a hard char-index cut turns "lectores de pantalla"
- * into "lectores de…", losing the word instead of just the tail of the sentence. Falls
- * back to a hard cut only when there is no whitespace to break on (one very long word). */
 function truncateAtWordBoundary(text, maxChars) {
   if (text.length <= maxChars) return text;
   const budget = text.slice(0, maxChars - 1);
@@ -228,7 +128,6 @@ function truncateAtWordBoundary(text, maxChars) {
   return `${cut.trimEnd()}…`;
 }
 
-/** The description's first clause, capped — the caveman blurb. */
 function firstClause(description, maxClauseChars) {
   if (!description) return '';
   const sentenceEnd = description.indexOf('. ');
@@ -237,294 +136,199 @@ function firstClause(description, maxClauseChars) {
   return truncateAtWordBoundary(clause, maxClauseChars);
 }
 
-/** Recursively lists files under a directory whose extension is in `extensions`. */
+// ── Discovery ───────────────────────────────────────────────────────────────────────
 function filesUnder(directory, extensions) {
-  if (!existsSync(directory)) return [];
-  let entries;
+  let names;
   try {
-    entries = readdirSync(directory, { withFileTypes: true });
+    names = readdirSync(directory);
   } catch {
     return [];
   }
   const files = [];
-  for (const entry of entries) {
-    const full = join(directory, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...filesUnder(full, extensions));
-    } else if (extensions.includes(extname(entry.name).toLowerCase())) {
-      files.push(full);
-    }
+  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;
 }
 
-/** The file's mtime in ms, or null when it cannot be stat'd (broken junction, race). A
- * source this gate cannot stat contributes nothing stable to the fingerprint — treated as
- * absent so a dangling link does not poison every future comparison with a NaN/undefined. */
-function mtimeMsOf(path) {
+function entryFor(file, fallbackName) {
+  const mtimeMs = mtimeMsOf(file);
+  if (mtimeMs === null) return null;
+  let content;
   try {
-    return statSync(path).mtimeMs;
+    content = readFileSync(file, 'utf8');
   } catch {
     return null;
   }
+  const { name, description } = parseFrontMatter(content);
+  return {
+    name: name || fallbackName,
+    description,
+    stamp: `${file}:${mtimeMs}`,
+  };
 }
 
-/** Skill capabilities under one root: <root>/skills/<name>/SKILL.md. Each entry carries
- * `stamp: "<path>:<mtimeMs>"`, the unit the disk fingerprint is built from (see
- * fingerprintOf) — cheap because it reuses the stat already needed to read the file, no
- * second filesystem pass. */
-function skillEntriesUnder(skillsRoot, maxClauseChars) {
-  if (!existsSync(skillsRoot)) return [];
-  let skillDirectories;
+function skillEntriesUnder(skillsRoot) {
+  let names;
   try {
-    skillDirectories = readdirSync(skillsRoot, { withFileTypes: true });
+    names = readdirSync(skillsRoot);
   } catch {
     return [];
   }
-  const entries = [];
-  for (const skillDirectory of skillDirectories) {
-    if (!skillDirectory.isDirectory()) continue;
-    const skillFile = join(skillsRoot, skillDirectory.name, 'SKILL.md');
-    const mtimeMs = mtimeMsOf(skillFile);
-    if (mtimeMs === null) continue; // missing or a dangling link: not a real source
-    let content;
-    try {
-      content = readFileSync(skillFile, 'utf8');
-    } catch {
-      continue;
-    }
-    const { name, description } = parseFrontMatter(content);
-    entries.push({
-      name: name || skillDirectory.name,
-      description,
-      maxClauseChars,
-      stamp: `${skillFile}:${mtimeMs}`,
-    });
-  }
-  return entries;
-}
-
-/** Agent/command capabilities: flat or nested files whose front matter carries a description.
- * Same stamp shape as skillEntriesUnder, for the same reason. */
-function fileEntriesUnder(directory, extensions, maxClauseChars) {
-  const entries = [];
-  for (const file of filesUnder(directory, extensions)) {
-    const mtimeMs = mtimeMsOf(file);
-    if (mtimeMs === null) continue;
-    let content;
-    try {
-      content = readFileSync(file, 'utf8');
-    } catch {
-      continue;
-    }
-    const { name, description } = parseFrontMatter(content);
-    entries.push({
-      name: name || basename(file, extname(file)),
-      description,
-      maxClauseChars,
-      stamp: `${file}:${mtimeMs}`,
-    });
-  }
-  return entries;
-}
-
-function baseRoots(cwd) {
-  return [join(homedir(), '.claude'), join(cwd, '.claude')];
-}
-
-// Skill directories seen in the wild outside the `.claude/skills` layout: the `skills`
-// upstream CLI (invoked by installers like caveman) writes to a project-local
-// `./.agents/skills` when run without its `-g` flag (see caveman/bin/install.js's own
-// comment on issue #836 — the exact bug that produced 65 dangling junctions under
-// `~/.claude/skills` in one real incident: they pointed at a `.agents/skills` that only
-// ever existed relative to the project the installer ran from). `.ai/skills` is included
-// per explicit user instruction, without independent verification of a specific installer
-// using it — kept here rather than as a project-declared default so every project gets it
-// without having to know the installer's quirk. These are SKILL roots only (the directory
-// IS the skills folder, unlike `.claude` where `skills/agents/commands` are siblings under
-// one root) — they never gain agents/commands lookup, which would be inventing a layout
-// this repo has no evidence for.
-function defaultSkillOnlyRoots(cwd) {
+  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(cwd, '.agents', 'skills'),
     join(homedir(), '.ai', 'skills'),
-    join(cwd, '.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 resolveExtra(cwd, directory) {
-  return isAbsolute(directory) ? directory : join(cwd, directory);
-}
-
-/** Every entry for one kind across all roots, de-duplicated by name (each entry still
- * carries description/maxClauseChars/stamp — blurb overrides and truncation are applied
- * later, once, in applyBlurbs, not per-root). */
-function entriesForKind(kind, cwd, config, maxClauseChars) {
-  const perKind = {
-    skills: {
-      subdir: 'skills',
-      extra: config.extraSkillsDirs,
-      collect: (root) =>
-        skillEntriesUnder(join(root, 'skills'), maxClauseChars),
-      collectExtra: (directory) => skillEntriesUnder(directory, maxClauseChars),
-    },
-    agents: {
-      extra: config.extraAgentsDirs,
-      collect: (root) =>
-        fileEntriesUnder(join(root, 'agents'), ['.md'], maxClauseChars),
-      collectExtra: (directory) =>
-        fileEntriesUnder(directory, ['.md'], maxClauseChars),
-    },
-    commands: {
-      extra: config.extraCommandsDirs,
-      collect: (root) =>
-        fileEntriesUnder(
-          join(root, 'commands'),
-          ['.md', '.toml'],
-          maxClauseChars,
-        ),
-      collectExtra: (directory) =>
-        fileEntriesUnder(directory, ['.md', '.toml'], maxClauseChars),
-    },
-  }[kind];
-  if (!perKind) return [];
-
-  const collected = [];
-  for (const root of baseRoots(cwd)) collected.push(...perKind.collect(root));
+function collectKind(kind, root, settings) {
   if (kind === 'skills') {
-    for (const root of defaultSkillOnlyRoots(cwd)) {
-      collected.push(...skillEntriesUnder(root, maxClauseChars));
-    }
-  }
-  const extra = Array.isArray(perKind.extra) ? perKind.extra : [];
-  for (const directory of extra) {
-    collected.push(...perKind.collectExtra(resolveExtra(cwd, directory)));
+    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 collected) {
-    if (seen.has(entry.name)) continue; // a capability present in two roots is listed once
+  for (const entry of collectKind(kind, root, settings)) {
+    if (seen.has(entry.name)) continue;
     seen.add(entry.name);
     unique.push(entry);
   }
-  unique.sort((a, b) => a.name.localeCompare(b.name));
-  return unique;
+  return unique.sort((a, b) => a.name.localeCompare(b.name));
 }
 
-/** The two override file paths in effect for this cwd (global always; project only when a
- * project root is found), regardless of whether either currently exists. Shared by
- * blurbOverridesFor (reads them) and blurbOverrideStampsFor (fingerprints them) so the two
- * can never drift to different paths. */
-function blurbOverridePathsFor(cwd, blurbOverridesFile) {
-  const globalPath = join(homedir(), '.claude', 'blurb-overrides.json');
-  const root = projectRootOf(cwd);
-  const projectPath = root ? join(root, blurbOverridesFile) : null;
-  return projectPath ? [globalPath, projectPath] : [globalPath];
+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 [
+    join(homedir(), '.claude', 'blurb-overrides.json'),
+    join(root, blurbOverridesFile),
+  ];
 }
 
-/** The overrides map (capability name -> hand-written blurb). Project file wins over the
- * global one entry-by-entry (spread, global first) so a project can override a single
- * global entry without having to repeat the rest. */
-function blurbOverridesFor(cwd, blurbOverridesFile) {
+function blurbOverridesFor(root, blurbOverridesFile) {
   const [globalPath, projectPath] = blurbOverridePathsFor(
-    cwd,
+    root,
     blurbOverridesFile,
   );
+  const asObject = (value) =>
+    value && typeof value === 'object' && !Array.isArray(value) ? value : {};
   return {
-    ...(readJson(globalPath) ?? {}),
-    ...(projectPath ? (readJson(projectPath) ?? {}) : {}),
+    ...asObject(readJsonOrNull(globalPath)),
+    ...asObject(readJsonOrNull(projectPath)),
   };
 }
 
-/** Stamps for the override file(s) themselves, in the same "<path>:<mtimeMs>" shape as a
- * capability's stamp — folded into the fingerprint so EDITING AN OVERRIDE (with no skill
- * file touched at all) still invalidates the cached catalog. Without this, a fresh or
- * changed blurb-overrides.json would sit unused: the persisted catalog's fingerprint would
- * still match (no skill/agent/command changed) and resolveCatalog would keep serving the
- * stale, un-overridden blurb forever — the exact bug a real run surfaced (clean-architecture
- * got an override added to blurb-overrides.json after the map had already been generated
- * once, and kept showing the mechanically-truncated text on every later run because nothing
- * ever invalidated the cache). A missing override file contributes a stable "absent" stamp
- * (not skipped) so going from absent -> present is itself a fingerprint change. */
-function blurbOverrideStampsFor(cwd, blurbOverridesFile) {
-  return blurbOverridePathsFor(cwd, blurbOverridesFile).map((path) => {
-    const mtimeMs = mtimeMsOf(path);
-    return `${path}:${mtimeMs === null ? 'absent' : mtimeMs}`;
-  });
-}
-
-/** Turns a raw entry (description/maxClauseChars/stamp) into the rendered shape
- * (name/blurb/stamp) — an override is used verbatim (still capped, in case it runs long
- * itself); with no override, falls back to the mechanical first-clause truncation. */
-function applyBlurbs(entries, overrides) {
+function applyBlurbs(entries, overrides, maxClauseChars) {
   return entries.map((entry) => {
     const override = overrides[entry.name];
-    const blurb = override
-      ? truncateAtWordBoundary(override, entry.maxClauseChars)
-      : firstClause(entry.description, entry.maxClauseChars);
-    return { name: entry.name, blurb, stamp: entry.stamp };
+    const blurb =
+      typeof override === 'string' && override
+        ? truncateAtWordBoundary(override, maxClauseChars)
+        : firstClause(entry.description, maxClauseChars);
+    return { name: entry.name, blurb };
   });
 }
 
-/** A stable, order-independent fingerprint of every source file's path+mtime across the
- * whole catalog, plus any `extraStamps` the caller folds in (the override file(s) — see
- * blurbOverrideStampsFor; a capability's rendered blurb depends on both its own source file
- * AND the overrides file, so both must be able to invalidate the cache). Two scans of an
- * otherwise-unchanged disk produce the same fingerprint; adding, removing, or touching any
- * skill/agent/command file, or the overrides file, changes it. Sorted before hashing so
- * filesystem enumeration order (which readdirSync does not guarantee) never causes a false
- * "changed" reading. sha256 not for any security property (this is a change-detection
- * checksum, nothing here is adversarial) — plain sha1 just trips the linter's blanket
- * weak-hash rule, and sha256 is just as cheap at this size. */
-function fingerprintOf(catalog, extraStamps = []) {
-  const stamps = Object.values(catalog)
+// Everything the rendered blurbs depend on: every source file's path+mtime, the override
+// files (absent counts as a stable stamp), and the settings that shape a blurb.
+function fingerprintOf(rawCatalog, root, settings) {
+  const overrideStamps = blurbOverridePathsFor(
+    root,
+    settings.blurbOverridesFile,
+  ).map((path) => `${path}:${mtimeMsOf(path) ?? 'absent'}`);
+  const settingStamps = [
+    `maxClauseChars=${settings.maxClauseChars}`,
+    `kinds=${settings.kinds.join(',')}`,
+    `blurbOverridesFile=${settings.blurbOverridesFile}`,
+  ];
+  const stamps = Object.values(rawCatalog)
     .flat()
     .map((entry) => entry.stamp)
-    .concat(extraStamps)
+    .concat(overrideStamps, settingStamps)
     .sort();
   return createHash('sha256').update(stamps.join('\n')).digest('hex');
 }
 
-/** Strips `stamp` before persisting/rendering — it is scan-time-only plumbing for the
- * fingerprint, not part of the public map shape. */
-function withoutStamps(catalog) {
-  const stripped = {};
-  for (const [kind, entries] of Object.entries(catalog)) {
-    stripped[kind] = entries.map(({ name, blurb }) => ({ name, blurb }));
-  }
-  return stripped;
+function renderedCatalogOf(rawCatalog, root, settings) {
+  const overrides = blurbOverridesFor(root, settings.blurbOverridesFile);
+  return Object.fromEntries(
+    Object.entries(rawCatalog).map(([kind, entries]) => [
+      kind,
+      applyBlurbs(entries, overrides, settings.maxClauseChars),
+    ]),
+  );
 }
 
-/** Reads the persisted map's catalog + fingerprint + injection counter, or nulls when
- * absent/corrupt. Used to decide whether a rescan is needed and to track injectEveryMessages
- * without a second store file. */
-function readPersistedState(mapPath) {
-  const data = readJson(mapPath);
-  if (!data || typeof data !== 'object') {
-    return { catalog: null, fingerprint: null, messageCount: 0 };
-  }
-  return {
-    catalog:
-      data.capabilities && typeof data.capabilities === 'object'
-        ? data.capabilities
-        : null,
-    fingerprint: typeof data.fingerprint === 'string' ? data.fingerprint : null,
-    messageCount: Number.isInteger(data.messageCount) ? data.messageCount : 0,
-  };
+// ── Persistence ─────────────────────────────────────────────────────────────────────
+function readPersistedMap(mapPath) {
+  const data = readJsonOrNull(mapPath);
+  const catalog =
+    data?.capabilities && typeof data.capabilities === 'object'
+      ? data.capabilities
+      : null;
+  const fingerprint =
+    typeof data?.fingerprint === 'string' ? data.fingerprint : null;
+  return { catalog, fingerprint };
 }
 
-/** Persists the map to .ai/capability-map.json, best-effort — never throws, never blocks. */
-function persistMap(cwd, mapFile, catalog, fingerprint, messageCount) {
-  const root = projectRootOf(cwd);
-  if (!root) return;
-  const mapPath = join(root, mapFile);
+function persistMap(mapPath, catalog, fingerprint) {
   const payload = {
     generatedAt: new Date().toISOString(),
     fingerprint,
-    messageCount,
-    capabilities: withoutStamps(catalog),
+    capabilities: catalog,
   };
   try {
     mkdirSync(dirname(mapPath), { recursive: true });
@@ -534,167 +338,137 @@ function persistMap(cwd, mapFile, catalog, fingerprint, messageCount) {
       'utf8',
     );
   } catch {
-    // The injection is the job; the persisted file is a convenience. A write failure must
-    // not break the turn.
+    // The injection is the job; the file is a convenience.
   }
 }
 
-const KIND_LABELS = {
-  skills: 'skills',
-  agents: 'agents',
-  commands: 'commands',
-};
-
-function dumpDefaults() {
-  process.stdout.write(
-    JSON.stringify({
-      id: 'capability-map',
-      configKey: CONFIG_KEY,
-      enabledByDefault: ENABLED_BY_DEFAULT,
-      defaultParams: {
-        kinds: DEFAULT_KINDS,
-        maxClauseChars: DEFAULT_MAX_CLAUSE_CHARS,
-        extraSkillsDirs: [],
-        extraAgentsDirs: [],
-        extraCommandsDirs: [],
-        persist: true,
-        mapFile: DEFAULT_MAP_FILE,
-        blurbOverridesFile: DEFAULT_BLURB_OVERRIDES_FILE,
-        injectEveryMessages: DEFAULT_INJECT_EVERY_MESSAGES,
-      },
-    }),
-  );
-}
-
-/** The non-empty raw catalog (description/maxClauseChars/stamp per entry — no blurbs yet),
- * keyed by kind, in the order `kinds` lists them. */
-function buildRawCatalog(kinds, cwd, config, maxClauseChars) {
-  const catalog = {};
-  for (const kind of kinds) {
-    const entries = entriesForKind(kind, cwd, config, maxClauseChars);
-    if (entries.length > 0) catalog[kind] = entries;
-  }
-  return catalog;
-}
-
-/** The injected text for a catalog, grouped and captioned per kind. */
 function renderCatalog(catalog, kinds) {
   const sections = [];
   for (const kind of kinds) {
     const entries = catalog[kind];
     if (!entries) continue;
-    const label = KIND_LABELS[kind] || kind;
     const lines = entries.map((entry) =>
       entry.blurb ? `  ${entry.name} — ${entry.blurb}` : `  ${entry.name}`,
     );
-    sections.push(`${label}:\n${lines.join('\n')}`);
+    sections.push(`${kind}:\n${lines.join('\n')}`);
   }
   return `[capabilities] available (check before improvising something one of these covers):\n${sections.join('\n')}\n`;
 }
 
-/** Every tunable read out of the raw config object, with its default applied — keeps main()
- * a single flat read instead of five inline `config.x || DEFAULT_X` expressions. */
-function resolvedConfig(config) {
+// A changed catalog (or the first message of a session) injects immediately; otherwise
+// every Nth message.
+function injectionDecision(session, fingerprint, injectEveryMessages) {
+  const changed = session.fingerprint !== fingerprint;
+  const nextCount = (Number(session.messageCount) || 0) + 1;
+  const shouldInject = changed || nextCount >= injectEveryMessages;
+  return { shouldInject, messageCount: shouldInject ? 0 : nextCount };
+}
+
+function settingsFor(cwd) {
+  const config = loadGateConfig(cwd);
+  if (!config.isEnabled(CONFIG_KEY, ENABLED_BY_DEFAULT)) return null;
+  const { parameters } = coerceParameters(
+    DEFAULT_PARAMS,
+    config.paramsFor(CONFIG_KEY),
+  );
   return {
-    maxClauseChars: Number(config.maxClauseChars) || DEFAULT_MAX_CLAUSE_CHARS,
-    kinds: Array.isArray(config.kinds) ? config.kinds : DEFAULT_KINDS,
-    mapFile: config.mapFile || DEFAULT_MAP_FILE,
-    blurbOverridesFile:
-      config.blurbOverridesFile || DEFAULT_BLURB_OVERRIDES_FILE,
+    ...parameters,
+    kinds: parameters.kinds.map(String),
+    maxClauseChars:
+      parameters.maxClauseChars > 0
+        ? parameters.maxClauseChars
+        : DEFAULT_PARAMS.maxClauseChars,
     injectEveryMessages:
-      Number(config.injectEveryMessages) || DEFAULT_INJECT_EVERY_MESSAGES,
-    persist: config.persist !== false,
+      parameters.injectEveryMessages > 0
+        ? parameters.injectEveryMessages
+        : DEFAULT_PARAMS.injectEveryMessages,
   };
 }
 
-/** The rendered { name, blurb } catalog for this run: reused verbatim from the persisted
- * map when disk is provably unchanged since the last scan (same fingerprint), or freshly
- * derived (overrides applied, then mechanical truncation for the rest) otherwise. Re-
- * deriving is the only per-entry work worth skipping — everything downstream only ever
- * sees { name, blurb }, never `stamp`/`description`/`maxClauseChars`. */
-function resolveCatalog(rawCatalog, persisted, fingerprint, cwd, settings) {
-  if (persisted.fingerprint === fingerprint && persisted.catalog) {
-    return persisted.catalog;
-  }
-  const overrides = blurbOverridesFor(cwd, settings.blurbOverridesFile);
-  const rendered = Object.fromEntries(
-    Object.entries(rawCatalog).map(([kind, entries]) => [
-      kind,
-      applyBlurbs(entries, overrides),
-    ]),
+function dumpDefaults() {
+  process.stdout.write(
+    JSON.stringify({
+      id: GATE_ID,
+      configKey: CONFIG_KEY,
+      enabledByDefault: ENABLED_BY_DEFAULT,
+      defaultParams: DEFAULT_PARAMS,
+    }),
   );
-  return withoutStamps(rendered);
 }
 
-/** Whether this run should inject the rendered catalog, and the counter value to persist
- * either way. A fingerprint change forces immediate injection: either this is the very
- * first run for this project (persisted.fingerprint is null — nothing has ever been
- * injected, and waiting up to injectEveryMessages turns before the model learns these
- * capabilities exist is the wrong default) or the disk catalog changed since the last scan
- * (a capability was added/removed — worth surfacing right away, not on whatever the counter
- * happens to be). Both reset the counter, same as a normal throttled trigger. */
-function injectionDecision(persisted, fingerprint, injectEveryMessages) {
-  const catalogChanged = persisted.fingerprint !== fingerprint;
-  const nextMessageCount = persisted.messageCount + 1;
-  const shouldInject =
-    catalogChanged || nextMessageCount >= injectEveryMessages;
-  return { shouldInject, messageCount: shouldInject ? 0 : nextMessageCount };
+function cwdOf(payload) {
+  return typeof payload.cwd === 'string' && payload.cwd
+    ? payload.cwd
+    : process.cwd();
 }
 
-function main() {
-  if (process.env[DUMP_ENV]) {
-    dumpDefaults();
-    return;
-  }
+// The persisted rendering is reused only when its fingerprint matches; the map file is
+// rewritten only when the rendered catalog actually differs from what is on disk.
+function syncMap(mapPath, rawCatalog, fingerprint, root, settings) {
+  const persisted = readPersistedMap(mapPath);
+  const catalog =
+    persisted.fingerprint === fingerprint && persisted.catalog
+      ? persisted.catalog
+      : renderedCatalogOf(rawCatalog, root, settings);
+  const changed =
+    persisted.fingerprint !== fingerprint ||
+    JSON.stringify(persisted.catalog) !== JSON.stringify(catalog);
+  if (settings.persist && changed) persistMap(mapPath, catalog, fingerprint);
+  return catalog;
+}
 
-  const payload = readPayload();
-  const cwd = payload.cwd || process.cwd();
-
-  const config = gateConfig(cwd);
-  const isEnabled =
-    config.enabled === undefined ? ENABLED_BY_DEFAULT : config.enabled;
-  if (!isEnabled) return;
-
-  const settings = resolvedConfig(config);
-  const rawCatalog = buildRawCatalog(
-    settings.kinds,
-    cwd,
-    config,
-    settings.maxClauseChars,
+function shouldInjectNow(sessionId, root, fingerprint, injectEveryMessages) {
+  const session = readSessionState(GATE_ID, sessionId, {}, { cwd: root });
+  const { shouldInject, messageCount } = injectionDecision(
+    session,
+    fingerprint,
+    injectEveryMessages,
   );
-  if (Object.keys(rawCatalog).length === 0) return; // nothing to surface: never overwrite a good map
-
-  const overrideStamps = blurbOverrideStampsFor(
-    cwd,
-    settings.blurbOverridesFile,
+  writeSessionState(
+    GATE_ID,
+    sessionId,
+    { fingerprint, messageCount },
+    { cwd: root },
   );
-  const fingerprint = fingerprintOf(rawCatalog, overrideStamps);
-  const root = projectRootOf(cwd);
-  const mapPath = root ? join(root, settings.mapFile) : null;
-  const persisted = mapPath
-    ? readPersistedState(mapPath)
-    : { catalog: null, fingerprint: null, messageCount: 0 };
-
-  const catalog = resolveCatalog(
+  return shouldInject;
+}
+
+function run() {
+  const payload = readPayload();
+  const cwd = cwdOf(payload);
+  const settings = settingsFor(cwd);
+  if (!settings) return;
+  const root = projectRootOf(cwd) ?? cwd;
+
+  const rawCatalog = buildRawCatalog(root, settings);
+  if (Object.keys(rawCatalog).length === 0) return;
+
+  const fingerprint = fingerprintOf(rawCatalog, root, settings);
+  const catalog = syncMap(
+    join(root, settings.mapFile),
     rawCatalog,
-    persisted,
     fingerprint,
-    cwd,
+    root,
     settings,
   );
-
-  const { shouldInject, messageCount } = injectionDecision(
-    persisted,
+  const inject = shouldInjectNow(
+    payload.session_id ?? null,
+    root,
     fingerprint,
     settings.injectEveryMessages,
   );
+  if (inject) process.stdout.write(renderCatalog(catalog, settings.kinds));
+}
 
-  if (settings.persist && mapPath) {
-    persistMap(cwd, settings.mapFile, catalog, fingerprint, messageCount);
+function main() {
+  if (process.env[DUMP_ENV]) {
+    dumpDefaults();
+    return;
   }
-
-  if (shouldInject) {
-    process.stdout.write(renderCatalog(catalog, settings.kinds));
+  try {
+    run();
+  } catch {
+    // Context injection is best-effort; an error must never reach the user.
   }
 }