@hasna/skills 0.10.49 → 0.10.50

package/README.md

@@ -559,7 +559,8 @@ The plan proves the preserved original matches every witness being replaced,
 permits only the documented non-discovery differences, and labels the replacement
 witness (the JSON receipt lists them under `replacedWitnesses`). `--apply`
 preserves and reads back the original policy before writing, and never writes the
-native configuration. Claude upgrades to `claude-settings-v3`; Codex uses
+native configuration. Claude upgrades to `claude-settings-v3`, or to
+`claude-settings-v4` with `--claude-witness-version 4`; Codex uses
 `codex-settings-v2`, which also replaces the narrower automatic
 `plugins`/`marketplaces`/`skills` projection of the same file once the preserved
 original is proved to explain it. That projection is order-sensitive, so it keeps
@@ -1304,6 +1305,21 @@ the backup keeps the exact previous launcher (symlink text or pinned bytes), and
 projection and `skills self-update` read a managed pinned launcher as the exact
 entry it runs and bind the launcher's own bytes as well.
 
+An updater from before pinned launchers (0.10.48 and earlier) writes bare symlinks,
+including when it installs a version that has them, and an exact-version update to
+the version already installed is refused. `skills self-update --adopt-aliases` pins
+those launchers in place: in `~/.local/bin`, `~/.bun/bin`, `/opt/homebrew/bin` and
+`/usr/local/bin`, a bare symlink that already reaches the current runtime's entry is
+adopted like an alias still pointing at an older install. The same refusals apply
+(an unsafe or unwritable directory, a launcher owned by another account, a foreign
+file, an unsupported link chain), the exact symlink is kept as
+`<launcher>.skills-alias-prev-<receipt id>`, the receipt records it as the old
+`symlink` shape, and `--rollback-aliases <receipt id>` restores it exactly. A
+launcher already pinned to the current runtime is left unchanged. Undo in reverse
+order: roll back the adoption before rolling back the runtime update that wrote
+those symlinks, because that update's `--rollback` refuses with
+`LAUNCHER_DRIFT_ROLLBACK_REFUSED` while the adopted pinned launchers are in place.
+
 To require a minimum dependency age, pass a positive integer number of days and
 repeat the exclusion option for package names or package globs:
 
