@tekmidian/pai 0.42.5 → 0.43.0

package/src/hooks/ts/user-prompt/whisper-rules.ts

@@ -4,8 +4,8 @@
  * whisper-rules.ts
  *
  * UserPromptSubmit hook that injects:
- * 1. User-defined whisper rules from ~/.claude/whisper-rules.md
- * 2. Budget-aware model tiering guidance from ~/.claude/advisor-mode.json
+ * 1. User-defined whisper rules from ~/.claude/pai/whisper-rules.md
+ * 2. Budget-aware model tiering guidance from ~/.claude/pai/advisor-mode.json
  *
  * The advisor mode implements the "advisor strategy" pattern:
  * - Normal (budget < 70%): use any model freely
@@ -13,16 +13,25 @@
  * - Strict (85-95%): haiku only for subagents, main context stays on current model
  * - Critical (>95%): minimize all subagent spawning, essential work only
  *
- * Budget percentage is written by the statusline or manually to advisor-mode.json.
- * If the file doesn't exist, no advisor guidance is injected.
+ * Budget percentage is written by the statusline or manually to advisor-mode.json,
+ * stamped with the epoch second it was read. If the file doesn't exist, or its
+ * reading is too old to still describe the current window, no advisor guidance
+ * is injected — see lib/advisor-budget.ts for why that direction is the safe one.
  */
 
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { homedir, tmpdir } from "node:os";
+import { tmpdir } from "node:os";
+import { resolveAdvisorMode, type AdvisorConfig } from "../lib/advisor-budget.js";
+import { whisperRulesPath, advisorModePath } from "../../../config/pai-files.js";
 
-const WHISPER_FILE = join(homedir(), ".claude", "whisper-rules.md");
-const ADVISOR_FILE = join(homedir(), ".claude", "advisor-mode.json");
+const WHISPER_FILE = whisperRulesPath();
+const ADVISOR_FILE = advisorModePath();
+
+/** A "# N. TITLE" section header: the start of a new section, tag reset. */
+function isSectionHeader(line: string): boolean {
+  return /^#\s*\d+\.\s/.test(line);
+}
 
 /**
  * Read the rule file, dropping everything that is there for the author rather
@@ -35,28 +44,42 @@ const ADVISOR_FILE = join(homedir(), ".claude", "advisor-mode.json");
  * maintainable, and none of it reaches the prompt. Only the rules do.
  *
  * A line whose rule text legitimately starts with "#" can be escaped as "\\#".
+ *
+ * Section tags: this file is injected into every claude process, spawned
+ * workers included, and some rules (e.g. "delegate to workers") are true only
+ * for the interactive orchestrating session. A comment line "# @orchestrator"
+ * marks every following rule as orchestrator-only, "# @worker" marks
+ * worker-only, until the next "# N. TITLE" section header resets the tag (a
+ * section's own header/divider box, which the tag line sits inside, does not
+ * count as the next section). An untagged section reaches both. `isWorker`
+ * selects which side of the tag this process is on — see PAI_WORKER in
+ * run-env.ts.
  */
