@hasna/hooks 0.11.7 → 0.12.1

package/README.md

@@ -33,8 +33,20 @@ 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
+
+hooks safety startup registration-plan --target sumi
+hooks safety startup registration-apply --target sumi --expected-plan-digest SHA256
 ```
 
+Sumi runs the observer inside its own process from the bundled SDK, switched on
+by Sumi's own `experimental.trash_readiness` setting, so there is no startup
+command to register. For Sumi, the startup registration re-points the Hooks-owned
+guard record, `~/.hasna/hooks/native/sumi-trash-guard.json`, at this installed
+package. Sumi's startup check verifies that record. The registration uses the same
+read-only plan, the exact plan digest and a retained predecessor as the other
+targets. Unlike `hooks safety provision`, it also moves a different record that
+still verifies. It never writes Sumi's configuration.
+
 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:
@@ -44,9 +56,15 @@ hooks safety startup bind --target codex --binding /absolute/binding.json --expe
 hooks safety startup check --target codex
 ```
 
-The binding schema is `hasna.hooks.trash-readiness/v1`. It contains the exact
+The full binding-file contract is in
+[docs/trash-readiness.md](docs/trash-readiness.md). It covers where each field
+comes from, the compare-and-swap digest, the output and refusal codes, and how
+to probe a result. 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–60000). Use 45000 for a normal
+`plan:{path,sha256}`, and `timeoutMs` (1000–60000). The plan is the ready plan
+that `trash station plan --out` wrote, and `runtime` is that plan's `spec.runtime`.
+`--expected-binding-sha256` is the SHA-256 of the installed binding file, or
+`absent`. Use 45000 for a normal
 whole-startup budget, configurable within those bounds. Existing bindings retain
 their explicit budget until a guarded update. Claude and Codex registrations
 allow 65 seconds for the observer's 60-second maximum plus runner overhead.
