@hasna/skills 0.10.64 → 0.10.66

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

@@ -4,7 +4,7 @@ import { type ManagedPluginRegistrationWitness } from "./plugin-discovery.js";
 import { type CodexHookDiscoveryRecovery } from "./codex-hook-discovery-recovery.js";
 import { type CodexPluginSkillControl, type CodexPluginSourceInput } from "./codex-plugin-skill-controls.js";
 import { type RetainedReviewArtifact, type ReviewedArtifact } from "./retained-review-artifacts.js";
-import { type CodexSemanticCacheWitness, type CodexSemanticCacheAppOnlyParent } from "./codex-semantic-cache-witness.js";
+import { type CodexSemanticCacheWitness, type CodexSemanticCacheAppOnlyParent, type CodexSemanticCacheReviewedHookParent } from "./codex-semantic-cache-witness.js";
 export { captureDiscoveryDirectories, type DiscoveryDirectory } from "./agent-discovery-directories.js";
 export interface DiscoverySource {
     reviewArtifact?: RetainedReviewArtifact;
@@ -26,6 +26,7 @@ export interface CodexSemanticCacheDiscovery {
     } | null;
     witness: CodexSemanticCacheWitness;
     appOnlyParents: CodexSemanticCacheAppOnlyParent[];
+    reviewedHookParents?: CodexSemanticCacheReviewedHookParent[];
     previousPolicySha256: string;
     supersededSources: DiscoverySource[];
     supersededDirectories: DiscoveryDirectory[];
@@ -93,7 +94,7 @@ export declare function projectNativeDiscoveryFields(text: string, format: "json
 export declare function captureRetiredCodexDiscovery(binding: AgentDiscoveryBinding, controls: CodexPluginSkillControl[], rules: unknown): AgentDiscoveryBinding;
 /** Only native capability locations covered by the complete typed cache census
  * qualify. Historical sources remain stored; arbitrary missing files do not. */
-export declare function codexSemanticCacheSourceRole(source: DiscoverySource, cacheRoot: string, parents: readonly string[]): boolean;
+export declare function codexSemanticCacheSourceRole(source: DiscoverySource, cacheRoot: string, parents: readonly string[], hookParents?: readonly string[]): boolean;
 export declare function codexSemanticCacheDirectoryRole(path: string, cacheRoot: string): boolean;
 export declare function assertCodexSemanticCacheHookSafety(cacheRoot: string, parents: readonly string[], configPath: string, hookRootAlias?: CodexSemanticCacheDiscovery["hookRootAlias"]): void;
 export declare function verifyAgentDiscovery(binding: AgentDiscoveryBinding, codexRecovery?: CodexHookDiscoveryRecovery, reviewedRootAliases?: readonly {

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

@@ -215,6 +215,8 @@ export declare function planAgentSettingsWitnessUpgrade(options: {
 export interface CodexSemanticCacheUpgrade {
     agent: "codex";
     appOnlyParents: string[];
+    /** Explicit cache parents whose complete native mcp_tool hook contract was already enrolled. */
+    reviewedHookParents?: string[];
     expectedPolicySha256: string;
     expectedSettingsSha256: string;
     expectedCacheWitnessSha256?: string;

package/dist/lib/codex-semantic-cache-witness.d.ts

@@ -32,11 +32,31 @@ export interface CodexSemanticCacheAppOnlyParentWitness extends CodexSemanticCac
     appSha256: string;
     mcpSha256?: string;
 }
+/** Explicitly reviewed native MCP-hook parent. Its cache materializations are
+ * admitted only when the complete manifest and hooks declaration were already
+ * enrolled as full-byte native discovery sources. */
+export interface CodexSemanticCacheReviewedHookParent {
+    role: "reviewed-hook";
+    pluginId: string;
+    namespace: string;
+    pluginParent: string;
+    installation: "remote-receipt" | "local-marketplace";
+    remotePluginId?: string;
+    marketplaceSourcePath?: string;
+    marketplaceSha256?: string;
+}
+export interface CodexSemanticCacheReviewedHookParentWitness extends CodexSemanticCacheReviewedHookParent {
+    manifestSha256: string;
+    hooksSha256: string;
+    receiptSha256?: string;
+}
 export interface CodexSemanticCacheWitness {
     schema: typeof CODEX_SEMANTIC_CACHE_WITNESS_SCHEMA;
     cacheRoot: string;
     controls: CodexSemanticCacheControl[];
     appOnlyParents: CodexSemanticCacheAppOnlyParentWitness[];
+    /** Optional only for compatibility with already persisted v1 witnesses. */
+    hookParents?: CodexSemanticCacheReviewedHookParentWitness[];
     skills: CodexSemanticCacheSkill[];
     sha256: string;
 }
@@ -45,10 +65,13 @@ export interface CaptureCodexSemanticCacheWitnessOptions {
     controls: CodexPluginSkillControl[];
     /** Explicit package-reviewed parents; absence never infers this role. */
     appOnlyParents?: CodexSemanticCacheAppOnlyParent[];
+    /** Explicit roles only; cache presence never creates a hook role. */
+    reviewedHookParents?: CodexSemanticCacheReviewedHookParent[];
     rules: unknown;
     /** Package-owned, bounded read used by the existing semantic control review. */
     read?: (path: string) => string;
 }
+export declare function codexLocalMarketplaceMapsPlugin(text: string, marketplace: string, plugin: string): boolean;
 /** Capture the current semantic identity without changing the stored baseline.
  * Existing package-owned parsers validate documents and capability controls. */
 export declare function captureCodexSemanticCacheWitness(options: CaptureCodexSemanticCacheWitnessOptions): CodexSemanticCacheWitness;

package/dist/lib/hook-diagnostics.d.ts

@@ -1,3 +1,5 @@
+/** Fixed codes only; generated native adapters must never copy refusal prose. */
+export declare const HOOK_REFUSAL_REASON_CODES: readonly string[];
 export declare class HookDiagnosticError extends Error {
     readonly code: string;
     readonly stage: "context" | "sync";

package/dist/runtime-prerequisites.js

@@ -49,7 +49,7 @@ var __require = import.meta.require;
 // src/runtime-prerequisites.ts
 import { isAbsolute as isAbsolute5 } from "path";
 // package.json
-var version = "0.10.64";
+var version = "0.10.66";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -2643,8 +2643,8 @@ function assertAgentPolicyCollections(policy) {
         }
     }
     if (value.codexSemanticCache !== undefined) {
-      const proof = record(value.codexSemanticCache, 8), witness = record(proof.witness, 6);
-      requireBound(agent === "codex" && value.agent === "codex" && value.method === "reviewed" && Object.keys(proof).length === 8 && proof.schema === "hasna.codex-semantic-cache-discovery.v1" && typeof proof.previousPolicySha256 === "string" && /^[a-f0-9]{64}$/.test(proof.previousPolicySha256) && Object.keys(witness).length === 6 && witness.schema === "hasna.codex-semantic-cache-witness.v1" && typeof witness.sha256 === "string" && /^[a-f0-9]{64}$/.test(witness.sha256));
+      const proof = record(value.codexSemanticCache, 9), witness = record(proof.witness, 7);
+      requireBound(agent === "codex" && value.agent === "codex" && value.method === "reviewed" && [8, 9].includes(Object.keys(proof).length) && Object.keys(proof).every((key) => ["schema", "configPath", "hookRootAlias", "witness", "appOnlyParents", "previousPolicySha256", "supersededSources", "supersededDirectories", "reviewedHookParents"].includes(key)) && proof.schema === "hasna.codex-semantic-cache-discovery.v1" && typeof proof.previousPolicySha256 === "string" && /^[a-f0-9]{64}$/.test(proof.previousPolicySha256) && [6, 7].includes(Object.keys(witness).length) && Object.keys(witness).every((key) => ["schema", "cacheRoot", "controls", "appOnlyParents", "skills", "sha256", "hookParents"].includes(key)) && witness.schema === "hasna.codex-semantic-cache-witness.v1" && typeof witness.sha256 === "string" && /^[a-f0-9]{64}$/.test(witness.sha256));
       text(proof.configPath);
       requireBound(isAbsolute3(proof.configPath) && resolve5(proof.configPath) === proof.configPath && basename3(proof.configPath) === "config.toml");
       text(witness.cacheRoot);
@@ -2663,6 +2663,20 @@ function assertAgentPolicyCollections(policy) {
           text(parent[key]);
         requireBound(isAbsolute3(parent.pluginParent) && resolve5(parent.pluginParent) === parent.pluginParent);
       }
+      if (proof.reviewedHookParents !== undefined)
+        for (const parent of array(proof.reviewedHookParents, 4096)) {
+          requireBound(object(parent) && parent.role === "reviewed-hook" && (parent.installation === "remote-receipt" && Object.keys(parent).length === 6 || parent.installation === "local-marketplace" && Object.keys(parent).length === 7));
+          requireBound(parent.installation === "remote-receipt" ? Object.keys(parent).sort().join(",") === "installation,namespace,pluginId,pluginParent,remotePluginId,role" : Object.keys(parent).sort().join(",") === "installation,marketplaceSha256,marketplaceSourcePath,namespace,pluginId,pluginParent,role");
+          for (const key of ["pluginId", "namespace", "pluginParent", "installation"])
+            text(parent[key]);
+          if (parent.installation === "remote-receipt")
+            text(parent.remotePluginId);
+          else {
+            text(parent.marketplaceSourcePath);
+            requireBound(typeof parent.marketplaceSha256 === "string" && /^[a-f0-9]{64}$/.test(parent.marketplaceSha256) && isAbsolute3(parent.marketplaceSourcePath) && resolve5(parent.marketplaceSourcePath) === parent.marketplaceSourcePath && basename3(parent.marketplaceSourcePath) === "marketplace.json");
+          }
+          requireBound(isAbsolute3(parent.pluginParent) && resolve5(parent.pluginParent) === parent.pluginParent);
+        }
       for (const row of [...array(witness.controls, 4096), ...array(witness.appOnlyParents, 4096)]) {
         requireBound(object(row));
         for (const key of ["pluginId", "namespace", "pluginParent"])
@@ -2671,6 +2685,26 @@ function assertAgentPolicyCollections(policy) {
           if (row[key] !== undefined)
             requireBound(typeof row[key] === "string" && /^[a-f0-9]{64}$/.test(row[key]));
       }
+      if (witness.hookParents !== undefined)
+        for (const row of array(witness.hookParents, 4096)) {
+          requireBound(object(row) && row.role === "reviewed-hook" && (row.installation === "remote-receipt" && Object.keys(row).length === 9 || row.installation === "local-marketplace" && Object.keys(row).length === 9));
+          requireBound(row.installation === "remote-receipt" ? Object.keys(row).sort().join(",") === "hooksSha256,installation,manifestSha256,namespace,pluginId,pluginParent,receiptSha256,remotePluginId,role" : Object.keys(row).sort().join(",") === "hooksSha256,installation,manifestSha256,marketplaceSha256,marketplaceSourcePath,namespace,pluginId,pluginParent,role");
+          for (const key of ["pluginId", "namespace", "pluginParent", "installation"])
+            text(row[key]);
+          if (row.installation === "remote-receipt")
+            text(row.remotePluginId);
+          else {
+            text(row.marketplaceSourcePath);
+            requireBound(typeof row.marketplaceSha256 === "string" && /^[a-f0-9]{64}$/.test(row.marketplaceSha256) && isAbsolute3(row.marketplaceSourcePath) && resolve5(row.marketplaceSourcePath) === row.marketplaceSourcePath && basename3(row.marketplaceSourcePath) === "marketplace.json");
+          }
+          requireBound(isAbsolute3(row.pluginParent) && resolve5(row.pluginParent) === row.pluginParent);
+          for (const key of ["manifestSha256", "hooksSha256"])
+            requireBound(typeof row[key] === "string" && /^[a-f0-9]{64}$/.test(row[key]));
+          if (row.installation === "remote-receipt")
+            requireBound(typeof row.receiptSha256 === "string" && /^[a-f0-9]{64}$/.test(row.receiptSha256));
+          else
+            requireBound(row.receiptSha256 === undefined);
+        }
       for (const skill of array(witness.skills, 4096)) {
         requireBound(object(skill));
         for (const key of ["name", "pluginId", "namespace", "pluginParent"])
@@ -2864,6 +2898,78 @@ function detectedIntegrationAgents(options = {}) {
 import { spawnSync as spawnSync2 } from "child_process";
 import { accessSync, constants as constants4, existsSync as existsSync4, lstatSync as lstatSync5, realpathSync, statSync as statSync2 } from "fs";
 import { delimiter, isAbsolute as isAbsolute4, join as join8, resolve as resolve7 } from "path";
+
+// src/lib/hook-diagnostics.ts
+var CONTEXT_ERROR_CODES = new Set([
+  "SKILLS_API_CREDENTIAL_UNAVAILABLE",
+  "SKILLS_API_UNAVAILABLE",
+  "SKILLS_API_UNAUTHORIZED",
+  "SKILLS_API_FORBIDDEN",
+  "SKILLS_API_RESOURCE_UNAVAILABLE",
+  "SESSION_WRITE_BUSY",
+  "SKILLS_CONTEXT_FAILED",
+  "SKILLS_STORAGE_FULL",
+  "PROFILE_LOCK_MISMATCH",
+  "PROFILE_IDENTITY_MISMATCH",
+  "PROFILE_APPLIED_REPORT_FAILED",
+  "CACHED_AUTHORITY_REQUIRED",
+  "CACHED_PROFILE_EXPIRED",
+  "CACHED_PROFILE_MISSING",
+  "CACHED_BUNDLE_MISSING",
+  "INVALID_CONTEXT_INPUT",
+  "CONTEXT_INPUT_TOO_LARGE",
+  "INVALID_CONTEXT_BUDGET",
+  "INVALID_SELECTION",
+  "INVALID_SELECTION_ALIASES",
+  "INVALID_RECEIPT",
+  "INVALID_CACHE_FILE",
+  "UNSAFE_CACHE_PATH",
+  "RECEIPT_TOO_LARGE",
+  "BUNDLE_DIGEST_MISMATCH",
+  "BUNDLE_IDENTITY_MISMATCH",
+  "BUNDLE_UNAVAILABLE",
+  "BUNDLE_TOO_LARGE",
+  "SKILL_NOT_SELECTED",
+  "INVALID_SESSION",
+  "SESSION_PARENT_NOT_FOUND",
+  "SESSION_PARENT_MISMATCH",
+  "SESSION_NOT_FOUND",
+  "SESSION_GENERATION_CHANGED",
+  "SESSION_GENERATION_EXHAUSTED",
+  "SESSION_PARENT_CHANGED",
+  "SESSION_RECEIPT_CHANGED",
+  "SESSION_RECONCILIATION_REQUIRED",
+  "SESSION_RENEWAL_TIMEOUT",
+  "SESSION_CONTEXT_CONFLICT",
+  "SESSION_RECONCILIATION_INCOMPLETE",
+  "SESSION_WRITE_LOCKED",
+  "SESSION_WRITE_LOCK_CHANGED",
+  "SESSION_LOCK_RECOVERY_INCOMPLETE"
+]);
+var HOOK_REFUSAL_REASON_CODES = Object.freeze([
+  ...CONTEXT_ERROR_CODES,
+  "SKILLS_HOOK_FAILED",
+  "SKILLS_HOOK_TIMEOUT",
+  "SKILLS_HOOK_INVALID_RESPONSE"
+]);
+var OPTIONAL_CONTEXT_FAILURES = new Set([
+  "SKILLS_API_CREDENTIAL_UNAVAILABLE",
+  "SKILLS_API_UNAVAILABLE",
+  "SKILLS_API_UNAUTHORIZED",
+  "SKILLS_API_FORBIDDEN",
+  "SKILLS_API_RESOURCE_UNAVAILABLE",
+  "CACHED_PROFILE_EXPIRED",
+  "CACHED_PROFILE_MISSING",
+  "CACHED_BUNDLE_MISSING",
+  "SESSION_RECONCILIATION_REQUIRED",
+  "SESSION_RENEWAL_TIMEOUT",
+  "SESSION_WRITE_BUSY",
+  "SESSION_PARENT_CHANGED",
+  "SESSION_CONTEXT_CONFLICT",
+  "SKILLS_HOOK_TIMEOUT"
+]);
+
+// src/lib/agent-sumi.ts
 var SUMI_PATH_SELECTORS = ["SUMI_HOME", "SUMI_CONFIG_DIR", "XDG_DATA_HOME", "XDG_CACHE_HOME", "XDG_CONFIG_HOME", "XDG_STATE_HOME"];
 var SUMI_PATH_KEYS = ["data", "cache", "config", "state"];
 var SUMI_PATH_OUTPUT_LIMIT = 128 * 1024;
@@ -3005,24 +3111,33 @@ function sumiConfigPath(home, cwd = process.cwd(), env = process.env) {
   return join8(sumiConfigDirectory(home, env, cwd), "sumi.json");
 }
 function renderSumiPlugin(command, profile) {
-  return renderSumiPluginVersion(command, profile, false);
+  return renderSumiPluginVersion(command, profile, 3);
 }
 function isManagedSumiPlugin(text2, command, profile) {
-  return text2 === renderSumiPlugin(command, profile) || text2 === renderSumiPluginVersion(command, profile, true);
+  return text2 === renderSumiPlugin(command, profile) || text2 === renderSumiPluginVersion(command, profile, 2) || text2 === renderSumiPluginVersion(command, profile, 1);
 }
-function renderSumiPluginVersion(command, profile, legacy) {
+function renderSumiPluginVersion(command, profile, version2) {
+  const legacy = version2 === 1;
   const failure = (message) => legacy ? `new Error(${JSON.stringify(message)})` : "refusal()";
   return `// Managed by @hasna/skills. Regenerate with skills hook install --agent sumi.
 import { spawn } from "node:child_process";
 const command = ${JSON.stringify(command)};
 const profile = ${JSON.stringify(profile)};
-${legacy ? "" : `function refusal() {
-  const error = new Error("Skills verification blocked this request. Review the Sumi Skills hook configuration, then retry.");
+${legacy ? "" : `function refusal(${version2 === 3 ? "reasonCode" : ""}) {
+  const error = new Error("Skills verification blocked this request. Review the Sumi Skills hook configuration, then retry."${version2 === 3 ? ' + (reasonCode ? " [" + reasonCode + "]" : "")' : ""});
   error.name = "SkillsHookRefusal";
-  error.skillsHookRefusal = { version: 1, code: "SKILLS_HOOK_REFUSED" };
+  error.skillsHookRefusal = { version: 1, code: "SKILLS_HOOK_REFUSED"${version2 === 3 ? ", ...(reasonCode ? { reasonCode } : {})" : ""} };
   return error;
 }
-`}function context(input) {
+`}${version2 === 3 ? `const reasonCodes = new Set(${JSON.stringify(HOOK_REFUSAL_REASON_CODES)});
+function refusedResult(result) {
+  const reason = result.reason ?? result.stopReason ?? result.systemMessage;
+  if (typeof reason !== "string" || reason.length > 16384) return refusal();
+  if (reason.startsWith("NATIVE_SKILL_DRIFT:")) return refusal("NATIVE_SKILL_DRIFT");
+  const code = /^Skills context is unavailable \\[([A-Z_]+)\\]/.exec(reason)?.[1];
+  return refusal(reasonCodes.has(code) ? code : undefined);
+}
+` : ""}function context(input) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, ["hook", "user-prompt", "--agent", "sumi", "--selection-profile", profile], { cwd: input.cwd, stdio: ["pipe", "pipe", "pipe"] });
     const chunks = []; let bytes = 0, failure;
@@ -3037,12 +3152,12 @@ ${legacy ? "" : `function refusal() {
       try {
         const result = JSON.parse(Buffer.concat(chunks).toString("utf8"));
         if (!result || typeof result !== "object" || Array.isArray(result)) throw ${failure("Invalid Skills hook response")};
-        if (result.decision === "block" || result.continue === false) throw ${failure("Skills prompt hook refused")};
+        if (result.decision === "block" || result.continue === false) throw ${version2 === 3 ? "refusedResult(result)" : failure("Skills prompt hook refused")};
         if (Object.keys(result).length && (!result.hookSpecificOutput || result.hookSpecificOutput.hookEventName !== input.hook_event_name)) throw ${failure("Invalid Skills hook response")};
         const text = result.hookSpecificOutput?.additionalContext ?? "";
         if (typeof text !== "string") throw ${failure("Invalid Skills prompt context")};
         resolve(text);
-      } catch (error) { reject(${legacy ? "error" : "refusal()"}); }
+      } catch (error) { reject(${legacy ? "error" : version2 === 3 ? 'error instanceof Error && error.name === "SkillsHookRefusal" ? error : refusal()' : "refusal()"}); }
     });
     child.stdin.end(JSON.stringify(input));
   });
@@ -3075,9 +3190,13 @@ export default {
       sessions.add(event.sessionID);
     }));
     registrations.push(await ctx.session.hook("context", async event => {
-      const last = event.messages.findLast(message => message.role === "user");
+${version2 === 3 ? `      // Model messages also contain checkpoints, attachments and synthetic
+      // user-role history, with no owner-prompt provenance. Prompt admission
+      // already matched and persisted Skills; restore that verified state only.
+      const prompt = "";
+` : `      const last = event.messages.findLast(message => message.role === "user");
       const prompt = (last?.content ?? []).filter(part => part.type === "text").map(part => part.text).join("\\n");
-      // Recheck on every primary request, including resumed and synthetic
+`}      // Recheck on every primary request, including resumed and synthetic
       // sessions. The CLI owns optional failures versus explicit refusals.
       const text = await context(await input(event.sessionID, prompt, !sessions.has(event.sessionID)));
       if (text) event.system.push({ type: "text", text });