@hasna/hooks 0.12.2 → 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-check.d.ts

@@ -1,7 +1,7 @@
 import { verifyNativeSafetyCommand } from "../native-safety.js";
 /** Exact `codex --version` outputs whose app-server protocol was measured
  * against the real native binary. Anything else refuses as native_unsupported. */
-export declare const SUPPORTED_CODEX_SAFETY_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.154.0-alpha.6.1", "codex-cli 0.155.0", "codex-cli 0.155.1", "codex-cli 0.156.1", "codex-cli 0.157.0", "codex-cli 0.157.1", "codex-cli 0.158.0", "codex-cli 0.159.0", "codex-cli 0.159.2", "codex-cli 0.159.3"];
+export declare const SUPPORTED_CODEX_SAFETY_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.154.0-alpha.6.1", "codex-cli 0.155.0", "codex-cli 0.155.1", "codex-cli 0.156.1", "codex-cli 0.157.0", "codex-cli 0.157.1", "codex-cli 0.158.0", "codex-cli 0.159.0", "codex-cli 0.159.2", "codex-cli 0.159.3", "codex-cli 0.160.0"];
 export type CodexSafetyCode = "native_unavailable" | "native_unsafe_executable" | "native_executable_required" | "native_unsupported" | "native_failed" | "native_discovery_failed" | "hooks_disabled" | "guard_missing" | "guard_ambiguous" | "guard_definition_invalid" | "guard_disabled" | "guard_untrusted" | "guard_changed" | "guard_failed";
 export declare class CodexSafetyError extends Error {
     readonly code: CodexSafetyCode;

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/README.md

@@ -61,6 +61,26 @@ other than `$HOME`, `$( )`, backticks, a glob) fails closed to the directory
 the command runs in, so `rm -rf "$TMPDIR/x"` run from a protected checkout is
 refused. Use a literal absolute path for deletes outside the roots.
 
+A here-document body is data, not commands, when nothing in the command can
+run it: its delimiter is quoted (or it holds no `$( )` or backticks), and
+every command word of the command, including those in command substitutions
+at any depth and inside double quotes, is a command that never runs its input
+or arguments as code (`cat`, `tee`,
+`head`, `grep`, `jq`, `echo`, `cd`, `mkdir`, `cp`, `mv`, `rm`, `trash`, the
+Hasna record CLIs such as `todos` and `conversations`, `git` with a data
+subcommand such as `commit` and no `-c`, and `gh pr|issue|api|release|gist`).
+No command word may be a path, an expansion, or the bare name of a file the
+command writes, and the command may hold no variable assignment, process
+substitution, or shell, interpreter or runner word (`bash`, `python3`,
+`ssh`, `sudo`, `xargs`, `chmod`, ...). Any other command word (`rbash`,
+`newgrp`, `tclsh8.6`, an unknown tool) keeps the line-by-line analysis,
+because a list of runners can never be complete. A `<<` inside `${...}` or
+`$[...]` is not taken for a here-document. Such a body is analysed on
+its own, away from the session cwd: a protected path it names, or reaches
+with its own `cd`, still counts, but a word in it (`rm`, `>`, a trailing name)
+is never resolved against the cwd, and its `cd` never moves the outer shell.
+Every other body keeps the line-by-line analysis.
+
 ## Configuration
 
 Allowed orgs default to `hasna,hasnaxyz,hasna-products`. Private workspace