@tekmidian/pai 0.42.5 → 0.42.6

package/src/hooks/ts/lib/advisor-budget.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from "vitest";
+import {
+  ADVISOR_MAX_AGE_SECONDS,
+  freshBudgetPercent,
+  normaliseMode,
+  resolveAdvisorMode,
+} from "./advisor-budget.js";
+
+const NOW = 1_790_000_000;
+
+describe("freshBudgetPercent", () => {
+  it("returns the percentage while the reading is current", () => {
+    expect(freshBudgetPercent({ weeklyBudgetPercent: 2, asOf: NOW - 30 }, NOW)).toBe(2);
+  });
+
+  it("keeps a zero percentage — 0% used is a reading, not a missing one", () => {
+    expect(freshBudgetPercent({ weeklyBudgetPercent: 0, asOf: NOW }, NOW)).toBe(0);
+  });
+
+  it("drops a reading older than the max age", () => {
+    const stale = { weeklyBudgetPercent: 97, asOf: NOW - ADVISOR_MAX_AGE_SECONDS - 1 };
+    expect(freshBudgetPercent(stale, NOW)).toBeUndefined();
+  });
+
+  it("drops a reading with no asOf at all", () => {
+    // This is the shape the old statusline wrote. It is indistinguishable from
+    // one that stopped being updated, so it cannot be trusted.
+    expect(freshBudgetPercent({ weeklyBudgetPercent: 97, mode: "auto" }, NOW)).toBeUndefined();
+  });
+});
+
+describe("normaliseMode", () => {
+  it("accepts the five real modes", () => {
+    for (const m of ["normal", "conservative", "strict", "critical", "auto"]) {
+      expect(normaliseMode(m)).toBe(m);
+    }
+  });
+
+  it("treats the empty string as auto", () => {
+    // {"mode": ""} is what the statusline used to write with no manual
+    // override; `?? "auto"` did not catch it and the advisor went silent.
+    expect(normaliseMode("")).toBe("auto");
+  });
+
+  it("treats anything unrecognised as auto", () => {
+    expect(normaliseMode(undefined)).toBe("auto");
+    expect(normaliseMode(7)).toBe("auto");
+    expect(normaliseMode("panic")).toBe("auto");
+  });
+});
+
+describe("resolveAdvisorMode", () => {
+  it.each([
+    [0, "normal"],
+    [2, "normal"],
+    [59, "normal"],
+    [60, "conservative"],
+    [79, "conservative"],
+    [80, "strict"],
+    [91, "strict"],
+    [92, "critical"],
+    [100, "critical"],
+  ])("maps %i%% used to %s", (percent, expected) => {
+    const got = resolveAdvisorMode({ weeklyBudgetPercent: percent, asOf: NOW }, NOW);
+    expect(got.mode).toBe(expected);
+    expect(got.percent).toBe(percent);
+  });
+
+  it("reads the percentage as USED, not as remaining", () => {
+    // The whole fault this module exists for: 2% used is a nearly untouched
+    // budget and must read "normal". If anything ever flips the sense, 2 lands
+    // on 98 and this test fails rather than a session being told to stop
+    // working. Both ends are pinned so an inversion cannot pass.
+    expect(resolveAdvisorMode({ weeklyBudgetPercent: 2, asOf: NOW }, NOW).mode).toBe("normal");
+    expect(resolveAdvisorMode({ weeklyBudgetPercent: 98, asOf: NOW }, NOW).mode).toBe("critical");
+  });
+
+  it("says nothing at all when the reading is stale", () => {
+    const stale = { weeklyBudgetPercent: 97, asOf: NOW - ADVISOR_MAX_AGE_SECONDS - 1 };
+    expect(resolveAdvisorMode(stale, NOW)).toEqual({ mode: undefined, percent: undefined });
+  });
+
+  it("says nothing at all when there is no reading", () => {
+    expect(resolveAdvisorMode({}, NOW)).toEqual({ mode: undefined, percent: undefined });
+  });
+
+  it("honours a manual mode even with no usable percentage", () => {
+    const got = resolveAdvisorMode({ mode: "strict" }, NOW);
+    expect(got.mode).toBe("strict");
+    expect(got.percent).toBeUndefined();
+  });
+
+  it("lets a manual mode override a current reading", () => {
+    const got = resolveAdvisorMode({ mode: "critical", weeklyBudgetPercent: 2, asOf: NOW }, NOW);
+    expect(got.mode).toBe("critical");
+    expect(got.percent).toBe(2);
+  });
+});

