@hasna/skills 0.10.63 → 0.10.65

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

@@ -4,19 +4,34 @@ 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";
 export { captureDiscoveryDirectories, type DiscoveryDirectory } from "./agent-discovery-directories.js";
 export interface DiscoverySource {
     reviewArtifact?: RetainedReviewArtifact;
     path: string;
     sha256: string | null;
-    hashMode?: "bytes" | "path-bytes" | "claude-plugin-manifest-v1" | "claude-plugin-registry" | "claude-marketplace-registry" | "claude-settings-v1" | "claude-settings-v2" | "claude-settings-v3" | "claude-settings-v4" | "claude-marketplace-registry-v2" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4" | "sumi-settings-v1" | "claude-marketplace-entry-v1";
+    hashMode?: "bytes" | "path-bytes" | "claude-plugin-manifest-v1" | "claude-plugin-registry" | "claude-marketplace-registry" | "claude-settings-v1" | "claude-settings-v2" | "claude-settings-v3" | "claude-settings-v4" | "claude-marketplace-registry-v2" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4" | "codex-settings-v5" | "sumi-settings-v1" | "claude-marketplace-entry-v1";
     managedPlugins?: ManagedPluginRegistrationWitness[];
     format?: "json" | "toml" | "yaml";
     fields?: string[];
     marketplace?: string;
     plugin?: string;
 }
