@hasna/skills 0.10.88 → 0.10.90

package/bin/mcp.js

@@ -38,7 +38,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.88",
+    version: "0.10.90",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -22957,7 +22957,8 @@ var init_codex_native_compatibility = __esm(() => {
     "codex-cli 0.162.1": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
     "codex-cli 0.163.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
     "codex-cli 0.164.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
-    "codex-cli 0.165.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"]
+    "codex-cli 0.165.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
+    "codex-cli 0.166.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"]
   };
   SUPPORTED_CODEX_HOOK_VERSIONS = Object.freeze(Object.keys(MEASURED_CODEX_CAPABILITIES).filter((version2) => supportsCodexNativeCapability(version2, "hooks")));
 });
@@ -37171,6 +37172,7 @@ var init_selected_document = __esm(() => {
 });
 
 // src/lib/selection-resolver.ts
+import { isDeepStrictEqual as isDeepStrictEqual5 } from "util";
 async function resolveSelectionContext(profileId, options = {}) {
   const sessionState = options.sessionId ? readSkillSessionSnapshotIfExists(options.sessionId, options) : null;
   const session = sessionState?.receipt ?? null;
@@ -37255,21 +37257,70 @@ function unknownNameRefusal(slug, profile) {
   return `Skill '${slug}' is not selected by this Skills profile or project lock.${hint} ` + `Read the accepted names with 'skills search <term>' or 'skills list --all --json'; accept one with 'skills pin <name>'. ${ACCEPTED_FORM}`;
 }
 async function loadSelectedSkill(spec, profileId, options = {}) {
-  const context = await resolveSelectionContext(profileId, options);
+  if (!options.cacheFirst)
+    return readSelectedSkill(spec, profileId, options);
+  const { cacheFirst: _cacheFirst, cached: _cached, authority, ...service } = options;
+  try {
+    return await readSelectedSkill(spec, profileId, { ...service, authority, cached: true });
+  } catch (cacheError) {
+    if (!(cacheError instanceof SkillSelectionError) || !RECOVERABLE_CACHE_ERRORS.has(cacheError.code))
+      throw cacheError;
+    try {
+      return await readSelectedSkill(spec, profileId, service);
+    } catch (serviceError) {
+      if (!(serviceError instanceof SkillSelectionError) || serviceError.code !== "SKILLS_API_UNAVAILABLE")
+        throw serviceError;
+      throw new SkillSelectionError(cacheError.code, "The verified cache can't serve this load and the Skills service can't be reached from here, so it has to run where the network is available. `skills sync` doesn't renew a session's pin.");
+    }
+  }
+}
+async function readSelectedSkill(spec, profileId, options) {
+  const context = await resolveSelectionContext(profileId, options).catch((error61) => {
+    if (options.cached && options.sessionId && error61 instanceof SkillSelectionError && error61.code === "CACHED_PROFILE_EXPIRED" && readSkillSessionSnapshotIfExists(options.sessionId, options)) {
+      throw new SkillSelectionError("CACHED_PROFILE_EXPIRED", "This session's Skills pin was verified too long ago to read from the cache. Run the same command without --cached: that keeps the pin but needs the network and sign-in. `skills sync` doesn't renew a session's pin.");
+    }
+    throw error61;
+  });
   const selection = exactProfileSelection(spec, context.receipt.profile);
   const entries = await readSelectedEntries(selection, context, options);
   const { file: file2, content } = readSelectedDocument(entries, options.file);
   const receipt = { ...selection, file: file2, source: options.cached ? "verified-cache" : "api", verifiedAt: context.receipt.verifiedAt };
-  if (options.sessionId) {
-    const session = {
-      ...context.receipt,
-      sessionId: options.sessionId,
-      loaded: [...new Set([...context.session?.loaded ?? [], selectionKey(selection)])],
-      ...context.projectLock ? { projectLock: context.projectLock } : {}
-    };
-    writeSkillSession(session, { current: context.sessionSnapshot, parent: context.parentSnapshot }, options);
+  const sessionRecorded = options.sessionId ? recordSessionLoad(options.sessionId, selection, context, options) : undefined;
+  return { content, selection, receipt, ...sessionRecorded === undefined ? {} : { sessionRecorded } };
+}
+function isUnwritableStore(error61) {
+  for (let cause = error61, depth = 0;cause && depth < 4; cause = cause.cause, depth++)
+    if (UNWRITABLE_CODES.has(cause.code))
+      return true;
+  return false;
+}
+function recordSessionLoad(sessionId, selection, context, options) {
+  const key2 = selectionKey(selection);
+  let snapshot2 = context.sessionSnapshot;
+  for (let attempt = 0;attempt < SESSION_LOAD_RECORD_ATTEMPTS; attempt++) {
+    try {
+      const session = {
+        ...context.receipt,
+        sessionId,
+        loaded: [...new Set([...context.session?.loaded ?? [], key2])],
+        ...context.projectLock ? { projectLock: context.projectLock } : {}
+      };
+      writeSkillSession(session, { current: snapshot2, parent: context.parentSnapshot }, options);
+      return true;
+    } catch (error61) {
+      const blocked = isUnwritableStore(error61) || error61 instanceof SkillSelectionError && error61.code === "SESSION_WRITE_BUSY";
+      if (!blocked && !(error61 instanceof SkillSelectionError && error61.code === "SESSION_CONTEXT_CONFLICT"))
+        throw error61;
+      const current = readSkillSessionSnapshotIfExists(sessionId, options);
+      if (current ? !isDeepStrictEqual5(current.receipt.profile, context.receipt.profile) : !blocked) {
+        throw new SkillSelectionError("SESSION_CONTEXT_CONFLICT", "The Skills session's pin changed while this skill was loading, so its content no longer belongs to that pin. Load it again.");
+      }
+      if (blocked)
+        return false;
+      snapshot2 = skillSessionSnapshotBinding(current);
+    }
   }
-  return { content, selection, receipt };
+  return false;
 }
 async function pinSelectedSkillVersion(spec, profileId, options) {
   const context = await resolveSelectionContext(profileId, options);
@@ -37298,13 +37349,15 @@ async function selectedSkillRequirements(spec, profileId, options = {}) {
   }
   return { ...getSkillRequirementsFromContent(selection.slug, texts, dependencies), selection };
 }
-var ACCEPTED_FORM = "Accepted form: '<slug>' or '<slug>@<version>'.";
+var ACCEPTED_FORM = "Accepted form: '<slug>' or '<slug>@<version>'.", RECOVERABLE_CACHE_ERRORS, SESSION_LOAD_RECORD_ATTEMPTS = 8, UNWRITABLE_CODES;
 var init_selection_resolver = __esm(() => {
   init_profile_client();
   init_skillinfo();
   init_search();
   init_selected_document();
   init_selection_cache();
+  RECOVERABLE_CACHE_ERRORS = new Set(["CACHED_PROFILE_EXPIRED", "CACHED_PROFILE_MISSING", "CACHED_BUNDLE_MISSING"]);
+  UNWRITABLE_CODES = new Set(["EACCES", "EPERM", "EROFS", "ENOSPC", "EDQUOT"]);
 });
 
 // src/lib/selected-manifest.ts
@@ -37916,7 +37969,7 @@ var init_codex_hook_discovery_recovery = __esm(() => {
 import { createHash as createHash26 } from "crypto";
 import { lstatSync as lstatSync25, opendirSync as opendirSync4, readFileSync as readFileSync18, readdirSync as readdirSync9, realpathSync as realpathSync8 } from "fs";
 import { basename as basename14, dirname as dirname24, isAbsolute as isAbsolute22, join as join33, relative as relative7, resolve as resolve23, sep as sep11 } from "path";
-import { isDeepStrictEqual as isDeepStrictEqual5 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual6 } from "util";
 function discoveryExecutable(agent) {
   const command = DISCOVERY_RUNTIME_COMMANDS[agent];
   const found = command ? Bun.which(command) : null;
@@ -38063,8 +38116,8 @@ function projectNativeDiscoveryFields(text2, format, fields2, path) {
 }
 function isSupersededSettingsProjection(agent, configPath, source) {
   if (agent === "sumi")
-    return source.path === configPath && source.format === "json" && isDeepStrictEqual5(source.fields, [...SUMI_DISCOVERY_PROJECTION_FIELDS]);
-  return agent === "codex" && source.path === configPath && source.format === "toml" && isDeepStrictEqual5(source.fields, [...CODEX_DISCOVERY_PROJECTION_FIELDS]);
+    return source.path === configPath && source.format === "json" && isDeepStrictEqual6(source.fields, [...SUMI_DISCOVERY_PROJECTION_FIELDS]);
+  return agent === "codex" && source.path === configPath && source.format === "toml" && isDeepStrictEqual6(source.fields, [...CODEX_DISCOVERY_PROJECTION_FIELDS]);
 }
 function supersedesSettingsProjection(agent, sources, configPath) {
   if (agent === "sumi")
@@ -38085,7 +38138,7 @@ function projected(source, changes, budget3 = discoveryByteBudget()) {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || !Array.isArray(source.hookSources))
       throw new Error("Codex V6 requires exact reviewed hook sources");
     const current = captureCodexSettingsV6(source.path, source.hookSources, budget3);
-    if (current.sha256 !== source.sha256 || !isDeepStrictEqual5(current.hookSources, source.hookSources))
+    if (current.sha256 !== source.sha256 || !isDeepStrictEqual6(current.hookSources, source.hookSources))
       throw new Error("Codex hook provider or dependency changed; explicit discovery review required");
     return changes ? captureCodexSettingsV6(source.path, source.hookSources, budget3, changes).sha256 : current.sha256;
   }
@@ -38361,7 +38414,7 @@ function verifyCodexSemanticCacheDiscovery(binding, reviewedRootAliases, narrowe
   if (reviewedRootAliases !== undefined) {
     const alias = reviewedRootAliases.find((alias2) => alias2.agent === "codex");
     const expected = alias ? { alias: alias.alias, target: alias.target } : null;
-    if (!isDeepStrictEqual5(proof.hookRootAlias, expected))
+    if (!isDeepStrictEqual6(proof.hookRootAlias, expected))
       throw new Error("Semantic cache hook alias differs from reviewed root binding");
   }
   const controls = binding.codexDisabledPluginSkills;
@@ -38371,7 +38424,7 @@ function verifyCodexSemanticCacheDiscovery(binding, reviewedRootAliases, narrowe
   if (controls.some((control) => dirname24(dirname24(control.pluginParent)) !== cacheRoot))
     throw new Error("Codex semantic cache names another enrolled cache");
   const reviewedHookParents = proof.reviewedHookParents ?? [];
-  if (!Array.isArray(reviewedHookParents) || reviewedHookParents.length > 4096 || reviewedHookParents.some((parent) => !parent || !(parent.installation === "remote-receipt" && Object.keys(parent).sort().join(",") === "installation,namespace,pluginId,pluginParent,remotePluginId,role" && typeof parent.remotePluginId === "string" || parent.installation === "local-marketplace" && Object.keys(parent).sort().join(",") === "installation,marketplaceSha256,marketplaceSourcePath,namespace,pluginId,pluginParent,role" && typeof parent.marketplaceSourcePath === "string" && /^[a-f0-9]{64}$/.test(parent.marketplaceSha256 ?? "")) || parent.role !== "reviewed-hook" || typeof parent.pluginId !== "string" || typeof parent.namespace !== "string" || typeof parent.pluginParent !== "string") || new Set(reviewedHookParents.map((parent) => parent.pluginParent)).size !== reviewedHookParents.length || !isDeepStrictEqual5((proof.witness.hookParents ?? []).map(({ manifestSha256: _manifest, hooksSha256: _hooks, receiptSha256: _receipt, ...parent }) => parent), reviewedHookParents)) {
+  if (!Array.isArray(reviewedHookParents) || reviewedHookParents.length > 4096 || reviewedHookParents.some((parent) => !parent || !(parent.installation === "remote-receipt" && Object.keys(parent).sort().join(",") === "installation,namespace,pluginId,pluginParent,remotePluginId,role" && typeof parent.remotePluginId === "string" || parent.installation === "local-marketplace" && Object.keys(parent).sort().join(",") === "installation,marketplaceSha256,marketplaceSourcePath,namespace,pluginId,pluginParent,role" && typeof parent.marketplaceSourcePath === "string" && /^[a-f0-9]{64}$/.test(parent.marketplaceSha256 ?? "")) || parent.role !== "reviewed-hook" || typeof parent.pluginId !== "string" || typeof parent.namespace !== "string" || typeof parent.pluginParent !== "string") || new Set(reviewedHookParents.map((parent) => parent.pluginParent)).size !== reviewedHookParents.length || !isDeepStrictEqual6((proof.witness.hookParents ?? []).map(({ manifestSha256: _manifest, hooksSha256: _hooks, receiptSha256: _receipt, ...parent }) => parent), reviewedHookParents)) {
     throw new Error("Invalid reviewed native-hook cache role");
   }
   for (const parent of reviewedHookParents)
@@ -38381,7 +38434,7 @@ function verifyCodexSemanticCacheDiscovery(binding, reviewedRootAliases, narrowe
   const hookParentPaths = reviewedHookParents.map((parent) => parent.pluginParent);
   const sources = binding.sources.filter((source) => codexSemanticCacheSourceRole(source, cacheRoot, parents3, hookParentPaths));
   const directories = (binding.directories ?? []).filter((directory) => codexSemanticCacheDirectoryRole(directory.path, cacheRoot));
-  if (!directories.length || !isDeepStrictEqual5(sources, proof.supersededSources) || !isDeepStrictEqual5(directories, proof.supersededDirectories))
+  if (!directories.length || !isDeepStrictEqual6(sources, proof.supersededSources) || !isDeepStrictEqual6(directories, proof.supersededDirectories))
     throw new Error("Codex semantic cache provenance changed");
   const configPath = proof.configPath;
   if (!isAbsolute22(configPath) || resolve23(configPath) !== configPath || basename14(configPath) !== "config.toml" || /[\x00-\x1f\x7f]/.test(configPath))
@@ -38427,8 +38480,8 @@ function verifyDiscovery(binding, codexRecovery, reviewedRootAliases, witnessTol
         if (omitted.some((root) => !retiredRoots.includes(root)))
           throw new Error("Missing reviewed directory membership inventory; provide a fresh discovery review");
         const current = captureDiscoveryDirectoryProjection(ordinary.map((item) => item.path), retiredRoots).map(({ entries, ...item }) => item);
-        if (!isDeepStrictEqual5(current, projection)) {
-          const changed = projection.filter((item, index) => !isDeepStrictEqual5(current[index], item));
+        if (!isDeepStrictEqual6(current, projection)) {
+          const changed = projection.filter((item, index) => !isDeepStrictEqual6(current[index], item));
           for (const item of changed.length && current.length === projection.length ? changed : [null])
             witnessChanged(new NativeDiscoveryWitnessChange("membership", item?.path ?? null, "Native discovery directory membership changed outside retired Codex roots"), witnessTolerance, item !== null && witnessTolerance?.acceptsMembership(item.path) === true);
         }
@@ -38451,7 +38504,7 @@ function verifyDiscovery(binding, codexRecovery, reviewedRootAliases, witnessTol
       safe6(source.path);
       continue;
     }
-    if (semanticCache?.supersededSources.some((previous) => isDeepStrictEqual5(previous, source))) {
+    if (semanticCache?.supersededSources.some((previous) => isDeepStrictEqual6(previous, source))) {
       safe6(source.path);
       continue;
     }
@@ -38950,7 +39003,7 @@ function resolveDiscovery(options, exclusion) {
       const parents3 = [...new Set([...(retained.codexDisabledPluginSkills ?? []).map((control) => control.pluginParent), ...proof.appOnlyParents.map((parent) => parent.pluginParent)])];
       covered = covered.filter((source) => !codexSemanticCacheSourceRole(source, proof.witness.cacheRoot, parents3));
     }
-    if (covered.some((source) => !retained.sources.some((saved) => isDeepStrictEqual5(saved, source))) || [...roots].some((root) => !retained.roots.includes(root)) || agent === "gemini" && JSON.stringify(retained.builtinNames) !== JSON.stringify(builtinNames))
+    if (covered.some((source) => !retained.sources.some((saved) => isDeepStrictEqual6(saved, source))) || [...roots].some((root) => !retained.roots.includes(root)) || agent === "gemini" && JSON.stringify(retained.builtinNames) !== JSON.stringify(builtinNames))
       unresolved("retained review is missing current runtime discovery coverage");
     return retained;
   }
@@ -39008,7 +39061,7 @@ function resolveDiscovery(options, exclusion) {
         throw new Error("Retired native materialization changed during discovery review");
     }
     const combined = [...reviewedSources, ...reviewedSourcesWithManifestProjection];
-    const unique = combined.filter((source, index) => combined.findIndex((candidate) => isDeepStrictEqual5(candidate, source)) === index);
+    const unique = combined.filter((source, index) => combined.findIndex((candidate) => isDeepStrictEqual6(candidate, source)) === index);
     return { ...supplied, roots: [...new Set([...roots, ...supplied.roots])].sort(), sources: unique, ...agent === "gemini" ? { builtinNames } : {} };
   }
   function plugin(root) {
@@ -47756,7 +47809,7 @@ var init_execution_grants = __esm(() => {
 });
 
 // src/lib/execution-grant-client.ts
-import { isDeepStrictEqual as isDeepStrictEqual6 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual7 } from "util";
 function id(value) {
   if (!grantIdentifier(value))
     throw new Error("Invalid execution grant profile or revision identifier.");
@@ -47799,7 +47852,7 @@ async function resolveExecutionGrant(input2) {
   if (!grantRecord(value) || Object.keys(value).length !== 3 || !grantIdentifier(value.policyRevision) || !grantIdentifier(value.grantId) || !grantRecord(value.bindings)) {
     throw new SkillSelectionError("INVALID_EXECUTION_GRANT", "The Skills API returned an invalid execution grant.");
   }
-  if (!isDeepStrictEqual6(value.bindings.selection, snapshot2.selection) || !isDeepStrictEqual6(value.bindings.consumer, snapshot2.consumer)) {
+  if (!isDeepStrictEqual7(value.bindings.selection, snapshot2.selection) || !isDeepStrictEqual7(value.bindings.consumer, snapshot2.consumer)) {
     throw new SkillSelectionError("EXECUTION_GRANT_SCOPE_MISMATCH", "The Skills API returned a grant for a different selection or consumer.");
   }
   return value;

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

package/dist/cli/commands/agent-integration.d.ts

@@ -16,12 +16,32 @@ export declare const MANAGED_HOOK_CONTEXT_MAX_CHARS = 12000;
 export declare const MANAGED_HOOK_CONTEXT_MAX_SKILLS = 2;
 /** Part of the cap kept for the policy, notices and up to ten load offers. */
 export declare const MANAGED_HOOK_CONTEXT_RESERVE_CHARS = 2500;
+/**
+ * A managed hook injects an unnamed prompt match only for a phrase of at least
+ * this many words. A one-word trigger says little about a turn's subject, more
+ * so in long text ("effect", "rollback", "handoff"), and several of them don't
+ * add up to a phrase, so such a match is offered as a load command instead
+ * (FAO-00144). SKILLS_HOOK_PROMPT_MIN_PHRASE_WORDS can only raise it.
+ */
+export declare const MANAGED_HOOK_PROMPT_MIN_PHRASE_WORDS = 2;
+/** A subagent's start carries no prompt to match against, so its parent's skills are offered, not injected. */
+export declare const MANAGED_HOOK_INHERITED_BODIES = 0;
 /** The effective hook limits: the defaults above, or a valid lower environment override. */
 export declare function managedHookContextLimits(): {
     maxChars: number;
     maxSkills: number;
     bodyChars: number;
 };
+/** The effective phrase length: the default above, or a valid higher environment override. */
+export declare function managedHookPromptMinPhraseWords(): number;
+/**
+ * The selection flags one agent's managed hook passes to its context child.
+ * Sumi's plugin and Cursor's prompt hook both discard the output of a prompt
+ * call and only deliver what a later call restores, so a pointer could never
+ * reach their models: it would turn a delivered body into nothing. They keep the
+ * plain selection until they can carry pointers.
+ */
+export declare function managedHookSelectionArgs(agent: IntegrationAgent): string[];
 /** Clamp assembled hook context to the cap at a line boundary, with a fixed note. */
 export declare function capManagedHookContext(context: string, maxChars?: number): string;
 /**

package/dist/cli/commands/context.d.ts

@@ -5,6 +5,8 @@ export declare function selectedProfileId(explicit?: string): string;
 export interface ContextCommandOptions {
     selectionProfile?: string;
     cached?: boolean;
+    cacheFirst?: boolean;
+    pointerCacheFirst?: boolean;
     autoReconcileSafe?: boolean;
     autoMigrateSessionPin?: boolean;
     backgroundRenewal?: boolean;
@@ -16,6 +18,8 @@ export interface ContextCommandOptions {
     maxChars?: string;
     maxSkills?: string;
     file?: string;
+    minPromptPhraseWords?: string;
+    inheritedBodies?: string;
 }
 export declare function contextResolverOptions(options: ContextCommandOptions): SelectionResolverOptions;
 export declare function registerContextCommands(parent: Command): void;

package/dist/index.js

@@ -9722,7 +9722,8 @@ var MEASURED_CODEX_CAPABILITIES = {
   "codex-cli 0.162.1": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
   "codex-cli 0.163.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
   "codex-cli 0.164.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
-  "codex-cli 0.165.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"]
+  "codex-cli 0.165.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
+  "codex-cli 0.166.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"]
 };
 function supportsCodexNativeCapability(version, capability) {
   return typeof version === "string" && Object.hasOwn(MEASURED_CODEX_CAPABILITIES, version) && MEASURED_CODEX_CAPABILITIES[version].includes(capability);
@@ -16368,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.88";
+var version = "0.10.90";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -24994,6 +24995,8 @@ function unknownNameRefusal(slug, profile) {
   const hint = close.length > 0 ? ` Did you mean: ${close.join(", ")}?` : "";
   return `Skill '${slug}' is not selected by this Skills profile or project lock.${hint} ` + `Read the accepted names with 'skills search <term>' or 'skills list --all --json'; accept one with 'skills pin <name>'. ${ACCEPTED_FORM}`;
 }
+var RECOVERABLE_CACHE_ERRORS = new Set(["CACHED_PROFILE_EXPIRED", "CACHED_PROFILE_MISSING", "CACHED_BUNDLE_MISSING"]);
+var UNWRITABLE_CODES = new Set(["EACCES", "EPERM", "EROFS", "ENOSPC", "EDQUOT"]);
 
 // src/lib/selected-manifest.ts
 function jsonEntry(entries, path) {
@@ -54368,6 +54371,12 @@ async function buildSkillContextOnce(input2, options, mayResolveAgain) {
   if (maxChars !== undefined && (!Number.isInteger(maxChars) || maxChars < 512 || maxChars > 64000) || !Number.isInteger(maxSkills) || maxSkills < 1 || maxSkills > 20) {
     throw new SkillSelectionError("INVALID_CONTEXT_BUDGET", "Context limits must be 512\u201364000 characters and 1\u201320 skills.");
   }
+  const minPromptPhraseWords = options.minPromptPhraseWords ?? 0;
+  const inheritedBodies = options.inheritedBodies ?? HISTORY_BODY_LIMITS["subagent-inherit"];
+  if (!Number.isInteger(minPromptPhraseWords) || minPromptPhraseWords < 0 || !Number.isInteger(inheritedBodies) || inheritedBodies < 0) {
+    throw new SkillSelectionError("INVALID_CONTEXT_BUDGET", "The prompt phrase and inherited body limits must be whole numbers of 0 or more.");
+  }
+  const historyBodyLimits = { ...HISTORY_BODY_LIMITS, "subagent-inherit": inheritedBodies };
   const profileId = input2.profileId ?? "default";
   const sessionId = input2.sessionId ? input2.agentId ? `${input2.sessionId}:${input2.agentId}` : input2.sessionId : undefined;
   if (input2.parentSessionId !== undefined) {
@@ -54397,8 +54406,9 @@ async function buildSkillContextOnce(input2, options, mayResolveAgain) {
     const key2 = selectionKey(selection);
     if (restoredOrder.has(key2))
       return [{ selection, reason: "session-restore", priority: 6, score: 2000, recency: restoredOrder.get(key2) }];
-    if (inheritedOrder.has(key2))
-      return [{ selection, reason: "subagent-inherit", priority: 6, score: 2000, recency: inheritedOrder.get(key2) }];
+    const inherited = inheritedOrder.has(key2) ? { selection, reason: "subagent-inherit", priority: 6, score: 2000, recency: inheritedOrder.get(key2) } : undefined;
+    if (inherited && inheritedBodies > 0)
+      return [inherited];
     if (explicit.has(key2))
       return [{ selection, reason: "explicit", priority: 5, score: 1000 }];
     if (selection.triggers?.always)
@@ -54407,7 +54417,10 @@ async function buildSkillContextOnce(input2, options, mayResolveAgain) {
     if (matchedPath)
       return [{ selection, reason: "path", priority: 3, score: 500 }];
     const match = relevance.get(key2);
-    return match ? [{ selection, reason: "prompt", priority: match.priority, score: match.score, weak: match.weak }] : [];
+    const weak = match !== undefined && (match.weak || match.priority === 1 && !match.phrases.some((phrase) => phrase.split(" ").length >= minPromptPhraseWords));
+    if (match && !(inherited && weak))
+      return [{ selection, reason: "prompt", priority: match.priority, score: match.score, weak }];
+    return inherited ? [inherited] : [];
   }).sort((a, b) => b.priority - a.priority || (b.recency ?? -1) - (a.recency ?? -1) || b.score - a.score || a.selection.slug.localeCompare(b.selection.slug));
   const historyOffered = new Map;
   const candidates = ranked.filter((candidate2) => {
@@ -54417,6 +54430,9 @@ async function buildSkillContextOnce(input2, options, mayResolveAgain) {
     historyOffered.set(candidate2.reason, count + 1);
     return count < HISTORY_CANDIDATE_LIMIT;
   });
+  const pointerSession = sessionId && /^[A-Za-z0-9._:@][A-Za-z0-9._:@-]{0,255}$/.test(sessionId) ? ` --session ${sessionId}` : "";
+  const pointerCache = options.cached || options.pointerCacheFirst ? " --cache-first" : "";
+  const loadCommandFor = (selection) => `skills load ${selection.slug}@${selection.version} --selection-profile ${profile.profileId}${pointerCache}${pointerSession}`;
   const delivered = [];
   let selections = [];
   const omitted = [];
@@ -54426,7 +54442,7 @@ async function buildSkillContextOnce(input2, options, mayResolveAgain) {
     const { selection, reason: reason2 } = candidates[index];
     if (!input2.restore && !explicit.has(selectionKey(selection)) && loaded.has(selectionKey(selection)))
       continue;
-    const loadCommand = `skills load ${selection.slug}@${selection.version} --selection-profile ${profile.profileId}`;
+    const loadCommand = loadCommandFor(selection);
     if (selections.length >= maxSkills || ambiguous && reason2 === "prompt") {
       omitted.push({ slug: selection.slug, version: selection.version, reason: "skill-limit", loadCommand });
       continue;
@@ -54435,7 +54451,7 @@ async function buildSkillContextOnce(input2, options, mayResolveAgain) {
       omitted.push({ slug: selection.slug, version: selection.version, reason: "weak-match", loadCommand });
       continue;
     }
-    const historyLimit = HISTORY_BODY_LIMITS[reason2];
+    const historyLimit = historyBodyLimits[reason2];
     if (historyLimit !== undefined) {
       const delivered2 = historyBodies.get(reason2) ?? 0;
       if (delivered2 >= historyLimit) {
@@ -54446,12 +54462,13 @@ async function buildSkillContextOnce(input2, options, mayResolveAgain) {
     if (reason2 === "prompt") {
       const candidate2 = candidates[index];
       let end = index;
-      while (end + 1 < candidates.length && candidates[end + 1].reason === "prompt" && candidates[end + 1].priority === candidate2.priority && candidates[end + 1].score === candidate2.score && !candidates[end + 1].weak)
+      while (end + 1 < candidates.length && candidates[end + 1].reason === "prompt" && candidates[end + 1].priority === candidate2.priority && candidates[end + 1].score === candidate2.score)
         end++;
-      const tied = candidates.slice(index, end + 1).filter((entry) => explicit.has(selectionKey(entry.selection)) || !loaded.has(selectionKey(entry.selection)));
+      const block = candidates.slice(index, end + 1).filter((entry) => explicit.has(selectionKey(entry.selection)) || !loaded.has(selectionKey(entry.selection)));
+      const tied = block.filter((entry) => !entry.weak);
       if (tied.length > maxSkills - selections.length) {
-        for (const entry of tied)
-          omitted.push({ slug: entry.selection.slug, version: entry.selection.version, reason: "ambiguous-match", loadCommand: `skills load ${entry.selection.slug}@${entry.selection.version} --selection-profile ${profile.profileId}` });
+        for (const entry of block)
+          omitted.push({ slug: entry.selection.slug, version: entry.selection.version, reason: entry.weak ? "weak-match" : "ambiguous-match", loadCommand: loadCommandFor(entry.selection) });
         ambiguous = true;
         index = end;
         continue;
@@ -54478,7 +54495,7 @@ ${content}`;
     return considered.has(key2) || !explicit.has(key2) && loaded.has(key2);
   });
   for (const offer of offers)
-    omitted.push({ slug: offer.selection.slug, version: offer.selection.version, reason: offer.reason, loadCommand: `skills load ${offer.selection.slug}@${offer.selection.version} --selection-profile ${profile.profileId}` });
+    omitted.push({ slug: offer.selection.slug, version: offer.selection.version, reason: offer.reason, loadCommand: loadCommandFor(offer.selection) });
   let notice;
   if (sessionId) {
     if (!resolved.session || [...loaded].some((key2) => !previouslyLoaded.has(key2))) {
@@ -54494,7 +54511,7 @@ ${content}`;
           slug: selection.slug,
           version: selection.version,
           reason: "write-busy",
-          loadCommand: `skills load ${selection.slug}@${selection.version} --selection-profile ${profile.profileId}`
+          loadCommand: loadCommandFor(selection)
         })));
         selections = selections.filter((selection) => !unrecorded.has(selectionKey(selection)));
         delivered.splice(0, delivered.length, ...delivered.filter((entry) => !unrecorded.has(entry.key)));

package/dist/lib/selection-resolver.d.ts

@@ -1,4 +1,3 @@
-/** One resolution path for API-selected content. Local drafts cannot shadow a published selection. */
 import { type ProfileClient } from "./profile-client.js";
 import type { ResolvedSkillProfile, ResolvedSkillSelection } from "../types/skill-selection.js";
 import type { SkillBundleEntry } from "./skill-bundle.js";
@@ -6,6 +5,8 @@ import { type CachedSelectionProfile, type SelectionCacheOptions, type SkillSess
 export interface SelectionResolverOptions extends SelectionCacheOptions {
     client?: ProfileClient;
     cached?: boolean;
+    /** Read the verified cache while it can serve a load, and the service after that. */
+    cacheFirst?: boolean;
     /** Explicit cached authority binding, checked even when no credential is read. */
     authority?: string;
     workspaceId?: string;
@@ -42,9 +43,18 @@ export interface ResolvedSelectionContext {
 export declare function resolveSelectionContext(profileId: string, options?: SelectionResolverOptions): Promise<ResolvedSelectionContext>;
 export declare function readSelectedEntries(selection: ResolvedSkillSelection, context: ResolvedSelectionContext, options?: SelectionResolverOptions): Promise<SkillBundleEntry[]>;
 export declare function exactProfileSelection(spec: string, profile: ResolvedSkillProfile): ResolvedSkillSelection;
+/** Refusals that mean the verified cache can't serve a read, not that the read is wrong. Identity and integrity failures never fall back. */
+export declare const RECOVERABLE_CACHE_ERRORS: ReadonlySet<string>;
+/**
+ * Load one selected skill. With cacheFirst it reads the verified cache while that
+ * can serve this load, which works with no network, and the Skills service after
+ * that, as the managed hook does. A subagent inherits its parent's verifiedAt and
+ * gets no renewal of its own, so a pointer it holds outlives the cache's limit.
+ */
 export declare function loadSelectedSkill(spec: string, profileId: string, options?: SelectionResolverOptions & {
     file?: string;
 }): Promise<{
+    sessionRecorded?: boolean | undefined;
     content: string;
     selection: ResolvedSkillSelection;
     receipt: {
@@ -66,6 +76,8 @@ export declare function loadSelectedSkill(spec: string, profileId: string, optio
         };
     };
 }>;
+/** A session store that this process can't write: a sandbox, or a full disk or quota. */
+export declare function isUnwritableStore(error: unknown): boolean;
 /** Pin the resolved profile metadata without copying a definition into the project. */
 export declare function pinSelectedSkillVersion(spec: string, profileId: string, options: SelectionResolverOptions & {
     projectDir: string;

package/dist/lib/skill-context.d.ts

@@ -15,6 +15,17 @@ export interface SkillContextInput {
 export interface SkillContextOptions extends SelectionResolverOptions {
     maxChars?: number;
     maxSkills?: number;
+    /**
+     * An unnamed prompt match whose longest matched phrase has fewer words than
+     * this is offered as a load command instead of being injected, however many
+     * such words matched. Named, explicit, path and required selections are not
+     * affected. Unset, every counted match may be injected.
+     */
+    minPromptPhraseWords?: number;
+    /** Print load pointers with --cache-first even though this context didn't come from the cache: a managed hook that fell back to the service. */
+    pointerCacheFirst?: boolean;
+    /** Bodies a child session receives from its parent's loaded skills; the rest are offered. Unset, HISTORY_BODY_LIMITS applies. */
+    inheritedBodies?: number;
     /** Called with the resolved pin before any payload is read (again if a new child is resolved again); metadata only. */
     onResolved?: (resolved: ResolvedSelectionContext) => void;
     /**

package/dist/runtime-prerequisites.js

@@ -49,7 +49,7 @@ var __require = import.meta.require;
 // src/runtime-prerequisites.ts
 import { isAbsolute as isAbsolute7 } from "path";
 // package.json
-var version = "0.10.88";
+var version = "0.10.90";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -2276,7 +2276,8 @@ var MEASURED_CODEX_CAPABILITIES = {
   "codex-cli 0.162.1": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
   "codex-cli 0.163.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
   "codex-cli 0.164.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
-  "codex-cli 0.165.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"]
+  "codex-cli 0.165.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
+  "codex-cli 0.166.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"]
 };
 function supportsCodexNativeCapability(version2, capability) {
   return typeof version2 === "string" && Object.hasOwn(MEASURED_CODEX_CAPABILITIES, version2) && MEASURED_CODEX_CAPABILITIES[version2].includes(capability);

package/dist/sdk/index.js

@@ -32371,7 +32371,7 @@ var init_event_sink = __esm(() => {
   init_dist();
 });
 // package.json
-var version = "0.10.88";
+var version = "0.10.90";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -39270,7 +39270,8 @@ var MEASURED_CODEX_CAPABILITIES = {
   "codex-cli 0.162.1": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
   "codex-cli 0.163.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
   "codex-cli 0.164.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
-  "codex-cli 0.165.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"]
+  "codex-cli 0.165.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"],
+  "codex-cli 0.166.0": ["hooks", "qualified-skill-catalog", "installed-plugin-review"]
 };
 function supportsCodexNativeCapability(version2, capability) {
   return typeof version2 === "string" && Object.hasOwn(MEASURED_CODEX_CAPABILITIES, version2) && MEASURED_CODEX_CAPABILITIES[version2].includes(capability);
@@ -55419,6 +55420,8 @@ function unknownNameRefusal(slug, profile) {
   const hint = close.length > 0 ? ` Did you mean: ${close.join(", ")}?` : "";
   return `Skill '${slug}' is not selected by this Skills profile or project lock.${hint} ` + `Read the accepted names with 'skills search <term>' or 'skills list --all --json'; accept one with 'skills pin <name>'. ${ACCEPTED_FORM}`;
 }
+var RECOVERABLE_CACHE_ERRORS = new Set(["CACHED_PROFILE_EXPIRED", "CACHED_PROFILE_MISSING", "CACHED_BUNDLE_MISSING"]);
+var UNWRITABLE_CODES = new Set(["EACCES", "EPERM", "EROFS", "ENOSPC", "EDQUOT"]);
 
 // src/lib/selected-run.ts
 async function resolveSelectedRun(spec, profileId, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.10.88",
+  "version": "0.10.90",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {