skillrepo 3.2.0 → 4.1.0

package/src/lib/agent-registry.mjs

@@ -0,0 +1,399 @@
+/**
+ * Single source of truth for the agent vendors the CLI supports (#1234).
+ *
+ * Every agent the CLI knows about is declared here exactly once. Path
+ * resolvers (file-write.mjs), flag parsers (cli-config.mjs), MCP merge
+ * coordinators (mcp-merge.mjs), gitignore management (mergers/gitignore.mjs),
+ * detection probes (detect-agents.mjs), agent-hook installers
+ * (agent-hook-merge.mjs), and orphan sweeps all derive their vendor lists
+ * from this registry.
+ *
+ * Adding a vendor: append a frozen entry. Renaming a vendor: change `key`
+ * and put the old key in `aliases` so prior CLI invocations keep working.
+ *
+ * The two-target placement model (per the verified vendor matrix):
+ *   - Claude Code uses Anthropic's documented `.claude/skills/` path.
+ *   - Every other supported agent shares `.agents/skills/` for project
+ *     scope and (with the exception of Windsurf and Copilot) for personal
+ *     scope. Windsurf has a vendor-specific personal path under
+ *     `~/.codeium/windsurf/skills/`. Copilot has no personal scope.
+ *
+ * Detection signals (`detectionSignals`) are the primary-source-verified
+ * fingerprints `detect-agents.mjs` probes when picking which agents have
+ * footprint on this machine / in this project. Three signal types:
+ *
+ *   - `env` — an environment variable the agent sets in shells/sub-processes
+ *     it spawns. Truthy presence in `process.env` indicates an active session.
+ *     NOTE: only assert env vars the vendor's own docs document as set BY the
+ *     agent in spawned shells. Variables the agent merely *reads* (e.g.
+ *     `CODEX_HOME` for Codex's config dir) are config inputs, not detection
+ *     signals — listing them here would produce false positives.
+ *   - `home` — a HOME-relative path the agent creates on first run. Used as
+ *     a "this user has installed the agent" proxy when no env var is
+ *     documented.
+ *   - `project` — a CWD-relative dotfile / dotdir the user keeps in the
+ *     repo to drive agent behavior. Used as the "configured in this repo"
+ *     signal.
+ *
+ * Detection is registry-driven: adding a new signal is a registry edit,
+ * no detect-agents.mjs change required.
+ *
+ * @typedef {"claudeProject" | "claudeGlobal" | "agentsProject" | "agentsGlobal" | "windsurfGlobal"} PlacementTarget
+ *
+ * @typedef {Object} DetectionSignal
+ * @property {"env"|"home"|"project"} type
+ * @property {string} value           - Env var name, HOME-relative path, or
+ *           project (CWD)-relative path. Use forward slashes; resolution is
+ *           via `node:path.join` so Windows separators are produced
+ *           automatically at probe time.
+ *
+ * @typedef {"claude-shape" | "cursor-shape"} AgentHookShape
+ *           Hook config schema variant the vendor accepts (#1240):
+ *             - `claude-shape`: nested `{ hooks: { <Event>: [{ hooks: [{
+ *               type:"command", command, timeout? }] }] } }`. Used by
+ *               Gemini CLI, Codex CLI, and VS Code + Copilot per their
+ *               primary docs.
+ *             - `cursor-shape`: flat `{ version: 1, hooks: { <event>: [{
+ *               command }] } }`. Used by Cursor.
+ *
+ * @typedef {Object} AgentHookSpec
+ * @property {AgentHookShape} shape       - Schema variant the merger uses.
+ * @property {string} eventName           - Event-array key name. Cursor and
+ *           VS Code + Copilot use lowercase `sessionStart`; Gemini and
+ *           Codex use uppercase `SessionStart`. Verify against vendor
+ *           docs before adding new entries — casing is load-bearing.
+ * @property {() => string} pathFn        - Resolves the absolute hook config
+ *           path on the host (always under `os.homedir()` per
+ *           rule-4-of-the-spec: hook configs are user-scope).
+ * @property {string} displayPath         - User-facing path label (e.g.
+ *           `~/.cursor/hooks.json`). Never a real absolute path — leaks
+ *           the developer's home directory into JSON output.
+ * @property {Record<string, unknown>} [entryFields] - Optional extra
+ *           fields merged into the per-hook entry alongside `command`.
+ *           Used by Gemini's `timeout: 60000` (milliseconds) and Codex's
+ *           `timeout: 60` (seconds), the `type: "command"` requirement
+ *           shared by claude-shape vendors, Cursor's seconds-unit
+ *           `timeout: 60`, and Gemini's friendly `name: "skillrepo-update"`
+ *           identifier. Keys MUST be JSON-serializable; the merger does
+ *           a shallow spread.
+ * @property {Record<string, unknown>} [groupFields] - Optional extra
+ *           fields merged into the OUTER group object (claude-shape
+ *           only). Gemini requires `matcher: "*"` at this level so the
+ *           group fires on every SessionStart event; without it the
+ *           group is filtered out. cursor-shape has no group level
+ *           (entries live directly in the event array), so this field
+ *           is ignored for that variant. Like `entryFields`, all keys
+ *           must be JSON-serializable.
+ *
+ * @typedef {Object} AgentEntry
+ * @property {string} key             - Canonical key. Stored in config files.
+ * @property {string} displayName     - User-facing name (used in prompts and summaries).
+ * @property {string[]} aliases       - Alternate names accepted on the command line.
+ * @property {PlacementTarget} projectTarget    - Where project-scope writes land.
+ * @property {PlacementTarget|null} globalTarget - Where personal-scope writes land, or null if the vendor has no personal scope.
+ * @property {boolean} hasMcp         - True if the CLI has a per-vendor MCP merger; false for file-only vendors (cohort vendors without a documented MCP config path).
+ * @property {AgentHookSpec | null} agentHook - Cohort SessionStart-hook
+ *           config (#1240). `null` for vendors the cohort installer
+ *           skips:
+ *             - **Claude Code**: has its own session hook (the legacy
+ *               `mergers/session-hook.mjs` writes a binaryPath-resolved
+ *               command into `.claude/settings.local.json`). The cohort
+ *               installer must NOT write a second hook into the Claude
+ *               settings file.
+ *             - **Windsurf**: no documented SessionStart-equivalent
+ *               event in vendor docs (#1239 epic body — deferred).
+ *             - **Cline**: per-task semantics + non-standard global
+ *               path (`~/Documents/Cline/Hooks/`); deferred.
+ * @property {readonly DetectionSignal[]} detectionSignals - Fingerprints that mark this agent as present.
+ */
+
+// Hook config paths are HOME-relative; resolution must use
+// `node:path.join` so Windows separators are produced at probe time.
+// Hook configs are USER-SCOPE only (gitignored equivalent surface):
+// the SkillRepo skills they sync are per-developer, not committed
+// project state, so the hook config that drives that sync follows
+// suit.
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** @type {readonly AgentEntry[]} */
+export const AGENT_REGISTRY = Object.freeze([
+  Object.freeze({
+    key: "claudeCode",
+    displayName: "Claude Code",
+    // `claude` is the canonical short token (also recognized
+    // explicitly by parseAgentList for the target-shortcut role).
+    // `claude-code` is the kebab-case form some users reach for by
+    // habit; accepting it as a silent alias matches the spec's
+    // "vendor names accepted silently as courtesy aliases" rule.
+    aliases: Object.freeze(["claude", "claude-code"]),
+    projectTarget: "claudeProject",
+    globalTarget: "claudeGlobal",
+    hasMcp: true,
+    // Claude Code's session hook predates the cohort framework
+    // (#884 / `mergers/session-hook.mjs`). It writes a binaryPath-
+    // resolved command into `.claude/settings.local.json` with
+    // exit-0-on-error semantics that the cohort framework
+    // deliberately doesn't reproduce. Setting `agentHook: null`
+    // here is the gate that prevents the cohort installer from
+    // writing a duplicate hook into the same settings file.
+    agentHook: null,
+    detectionSignals: Object.freeze([
+      Object.freeze({ type: "env", value: "CLAUDECODE" }),
+      Object.freeze({ type: "home", value: ".claude" }),
+      Object.freeze({ type: "project", value: ".claude" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "cursor",
+    displayName: "Cursor",
+    aliases: Object.freeze([]),
+    projectTarget: "agentsProject",
+    globalTarget: "agentsGlobal",
+    hasMcp: true,
+    agentHook: Object.freeze({
+      // Cursor docs 2026-05 (#1241): cursor-shape `{ version: 1, hooks:
+      // { sessionStart: [{ command, timeout }] } }`. Multi-tool merge
+      // surface (1Password, Snyk, Apiiro extend the same file) —
+      // round-trip preservation of unknown keys is enforced by the
+      // merger's idempotency tests.
+      //
+      // Cursor's `timeout` is in SECONDS (verified against
+      // cursor.com/docs/hooks). Distinct from Gemini's milliseconds
+      // and identical to Codex's seconds — comments at each entry
+      // call out the unit so a future refactor can't conflate them.
+      shape: "cursor-shape",
+      eventName: "sessionStart",
+      pathFn: () => join(homedir(), ".cursor", "hooks.json"),
+      displayPath: "~/.cursor/hooks.json",
+      entryFields: Object.freeze({ timeout: 60 }),
+    }),
+    detectionSignals: Object.freeze([
+      Object.freeze({ type: "env", value: "CURSOR_AGENT" }),
+      // CURSOR_CLI is the documented fallback when CURSOR_AGENT is
+      // not set in older Cursor builds; both fire under the same
+      // OR semantics so listing both costs nothing.
+      Object.freeze({ type: "env", value: "CURSOR_CLI" }),
+      Object.freeze({ type: "home", value: ".cursor" }),
+      Object.freeze({ type: "project", value: ".cursor" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "windsurf",
+    displayName: "Windsurf",
+    aliases: Object.freeze([]),
+    projectTarget: "agentsProject",
+    globalTarget: "windsurfGlobal",
+    hasMcp: true,
+    // Windsurf has no documented SessionStart-equivalent hook event
+    // (verified absent in Windsurf docs 2026-05). The cohort
+    // installer skips Windsurf — users still get the file-based
+    // skill sync, just no auto-refresh on session start. Tracked in
+    // #1239 epic body; revisit if/when Windsurf publishes a hook
+    // event.
+    agentHook: null,
+    detectionSignals: Object.freeze([
+      // No documented active-session env var (verified absent in
+      // Windsurf docs 2026-05). HOME trace under the Codeium prefix
+      // is the strongest available signal.
+      Object.freeze({ type: "home", value: ".codeium/windsurf" }),
+      Object.freeze({ type: "project", value: ".windsurf" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "gemini",
+    displayName: "Gemini CLI",
+    aliases: Object.freeze([]),
+    projectTarget: "agentsProject",
+    globalTarget: "agentsGlobal",
+    hasMcp: false,
+    agentHook: Object.freeze({
+      // Gemini CLI docs 2026-05 (#1242): claude-shape with a vendor-
+      // specific group-level `matcher` field. Required schema:
+      //   hooks.SessionStart[i] = { matcher: "*", hooks: [{ name,
+      //                              type, command, timeout }] }
+      //
+      // The `matcher` glob filters which sessions the hook fires for.
+      // `"*"` = every session. WITHOUT `matcher`, Gemini silently
+      // skips the group (verified against Gemini's hook-filter logic
+      // in the gemini-cli source). `groupFields` is the registry
+      // mechanism for this — claude-shape merger spreads it into the
+      // group it appends.
+      //
+      // `name: "skillrepo-update"` is a friendly identifier Gemini's
+      // hook-debug UI surfaces. Not load-bearing for our dedupe (we
+      // fingerprint on `command`), but recommended by Gemini's docs
+      // for any tool that owns a hook entry.
+      //
+      // Hook stdout MUST be valid JSON — satisfied by `--silent`
+      // emitting `{}`. Timeout is MILLISECONDS (distinct from
+      // Cursor/Codex/Copilot, which use seconds — see those entries).
+      // Default is 60000ms but Gemini's docs note the default has
+      // shifted in past releases, so we set it explicitly to lock
+      // the contract.
+      shape: "claude-shape",
+      eventName: "SessionStart",
+      pathFn: () => join(homedir(), ".gemini", "settings.json"),
+      displayPath: "~/.gemini/settings.json",
+      entryFields: Object.freeze({
+        name: "skillrepo-update",
+        type: "command",
+        timeout: 60000,
+      }),
+      groupFields: Object.freeze({ matcher: "*" }),
+    }),
+    detectionSignals: Object.freeze([
+      Object.freeze({ type: "env", value: "GEMINI_CLI" }),
+      Object.freeze({ type: "home", value: ".gemini" }),
+      Object.freeze({ type: "project", value: ".gemini" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "codex",
+    displayName: "Codex CLI",
+    aliases: Object.freeze([]),
+    projectTarget: "agentsProject",
+    globalTarget: "agentsGlobal",
+    hasMcp: false,
+    agentHook: Object.freeze({
+      // Codex docs 2026-05 (#1243): claude-shape `hooks.SessionStart[].
+      // hooks[]`. CodexHooks is a Stable, default-on feature in the
+      // Codex CLI source (`Feature::CodexHooks` / Stage::Stable).
+      // Hook stdout becomes model context — `--silent` emits `{}` to
+      // avoid polluting the context with human-readable progress
+      // lines.
+      //
+      // `timeout` is in SECONDS (verified against the Codex hooks
+      // source). Distinct from Gemini's milliseconds; matches
+      // Cursor's units. Codex also accepts a `[hooks]` table in
+      // `~/.codex/config.toml`; users with that configuration will
+      // see Codex MERGE both sources at runtime, so our JSON file
+      // and a hand-written TOML can coexist (documented in the CLI
+      // README).
+      shape: "claude-shape",
+      eventName: "SessionStart",
+      pathFn: () => join(homedir(), ".codex", "hooks.json"),
+      displayPath: "~/.codex/hooks.json",
+      entryFields: Object.freeze({ type: "command", timeout: 60 }),
+    }),
+    detectionSignals: Object.freeze([
+      // Codex has no documented active-session env var. CODEX_HOME
+      // is a config var Codex *reads*, not one it sets — listing it
+      // would produce false positives for users who simply have the
+      // var pointed elsewhere. Detection is HOME + project only.
+      Object.freeze({ type: "home", value: ".codex" }),
+      Object.freeze({ type: "project", value: ".codex" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "cline",
+    displayName: "Cline",
+    aliases: Object.freeze([]),
+    projectTarget: "agentsProject",
+    globalTarget: "agentsGlobal",
+    hasMcp: false,
+    // Cline uses per-task hooks (TaskStart / TaskEnd) rather than a
+    // SessionStart equivalent, AND its hook config lives at a
+    // non-standard global path (`~/Documents/Cline/Hooks/`) that
+    // doesn't fit the user-scope dotfile convention the cohort
+    // framework assumes. Deferred per #1239 epic body.
+    agentHook: null,
+    detectionSignals: Object.freeze([
+      // Cline v3.24+ sets CLINE_ACTIVE="true" in spawned shells.
+      // Detection treats any truthy value as the signal.
+      Object.freeze({ type: "env", value: "CLINE_ACTIVE" }),
+      Object.freeze({ type: "home", value: ".cline" }),
+      Object.freeze({ type: "project", value: ".cline" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "copilot",
+    displayName: "VS Code + Copilot",
+    aliases: Object.freeze(["vscode"]),
+    projectTarget: "agentsProject",
+    globalTarget: null,
+    hasMcp: true,
+    agentHook: Object.freeze({
+      // VS Code + Copilot docs 2026-05 (#1244): cross-compatible with
+      // the Claude / Codex hook schema. The file is per-tool
+      // (`~/.copilot/hooks/skillrepo-update.json`) rather than a
+      // shared multi-tool merge surface — the merger still uses
+      // claude-shape so the file is structurally identical to the
+      // other claude-shape configs.
+      //
+      // Event name is LOWERCASE `sessionStart` per the schema example
+      // in VS Code + Copilot's hooks docs. Distinct from Gemini and
+      // Codex's uppercase `SessionStart`. Both VS Code and the Copilot
+      // CLI read the same file; the lowercase event matches both
+      // surfaces.
+      //
+      // **Preview status**: Copilot's hook system is currently
+      // labelled Preview by GitHub. The CLI README and init step-6
+      // copy surface this caveat so users know the schema may shift.
+      // Cloud-agent runners (GitHub Codespaces) skip gitignored hook
+      // files, which is fine: the hook is per-developer and not
+      // load-bearing for runner work — same documented limitation as
+      // skill placement.
+      //
+      // `timeout` is in SECONDS (matches Cursor and Codex; distinct
+      // from Gemini's milliseconds).
+      shape: "claude-shape",
+      eventName: "sessionStart",
+      pathFn: () => join(homedir(), ".copilot", "hooks", "skillrepo-update.json"),
+      displayPath: "~/.copilot/hooks/skillrepo-update.json",
+      entryFields: Object.freeze({ type: "command", timeout: 60 }),
+    }),
+    detectionSignals: Object.freeze([
+      // Copilot has no documented active-session env var. The HOME
+      // path is the directory the Copilot CLI / VS Code Copilot
+      // extension creates on first run; the project path is the
+      // documented Agent Skills location for VS Code + Copilot.
+      Object.freeze({ type: "home", value: ".copilot" }),
+      Object.freeze({ type: "project", value: ".github/skills" }),
+    ]),
+  }),
+]);
+
+/**
+ * Canonical keys of every cohort vendor — every registry entry whose
+ * project-scope writes land in `.agents/skills/`. Derived from the
+ * registry so a future cohort addition flows through every consumer
+ * without touching their code. Used by `cli-config.mjs` to expand the
+ * `--agent agents` token, and by `init.mjs` to translate the
+ * "Other agents" picker row to a vendor list.
+ *
+ * @type {readonly string[]}
+ */
+export const AGENTS_COHORT_KEYS = Object.freeze(
+  AGENT_REGISTRY.filter((entry) => entry.projectTarget === "agentsProject").map(
+    (entry) => entry.key,
+  ),
+);
+
+/**
+ * Look up a registry entry by its canonical key. Returns `undefined`
+ * for unknown keys — callers should treat that as a programming error.
+ *
+ * @param {string} key
+ * @returns {AgentEntry | undefined}
+ */
+export function getAgentByKey(key) {
+  return AGENT_REGISTRY.find((entry) => entry.key === key);
+}
+
+/**
+ * Resolve an alias (or canonical key) to its canonical key. Returns
+ * `null` for inputs that match neither a canonical key nor any
+ * declared alias. The function is case-sensitive — alias normalization
+ * is the caller's responsibility.
+ *
+ * @param {string} alias
+ * @returns {string | null}
+ */
+export function getAgentByAlias(alias) {
+  for (const entry of AGENT_REGISTRY) {
+    if (entry.key === alias) return entry.key;
+    if (entry.aliases.includes(alias)) return entry.key;
+  }
+  return null;
+}

package/src/lib/artifact-registry.mjs

@@ -42,6 +42,13 @@ import {
 } from "./paths.mjs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+// Cohort agent-hook descriptors derive from the agent registry so the
+// catalog never drifts from the registry's `agentHook` data. Pure data
+// composition: no fs, no dynamic behavior beyond reading frozen
+// constants. The DATA-ONLY rule for this module forbids fs access and
+// runtime mutation; reading another data-only module's exports is in
+// scope.
+import { AGENT_REGISTRY } from "./agent-registry.mjs";
 
 // ── Fingerprint constants exported for cross-module consumption ───────
 
@@ -139,13 +146,84 @@ export const VSCODE_INPUT_ID = "skillrepo-api-key";
  */
 export const SESSION_HOOK_FINGERPRINT = " update --session-hook";
 
+/**
+ * The canonical SessionStart-hook command the CLI installs into every
+ * cohort agent's hook config (#1240). Cohort agents = Cursor, Gemini
+ * CLI, Codex CLI, VS Code + Copilot — every cohort vendor whose
+ * placement target is `agentsProject` AND whose vendor docs publish a
+ * SessionStart-equivalent hook surface.
+ *
+ * The command is intentionally short and shell-portable:
+ *
+ *   - `npx --yes` works on Windows (cmd.exe + PowerShell) and POSIX
+ *     shells with no shell-builtin dependency. The session-hook
+ *     installer's `<absolute-path>` + `|| true` design is
+ *     Claude-Code-specific (Claude doesn't load PATH); the cohort
+ *     vendors all spawn hooks through the user's normal shell where
+ *     `npx` resolves naturally.
+ *   - `--yes` suppresses npx's interactive "Need to install …" prompt
+ *     so the hook never blocks waiting for stdin.
+ *   - `--silent` (#1240) suppresses stdout to a single `{}` line on
+ *     success. Gemini CLI specifically requires hook stdout to be
+ *     valid JSON; the empty object is the minimal valid value that
+ *     injects no model context. Other vendors tolerate it.
+ *
+ * Distinct from `--session-hook` (Claude-Code-specific, exit-0 on
+ * every error). See `commands/update.mjs`'s docstring for the
+ * cross-flag contract table.
+ */
+export const AGENT_HOOK_COMMAND = "npx --yes skillrepo update --silent";
+
+/**
+ * Substring that identifies a cohort SessionStart-hook entry as
+ * SkillRepo-owned (#1240). The cohort installers write a `command`
+ * field equal to `AGENT_HOOK_COMMAND`; the remover walks each cohort
+ * agent's hook config and filters out any entry whose command
+ * contains this substring.
+ *
+ * Same word-boundary rationale as `SESSION_HOOK_FINGERPRINT`: the
+ * leading space requires `skillrepo` to be preceded by whitespace
+ * (i.e., its own argv token), so a hypothetical command like
+ * `myapp-skillrepo update --silent` cannot false-match.
+ *
+ * Both ends of the fingerprint are deliberately permissive — the
+ * fingerprint is shorter than the full command at BOTH the prefix
+ * and suffix:
+ *   - PREFIX tolerance: a future change to the wrapper invocation
+ *     (e.g., switching from `npx --yes` to `bunx`) preserves this
+ *     substring and stays round-trip compatible with installed
+ *     hook entries.
+ *   - SUFFIX tolerance: a future suffix addition (e.g., piping to
+ *     a logger, or adding a `--quiet`-style alias flag) ALSO
+ *     preserves the substring. This is intentional: the remover
+ *     must match every legitimate evolution of the SkillRepo hook
+ *     command without forcing a fingerprint bump.
+ *
+ * The trade-off is that an unrelated tool's hook command containing
+ * the literal sequence ` skillrepo update --silent` somewhere in its
+ * argv would false-match. The two-token combination
+ * `skillrepo update --silent` is specific enough that no real-world
+ * non-SkillRepo command realistically produces it; the fingerprint
+ * test in `agent-hook-{claude,cursor}-shape.test.mjs` covers the
+ * round-trip but does not enumerate every possible false-positive.
+ * If a real-world collision ever surfaces, the right fix is to bump
+ * the fingerprint to a more specific marker (e.g., a version-pinned
+ * sentinel) and gate the change with a backward-compat test that
+ * proves both old and new shapes are matched.
+ *
+ * Any change to the substring itself MUST be coordinated with the
+ * installer mergers (agent-hook-{claude,cursor}-shape.mjs) and the
+ * remover (removers/agent-hooks.mjs).
+ */
+export const AGENT_HOOK_FINGERPRINT = " skillrepo update --silent";
+
 // ── Artifact descriptors ────────────────────────────────────────────
 
 /**
  * @typedef {Object} ArtifactDescriptor
  * @property {string} id - Stable identifier. Shows up in --json output.
  * @property {"project" | "global"} scope - Which teardown pass owns this.
- * @property {"json-key" | "json-input" | "line" | "section" | "directory"} kind
+ * @property {"json-key" | "json-input" | "line" | "section" | "directory" | "agent-hook"} kind
  *          How the remover deletes this artifact.
  * @property {() => string} pathFn - Resolves the on-disk path (absolute).
  * @property {string} displayPath - Human-readable path for output (e.g.
@@ -158,7 +236,13 @@ export const SESSION_HOOK_FINGERPRINT = " update --session-hook";
  * @property {string} [sectionHeader] - For section: the header line;
  *          every line under it up to a blank-line sentinel is owned.
  * @property {string} [commandFingerprint] - For the SessionStart hook
- *          entry: `command` field contains this substring.
+ *          entry (kind="json-key" or "agent-hook"): `command` field
+ *          contains this substring.
+ * @property {string} [vendorKey] - For kind="agent-hook" (#1240):
+ *          AGENT_REGISTRY key whose `agentHook` spec drives the walk.
+ *          The remover dispatches to the per-shape merger via this key
+ *          rather than inlining the shape data here, so the registry
+ *          stays static even as the per-shape merger logic evolves.
  */
 
 /**
@@ -284,6 +368,31 @@ export const ARTIFACT_REGISTRY = Object.freeze([
     displayPath: "~/.claude/settings.local.json",
     commandFingerprint: SESSION_HOOK_FINGERPRINT,
   }),
+
+  // ── Cohort agent-hook artifacts (#1240) ────────────────────────────
+  //
+  // One descriptor per cohort vendor whose `agentHook` spec is non-null
+  // in the agent registry. Each descriptor's `kind: "agent-hook"`
+  // routes the uninstaller to `removers/agent-hooks.mjs`, which uses
+  // the `vendorKey` to look up the per-shape walk in the agent
+  // registry. The cohort hooks live under `~/.<vendor>/...` (user
+  // scope), so all four are scope: "global".
+  //
+  // These descriptors are derived (filter+map) rather than hand-typed
+  // so the catalog cannot drift from `agent-registry.mjs`'s `agentHook`
+  // data. The agent registry is the single source of truth for
+  // per-vendor hook configuration; this is just its uninstall index.
+  ...AGENT_REGISTRY.filter((entry) => entry.agentHook !== null).map((entry) =>
+    Object.freeze({
+      id: `agent-hook-${entry.key}`,
+      scope: "global",
+      kind: "agent-hook",
+      pathFn: entry.agentHook.pathFn,
+      displayPath: entry.agentHook.displayPath,
+      commandFingerprint: AGENT_HOOK_FINGERPRINT,
+      vendorKey: entry.key,
+    }),
+  ),
 ]);
 
 /**