package/src/hooks/ts/lib/advisor-budget.ts

@@ -0,0 +1,90 @@
+/**
+ * advisor-budget.ts
+ *
+ * Deciding how much of the weekly Anthropic budget is gone, and whether that
+ * answer is current enough to act on.
+ *
+ * The statusline writes `~/.claude/pai/advisor-mode.json` on every render of an
+ * Anthropic session; the whisper hook reads it and injects an instruction about
+ * how much work to do. That makes this the one number in PAI that changes the
+ * assistant's behaviour rather than merely describing it, which is why it is
+ * worth its own module with its own tests.
+ */
+
+export interface AdvisorConfig {
+  weeklyBudgetPercent?: number;  // 0-100, used (not remaining)
+  asOf?: number;                 // epoch seconds the percentage was read
+  mode?: "normal" | "conservative" | "strict" | "critical" | "auto";
+  forceModel?: string;           // override: always use this model for subagents
+}
+
+export type AdvisorMode = "normal" | "conservative" | "strict" | "critical" | "auto";
+
+const VALID_MODES: readonly string[] = ["normal", "conservative", "strict", "critical", "auto"];
+
+/**
+ * How old a budget reading may be before it stops being obeyed.
+ *
+ * A live machine rewrites the file many times a minute, so it never comes near
+ * this. Exceeding it means nothing has reported a budget for hours — which is
+ * exactly what a broken usage source looks like.
+ *
+ * That failure has happened: the OAuth token the statusline read went away, its
+ * usage cache froze, and "weekly budget at 97%" was injected into every session
+ * for a day and a half after the real figure had reset to 2% — telling every
+ * assistant to downgrade models and skip verification on a budget that was
+ * almost untouched. A budget guard has to fail towards doing the work, not
+ * towards refusing it.
+ */
+export const ADVISOR_MAX_AGE_SECONDS = 6 * 60 * 60;
+
+/**
+ * The budget percentage, but only while it can be shown to be current.
+ *
+ * A reading with no `asOf` comes from a writer that predates the timestamp, and
+ * there is no way to tell a fresh one from one that stopped being updated — so
+ * it counts as unknown rather than as true.
+ */
+export function freshBudgetPercent(
+  config: AdvisorConfig,
+  nowSeconds: number,
+): number | undefined {
+  const pct = config.weeklyBudgetPercent;
+  if (typeof pct !== "number" || !Number.isFinite(pct)) return undefined;
+  if (typeof config.asOf !== "number" || !Number.isFinite(config.asOf)) return undefined;
+  if (nowSeconds - config.asOf > ADVISOR_MAX_AGE_SECONDS) return undefined;
+  return pct;
+}
+
+/**
+ * Normalise whatever is in the file to a mode.
+ *
+ * `??` only substitutes on null/undefined, so a config written as {"mode": ""}
+ * — which is what an older statusline produced when there was no manual
+ * override — left mode as the empty string, matching no branch downstream and
+ * silently disabling the advisor whatever the budget said. Anything that is not
+ * a recognised mode is "auto".
+ */
+export function normaliseMode(mode: unknown): AdvisorMode {
+  return typeof mode === "string" && VALID_MODES.includes(mode)
+    ? (mode as AdvisorMode)
+    : "auto";
+}
+
+/**
+ * The mode to act on: the manual one if set, else derived from a current
+ * budget reading, else undefined — meaning say nothing at all.
+ */
+export function resolveAdvisorMode(
+  config: AdvisorConfig,
+  nowSeconds: number,
+): { mode: Exclude<AdvisorMode, "auto"> | undefined; percent: number | undefined } {
+  const percent = freshBudgetPercent(config, nowSeconds);
+  const configured = normaliseMode(config.mode);
+  if (configured !== "auto") return { mode: configured, percent };
+  if (percent === undefined) return { mode: undefined, percent: undefined };
+  if (percent < 60) return { mode: "normal", percent };
+  if (percent < 80) return { mode: "conservative", percent };
+  if (percent < 92) return { mode: "strict", percent };
+  return { mode: "critical", percent };
+}

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

