@hasna/hooks 0.5.0 → 0.6.1

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

@@ -0,0 +1,312 @@
+import { describe, test, expect } from "bun:test";
+import { homedir } from "os";
+import { join } from "path";
+import { evaluate, resolveAllowedOrgs } from "./hook";
+
+const HOME = homedir();
+const REPOS = join(HOME, "workspace", "repos");
+
+function preToolUse(tool_name: string, tool_input: Record<string, unknown>, cwd = join(REPOS, "hasna", "apps")) {
+  return { hook_event_name: "PreToolUse", tool_name, tool_input, cwd };
+}
+
+function isBlocked(result: { output: { decision?: string; reason?: string } }): string | null {
+  if (result.output.decision === "block") return result.output.reason ?? "blocked";
+  return null;
+}describe("hook-workspace-repos-guard", () => {
+  describe("resolveAllowedOrgs", () => {
+    test("defaults to the four canonical GitHub orgs", () => {
+      expect([...resolveAllowedOrgs({})].sort()).toEqual(["hasna", "hasna-internal", "hasna-products", "hasnaxyz"]);
+    });
+
+    test("parses comma-separated env override, trimming whitespace and empties", () => {
+      expect([...resolveAllowedOrgs({ WORKSPACE_REPOS_GUARD_ORGS: " hasna ,  myorg ,, " })].sort()).toEqual(["hasna", "myorg"]);
+    });
+  });
+
+  describe("positive controls — must continue", () => {
+    test("Write deep inside an allowed org checkout continues", () => {
+      const result = evaluate(preToolUse("Write", { file_path: join(REPOS, "hasna", "apps", "apps", "foo", "src", "index.ts") }));
+      expect(result.output.continue).toBe(true);
+      expect(isBlocked(result)).toBeNull();
+    });
+
+    test("Edit inside hasna-internal org continues", () => {
+      const result = evaluate(preToolUse("Edit", { file_path: join(REPOS, "hasna-internal", "platform", "docs", "readme.md") }));
+      expect(result.output.continue).toBe(true);
+    });
+
+    test("MultiEdit with relative file_path resolves against cwd and continues inside allowed org", () => {
+      const result = evaluate(preToolUse("MultiEdit", { file_path: "apps/hooks/src/lib/registry.ts" }));
+      expect(result.output.continue).toBe(true);
+    });
+
+    test("NotebookEdit inside allowed org continues", () => {
+      const result = evaluate(preToolUse("NotebookEdit", { notebook_path: join(REPOS, "hasnaxyz", "iapp-probe", "probe.ipynb") }));
+      expect(result.output.continue).toBe(true);
+    });
+
+    test("Bash read commands under repos are never blocked", () => {
+      const reads = [
+        `ls ${REPOS}`,
+        `cat ${join(REPOS, "hasna", "apps", "README.md")}`,
+        `git -C ${join(REPOS, "hasna", "apps")} status`,
+        `cd ${REPOS} && git pull`,
+        `find ${join(REPOS, "hasna")} -name AGENTS.md`,
+      ];
+      for (const command of reads) {
+        const result = evaluate(preToolUse("Bash", { command }));
+        expect(result.output.continue).toBe(true);
+      }
+    });
+
+    test("Bash write deep inside an allowed org checkout continues", () => {
+      const commands = [
+        `echo note > ${join(REPOS, "hasna", "apps", "scratch.md")}`,
+        `touch ${join(REPOS, "hasna", "apps", "apps", "foo", "x.txt")}`,
+        `git clone https://github.com/hasna/foo.git ${join(REPOS, "hasna", "foo")}`,
+        `mkdir -p ${join(REPOS, "hasna-internal", "platform", "apps")}`,
+      ];
+      for (const command of commands) {
+        const result = evaluate(preToolUse("Bash", { command }));
+        expect(result.output.continue).toBe(true);
+      }
+    });
+
+    test("tilde/$HOME spellings of deep allowed-org writes continue", () => {
+      const commands = [
+        `touch ~/workspace/repos/hasna/apps/foo.md`,
+        `echo x > ~/workspace/repos/hasnaxyz/iapp-probe/notes.md`,
+        `mkdir -p "${HOME}/workspace/repos/hasna-internal/platform/apps"`,
+        `touch "$HOME"/workspace/repos/hasna/apps/x.txt`,
+        `echo x > "\${HOME}"/workspace/repos/hasnaxyz/iapp-probe/notes.md`,
+      ];
+      for (const command of commands) {
+        const result = evaluate(preToolUse("Bash", { command }));
+        expect(result.output.continue).toBe(true);
+      }
+    });
+
+    test("file-tool tilde/$HOME paths deep inside an allowed org continue", () => {
+      const results = [
+        evaluate(preToolUse("Write", { file_path: `~/workspace/repos/hasna/apps/src/x.ts` })),
+        evaluate(preToolUse("Edit", { file_path: `$HOME/workspace/repos/hasnaxyz/iapp-probe/n.ipynb` })),
+        evaluate(preToolUse("Write", { file_path: `"${HOME}/workspace/repos/hasna/apps/notes.md"` })),
+        evaluate(preToolUse("Write", { file_path: `"$HOME"/workspace/repos/hasna/apps/notes2.md` })),
+      ];
+      for (const result of results) {
+        expect(result.output.continue).toBe(true);
+      }
+    });
+
+    test("apply_patch Add/Update File deep inside an allowed org continues", () => {
+      const result = evaluate(
+        preToolUse("apply_patch", {
+          patch: `*** Begin Patch\n*** Add File: apps/hooks/src/lib/registry.ts\n+export const x = 1;\n*** End Patch`,
+        })
+      );
+      expect(result.output.continue).toBe(true);
+    });
+
+    test("non-mutating sed without -i, and interpreter without a path, continue", () => {
+      const commands = [
+        `sed 's/a/b/' ${join(REPOS, "hasna", "apps", "README.md")}`,
+        `node -e "console.log('no path here')"`,
+        `python3 -c "print('no path here')"`,
+      ];
+      for (const command of commands) {
+        const result = evaluate(preToolUse("Bash", { command }));
+        expect(result.output.continue).toBe(true);
+      }
+    });
+
+    test("non-PreToolUse events and non-file tools are ignored", () => {
+      const result = evaluate({ hook_event_name: "PostToolUse", tool_name: "Write", tool_input: { file_path: join(REPOS, "hasna", "x.ts") } });
+      expect(result.output.continue).toBe(true);
+      const read = evaluate(preToolUse("Read", { file_path: join(REPOS, "hasna", "apps", "README.md") }));
+      expect(read.output.continue).toBe(true);
+    });
+  });
+
+  describe("negative controls — must block", () => {
+    test("Write to ~/workspace/repos itself is blocked", () => {
+      const result = evaluate(preToolUse("Write", { file_path: join(REPOS, "stray.txt") }));
+      const reason = isBlocked(result);
+      expect(reason).not.toBeNull();
+      expect(reason).toContain("workspace-repos-guard");
+    });
+
+    test("Write to the repos root directory entry is blocked", () => {
+      const result = evaluate(preToolUse("Edit", { file_path: REPOS }));
+      expect(isBlocked(result)).not.toBeNull();
+    });
+
+    test("Write whose second segment is not an allowed org is blocked", () => {
+      const result = evaluate(preToolUse("Write", { file_path: join(REPOS, "notanorg", "x", "file.ts") }));
+      const reason = isBlocked(result);
+      expect(reason).not.toBeNull();
+      expect(reason).toContain("notanorg");
+    });
+
+    test("Write creating a top-level entry under repos (org-level, no deeper path) is blocked", () => {
+      const result = evaluate(preToolUse("Write", { file_path: join(REPOS, "hasna") }));
+      expect(isBlocked(result)).not.toBeNull();
+    });
+
+    test("rm -rf deep inside an allowed org checkout is blocked", () => {
+      const result = evaluate(preToolUse("Bash", { command: `rm -rf ${join(REPOS, "hasna", "apps", ".git")}` }));
+      const reason = isBlocked(result);
+      expect(reason).not.toBeNull();
+      expect(reason).toContain("delete");
+    });
+
+    test("rmdir of an org folder is blocked", () => {
+      const result = evaluate(preToolUse("Bash", { command: `rmdir ${join(REPOS, "oldorg")}` }));
+      expect(isBlocked(result)).not.toBeNull();
+    });
+
+    test("git clean inside a checkout is blocked", () => {
+      const result = evaluate(preToolUse("Bash", { command: `git -C ${join(REPOS, "hasna", "apps")} clean -fd` }));
+      expect(isBlocked(result)).not.toBeNull();
+    });
+
+    test("rm -rf of the repos root itself is blocked", () => {
+      const result = evaluate(preToolUse("Bash", { command: `rm -rf ${REPOS}` }));
+      expect(isBlocked(result)).not.toBeNull();
+    });
+
+    test("cd into repos followed by rm -rf . is blocked via relative resolution", () => {
+      const result = evaluate(preToolUse("Bash", { command: `cd ${REPOS} && rm -rf .` }));
+      expect(isBlocked(result)).not.toBeNull();
+    });
+
+    test("top-level non-org folder creation via Bash is blocked", () => {
+      const commands = [
+        `mkdir -p ${join(REPOS, "notanorg")}`,
+        `mkdir -p ${join(REPOS, "notanorg", "sub")}`,
+        `touch ${join(REPOS, "neworg", "x")}`,
+        `mv ${join(REPOS, "hasna", "apps", "a")} ${join(REPOS, "anotherorg")}`,
+      ];
+      for (const command of commands) {
+        const result = evaluate(preToolUse("Bash", { command }));
+        expect(isBlocked(result)).not.toBeNull();
+      }
+    });
+
+    test("Bash write into a non-allowed org folder is blocked", () => {
+      const result = evaluate(preToolUse("Bash", { command: `echo x > ${join(REPOS, "notanorg", "deep", "f.ts")}` }));
+      const reason = isBlocked(result);
+      expect(reason).not.toBeNull();
+      expect(reason).toContain("notanorg");
+    });
+
+    test("delete via git rm is blocked", () => {
+      const result = evaluate(preToolUse("Bash", { command: `git -C ${join(REPOS, "hasna", "apps")} rm src/foo.ts` }));
+      expect(isBlocked(result)).not.toBeNull();
+    });
+
+    test("tilde/$HOME spellings of the protected path are blocked", () => {
+      const commands = [
+        `rm -rf ~/workspace/repos`,
+        `rm -rf ~/workspace/repos/hasna/apps`,
+        `rm -rf $HOME/workspace/repos/hasna`,
+        `rm -rf "${HOME}/workspace/repos"`,
+        `rm -rf "$HOME"/workspace/repos`,
+        `rm -rf "$HOME"/workspace/repos/hasna/apps`,
+        `rm -rf "\${HOME}"/workspace/repos/hasna`,
+        `rm -rf "${HOME}"/workspace/repos/hasna`,
+        `touch ~/workspace/repos/stray.txt`,
+        `mkdir -p ~/workspace/repos/notanorg`,
+        `echo x > ~/workspace/repos/notanorg/f.ts`,
+        `mv /tmp/x ~/workspace/repos`,
+        `truncate -s 0 ~/workspace/repos/stray.log`,
+        `rsync -a /tmp/x ~/workspace/repos/`,
+        `scp f.txt ~/workspace/repos/`,
+      ];
+      for (const command of commands) {
+        const result = evaluate(preToolUse("Bash", { command }));
+        expect(isBlocked(result), `expected BLOCK for: ${command}`).not.toBeNull();
+      }
+    });
+
+    test("file-tool tilde/$HOME spellings are blocked", () => {
+      const results = [
+        evaluate(preToolUse("Write", { file_path: `~/workspace/repos/stray.txt` })),
+        evaluate(preToolUse("Write", { file_path: `$HOME/workspace/repos/notanorg/f.ts` })),
+        evaluate(preToolUse("Edit", { file_path: `~/workspace/repos/hasna` })),
+        evaluate(preToolUse("Write", { file_path: `~/workspace/repos` })),
+        evaluate(preToolUse("Write", { file_path: `"$HOME"/workspace/repos/stray.txt` })),
+      ];
+      for (const result of results) {
+        expect(isBlocked(result)).not.toBeNull();
+      }
+    });
+
+    test("subshell-grouped cd + rm is blocked", () => {
+      const commands = [
+        `(cd ~/workspace/repos && rm -rf hasna)`,
+        `(cd ${REPOS} && rm -rf hasna)`,
+        `( cd ${REPOS} && touch stray.txt )`,
+      ];
+      for (const command of commands) {
+        const result = evaluate(preToolUse("Bash", { command }));
+        expect(isBlocked(result), `expected BLOCK for: ${command}`).not.toBeNull();
+      }
+    });
+
+    test("cwd-relative deletes without an explicit cd are blocked", () => {
+      const fromCheckout = evaluate(preToolUse("Bash", { command: `rm -rf ../` }, join(REPOS, "hasna", "apps")));
+      expect(isBlocked(fromCheckout)).not.toBeNull();
+      const fromRoot = evaluate(preToolUse("Bash", { command: `mkdir -p notanorg` }, REPOS));
+      expect(isBlocked(fromRoot)).not.toBeNull();
+      const bareRm = evaluate(preToolUse("Bash", { command: `rm -rf .` }, join(REPOS, "hasnaxyz")));
+      expect(isBlocked(bareRm)).not.toBeNull();
+    });
+
+    test("mutating verbs writing under the protected root are blocked", () => {
+      const commands = [
+        `sed -i 's/x/y/' ~/workspace/repos/stray.txt`,
+        `rsync -a ${join(REPOS, "hasna")} /tmp/out`,
+        `scp -r ${join(REPOS, "hasna")} other:/tmp/`,
+        `truncate -s 0 ${join(REPOS, "notanorg", "f.ts")}`,
+        `python3 -c "open('~/workspace/repos/stray.txt','w')"`,
+        `node -e "require('fs').writeFileSync('${join(REPOS, "notanorg", "f.ts")}','x')"`,
+      ];
+      for (const command of commands) {
+        const result = evaluate(preToolUse("Bash", { command }));
+        expect(isBlocked(result), `expected BLOCK for: ${command}`).not.toBeNull();
+      }
+    });
+
+    test("apply_patch Delete File and shallow Add File are blocked", () => {
+      const del = evaluate(
+        preToolUse("ApplyPatch", {
+          patch: `*** Begin Patch\n*** Delete File: src/foo.ts\n*** End Patch`,
+        })
+      );
+      expect(isBlocked(del)).not.toBeNull();
+      const shallow = evaluate(
+        preToolUse("functions.apply_patch", {
+          patch: `*** Begin Patch\n*** Add File: ../../stray.txt\n+x\n*** End Patch`,
+        })
+      );
+      expect(isBlocked(shallow)).not.toBeNull();
+    });
+  });
+
+  describe("orgs env override", () => {
+    test("override widens and narrows the allowed set", () => {
+      const previous = process.env.WORKSPACE_REPOS_GUARD_ORGS;
+      try {
+        process.env.WORKSPACE_REPOS_GUARD_ORGS = "hasna,myorg";
+        const allowed = evaluate(preToolUse("Write", { file_path: join(REPOS, "myorg", "proj", "f.ts") }));
+        expect(allowed.output.continue).toBe(true);
+        const narrowed = evaluate(preToolUse("Write", { file_path: join(REPOS, "hasnaxyz", "iapp-x", "f.ts") }));
+        expect(isBlocked(narrowed)).not.toBeNull();
+      } finally {
+        if (previous === undefined) delete process.env.WORKSPACE_REPOS_GUARD_ORGS;
+        else process.env.WORKSPACE_REPOS_GUARD_ORGS = previous;
+      }
+    });
+  });
+});

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