+export interface CodexSemanticCacheDiscovery {
+    schema: "hasna.codex-semantic-cache-discovery.v1";
+    configPath: string;
+    hookRootAlias: {
+        alias: string;
+        target: string;
+    } | null;
+    witness: CodexSemanticCacheWitness;
+    appOnlyParents: CodexSemanticCacheAppOnlyParent[];
+    previousPolicySha256: string;
+    supersededSources: DiscoverySource[];
+    supersededDirectories: DiscoveryDirectory[];
+}
 export interface AgentDiscoveryBinding {
+    codexSemanticCache?: CodexSemanticCacheDiscovery;
     agent: IntegrationAgent;
     roots: string[];
     sources: DiscoverySource[];
@@ -76,7 +91,16 @@ export declare function projectNativeDiscoveryFields(text: string, format: "json
 /** Called only after the owning planner validated discovery and capabilities.
  * New roots must already be body-free; absent roots need the prior typed proof. */
 export declare function captureRetiredCodexDiscovery(binding: AgentDiscoveryBinding, controls: CodexPluginSkillControl[], rules: unknown): AgentDiscoveryBinding;
-export declare function verifyAgentDiscovery(binding: AgentDiscoveryBinding, codexRecovery?: CodexHookDiscoveryRecovery): void;
+/** 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 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 {
+    agent: IntegrationAgent;
+    alias: string;
+    target: string;
+}[]): void;
 export declare function rebindAgentDiscovery(binding: AgentDiscoveryBinding, changes: Map<string, string>): AgentDiscoveryBinding;
 /** Capture full byte witnesses for reviewed source or executable files; never import or execute them. */
 export declare function captureDiscoveryByteSources(paths: string[]): DiscoverySource[];

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

@@ -48,6 +48,7 @@ export interface AgentConfigChange {
     after: string;
 }
 export interface AgentIntegrationPlan {
+    cacheWitnessUpgrade?: CodexSemanticCacheUpgrade;
     reviewArtifactSources?: Array<{
         path: string;
         sha256: string;
@@ -202,7 +203,7 @@ export declare function planClaudeHookEventsUpdate(options: ClaudeHookUpdateOpti
  */
 export declare function planAgentSettingsWitnessUpgrade(options: {
     agent: "claude" | "codex" | "sumi";
-    targetCodexVersion?: 2 | 3 | 4;
+    targetCodexVersion?: 2 | 3 | 4 | 5;
     targetClaudeVersion?: 3 | 4;
     reviewedPreimage: string;
     home?: string;
@@ -211,6 +212,18 @@ export declare function planAgentSettingsWitnessUpgrade(options: {
     expectedPolicySha256: string;
     expectedSettingsSha256: string;
 }): AgentIntegrationPlan;
+export interface CodexSemanticCacheUpgrade {
+    agent: "codex";
+    appOnlyParents: string[];
+    expectedPolicySha256: string;
+    expectedSettingsSha256: string;
+    expectedCacheWitnessSha256?: string;
+    home?: string;
+    dataDir?: string;
+}
+/** Explicit current capability review. Old aggregate directory digests remain
+ * evidence, not a reconstructed historical tree or a new byte baseline. */
+export declare function planCodexSemanticCacheWitnessUpgrade(options: CodexSemanticCacheUpgrade): AgentIntegrationPlan;
 export interface ReviewArtifactMigration {
     kind: "codex-native-catalog";
     sourcePath: string;

package/dist/lib/codex-plugin-skill-controls.d.ts

@@ -32,6 +32,15 @@ export interface CodexPluginSourceInput {
     sourceSha256: string;
 }
 type Read = (path: string) => string;
+export interface CodexPluginRootControls {
+    namespace: string;
+    manifestSha256: string;
+    appSha256?: string;
+    mcpSha256?: string;
+}
+/** Reuse the strict package-owned capability parser for an explicitly reviewed
+ * plugin materialization. This does not establish parent or receipt identity. */
+export declare function readCodexPluginRootControls(root: string, read: Read): CodexPluginRootControls;
 export interface CodexPluginCacheDocumentIdentity {
     name: string;
     namespace: string;

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

@@ -0,0 +1,57 @@
+import { type CodexPluginSkillControl } from "./codex-plugin-skill-controls.js";
+export declare const CODEX_SEMANTIC_CACHE_WITNESS_SCHEMA: "hasna.codex-semantic-cache-witness.v1";
+export interface CodexSemanticCacheControl {
+    pluginId: string;
+    namespace: string;
+    pluginParent: string;
+    remotePluginId?: string;
+    receiptSha256?: string;
+    manifestSha256: string;
+    appSha256?: string;
+    mcpSha256?: string;
+}
+export interface CodexSemanticCacheSkill {
+    name: string;
+    pluginId: string;
+    namespace: string;
+    pluginParent: string;
+    disabledRules: string[];
+}
+/** Caller explicitly classifies a remote plugin parent whose only reviewed
+ * capability is its app integration and whose cache contains no Skill docs. */
+export interface CodexSemanticCacheAppOnlyParent {
+    role: "app-only";
+    pluginId: string;
+    namespace: string;
+    pluginParent: string;
+    remotePluginId: string;
+}
+export interface CodexSemanticCacheAppOnlyParentWitness extends CodexSemanticCacheAppOnlyParent {
+    receiptSha256: string;
+    manifestSha256: string;
+    appSha256: string;
+    mcpSha256?: string;
+}
+export interface CodexSemanticCacheWitness {
+    schema: typeof CODEX_SEMANTIC_CACHE_WITNESS_SCHEMA;
+    cacheRoot: string;
+    controls: CodexSemanticCacheControl[];
+    appOnlyParents: CodexSemanticCacheAppOnlyParentWitness[];
+    skills: CodexSemanticCacheSkill[];
+    sha256: string;
+}
+export interface CaptureCodexSemanticCacheWitnessOptions {
+    cacheRoot: string;
+    controls: CodexPluginSkillControl[];
+    /** Explicit package-reviewed parents; absence never infers this role. */
+    appOnlyParents?: CodexSemanticCacheAppOnlyParent[];
+    rules: unknown;
+    /** Package-owned, bounded read used by the existing semantic control review. */
+    read?: (path: string) => string;
+}
+/** 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;
+/** Verify without mutating or replacing the saved witness. Version refreshes
+ * pass only when their complete semantic projection and qualified names match. */
+export declare function assertCodexSemanticCacheWitnessUnchanged(previous: CodexSemanticCacheWitness, current: CodexSemanticCacheWitness): void;

package/dist/lib/codex-settings-witness.d.ts

@@ -46,3 +46,17 @@ export declare function upgradeCodexSettingsWitnessV4(previous: {
     hashMode?: "bytes" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3";
     sha256: string;
 }, reviewedSettingsPath: string): ReturnType<typeof captureCodexSettingsV4>;
+/** Explicit V5 adds only schema-valid root status-line string vectors. */
+export declare function hashCodexSettingsReplacementV5(text: string, budget?: ClaudeSettingsWitnessBudget): string;
+export declare function captureCodexSettingsV5(path: string, budget?: ClaudeSettingsWitnessBudget): {
+    path: string;
+    hashMode: "codex-settings-v5";
+    sha256: string;
+};
+/** A V5 hash never verifies an old pin: prove the preserved original under its
+ * exact original contract before comparing old/current under V5. */
+export declare function upgradeCodexSettingsWitnessV5(previous: {
+    path: string;
+    hashMode?: "bytes" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4";
+    sha256: string;
+}, reviewedSettingsPath: string): ReturnType<typeof captureCodexSettingsV5>;

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.63";
+var version = "0.10.65";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -2642,6 +2642,53 @@ function assertAgentPolicyCollections(policy) {
           requireBound(directory.sha256 === null || typeof directory.sha256 === "string" && /^[a-f0-9]{64}$/.test(directory.sha256));
         }
     }
+    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));
+      text(proof.configPath);
+      requireBound(isAbsolute3(proof.configPath) && resolve5(proof.configPath) === proof.configPath && basename3(proof.configPath) === "config.toml");
+      text(witness.cacheRoot);
+      requireBound(isAbsolute3(witness.cacheRoot) && resolve5(witness.cacheRoot) === witness.cacheRoot);
+      if (proof.hookRootAlias !== null) {
+        requireBound(object(proof.hookRootAlias) && Object.keys(proof.hookRootAlias).length === 2);
+        for (const key of ["alias", "target"]) {
+          text(proof.hookRootAlias[key]);
+          requireBound(isAbsolute3(proof.hookRootAlias[key]) && resolve5(proof.hookRootAlias[key]) === proof.hookRootAlias[key]);
+        }
+      }
+      const parents2 = array(proof.appOnlyParents, 4096);
+      for (const parent of parents2) {
+        requireBound(object(parent) && Object.keys(parent).length === 5 && parent.role === "app-only");
+        for (const key of ["pluginId", "namespace", "pluginParent", "remotePluginId"])
+          text(parent[key]);
+        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"])
+          text(row[key]);
+        for (const key of ["manifestSha256", "appSha256", "mcpSha256", "receiptSha256"])
+          if (row[key] !== undefined)
+            requireBound(typeof row[key] === "string" && /^[a-f0-9]{64}$/.test(row[key]));
+      }
+      for (const skill of array(witness.skills, 4096)) {
+        requireBound(object(skill));
+        for (const key of ["name", "pluginId", "namespace", "pluginParent"])
+          text(skill[key]);
+        for (const rule of array(skill.disabledRules, 4096))
+          text(rule);
+      }
+      for (const source of array(proof.supersededSources, AGENT_POLICY_LIMITS.discoverySources)) {
+        requireBound(object(source));
+        text(source.path);
+        requireBound(source.sha256 === null || typeof source.sha256 === "string" && /^[a-f0-9]{64}$/.test(source.sha256));
+      }
+      for (const directory of array(proof.supersededDirectories, AGENT_POLICY_LIMITS.discoveryDirectories)) {
+        requireBound(object(directory));
+        text(directory.path);
+        requireBound(directory.sha256 === null || typeof directory.sha256 === "string" && /^[a-f0-9]{64}$/.test(directory.sha256));
+      }
+    }
     for (const root of array(value.roots, AGENT_POLICY_LIMITS.discoveryRoots))
       text(root);
     for (const source of array(value.sources, AGENT_POLICY_LIMITS.discoverySources)) {
@@ -2649,12 +2696,12 @@ function assertAgentPolicyCollections(policy) {
       text(source.path);
       requireBound(source.sha256 === null || typeof source.sha256 === "string" && /^[a-f0-9]{64}$/.test(source.sha256));
       if (source.hashMode !== undefined)
-        requireBound(["bytes", "path-bytes", "claude-plugin-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "sumi-settings-v1", "claude-marketplace-entry-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
+        requireBound(["bytes", "path-bytes", "claude-plugin-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "codex-settings-v5", "sumi-settings-v1", "claude-marketplace-entry-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
       if (source.hashMode === "claude-plugin-manifest-v1")
         requireBound(agent === "claude" && value.agent === "claude" && ["automatic", "reviewed"].includes(value.method) && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve5(source.path) === source.path && source.path.endsWith(join5(sep, ".claude-plugin", "plugin.json")) && source.managedPlugins === undefined);
       if (source.hashMode === "sumi-settings-v1")
         requireBound(agent === "sumi" && value.agent === "sumi" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve5(source.path) === source.path && basename3(source.path) === "sumi.json");
-      if (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4"))
+      if (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4" || source.hashMode === "codex-settings-v5"))
         requireBound(agent === "codex" && value.agent === "codex" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve5(source.path) === source.path && basename3(source.path) === "config.toml");
       if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4"))
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve5(source.path) === source.path && basename3(source.path) === "settings.json");
@@ -2817,6 +2864,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;
@@ -2958,24 +3077,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;
@@ -2990,12 +3118,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));
   });
@@ -3028,9 +3156,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 });