@@ -0,0 +1,101 @@
+import { describe, it, expect } from "vitest";
+import {
+  decideAgentGate,
+  renderDecision,
+  shortLabel,
+  SUBAGENT_TOOL_NAMES,
+  BYPASS_ENV,
+  type AgentGateInput,
+} from "./agent-gate.js";
+
+/**
+ * A real PreToolUse payload shape: taken from an actual in-process subagent
+ * launch recorded in a session transcript (tool_use name "Agent", input keys
+ * description/model/prompt), wrapped in the PreToolUse envelope the harness
+ * feeds hooks on stdin.
+ */
+function payload(toolName: string, description = "Survey App Store state"): AgentGateInput {
+  return {
+    session_id: "00000000-0000-0000-0000-000000000000",
+    cwd: "/tmp/some-project",
+    tool_name: toolName,
+    tool_input: { description, model: "sonnet", prompt: "Do the thing." } as AgentGateInput["tool_input"],
+  };
+}
+
+/** What the harness actually reads: parse the hook's stdout. */
+function decisionOf(input: AgentGateInput, env: Record<string, string | undefined>) {
+  return JSON.parse(renderDecision(decideAgentGate(input, env))).hookSpecificOutput;
+}
+
+describe("agent gate", () => {
+  it("covers both the current and the legacy subagent tool name", () => {
+    expect([...SUBAGENT_TOOL_NAMES]).toEqual(["Agent", "Task"]);
+  });
+
+  for (const name of SUBAGENT_TOOL_NAMES) {
+    it(`denies a ${name} call`, () => {
+      const out = decisionOf(payload(name), {});
+      expect(out.permissionDecision).toBe("deny");
+      expect(out.hookEventName).toBe("PreToolUse");
+      expect(out.permissionDecisionReason).toContain("pai worker run --provider anthropic");
+    });
+
+    it(`allows a ${name} call when ${BYPASS_ENV}=1`, () => {
+      const out = decisionOf(payload(name), { [BYPASS_ENV]: "1" });
+      expect(out.permissionDecision).toBe("allow");
+      expect(out.permissionDecisionReason).toBeUndefined();
+    });
+  }
+
+  it("denies regardless of the workers config — no config is consulted", () => {
+    // The gate used to allow when routing was off or the active provider was
+    // Anthropic. It takes no config argument at all now, so there is nothing
+    // left that can switch it off but the bypass env var.
+    expect(decideAgentGate.length).toBe(2);
+    expect(decisionOf(payload("Agent"), { PAI_WORKERS_ACTIVE: "anthropic" }).permissionDecision).toBe(
+      "deny"
+    );
+  });
+
+  it("only the exact value 1 bypasses", () => {
+    for (const v of ["0", "true", "yes", "", undefined]) {
+      expect(decisionOf(payload("Agent"), { [BYPASS_ENV]: v }).permissionDecision).toBe("deny");
+    }
+  });
+
+  it("lets a non-subagent tool through untouched", () => {
+    const out = decisionOf(payload("Bash"), {});
+    expect(out.permissionDecision).toBe("allow");
+  });
+
+  it("denies an event with no tool_name (malformed subagent launch)", () => {
+    expect(decisionOf({}, {}).permissionDecision).toBe("deny");
+  });
+
+  it("ledgers both outcomes so `pai worker log` shows them", () => {
+    expect(decideAgentGate(payload("Agent"), {}).ledger).toBe("DENIED-ANTHROPIC-AGENT");
+    expect(decideAgentGate(payload("Agent"), { [BYPASS_ENV]: "1" }).ledger).toBe(
+      "ALLOWED-ANTHROPIC-AGENT"
+    );
+  });
+
+  it("puts the subagent description in the suggested --label", () => {
+    const out = decisionOf(payload("Agent", "  Report   local release config  "), {});
+    expect(out.permissionDecisionReason).toContain('--label "Report local release config"');
+  });
+
+  it("falls back to a generic label when there is no description", () => {
+    const out = decisionOf({ tool_name: "Agent" }, {});
+    expect(out.permissionDecisionReason).toContain('--label "task"');
+  });
+
+  it("truncates a very long description to a usable label", () => {
+    expect(shortLabel(payload("Agent", "x".repeat(200)))).toHaveLength(60);
+  });
+
+  it("names the bypass in the deny reason so the escape hatch stays discoverable", () => {
+    const out = decisionOf(payload("Agent"), {});
+    expect(out.permissionDecisionReason).toContain(`${BYPASS_ENV}=1`);
+  });
+});

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

