@tekmidian/pai 0.54.1 → 0.55.0

package/src/hooks/pre-compact.sh

@@ -15,13 +15,6 @@ TAB_COLOR="${ADAPTER_DIR:-${PAI_DIR:-$HOME/.claude}}/tab-color-command.sh"
 
 # Bail gracefully if pai is not installed
 command -v "$PAI_OS" &>/dev/null || exit 0
-command -v sqlite3 &>/dev/null || exit 0
-
-# PAI_HOME (~/.claude/pai by default — see src/config/pai-home.ts), falling
-# back to the pre-2026-09-19 ~/.pai/registry.db.
-REGISTRY_DB="${PAI_HOME:-$HOME/.claude/pai}/registry.db"
-[ -f "$REGISTRY_DB" ] || REGISTRY_DB="$HOME/.pai/registry.db"
-[ -f "$REGISTRY_DB" ] || exit 0
 
 # ---------------------------------------------------------------------------
 # Detect current project
@@ -41,41 +34,10 @@ fi
 [ -z "$PROJECT_SLUG" ] && exit 0
 
 # ---------------------------------------------------------------------------
-# Look up project and latest open session
-# ---------------------------------------------------------------------------
-
-PROJECT_ID=$(sqlite3 "$REGISTRY_DB" \
-  "SELECT id FROM projects WHERE slug = '$PROJECT_SLUG' LIMIT 1" 2>/dev/null) || exit 0
-[ -z "$PROJECT_ID" ] && exit 0
-
-SESSION_ID=$(sqlite3 "$REGISTRY_DB" \
-  "SELECT id FROM sessions WHERE project_id = $PROJECT_ID AND status = 'open' ORDER BY created_at DESC LIMIT 1" \
-  2>/dev/null) || true
-
-# ---------------------------------------------------------------------------
-# Update session status to compacted
-# ---------------------------------------------------------------------------
-
-if [ -n "$SESSION_ID" ]; then
-  sqlite3 "$REGISTRY_DB" \
-    "UPDATE sessions SET status = 'compacted' WHERE id = $SESSION_ID" 2>/dev/null || true
-fi
-
-# ---------------------------------------------------------------------------
-# Log to compaction_log
+# Mark the latest open session compacted and log the event
 # ---------------------------------------------------------------------------
 
-TS=$(date +%s)000
-
-if [ -n "$SESSION_ID" ]; then
-  sqlite3 "$REGISTRY_DB" \
-    "INSERT INTO compaction_log (project_id, session_id, trigger, files_written, created_at) VALUES ($PROJECT_ID, $SESSION_ID, 'precompact', '', $TS)" \
-    2>/dev/null || true
-else
-  sqlite3 "$REGISTRY_DB" \
-    "INSERT INTO compaction_log (project_id, session_id, trigger, files_written, created_at) VALUES ($PROJECT_ID, NULL, 'precompact', '', $TS)" \
-    2>/dev/null || true
-fi
+"$PAI_OS" hooks-db pre-compact "$PROJECT_SLUG" 2>/dev/null || true
 
 # ---------------------------------------------------------------------------
 # Sync Obsidian vault

