@hasna/skills 0.10.92 → 0.10.93

package/bin/mcp.js

@@ -38,7 +38,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.92",
+    version: "0.10.93",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -36403,6 +36403,17 @@ var init_runtime_launcher = __esm(() => {
   PINNED_LAUNCHER_MAX_BYTES = 16 * 1024;
 });
 
+// src/lib/linux-access-acl.ts
+var LINUX_ACL_FREE_WHEN_UNSUPPORTED;
+var init_linux_access_acl = __esm(() => {
+  LINUX_ACL_FREE_WHEN_UNSUPPORTED = new Set([
+    0xef53n,
+    0x58465342n,
+    0x9123683en,
+    0x01021994n
+  ]);
+});
+
 // src/lib/retained-review-artifacts.ts
 import { createHash as createHash23 } from "crypto";
 import { constants as constants15, closeSync as closeSync17, fstatSync as fstatSync17, fsyncSync as fsyncSync4, lstatSync as lstatSync22, mkdirSync as mkdirSync6, openSync as openSync17, readSync as readSync11, writeSync as writeSync3 } from "fs";
@@ -36524,6 +36535,7 @@ var init_agent_integration = __esm(() => {
   init_claude_settings_witness();
   init_codex_hook_trust_files();
   init_runtime_launcher();
+  init_linux_access_acl();
   init_retained_review_artifacts();
 });
 