@@ -0,0 +1,352 @@
+#!/usr/bin/env bun
+
+/**
+ * PreToolUse hook: workspace-repos-guard
+ *
+ * Guards the canonical workspace structure (knowledge k_mssu9jdq_dgnnu2):
+ * $HOME/workspace contains ONLY repos/ + scratch/ + AGENTS.md, and repos/
+ * contains ONLY GitHub-org folders. Checkouts at
+ * $HOME/workspace/repos/<org>/<repo>/ are read/context only.
+ *
+ * Structure-only guard — it deliberately does NOT duplicate the worktree-guard
+ * hook, which owns edits-in-shared-checkouts semantics.
+ *
+ * BLOCKS:
+ *   - any write to $HOME/workspace/repos itself (file tools and Bash),
+ *   - any write that would create a top-level entry under repos/ (depth <= 1),
+ *   - any write whose second path segment is not an allowed GitHub org,
+ *   - any delete (rm, rmdir, git clean, git rm, unlink, shred, trash, ...)
+ *     anywhere under $HOME/workspace/repos, at any depth.
+ *
+ * ALLOWS (structure only):
+ *   - reads, always,
+ *   - writes deeper inside an allowed org folder (repos/<org>/<repo>/...).
+ *
+ * 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.
+ *
+ * Allowed orgs default to hasna,hasnaxyz,hasna-internal,hasna-products and are
+ * overridable with the WORKSPACE_REPOS_GUARD_ORGS env var (comma-separated).
+ * 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 { homedir } from "os";
+import { isAbsolute, join, normalize, relative, resolve, sep } from "path";
+import {
+  getCommand,
+  readInput,
+  respond,
+  warn,
+  type CodewithHookInput,
+  type CodewithHookOutput,
+} from "../../codewith-native-common";
+
+const FILE_WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+
+const PATCH_TOOLS = new Set(["apply_patch", "ApplyPatch", "functions.apply_patch"]);
+
+const DEFAULT_ORGS = ["hasna", "hasnaxyz", "hasna-internal", "hasna-products"];
+
+const RULE = "workspace-repos-guard";
+
+function reposRoot(home: string): string {
+  return join(home, "workspace", "repos");
+}
+
+export function resolveAllowedOrgs(env: NodeJS.ProcessEnv = process.env): 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)
+  );
+}
+
+type Operation = "read" | "write" | "delete";
+
+interface Verdict {
+  blocked: boolean;
+  reason?: string;
+}
+
+/**
+ * Classify a single absolute target path against the repos root. Structure
+ * only: a write at depth >= 2 inside an allowed org passes, and anything else
+ * (deletes at any depth, writes at the root or org level, writes into a
+ * non-allowed org) is blocked. Paths outside the repos root are not this
+ * hook's concern and pass.
+ */
+export function classifyPath(target: string, root: string, orgs: Set<string>, op: Operation): Verdict {
+  if (op === "read") return { blocked: false };
+  let rel = relative(root, target);
+  if (rel === "") {
+    if (op === "delete") return { blocked: true, reason: `[${RULE}] delete of the repos root is forbidden: ${root}` };
+    return { blocked: true, reason: `[${RULE}] writes directly to the repos root are forbidden: ${root}` };
+  }
+  if (rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel)) {
+    return { blocked: false };
+  }
+  const segments = rel.split(sep).filter(Boolean);
+
+  if (op === "delete") {
+    return { blocked: true, reason: `[${RULE}] delete under ~/workspace/repos is forbidden at any depth: ${target}` };
+  }
+
+  if (segments.length <= 1) {
+    return {
+      blocked: true,
+      reason: `[${RULE}] writing would create a top-level entry directly under repos/; only GitHub-org folders belong there: ${target}`,
+    };
+  }
+
+  const org = segments[0];
+  if (!orgs.has(org)) {
+    return {
+      blocked: true,
+      reason: `[${RULE}] '${org}' is not an allowed GitHub org under ~/workspace/repos (allowed: ${[...orgs].join(", ")}): ${target}`,
+    };
+  }
+
+  return { blocked: false };
+}
+
+const WRITE_FLAGS = /\b(?:-o|--output|-O|--output-document|-out)\b/;
+
+/**
+ * Classify the operation of one command segment (a `&&`/`||`/`;`-delimited
+ * unit). Git is handled by its subcommand: clean|rm delete, clone|init write,
+ * everything else (status/pull/fetch/log/diff/...) is read. Sed without an
+ * 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.
+ */
+function segmentOperation(segment: string): Operation {
+  const trimmed = segment.trim();
+  if (!trimmed) return "read";
+
+  if (/(?:^|\s)(?:rm|rmdir|unlink|shred|trash|rmtree|del)(?:\s|$)/.test(trimmed)) return "delete";
+  if (/\bgit\b/.test(trimmed)) {
+    if (/\bgit\b[^;&|]*\b(?:clean|rm)\b/.test(trimmed)) return "delete";
+    if (/\bgit\b[^;&|]*\b(?:clone|init)\b/.test(trimmed)) return "write";
+    return "read";
+  }
+  if (/(?:^|\s)(?:mkdir|mkfile|touch|mv|cp|ln|tee|install|dd)(?:\s|$)/.test(trimmed)) return "write";
+  if (/\b(?:curl|wget)\b/.test(trimmed)) {
+    if (WRITE_FLAGS.test(trimmed)) return "write";
+    return "read";
+  }
+  if (/\bsed\b/.test(trimmed)) {
+    if (/(?:^|\s)-i\S*(?:\s|$)|--in-place(?:\s|$)/.test(trimmed)) return "write";
+    // sed without -i is a filter; `>` redirection is caught by the check below.
+  } else if (/\b(?:rsync|scp|truncate)\b/.test(trimmed)) {
+    return "write";
+  } else if (/(?:^|\s)(?:python3?|node|bun)\b[^;&|]*\s+-[ce](?:\s|$)/.test(trimmed)) {
+    return "write";
+  }
+  if (/(?:^|[;&|])\s*echo\b/.test(trimmed) || /[>&]/.test(trimmed)) return "write";
+  return "read";
+}
+
+interface PathTarget {
+  path: string;
+  op: Operation;
+}
+
+/**
+ * Expand one token's home spelling (`~`, `~/...`, `$HOME`, `$HOME/...`,
+ * `${HOME}`, `${HOME}/...`) to the resolved home, tolerating a single layer
+ * of wrapping single/double quotes and a closing quote between the home
+ * token and its path suffix (`"$HOME"/x`, `"${HOME}"/x` — Bash treats these
+ * identically to the unquoted form, because double quotes allow parameter
+ * expansion and adjacent quoted/unquoted parts concatenate into one word).
+ * Non-home spellings are returned unchanged.
+ */
+export function expandHomeSpelling(token: string, home: string): string {
+  let body = token.trim();
+  const quoted = body.match(/^(['"])([\s\S]*)\1$/);
+  if (quoted) body = quoted[2];
+  // Split-quote forms — `"$HOME"/x`, `"${HOME}"/x`, `"/home/hasna"/x`: the
+  // quotes wrap only the home token, and Bash concatenates the adjacent
+  // quoted and unquoted parts into the same word as the unquoted spelling.
+  body = body.replace(/^"*\$HOME"*\//, "$HOME/");
+  body = body.replace(/^"*\$\{HOME\}"*\//, "${HOME}/");
+  if (body === "~") return home;
+  if (body.startsWith("~/")) return join(home, body.slice(2));
+  if (body === "$HOME" || body === "${HOME}") return home;
+  if (body.startsWith("$HOME/")) return join(home, body.slice("$HOME/".length));
+  if (body.startsWith("${HOME}/")) return join(home, body.slice("${HOME}/".length));
+  const homeMatch = body.match(new RegExp(`^"*${regexEscape(home)}"*/`));
+  if (homeMatch) return home + "/" + body.slice(homeMatch[0].length);
+  return token;
+}
+
+/**
+ * Strip one level of wrapping shell-group punctuation from a segment so a
+ * subshell group like `(cd ~/workspace/repos && rm -rf hasna)` is analysed as
+ * its parts after the `&&` split.
+ */
+function unwrapSegment(segment: string): string {
+  let s = segment.trim();
+  while (s.startsWith("(") || s.startsWith("{")) s = s.slice(1).trim();
+  while (s.endsWith(")") || s.endsWith("}")) s = s.slice(0, -1).trim();
+  return s;
+}
+
+function regexEscape(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Extract workspace-repos targets from a Bash command. Recognises explicit
+ * `~/...`, `$HOME/...`, `${HOME}/...` and literal-home references (expanded
+ * before classification), plus a trailing relative operand (`.`, `..`, a bare
+ * name) when the command `cd`s into the repos root or the command's cwd
+ * already sits under it. Tokens outside the repos root are ignored; reads are
+ * returned so callers can decide (they are never blocked).
+ */
+export function bashTargets(command: string, home: string, cwd: string): PathTarget[] {
+  if (!command) return [];
+  const root = reposRoot(home);
+  const segments = command.split(/\s*&&\s*|\s*\|\|\s*|;\s*|\n+/);
+
+  const targets: PathTarget[] = [];
+  let cwdUnderRepos: string | null = null;
+
+  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 && (cdTarget === root || cdTarget.startsWith(`${root}${sep}`))) cwdUnderRepos = cdTarget;
+    }
+
+    const homeLiteral = regexEscape(home);
+    const prefixRe = new RegExp(`(?:~|\\$HOME"*|\\$\\{HOME\\}"*|${homeLiteral}"*)/workspace/repos`);
+    const re = new RegExp(`(${prefixRe.source})([^\\s"';&|<>()\x60]*|$)`, "g");
+    let m: RegExpExecArray | null;
+    let foundExplicit = false;
+    while ((m = re.exec(segment)) !== null) {
+      foundExplicit = true;
+      const expanded = expandHomeSpelling(m[0], home);
+      targets.push({ path: normalize(expanded).replace(/\/+$/, ""), op });
+    }
+
+    if (!foundExplicit && (op === "delete" || op === "write")) {
+      const base =
+        cwdUnderRepos ?? (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 });
+        }
+      }
+    }
+  }
+
+  return targets;
+}
+
+const PATCH_FILE_RE = /^\s*\*\*\*\s+(Add File|Update File|Delete File):\s+(\S+)\s*$/gm;
+
+/**
+ * Extract targets from an apply_patch payload: the `*** Add File:` /
+ * `*** Update File:` / `*** Delete File:` markers, resolved against cwd.
+ * Add/Update classify as write; Delete classifies as delete.
+ */
+export function patchTargets(patch: string, cwd: string): PathTarget[] {
+  const targets: PathTarget[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = PATCH_FILE_RE.exec(patch)) !== null) {
+    const op: Operation = m[1] === "Delete File" ? "delete" : "write";
+    targets.push({ path: normalize(resolve(cwd, m[2])), op });
+  }
+  return targets;
+}
+
+export function evaluate(input: CodewithHookInput): { 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 root = reposRoot(home);
+  const orgs = resolveAllowedOrgs();
+
+  if (tool === "Bash") {
+    const command = getCommand(input);
+    if (!command) return { output: { continue: true }, warnings };
+    const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
+    const targets = bashTargets(command, home, cwd);
+    for (const target of targets) {
+      const verdict = classifyPath(target.path, root, orgs, target.op);
+      if (verdict.blocked) {
+        return { output: { decision: "block", reason: verdict.reason }, warnings };
+      }
+    }
+    return { output: { continue: true }, warnings };
+  }
+
+  const toolInput = input.tool_input ?? {};
+  const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
+
+  if (PATCH_TOOLS.has(tool)) {
+    const patch = typeof toolInput.patch === "string" ? toolInput.patch : "";
+    if (!patch) return { output: { continue: true }, warnings };
+    const targets = patchTargets(patch, cwd);
+    for (const target of targets) {
+      const verdict = classifyPath(target.path, root, orgs, target.op);
+      if (verdict.blocked) {
+        return { output: { decision: "block", reason: verdict.reason }, warnings };
+      }
+    }
+    return { output: { continue: true }, warnings };
+  }
+
+  if (!FILE_WRITE_TOOLS.has(tool)) return { output: { continue: true }, warnings };
+
+  const raw =
+    typeof toolInput.file_path === "string"
+      ? toolInput.file_path
+      : typeof toolInput.path === "string"
+        ? toolInput.path
+        : typeof toolInput.notebook_path === "string"
+          ? toolInput.notebook_path
+          : null;
+  if (!raw) return { output: { continue: true }, warnings };
+
+  const expanded = expandHomeSpelling(raw, home);
+  const target = isAbsolute(expanded) ? normalize(expanded) : resolve(cwd, expanded);
+  const verdict = classifyPath(target, root, orgs, "write");
+  if (verdict.blocked) {
+    return { output: { decision: "block", reason: verdict.reason }, warnings };
+  }
+  return { output: { continue: true }, warnings };
+}
+
+export async function run(): Promise<void> {
+  const input = readInput();
+  try {
+    const { output, warnings } = evaluate(input);
+    for (const message of warnings) warn(message);
+    respond(output);
+  } catch (error) {
+    warn(`${RULE} failed open: ${error instanceof Error ? error.message : String(error)}`);
+    respond({ continue: true });
+  }
+}
+
+if (import.meta.main) {
+  await run();
+  process.exit(0);
+}

package/hooks/hook-workspace-repos-guard/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "lib": ["ESNext"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}