@hasna/hooks 0.10.1 → 0.10.3

package/dist/lib/claude-skills-coordination.d.ts

@@ -0,0 +1,8 @@
+/** The owning Skills writer commits Claude settings and discovery together.
+ * A missing policy permits ordinary standalone installation. Any other refusal
+ * propagates before settings are written; it never selects a fallback writer.
+ */
+export declare function coordinateClaudeSettings(before: string | null, replacement: string, options: {
+    home: string;
+    dataDir?: string;
+}): boolean;

package/dist/sdk/index.js

@@ -1,5 +1,5 @@
 // @bun
-// ../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 closeSync2, fstatSync as fstatSync2, openSync as openSync2, readFileSync as readFileSync2 } from "fs";

package/hooks/hook-workspace-repos-guard/README.md

@@ -32,17 +32,39 @@ Home spellings (`~`, `$HOME`, `${HOME}`, quoted or not, including split-quote
 forms like `"$HOME"/.hasna/repos/clones`, which Bash treats identically to the
 unquoted spelling) are expanded before classification; `apply_patch` tools
 are inspected through their `Add File` / `Update File` / `Delete File`
-markers; Bash relative operands are resolved against the command's cwd when
-it sits under the clones root; parenthesized command groups
-(`(cd ... && rm -rf ...)`) are unwrapped.
+markers; parenthesized command groups (`(cd ... && rm -rf ...)`) are
+unwrapped.
+
+Bash relative operands (a trailing bare name, `.`, `..`, and the operand of
+an output redirection such as `> file` or `>> file`) are resolved against the
+directory the command segment runs in, and only count when that directory is
+under a protected root. That directory starts as the command's cwd. A plain
+`cd DIR` moves it for the segments joined to it by `&&`, so
+`cd /tmp && printf x > out` is not attributed to the session cwd. After `;`,
+a newline or `||` the `cd` may have failed, so the earlier directories stay
+in scope. A `cd` inside `( ... )`, a pipeline or the background does not move
+it, and neither does a `cd` whose target cannot be resolved statically.
+Descriptor duplication (`2>&1`, `>&2`, `1>&-`) is not a write.
 
 ## Configuration
 
-Allowed orgs default to `hasna,hasnaxyz,hasna-products` and are overridable
-with the `WORKSPACE_REPOS_GUARD_ORGS` env var (comma-separated). Private
-workspace orgs must be added per-install via that var; they are never part
-of the public default. The home directory is resolved with `os.homedir()` —
-never hardcoded.
+Allowed orgs default to `hasna,hasnaxyz,hasna-products`. Private workspace
+orgs must be added per-install; they are never part of the public default.
+There are two per-install routes, checked in this order:
+
+1. The `WORKSPACE_REPOS_GUARD_ORGS` env var (comma-separated), for installs
+   that run the hook with the harness environment (`hooks run`).
+2. The file `$HOME/.hasna/hooks/config/workspace-repos-guard-orgs`. The
+   native safety registration (`hooks safety install`) runs the guard with
+   only `HOME` and `PATH`, so the env var never reaches it and this file is
+   the route that does. List the org names separated by commas or whitespace;
+   `#` starts a comment. The list replaces the default, so include the
+   default orgs you still need. The file and every directory from it up to
+   `HOME` must be owned by the user or root and not writable by group or
+   others. A missing, untrusted or malformed file is ignored and the default
+   applies.
+
+The home directory is resolved with `os.homedir()` — never hardcoded.
 
 ## Failure mode
 

package/hooks/hook-workspace-repos-guard/src/hook.ts

@@ -28,22 +28,28 @@
  *
  * Home spellings (~, $HOME, ${HOME}, including quoted forms) are expanded
  * before classification in Bash targets, file-tool paths, cd operands and