-function getWhisperRules(): string {
+function getWhisperRules(isWorker: boolean): string {
   if (!existsSync(WHISPER_FILE)) return "";
   try {
-    return readFileSync(WHISPER_FILE, "utf-8")
-      .split("\n")
-      .map((l) => l.trim())
-      .filter((l) => l.length > 0 && !l.startsWith("#"))
-      .map((l) => (l.startsWith("\\#") ? l.slice(1) : l))
-      .join("\n")
-      .trim();
+    const lines = readFileSync(WHISPER_FILE, "utf-8").split("\n");
+    const out: string[] = [];
+    let tag: "orchestrator" | "worker" | null = null;
+    for (const raw of lines) {
+      const line = raw.trim();
+      if (line.length === 0) continue;
+      if (line.startsWith("#")) {
+        if (isSectionHeader(line)) tag = null;
+        else if (line === "# @orchestrator") tag = "orchestrator";
+        else if (line === "# @worker") tag = "worker";
+        continue;
+      }
+      if (tag === "orchestrator" && isWorker) continue;
+      if (tag === "worker" && !isWorker) continue;
+      out.push(line.startsWith("\\#") ? line.slice(1) : line);
+    }
+    return out.join("\n").trim();
   } catch {
     return "";
   }
 }
 
-interface AdvisorConfig {
-  weeklyBudgetPercent?: number;  // 0-100, written by statusline or manually
-  mode?: "normal" | "conservative" | "strict" | "critical" | "auto";
-  forceModel?: string;  // override: always use this model for subagents
-}
-
 function getAdvisorGuidance(): string {
   if (!existsSync(ADVISOR_FILE)) return "";
 
@@ -67,24 +90,12 @@ function getAdvisorGuidance(): string {
     return "";
   }
 
-  // Determine mode.
-  //
-  // `??` only substitutes on null/undefined, so a config written as
-  // {"mode": ""} — which is what the statusline produces when it has no manual
-  // override — left mode as the empty string. That matched no case below, so
-  // the advisor silently returned nothing regardless of budget. A budget guard
-  // that quietly does nothing is worse than none, because you believe you have
-  // one. Treat anything that is not a recognised mode as "auto".
-  const VALID = ["normal", "conservative", "strict", "critical", "auto"] as const;
-  let mode: string =
-    config.mode && (VALID as readonly string[]).includes(config.mode) ? config.mode : "auto";
-  if (mode === "auto" && typeof config.weeklyBudgetPercent === "number") {
-    const pct = config.weeklyBudgetPercent;
-    if (pct < 60) mode = "normal";
-    else if (pct < 80) mode = "conservative";
-    else if (pct < 92) mode = "strict";
-    else mode = "critical";
-  }
+  // Determine mode: the manual one if set, else derived from a budget reading
+  // that is current. No current reading and no manual mode means say nothing —
+  // guessing is how a wrong number gets obeyed for a day and a half. See
+  // lib/advisor-budget.ts.
+  const { mode, percent: pct } = resolveAdvisorMode(config, Math.floor(Date.now() / 1000));
+  if (mode === undefined) return "";
 
   // Force model override
   if (config.forceModel) {
@@ -97,7 +108,7 @@ function getAdvisorGuidance(): string {
 
     case "conservative":
       return [
-        `ADVISOR MODE (conservative — weekly budget at ${config.weeklyBudgetPercent ?? "?"}%):`,
+        `ADVISOR MODE (conservative — weekly budget at ${pct ?? "?"}%):`,
         "Main context is opus (most expensive — 20x haiku, 5x sonnet). Delegate aggressively to subagents.",
         "Default subagents to SONNET (Agent tool, model: sonnet). Use haiku for simple lookups/verification.",
         "For substantial tasks, use swarm mode: spawn a sonnet orchestrator that delegates to haiku workers.",
@@ -106,7 +117,7 @@ function getAdvisorGuidance(): string {
 
     case "strict":
       return [
-        `ADVISOR MODE (strict — weekly budget at ${config.weeklyBudgetPercent ?? "?"}%):`,
+        `ADVISOR MODE (strict — weekly budget at ${pct ?? "?"}%):`,
         "Main context is opus (most expensive — 20x haiku, 5x sonnet). Minimize work done here.",
         "Default subagents to SONNET (Agent tool, model: sonnet) for implementation and research. Use haiku for simple tasks.",
         "For any substantial task, use swarm mode: spawn ONE sonnet orchestrator that delegates to haiku workers.",
@@ -116,7 +127,7 @@ function getAdvisorGuidance(): string {
 
     case "critical":
       return [
-        `ADVISOR MODE (critical — weekly budget at ${config.weeklyBudgetPercent ?? "?"}%):`,
+        `ADVISOR MODE (critical — weekly budget at ${pct ?? "?"}%):`,
         "MINIMIZE ALL TOKEN USAGE. Main context is opus — the most expensive model (20x haiku, 5x sonnet).",
         "For ANY non-trivial task, immediately spawn a sonnet orchestrator agent and let it handle everything.",
         "Main context should only send the task and receive the final result — do not do work here.",
@@ -153,24 +164,54 @@ function currentLocalTime(): string {
  * true after the first turn — a reminder that misstates its own trigger is one
  * the reader learns to discount.
  */
-function resetReinjectCounter(): void {
+function resetReinjectCounter(sessionId: string): void {
   try {
-    const raw = readFileSync(0, "utf-8");
-    const sessionId = raw.trim() ? (JSON.parse(raw) as { session_id?: string }).session_id ?? "" : "";
     const safe = sessionId.replace(/[^A-Za-z0-9_-]/g, "") || "nosession";
     const f = join(tmpdir(), "pai-whisper-reinject", `${safe}.count`);
     if (existsSync(f)) unlinkSync(f);
   } catch { /* best effort — a stale count is not worth failing the hook over */ }
 }
 
+/**
+ * True for prompts this hook never authored a human at the keyboard: a
+ * worker-completion relay ("[Session: …] worker … finished …"), a clickr
+ * control-handover line ("your controls." / "my controls."), or a harness
+ * notification (a "[SYSTEM NOTIFICATION" preamble, or a background task
+ * completion carrying a <task-notification> block). All of these fire
+ * several times per turn during worker-heavy work, so injecting the ~5KB rule
+ * block on each one was landing it 3-5 times in a single turn.
+ */
+export function isRelayedPrompt(prompt: string): boolean {
+  return (
+    /^\s*\[Session:[^\]]+\]/.test(prompt) ||
+    /^\s*(your|my) controls\b/i.test(prompt) ||
+    /^\s*\[SYSTEM NOTIFICATION/.test(prompt) ||
+    prompt.includes("<task-notification>")
+  );
+}
+
 function main() {
-  resetReinjectCounter();
+  let sessionId = "";
+  let prompt = "";
+  try {
+    const raw = readFileSync(0, "utf-8");
+    if (raw.trim()) {
+      const input = JSON.parse(raw) as { session_id?: string; prompt?: string };
+      sessionId = input.session_id ?? "";
+      prompt = input.prompt ?? "";
+    }
+  } catch { /* malformed/empty stdin — treat as no session, no prompt */ }
+
+  resetReinjectCounter(sessionId);
+
+  if (isRelayedPrompt(prompt)) return;
 
+  const isWorker = process.env.PAI_WORKER === "1";
   const parts: string[] = [];
 
   parts.push(`CURRENT LOCAL TIME: ${currentLocalTime()} — use this verbatim for any [YYYY-MM-DD HH:MM] stamp; never estimate or increment it.`);
 
-  const rules = getWhisperRules();
+  const rules = getWhisperRules(isWorker);
   if (rules) parts.push(rules);
 
   const advisor = getAdvisorGuidance();

package/src/hooks/ztk-auto.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Wrapper around ztk rewrite that auto-approves and passes through commands
+# whose output ztk would compact lossily (plain-text tools, interpreters,
+# pipelines already tailed/headed/counted, or anything requesting JSON output).
+# Changes permissionDecision from "ask" to "allow" for everything else.
+# Also handles empty responses from ztk (passthrough).
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+stdin="$(cat)"
+
+command="$(printf '%s' "$stdin" | jq -r '.tool_input.command // empty' 2>/dev/null)"
+
+if [ -n "$command" ]; then
+  decision="$(node "$script_dir/ztk-passthrough.mjs" "$command" 2>/dev/null)"
+  if [ "$decision" = "yes" ]; then
+    exit 0
+  fi
+fi
+
+result=$(printf '%s' "$stdin" | ztk rewrite 2>/dev/null)
+
+if [ -z "$result" ]; then
+  # ztk returned nothing - allow the command as-is
+  echo '{"permissionDecision":"allow"}'
+else
+  # ztk returned something - change ask to allow
+  echo "$result" | sed 's/"permissionDecision":"ask"/"permissionDecision":"allow"/'
+fi

package/src/hooks/ztk-auto.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// ztk-auto.sh reads the PreToolUse payload from stdin, decides whether the
+// command should bypass ztk's (lossy, for short/structured output) rewrite
+// step via ztk-passthrough.mjs, and otherwise shells out to the real `ztk`
+// binary. A pass-through decision prints nothing and exits 0 — Claude Code
+// treats a silent PreToolUse hook as "no opinion", i.e. the command runs
+// untouched. A non-pass-through decision always produces JSON output.
+describe("ztk-auto.sh", () => {
+  const SCRIPT = "src/hooks/ztk-auto.sh";
+  let fakeBinDir: string;
+
+  // Stub `ztk` so the test doesn't depend on the real binary being installed
+  // or on its exact output shape — only that ztk-auto.sh calls it and
+  // forwards its (sed-patched) output for non-pass-through commands.
+  beforeAll(() => {
+    fakeBinDir = mkdtempSync(join(tmpdir(), "ztk-auto-test-bin-"));
+    const fakeZtk = join(fakeBinDir, "ztk");
+    writeFileSync(
+      fakeZtk,
+      [
+        "#!/bin/bash",
+        "cat > /dev/null",
+        'echo \'{"permissionDecision":"ask","hookSpecificOutput":{"updatedInput":{"command":"ztk run npm test"}}}\'',
+      ].join("\n"),
+    );
+    chmodSync(fakeZtk, 0o755);
+  });
+
+  afterAll(() => {
+    rmSync(fakeBinDir, { recursive: true, force: true });
+  });
+
+  function runHook(command: string): string {
+    return execFileSync("bash", [SCRIPT], {
+      input: JSON.stringify({
+        hook_event_name: "PreToolUse",
+        tool_name: "Bash",
+        tool_input: { command },
+      }),
+      encoding: "utf8",
+      timeout: 15_000,
+      env: { ...process.env, PATH: `${fakeBinDir}:${process.env.PATH}` },
+    });
+  }
+
+  it("passes through a plain ls (empty stdout, command runs untouched)", () => {
+    expect(runHook("ls -la src")).toBe("");
+  });
+
+  it("sends an unrecognised command to ztk and rewrites it", () => {
+    const stdout = runHook("npm test");
+    expect(stdout).toContain("ztk run");
+    expect(stdout).toContain('"permissionDecision":"allow"');
+  });
+
+  it("passes through a cd-prefixed wc command", () => {
+    expect(runHook("cd /x && wc -l a")).toBe("");
+  });
+
+  it("passes through a pipeline whose last stage is tail", () => {
+    expect(runHook("cargo build 2>&1 | tail -20")).toBe("");
+  });
+
+  it("passes through a command requesting --json output", () => {
+    expect(runHook("pai worker ps --json")).toBe("");
+  });
+});

package/src/hooks/ztk-passthrough.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * ztk-passthrough — decide whether a Bash command's output should skip
+ * ztk's rewrite/compaction step.
+ *
+ * ztk compacts aggressively and is lossy for short, already-structured
+ * output: a plain `ls` came back with a file misreported as a directory,
+ * and `wc -l ... | tail -1` came back summarised instead of verbatim.
+ * Interpreters, text-processing tools, anything already piped through
+ * head/tail/wc, and anything asking for machine-readable JSON output must
+ * keep their exact stdout, so they bypass ztk entirely.
+ *
+ * Prints "yes" (pass through, skip ztk) or "no" (send to ztk) to stdout.
+ */
+
+const PASSTHROUGH_COMMANDS = new Set([
+  "ls", "wc", "echo", "printf", "pwd", "which", "whoami", "date",
+  "basename", "dirname", "readlink", "stat", "du", "df",
+  "head", "tail", "cat", "jq", "sed", "awk", "sort", "uniq", "tr", "cut",
+  "true", "test", "[",
+  "python3", "node", "bun",
+]);
+
+const LAST_STAGE_PASSTHROUGH = new Set(["head", "tail", "wc"]);
+
+const VAR_ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\S*)\s+/;
+const CD_PREFIX = /^cd\s+(?:'[^']*'|"[^"]*"|\S+)\s*&&\s*/;
+const ENV_PREFIX = /^env\s+/;
+const TIMEOUT_PREFIX = /^timeout\s+\S+\s+/;
+
+/** Strip leading `cd … &&`, `env …`, `timeout N`, and variable assignments, in any order. */
+function stripLeaders(command) {
+  let cur = command.trimStart();
+  for (let i = 0; i < 20; i++) {
+    const before = cur;
+    cur = cur.replace(CD_PREFIX, "").replace(ENV_PREFIX, "").replace(TIMEOUT_PREFIX, "").replace(VAR_ASSIGN, "");
+    cur = cur.trimStart();
+    if (cur === before) break;
+  }
+  return cur;
+}
+
+function firstWord(command) {
+  return command.trim().split(/\s+/)[0] ?? "";
+}
+
+function lastPipelineStage(command) {
+  const stages = command.split("|");
+  return stages[stages.length - 1] ?? "";
+}
+
+export function shouldPassThrough(rawCommand) {
+  const command = rawCommand ?? "";
+  if (!command.trim()) return false;
+
+  if (command.includes("--output-format json") || command.includes("--json")) return true;
+
+  const lastStageFirstWord = firstWord(lastPipelineStage(command));
+  if (LAST_STAGE_PASSTHROUGH.has(lastStageFirstWord)) return true;
+
+  const stripped = stripLeaders(command);
+  const head = firstWord(stripped);
+  return PASSTHROUGH_COMMANDS.has(head);
+}
+
+function main() {
+  const command = process.argv[2] ?? "";
+  console.log(shouldPassThrough(command) ? "yes" : "no");
+}
+
+main();