@@ -64,7 +82,10 @@ 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.
+supported startup path and verify delivery separately. A running harness keeps
+the SDK version it started with. A 45000 ms binding needs a consumer built with
+0.11.4 or later, because older consumers cap `timeoutMs` at 15000 and report
+`binding_invalid`.
 
 ```bash
 hooks --help
@@ -121,6 +142,37 @@ reinstalling the registration and reviewing the new native trust definition. Uns
 installation paths are refused before settings are written. Codex also requires
 trust through `/hooks`; registration alone does not prove interception.
 
+The same bundled entry also evaluates the `signed-link-guard` for every Bash
+and Monitor command (Claude Code's `Monitor` tool runs a shell command and
+streams its stdout to the model), under either capability name (`trash-guard`
+or `workspace-repos-guard`): a `gh` read that would print composite GitHub
+content (bodies, comments, reviews, check links and details, raw issue and
+pull request objects) is refused before it runs with the reason
+`composite output withheld: signed-link shape; use bounded scalar projections per class disposition 799310`.
+Bounded scalar reads such as `gh pr view <n> --json number,state,headRefOid`,
+`gh pr checks <n> --json name,state,bucket` and `gh api … --jq .head.sha` pass,
+and so does every `gh` write, including a `--body "$(cat <<'EOF' … EOF)"`
+body. A plain `gh pr view <n>` and a plain or `--watch` `gh pr checks <n>` are
+refused, because they print the body and the check links; the guard's README
+lists the scalar alternatives. See `hooks/hook-signed-link-guard/README.md` for
+the full rule list and its limits. The guard is also a catalog hook
+(`hooks install signed-link-guard`), and `signed-link-output` is an optional
+Claude PostToolUse backstop that replaces signed-link URLs in tool output where
+the running Claude Code supports output replacement.
+
+Monitor commands get every check a Bash command gets. A deletion inside a
+Monitor command is refused instead of rewritten into Trash, because the
+rewrite is proven only for the Bash tool; run deletions with Bash. Claude
+registrations therefore match
+`^(Bash|Monitor|apply_patch|ApplyPatch|functions\.apply_patch)$` (the
+repository guard also matches `Write`, `Edit`, `MultiEdit` and
+`NotebookEdit`). Re-registering with `--overwrite` or `registration-apply`
+updates a registration that still has the matcher without `Monitor` in place,
+and the Claude safety check reports that older matcher as not installed.
+Because a registration pins the worker's digest, an installed registration
+keeps running the previous worker until it is re-registered for the new
+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;
@@ -188,6 +240,79 @@ runtime-policy verification, native discovery and native adoption false;
 MDM/server policy, workspace trust and launch flags require native acceptance.
 
 
+## Rolling out a new native worker
+
+Every native registration pins the SHA-256 of `bin/native-safety-entry.js`, so
+a release that changes the worker reaches a harness only when that harness is
+re-registered against the new install. Run each step with the new version's
+CLI (`hooks --version`), after installing that version:
+
+```bash
+# Claude Code
+hooks safety registration-plan --target claude
+hooks safety registration-apply --target claude --expected-plan-digest PLAN_SHA256
+# Only where the repository guard is registered under its own name:
+hooks safety install workspace-repos-guard --target claude --overwrite
+
+# Codex (a changed definition runs only after it is trusted again)
+hooks safety registration-plan --target codex
+hooks safety registration-apply --target codex --expected-plan-digest PLAN_SHA256
+hooks safety trust-plan --target codex --cwd /path/to/project --codex-command /absolute/path/to/native/codex
+hooks safety trust-apply --target codex --cwd /path/to/project --codex-command /absolute/path/to/native/codex --expected-plan-digest PLAN_SHA256
+
+# Sumi
+hooks safety verify --target sumi            # prints the current binding's sha256
+hooks safety install trash-guard --target sumi --expected-binding-sha256 CURRENT_SHA256
+hooks safety verify --target sumi --execution
+```
+
+`hooks safety provision --target sumi`, which the package's lifecycle script
+also runs, keeps a binding that still verifies, so it does not move Sumi to a
+worker installed in a different tree; the explicit install above does. That
+install refuses `--overwrite` with `input_invalid`: the expected digest is its
+upgrade guard. A binding that no longer verifies (its worker was rewritten)
+cannot report its digest; `hooks safety provision --target sumi` re-registers
+that one and keeps the previous record beside it. Where
+`hooks safety startup registration-plan` and `registration-apply` accept
+`--target sumi` (hasna/apps#2932), that registration re-points the same record
+through a read-only plan and an exact plan digest, and it supersedes the install
+form above.
+
+A running Sumi service keeps the readiness code bundled into its own build, so
+Sumi's startup readiness warning clears only once the service runs a Sumi build
+of 0.2.45 or later. Restarting the service is an owner decision and is not part
+of this rollout.
+
+Installing over the running version is a half-registration hazard.
+`bun add -g @hasna/hooks@<version>` (or `npm install -g`) rewrites the worker
+in place in the global package tree. Every registration still pinned to the
+old digest then refuses every shell and patch command in its harness, since
+the supervisor fails closed on changed bytes, until it is re-registered; the
+lifecycle script re-provisions only Sumi. Until the last registration is
+applied, some harnesses run the new guard and the others refuse everything.
+Install each version into its own tree (the fleet's
+`~/.hasna/hooks/runtime/<version>-copyfile` layout) and register from there,
+so every old registration keeps verifying its own tree until it is moved. If
+an in-place global upgrade cannot be avoided, re-register all three targets
+straight after it.
+
+The supervisor passes the worker to the runtime as one `--eval` argument, and
+Linux limits a single argument to 131,072 bytes (32 pages of 4 KiB). The
+worker is therefore built minified, and the package validation refuses a
+worker at or above that size.
+
+Known limits of the native entry:
+
+- The signed-link guard judges command text: interpreters and script files
+  that run `gh` themselves, shell aliases and functions from earlier commands,
+  `gh` extensions, direct HTTP clients such as `curl` and `GH_DEBUG` set in the
+  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.
+
 ## Codex safety readiness
 
 ```bash