- * apply_patch file markers. Bash relative operands (`.`, `..`, bare names)
- * are resolved against the command's cwd when it sits under the repos root,
- * and against an explicit `cd` into the root when one is present. apply_patch
- * tools are inspected through their `*** Add File:` / `*** Update File:` /
- * `*** Delete File:` markers. Parenthesized command groups are unwrapped.
+ * apply_patch file markers. Bash relative operands (`.`, `..`, bare names,
+ * redirection operands) are resolved against the directory the segment runs
+ * in: the command's cwd, narrowed by a plain `cd` only across `&&` (see
+ * bashTargets). Descriptor duplication (`2>&1`, `>&2`) is not a write.
+ * apply_patch tools are inspected through their `*** Add File:` /
+ * `*** Update File:` / `*** Delete File:` markers. Parenthesized command
+ * groups are unwrapped.
  *
  * Allowed orgs default to hasna,hasnaxyz,hasna-products and are overridable
- * with the WORKSPACE_REPOS_GUARD_ORGS env var (comma-separated). Private
- * workspace orgs must be added per-install via that var; they are never part
+ * with the WORKSPACE_REPOS_GUARD_ORGS env var (comma-separated) or, where
+ * that var cannot reach the guard (the native safety supervisor passes only
+ * HOME and PATH), the per-install file
+ * $HOME/.hasna/hooks/config/workspace-repos-guard-orgs. Private workspace
+ * orgs must be added per-install through one of those; they are never part
  * of the public default.
  * Home is resolved with os.homedir(); never hardcoded. Fail-open on any parse
  * or evaluation error so a guard defect cannot wedge the agent.
  */
 
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, statSync } from "fs";
 import { homedir } from "os";
