@hasna/hooks 0.10.9 → 0.11.1

package/README.md

@@ -13,6 +13,54 @@ npm install -g @hasna/hooks
 
 ## CLI Usage
 
+### Trash startup readiness
+
+The bundled `trash-readiness` observer checks an installed Trash ready plan at
+session startup. It reports a short ready or attention message. It does not
+capture files, repair settings, retry failed requests, or authorize deletion.
+Keep the separate `trash-guard` installed and enabled.
+
+Claude and Codex use their native `SessionStart` event for startup, resume,
+clear and fork. Compaction does not repeat this check. Configuration and native
+execution are separate: successful setup leaves `nativeAdoptionVerified:false`
+until the actual consumer has been exercised.
+
+```bash
+hooks safety startup registration-plan --target claude
+hooks safety startup registration-apply --target claude --expected-plan-digest SHA256
+
+hooks safety startup registration-plan --target codex
+hooks safety startup registration-apply --target codex --expected-plan-digest SHA256
+hooks safety startup trust-plan --target codex --codex-command /absolute/native/codex --cwd /absolute/project
+hooks safety startup trust-apply --target codex --codex-command /absolute/native/codex --cwd /absolute/project --expected-plan-digest SHA256
+```
+
+After registration and trust, use Trash's station setup flow to produce a new
+ready plan. Native configuration changes must precede this plan because its
+digest binds the selected configuration. Bind that plan explicitly:
+
+```bash
+hooks safety startup bind --target codex --binding /absolute/binding.json --expected-binding-sha256 absent
+hooks safety startup check --target codex
+```
+
+The binding schema is `hasna.hooks.trash-readiness/v1`. It contains the exact
+provider and home, `runtime:{path,sha256}`, `trash:{root,version,cliSha256}`,
+`plan:{path,sha256}`, and `timeoutMs` (1000–15000). Paths are absolute; the
+package and plan must be inside that home. The installed binding lives at
+`~/.hasna/hooks/native/trash-readiness/<provider>.json`. Updating it requires its
+current digest; the writer preserves an immutable predecessor, intent and
+receipt. Response loss requires inspection before another explicit operation.
+Generic Hooks registry authentication is unchanged.
+
+The `@hasna/hooks/native-readiness` export also exposes the observer for harness
+integrations as `await runTrashReadiness(provider, { signal })`. The observer
+supervises only its newly created check process group, including nested clients,
+and cleans it up on completion, cancellation or timeout. Selecting `sumi`
+identifies that consumer; it does not register
+a Sumi lifecycle event. A Sumi adapter must call the observer through its own
+supported startup path and verify delivery separately.
+
 ```bash
 hooks --help
 ```