@hasna/hooks 0.10.6 → 0.10.8

package/README.md

@@ -92,6 +92,49 @@ Repair unsafe installation permissions with a verified package installer, then
 check again. This check alone does not prove hosted authentication, native hook
 trust or a running agent's interception.
 
+## Planned safety registration
+
+For repeatable global setup, use the owning installer through its plan/apply
+commands. Planning leaves native settings unchanged and returns a compact digest.
+
+```bash
+hooks safety registration-plan --target codex
+hooks safety registration-apply --target codex --expected-plan-digest PLAN_SHA256
+# The same two commands support --target claude.
+```
+
+Apply checks the exact predecessor, retains an owner-only original and intent,
+and reads back the result. An identical registration returns unchanged without
+rewriting its settings. The planner honors `CODEX_HOME` and `CLAUDE_CONFIG_DIR`;
+conflicting Hooks path overrides refuse. Missing native settings directories are
+created only on apply. Disabled or asynchronous guards, unsafe paths, duplicate
+JSON keys and numbers that cannot be preserved exactly refuse before a write.
+Managed default Claude settings continue through Skills' coordinated writer.
+
+The SDK exports `planNativeSafetyRegistration` and
+`applyNativeSafetyRegistration`. Both return `nativeAdoptionVerified: false`.
+A changed or uncertain apply requires a fresh read-only plan and inspection of
+its recorded operation; no automatic retry or direct overwrite is performed.
+
+After registration, Codex trust uses its supported native configuration writer:
+
+```bash
+hooks safety trust-plan --target codex --cwd /path/to/project --codex-command /absolute/path/to/native/codex
+hooks safety trust-apply --target codex --cwd /path/to/project --codex-command /absolute/path/to/native/codex --expected-plan-digest PLAN_SHA256
+```
+
+The exact definition is verified before trusting and enabling only that guard.
+Unrelated configuration is preserved, and an already trusted, enabled guard
+does not cause a write. A disabled native hooks feature is a refusal, not an
+implicit feature change. Neither registration nor trust proves that an existing
+agent has adopted the change.
+
+For Claude, `hooks safety verify --target claude --cwd /path/to/project` checks
+the selected settings and bundled supervisor. Its result explicitly leaves
+runtime-policy verification, native discovery and native adoption false;
+MDM/server policy, workspace trust and launch flags require native acceptance.
+
+
 ## Codex safety readiness
 
 ```bash
@@ -350,8 +393,46 @@ commands are credential-free and return compact JSON. Verification explicitly
 reports `nativeAdoptionVerified: false`: a fresh native Sumi tool invocation is
 still required to prove that the installed harness uses this binding.
 
+The binding is provisioned from the package's own install, upgrade and safety
+surfaces, so a rollout cannot leave Sumi's fail-closed check unbound:
+
+- the package lifecycle script (`postinstall`) provisions it for a packaged
+  install — a copy inside a `node_modules` directory, never a source checkout;
+- `hooks install` and `hooks upgrade` apply the same step after a successful
+  hook install or package upgrade, and report it as `sumiBinding` in `--json`;
+- `hooks safety provision` runs it on demand and is credential-free.
+
+Every surface is idempotent and shares one policy: a missing binding is created,
+a byte-identical one is written nowhere, a different binding that still verifies
+is left intact, and one whose pinned runtime or worker no longer verifies (an
+upgrade rewrote the worker, or the runtime prefix was pruned) is re-registered
+with the previous record preserved beside it as `<path>.before-<sha256>`. An
+unreadable or unrecognized record is refused rather than overwritten, and
+provisioning never fails the calling command — it reports a stable `code`,
+because an unavailable Trash guard must not break a hook install. bun blocks
+lifecycle scripts for untrusted dependencies and `--ignore-scripts` skips them,
+so the CLI surfaces carry the same policy wherever the lifecycle script does not
+run. A harness rollout that installs this package with scripts disabled must run
+one of those surfaces; that is the harness owner's half of this contract.
+
+The binding pins the absolute paths and sha256 of the Bun runtime and the worker
+bundle as they exist when it is registered, and every evaluation re-verifies
+those exact bytes. A worker inside a tree a package upgrade rewrites in place —
+bun's global install root, its cache, or an isolated `node_modules/.bun/…` store —
+is therefore only valid until that tree is upgraded; the next rewrite refuses
+every command until provisioning runs again. Provisioning still closes the
+immediate gap (an unbound station has no shell at all) but reports it: every
+result carries `durable`, and a false value prints the repair step. Provision
+rollouts from a stable, versioned install tree (for example the fleet's
+`~/.hasna/hooks/runtime/<version>-copyfile` layout) and re-run
+`hooks safety provision` after upgrading a tree the binding points at.
+
 The owner-only `~/.hasna/hooks/native/sumi-trash-guard.json` pins the supervisor's
-runtime, worker, home and PATH. Identical setup is a no-op. An upgrade requires
+runtime, worker, home and PATH. Owner and mode are part of the trust decision: a
+record that is not owned by the current user, or that group or others can read or
+write, is refused with the failing property named — never trusted, adopted or
+silently replaced — because a rewritable binding can point the supervisor at a
+different worker. Identical setup is a no-op. An upgrade requires
 `--expected-binding-sha256 <current-digest>` and preserves the previous record.
 An interrupted lock or unexpected current record requires reconciliation; setup
 does not overwrite it. This file is native configuration, not a Hooks app store.

package/bin/hooks-mcp.js

@@ -3104,7 +3104,7 @@ function checkScriptHash(name, actual) {
 // src/lib/codex-settings.ts
 import { closeSync as closeSync2, existsSync as existsSync8, lstatSync as lstatSync2, mkdirSync as mkdirSync4, openSync as openSync2, readFileSync as readFileSync5, renameSync as renameSync2, unlinkSync, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname4 } from "path";
-import { randomUUID } from "crypto";
+import { createHash as createHash3, randomUUID } from "crypto";
 var snapshots = new WeakMap;
 function current(path) {
   try {
@@ -3139,11 +3139,24 @@ function readCodexSettings(path) {
   snapshots.set(settings, { path, raw });
   return settings;
 }
-function writeCodexSettings(path, settings) {
+function assertSettingsPreimage(raw, expected) {
+  if (expected === undefined)
+    return;
+  if (!/^(?:absent|[a-f0-9]{64})$/.test(expected) || (raw === null ? "absent" : createHash3("sha256").update(raw).digest("hex")) !== expected) {
+    throw new Error("Hook settings changed since planning; no settings were written.");
+  }
+}
+function writeCodexSettings(path, settings, expectedSha256) {
   const snapshot = snapshots.get(settings);
   if (!snapshot || snapshot.path !== path)
     throw new Error("Codex settings require a complete current read before writing.");
-  mkdirSync4(dirname4(path), { recursive: true });
+  assertSettingsPreimage(snapshot.raw, expectedSha256);
+  writeHookSettingsPreimage(path, settings, snapshot.raw);
+  snapshots.set(settings, { path, raw: JSON.stringify(settings, null, 2) + `
+` });
+}
+function writeHookSettingsPreimage(path, settings, before) {
+  mkdirSync4(dirname4(path), { recursive: true, mode: 448 });
   const lock = `${path}.hooks-write.lock`;
   let fd;
   try {
@@ -3153,15 +3166,14 @@ function writeCodexSettings(path, settings) {
   }
   const temp = `${path}.${randomUUID()}.tmp`;
   try {
-    if (current(path) !== snapshot.raw)
-      throw new Error("Codex settings changed since reading; re-read before retrying.");
+    if (current(path) !== before)
+      throw new Error("Hook settings changed since reading; re-read before retrying.");
     const next = JSON.stringify(settings, null, 2) + `
 `;
     writeFileSync3(temp, next, { flag: "wx", mode: 384 });
-    if (current(path) !== snapshot.raw)
-      throw new Error("Codex settings changed since reading; re-read before retrying.");
+    if (current(path) !== before)
+      throw new Error("Hook settings changed since reading; re-read before retrying.");
     renameSync2(temp, path);
-    snapshots.set(settings, { path, raw: next });
   } finally {
     if (existsSync8(temp))
       unlinkSync(temp);
@@ -3173,19 +3185,20 @@ function writeCodexSettings(path, settings) {
 // src/lib/claude-skills-coordination.ts
 import { createHash as createHash5 } from "crypto";
 
-// ../../node_modules/.bun/@hasna+skills@0.9.14+a00d3064559565bb/node_modules/@hasna/skills/dist/index.js
+// ../../node_modules/.bun/@hasna+skills@0.9.17+a00d3064559565bb/node_modules/@hasna/skills/dist/index.js
 import { existsSync as existsSync9 } from "fs";
 import { homedir as homedir4 } from "os";
 import { join as join8, resolve as resolve3 } from "path";
 import { homedir as pathsResolverHomedir2 } from "os";
 import { join as pathsResolverJoin2 } from "path";
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import { existsSync as existsSync52, readdirSync as readdirSync3, readFileSync as readFileSync42, statSync as statSync3 } from "fs";
 import { join as join52, sep as sep2 } from "path";
 import { basename as basename2, isAbsolute as isAbsolute22, resolve as resolve22 } from "path";
 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";
 import { dirname as dirname32, isAbsolute as isAbsolute3, join as join72, resolve as resolve32 } from "path";
 import { lstatSync as lstatSync3, readFileSync as readFileSync6, opendirSync } from "fs";
 import { createHash as createHash22 } from "crypto";
@@ -3194,7 +3207,7 @@ import { dirname as dirname42, isAbsolute as isAbsolute4, join as join82, resolv
 import { createHash as createHash32 } from "crypto";
 import { closeSync as closeSync3, constants as constants2, fstatSync as fstatSync2, lstatSync as lstatSync5, openSync as openSync3, readSync } from "fs";
 import { dirname as dirname5, isAbsolute as isAbsolute5, resolve as resolve5 } from "path";
-import { createHash as createHash4 } from "crypto";
+import { createHash as createHash42 } from "crypto";
 import { lstatSync as lstatSync6, readlinkSync } from "fs";
 import { dirname as dirname6, isAbsolute as isAbsolute6, join as join9, parse, resolve as resolve6, sep as sep22 } from "path";
 import { closeSync as closeSync12, constants as constants9, fstatSync as fstatSync12, lstatSync as lstatSync17, openSync as openSync12, opendirSync as opendirSync5, readSync as readSync8 } from "fs";
@@ -10322,7 +10335,7 @@ function* bundleHashParts(files) {
   yield new TextEncoder().encode("\x00");
 }
 function hashBundleFiles(files) {
-  const hash = createHash3(CONTENT_HASH_ALGORITHM);
+  const hash = createHash4(CONTENT_HASH_ALGORITHM);
   for (const part of bundleHashParts(files))
     hash.update(part);
   return hash.digest("hex");
@@ -10666,8 +10679,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) && isAbsolute22(source.path) && resolve22(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) && isAbsolute22(source.path) && resolve22(source.path) === source.path && basename2(source.path) === "known_marketplaces.json");
@@ -11158,11 +11171,11 @@ function hashDiscoveryPathFile(path, budget, changes) {
   const after = trace(path);
   if (JSON.stringify(before.rows) !== JSON.stringify(after.rows) || before.file !== after.file)
     throw new Error("Discovery path input changed during read");
-  return createHash4("sha256").update(JSON.stringify({ version: 1, path, rows: before.rows, content })).digest("hex");
+  return createHash42("sha256").update(JSON.stringify({ version: 1, path, rows: before.rows, content })).digest("hex");
 }
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.14",
+  version: "0.9.17",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -12017,7 +12030,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;
@@ -12030,7 +12043,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");
@@ -12041,7 +12054,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");
@@ -12079,6 +12092,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 sha = (data) => createHash10("sha256").update(data).digest("hex");
 var ROOTS = NATIVE_SKILL_ROOTS;
 function assertSafePath(path) {
@@ -12532,6 +12555,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 ?? []) {
@@ -13545,13 +13570,17 @@ function unchanged2(before) {
   const after = snapshot(before.file, before.privateFile, before.readOnlyPackage ? { readOnlyPackage: true } : {});
   need4(sameStat(before.stat, after.stat) && after.sha256 === before.sha256, "INPUT_CHANGED");
 }
-var sha2 = (text2) => createHash15("sha256").update(text2).digest("hex");
+var events = { UserPromptSubmit: ["userPromptSubmit", "user_prompt_submit"], SessionStart: ["sessionStart", "session_start"], SubagentStart: ["subagentStart", "subagent_start"] };
+var matchedEvents = { ...events, PreToolUse: ["preToolUse", "pre_tool_use"] };
 var proofs = new WeakMap;
+var sha2 = (text2) => createHash15("sha256").update(text2).digest("hex");
+var proofs2 = new WeakMap;
 function assertCodexHookDiscoveryRecovery(binding, witness) {
-  const proof = proofs.get(witness);
+  const proof = proofs2.get(witness);
   need4(!!proof && binding.agent === "codex" && witness.discoverySha256 === sha2(JSON.stringify(binding)), "RECONCILE_DISCOVERY_RECOVERY_CHANGED");
   unchanged2(proof.before);
   unchanged2(proof.current);
+  proof.recheckAdditions();
 }
 function verifiesCodexHookDiscoverySource(binding, source, currentDigest, witness) {
   if (!witness || source.path !== witness.configPath || source.hashMode !== "bytes")
@@ -13593,13 +13622,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 current2 = (source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget).sha256;
+    const current2 = (source.hashMode === "claude-settings-v3" ? captureClaudeSettingsV3 : source.hashMode === "claude-settings-v2" ? captureClaudeSettingsV2 : captureClaudeSettings)(source.path, budget).sha256;
     if (current2 !== 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) : current2;
+    return changes?.has(source.path) ? (source.hashMode === "claude-settings-v3" ? hashClaudeSettingsReplacementV3 : source.hashMode === "claude-settings-v2" ? hashClaudeSettingsReplacementV2 : hashClaudeSettingsReplacement)(changes.get(source.path), budget) : current2;
   }
   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))
@@ -13661,7 +13690,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");
@@ -13670,7 +13699,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 = resolve14, reviewed) {
@@ -13782,6 +13814,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);
@@ -13792,7 +13837,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");
@@ -34302,8 +34347,8 @@ var SESSION_RECONCILIATION_PLAN_TTL_MS = 5 * 60 * 1000;
 // src/lib/claude-skills-coordination.ts
 function coordinateClaudeSettings(before, replacement, options) {
   const prior = JSON.parse(before ?? "{}"), next = JSON.parse(replacement);
-  const events = new Set([...Object.keys(prior.hooks ?? {}), ...Object.keys(next.hooks ?? {})]);
-  const changed = [...events].filter((event) => JSON.stringify(prior.hooks?.[event]) !== JSON.stringify(next.hooks?.[event]));
+  const events2 = new Set([...Object.keys(prior.hooks ?? {}), ...Object.keys(next.hooks ?? {})]);
+  const changed = [...events2].filter((event) => JSON.stringify(prior.hooks?.[event]) !== JSON.stringify(next.hooks?.[event]));
   const selected = changed.length ? changed : ["PreToolUse"];
   const plan = planClaudeHookEventsUpdate({
     ...options,
@@ -34389,9 +34434,9 @@ function getTargetSettingsDir(target) {
 }
 function getGlobalSettingsPathOverride(target) {
   if (target === "codex")
-    return process.env.HASNA_HOOKS_CODEX_SETTINGS_PATH;
+    return process.env.HASNA_HOOKS_CODEX_SETTINGS_PATH ?? (process.env.CODEX_HOME ? resolve7(process.env.CODEX_HOME, "hooks.json") : undefined);
   if (target === "claude")
-    return process.env.HASNA_HOOKS_CLAUDE_SETTINGS_PATH;
+    return process.env.HASNA_HOOKS_CLAUDE_SETTINGS_PATH ?? (process.env.CLAUDE_CONFIG_DIR ? resolve7(process.env.CLAUDE_CONFIG_DIR, "settings.json") : undefined);
   if (target === "gemini")
     return process.env.HASNA_HOOKS_GEMINI_SETTINGS_PATH;
   return;
@@ -34435,7 +34480,7 @@ function readSettings2(scope = "global", target = "claude") {
       return value;
     }
   } catch (error61) {
-    console.warn(`[hooks] Failed to read settings at ${path}: ${error61 instanceof Error ? error61.message : String(error61)}`);
+    console.warn("[hooks] Cannot read hook settings; repair the selected file before installation.");
   }
   const empty = {};
   if (!existsSync10(path))
@@ -34447,10 +34492,16 @@ function settingsIdentity(path) {
     return realpathSync5(path);
   return existsSync10(dirname7(path)) ? join10(realpathSync5(dirname7(path)), basename3(path)) : resolve7(path);
 }
-function writeSettings(settings, scope = "global", target = "claude") {
+function writeSettings(settings, scope = "global", target = "claude", expectedSettingsSha256) {
   const path = getSettingsPath(scope, target);
   if (target === "codex")
-    return writeCodexSettings(path, settings);
+    return writeCodexSettings(path, settings, expectedSettingsSha256);
+  const captured = settingsPreimages.get(settings);
+  if (expectedSettingsSha256 !== undefined) {
+    if (!captured || captured.path !== path)
+      throw new Error("Hook settings require a valid captured preimage.");
+    assertSettingsPreimage(captured.text, expectedSettingsSha256);
+  }
   if (target === "claude" && settingsIdentity(path) === settingsIdentity(join10(homedir5(), ".claude/settings.json"))) {
     const before = settingsPreimages.get(settings);
     if (!before || before.path !== path)
@@ -34462,6 +34513,8 @@ function writeSettings(settings, scope = "global", target = "claude") {
 `, { home: homedir5() }))
       return;
   }
