@hasna/hooks 0.12.3 → 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: