@hasna/hooks 0.12.7 → 0.12.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -13,7 +13,7 @@ export declare class ClaudeSettingsRefusal extends Error {
13
13
  * as any file type. A lookup error other than ENOENT/ENOTDIR counts as present.
14
14
  * Returns the evidence found; an empty list means Skills is genuinely absent. */
15
15
  export declare function claudeSkillsUsage(before: string | null, home: string): string[];
16
- /** Every location the bundled Skills package (@hasna/skills 0.10.47, `getDataRoot`)
16
+ /** Every location the bundled Skills package (@hasna/skills 0.10.53, `getDataRoot`)
17
17
  * considers for `agent-policy.json`, in its resolution order, with the outcome
18
18
  * at each. Only called after Skills found no policy at the selected location. */
19
19
  export declare function skillsPolicyLocations(dataDir?: string): string[];
@@ -1,7 +1,8 @@
1
+ import { type NativeSafetyName } from "./native-safety.js";
1
2
  import { verifyNativeSafetyCommand } from "../native-safety.js";
2
3
  /** Exact `codex --version` outputs whose app-server protocol was measured
3
4
  * against the real native binary. Anything else refuses as native_unsupported. */
4
- 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", "codex-cli 0.160.1"];
5
+ 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", "codex-cli 0.160.1", "codex-cli 0.161.0"];
5
6
  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";
6
7
  export declare class CodexSafetyError extends Error {
7
8
  readonly code: CodexSafetyCode;
@@ -30,12 +31,15 @@ type NativeGuard = {
30
31
  trustStatus: string;
31
32
  };
32
33
  /** Select only the exact packaged composite definition in native discovery.
33
- * A name, a settings file, or a trusted hash by itself is not enough. */
34
- export declare function selectCodexSafety(discovery: unknown, configuration: unknown, home: string, cwd: string, featureEnabled?: boolean, requireReady?: boolean, readiness?: boolean): NativeGuard;
34
+ * A name, a settings file, or a trusted hash by itself is not enough. `guard`
35
+ * selects which bundled guard's definition (default trash-guard); every other
36
+ * hook, the other guard's included, is only checked for well-formedness. */
37
+ export declare function selectCodexSafety(discovery: unknown, configuration: unknown, home: string, cwd: string, featureEnabled?: boolean, requireReady?: boolean, readiness?: boolean, guard?: NativeSafetyName): NativeGuard;
35
38
  export declare function readCodexSafety(rpc: CodexSafetyRpc, home: string, cwd: string, options?: {
36
39
  includeLayers?: boolean;
37
40
  requireReady?: boolean;
38
41
  readiness?: boolean;
42
+ guard?: NativeSafetyName;
39
43
  }): Promise<{
40
44
  guard: NativeGuard;
41
45
  discovery: unknown;
@@ -1,5 +1,6 @@
1
1
  import { connectCodexSafety, type CodexSafetyOptions } from "./codex-safety-check.js";
2
2
  import { verifyNativeSafetyCommand } from "../native-safety.js";
3
+ import { type NativeSafetyName } from "./native-safety.js";
3
4
  export declare class CodexTrustError extends Error {
4
5
  readonly code: "input_invalid" | "native_changed" | "native_config_invalid" | "preimage_unsafe" | "trust_refused" | "trust_outcome_uncertain";
5
6
  readonly operationId?: string | undefined;
@@ -16,6 +17,11 @@ interface Dependencies {
16
17
  connect?: typeof connectCodexSafety;
17
18
  verify?: typeof verifyNativeSafetyCommand;
18
19
  }
20
+ /** `guard` selects the bundled native safety guard to trust (default
21
+ * trash-guard). Only `hooks.state[<that guard's key>]` is written. */
22
+ export type CodexSafetyTrustOptions = CodexSafetyOptions & {
23
+ guard?: NativeSafetyName;
24
+ };
19
25
  export interface CodexTrustPlan {
20
26
  schema: "hasna.hooks.codex-safety-trust/v1" | "hasna.hooks.codex-readiness-trust/v1";
21
27
  planDigest: string;
@@ -26,24 +32,29 @@ export interface CodexTrustPlan {
26
32
  configPath: string;
27
33
  configVersion: string;
28
34
  action: "unchanged" | "trust_and_enable";
35
+ /** Present only for a guard other than trash-guard, whose plans and digests
36
+ * keep their earlier exact shape. Either way the digest binds the guard: by
37
+ * this field, and by the discovered definition it covers, whose command names it. */
38
+ guard?: Exclude<NativeSafetyName, "trash-guard">;
29
39
  guardVerified: boolean;
30
40
  readinessRunnerVerified?: true;
31
41
  nativeAdoptionVerified: false;
32
42
  }
33
- export declare const planCodexSafetyTrust: (options?: CodexSafetyOptions, dependencies?: Dependencies) => Promise<CodexTrustPlan>;
34
- export declare const applyCodexSafetyTrust: (options: CodexSafetyOptions & {
43
+ export declare const planCodexSafetyTrust: (options?: CodexSafetyTrustOptions, dependencies?: Dependencies) => Promise<CodexTrustPlan>;
44
+ export declare const applyCodexSafetyTrust: (options: CodexSafetyTrustOptions & {
35
45
  expectedPlanDigest: string;
36
46
  }, dependencies?: Dependencies) => Promise<{
37
47
  nativeDiscoveryVerified: boolean;
38
48
  nativeAdoptionVerified: boolean;
39
49
  unrelatedConfigurationPreserved: boolean;
40
50
  readinessRunnerVerified?: boolean | undefined;
51
+ guardVerified: boolean;
52
+ guard?: "workspace-repos-guard" | undefined;
41
53
  ok: boolean;
42
54
  changed: boolean;
43
55
  operationId: string;
44
56
  planDigest: string;
45
57
  configVersion: any;
46
- guardVerified: boolean;
47
58
  } | {
48
59
  schema: "hasna.hooks.codex-safety-trust/v1" | "hasna.hooks.codex-readiness-trust/v1";
49
60
  planDigest: string;
@@ -54,6 +65,10 @@ export declare const applyCodexSafetyTrust: (options: CodexSafetyOptions & {
54
65
  configPath: string;
55
66
  configVersion: string;
56
67
  action: "unchanged" | "trust_and_enable";
68
+ /** Present only for a guard other than trash-guard, whose plans and digests
69
+ * keep their earlier exact shape. Either way the digest binds the guard: by
70
+ * this field, and by the discovered definition it covers, whose command names it. */
71
+ guard?: Exclude<NativeSafetyName, "trash-guard">;
57
72
  guardVerified: boolean;
58
73
  readinessRunnerVerified?: true;
59
74
  nativeAdoptionVerified: false;
@@ -68,12 +83,13 @@ export declare const applyCodexReadinessTrust: (options: CodexSafetyOptions & {
68
83
  nativeAdoptionVerified: boolean;
69
84
  unrelatedConfigurationPreserved: boolean;
70
85
  readinessRunnerVerified?: boolean | undefined;
86
+ guardVerified: boolean;
87
+ guard?: "workspace-repos-guard" | undefined;
71
88
  ok: boolean;
72
89
  changed: boolean;
73
90
  operationId: string;
74
91
  planDigest: string;
75
92
  configVersion: any;
76
- guardVerified: boolean;
77
93
  } | {
78
94
  schema: "hasna.hooks.codex-safety-trust/v1" | "hasna.hooks.codex-readiness-trust/v1";
79
95
  planDigest: string;
@@ -84,6 +100,10 @@ export declare const applyCodexReadinessTrust: (options: CodexSafetyOptions & {
84
100
  configPath: string;
85
101
  configVersion: string;
86
102
  action: "unchanged" | "trust_and_enable";
103
+ /** Present only for a guard other than trash-guard, whose plans and digests
104
+ * keep their earlier exact shape. Either way the digest binds the guard: by
105
+ * this field, and by the discovered definition it covers, whose command names it. */
106
+ guard?: Exclude<NativeSafetyName, "trash-guard">;
87
107
  guardVerified: boolean;
88
108
  readinessRunnerVerified?: true;
89
109
  nativeAdoptionVerified: false;
@@ -11,6 +11,7 @@
11
11
  */
12
12
  import { type HookEvent, type HookMeta } from "./registry.js";
13
13
  import { type StaleRegistration } from "./registration.js";
14
+ import { type NativeSafetyName } from "./native-safety.js";
14
15
  import { type MementosRegistration } from "./mementos-options.js";
15
16
  export type Scope = "global" | "project";
16
17
  export type Target = "claude" | "gemini" | "codewith" | "codex" | "all";
@@ -85,8 +86,12 @@ export declare function detectRewriteConflict(name: string, scope: Scope, target
85
86
  /** Injected for tests: the rewrite claim is a registry concern, the overlap is not. */
86
87
  lookup?: (hookName: string) => HookMeta | undefined): string | undefined;
87
88
  export declare function installHook(name: string, options?: InstallOptions): InstallResult;
88
- /** Render through the installer without writing settings or trust state. */
89
- export declare function previewNativeSafetyRegistration(target: "codex" | "claude", scope?: Scope): {
89
+ /** Render through the installer without writing settings or trust state.
90
+ * The rewrite-conflict check is the installer's own, per guard: it refuses only
91
+ * a guard that rewrites tool input (trash-guard) beside another input rewriter
92
+ * on an overlapping matcher. workspace-repos-guard only denies, and a denial is
93
+ * not lost to another hook's rewrite, so no rewrite conflict applies to it. */
94
+ export declare function previewNativeSafetyRegistration(target: "codex" | "claude", scope?: Scope, guard?: NativeSafetyName): {
90
95
  before: string | null;
91
96
  after: string;
92
97
  command: string;
@@ -1,4 +1,5 @@
1
1
  import { verifyNativeSafetyCommand } from "../native-safety.js";
2
+ import { type NativeSafetyName } from "./native-safety.js";
2
3
  /** The definite cause of a refusal by the owning settings writer, before it could change the target. */
3
4
  export interface RegistrationRefusal {
4
5
  code: string;
@@ -15,8 +16,12 @@ export declare class NativeRegistrationError extends Error {
15
16
  readonly refusal?: RegistrationRefusal | undefined;
16
17
  constructor(code: "input_invalid" | "settings_unsafe" | "settings_invalid" | "settings_changed" | "hooks_disabled" | "registration_conflict" | "guard_failed" | "writer_refused" | "apply_refused" | "apply_outcome_uncertain", operationId?: string | undefined, refusal?: RegistrationRefusal | undefined);
17
18
  }
19
+ /** `guard` selects the bundled native safety guard (default trash-guard). Only
20
+ * that guard's own entry is rendered, verified and written; every other entry,
21
+ * a disabled one included, keeps its exact bytes. */
18
22
  export interface NativeRegistrationOptions {
19
23
  target: "codex" | "claude";
24
+ guard?: NativeSafetyName;
20
25
  }
21
26
  export interface NativeReadinessRegistrationOptions {
22
27
  target: "codex" | "claude" | "sumi";
@@ -30,6 +35,10 @@ export interface NativeRegistrationPlan {
30
35
  desiredSHA256: string;
31
36
  commandSHA256: string;
32
37
  action: "unchanged" | "register";
38
+ /** Present only for a guard other than trash-guard, whose plans and digests
39
+ * keep their earlier exact shape. Either way the guard is bound into the
40
+ * digest: by this field, and by `commandSHA256`, whose command names it. */
41
+ guard?: Exclude<NativeSafetyName, "trash-guard">;
33
42
  planDigest: string;
34
43
  guardVerified: boolean;
35
44
  readinessRunnerVerified?: true;
@@ -59,12 +68,13 @@ export declare const applyNativeSafetyRegistration: (options: NativeRegistration
59
68
  }, dependencies?: Dependencies) => Promise<{
60
69
  nativeAdoptionVerified: boolean;
61
70
  readinessRunnerVerified?: boolean | undefined;
71
+ guardVerified: boolean;
72
+ guard?: "workspace-repos-guard" | undefined;
62
73
  ok: boolean;
63
74
  changed: boolean;
64
75
  operationId: `${string}-${string}-${string}-${string}-${string}`;
65
76
  planDigest: string;
66
77
  settingsSHA256: string;
67
- guardVerified: boolean;
68
78
  } | {
69
79
  schema: "hasna.hooks.native-safety-registration/v1" | "hasna.hooks.native-readiness-registration/v1";
70
80
  target: "codex" | "claude" | "sumi";
@@ -74,6 +84,10 @@ export declare const applyNativeSafetyRegistration: (options: NativeRegistration
74
84
  desiredSHA256: string;
75
85
  commandSHA256: string;
76
86
  action: "unchanged" | "register";
87
+ /** Present only for a guard other than trash-guard, whose plans and digests
88
+ * keep their earlier exact shape. Either way the guard is bound into the
89
+ * digest: by this field, and by `commandSHA256`, whose command names it. */
90
+ guard?: Exclude<NativeSafetyName, "trash-guard">;
77
91
  planDigest: string;
78
92
  guardVerified: boolean;
79
93
  readinessRunnerVerified?: true;
@@ -88,12 +102,13 @@ export declare const applyNativeReadinessRegistration: (options: NativeReadiness
88
102
  }, sumiDependencies?: SumiRegistrationDependencies) => Promise<{
89
103
  nativeAdoptionVerified: boolean;
90
104
  readinessRunnerVerified?: boolean | undefined;
105
+ guardVerified: boolean;
106
+ guard?: "workspace-repos-guard" | undefined;
91
107
  ok: boolean;
92
108
  changed: boolean;
93
109
  operationId: `${string}-${string}-${string}-${string}-${string}`;
94
110
  planDigest: string;
95
111
  settingsSHA256: string;
96
- guardVerified: boolean;
97
112
  } | {
98
113
  schema: "hasna.hooks.native-safety-registration/v1" | "hasna.hooks.native-readiness-registration/v1";
99
114
  target: "codex" | "claude" | "sumi";
@@ -103,6 +118,10 @@ export declare const applyNativeReadinessRegistration: (options: NativeReadiness
103
118
  desiredSHA256: string;
104
119
  commandSHA256: string;
105
120
  action: "unchanged" | "register";
121
+ /** Present only for a guard other than trash-guard, whose plans and digests
122
+ * keep their earlier exact shape. Either way the guard is bound into the
123
+ * digest: by this field, and by `commandSHA256`, whose command names it. */
124
+ guard?: Exclude<NativeSafetyName, "trash-guard">;
106
125
  planDigest: string;
107
126
  guardVerified: boolean;
108
127
  readinessRunnerVerified?: true;
@@ -127,6 +146,10 @@ export declare const applyNativeReadinessRegistration: (options: NativeReadiness
127
146
  desiredSHA256: string;
128
147
  commandSHA256: string;
129
148
  action: "unchanged" | "register";
149
+ /** Present only for a guard other than trash-guard, whose plans and digests
150
+ * keep their earlier exact shape. Either way the guard is bound into the
151
+ * digest: by this field, and by `commandSHA256`, whose command names it. */
152
+ guard?: Exclude<NativeSafetyName, "trash-guard">;
130
153
  planDigest: string;
131
154
  guardVerified: boolean;
132
155
  readinessRunnerVerified?: true;
@@ -1,3 +1,4 @@
1
+ import { type NativeSafetyName } from "./lib/native-safety.js";
1
2
  export declare class NativeSafetyError extends Error {
2
3
  readonly code: "binding_missing" | "binding_invalid" | "binding_changed" | "binding_busy" | "guard_failed" | "input_invalid";
3
4
  readonly reason?: string | undefined;
@@ -86,8 +87,15 @@ export declare function evaluateNativeSafetyForExecution(event: NativeSafetyEven
86
87
  }): Promise<NativeSafetyExecutionDecision>;
87
88
  /** Classify a synthetic removal through this exact supervisor without executing
88
89
  * the returned command or creating a file. A harmless ':' would not test whether
89
- * the saved PATH can actually resolve Trash. */
90
- export declare function verifyNativeSafetyCommand(command: string, home?: string): Promise<void>;
90
+ * the saved PATH can actually resolve Trash.
91
+ *
92
+ * `guard` names the capability the command must carry, with the same home.
93
+ * trash-guard must rewrite the removal into Trash. workspace-repos-guard never
94
+ * rewrites, so its probe is a removal below the protected clones root, which it
95
+ * refuses from the path alone: the exact deny proves the pinned runtime and
96
+ * worker, the worker's execution and its classification. Neither probe runs the
97
+ * removal, and neither path is created. */
98
+ export declare function verifyNativeSafetyCommand(command: string, home?: string, guard?: NativeSafetyName): Promise<void>;
91
99
  export declare function verifyNativeSafetyRegistration(home?: string): Promise<{
92
100
  path: string;
93
101
  sha256: string;
@@ -382,8 +382,25 @@ async function evaluateRecord(event, record, signal, executionAgent) {
382
382
  } catch {}
383
383
  throw new NativeSafetyError("guard_failed");
384
384
  }
385
- async function verifyNativeSafetyCommand(command, home = homedir2()) {
385
+ async function verifyNativeSafetyCommand(command, home = homedir2(), guard = "trash-guard") {
386
+ if (guard !== "trash-guard" && guard !== "workspace-repos-guard")
387
+ throw new NativeSafetyError("input_invalid");
386
388
  home = canonicalHome(home);
389
+ if (guard === "workspace-repos-guard") {
390
+ const binding = nativeSafetyCommandBinding(command);
391
+ if (binding?.name !== guard || binding.home !== home)
392
+ throw new NativeSafetyError("binding_invalid");
393
+ const root = join2(home, ".hasna", "repos", "clones"), probe = join2(root, ".hasna-workspace-repos-verification-only");
394
+ const verdict2 = await evaluateRecord({
395
+ hook_event_name: "PreToolUse",
396
+ tool_name: "Bash",
397
+ cwd: home,
398
+ tool_input: { command: "rm -- '" + probe.replaceAll("'", "'\\''") + "'" }
399
+ }, { schema: "hasna.hooks.native-safety.v1", harness: "sumi", command });
400
+ if (verdict2.decision !== "deny" || verdict2.reason !== `[workspace-repos-guard] delete under the protected repo-checkout root (${root}) is forbidden at any depth: ${probe}`)
401
+ throw new NativeSafetyError("guard_failed", verdict2.decision === "deny" ? verdict2.reason.slice(0, 512) : undefined);
402
+ return;
403
+ }
387
404
  const record = parseRecord(JSON.stringify({ schema: "hasna.hooks.native-safety.v1", harness: "sumi", command }), home);
388
405
  const verdict = await evaluateRecord({ hook_event_name: "PreToolUse", tool_name: "Bash", cwd: home, tool_input: { command: "rm -- .hasna-trash-verification-only" } }, record);
389
406
  if (verdict.decision !== "rewrite")
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hasna/hooks",
3
- "version": "0.12.7",
3
+ "version": "0.12.9",
4
4
  "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
5
5
  "type": "module",
6
6
  "bin": {
@@ -70,7 +70,7 @@
70
70
  "@hasna/contracts": "~1.2.1"
71
71
  },
72
72
  "dependencies": {
73
- "@hasna/skills": "0.10.47",
73
+ "@hasna/skills": "0.10.55",
74
74
  "@hasna/events": "^0.1.16",
75
75
  "@hasna/secrets": "0.4.2",
76
76
  "@modelcontextprotocol/sdk": "^1.26.0",