package/src/hooks/session-hooks-db.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, chmodSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+/**
+ * Proof for docs/design/postgres-only.md unit 8: session-stop.sh and
+ * pre-compact.sh no longer shell out to sqlite3 — they shell out to
+ * `pai hooks-db <verb> <projectSlug>`, exactly once per run. A fake `pai`
+ * on PATH logs every invocation it receives; both scripts run detached
+ * (backgrounded + disowned), so the test polls the log file for the
+ * expected line instead of asserting on synchronous stdout.
+ */
+describe("session-stop.sh / pre-compact.sh call pai hooks-db", () => {
+  let fakeBinDir: string;
+  let homeDir: string;
+  let logFile: string;
+
+  beforeEach(() => {
+    fakeBinDir = mkdtempSync(join(tmpdir(), "hooks-db-test-bin-"));
+    homeDir = mkdtempSync(join(tmpdir(), "hooks-db-test-home-"));
+    logFile = join(fakeBinDir, "pai-calls.log");
+    writeFileSync(logFile, "");
+
+    const fakePai = join(fakeBinDir, "pai");
+    writeFileSync(
+      fakePai,
+      [
+        "#!/bin/bash",
+        `echo "$*" >> ${JSON.stringify(logFile)}`,
+        'if [ "$1" = "project" ] && [ "$2" = "detect" ]; then',
+        '  echo \'{"slug":"testproj"}\'',
+        "fi",
+        "exit 0",
+      ].join("\n")
+    );
+    chmodSync(fakePai, 0o755);
+  });
+
+  afterEach(() => {
+    rmSync(fakeBinDir, { recursive: true, force: true });
+    rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  function runHookDetached(script: string): void {
+    execFileSync("bash", [script], {
+      encoding: "utf8",
+      timeout: 15_000,
+      input: "",
+      env: {
+        ...process.env,
+        PATH: `${fakeBinDir}:${process.env.PATH}`,
+        HOME: homeDir,
+        PAI_HOME: join(homeDir, ".claude", "pai"),
+        PAI_DIR: join(homeDir, ".claude"), // no tab-color-command.sh here: TAB_COLOR call is a no-op
+        PAI_WORKER: "",
+      },
+    });
+  }
+
+  function waitForLogLine(match: string, timeoutMs = 5000): string {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (existsSync(logFile)) {
+        const content = readFileSync(logFile, "utf8");
+        if (content.includes(match)) return content;
+      }
+    }
+    return existsSync(logFile) ? readFileSync(logFile, "utf8") : "";
+  }
+
+  it("session-stop.sh invokes exactly `pai hooks-db session-stop <slug>`", () => {
+    runHookDetached("src/hooks/session-stop.sh");
+    const content = waitForLogLine("hooks-db session-stop");
+    const calls = content.split("\n").filter((l) => l.startsWith("hooks-db"));
+    expect(calls).toEqual(["hooks-db session-stop testproj"]);
+  });
+
+  it("pre-compact.sh invokes exactly `pai hooks-db pre-compact <slug>`", () => {
+    runHookDetached("src/hooks/pre-compact.sh");
+    const content = waitForLogLine("hooks-db pre-compact");
+    const calls = content.split("\n").filter((l) => l.startsWith("hooks-db"));
+    expect(calls).toEqual(["hooks-db pre-compact testproj"]);
+  });
+
+  it("neither script contains a raw sqlite3 call", () => {
+    const stopScript = readFileSync("src/hooks/session-stop.sh", "utf8");
+    const compactScript = readFileSync("src/hooks/pre-compact.sh", "utf8");
+    expect(stopScript).not.toContain("sqlite3");
+    expect(compactScript).not.toContain("sqlite3");
+  });
+});

package/src/hooks/session-stop.sh

@@ -11,7 +11,6 @@ PAI_OS="pai"
 
 # Bail gracefully if pai is not installed
 command -v "$PAI_OS" &>/dev/null || exit 0
-command -v sqlite3 &>/dev/null || exit 0
 
 # ---------------------------------------------------------------------------
 # Read the Claude session UUID from the hook payload
@@ -39,12 +38,6 @@ if [ ! -t 0 ]; then
   fi
 fi
 
-# PAI_HOME (~/.claude/pai by default — see src/config/pai-home.ts), falling
-# back to the pre-2026-09-19 ~/.pai/registry.db.
-REGISTRY_DB="${PAI_HOME:-$HOME/.claude/pai}/registry.db"
-[ -f "$REGISTRY_DB" ] || REGISTRY_DB="$HOME/.pai/registry.db"
-[ -f "$REGISTRY_DB" ] || exit 0
-
 # ---------------------------------------------------------------------------
 # Everything below runs DETACHED. Nothing here is on the critical path.
 # ---------------------------------------------------------------------------
@@ -112,27 +105,10 @@ fi
 [ -z "$PROJECT_SLUG" ] && exit 0
 
 # ---------------------------------------------------------------------------
-# Look up project and latest open/compacted session
+# Mark the latest open/compacted session completed
 # ---------------------------------------------------------------------------
 
-PROJECT_ID=$(sqlite3 "$REGISTRY_DB" \
-  "SELECT id FROM projects WHERE slug = '$PROJECT_SLUG' LIMIT 1" 2>/dev/null) || exit 0
-[ -z "$PROJECT_ID" ] && exit 0
-
-SESSION_ID=$(sqlite3 "$REGISTRY_DB" \
-  "SELECT id FROM sessions WHERE project_id = $PROJECT_ID AND status IN ('open','compacted') ORDER BY created_at DESC LIMIT 1" \
-  2>/dev/null) || true
-
-# ---------------------------------------------------------------------------
-# Mark session completed and set closed_at
-# ---------------------------------------------------------------------------
-
-if [ -n "$SESSION_ID" ]; then
-  TS=$(date +%s)000
-  sqlite3 "$REGISTRY_DB" \
-    "UPDATE sessions SET status = 'completed', closed_at = $TS WHERE id = $SESSION_ID" \
-    2>/dev/null || true
-fi
+"$PAI_OS" hooks-db session-stop "$PROJECT_SLUG" 2>/dev/null || true
 
 # ---------------------------------------------------------------------------
 # Auto-generate slug from transcript and rename session note

package/src/hooks/ts/lib/edit-gate.test.ts

@@ -38,6 +38,15 @@ describe("decideEditGate", () => {
     expect((out as { reason: string }).reason).toContain("pai worker run");
   });
 
+  it("tells the session this is a standing policy, not a one-off error, and names the next step", () => {
+    const out = decideEditGate(ctx({}));
+    const reason = (out as { reason: string }).reason;
+    expect(reason).toContain("standing policy for the whole session");
+    expect(reason).toContain("retrying Edit/Write");
+    expect(reason).toContain("--provider anthropic");
+    expect(reason).toContain(ctx({}).filePath);
+  });
+
   it("allows worker sessions regardless of path", () => {
     expect(decideEditGate(ctx({ isPaiWorker: true }))).toEqual({ decision: "allow" });
   });

package/src/hooks/ts/lib/edit-gate.ts

@@ -45,7 +45,10 @@ export function decideEditGate(ctx: EditGateContext): EditGateDecision {
   return {
     decision: "block",
     reason:
-      `main session does not edit code: run a worker instead — ` +
-      `pai worker run --label "${label}" --class implement --output-format json -p <spec> (target: ${ctx.filePath})`,
+      `main session does not edit code — this is a standing policy for the whole session, not a problem ` +
+      `with this edit: retrying Edit/Write on ${ctx.filePath} or any other code file will be denied the ` +
+      `same way. Next step: write a spec file, then run ` +
+      `pai worker run --label "${label}" --class implement --provider anthropic --output-format json -p "$(cat <spec>)" ` +
+      `(target: ${ctx.filePath})`,
   };
 }

package/src/hooks/ts/lib/plutil-guard.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import { detectUnsafePlutil, plutilGuardMessage } from "./plutil-guard.js";
+
+const DENIED_COMMANDS = [
+  "plutil -extract Label json /tmp/x.plist",
+  "plutil -replace Label -string foo /tmp/x.plist",
+  "plutil -insert Label -string foo /tmp/x.plist",
+  "plutil -remove Label /tmp/x.plist",
+  "plutil -convert xml1 /tmp/x.plist",
+  "plutil -create xml1 /tmp/x.plist",
+  "cd /tmp && plutil -extract Label json /tmp/x.plist",
+  "plutil -extract Label json /tmp/x.plist | cat",
+  "plutil -extract Label json /tmp/x.plist; echo done",
+  "echo $(plutil -extract Label json /tmp/x.plist)",
+  "echo `plutil -extract Label json /tmp/x.plist`",
+  "for f in *.plist; do plutil -extract Label json $f; done",
+];
+
+const ALLOWED_COMMANDS = [
+  "plutil -p /tmp/x.plist",
+  "plutil -lint /tmp/x.plist",
+  "plutil -help",
+  "plutil -extract Label json -o - /tmp/x.plist",
+  "plutil -extract ProgramArguments json -o /tmp/out.json /tmp/x.plist",
+  "plutil -convert xml1 -o /tmp/out.plist /tmp/x.plist",
+  "for f in *.plist; do plutil -extract Label json -o - $f; done",
+  "ls -la",
+  "git status",
+];
+
+describe("detectUnsafePlutil", () => {
+  for (const cmd of DENIED_COMMANDS) {
+    it(`denies: ${cmd}`, () => {
+      const result = detectUnsafePlutil(cmd);
+      expect(result.blocked).toBe(true);
+      expect(result.verb).toBeTruthy();
+    });
+  }
+
+  for (const cmd of ALLOWED_COMMANDS) {
+    it(`allows: ${cmd}`, () => {
+      expect(detectUnsafePlutil(cmd).blocked).toBe(false);
+    });
+  }
+});
+
+describe("plutilGuardMessage", () => {
+  it("names the verb and the safe alternatives", () => {
+    const msg = plutilGuardMessage("-extract");
+    expect(msg).toContain("-extract");
+    expect(msg).toContain("plutil -p <file>");
+    expect(msg).toContain("-o - <file>");
+  });
+});

package/src/hooks/ts/lib/plutil-guard.ts

@@ -0,0 +1,43 @@
+/**
+ * plutil-guard.ts — blocks plutil edit verbs (-extract, -replace, -insert,
+ * -remove, -convert, -create) run without an explicit -o <path>.
+ *
+ * Without -o, plutil writes the result back into the source file instead of
+ * printing it — `plutil -extract ProgramArguments json <plist>` run as a
+ * read destroyed three LaunchAgent plists on 2026-09-23. -p, -lint, -help
+ * and any edit verb that does carry -o are unaffected.
+ *
+ * Pure: scans the raw command string for each `plutil ...` invocation up to
+ * the next hard shell separator (&& || ; | backtick paren newline), so it
+ * catches compound lines, subshells, and loop bodies without a real parser.
+ */
+
+const EDIT_VERB = /-(extract|replace|insert|remove|convert|create)\b/;
+const HAS_DASH_O = /(^|\s)-o(\s|$)/;
+const INVOCATION = /\bplutil\b([^&|;`()\n]*)/g;
+
+export interface PlutilGuardResult {
+  blocked: boolean;
+  invocation?: string;
+  verb?: string;
+}
+
+export function detectUnsafePlutil(command: string): PlutilGuardResult {
+  INVOCATION.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = INVOCATION.exec(command))) {
+    const args = m[1];
+    const verbMatch = args.match(EDIT_VERB);
+    if (!verbMatch) continue;
+    if (HAS_DASH_O.test(args)) continue;
+    return { blocked: true, invocation: `plutil${args}`.trim(), verb: `-${verbMatch[1]}` };
+  }
+  return { blocked: false };
+}
+
+export function plutilGuardMessage(verb: string): string {
+  return (
+    `plutil ${verb} without -o rewrites the file in place; ` +
+    "read with `plutil -p <file>` or `plutil -extract <key> raw -o - <file>`"
+  );
+}

package/src/hooks/ts/lib/worker-git-guard.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from "vitest";
+import { decideWorkerGitGuard, workerGitGuardMessage } from "./worker-git-guard.js";
+
+const CWD = "/repo";
+const WORKTREES_ROOT = "/repo/.workers/worktrees";
+const WORKTREE_CWD = "/repo/.workers/worktrees/abc123";
+
+const DENIED_COMMANDS = [
+  "git stash",
+  "git stash pop",
+  "git stash push -m wip",
+  "git stash apply",
+  "git stash drop",
+  "git stash clear",
+  "git stash save wip",
+  "git stash branch new-branch",
+  "git stash create",
+  "git stash store stash@{0}",
+  "git reset --hard",
+  "git reset --hard HEAD~1",
+  "git reset HEAD",
+  "git clean -fd",
+  "git clean -fdx",
+  "git checkout -- src/file.ts",
+  "git checkout HEAD -- src/file.ts",
+  "git checkout .",
+  "git restore src/file.ts",
+  "git restore --staged src/file.ts",
+  "git switch main",
+  "git switch -c feature",
+  "git rebase main",
+  "git rebase -i HEAD~3",
+  "git merge feature-branch",
+  "git merge --no-ff worker/abc",
+];
+
+const ALLOWED_COMMANDS = [
+  "git status",
+  "git diff",
+  "git diff --name-only HEAD",
+  "git log --oneline -5",
+  "git show HEAD",
+  "git rev-parse HEAD",
+  "git ls-files --others --exclude-standard",
+  "git blame src/file.ts",
+  "git add -A",
+  "git add src/file.ts",
+  "git commit -m 'wip'",
+  "git checkout main",
+  "git checkout -b feature",
+  "git stash list",
+  "git stash list --oneline",
+  "git stash show",
+  "git stash show -p",
+  "git stash show stash@{0}",
+];
+
+describe("decideWorkerGitGuard", () => {
+  for (const cmd of DENIED_COMMANDS) {
+    it(`denies "${cmd}" for an in-place worker`, () => {
+      const r = decideWorkerGitGuard(cmd, true, CWD, WORKTREES_ROOT);
+      expect(r.blocked).toBe(true);
+    });
+  }
+
+  for (const cmd of ALLOWED_COMMANDS) {
+    it(`allows "${cmd}" for an in-place worker`, () => {
+      expect(decideWorkerGitGuard(cmd, true, CWD, WORKTREES_ROOT).blocked).toBe(false);
+    });
+  }
+
+  it("detects a denied command inside a compound line (&&)", () => {
+    expect(decideWorkerGitGuard("npm test && git stash", true, CWD, WORKTREES_ROOT).blocked).toBe(
+      true
+    );
+  });
+
+  it("detects a denied command inside a compound line (;)", () => {
+    expect(decideWorkerGitGuard("cd /tmp; git reset --hard", true, CWD, WORKTREES_ROOT).blocked).toBe(
+      true
+    );
+  });
+
+  it("detects a denied command inside a compound line (|)", () => {
+    expect(
+      decideWorkerGitGuard("echo apply | git stash apply", true, CWD, WORKTREES_ROOT).blocked
+    ).toBe(true);
+  });
+
+  it("detects a denied command behind a `git -C <dir>` prefix", () => {
+    expect(
+      decideWorkerGitGuard("git -C /repo stash", true, CWD, WORKTREES_ROOT).blocked
+    ).toBe(true);
+  });
+
+  it("allows every denied command for a worker whose cwd is inside the worktrees root", () => {
+    for (const cmd of DENIED_COMMANDS) {
+      expect(decideWorkerGitGuard(cmd, true, WORKTREE_CWD, WORKTREES_ROOT).blocked).toBe(false);
+    }
+  });
+
+  it("allows every denied command for a non-worker session", () => {
+    for (const cmd of DENIED_COMMANDS) {
+      expect(decideWorkerGitGuard(cmd, false, CWD, WORKTREES_ROOT).blocked).toBe(false);
+    }
+  });
+
+  it("allows read-only git regardless of worker status or cwd", () => {
+    for (const cmd of ALLOWED_COMMANDS) {
+      expect(decideWorkerGitGuard(cmd, true, WORKTREE_CWD, WORKTREES_ROOT).blocked).toBe(false);
+      expect(decideWorkerGitGuard(cmd, false, CWD, WORKTREES_ROOT).blocked).toBe(false);
+    }
+  });
+
+  it("blocks when the worktrees root could not be resolved — cannot prove cwd is a worktree", () => {
+    expect(decideWorkerGitGuard("git stash", true, CWD, null).blocked).toBe(true);
+  });
+
+  it("names the matched command in the result", () => {
+    expect(decideWorkerGitGuard("git stash", true, CWD, WORKTREES_ROOT).cmd).toBe("git stash");
+    expect(decideWorkerGitGuard("git checkout .", true, CWD, WORKTREES_ROOT).cmd).toBe(
+      "git checkout"
+    );
+  });
+});
+
+describe("workerGitGuardMessage", () => {
+  it("names the command and the --worktree escape hatch", () => {
+    const msg = workerGitGuardMessage("git stash");
+    expect(msg).toContain("git stash");
+    expect(msg).toContain("rewrites the shared checkout and is blocked");
+    expect(msg).toContain("--worktree");
+  });
+});

package/src/hooks/ts/lib/worker-git-guard.ts

@@ -0,0 +1,103 @@
+/**
+ * worker-git-guard.ts — blocks tree-rewriting git commands from an in-place
+ * worker: one whose cwd is the operator's checkout itself, not a worktree
+ * under `<workers logDir>/worktrees/`.
+ *
+ * `git stash` (or reset/clean/checkout --/restore/switch/rebase/merge) in a
+ * shared checkout can drop or conflict with another worker's in-flight
+ * edits — observed twice on 2026-09-22, each time with a spec that already
+ * said "do not run git stash" in prose. Prose did not stop it; this gate
+ * does.
+ *
+ * Pure: no fs, no config read, no process.env read of its own. The hook
+ * (pre-tool-use/security-validator.ts) resolves whether the session is a
+ * worker and where its worktrees root is, and passes both in.
+ */
+
+const TREE_REWRITE: { name: string; pattern: RegExp }[] = [
+  { name: "git reset", pattern: /\bgit(?:\s+-C\s+\S+)?\s+reset\b/ },
+  { name: "git clean", pattern: /\bgit(?:\s+-C\s+\S+)?\s+clean\b/ },
+  { name: "git restore", pattern: /\bgit(?:\s+-C\s+\S+)?\s+restore\b/ },
+  { name: "git switch", pattern: /\bgit(?:\s+-C\s+\S+)?\s+switch\b/ },
+  { name: "git rebase", pattern: /\bgit(?:\s+-C\s+\S+)?\s+rebase\b/ },
+  { name: "git merge", pattern: /\bgit(?:\s+-C\s+\S+)?\s+merge\b/ },
+];
+
+/**
+ * `git checkout` only rewrites the tree when it names paths (`-- <paths>`,
+ * with or without a leading ref) or restores everything (`git checkout .`).
+ * A bare `git checkout <branch>` is a branch switch, not covered here —
+ * `git switch` above is the tree-rewriting form of that.
+ */
+const CHECKOUT_INVOCATION = /\bgit(?:\s+-C\s+\S+)?\s+checkout\s+([^&;|`\n)]*)/g;
+
+function checkoutRewritesTree(command: string): boolean {
+  CHECKOUT_INVOCATION.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = CHECKOUT_INVOCATION.exec(command))) {
+    const args = m[1].trim();
+    if (args === ".") return true;
+    if (/(^|\s)--(\s|$)/.test(args)) return true;
+  }
+  return false;
+}
+
+/**
+ * `git stash list` and `git stash show` only read the stash; every other
+ * subcommand (push/pop/apply/drop/clear/save/create/store/branch) and the
+ * bare `git stash` (a push) can drop or conflict with in-flight edits.
+ */
+const STASH_INVOCATION = /\bgit(?:\s+-C\s+\S+)?\s+stash\b(?:\s+(\S+))?/g;
+const STASH_READONLY_SUBCOMMANDS = new Set(["list", "show"]);
+
+function stashRewritesTree(command: string): boolean {
+  STASH_INVOCATION.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = STASH_INVOCATION.exec(command))) {
+    const sub = m[1];
+    if (!sub || !STASH_READONLY_SUBCOMMANDS.has(sub)) return true;
+  }
+  return false;
+}
+
+/** Absolute-path prefix check; `root` with or without a trailing separator. */
+function isInsideWorktree(cwd: string, root: string): boolean {
+  const normalizedRoot = root.endsWith("/") ? root.slice(0, -1) : root;
+  return cwd === normalizedRoot || cwd.startsWith(`${normalizedRoot}/`);
+}
+
+export interface WorkerGitGuardResult {
+  blocked: boolean;
+  /** The tree-rewriting git invocation matched, e.g. "git stash". */
+  cmd?: string;
+}
+
+/**
+ * `worktreesRoot` is the absolute worktrees directory (see
+ * `worktreesDir` in src/workers/worktree.ts), or null when the hook could
+ * not resolve it. Null cannot prove `cwd` is a worktree, so a worker blocks
+ * in that case too — the guard fails closed on tree-rewriting git, not open.
+ */
+export function decideWorkerGitGuard(
+  command: string,
+  isWorker: boolean,
+  cwd: string,
+  worktreesRoot: string | null
+): WorkerGitGuardResult {
+  if (!isWorker) return { blocked: false };
+  if (worktreesRoot && isInsideWorktree(cwd, worktreesRoot)) return { blocked: false };
+
+  for (const { name, pattern } of TREE_REWRITE) {
+    if (pattern.test(command)) return { blocked: true, cmd: name };
+  }
+  if (checkoutRewritesTree(command)) return { blocked: true, cmd: "git checkout" };
+  if (stashRewritesTree(command)) return { blocked: true, cmd: "git stash" };
+  return { blocked: false };
+}
+
+export function workerGitGuardMessage(cmd: string): string {
+  return (
+    `in-place worker: ${cmd} rewrites the shared checkout and is blocked; ` +
+    "take baselines from the numbers before your edit, or run with --worktree"
+  );
+}

