@hasna/hooks 0.12.23 → 0.13.1

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
@@ -10,6 +10,7 @@ Open source hooks library for AI coding agents - Install safety, quality, and au
10
10
  `@hasna/hooks` installs hooks into AI coding agents. A hook is a small program the agent runs at a fixed point: before a shell command, after a file edit, or when a turn ends. Hooks block a mistake, check the work, or automate a step. One CLI installs, lists, updates and removes them.
11
11
 
12
12
  - **Agents.** Claude Code (the default target) and Codex. Compatible OpenCode and Sumi builds are supported for the stop-review hook. Gemini CLI is an install target (`--target gemini`), but the bundled shell guards do not yet recognise Gemini's tool names (`run_shell_command` rather than `Bash`), so do not rely on them there yet. Codewith targets remain for existing setups, but Codewith is deprecated.
13
+ - **Install targets.** `--target` also accepts `qwen`, `muse`, `kimi`, `pi` and `cursor`, each writing that harness's own config with an entry that calls `hooks run <hook> --target <name>`. They are not interchangeable: Muse hands over the final message as a quoted JSON string, which `hooks run --target muse` parses once; Kimi's stop payload carries no assistant text and Kimi blocks with exit 2 and stderr; Pi runs hooks through the `hasna-pi-hooks` bridge and receives no assistant text; Cursor's stop hook can neither block the turn nor carry the assistant text. A hook whose manifest sets `requires_final_message` or `requires_block` is refused at install on a target that cannot honour it, with the measured reason, instead of being installed to do nothing. `opencode` and `sumi` have no generic install path and are refused by name; their stop review is registered through `hooks install stop-review --target <opencode|sumi>`.
13
14
  - **Catalog.** 57 bundled hooks in 10 categories, listed below. You can also install your own hooks from a local directory, a git URL or a manifest URL.
14
15
  - **Safety core.** Guards that:
15
16
  - block destructive git commands (gitguard);
@@ -732,7 +733,7 @@ Local mode is answered BEFORE the resolver runs (so an unhosted run touches neit
732
733
 
733
734
  **Hosted is a route, not just admission (owner ruling 2026-09-07).** Once a registry credential resolves — the env pair, the Keychain item, or the credentials file — the on-box SQLite store is refused for the whole process: `hooks log *`, `hooks storage *`, the MCP `hooks_log_*` / `storage_*` / `send_feedback` tools and the hook-event writer answer `REMOTE_COMMAND_UNSUPPORTED` (naming the opt-in) instead of reading or creating `~/.hasna/hooks/hooks.db`. Pins and trust keep working on the hosted route through `hooks.lock` alone; the SQLite `hooks` table is a local-mode mirror.
734
735
 
735
- **`hooks run` decides its route like every other client verb.** Under the explicit opt-in it executes the hook and records the event in the on-box store (the child hook sees `HOOKS_LOCAL`); on the hosted route it executes the hook but refuses the event write loudly (one stderr line — the hosted registry has no event route); with nothing configured it prints a `REMOTE_API_CONFIG_MISSING` error naming the credential tiers and the opt-in, creates nothing, and exits non-zero. For a bundled hook whose only event is PreToolUse (including a credential that is present but refused) it exits 2 and adds a "Blocked:" line, so the agent refuses the tool call instead of running it; every other hook exits 1, which agents treat as a non-blocking error. The same exit 2 applies whenever `hooks run` cannot run such a guard and so decides nothing: a missing script, an unreadable script or trust record (such as a malformed `hooks.lock`), a script changed since it was trusted, invalid run options (including an unknown option or a missing option value), an invalid native target, or a failure to start such as a read-only install refusing the temporary copy. The `hook-` alias of a guard's name counts as the guard; a custom hook installed under a guard's name takes precedence and keeps exit 1. Bundled hooks have no `hooks run` timeout, so a hung guard is bounded by the agent's own hook timeout. Before 0.12.21 an unconfigured PreToolUse guard also exited 1, and the guarded command ran. Agents that wire `hooks run <name>` into their settings on an unconfigured machine therefore need either a registry credential or `HASNA_HOOKS_LOCAL=1` in the hook's environment.
736
+ **`hooks run` decides its route like every other client verb.** Under the explicit opt-in it executes the hook and records the event in the on-box store (the child hook sees `HOOKS_LOCAL`); on the hosted route it executes the hook but refuses the event write loudly (one stderr line — the hosted registry has no event route). `hooks run` uses no registry credential, so when the Keychain item `hasna.credentials.hooks.api-key` (or `.api-url`) exists but this session may not read it (`security` exit 36: a locked login keychain, or a session without access to it, such as one started over SSH), it still takes the hosted route and runs the hook pinned in `hooks.lock`. It does not read the disk file or the environment in the Keychain's place, and it does not open `hooks.db`; every other command, and every other Keychain failure, still fails closed. With nothing configured it prints a `REMOTE_API_CONFIG_MISSING` error naming the credential tiers and the opt-in, creates nothing, and exits non-zero. For a bundled hook whose only event is PreToolUse (including a credential that is present but refused, other than the exit-36 Keychain case above) it exits 2 and adds a "Blocked:" line, so the agent refuses the tool call instead of running it; every other hook exits 1, which agents treat as a non-blocking error. The same exit 2 applies whenever `hooks run` cannot run such a guard and so decides nothing: a missing script, an unreadable script or trust record (such as a malformed `hooks.lock`), a script changed since it was trusted, invalid run options (including an unknown option or a missing option value), an invalid native target, or a failure to start such as a read-only install refusing the temporary copy. The `hook-` alias of a guard's name counts as the guard; a custom hook installed under a guard's name takes precedence and keeps exit 1. Bundled hooks have no `hooks run` timeout, so a hung guard is bounded by the agent's own hook timeout. Before 0.12.21 an unconfigured PreToolUse guard also exited 1, and the guarded command ran. Agents that wire `hooks run <name>` into their settings on an unconfigured machine therefore need either a registry credential or `HASNA_HOOKS_LOCAL=1` in the hook's environment.
736
737
 
737
738
  Surfaces that never open the client store and are server/operator-only by design need neither setting: `serve` (`hooks-serve`), `cf`, `migrate`, `init`, `profile-export`/`profile-import`, `channels`, `events`, and `--help`/`--version`. `hooks mcp` and the `hooks-mcp` bin decide their authority themselves before any transport connects (below).
738
739