@hasna/hooks 0.12.3 → 0.12.4

package/dist/lib/claude-skills-coordination.d.ts

@@ -1,8 +1,30 @@
+/** A definite refusal raised before any Claude settings byte is written.
+ * `settings_unreadable` (raised by the installer's writer, also for Gemini
+ * settings): the file exists but was not read and parsed as a JSON object. */
+export declare class ClaudeSettingsRefusal extends Error {
+    readonly code: "skills_policy_unresolved" | "settings_unreadable";
+    constructor(code: "skills_policy_unresolved" | "settings_unreadable", message: string);
+}
+/** Skills is in use for the Claude settings under `home` when at least one holds:
+ *  1. the current settings text has a hook handler (`hooks.<event>[].hooks[].command`,
+ *     or a flat `hooks.<event>[].command`) matching SKILLS_HOOK_COMMAND; or
+ *  2. the Skills Claude bridge `<home>/.claude/skills/skills-cli/SKILL.md` exists,
+ *     as any file type. A lookup error other than ENOENT/ENOTDIR counts as present.
+ * Returns the evidence found; an empty list means Skills is genuinely absent. */
+export declare function claudeSkillsUsage(before: string | null, home: string): string[];
+/** Every location the bundled Skills package (@hasna/skills 0.10.28, `getDataRoot`)
+ * considers for `agent-policy.json`, in its resolution order, with the outcome
+ * at each. Only called after Skills found no policy at the selected location. */
+export declare function skillsPolicyLocations(dataDir?: string): string[];
 /** The owning Skills writer commits Claude settings and discovery together.
- * A missing policy permits ordinary standalone installation. Any other refusal
- * propagates before settings are written; it never selects a fallback writer.
+ * A missing policy permits ordinary standalone installation only while Skills is
+ * genuinely absent (`claudeSkillsUsage`). When Skills is in use but its policy
+ * cannot be resolved, it refuses with `skills_policy_unresolved` and writes
+ * nothing. Any other refusal propagates before settings are written; it never
+ * selects a fallback writer. `beforeWrite` runs once, immediately before the
+ * coordinated write starts.
  */
 export declare function coordinateClaudeSettings(before: string | null, replacement: string, options: {
     home: string;
     dataDir?: string;
-}): boolean;
+}, beforeWrite?: () => void): boolean;

package/dist/lib/codex-safety-trust.d.ts

