@hasna/skills 0.9.15 → 0.9.17

package/README.md

@@ -373,6 +373,13 @@ system configuration, process-specific overrides, and alternate agent home
 directories are outside automatic coverage and require their own integration
 review before declaring a station migrated.
 
+When `hook install` omits `--discovery-inputs`, it reuses an existing reviewed
+binding only after rechecking its sources, directory membership, configuration
+coverage, managed bridge and native trust. Unchanged reviews need no new input
+file; drift still requires a fresh explicit review. Explicit discovery inputs
+take precedence, including when their `agents` array omits a previously reviewed
+agent. The default `--agent all` still includes every supported adapter.
+
 For reviewed Claude plugins, `skills integration plugin plan`, `admit` and
 `resolve` provide a command-source admission boundary before native discovery.
 Original packages and migrated skill/command prompts remain in private versioned

package/bin/index.js

@@ -36868,7 +36868,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.9.15",
+    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 });
@@ -51146,7 +51156,15 @@ function planAgentIntegration(options) {
     validateProfile(profileId2);
     return [agent, { command, profileId: profileId2 }];
   }));
-  const discoveries = [...new Set(options.agents)].map((agent) => resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, canonical: (path) => canonicalAgentPath(path, aliases) }));
+  const retainedAgents = [];
+  const discoveries = [...new Set(options.agents)].map((agent) => {
+    const retainedReview = options.discoveryInputs === undefined && policy.bridge?.discovery?.[agent]?.method === "reviewed" ? policy.bridge.discovery[agent] : undefined;
+    if (retainedReview) {
+      assertManagedAgentBridge(agent, { home, dataDir: dataDir3, projectDir: options.projectDir ?? home });
+      retainedAgents.push(agent);
+    }
+    return resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, retainedReview, canonical: (path) => canonicalAgentPath(path, aliases) });
+  });
   const nativeSkills = inventoryNativeSkills(home, { includeVendor: true, guardHermes: options.agents.includes("hermes"), agents: options.agents, projectDir: options.projectDir, agentRoots: discoveries.flatMap((binding) => binding.roots.map((path) => ({ agent: binding.agent, path }))), allowRootAliases: options.allowRootAliases });
   const changes = [];
   for (const agent of [...new Set(options.agents)]) {
@@ -51231,7 +51249,7 @@ function planAgentIntegration(options) {
   if (JSON.stringify(policy) !== JSON.stringify(nextPolicy))
     changes.push({ path: policyPath, before: previousPolicy, after: serializedPolicy });
   recheckRootAliases(aliases);
-  return { dataDir: dataDir3, profileId, changes, nativeSkills, observedPolicy: { path: policyPath, before: previousPolicy }, discoveryBefore: discoveries, discoveryAfter, ...aliases.length ? { rootAliases: aliases } : {} };
+  return { dataDir: dataDir3, profileId, changes, nativeSkills, observedPolicy: { path: policyPath, before: previousPolicy }, discoveryBefore: discoveries, discoveryAfter, ...aliases.length ? { rootAliases: aliases } : {}, ...retainedAgents.length ? { retainedReviewChecks: { home, projectDir: options.projectDir ?? home, agents: retainedAgents } } : {} };
 }
 function verifyCoordinatedDiscovery(binding, home, aliases) {
   try {
@@ -51269,6 +51287,8 @@ function applyAgentIntegration(plan) {
       parseManagedSkillPolicy(change.after);
   const aliases = plan.rootAliases ?? [];
   recheckRootAliases(aliases);
+  for (const agent of plan.retainedReviewChecks?.agents ?? [])
+    assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
   for (const agent of plan.managedAgentChecks?.agents ?? [])
     assertManagedAgentBridge(agent, { home: plan.managedAgentChecks.home, dataDir: plan.dataDir, projectDir: plan.managedAgentChecks.home });
   for (const binding of plan.discoveryBefore ?? []) {
@@ -54741,7 +54761,7 @@ function reviewNativeHookAdditions(options) {
     need4(Array.isArray(groups), "RECONCILE_ADDITIONS_DECLARATIONS");
     const key = `${options.nativeHooksPath}:${matchedEvents[event][1]}:${groups.length}:0`;
     need4(hook.key === key && !seen.has(key) && !options.recordedNativeHooks.some((originalHook) => originalHook.key === key) && !Object.hasOwn(expectedConfig.hooks.state, key), "RECONCILE_ADDITIONS_IDENTITY");
-    need4(hook.eventName === matchedEvents[event][0] && hook.handlerType === "command" && text2(hook.command, 16384) && !commands.has(hook.command) && Number.isInteger(hook.timeoutSec) && hook.timeoutSec > 0 && hook.timeoutSec <= 60 && (event === "PreToolUse" ? text2(hook.matcher) : hook.matcher === null) && hook.async === false && hook.statusMessage === null && hook.additionalContextLimit === null && hook.sourcePath === options.nativeHooksPath && hook.source === "user" && hook.pluginId === null && hook.isManaged === false && /^sha256:[a-f0-9]{64}$/.test(hook.currentHash) && hook.enabled === true && hook.trustStatus === "trusted", "RECONCILE_ADDITIONS_IDENTITY");
+    need4(hook.eventName === matchedEvents[event][0] && hook.handlerType === "command" && (review.version === 2 ? v2Command(hook.command) : text2(hook.command, 16384)) && !commands.has(hook.command) && Number.isInteger(hook.timeoutSec) && hook.timeoutSec > 0 && hook.timeoutSec <= 60 && (event === "PreToolUse" ? text2(hook.matcher) : hook.matcher === null) && hook.async === false && hook.statusMessage === null && hook.additionalContextLimit === null && hook.sourcePath === options.nativeHooksPath && hook.source === "user" && hook.pluginId === null && hook.isManaged === false && /^sha256:[a-f0-9]{64}$/.test(hook.currentHash) && hook.enabled === true && hook.trustStatus === "trusted", "RECONCILE_ADDITIONS_IDENTITY");
     let trustState = { enabled: true, trusted_hash: hook.currentHash };
     if (review.version === 2) {
       const state = addition.trustState;
@@ -54769,7 +54789,7 @@ function reviewNativeHookAdditions(options) {
   proofs.set(trustProof, { before: options.configBefore, current: options.configCurrent, journalHooks: options.journalHooks.map(({ key, currentHash }) => ({ key, currentHash })), states: Object.freeze(states), recheck });
   return { hooks: added, recheck, trustProof, receipt: { ...review.version === 2 ? { version: 2 } : {}, reviewPath: reviewFile.file, reviewSha256: reviewFile.sha256, reason: review.reason, producerEvidence: review.producerEvidence, producerBefore: { configPath: producerConfig.file, configSha256: producerConfig.sha256, hooksPath: producerHooks.file, hooksSha256: producerHooks.sha256 }, additions: review.version === 1 ? added : review.additions } };
 }
-var events, matchedEvents, hash2 = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value), text2 = (value, max2 = 2048) => typeof value === "string" && value.trim().length > 0 && value.length <= max2 && !/[\0\r\n]/.test(value), structure = (value) => JSON.parse(JSON.stringify(Bun.TOML.parse(value))), nativeKeys, proofs;
+var events, matchedEvents, hash2 = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value), text2 = (value, max2 = 2048) => typeof value === "string" && value.trim().length > 0 && value.length <= max2 && !/[\0\r\n]/.test(value), v2Command = (value) => typeof value === "string" && value.trim().length > 0 && value.length <= 16384 && !/[\0\r]/.test(value), structure = (value) => JSON.parse(JSON.stringify(Bun.TOML.parse(value))), nativeKeys, proofs;
 var init_codex_hook_additions_review = __esm(() => {
   init_codex_hook_trust_files();
   init_codex_hook_trust_layout();
@@ -54843,6 +54863,7 @@ var init_codex_hook_discovery_recovery = __esm(() => {
 import { createHash as createHash16 } from "crypto";
 import { lstatSync as lstatSync20, readFileSync as readFileSync17, readdirSync as readdirSync10, realpathSync as realpathSync4 } from "fs";
 import { basename as basename8, dirname as dirname16, isAbsolute as isAbsolute15, join as join31, resolve as resolve15, sep as sep5 } from "path";
+import { isDeepStrictEqual as isDeepStrictEqual7 } from "util";
 function parseConfig(text3, path, toml = false) {
   try {
     const value = toml ? Bun.TOML.parse(text3) : JSON.parse(text3);
@@ -54875,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))
@@ -54943,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");
@@ -54952,7 +54973,10 @@ function rebindAgentDiscovery(binding, changes) {
   const budget = discoveryByteBudget();
   return { ...binding, sources: binding.sources.map((source) => {
     assertMarketplaceBinding(binding, source);
-    return { ...source, sha256: projected(source, changes, budget) };
+    const sha2562 = projected(source, changes, budget);
+    if (!changes.has(source.path) && sha2562 !== source.sha256)
+      throw new Error(`Native discovery input changed; run skills hook install with a fresh discovery review: ${source.path}`);
+    return { ...source, sha256: sha2562 };
   }) };
 }
 function assertProjectDiscovery(agent, directories, home, canonical4 = resolve15, reviewed) {
@@ -55064,6 +55088,19 @@ function resolveAgentDiscovery(options) {
       }
     }
   }
+  if (options.reviewed === undefined && options.retainedReview !== undefined) {
+    const retained = options.retainedReview;
+    if (retained.agent !== agent || retained.method !== "reviewed")
+      unresolved("invalid retained review");
+    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.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");
+    return retained;
+  }
   if (options.reviewed && (options.reviewed.version !== 1 || !Array.isArray(options.reviewed.agents) || options.reviewed.agents.some((item) => !item || typeof item !== "object") || new Set(options.reviewed.agents.map((item) => item.agent)).size !== options.reviewed.agents.length))
     throw new Error("Invalid --discovery-inputs version or agents");
   const review = options.reviewed?.agents.find((item) => item.agent === agent);
@@ -55074,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");
@@ -80129,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
@@ -84538,7 +84576,7 @@ var init_execution_grants = __esm(() => {
 });
 
 // src/lib/execution-grant-client.ts
-import { isDeepStrictEqual as isDeepStrictEqual7 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual8 } from "util";
 function id(value) {
   if (!grantIdentifier(value))
     throw new Error("Invalid execution grant profile or revision identifier.");
@@ -84590,7 +84628,7 @@ async function saveExecutionGrantPolicy(profileId, grants, revision) {
     headers: revision === undefined ? { "If-None-Match": "*" } : { "If-Match": `"${revision}"` },
     body: JSON.stringify({ grants: snapshot2 })
   }));
-  if (policy.profileId !== profileId || policy.previousRevision !== (revision ?? null) || !isDeepStrictEqual7(policy.grants, snapshot2)) {
+  if (policy.profileId !== profileId || policy.previousRevision !== (revision ?? null) || !isDeepStrictEqual8(policy.grants, snapshot2)) {
     throw new Error("The API did not preserve the reviewed execution grant policy; read it before retrying.");
   }
   return policy;
@@ -84601,7 +84639,7 @@ async function resolveExecutionGrant(input2) {
   if (!grantRecord(value) || Object.keys(value).length !== 3 || !grantIdentifier(value.policyRevision) || !grantIdentifier(value.grantId) || !grantRecord(value.bindings)) {
     throw new SkillSelectionError("INVALID_EXECUTION_GRANT", "The Skills API returned an invalid execution grant.");
   }
-  if (!isDeepStrictEqual7(value.bindings.selection, snapshot2.selection) || !isDeepStrictEqual7(value.bindings.consumer, snapshot2.consumer)) {
+  if (!isDeepStrictEqual8(value.bindings.selection, snapshot2.selection) || !isDeepStrictEqual8(value.bindings.consumer, snapshot2.consumer)) {
     throw new SkillSelectionError("EXECUTION_GRANT_SCOPE_MISMATCH", "The Skills API returned a grant for a different selection or consumer.");
   }
   return value;
@@ -108589,13 +108627,13 @@ 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
 import { realpathSync as realpathSync13 } from "fs";
 import { dirname as dirname30, isAbsolute as isAbsolute25, join as join56 } from "path";
-import { isDeepStrictEqual as isDeepStrictEqual8 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual9 } from "util";
 function inspectRecordedSkillsCli(command, expected) {
   need4(isAbsolute25(command) && !command.includes("\x00"), "RECONCILE_RECORDED_COMMAND_REQUIRED");
   const resolved = realpathSync13(command);
@@ -108605,7 +108643,7 @@ function inspectRecordedSkillsCli(command, expected) {
   need4(pkg.name === "@hasna/skills" && /^\d+\.\d+\.\d+$/.test(pkg.version) && pkg.bin?.skills === "bin/index.js" && resolved === join56(dirname30(manifest.file), "bin/index.js"), "SKILLS_PACKAGE_MISMATCH");
   need4((cli.stat.mode & 0o100n) !== 0n, "SKILLS_COMMAND_NOT_EXECUTABLE");
   const receipt = { path: resolved, version: pkg.version, sha256: cli.sha256, manifestSha256: manifest.sha256 };
-  need4(isDeepStrictEqual8(receipt, expected), "RECONCILE_SKILLS_BINDING_CHANGED");
+  need4(isDeepStrictEqual9(receipt, expected), "RECONCILE_SKILLS_BINDING_CHANGED");
   return { receipt, recheck() {
     need4(realpathSync13(command) === resolved, "SKILLS_COMMAND_CHANGED");
     unchanged2(cli);
@@ -108641,19 +108679,19 @@ var init_codex_hook_trust_identity = __esm(() => {
 });
 
 // src/lib/codex-hook-policy-recovery.ts
-import { isDeepStrictEqual as isDeepStrictEqual9 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual10 } from "util";
 function reviewedClaudeDiscoveryChange(beforeText, currentText, options) {
   need4(typeof options.reason === "string" && options.reason.trim().length > 0 && options.reason.length <= 512 && !/[\x00-\x1f\x7f]/.test(options.reason), "RECONCILE_RECOVERY_REASON_REQUIRED");
   need4(options.reviewedPlanDigest === undefined || /^[a-f0-9]{64}$/.test(options.reviewedPlanDigest), "RECONCILE_RECOVERY_PLAN_CHANGED");
   const before2 = parseManagedSkillPolicy(beforeText), current = parseManagedSkillPolicy(currentText);
   const oldDiscovery = before2.bridge?.discovery?.claude, newDiscovery = current.bridge?.discovery?.claude;
   need4(oldDiscovery?.agent === "claude" && newDiscovery?.agent === "claude" && oldDiscovery.method === "reviewed" && newDiscovery.method === "reviewed", "RECONCILE_POLICY_CHANGED");
-  const changes = ["roots", "sources"].filter((key) => !isDeepStrictEqual9(oldDiscovery[key], newDiscovery[key])).map((key) => ({ path: `bridge.discovery.claude.${key}`, before: oldDiscovery[key], after: newDiscovery[key] }));
+  const changes = ["roots", "sources"].filter((key) => !isDeepStrictEqual10(oldDiscovery[key], newDiscovery[key])).map((key) => ({ path: `bridge.discovery.claude.${key}`, before: oldDiscovery[key], after: newDiscovery[key] }));
   need4(changes.length > 0, "RECONCILE_POLICY_CHANGED");
   const compared = structuredClone(current);
   compared.bridge.discovery.claude.roots = oldDiscovery.roots;
   compared.bridge.discovery.claude.sources = oldDiscovery.sources;
-  need4(isDeepStrictEqual9(before2, compared), "RECONCILE_POLICY_CHANGED");
+  need4(isDeepStrictEqual10(before2, compared), "RECONCILE_POLICY_CHANGED");
   verifyAgentDiscovery(newDiscovery);
   return { reason: options.reason, changes };
 }
@@ -108669,7 +108707,7 @@ import { createHash as createHash27, randomUUID as randomUUID10 } from "crypto";
 import { execFileSync } from "child_process";
 import { dirname as dirname31, isAbsolute as isAbsolute26, join as join57, resolve as resolve23 } from "path";
 import { homedir as homedir12 } from "os";
-import { isDeepStrictEqual as isDeepStrictEqual10 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual11 } from "util";
 function verifyReleaseArtifact(proof, skillsCli) {
   need4(isAbsolute26(proof.packageTarPath) && !proof.packageTarPath.includes("\x00"), "RECONCILE_RELEASE_PROVENANCE_PATH");
   const tarPath = realpathSync14(proof.packageTarPath);
@@ -108711,7 +108749,7 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
     const configSha256 = intent.configSha256 ?? configBefore.sha256, configVersion = intent.configVersion ?? intent.expectedVersion;
     const digestInput = { version: 1, home: intent.home ?? home, configPath: intent.configPath, ...intent.nativeConfigPath !== undefined ? { nativeConfigPath: intent.nativeConfigPath } : {}, configSha256, configVersion, policySha256: intent.policySha256, hooksSha256: intent.hooksSha256, skillsCli: intent.skillsCli, nativeVersion: intent.nativeVersion, declarations, admitted };
     need4(makePlanDigest(digestInput) === intent.planDigest, "RECONCILE_PLAN_CHANGED");
-    need4(isDeepStrictEqual10(intent.hooks, admitted.filter((hook) => !hook.enabled || hook.trustStatus !== "trusted")), "RECONCILE_INTENT_HOOKS_CHANGED");
+    need4(isDeepStrictEqual11(intent.hooks, admitted.filter((hook) => !hook.enabled || hook.trustStatus !== "trusted")), "RECONCILE_INTENT_HOOKS_CHANGED");
     need4(configBefore.sha256 === (intent.beforeSha256 ?? intent.configSha256) && hooksBefore.sha256 === intent.hooksSha256 && policyBefore.sha256 === intent.policySha256, "RECONCILE_JOURNAL_CHANGED");
     const policyCurrent = snapshot(join57(dataDir3, "agent-policy.json"), true);
     const { claudeDiscoveryRecovery: claudeRecovery, nativeHookAdditionsRecovery: additionsRecovery } = options;
@@ -108724,7 +108762,7 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
     if (policyCurrent.sha256 !== policyBefore.sha256 && !claudeRecovery) {
       need4(options.supersedeBinding === true, "RECONCILE_POLICY_CHANGED");
       const oldPolicy = JSON.parse(policyBefore.text), currentPolicy = JSON.parse(policyCurrent.text);
-      need4(isDeepStrictEqual10(withoutCodexCommand(oldPolicy), withoutCodexCommand(currentPolicy)), "RECONCILE_POLICY_CHANGED");
+      need4(isDeepStrictEqual11(withoutCodexCommand(oldPolicy), withoutCodexCommand(currentPolicy)), "RECONCILE_POLICY_CHANGED");
       supersededBinding = true;
     }
     if (supersededBinding || recovery) {
@@ -108760,7 +108798,7 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
         need4(state?.enabled === true && typeof state.trusted_hash === "string" && /^sha256:[a-f0-9]{64}$/.test(state.trusted_hash), "RECONCILE_CONFIG_DRIFT");
       }
     } else
-      need4(isDeepStrictEqual10(expectedConfig, current), "RECONCILE_CONFIG_DRIFT");
+      need4(isDeepStrictEqual11(expectedConfig, current), "RECONCILE_CONFIG_DRIFT");
     const configDiscoveryRecovery = recovery && binding.discovery?.codex ? createCodexHookDiscoveryRecovery(binding.discovery.codex, configBefore, currentConfig, intent.hooks, additions?.trustProof) : undefined;
     assertManagedAgentBridge("codex", { home, dataDir: dataDir3, projectDir: home, codexDiscoveryRecovery: configDiscoveryRecovery });
     const recoveryCli = recovery ? bindSkillsCli("skills", options.reviewedSkillsCli) : undefined;
@@ -108769,14 +108807,14 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
     const skillsCli = recovery ? inspectRecordedSkillsCli(binding.commands.codex, intent.skillsCli) : bindSkillsCli(binding.commands.codex, options.reviewedSkillsCli);
     if (supersededBinding)
       verifyReleaseArtifact(options.releaseProof, skillsCli);
-    const skillsBindingChanged = !isDeepStrictEqual10(skillsCli.receipt, intent.skillsCli);
+    const skillsBindingChanged = !isDeepStrictEqual11(skillsCli.receipt, intent.skillsCli);
     need4(!skillsBindingChanged || supersededBinding, "RECONCILE_SKILLS_BINDING_CHANGED");
     if (!additions && hooksCurrent.sha256 !== intent.hooksSha256 && hooksCurrent.sha256 !== hooksBefore.sha256) {
       need4(supersededBinding, "RECONCILE_HOOKS_CHANGED");
       const currentDeclarations = JSON.parse(hooksCurrent.text).hooks;
       for (const [event, [nativeEvent]] of Object.entries(eventNames)) {
         const command = renderAgentHookCommand(binding.commands.codex, "codex", binding.profiles.codex, event);
-        need4(isDeepStrictEqual10(currentDeclarations?.[event], [{ hooks: [{ type: "command", command, timeout: 15 }] }]), "RECONCILE_BINDING_HOOK_CHANGED");
+        need4(isDeepStrictEqual11(currentDeclarations?.[event], [{ hooks: [{ type: "command", command, timeout: 15 }] }]), "RECONCILE_BINDING_HOOK_CHANGED");
       }
     }
     rpc = await connect({ command: options.codexCommand ?? "codex", home, codexHome });
@@ -108799,9 +108837,9 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
           delete identity4.command;
         return identity4;
       };
-      need4(isDeepStrictEqual10(stable(actual), stable(expected)), "RECONCILE_NATIVE_IDENTITY_CHANGED");
+      need4(isDeepStrictEqual11(stable(actual), stable(expected)), "RECONCILE_NATIVE_IDENTITY_CHANGED");
       if (!plannedKeys.has(expected.key))
-        need4(isDeepStrictEqual10(actual, expected), "RECONCILE_UNRELATED_HOOK_CHANGED");
+        need4(isDeepStrictEqual11(actual, expected), "RECONCILE_UNRELATED_HOOK_CHANGED");
     }
     for (const wanted of intent.hooks) {
       const matches2 = nativeHooks.filter((h2) => h2.key === wanted.key || h2.key === wanted.key.replace(join57(home, ".codex/hooks.json"), hooksPath));
@@ -108818,12 +108856,12 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
     }
     const config2 = await rpc.request("config/read", { includeLayers: true, cwd: home });
     const layers = config2?.layers?.filter((layer) => layer.name?.type === "user" && layer.name.file === nativeConfigPath && !layer.name.profile);
-    need4(layers?.length === 1 && !layers[0].disabledReason && isDeepStrictEqual10(layers[0].config, current), "RECONCILE_NATIVE_CONFIG_MISMATCH");
+    need4(layers?.length === 1 && !layers[0].disabledReason && isDeepStrictEqual11(layers[0].config, current), "RECONCILE_NATIVE_CONFIG_MISMATCH");
     const finalDiscovery = await rpc.request("hooks/list", { cwds: [home] });
-    need4(Array.isArray(finalDiscovery?.data) && finalDiscovery.data.length === 1 && finalDiscovery.data[0].cwd === home && !finalDiscovery.data[0].errors?.length && !finalDiscovery.data[0].warnings?.length && (!recordedNativeHooks || isDeepStrictEqual10(finalDiscovery.data[0].hooks.map(safeNativeHook), nativeHooks.map(safeNativeHook))), "RECONCILE_NATIVE_STATE_CHANGED");
+    need4(Array.isArray(finalDiscovery?.data) && finalDiscovery.data.length === 1 && finalDiscovery.data[0].cwd === home && !finalDiscovery.data[0].errors?.length && !finalDiscovery.data[0].warnings?.length && (!recordedNativeHooks || isDeepStrictEqual11(finalDiscovery.data[0].hooks.map(safeNativeHook), nativeHooks.map(safeNativeHook))), "RECONCILE_NATIVE_STATE_CHANGED");
     const finalConfig = await rpc.request("config/read", { includeLayers: true, cwd: home });
     const finalLayers = finalConfig?.layers?.filter((layer) => layer.name?.type === "user" && layer.name.file === nativeConfigPath && !layer.name.profile);
-    need4(finalLayers?.length === 1 && !finalLayers[0].disabledReason && isDeepStrictEqual10(finalLayers[0].config, current), "RECONCILE_NATIVE_CONFIG_CHANGED");
+    need4(finalLayers?.length === 1 && !finalLayers[0].disabledReason && isDeepStrictEqual11(finalLayers[0].config, current), "RECONCILE_NATIVE_CONFIG_CHANGED");
     if (recovery) {
       for (const response of [config2, finalConfig]) {
         const layerIndex = response.layers.findIndex((layer) => layer.name?.type === "user" && layer.name.file === nativeConfigPath && !layer.name.profile);
@@ -108881,7 +108919,7 @@ async function enrollCodexNativeHooks(options = {}, connect = connectCodexHookRp
       const groups = declarations[event];
       need4(Array.isArray(groups), "DECLARATION_CHANGED");
       const matches2 = groups.flatMap((group, gi) => (group.hooks ?? []).flatMap((entry, hi) => entry.command === command ? [{ group, entry, gi, hi }] : []));
-      need4(matches2.length === 1 && isDeepStrictEqual10(matches2[0].group, { hooks: [{ type: "command", command, timeout: 15 }] }), "DECLARATION_CHANGED");
+      need4(matches2.length === 1 && isDeepStrictEqual11(matches2[0].group, { hooks: [{ type: "command", command, timeout: 15 }] }), "DECLARATION_CHANGED");
       expected.push({ event: nativeEvent, key: `${join57(home, ".codex/hooks.json")}:${label}:${matches2[0].gi}:${matches2[0].hi}`, command });
     }
     codexTrustTextWitness(configFile.text, expected.map((h) => h.key));
@@ -108905,7 +108943,7 @@ async function enrollCodexNativeHooks(options = {}, connect = connectCodexHookRp
     const discovered = await list2(), admitted = admit(discovered);
     const config2 = await rpc.request("config/read", { includeLayers: true, cwd: home });
     const layers = config2?.layers?.filter((layer) => layer.name?.type === "user" && layer.name.file === nativeConfigPath && !layer.name.profile);
-    need4(layers?.length === 1 && /^sha256:[a-f0-9]{64}$/.test(layers[0].version) && !layers[0].disabledReason && isDeepStrictEqual10(layers[0].config, original), "NATIVE_CONFIG_MISMATCH");
+    need4(layers?.length === 1 && /^sha256:[a-f0-9]{64}$/.test(layers[0].version) && !layers[0].disabledReason && isDeepStrictEqual11(layers[0].config, original), "NATIVE_CONFIG_MISMATCH");
     need4(config2.config && config2.config.features?.hooks !== false, "NATIVE_HOOKS_DISABLED");
     need4(config2.layers.slice(0, config2.layers.indexOf(layers[0])).every((layer) => layer.config?.hooks === undefined && layer.config?.features?.hooks === undefined), "NATIVE_CONFIG_OVERRIDDEN");
     const keys3 = admitted.map((h) => h.key), planned = admitted.filter((h) => !h.enabled || h.trustStatus !== "trusted");
@@ -108944,7 +108982,7 @@ async function enrollCodexNativeHooks(options = {}, connect = connectCodexHookRp
     save(join57(journal, "hooks.before.json"), hooksFile.bytes);
     save(join57(journal, "policy.before.json"), policyFile.bytes);
     save(join57(journal, "intent.json"), json2({ ...digestInput, planDigest, hooks: planned, nativeHooks: discovered.map(safeNativeHook) }));
-    need4(isDeepStrictEqual10(admit(await list2()), admitted), "NATIVE_DISCOVERY_CHANGED");
+    need4(isDeepStrictEqual11(admit(await list2()), admitted), "NATIVE_DISCOVERY_CHANGED");
     checkInputs();
     let result2;
     try {
@@ -108958,7 +108996,7 @@ async function enrollCodexNativeHooks(options = {}, connect = connectCodexHookRp
     expectedConfig.hooks.state ??= {};
     for (const h of planned)
       expectedConfig.hooks.state[h.key] = { ...expectedConfig.hooks.state[h.key], enabled: true, trusted_hash: h.currentHash };
-    need4(isDeepStrictEqual10(structure3(after2.text), expectedConfig) && codexTrustTextWitness(after2.text, keys3) === preservationText, "PRESERVATION_FAILED");
+    need4(isDeepStrictEqual11(structure3(after2.text), expectedConfig) && codexTrustTextWitness(after2.text, keys3) === preservationText, "PRESERVATION_FAILED");
     const savedConfig = snapshot(join57(journal, "config.before.toml"), true);
     need4(savedConfig.sha256 === configFile.sha256, "JOURNAL_CHANGED");
     const discoveryTransition = binding.discovery?.codex ? createCodexHookDiscoveryRecovery(binding.discovery.codex, savedConfig, after2, planned) : undefined;
@@ -108966,8 +109004,8 @@ async function enrollCodexNativeHooks(options = {}, connect = connectCodexHookRp
     unchanged2(hooksFile);
     assertManagedAgentBridge("codex", { home, dataDir: dataDir3, projectDir: home, codexDiscoveryRecovery: discoveryTransition });
     const current = await list2(), confirmed = admit(current);
-    need4(confirmed.every((h) => h.enabled && h.trustStatus === "trusted") && isDeepStrictEqual10(confirmed.map((h) => [h.key, h.currentHash]), admitted.map((h) => [h.key, h.currentHash])), "NATIVE_NOT_ELIGIBLE");
-    need4(isDeepStrictEqual10(current.filter((h) => !keys3.includes(h.key)), discovered.filter((h) => !keys3.includes(h.key))), "UNRELATED_HOOK_CHANGED");
+    need4(confirmed.every((h) => h.enabled && h.trustStatus === "trusted") && isDeepStrictEqual11(confirmed.map((h) => [h.key, h.currentHash]), admitted.map((h) => [h.key, h.currentHash])), "NATIVE_NOT_ELIGIBLE");
+    need4(isDeepStrictEqual11(current.filter((h) => !keys3.includes(h.key)), discovered.filter((h) => !keys3.includes(h.key))), "UNRELATED_HOOK_CHANGED");
     unchanged2(after2);
     unchanged2(savedConfig);
     unchanged2(hooksFile);
@@ -109027,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.`;
   }
@@ -109043,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",
@@ -109158,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.15",
+    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 });
@@ -48834,6 +48844,7 @@ var init_codex_hook_discovery_recovery = __esm(() => {
 import { createHash as createHash14 } from "crypto";
 import { lstatSync as lstatSync16, readFileSync as readFileSync14, readdirSync as readdirSync6, realpathSync as realpathSync3 } from "fs";
 import { basename as basename7, dirname as dirname14, isAbsolute as isAbsolute13, join as join23, resolve as resolve13, sep as sep4 } from "path";
+import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
 function parseConfig(text2, path, toml = false) {
   try {
     const value = toml ? Bun.TOML.parse(text2) : JSON.parse(text2);
@@ -48866,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))
@@ -48934,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");
@@ -49008,6 +49019,19 @@ function resolveAgentDiscovery(options) {
       }
     }
   }
+  if (options.reviewed === undefined && options.retainedReview !== undefined) {
+    const retained = options.retainedReview;
+    if (retained.agent !== agent || retained.method !== "reviewed")
+      unresolved("invalid retained review");
+    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.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");
+    return retained;
+  }
   if (options.reviewed && (options.reviewed.version !== 1 || !Array.isArray(options.reviewed.agents) || options.reviewed.agents.some((item) => !item || typeof item !== "object") || new Set(options.reviewed.agents.map((item) => item.agent)).size !== options.reviewed.agents.length))
     throw new Error("Invalid --discovery-inputs version or agents");
   const review = options.reviewed?.agents.find((item) => item.agent === agent);
@@ -49018,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");
@@ -57344,7 +57368,7 @@ var init_execution_grants = __esm(() => {
 });
 
 // src/lib/execution-grant-client.ts
-import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual3 } from "util";
 function id(value) {
   if (!grantIdentifier(value))
     throw new Error("Invalid execution grant profile or revision identifier.");
@@ -57387,7 +57411,7 @@ async function resolveExecutionGrant(input2) {
   if (!grantRecord(value) || Object.keys(value).length !== 3 || !grantIdentifier(value.policyRevision) || !grantIdentifier(value.grantId) || !grantRecord(value.bindings)) {
     throw new SkillSelectionError("INVALID_EXECUTION_GRANT", "The Skills API returned an invalid execution grant.");
   }
-  if (!isDeepStrictEqual2(value.bindings.selection, snapshot2.selection) || !isDeepStrictEqual2(value.bindings.consumer, snapshot2.consumer)) {
+  if (!isDeepStrictEqual3(value.bindings.selection, snapshot2.selection) || !isDeepStrictEqual3(value.bindings.consumer, snapshot2.consumer)) {
     throw new SkillSelectionError("EXECUTION_GRANT_SCOPE_MISMATCH", "The Skills API returned a grant for a different selection or consumer.");
   }
   return value;

package/bin/migrate.js

@@ -7,7 +7,7 @@ import { join as join5 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.15",
+  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.15",
+  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.15",
+  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");
@@ -9093,6 +9093,7 @@ function assertAgentPolicyCollections(policy) {
 import { createHash as createHash16 } from "crypto";
 import { lstatSync as lstatSync20, readFileSync as readFileSync16, readdirSync as readdirSync9, realpathSync as realpathSync4 } from "fs";
 import { basename as basename8, dirname as dirname16, isAbsolute as isAbsolute14, join as join26, resolve as resolve14, sep as sep5 } from "path";
+import { isDeepStrictEqual as isDeepStrictEqual3 } from "util";
 
 // node_modules/yaml/dist/index.js
 var composer = require_composer();
@@ -9610,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.15",
+  version: "0.9.17",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -12873,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;
@@ -12886,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");
@@ -12897,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");
@@ -12935,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");
@@ -13369,7 +13389,15 @@ function planAgentIntegration(options) {
     validateProfile(profileId2);
     return [agent, { command, profileId: profileId2 }];
   }));
-  const discoveries = [...new Set(options.agents)].map((agent) => resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, canonical: (path) => canonicalAgentPath(path, aliases) }));
+  const retainedAgents = [];
+  const discoveries = [...new Set(options.agents)].map((agent) => {
+    const retainedReview = options.discoveryInputs === undefined && policy.bridge?.discovery?.[agent]?.method === "reviewed" ? policy.bridge.discovery[agent] : undefined;
+    if (retainedReview) {
+      assertManagedAgentBridge(agent, { home, dataDir: dataDir2, projectDir: options.projectDir ?? home });
+      retainedAgents.push(agent);
+    }
+    return resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, retainedReview, canonical: (path) => canonicalAgentPath(path, aliases) });
+  });
   const nativeSkills = inventoryNativeSkills(home, { includeVendor: true, guardHermes: options.agents.includes("hermes"), agents: options.agents, projectDir: options.projectDir, agentRoots: discoveries.flatMap((binding) => binding.roots.map((path) => ({ agent: binding.agent, path }))), allowRootAliases: options.allowRootAliases });
   const changes = [];
   for (const agent of [...new Set(options.agents)]) {
@@ -13454,7 +13482,7 @@ function planAgentIntegration(options) {
   if (JSON.stringify(policy) !== JSON.stringify(nextPolicy))
     changes.push({ path: policyPath, before: previousPolicy, after: serializedPolicy });
   recheckRootAliases(aliases);
-  return { dataDir: dataDir2, profileId, changes, nativeSkills, observedPolicy: { path: policyPath, before: previousPolicy }, discoveryBefore: discoveries, discoveryAfter, ...aliases.length ? { rootAliases: aliases } : {} };
+  return { dataDir: dataDir2, profileId, changes, nativeSkills, observedPolicy: { path: policyPath, before: previousPolicy }, discoveryBefore: discoveries, discoveryAfter, ...aliases.length ? { rootAliases: aliases } : {}, ...retainedAgents.length ? { retainedReviewChecks: { home, projectDir: options.projectDir ?? home, agents: retainedAgents } } : {} };
 }
 function planClaudeStopHookUpdate(options) {
   return planClaudeHookEventsUpdate({ ...options, events: ["Stop"] });
@@ -13573,6 +13601,8 @@ function applyAgentIntegration(plan) {
       parseManagedSkillPolicy(change.after);
   const aliases = plan.rootAliases ?? [];
   recheckRootAliases(aliases);
+  for (const agent of plan.retainedReviewChecks?.agents ?? [])
+    assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
   for (const agent of plan.managedAgentChecks?.agents ?? [])
     assertManagedAgentBridge(agent, { home: plan.managedAgentChecks.home, dataDir: plan.dataDir, projectDir: plan.managedAgentChecks.home });
   for (const binding of plan.discoveryBefore ?? []) {
@@ -16496,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))
@@ -16564,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");
@@ -16573,7 +16603,10 @@ function rebindAgentDiscovery(binding, changes) {
   const budget = discoveryByteBudget();
   return { ...binding, sources: binding.sources.map((source) => {
     assertMarketplaceBinding(binding, source);
-    return { ...source, sha256: projected(source, changes, budget) };
+    const sha2562 = projected(source, changes, budget);
+    if (!changes.has(source.path) && sha2562 !== source.sha256)
+      throw new Error(`Native discovery input changed; run skills hook install with a fresh discovery review: ${source.path}`);
+    return { ...source, sha256: sha2562 };
   }) };
 }
 function captureDiscoveryByteSources(paths) {
@@ -16697,6 +16730,19 @@ function resolveAgentDiscovery(options) {
       }
     }
   }
+  if (options.reviewed === undefined && options.retainedReview !== undefined) {
+    const retained = options.retainedReview;
+    if (retained.agent !== agent || retained.method !== "reviewed")
+      unresolved("invalid retained review");
+    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.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");
+    return retained;
+  }
   if (options.reviewed && (options.reviewed.version !== 1 || !Array.isArray(options.reviewed.agents) || options.reviewed.agents.some((item) => !item || typeof item !== "object") || new Set(options.reviewed.agents.map((item) => item.agent)).size !== options.reviewed.agents.length))
     throw new Error("Invalid --discovery-inputs version or agents");
   const review = options.reviewed?.agents.find((item) => item.agent === agent);
@@ -16707,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");
@@ -43655,6 +43701,7 @@ export {
   validateCron,
   validateBlogArticleRunOptions,
   uploadSkillsSnapshotFilesToS3,
+  upgradeClaudeSettingsWitness,
   updateSkillRun,
   unsetConfig,
   unpinSkill,
@@ -43833,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[];
@@ -46,5 +46,6 @@ export declare function resolveAgentDiscovery(options: {
     home: string;
     agent: IntegrationAgent;
     reviewed?: ReviewedDiscoveryInputs;
+    retainedReview?: AgentDiscoveryBinding;
     canonical?: (path: string) => string;
 }): AgentDiscoveryBinding;

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

@@ -56,6 +56,11 @@ export interface AgentIntegrationPlan {
         home: string;
         agents: IntegrationAgent[];
     };
+    retainedReviewChecks?: {
+        home: string;
+        projectDir: string;
+        agents: IntegrationAgent[];
+    };
 }
 /** Parse the reviewed exact-target binding used by native migration. Paths are
  * deliberately project-relative so a manifest cannot silently select another

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.15",
+  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");
@@ -37704,6 +37704,7 @@ function isOwnedCliBridge(path, expectedPaths) {
 import { createHash as createHash15 } from "crypto";
 import { lstatSync as lstatSync17, readFileSync as readFileSync12, readdirSync as readdirSync6, realpathSync as realpathSync3 } from "fs";
 import { basename as basename6, dirname as dirname13, isAbsolute as isAbsolute14, join as join20, resolve as resolve13, sep as sep3 } from "path";
+import { isDeepStrictEqual as isDeepStrictEqual3 } from "util";
 
 // node_modules/yaml/dist/index.js
 var composer = require_composer();
@@ -40153,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;
@@ -40166,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");
@@ -40177,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");
@@ -40215,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";
@@ -40324,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))
@@ -40392,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");
@@ -40401,7 +40421,10 @@ function rebindAgentDiscovery(binding, changes) {
   const budget = discoveryByteBudget();
   return { ...binding, sources: binding.sources.map((source) => {
     assertMarketplaceBinding(binding, source);
-    return { ...source, sha256: projected(source, changes, budget) };
+    const sha2562 = projected(source, changes, budget);
+    if (!changes.has(source.path) && sha2562 !== source.sha256)
+      throw new Error(`Native discovery input changed; run skills hook install with a fresh discovery review: ${source.path}`);
+    return { ...source, sha256: sha2562 };
   }) };
 }
 function captureDiscoveryByteSources(paths) {
@@ -40525,6 +40548,19 @@ function resolveAgentDiscovery(options) {
       }
     }
   }
+  if (options.reviewed === undefined && options.retainedReview !== undefined) {
+    const retained = options.retainedReview;
+    if (retained.agent !== agent || retained.method !== "reviewed")
+      unresolved("invalid retained review");
+    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.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");
+    return retained;
+  }
   if (options.reviewed && (options.reviewed.version !== 1 || !Array.isArray(options.reviewed.agents) || options.reviewed.agents.some((item) => !item || typeof item !== "object") || new Set(options.reviewed.agents.map((item) => item.agent)).size !== options.reviewed.agents.length))
     throw new Error("Invalid --discovery-inputs version or agents");
   const review = options.reviewed?.agents.find((item) => item.agent === agent);
@@ -40535,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");
@@ -40718,7 +40754,7 @@ export default async ({ directory }) => {
 }
 
 // src/lib/agent-codex.ts
-import { isDeepStrictEqual as isDeepStrictEqual3 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual4 } from "util";
 var CODEX_SKILL_CONFIG_SECTIONS = /^\[\[skills\.config\]\][^\n]*(?:\n(?!\s*\[)[^\n]*)*/gm;
 function assertCodexPathConfigEditable(text2) {
   const before = Bun.TOML.parse(text2);
@@ -40728,7 +40764,7 @@ function assertCodexPathConfigEditable(text2) {
   delete expected.skills.config;
   try {
     const withoutSections = Bun.TOML.parse(text2.replace(CODEX_SKILL_CONFIG_SECTIONS, ""));
-    if (isDeepStrictEqual3(withoutSections, expected))
+    if (isDeepStrictEqual4(withoutSections, expected))
       return;
   } catch {}
   throw new Error("Codex skill path controls require ordinary [[skills.config]] TOML tables; preserve and convert inline or dotted config arrays before running skills hook install");
@@ -40766,7 +40802,7 @@ function disableCodexBundledSkills(text2) {
   const candidates = new Set;
   const consider = (candidate2) => {
     try {
-      if (isDeepStrictEqual3(Bun.TOML.parse(candidate2), expected))
+      if (isDeepStrictEqual4(Bun.TOML.parse(candidate2), expected))
         candidates.add(candidate2);
     } catch {}
   };
@@ -41224,7 +41260,15 @@ function planAgentIntegration(options) {
     validateProfile(profileId2);
     return [agent, { command, profileId: profileId2 }];
   }));
-  const discoveries = [...new Set(options.agents)].map((agent) => resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, canonical: (path) => canonicalAgentPath(path, aliases) }));
+  const retainedAgents = [];
+  const discoveries = [...new Set(options.agents)].map((agent) => {
+    const retainedReview = options.discoveryInputs === undefined && policy.bridge?.discovery?.[agent]?.method === "reviewed" ? policy.bridge.discovery[agent] : undefined;
+    if (retainedReview) {
+      assertManagedAgentBridge(agent, { home, dataDir: dataDir2, projectDir: options.projectDir ?? home });
+      retainedAgents.push(agent);
+    }
+    return resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, retainedReview, canonical: (path) => canonicalAgentPath(path, aliases) });
+  });
   const nativeSkills = inventoryNativeSkills(home, { includeVendor: true, guardHermes: options.agents.includes("hermes"), agents: options.agents, projectDir: options.projectDir, agentRoots: discoveries.flatMap((binding) => binding.roots.map((path) => ({ agent: binding.agent, path }))), allowRootAliases: options.allowRootAliases });
   const changes = [];
   for (const agent of [...new Set(options.agents)]) {
@@ -41309,7 +41353,7 @@ function planAgentIntegration(options) {
   if (JSON.stringify(policy) !== JSON.stringify(nextPolicy))
     changes.push({ path: policyPath, before: previousPolicy, after: serializedPolicy });
   recheckRootAliases(aliases);
-  return { dataDir: dataDir2, profileId, changes, nativeSkills, observedPolicy: { path: policyPath, before: previousPolicy }, discoveryBefore: discoveries, discoveryAfter, ...aliases.length ? { rootAliases: aliases } : {} };
+  return { dataDir: dataDir2, profileId, changes, nativeSkills, observedPolicy: { path: policyPath, before: previousPolicy }, discoveryBefore: discoveries, discoveryAfter, ...aliases.length ? { rootAliases: aliases } : {}, ...retainedAgents.length ? { retainedReviewChecks: { home, projectDir: options.projectDir ?? home, agents: retainedAgents } } : {} };
 }
 function planClaudeStopHookUpdate(options) {
   return planClaudeHookEventsUpdate({ ...options, events: ["Stop"] });
@@ -41428,6 +41472,8 @@ function applyAgentIntegration(plan) {
       parseManagedSkillPolicy(change.after);
   const aliases = plan.rootAliases ?? [];
   recheckRootAliases(aliases);
+  for (const agent of plan.retainedReviewChecks?.agents ?? [])
+    assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
   for (const agent of plan.managedAgentChecks?.agents ?? [])
     assertManagedAgentBridge(agent, { home: plan.managedAgentChecks.home, dataDir: plan.dataDir, projectDir: plan.managedAgentChecks.home });
   for (const binding of plan.discoveryBefore ?? []) {

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