pi-claude-supervisor 0.5.3 → 0.5.4

package/src/policy.ts

@@ -1,3 +1,6 @@
+import { lstatSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
 export type PolicyDecision = "allow" | "review" | "deny";
 
 export interface PolicyResult {
@@ -11,16 +14,85 @@ export interface PolicyResult {
  * turn. AskUserQuestion is denied so the Worker can restate the question as
  * ordinary text and the Decision Worker can answer it from task evidence.
  */
-export function evaluatePermission(toolName: string, input: unknown): PolicyResult {
+const allowedWorkerTools = new Set(["Bash", "Edit", "Glob", "Grep", "Read", "Write", "NotebookEdit"]);
+
+export function evaluatePermission(toolName: string, input: unknown, cwd = process.cwd()): PolicyResult {
   if (toolName === "AskUserQuestion") return { decision: "deny", reason: "interactive questions are converted to ordinary Worker text" };
+  if (!allowedWorkerTools.has(toolName)) return { decision: "deny", reason: `Worker tool is outside the automatic allowlist: ${toolName}` };
+  if (toolName === "Edit" || toolName === "Write" || toolName === "NotebookEdit") {
+    const paths = fileToolPaths(input);
+    if (paths.length === 0) return { decision: "deny", reason: `${toolName} request has no recognizable file path` };
+    if (paths.some((path) => isGitMetadataPath(path, cwd))) return { decision: "deny", reason: "Worker cannot write Git metadata or protected branch refs" };
+    return { decision: "allow", reason: `local Claude file tool is allowed by the task policy: ${toolName}` };
+  }
   if (toolName !== "Bash") return { decision: "allow", reason: `local Claude tool is allowed by the task policy: ${toolName}` };
   const command = input && typeof input === "object" && typeof (input as { command?: unknown }).command === "string"
     ? (input as { command: string }).command
     : "";
   if (!command) return { decision: "deny", reason: "Bash request has no recognizable command" };
+  if (containsNestedClaude(command)) {
+    return { decision: "deny", reason: "Worker cannot start a nested Claude or background Reviewer" };
+  }
   return evaluateCommand("bash", ["-lc", command]);
 }
 
+function fileToolPaths(input: unknown): string[] {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return [];
+  const value = input as Record<string, unknown>;
+  return ["file_path", "filePath", "path", "notebook_path", "notebookPath"]
+    .map((key) => value[key])
+    .filter((path): path is string => typeof path === "string" && path.trim().length > 0);
+}
+
+function isGitMetadataPath(value: string, cwd: string): boolean {
+  if (value.replaceAll("\\", "/").split("/").some((segment) => segment.toLowerCase() === ".git")) return true;
+  let root: string;
+  try { root = realpathSync(cwd); }
+  catch { return true; }
+  const raw = value.replaceAll("\\", "/");
+  const canonicalRoot = root.replaceAll("\\", "/").replace(/\/+$/u, "") || "/";
+  let components: string[];
+  if (isAbsolute(value)) {
+    const prefix = canonicalRoot === "/" ? "/" : `${canonicalRoot}/`;
+    if (raw !== canonicalRoot && !raw.startsWith(prefix)) return true;
+    components = raw === canonicalRoot ? [] : raw.slice(prefix.length).split("/");
+  } else {
+    components = raw.split("/");
+  }
+  const normalized: string[] = [];
+  for (const segment of components) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (normalized.length === 0) return true;
+      normalized.pop();
+      continue;
+    }
+    if (segment.toLowerCase() === ".git") return true;
+    const candidate = join(root, ...normalized, segment);
+    try {
+      const info = lstatSync(candidate);
+      if (info.isSymbolicLink()) return true;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") return true;
+    }
+    normalized.push(segment);
+  }
+  const absolute = join(root, ...normalized);
+  try {
+    const info = statSync(absolute);
+    // A regular file with multiple links may be an alias for a Git ref or
+    // other metadata file even when its pathname contains no `.git` segment.
+    if (info.isFile() && info.nlink > 1) return true;
+    const resolved = realpathSync(absolute);
+    if (resolved.replaceAll("\\", "/").split("/").some((segment) => segment.toLowerCase() === ".git")) return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT" && code !== "ENOTDIR") return true;
+  }
+  return false;
+}
+
 const deniedPatterns = [
   /\b(?:npm|pnpm|yarn)\b[\s\S]*\bpublish\b/iu,
   /\b(?:ssh|scp|sftp|rsync)\b/iu,
@@ -63,6 +135,7 @@ function evaluateRepositoryBoundary(tokens: readonly ShellToken[], canonical: st
   const hasGhRemote = lower.some((value) => value === "gh" || value === "glab" || value === "hub")
     && lower.some((value) => value === "api" || value === "release" || value === "pull-request" || value === "pr" || value === "mr");
   const hasPackagePublication = lower.some((value) => value === "npm" || value === "pnpm" || value === "yarn") && lower.includes("publish");
+  const hasGitAliasConfiguration = hasGit && lower.some((value) => /^alias\.[^=]*(?:=|$)/u.test(value));
   if (depth < 4) {
     for (const nested of nestedShellCommands(lower, values)) {
       const nestedResult = evaluateCommandInternal(nested, depth + 1);
@@ -85,6 +158,9 @@ function evaluateRepositoryBoundary(tokens: readonly ShellToken[], canonical: st
   if (hasGit && (hasRemoteOperation || hasGitTransport) || hasGhRemote) {
     return { decision: "deny", reason: "Worker has no remote repository or main/integration merge authority" };
   }
+  if (hasGitAliasConfiguration) {
+    return { decision: "deny", reason: "Worker cannot redefine Git command aliases" };
+  }
   if (hasGit && gitOperation && hasProtectedBranch) {
     return { decision: "deny", reason: "Worker cannot switch to or mutate a protected integration branch" };
   }
@@ -105,6 +181,27 @@ function evaluateRepositoryBoundary(tokens: readonly ShellToken[], canonical: st
   return undefined;
 }
 
+function containsNestedClaude(command: string, depth = 0): boolean {
+  // Bash can hand an opaque quoted program to Python, Node, eval, env,
+  // command, or another interpreter. Once this permission boundary sees a
+  // Claude executable reference, fail closed rather than trying to prove which
+  // wrapper will eventually exec it. This intentionally rejects harmless prose
+  // mentions too; false positives cannot grant a nested Worker capability.
+  if (/\b(?:claude(?:\.exe)?|review(?:er)?|code[-_ ]?review|read[-_ ]?only[-_ ]?review|independent[-_ ]?review|codex|cursor(?:-agent)?|aider|opencode|gemini)\b/iu.test(command)) return true;
+  if (depth > 4) return false;
+  const lexical = lexShell(command);
+  if (lexical.error) return true;
+  for (const token of lexical.tokens) {
+    if (token.operator) continue;
+    const executable = token.value.split(/[\\/]/u).at(-1)?.toLowerCase();
+    if (executable === "claude" || executable === "claude.exe") return true;
+    // Quote concatenation such as c'l'a'u'd'e is normalized by the shell
+    // lexer into one token. Recurse into quoted interpreter payloads too.
+    if (/\s/u.test(token.value) && containsNestedClaude(token.value, depth + 1)) return true;
+  }
+  return false;
+}
+
 function nestedShellCommands(lower: readonly string[], values: readonly string[]): string[] {
   const nested: string[] = [];
   const shellNames = new Set(["sh", "bash", "dash", "zsh", "fish", "ksh"]);

package/src/reviewer.ts

@@ -1,4 +1,5 @@
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager } from "@earendil-works/pi-coding-agent";
+import { isDeepStrictEqual } from "node:util";
 import { redactSensitive } from "./redaction.ts";
 import type { AcceptanceReport, ReviewFinding, ReviewReport, TaskSpec } from "./types.ts";
 import type { RepositoryEvidence } from "./verifier.ts";
@@ -147,7 +148,7 @@ ${boundText(redactText(input.evidence.untracked ?? "(none)"), 16_000)}
 
 EVIDENCE COMPLETE:
 ${String(input.evidence.complete !== false && input.evidence.truncated !== true)}
-If repository evidence is incomplete or truncated, do not return pass; return human and explain which evidence is unavailable.
+DISPLAY NOTE: fields below may end with [DISPLAY_TRUNCATED] because the prompt has a bounded presentation window. This is presentation-only and is not evidence loss. If EVIDENCE COMPLETE is true, do not return human merely because a displayed field is shortened; inspect the repository with the read-only tools instead. If EVIDENCE COMPLETE is false, do not return pass; return human and explain which evidence is unavailable.
 
 WORKER OUTPUT (UNTRUSTED):
 ${boundTailText(redactSensitive(input.workerOutput ?? "(none)"), 8_000)}
@@ -187,17 +188,21 @@ export function normalizeReviewReport(value: unknown, round: number): ReviewRepo
 export function parseReview(text: string, round: number): ReviewReport {
   const checkedAt = new Date().toISOString();
   if (Buffer.byteLength(text, "utf8") > MAX_REVIEW_RESPONSE_BYTES) return invalidReview(`Reviewer response exceeded ${MAX_REVIEW_RESPONSE_BYTES} bytes`, round, checkedAt);
-  const candidate = text.trim();
-  if (!candidate) return invalidReview("Reviewer returned no JSON object", round, checkedAt);
+  if (!text.trim()) return invalidReview("Reviewer returned no JSON object", round, checkedAt);
   try {
-    const value = JSON.parse(candidate) as Record<string, unknown>;
+    const objects = extractJsonObjects(text);
+    if (objects.length === 0) throw new Error("Reviewer output did not contain a JSON object");
+    if (objects.slice(1).some((value) => !isDeepStrictEqual(value, objects[0]))) {
+      throw new Error("Reviewer output contained multiple distinct JSON objects");
+    }
+    const value = objects[0] as Record<string, unknown>;
     if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Reviewer output must be a JSON object");
     const verdict = value.verdict;
     if (verdict !== "pass" && verdict !== "revise" && verdict !== "human") throw new Error("unsupported verdict");
     const summary = typeof value.summary === "string" && value.summary.trim() ? value.summary.trim() : "no summary provided";
-    if (value.findings !== undefined && !Array.isArray(value.findings)) throw new Error("findings must be an array");
-    if (Array.isArray(value.findings) && value.findings.length > MAX_REVIEW_FINDINGS) throw new Error(`findings exceed the limit of ${MAX_REVIEW_FINDINGS}`);
-    const findings = (value.findings ?? []).map((finding, index) => parseFinding(finding, index));
+    if (!Array.isArray(value.findings)) throw new Error("findings must be an array");
+    if (value.findings.length > MAX_REVIEW_FINDINGS) throw new Error(`findings exceed the limit of ${MAX_REVIEW_FINDINGS}`);
+    const findings = value.findings.map((finding, index) => parseFinding(finding, index));
     if (verdict === "revise" && findings.length === 0) throw new Error("revise verdict requires at least one finding");
     return { verdict, summary: boundText(summary, 4_000), findings, round, checkedAt };
   } catch (error) {
@@ -205,6 +210,56 @@ export function parseReview(text: string, round: number): ReviewReport {
   }
 }
 
+/**
+ * Claude occasionally wraps its answer in a fence, a sentence, or repeats
+ * the same JSON object. Extract one bounded object while rejecting conflicting
+ * objects: prose is harmless, but ambiguity must remain non-publishable.
+ */
+function extractJsonObjects(text: string): unknown[] {
+  const objects: unknown[] = [];
+  let offset = 0;
+  while (offset < text.length) {
+    const start = text.indexOf("{", offset);
+    if (start < 0) break;
+    const end = balancedObjectEnd(text, start);
+    if (end < 0) {
+      offset = start + 1;
+      continue;
+    }
+    const candidate = text.slice(start, end + 1);
+    try {
+      const value = JSON.parse(candidate) as unknown;
+      if (value && typeof value === "object" && !Array.isArray(value)) objects.push(value);
+      offset = end + 1;
+    } catch {
+      offset = start + 1;
+    }
+  }
+  return objects;
+}
+
+function balancedObjectEnd(text: string, start: number): number {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = start; index < text.length; index += 1) {
+    const character = text[index];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"') {
+      inString = true;
+      continue;
+    }
+    if (character === "{") depth += 1;
+    else if (character === "}" && --depth === 0) return index;
+  }
+  return -1;
+}
+
 function parseFinding(value: unknown, index: number): ReviewFinding {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`finding ${index} must be an object`);
   const source = value as Record<string, unknown>;
@@ -273,11 +328,11 @@ async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: str
 function boundTailText(value: unknown, maxBytes: number): string {
   const text = String(value);
   if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
-  return `[TRUNCATED]\n${Buffer.from(text, "utf8").subarray(-maxBytes).toString("utf8")}`;
+  return `[DISPLAY_TRUNCATED]\n${Buffer.from(text, "utf8").subarray(-maxBytes).toString("utf8")}`;
 }
 
 function boundText(value: unknown, maxBytes: number): string {
   const text = String(value);
   if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
-  return `${Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8")}\n[TRUNCATED]`;
+  return `${Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8")}\n[DISPLAY_TRUNCATED]`;
 }

package/src/supervisor.ts

@@ -264,8 +264,8 @@ export class Supervisor {
         },
       });
       this.#reportProgress("starting", "preflight and Worker startup");
-      if (this.#automation && this.#adapter.capabilities().transport !== "jsonl") {
-        throw new Error("automatic supervision requires the claude-jsonl transport; tmux is manual-only");
+      if (this.#automation && !["jsonl", "tmux"].includes(this.#adapter.capabilities().transport)) {
+        throw new Error("automatic supervision requires the claude-jsonl or automated tmux transport");
       }
       const workerEnvironment = this.#automation ? automaticWorkerEnvironment(options.env) : options.env;
       if (this.#automation) {
@@ -279,6 +279,7 @@ export class Supervisor {
         args: workerArgs,
         env: workerEnvironment,
         approval: options.approval,
+        automatic: this.#automation,
       });
       this.#assertStartNotAborted(startAbortController.signal);
       if (this.#automation) {
@@ -328,6 +329,7 @@ export class Supervisor {
         tmuxSocket: options.tmuxSocket,
         tmuxExpectedIdentity: options.tmuxExpectedIdentity,
         sendInitialInput: options.sendInitialInput,
+        automatic: this.#automation,
         eventListener: (event) => this.#receiveWorkerEvent(event),
         env: workerEnvironment,
         abortSignal: startAbortController.signal,
@@ -518,7 +520,7 @@ export class Supervisor {
           await this.#parkCandidate(`Permission response is unavailable for ${event.type}`, event);
           return;
         }
-        const policy = evaluatePermission(event.request.toolName, event.request.input);
+        const policy = evaluatePermission(event.request.toolName, event.request.input, task.cwd);
         const behavior = policy.decision === "deny" ? "deny" : action.action === "allow_permission" ? "allow" : "deny";
         await this.#adapter.respondPermission(handle, event.request.requestId, event.request.toolUseId, {
           behavior,
@@ -629,7 +631,7 @@ export class Supervisor {
       const request = requestId ? this.#pendingPermissions.get(requestId) : [...this.#pendingPermissions.values()].at(-1);
       if (!request) throw new Error("no pending permission request");
       if (this.#humanRequired && this.#humanGate !== "permission") throw new Error("automatic decisions are held by a separate human gate; use resume-auto explicitly");
-      const policy = evaluatePermission(request.toolName, request.input);
+      const policy = evaluatePermission(request.toolName, request.input, task.cwd);
       if (policy.decision === "deny" && behavior === "allow") throw new Error(`permission denied by policy: ${policy.reason}`);
       await this.#adapter.respondPermission(handle, request.requestId, request.toolUseId, { behavior: policy.decision === "deny" ? "deny" : behavior }, behavior === "allow" ? request.input : undefined);
       this.#pendingPermissions.delete(request.requestId);

package/src/types.ts

@@ -52,6 +52,8 @@ export interface WorkerStartInput {
   };
   /** Adopted sessions must not replay the task as a new user message. */
   sendInitialInput?: boolean;
+  /** Automatic mode selects the structured tmux bridge instead of the manual TUI transport. */
+  automatic?: boolean;
   /** Cancel startup before a worker is fully returned to the supervisor. */
   abortSignal?: AbortSignal;
   /** Internal token that scopes out-of-band startup cancellation. */
@@ -111,7 +113,7 @@ export interface PermissionDecision {
 export interface WorkerAdapter {
   capabilities(): WorkerCapabilities;
   /** Validate host/transport prerequisites before starting a Worker. */
-  preflight?(input: Pick<WorkerStartInput, "cwd" | "command" | "args" | "env" | "approval">): Promise<void>;
+  preflight?(input: Pick<WorkerStartInput, "cwd" | "command" | "args" | "env" | "approval" | "automatic">): Promise<void>;
   start(input: WorkerStartInput): Promise<WorkerHandle>;
   /** Cancel adapter-owned startup work before a WorkerHandle is returned. */
   abortStart?(reason: string, startupToken?: string): Promise<void>;

package/src/verifier.ts

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { constants as fsConstants } from "node:fs";
-import { lstat, open, realpath } from "node:fs/promises";
+import { lstat, open, readlink, realpath } from "node:fs/promises";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import type { AcceptanceCheck, AcceptanceCheckResult, AcceptanceReport, VerificationResult } from "./types.ts";
@@ -310,6 +310,12 @@ async function collectUntrackedEvidence(cwd: string, signal?: AbortSignal): Prom
         sections.push(`--- ${JSON.stringify(path)} [non-regular file omitted]`);
         continue;
       }
+      if (opened.nlink > 1) {
+        complete = false;
+        sections.push(`--- ${JSON.stringify(path)} [hard-link file omitted]`);
+        continue;
+      }
+      await assertOpenedEvidencePath(root, handle.fd);
       const buffer = Buffer.alloc(MAX_UNTRACKED_FILE_BYTES + 1);
       const read = await handle.read(buffer, 0, buffer.length, 0);
       const bytes = buffer.subarray(0, read.bytesRead);
@@ -338,6 +344,17 @@ async function collectUntrackedEvidence(cwd: string, signal?: AbortSignal): Prom
   return { ...bounded, complete: complete && bounded.complete, truncated: truncated || bounded.truncated };
 }
 
+async function assertOpenedEvidencePath(root: string, fd: number): Promise<void> {
+  if (process.platform !== "linux") throw new Error("opened evidence identity cannot be verified on this platform");
+  const target = (await readlink(`/proc/self/fd/${fd}`)).replace(/ \(deleted\)$/u, "");
+  const normalizedTarget = target.replaceAll("\\", "/");
+  if (normalizedTarget.split("/").some((segment) => segment.toLowerCase() === ".git")) throw new Error("opened evidence path resolves into Git metadata");
+  const relativeTarget = relative(root, target);
+  if (isAbsolute(relativeTarget) || relativeTarget === ".." || relativeTarget.startsWith(`..${sep}`) || relativeTarget.startsWith(`..${"\\"}`)) {
+    throw new Error("opened evidence path escaped the repository root");
+  }
+}
+
 async function assertNoSymlinkComponents(root: string, relativePath: string): Promise<void> {
   const parts = relativePath.split(sep).filter(Boolean);
   let current = root;

package/src/worker/environment.ts

@@ -71,6 +71,24 @@ export function automaticWorkerEnvironment(explicit: NodeJS.ProcessEnv = {}): No
  * operator-owned executable path so a custom path or writable replacement
  * cannot silently omit this boundary.
  */
+const automaticToolAllowlist = new Set([
+  "Bash",
+  "Edit",
+  "Glob",
+  "Grep",
+  "Read",
+  "Write",
+  "NotebookEdit",
+  "AskUserQuestion",
+]);
+
+/**
+ * The automatic Worker is the only Claude session allowed to drive the local
+ * lifecycle. Keep its tool surface explicit: nested agents/background tasks
+ * can start a second reviewer, outlive the Worker, or hide work from the
+ * Supervisor's event stream. The safe-mode and strict-MCP flags also prevent
+ * project/user customizations from reintroducing that capability.
+ */
 export function automaticClaudeArgs(command: string, args: readonly string[] = []): string[] {
   if (!isDirectClaudeName(command)) {
     throw new Error("automatic supervision requires the direct Claude executable command name; custom executable paths need their own host boundary");
@@ -78,8 +96,22 @@ export function automaticClaudeArgs(command: string, args: readonly string[] = [
   if (args.some((arg) => arg === "--settings" || arg.startsWith("--settings="))) {
     throw new Error("automatic Claude supervision controls --settings; remove the caller-provided settings override");
   }
-  return [
-    ...args,
+  for (const option of ["--allowedTools", "--allowed-tools", "--agent", "--agents", "--plugin-dir", "--plugin-url", "--resume", "-r", "--continue", "-c", "--bg", "--background", "--remote-control", "--tmux", "--worktree", "-w"]) {
+    if (args.some((arg) => arg === option || arg.startsWith(`${option}=`))) {
+      throw new Error(`automatic Claude supervision controls ${option}; remove the caller-provided session or tool-extension override`);
+    }
+  }
+  const result = [...args];
+  const tools = requestedAutomaticTools(result);
+  if (tools === undefined) result.push("--tools", [...automaticToolAllowlist].join(","));
+  else if (tools.some((tool) => !automaticToolAllowlist.has(tool))) {
+    throw new Error("automatic Claude supervision permits only the bounded local tool allowlist; nested agents and background reviewers are disabled");
+  }
+  result.push(
+    "--safe-mode",
+    "--strict-mcp-config",
+    "--disallowed-tools",
+    "Task,TaskOutput,Agent,Skill,SendUserMessage",
     "--settings",
     JSON.stringify({
       sandbox: {
@@ -89,7 +121,23 @@ export function automaticClaudeArgs(command: string, args: readonly string[] = [
         network: { allowedDomains: [] },
       },
     }),
-  ];
+  );
+  return result;
+}
+
+function requestedAutomaticTools(args: string[]): string[] | undefined {
+  const index = args.findIndex((arg) => arg === "--tools" || arg.startsWith("--tools="));
+  if (index < 0) return undefined;
+  const values = args[index].startsWith("--tools=")
+    ? [args[index].slice("--tools=".length)]
+    : (() => {
+        const collected: string[] = [];
+        for (let cursor = index + 1; cursor < args.length && !args[cursor]!.startsWith("-"); cursor += 1) collected.push(args[cursor]!);
+        return collected;
+      })();
+  const tools = values.flatMap((value) => value.split(/[\s,]+/u)).map((value) => value.trim()).filter(Boolean);
+  if (tools.includes("default")) throw new Error("automatic Claude supervision requires an explicit tool allowlist; --tools default is not permitted");
+  return tools.map((tool) => tool.replace(/\(.*/u, ""));
 }
 
 /**