@@ -2568,3 +2584,18 @@ Upgrade an existing review with `skills hook rebind-settings --agent codex
 Review the plan before adding `--apply`; the original review preimage must match
 its original mode, and unrelated changes refuse. This preserves the native
 configuration, root aliases, other witnesses and active session pins.
+
+`claude-settings-v4` is an explicit successor to `claude-settings-v3`. It
+additionally ignores only a top-level `theme` whose value is exactly one of the
+documented built-in values (`auto`, `dark`, `light`, `dark-daltonized`,
+`light-daltonized`, `dark-ansi`, `light-ansi`). Custom and plugin themes, other
+values or types, nested `theme` keys, `skipDangerousModePermissionPrompt` and
+every permission, hook, environment, helper and unknown setting stay bound.
+Existing raw/V1/V2/V3 reviews retain their original meaning.
+
+Capture with `skills hook witness --kind claude-settings-v4 --path <settings.json>`.
+Upgrade an existing review with `skills hook rebind-settings --agent claude
+--claude-witness-version 4 --reviewed-preimage <preserved-settings.json>
+--expected-policy-sha256 <policy-hash> --expected-settings-sha256 <settings-hash>`.
+Review the plan before adding `--apply`. See
+[built-in theme reviews](docs/plugin-admission.md#explicit-v4-built-in-theme-reviews).

package/bin/index.js

@@ -36888,7 +36888,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.49",
+    version: "0.10.50",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -40066,7 +40066,9 @@ function inferencePreference(key, child, version) {
 function settingsDigest(text, version = 1) {
   const value = parse(text);
   value.entries = value.entries.filter(([key, child]) => {
-    if (version !== 1 && inferencePreference(key, child, version))
+    if (version === 4 && key === "theme" && child.kind === "string" && BUILTIN_THEMES.has(child.value))
+      return false;
+    if (version !== 1 && inferencePreference(key, child, version === 4 ? 3 : version))
       return false;
     if (key === "model") {
       need(child.kind === "string", "contains an invalid model selection");
@@ -40124,6 +40126,26 @@ function upgradeClaudeSettingsWitness(previous, reviewedSettingsPath) {
   need(settingsDigest(before2, 3) === sha256, "non-preference settings changed; explicit discovery review required");
   return { path: previous.path, hashMode: "claude-settings-v3", sha256 };
 }
+function captureClaudeSettingsV4(path, budget = { remaining: 256 * 1024 * 1024 }) {
+  return { path, hashMode: "claude-settings-v4", sha256: settingsDigest(readNativeSettingsWitnessFile(path, budget), 4) };
+}
+function hashClaudeSettingsReplacementV4(text, budget) {
+  need(typeof text === "string", "requires settings text");
+  const bytes = Buffer.byteLength(text);
+  need(bytes <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes && Number.isSafeInteger(budget.remaining) && budget.remaining >= bytes, "exceeds its byte limit");
+  budget.remaining -= bytes;
+  return settingsDigest(text, 4);
+}
+function upgradeClaudeSettingsWitnessV4(previous, reviewedSettingsPath) {
+  need(previous && Object.keys(previous).every((key) => ["path", "hashMode", "sha256"].includes(key)) && (previous.hashMode === undefined || previous.hashMode === "bytes" || previous.hashMode === "claude-settings-v1" || previous.hashMode === "claude-settings-v2" || previous.hashMode === "claude-settings-v3") && typeof previous.sha256 === "string" && /^[a-f0-9]{64}$/.test(previous.sha256), "requires an exact prior settings witness");
+  const budget = { remaining: 2 * CLAUDE_SETTINGS_WITNESS_LIMITS.bytes };
+  const before2 = readNativeSettingsWitnessFile(reviewedSettingsPath, budget), current = readNativeSettingsWitnessFile(previous.path, budget);
+  const beforeDigest = previous.hashMode === undefined || previous.hashMode === "bytes" ? createHash2("sha256").update(before2).digest("hex") : settingsDigest(before2, previous.hashMode === "claude-settings-v1" ? 1 : previous.hashMode === "claude-settings-v2" ? 2 : 3);
+  need(beforeDigest === previous.sha256, "reviewed preimage does not match the prior witness");
+  const sha256 = settingsDigest(current, 4);
+  need(settingsDigest(before2, 4) === sha256, "non-preference settings changed; explicit discovery review required");
+  return { path: previous.path, hashMode: "claude-settings-v4", sha256 };
+}
 function hashNativeJsonControls(text, excludedMetadata) {
   need(Buffer.byteLength(text) <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes, "exceeds its byte limit");
   const value = parse(text);
@@ -40156,7 +40178,7 @@ function hashSumiNativeJsonControls(text) {
   });
   return createHash2("sha256").update("hasna.skills.sumi-settings.v1\x00").update(JSON.stringify(value)).digest("hex");
 }
-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 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, CLAUDE_BUILTIN_THEMES, BUILTIN_THEMES, 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 });
   BOOLEAN_PREFERENCES = new Set([
@@ -40210,6 +40232,8 @@ var init_claude_settings_witness = __esm(() => {
     "claude-opus-4-6[1m]",
     "claude-sonnet-4-6[1m]"
   ]);
+  CLAUDE_BUILTIN_THEMES = Object.freeze(["auto", "dark", "light", "dark-daltonized", "light-daltonized", "dark-ansi", "light-ansi"]);
+  BUILTIN_THEMES = new Set(CLAUDE_BUILTIN_THEMES);
   PERSISTED_EFFORT_LEVELS = new Set(["low", "medium", "high", "xhigh"]);
 });
 
@@ -40387,14 +40411,14 @@ function assertAgentPolicyCollections(policy) {
       text(source.path);
       requireBound(source.sha256 === null || typeof source.sha256 === "string" && /^[a-f0-9]{64}$/.test(source.sha256));
       if (source.hashMode !== undefined)
-        requireBound(["bytes", "path-bytes", "claude-plugin-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "sumi-settings-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
+        requireBound(["bytes", "path-bytes", "claude-plugin-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "sumi-settings-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
       if (source.hashMode === "claude-plugin-manifest-v1")
         requireBound(agent === "claude" && value.agent === "claude" && ["automatic", "reviewed"].includes(value.method) && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve4(source.path) === source.path && source.path.endsWith(join11(sep2, ".claude-plugin", "plugin.json")) && source.managedPlugins === undefined);
       if (source.hashMode === "sumi-settings-v1")
         requireBound(agent === "sumi" && value.agent === "sumi" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve4(source.path) === source.path && basename3(source.path) === "sumi.json");
       if (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4"))
         requireBound(agent === "codex" && value.agent === "codex" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve4(source.path) === source.path && basename3(source.path) === "config.toml");
-      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3")
+      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4"))
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve4(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) && resolve4(source.path) === source.path && basename3(source.path) === "known_marketplaces.json");
@@ -55262,6 +55286,8 @@ function atomicWrite2(path, content) {
 function planAgentSettingsWitnessUpgrade(options) {
   if (options.targetCodexVersion !== undefined && (options.agent !== "codex" || ![2, 3, 4].includes(options.targetCodexVersion)))
     throw new Error("Invalid Codex witness target version");
+  if (options.targetClaudeVersion !== undefined && (options.agent !== "claude" || ![3, 4].includes(options.targetClaudeVersion)))
+    throw new Error("Invalid Claude witness target version");
   const home = resolve14(options.home ?? homedir3()), dataDir3 = options.dataDir ?? getDataDirReadOnly();
   const snapshot2 = readManagedSkillPolicySnapshot(dataDir3);
   if (!snapshot2 || sha3(snapshot2.text) !== options.expectedPolicySha256)
@@ -55309,7 +55335,7 @@ function planAgentSettingsWitnessUpgrade(options) {
       replaced.push(source);
     }
   }
-  const next = options.agent === "sumi" ? upgradeSumiSettingsWitness(previous, options.reviewedPreimage) : options.agent === "claude" ? upgradeClaudeSettingsWitness(previous, options.reviewedPreimage) : options.targetCodexVersion === 4 ? upgradeCodexSettingsWitnessV4(previous, options.reviewedPreimage) : options.targetCodexVersion === 3 ? upgradeCodexSettingsWitnessV3(previous, options.reviewedPreimage) : upgradeCodexSettingsWitness(previous, options.reviewedPreimage);
+  const next = options.agent === "sumi" ? upgradeSumiSettingsWitness(previous, options.reviewedPreimage) : options.agent === "claude" ? options.targetClaudeVersion === 4 ? upgradeClaudeSettingsWitnessV4(previous, options.reviewedPreimage) : upgradeClaudeSettingsWitness(previous, options.reviewedPreimage) : options.targetCodexVersion === 4 ? upgradeCodexSettingsWitnessV4(previous, options.reviewedPreimage) : options.targetCodexVersion === 3 ? upgradeCodexSettingsWitnessV3(previous, options.reviewedPreimage) : upgradeCodexSettingsWitness(previous, options.reviewedPreimage);
   const rebound = [];
   for (const source of binding.sources) {
     if (!replaced.includes(source)) {
@@ -55355,7 +55381,7 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
     const upgrade = plan.settingsWitnessUpgrade;
     if (!plan.managedAgentChecks || !plan.observedPolicy?.before)
       throw new Error("Invalid settings witness upgrade plan");
-    const verified = planAgentSettingsWitnessUpgrade({ agent: upgrade.agent, ...upgrade.agent === "codex" ? { targetCodexVersion: upgrade.toHashMode === "codex-settings-v4" ? 4 : upgrade.toHashMode === "codex-settings-v3" ? 3 : 2 } : {}, reviewedPreimage: upgrade.reviewedPreimage, home: plan.managedAgentChecks.home, dataDir: plan.dataDir, expectedPolicySha256: sha3(plan.observedPolicy.before), expectedSettingsSha256: upgrade.currentSettingsSha256 });
+    const verified = planAgentSettingsWitnessUpgrade({ agent: upgrade.agent, ...upgrade.agent === "codex" ? { targetCodexVersion: upgrade.toHashMode === "codex-settings-v4" ? 4 : upgrade.toHashMode === "codex-settings-v3" ? 3 : 2 } : {}, ...upgrade.agent === "claude" && upgrade.toHashMode === "claude-settings-v4" ? { targetClaudeVersion: 4 } : {}, reviewedPreimage: upgrade.reviewedPreimage, home: plan.managedAgentChecks.home, dataDir: plan.dataDir, expectedPolicySha256: sha3(plan.observedPolicy.before), expectedSettingsSha256: upgrade.currentSettingsSha256 });
     if (JSON.stringify(verified.changes) !== JSON.stringify(plan.changes) || JSON.stringify(verified.settingsWitnessUpgrade) !== JSON.stringify(upgrade))
       throw new Error("Settings witness upgrade plan changed");
     provenDiscovery = verified.discoveryBefore[0];
@@ -59082,13 +59108,13 @@ function projected(source, changes, budget2 = discoveryByteBudget()) {
       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 === "codex-settings-v4" ? hashCodexSettingsReplacementV4 : source.hashMode === "codex-settings-v3" ? hashCodexSettingsReplacementV3 : source.hashMode === "codex-settings-v2" ? hashCodexSettingsReplacementV2 : hashCodexSettingsReplacement)(changes.get(source.path), budget2) : current;
   }
-  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") {
+  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4")) {
     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-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget2).sha256;
+    const current = (source.hashMode === "claude-settings-v4" ? captureClaudeSettingsV4 : source.hashMode === "claude-settings-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget2).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-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget2) : current;
+    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v4" ? hashClaudeSettingsReplacementV4 : source.hashMode === "claude-settings-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget2) : 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))
@@ -59323,7 +59349,7 @@ function assertMarketplaceBinding(binding, source) {
     throw new Error("Sumi settings witnesses require explicit reviewed Sumi configuration");
   if ((source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")) && (binding.agent !== "codex" || binding.method !== "reviewed" || basename10(source.path) !== "config.toml"))
     throw new Error("Codex settings witnesses require explicit reviewed Codex configuration");
-  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && (binding.agent !== "claude" || binding.method !== "reviewed" || basename10(source.path) !== "settings.json"))
+  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4")) && (binding.agent !== "claude" || binding.method !== "reviewed" || basename10(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");
@@ -59513,7 +59539,7 @@ function resolveAgentDiscovery(options) {
     verifyAgentDiscovery(retained);
     if (!retained.sources.some((source) => source.path === canonical7(configPath) && source.format === undefined && source.fields === undefined))
       unresolved("retained review is missing the full agent configuration source");
-    if (retained.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
+    if (retained.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
       unresolved("retained settings witness names another configuration source");
     const covered = supersedesSettingsProjection(agent, retained.sources, canonical7(configPath)) ? sources.filter((source) => !isSupersededSettingsProjection(agent, canonical7(configPath), source)) : sources;
     if (covered.some((source) => !retained.sources.some((saved) => isDeepStrictEqual11(saved, source))) || [...roots].some((root2) => !retained.roots.includes(root2)) || agent === "gemini" && JSON.stringify(retained.builtinNames) !== JSON.stringify(builtinNames))
@@ -59527,7 +59553,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 === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
+    if (review.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
       throw new Error("Semantic settings witnesses must name the configured agent configuration source");
     if (!review.sources.some((source) => source.path === canonical7(configPath)))
       throw new Error("Discovery review must include the agent configuration source");
@@ -112470,7 +112496,7 @@ function adoptCopyfileAliases(options = {}) {
         const actual = launcher.target;
         const oldLinkTarget = launcher.kind === "symlink" ? launcher.linkTarget : actual;
         const newTarget = join60(layout.currentPackageRoot, target);
-        if (actual === newTarget)
+        if (actual === newTarget && launcher.kind === "pinned")
           continue;
         const chain = inspectAliasPackageChain(home, path, oldLinkTarget, actual, target);
         const source = validateAliasSource(home, name, actual);
@@ -112627,7 +112653,7 @@ function rollbackCopyfileAliases(receiptId, options = {}) {
       if (entryExists(item.backupPath)) {
         if (!launcherIs(item.backupPath, oldLauncherState(item)))
           throw new Error("ALIAS_PREIMAGE_DRIFT");
-      } else if (current !== item.oldTarget) {
+      } else if (current !== item.oldTarget || !launcherIs(item.path, oldLauncherState(item))) {
         throw new Error("ALIAS_BACKUP_MISSING_FOR_SWITCH");
       }
     }
@@ -116159,19 +116185,21 @@ function registerAgentIntegration(parent) {
       process.exitCode = 1;
     }
   });
-  hook.command("witness").requiredOption("--kind <kind>", "sumi-settings-v1, claude-settings-v3, claude-settings-v2, codex-settings-v4, codex-settings-v3, codex-settings-v2, codex-settings-v1 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 === "sumi-settings-v1" ? captureSumiSettings : options.kind === "codex-settings-v4" ? captureCodexSettingsV4 : options.kind === "codex-settings-v3" ? captureCodexSettingsV3 : options.kind === "codex-settings-v2" ? captureCodexSettingsV2 : options.kind === "codex-settings-v1" ? captureCodexSettings : options.kind === "claude-settings-v3" ? captureClaudeSettingsV3 : options.kind === "claude-settings-v2" ? captureClaudeSettingsV2 : options.kind === "claude-marketplace-registry-v2" ? captureClaudeMarketplaceRegistryV2 : null;
+  hook.command("witness").requiredOption("--kind <kind>", "sumi-settings-v1, claude-settings-v4, claude-settings-v3, claude-settings-v2, codex-settings-v4, codex-settings-v3, codex-settings-v2, codex-settings-v1 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 === "sumi-settings-v1" ? captureSumiSettings : options.kind === "codex-settings-v4" ? captureCodexSettingsV4 : options.kind === "codex-settings-v3" ? captureCodexSettingsV3 : options.kind === "codex-settings-v2" ? captureCodexSettingsV2 : options.kind === "codex-settings-v1" ? captureCodexSettings : options.kind === "claude-settings-v4" ? captureClaudeSettingsV4 : 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 sumi-settings-v1, claude-settings-v3, claude-settings-v2, codex-settings-v4, codex-settings-v3, codex-settings-v2, codex-settings-v1 or claude-marketplace-registry-v2");
+      throw new Error("Unsupported witness kind; select sumi-settings-v1, claude-settings-v4, claude-settings-v3, claude-settings-v2, codex-settings-v4, codex-settings-v3, codex-settings-v2, codex-settings-v1 or claude-marketplace-registry-v2");
     await writeCliOutput(JSON.stringify(capture2(options.path), null, 2));
   });
-  hook.command("rebind-settings").requiredOption("--agent <agent>", "claude, codex or sumi").requiredOption("--reviewed-preimage <path>", "Exact preserved legacy settings.json, config.toml or sumi.json").requiredOption("--expected-policy-sha256 <sha256>", "Exact current managed policy bytes").requiredOption("--expected-settings-sha256 <sha256>", "Exact current native settings bytes").option("--codex-witness-version <version>", "Explicit target: 2 (legacy default) 3 (service tier and model-advertised effort), or 4 (native availability UI counts)").option("--apply", "Apply the explicit semantic witness upgrade with preservation and readback", false).option("--json", "Return the metadata-only plan or receipt", false).description("Explicitly migrate a legacy native settings witness after proving only known preferences changed").action(async (options) => {
+  hook.command("rebind-settings").requiredOption("--agent <agent>", "claude, codex or sumi").requiredOption("--reviewed-preimage <path>", "Exact preserved legacy settings.json, config.toml or sumi.json").requiredOption("--expected-policy-sha256 <sha256>", "Exact current managed policy bytes").requiredOption("--expected-settings-sha256 <sha256>", "Exact current native settings bytes").option("--codex-witness-version <version>", "Explicit target: 2 (legacy default) 3 (service tier and model-advertised effort), or 4 (native availability UI counts)").option("--claude-witness-version <version>", "Explicit target: 3 (default) or 4 (also permits a built-in top-level theme)").option("--apply", "Apply the explicit semantic witness upgrade with preservation and readback", false).option("--json", "Return the metadata-only plan or receipt", false).description("Explicitly migrate a legacy native settings witness after proving only known preferences changed").action(async (options) => {
     try {
       if (!["claude", "codex", "sumi"].includes(options.agent))
         throw new Error("Settings witness rebind accepts claude, codex or sumi");
       if (options.codexWitnessVersion !== undefined && !["2", "3", "4"].includes(options.codexWitnessVersion))
         throw new Error("Codex witness version accepts 2, 3 or 4");
-      const plan = planAgentSettingsWitnessUpgrade({ ...options.codexWitnessVersion !== undefined ? { targetCodexVersion: Number(options.codexWitnessVersion) } : {}, agent: options.agent, reviewedPreimage: options.reviewedPreimage, expectedPolicySha256: options.expectedPolicySha256, expectedSettingsSha256: options.expectedSettingsSha256 });
+      if (options.claudeWitnessVersion !== undefined && !["3", "4"].includes(options.claudeWitnessVersion))
+        throw new Error("Claude witness version accepts 3 or 4");
+      const plan = planAgentSettingsWitnessUpgrade({ ...options.codexWitnessVersion !== undefined ? { targetCodexVersion: Number(options.codexWitnessVersion) } : {}, ...options.claudeWitnessVersion !== undefined ? { targetClaudeVersion: Number(options.claudeWitnessVersion) } : {}, agent: options.agent, reviewedPreimage: options.reviewedPreimage, expectedPolicySha256: options.expectedPolicySha256, expectedSettingsSha256: options.expectedSettingsSha256 });
       const result2 = options.apply ? applyAgentIntegration(plan) : { changed: [], backups: [] };
       const receipt = { applied: options.apply, settingsWitnessUpgrade: plan.settingsWitnessUpgrade, ...result2 };
       await writeCliOutput(options.json ? JSON.stringify(receipt) : `Settings witness ${options.apply ? "upgraded" : "planned"} for ${options.agent}. Native configuration was not changed.`);

package/bin/mcp.js

@@ -20019,7 +20019,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.49",
+    version: "0.10.50",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -38370,7 +38370,9 @@ function inferencePreference(key, child, version2) {
 function settingsDigest(text, version2 = 1) {
   const value = parse6(text);
   value.entries = value.entries.filter(([key, child]) => {
-    if (version2 !== 1 && inferencePreference(key, child, version2))
+    if (version2 === 4 && key === "theme" && child.kind === "string" && BUILTIN_THEMES.has(child.value))
+      return false;
+    if (version2 !== 1 && inferencePreference(key, child, version2 === 4 ? 3 : version2))
       return false;
     if (key === "model") {
       need(child.kind === "string", "contains an invalid model selection");
@@ -38418,6 +38420,16 @@ function hashClaudeSettingsReplacementV3(text, budget) {
   budget.remaining -= bytes;
   return settingsDigest(text, 3);
 }
+function captureClaudeSettingsV4(path, budget = { remaining: 256 * 1024 * 1024 }) {
+  return { path, hashMode: "claude-settings-v4", sha256: settingsDigest(readNativeSettingsWitnessFile(path, budget), 4) };
+}
+function hashClaudeSettingsReplacementV4(text, budget) {
+  need(typeof text === "string", "requires settings text");
+  const bytes = Buffer.byteLength(text);
+  need(bytes <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes && Number.isSafeInteger(budget.remaining) && budget.remaining >= bytes, "exceeds its byte limit");
+  budget.remaining -= bytes;
+  return settingsDigest(text, 4);
+}
 function hashNativeJsonControls(text, excludedMetadata) {
   need(Buffer.byteLength(text) <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes, "exceeds its byte limit");
   const value = parse6(text);
@@ -38450,7 +38462,7 @@ function hashSumiNativeJsonControls(text) {
   });
   return createHash2("sha256").update("hasna.skills.sumi-settings.v1\x00").update(JSON.stringify(value)).digest("hex");
 }
-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 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, CLAUDE_BUILTIN_THEMES, BUILTIN_THEMES, 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 });
   BOOLEAN_PREFERENCES = new Set([
@@ -38504,6 +38516,8 @@ var init_claude_settings_witness = __esm(() => {
     "claude-opus-4-6[1m]",
     "claude-sonnet-4-6[1m]"
   ]);
+  CLAUDE_BUILTIN_THEMES = Object.freeze(["auto", "dark", "light", "dark-daltonized", "light-daltonized", "dark-ansi", "light-ansi"]);
+  BUILTIN_THEMES = new Set(CLAUDE_BUILTIN_THEMES);
   PERSISTED_EFFORT_LEVELS = new Set(["low", "medium", "high", "xhigh"]);
 });
 
@@ -38666,14 +38680,14 @@ function assertAgentPolicyCollections(policy) {
       text(source.path);
       requireBound(source.sha256 === null || typeof source.sha256 === "string" && /^[a-f0-9]{64}$/.test(source.sha256));
       if (source.hashMode !== undefined)
-        requireBound(["bytes", "path-bytes", "claude-plugin-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "sumi-settings-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
+        requireBound(["bytes", "path-bytes", "claude-plugin-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "sumi-settings-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
       if (source.hashMode === "claude-plugin-manifest-v1")
         requireBound(agent === "claude" && value.agent === "claude" && ["automatic", "reviewed"].includes(value.method) && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute4(source.path) && resolve3(source.path) === source.path && source.path.endsWith(join10(sep3, ".claude-plugin", "plugin.json")) && source.managedPlugins === undefined);
       if (source.hashMode === "sumi-settings-v1")
         requireBound(agent === "sumi" && value.agent === "sumi" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute4(source.path) && resolve3(source.path) === source.path && basename4(source.path) === "sumi.json");
       if (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4"))
         requireBound(agent === "codex" && value.agent === "codex" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute4(source.path) && resolve3(source.path) === source.path && basename4(source.path) === "config.toml");
-      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3")
+      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4"))
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute4(source.path) && resolve3(source.path) === source.path && basename4(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) && isAbsolute4(source.path) && resolve3(source.path) === source.path && basename4(source.path) === "known_marketplaces.json");
@@ -50580,13 +50594,13 @@ function projected(source, changes, budget2 = discoveryByteBudget()) {
       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 === "codex-settings-v4" ? hashCodexSettingsReplacementV4 : source.hashMode === "codex-settings-v3" ? hashCodexSettingsReplacementV3 : source.hashMode === "codex-settings-v2" ? hashCodexSettingsReplacementV2 : hashCodexSettingsReplacement)(changes.get(source.path), budget2) : current;
   }
-  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") {
+  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4")) {
     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-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget2).sha256;
+    const current = (source.hashMode === "claude-settings-v4" ? captureClaudeSettingsV4 : source.hashMode === "claude-settings-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget2).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-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget2) : current;
+    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v4" ? hashClaudeSettingsReplacementV4 : source.hashMode === "claude-settings-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget2) : 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))
@@ -50805,7 +50819,7 @@ function assertMarketplaceBinding(binding, source) {
     throw new Error("Sumi settings witnesses require explicit reviewed Sumi configuration");
   if ((source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")) && (binding.agent !== "codex" || binding.method !== "reviewed" || basename8(source.path) !== "config.toml"))
     throw new Error("Codex settings witnesses require explicit reviewed Codex configuration");
-  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"))
+  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4")) && (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");
@@ -50927,7 +50941,7 @@ function resolveAgentDiscovery(options) {
     verifyAgentDiscovery(retained);
     if (!retained.sources.some((source) => source.path === canonical7(configPath) && source.format === undefined && source.fields === undefined))
       unresolved("retained review is missing the full agent configuration source");
-    if (retained.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
+    if (retained.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
       unresolved("retained settings witness names another configuration source");
     const covered = supersedesSettingsProjection(agent, retained.sources, canonical7(configPath)) ? sources.filter((source) => !isSupersededSettingsProjection(agent, canonical7(configPath), source)) : sources;
     if (covered.some((source) => !retained.sources.some((saved) => isDeepStrictEqual4(saved, source))) || [...roots].some((root) => !retained.roots.includes(root)) || agent === "gemini" && JSON.stringify(retained.builtinNames) !== JSON.stringify(builtinNames))
@@ -50941,7 +50955,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 === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
+    if (review.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
       throw new Error("Semantic settings witnesses must name the configured agent configuration source");
     if (!review.sources.some((source) => source.path === canonical7(configPath)))
       throw new Error("Discovery review must include the agent configuration source");

package/bin/migrate.js

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

package/bin/server.js

@@ -24140,7 +24140,7 @@ restoreLaunchCwd();
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.49",
+  version: "0.10.50",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

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

package/dist/index.d.ts

@@ -64,7 +64,7 @@ export { planAgentIntegration, planClaudeStopHookUpdate, planClaudePreToolUseHoo
 export type { ClaudeManagedHookProjection, ClaudeManagedHookProjectionOptions } 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, captureClaudeSettingsV3, upgradeClaudeSettingsWitness } from "./lib/claude-settings-witness.js";
+export { captureClaudeSettings, captureClaudeSettingsV2, captureClaudeSettingsV3, captureClaudeSettingsV4, upgradeClaudeSettingsWitness, upgradeClaudeSettingsWitnessV4 } 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

@@ -9177,6 +9177,8 @@ var BUILTIN_MODEL_SELECTIONS = new Set([
   "claude-opus-4-6[1m]",
   "claude-sonnet-4-6[1m]"
 ]);
+var CLAUDE_BUILTIN_THEMES = Object.freeze(["auto", "dark", "light", "dark-daltonized", "light-daltonized", "dark-ansi", "light-ansi"]);
+var BUILTIN_THEMES = new Set(CLAUDE_BUILTIN_THEMES);
 function canonical(value) {
   if (value.kind === "object")
     return { kind: "object", entries: value.entries.map(([key, child]) => [key, canonical(child)]).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0) };
@@ -9235,7 +9237,9 @@ function inferencePreference(key, child, version) {
 function settingsDigest(text, version = 1) {
   const value = parse(text);
   value.entries = value.entries.filter(([key, child]) => {
-    if (version !== 1 && inferencePreference(key, child, version))
+    if (version === 4 && key === "theme" && child.kind === "string" && BUILTIN_THEMES.has(child.value))
+      return false;
+    if (version !== 1 && inferencePreference(key, child, version === 4 ? 3 : version))
       return false;
     if (key === "model") {
       need(child.kind === "string", "contains an invalid model selection");
@@ -9293,6 +9297,26 @@ function upgradeClaudeSettingsWitness(previous, reviewedSettingsPath) {
   need(settingsDigest(before, 3) === sha256, "non-preference settings changed; explicit discovery review required");
   return { path: previous.path, hashMode: "claude-settings-v3", sha256 };
 }
+function captureClaudeSettingsV4(path, budget = { remaining: 256 * 1024 * 1024 }) {
+  return { path, hashMode: "claude-settings-v4", sha256: settingsDigest(readNativeSettingsWitnessFile(path, budget), 4) };
+}
+function hashClaudeSettingsReplacementV4(text, budget) {
+  need(typeof text === "string", "requires settings text");
+  const bytes = Buffer.byteLength(text);
+  need(bytes <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes && Number.isSafeInteger(budget.remaining) && budget.remaining >= bytes, "exceeds its byte limit");
+  budget.remaining -= bytes;
+  return settingsDigest(text, 4);
+}
+function upgradeClaudeSettingsWitnessV4(previous, reviewedSettingsPath) {
+  need(previous && Object.keys(previous).every((key) => ["path", "hashMode", "sha256"].includes(key)) && (previous.hashMode === undefined || previous.hashMode === "bytes" || previous.hashMode === "claude-settings-v1" || previous.hashMode === "claude-settings-v2" || previous.hashMode === "claude-settings-v3") && typeof previous.sha256 === "string" && /^[a-f0-9]{64}$/.test(previous.sha256), "requires an exact prior settings witness");
+  const budget = { remaining: 2 * CLAUDE_SETTINGS_WITNESS_LIMITS.bytes };
+  const before = readNativeSettingsWitnessFile(reviewedSettingsPath, budget), current = readNativeSettingsWitnessFile(previous.path, budget);
+  const beforeDigest = previous.hashMode === undefined || previous.hashMode === "bytes" ? createHash2("sha256").update(before).digest("hex") : settingsDigest(before, previous.hashMode === "claude-settings-v1" ? 1 : previous.hashMode === "claude-settings-v2" ? 2 : 3);
+  need(beforeDigest === previous.sha256, "reviewed preimage does not match the prior witness");
+  const sha256 = settingsDigest(current, 4);
+  need(settingsDigest(before, 4) === sha256, "non-preference settings changed; explicit discovery review required");
+  return { path: previous.path, hashMode: "claude-settings-v4", sha256 };
+}
 function hashNativeJsonControls(text, excludedMetadata) {
   need(Buffer.byteLength(text) <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes, "exceeds its byte limit");
   const value = parse(text);
@@ -9497,14 +9521,14 @@ function assertAgentPolicyCollections(policy) {
       text(source.path);
       requireBound(source.sha256 === null || typeof source.sha256 === "string" && /^[a-f0-9]{64}$/.test(source.sha256));
       if (source.hashMode !== undefined)
-        requireBound(["bytes", "path-bytes", "claude-plugin-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "sumi-settings-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
+        requireBound(["bytes", "path-bytes", "claude-plugin-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "sumi-settings-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
       if (source.hashMode === "claude-plugin-manifest-v1")
         requireBound(agent === "claude" && value.agent === "claude" && ["automatic", "reviewed"].includes(value.method) && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve3(source.path) === source.path && source.path.endsWith(join7(sep2, ".claude-plugin", "plugin.json")) && source.managedPlugins === undefined);
       if (source.hashMode === "sumi-settings-v1")
         requireBound(agent === "sumi" && value.agent === "sumi" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve3(source.path) === source.path && basename3(source.path) === "sumi.json");
       if (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4"))
         requireBound(agent === "codex" && value.agent === "codex" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve3(source.path) === source.path && basename3(source.path) === "config.toml");
-      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3")
+      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4"))
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute3(source.path) && resolve3(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) && resolve3(source.path) === source.path && basename3(source.path) === "known_marketplaces.json");
@@ -11572,7 +11596,7 @@ function replaceSkillSession(expected, replacement, plan, options = {}, beforeCo
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.49",
+  version: "0.10.50",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -17254,6 +17278,8 @@ function atomicWrite2(path, content) {
 function planAgentSettingsWitnessUpgrade(options) {
   if (options.targetCodexVersion !== undefined && (options.agent !== "codex" || ![2, 3, 4].includes(options.targetCodexVersion)))
     throw new Error("Invalid Codex witness target version");
+  if (options.targetClaudeVersion !== undefined && (options.agent !== "claude" || ![3, 4].includes(options.targetClaudeVersion)))
+    throw new Error("Invalid Claude witness target version");
   const home = resolve13(options.home ?? homedir2()), dataDir2 = options.dataDir ?? getDataDirReadOnly();
   const snapshot2 = readManagedSkillPolicySnapshot(dataDir2);
   if (!snapshot2 || sha3(snapshot2.text) !== options.expectedPolicySha256)
@@ -17301,7 +17327,7 @@ function planAgentSettingsWitnessUpgrade(options) {
       replaced.push(source);
     }
   }
-  const next = options.agent === "sumi" ? upgradeSumiSettingsWitness(previous, options.reviewedPreimage) : options.agent === "claude" ? upgradeClaudeSettingsWitness(previous, options.reviewedPreimage) : options.targetCodexVersion === 4 ? upgradeCodexSettingsWitnessV4(previous, options.reviewedPreimage) : options.targetCodexVersion === 3 ? upgradeCodexSettingsWitnessV3(previous, options.reviewedPreimage) : upgradeCodexSettingsWitness(previous, options.reviewedPreimage);
+  const next = options.agent === "sumi" ? upgradeSumiSettingsWitness(previous, options.reviewedPreimage) : options.agent === "claude" ? options.targetClaudeVersion === 4 ? upgradeClaudeSettingsWitnessV4(previous, options.reviewedPreimage) : upgradeClaudeSettingsWitness(previous, options.reviewedPreimage) : options.targetCodexVersion === 4 ? upgradeCodexSettingsWitnessV4(previous, options.reviewedPreimage) : options.targetCodexVersion === 3 ? upgradeCodexSettingsWitnessV3(previous, options.reviewedPreimage) : upgradeCodexSettingsWitness(previous, options.reviewedPreimage);
   const rebound = [];
   for (const source of binding.sources) {
     if (!replaced.includes(source)) {
@@ -17347,7 +17373,7 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
     const upgrade = plan.settingsWitnessUpgrade;
     if (!plan.managedAgentChecks || !plan.observedPolicy?.before)
       throw new Error("Invalid settings witness upgrade plan");
-    const verified = planAgentSettingsWitnessUpgrade({ agent: upgrade.agent, ...upgrade.agent === "codex" ? { targetCodexVersion: upgrade.toHashMode === "codex-settings-v4" ? 4 : upgrade.toHashMode === "codex-settings-v3" ? 3 : 2 } : {}, reviewedPreimage: upgrade.reviewedPreimage, home: plan.managedAgentChecks.home, dataDir: plan.dataDir, expectedPolicySha256: sha3(plan.observedPolicy.before), expectedSettingsSha256: upgrade.currentSettingsSha256 });
+    const verified = planAgentSettingsWitnessUpgrade({ agent: upgrade.agent, ...upgrade.agent === "codex" ? { targetCodexVersion: upgrade.toHashMode === "codex-settings-v4" ? 4 : upgrade.toHashMode === "codex-settings-v3" ? 3 : 2 } : {}, ...upgrade.agent === "claude" && upgrade.toHashMode === "claude-settings-v4" ? { targetClaudeVersion: 4 } : {}, reviewedPreimage: upgrade.reviewedPreimage, home: plan.managedAgentChecks.home, dataDir: plan.dataDir, expectedPolicySha256: sha3(plan.observedPolicy.before), expectedSettingsSha256: upgrade.currentSettingsSha256 });
     if (JSON.stringify(verified.changes) !== JSON.stringify(plan.changes) || JSON.stringify(verified.settingsWitnessUpgrade) !== JSON.stringify(upgrade))
       throw new Error("Settings witness upgrade plan changed");
     provenDiscovery = verified.discoveryBefore[0];
@@ -20394,13 +20420,13 @@ function projected(source, changes, budget2 = discoveryByteBudget()) {
       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 === "codex-settings-v4" ? hashCodexSettingsReplacementV4 : source.hashMode === "codex-settings-v3" ? hashCodexSettingsReplacementV3 : source.hashMode === "codex-settings-v2" ? hashCodexSettingsReplacementV2 : hashCodexSettingsReplacement)(changes.get(source.path), budget2) : current;
   }
-  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") {
+  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4")) {
     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-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget2).sha256;
+    const current = (source.hashMode === "claude-settings-v4" ? captureClaudeSettingsV4 : source.hashMode === "claude-settings-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget2).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-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget2) : current;
+    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v4" ? hashClaudeSettingsReplacementV4 : source.hashMode === "claude-settings-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget2) : 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))
@@ -20635,7 +20661,7 @@ function assertMarketplaceBinding(binding, source) {
     throw new Error("Sumi settings witnesses require explicit reviewed Sumi configuration");
   if ((source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")) && (binding.agent !== "codex" || binding.method !== "reviewed" || basename10(source.path) !== "config.toml"))
     throw new Error("Codex settings witnesses require explicit reviewed Codex configuration");
-  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") && (binding.agent !== "claude" || binding.method !== "reviewed" || basename10(source.path) !== "settings.json"))
+  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4")) && (binding.agent !== "claude" || binding.method !== "reviewed" || basename10(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");
@@ -20837,7 +20863,7 @@ function resolveAgentDiscovery(options) {
     verifyAgentDiscovery(retained);
     if (!retained.sources.some((source) => source.path === canonical7(configPath) && source.format === undefined && source.fields === undefined))
       unresolved("retained review is missing the full agent configuration source");
-    if (retained.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
+    if (retained.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
       unresolved("retained settings witness names another configuration source");
     const covered = supersedesSettingsProjection(agent, retained.sources, canonical7(configPath)) ? sources.filter((source) => !isSupersededSettingsProjection(agent, canonical7(configPath), source)) : sources;
     if (covered.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))
@@ -20851,7 +20877,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 === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
+    if (review.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
       throw new Error("Semantic settings witnesses must name the configured agent configuration source");
     if (!review.sources.some((source) => source.path === canonical7(configPath)))
       throw new Error("Discovery review must include the agent configuration source");
@@ -47854,6 +47880,7 @@ export {
   upgradeCodexSettingsWitnessV4,
   upgradeCodexSettingsWitnessV3,
   upgradeCodexSettingsWitness,
+  upgradeClaudeSettingsWitnessV4,
   upgradeClaudeSettingsWitness,
   updateSkillRun,
   unsetConfig,
@@ -48045,6 +48072,7 @@ export {
   captureCodexSettingsV2,
   captureCodexSettings,
   captureCodexNativeSkillCatalog,
+  captureClaudeSettingsV4,
   captureClaudeSettingsV3,
   captureClaudeSettingsV2,
   captureClaudeSettings,

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

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

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

@@ -190,6 +190,7 @@ export declare function planClaudeHookEventsUpdate(options: ClaudeHookUpdateOpti
 export declare function planAgentSettingsWitnessUpgrade(options: {
     agent: "claude" | "codex" | "sumi";
     targetCodexVersion?: 2 | 3 | 4;
+    targetClaudeVersion?: 3 | 4;
     reviewedPreimage: string;
     home?: string;
     dataDir?: string;

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

@@ -10,6 +10,7 @@ export interface ClaudeSettingsWitnessBudget {
     remaining: number;
 }
 export declare function readNativeSettingsWitnessFile(path: string, budget: ClaudeSettingsWitnessBudget, filename?: "settings.json" | "config.toml" | "sumi.json"): string;
+export declare const CLAUDE_BUILTIN_THEMES: readonly ["auto", "dark", "light", "dark-daltonized", "light-daltonized", "dark-ansi", "light-ansi"];
 /** Cooperating installers may replace only their explicitly selected event. Compare the strict syntax
  * trees, not JSON.parse values or the preference-tolerant witness digest: all
  * other hooks, discovery settings, unknown values and number spellings remain
@@ -51,6 +52,24 @@ export declare function upgradeClaudeSettingsWitness(previous: {
     hashMode?: "bytes" | "claude-settings-v1" | "claude-settings-v2";
     sha256: string;
 }, reviewedSettingsPath: string): ReturnType<typeof captureClaudeSettingsV3>;
+/** Explicit review that additionally permits a built-in top-level theme.
+ * v1/v2/v3 witnesses keep their meaning; nothing selects v4 implicitly. */
+export declare function captureClaudeSettingsV4(path: string, budget?: ClaudeSettingsWitnessBudget): {
+    path: string;
+    hashMode: "claude-settings-v4";
+    sha256: string;
+};
+export declare function hashClaudeSettingsReplacementV4(text: string, budget: ClaudeSettingsWitnessBudget): string;
+/** Explicit opt-in upgrade to v4 with an exact preserved preimage of the prior
+ * review (raw bytes, v1, v2 or v3). It proves that every setting v4 binds is
+ * unchanged; any other drift, including skipDangerousModePermissionPrompt,
+ * refuses. A stored witness is never rewritten without this call.
+ */
+export declare function upgradeClaudeSettingsWitnessV4(previous: {
+    path: string;
+    hashMode?: "bytes" | "claude-settings-v1" | "claude-settings-v2" | "claude-settings-v3";
+    sha256: string;
+}, reviewedSettingsPath: string): ReturnType<typeof captureClaudeSettingsV4>;
 /** Strict bounded JSON control witness; metadata exclusion must be explicit. */
 export declare function hashNativeJsonControls(text: string, excludedMetadata?: "version"): string;
 /** Sumi's versioned review uses the same strict JSON parser and bounded syntax

package/dist/sdk/index.js

@@ -32373,7 +32373,7 @@ var init_event_sink = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.49",
+  version: "0.10.50",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -38140,6 +38140,8 @@ var BUILTIN_MODEL_SELECTIONS = new Set([
   "claude-opus-4-6[1m]",
   "claude-sonnet-4-6[1m]"
 ]);
+var CLAUDE_BUILTIN_THEMES = Object.freeze(["auto", "dark", "light", "dark-daltonized", "light-daltonized", "dark-ansi", "light-ansi"]);
+var BUILTIN_THEMES = new Set(CLAUDE_BUILTIN_THEMES);
 function canonical(value) {
   if (value.kind === "object")
     return { kind: "object", entries: value.entries.map(([key, child]) => [key, canonical(child)]).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0) };
@@ -38198,7 +38200,9 @@ function inferencePreference(key, child, version) {
 function settingsDigest(text, version = 1) {
   const value = parse2(text);
   value.entries = value.entries.filter(([key, child]) => {
-    if (version !== 1 && inferencePreference(key, child, version))
+    if (version === 4 && key === "theme" && child.kind === "string" && BUILTIN_THEMES.has(child.value))
+      return false;
+    if (version !== 1 && inferencePreference(key, child, version === 4 ? 3 : version))
       return false;
     if (key === "model") {
       need(child.kind === "string", "contains an invalid model selection");
@@ -38256,6 +38260,26 @@ function upgradeClaudeSettingsWitness(previous, reviewedSettingsPath) {
   need(settingsDigest(before, 3) === sha2562, "non-preference settings changed; explicit discovery review required");
   return { path: previous.path, hashMode: "claude-settings-v3", sha256: sha2562 };
 }
+function captureClaudeSettingsV4(path, budget = { remaining: 256 * 1024 * 1024 }) {
+  return { path, hashMode: "claude-settings-v4", sha256: settingsDigest(readNativeSettingsWitnessFile(path, budget), 4) };
+}
+function hashClaudeSettingsReplacementV4(text, budget) {
+  need(typeof text === "string", "requires settings text");
+  const bytes = Buffer.byteLength(text);
+  need(bytes <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes && Number.isSafeInteger(budget.remaining) && budget.remaining >= bytes, "exceeds its byte limit");
+  budget.remaining -= bytes;
+  return settingsDigest(text, 4);
+}
+function upgradeClaudeSettingsWitnessV4(previous, reviewedSettingsPath) {
+  need(previous && Object.keys(previous).every((key) => ["path", "hashMode", "sha256"].includes(key)) && (previous.hashMode === undefined || previous.hashMode === "bytes" || previous.hashMode === "claude-settings-v1" || previous.hashMode === "claude-settings-v2" || previous.hashMode === "claude-settings-v3") && typeof previous.sha256 === "string" && /^[a-f0-9]{64}$/.test(previous.sha256), "requires an exact prior settings witness");
+  const budget = { remaining: 2 * CLAUDE_SETTINGS_WITNESS_LIMITS.bytes };
+  const before = readNativeSettingsWitnessFile(reviewedSettingsPath, budget), current = readNativeSettingsWitnessFile(previous.path, budget);
+  const beforeDigest = previous.hashMode === undefined || previous.hashMode === "bytes" ? createHash6("sha256").update(before).digest("hex") : settingsDigest(before, previous.hashMode === "claude-settings-v1" ? 1 : previous.hashMode === "claude-settings-v2" ? 2 : 3);
+  need(beforeDigest === previous.sha256, "reviewed preimage does not match the prior witness");
+  const sha2562 = settingsDigest(current, 4);
+  need(settingsDigest(before, 4) === sha2562, "non-preference settings changed; explicit discovery review required");
+  return { path: previous.path, hashMode: "claude-settings-v4", sha256: sha2562 };
+}
 function hashNativeJsonControls(text, excludedMetadata) {
   need(Buffer.byteLength(text) <= CLAUDE_SETTINGS_WITNESS_LIMITS.bytes, "exceeds its byte limit");
   const value = parse2(text);
@@ -40405,14 +40429,14 @@ function assertAgentPolicyCollections(policy) {
       text(source.path);
       requireBound(source.sha256 === null || typeof source.sha256 === "string" && /^[a-f0-9]{64}$/.test(source.sha256));
       if (source.hashMode !== undefined)
-        requireBound(["bytes", "path-bytes", "claude-plugin-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "sumi-settings-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
+        requireBound(["bytes", "path-bytes", "claude-plugin-manifest-v1", "claude-plugin-registry", "claude-marketplace-registry", "claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-marketplace-registry-v2", "codex-settings-v1", "codex-settings-v2", "codex-settings-v3", "codex-settings-v4", "sumi-settings-v1"].includes(source.hashMode) && source.format === undefined && source.fields === undefined && (source.hashMode === "bytes" || source.sha256 !== null));
       if (source.hashMode === "claude-plugin-manifest-v1")
         requireBound(agent === "claude" && value.agent === "claude" && ["automatic", "reviewed"].includes(value.method) && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute8(source.path) && resolve7(source.path) === source.path && source.path.endsWith(join14(sep4, ".claude-plugin", "plugin.json")) && source.managedPlugins === undefined);
       if (source.hashMode === "sumi-settings-v1")
         requireBound(agent === "sumi" && value.agent === "sumi" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute8(source.path) && resolve7(source.path) === source.path && basename5(source.path) === "sumi.json");
       if (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4"))
         requireBound(agent === "codex" && value.agent === "codex" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute8(source.path) && resolve7(source.path) === source.path && basename5(source.path) === "config.toml");
-      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3")
+      if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4"))
         requireBound(agent === "claude" && value.agent === "claude" && value.method === "reviewed" && !/[\x00-\x1f\x7f]/.test(source.path) && isAbsolute8(source.path) && resolve7(source.path) === source.path && basename5(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) && isAbsolute8(source.path) && resolve7(source.path) === source.path && basename5(source.path) === "known_marketplaces.json");
@@ -43246,13 +43270,13 @@ function projected(source, changes, budget2 = discoveryByteBudget()) {
       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 === "codex-settings-v4" ? hashCodexSettingsReplacementV4 : source.hashMode === "codex-settings-v3" ? hashCodexSettingsReplacementV3 : source.hashMode === "codex-settings-v2" ? hashCodexSettingsReplacementV2 : hashCodexSettingsReplacement)(changes.get(source.path), budget2) : current;
   }
-  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || source.hashMode === "claude-settings-v3") {
+  if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4")) {
     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-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget2).sha256;
+    const current = (source.hashMode === "claude-settings-v4" ? captureClaudeSettingsV4 : source.hashMode === "claude-settings-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget2).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-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget2) : current;
+    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v4" ? hashClaudeSettingsReplacementV4 : source.hashMode === "claude-settings-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget2) : 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))
@@ -43487,7 +43511,7 @@ function assertMarketplaceBinding(binding, source) {
     throw new Error("Sumi settings witnesses require explicit reviewed Sumi configuration");
   if ((source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")) && (binding.agent !== "codex" || binding.method !== "reviewed" || basename8(source.path) !== "config.toml"))
     throw new Error("Codex settings witnesses require explicit reviewed Codex configuration");
-  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"))
+  if ((source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4")) && (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");
@@ -43689,7 +43713,7 @@ function resolveAgentDiscovery(options) {
     verifyAgentDiscovery(retained);
     if (!retained.sources.some((source) => source.path === canonical7(configPath) && source.format === undefined && source.fields === undefined))
       unresolved("retained review is missing the full agent configuration source");
-    if (retained.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
+    if (retained.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
       unresolved("retained settings witness names another configuration source");
     const covered = supersedesSettingsProjection(agent, retained.sources, canonical7(configPath)) ? sources.filter((source) => !isSupersededSettingsProjection(agent, canonical7(configPath), source)) : sources;
     if (covered.some((source) => !retained.sources.some((saved) => isDeepStrictEqual6(saved, source))) || [...roots].some((root2) => !retained.roots.includes(root2)) || agent === "gemini" && JSON.stringify(retained.builtinNames) !== JSON.stringify(builtinNames))
@@ -43703,7 +43727,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 === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
+    if (review.sources.some((source) => (source.hashMode === "sumi-settings-v1" || source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4" || (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4")))) && source.path !== canonical7(configPath)))
       throw new Error("Semantic settings witnesses must name the configured agent configuration source");
     if (!review.sources.some((source) => source.path === canonical7(configPath)))
       throw new Error("Discovery review must include the agent configuration source");
@@ -45374,6 +45398,8 @@ function atomicWrite2(path, content) {
 function planAgentSettingsWitnessUpgrade(options) {
   if (options.targetCodexVersion !== undefined && (options.agent !== "codex" || ![2, 3, 4].includes(options.targetCodexVersion)))
     throw new Error("Invalid Codex witness target version");
+  if (options.targetClaudeVersion !== undefined && (options.agent !== "claude" || ![3, 4].includes(options.targetClaudeVersion)))
+    throw new Error("Invalid Claude witness target version");
   const home = resolve18(options.home ?? homedir3()), dataDir2 = options.dataDir ?? getDataDirReadOnly();
   const snapshot2 = readManagedSkillPolicySnapshot(dataDir2);
   if (!snapshot2 || sha4(snapshot2.text) !== options.expectedPolicySha256)
@@ -45421,7 +45447,7 @@ function planAgentSettingsWitnessUpgrade(options) {
       replaced.push(source);
     }
   }
-  const next = options.agent === "sumi" ? upgradeSumiSettingsWitness(previous, options.reviewedPreimage) : options.agent === "claude" ? upgradeClaudeSettingsWitness(previous, options.reviewedPreimage) : options.targetCodexVersion === 4 ? upgradeCodexSettingsWitnessV4(previous, options.reviewedPreimage) : options.targetCodexVersion === 3 ? upgradeCodexSettingsWitnessV3(previous, options.reviewedPreimage) : upgradeCodexSettingsWitness(previous, options.reviewedPreimage);
+  const next = options.agent === "sumi" ? upgradeSumiSettingsWitness(previous, options.reviewedPreimage) : options.agent === "claude" ? options.targetClaudeVersion === 4 ? upgradeClaudeSettingsWitnessV4(previous, options.reviewedPreimage) : upgradeClaudeSettingsWitness(previous, options.reviewedPreimage) : options.targetCodexVersion === 4 ? upgradeCodexSettingsWitnessV4(previous, options.reviewedPreimage) : options.targetCodexVersion === 3 ? upgradeCodexSettingsWitnessV3(previous, options.reviewedPreimage) : upgradeCodexSettingsWitness(previous, options.reviewedPreimage);
   const rebound = [];
   for (const source of binding.sources) {
     if (!replaced.includes(source)) {
@@ -45467,7 +45493,7 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
     const upgrade = plan.settingsWitnessUpgrade;
     if (!plan.managedAgentChecks || !plan.observedPolicy?.before)
       throw new Error("Invalid settings witness upgrade plan");
-    const verified = planAgentSettingsWitnessUpgrade({ agent: upgrade.agent, ...upgrade.agent === "codex" ? { targetCodexVersion: upgrade.toHashMode === "codex-settings-v4" ? 4 : upgrade.toHashMode === "codex-settings-v3" ? 3 : 2 } : {}, reviewedPreimage: upgrade.reviewedPreimage, home: plan.managedAgentChecks.home, dataDir: plan.dataDir, expectedPolicySha256: sha4(plan.observedPolicy.before), expectedSettingsSha256: upgrade.currentSettingsSha256 });
+    const verified = planAgentSettingsWitnessUpgrade({ agent: upgrade.agent, ...upgrade.agent === "codex" ? { targetCodexVersion: upgrade.toHashMode === "codex-settings-v4" ? 4 : upgrade.toHashMode === "codex-settings-v3" ? 3 : 2 } : {}, ...upgrade.agent === "claude" && upgrade.toHashMode === "claude-settings-v4" ? { targetClaudeVersion: 4 } : {}, reviewedPreimage: upgrade.reviewedPreimage, home: plan.managedAgentChecks.home, dataDir: plan.dataDir, expectedPolicySha256: sha4(plan.observedPolicy.before), expectedSettingsSha256: upgrade.currentSettingsSha256 });
     if (JSON.stringify(verified.changes) !== JSON.stringify(plan.changes) || JSON.stringify(verified.settingsWitnessUpgrade) !== JSON.stringify(upgrade))
       throw new Error("Settings witness upgrade plan changed");
     provenDiscovery = verified.discoveryBefore[0];

package/docs/plugin-admission.md

@@ -239,8 +239,8 @@ Invalid values for the display preferences refuse capture and verification. Ever
 other field remains bound, including unknown future fields, hooks and their
 exact commands, permissions, native skill suppression and synchronization,
 plugin roots, marketplaces, environment and configuration precedence. Language,
-output style, theme, and command-bearing status or file suggestion settings are
-intentionally retained. These are narrow preference and inference-selection
+output style, theme (v4 alone permits the built-in theme values), and
+command-bearing status or file suggestion settings are intentionally retained. These are narrow preference and inference-selection
 exceptions, not general permission to change Claude configuration. The native
 bridge guard continues to check its exact commands and native Skill policy.
 
@@ -263,6 +263,43 @@ or guarantee when a running native client adopts a settings edit.
 Those complementary checks retain their existing exact registration and hook
 entry comparisons; this mode does not relax them for property-order changes.
 
+### Explicit v4 built-in theme reviews
+
+`claude-settings-v4` is an explicit successor to v3. It binds everything v3
+binds, with one more omission: the top-level `theme` key, and only when its
+value is exactly one of the built-in values `auto`, `dark`, `light`,
+`dark-daltonized`, `light-daltonized`, `dark-ansi` or `light-ansi`. The list is
+pinned in code (`CLAUDE_BUILTIN_THEMES`) from the
+[`theme` setting reference](https://code.claude.com/docs/en/settings-reference#theme)
+and the [built-in presets](https://code.claude.com/docs/en/terminal-config#match-the-color-theme),
+read on 2026-10-07. Custom and plugin themes (`custom:<slug>`,
+`custom:<plugin-name>:<slug>`) load theme files, so they stay bound, as does any
+other value, type, spelling or letter case, and any `theme` key nested inside
+another setting. `skipDangerousModePermissionPrompt`, permissions, hooks,
+environment, `apiKeyHelper` and other helpers, plugins, marketplaces, custom
+model values and unknown settings stay bound exactly as in v3. The digest is
+domain-separated from v3.
+
+Existing v1, v2 and v3 witnesses keep their meaning; nothing selects v4
+implicitly, and a stored witness is never rewritten. A policy opts in through
+either explicit path:
+
+- a fresh review: `skills hook witness --kind claude-settings-v4 --path
+  <settings.json> --json` (or `captureClaudeSettingsV4(path)`), placed in the
+  reviewed discovery inputs and applied with the normal `skills hook install
+  --discovery-inputs <file>` plan/apply flow;
+- a preserved-preimage upgrade: `skills hook rebind-settings --agent claude
+  --claude-witness-version 4 --reviewed-preimage <preserved-settings.json>
+  --expected-policy-sha256 <policy-hash> --expected-settings-sha256
+  <settings-hash>` (or `upgradeClaudeSettingsWitnessV4`). It accepts a raw, v1,
+  v2 or v3 witness, proves the preimage matches it in its original mode, and
+  refuses unless the current settings equal the preimage under v4. Without
+  `--claude-witness-version` the rebind target remains v3.
+
+Install a runtime that recognizes `claude-settings-v4`, including any bundled
+copy of the verifier, before a policy carries it; an older runtime refuses the
+unknown hash mode.
+
 ## Verification and limits
 
 Unit tests cover provenance and mapping failures, offline/revoked authorities,

package/package.json

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