skillrepo 4.0.0 → 4.1.0

package/src/lib/agent-hook-merge.mjs

@@ -0,0 +1,203 @@
+/**
+ * Cohort SessionStart-hook fan-out (#1240).
+ *
+ * Public API:
+ *
+ *   - `installAgentHookFor(vendorKey)` → install or refresh the hook
+ *     for one vendor.
+ *   - `uninstallAgentHookFor(vendorKey, options)` → strip the hook
+ *     from one vendor.
+ *   - `installAgentHooksForVendors({ vendors, io? })` → fan-out
+ *     wrapper that runs `installAgentHookFor` for each vendor and
+ *     aggregates results, mirroring `mcp-merge.mjs` for the cohort
+ *     session-hook flow.
+ *
+ * The dispatcher's job is to translate a registry vendorKey into the
+ * correct per-shape merger call. The merger choice is data-driven via
+ * `agent-registry.mjs`'s `agentHook.shape` field — adding a new shape
+ * is a registry edit + a new merger module + a new switch arm here.
+ *
+ * ## Why fan-out instead of a single `installAll()`
+ *
+ * The init flow only installs hooks for vendors the picker selected,
+ * not every vendor in the registry. A bare `installAll()` would
+ * install Cursor's hook for a user who picked only Gemini. The
+ * fan-out wrapper accepts the explicit vendor list so the call site
+ * (init step 6) decides scope.
+ *
+ * Per-vendor failures are NOT fatal to the fan-out: one broken hook
+ * config doesn't abort init. The result array reports each vendor's
+ * outcome so the caller can summarize and surface failures
+ * individually. Mirrors `mergeMcpForVendors`'s same-error contract.
+ */
+
+import { getAgentByKey } from "./agent-registry.mjs";
+import {
+  mergeClaudeShapeAgentHook,
+  unmergeClaudeShapeAgentHook,
+} from "./mergers/agent-hook-claude-shape.mjs";
+import {
+  mergeCursorShapeAgentHook,
+  unmergeCursorShapeAgentHook,
+} from "./mergers/agent-hook-cursor-shape.mjs";
+import { validationError } from "./errors.mjs";
+
+/**
+ * @typedef {Object} AgentHookInstallResult
+ * @property {string} vendorKey
+ * @property {string} displayName
+ * @property {string} path - User-facing path (e.g. `~/.cursor/hooks.json`).
+ * @property {"installed" | "updated" | "unchanged" | "failed"} action
+ * @property {string} [reason] - Present when action is "failed".
+ */
+
+/**
+ * @typedef {Object} AgentHookUninstallResult
+ * @property {string} vendorKey
+ * @property {string} displayName
+ * @property {string} path
+ * @property {"removed" | "would-remove" | "skipped" | "unchanged" | "failed"} action
+ * @property {string} [error] - Present when action is "skipped" due to
+ *           a parse error, or when action is "failed".
+ */
+
+/**
+ * Install the cohort SessionStart hook for one vendor. Throws
+ * `validationError` for unknown vendors or vendors whose `agentHook`
+ * is null (Claude Code, Windsurf, Cline). The dispatcher does NOT
+ * silently no-op on null: a caller asking to install a hook for a
+ * vendor with no spec is a programming error, and a silent no-op
+ * would mask it.
+ *
+ * @param {string} vendorKey
+ * @returns {{ path: string; action: "installed" | "updated" | "unchanged"; command: string }}
+ */
+export function installAgentHookFor(vendorKey) {
+  const entry = requireRegistryEntryWithHook(vendorKey, "install");
+  switch (entry.agentHook.shape) {
+    case "claude-shape":
+      return mergeClaudeShapeAgentHook({ vendorKey });
+    case "cursor-shape":
+      return mergeCursorShapeAgentHook({ vendorKey });
+    default:
+      // The agent-registry typedef caps `shape` to the known set;
+      // hitting this branch means a registry author added a new shape
+      // value without wiring a merger. Surface the gap loudly.
+      throw validationError(
+        `Unknown agentHook.shape "${entry.agentHook.shape}" for vendor "${vendorKey}". Wire a merger in agent-hook-merge.mjs.`,
+      );
+  }
+}
+
+/**
+ * Uninstall the cohort SessionStart hook for one vendor. See
+ * `installAgentHookFor` for the validation contract.
+ *
+ * @param {string} vendorKey
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false]
+ * @returns {{ path: string; action: "removed" | "would-remove" | "skipped" | "unchanged"; error?: string }}
+ */
+export function uninstallAgentHookFor(vendorKey, { dryRun = false } = {}) {
+  const entry = requireRegistryEntryWithHook(vendorKey, "uninstall");
+  switch (entry.agentHook.shape) {
+    case "claude-shape":
+      return unmergeClaudeShapeAgentHook({ vendorKey, dryRun });
+    case "cursor-shape":
+      return unmergeCursorShapeAgentHook({ vendorKey, dryRun });
+    default:
+      throw validationError(
+        `Unknown agentHook.shape "${entry.agentHook.shape}" for vendor "${vendorKey}". Wire a remover in agent-hook-merge.mjs.`,
+      );
+  }
+}
+
+/**
+ * Fan-out installer for an explicit list of vendor keys. Used by init
+ * step 6's cohort sibling. Vendors without an `agentHook` spec
+ * (Claude Code, Windsurf, Cline) are silently skipped — they're a
+ * deliberate registry classification, not a caller error. Truly
+ * unknown vendor keys are NOT silently skipped: they surface as
+ * `action: "failed"` so a typo in `--agent` doesn't hide.
+ *
+ * @param {object} options
+ * @param {string[]} options.vendors - Canonical vendor keys.
+ * @returns {AgentHookInstallResult[]}
+ */
+export function installAgentHooksForVendors({ vendors }) {
+  if (!Array.isArray(vendors)) {
+    throw validationError(
+      "installAgentHooksForVendors: vendors must be an array of canonical agent keys.",
+    );
+  }
+
+  // Dedupe to avoid running the merger twice on a caller that built a
+  // vendor list with a duplicate (e.g. a future `--agent agents,gemini`
+  // expansion). Set preserves first-seen order.
+  const uniqueVendors = Array.from(new Set(vendors));
+  const results = [];
+
+  for (const vendorKey of uniqueVendors) {
+    const entry = getAgentByKey(vendorKey);
+    if (!entry) {
+      // Unknown key. Don't silently skip — that hides typos. Surface
+      // as a failure with a clear reason.
+      results.push({
+        vendorKey,
+        displayName: vendorKey,
+        path: "(unknown)",
+        action: "failed",
+        reason: `Unknown agent key: ${vendorKey}`,
+      });
+      continue;
+    }
+    if (!entry.agentHook) {
+      // Deliberate skip: Claude Code uses the legacy session-hook;
+      // Windsurf and Cline are deferred per the agent-registry
+      // docstring. Skipping silently is correct.
+      continue;
+    }
+
+    try {
+      const r = installAgentHookFor(vendorKey);
+      results.push({
+        vendorKey,
+        displayName: entry.displayName,
+        path: r.path,
+        action: r.action,
+      });
+    } catch (err) {
+      results.push({
+        vendorKey,
+        displayName: entry.displayName,
+        path: entry.agentHook.displayPath,
+        action: "failed",
+        reason: err?.message ?? String(err),
+      });
+    }
+  }
+
+  return results;
+}
+
+// ── Internals ─────────────────────────────────────────────────────
+
+function requireRegistryEntryWithHook(vendorKey, verb) {
+  const entry = getAgentByKey(vendorKey);
+  if (!entry) {
+    throw validationError(
+      `Cannot ${verb} cohort hook for unknown agent: ${vendorKey}.`,
+    );
+  }
+  if (!entry.agentHook) {
+    throw validationError(
+      `Cannot ${verb} cohort hook for "${vendorKey}" — no agentHook spec.`,
+      {
+        hint:
+          "Claude Code uses the legacy session-hook (mergers/session-hook.mjs); " +
+          "Windsurf and Cline are deferred (#1239 epic).",
+      },
+    );
+  }
+  return entry;
+}