@@ -0,0 +1,112 @@
+/**
+ * agent-gate.ts — the decision behind the PreToolUse subagent gate.
+ *
+ * Pure: no stdin, no filesystem, no config, no process.env read of its own.
+ * The hook entry (pre-tool-use/route-agents-to-worker.ts) does the I/O; this
+ * module decides, so the decision can be tested directly instead of inferred
+ * from a hook that happens to exit 0.
+ *
+ * The gate is deliberately NOT conditional on the workers config. It used to
+ * allow whenever routing was off, no provider was configured, or the active
+ * provider was the native Anthropic one — which made the guard silently
+ * self-disabling. Observed 2026-09-19 with `workers.active = "anthropic"`:
+ * two in-process subagents ran to completion, invisible to `pai worker ps`.
+ * Visibility is the point of the gate, and it is worth just as much when the
+ * work is meant to run on an Anthropic model — `pai worker run --provider
+ * anthropic` delivers exactly that, and shows up in `pai worker ps`.
+ */
+
+export interface AgentGateInput {
+  session_id?: string;
+  cwd?: string;
+  tool_name?: string;
+  tool_input?: { description?: string; prompt?: string; subagent_type?: string } | string;
+}
+
+/**
+ * Tool names the harness has used for in-process subagents. "Agent" is what
+ * the current harness emits (verified against real tool_use records in the
+ * session transcripts); "Task" is the older name, matched as well so that a
+ * harness rename in either direction cannot silently reopen the hole.
+ */
+export const SUBAGENT_TOOL_NAMES = ["Agent", "Task"] as const;
+
+/** Environment variable that disables the gate for one session. */
+export const BYPASS_ENV = "ALLOW_ANTHROPIC_AGENTS";
+
+export type GateDecision =
+  | { decision: "allow"; ledger: string | null }
+  | { decision: "deny"; reason: string; ledger: string };
+
+export function isSubagentTool(name: string): boolean {
+  return (SUBAGENT_TOOL_NAMES as readonly string[]).includes(name);
+}
+
+/** The label the deny message suggests for the replacement worker run. */
+export function shortLabel(input: AgentGateInput): string {
+  const desc =
+    typeof input.tool_input === "object" && input.tool_input !== null
+      ? input.tool_input.description ?? ""
+      : "";
+  return desc.replace(/\s+/g, " ").trim().slice(0, 60);
+}
+
+export function denyReason(label: string): string {
+  const name = label || "task";
+  return (
+    "The in-process subagent tool is disabled: every subagent must run through " +
+    "`pai worker run`, so that it shows up in `pai worker ps` and the status line and " +
+    "can be followed, replayed and killed. Delegate with Bash instead, in the background:\n\n" +
+    `pai worker run --provider anthropic --label "${name}" -p '<full, self-contained task spec>' ` +
+    "--allowedTools 'Read,Edit,Write,Bash,Grep,Glob' --output-format json\n\n" +
+    "- `--provider anthropic` is the supported way to get an Anthropic-model subagent, " +
+    "so there is never a reason to reach for the built-in tool.\n" +
+    "- Drop `--provider` to use the configured worker provider; pick the job with " +
+    "`--class draft|plan|implement|review|research|spotcheck`.\n" +
+    "- Run it in the background and always with a timeout.\n" +
+    "- Web research: add WebSearch,WebFetch to --allowedTools.\n" +
+    "- The answer is in the `result` field of the JSON it prints. Review the diff yourself.\n" +
+    "- `pai worker ps` lists running workers; `pai worker follow <id>` shows one live.\n" +
+    "Keep only orchestration, review and synthesis in this session. " +
+    `To re-enable in-process subagents for one session: start it with ${BYPASS_ENV}=1.`
+  );
+}
+
+/**
+ * Decide. `env` is passed in so the bypass can be exercised without mutating
+ * the process environment.
+ */
+export function decideAgentGate(
+  input: AgentGateInput,
+  env: Record<string, string | undefined>
+): GateDecision {
+  const name = input.tool_name;
+  // Matcher-scoped hook, but a stray event for another tool must pass through.
+  // A *missing* tool_name is not treated as another tool: the gate denies,
+  // because the only thing routed here is a subagent launch.
+  if (name && !isSubagentTool(name)) return { decision: "allow", ledger: null };
+
+  if (env[BYPASS_ENV] === "1") return { decision: "allow", ledger: "ALLOWED-ANTHROPIC-AGENT" };
+
+  return {
+    decision: "deny",
+    reason: denyReason(shortLabel(input)),
+    ledger: "DENIED-ANTHROPIC-AGENT",
+  };
+}
+
+/** Render a decision as the JSON the harness reads on the hook's stdout. */
+export function renderDecision(d: GateDecision): string {
+  if (d.decision === "allow") {
+    return JSON.stringify({
+      hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow" },
+    });
+  }
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: d.reason,
+    },
+  });
+}