+  if (expectedSettingsSha256 !== undefined)
+    return writeHookSettingsPreimage(path, settings, captured.text);
   const dir = dirname7(path);
   if (!existsSync10(dir)) {
     mkdirSync6(dir, { recursive: true });
@@ -34583,7 +34636,7 @@ function detectConflict(name, scope, target) {
   const meta3 = isNativeSafetyName(name) ? getHook(name) : resolveHookMeta(name);
   if (!meta3 || !meta3.matcher)
     return;
-  const events = new Set(getHookEvents(meta3));
+  const events2 = new Set(getHookEvents(meta3));
   const registered = getRegisteredHooksForTarget(scope, target);
   for (const existingName of registered) {
     if (existingName === name)
@@ -34591,7 +34644,7 @@ function detectConflict(name, scope, target) {
     const existing = getHook(existingName);
     if (!existing || !existing.matcher)
       continue;
-    if (!getHookEvents(existing).some((event) => events.has(event)))
+    if (!getHookEvents(existing).some((event) => events2.has(event)))
       continue;
     if (matchersOverlap(meta3.matcher.toLowerCase(), existing.matcher.toLowerCase())) {
       return `conflicts with '${existingName}' (same event ${meta3.event}, overlapping matcher '${existing.matcher}')`;
@@ -34619,7 +34672,7 @@ function detectRewriteConflict(name, scope, target, lookup = getHook) {
   }
   return;
 }
-function installForTarget(name, scope, overwrite, target, profile, codewithMode = "fragment", codewithConfigPath, mementos) {
+function installForTarget(name, scope, overwrite, target, profile, codewithMode = "fragment", codewithConfigPath, mementos, expectedSettingsSha256) {
   const shortName = shortHookName(name);
   if (isNativeSafetyName(shortName) && (profile || target === "gemini" || target === "codewith" && codewithMode === "write")) {
     return { hook: shortName, success: false, error: "Bundled native safety guards support Claude/Codex and managed Codewith fragments, without registry profiles.", target };
@@ -34686,7 +34739,7 @@ function installForTarget(name, scope, overwrite, target, profile, codewithMode
     if (rewriteConflict) {
       return { hook: shortName, success: false, error: `Refused: ${rewriteConflict}`, scope, target };
     }
-    registerHook(shortName, scope, target, profile, mementos);
+    registerHook(shortName, scope, target, profile, mementos, (settings, selectedScope, selectedTarget) => writeSettings(settings, selectedScope, selectedTarget, expectedSettingsSha256));
     return {
       hook: shortName,
       success: true,
@@ -34705,7 +34758,10 @@ function installForTarget(name, scope, overwrite, target, profile, codewithMode
   }
 }
 function installHook(name, options = {}) {
-  const { scope = "global", overwrite = false, target = "claude", profile, codewithMode = "fragment", codewithConfigPath, mementos } = options;
+  const { scope = "global", overwrite = false, target = "claude", profile, codewithMode = "fragment", codewithConfigPath, mementos, expectedSettingsSha256 } = options;
+  if (expectedSettingsSha256 !== undefined && (!/^(?:absent|[a-f0-9]{64})$/.test(expectedSettingsSha256) || !isNativeSafetyName(shortHookName(name)) || target !== "codex" && target !== "claude")) {
+    return { hook: name, success: false, target, error: "An exact settings predecessor requires a Claude or Codex native safety guard." };
+  }
   try {
     validateMementosRegistration(name, mementos);
   } catch (error61) {
@@ -34746,9 +34802,9 @@ function installHook(name, options = {}) {
     }
     return { ...claudeResult, target: "all" };
   }
-  return installForTarget(name, scope, overwrite, target, profile, codewithMode, codewithConfigPath, mementos);
+  return installForTarget(name, scope, overwrite, target, profile, codewithMode, codewithConfigPath, mementos, expectedSettingsSha256);
 }
-function registerHook(name, scope = "global", target = "claude", profile, mementos) {
+function registerHook(name, scope = "global", target = "claude", profile, mementos, write = writeSettings) {
   const meta3 = isNativeSafetyName(name) ? getHook(name) : resolveHookMeta(name);
   if (!meta3)
     return;
@@ -34777,7 +34833,7 @@ function registerHook(name, scope = "global", target = "claude", profile, mement
   }
   const retained = name === "mementos-context" && mementos === undefined ? retainedMementosRegistration(Object.values(settings.hooks).flatMap((groups) => Array.isArray(groups) ? groups.flatMap((group) => Array.isArray(group.hooks) ? group.hooks.map((hook) => hook.command).filter((command) => typeof command === "string") : []) : [])) : undefined;
   const hookCommand = isNativeSafetyName(name) ? installedNativeSafetyCommand(name) : (profile ? `hooks run ${name} --profile ${profile}` : `hooks run ${name}`) + mementosCommandSuffix(mementos ?? retained);
-  if (target === "codex") {
+  if (target === "codex" || target === "claude" && isNativeSafetyName(name)) {
     const positions = [];
     for (const [event, groups] of Object.entries(settings.hooks)) {
       for (const entry of groups) {
@@ -34803,7 +34859,7 @@ function registerHook(name, scope = "global", target = "claude", profile, mement
         if (typeof meta3.timeoutSeconds === "number" && meta3.timeoutSeconds > 0)
           entry.hooks[index].timeout = meta3.timeoutSeconds;
       }
-      writeSettings(settings, scope, target);
+      write(settings, scope, target);
       return;
     }
   }
@@ -34823,7 +34879,7 @@ function registerHook(name, scope = "global", target = "claude", profile, mement
     }
     settings.hooks[eventKey].push(entry);
   }
-  writeSettings(settings, scope, target);
+  write(settings, scope, target);
 }
 function removeHookFromAllEvents(settings, name) {
   if (!settings.hooks)