@codyswann/lisa 2.119.0 → 2.121.0

package/scripts/generate-copilot-plugin-artifacts.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/**
+ * Generate the GitHub Copilot variant of a Lisa plugin from the built Claude
+ * artifact.
+ *
+ * Copilot reads `.claude-plugin/plugin.json` as a documented fallback (per its
+ * manifest lookup order: plugin.json → .plugin/ → .github/plugin/ →
+ * .claude-plugin/). The Copilot variant keeps the `.claude-plugin/` manifest
+ * but rewrites hook event names to Copilot's camelCase convention
+ * (`preToolUse`, `agentStop`, etc.) and strips hooks that don't have a Copilot
+ * equivalent (SubagentStart entries — Copilot lacks the event).
+ *
+ * Per the Wave 1 audit, Copilot ships:
+ *   block-no-verify.sh, inject-rules.sh (conservative default — conditional on
+ *   the rules-auto-load probe), notify-ntfy.sh, install-pkgs.sh, setup-jira-cli.sh.
+ *
+ * Per the Wave 2 pattern-b-fan-out-spec.md, this generator runs four pre-flight
+ * probes when `copilot` is on PATH and caches the results. When `copilot` is
+ * not on PATH (CI builds, contributors without Copilot), the cached values are
+ * used; absent cache values fall through to conservative defaults.
+ *
+ * Usage: node scripts/generate-copilot-plugin-artifacts.mjs <source-plugin-dir> <out-dir> <version>
+ *
+ * @module scripts/generate-copilot-plugin-artifacts
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  filterHooksForAgent,
+  filterScriptsForAgent,
+} from "./lib/per-agent-hook-filter.mjs";
+
+const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+const POLICY_PATH = path.join(
+  REPO_ROOT,
+  "scripts",
+  "internal-copilot-skill-policy.json"
+);
+const PROBE_CACHE_PATH = path.join(
+  REPO_ROOT,
+  "scripts",
+  "internal-copilot-runtime-probe.json"
+);
+
+/**
+ * @returns {{ denylist?: string[] }}
+ */
+function readPolicy() {
+  if (!fs.existsSync(POLICY_PATH)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(POLICY_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Read cached Copilot runtime probe results.
+ *
+ * Fields documented in pattern-b-fan-out-spec.md §Pre-flight probes:
+ *   - pluginRootEnvVar: e.g. "COPILOT_PLUGIN_ROOT" or null (use absolute paths)
+ *   - rulesAutoLoads: boolean — Copilot reads plugin's rules/ natively
+ *   - agentPathOverrideAccepted: boolean — manifest agents:"agents/" accepts non-.agent.md
+ *   - cliVersion: string for invalidation
+ *
+ * @returns {{ pluginRootEnvVar?: string|null, rulesAutoLoads?: boolean, agentPathOverrideAccepted?: boolean, cliVersion?: string }}
+ */
+function readProbeCache() {
+  if (!fs.existsSync(PROBE_CACHE_PATH)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(PROBE_CACHE_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Recursive directory copy with optional path-level filter.
+ *
+ * @param {string} src
+ * @param {string} dst
+ * @param {(relPath: string, stat: fs.Stats) => boolean} keep
+ */
+function copyDir(src, dst, keep = () => true) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dst, { recursive: true });
+  const walk = (current, rel) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const srcPath = path.join(current, entry.name);
+      const relPath = path.join(rel, entry.name);
+      const dstPath = path.join(dst, relPath);
+      const stat = fs.statSync(srcPath);
+      if (!keep(relPath, stat)) continue;
+      if (entry.isDirectory()) {
+        fs.mkdirSync(dstPath, { recursive: true });
+        walk(srcPath, relPath);
+      } else if (entry.isFile()) {
+        fs.copyFileSync(srcPath, dstPath);
+      }
+    }
+  };
+  walk(src, "");
+}
+
+/**
+ * Generate the Copilot variant.
+ *
+ * @param {string} srcDir Built Claude plugin directory (input).
+ * @param {string} outDir Copilot variant output directory.
+ * @param {string} version Version string for the manifest.
+ */
+export function generateCopilotVariant(srcDir, outDir, version) {
+  if (!fs.existsSync(path.join(srcDir, ".claude-plugin", "plugin.json"))) {
+    return;
+  }
+
+  const policy = readPolicy();
+  const denylist = new Set(policy.denylist ?? []);
+  const probe = readProbeCache();
+
+  // Conservative defaults for any probe value not in cache:
+  //   - rulesAutoLoads: false (ship inject-rules.sh, accept potential double-load
+  //     until empirically refuted by the probe — same as the Wave 1 audit's default)
+  //   - pluginRootEnvVar: null (use ${CLAUDE_PLUGIN_ROOT} in command strings; Copilot
+  //     may or may not honor it. Wave 3 verify-by-run resolves this.)
+  //   - agentPathOverrideAccepted: false (rename agents/*.md to *.agent.md in the variant
+  //     to be safe; if the override works, this is harmless extra renaming)
+  const copilotRulesAutoLoads = probe.rulesAutoLoads === true;
+  const renameAgentsToAgentMd = probe.agentPathOverrideAccepted !== true;
+
+  fs.rmSync(outDir, { recursive: true, force: true });
+  fs.mkdirSync(outDir, { recursive: true });
+
+  // 1. Copy source minus .codex-plugin/ and apply skill denylist.
+  copyDir(srcDir, outDir, relPath => {
+    if (relPath.startsWith(".codex-plugin/") || relPath === ".codex-plugin")
+      return false;
+    // Drop Codex-specific per-skill openai.yaml artifacts — Copilot does not use them.
+    if (/^skills\/[^/]+\/agents\/openai\.ya?ml$/.test(relPath)) return false;
+    const skillsPrefix = path.join("skills") + path.sep;
+    if (relPath.startsWith(skillsPrefix)) {
+      const skillName = relPath.slice(skillsPrefix.length).split(path.sep)[0];
+      if (denylist.has(skillName)) return false;
+    }
+    return true;
+  });
+
+  // 1a. Remove any now-empty `skills/<n>/agents/` directories left by the openai.yaml strip.
+  const skillsDirForCleanup = path.join(outDir, "skills");
+  if (fs.existsSync(skillsDirForCleanup)) {
+    for (const skillName of fs.readdirSync(skillsDirForCleanup)) {
+      const agentsDir = path.join(skillsDirForCleanup, skillName, "agents");
+      if (fs.existsSync(agentsDir) && fs.readdirSync(agentsDir).length === 0) {
+        fs.rmdirSync(agentsDir);
+      }
+    }
+  }
+
+  // 2. Rename agents/<n>.md to agents/<n>.agent.md (per Copilot's default convention).
+  //    This is the safe-default path; if the manifest agents-path override probe
+  //    returns positive, this rename is unnecessary but harmless.
+  if (renameAgentsToAgentMd) {
+    const agentsDir = path.join(outDir, "agents");
+    if (fs.existsSync(agentsDir)) {
+      for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+        if (
+          entry.isFile() &&
+          entry.name.endsWith(".md") &&
+          !entry.name.endsWith(".agent.md")
+        ) {
+          const oldPath = path.join(agentsDir, entry.name);
+          const newName = entry.name.replace(/\.md$/, ".agent.md");
+          const newPath = path.join(agentsDir, newName);
+          fs.renameSync(oldPath, newPath);
+        }
+      }
+    }
+  }
+
+  // 3. Read + filter the manifest, translate event names to Copilot camelCase.
+  const manifestPath = path.join(outDir, ".claude-plugin", "plugin.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  manifest.version = version;
+  const filteredHooks = filterHooksForAgent(manifest.hooks ?? {}, "copilot", {
+    copilotRulesAutoLoads,
+  });
+  if (filteredHooks) {
+    manifest.hooks = filteredHooks;
+  } else {
+    delete manifest.hooks;
+  }
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+
+  // 4. Filter the hooks/ directory.
+  const hooksDir = path.join(outDir, "hooks");
+  if (fs.existsSync(hooksDir)) {
+    const all = fs
+      .readdirSync(hooksDir, { withFileTypes: true })
+      .filter(e => e.isFile() && e.name.endsWith(".sh"))
+      .map(e => e.name);
+    // Copilot ships everything Cursor ships, plus inject-rules.sh when
+    // copilotRulesAutoLoads is false. The filter helper handles this.
+    const keep = new Set(filterScriptsForAgent(all, "copilot"));
+    // If the rules-auto-load probe is positive, ALSO strip inject-rules.sh.
+    if (copilotRulesAutoLoads) keep.delete("inject-rules.sh");
+    for (const name of all) {
+      if (!keep.has(name)) fs.rmSync(path.join(hooksDir, name));
+    }
+    if (fs.readdirSync(hooksDir).length === 0) {
+      fs.rmdirSync(hooksDir);
+    }
+  }
+}
+
+// CLI entrypoint.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [srcDir, outDir, version] = process.argv.slice(2);
+  if (!srcDir || !outDir || !version) {
+    console.error(
+      "Usage: generate-copilot-plugin-artifacts.mjs <src> <out> <version>"
+    );
+    process.exit(1);
+  }
+  generateCopilotVariant(srcDir, outDir, version);
+  console.log(`Generated Copilot variant at ${outDir} (v${version})`);
+}

package/scripts/generate-cursor-plugin-artifacts.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * Generate the Cursor variant of a Lisa plugin from the built Claude artifact.
+ *
+ * Cursor reads `.claude-plugin/plugin.json` natively via its dual-namespace
+ * loader (also accepts `.cursor-plugin/plugin.json`). The Cursor variant
+ * therefore keeps the `.claude-plugin/` manifest but filters the hooks block
+ * to drop `inject-rules.sh` (Cursor auto-loads `rules/` from plugins natively,
+ * so shipping the polyfill would double-inject), `enforce-team-first.sh`
+ * (Claude-team-specific), and the `entire hooks claude-code *` analytics calls
+ * (Claude-only).
+ *
+ * The variant's `hooks/` directory mirrors the surviving script ship-list.
+ *
+ * Usage: node scripts/generate-cursor-plugin-artifacts.mjs <source-plugin-dir> <out-dir> <version>
+ *
+ * Where:
+ *   source-plugin-dir: path to the built Claude plugin (e.g. plugins/lisa/)
+ *   out-dir: path to write the Cursor variant (e.g. plugins/lisa-cursor/)
+ *   version: version string injected into the manifest
+ *
+ * @module scripts/generate-cursor-plugin-artifacts
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  filterHooksForAgent,
+  filterScriptsForAgent,
+} from "./lib/per-agent-hook-filter.mjs";
+
+const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+const POLICY_PATH = path.join(
+  REPO_ROOT,
+  "scripts",
+  "internal-cursor-skill-policy.json"
+);
+
+/**
+ * Read the per-agent skill policy file. Missing-policy is treated as
+ * "ship all skills" (no denylist).
+ *
+ * @returns {{ denylist?: string[] }}
+ */
+function readPolicy() {
+  if (!fs.existsSync(POLICY_PATH)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(POLICY_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Recursive directory copy with optional path-level filter.
+ *
+ * @param {string} src
+ * @param {string} dst
+ * @param {(relPath: string, stat: fs.Stats) => boolean} keep
+ */
+function copyDir(src, dst, keep = () => true) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dst, { recursive: true });
+  const walk = (current, rel) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const srcPath = path.join(current, entry.name);
+      const relPath = path.join(rel, entry.name);
+      const dstPath = path.join(dst, relPath);
+      const stat = fs.statSync(srcPath);
+      if (!keep(relPath, stat)) continue;
+      if (entry.isDirectory()) {
+        fs.mkdirSync(dstPath, { recursive: true });
+        walk(srcPath, relPath);
+      } else if (entry.isFile()) {
+        fs.copyFileSync(srcPath, dstPath);
+      }
+    }
+  };
+  walk(src, "");
+}
+
+/**
+ * Generate the Cursor variant.
+ *
+ * @param {string} srcDir Built Claude plugin directory (input).
+ * @param {string} outDir Cursor variant output directory.
+ * @param {string} version Version string for the manifest.
+ */
+export function generateCursorVariant(srcDir, outDir, version) {
+  if (!fs.existsSync(path.join(srcDir, ".claude-plugin", "plugin.json"))) {
+    return; // base plugin has no manifest; nothing to do
+  }
+
+  const policy = readPolicy();
+  const denylist = new Set(policy.denylist ?? []);
+
+  fs.rmSync(outDir, { recursive: true, force: true });
+  fs.mkdirSync(outDir, { recursive: true });
+
+  // 1. Copy the source plugin, applying the skill denylist filter.
+  copyDir(srcDir, outDir, relPath => {
+    // Drop the `.codex-plugin/` directory — Cursor does not consume it.
+    if (relPath.startsWith(".codex-plugin/") || relPath === ".codex-plugin")
+      return false;
+    // Drop Codex-specific per-skill openai.yaml artifacts — Cursor does not use them.
+    // These live at skills/<n>/agents/openai.yaml and are generated by the Codex
+    // artifact builder; the per-agent variants ship only the SKILL.md.
+    if (/^skills\/[^/]+\/agents\/openai\.ya?ml$/.test(relPath)) return false;
+    // Apply the per-agent skill denylist (skills/<name>/).
+    const skillsPrefix = path.join("skills") + path.sep;
+    if (relPath.startsWith(skillsPrefix)) {
+      const skillName = relPath.slice(skillsPrefix.length).split(path.sep)[0];
+      if (denylist.has(skillName)) return false;
+    }
+    return true;
+  });
+
+  // 1a. Remove any now-empty `skills/<n>/agents/` directories left by the openai.yaml strip.
+  const skillsDir = path.join(outDir, "skills");
+  if (fs.existsSync(skillsDir)) {
+    for (const skillName of fs.readdirSync(skillsDir)) {
+      const agentsDir = path.join(skillsDir, skillName, "agents");
+      if (fs.existsSync(agentsDir) && fs.readdirSync(agentsDir).length === 0) {
+        fs.rmdirSync(agentsDir);
+      }
+    }
+  }
+
+  // 2. Read + filter the manifest.
+  const manifestPath = path.join(outDir, ".claude-plugin", "plugin.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  manifest.version = version;
+  const filteredHooks = filterHooksForAgent(manifest.hooks ?? {}, "cursor");
+  if (filteredHooks) {
+    manifest.hooks = filteredHooks;
+  } else {
+    delete manifest.hooks;
+  }
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+
+  // 3. Filter the hooks/ directory to match the script ship-list.
+  const hooksDir = path.join(outDir, "hooks");
+  if (fs.existsSync(hooksDir)) {
+    const all = fs
+      .readdirSync(hooksDir, { withFileTypes: true })
+      .filter(e => e.isFile() && e.name.endsWith(".sh"))
+      .map(e => e.name);
+    const keep = new Set(filterScriptsForAgent(all, "cursor"));
+    for (const name of all) {
+      if (!keep.has(name)) fs.rmSync(path.join(hooksDir, name));
+    }
+    // Remove empty hooks dir.
+    if (fs.readdirSync(hooksDir).length === 0) {
+      fs.rmdirSync(hooksDir);
+    }
+  }
+}
+
+// CLI entrypoint.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [srcDir, outDir, version] = process.argv.slice(2);
+  if (!srcDir || !outDir || !version) {
+    console.error(
+      "Usage: generate-cursor-plugin-artifacts.mjs <src> <out> <version>"
+    );
+    process.exit(1);
+  }
+  generateCursorVariant(srcDir, outDir, version);
+  console.log(`Generated Cursor variant at ${outDir} (v${version})`);
+}