package/src/hooks/ts/pre-tool-use/security-validator.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import { execFileSync } from "node:child_process";
+
+// The entry does its own stdin read and calls main() unconditionally at
+// module scope, and it must exercise the real exit-code/stderr contract —
+// run it as a real subprocess, exactly like route-edits-to-worker.test.ts.
+describe("security-validator", () => {
+  const ENTRYPOINT = "src/hooks/ts/pre-tool-use/security-validator.ts";
+
+  function runHook(
+    command: string,
+    env: NodeJS.ProcessEnv = {}
+  ): { status: number | null; stdout: string; stderr: string } {
+    const { PAI_WORKER: _drop, ...baseEnv } = process.env;
+    try {
+      const stdout = execFileSync("bun", [ENTRYPOINT], {
+        input: JSON.stringify({
+          session_id: "test",
+          tool_name: "Bash",
+          tool_input: { command },
+          cwd: process.cwd(),
+        }),
+        encoding: "utf8",
+        timeout: 15_000,
+        env: { ...baseEnv, ...env },
+      });
+      return { status: 0, stdout, stderr: "" };
+    } catch (err) {
+      const e = err as { status: number | null; stdout: string; stderr: string };
+      return { status: e.status, stdout: e.stdout, stderr: e.stderr };
+    }
+  }
+
+  it("writes the deny reason to stderr with exit code 2", () => {
+    const { status, stderr } = runHook("git stash", { PAI_WORKER: "1" });
+    expect(status).toBe(2);
+    expect(stderr).toContain("Blocked by PAI security validator:");
+    expect(stderr.length).toBeGreaterThan(0);
+  });
+
+  it("allows git stash list for an in-place worker", () => {
+    const { status, stderr } = runHook("git stash list", { PAI_WORKER: "1" });
+    expect(status).toBe(0);
+    expect(stderr).toBe("");
+  });
+
+  it("allows git stash show for an in-place worker", () => {
+    const { status } = runHook("git stash show", { PAI_WORKER: "1" });
+    expect(status).toBe(0);
+  });
+
+  it("denies git stash push for an in-place worker", () => {
+    const { status, stderr } = runHook("git stash push -m wip", { PAI_WORKER: "1" });
+    expect(status).toBe(2);
+    expect(stderr).toContain("Blocked by PAI security validator:");
+  });
+
+  it("denies git stash pop for an in-place worker", () => {
+    const { status } = runHook("git stash pop", { PAI_WORKER: "1" });
+    expect(status).toBe(2);
+  });
+
+  it("allows an ordinary command", () => {
+    const { status, stderr } = runHook("ls -la");
+    expect(status).toBe(0);
+    expect(stderr).toBe("");
+  });
+});