@hasna/hooks 0.12.2 → 0.12.4

package/README.md

@@ -175,11 +175,38 @@ install; see "Rolling out a new native worker" below.
 
 For the default global Claude settings path, a managed Skills installation
 coordinates hook changes and discovery witnesses in one guarded update. Existing
-drift or concurrent edits refuse installation before an uncoordinated write;
-standalone installation remains available when no Skills policy exists. This
+drift or concurrent edits refuse installation before an uncoordinated write.
+Standalone installation remains available only while Skills is absent. When the
+file carries Skills' own `hook user-prompt` entries, or the Skills bridge
+`~/.claude/skills/skills-cli/SKILL.md` exists, but no Skills agent policy
+resolves, installing, removing and pruning refuse with `skills_policy_unresolved`,
+list every location searched and write nothing; run Hooks with the environment
+that selects the Skills data directory (for example `HASNA_SKILLS_DIR`). This
 coordination includes project or custom paths resolving to that same file; it
 does not cover separate project settings files.
 
+At every Claude or Gemini settings path, a settings file that exists but cannot
+be read or does not parse as a JSON object is never replaced: installing (also
+through `hooks_enable`) refuses with `settings_unreadable` and writes nothing.
+Repair the file or move it aside, then retry. A missing file is still created.
+
+The MCP tools `hooks_disable` and `hooks_enable` use the same writer, and a
+refusal is an MCP error carrying its `code` and message. `hooks_disable` removes
+the hook's Claude registration, which is equivalent to `hooks_remove` for that
+registration; the hook stays installed. For the safety guards `trash-guard` and
+`workspace-repos-guard` that also removes their protection until the guard is
+enabled or installed again. `hooks_enable` is equivalent to a non-overwrite
+`hooks_install`: it installs a hook that was never installed, and does nothing
+when the hook is already registered. It only registers hooks that `hooks_install`
+can install, so after disabling `trash-readiness`, or a stale registration of a
+hook that no longer exists, `hooks_enable` fails with `Hook '<name>' not found`.
+No separate disabled state is stored, so a disable then enable is not an exact
+round trip. The registration comes back with the default matcher and timeout,
+at the end of its event's list, in a group of its own rather than one it shared
+with other hooks, and once per event even where disable removed duplicates. A
+`--profile` binding returns only if `profile` is passed to `hooks_enable` again,
+and Mementos options set at the original install are not restored.
+
 Supported controls cover shell `rm` rewrites through a verified `@hasna/trash`
 guard, explicit unsupported delete commands, and whole-file `apply_patch`
 deletions. They do not intercept arbitrary filesystem syscalls, application APIs,
@@ -220,6 +247,10 @@ 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.
+A refusal before the write returns `apply_refused` with its cause as
+`refusal: {code, message}` and records `refused.json` beside the operation's
+intent; settings are unchanged. Only a failure after the write may have started
+returns `apply_outcome_uncertain`.
 
 After registration, Codex trust uses its supported native configuration writer:
 
@@ -309,9 +340,11 @@ Known limits of the native entry:
   harness environment are outside it (details in the guard's README).
 - Codex's input into a running unified exec session (`write_stdin`) has not
   been verified to pass through PreToolUse.
-- The repository guard still reads a here-document body line by line, so prose
-  in a `--body "$(cat <<'EOF' … EOF)"` body that mentions a delete command
-  beside an unbalanced quote can still be refused by that guard.
+- The repository guard reads a here-document body as data only when every
+  command word of the command is a data command such as `cat`, `git commit`
+  or `gh pr` (the list is in the guard's README). With any other command word
+  it reads the body line by line, so prose in such a body that mentions a
+  delete command can still be refused inside a protected checkout.
 
 ## Codex safety readiness
 
@@ -331,8 +364,8 @@ 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.154.0-alpha.6.1, 0.155.0, 0.155.1, 0.156.1, 0.157.0, 0.157.1, 0.158.0, 0.159.0, 0.159.2
-and 0.159.3;
+0.154.0-alpha.6.1, 0.155.0, 0.155.1, 0.156.1, 0.157.0, 0.157.1, 0.158.0, 0.159.0, 0.159.2,
+0.159.3 and 0.160.0;
 other versions refuse pending compatibility validation. Updating Codex can
 therefore require a compatible Hooks release before native safety verification
 and trust provisioning succeed. Keep existing hook definitions and trust intact