package/src/hooks/ts/lib/context-fill.ts

@@ -324,12 +324,12 @@ export const THRESHOLD_MARGIN_TOKENS = {
 //
 // Deliberately re-implements the tiny bit of path encoding it needs (below)
 // rather than importing project-utils/paths.ts's encodePath: that module
-// chain ends in pai-paths.ts, which calls process.exit(1) if PAI_DIR does
+// chain ends in pai-paths.ts, which calls process.exit(1) if ADAPTER_DIR does
 // not resolve to an existing directory. context-fill.ts is specifically the
 // module a hook falls back on when its environment is unreliable — pulling
 // in a dependency that can kill the process on import would defeat that.
 // Claude Code's transcript directory is a fixed, home-relative convention
-// (~/.claude/projects/<encoded-cwd>/), not something PAI_DIR governs, so
+// (~/.claude/projects/<encoded-cwd>/), not something ADAPTER_DIR governs, so
 // resolving it directly here is also just the more correct dependency, not
 // only the safer one.
 

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

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { isProseEdit, decideEditGate, type EditGateContext } from "./edit-gate.js";
+
+describe("isProseEdit", () => {
+  it.each([
+    ["Notes/TODO.md", true],
+    ["notes/x.md", true],
+    ["README.md", true],
+    ["docs/commands/worker.md", true],
+    ["src/workers/run.ts", false],
+    ["package.json", false],
+    ["scripts/build-hooks.mjs", false],
+    ["src/foo.md", true],
+  ])("%s -> %s", (filePath, expected) => {
+    expect(isProseEdit(filePath)).toBe(expected);
+  });
+});
+
+describe("decideEditGate", () => {
+  function ctx(overrides: Partial<EditGateContext>): EditGateContext {
+    return {
+      filePath: "/repo/src/workers/run.ts",
+      isPaiWorker: false,
+      isExemptPrefix: false,
+      isGitWorkTree: true,
+      ...overrides,
+    };
+  }
+
+  it("allows a prose path even inside a git work tree", () => {
+    expect(decideEditGate(ctx({ filePath: "/repo/Notes/TODO.md" }))).toEqual({ decision: "allow" });
+  });
+
+  it("blocks a code path inside a git work tree with the standing message", () => {
+    const out = decideEditGate(ctx({}));
+    expect(out.decision).toBe("block");
+    expect((out as { reason: string }).reason).toContain("main session does not edit code");
+    expect((out as { reason: string }).reason).toContain("pai worker run");
+  });
+
+  it("allows worker sessions regardless of path", () => {
+    expect(decideEditGate(ctx({ isPaiWorker: true }))).toEqual({ decision: "allow" });
+  });
+
+  it("allows exempt prefixes regardless of path", () => {
+    expect(decideEditGate(ctx({ isExemptPrefix: true }))).toEqual({ decision: "allow" });
+  });
+
+  it("allows paths outside any git work tree", () => {
+    expect(decideEditGate(ctx({ isGitWorkTree: false }))).toEqual({ decision: "allow" });
+  });
+});

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

@@ -0,0 +1,51 @@
+/**
+ * edit-gate.ts — the decision behind the PreToolUse edit-routing gate.
+ *
+ * Pure: no stdin, no filesystem, no process.env read of its own. The hook
+ * entry (pre-tool-use/route-edits-to-worker.ts) resolves paths and checks the
+ * filesystem/env, then hands this module the already-computed facts to
+ * decide on — same split as lib/agent-gate.ts.
+ */
+
+import { basename, extname } from "node:path";
+
+export interface EditGateContext {
+  /** Absolute, already-resolved target path. */
+  filePath: string;
+  isPaiWorker: boolean;
+  isExemptPrefix: boolean;
+  isGitWorkTree: boolean;
+}
+
+export type EditGateDecision = { decision: "allow" } | { decision: "block"; reason: string };
+
+/** Extensions that are prose regardless of which directory they live in. */
+const PROSE_EXTENSIONS = new Set([".md", ".markdown", ".txt"]);
+
+/**
+ * True for notes, session logs, handovers and other prose the outer session
+ * writes directly instead of routing through a worker — a `Notes`/`notes`
+ * directory segment anywhere in the path, or a prose file extension.
+ * Extension check runs first: a source file that happens to live under a
+ * `notes/` directory is still code, but `src/foo.md` is still prose.
+ */
+export function isProseEdit(filePath: string): boolean {
+  const ext = extname(filePath).toLowerCase();
+  if (PROSE_EXTENSIONS.has(ext)) return true;
+  return filePath.split(/[\\/]/).some((segment) => segment === "Notes" || segment === "notes");
+}
+
+export function decideEditGate(ctx: EditGateContext): EditGateDecision {
+  if (ctx.isPaiWorker) return { decision: "allow" };
+  if (ctx.isExemptPrefix) return { decision: "allow" };
+  if (isProseEdit(ctx.filePath)) return { decision: "allow" };
+  if (!ctx.isGitWorkTree) return { decision: "allow" };
+
+  const label = basename(ctx.filePath).slice(0, 60) || "edit";
+  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})`,
+  };
+}

package/src/hooks/ts/lib/mcp-deferred-reminder.test.ts

@@ -61,10 +61,18 @@ describe("session-start/mcp-deferred-reminder entrypoint", () => {
   const ENTRYPOINT = "src/hooks/ts/session-start/mcp-deferred-reminder.ts";
 
   function runHook(stdin: string): { status: number; stdout: string } {
+    // Explicitly unset PAI_WORKER: this suite may itself be running inside a
+    // worker (PAI_WORKER=1 inherited from process.env), which would make the
+    // session-start worker guard swallow output regardless of `source` and
+    // give a false negative here — these cases are about the source-based
+    // decision, not the worker guard (see session-start-worker-guard.test.ts
+    // for that).
+    const { PAI_WORKER: _unused, ...env } = process.env;
     const stdout = execFileSync("bun", [ENTRYPOINT], {
       input: stdin,
       encoding: "utf8",
       timeout: 15_000,
+      env,
     });
     return { status: 0, stdout };
   }

package/src/hooks/ts/lib/pai-paths.test.ts

@@ -0,0 +1,93 @@
+/**
+ * The PAI_DIR→ADAPTER_DIR deprecation notice used to fire on every process
+ * that had PAI_DIR set at all — including the operator's own settings.json,
+ * which sets PAI_DIR to exactly the default adapter root (~/.claude). That
+ * must stay silent; only a PAI_DIR that actually differs from the default is
+ * worth a heads-up, and even then only once per process.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+let home: string;
+
+// resolveAdapterDir() resolves the default (homedir()/.claude) at module
+// load, so the stub has to be in place before the dynamic import below.
+vi.mock("os", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("os")>();
+  return { ...actual, homedir: () => home, default: { ...actual, homedir: () => home } };
+});
+
+const ORIGINAL_ENV = { ...process.env };
+const ORIGINAL_ARGV = [...process.argv];
+
+function resetNoticeFlag(): void {
+  delete (globalThis as { __paiDirNoticePrinted?: boolean }).__paiDirNoticePrinted;
+}
+
+function deprecationLines(writeSpy: ReturnType<typeof vi.spyOn>): string[] {
+  return writeSpy.mock.calls.map((c) => String(c[0])).filter((line) => line.includes("PAI_DIR is deprecated"));
+}
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "pai-paths-test-"));
+  mkdirSync(join(home, ".claude", "Hooks"), { recursive: true });
+  delete process.env.ADAPTER_DIR;
+  delete process.env.PAI_DIR;
+  delete process.env.PAI_QUIET_NOTICES;
+  process.argv = [...ORIGINAL_ARGV];
+  resetNoticeFlag();
+});
+
+afterEach(() => {
+  rmSync(home, { recursive: true, force: true });
+  process.env = { ...ORIGINAL_ENV };
+  process.argv = [...ORIGINAL_ARGV];
+  resetNoticeFlag();
+  vi.resetModules();
+});
+
+describe("resolveAdapterDir PAI_DIR deprecation notice", () => {
+  it("stays silent when PAI_DIR equals the default adapter root", async () => {
+    process.env.PAI_DIR = join(home, ".claude");
+    const writeSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    const { ADAPTER_DIR } = await import("./pai-paths.js");
+
+    expect(ADAPTER_DIR).toBe(join(home, ".claude"));
+    expect(deprecationLines(writeSpy)).toHaveLength(0);
+    writeSpy.mockRestore();
+  });
+
+  it("prints exactly one line when PAI_DIR differs from the default", async () => {
+    const otherAdapter = mkdtempSync(join(tmpdir(), "pai-paths-other-"));
+    mkdirSync(join(otherAdapter, "Hooks"), { recursive: true });
+    process.env.PAI_DIR = otherAdapter;
+    const writeSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    const { ADAPTER_DIR } = await import("./pai-paths.js");
+
+    expect(ADAPTER_DIR).toBe(otherAdapter);
+    expect(deprecationLines(writeSpy)).toHaveLength(1);
+
+    writeSpy.mockRestore();
+    rmSync(otherAdapter, { recursive: true, force: true });
+  });
+
+  it("stays silent when PAI_QUIET_NOTICES=1 even if PAI_DIR differs", async () => {
+    const otherAdapter = mkdtempSync(join(tmpdir(), "pai-paths-quiet-"));
+    mkdirSync(join(otherAdapter, "Hooks"), { recursive: true });
+    process.env.PAI_DIR = otherAdapter;
+    process.env.PAI_QUIET_NOTICES = "1";
+    const writeSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    await import("./pai-paths.js");
+
+    expect(deprecationLines(writeSpy)).toHaveLength(0);
+
+    writeSpy.mockRestore();
+    rmSync(otherAdapter, { recursive: true, force: true });
+  });
+});