package/scripts/internal-agy-skill-policy.json

@@ -0,0 +1,3 @@
+{
+  "denylist": []
+}

package/scripts/internal-copilot-runtime-probe.json

@@ -0,0 +1,7 @@
+{
+  "_comment": "Cached Copilot runtime probe results. Updated by Wave 3 verification probes (Task #17) and consumed by scripts/generate-copilot-plugin-artifacts.mjs. Missing values fall through to conservative defaults.",
+  "cliVersion": null,
+  "pluginRootEnvVar": null,
+  "rulesAutoLoads": null,
+  "agentPathOverrideAccepted": null
+}

package/scripts/internal-copilot-skill-policy.json

@@ -0,0 +1,3 @@
+{
+  "denylist": []
+}

package/scripts/internal-cursor-skill-policy.json

@@ -0,0 +1,3 @@
+{
+  "denylist": []
+}

package/scripts/lib/per-agent-hook-filter.mjs

@@ -0,0 +1,249 @@
+/**
+ * Per-agent hook ship/strip filter for Pattern B plugin variant generators.
+ *
+ * Implements the per-agent ship-list from
+ * wiki/architecture/lisa-hook-per-agent-ship-list.md (Wave 1 audit).
+ *
+ * Each Pattern B per-agent plugin variant generator imports `filterHooksForAgent`
+ * to walk the source plugin's hook block and the on-disk hook scripts, returning
+ * an agent-appropriate filtered set.
+ *
+ * Agent strategies:
+ *   - Claude: keep everything (this module is not invoked for the Claude variant)
+ *   - Codex: ship universal + SubagentStart (handled by the Codex generator's own
+ *     ship list — this module is not invoked for Codex; Codex uses the existing
+ *     generate-codex-plugin-artifacts.mjs path)
+ *   - Cursor: strip inject-rules.sh (Cursor auto-loads rules/ natively), strip
+ *     Claude-team-specific scripts and `entire hooks claude-code *` calls
+ *   - agy: ship NOTHING (agy plugin hooks do not fire in -p mode per verified-by-run)
+ *   - Copilot: strip SubagentStart hooks (event missing), strip Claude-team-specific
+ *     scripts, conditionally strip inject-rules.sh if the rules-auto-load probe is
+ *     positive (caller passes copilotRulesAutoLoads via options)
+ *
+ * @module scripts/lib/per-agent-hook-filter
+ */
+
+/** Per-script applicability rules from the Wave 1 audit. */
+const SCRIPT_RULES = {
+  "block-no-verify.sh": {
+    claude: true,
+    codex: true,
+    cursor: true,
+    agy: false,
+    copilot: true,
+  },
+  "enforce-team-first.sh": {
+    claude: true,
+    codex: false,
+    cursor: false,
+    agy: false,
+    copilot: false,
+  },
+  "inject-rules.sh": {
+    claude: true,
+    codex: true,
+    cursor: false, // collision: Cursor auto-loads rules/ natively
+    agy: false, // hooks don't fire in -p
+    copilot: true, // conservative default; conditionally stripped if rules-auto-load probe positive
+  },
+  "inject-flow-context.sh": {
+    claude: true,
+    codex: true,
+    cursor: false, // SubagentStart unverified on Cursor; conservative default
+    agy: false,
+    copilot: false, // Copilot lacks SubagentStart event
+  },
+  "install-pkgs.sh": {
+    claude: true,
+    codex: true,
+    cursor: true,
+    agy: false,
+    copilot: true,
+  },
+  "notify-ntfy.sh": {
+    claude: true,
+    codex: true,
+    cursor: true,
+    agy: false,
+    copilot: true,
+  },
+  "setup-jira-cli.sh": {
+    claude: true,
+    codex: true,
+    cursor: true,
+    agy: false,
+    copilot: true,
+  },
+  // Unregistered scripts — exclude by default until classified.
+  "ticket-sync-reminder.sh": {
+    claude: false,
+    codex: false,
+    cursor: false,
+    agy: false,
+    copilot: false,
+  },
+  "track-plan-sessions.sh": {
+    claude: false,
+    codex: false,
+    cursor: false,
+    agy: false,
+    copilot: false,
+  },
+};
+
+/** Universal exclude pattern: development helpers. */
+const SCRIPT_EXCLUDE_PATTERNS = [/debug/i];
+
+/** Hook command shape: { type: "command", command: "..." } */
+const isEntireClaudeCodeCommand = cmd =>
+  typeof cmd === "string" &&
+  /^command -v entire >\/dev\/null 2>&1 && entire hooks claude-code /.test(cmd);
+
+const scriptNameFromCommand = cmd => {
+  if (typeof cmd !== "string") return null;
+  const match = /\$\{CLAUDE_PLUGIN_ROOT\}\/hooks\/([^/\s]+\.sh)/.exec(cmd);
+  return match ? match[1] : null;
+};
+
+/**
+ * Translate Claude PascalCase event names to a target agent's native casing.
+ *
+ * Per the Wave 1 audit's Wave 3 contract step 4 + step 6:
+ *   - Cursor: keep PascalCase (loader auto-normalizes)
+ *   - Codex: keep PascalCase
+ *   - Copilot: rewrite to lowercase / camelCase per Copilot's docs
+ *
+ * @param {string} eventName Claude event name (e.g. "PreToolUse")
+ * @param {"cursor"|"agy"|"copilot"} agent Target agent slug
+ * @returns {string} Translated event name
+ */
+export function translateEventName(eventName, agent) {
+  if (agent !== "copilot") return eventName;
+  const COPILOT_EVENTS = {
+    PreToolUse: "preToolUse",
+    PostToolUse: "postToolUse",
+    SessionStart: "sessionStart",
+    SessionEnd: "sessionEnd",
+    UserPromptSubmit: "userPromptSubmitted",
+    Stop: "agentStop",
+    SubagentStart: "subagentStart", // not supported but include for symmetry
+    SubagentStop: "subagentStop",
+  };
+  return COPILOT_EVENTS[eventName] ?? eventName;
+}
+
+/**
+ * Whether a script ships to the given agent under the Wave 1 audit ship-list.
+ *
+ * Falls through to true (ship) for scripts not in the rules table — the
+ * conservative default for unknown scripts is to include them; explicit
+ * exclusions live in SCRIPT_RULES.
+ *
+ * @param {string} scriptName e.g. "inject-rules.sh"
+ * @param {"claude"|"codex"|"cursor"|"agy"|"copilot"} agent
+ * @returns {boolean}
+ */
+export function shouldShipScript(scriptName, agent) {
+  // Universal exclude (debug helpers etc.)
+  if (SCRIPT_EXCLUDE_PATTERNS.some(re => re.test(scriptName))) return false;
+  const rules = SCRIPT_RULES[scriptName];
+  if (!rules) return true;
+  return Boolean(rules[agent]);
+}
+
+/**
+ * Whether a hook command entry ships to the given agent.
+ *
+ * Three classes of hook commands:
+ *   1. `entire hooks claude-code *` — Claude-only, strip for everyone else
+ *   2. `${CLAUDE_PLUGIN_ROOT}/hooks/<script>` — ship per script rules
+ *   3. Anything else — ship by default (rare; conservative)
+ *
+ * @param {{ type: string, command: string }} hook
+ * @param {string} eventName
+ * @param {"cursor"|"agy"|"copilot"|"codex"} agent
+ * @param {{ copilotRulesAutoLoads?: boolean }} [opts]
+ * @returns {boolean}
+ */
+export function shouldShipHook(hook, _eventName, agent, opts = {}) {
+  if (!hook || typeof hook.command !== "string") return false;
+  const { command } = hook;
+
+  // entire calls are Claude-only.
+  if (isEntireClaudeCodeCommand(command)) return false;
+
+  // Script reference: look up per-script rules.
+  const scriptName = scriptNameFromCommand(command);
+  if (scriptName) {
+    // Cursor collision rule for rules + Copilot conditional rules strip
+    if (scriptName === "inject-rules.sh") {
+      if (agent === "cursor") return false;
+      if (agent === "agy") return false;
+      if (agent === "copilot" && opts.copilotRulesAutoLoads === true)
+        return false;
+    }
+    return shouldShipScript(scriptName, agent);
+  }
+
+  // Anything else (rare) — ship by default
+  return true;
+}
+
+/**
+ * Filter the plugin's hook block for a target agent and translate event names.
+ *
+ * Returns the new hook block (or undefined when the block ends up empty after
+ * filtering, which means the manifest should omit the hooks field entirely).
+ *
+ * For agy this function returns undefined regardless of input because agy
+ * variants ship no hooks.
+ *
+ * @param {Record<string, Array<{ matcher?: string, hooks: Array<object> }>>} hookBlock
+ *   The Claude-format hook block from .claude-plugin/plugin.json.
+ * @param {"cursor"|"agy"|"copilot"|"codex"} agent
+ * @param {{ copilotRulesAutoLoads?: boolean }} [opts]
+ * @returns {Record<string, Array<{ matcher?: string, hooks: Array<object> }>> | undefined}
+ */
+export function filterHooksForAgent(hookBlock, agent, opts = {}) {
+  if (agent === "agy") return undefined;
+  if (!hookBlock || typeof hookBlock !== "object") return undefined;
+
+  /** @type {Record<string, Array<{ matcher?: string, hooks: Array<object> }>>} */
+  const out = {};
+
+  for (const [claudeEventName, entries] of Object.entries(hookBlock)) {
+    if (!Array.isArray(entries)) continue;
+    const filteredEntries = [];
+    for (const entry of entries) {
+      const handlerArray = entry?.hooks;
+      if (!Array.isArray(handlerArray)) continue;
+      const filteredHandlers = handlerArray.filter(h =>
+        shouldShipHook(h, claudeEventName, agent, opts)
+      );
+      if (filteredHandlers.length > 0) {
+        filteredEntries.push({ ...entry, hooks: filteredHandlers });
+      }
+    }
+    if (filteredEntries.length > 0) {
+      const translated = translateEventName(claudeEventName, agent);
+      out[translated] = filteredEntries;
+    }
+  }
+
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Walk a hooks/ directory and return the list of script filenames that should
+ * ship to the agent. Scripts referenced by no surviving hook entry are
+ * naturally excluded by callers (they should call this to enumerate files
+ * to keep AFTER filtering the manifest).
+ *
+ * @param {string[]} scriptFilenames Filenames found in hooks/
+ * @param {"cursor"|"agy"|"copilot"|"codex"} agent
+ * @returns {string[]}
+ */
+export function filterScriptsForAgent(scriptFilenames, agent) {
+  if (agent === "agy") return [];
+  return scriptFilenames.filter(name => shouldShipScript(name, agent));
+}