@@ -206,7 +331,7 @@ 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 and 0.159.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 and 0.159.2;
 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

package/bin/hooks-mcp.js

@@ -135,6 +135,9 @@ var init_app_home = __esm(() => {
 });
 
 // src/lib/registry.ts
+function matcherFor(meta, target) {
+  return meta.targetMatchers?.[target] ?? meta.matcher;
+}
 function getHooksByCategory(category) {
   return HOOKS.filter((h) => h.category === category);
 }
@@ -148,7 +151,7 @@ function searchHooks(query) {
 function getHook(name) {
   return HOOKS.find((h) => h.name === name);
 }
-var CATEGORIES, HOOKS;
+var CLAUDE_TRASH_GUARD_MATCHER = "^(Bash|Monitor|apply_patch|ApplyPatch|functions\\.apply_patch)$", CATEGORIES, HOOKS;
 var init_registry = __esm(() => {
   init_app_home();
   CATEGORIES = [
@@ -213,6 +216,8 @@ var init_registry = __esm(() => {
       category: "Git Safety",
       event: "PreToolUse",
       matcher: "^(Bash|Write|Edit|MultiEdit|NotebookEdit|apply_patch|ApplyPatch|functions\\.apply_patch)$",
+      targetMatchers: { claude: "^(Bash|Monitor|Write|Edit|MultiEdit|NotebookEdit|apply_patch|ApplyPatch|functions\\.apply_patch)$" },
+      legacyMatchers: ["^(Bash|Write|Edit|MultiEdit|NotebookEdit|apply_patch|ApplyPatch|functions\\.apply_patch)$"],
       tags: ["workspace", "repos", "structure", "guard", "safety", "orgs", "multi-agent"]
     },
     {
@@ -223,6 +228,8 @@ var init_registry = __esm(() => {
       category: "Git Safety",
       event: "PreToolUse",
       matcher: "^(Bash|apply_patch|ApplyPatch|functions\\.apply_patch)$",
+      targetMatchers: { claude: CLAUDE_TRASH_GUARD_MATCHER },
+      legacyMatchers: ["^(Bash|apply_patch|ApplyPatch|functions\\.apply_patch)$"],
       tags: ["rm", "delete", "trash", "recoverable", "guard", "safety", "bash"],
       rewritesInput: true,
       timeoutSeconds: 10
@@ -327,6 +334,28 @@ var init_registry = __esm(() => {
       matcher: "Bash",
       tags: ["security", "credentials", "secrets", "detection", "audit"]
     },
+    {
+      name: "signed-link-guard",
+      displayName: "Signed Link Guard",
+      description: "Refuses gh reads that would print composite GitHub content (bodies, comments, reviews, commit messages, check links and details, raw issue/PR/check API objects) where signed action links appear; bounded scalar projections, diffs, lists and writes pass",
+      version: "0.1.0",
+      category: "Security",
+      event: "PreToolUse",
+      matcher: "^(Bash|Monitor)$",
+      tags: ["github", "gh", "signed-links", "capabilities", "transcript", "guard", "security"],
+      timeoutSeconds: 10
+    },
+    {
+      name: "signed-link-output",
+      displayName: "Signed Link Output",
+      description: "Claude PostToolUse backstop: replaces signed-link URLs in tool output with a redaction marker (updatedToolOutput, where the running Claude Code supports it) and tells the model not to repeat or store the link. It runs after the tool, so it cannot undo display or other persistence",
+      version: "0.1.0",
+      category: "Security",
+      event: "PostToolUse",
+      matcher: "^(Bash|WebFetch|mcp__.*)$",
+      tags: ["github", "signed-links", "capabilities", "redaction", "transcript", "security"],
+      timeoutSeconds: 10
+    },
     {
       name: "phonenotify",
       displayName: "Phone Notify",
@@ -1419,7 +1448,7 @@ var init_redact = __esm(() => {
   ];
 });
 
-// ../../../../validation/build/apps/hooks/node_modules/@hasna/contracts/dist/client/transport.js
+// ../../node_modules/.bun/@hasna+contracts@1.2.2+944b86d8024e79fa/node_modules/@hasna/contracts/dist/client/transport.js
 import { isIP } from "net";
 import { spawnSync } from "child_process";
 import { closeSync as closeSync22, fstatSync as fstatSync22, openSync as openSync22, readFileSync as readFileSync22 } from "fs";
@@ -3342,7 +3371,7 @@ function writeHookSettingsPreimage(path, settings, before) {
 // src/lib/claude-skills-coordination.ts
 import { createHash as createHash6 } from "crypto";
 
-// ../../../../validation/build/apps/hooks/node_modules/@hasna/skills/dist/index.js
+// ../../node_modules/.bun/@hasna+skills@0.9.17+a00d3064559565bb/node_modules/@hasna/skills/dist/index.js
 import { existsSync as existsSync10 } from "fs";
 import { homedir as homedir5 } from "os";
 import { join as join9, resolve as resolve3 } from "path";
@@ -34989,6 +35018,7 @@ function registerHook(name, scope = "global", target = "claude", profile, mement
   if (uniqueEventKeys.length === 0) {
     throw new Error(`Hook '${name}' has no installable events for target '${target}'`);
   }
+  const matcher = matcherFor(meta3, target);
   const settings = readSettings2(scope, target);
   if (!settings.hooks)
     settings.hooks = {};
@@ -35023,10 +35053,12 @@ function registerHook(name, scope = "global", target = "claude", profile, mement
       }
     }
     if (positions.length) {
-      if (positions.length !== uniqueEventKeys.length || uniqueEventKeys.some((event) => positions.filter((position) => position.event === event).length !== 1) || positions.some((position) => (position.entry.matcher ?? "") !== (meta3.matcher ?? ""))) {
+      if (positions.length !== uniqueEventKeys.length || uniqueEventKeys.some((event) => positions.filter((position) => position.event === event).length !== 1) || positions.some((position) => (position.entry.matcher ?? "") !== matcher && !(meta3.legacyMatchers ?? []).includes(position.entry.matcher ?? ""))) {
         throw new Error("Codex hook events, matchers or duplicate registrations require explicit reconciliation; no settings were changed.");
       }
       for (const { entry, index } of positions) {
+        if (matcher)
+          entry.matcher = matcher;
         entry.hooks[index] = { ...entry.hooks[index], type: "command", command: hookCommand };
         if (typeof meta3.timeoutSeconds === "number" && meta3.timeoutSeconds > 0)
           entry.hooks[index].timeout = meta3.timeoutSeconds;
@@ -35046,8 +35078,8 @@ function registerHook(name, scope = "global", target = "claude", profile, mement
     const entry = {
       hooks: [hookEntry]
     };
-    if (meta3.matcher) {
-      entry.matcher = meta3.matcher;
+    if (matcher) {
+      entry.matcher = matcher;
     }
     settings.hooks[eventKey].push(entry);
   }
@@ -35983,7 +36015,7 @@ function createHooksServer() {
       if (meta3 && settingsExist) {
         try {
           const settings = JSON.parse(readFileSync9(settingsPath, "utf-8"));
-          if (!hookRegisteredInSettings(settings, name, meta3.event, meta3.matcher)) {
+          if (!hookRegisteredInSettings(settings, name, meta3.event, matcherFor(meta3, "claude"))) {
             const eventName = meta3.event.split(":")[0];
             issues.push({ hook: name, issue: `Not registered under correct event (${eventName})`, severity: "error" });
             hookHealthy = false;