package/src/lib/agent-registry.mjs

@@ -4,8 +4,9 @@
  * 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), and orphan sweeps all derive their
- * vendor lists from this registry.
+ * 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.
@@ -46,6 +47,44 @@
  *           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).
@@ -53,9 +92,30 @@
  * @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({
@@ -70,6 +130,14 @@ export const AGENT_REGISTRY = Object.freeze([
     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" }),
@@ -83,6 +151,23 @@ export const AGENT_REGISTRY = 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
@@ -100,6 +185,13 @@ export const AGENT_REGISTRY = 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
@@ -115,6 +207,41 @@ export const AGENT_REGISTRY = 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" }),
@@ -128,6 +255,27 @@ export const AGENT_REGISTRY = 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
@@ -144,6 +292,12 @@ export const AGENT_REGISTRY = 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.
@@ -159,6 +313,36 @@ export const AGENT_REGISTRY = Object.freeze([
     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

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,
+    }),
+  ),
 ]);
 
 /**

package/src/lib/fs-utils.mjs

@@ -87,7 +87,22 @@ export function writeFileAtomic(filePath, content, { mode } = {}) {
     throw new Error(`${filePath} is a directory, expected a file`);
   }
 
-  const tmpPath = `${filePath}.tmp`;
+  // Per-process unique temp suffix prevents two concurrent writers
+  // (e.g. a SessionStart hook firing `skillrepo update --silent` while
+  // the user runs `skillrepo uninstall --global`) from writing to the
+  // same `.tmp` path and producing non-deterministic final content.
+  // The cohort SessionStart hooks (#1240) made this race observable
+  // in production: hook configs at user-scope can be touched by both
+  // the hook runner and the uninstaller simultaneously.
+  //
+  // `process.pid` plus a `Math.random()` token gives uniqueness across
+  // processes AND across rapid same-process re-entrant writes. The
+  // token is base-36 chars from a 64-bit float — collision probability
+  // between siblings within the rename window is astronomically low.
+  // No cryptographic strength required: this is a temp-file suffix,
+  // not a security boundary.
+  const uniqueSuffix = `${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
+  const tmpPath = `${filePath}.${uniqueSuffix}.tmp`;
   try {
     writeFileSync(tmpPath, content, "utf-8");
   } catch (err) {