@hasna/skills 0.10.55 → 0.10.57

package/bin/mcp.js

@@ -20019,7 +20019,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.55",
+    version: "0.10.57",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -50788,6 +50788,97 @@ function read(path, changes) {
     throw new Error(`Unsupported or oversized native discovery input: ${path}`);
   return readFileSync15(path, "utf8");
 }
+function assertReviewedClaudeCacheClosures(home, config2, review) {
+  const enabledIds = Object.entries(config2.enabledPlugins ?? {}).filter(([, enabled]) => enabled === true).map(([id]) => id);
+  if (enabledIds.length === 0)
+    return;
+  const registryPath = join26(home, ".claude/plugins/installed_plugins.json");
+  const cacheRoot = join26(home, ".claude/plugins/cache");
+  const registryText = read(registryPath);
+  if (registryText === null)
+    return;
+  const registry2 = parseConfig(registryText, registryPath);
+  if (registry2.version !== 2 || !registry2.plugins || typeof registry2.plugins !== "object" || Array.isArray(registry2.plugins))
+    throw new Error("Reviewed Claude installed plugin registrations are invalid");
+  const cachePath = (path) => typeof path === "string" && isAbsolute15(path) && resolve17(path) === path && (path === cacheRoot || path.startsWith(cacheRoot + sep6));
+  const activeRoots = new Set;
+  for (const id of enabledIds) {
+    const rows = registry2.plugins[id];
+    if (rows === undefined)
+      continue;
+    if (!Array.isArray(rows))
+      throw new Error("Reviewed Claude enabled plugin registrations must be an array");
+    for (const row of rows) {
+      if (!row || typeof row !== "object" || Array.isArray(row) || typeof row.installPath !== "string") {
+        throw new Error("Reviewed Claude enabled plugin registration requires an object with an installPath string");
+      }
+      if (typeof row.installPath === "string" && (row.installPath === cacheRoot || row.installPath.startsWith(cacheRoot + sep6))) {
+        if (!cachePath(row.installPath) || row.installPath.length > AGENT_POLICY_LIMITS.pathCharacters || row.version !== undefined && (typeof row.version !== "string" || basename9(row.installPath) !== row.version)) {
+          throw new Error("Reviewed Claude discovery has a malformed active cache registration");
+        }
+        if (row.scope === "user" && (row.projectPath === undefined || row.projectPath === null)) {} else if (row.scope === "project" && typeof row.projectPath === "string" && isAbsolute15(row.projectPath) && resolve17(row.projectPath) === row.projectPath && row.projectPath.length <= AGENT_POLICY_LIMITS.pathCharacters) {} else
+          throw new Error("Reviewed Claude discovery has an unsupported active cache registration scope");
+        activeRoots.add(row.installPath);
+      }
+    }
+  }
+  if (activeRoots.size === 0)
+    return;
+  const registrySource = review.sources.find((source) => source.path === registryPath && source.sha256 !== null && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined && (source.hashMode === undefined || source.hashMode === "bytes"));
+  if (!registrySource)
+    throw new Error("Reviewed Claude discovery must bind installed registrations for active cache plugins");
+  const reviewedFile = (path, manifest = false) => review.sources.some((source) => source.path === path && source.sha256 !== null && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined && (source.hashMode === undefined || source.hashMode === "bytes" || manifest && source.hashMode === "claude-plugin-manifest-v1"));
+  const requireSource = (path, description, manifest = false) => {
+    if (!reviewedFile(path, manifest))
+      throw new Error(`Reviewed active Claude cache plugin ${description} is not bound`);
+  };
+  for (const root of activeRoots) {
+    safe4(root);
+    const rootStat = lstatSync18(root, { throwIfNoEntry: false });
+    if (!rootStat?.isDirectory() || realpathSync5(root) !== root)
+      throw new Error("Reviewed Claude active cache plugin root is missing or unsafe");
+    const manifestPath = join26(root, ".claude-plugin/plugin.json");
+    const manifestStat = lstatSync18(manifestPath, { throwIfNoEntry: false });
+    let manifest;
+    if (manifestStat) {
+      if (!manifestStat.isFile())
+        throw new Error("Reviewed active Claude cache plugin manifest is unsupported");
+      requireSource(manifestPath, "manifest", true);
+      const raw = read(manifestPath);
+      if (raw === null)
+        throw new Error("Reviewed Claude active cache plugin manifest is missing");
+      manifest = JSON.parse(raw);
+      if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        throw new Error("Reviewed Claude active cache plugin manifest is invalid");
+    } else if (!review.sources.some((source) => source.path === manifestPath && source.hashMode === "path-bytes" && source.sha256 !== null && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined)) {
+      throw new Error("Reviewed Claude active cache plugin manifest absence requires a path-bytes witness");
+    }
+    const roots = new Set([join26(root, "skills")]);
+    if (lstatSync18(join26(root, "SKILL.md"), { throwIfNoEntry: false })?.isFile())
+      roots.add(root);
+    const declared = manifest?.skills === undefined ? ["./skills"] : typeof manifest.skills === "string" ? [manifest.skills] : manifest.skills;
+    if (!Array.isArray(declared) || declared.some((path) => typeof path !== "string"))
+      throw new Error("Reviewed Claude active cache plugin has unsupported skill paths");
+    for (const value of declared) {
+      const path = resolve17(root, value);
+      if (path !== root && !path.startsWith(root + sep6))
+        throw new Error("Reviewed Claude active cache plugin skill path escapes its root");
+      roots.add(path.endsWith(`${sep6}SKILL.md`) ? dirname16(path) : path);
+    }
+    for (const skillRoot of roots)
+      if (!review.roots.includes(skillRoot))
+        throw new Error("Reviewed Claude active cache plugin skill root is not covered");
+    const hooksPath = join26(root, "hooks/hooks.json");
+    const hooksStat = lstatSync18(hooksPath, { throwIfNoEntry: false });
+    if (hooksStat) {
+      if (!hooksStat.isFile())
+        throw new Error("Reviewed Claude plugin hook manifest is unsupported");
+      requireSource(hooksPath, "hook manifest");
+    }
+    if (typeof manifest?.hooks === "string")
+      requireSource(resolve17(root, manifest.hooks), "manifest-declared hook source");
+  }
+}
 function projectNativeDiscoveryFields(text2, format, fields2, path) {
   const object7 = format === "yaml" ? parseHermesConfig(text2) : parseConfig(text2, path, format === "toml");
   if (!object7 || typeof object7 !== "object" || Array.isArray(object7))
@@ -51254,6 +51345,8 @@ function resolveAgentDiscovery(options) {
           throw new Error("Reviewed Claude plugin manifest requires separately reviewed exact hook file sources");
       return { path: source.path, sha256: manifestSha256, hashMode: "claude-plugin-manifest-v1" };
     });
+    if (agent === "claude")
+      assertReviewedClaudeCacheClosures(home, config2, review);
     const combined = [...reviewedSources, ...reviewedSourcesWithManifestProjection];
     const unique = combined.filter((source, index) => combined.findIndex((candidate) => isDeepStrictEqual4(candidate, source)) === index);
     return { ...supplied, roots: [...new Set([...roots, ...supplied.roots])].sort(), sources: unique, ...agent === "gemini" ? { builtinNames } : {} };

package/bin/migrate.js

@@ -25,7 +25,7 @@ import { join as join5 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.55",
+  version: "0.10.57",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/server.js

@@ -24140,7 +24140,7 @@ restoreLaunchCwd();
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.55",
+  version: "0.10.57",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

@@ -24143,7 +24143,7 @@ import { randomUUID as randomUUID6 } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.55",
+  version: "0.10.57",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/index.d.ts

@@ -65,6 +65,8 @@ export type { ClaudeManagedHookProjection, ClaudeManagedHookProjectionOptions }
 export { captureDiscoveryDirectories, captureDiscoveryByteSources, captureDiscoveryPathSources, DISCOVERY_ROOT_UNRESOLVED, isDiscoveryRootUnresolved, type DiscoveryDirectory, type DiscoveryExecutable, type DiscoverySource } from "./lib/agent-discovery.js";
 export { captureClaudeMarketplaceRegistry, captureClaudeMarketplaceRegistryV2 } from "./lib/claude-marketplace-registry.js";
 export { captureClaudeMarketplaceEntry, hashClaudeMarketplaceEntry, CLAUDE_MARKETPLACE_ENTRY_HASH_MODE, type ClaudeMarketplaceEntrySelector, type ClaudeMarketplaceEntryWitness } from "./lib/claude-marketplace-entry-witness.js";
+export { captureClaudeProspectiveCandidateClosure } from "./lib/claude-prospective-review.js";
+export { hashClaudePluginManifest } from "./lib/claude-plugin-manifest-witness.js";
 export { captureClaudeSettings, captureClaudeSettingsV2, captureClaudeSettingsV3, captureClaudeSettingsV4, upgradeClaudeSettingsWitness, upgradeClaudeSettingsWitnessV4 } from "./lib/claude-settings-witness.js";
 export { buildPluginProjection, pluginTreeDigest, type PluginProjectionManifest, type PluginPayloadMapping, type PluginFileWitness } from "./lib/plugin-projection.js";
 export { planPluginAdmission, admitPlugin, resolveAdmittedPlugin, pluginResolverCommand, type PluginAdmissionTarget, type PluginAdmissionBinding, type PluginAdmissionPrincipal, type PluginAdmissionPlan, type PluginAdmissionIdentity, type PluginBundleIdentity, type PluginRoutingIdentity, type PluginAdmissionReceipt } from "./lib/plugin-admission.js";

package/dist/index.js

@@ -11833,7 +11833,7 @@ function replaceSkillSession(expected, replacement, plan, options = {}, beforeCo
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.55",
+  version: "0.10.57",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -20693,6 +20693,97 @@ function read2(path, changes) {
     throw new Error(`Unsupported or oversized native discovery input: ${path}`);
   return readFileSync20(path, "utf8");
 }
+function assertReviewedClaudeCacheClosures(home, config, review) {
+  const enabledIds = Object.entries(config.enabledPlugins ?? {}).filter(([, enabled]) => enabled === true).map(([id]) => id);
+  if (enabledIds.length === 0)
+    return;
+  const registryPath = join32(home, ".claude/plugins/installed_plugins.json");
+  const cacheRoot = join32(home, ".claude/plugins/cache");
+  const registryText = read2(registryPath);
+  if (registryText === null)
+    return;
+  const registry = parseConfig(registryText, registryPath);
+  if (registry.version !== 2 || !registry.plugins || typeof registry.plugins !== "object" || Array.isArray(registry.plugins))
+    throw new Error("Reviewed Claude installed plugin registrations are invalid");
+  const cachePath = (path) => typeof path === "string" && isAbsolute21(path) && resolve20(path) === path && (path === cacheRoot || path.startsWith(cacheRoot + sep8));
+  const activeRoots = new Set;
+  for (const id of enabledIds) {
+    const rows = registry.plugins[id];
+    if (rows === undefined)
+      continue;
+    if (!Array.isArray(rows))
+      throw new Error("Reviewed Claude enabled plugin registrations must be an array");
+    for (const row of rows) {
+      if (!row || typeof row !== "object" || Array.isArray(row) || typeof row.installPath !== "string") {
+        throw new Error("Reviewed Claude enabled plugin registration requires an object with an installPath string");
+      }
+      if (typeof row.installPath === "string" && (row.installPath === cacheRoot || row.installPath.startsWith(cacheRoot + sep8))) {
+        if (!cachePath(row.installPath) || row.installPath.length > AGENT_POLICY_LIMITS.pathCharacters || row.version !== undefined && (typeof row.version !== "string" || basename11(row.installPath) !== row.version)) {
+          throw new Error("Reviewed Claude discovery has a malformed active cache registration");
+        }
+        if (row.scope === "user" && (row.projectPath === undefined || row.projectPath === null)) {} else if (row.scope === "project" && typeof row.projectPath === "string" && isAbsolute21(row.projectPath) && resolve20(row.projectPath) === row.projectPath && row.projectPath.length <= AGENT_POLICY_LIMITS.pathCharacters) {} else
+          throw new Error("Reviewed Claude discovery has an unsupported active cache registration scope");
+        activeRoots.add(row.installPath);
+      }
+    }
+  }
+  if (activeRoots.size === 0)
+    return;
+  const registrySource = review.sources.find((source) => source.path === registryPath && source.sha256 !== null && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined && (source.hashMode === undefined || source.hashMode === "bytes"));
+  if (!registrySource)
+    throw new Error("Reviewed Claude discovery must bind installed registrations for active cache plugins");
+  const reviewedFile = (path, manifest = false) => review.sources.some((source) => source.path === path && source.sha256 !== null && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined && (source.hashMode === undefined || source.hashMode === "bytes" || manifest && source.hashMode === "claude-plugin-manifest-v1"));
+  const requireSource = (path, description, manifest = false) => {
+    if (!reviewedFile(path, manifest))
+      throw new Error(`Reviewed active Claude cache plugin ${description} is not bound`);
+  };
+  for (const root2 of activeRoots) {
+    safe4(root2);
+    const rootStat = lstatSync25(root2, { throwIfNoEntry: false });
+    if (!rootStat?.isDirectory() || realpathSync11(root2) !== root2)
+      throw new Error("Reviewed Claude active cache plugin root is missing or unsafe");
+    const manifestPath = join32(root2, ".claude-plugin/plugin.json");
+    const manifestStat = lstatSync25(manifestPath, { throwIfNoEntry: false });
+    let manifest;
+    if (manifestStat) {
+      if (!manifestStat.isFile())
+        throw new Error("Reviewed active Claude cache plugin manifest is unsupported");
+      requireSource(manifestPath, "manifest", true);
+      const raw = read2(manifestPath);
+      if (raw === null)
+        throw new Error("Reviewed Claude active cache plugin manifest is missing");
+      manifest = JSON.parse(raw);
+      if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        throw new Error("Reviewed Claude active cache plugin manifest is invalid");
+    } else if (!review.sources.some((source) => source.path === manifestPath && source.hashMode === "path-bytes" && source.sha256 !== null && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined)) {
+      throw new Error("Reviewed Claude active cache plugin manifest absence requires a path-bytes witness");
+    }
+    const roots = new Set([join32(root2, "skills")]);
+    if (lstatSync25(join32(root2, "SKILL.md"), { throwIfNoEntry: false })?.isFile())
+      roots.add(root2);
+    const declared = manifest?.skills === undefined ? ["./skills"] : typeof manifest.skills === "string" ? [manifest.skills] : manifest.skills;
+    if (!Array.isArray(declared) || declared.some((path) => typeof path !== "string"))
+      throw new Error("Reviewed Claude active cache plugin has unsupported skill paths");
+    for (const value of declared) {
+      const path = resolve20(root2, value);
+      if (path !== root2 && !path.startsWith(root2 + sep8))
+        throw new Error("Reviewed Claude active cache plugin skill path escapes its root");
+      roots.add(path.endsWith(`${sep8}SKILL.md`) ? dirname20(path) : path);
+    }
+    for (const skillRoot of roots)
+      if (!review.roots.includes(skillRoot))
+        throw new Error("Reviewed Claude active cache plugin skill root is not covered");
+    const hooksPath = join32(root2, "hooks/hooks.json");
+    const hooksStat = lstatSync25(hooksPath, { throwIfNoEntry: false });
+    if (hooksStat) {
+      if (!hooksStat.isFile())
+        throw new Error("Reviewed Claude plugin hook manifest is unsupported");
+      requireSource(hooksPath, "hook manifest");
+    }
+    if (typeof manifest?.hooks === "string")
+      requireSource(resolve20(root2, manifest.hooks), "manifest-declared hook source");
+  }
+}
 function projectNativeDiscoveryFields(text2, format, fields2, path) {
   const object6 = format === "yaml" ? parseHermesConfig(text2) : parseConfig(text2, path, format === "toml");
   if (!object6 || typeof object6 !== "object" || Array.isArray(object6))
@@ -21281,6 +21372,8 @@ function resolveAgentDiscovery(options) {
           throw new Error("Reviewed Claude plugin manifest requires separately reviewed exact hook file sources");
       return { path: source.path, sha256: manifestSha256, hashMode: "claude-plugin-manifest-v1" };
     });
+    if (agent === "claude")
+      assertReviewedClaudeCacheClosures(home, config, review);
     const combined = [...reviewedSources, ...reviewedSourcesWithManifestProjection];
     const unique = combined.filter((source, index) => combined.findIndex((candidate2) => isDeepStrictEqual7(candidate2, source)) === index);
     return { ...supplied, roots: [...new Set([...roots, ...supplied.roots])].sort(), sources: unique, ...agent === "gemini" ? { builtinNames } : {} };
@@ -48250,6 +48343,89 @@ async function reconcileSkillSession(input2, options = {}) {
   const result = replaceSkillSession(skillSessionSnapshotBinding(snapshot2), replacement, { ...plan, planDigest }, options, () => assertPlanWindow(issuedAt, expiresAt, (options.now ?? Date.now)()));
   return { applied: true, plan, planDigest, ...result };
 }
+// src/lib/claude-prospective-review.ts
+import { createHash as createHash35 } from "crypto";
+import { lstatSync as lstatSync28, readFileSync as readFileSync30, readdirSync as readdirSync17, realpathSync as realpathSync15 } from "fs";
+import { basename as basename14, dirname as dirname30, isAbsolute as isAbsolute26, join as join44, relative as relative12, resolve as resolve27, sep as sep15 } from "path";
+var MAX_CANDIDATE_FILES = 16384;
+var MAX_CANDIDATE_BYTES = 256 * 1024 * 1024;
+var sha6 = (data) => createHash35("sha256").update(data).digest("hex");
+function refuse4(reason2) {
+  throw new Error(`CLAUDE_CANDIDATE_REVIEW_REFUSED: ${reason2}`);
+}
+var GENERATED_MARKETPLACE_TIME = Object.freeze({ $generated: "claude-utc-timestamp", field: "known-marketplaces.lastUpdated" });
+var GENERATED_FRESH_PLUGIN_INSTALLED_AT = Object.freeze({ $generated: "claude-utc-timestamp", field: "installed_plugins.fresh-row.installedAt" });
+var GENERATED_PLUGIN_UPDATE_TIME = Object.freeze({ $generated: "claude-utc-timestamp", field: "installed_plugins.selected-row.lastUpdated" });
+function abs(path, name) {
+  if (typeof path !== "string" || !path || path.length > 4096 || /[\x00-\x1f\x7f]/.test(path) || !isAbsolute26(path) || resolve27(path) !== path)
+    refuse4(`${name} must be a normalized absolute path`);
+}
+function safeFile(path, name) {
+  abs(path, name);
+  for (let at = dirname30(path);; at = dirname30(at)) {
+    const stat3 = lstatSync28(at, { throwIfNoEntry: false });
+    if (!stat3?.isDirectory() || stat3.isSymbolicLink())
+      refuse4(`${name} traverses a symlink or non-directory`);
+    if (at === dirname30(at))
+      break;
+  }
+  const stat2 = lstatSync28(path, { throwIfNoEntry: false });
+  if (!stat2?.isFile() || stat2.isSymbolicLink() || stat2.size > MAX_CANDIDATE_BYTES)
+    refuse4(`${name} is not a bounded regular file`);
+  return readFileSync30(path);
+}
+function canonicalDir(path, name) {
+  abs(path, name);
+  if (realpathSync15(path) !== path || !lstatSync28(path).isDirectory())
+    refuse4(`${name} is not a canonical directory`);
+  for (let at = path;; at = dirname30(at)) {
+    const stat2 = lstatSync28(at);
+    if (!stat2.isDirectory() || stat2.isSymbolicLink())
+      refuse4(`${name} traverses a symlink`);
+    if (at === dirname30(at))
+      break;
+  }
+}
+function captureClaudeProspectiveCandidateClosure(root2) {
+  canonicalDir(root2, "candidate root");
+  const entries = [];
+  let bytes = 0;
+  const walk2 = (directory2) => {
+    const beforeDirectory = lstatSync28(directory2);
+    const names = readdirSync17(directory2).sort();
+    if (new Set(names).size !== names.length)
+      refuse4("candidate contains ambiguous directory entries");
+    for (const name of names) {
+      if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\") || /[\x00-\x1f\x7f]/.test(name))
+        refuse4("candidate contains an unsupported path member");
+      const path = join44(directory2, name), rel = relative12(root2, path).split(sep15).join("/");
+      if (entries.length >= MAX_CANDIDATE_FILES)
+        refuse4("candidate closure exceeds its member limit");
+      const stat2 = lstatSync28(path);
+      if (stat2.isSymbolicLink())
+        refuse4("candidate closure contains a symlink");
+      if (stat2.isDirectory()) {
+        entries.push([rel, "directory", null]);
+        walk2(path);
+      } else if (stat2.isFile()) {
+        bytes += stat2.size;
+        if (bytes > MAX_CANDIDATE_BYTES)
+          refuse4("candidate closure exceeds its byte limit");
+        const content = safeFile(path, "candidate member"), after = lstatSync28(path);
+        if (!after.isFile() || after.dev !== stat2.dev || after.ino !== stat2.ino || after.size !== stat2.size || after.mtimeMs !== stat2.mtimeMs || after.ctimeMs !== stat2.ctimeMs)
+          refuse4("candidate member changed while being read");
+        entries.push([rel, "file", sha6(content)]);
+      } else
+        refuse4("candidate closure contains a special file");
+    }
+    const afterDirectory = lstatSync28(directory2);
+    if (!afterDirectory.isDirectory() || afterDirectory.dev !== beforeDirectory.dev || afterDirectory.ino !== beforeDirectory.ino || afterDirectory.mtimeMs !== beforeDirectory.mtimeMs || afterDirectory.ctimeMs !== beforeDirectory.ctimeMs)
+      refuse4("candidate directory changed while being read");
+  };
+  walk2(root2);
+  entries.sort((a, b) => a[0].localeCompare(b[0]));
+  return sha6(JSON.stringify(entries));
+}
 export {
   writeStationSnapshot,
   writeStationHydration,
@@ -48390,6 +48566,7 @@ export {
   inspectPrivatePublication,
   importSkillsLocalSnapshot,
   homePathFor,
+  hashClaudePluginManifest,
   hashClaudeMarketplaceEntry,
   getToolPrimitive,
   getStorageStatus,
@@ -48473,6 +48650,7 @@ export {
   captureClaudeSettingsV3,
   captureClaudeSettingsV2,
   captureClaudeSettings,
+  captureClaudeProspectiveCandidateClosure,
   captureClaudeMarketplaceRegistryV2,
   captureClaudeMarketplaceRegistry,
   captureClaudeMarketplaceEntry,

package/dist/lib/agent-integration.d.ts

@@ -99,6 +99,8 @@ export interface AgentIntegrationPlan {
 }
 /** Normalize only the verified OS prefix, never hide user-controlled links. */
 export declare function canonicalSystemPath(path: string): string;
+export declare function canonicalAgentPath(path: string, aliases: AgentRootAlias[]): string;
+export declare function recheckRootAliases(aliases: AgentRootAlias[]): void;
 /** Parse the reviewed exact-target binding used by native migration. Paths are
  * deliberately project-relative so a manifest cannot silently select another
  * checkout when a project root changes. */

package/dist/lib/claude-prospective-review.d.ts

@@ -0,0 +1,140 @@
+import { type ReviewedDiscoveryInputs } from "./agent-discovery.js";
+export declare const CLAUDE_PROSPECTIVE_REVIEW_SCHEMA: "skills.claude-plugin-prospective-review/v1";
+export interface ClaudeProspectiveReviewRequest {
+    schema: typeof CLAUDE_PROSPECTIVE_REVIEW_SCHEMA;
+    scope: {
+        kind: "user" | "project";
+        projectPath: string;
+    };
+    native: {
+        home: string;
+        executable: {
+            path: string;
+            target: string;
+            version: string;
+            sha256: string;
+        };
+        configRoot: string;
+        pluginRoot: string;
+    };
+    skills: {
+        dataDir: string;
+        policySha256: string;
+        discoverySha256: string;
+        discoveryInputs: ReviewedDiscoveryInputs;
+    };
+    candidate: {
+        marketplace: string;
+        root: string;
+        catalogPath: string;
+        catalogSha256: string;
+        closureSha256: string;
+        plugins: Array<{
+            plugin: string;
+            manifestPath: string;
+            manifestSha256: string;
+            optionsPatch: Record<string, unknown>;
+        }>;
+        releaseManifest?: {
+            path: string;
+            sha256: string;
+        };
+        functionHooksEnv?: "1";
+    };
+    preimages: {
+        settings: {
+            path: string;
+            sha256: string | null;
+        };
+        userSettings: {
+            path: string;
+            sha256: string | null;
+        };
+        projectSettings: {
+            path: string;
+            sha256: string | null;
+        };
+        projectSettingsLocal: {
+            path: string;
+            sha256: string | null;
+        };
+        marketplaces: {
+            path: string;
+            sha256: string | null;
+        };
+        installedPlugins: {
+            path: string;
+            sha256: string | null;
+        };
+    };
+    /** Complete semantic documents expected after native adoption. The one
+     * timestamps generated by Claude for the owned marketplace and registration
+     * rows use exact typed field markers documented below; every other field is
+     * concrete. */
+    delta: {
+        settingsAfter: Record<string, unknown>;
+        knownMarketplacesAfter: Record<string, unknown>;
+        installedPluginsAfter: Record<string, unknown>;
+    };
+    review: {
+        pluginHooks: "reviewed-no-skill-injection";
+    };
+}
+export interface ClaudeProspectiveReviewReceipt {
+    schema: typeof CLAUDE_PROSPECTIVE_REVIEW_SCHEMA;
+    accepted: true;
+    applied: false;
+    scope: ClaudeProspectiveReviewRequest["scope"];
+    pluginIds: string[];
+    native: {
+        executablePath: string;
+        executableTarget: string;
+        executableVersion: string;
+        executableSha256: string;
+        configRoot: string;
+        pluginRoot: string;
+    };
+    candidate: {
+        marketplace: string;
+        plugins: Array<{
+            plugin: string;
+            pluginId: string;
+            manifestSha256: string;
+            optionsPatchSha256: string;
+        }>;
+        closureSha256: string;
+        catalogSha256: string;
+        releaseManifest?: {
+            path: string;
+            sha256: string;
+        };
+    };
+    targetSettingsPath: string;
+    skillsDiscoverySha256: string;
+    requestFileSha256: string;
+    semanticDocumentsSha256: string;
+    operationSha256: string;
+    expectedPostStateSha256: string;
+    preimages: Array<{
+        name: string;
+        path: string;
+        sha256: string | null;
+    }>;
+    ownedDelta: {
+        settingsEnabledPlugins: string[];
+        selectedPluginOptions: string[];
+        functionHooksEnv: string | null;
+        knownMarketplace: string;
+        installedPlugins: string[];
+        unrelatedGraph: "preserved-by-complete-semantic-documents";
+    };
+    identityPrecondition: "Harnesses must resolve the installed Claude home/config/plugin roots and executable path/version/hash plus the installed Skills data directory through their package-owned consumers, then compare every value before trusting this receipt; this validator checks supplied paths and current bytes only and does not establish actual consumer identity";
+    reviewPrecondition: "The caller's no-skill-injection assessment is bound to the raw request hash; structural checks are not semantic hook review, and Harnesses must retain its existing review record and verify the exact candidate binding";
+    limitation: "validation-only; native installer atomicity and crash recovery are not established";
+}
+/** Fingerprint every file byte and directory name under the frozen candidate.
+ * Symlinks and special files refuse; the digest binds the complete closure. */
+export declare function captureClaudeProspectiveCandidateClosure(root: string): string;
+/** Validate a frozen candidate review against the current filesystem. This is
+ * intentionally a planner only: its receipt is not native-install authority. */
+export declare function reviewClaudeProspectiveCandidate(request: ClaudeProspectiveReviewRequest, requestFileSha256: string): ClaudeProspectiveReviewReceipt;

package/dist/sdk/index.js

@@ -32373,7 +32373,7 @@ var init_event_sink = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.55",
+  version: "0.10.57",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -43533,6 +43533,97 @@ function read2(path, changes) {
     throw new Error(`Unsupported or oversized native discovery input: ${path}`);
   return readFileSync15(path, "utf8");
 }
+function assertReviewedClaudeCacheClosures(home, config, review) {
+  const enabledIds = Object.entries(config.enabledPlugins ?? {}).filter(([, enabled]) => enabled === true).map(([id2]) => id2);
+  if (enabledIds.length === 0)
+    return;
+  const registryPath = join26(home, ".claude/plugins/installed_plugins.json");
+  const cacheRoot = join26(home, ".claude/plugins/cache");
+  const registryText = read2(registryPath);
+  if (registryText === null)
+    return;
+  const registry = parseConfig(registryText, registryPath);
+  if (registry.version !== 2 || !registry.plugins || typeof registry.plugins !== "object" || Array.isArray(registry.plugins))
+    throw new Error("Reviewed Claude installed plugin registrations are invalid");
+  const cachePath = (path) => typeof path === "string" && isAbsolute20(path) && resolve19(path) === path && (path === cacheRoot || path.startsWith(cacheRoot + sep6));
+  const activeRoots = new Set;
+  for (const id2 of enabledIds) {
+    const rows = registry.plugins[id2];
+    if (rows === undefined)
+      continue;
+    if (!Array.isArray(rows))
+      throw new Error("Reviewed Claude enabled plugin registrations must be an array");
+    for (const row of rows) {
+      if (!row || typeof row !== "object" || Array.isArray(row) || typeof row.installPath !== "string") {
+        throw new Error("Reviewed Claude enabled plugin registration requires an object with an installPath string");
+      }
+      if (typeof row.installPath === "string" && (row.installPath === cacheRoot || row.installPath.startsWith(cacheRoot + sep6))) {
+        if (!cachePath(row.installPath) || row.installPath.length > AGENT_POLICY_LIMITS.pathCharacters || row.version !== undefined && (typeof row.version !== "string" || basename9(row.installPath) !== row.version)) {
+          throw new Error("Reviewed Claude discovery has a malformed active cache registration");
+        }
+        if (row.scope === "user" && (row.projectPath === undefined || row.projectPath === null)) {} else if (row.scope === "project" && typeof row.projectPath === "string" && isAbsolute20(row.projectPath) && resolve19(row.projectPath) === row.projectPath && row.projectPath.length <= AGENT_POLICY_LIMITS.pathCharacters) {} else
+          throw new Error("Reviewed Claude discovery has an unsupported active cache registration scope");
+        activeRoots.add(row.installPath);
+      }
+    }
+  }
+  if (activeRoots.size === 0)
+    return;
+  const registrySource = review.sources.find((source) => source.path === registryPath && source.sha256 !== null && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined && (source.hashMode === undefined || source.hashMode === "bytes"));
+  if (!registrySource)
+    throw new Error("Reviewed Claude discovery must bind installed registrations for active cache plugins");
+  const reviewedFile = (path, manifest = false) => review.sources.some((source) => source.path === path && source.sha256 !== null && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined && (source.hashMode === undefined || source.hashMode === "bytes" || manifest && source.hashMode === "claude-plugin-manifest-v1"));
+  const requireSource = (path, description, manifest = false) => {
+    if (!reviewedFile(path, manifest))
+      throw new Error(`Reviewed active Claude cache plugin ${description} is not bound`);
+  };
+  for (const root2 of activeRoots) {
+    safe4(root2);
+    const rootStat = lstatSync21(root2, { throwIfNoEntry: false });
+    if (!rootStat?.isDirectory() || realpathSync9(root2) !== root2)
+      throw new Error("Reviewed Claude active cache plugin root is missing or unsafe");
+    const manifestPath = join26(root2, ".claude-plugin/plugin.json");
+    const manifestStat = lstatSync21(manifestPath, { throwIfNoEntry: false });
+    let manifest;
+    if (manifestStat) {
+      if (!manifestStat.isFile())
+        throw new Error("Reviewed active Claude cache plugin manifest is unsupported");
+      requireSource(manifestPath, "manifest", true);
+      const raw = read2(manifestPath);
+      if (raw === null)
+        throw new Error("Reviewed Claude active cache plugin manifest is missing");
+      manifest = JSON.parse(raw);
+      if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        throw new Error("Reviewed Claude active cache plugin manifest is invalid");
+    } else if (!review.sources.some((source) => source.path === manifestPath && source.hashMode === "path-bytes" && source.sha256 !== null && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined)) {
+      throw new Error("Reviewed Claude active cache plugin manifest absence requires a path-bytes witness");
+    }
+    const roots = new Set([join26(root2, "skills")]);
+    if (lstatSync21(join26(root2, "SKILL.md"), { throwIfNoEntry: false })?.isFile())
+      roots.add(root2);
+    const declared = manifest?.skills === undefined ? ["./skills"] : typeof manifest.skills === "string" ? [manifest.skills] : manifest.skills;
+    if (!Array.isArray(declared) || declared.some((path) => typeof path !== "string"))
+      throw new Error("Reviewed Claude active cache plugin has unsupported skill paths");
+    for (const value of declared) {
+      const path = resolve19(root2, value);
+      if (path !== root2 && !path.startsWith(root2 + sep6))
+        throw new Error("Reviewed Claude active cache plugin skill path escapes its root");
+      roots.add(path.endsWith(`${sep6}SKILL.md`) ? dirname17(path) : path);
+    }
+    for (const skillRoot of roots)
+      if (!review.roots.includes(skillRoot))
+        throw new Error("Reviewed Claude active cache plugin skill root is not covered");
+    const hooksPath = join26(root2, "hooks/hooks.json");
+    const hooksStat = lstatSync21(hooksPath, { throwIfNoEntry: false });
+    if (hooksStat) {
+      if (!hooksStat.isFile())
+        throw new Error("Reviewed Claude plugin hook manifest is unsupported");
+      requireSource(hooksPath, "hook manifest");
+    }
+    if (typeof manifest?.hooks === "string")
+      requireSource(resolve19(root2, manifest.hooks), "manifest-declared hook source");
+  }
+}
 function projectNativeDiscoveryFields(text2, format, fields2, path) {
   const object6 = format === "yaml" ? parseHermesConfig(text2) : parseConfig(text2, path, format === "toml");
   if (!object6 || typeof object6 !== "object" || Array.isArray(object6))
@@ -44121,6 +44212,8 @@ function resolveAgentDiscovery(options) {
           throw new Error("Reviewed Claude plugin manifest requires separately reviewed exact hook file sources");
       return { path: source.path, sha256: manifestSha256, hashMode: "claude-plugin-manifest-v1" };
     });
+    if (agent === "claude")
+      assertReviewedClaudeCacheClosures(home, config, review);
     const combined = [...reviewedSources, ...reviewedSourcesWithManifestProjection];
     const unique = combined.filter((source, index) => combined.findIndex((candidate2) => isDeepStrictEqual6(candidate2, source)) === index);
     return { ...supplied, roots: [...new Set([...roots, ...supplied.roots])].sort(), sources: unique, ...agent === "gemini" ? { builtinNames } : {} };