@@ -38806,8 +38818,8 @@ function resolveDiscovery(options, exclusion) {
   const configPath = exclusion?.nativeHome === undefined ? agentDiscoveryConfigPath(home, agent) : join33(nativeHome, agent === "codex" ? "config.toml" : "settings.json");
   const configText = witness(configPath, agent === "hermes" ? "yaml" : agent === "codex" ? "toml" : "json", agent === "hermes" ? ["skills", "plugins", "hooks"] : agent === "claude" ? ["enabledPlugins", "extraKnownMarketplaces"] : agent === "codex" ? [...CODEX_DISCOVERY_PROJECTION_FIELDS] : agent === "gemini" ? ["skills", "extensions", "security"] : agent === "opencode" ? ["plugin", "skills"] : agent === "sumi" ? [...SUMI_DISCOVERY_PROJECTION_FIELDS] : ["version"]);
   const config2 = configText === null ? {} : agent === "hermes" ? parseHermesConfig(configText) : parseConfig(configText, configPath, agent === "codex");
-  const unresolved = (detail) => {
-    throw new Error(`Native discovery is unresolved (${agent}: ${detail}); provide a reviewed --discovery-inputs file`);
+  const unresolved = (detail, source) => {
+    throw new NativeDiscoveryUnresolved(agent, detail, source);
   };
   let opaqueClosureVerified = false;
   const verifyOpaqueClosure = (declarations) => {
@@ -38821,6 +38833,17 @@ function resolveDiscovery(options, exclusion) {
     verifyDiscovery(retained, undefined, undefined, undefined, exclusion?.narrowed, canonical9(configPath));
     opaqueClosureVerified = true;
   };
+  const reviewRemedy = (source, check2) => {
+    try {
+      check2();
+    } catch (error61) {
+      if (error61 instanceof NativeDiscoveryUnresolved) {
+        error61.reviewable = true;
+        error61.source ??= source;
+      }
+      throw error61;
+    }
+  };
   if (exclusion) {
     if (configText !== null && agent !== "codex" && agent !== "hermes")
       parseNativeJsonObject(configText);
@@ -38892,7 +38915,7 @@ function resolveDiscovery(options, exclusion) {
         unresolved(`non-enumerable ${label} require a current settings review`);
     };
     if (hasHooks)
-      verifyCurrentOpaqueSettings("hooks");
+      reviewRemedy(canonical9(configPath), () => verifyCurrentOpaqueSettings("hooks"));
     if (agent === "claude") {
       if (config2.env !== undefined) {
         if (!object6(config2.env) || Object.keys(config2.env).length > 512)
@@ -38905,7 +38928,7 @@ function resolveDiscovery(options, exclusion) {
         if (hasFunctionHookEnvironment) {
           if (!["0", "1"].includes(config2.env.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS))
             unresolved("malformed Claude env.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS flag");
-          verifyCurrentOpaqueSettings("function-hook environment controls");
+          reviewRemedy(canonical9(configPath), () => verifyCurrentOpaqueSettings("function-hook environment controls"));
         }
       }
       if (config2.pluginConfigs !== undefined) {
@@ -38932,7 +38955,7 @@ function resolveDiscovery(options, exclusion) {
         }
         hasPluginConfigs = Object.keys(config2.pluginConfigs).length > 0;
         if (hasPluginConfigs)
-          verifyCurrentOpaqueSettings("plugin configurations");
+          reviewRemedy(canonical9(configPath), () => verifyCurrentOpaqueSettings("plugin configurations"));
       }
       if (config2.enabledPlugins !== undefined && !object6(config2.enabledPlugins))
         unresolved("enabledPlugins must be an object");
@@ -39044,7 +39067,7 @@ function resolveDiscovery(options, exclusion) {
     if (Object.keys(config2.enabledPlugins ?? config2.plugins ?? config2.extensions ?? {}).length > 512)
       unresolved("unbounded native registrations");
     if (hasHooks || hasPluginConfigs || hasFunctionHookEnvironment)
-      verifyOpaqueClosure([]);
+      reviewRemedy(canonical9(configPath), () => verifyOpaqueClosure([]));
   }
   if (options.reviewed && (options.reviewed.version !== 1 || !Array.isArray(options.reviewed.agents) || options.reviewed.agents.some((item) => !item || typeof item !== "object") || new Set(options.reviewed.agents.map((item) => item.agent)).size !== options.reviewed.agents.length))
     throw new Error("Invalid --discovery-inputs version or agents");
@@ -39297,40 +39320,41 @@ function resolveDiscovery(options, exclusion) {
     if (exclusion && Object.keys(manifest).some((key2) => /skill|plugin|hook|marketplace|extension|instruction/i.test(key2) && !["skills", "hooks"].includes(key2)))
       unresolved("unknown plugin discovery controls");
     const hooks = witness(join33(root, "hooks/hooks.json"));
-    if (manifest.hooks !== undefined || hooks !== null) {
-      if (!exclusion || exclusion.retained?.method !== "reviewed")
-        unresolved("plugin hooks require a separate no-skill-injection review");
-      const required2 = [manifestPath, ...hooks !== null ? [join33(root, "hooks/hooks.json")] : []];
-      const scoped = agent === "codex" && codex !== undefined ? [] : undefined;
-      if (manifest.hooks !== undefined) {
-        if (scoped && manifest.hooks && typeof manifest.hooks === "object" && !Array.isArray(manifest.hooks)) {
-          const inline = codexPluginHookHandlers(manifest.hooks);
-          if (!inline)
-            unresolved("unsupported inline plugin hooks");
-          scoped.push(inline);
-        } else {
-          if (typeof manifest.hooks !== "string")
-            unresolved("unsupported plugin hooks target");
-          const hook = resolve23(root, manifest.hooks);
-          if (!hook.startsWith(root + sep11))
-            unresolved("plugin hooks target escapes its root");
-          required2.push(hook);
-          if (scoped)
-            scoped.push(readCodexHookDeclaration(witness(hook), hook));
-        }
-      }
-      if (scoped && hooks !== null)
-        scoped.push(readCodexHookDeclaration(hooks, join33(root, "hooks/hooks.json")));
-      for (const path of required2) {
-        const saved = exclusion.retained.sources.filter((source) => source.path === canonical9(path) && source.sha256 !== null && source.format === undefined && source.fields === undefined);
-        if (saved.length ? saved.some((source) => projected(source, undefined, budget3) !== source.sha256) : !(scoped && reviewedInstalledCopy(root, path, codex)))
-          unresolved("plugin hooks require current independently reviewed sources");
-      }
-      if (scoped && scoped.every((item) => item !== null && item.commands === 0)) {
-        verifyCodexPluginHookClosure(root, codex, codex.source, new Set(scoped.flatMap((item) => [...item.servers])), required2.map((path) => canonical9(path)));
-      } else
-        verifyOpaqueClosure(required2.map((path) => canonical9(path)));
-    }
+    if (manifest.hooks !== undefined || hooks !== null)
+      reviewRemedy(canonical9(hooks !== null ? join33(root, "hooks/hooks.json") : manifestPath), () => {
+        if (!exclusion || exclusion.retained?.method !== "reviewed")
+          unresolved("plugin hooks require a separate no-skill-injection review");
+        const required2 = [manifestPath, ...hooks !== null ? [join33(root, "hooks/hooks.json")] : []];
+        const scoped = agent === "codex" && codex !== undefined ? [] : undefined;
+        if (manifest.hooks !== undefined) {
+          if (scoped && manifest.hooks && typeof manifest.hooks === "object" && !Array.isArray(manifest.hooks)) {
+            const inline = codexPluginHookHandlers(manifest.hooks);
+            if (!inline)
+              unresolved("unsupported inline plugin hooks");
+            scoped.push(inline);
+          } else {
+            if (typeof manifest.hooks !== "string")
+              unresolved("unsupported plugin hooks target");
+            const hook = resolve23(root, manifest.hooks);
+            if (!hook.startsWith(root + sep11))
+              unresolved("plugin hooks target escapes its root");
+            required2.push(hook);
+            if (scoped)
+              scoped.push(readCodexHookDeclaration(witness(hook), hook));
+          }
+        }
+        if (scoped && hooks !== null)
+          scoped.push(readCodexHookDeclaration(hooks, join33(root, "hooks/hooks.json")));
+        for (const path of required2) {
+          const saved = exclusion.retained.sources.filter((source) => source.path === canonical9(path) && source.sha256 !== null && source.format === undefined && source.fields === undefined);
+          if (saved.length ? saved.some((source) => projected(source, undefined, budget3) !== source.sha256) : !(scoped && reviewedInstalledCopy(root, path, codex)))
+            unresolved("plugin hooks require current independently reviewed sources", canonical9(path));
+        }
+        if (scoped && scoped.every((item) => item !== null && item.commands === 0)) {
+          verifyCodexPluginHookClosure(root, codex, codex.source, new Set(scoped.flatMap((item) => [...item.servers])), required2.map((path) => canonical9(path)));
+        } else
+          verifyOpaqueClosure(required2.map((path) => canonical9(path)));
+      });
     const commands = join33(root, "commands");
     safe6(commands);
     if (agent === "claude" && (manifest.commands !== undefined || lstatSync25(commands, { throwIfNoEntry: false })?.isDirectory() && entries(commands).length))
@@ -39440,7 +39464,7 @@ function resolveDiscovery(options, exclusion) {
     unresolved("native discovery roots exceed their bound");
   return { agent, roots: [...roots].sort(), sources, method: "automatic", ...agent === "gemini" ? { builtinNames } : {}, ...agent === "hermes" ? { directories: captureDiscoveryDirectories([join33(home, ".hermes/plugins"), join33(home, ".hermes/hermes-agent")].map((path) => canonical9(path))) } : {} };
 }
-var DISCOVERY_RUNTIME_COMMANDS, quotedPath = (path) => JSON.stringify(path).replace(/[^\x20-\x7e]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`), realpathOrNull = (path) => {
+var DISCOVERY_RUNTIME_COMMANDS, NativeDiscoveryUnresolved, quotedPath = (path) => JSON.stringify(path).replace(/[^\x20-\x7e]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`), realpathOrNull = (path) => {
   try {
     return realpathSync8(path);
   } catch {
@@ -39477,6 +39501,18 @@ var init_agent_discovery = __esm(() => {
   init_codex_semantic_cache_witness();
   init_agent_discovery_directories();
   DISCOVERY_RUNTIME_COMMANDS = Object.freeze({ gemini: "gemini" });
+  NativeDiscoveryUnresolved = class NativeDiscoveryUnresolved extends Error {
+    agent;
+    detail;
+    source;
+    reviewable = false;
+    constructor(agent, detail, source) {
+      super(`Native discovery is unresolved (${agent}: ${detail}); provide a reviewed --discovery-inputs file`);
+      this.agent = agent;
+      this.detail = detail;
+      this.source = source;
+    }
+  };
   CLAUDE_CONTROL_WITNESS_MODES = new Set(["claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-settings-v5", "claude-marketplace-registry", "claude-marketplace-registry-v2", "claude-marketplace-entry-v1", "claude-plugin-registry"]);
   CLAUDE_CONTROL_FILES = new Set(["settings.json", "settings.local.json", "installed_plugins.json", "known_marketplaces.json"]);
   ADOPTABLE_SETTINGS_MATCHES = Object.freeze(["exact", "screen-reader-receipt"]);
@@ -39515,6 +39551,11 @@ function physicalPath(path) {
   }
   return resolve24(realpathSync9(cursor), ...suffix);
 }
+function portableAuthoringDiscoveryRefusal(error61, destination) {
+  const head = `Native discovery is unresolved (${error61.agent}: ${error61.detail}).${error61.source ? ` Checked source: ${error61.source}.` : ""}`;
+  const review = `skills hook install --agent ${error61.agent} --discovery-inputs <reviewed-file> --apply`;
+  return error61.reviewable ? `${head} Portable Skills authoring stays refused: an unreviewed ${error61.agent} hook or plugin option could load skills written to ${destination}. This command takes no --discovery-inputs option; review the current ${error61.agent} configuration with ${review}, then retry.` : `${head} Portable Skills authoring stays refused: Skills cannot list every skill root this ${error61.agent} configuration registers, so it cannot rule out ${destination}. This command takes no --discovery-inputs option; correct that ${error61.agent} configuration entry, then retry. Where a reviewed discovery binding covers it, record one with ${review}.`;
+}
 function contains(root, path) {
   const boundary = root.endsWith(sep12) ? root : root + sep12;
   return path === root || path.startsWith(boundary);
@@ -39615,11 +39656,18 @@ function assertPortableAuthoringPath(path, options = {}) {
   if (native) {
     throw new Error(`Refusing portable Skills authoring below native discovery root '${native}': ${lexical}. Set HASNA_SKILLS_DIR to a private authoring corpus outside native roots.`);
   }
-  const roots = configuredRoots(home, options.homeDir !== undefined);
-  for (const value of selected) {
-    if (physicalPath(value.path) === physicalPath(join34(home, `.${value.agent}`)))
-      continue;
-    roots.push(...resolveAgentDiscoveryExclusionRoots({ home, agent: value.agent, nativeHome: value.path, canonical: physicalPath, executable: null }));
+  const roots = [];
+  try {
+    roots.push(...configuredRoots(home, options.homeDir !== undefined));
+    for (const value of selected) {
+      if (physicalPath(value.path) === physicalPath(join34(home, `.${value.agent}`)))
+        continue;
+      roots.push(...resolveAgentDiscoveryExclusionRoots({ home, agent: value.agent, nativeHome: value.path, canonical: physicalPath, executable: null }));
+    }
+  } catch (error61) {
+    if (error61 instanceof NativeDiscoveryUnresolved)
+      throw new Error(portableAuthoringDiscoveryRefusal(error61, lexical));
+    throw error61;
   }
   for (const root of roots) {
     if (candidates.some((candidate) => [resolve24(root), physicalPath(root)].some((nativeRoot) => contains(nativeRoot, candidate) || contains(candidate, nativeRoot)))) {

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.92",
+  version: "0.10.93",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/server.js

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

package/bin/worker.js

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

package/dist/cli/commands/portable-skills.d.ts

@@ -1,2 +1,3 @@
 import type { Command } from "commander";
+export declare const AUTHORING_NATIVE_HOOKS_HELP = "\nNative hooks:\n  Authoring refuses while another agent's native hooks, plugin hooks or plugin\n  options are not covered by a current discovery review, because they could\n  load skills from the authoring corpus. The refusal names the agent and the\n  file it checked; review that agent's configuration with\n    skills hook install --agent <agent> --discovery-inputs <reviewed-file> --apply\n  and retry. Authoring commands themselves take no --discovery-inputs option.\n";
 export declare function registerPortableSkillCommands(parent: Command): void;

package/dist/index.js

@@ -16369,7 +16369,7 @@ import { basename as basename15, dirname as dirname27, isAbsolute as isAbsolute2
 import { homedir as homedir5 } from "os";
 import { isAbsolute as isAbsolute25, join as join39, resolve as resolve25 } from "path";
 // package.json
-var version = "0.10.92";
+var version = "0.10.93";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -20802,6 +20802,82 @@ function assertPinnedLauncherRuntimeSafe(runtime) {
   }
 }
 
+// src/lib/linux-access-acl.ts
+var LINUX_ENODATA = 61;
+var LINUX_EOPNOTSUPP = 95;
+var LINUX_ACL_QUERY_ATTEMPTS = 4;
+var LINUX_ACL_FREE_WHEN_UNSUPPORTED = new Set([
+  0xef53n,
+  0x58465342n,
+  0x9123683en,
+  0x01021994n
+]);
+function queryAttribute(probe2, errno, fd, attribute) {
+  for (let attempt = 0;attempt < LINUX_ACL_QUERY_ATTEMPTS; attempt++) {
+    errno.set?.(0);
+    const result = probe2.fgetxattr(fd, attribute);
+    const code = errno.get();
+    if (result !== -1 && result !== -1n)
+      return "present";
+    if (code === LINUX_ENODATA)
+      return "absent";
+    if (code === LINUX_EOPNOTSUPP)
+      return "unsupported";
+  }
+  return "unverified";
+}
+function linuxAccessAclAbsent(probe2, fd, creationParent) {
+  if (probe2.arch !== "x64" && probe2.arch !== "arm64")
+    return false;
+  const errno = probe2.errno;
+  if (!errno)
+    return false;
+  let unsupported = false;
+  for (const attribute of ["system.posix_acl_access", ...creationParent ? ["system.posix_acl_default"] : []]) {
+    const state = queryAttribute(probe2, errno, fd, attribute);
+    if (state === "present" || state === "unverified")
+      return false;
+    if (state === "unsupported")
+      unsupported = true;
+  }
+  if (!unsupported)
+    return true;
+  const type = probe2.filesystemType(fd);
+  return type !== null && LINUX_ACL_FREE_WHEN_UNSUPPORTED.has(type);
+}
+function withGlibcAclProbe(use) {
+  try {
+    const { dlopen, ptr, read: read2, FFIType } = __require("bun:ffi");
+    const library = dlopen("libc.so.6", {
+      fgetxattr: { args: ["i32", "ptr", "ptr", "u64"], returns: FFIType.i64_fast },
+      fstatfs: { args: ["i32", "ptr"], returns: "i32" },
+      __errno_location: { args: [], returns: "ptr" }
+    });
+    try {
+      const location = library.symbols.__errno_location();
+      const names = new Map;
+      return use({
+        arch: process.arch,
+        errno: location ? { get: () => read2.i32(location) } : null,
+        fgetxattr: (fd, attribute) => {
+          let name = names.get(attribute);
+          if (!name)
+            names.set(attribute, name = Buffer.from(attribute + "\x00"));
+          return library.symbols.fgetxattr(fd, ptr(name), null, 0);
+        },
+        filesystemType: (fd) => {
+          const statfs = new BigUint64Array(32);
+          return library.symbols.fstatfs(fd, ptr(statfs)) === 0 ? statfs[0] : null;
+        }
+      });
+    } finally {
+      library.close();
+    }
+  } catch {
+    return false;
+  }
+}
+
 // src/lib/retained-review-artifacts.ts
 import { createHash as createHash29 } from "crypto";
 import { constants as constants18, closeSync as closeSync17, fstatSync as fstatSync17, fsyncSync as fsyncSync6, lstatSync as lstatSync29, mkdirSync as mkdirSync8, openSync as openSync17, readSync as readSync12, writeSync as writeSync4 } from "fs";
@@ -21796,28 +21872,7 @@ function hookProjectionRefusal(reason2) {
   throw new Error(`CLAUDE_MANAGED_HOOK_${reason2}`);
 }
 function hasNoLinuxAccessAcl(fd, creationParent) {
-  try {
-    const { dlopen, read: read2, ptr } = __require("bun:ffi");
-    const library = dlopen("libc.so.6", {
-      fgetxattr: { args: ["i32", "ptr", "ptr", "u64"], returns: "i64" },
-      __errno_location: { args: [], returns: "ptr" }
-    });
-    try {
-      const errno = library.symbols.__errno_location();
-      if (!errno)
-        return false;
-      for (const attribute of ["system.posix_acl_access", ...creationParent ? ["system.posix_acl_default"] : []]) {
-        const name = Buffer.from(attribute + "\x00");
-        if (Number(library.symbols.fgetxattr(fd, ptr(name), null, 0)) !== -1 || read2.i32(errno) !== 61)
-          return false;
-      }
-      return true;
-    } finally {
-      library.close();
-    }
-  } catch {
-    return false;
-  }
+  return withGlibcAclProbe((probe2) => linuxAccessAclAbsent(probe2, fd, creationParent));
 }
 function assertNativePathAcl(path, observed, options = {}) {
   if (process.platform !== "darwin" && process.platform !== "linux")
@@ -22758,7 +22813,7 @@ function planCodexPluginNameReconcile(request) {
     pathDenies: [...pathDenies].sort(),
     ...discovery ? { discovery } : {}
   };
-  const plan = planAgentIntegration({ home, dataDir: dataDir2, projectDir, agents: ["codex"], codexNativeCatalog: catalog, codexReconcile: input });
+  const plan = planAgentIntegration({ home, dataDir: dataDir2, projectDir, agents: ["codex"], codexNativeCatalog: catalog, codexReconcile: input, allowRootAliases: aliases.length > 0 });
   assertCodexReconcileScope(plan, { configPath, policyPath, prior, names, remoteIdentities, discovery: discovery ?? savedDiscovery });
   const configChange = plan.changes.find((change) => resolve24(change.path) === configPath);
   const plannedRules = configChange ? Bun.TOML.parse(configChange.after).skills?.config ?? [] : [];
@@ -25764,6 +25819,19 @@ function discoveryRootUnresolved(agent, command, detail) {
 function isDiscoveryRootUnresolved(error) {
   return error instanceof Error && error.message.startsWith(`${DISCOVERY_ROOT_UNRESOLVED}: `);
 }
+
+class NativeDiscoveryUnresolved extends Error {
+  agent;
+  detail;
+  source;
+  reviewable = false;
+  constructor(agent, detail, source) {
+    super(`Native discovery is unresolved (${agent}: ${detail}); provide a reviewed --discovery-inputs file`);
+    this.agent = agent;
+    this.detail = detail;
+    this.source = source;
+  }
+}
 var quotedPath = (path) => JSON.stringify(path).replace(/[^\x20-\x7e]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
 var realpathOrNull = (path) => {
   try {
@@ -26859,8 +26927,8 @@ function resolveDiscovery(options, exclusion) {
   const configPath = exclusion?.nativeHome === undefined ? agentDiscoveryConfigPath(home, agent) : join41(nativeHome, agent === "codex" ? "config.toml" : "settings.json");
   const configText = witness(configPath, agent === "hermes" ? "yaml" : agent === "codex" ? "toml" : "json", agent === "hermes" ? ["skills", "plugins", "hooks"] : agent === "claude" ? ["enabledPlugins", "extraKnownMarketplaces"] : agent === "codex" ? [...CODEX_DISCOVERY_PROJECTION_FIELDS] : agent === "gemini" ? ["skills", "extensions", "security"] : agent === "opencode" ? ["plugin", "skills"] : agent === "sumi" ? [...SUMI_DISCOVERY_PROJECTION_FIELDS] : ["version"]);
   const config = configText === null ? {} : agent === "hermes" ? parseHermesConfig(configText) : parseConfig(configText, configPath, agent === "codex");
-  const unresolved = (detail) => {
-    throw new Error(`Native discovery is unresolved (${agent}: ${detail}); provide a reviewed --discovery-inputs file`);
+  const unresolved = (detail, source) => {
+    throw new NativeDiscoveryUnresolved(agent, detail, source);
   };
   let opaqueClosureVerified = false;
   const verifyOpaqueClosure = (declarations) => {
@@ -26874,6 +26942,17 @@ function resolveDiscovery(options, exclusion) {
     verifyDiscovery(retained, undefined, undefined, undefined, exclusion?.narrowed, canonical9(configPath));
     opaqueClosureVerified = true;
   };
+  const reviewRemedy = (source, check) => {
+    try {
+      check();
+    } catch (error) {
+      if (error instanceof NativeDiscoveryUnresolved) {
+        error.reviewable = true;
+        error.source ??= source;
+      }
+      throw error;
+    }
+  };
   if (exclusion) {
     if (configText !== null && agent !== "codex" && agent !== "hermes")
       parseNativeJsonObject(configText);
@@ -26945,7 +27024,7 @@ function resolveDiscovery(options, exclusion) {
         unresolved(`non-enumerable ${label} require a current settings review`);
     };
     if (hasHooks)
-      verifyCurrentOpaqueSettings("hooks");
+      reviewRemedy(canonical9(configPath), () => verifyCurrentOpaqueSettings("hooks"));
     if (agent === "claude") {
       if (config.env !== undefined) {
         if (!object6(config.env) || Object.keys(config.env).length > 512)
@@ -26958,7 +27037,7 @@ function resolveDiscovery(options, exclusion) {
         if (hasFunctionHookEnvironment) {
           if (!["0", "1"].includes(config.env.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS))
             unresolved("malformed Claude env.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS flag");
-          verifyCurrentOpaqueSettings("function-hook environment controls");
+          reviewRemedy(canonical9(configPath), () => verifyCurrentOpaqueSettings("function-hook environment controls"));
         }
       }
       if (config.pluginConfigs !== undefined) {
@@ -26985,7 +27064,7 @@ function resolveDiscovery(options, exclusion) {
         }
         hasPluginConfigs = Object.keys(config.pluginConfigs).length > 0;
         if (hasPluginConfigs)
-          verifyCurrentOpaqueSettings("plugin configurations");
+          reviewRemedy(canonical9(configPath), () => verifyCurrentOpaqueSettings("plugin configurations"));
       }
       if (config.enabledPlugins !== undefined && !object6(config.enabledPlugins))
         unresolved("enabledPlugins must be an object");
@@ -27097,7 +27176,7 @@ function resolveDiscovery(options, exclusion) {
     if (Object.keys(config.enabledPlugins ?? config.plugins ?? config.extensions ?? {}).length > 512)
       unresolved("unbounded native registrations");
     if (hasHooks || hasPluginConfigs || hasFunctionHookEnvironment)
-      verifyOpaqueClosure([]);
+      reviewRemedy(canonical9(configPath), () => verifyOpaqueClosure([]));
   }
   if (options.reviewed && (options.reviewed.version !== 1 || !Array.isArray(options.reviewed.agents) || options.reviewed.agents.some((item) => !item || typeof item !== "object") || new Set(options.reviewed.agents.map((item) => item.agent)).size !== options.reviewed.agents.length))
     throw new Error("Invalid --discovery-inputs version or agents");
@@ -27350,40 +27429,41 @@ function resolveDiscovery(options, exclusion) {
     if (exclusion && Object.keys(manifest).some((key2) => /skill|plugin|hook|marketplace|extension|instruction/i.test(key2) && !["skills", "hooks"].includes(key2)))
       unresolved("unknown plugin discovery controls");
     const hooks = witness(join41(root2, "hooks/hooks.json"));
-    if (manifest.hooks !== undefined || hooks !== null) {
-      if (!exclusion || exclusion.retained?.method !== "reviewed")
-        unresolved("plugin hooks require a separate no-skill-injection review");
-      const required = [manifestPath, ...hooks !== null ? [join41(root2, "hooks/hooks.json")] : []];
-      const scoped2 = agent === "codex" && codex !== undefined ? [] : undefined;
-      if (manifest.hooks !== undefined) {
-        if (scoped2 && manifest.hooks && typeof manifest.hooks === "object" && !Array.isArray(manifest.hooks)) {
-          const inline = codexPluginHookHandlers(manifest.hooks);
-          if (!inline)
-            unresolved("unsupported inline plugin hooks");
-          scoped2.push(inline);
-        } else {
-          if (typeof manifest.hooks !== "string")
-            unresolved("unsupported plugin hooks target");
-          const hook = resolve28(root2, manifest.hooks);
-          if (!hook.startsWith(root2 + sep15))
-            unresolved("plugin hooks target escapes its root");
-          required.push(hook);
-          if (scoped2)
-            scoped2.push(readCodexHookDeclaration(witness(hook), hook));
-        }
-      }
-      if (scoped2 && hooks !== null)
-        scoped2.push(readCodexHookDeclaration(hooks, join41(root2, "hooks/hooks.json")));
-      for (const path of required) {
-        const saved = exclusion.retained.sources.filter((source) => source.path === canonical9(path) && source.sha256 !== null && source.format === undefined && source.fields === undefined);
-        if (saved.length ? saved.some((source) => projected(source, undefined, budget3) !== source.sha256) : !(scoped2 && reviewedInstalledCopy(root2, path, codex)))
-          unresolved("plugin hooks require current independently reviewed sources");
-      }
-      if (scoped2 && scoped2.every((item) => item !== null && item.commands === 0)) {
-        verifyCodexPluginHookClosure(root2, codex, codex.source, new Set(scoped2.flatMap((item) => [...item.servers])), required.map((path) => canonical9(path)));
-      } else
-        verifyOpaqueClosure(required.map((path) => canonical9(path)));
-    }
+    if (manifest.hooks !== undefined || hooks !== null)
+      reviewRemedy(canonical9(hooks !== null ? join41(root2, "hooks/hooks.json") : manifestPath), () => {
+        if (!exclusion || exclusion.retained?.method !== "reviewed")
+          unresolved("plugin hooks require a separate no-skill-injection review");
+        const required = [manifestPath, ...hooks !== null ? [join41(root2, "hooks/hooks.json")] : []];
+        const scoped2 = agent === "codex" && codex !== undefined ? [] : undefined;
+        if (manifest.hooks !== undefined) {
+          if (scoped2 && manifest.hooks && typeof manifest.hooks === "object" && !Array.isArray(manifest.hooks)) {
+            const inline = codexPluginHookHandlers(manifest.hooks);
+            if (!inline)
+              unresolved("unsupported inline plugin hooks");
+            scoped2.push(inline);
+          } else {
+            if (typeof manifest.hooks !== "string")
+              unresolved("unsupported plugin hooks target");
+            const hook = resolve28(root2, manifest.hooks);
+            if (!hook.startsWith(root2 + sep15))
+              unresolved("plugin hooks target escapes its root");
+            required.push(hook);
+            if (scoped2)
+              scoped2.push(readCodexHookDeclaration(witness(hook), hook));
+          }
+        }
+        if (scoped2 && hooks !== null)
+          scoped2.push(readCodexHookDeclaration(hooks, join41(root2, "hooks/hooks.json")));
+        for (const path of required) {
+          const saved = exclusion.retained.sources.filter((source) => source.path === canonical9(path) && source.sha256 !== null && source.format === undefined && source.fields === undefined);
+          if (saved.length ? saved.some((source) => projected(source, undefined, budget3) !== source.sha256) : !(scoped2 && reviewedInstalledCopy(root2, path, codex)))
+            unresolved("plugin hooks require current independently reviewed sources", canonical9(path));
+        }
+        if (scoped2 && scoped2.every((item) => item !== null && item.commands === 0)) {
+          verifyCodexPluginHookClosure(root2, codex, codex.source, new Set(scoped2.flatMap((item) => [...item.servers])), required.map((path) => canonical9(path)));
+        } else
+          verifyOpaqueClosure(required.map((path) => canonical9(path)));
+      });
     const commands = join41(root2, "commands");
     safe6(commands);
     if (agent === "claude" && (manifest.commands !== undefined || lstatSync34(commands, { throwIfNoEntry: false })?.isDirectory() && entries(commands).length))
@@ -27522,6 +27602,11 @@ function physicalPath(path) {
   }
   return resolve29(realpathSync14(cursor), ...suffix);
 }
+function portableAuthoringDiscoveryRefusal(error, destination) {
+  const head = `Native discovery is unresolved (${error.agent}: ${error.detail}).${error.source ? ` Checked source: ${error.source}.` : ""}`;
+  const review = `skills hook install --agent ${error.agent} --discovery-inputs <reviewed-file> --apply`;
+  return error.reviewable ? `${head} Portable Skills authoring stays refused: an unreviewed ${error.agent} hook or plugin option could load skills written to ${destination}. This command takes no --discovery-inputs option; review the current ${error.agent} configuration with ${review}, then retry.` : `${head} Portable Skills authoring stays refused: Skills cannot list every skill root this ${error.agent} configuration registers, so it cannot rule out ${destination}. This command takes no --discovery-inputs option; correct that ${error.agent} configuration entry, then retry. Where a reviewed discovery binding covers it, record one with ${review}.`;
+}
 function contains2(root2, path) {
   const boundary = root2.endsWith(sep16) ? root2 : root2 + sep16;
   return path === root2 || path.startsWith(boundary);
@@ -27622,11 +27707,18 @@ function assertPortableAuthoringPath(path, options = {}) {
   if (native) {
     throw new Error(`Refusing portable Skills authoring below native discovery root '${native}': ${lexical}. Set HASNA_SKILLS_DIR to a private authoring corpus outside native roots.`);
   }
-  const roots = configuredRoots(home, options.homeDir !== undefined);
-  for (const value of selected) {
-    if (physicalPath(value.path) === physicalPath(join42(home, `.${value.agent}`)))
-      continue;
-    roots.push(...resolveAgentDiscoveryExclusionRoots({ home, agent: value.agent, nativeHome: value.path, canonical: physicalPath, executable: null }));
+  const roots = [];
+  try {
+    roots.push(...configuredRoots(home, options.homeDir !== undefined));
+    for (const value of selected) {
+      if (physicalPath(value.path) === physicalPath(join42(home, `.${value.agent}`)))
+        continue;
+      roots.push(...resolveAgentDiscoveryExclusionRoots({ home, agent: value.agent, nativeHome: value.path, canonical: physicalPath, executable: null }));
+    }
+  } catch (error) {
+    if (error instanceof NativeDiscoveryUnresolved)
+      throw new Error(portableAuthoringDiscoveryRefusal(error, lexical));
+    throw error;
   }
   for (const root2 of roots) {
     if (candidates.some((candidate2) => [resolve29(root2), physicalPath(root2)].some((nativeRoot) => contains2(nativeRoot, candidate2) || contains2(candidate2, nativeRoot)))) {

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

@@ -65,6 +65,19 @@ export interface AgentDiscoveryBinding {
 export declare const DISCOVERY_ROOT_UNRESOLVED = "DISCOVERY_ROOT_UNRESOLVED";
 export declare function discoveryRootUnresolved(agent: IntegrationAgent, command: string, detail: string): Error;
 export declare function isDiscoveryRootUnresolved(error: unknown): error is Error;
+/** A native configuration Skills cannot resolve. The message names the
+ * --discovery-inputs option of the native commands that accept it (hook
+ * install, migrate native). Portable authoring takes no such option and
+ * rewrites the remedy from these fields: `reviewable` marks a hook, plugin hook
+ * or plugin option check that a current discovery review satisfies, and
+ * `source` names the configuration or hook file it checked (a path only). */
+export declare class NativeDiscoveryUnresolved extends Error {
+    readonly agent: IntegrationAgent;
+    readonly detail: string;
+    source?: string | undefined;
+    reviewable: boolean;
+    constructor(agent: IntegrationAgent, detail: string, source?: string | undefined);
+}
 /** The runtime executable a discovery review resolved through PATH, with the
  * realpath its launcher led to. The policy stores it beside the binding
  * (bridge.discoveryExecutables), not inside it, so a consumer that compares