@hasna/hooks 0.10.5 → 0.10.7

package/README.md

@@ -92,6 +92,79 @@ 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
+hooks safety verify --target codex --cwd /path/to/project --codex-command /absolute/path/to/native/codex
+```
+
+This bounded, read-only check starts its own fresh Codex app-server and asks the
+native consumer for the selected project's hook definitions and feature state.
+It requires exactly one enabled, trusted, synchronous bundled Trash guard, checks
+its installed supervisor by classifying data, and verifies that the native
+definition stayed unchanged. It returns compact JSON and a nonzero exit on
+missing, disabled, untrusted, changed or unsafe state. No deletion is executed.
+
+The command accepts a native Linux ELF or macOS Mach-O executable for the host
+architecture (arm64 or x64); script launchers are refused before execution. When
+Codex is installed through npm, pass the platform package's native binary rather
+than its JavaScript launcher. Executable ownership, permissions, ancestry and
+bytes are checked. Supported protocol versions are 0.153.0, 0.154.0, 0.155.0,
+0.155.1 and 0.156.1; other versions refuse pending compatibility validation.
+The version probe has a five-second forced timeout and native discovery a
+fifteen-second lifetime budget. Neither step restarts an existing agent.
+
+Success reports `nativeDiscoveryVerified: true`, `guardVerified: true` and
+`nativeAdoptionVerified: false`. It does not enroll trust, change configuration,
+authenticate Trash, verify MCP or Instructions, or prove interception by an
+already-running session. Complete those separate setup checks and a fresh native
+interception proof before declaring station support. Use this small readiness
+check after installation, meaningful upgrades and during fresh-agent startup;
+never substitute repeated deletion smoke tests for a startup check.
+
 ## Optional Mementos prompt context
 
 `hooks install mementos-context --target codex` registers a native prompt hook.

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);
@@ -3179,7 +3191,7 @@ 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";
@@ -3194,7 +3206,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 +10334,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");
@@ -11158,7 +11170,7 @@ 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",
@@ -34389,9 +34401,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 +34447,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 +34459,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 +34480,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 });
@@ -34619,7 +34639,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 +34706,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 +34725,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 +34769,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 +34800,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 +34826,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 +34846,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)