-import { isAbsolute, join, normalize, relative, resolve, sep } from "path";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "path";
 import {
   getCommand,
   readInput,
@@ -78,15 +84,67 @@ function protectedRoots(home: string): string[] {
   return [reposRoot(home), legacyRoot(home)];
 }
 
-export function resolveAllowedOrgs(env: NodeJS.ProcessEnv = process.env): Set<string> {
+/**
+ * Per-install allowed-orgs file, read from the guard's own HOME. The native
+ * safety supervisor runs this guard with only HOME and PATH, so the
+ * WORKSPACE_REPOS_GUARD_ORGS override never reaches it there; this file is the
+ * per-install route that does. Org names are separated by commas or
+ * whitespace and `#` starts a comment. The file and every directory from it
+ * up to HOME must be owned by the user or root and not writable by group or
+ * others (the supervisor's own bundle rule). A missing, untrusted, oversized
+ * or malformed file is ignored, which leaves the narrower default list.
+ */
+export function allowedOrgsFile(home: string): string {
+  return join(home, ".hasna", "hooks", "config", "workspace-repos-guard-orgs");
+}
+
+const ORG_NAME = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
+
+function ownedAndClosed(stat: { uid: number; mode: number }): boolean {
+  const uid = process.getuid?.();
+  return uid !== undefined && (stat.uid === 0 || stat.uid === uid) && (stat.mode & 0o022) === 0;
+}
+
+function readAllowedOrgsFile(home: string): Set<string> | null {
+  const file = allowedOrgsFile(home);
+  let text: string;
+  try {
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const stat = fstatSync(fd);
+      if (!stat.isFile() || !ownedAndClosed(stat) || stat.size > 4096) return null;
+      text = readFileSync(fd, "utf8");
+    } finally {
+      closeSync(fd);
+    }
+    const top = normalize(home);
+    for (let dir = dirname(file); dir !== top; dir = dirname(dir)) {
+      const stat = lstatSync(dir);
+      if (!stat.isDirectory() || !ownedAndClosed(stat) || dir === dirname(dir)) return null;
+    }
+    if (!ownedAndClosed(statSync(top))) return null;
+  } catch {
+    return null;
+  }
+  const names = text.replace(/#[^\n]*/g, "").split(/[\s,]+/).filter(Boolean);
+  return names.length > 0 && names.every((name) => ORG_NAME.test(name)) ? new Set(names) : null;
+}
+
+/**
+ * Allowed orgs: the WORKSPACE_REPOS_GUARD_ORGS env var when set, else the
+ * per-install file under `home`, else the public default.
+ */
+export function resolveAllowedOrgs(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): Set<string> {
   const raw = env.WORKSPACE_REPOS_GUARD_ORGS;
-  if (typeof raw !== "string" || !raw.trim()) return new Set(DEFAULT_ORGS);
-  return new Set(
-    raw
-      .split(",")
-      .map((s) => s.trim())
-      .filter(Boolean)
-  );
+  if (typeof raw === "string" && raw.trim()) {
+    return new Set(
+      raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    );
+  }
+  return readAllowedOrgsFile(home) ?? new Set(DEFAULT_ORGS);
 }
 
 type Operation = "read" | "write" | "delete";
@@ -139,6 +197,24 @@ export function classifyPath(target: string, root: string, orgs: Set<string>, op
 
 const WRITE_FLAGS = /\b(?:-o|--output|-O|--output-document|-out)\b/;
 
+/**
+ * Descriptor duplication or close (`2>&1`, `>&2`, `1>&-`, `0<&3`). It only
+ * rewires descriptors that are already open and names no file, so it is
+ * never a write.
+ */
+const FD_DUPLICATION = /\d*[<>]&\s*(?:\d+|-)(?=$|[\s;&|)])/g;
+
+/**
+ * An output redirection and its file operand: `>`, `>>`, `>|`, `&>`, `&>>`,
+ * `<>` and `>&word`, optionally fd-prefixed (`2>`, `2>>`). Apply it only after
+ * FD_DUPLICATION is removed, so a remaining `>&word` names a file.
+ */
+const OUTPUT_REDIRECT = /(?:\d+|&)?(?:>>|>\||>&|<>|>)\s*([^\s;&|<>()\x60]*)/g;
+
+function withoutFdDuplication(segment: string): string {
+  return segment.replace(FD_DUPLICATION, " ");
+}
+
 /**
  * Classify the operation of one command segment (a `&&`/`||`/`;`-delimited
  * unit). Git is handled by its subcommand: clean|rm delete, clone|init write,
@@ -146,7 +222,8 @@ const WRITE_FLAGS = /\b(?:-o|--output|-O|--output-document|-out)\b/;
  * in-place flag is a stream filter (redirection is caught separately);
  * rsync/scp/truncate and inline interpreters (python3 -c, node -e, bun -e)
  * are treated as writes — conservative: they only matter when a path under
- * the protected root is also present.
+ * the protected root is also present. An output redirection is a write;
+ * descriptor duplication (`2>&1`) and `&` are not.
  */
 function segmentOperation(segment: string): Operation {
   const trimmed = segment.trim();
@@ -171,7 +248,7 @@ function segmentOperation(segment: string): Operation {
   } else if (/(?:^|\s)(?:python3?|node|bun)\b[^;&|]*\s+-[ce](?:\s|$)/.test(trimmed)) {
     return "write";
   }
-  if (/(?:^|[;&|])\s*echo\b/.test(trimmed) || /[>&]/.test(trimmed)) return "write";
+  if (/(?:^|[;&|])\s*echo\b/.test(trimmed) || />/.test(withoutFdDuplication(trimmed))) return "write";
   return "read";
 }
 
@@ -224,34 +301,79 @@ function regexEscape(text: string): string {
   return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/**
+ * Directories a `cd` operand leads to from each candidate cwd, or null when
+ * the operand cannot be resolved statically (`cd -`, variables, globs,
+ * command substitution). A bare `cd` goes home.
+ */
+function cdDestinations(operand: string | undefined, bases: string[], home: string): string[] | null {
+  if (operand === undefined) return [home];
+  let word = expandHomeSpelling(operand, home);
+  const quoted = word.match(/^(['"])(.*)\1$/);
+  if (quoted) word = quoted[2];
+  if (!word || word === "-" || /[$\x60*?[\]{}~\\'"]/.test(word)) return null;
+  return [...new Set(bases.map((base) => resolve(base, word)))];
+}
+
+const REL_OPERAND = /(?:^|\s)(\.\.?|[^\s"';&|<>()\x60/]+(?:\/[^\s"';&|<>()\x60]*)?)\s*$/;
+
 /**
  * Extract protected-repo-checkout targets from a Bash command. Recognises
  * explicit `~/...`, `$HOME/...`, `${HOME}/...` and literal-home references
  * (expanded before classification) under EITHER protected root (the canonical
- * clones root or the legacy workspace/repos root), plus a trailing relative
- * operand (`.`, `..`, a bare name) when the command `cd`s into one of the
- * protected roots or the command's cwd already sits under one. Tokens outside
- * both protected roots are ignored; reads are returned so callers can decide
- * (they are never blocked).
+ * clones root or the legacy workspace/repos root). When a writing or deleting
+ * segment names no protected path, its relative operands are resolved against
+ * every directory the segment can run in, and count only when that directory
+ * sits under a protected root: the redirection operands (`> file`), plus the
+ * trailing operand (`.`, `..`, a bare name) when the command itself writes or
+ * deletes. Tokens outside both protected roots are ignored; reads are
+ * returned so callers can decide (they are never blocked).
+ *
+ * The directory a segment runs in starts as the command's cwd. A plain
+ * `cd DIR` narrows it for the segments after it only while they are joined
+ * by `&&` from the start of their and-or list, because only then do they run
+ * after a successful cd. After `;`, a newline or `||` the cd may have failed,
+ * so every directory reached so far stays in scope; a cd inside `( ... )`, a
+ * pipeline or the background does not change the outer cwd, and a cd that
+ * cannot be resolved statically never narrows it.
  */
 export function bashTargets(command: string, home: string, cwd: string): PathTarget[] {
   if (!command) return [];
   const roots = protectedRoots(home);
-  const segments = command.split(/\s*&&\s*|\s*\|\|\s*|;\s*|\n+/);
+  const underRoot = (path: string) => roots.some((root) => path === root || path.startsWith(`${root}${sep}`));
+  const parts = command.split(/(\s*&&\s*|\s*\|\|\s*|;\s*|\n+)/);
 
   const targets: PathTarget[] = [];
-  let cwdUnderRepos: string | null = null;
+  // Every directory the current segment can run in, every directory any
+  // segment so far can have left the shell in, and whether the current and-or
+  // list has only been joined by `&&` so far.
+  let current = [cwd];
+  let reachable = new Set([cwd]);
+  let certain = true;
+  const subshells: Array<{ current: string[]; reachable: Set<string>; certain: boolean }> = [];
+
+  for (let index = 0; index < parts.length; index += 2) {
+    const separator = index === 0 ? "" : parts[index - 1].trim();
+    if (separator === "||") certain = false;
+    else if (separator !== "&&") certain = true;
+    if (separator !== "&&" || !certain) current = [...reachable];
+
+    const rawSegment = parts[index];
+    const opens = (rawSegment.match(/^[\s({]*/)?.[0].match(/\(/g) ?? []).length;
+    const closes = (rawSegment.match(/[\s)}]*$/)?.[0].match(/\)/g) ?? []).length;
+    for (let i = 0; i < opens; i++) subshells.push({ current: [...current], reachable: new Set(reachable), certain });
 
-  for (const rawSegment of segments) {
     const segment = unwrapSegment(rawSegment);
     const op = segmentOperation(segment);
 
-    const cdMatch = segment.match(/(?:^|\s)cd(?:\s+(?:-[A-Za-z]+|--))*\s+([^\s;&|<>()\x60]+)/);
-    if (cdMatch) {
-      const cdTarget = expandHomeSpelling(cdMatch[1], home);
-      if (cdTarget && roots.some((root) => cdTarget === root || cdTarget.startsWith(`${root}${sep}`))) {
-        cwdUnderRepos = cdTarget;
-      }
+    const plainCd = segment.match(/^cd(?:\s+(?:-[A-Za-z@]+|--))*(?:\s+([^\s;&|<>()\x60]+))?$/);
+    const embeddedCd = plainCd ? null : segment.match(/(?:^|\s)cd(?:\s+(?:-[A-Za-z]+|--))*\s+([^\s;&|<>()\x60]+)/);
+    if (embeddedCd) {
+      // A cd sharing its segment (pipeline, background, compound command) may
+      // or may not have moved the shell: widen, never narrow.
+      for (const dir of cdDestinations(embeddedCd[1], current, home) ?? []) reachable.add(dir);
+      certain = false;
+      current = [...reachable];
     }
 
     const homeLiteral = regexEscape(home);
@@ -267,16 +389,32 @@ export function bashTargets(command: string, home: string, cwd: string): PathTar
     }
 
     if (!foundExplicit && (op === "delete" || op === "write")) {
-      const base =
-        cwdUnderRepos ??
-        (roots.some((root) => cwd === root || cwd.startsWith(`${root}${sep}`)) ? cwd : null);
-      if (base) {
-        const relMatch = segment.match(/(?:^|\s)(\.\.?|[^\s"';&|<>()\x60/]+(?:\/[^\s"';&|<>()\x60]*)?)\s*$/);
-        if (relMatch) {
-          targets.push({ path: normalize(resolve(base, relMatch[1])), op });
+      const operands: string[] = [];
+      const commandPart = withoutFdDuplication(segment).replace(OUTPUT_REDIRECT, (_match, operand: string) => {
+        if (operand) operands.push(operand);
+        return " ";
+      });
+      const commandOp = segmentOperation(commandPart);
+      const relMatch = commandOp === "read" ? null : commandPart.match(REL_OPERAND);
+      for (const base of current.filter(underRoot)) {
+        for (const operand of operands) {
+          targets.push({ path: normalize(resolve(base, expandHomeSpelling(operand, home))), op: "write" });
         }
+        if (relMatch) targets.push({ path: normalize(resolve(base, relMatch[1])), op: commandOp });
       }
     }
+
+    if (plainCd) {
+      const next = cdDestinations(plainCd[1], current, home);
+      if (next) {
+        for (const dir of next) reachable.add(dir);
+        if (certain) current = next;
+      } else {
+        certain = false;
+      }
+    }
+
+    for (let i = 0; i < closes && subshells.length > 0; i++) ({ current, reachable, certain } = subshells.pop()!);
   }
 
   return targets;
@@ -299,14 +437,15 @@ export function patchTargets(patch: string, cwd: string): PathTarget[] {
   return targets;
 }
 
-export function evaluate(input: CodewithHookInput): { output: CodewithHookOutput; warnings: string[] } {
+/** `options.home` defaults to os.homedir(); tests pass a private home. */
+export function evaluate(input: CodewithHookInput, options: { home?: string } = {}): { output: CodewithHookOutput; warnings: string[] } {
   const warnings: string[] = [];
   if (input.hook_event_name !== "PreToolUse") return { output: { continue: true }, warnings };
 
   const tool = typeof input.tool_name === "string" ? input.tool_name : "";
-  const home = homedir();
+  const home = options.home ?? homedir();
   const roots = protectedRoots(home);
-  const orgs = resolveAllowedOrgs();
+  const orgs = resolveAllowedOrgs(process.env, home);
 
   if (tool === "Bash") {
     const command = getCommand(input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
@@ -60,6 +60,7 @@
     "@hasna/contracts": "~1.2.1"
   },
   "dependencies": {
+    "@hasna/skills": "0.9.14",
     "@hasna/events": "^0.1.16",
     "@hasna/secrets": "0.4.2",
     "@modelcontextprotocol/sdk": "^1.26.0",