@@ -1,9 +1,16 @@
 import { connectCodexSafety, type CodexSafetyOptions } from "./codex-safety-check.js";
 import { verifyNativeSafetyCommand } from "../native-safety.js";
 export declare class CodexTrustError extends Error {
-    readonly code: "input_invalid" | "native_changed" | "native_config_invalid" | "preimage_unsafe" | "trust_outcome_uncertain";
+    readonly code: "input_invalid" | "native_changed" | "native_config_invalid" | "preimage_unsafe" | "trust_refused" | "trust_outcome_uncertain";
     readonly operationId?: string | undefined;
-    constructor(code: "input_invalid" | "native_changed" | "native_config_invalid" | "preimage_unsafe" | "trust_outcome_uncertain", operationId?: string | undefined);
+    readonly refusal?: {
+        code: string;
+        message: string;
+    } | undefined;
+    constructor(code: "input_invalid" | "native_changed" | "native_config_invalid" | "preimage_unsafe" | "trust_refused" | "trust_outcome_uncertain", operationId?: string | undefined, refusal?: {
+        code: string;
+        message: string;
+    } | undefined);
 }
 interface Dependencies {
     connect?: typeof connectCodexSafety;

package/dist/lib/codex-settings.d.ts

@@ -2,6 +2,9 @@ export declare function readCodexSettings(path: string): Record<string, any>;
 /** Preserve the exact read version. Never write trust state or config.toml. */
 export declare function capturedCodexSettings(settings: Record<string, any>): string | null;
 export declare function assertSettingsPreimage(raw: string | null, expected?: string): void;
-export declare function writeCodexSettings(path: string, settings: Record<string, any>, expectedSha256?: string): void;
-/** Shared standalone writer. Managed Claude settings still use Skills. */
-export declare function writeHookSettingsPreimage(path: string, settings: Record<string, any>, before: string | null): void;
+export declare function writeCodexSettings(path: string, settings: Record<string, any>, expectedSha256?: string, beforeWrite?: () => void): void;
+/** Shared standalone writer. Managed Claude settings still use Skills.
+ * `beforeWrite` runs once, after every predecessor check and immediately before
+ * the replacement is renamed over `path`; a failure before it is a definite
+ * refusal that left `path` unchanged. */
+export declare function writeHookSettingsPreimage(path: string, settings: Record<string, any>, before: string | null, beforeWrite?: () => void): void;

package/dist/lib/installer.d.ts

@@ -28,6 +28,8 @@ export interface InstallResult {
     applied?: boolean;
     note?: string;
     configPath?: string;
+    /** Stable refusal code, when the failure carries one (e.g. skills_policy_unresolved). */
+    code?: string;
 }
 export interface InstallOptions {
     /** Optional exact predecessor for a planned native safety registration. */
@@ -46,6 +48,12 @@ export interface InstallOptions {
     codewithMode?: CodewithInstallMode;
     /** Explicit Codewith config path for the direct-write mode and tests. */
     codewithConfigPath?: string;
+    /**
+     * Single JSON-settings target only: runs once, immediately before the
+     * selected writer may change the settings file. A failure reported before it
+     * runs is a definite refusal that left the settings unchanged.
+     */
+    beforeWrite?: () => void;
 }
 export declare function getSettingsPath(scope?: Scope, target?: SingleTarget, codewithConfigPath?: string): string;
 export declare function getHookPath(name: string): string;
@@ -80,7 +88,7 @@ export declare function previewNativeReadinessRegistration(target: "codex" | "cl
     after: string;
     command: string;
 };
-export declare function installNativeReadinessRegistration(target: "codex" | "claude", expectedSettingsSha256: string): {
+export declare function installNativeReadinessRegistration(target: "codex" | "claude", expectedSettingsSha256: string, beforeWrite?: () => void): {
     success: boolean;
 };
 export declare function installHooks(names: string[], options?: InstallOptions): InstallResult[];

package/dist/lib/native-safety-registration.d.ts

@@ -1,8 +1,14 @@
 import { verifyNativeSafetyCommand } from "../native-safety.js";
+/** The definite cause of an apply that stopped before its writer could change the target. */
+export interface RegistrationRefusal {
+    code: string;
+    message: string;
+}
 export declare class NativeRegistrationError extends Error {
-    readonly code: "input_invalid" | "settings_unsafe" | "settings_invalid" | "settings_changed" | "hooks_disabled" | "registration_conflict" | "guard_failed" | "apply_outcome_uncertain";
+    readonly code: "input_invalid" | "settings_unsafe" | "settings_invalid" | "settings_changed" | "hooks_disabled" | "registration_conflict" | "guard_failed" | "apply_refused" | "apply_outcome_uncertain";
     readonly operationId?: string | undefined;
-    constructor(code: "input_invalid" | "settings_unsafe" | "settings_invalid" | "settings_changed" | "hooks_disabled" | "registration_conflict" | "guard_failed" | "apply_outcome_uncertain", operationId?: string | undefined);
+    readonly refusal?: RegistrationRefusal | undefined;
+    constructor(code: "input_invalid" | "settings_unsafe" | "settings_invalid" | "settings_changed" | "hooks_disabled" | "registration_conflict" | "guard_failed" | "apply_refused" | "apply_outcome_uncertain", operationId?: string | undefined, refusal?: RegistrationRefusal | undefined);
 }
 export interface NativeRegistrationOptions {
     target: "codex" | "claude";

package/dist/native-safety.d.ts

@@ -55,11 +55,14 @@ export declare function readNativeSafetyRegistration(home?: string): {
 export declare function nativeSafetyBindingIntegrityReason(home?: string): string | undefined;
 /** Register only the bundled composite guard. Updates preserve the exact prior
  * record and require its digest. A lock coordinates package-owned writers; an
- * unexpected preimage or a retained interrupted lock requires reconciliation. */
+ * unexpected preimage or a retained interrupted lock requires reconciliation.
+ * `beforeWrite` runs once, after the last predecessor check and immediately
+ * before the record is replaced; a failure before it left the record unchanged. */
 export declare function registerNativeSafety(options?: {
     home?: string;
     expectedSHA256?: string;
     command?: string;
+    beforeWrite?: () => void;
 }): {
     ok: true;
     changed: boolean;

package/dist/native-safety.js

@@ -301,8 +301,10 @@ function registerNativeSafety(options = {}) {
     if (before) {
       if (hash(readOwned(path)) !== before.sha256)
         throw new NativeSafetyError("binding_changed");
+      options.beforeWrite?.();
       renameSync(temporary, path);
     } else {
+      options.beforeWrite?.();
       linkSync(temporary, path);
       unlinkSync(temporary);
     }

package/hooks/codewith-native-common.ts

@@ -1,6 +1,6 @@
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, writeSync } from "fs";
-import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "path";
-import { homedir, tmpdir } from "os";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, writeSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { homedir, tmpdir } from "node:os";
 
 export interface CodewithHookInput {
   session_id?: string;

package/hooks/hook-signed-link-guard/src/hook.ts

@@ -66,7 +66,10 @@ export async function run(): Promise<void> {
   if (!("continue" in verdict && verdict.continue === true)) respond(verdict);
 }
 
+// Standalone run only. No top-level await: the CommonJS native safety worker
+// (scripts/build-native-worker.ts) bundles this module, and its parser refuses
+// top-level await even where import.meta.main=false makes the block dead.
+// A rejected run still exits non-zero, as an awaited one did.
 if (import.meta.main) {
-  await run();
-  process.exit(0);
+  void run().then(() => process.exit(0));
 }

package/hooks/hook-trash-guard/src/hook.ts

@@ -46,8 +46,8 @@
  * command that contains a delete-verb word and stays silent otherwise.
  */
 
-import { homedir } from "os";
-import { isAbsolute, join, normalize, resolve, sep } from "path";
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize, resolve, sep } from "node:path";
 import { BINARY_FAILURES, findTrashBinary, inspectTrashBinary, type TrashBinaryInspection } from "./binary.js";
 export { findTrashBinary, inspectTrashBinary } from "./binary.js";
 import {
@@ -1297,7 +1297,10 @@ export async function run(): Promise<void> {
   }
 }
 
+// Standalone run only. No top-level await: the CommonJS native safety worker
+// (scripts/build-native-worker.ts) bundles this module, and its parser refuses
+// top-level await even where import.meta.main=false makes the block dead.
+// A rejected run still exits non-zero, as an awaited one did.
 if (import.meta.main) {
-  await run();
-  process.exit(0);
+  void run().then(() => process.exit(0));
 }

package/hooks/hook-workspace-repos-guard/src/hook.ts

@@ -51,9 +51,9 @@
  * or evaluation error so a guard defect cannot wedge the agent.
  */
 
-import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, statSync } from "fs";
-import { homedir } from "os";
-import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "path";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import {
   commandWordIndex,
   decodeWord,
@@ -1213,7 +1213,10 @@ export async function run(): Promise<void> {
   }
 }
 
+// Standalone run only. No top-level await: the CommonJS native safety worker
+// (scripts/build-native-worker.ts) bundles this module, and its parser refuses
+// top-level await even where import.meta.main=false makes the block dead.
+// A rejected run still exits non-zero, as an awaited one did.
 if (import.meta.main) {
-  await run();
-  process.exit(0);
+  void run().then(() => process.exit(0));
 }

package/hooks/native-safety-composite.ts

@@ -0,0 +1,75 @@
+import { homedir } from "node:os";
+import { isAbsolute } from "node:path";
+import { evaluate as evaluateTrash, findTrashBinary, inspectTrashBinary, scanCommand } from "./hook-trash-guard/src/hook";
+import { evaluate as evaluateRepos } from "./hook-workspace-repos-guard/src/hook";
+import { evaluate as evaluateSignedLinks } from "./hook-signed-link-guard/src/hook";
+import type { CodewithHookInput, CodewithHookOutput } from "./codewith-native-common";
+
+// The native safety composite: trash-guard, workspace-repos-guard and
+// signed-link-guard judged together for one capability name. Both the v1 entry
+// (hooks/native-safety-entry.ts) and the v2 worker (hooks/native-safety-worker.ts)
+// call it, so one guard decision has one implementation. It reads no stdin,
+// writes no stdout and never exits: the caller owns the process.
+
+export type NativeSafetyCompositeGuard = "trash-guard" | "workspace-repos-guard";
+
+/** Refuses an unknown capability name exactly as the v1 entry always has. */
+export function assertCompositeGuard(guard: unknown): asserts guard is NativeSafetyCompositeGuard {
+  if (guard !== "trash-guard" && guard !== "workspace-repos-guard") throw new Error("Invalid safety capability");
+}
+
+/**
+ * Judge one PreToolUse input for `guard`. Returns the exact text the v1 entry
+ * writes to stdout (`{"verdict":null}` or `{"verdict":{hookSpecificOutput}}`),
+ * and throws where the v1 entry exits non-zero.
+ */
+export function evaluateComposite(guard: string, inputText: string): string {
+  assertCompositeGuard(guard);
+  const name = guard;
+  const input = JSON.parse(inputText) as CodewithHookInput;
+  if (!input || Array.isArray(input) || input.hook_event_name !== "PreToolUse" || typeof input.tool_name !== "string"
+    || !input.tool_input || typeof input.tool_input !== "object" || Array.isArray(input.tool_input)
+    || typeof input.cwd !== "string" || !isAbsolute(input.cwd)) throw new Error("Invalid safety input");
+  if (input.tool_name === "Bash" && typeof input.tool_input.command !== "string") throw new Error("Invalid shell input");
+  // Claude Code's Monitor runs a shell command and streams its stdout to the
+  // model; a websocket Monitor carries `ws` and no command.
+  if (input.tool_name === "Monitor" && input.tool_input.command !== undefined && typeof input.tool_input.command !== "string") throw new Error("Invalid monitor input");
+  const requestedExecution = (input as CodewithHookInput & { hasna_execution?: { schema: string; agent: string } }).hasna_execution;
+  if (requestedExecution !== undefined && (!requestedExecution || Object.keys(requestedExecution).sort().join() !== "agent,schema"
+    || requestedExecution.schema !== "hasna.hooks.execution.v1" || typeof requestedExecution.agent !== "string"
+    || !/^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/.test(requestedExecution.agent))) throw new Error("Invalid execution capability");
+  const execution = requestedExecution === undefined ? undefined : {
+    runtime: process.execPath, home: homedir(), path: process.env.PATH!, agent: requestedExecution.agent,
+  };
+  if (execution && (!isAbsolute(execution.runtime) || !execution.path)) throw new Error("Invalid bound execution context");
+  if (["apply_patch", "ApplyPatch", "functions.apply_patch"].includes(input.tool_name)) {
+    if (input.tool_input.command !== undefined && input.tool_input.patch !== undefined && input.tool_input.command !== input.tool_input.patch) throw new Error("Conflicting patch aliases");
+    const patch = input.tool_input.command ?? input.tool_input.patch;
+    if (typeof patch !== "string") throw new Error("Invalid patch input");
+    input.tool_input = { ...input.tool_input, command: patch, patch };
+  }
+  // Every guard judges a Monitor command exactly as it judges the same Bash command.
+  const monitor = input.tool_name === "Monitor";
+  const shellCommand = input.tool_name === "Bash" || (monitor && typeof input.tool_input.command === "string");
+  const evaluated: CodewithHookInput = monitor && shellCommand ? { ...input, tool_name: "Bash" } : input;
+  const deny = (reason: string) => ({ hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "deny" as const, permissionDecisionReason: reason } });
+  const repos = evaluateRepos(evaluated).output;
+  // Every shell command, whatever the capability name: the guard reaches each
+  // registration of this entry. Its refusal outranks a Trash rewrite, because an
+  // allowed rewrite would also run the composite gh read.
+  const signedLinks = evaluateSignedLinks(evaluated);
+  const handoff = shellCommand && scanCommand(evaluated.tool_input!.command as string, { home: homedir(), cwd: input.cwd }).handoffHits.length > 0;
+  let trash: CodewithHookOutput = name === "trash-guard" && (!monitor || shellCommand)
+    ? evaluateTrash(evaluated, { home: homedir(), cwd: input.cwd, findTrash: findTrashBinary, inspectTrash: inspectTrashBinary, execution }) : { continue: true };
+  // A Trash rewrite is proven only for Bash. Under Monitor the deletion is
+  // refused rather than rewritten: a rewrite the harness dropped would run the
+  // raw command.
+  if (monitor && trash.hookSpecificOutput?.permissionDecision === "allow") {
+    trash = deny("[trash-guard] A deletion inside a Monitor command is refused; run it with the Bash tool, where it is redirected into trash.");
+  }
+  const verdict: CodewithHookOutput = repos.decision === "block" ? deny(repos.reason!)
+    : signedLinks.hookSpecificOutput ? signedLinks
+    : handoff ? deny("[workspace-repos-guard] Deletion under a protected repository checkout is refused.")
+    : trash;
+  return JSON.stringify({ verdict: "continue" in verdict ? null : verdict });
+}

package/hooks/native-safety-entry.ts

@@ -1,57 +1,11 @@
-import { homedir } from "node:os";
-import { isAbsolute } from "node:path";
-import { evaluate as evaluateTrash, findTrashBinary, inspectTrashBinary, scanCommand } from "./hook-trash-guard/src/hook";
-import { evaluate as evaluateRepos } from "./hook-workspace-repos-guard/src/hook";
-import { evaluate as evaluateSignedLinks } from "./hook-signed-link-guard/src/hook";
-import type { CodewithHookInput, CodewithHookOutput } from "./codewith-native-common";
+import { assertCompositeGuard, evaluateComposite } from "./native-safety-composite";
 
+// The v1 native safety entry: a thin wrapper over the composite. Its contract is
+// fixed by the v1 supervisor (src/lib/native-safety.ts): the capability name is
+// argv[1], the hook input is stdin, the verdict is one JSON write to stdout, and
+// any failure exits non-zero.
 // Bundled with import.meta.main=false, so the original standalone run wrappers
 // cannot swallow exceptions or emit a second response. Only this entry runs.
 const name = process.argv[1];
-if (name !== "trash-guard" && name !== "workspace-repos-guard") throw new Error("Invalid safety capability");
-const input = JSON.parse(await Bun.stdin.text()) as CodewithHookInput;
-if (!input || Array.isArray(input) || input.hook_event_name !== "PreToolUse" || typeof input.tool_name !== "string"
-  || !input.tool_input || typeof input.tool_input !== "object" || Array.isArray(input.tool_input)
-  || typeof input.cwd !== "string" || !isAbsolute(input.cwd)) throw new Error("Invalid safety input");
-if (input.tool_name === "Bash" && typeof input.tool_input.command !== "string") throw new Error("Invalid shell input");
-// Claude Code's Monitor runs a shell command and streams its stdout to the
-// model; a websocket Monitor carries `ws` and no command.
-if (input.tool_name === "Monitor" && input.tool_input.command !== undefined && typeof input.tool_input.command !== "string") throw new Error("Invalid monitor input");
-const requestedExecution = (input as CodewithHookInput & { hasna_execution?: { schema: string; agent: string } }).hasna_execution;
-if (requestedExecution !== undefined && (!requestedExecution || Object.keys(requestedExecution).sort().join() !== "agent,schema"
-  || requestedExecution.schema !== "hasna.hooks.execution.v1" || typeof requestedExecution.agent !== "string"
-  || !/^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/.test(requestedExecution.agent))) throw new Error("Invalid execution capability");
-const execution = requestedExecution === undefined ? undefined : {
-  runtime: process.execPath, home: homedir(), path: process.env.PATH!, agent: requestedExecution.agent,
-};
-if (execution && (!isAbsolute(execution.runtime) || !execution.path)) throw new Error("Invalid bound execution context");
-if (["apply_patch", "ApplyPatch", "functions.apply_patch"].includes(input.tool_name)) {
-  if (input.tool_input.command !== undefined && input.tool_input.patch !== undefined && input.tool_input.command !== input.tool_input.patch) throw new Error("Conflicting patch aliases");
-  const patch = input.tool_input.command ?? input.tool_input.patch;
-  if (typeof patch !== "string") throw new Error("Invalid patch input");
-  input.tool_input = { ...input.tool_input, command: patch, patch };
-}
-// Every guard judges a Monitor command exactly as it judges the same Bash command.
-const monitor = input.tool_name === "Monitor";
-const shellCommand = input.tool_name === "Bash" || (monitor && typeof input.tool_input.command === "string");
-const evaluated: CodewithHookInput = monitor && shellCommand ? { ...input, tool_name: "Bash" } : input;
-const deny = (reason: string) => ({ hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "deny" as const, permissionDecisionReason: reason } });
-const repos = evaluateRepos(evaluated).output;
-// Every shell command, whatever the capability name: the guard reaches each
-// registration of this entry. Its refusal outranks a Trash rewrite, because an
-// allowed rewrite would also run the composite gh read.
-const signedLinks = evaluateSignedLinks(evaluated);
-const handoff = shellCommand && scanCommand(evaluated.tool_input!.command as string, { home: homedir(), cwd: input.cwd }).handoffHits.length > 0;
-let trash: CodewithHookOutput = name === "trash-guard" && (!monitor || shellCommand)
-  ? evaluateTrash(evaluated, { home: homedir(), cwd: input.cwd, findTrash: findTrashBinary, inspectTrash: inspectTrashBinary, execution }) : { continue: true };
-// A Trash rewrite is proven only for Bash. Under Monitor the deletion is
-// refused rather than rewritten: a rewrite the harness dropped would run the
-// raw command.
-if (monitor && trash.hookSpecificOutput?.permissionDecision === "allow") {
-  trash = deny("[trash-guard] A deletion inside a Monitor command is refused; run it with the Bash tool, where it is redirected into trash.");
-}
-const verdict: CodewithHookOutput = repos.decision === "block" ? deny(repos.reason!)
-  : signedLinks.hookSpecificOutput ? signedLinks
-  : handoff ? deny("[workspace-repos-guard] Deletion under a protected repository checkout is refused.")
-  : trash;
-process.stdout.write(JSON.stringify({ verdict: "continue" in verdict ? null : verdict }));
+assertCompositeGuard(name);
+process.stdout.write(evaluateComposite(name, await Bun.stdin.text()));

package/hooks/native-safety-worker.ts

@@ -0,0 +1,19 @@
+import { evaluateComposite } from "./native-safety-composite";
+
+// The native safety worker, ABI v2 (docs/adr/0001-stable-native-safety-launcher.md
+// section 3.4). scripts/build-native-worker.ts bundles it into
+// bin/native-safety-worker.cjs: CommonJS for Node's module shape, requiring only
+// node: builtins, with no top-level await and no top-level side effects. It reads
+// no stdin, writes no stdout and never exits; the loader that evaluates the
+// verified bundle owns the process.
+
+/** Replaced at build time with the package.json version; never set at run time. */
+declare const HASNA_HOOKS_NATIVE_SAFETY_WORKER_VERSION: string;
+
+export const abi = 2;
+export const version: string = HASNA_HOOKS_NATIVE_SAFETY_WORKER_VERSION;
+
+/** The v1 entry's exact stdout text for this input; throws where the v1 entry exits non-zero. */
+export function evaluate(guard: string, inputText: string): string {
+  return evaluateComposite(guard, inputText);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "rm -rf dist bin && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external pg --external ink --external react --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/serve.ts --outdir ./bin --target bun --external pg && bun build ./src/mcp/hooks-mcp.ts --outdir ./bin --target bun --external pg --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/sdk/index.ts --outdir ./dist/sdk --target bun && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun --external pg && bun run build:native-safety && bun run build:types",
+    "build": "rm -rf dist bin && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external pg --external ink --external react --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/serve.ts --outdir ./bin --target bun --external pg && bun build ./src/mcp/hooks-mcp.ts --outdir ./bin --target bun --external pg --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/sdk/index.ts --outdir ./dist/sdk --target bun && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun --external pg && bun run build:native-safety && bun run build:native-safety-worker && bun run build:types",
     "build:types": "tsc -p tsconfig.build.json",
     "generate:sdk": "bun run scripts/generate-sdk.ts",
     "verify:generated": "bun run scripts/verify-generated-artifacts.ts",
@@ -46,7 +46,8 @@
     "scan:artifact": "bun scripts/artifact-scan.ts",
     "prepack": "bun run build && bun run scan:artifact",
     "build:native-safety": "bun build ./hooks/native-safety-entry.ts --outdir ./bin --target bun --minify --define import.meta.main=false && bun build ./src/native-safety.ts --outdir ./dist --target bun && bun run build:native-readiness",
-    "build:native-readiness": "bun build ./hooks/native-readiness-entry.ts --outdir ./bin --target node --format=cjs && bun build ./src/native-readiness.ts --outdir ./dist --target bun"
+    "build:native-readiness": "bun build ./hooks/native-readiness-entry.ts --outdir ./bin --target node --format=cjs && bun build ./src/native-readiness.ts --outdir ./dist --target bun",
+    "build:native-safety-worker": "bun scripts/build-native-worker.ts"
   },
   "keywords": [
     "claude-code",
@@ -69,7 +70,7 @@
     "@hasna/contracts": "~1.2.1"
   },
   "dependencies": {
-    "@hasna/skills": "0.9.17",
+    "@hasna/skills": "0.10.28",
     "@hasna/events": "^0.1.16",
     "@hasna/secrets": "0.4.2",
     "@modelcontextprotocol/sdk": "^1.26.0",

package/scripts/build-native-worker.ts

@@ -0,0 +1,152 @@
+#!/usr/bin/env bun
+/**
+ * Build the native safety worker, ABI v2 (docs/adr/0001-stable-native-safety-launcher.md
+ * sections 3.3 and 3.4), into bin/native-safety-worker.cjs.
+ *
+ * The launcher's loader evaluates the verified bytes as a CommonJS function body,
+ * `new Function("module", "exports", "require", source)`, and passes a `require`
+ * that accepts only `node:` builtins. A bundle that needs anything else fails at
+ * every guarded call, so this build refuses it instead. Each check below fails
+ * the build, and nothing is written:
+ * - a `require(...)` whose specifier is not a literal `node:` builtin;
+ * - any `bun:` specifier, static import or export, dynamic `import()` or
+ *   `import.meta`, none of which the loader's CommonJS shape can serve;
+ * - a top-level `await` (including `for await`);
+ * - a `require` used other than as a direct call, which would hide a specifier;
+ * - the version placeholder left unreplaced by the define;
+ * - a bundle that does not compile in the loader's function shape.
+ *
+ * Usage: bun scripts/build-native-worker.ts [--outfile <path>]
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { builtinModules } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import ts from "typescript";
+
+export const WORKER_ENTRY = "hooks/native-safety-worker.ts";
+export const WORKER_OUTFILE = "bin/native-safety-worker.cjs";
+/** The identifier hooks/native-safety-worker.ts declares; the build replaces it with package.json's version. */
+export const WORKER_VERSION_DEFINE = "HASNA_HOOKS_NATIVE_SAFETY_WORKER_VERSION";
+
+const BUILTINS = new Set(builtinModules);
+
+/** Whether `specifier` is exactly `node:<builtin>`, the only form the loader's require accepts. */
+export function isNodeBuiltinSpecifier(specifier: string): boolean {
+  if (!specifier.startsWith("node:")) return false;
+  const name = specifier.slice("node:".length);
+  return /^[a-z][a-z0-9_]*(?:\/[a-z][a-z0-9_]*)*$/.test(name) && BUILTINS.has(name);
+}
+
+function literalText(node: ts.Node | undefined): string | undefined {
+  return node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) ? node.text : undefined;
+}
+
+/** Whether an identifier named `require` sits in a property-name position rather than referring to a binding. */
+function isPropertyName(node: ts.Identifier): boolean {
+  const parent = node.parent;
+  return (ts.isPropertyAccessExpression(parent) && parent.name === node)
+    || ((ts.isPropertyAssignment(parent) || ts.isMethodDeclaration(parent) || ts.isPropertyDeclaration(parent)
+      || ts.isGetAccessorDeclaration(parent) || ts.isSetAccessorDeclaration(parent)) && parent.name === node);
+}
+
+/**
+ * Every reason `source` cannot run under the v2 loader. Empty means the bundle
+ * passed. Parsed, not pattern-matched: a `require(` or `await` inside a string
+ * or a comment is data and is not reported.
+ */
+export function workerBundleProblems(source: string): string[] {
+  const problems: string[] = [];
+  const file = ts.createSourceFile("native-safety-worker.cjs", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+  const at = (node: ts.Node) => {
+    const { line, character } = file.getLineAndCharacterOfPosition(node.getStart(file));
+    return `${line + 1}:${character + 1}`;
+  };
+  const specifier = (node: ts.Node, text: string, how: string) => {
+    if (text.startsWith("bun:")) problems.push(`bun: import ${JSON.stringify(text)} via ${how} at ${at(node)}`);
+    else if (how !== "require") problems.push(`${how} of ${JSON.stringify(text)}; the loader serves only require at ${at(node)}`);
+    else if (!isNodeBuiltinSpecifier(text)) problems.push(`require of non-node: specifier ${JSON.stringify(text)} at ${at(node)}`);
+  };
+  const visit = (node: ts.Node, inFunction: boolean): void => {
+    if (!inFunction && ts.isAwaitExpression(node)) problems.push(`top-level await at ${at(node)}`);
+    if (!inFunction && ts.isForOfStatement(node) && node.awaitModifier) problems.push(`top-level for await at ${at(node)}`);
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier) {
+      specifier(node, literalText(node.moduleSpecifier) ?? "<non-literal>", ts.isImportDeclaration(node) ? "static import" : "re-export");
+    } else if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node) || ts.isExportAssignment(node)
+      || (ts.canHaveModifiers(node) && ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword))) {
+      problems.push(`ESM syntax at ${at(node)}`);
+    }
+    if (ts.isMetaProperty(node) && node.keywordToken === ts.SyntaxKind.ImportKeyword) problems.push(`import.meta at ${at(node)}`);
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+      const text = node.arguments.length === 1 ? literalText(node.arguments[0]) : undefined;
+      specifier(node, text ?? "<non-literal>", "dynamic import()");
+    }
+    if (ts.isIdentifier(node) && node.text === WORKER_VERSION_DEFINE) problems.push(`version define not applied (${WORKER_VERSION_DEFINE}) at ${at(node)}`);
+    if (ts.isIdentifier(node) && node.text === "require" && !isPropertyName(node)) {
+      const call = node.parent;
+      if (ts.isCallExpression(call) && call.expression === node) {
+        const text = call.arguments.length === 1 ? literalText(call.arguments[0]) : undefined;
+        if (text === undefined) problems.push(`require with a non-literal specifier at ${at(call)}`);
+        else specifier(call, text, "require");
+      } else {
+        problems.push(`require used other than as a direct call at ${at(node)}`);
+      }
+    }
+    const scope = inFunction || ts.isFunctionLike(node) || ts.isClassStaticBlockDeclaration(node);
+    ts.forEachChild(node, (child) => visit(child, scope));
+  };
+  visit(file, false);
+  try {
+    // Compile, never call: the loader's exact CommonJS function shape.
+    new Function("module", "exports", "require", source);
+  } catch (error) {
+    problems.push(`does not compile as the loader's CommonJS function body: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return problems;
+}
+
+export interface NativeSafetyWorkerBuild { outfile: string; bytes: number; sha256: string; version: string }
+
+/** Bundle, check and write the worker. Writes nothing when a check fails. */
+export async function buildNativeSafetyWorker(options: { packageDir?: string; outfile?: string } = {}): Promise<NativeSafetyWorkerBuild> {
+  const packageDir = resolve(options.packageDir ?? join(import.meta.dir, ".."));
+  const outfile = resolve(packageDir, options.outfile ?? WORKER_OUTFILE);
+  const version: unknown = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8")).version;
+  if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) throw new Error("package.json has no valid version for the native safety worker");
+  const result = await Bun.build({
+    entrypoints: [join(packageDir, WORKER_ENTRY)],
+    target: "node",
+    format: "cjs",
+    minify: true,
+    define: { "import.meta.main": "false", [WORKER_VERSION_DEFINE]: JSON.stringify(version) },
+    // Report the bundler's own messages (a parse error such as a top-level
+    // await in CommonJS) instead of a bare "Bundle failed".
+    throw: false,
+  });
+  if (!result.success) throw new Error(`native safety worker build failed:\n${result.logs.map(String).join("\n")}`);
+  if (result.outputs.length !== 1) throw new Error(`native safety worker build produced ${result.outputs.length} outputs, expected 1`);
+  const source = await result.outputs[0]!.text();
+  const problems = workerBundleProblems(source);
+  if (problems.length > 0) throw new Error(`native safety worker bundle refused:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`);
+  mkdirSync(dirname(outfile), { recursive: true });
+  // A new file is never group- or world-writable, whatever the umask: the launcher's pin check refuses such a worker.
+  writeFileSync(outfile, source, { mode: 0o644 });
+  return { outfile, bytes: Buffer.byteLength(source), sha256: createHash("sha256").update(source).digest("hex"), version };
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  let outfile: string | undefined;
+  if (args.length === 2 && args[0] === "--outfile" && args[1]) outfile = resolve(args[1]);
+  else if (args.length !== 0) {
+    console.error("usage: bun scripts/build-native-worker.ts [--outfile <path>]");
+    process.exit(2);
+  }
+  try {
+    const built = await buildNativeSafetyWorker({ outfile });
+    console.log(`native-safety-worker.cjs ${built.version}: ${built.bytes} bytes, sha256 ${built.sha256} -> ${built.outfile}`);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}