@hasna/skills 0.9.16 → 0.9.17

package/bin/index.js

@@ -36868,7 +36868,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.9.16",
+    version: "0.9.17",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -39947,8 +39947,8 @@ 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-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-marketplace-registry-v2"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
-      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2")
+        requireBound(["bytes", "path-bytes", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-marketplace-registry-v2"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
+      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3")
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute2(source.path) && resolve3(source.path) === source.path && basename2(source.path) === "settings.json");
       if (source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2")
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute2(source.path) && resolve3(source.path) === source.path && basename2(source.path) === "known_marketplaces.json");
@@ -50545,7 +50545,7 @@ function canonical2(value) {
     return { kind: "array", items: value.items.map(canonical2) };
   return value;
 }
-function inferencePreference(key, child) {
+function inferencePreference(key, child, version) {
   if (key === "skipDangerousModePermissionPrompt") {
     need2(child.kind === "literal" && (child.value === "true" || child.value === "false"), "contains an invalid dialog acknowledgment");
     return false;
@@ -50558,7 +50558,7 @@ function inferencePreference(key, child) {
     return false;
   need2(child.kind === "object", "requires an object of model preferences");
   child.entries = child.entries.filter(([model, preferences]) => {
-    if (!BUILTIN_MODEL_SELECTIONS.has(model) || preferences.kind !== "object" || preferences.entries.length !== 1 || preferences.entries[0][0] !== "effortLevel")
+    if (version === 2 && !BUILTIN_MODEL_SELECTIONS.has(model) || preferences.kind !== "object" || preferences.entries.length !== 1 || preferences.entries[0][0] !== "effortLevel")
       return true;
     const effort = preferences.entries[0][1];
     need2(effort.kind === "string" && PERSISTED_EFFORT_LEVELS.has(effort.value), "contains an invalid persisted model effort level");
@@ -50569,7 +50569,7 @@ function inferencePreference(key, child) {
 function settingsDigest(text2, version = 1) {
   const value = parse3(text2);
   value.entries = value.entries.filter(([key, child]) => {
-    if (version === 2 && inferencePreference(key, child))
+    if (version !== 1 && inferencePreference(key, child, version))
       return false;
     if (key === "model") {
       need2(child.kind === "string", "contains an invalid model selection");
@@ -50607,6 +50607,16 @@ function hashClaudeSettingsReplacementV2(text2, budget) {
   budget.remaining -= bytes;
   return settingsDigest(text2, 2);
 }
+function captureClaudeSettingsV3(path, budget = { remaining: 256 * 1024 * 1024 }) {
+  return { path, hashMode: "claude-settings-v3", sha256: settingsDigest(readSettings(path, budget), 3) };
+}
+function hashClaudeSettingsReplacementV3(text2, budget) {
+  need2(typeof text2 === "string", "requires settings text");
+  const bytes = Buffer.byteLength(text2);
+  need2(bytes <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes && Number.isSafeInteger(budget.remaining) && budget.remaining >= bytes, "exceeds its byte limit");
+  budget.remaining -= bytes;
+  return settingsDigest(text2, 3);
+}
 var CLAUDE_SETTINGS_WITNESS_LIMITS, sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino && a.mode === b.mode && a.uid === b.uid && a.gid === b.gid && a.nlink === b.nlink && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs, BOOLEAN_PREFERENCES, ENUM_PREFERENCES, BUILTIN_MODEL_SELECTIONS, PERSISTED_EFFORT_LEVELS;
 var init_claude_settings_witness = __esm(() => {
   CLAUDE_SETTINGS_WITNESS_LIMITS = Object.freeze({ bytes: 1024 * 1024, rows: 1024, depth: 32, nodes: 65536, stringCharacters: 16384, pathCharacters: 4096 });
@@ -54886,13 +54896,13 @@ function read2(path, changes) {
   return readFileSync17(path, "utf8");
 }
 function projected(source, changes, budget = discoveryByteBudget()) {
-  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") {
+  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256))
       throw new Error("Claude settings witnesses require exact typed metadata");
-    const current = (source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget).sha256;
+    const current = (source.hashMode === "claude-settings-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget).sha256;
     if (current !== source.sha256)
       throw new Error(`Native discovery input changed; run skills hook install with a fresh discovery review: ${source.path}`);
-    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget) : current;
+    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget) : current;
   }
   if (source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2") {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256) || changes?.has(source.path))
@@ -54954,7 +54964,7 @@ function verifyAgentDiscovery(binding, codexRecovery) {
     safe4(root2);
 }
 function assertMarketplaceBinding(binding, source) {
-  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && (binding.agent !== "claude" || binding.method !== "reviewed" || basename8(source.path) !== "settings.json"))
+  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && (binding.agent !== "claude" || binding.method !== "reviewed" || basename8(source.path) !== "settings.json"))
     throw new Error("Claude settings witnesses require explicit reviewed Claude configuration");
   if ((source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2") && (binding.agent !== "claude" || binding.method !== "reviewed"))
     throw new Error("Claude marketplace witnesses require explicit reviewed Claude discovery");
@@ -55085,7 +55095,7 @@ function resolveAgentDiscovery(options) {
     verifyAgentDiscovery(retained);
     if (!retained.sources.some((source) => source.path === canonical4(configPath) && source.format === undefined && source.fields === undefined))
       unresolved("retained review is missing the full agent configuration source");
-    if (retained.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && source.path !== canonical4(configPath)))
+    if (retained.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && source.path !== canonical4(configPath)))
       unresolved("retained settings witness names another configuration source");
     if (sources.some((source) => !retained.sources.some((saved) => isDeepStrictEqual7(saved, source))) || [...roots].some((root2) => !retained.roots.includes(root2)) || agent === "gemini" && JSON.stringify(retained.builtinNames) !== JSON.stringify(builtinNames))
       unresolved("retained review is missing current runtime discovery coverage");
@@ -55101,7 +55111,7 @@ function resolveAgentDiscovery(options) {
     if (review.sources.some((source) => source.format !== undefined || source.fields !== undefined))
       throw new Error("Explicit discovery reviews require full source-file hashes");
     verifyAgentDiscovery(supplied);
-    if (review.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && source.path !== canonical4(configPath)))
+    if (review.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && source.path !== canonical4(configPath)))
       throw new Error("Semantic settings witnesses must name the configured Claude configuration source");
     if (!review.sources.some((source) => source.path === canonical4(configPath)))
       throw new Error("Discovery review must include the agent configuration source");
@@ -80156,8 +80166,9 @@ Preserved original receipt: ${result2.archivePath}` : `Planned one session recon
   });
 }
 function reportContextError(error61, json2 = false) {
-  const code = error61 instanceof SkillSelectionError ? error61.code : "SKILLS_CONTEXT_FAILED";
-  const message = error61 instanceof SkillSelectionError ? error61.message : "Skills context could not be loaded. Check authentication and the selected profile.";
+  const storageFull = error61 instanceof Error && ["ENOSPC", "EDQUOT"].includes(error61.code ?? "");
+  const code = error61 instanceof SkillSelectionError ? error61.code : storageFull ? "SKILLS_STORAGE_FULL" : "SKILLS_CONTEXT_FAILED";
+  const message = error61 instanceof SkillSelectionError ? error61.message : storageFull ? "Skills could not save verified local state because the filesystem is full or its quota is exhausted. Free space through your approved recoverable cleanup process, then retry the same session." : "Skills context could not be loaded. Check authentication and the selected profile.";
   if (json2)
     console.log(JSON.stringify({ error: { code, message } }));
   else
@@ -108616,7 +108627,7 @@ async function connectCodexHookRpc(options) {
 }
 var SUPPORTED_CODEX_HOOK_VERSIONS;
 var init_codex_hook_rpc = __esm(() => {
-  SUPPORTED_CODEX_HOOK_VERSIONS = ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.155.0", "codex-cli 0.155.1"];
+  SUPPORTED_CODEX_HOOK_VERSIONS = ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.155.0", "codex-cli 0.155.1", "codex-cli 0.156.1"];
 });
 
 // src/lib/codex-hook-trust-identity.ts
@@ -109054,6 +109065,9 @@ function hookFailureReason(error61, profileId) {
   const profile = typeof profileId === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(profileId) && !profileId.includes("..") ? profileId : undefined;
   const identity4 = [profile ? `profile=${profile}` : undefined, owned ? `stage=${error61.stage}` : undefined].filter(Boolean).join(", ");
   const prefix = `Skills context is unavailable [${code2}]${identity4 ? ` (${identity4})` : ""}.`;
+  if (code2 === "SKILLS_STORAGE_FULL") {
+    return `${prefix} The filesystem is full or its quota is exhausted. Free space through your approved recoverable cleanup process, then retry the same session. Do not delete session receipts or change credentials to bypass this failure.`;
+  }
   if (code2 === "PROFILE_LOCK_MISMATCH") {
     return `${prefix} This session or project is pinned to a different profile. Inspect the session with skills sessions show <session-id> --json; review skills sessions reconcile for an intentional session change, or explicit project sync for a project change. Sync alone does not change that pin.`;
   }
@@ -109070,6 +109084,7 @@ var CONTEXT_ERROR_CODES, HookDiagnosticError;
 var init_hook_diagnostics = __esm(() => {
   CONTEXT_ERROR_CODES = new Set([
     "SKILLS_CONTEXT_FAILED",
+    "SKILLS_STORAGE_FULL",
     "PROFILE_LOCK_MISMATCH",
     "PROFILE_IDENTITY_MISMATCH",
     "PROFILE_APPLIED_REPORT_FAILED",
@@ -109185,10 +109200,10 @@ function agents(value) {
 }
 function registerAgentIntegration(parent) {
   const hook = parent.command("hook").description("Load selected Skills context through agent lifecycle hooks");
-  hook.command("witness").requiredOption("--kind <kind>", "claude-settings-v2 or claude-marketplace-registry-v2").requiredOption("--path <path>", "Canonical absolute path to the reviewed settings or registry file").option("--json", "Output the discovery witness as JSON", false).description("Capture an explicit versioned review witness without installing it").action(async (options) => {
-    const capture2 = options.kind === "claude-settings-v2" ? captureClaudeSettingsV2 : options.kind === "claude-marketplace-registry-v2" ? captureClaudeMarketplaceRegistryV2 : null;
+  hook.command("witness").requiredOption("--kind <kind>", "claude-settings-v3, claude-settings-v2 or claude-marketplace-registry-v2").requiredOption("--path <path>", "Canonical absolute path to the reviewed settings or registry file").option("--json", "Output the discovery witness as JSON", false).description("Capture an explicit versioned review witness without installing it").action(async (options) => {
+    const capture2 = options.kind === "claude-settings-v3" ? captureClaudeSettingsV3 : options.kind === "claude-settings-v2" ? captureClaudeSettingsV2 : options.kind === "claude-marketplace-registry-v2" ? captureClaudeMarketplaceRegistryV2 : null;
     if (!capture2)
-      throw new Error("Unsupported witness kind; select claude-settings-v2 or claude-marketplace-registry-v2");
+      throw new Error("Unsupported witness kind; select claude-settings-v3, claude-settings-v2 or claude-marketplace-registry-v2");
     await writeCliOutput(JSON.stringify(capture2(options.path), null, 2));
   });
   hook.command("agents").option("--json", "Output the adapter capability inventory", false).description("Show maintained native adapters and explicit coverage limits").action(async () => {

package/bin/mcp.js

@@ -20019,7 +20019,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.9.16",
+    version: "0.9.17",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -38126,8 +38126,8 @@ 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-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-marketplace-registry-v2"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
-      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2")
+        requireBound(["bytes", "path-bytes", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-marketplace-registry-v2"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
+      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3")
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve2(source.path) === source.path && basename3(source.path) === "settings.json");
       if (source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2")
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve2(source.path) === source.path && basename3(source.path) === "known_marketplaces.json");
@@ -47080,7 +47080,7 @@ function canonical2(value) {
     return { kind: "array", items: value.items.map(canonical2) };
   return value;
 }
-function inferencePreference(key, child) {
+function inferencePreference(key, child, version2) {
   if (key === "skipDangerousModePermissionPrompt") {
     need2(child.kind === "literal" && (child.value === "true" || child.value === "false"), "contains an invalid dialog acknowledgment");
     return false;
@@ -47093,7 +47093,7 @@ function inferencePreference(key, child) {
     return false;
   need2(child.kind === "object", "requires an object of model preferences");
   child.entries = child.entries.filter(([model, preferences]) => {
-    if (!BUILTIN_MODEL_SELECTIONS.has(model) || preferences.kind !== "object" || preferences.entries.length !== 1 || preferences.entries[0][0] !== "effortLevel")
+    if (version2 === 2 && !BUILTIN_MODEL_SELECTIONS.has(model) || preferences.kind !== "object" || preferences.entries.length !== 1 || preferences.entries[0][0] !== "effortLevel")
       return true;
     const effort = preferences.entries[0][1];
     need2(effort.kind === "string" && PERSISTED_EFFORT_LEVELS.has(effort.value), "contains an invalid persisted model effort level");
@@ -47104,7 +47104,7 @@ function inferencePreference(key, child) {
 function settingsDigest(text2, version2 = 1) {
   const value = parse8(text2);
   value.entries = value.entries.filter(([key, child]) => {
-    if (version2 === 2 && inferencePreference(key, child))
+    if (version2 !== 1 && inferencePreference(key, child, version2))
       return false;
     if (key === "model") {
       need2(child.kind === "string", "contains an invalid model selection");
@@ -47142,6 +47142,16 @@ function hashClaudeSettingsReplacementV2(text2, budget) {
   budget.remaining -= bytes;
   return settingsDigest(text2, 2);
 }
+function captureClaudeSettingsV3(path, budget = { remaining: 256 * 1024 * 1024 }) {
+  return { path, hashMode: "claude-settings-v3", sha256: settingsDigest(readSettings(path, budget), 3) };
+}
+function hashClaudeSettingsReplacementV3(text2, budget) {
+  need2(typeof text2 === "string", "requires settings text");
+  const bytes = Buffer.byteLength(text2);
+  need2(bytes <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes && Number.isSafeInteger(budget.remaining) && budget.remaining >= bytes, "exceeds its byte limit");
+  budget.remaining -= bytes;
+  return settingsDigest(text2, 3);
+}
 var CLAUDE_SETTINGS_WITNESS_LIMITS, sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino && a.mode === b.mode && a.uid === b.uid && a.gid === b.gid && a.nlink === b.nlink && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs, BOOLEAN_PREFERENCES, ENUM_PREFERENCES, BUILTIN_MODEL_SELECTIONS, PERSISTED_EFFORT_LEVELS;
 var init_claude_settings_witness = __esm(() => {
   CLAUDE_SETTINGS_WITNESS_LIMITS = Object.freeze({ bytes: 1024 * 1024, rows: 1024, depth: 32, nodes: 65536, stringCharacters: 16384, pathCharacters: 4096 });
@@ -48867,13 +48877,13 @@ function read(path, changes) {
   return readFileSync14(path, "utf8");
 }
 function projected(source, changes, budget = discoveryByteBudget()) {
-  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") {
+  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256))
       throw new Error("Claude settings witnesses require exact typed metadata");
-    const current = (source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget).sha256;
+    const current = (source.hashMode === "claude-settings-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget).sha256;
     if (current !== source.sha256)
       throw new Error(`Native discovery input changed; run skills hook install with a fresh discovery review: ${source.path}`);
-    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget) : current;
+    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget) : current;
   }
   if (source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2") {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256) || changes?.has(source.path))
@@ -48935,7 +48945,7 @@ function verifyAgentDiscovery(binding, codexRecovery) {
     safe4(root);
 }
 function assertMarketplaceBinding(binding, source) {
-  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && (binding.agent !== "claude" || binding.method !== "reviewed" || basename7(source.path) !== "settings.json"))
+  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && (binding.agent !== "claude" || binding.method !== "reviewed" || basename7(source.path) !== "settings.json"))
     throw new Error("Claude settings witnesses require explicit reviewed Claude configuration");
   if ((source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2") && (binding.agent !== "claude" || binding.method !== "reviewed"))
     throw new Error("Claude marketplace witnesses require explicit reviewed Claude discovery");
@@ -49016,7 +49026,7 @@ function resolveAgentDiscovery(options) {
     verifyAgentDiscovery(retained);
     if (!retained.sources.some((source) => source.path === canonical4(configPath) && source.format === undefined && source.fields === undefined))
       unresolved("retained review is missing the full agent configuration source");
-    if (retained.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && source.path !== canonical4(configPath)))
+    if (retained.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && source.path !== canonical4(configPath)))
       unresolved("retained settings witness names another configuration source");
     if (sources.some((source) => !retained.sources.some((saved) => isDeepStrictEqual2(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");
@@ -49032,7 +49042,7 @@ function resolveAgentDiscovery(options) {
     if (review.sources.some((source) => source.format !== undefined || source.fields !== undefined))
       throw new Error("Explicit discovery reviews require full source-file hashes");
     verifyAgentDiscovery(supplied);
-    if (review.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && source.path !== canonical4(configPath)))
+    if (review.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && source.path !== canonical4(configPath)))
       throw new Error("Semantic settings witnesses must name the configured Claude configuration source");
     if (!review.sources.some((source) => source.path === canonical4(configPath)))
       throw new Error("Discovery review must include the agent configuration source");

package/bin/migrate.js

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

package/bin/server.js

@@ -24122,7 +24122,7 @@ var init_dist_es9 = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.16",
+  version: "0.9.17",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

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

package/dist/index.d.ts

@@ -63,7 +63,7 @@ export { inspectSkillSession, reconcileSkillSession, type SessionReconciliationI
 export { planAgentIntegration, planClaudeStopHookUpdate, planClaudePreToolUseHookUpdate, planClaudeHookEventsUpdate, applyAgentIntegration, inventoryNativeSkills, archiveNativeSkills } from "./lib/agent-integration.js";
 export { captureDiscoveryDirectories, captureDiscoveryByteSources, captureDiscoveryPathSources, type DiscoveryDirectory, type DiscoverySource } from "./lib/agent-discovery.js";
 export { captureClaudeMarketplaceRegistry, captureClaudeMarketplaceRegistryV2 } from "./lib/claude-marketplace-registry.js";
-export { captureClaudeSettings, captureClaudeSettingsV2 } from "./lib/claude-settings-witness.js";
+export { captureClaudeSettings, captureClaudeSettingsV2, captureClaudeSettingsV3, upgradeClaudeSettingsWitness } from "./lib/claude-settings-witness.js";
 export { buildPluginProjection, pluginTreeDigest, type PluginProjectionManifest, type PluginPayloadMapping, type PluginFileWitness } from "./lib/plugin-projection.js";
 export { planPluginAdmission, admitPlugin, resolveAdmittedPlugin, pluginResolverCommand, type PluginAdmissionTarget, type PluginAdmissionBinding, type PluginAdmissionPrincipal, type PluginAdmissionPlan, type PluginAdmissionIdentity, type PluginBundleIdentity, type PluginRoutingIdentity, type PluginAdmissionReceipt } from "./lib/plugin-admission.js";
 export { captureManagedPluginRegistry, type ManagedPluginRegistrationWitness } from "./lib/plugin-discovery.js";

package/dist/index.js

@@ -9055,8 +9055,8 @@ 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-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-marketplace-registry-v2"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
-      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2")
+        requireBound(["bytes", "path-bytes", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-marketplace-registry-v2"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
+      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3")
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute2(source.path) && resolve2(source.path) === source.path && basename2(source.path) === "settings.json");
       if (source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2")
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute2(source.path) && resolve2(source.path) === source.path && basename2(source.path) === "known_marketplaces.json");
@@ -9611,7 +9611,7 @@ import { isAbsolute as isAbsolute11, join as join23, resolve as resolve11 } from
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.16",
+  version: "0.9.17",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -12874,7 +12874,7 @@ function assertClaudeHookEventsReplacement(before, replacement, events) {
   need2(JSON.stringify(withoutOwnedEvents(original)) === JSON.stringify(withoutOwnedEvents(next)), `${label} update changed settings outside hooks.${label}`);
 }
 var PERSISTED_EFFORT_LEVELS = new Set(["low", "medium", "high", "xhigh"]);
-function inferencePreference(key, child) {
+function inferencePreference(key, child, version) {
   if (key === "skipDangerousModePermissionPrompt") {
     need2(child.kind === "literal" && (child.value === "true" || child.value === "false"), "contains an invalid dialog acknowledgment");
     return false;
@@ -12887,7 +12887,7 @@ function inferencePreference(key, child) {
     return false;
   need2(child.kind === "object", "requires an object of model preferences");
   child.entries = child.entries.filter(([model, preferences]) => {
-    if (!BUILTIN_MODEL_SELECTIONS.has(model) || preferences.kind !== "object" || preferences.entries.length !== 1 || preferences.entries[0][0] !== "effortLevel")
+    if (version === 2 && !BUILTIN_MODEL_SELECTIONS.has(model) || preferences.kind !== "object" || preferences.entries.length !== 1 || preferences.entries[0][0] !== "effortLevel")
       return true;
     const effort = preferences.entries[0][1];
     need2(effort.kind === "string" && PERSISTED_EFFORT_LEVELS.has(effort.value), "contains an invalid persisted model effort level");
@@ -12898,7 +12898,7 @@ function inferencePreference(key, child) {
 function settingsDigest(text2, version = 1) {
   const value = parse3(text2);
   value.entries = value.entries.filter(([key, child]) => {
-    if (version === 2 && inferencePreference(key, child))
+    if (version !== 1 && inferencePreference(key, child, version))
       return false;
     if (key === "model") {
       need2(child.kind === "string", "contains an invalid model selection");
@@ -12936,6 +12936,25 @@ function hashClaudeSettingsReplacementV2(text2, budget) {
   budget.remaining -= bytes;
   return settingsDigest(text2, 2);
 }
+function captureClaudeSettingsV3(path, budget = { remaining: 256 * 1024 * 1024 }) {
+  return { path, hashMode: "claude-settings-v3", sha256: settingsDigest(readSettings(path, budget), 3) };
+}
+function hashClaudeSettingsReplacementV3(text2, budget) {
+  need2(typeof text2 === "string", "requires settings text");
+  const bytes = Buffer.byteLength(text2);
+  need2(bytes <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes && Number.isSafeInteger(budget.remaining) && budget.remaining >= bytes, "exceeds its byte limit");
+  budget.remaining -= bytes;
+  return settingsDigest(text2, 3);
+}
+function upgradeClaudeSettingsWitness(previous, reviewedSettingsPath) {
+  need2(previous && Object.keys(previous).every((key) => ["path", "hashMode", "sha256"].includes(key)) && (previous.hashMode === "claude-settings-v1" || previous.hashMode === "claude-settings-v2") && typeof previous.sha256 === "string" && /^[a-f0-9]{64}$/.test(previous.sha256), "requires an exact legacy settings witness");
+  const budget = { remaining: 2 * CLAUDE_SETTINGS_WITNESS_LIMITS.bytes };
+  const before = readSettings(reviewedSettingsPath, budget), current = readSettings(previous.path, budget);
+  need2(settingsDigest(before, previous.hashMode === "claude-settings-v1" ? 1 : 2) === previous.sha256, "reviewed preimage does not match the legacy witness");
+  const sha2562 = settingsDigest(current, 3);
+  need2(settingsDigest(before, 3) === sha2562, "non-preference settings changed; explicit discovery review required");
+  return { path: previous.path, hashMode: "claude-settings-v3", sha256: sha2562 };
+}
 
 // src/lib/agent-integration.ts
 var sha = (data) => createHash10("sha256").update(data).digest("hex");
@@ -16507,13 +16526,13 @@ function read2(path, changes) {
   return readFileSync16(path, "utf8");
 }
 function projected(source, changes, budget = discoveryByteBudget()) {
-  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") {
+  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256))
       throw new Error("Claude settings witnesses require exact typed metadata");
-    const current = (source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget).sha256;
+    const current = (source.hashMode === "claude-settings-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget).sha256;
     if (current !== source.sha256)
       throw new Error(`Native discovery input changed; run skills hook install with a fresh discovery review: ${source.path}`);
-    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget) : current;
+    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget) : current;
   }
   if (source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2") {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256) || changes?.has(source.path))
@@ -16575,7 +16594,7 @@ function verifyAgentDiscovery(binding, codexRecovery) {
     safe4(root2);
 }
 function assertMarketplaceBinding(binding, source) {
-  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && (binding.agent !== "claude" || binding.method !== "reviewed" || basename8(source.path) !== "settings.json"))
+  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && (binding.agent !== "claude" || binding.method !== "reviewed" || basename8(source.path) !== "settings.json"))
     throw new Error("Claude settings witnesses require explicit reviewed Claude configuration");
   if ((source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2") && (binding.agent !== "claude" || binding.method !== "reviewed"))
     throw new Error("Claude marketplace witnesses require explicit reviewed Claude discovery");
@@ -16718,7 +16737,7 @@ function resolveAgentDiscovery(options) {
     verifyAgentDiscovery(retained);
     if (!retained.sources.some((source) => source.path === canonical4(configPath) && source.format === undefined && source.fields === undefined))
       unresolved("retained review is missing the full agent configuration source");
-    if (retained.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && source.path !== canonical4(configPath)))
+    if (retained.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && source.path !== canonical4(configPath)))
       unresolved("retained settings witness names another configuration source");
     if (sources.some((source) => !retained.sources.some((saved) => isDeepStrictEqual3(saved, source))) || [...roots].some((root2) => !retained.roots.includes(root2)) || agent === "gemini" && JSON.stringify(retained.builtinNames) !== JSON.stringify(builtinNames))
       unresolved("retained review is missing current runtime discovery coverage");
@@ -16734,7 +16753,7 @@ function resolveAgentDiscovery(options) {
     if (review.sources.some((source) => source.format !== undefined || source.fields !== undefined))
       throw new Error("Explicit discovery reviews require full source-file hashes");
     verifyAgentDiscovery(supplied);
-    if (review.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && source.path !== canonical4(configPath)))
+    if (review.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && source.path !== canonical4(configPath)))
       throw new Error("Semantic settings witnesses must name the configured Claude configuration source");
     if (!review.sources.some((source) => source.path === canonical4(configPath)))
       throw new Error("Discovery review must include the agent configuration source");
@@ -43682,6 +43701,7 @@ export {
   validateCron,
   validateBlogArticleRunOptions,
   uploadSkillsSnapshotFilesToS3,
+  upgradeClaudeSettingsWitness,
   updateSkillRun,
   unsetConfig,
   unpinSkill,
@@ -43860,6 +43880,7 @@ export {
   captureDiscoveryPathSources,
   captureDiscoveryDirectories,
   captureDiscoveryByteSources,
+  captureClaudeSettingsV3,
   captureClaudeSettingsV2,
   captureClaudeSettings,
   captureClaudeMarketplaceRegistryV2,

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

@@ -6,7 +6,7 @@ export { captureDiscoveryDirectories, type DiscoveryDirectory } from "./agent-di
 export interface DiscoverySource {
     path: string;
     sha256: string | null;
-    hashMode?: "bytes" | "path-bytes" | "claude-plugin-registry" | "claude-marketplace-registry" | "claude-settings-v1" | "claude-settings-v2" | "claude-marketplace-registry-v2";
+    hashMode?: "bytes" | "path-bytes" | "claude-plugin-registry" | "claude-marketplace-registry" | "claude-settings-v1" | "claude-settings-v2" | "claude-settings-v3" | "claude-marketplace-registry-v2";
     managedPlugins?: ManagedPluginRegistrationWitness[];
     format?: "json" | "toml" | "yaml";
     fields?: string[];

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

@@ -34,3 +34,19 @@ export declare function captureClaudeSettingsV2(path: string, budget?: ClaudeSet
     sha256: string;
 };
 export declare function hashClaudeSettingsReplacementV2(text: string, budget: ClaudeSettingsWitnessBudget): string;
+/** Explicit review of model-independent effort preferences; v1/v2 stay exact. */
+export declare function captureClaudeSettingsV3(path: string, budget?: ClaudeSettingsWitnessBudget): {
+    path: string;
+    hashMode: "claude-settings-v3";
+    sha256: string;
+};
+export declare function hashClaudeSettingsReplacementV3(text: string, budget: ClaudeSettingsWitnessBudget): string;
+/** Upgrade only with an exact semantic preimage of the prior review. This
+ * proves every non-preference setting is unchanged; it never refreshes drift.
+ * Both files are bounded regular settings.json files, read without symlinks.
+ */
+export declare function upgradeClaudeSettingsWitness(previous: {
+    path: string;
+    hashMode: "claude-settings-v1" | "claude-settings-v2";
+    sha256: string;
+}, reviewedSettingsPath: string): ReturnType<typeof captureClaudeSettingsV3>;

package/dist/lib/codex-hook-rpc.d.ts

@@ -1,4 +1,4 @@
-export declare const SUPPORTED_CODEX_HOOK_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.155.0", "codex-cli 0.155.1"];
+export declare const SUPPORTED_CODEX_HOOK_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.155.0", "codex-cli 0.155.1", "codex-cli 0.156.1"];
 export interface CodexHookRpc {
     version: string;
     processId?: number;

package/dist/sdk/index.js

@@ -32373,7 +32373,7 @@ var init_event_sink = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.16",
+  version: "0.9.17",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -37545,8 +37545,8 @@ 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-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-marketplace-registry-v2"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
-      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2")
+        requireBound(["bytes", "path-bytes", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-marketplace-registry-v2"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
+      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3")
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve3(source.path) === source.path && basename2(source.path) === "settings.json");
       if (source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2")
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve3(source.path) === source.path && basename2(source.path) === "known_marketplaces.json");
@@ -40154,7 +40154,7 @@ function assertClaudeHookEventsReplacement(before, replacement, events) {
   need3(JSON.stringify(withoutOwnedEvents(original)) === JSON.stringify(withoutOwnedEvents(next)), `${label} update changed settings outside hooks.${label}`);
 }
 var PERSISTED_EFFORT_LEVELS = new Set(["low", "medium", "high", "xhigh"]);
-function inferencePreference(key, child) {
+function inferencePreference(key, child, version) {
   if (key === "skipDangerousModePermissionPrompt") {
     need3(child.kind === "literal" && (child.value === "true" || child.value === "false"), "contains an invalid dialog acknowledgment");
     return false;
@@ -40167,7 +40167,7 @@ function inferencePreference(key, child) {
     return false;
   need3(child.kind === "object", "requires an object of model preferences");
   child.entries = child.entries.filter(([model, preferences]) => {
-    if (!BUILTIN_MODEL_SELECTIONS.has(model) || preferences.kind !== "object" || preferences.entries.length !== 1 || preferences.entries[0][0] !== "effortLevel")
+    if (version === 2 && !BUILTIN_MODEL_SELECTIONS.has(model) || preferences.kind !== "object" || preferences.entries.length !== 1 || preferences.entries[0][0] !== "effortLevel")
       return true;
     const effort = preferences.entries[0][1];
     need3(effort.kind === "string" && PERSISTED_EFFORT_LEVELS.has(effort.value), "contains an invalid persisted model effort level");
@@ -40178,7 +40178,7 @@ function inferencePreference(key, child) {
 function settingsDigest(text2, version = 1) {
   const value = parse6(text2);
   value.entries = value.entries.filter(([key, child]) => {
-    if (version === 2 && inferencePreference(key, child))
+    if (version !== 1 && inferencePreference(key, child, version))
       return false;
     if (key === "model") {
       need3(child.kind === "string", "contains an invalid model selection");
@@ -40216,6 +40216,25 @@ function hashClaudeSettingsReplacementV2(text2, budget) {
   budget.remaining -= bytes;
   return settingsDigest(text2, 2);
 }
+function captureClaudeSettingsV3(path, budget = { remaining: 256 * 1024 * 1024 }) {
+  return { path, hashMode: "claude-settings-v3", sha256: settingsDigest(readSettings(path, budget), 3) };
+}
+function hashClaudeSettingsReplacementV3(text2, budget) {
+  need3(typeof text2 === "string", "requires settings text");
+  const bytes = Buffer.byteLength(text2);
+  need3(bytes <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes && Number.isSafeInteger(budget.remaining) && budget.remaining >= bytes, "exceeds its byte limit");
+  budget.remaining -= bytes;
+  return settingsDigest(text2, 3);
+}
+function upgradeClaudeSettingsWitness(previous, reviewedSettingsPath) {
+  need3(previous && Object.keys(previous).every((key) => ["path", "hashMode", "sha256"].includes(key)) && (previous.hashMode === "claude-settings-v1" || previous.hashMode === "claude-settings-v2") && typeof previous.sha256 === "string" && /^[a-f0-9]{64}$/.test(previous.sha256), "requires an exact legacy settings witness");
+  const budget = { remaining: 2 * CLAUDE_SETTINGS_WITNESS_LIMITS.bytes };
+  const before = readSettings(reviewedSettingsPath, budget), current = readSettings(previous.path, budget);
+  need3(settingsDigest(before, previous.hashMode === "claude-settings-v1" ? 1 : 2) === previous.sha256, "reviewed preimage does not match the legacy witness");
+  const sha2562 = settingsDigest(current, 3);
+  need3(settingsDigest(before, 3) === sha2562, "non-preference settings changed; explicit discovery review required");
+  return { path: previous.path, hashMode: "claude-settings-v3", sha256: sha2562 };
+}
 
 // src/lib/codex-hook-discovery-recovery.ts
 import { createHash as createHash14 } from "crypto";
@@ -40325,13 +40344,13 @@ function read2(path, changes) {
   return readFileSync12(path, "utf8");
 }
 function projected(source, changes, budget = discoveryByteBudget()) {
-  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") {
+  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256))
       throw new Error("Claude settings witnesses require exact typed metadata");
-    const current = (source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget).sha256;
+    const current = (source.hashMode === "claude-settings-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget).sha256;
     if (current !== source.sha256)
       throw new Error(`Native discovery input changed; run skills hook install with a fresh discovery review: ${source.path}`);
-    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget) : current;
+    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget) : current;
   }
   if (source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2") {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256) || changes?.has(source.path))
@@ -40393,7 +40412,7 @@ function verifyAgentDiscovery(binding, codexRecovery) {
     safe4(root2);
 }
 function assertMarketplaceBinding(binding, source) {
-  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && (binding.agent !== "claude" || binding.method !== "reviewed" || basename6(source.path) !== "settings.json"))
+  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && (binding.agent !== "claude" || binding.method !== "reviewed" || basename6(source.path) !== "settings.json"))
     throw new Error("Claude settings witnesses require explicit reviewed Claude configuration");
   if ((source.hashMode === "claude-marketplace-registry" || source.hashMode === "claude-marketplace-registry-v2") && (binding.agent !== "claude" || binding.method !== "reviewed"))
     throw new Error("Claude marketplace witnesses require explicit reviewed Claude discovery");
@@ -40536,7 +40555,7 @@ function resolveAgentDiscovery(options) {
     verifyAgentDiscovery(retained);
     if (!retained.sources.some((source) => source.path === canonical4(configPath) && source.format === undefined && source.fields === undefined))
       unresolved("retained review is missing the full agent configuration source");
-    if (retained.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && source.path !== canonical4(configPath)))
+    if (retained.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && source.path !== canonical4(configPath)))
       unresolved("retained settings witness names another configuration source");
     if (sources.some((source) => !retained.sources.some((saved) => isDeepStrictEqual3(saved, source))) || [...roots].some((root2) => !retained.roots.includes(root2)) || agent === "gemini" && JSON.stringify(retained.builtinNames) !== JSON.stringify(builtinNames))
       unresolved("retained review is missing current runtime discovery coverage");
@@ -40552,7 +40571,7 @@ function resolveAgentDiscovery(options) {
     if (review.sources.some((source) => source.format !== undefined || source.fields !== undefined))
       throw new Error("Explicit discovery reviews require full source-file hashes");
     verifyAgentDiscovery(supplied);
-    if (review.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2") && source.path !== canonical4(configPath)))
+    if (review.sources.some((source) => (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && source.path !== canonical4(configPath)))
       throw new Error("Semantic settings witnesses must name the configured Claude configuration source");
     if (!review.sources.some((source) => source.path === canonical4(configPath)))
       throw new Error("Discovery review must include the agent configuration source");

package/docs/plugin-admission.md

@@ -289,6 +289,24 @@ Primary runtime references: [command sources](https://code.claude.com/docs/en/pl
 
 ### Explicit v2 preference reviews
 
+For new reviews, use `captureClaudeSettingsV3(path)` or
+`skills hook witness --kind claude-settings-v3 --path <settings.json> --json`.
+The v3 witness recognizes an entry containing only a valid `effortLevel`
+independently of its model name. Claude can persist a preference for a newly
+released model without blocking the next prompt. Entries with additional
+properties, including `maxEffortLevel`, remain fully bound, as do provider
+mappings, hooks, permissions, plugins, environment and unknown settings.
+The top-level model selection rules remain unchanged.
+
+Legacy v1 and v2 digests retain their meaning. `upgradeClaudeSettingsWitness`
+accepts a legacy witness and a saved `settings.json` preimage. It verifies that
+the preimage matches the old digest and that current settings differ only in
+recognized preferences before returning a v3 witness. It refuses all other
+drift. Use that witness in reviewed discovery inputs and apply the normal
+guarded integration plan. Install compatible runtimes before activating v3;
+when updating agents, verify their actual hook commands and native trust, not
+only the executable found on `PATH`.
+
 `captureClaudeSettingsV2(path)` creates a `claude-settings-v2` witness. In
 addition to the v1 display/model selections, it tolerates the documented
 persisted effort values `low`, `medium`, `high`, and `xhigh`, both at the top

package/package.json

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