@hasna/hooks 0.12.5 → 0.12.7

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.
package/README.md CHANGED
@@ -242,15 +242,21 @@ conflicting Hooks path overrides refuse. Missing native settings directories are
242
242
  created only on apply. Disabled or asynchronous guards, unsafe paths, duplicate
243
243
  JSON keys and numbers that cannot be preserved exactly refuse before a write.
244
244
  Managed default Claude settings continue through Skills' coordinated writer.
245
+ For those, the plan also runs that writer's own read-only checks on the exact
246
+ change: it parses the Skills agent policy and plans the update without writing.
247
+ When the writer would refuse, the plan refuses as apply does, with
248
+ `writer_refused` and the same `refusal: {code, message}`, and returns no digest.
245
249
 
246
250
  The SDK exports `planNativeSafetyRegistration` and
247
251
  `applyNativeSafetyRegistration`. Both return `nativeAdoptionVerified: false`.
248
252
  A changed or uncertain apply requires a fresh read-only plan and inspection of
249
253
  its recorded operation; no automatic retry or direct overwrite is performed.
250
- A refusal before the write returns `apply_refused` with its cause as
251
- `refusal: {code, message}` and records `refused.json` beside the operation's
252
- intent; settings are unchanged. Only a failure after the write may have started
253
- returns `apply_outcome_uncertain`.
254
+ A writer refusal found while planning returns `writer_refused` with its cause as
255
+ `refusal: {code, message}`, from plan and apply alike; nothing is written or
256
+ journaled. A refusal later, before the write, returns `apply_refused` with its
257
+ cause and records `refused.json` beside the operation's intent; settings are
258
+ unchanged. Only a failure after the write may have started returns
259
+ `apply_outcome_uncertain`.
254
260
 
255
261
  After registration, Codex trust uses its supported native configuration writer:
256
262
 
@@ -297,6 +303,13 @@ hooks safety install trash-guard --target sumi --expected-binding-sha256 CURRENT
297
303
  hooks safety verify --target sumi --execution
298
304
  ```
299
305
 
306
+ Hooks registered as `hooks run <hook>` do not go through the native worker, so
307
+ re-registration does not cover them. When a release changes the script of such
308
+ a hook, run `hooks trust <hook>` with the new CLI on every station after
309
+ switching PATH to it, as "Trust model" under "Custom and remote hooks"
310
+ describes. Until then, wherever an old pin exists, it refuses the new script
311
+ and that hook exits 1 on every call.
312
+
300
313
  `hooks safety provision --target sumi`, which the package's lifecycle script
301
314
  also runs, keeps a binding that still verifies, so it does not move Sumi to a
302
315
  worker installed in a different tree; the explicit install above does. That
@@ -372,6 +385,12 @@ and trust provisioning succeed. Keep existing hook definitions and trust intact
372
385
  when this check reports `native_unsupported`.
373
386
  The version probe has a five-second forced timeout and native discovery a
374
387
  fifteen-second lifetime budget. Neither step restarts an existing agent.
388
+ Both run the native with an explicit environment allowlist: `PATH`, `USER`,
389
+ `LOGNAME`, `LANG`, `LC_*`, `TMPDIR`, the XDG base directories and Codex's own
390
+ `CODEX_*` variables, with `HOME`, `NO_COLOR` and `CODEX_HOME` set by Hooks.
391
+ Dynamic-loader (`LD_*`, `DYLD_*`) and runtime-hook (`NODE_*`, `BUN_*`,
392
+ `BASH_ENV`, `ENV`) variables never reach it, because only the executable's
393
+ bytes are verified.
375
394
 
376
395
  Success reports `nativeDiscoveryVerified: true`, `guardVerified: true` and
377
396
  `nativeAdoptionVerified: false`. It does not enroll trust, change configuration,
@@ -449,13 +468,15 @@ hooks install https://example.com/hooks/my-hook/manifest.json
449
468
 
450
469
  Custom hooks land in `~/.hasna/hooks/hooks/<name>/`. A custom hook with the same name as a bundled hook takes precedence (visible in `hooks info <name>`).
451
470
 
452
- **Trust model.** Every hook script is pinned by sha256 in `~/.hasna/hooks/hooks.lock` and the SQLite `hooks` table. `hooks run` verifies the script hash before executing; if the script changed, the run is refused:
471
+ **Trust model.** Every hook script is pinned by sha256 in `hooks.lock` in the hooks data directory (`~/.hasna/hooks/hooks.lock` unless the data directory resolves elsewhere; `HASNA_HOOKS_LOCK_PATH`, or its alias `HOOKS_LOCK_PATH`, overrides the lock path) and, in local mode, in the SQLite `hooks` table, which is checked first. `hooks run` verifies the script hash before executing; if the script changed, the run is refused and exits 1:
453
472
 
454
473
  ```bash
455
474
  hooks trust <name> # re-pin the current script content
456
475
  hooks update # re-register hooks and refresh pins
457
476
  ```
458
477
 
478
+ A hook's first run writes its pin, and so do `hooks sync` (in local mode it pins every bundled hook without running any of them), `hooks update`, `hooks install <name>@<version>`, `hooks update <name>@<version>` and `hooks trust`. A station can therefore hold a pin for a hook that has never run there. After any upgrade that changes the script of a hook registered as `hooks run <hook>`, run `hooks trust <hook>` with the new CLI on every station. Run it as the same user and with the same hooks environment that the harness's `hooks run` sees: the local opt-in or registry credential, and any data directory, DB or lock path override. Otherwise it can write a pin that `hooks run` does not read. Where the hook is not pinned yet, it pins the same sha256 that the first run would have pinned, so it is harmless there.
479
+
459
480
  **Registry server.** `hooks serve` exposes the local store over HTTP — catalog, artifacts, and the published lock:
460
481
 
461
482
  ```bash