skillrepo 4.0.0 → 4.2.0

package/src/commands/update.mjs

@@ -21,6 +21,22 @@
  *                    command behaves as before (exit non-zero on
  *                    network / auth / disk failures).
  *
+ * v4.1.0 silent mode (#1240):
+ *   --silent         Suppress stdout: write `{}` on success, propagate
+ *                    failures (non-zero exit) with the error on stderr.
+ *                    Used by the per-agent SessionStart hooks (Cursor,
+ *                    Gemini CLI, Codex CLI, VS Code + Copilot) the
+ *                    cohort installer writes via `npx --yes skillrepo
+ *                    update --silent`. Gemini CLI specifically requires
+ *                    hook stdout to be valid JSON; the empty `{}`
+ *                    satisfies that. Distinct from `--session-hook` —
+ *                    `--silent` does NOT suppress error exit codes,
+ *                    because none of the cohort agents block session
+ *                    start on non-zero hook exits the way Claude Code
+ *                    does. If primary-source evidence later shows a
+ *                    cohort vendor DOES block, give that vendor its
+ *                    own contract flag rather than widening this one.
+ *
  * Exit codes are inherited from sync.mjs / http.mjs error types,
  * EXCEPT under `--session-hook` — see the flag's contract below.
  */
@@ -62,14 +78,12 @@ import {
  */
 export async function runUpdate(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
-  // `stderr` is not used directly — the session-hook path pipes to
-  // BLACK_HOLE_STREAM and the normal path forwards `io` to runSync
-  // which reads `io.stderr` itself.
+  const stderr = io.stderr ?? process.stderr;
 
-  // ── Pre-pass: detect --session-hook BEFORE resolveFlags runs ─────
+  // ── Pre-pass: detect --session-hook / --silent BEFORE resolveFlags runs ─
   //
-  // resolveFlags can throw in three categories we must catch under
-  // session-hook mode:
+  // resolveFlags can throw in three categories the wrapping mode must
+  // catch:
   //   - `authError` when no access key is configured (e.g., session
   //     fires before `skillrepo init` has run — a real first-run
   //     scenario, not synthetic)
@@ -78,15 +92,27 @@ export async function runUpdate(argv, io = {}) {
   //
   // All three happen INSIDE resolveFlags, before our try/catch block
   // could see them if we called it after. The only robust answer is
-  // to detect --session-hook without invoking resolveFlags, then
-  // wrap resolveFlags + runSync together in the error handler.
+  // to detect the mode flags without invoking resolveFlags, then wrap
+  // resolveFlags + runSync together in the error handler.
   //
-  // A simple argv scan is safe here: `--session-hook` has no value
-  // argument, so a plain `.includes` match can't misinterpret
-  // positional args. This DOES NOT accept variations like
-  // `--session-hook=true` or `-SH` — single canonical form only,
-  // matching what the installer writes.
+  // A simple argv scan is safe here: neither flag takes a value, so a
+  // plain `.includes` match can't misinterpret positional args. This
+  // DOES NOT accept variations like `--session-hook=true` or `-S` —
+  // single canonical form only, matching what the installers write.
   const sessionHook = argv.includes("--session-hook");
+  const silent = argv.includes("--silent");
+
+  // Precedence: when both flags appear in argv, `--session-hook`
+  // wins because the order of the branches below dispatches it
+  // first. The session-hook path's `acceptPositional` accepts both
+  // flags so it doesn't reject `--silent` as unknown. The silent
+  // path only accepts `--silent` (different exit-code contract).
+  // Don't reorder these branches without coordinating with the two
+  // hook-installer paths in `commands/init-cohort-hooks.mjs` and
+  // `mergers/session-hook.mjs`. Practical exposure: zero — neither
+  // installer writes a hook command containing both flags. The
+  // precedence is defensive against a future code path or a manual
+  // user edit, not an active scenario.
 
   if (sessionHook) {
     // Session-hook mode: wrap EVERY error path in try/catch so a
@@ -94,10 +120,13 @@ export async function runUpdate(argv, io = {}) {
     try {
       const flags = resolveFlags(argv, {
         acceptPositional(arg) {
-          // resolveFlags sees --session-hook as unknown unless we
-          // consume it here. Kept for the non-error path — the
-          // real "catch errors" logic is the outer try.
+          // resolveFlags sees these as unknown unless we consume them
+          // here. Both flags are accepted because a future caller may
+          // combine them (defense — installers should pick one); the
+          // outer mode dispatch above already chose `session-hook` if
+          // present, so accepting `--silent` here is a no-op tolerance.
           if (arg === "--session-hook") return 1;
+          if (arg === "--silent") return 1;
           return false;
         },
       });
@@ -148,6 +177,58 @@ export async function runUpdate(argv, io = {}) {
     return;
   }
 
+  // ── Silent mode (#1240): cohort SessionStart hook contract ──────
+  //
+  // Used by Cursor / Gemini CLI / Codex CLI / VS Code + Copilot. Their
+  // SessionStart hook config invokes `npx --yes skillrepo update
+  // --silent`. Contract:
+  //
+  //   - stdout produces ONE valid-JSON line on success: `{}`. Gemini
+  //     CLI specifically requires hook stdout to be JSON; the empty
+  //     object is the minimal valid value that injects no model
+  //     context. Other vendors tolerate it.
+  //   - On failure, stdout writes nothing extra; the typed error
+  //     propagates through the dispatcher's catch which writes to
+  //     stderr and exits with the appropriate code. We do NOT write
+  //     `{}` on failure — partial JSON output alongside an error
+  //     message on stderr would mislead a hook runner that treats
+  //     stdout as model context.
+  //   - All sync progress lines (the "failed to persist last-sync
+  //     state" warning from sync.mjs, etc.) are routed to a black-hole
+  //     stdout so they cannot leak into the JSON expectation.
+  //
+  // Distinct from `--session-hook`. That mode is Claude-Code-specific
+  // and contracts "EXIT 0 ON ALL ERRORS" because Claude Code's hook
+  // runner blocks session start on non-zero exits. The cohort vendors
+  // handled here have no documented session-blocking behavior, so a
+  // failure should surface as a real exit code — the user can then
+  // investigate via `skillrepo update` directly.
+  if (silent) {
+    const flags = resolveFlags(argv, {
+      acceptPositional(arg) {
+        if (arg === "--silent") return 1;
+        return false;
+      },
+    });
+    const vendors = effectiveVendors(flags);
+    requireVendorTargets(vendors, "update");
+
+    await runSync({
+      serverUrl: flags.serverUrl,
+      apiKey: flags.apiKey,
+      vendors,
+      global: flags.global,
+      // sync.mjs surfaces non-fatal warnings (e.g. failed to persist
+      // last-sync state) via stderr; preserve that channel so a real
+      // operator running `update --silent` from a terminal can still
+      // see them. Stdout is the contract-bearing stream and stays
+      // black-hole until we emit `{}` ourselves.
+      io: { stdout: BLACK_HOLE_STREAM, stderr },
+    });
+    stdout.write("{}\n");
+    return;
+  }
+
   // ── Normal mode: original behavior ───────────────────────────────
   // Forward `io` to runSync so the non-fatal "failed to persist
   // last-sync state" warning lands on the injected stderr stream

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