@hasna/hooks 0.4.0 → 0.5.0

package/hooks/pre-bash/README.md

@@ -6,8 +6,78 @@ This hook is OSS-safe: optional Hasna CLIs are best-effort and missing CLIs fail
 
 It also blocks scoped destructive shell operations such as recursive `rm`,
 `rsync --delete`, destructive `find`, and destructive `git clean` / `git reset
---hard` forms only when the resolved target threatens `~/.hasna`, configured
-workspace roots, Hasna division/scope roots, or active repo/worktree roots.
+--hard` forms when the resolved target threatens a protected root.
+
+## Protected roots
+
+- `/` and the system directories (`/usr`, `/etc`, `/bin`, `/lib`, `/var`, `/boot`,
+  `/home`, `/Users`, and the other FHS and macOS equivalents). Add machine-specific
+  entries with `HASNA_PROTECTED_SYSTEM_ROOTS` (colon-separated). `/tmp` is not
+  protected — scratch cleanup there is routine.
+- `~/.hasna`, configured workspace roots, Hasna division/scope roots, and active
+  repo/worktree roots.
+
+These match in *root* mode: wiping a root or its contents (`rm -rf /usr`,
+`rm -rf /usr/*`) blocks, while a targeted delete beneath one
+(`rm -rf /usr/local/lib/my-build`) is allowed.
+
+## Expansions that can collapse to empty
+
+A destructive target containing a command substitution, backtick substitution or
+variable expansion is checked twice: as written, and as the shell would render it
+if the expansion returned empty. `rm -rf "$(anything)"/*`, `` rm -rf `cmd`/* ``,
+`rm -rf "$VAR"/*` and `rm -rf "${VAR}"/*` are blocked by shape, whatever the
+expansion is.
+
+This exists because of a realized incident: `bun pm cache` exits non-zero with an
+empty stdout when no `package.json` is found walking up from cwd, so
+`rm -rf "$(bun pm cache)"/*` ran as `rm -rf /*`. Redirecting stderr does not help
+— it discards the diagnostic, not the path.
+
+Two forms are deliberately not blocked:
+
+- `${VAR:?}` / `${VAR:?message}`, which POSIX guarantees non-empty. (`${VAR?}`
+  without the colon permits an empty value and is *not* exempt.)
+- A bare `rm -rf "$(cmd)"` with no trailing separator, which degrades to
+  `rm -rf ""` — rejected by `rm` without deleting anything.
+
+The recommended form is to resolve the path first and assert it:
+
+```bash
+dir="$(bun pm cache)" || exit 1
+case "$dir" in /|"") exit 1;; esac
+rm -rf -- "$dir"
+```
+
+## Globs
+
+A glob threatens a protected root when it can match that root or an ancestor of it, or when it
+wipes the root's contents wholesale. Matching is per path component, so a trailing literal
+bounds the delete: `rm -rf */node_modules` at a monorepo root is allowed, while `rm -rf /*/*`
+is not.
+
+A glob directly under a protected root is refused only when it is *unanchored* — when no
+literal text survives once the wildcards are removed. `[a-z]*`, `?*`, `.??*` and `*.*` are
+unanchored and blocked; `*.log`, `tmp-*`, `.turbo*` and `snapshot-[0-9]*` keep their literal
+anchor and are allowed.
+
+Bracket expressions that this matcher does not model exactly — POSIX `[:class:]`, `[=equiv=]`,
+`[.collate.]`, backslash escapes, anything unterminated — are treated as **matching**, never as
+not-matching. An under-match would leave a protected root unmatched and allow the delete, so
+ambiguity resolves toward refusing.
+
+## Working directory
+
+`cd`, `pushd`, `pushd -n`, `popd` and `cd -` are tracked, per subshell, with a directory stack.
+A `cd` inside `( … )` or a pipeline stage applies within that shell and does not escape it.
+
+## Wrappers
+
+Commands are unwrapped before scanning: `bash -c` / `sh -c` / `zsh -c`, `su -c`,
+`runuser -c`, `eval`, and `ssh host '…'`, including nested combinations. `cd` is
+tracked within a command, and a `for VAR in <glob>` binding is followed into
+`rm -rf "$VAR"`. Remote (`ssh`) layers only consider absolute targets, because a
+remote relative path cannot be resolved against the local working directory.
 
 ## Install for Codewith
 

package/hooks/worktree-guard/README.md

@@ -5,8 +5,59 @@ Codewith-native hook installed as `hooks run worktree-guard`.
 This hook is OSS-safe: optional Hasna CLIs are best-effort and missing CLIs fail open with concise warnings. Security gates only fail closed when a guarded commit/push scan runs successfully and finds possible secrets.
 
 It blocks scoped destructive shell operations and file-tool-like payloads when
-the resolved target threatens `~/.hasna`, configured workspace roots, Hasna
-division/scope roots, or active repo/worktree roots.
+the resolved target threatens `/` or a system root (`/usr`, `/etc`, `/var`,
+`/home`, …), `~/.hasna`, configured workspace roots, Hasna division/scope roots,
+or active repo/worktree roots.
+
+It shares its classifier with `pre-bash`, so it also blocks destructive targets
+whose command substitution or variable expansion could collapse to empty —
+`rm -rf "$(cmd)"/*` and `rm -rf "$VAR"/*`. See
+[`hooks/pre-bash/README.md`](../pre-bash/README.md) for the full rules and the
+recommended safe form.
+
+## Canonical worktree path
+
+Git work is expected to happen in a task-specific worktree at the canonical path
+from Hasna Agent Operating Rules rule 8 (published by `@hasna/identities`):
+
+```
+$HOME/.hasna/repos/worktrees/<repo-name>/<worktree-name>
+```
+
+Repo name, then worktree name. Anything else is reported as unmanaged, with a
+reason: a flat single-segment worktree directly under the worktrees root, a
+station-id or machine segment in front of the repo name, and any deeper nesting
+are all rejected. Subdirectories of a canonical worktree are accepted.
+
+The classification is grounded in verified git provenance, not path shape. The
+two-segment path must be a real worktree root, no segment may be a symlink, and
+its `.git` must prove it owns its own history: a `.git` file's `gitdir:` target
+has to live under its repository's `worktrees/` directory and point back at this
+control file, and a `.git` directory must not be grafted on by a `commondir`.
+
+Shape alone proves nothing. `<root>/<flat-worktree>/<subdir>` has exactly the
+canonical shape, so a `cd` would otherwise launder a forbidden flat worktree into
+a compliant one; and a symlink or a two-line forged `.git` file would aim a
+compliant-looking path at a shared checkout, making `git commit` land there.
+
+Override the worktrees root with `HASNA_REPOS_WORKTREES_ROOT`.
+
+## Deprecated: the station-id lease layout
+
+The pre-rule-8 layout `<station-id>/<repo-slug>-<hex>/wt_<hex>` is deprecated and
+is never classified as a compliant worktree. Two migration tolerances keep
+existing worktrees working while they are re-homed:
+
+- git work there warns instead of being blocked, so in-flight tasks can still land;
+- it keeps its scoped `~/.hasna` write carve-out.
+
+Both are temporary. Re-home these worktrees to the canonical path, then set
+`HASNA_HOOKS_LEGACY_WORKTREE_TOLERANCE=0`; the branch is removed after that.
+
+The tolerance still requires the same provenance proof as the canonical path — it
+softens the verdict, it does not skip the check. It does key off the path name, so
+a worktree deliberately named to match also gets the warn tier; that is an opt-out
+from a guardrail by a cooperating agent, not a way to reach a shared checkout.
 
 ## Install for Codewith
 

package/hooks/worktree-guard/src/hook.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env bun
 
 import {
+  canonicalRepoIdentity,
+  canonicalWorktreeTemplate,
   classifyDangerousOperation,
   claimCommand,
   gitCommandInfo,
@@ -10,7 +12,6 @@ import {
   managedWorktreeInfo,
   readInput,
   respond,
-  runIdFrom,
   taskIdFrom,
   warn,
   type CodewithHookInput,
@@ -40,27 +41,63 @@ export async function evaluate(input: CodewithHookInput): Promise<{ output: Reco
   const managed = managedWorktreeInfo(targetCwd);
   if (managed.managed) return { output: { continue: true }, warnings };
 
+  // Migration shim, temporary and deliberately narrow: worktrees created under the
+  // pre-rule-8 station-id lease layout are non-compliant, but they are real, active
+  // worktrees. Hard-blocking their git work on day one would strand in-flight tasks
+  // with no way to land, so this one recognised layout warns instead of blocking.
+  // Everything else non-canonical is still blocked. Remove once they are re-homed.
+  if (managed.layout === "legacy-station-lease") {
+    const message = `${managed.reason}. This layout will stop being tolerated; re-home this worktree.`;
+    warnings.push(message);
+    return {
+      output: {
+        continue: true,
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: `[worktree-guard] ${message}`,
+        },
+      },
+      warnings,
+    };
+  }
+
   const repoRoot = await gitRepoRoot(targetCwd);
-  const repo = await gitRemoteSlug(targetCwd) || (repoRoot ? repoRoot.split("/").filter(Boolean).pop() || null : null);
+  // Rule 8 resolution order: the repos CLI is the source of truth for <repo-name>.
+  // The local checkout directory is the next best guess, and the remote slug is the
+  // last resort — for most repos the remote basename is NOT the canonical repo name.
+  const identity = await canonicalRepoIdentity(targetCwd);
+  const repo = identity.name
+    || (repoRoot ? repoRoot.split("/").filter(Boolean).pop() || null : null)
+    || (await gitRemoteSlug(targetCwd))?.split("/").filter(Boolean).pop()
+    || null;
   const taskId = taskIdFrom(input);
-  const runId = runIdFrom(input);
-  const recommended = claimCommand(repo, taskId, runId);
+  const recommended = claimCommand(repo, taskId, identity.defaultBranch);
   const action = gitInfo?.action || null;
+  const canonical = canonicalWorktreeTemplate(managed.root);
+  // Rule 8 requires an exact repos-CLI lookup for <repo-name>. When that lookup did
+  // not resolve, the name below is a local guess, so say so rather than imply it is
+  // authoritative — the repo directory name and the remote basename often differ.
+  const unverifiedRepoName = identity.name
+    ? null
+    : `Confirm <repo-name> with an exact repos CLI lookup first: repos repo ${repo || "<name>"} --json`;
 
   if (action) {
     const reason = [
-      `Blocked git ${action} outside a managed repos worktree (${managed.reason || "not under managed root"}).`,
+      `Blocked git ${action} outside a canonical task worktree (${managed.reason || "not under managed root"}).`,
       `Command target cwd: ${targetCwd}`,
-      `Managed root: ${managed.root}`,
-      `Claim a task worktree first: ${recommended}`,
+      `Canonical worktree path (Agent Operating Rules rule 8): ${canonical}`,
+      `Create one first: ${recommended}`,
+      ...(unverifiedRepoName ? [unverifiedRepoName] : []),
     ].join(" ");
     return { output: { decision: "block", reason }, warnings };
   }
 
   if (isFeatureWork(input, command)) {
     warnings.push([
-      `Feature work appears to be outside a managed repos worktree (${managed.reason || "not under managed root"}).`,
+      `Feature work appears to be outside a canonical task worktree (${managed.reason || "not under managed root"}).`,
+      `Canonical worktree path (Agent Operating Rules rule 8): ${canonical}.`,
       `Use: ${recommended}`,
+      ...(unverifiedRepoName ? [unverifiedRepoName] : []),
     ].join(" "));
     return {
       output: {
@@ -91,4 +128,9 @@ export async function run(): Promise<void> {
 
 if (import.meta.main) {
   await run();
+  // The verdict is written, so the hook is done. Exit rather than waiting for the
+  // event loop to drain: an optional CLI consulted during evaluation may have left a
+  // grandchild holding a pipe open, and a hook that has already answered must never
+  // keep the caller's PreToolUse path waiting on it.
+  process.exit(0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {