pi-claude-supervisor 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented here.
 
+## [0.7.2](https://github.com/btnalit/pi-claude-supervisor/compare/v0.7.1...v0.7.2) (2026-09-17)
+
+
+### Bug Fixes
+
+* **policy:** a redirection target is not a dynamic argument, and drop the regex twin of the token check ([94742c7](https://github.com/btnalit/pi-claude-supervisor/commit/94742c7c8c8c810843ddb62703d7b3c1fea1254f))
+* **policy:** an environment prefix's dynamic value is not a dynamic argument ([b53e77c](https://github.com/btnalit/pi-claude-supervisor/commit/b53e77c6932851a1c88452bca38c8d5bdf1030b5))
+* **policy:** scope the dynamic-argument veto to the statement holding the sensitive command ([5515a2b](https://github.com/btnalit/pi-claude-supervisor/commit/5515a2b0d746d3d3cd05b0ef4ba86602f92eb072))
+* **redaction:** keep numeric token counts in usage events ([6d4e183](https://github.com/btnalit/pi-claude-supervisor/commit/6d4e1831b588b71175d581764b611e5ed5cbe664))
+* **supervisor:** survive Claude's own background work in an interactive session ([d883b9a](https://github.com/btnalit/pi-claude-supervisor/commit/d883b9a2b187c55693ff2669a1ba4f7f949272d3))
+
 ## [0.7.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.7.0...v0.7.1) (2026-09-17)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {

package/src/decision-worker.ts

@@ -14,7 +14,7 @@ const MAX_DECISION_FIELD_BYTES = 8 * 1024;
 export type DecisionAction =
   | { action: "continue" | "redirect" | "answer"; message: string; reason: string; confidence?: number }
   | { action: "allow_permission" | "deny_permission"; requestId: string; toolUseId: string; reason: string; confidence?: number }
-  | { action: "verify" | "stop" | "park" | "ask_human" | "noop"; reason: string; question?: string; confidence?: number }
+  | { action: "verify" | "stop" | "park" | "ask_human" | "noop" | "wait"; reason: string; question?: string; confidence?: number }
   | { action: "retry"; reason: string; message?: string; confidence?: number };
 
 export interface DecisionContext {
@@ -280,7 +280,7 @@ Current repair round: ${context.repairRound ?? 0}
 Task specification: ${boundedJson(context.spec ?? { goal: context.task })}
 
 Return exactly one JSON object and no markdown:
-{"action":"continue|redirect|answer|allow_permission|deny_permission|verify|retry|stop|park|noop",...}
+{"action":"continue|redirect|answer|allow_permission|deny_permission|verify|retry|stop|park|wait|noop",...}
 For continue/redirect/answer include message and reason. For permission actions include
 requestId and toolUseId. Retry may include a corrective message. Never choose allow_permission
 for a command that crosses the remote push or main/integration merge boundary; the deterministic
@@ -300,7 +300,10 @@ Claude says it will stop; choose stop only for an explicit stop or technical con
 Use park only when the task cannot safely produce a candidate because required evidence,
 authority, or runtime capability is unavailable. A parked candidate is asynchronous and must not
 wait for a human to be online. For an exited event choose verify, park or stop; a noop on an exited event is treated as
-verify. A completed turn or a permission request always requires a concrete action.`;
+verify. Choose wait when the Worker's result says it is waiting for its own background agents,
+tasks or monitors: their completion re-invokes the Worker automatically, a message would only
+interrupt it, and the Supervisor asks you again if the Worker has not resumed within the wait
+timeout. A completed turn or a permission request always requires a concrete action.`;
 }
 
 /**
@@ -544,7 +547,7 @@ function parseDecision(text: string, event: WorkerEvent): DecisionAction {
     const value = distinct[0] as Record<string, unknown>;
     const action = value.action;
     if (typeof action !== "string") throw new Error("missing action");
-    const allowed = new Set(["continue", "redirect", "answer", "allow_permission", "deny_permission", "verify", "retry", "stop", "park", "ask_human", "noop"]);
+    const allowed = new Set(["continue", "redirect", "answer", "allow_permission", "deny_permission", "verify", "retry", "stop", "park", "ask_human", "noop", "wait"]);
     if (!allowed.has(action)) throw new Error(`unsupported action: ${action}`);
     const reason = typeof value.reason === "string" && value.reason.trim() ? boundedDecisionText(value.reason, "reason") : "no reason provided";
     const confidence = value.confidence === undefined ? undefined : typeof value.confidence === "number" && Number.isFinite(value.confidence) && value.confidence >= 0 && value.confidence <= 1
@@ -564,7 +567,7 @@ function parseDecision(text: string, event: WorkerEvent): DecisionAction {
     if (action === "retry") {
       return { action, reason, message: typeof value.message === "string" ? boundedDecisionText(value.message, "message") : undefined, confidence };
     }
-    return { action: action as "verify" | "stop" | "park" | "ask_human" | "noop", reason, question: typeof value.question === "string" ? boundedDecisionText(value.question, "question") : undefined, confidence };
+    return { action: action as "verify" | "stop" | "park" | "ask_human" | "noop" | "wait", reason, question: typeof value.question === "string" ? boundedDecisionText(value.question, "question") : undefined, confidence };
   } catch (error) {
     return { action: "park", reason: `invalid Decision Worker action: ${error instanceof Error ? error.message : String(error)}` };
   }

package/src/policy.ts

@@ -112,10 +112,6 @@ const deniedPatterns = [
   // word (scripts/publish-package.mjs) is not a publication.
   /\b(?:npm|pnpm|yarn)\b(?:\s+-\S+)*\s+publish\b/iu,
   /\b(?:curl|wget)\b[\s\S]*(?:-X\s*(?:POST|PUT|PATCH|DELETE)|--request(?:=|\s+)(?:POST|PUT|PATCH|DELETE)|--method(?:=|\s+)(?:POST|PUT|PATCH|DELETE)|(?:^|\s)(?:-d|--data(?:[-a-z]*)(?:=|\s+)|--post-data(?:=|\s+)|--body-data(?:=|\s+)))[\s\S]*https?:\/\/(?:api\.)?(?:github|gitlab|bitbucket|registry\.npmjs)\b/iu,
-  // A repository/package command with a dynamic argument cannot be
-  // capability-checked (`git $ACTION origin main`); dynamic text elsewhere in a
-  // command is ordinary shell and is not a boundary concern.
-  /\b(?:git|gh|glab|hub|npm|pnpm|yarn)\b[^|;&\n]*(?:\$\{?[^\s`}]+\}?|`[^`]*`|\$\([^)]*\))/iu,
   /--(?:allow-)?dangerously-skip-permissions\b/iu,
   /--permission-mode\s+(?:bypasspermissions|dontask)\b/iu,
   // Only the filesystem root itself; `rm -rf /abs/path/dist` is ordinary local work.
@@ -212,11 +208,10 @@ function evaluateRepositoryBoundary(tokens: readonly ShellToken[], canonical: st
 
   // An argument the lexer cannot see through matters only where it could reach
   // the boundary: a repository, package, network or remote-shell command, or an
-  // interpreter that would execute the expanded text. Dynamic text in an
-  // ordinary local command (`for f in …; echo "$f"`) is Claude's own business.
-  const dynamicSensitive = lower.some((value) => DYNAMIC_SENSITIVE_COMMANDS.has(value.split(/[\\/]/u).at(-1) ?? value))
-    || (lower.some((value) => (value.split(/[\\/]/u).at(-1) ?? value) === "find") && lower.some((value) => FIND_EXEC_ACTIONS.has(value)));
-  if (hasDynamicArgument && (hasGit || hasGhRemote || hasPackagePublication || dynamicSensitive || hasDynamicCommandName(tokens))) {
+  // interpreter that would execute the expanded text, in the same statement.
+  // Dynamic text in an ordinary local command (`for f in …; echo "$f"`) or in
+  // another statement (`npm test; echo "exit $?"`) is Claude's own business.
+  if ((hasDynamicArgument && hasDynamicCommandName(tokens)) || segmentsOf(tokens).some((segment) => hasDynamicSensitiveArgument(segment))) {
     return { decision: "deny", reason: "a repository, package, network or shell command with a dynamic argument cannot be capability-checked" };
   }
   if (/\bgit\b[\s\S]*\b(?:push|merge(?!-)|send-pack|receive-pack|update-ref)\b/iu.test(canonical)
@@ -250,6 +245,43 @@ function evaluateRepositoryBoundary(tokens: readonly ShellToken[], canonical: st
   return undefined;
 }
 
+/** The statements of a command, split on `;`, `&&`, `||`, `|` and `&`. */
+function segmentsOf(tokens: readonly ShellToken[]): ShellToken[][] {
+  const segments: ShellToken[][] = [[]];
+  for (const token of tokens) {
+    if (token.operator && SEGMENT_SPLIT_OPERATORS.has(token.value)) segments.push([]);
+    else segments.at(-1)!.push(token);
+  }
+  return segments.filter((segment) => segment.length > 0);
+}
+
+/** True when one statement combines a dynamic word with a command whose dynamic argument could reach the boundary. */
+function hasDynamicSensitiveArgument(segment: readonly ShellToken[]): boolean {
+  // A leading `NAME=value` prefix sets the environment and a redirection
+  // target names a file; neither reaches the command's argv, so
+  // `npm_config_cache=$TMPDIR/x npm run check` and `git show HEAD:f > $OLD/f`
+  // are literal commands.
+  const words: ShellToken[] = [];
+  let afterRedirect = false;
+  for (const token of segment) {
+    if (token.operator) { afterRedirect = [">", ">>", "<", "<<<"].includes(token.value); continue; }
+    if (!afterRedirect) words.push(token);
+    afterRedirect = false;
+  }
+  let argvStart = 0;
+  while (argvStart < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/u.test(words[argvStart]!.value)) argvStart += 1;
+  if (!words.slice(argvStart).some((token) => token.dynamic)) return false;
+  const values = words.map((token) => token.value);
+  const lower = values.map((value) => value.toLowerCase());
+  const executables = lower.map((value) => value.split(/[\\/]/u).at(-1) ?? value);
+  const canonical = values.join(" ");
+  return values.some((value) => /(?:^|[\\/])git$/iu.test(value) || /^git-(?:send|receive|upload)-pack$/iu.test(value))
+    || containsRemoteCliMutation(canonical)
+    || (lower.some((value) => value === "npm" || value === "pnpm" || value === "yarn") && lower.includes("publish"))
+    || executables.some((executable) => DYNAMIC_SENSITIVE_COMMANDS.has(executable))
+    || (executables.includes("find") && lower.some((value) => FIND_EXEC_ACTIONS.has(value)));
+}
+
 /** A dynamic word in command position (`$CMD …`, `; $CMD`, `do . $file`) could name anything. */
 function hasDynamicCommandName(tokens: readonly ShellToken[]): boolean {
   let commandPosition = true;
@@ -326,9 +358,6 @@ function evaluateTokens(rawTokens: readonly ShellToken[], depth: number): Policy
     if (/\b(?:npm|pnpm|yarn)\b(?:\s+-\S+)*\s+publish\b/iu.test(canonical)) {
       return { decision: "deny", reason: "package publication belongs to the protected release workflow" };
     }
-    if (/\b(?:git|gh|glab|hub|npm|pnpm|yarn)\b[^|;&\n]*(?:\$\{?[^\s`}]+\}?|`[^`]*`|\$\([^)]*\))/iu.test(canonical)) {
-      return { decision: "deny", reason: "a repository or package command with a dynamic argument cannot be capability-checked" };
-    }
     return { decision: "deny", reason: "command matches a prohibited destructive pattern" };
   }
   return { decision: "allow", reason: "command is allowed for unattended local development" };

package/src/redaction.ts

@@ -2,7 +2,9 @@ const sensitiveKeyPattern = /(password|secret|token|api[-_]?key|authorization|cr
 
 /** Recursively redact credential-shaped values before persistence or model prompts. */
 export function redactSensitive(value: unknown, key?: string): unknown {
-  if (key && sensitiveKeyPattern.test(key)) return "[REDACTED]";
+  // A credential is a string; a number or boolean under a sensitive-looking
+  // key (`totalTokens`, `contextTokens`, `maxTokens`) is a count, not a secret.
+  if (key && sensitiveKeyPattern.test(key) && typeof value === "string") return "[REDACTED]";
   if (typeof value === "string") {
     return value
       .replace(/\b(sk-ant-[A-Za-z0-9_-]+)\b/gu, "[REDACTED]")

package/src/supervisor.ts

@@ -98,6 +98,8 @@ export interface SupervisorStartOptions {
   deadlineMs?: number;
   /** Maximum time without worker output; defaults to 20 minutes. Set to 0 to disable. */
   noOutputTimeoutMs?: number;
+  /** After a `wait` decision, how long the Worker may stay silent before the Decision Worker is asked again; defaults to 10 minutes. Set to 0 to disable. */
+  waitTimeoutMs?: number;
   /** Human approval for a review-level worker command. */
   approval?: { actor: "human"; reason: string };
   /** Adopt an existing tmux session instead of starting a new worker. */
@@ -196,6 +198,9 @@ export class Supervisor {
   #workerOutput = "";
   #lastWorkerResult?: Record<string, unknown>;
   #lastTurnCompleted?: WorkerEvent;
+  /** Armed by a `wait` decision: re-asks the Decision Worker if the Worker never resumes on its own. */
+  #waitTimer?: NodeJS.Timeout;
+  #waitTimeoutMs = 10 * 60_000;
   #turn = 0;
   #repairRound = 0;
   #lastFindingSignature?: string;
@@ -324,6 +329,7 @@ export class Supervisor {
     this.#turn = options.initialTurn ?? 0;
     this.#deadlineMs = options.deadlineMs ?? 4 * 60 * 60_000;
     this.#noOutputTimeoutMs = options.noOutputTimeoutMs ?? 20 * 60_000;
+    this.#waitTimeoutMs = options.waitTimeoutMs ?? 10 * 60_000;
     this.#noOutputBaselineAt = undefined;
     this.#verificationAbortController = undefined;
     this.#progressPhase = undefined;
@@ -608,6 +614,8 @@ export class Supervisor {
     if (this.#handledEvents.has(key)) return;
     try {
       let skipDecisionNotify = false;
+      // Any fresh Worker activity supersedes a pending wait.
+      this.#clearWaitTimer();
       if (event.type === "turn_completed") { this.#lastWorkerResult = event.result; this.#lastTurnCompleted = event; }
       // Do not call #pollInternal from within a deferred retry: it would
       // recurse back into #retryDeferredWorkerEvents through #pollInternal's
@@ -901,9 +909,16 @@ export class Supervisor {
         return;
       }
       if (action.action === "continue" || action.action === "redirect" || action.action === "answer") {
+        if (await this.#decisionIsStale(event)) return;
         await this.#sendInternal(action.message);
         return;
       }
+      if (action.action === "wait") {
+        // The Worker will be re-invoked by its own background work; send
+        // nothing, but re-ask if it stays silent for the wait timeout.
+        this.#armWaitTimer(event);
+        return;
+      }
       if (action.action === "verify") {
         if (this.#machine.state === "waiting" && canRepairInPlace(this.#adapter)) {
           this.#machine.transition("verifying");
@@ -938,12 +953,57 @@ export class Supervisor {
         return;
       }
       if (action.action === "retry") {
-        if (action.message?.trim()) await this.#sendInternal(action.message);
-        else await this.#parkCandidate(`Retry requires a concrete corrective instruction: ${action.reason}`, event);
+        if (!action.message?.trim()) { await this.#parkCandidate(`Retry requires a concrete corrective instruction: ${action.reason}`, event); return; }
+        if (await this.#decisionIsStale(event)) return;
+        await this.#sendInternal(action.message);
       }
     });
   }
 
+  /**
+   * A decision about a completed turn is stale once the Worker has started a
+   * new turn on its own (a background agent, task or monitor of its own
+   * re-invoked it). Sending then would be refused by the adapter; it is not a
+   * failure of anything, so record it and let the next turn drive a new decision.
+   */
+  async #decisionIsStale(event: WorkerEvent): Promise<boolean> {
+    const handle = this.#handle;
+    if (!handle || event.type !== "turn_completed") return false;
+    const status = await this.#adapter.getStatus(handle).catch(() => undefined);
+    if (!status || status.activeRequests === undefined || status.activeRequests === 0) return false;
+    await this.#appendEvent({
+      type: "decision_ignored",
+      taskId: this.#task?.taskId,
+      workerId: handle.id,
+      data: { reason: "worker resumed on its own before the decision arrived", eventType: event.type },
+    }).catch(() => {});
+    return true;
+  }
+
+  #armWaitTimer(event: WorkerEvent): void {
+    this.#clearWaitTimer();
+    if (this.#waitTimeoutMs <= 0) return;
+    this.#waitTimer = setTimeout(() => {
+      this.#waitTimer = undefined;
+      void this.#exclusive(async () => {
+        if (!this.#decision || !this.#automation || this.#humanRequired || this.#machine.state !== "waiting" || this.#lastTurnCompleted !== event) return;
+        const handle = this.#handle;
+        if (!handle) return;
+        const status = await this.#adapter.getStatus(handle).catch(() => undefined);
+        if (status?.activeRequests) return;
+        await this.#appendEvent({ type: "wait_expired", taskId: this.#task?.taskId, workerId: handle.id, data: { waitTimeoutMs: this.#waitTimeoutMs } }).catch(() => {});
+        this.#decision.updateContext({ state: this.#machine.state, turn: this.#turn, repairRound: this.#repairRound });
+        this.#decision.replay?.(event);
+      }).catch(() => { /* the watchdog still covers a silent Worker */ });
+    }, this.#waitTimeoutMs);
+    this.#waitTimer.unref?.();
+  }
+
+  #clearWaitTimer(): void {
+    if (this.#waitTimer) clearTimeout(this.#waitTimer);
+    this.#waitTimer = undefined;
+  }
+
   /**
    * Record, best effort, that the task's current branch diverged from the
    * last one observed. The task is anchored to its baseline commit, not to a
@@ -1069,7 +1129,11 @@ export class Supervisor {
       this.#humanRequired = false;
       this.#humanGate = undefined;
       await this.#appendEvent({ type: "automation_resumed", taskId: this.#task?.taskId, workerId: this.#handle?.id });
-      if (this.#decision && this.#machine.state === "waiting" && this.#lastTurnCompleted) {
+      if (this.#decision && this.#machine.state === "waiting" && this.#lastTurnCompleted && this.#handle) {
+        // Replay the last completed turn only if the Worker is really idle; if
+        // it has resumed on its own, its next Stop brings a fresh turn.
+        const status = await this.#adapter.getStatus(this.#handle).catch(() => undefined);
+        if (status?.activeRequests) return;
         this.#decision.updateContext({ state: this.#machine.state, turn: this.#turn, repairRound: this.#repairRound });
         this.#decision.replay?.(this.#lastTurnCompleted);
       }
@@ -1727,6 +1791,7 @@ export class Supervisor {
   #clearWatchdog(): void {
     if (this.#watchdog) clearInterval(this.#watchdog);
     this.#watchdog = undefined;
+    this.#clearWaitTimer();
   }
 
   async #checkWatchdog(): Promise<void> {

package/src/worker/tmux-adapter.ts

@@ -2003,7 +2003,11 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
           record.pendingSentMessages.splice(matchedIndex, 1);
           return {};
         }
-        this.#emit(record, { type: "human_input", handle: record.handle, text: boundTextHead(prompt, 4_096) });
+        // Claude Code delivers its own background-task, monitor and agent
+        // completions through this hook as a user-role message; nobody typed it.
+        if (!isClaudeRuntimePrompt(prompt)) {
+          this.#emit(record, { type: "human_input", handle: record.handle, text: boundTextHead(prompt, 4_096) });
+        }
         record.activeRequests = 1;
         record.inputAt = Date.now();
         record.lastInputAt = new Date().toISOString();
@@ -2277,6 +2281,11 @@ function normalizeForMatch(value: string): string {
   return value.trim().replace(/\s+/gu, " ");
 }
 
+/** True for a prompt Claude Code injected itself (`<task-notification>`, `<system-reminder>`), which a human never typed. */
+function isClaudeRuntimePrompt(prompt: string): boolean {
+  return /^\s*<(?:task-notification|system-reminder)\b/u.test(prompt);
+}
+
 /**
  * A UserPromptSubmit hook reports the prompt as Claude's TUI captured it,
  * which can reflow long pasted text. Treat it as the adapter's own send when