@hasna/hooks 0.4.0 → 0.4.1

package/hooks/codewith-native-common.ts

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, writeSync } from "fs";
 import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "path";
 import { homedir, tmpdir } from "os";
 
@@ -57,7 +57,15 @@ export function readInput(): CodewithHookInput {
 }
 
 export function respond(output: CodewithHookOutput): void {
-  process.stdout.write(`${JSON.stringify(output)}\n`);
+  // Written synchronously: `process.stdout.write` is async on a pipe, so a verdict
+  // larger than the pipe buffer is silently truncated if the process exits before it
+  // drains — and a truncated verdict is unparseable, so the caller sees no decision.
+  const payload = `${JSON.stringify(output)}\n`;
+  try {
+    writeSync(1, payload);
+  } catch {
+    process.stdout.write(payload);
+  }
 }
 
 export function warn(message: string): void {
@@ -516,12 +524,41 @@ function hasUnsafeTargetComponent(worktreesRoot: string, target: string): boolea
   return false;
 }
 
-function managedLeaseRoot(worktreesRoot: string, target: string): string | null {
-  const relativeTarget = relative(worktreesRoot, target);
-  const parts = relativeTarget.split(sep).filter(Boolean);
-  if (parts.length < 3) return null;
-  const leaseRoot = resolve(worktreesRoot, ...parts.slice(0, 3));
-  return managedWorktreeInfo(leaseRoot).managed ? leaseRoot : null;
+/**
+ * Candidate worktree roots for an absolute target, canonical shape first.
+ *
+ * The canonical root sits at `<worktrees-root>/<repo-name>/<worktree-name>`
+ * (CANONICAL_WORKTREE_SEGMENTS). The deprecated station-id lease layout sits one
+ * level deeper. Order matters: a canonical worktree that happens to contain a
+ * subdirectory must resolve to the canonical root, never to the subdirectory.
+ */
+function managedWorktreeRootCandidates(worktreesRoot: string, target: string): string[] {
+  const parts = relative(worktreesRoot, target).split(sep).filter(Boolean);
+  const depths = [CANONICAL_WORKTREE_SEGMENTS, LEGACY_LEASE_WORKTREE_SEGMENTS];
+  return depths
+    .filter((depth) => parts.length >= depth)
+    .map((depth) => resolve(worktreesRoot, ...parts.slice(0, depth)));
+}
+
+/**
+ * Worktree roots that could own `target`, for the scoped dangerous-operation
+ * carve-out only.
+ *
+ * This is a structural lookup ("could a real managed worktree own this path?"),
+ * not a policy check ("is this path canonical?"). It therefore keeps the
+ * deprecated station-id lease layout as a candidate, so that worktrees created
+ * before rule 8 keep their `~/.hasna` write carve-out during migration. Policy
+ * enforcement lives in managedWorktreeInfo() / worktree-guard.
+ *
+ * Both depths are returned when both are plausible, because path shape alone
+ * cannot tell a canonical root from a legacy lease container. Each candidate is
+ * still verified against Git provenance by the caller, which fails closed.
+ */
+function managedLeaseRootCandidates(worktreesRoot: string, target: string): string[] {
+  return managedWorktreeRootCandidates(worktreesRoot, target).filter((candidate) => {
+    const info = managedWorktreeInfo(candidate);
+    return info.managed || info.layout === "legacy-station-lease";
+  });
 }
 
 async function verifiedLinkedWorktreeRoot(leaseRoot: string): Promise<string | null> {
@@ -587,8 +624,19 @@ async function managedRepoRootForAbsoluteTarget(
     return null;
   }
 
-  const leaseRoot = managedLeaseRoot(worktreesRoot, target);
-  if (!leaseRoot) return null;
+  for (const leaseRoot of managedLeaseRootCandidates(worktreesRoot, target)) {
+    const repoRoot = await verifiedManagedRepoRoot(leaseRoot, target, physicalWorktreesRoot, repoRootCache);
+    if (repoRoot) return repoRoot;
+  }
+  return null;
+}
+
+async function verifiedManagedRepoRoot(
+  leaseRoot: string,
+  target: string,
+  physicalWorktreesRoot: string,
+  repoRootCache: Map<string, Promise<string | null>>,
+): Promise<string | null> {
   let repoRootPromise = repoRootCache.get(leaseRoot);
   if (!repoRootPromise) {
     repoRootPromise = verifiedLinkedWorktreeRoot(leaseRoot);
@@ -1086,22 +1134,265 @@ export function isInsidePath(child: string, parent: string): boolean {
   return rel === "" || (!!rel && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
 }
 
-export function managedWorktreeInfo(cwd: string): { managed: boolean; root: string; reason?: string } {
+/**
+ * Canonical managed-worktree path shape.
+ *
+ * Source of truth: Hasna Agent Operating Rules rule 8, as published by the
+ * @hasna/identities 0.4.4 global agent rules, verbatim:
+ *
+ *   "must happen in a task-specific worktree at
+ *    $HOME/.hasna/repos/worktrees/<repo-name>/<worktree-name>
+ *    (repo name then worktree name; no station-id or machine segment,
+ *    never flat under the worktrees root)"
+ *
+ * So, relative to the worktrees root, a compliant worktree root is exactly two
+ * segments deep: <repo-name>/<worktree-name>.
+ */
+export const CANONICAL_WORKTREE_SEGMENTS = 2;
+
+/**
+ * Depth of the DEPRECATED station-id lease layout
+ * (`<station-id>/<repo-slug>-<hex>/wt_<hex>`) that predates rule 8.
+ *
+ * Read-only migration tolerance: it is never a compliant target shape, and it is
+ * never reported as `managed`. It is recognised only so that (a) guard messages
+ * can name it precisely and (b) the scoped dangerous-operation carve-out keeps
+ * working for worktrees created before the canonical shape was mandated.
+ */
+export const LEGACY_LEASE_WORKTREE_SEGMENTS = 3;
+
+// Any ordinary directory name, bounded by the filesystem's own limit rather than an
+// allowlist — repo and worktree names are user data, and an over-narrow pattern would
+// reject legitimate work (real fleet names include `_base`). Refused: a leading `.`,
+// so `.`, `..` and `.git` can never be read as a segment; a leading `-`, so a segment
+// can never read as an option in the remediation command; and control characters.
+const WORKTREE_SEGMENT_PATTERN = /^[^.\-\/\x00-\x1f][^\/\x00-\x1f]{0,254}$/;
+const LEGACY_LEASE_REPO_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*-[0-9a-fA-F]{7,16}$/;
+const LEGACY_LEASE_ID_PATTERN = /^wt_[0-9a-fA-F]{16,64}$/;
+
+/**
+ * Whether the deprecated station-id lease layout still gets its migration tolerance.
+ *
+ * Default on, so the change does not strand worktrees created before rule 8. It is a
+ * kill switch, not a policy knob: the layout is non-compliant either way, and the
+ * tolerance only softens the verdict from blocked to warned. Set
+ * `HASNA_HOOKS_LEGACY_WORKTREE_TOLERANCE=0` once those worktrees are re-homed; the
+ * whole branch goes away after that.
+ *
+ * Known limitation while it is on: the tolerance keys off the path name, so a newly
+ * created worktree deliberately named to match also gets the warn tier. That is an
+ * opt-out from a guardrail by a cooperating agent, not a security boundary — the
+ * boundary is the provenance proof above, which applies to both tiers.
+ */
+export function legacyWorktreeToleranceEnabled(): boolean {
+  return process.env.HASNA_HOOKS_LEGACY_WORKTREE_TOLERANCE !== "0";
+}
+
+export type ManagedWorktreeLayout = "canonical" | "legacy-station-lease";
+
+export interface ManagedWorktreeInfo {
+  managed: boolean;
+  /** The worktrees root the path was classified against. */
+  root: string;
+  /** Recognised layout, set for compliant and for deprecated-but-recognised paths. */
+  layout?: ManagedWorktreeLayout;
+  /** True when the layout is recognised but no longer permitted by rule 8. */
+  deprecated?: boolean;
+  repo?: string;
+  worktree?: string;
+  /** Absolute path of the worktree root that owns `cwd`. */
+  worktreeRoot?: string;
+  reason?: string;
+}
+
+/** The canonical worktree path template, for user-facing guard messages. */
+export function canonicalWorktreeTemplate(root: string = defaultWorktreesRoot()): string {
+  return join(root, "<repo-name>", "<worktree-name>");
+}
+
+/**
+ * Prove that `worktreeRoot` owns its own git history, synchronously.
+ *
+ * Shape is not evidence and neither is the mere presence of `.git`. A `.git` file is
+ * two lines of text: pointing it at a shared checkout's `.git` grafts a second working
+ * tree onto that checkout, so `git commit`/`git push` from the forged directory lands
+ * on the shared checkout — the exact outcome rule 10 forbids. So a `.git` file must
+ * carry real linked-worktree provenance:
+ *
+ *   - its `gitdir:` target must live under `<common-dir>/worktrees/`, and
+ *   - that target's `gitdir` back-pointer must resolve to this very control file.
+ *
+ * A `.git` directory is accepted only as a self-contained repository. A `commondir`
+ * grafts it onto another repository's history outright, and symlinked `objects` or
+ * `refs` graft it onto another repository's refs — reaching the same end state as a
+ * forged `.git` file without writing anything inside the victim.
+ *
+ * This is a structural proof only. It is deliberately close to, but not the same as,
+ * the async verifiedLinkedWorktreeRoot() used for the write carve-out, which is
+ * stricter still (regular-file control file, nlink === 1, worktrees dir directly
+ * under the common dir).
+ */
+function worktreeProvenanceReason(worktreeRoot: string): string | null {
+  const controlPath = join(worktreeRoot, ".git");
+  let control;
+  try {
+    control = lstatSync(controlPath);
+  } catch {
+    return `${worktreeRoot} is not a git worktree root (no .git)`;
+  }
+  if (control.isSymbolicLink()) return `worktree .git is a symlink at ${worktreeRoot}`;
+
+  if (control.isDirectory()) {
+    if (existsSync(join(controlPath, "commondir"))) {
+      return `worktree .git is grafted onto another repository at ${worktreeRoot}`;
+    }
+    if (!existsSync(join(controlPath, "HEAD"))) return `worktree .git is not a repository at ${worktreeRoot}`;
+    // A self-contained repository owns its object and ref storage. Symlinking either
+    // into another repository makes commits here land on that repository's refs.
+    for (const store of ["objects", "refs"]) {
+      let metadata;
+      try {
+        metadata = lstatSync(join(controlPath, store));
+      } catch {
+        return `worktree .git is missing ${store} at ${worktreeRoot}`;
+      }
+      if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+        return `worktree .git ${store} is grafted onto another repository at ${worktreeRoot}`;
+      }
+    }
+    return null;
+  }
+  if (!control.isFile()) return `worktree .git is not a file or directory at ${worktreeRoot}`;
+
+  try {
+    const pointer = readFileSync(controlPath, "utf-8").trim();
+    const match = pointer.match(/^gitdir:\s*(.+)$/);
+    if (!match?.[1]) return `worktree .git is not a git worktree pointer at ${worktreeRoot}`;
+    const gitDir = resolveFrom(worktreeRoot, match[1].trim());
+    const commonDir = resolveFrom(gitDir, readFileSync(join(gitDir, "commondir"), "utf-8").trim());
+    const physicalGitDir = realpathSync(gitDir);
+    const physicalWorktreesDir = realpathSync(join(commonDir, "worktrees"));
+    if (physicalGitDir === physicalWorktreesDir || !isInsidePath(physicalGitDir, physicalWorktreesDir)) {
+      return `worktree .git points outside its repository's worktrees directory at ${worktreeRoot}`;
+    }
+    const backPointer = resolveFrom(gitDir, readFileSync(join(gitDir, "gitdir"), "utf-8").trim());
+    if (realpathSync(backPointer) !== realpathSync(controlPath)) {
+      return `worktree .git is not registered by its repository at ${worktreeRoot}`;
+    }
+  } catch {
+    return `worktree .git provenance could not be verified at ${worktreeRoot}`;
+  }
+  return null;
+}
+
+/**
+ * Verify that `<root>/<repo>/<worktree>` is a real, non-symlinked, provenance-checked
+ * git worktree root.
+ *
+ * Path shape alone is not evidence: `<root>/<flat-worktree>/<subdir>` has exactly the
+ * same shape as `<root>/<repo>/<worktree>`, so without this check a `cd` into any
+ * subdirectory of a flat worktree would launder it into a compliant-looking path.
+ * Symlinks are refused at every level (hence lstat, not existsSync, which follows
+ * them) because a symlinked segment can aim a canonical-looking path at a shared
+ * checkout.
+ */
+function groundedWorktreeRootReason(root: string, segments: string[]): string | null {
+  let probe = resolve(root);
+  for (const segment of segments) {
+    probe = join(probe, segment);
+    let metadata;
+    try {
+      metadata = lstatSync(probe);
+    } catch {
+      return `no worktree exists at ${probe}`;
+    }
+    if (metadata.isSymbolicLink()) return `worktree path traverses a symlink at ${probe}`;
+    if (!metadata.isDirectory()) return `worktree path is not a directory at ${probe}`;
+  }
+  return worktreeProvenanceReason(probe);
+}
+
+/**
+ * Classify a path against the canonical managed-worktree shape (rule 8).
+ *
+ * Accepted: a real git worktree root at `<worktrees-root>/<repo-name>/<worktree-name>`,
+ * and any path inside it. Rejected, each with a reason: paths outside the worktrees
+ * root, the root itself, flat single-segment worktrees, station-id/machine segments,
+ * deeper nesting, and canonical-shaped paths that are not actually a worktree root
+ * (invented, symlinked, or a subdirectory of a flat worktree).
+ */
+export function managedWorktreeInfo(cwd: string): ManagedWorktreeInfo {
   const root = defaultWorktreesRoot();
+  const canonical = canonicalWorktreeTemplate(root);
   if (!isInsidePath(cwd, root)) return { managed: false, root, reason: "outside worktrees root" };
-  const rel = relative(resolve(root), resolve(cwd));
-  const parts = rel.split(sep).filter(Boolean);
-  if (parts.length < 3) return { managed: false, root, reason: "path is inside worktrees root but not deep enough" };
-  const [machine, repoSlugHash, lease] = parts;
-  if (!machine || !repoSlugHash || !lease) return { managed: false, root, reason: "missing machine/repo/lease path segments" };
-  if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]{1,80}$/.test(machine)) return { managed: false, root, reason: "machine segment is malformed" };
-  if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*-[0-9a-fA-F]{7,16}$/.test(repoSlugHash)) {
-    return { managed: false, root, reason: "repo segment must end in a hex hash suffix" };
+
+  const parts = relative(resolve(root), resolve(cwd)).split(sep).filter(Boolean);
+  if (parts.length === 0) {
+    return { managed: false, root, reason: `path is the worktrees root itself; canonical worktrees live at ${canonical}` };
+  }
+  if (parts.length < CANONICAL_WORKTREE_SEGMENTS) {
+    return {
+      managed: false,
+      root,
+      reason: `worktree is flat under the worktrees root, which rule 8 forbids; canonical shape is ${canonical}`,
+    };
+  }
+
+  const [repo, worktree] = parts;
+  for (const [label, segment] of [["repo-name", repo], ["worktree-name", worktree]] as const) {
+    if (!segment || !WORKTREE_SEGMENT_PATTERN.test(segment)) {
+      return { managed: false, root, reason: `${label} segment is malformed; canonical shape is ${canonical}` };
+    }
+  }
+
+  // A canonical classification must be grounded in a real worktree root at depth 2,
+  // never in path shape alone: at depth 2 the shape is ambiguous with a subdirectory
+  // of a forbidden flat worktree, and at any depth it is ambiguous with an invented
+  // or symlinked path.
+  const worktreeRoot = resolve(root, repo!, worktree!);
+  const rootReason = groundedWorktreeRootReason(root, [repo!, worktree!]);
+  if (!rootReason) {
+    return { managed: true, root, layout: "canonical", repo, worktree, worktreeRoot };
+  }
+
+  if (parts.length === CANONICAL_WORKTREE_SEGMENTS) {
+    return { managed: false, root, reason: `${rootReason}; canonical shape is ${canonical}` };
   }
-  if (!/^wt_[0-9a-fA-F]{16,64}$/.test(lease)) {
-    return { managed: false, root, reason: "lease segment must look like wt_<hex hash>" };
+
+  // Recognised at or inside a legacy lease root, mirroring how a canonical worktree
+  // covers its own subdirectories — an agent cwd'd into `src/` of a legacy worktree
+  // is in the same non-compliant worktree, and must get the same migration message.
+  //
+  // The migration tolerance grants a weaker verdict than "blocked", so it has to clear
+  // the same grounding as the canonical branch. Otherwise the lease name pattern is a
+  // forgery kit: two directories named to match would launder a symlinked or grafted
+  // path into a warn-and-allow.
+  if (legacyWorktreeToleranceEnabled()
+    && parts.length >= LEGACY_LEASE_WORKTREE_SEGMENTS
+    && LEGACY_LEASE_REPO_PATTERN.test(parts[1]!)
+    && LEGACY_LEASE_ID_PATTERN.test(parts[2]!)) {
+    // The layout has two historical variants: the checkout sits at the lease dir, or
+    // one level below it in a `repo/` child. Try both, nothing deeper.
+    for (const depth of [LEGACY_LEASE_WORKTREE_SEGMENTS, LEGACY_LEASE_WORKTREE_SEGMENTS + 1]) {
+      if (parts.length < depth) break;
+      const segments = parts.slice(0, depth);
+      if (groundedWorktreeRootReason(root, segments)) continue;
+      return {
+        managed: false,
+        root,
+        layout: "legacy-station-lease",
+        deprecated: true,
+        worktreeRoot: resolve(root, ...segments),
+        reason: `deprecated station-id lease layout <station-id>/<repo-slug>-<hex>/wt_<hex>; rule 8 forbids a station-id or machine segment — re-home to ${canonical}`,
+      };
+    }
   }
-  return { managed: true, root };
+
+  return {
+    managed: false,
+    root,
+    reason: `worktree root is ${parts.length} segments under the worktrees root (station-id/machine segment or extra nesting); rule 8 requires the worktree to be created at exactly ${canonical}`,
+  };
 }
 
 export async function gitRepoRoot(cwd: string): Promise<string | null> {
@@ -1121,8 +1412,105 @@ export async function gitRemoteSlug(cwd: string): Promise<string | null> {
   return match?.[1] || null;
 }
 
-export function claimCommand(repo: string | null, taskId: string | null, runId: string | null): string {
-  return `repos worktrees claim --repo ${repo || "<repo>"} --task-id ${taskId || "<task-id>"} --run-id ${runId || "<run-id>"} --base main --mode required --json`;
+/** `origin` normalised to the `host/org/name` form the repos CLI resolves exactly. */
+export async function gitRemoteHostSlug(cwd: string): Promise<string | null> {
+  if (!commandExists("git")) return null;
+  const result = await runCommand(["git", "remote", "get-url", "origin"], { cwd, timeoutMs: 2000 });
+  if (result.exitCode !== 0) return null;
+  const remote = result.stdout.trim().replace(/\.git$/, "");
+  if (!remote) return null;
+  const match = remote.match(/^(?:[a-z+]+:\/\/)?(?:[^@/]+@)?([^/:\s]+)[:/](.+)$/i);
+  const host = match?.[1];
+  const path = match?.[2]?.replace(/^\/+/, "");
+  if (!host || !path || !/^[^/\s]+\/[^/\s]+$/.test(path)) return null;
+  return `${host}/${path}`;
+}
+
+export interface CanonicalRepoIdentity {
+  /** The repo name that forms the `<repo-name>` segment of the canonical path. */
+  name: string | null;
+  defaultBranch: string | null;
+}
+
+/**
+ * Resolve the canonical repo name via the repos CLI, as rule 8 requires:
+ * "Locate repos with the repos CLI (`repos repo <name> --json` for the exact
+ * lookup; never fuzzy `repos cd` or 'did you mean' output for targeting)".
+ *
+ * This matters because the repos-CLI name is frequently NOT the git remote
+ * basename — on this fleet 46 of 50 indexed repos differ (`open-hooks` is
+ * `github.com/hasna/hooks`, `open-mailery` is `.../emails`). Deriving the
+ * canonical path segment from the remote would send every agent to the wrong
+ * directory, so the remote is only ever used as the exact lookup key.
+ *
+ * `--remote host/org/name` is the exact-match form, so no fuzzy "did you mean"
+ * output can be mistaken for a hit. OSS-safe: a missing or failing repos CLI
+ * yields nulls and the caller falls back to local information.
+ */
+export async function canonicalRepoIdentity(cwd: string): Promise<CanonicalRepoIdentity> {
+  const empty: CanonicalRepoIdentity = { name: null, defaultBranch: null };
+  if (!commandExists("repos")) return empty;
+  const remote = await gitRemoteHostSlug(cwd);
+  if (!remote) return empty;
+  // Hard ceiling on the lookup. runCommand's timeout kills the direct child but still
+  // awaits its pipes, which a forking CLI can hold open indefinitely; this hook sits on
+  // the PreToolUse path, so it must degrade to local information rather than stall.
+  const result = await Promise.race([
+    runCommand(["repos", "repo", "--remote", remote, "--json"], { cwd, timeoutMs: 1000 }),
+    new Promise<null>((done) => setTimeout(() => done(null), 1500).unref?.()),
+  ]);
+  if (!result || result.exitCode !== 0) return empty;
+  try {
+    const parsed = JSON.parse(result.stdout) as { name?: unknown; default_branch?: unknown; path?: unknown };
+    const name = typeof parsed.name === "string" && parsed.name ? parsed.name : null;
+    const defaultBranch = typeof parsed.default_branch === "string" && parsed.default_branch
+      ? parsed.default_branch
+      : null;
+
+    // The index holds worktree directories as first-class rows, so an exact remote
+    // match can resolve to a worktree rather than the repo. Such a row's name is a
+    // worktree name and its default_branch is that worktree's branch — both wrong for
+    // the canonical path. When the row lives under the worktrees root, the real repo
+    // name is its first segment there; the branch is not recoverable, so drop it.
+    const worktreesRoot = resolve(defaultWorktreesRoot());
+    const rowPath = typeof parsed.path === "string" && parsed.path ? resolve(parsed.path) : null;
+    if (rowPath && isInsidePath(rowPath, worktreesRoot) && rowPath !== worktreesRoot) {
+      const segment = relative(worktreesRoot, rowPath).split(sep).filter(Boolean)[0];
+      return { name: segment || null, defaultBranch: null };
+    }
+    return { name, defaultBranch };
+  } catch {
+    return empty;
+  }
+}
+
+/**
+ * Remediation command for work happening outside a canonical worktree.
+ *
+ * Rule 8: create the worktree at `<worktrees-root>/<repo-name>/<worktree-name>`,
+ * named after the todos task where one exists, then `repos scan`. The repos CLI
+ * has no worktree verb, so `git worktree` is the creation path.
+ *
+ * `repo` must be a canonical repo name (see canonicalRepoIdentity) — never a
+ * remote slug, which names a different directory for most repos.
+ *
+ * This is the boundary where names become a command an operator may paste, so every
+ * interpolated value is validated here rather than trusted from its source: a repo
+ * name is attacker-influenced via the remote, and a task id is unvalidated hook input.
+ * Anything unsafe degrades to the explicit placeholder instead of being emitted.
+ */
+const SAFE_COMMAND_VALUE = /^[a-zA-Z0-9_][a-zA-Z0-9_.\/-]{0,120}$/;
+
+export function claimCommand(repo: string | null, taskId: string | null, defaultBranch: string | null = null): string {
+  // A repo name is one path segment: a slug would silently add a third segment.
+  const safeRepo = repo && SAFE_COMMAND_VALUE.test(repo) && !repo.includes("/") ? repo : null;
+  const safeTask = taskId && SAFE_COMMAND_VALUE.test(taskId) ? taskId : null;
+  const safeBase = defaultBranch && SAFE_COMMAND_VALUE.test(defaultBranch) ? defaultBranch : null;
+
+  const repoName = safeRepo || "<repo-name>";
+  const worktreeName = safeTask || "<worktree-name>";
+  const path = join(defaultWorktreesRoot(), repoName, worktreeName);
+  return `git worktree add -b ${worktreeName} ${path} origin/${safeBase || "<default-branch>"} && repos scan`;
 }
 
 export function taskIdFrom(input: CodewithHookInput): string | null {

package/hooks/worktree-guard/README.md

@@ -8,6 +8,50 @@ 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.
 
+## 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
 
 Prefer renderer-managed configuration through open-configs. @hasna/hooks can emit the TOML fragment:

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.4.1",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {