pi-claude-supervisor 0.5.2 → 0.5.3

package/src/index.ts

@@ -7,11 +7,12 @@ import { readFile, realpath } from "node:fs/promises";
 import { EventLog } from "./events.ts";
 import { redactSensitive } from "./redaction.ts";
 import { ProcessWorkerAdapter } from "./worker/process-adapter.ts";
+import { automaticWorkerEnvironment } from "./worker/environment.ts";
 import { TmuxWorkerAdapter, attachCommand } from "./worker/tmux-adapter.ts";
 import { Supervisor, type DecisionSessionClosedInfo, type SupervisorProgress } from "./supervisor.ts";
 import { evaluateCommand } from "./policy.ts";
 import { HumanWebhookNotifier } from "./notifications.ts";
-import { loadSupervisorEnvironment } from "./config.ts";
+import { autonomyDefaults, loadSupervisorEnvironment } from "./config.ts";
 import { DecisionSessionStore, type DecisionSessionRecord } from "./decision-session-store.ts";
 import { CwdLeaseStore, type CwdLeaseHandle, pathsOverlap, workerIdentity } from "./cwd-lease.ts";
 import { normalizeTaskSpec } from "./acceptance.ts";
@@ -41,8 +42,8 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
   if (transport === "tmux" && cgroupMode === "required") {
     throw new Error("PI_CLAUDE_SUPERVISOR_CGROUP_MODE=required is unsupported with tmux; use process-pipe/jsonl or set cgroup mode to auto/off");
   }
-  if (automation && transport === "process-pipe") {
-    throw new Error("automatic supervision requires PI_CLAUDE_SUPERVISOR_TRANSPORT=jsonl or tmux; explicit process-pipe is manual-only");
+  if (automation && transport !== "jsonl") {
+    throw new Error("automatic supervision requires PI_CLAUDE_SUPERVISOR_TRANSPORT=jsonl; process-pipe and tmux are manual-only");
   }
   const adapter = transport === "tmux"
     ? new TmuxWorkerAdapter({ stateDir })
@@ -115,7 +116,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
   };
   const releaseSettledReservations = async (): Promise<void> => {
     for (const [taskId, session] of sessions) {
-      const terminal = ["completed", "stopped", "failed"].includes(session.state);
+      const terminal = ["completed", "blocked", "stopped", "failed"].includes(session.state);
       const detached = session.released;
       if (!terminal && !detached) continue;
       if (!session.handle) {
@@ -165,7 +166,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
       await session.release(reason);
       return;
     }
-    if (!handle && ["failed", "completed", "stopped"].includes(session.state)) return;
+    if (!handle && ["failed", "completed", "blocked", "stopped"].includes(session.state)) return;
     let lifecycleError: unknown;
     try {
       await session.stop(reason, { preserveDecisionSession });
@@ -228,24 +229,17 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           }
           const tmuxSession = operation === "adopt-tmux" ? rest.shift() : undefined;
           const task = rest.join(" ").trim();
-          const spec = specPath ? await readTaskSpecFile(specPath, ctx.cwd) : undefined;
-          const goal = spec?.goal ?? task;
+          const fileSpec = specPath ? await readTaskSpecFile(specPath, ctx.cwd) : undefined;
+          const spec = fileSpec ?? { autonomy: autonomyDefaults() };
+          const goal = fileSpec?.goal ?? task;
+          const taskAutomation = automation && spec.autonomy.unattended;
           if (!goal) throw new Error(operation === "adopt-tmux" ? "Usage: /supervise adopt-tmux [--spec <file>] <tmux-session> <task>" : "Usage: /supervise start [--spec <file>] <task>");
           if (operation === "adopt-tmux" && adapter.capabilities().transport !== "tmux") throw new Error("/supervise adopt-tmux requires PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux");
           const [command, ...workerArgs] = parseCommand(process.env.PI_CLAUDE_SUPERVISOR_WORKER ?? "claude");
           if (!command) throw new Error("PI_CLAUDE_SUPERVISOR_WORKER must contain an executable");
           const policy = evaluateCommand(command, workerArgs);
-          let approval: { actor: "human"; reason: string } | undefined;
+          const approval: { actor: "human"; reason: string } | undefined = undefined;
           if (policy.decision === "deny") throw new Error(`Worker command denied: ${policy.reason}`);
-          if (policy.decision === "review") {
-            if (!ctx.hasUI) throw new Error(`Worker command requires interactive approval: ${policy.reason}`);
-            const approved = await ctx.ui.confirm(
-              "Approve Claude worker command?",
-              `${redactText([command, ...workerArgs].join(" "))}\n\nReason: ${redactText(policy.reason)}`,
-            );
-            if (!approved) throw new Error("Worker command not approved");
-            approval = { actor: "human", reason: policy.reason };
-          }
           if (shuttingDown) throw new Error("Pi session is shutting down");
           const cwdKey = await canonicalCwd(ctx.cwd);
           await releaseSettledReservations();
@@ -266,16 +260,11 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           pendingCwds.add(cwdKey);
           const session = new Supervisor(adapter, events, {
             reviewer,
-            onHumanRequired: async (notice) => {
-              if (ctx.hasUI) notify(ctx, `Claude Worker needs human intervention: ${notice.reason}`, "warning");
+            onCandidate: async (notice) => {
+              if (ctx.hasUI) notify(ctx, `Candidate ${notice.status}: ${notice.reason}`, notice.status === "ready" ? "info" : "warning");
               if (humanWebhook.enabled) {
-                try {
-                  await humanWebhook.notify(notice);
-                } catch (error) {
-                  console.error(`pi-claude-supervisor human webhook failed: ${redactText(error instanceof Error ? error.message : String(error))}`);
-                }
-              } else {
-                console.error(`pi-claude-supervisor human intervention required: ${redactText(notice.reason)}`);
+                try { await humanWebhook.notifyCandidate(notice); }
+                catch (error) { console.error(`pi-claude-supervisor candidate webhook failed: ${redactText(error instanceof Error ? error.message : String(error))}`); }
               }
             },
           });
@@ -291,9 +280,9 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 cwd: cwdKey,
                 command,
                 args: workerArgs,
-                env: selectedWorkerEnvironment(),
+                env: selectedWorkerEnvironment(taskAutomation),
                 approval,
-                automation,
+                automation: taskAutomation,
                 tmuxSession,
                 tmuxSocket: process.env.PI_CLAUDE_SUPERVISOR_TMUX_SOCKET,
                 tmuxExpectedIdentity: tmuxSession && lease.record.worker ? {
@@ -321,6 +310,9 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                     deadlineMs: info.deadlineMs,
                     noOutputTimeoutMs: info.noOutputTimeoutMs,
                     startedAt: info.startedAt,
+                    ...(info.baseCommit ? { baseCommit: info.baseCommit } : {}),
+                    ...(info.baseBranch ? { baseBranch: info.baseBranch } : {}),
+                    ...(info.resolvedExecutable ? { resolvedExecutable: info.resolvedExecutable } : {}),
                     turn: info.turn,
                     repairRound: info.repairRound,
                     ...(info.lastFindingSignature ? { lastFindingSignature: info.lastFindingSignature } : {}),
@@ -455,16 +447,9 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           }
           const policy = evaluateCommand(record.command, record.args);
           if (policy.decision === "deny") throw new Error(`Worker command denied: ${policy.reason}`);
-          let approval = record.approval;
-          if (policy.decision === "review" && !approval) {
-            if (!ctx.hasUI) throw new Error(`Worker command requires interactive approval: ${policy.reason}`);
-            const approved = await ctx.ui.confirm(
-              "Approve recovered Claude worker command?",
-              `${redactText([record.command, ...record.args].join(" "))}\n\nReason: ${redactText(policy.reason)}`,
-            );
-            if (!approved) throw new Error("Worker command not approved");
-            approval = { actor: "human", reason: policy.reason };
-          }
+          const automaticRecovery = record.spec?.autonomy.unattended !== false;
+          if (automaticRecovery && !record.resolvedExecutable) throw new Error("automatic recovery requires a persisted resolved Claude executable identity");
+          const approval = record.approval;
           const lease = await cwdLeaseStore.acquire(cwdKey, record.taskId, adapter.capabilities().transport, takeover
             ? {
               takeover: {
@@ -491,13 +476,11 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           pendingCwds.add(cwdKey);
           const session = new Supervisor(adapter, events, {
             reviewer,
-            onHumanRequired: async (notice) => {
-              if (ctx.hasUI) notify(ctx, `Claude Worker needs human intervention: ${notice.reason}`, "warning");
+            onCandidate: async (notice) => {
+              if (ctx.hasUI) notify(ctx, `Candidate ${notice.status}: ${notice.reason}`, notice.status === "ready" ? "info" : "warning");
               if (humanWebhook.enabled) {
-                try { await humanWebhook.notify(notice); }
-                catch (error) { console.error(`pi-claude-supervisor human webhook failed: ${redactText(error instanceof Error ? error.message : String(error))}`); }
-              } else {
-                console.error(`pi-claude-supervisor human intervention required: ${redactText(notice.reason)}`);
+                try { await humanWebhook.notifyCandidate(notice); }
+                catch (error) { console.error(`pi-claude-supervisor candidate webhook failed: ${redactText(error instanceof Error ? error.message : String(error))}`); }
               }
             },
           });
@@ -518,13 +501,16 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 cwd: cwdKey,
                 command: record.command,
                 args: record.args,
-                env: selectedWorkerEnvironment(),
+                env: selectedWorkerEnvironment(automaticRecovery),
                 approval,
-                automation: true,
+                automation: automaticRecovery,
+                ...(automaticRecovery && record.resolvedExecutable ? { expectedClaudeExecutable: record.resolvedExecutable } : {}),
                 maxTurns: record.maxTurns,
                 deadlineMs: record.deadlineMs,
                 noOutputTimeoutMs: record.noOutputTimeoutMs,
                 startedAt: record.startedAt,
+                baseCommit: record.baseCommit,
+                baseBranch: record.baseBranch,
                 initialTurn: record.turn,
                 initialRepairRound: record.repairRound,
                 initialFindingSignature: record.lastFindingSignature,
@@ -546,6 +532,9 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                     deadlineMs: info.deadlineMs,
                     noOutputTimeoutMs: info.noOutputTimeoutMs,
                     startedAt: info.startedAt,
+                    ...(info.baseCommit ? { baseCommit: info.baseCommit } : {}),
+                    ...(info.baseBranch ? { baseBranch: info.baseBranch } : {}),
+                    ...(info.resolvedExecutable ? { resolvedExecutable: info.resolvedExecutable } : {}),
                     turn: info.turn,
                     repairRound: info.repairRound,
                     ...(info.lastFindingSignature ? { lastFindingSignature: info.lastFindingSignature } : {}),
@@ -775,7 +764,7 @@ function formatSessions(sessions: Map<string, Supervisor>, recoverable: Decision
   return [...active, ...pending].join("\n") || "No task sessions.";
 }
 
-function selectedWorkerEnvironment(): NodeJS.ProcessEnv {
+function selectedWorkerEnvironment(automatic = false): NodeJS.ProcessEnv {
   const result: NodeJS.ProcessEnv = {};
   const names = (process.env.PI_CLAUDE_SUPERVISOR_WORKER_ENV ?? "")
     .split(",")
@@ -784,7 +773,7 @@ function selectedWorkerEnvironment(): NodeJS.ProcessEnv {
   for (const name of names) {
     if (process.env[name] !== undefined) result[name] = process.env[name];
   }
-  return result;
+  return automatic ? automaticWorkerEnvironment(result) : result;
 }
 
 async function readTaskSpecFile(path: string, cwd: string): Promise<TaskSpec> {

package/src/notifications.ts

@@ -1,5 +1,5 @@
 import { createHmac, randomUUID } from "node:crypto";
-import type { HumanInterventionNotice } from "./supervisor.ts";
+import type { CandidateNotice, HumanInterventionNotice } from "./supervisor.ts";
 import { redactSensitive } from "./redaction.ts";
 
 export interface HumanWebhookOptions {
@@ -9,7 +9,7 @@ export interface HumanWebhookOptions {
   timeoutMs?: number;
 }
 
-/** Outbound-only human escalation. Approval still happens through Pi/manual control. */
+/** Optional outbound candidate delivery. It never grants permission or controls the Worker. */
 export class HumanWebhookNotifier {
   readonly #url?: string;
   readonly #format: "generic" | "wecom";
@@ -28,42 +28,60 @@ export class HumanWebhookNotifier {
   async notify(notice: HumanInterventionNotice): Promise<void> {
     if (!this.#url) return;
     const body = this.#format === "wecom" ? JSON.stringify(toWeCom(notice)) : JSON.stringify(toGeneric(notice));
+    await this.#send(body);
+  }
+
+  async notifyCandidate(notice: CandidateNotice): Promise<void> {
+    if (!this.#url) return;
+    const body = this.#format === "wecom" ? JSON.stringify(toWeCom(notice)) : JSON.stringify(toGeneric(notice));
+    await this.#send(body);
+  }
+
+  async #send(body: string): Promise<void> {
     const headers: Record<string, string> = { "content-type": "application/json", "user-agent": "pi-claude-supervisor/0.1" };
     if (this.#secret) headers["x-pi-supervisor-signature"] = `sha256=${createHmac("sha256", this.#secret).update(body).digest("hex")}`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
     try {
-      const response = await fetch(this.#url, { method: "POST", headers, body, signal: controller.signal });
-      if (!response.ok) throw new Error(`human webhook returned HTTP ${response.status}`);
+      const response = await fetch(this.#url!, { method: "POST", headers, body, signal: controller.signal });
+      if (!response.ok) throw new Error(`candidate webhook returned HTTP ${response.status}`);
     } finally {
       clearTimeout(timer);
     }
   }
 }
 
-function toGeneric(notice: HumanInterventionNotice): Record<string, unknown> {
+function toGeneric(notice: HumanInterventionNotice | CandidateNotice): Record<string, unknown> {
+  const candidate = "status" in notice;
   return {
-    schema: "pi-claude-supervisor/human-intervention/v1",
+    schema: candidate ? "pi-claude-supervisor/candidate/v1" : "pi-claude-supervisor/human-intervention/v1",
     eventId: randomUUID(),
-    event: "human_intervention_required",
+    event: candidate ? "candidate_status" : "human_intervention_required",
     occurredAt: new Date().toISOString(),
     task: { id: sanitize(notice.taskId), goal: sanitize(notice.task), cwd: sanitize(notice.cwd) },
     worker: { id: sanitize(notice.workerId) },
     reason: sanitize(notice.reason),
     question: sanitize(notice.question),
     permission: notice.permission ? sanitize(notice.permission) : undefined,
-    actions: ["approve_or_deny_permission", "send_instruction", "stop_worker", "takeover"],
-    note: "This is an outbound notification. Use the Pi session or a separately authenticated callback service to approve actions.",
+    ...(candidate ? { status: notice.status, deliverable: notice.deliverable } : { actions: ["approve_or_deny_permission", "send_instruction", "stop_worker", "takeover"] }),
+    note: candidate
+      ? "This is an optional candidate notification. It does not grant remote push or main/integration merge permission."
+      : "This is an outbound notification. Use the Pi session or a separately authenticated callback service to approve actions.",
   };
 }
 
-function toWeCom(notice: HumanInterventionNotice): Record<string, unknown> {
+function toWeCom(notice: HumanInterventionNotice | CandidateNotice): Record<string, unknown> {
+  const candidate = "status" in notice;
   const permission = notice.permission ? `\n工具: ${safeText(notice.permission.toolName)}\n请求 ID: ${safeText(notice.permission.requestId)}` : "";
   const question = notice.question ? `\n问题: ${safeText(notice.question)}` : "";
+  const title = candidate ? "Claude Supervisor 候选状态" : "Claude Supervisor 需要人工介入";
+  const suffix = candidate
+    ? `\n> 状态: ${safeText(notice.status)}\n> 可交付: ${notice.deliverable ? "yes" : "no"}\n\n该通知不授予远程 push 或 main/integration merge 权限。`
+    : "\n\n请在 Pi 中执行对应的 approve/deny、send、stop 或 takeover 操作。";
   return {
     msgtype: "markdown",
     markdown: {
-      content: `### Claude Supervisor 需要人工介入\n> 任务: ${safeText(notice.task)}\n> Task ID: ${safeText(notice.taskId)}\n> 原因: ${safeText(notice.reason)}${escapeMarkdown(question)}${escapeMarkdown(permission)}\n\n请在 Pi 中执行对应的 approve/deny、send、stop 或 takeover 操作。`,
+      content: `### ${title}\n> 任务: ${safeText(notice.task)}\n> Task ID: ${safeText(notice.taskId)}\n> 原因: ${safeText(notice.reason)}${escapeMarkdown(question)}${escapeMarkdown(permission)}${suffix}`,
     },
   };
 }

package/src/policy.ts

@@ -5,18 +5,28 @@ export interface PolicyResult {
   reason: string;
 }
 
+/**
+ * Permission decisions are autonomous for local development. A denial is a
+ * hard capability boundary, not a request for a human to approve the next
+ * 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 {
-  if (toolName === "AskUserQuestion") return { decision: "review", reason: "Claude requested an interactive product decision" };
-  if (toolName !== "Bash") return { decision: "review", reason: `unknown Claude tool requires review: ${toolName}` };
+  if (toolName === "AskUserQuestion") return { decision: "deny", reason: "interactive questions are converted to ordinary Worker text" };
+  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: "review", reason: "Bash request has no recognizable command" };
+  if (!command) return { decision: "deny", reason: "Bash request has no recognizable command" };
   return evaluateCommand("bash", ["-lc", command]);
 }
 
 const deniedPatterns = [
-  /--dangerously-skip-permissions\b/iu,
+  /\b(?:npm|pnpm|yarn)\b[\s\S]*\bpublish\b/iu,
+  /\b(?:ssh|scp|sftp|rsync)\b/iu,
+  /\b(?:curl|wget)\b[\s\S]*(?:-X\s*(?:POST|PUT|PATCH|DELETE)|--method(?:=|\s+)(?:POST|PUT|PATCH|DELETE)|https?:\/\/(?:api\.)?(?:github|gitlab|bitbucket|registry\.npmjs)\.)/iu,
+  /(?:\$\{?[^\s`}]+\}?|`[^`]*`|\$\([^)]*\))[\s\S]*\b(?:push|merge|publish)\b|\b(?:push|merge|publish)\b[\s\S]*(?:\$\{?[^\s`}]+\}?|`[^`]*`|\$\([^)]*\))/iu,
+  /--(?:allow-)?dangerously-skip-permissions\b/iu,
   /--permission-mode\s+(?:bypasspermissions|dontask)\b/iu,
   /\brm\s+-rf\s+\//iu,
   /\bmkfs(?:\.|\s)/iu,
@@ -25,37 +35,202 @@ const deniedPatterns = [
   /\b(shutdown|reboot|poweroff)\b/iu,
 ];
 
-const reviewPatterns = [
-  /\bgit\s+push\b/iu,
-  /\bgit\s+reset\s+--hard\b/iu,
-  /\bgit\s+(merge|rebase)\b/iu,
-  /\b(npm|pnpm|yarn)\s+publish\b/iu,
-  /\b(curl|wget)\b.*\|\s*(?:\/[\w./-]+\/)?(?:sh|bash|zsh)\b/iu,
-  /\b(chmod|chown)\b/iu,
-];
+interface ShellToken {
+  value: string;
+  operator: boolean;
+  dynamic: boolean;
+}
+
+const protectedBranches = new Set(["main", "master", "trunk", "integration", "develop"]);
+const protectedBranchOperations = new Set(["checkout", "switch", "branch", "reset", "restore", "worktree", "update-ref", "symbolic-ref"]);
+const remoteOperations = new Set(["push", "merge", "send-pack", "receive-pack", "update-ref"]);
 
 export function evaluateCommand(command: string, args: readonly string[] = []): PolicyResult {
-  const normalized = [command, ...args].join(" ").trim();
+  const normalized = command.trim();
   if (!normalized) return { decision: "deny", reason: "empty command" };
-  if (deniedPatterns.some((pattern) => pattern.test(normalized))) {
+  const lexical = lexShell(normalized);
+  if (lexical.error) return { decision: "deny", reason: `command could not be safely parsed: ${lexical.error}` };
+  const literalArgs = args.map((value) => ({ value, operator: false, dynamic: false }));
+  return evaluateTokens([...lexical.tokens, ...literalArgs], 0);
+}
+
+function evaluateRepositoryBoundary(tokens: readonly ShellToken[], canonical: string, depth: number): PolicyResult | undefined {
+  const values = tokens.filter((token) => !token.operator).map((token) => token.value);
+  const lower = values.map((value) => value.toLowerCase());
+  const hasGit = values.some((value) => /(?:^|[\\/])git$/iu.test(value) || /^(?:git-(?:send|receive|upload)-pack)$/iu.test(value));
+  const hasGitTransport = lower.some((value) => /^(?:git-(?:send|receive|upload)-pack)$/u.test(value));
+  const hasRemoteOperation = lower.some((value) => remoteOperations.has(value));
+  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");
+  if (depth < 4) {
+    for (const nested of nestedShellCommands(lower, values)) {
+      const nestedResult = evaluateCommandInternal(nested, depth + 1);
+      if (nestedResult.decision === "deny") return nestedResult;
+    }
+  }
+  const hasDynamicArgument = tokens.some((token) => !token.operator && token.dynamic);
+  const hasProtectedBranch = lower.some((value) => protectedBranches.has(value))
+    || /(?:^|\s)(?:[^\s]*\.git[\\/]refs[\\/]heads[\\/]|[^\s]*refs[\\/]heads[\\/])(?:main|master|trunk|integration|develop)(?:$|\s)/iu.test(canonical);
+  const gitOperation = lower.find((value) => protectedBranchOperations.has(value));
+
+  if (hasDynamicArgument) {
+    return { decision: "deny", reason: "dynamic shell arguments cannot be capability-checked safely" };
+  }
+  if (/\bgit\b[\s\S]*\b(?:push|merge|send-pack|receive-pack|update-ref)\b/iu.test(canonical)
+    || /\bgit-(?:send|receive|upload)-pack\b/iu.test(canonical)
+    || /\b(?:gh|glab|hub)\b[\s\S]*\b(?:api|pr|mr|pull-request|release)\b/iu.test(canonical)) {
+    return { decision: "deny", reason: "Worker has no remote repository or main/integration merge authority" };
+  }
+  if (hasGit && (hasRemoteOperation || hasGitTransport) || hasGhRemote) {
+    return { decision: "deny", reason: "Worker has no remote repository or main/integration merge authority" };
+  }
+  if (hasGit && gitOperation && hasProtectedBranch) {
+    return { decision: "deny", reason: "Worker cannot switch to or mutate a protected integration branch" };
+  }
+  const directRefWrite = tokens.some((token) => token.operator && (token.value === ">" || token.value === ">>"))
+    || ["cp", "echo", "install", "mv", "printf", "sed", "tee"].includes(lower[0] ?? "");
+  if (/\.git[\\/](?:HEAD|packed-refs|refs[\\/]heads[\\/])/iu.test(canonical)
+    || (directRefWrite && hasProtectedBranch && /refs[\\/]heads[\\/]/iu.test(canonical))) {
+    return { decision: "deny", reason: "Worker cannot write protected Git branch refs directly" };
+  }
+  if (hasPackagePublication) {
+    return { decision: "deny", reason: "package publication belongs to the protected release workflow" };
+  }
+  const unsafePermissionMode = (value: string): boolean => value.replace(/[-_]/gu, "") === "bypasspermissions" || value.replace(/[-_]/gu, "") === "dontask";
+  if (lower.some((value) => value.startsWith("--permission-mode=") && unsafePermissionMode(value.slice("--permission-mode=".length)))
+    || (lower.includes("--permission-mode") && lower.some((value) => unsafePermissionMode(value)))) {
+    return { decision: "deny", reason: "Worker cannot bypass Claude permission prompts" };
+  }
+  return undefined;
+}
+
+function nestedShellCommands(lower: readonly string[], values: readonly string[]): string[] {
+  const nested: string[] = [];
+  const shellNames = new Set(["sh", "bash", "dash", "zsh", "fish", "ksh"]);
+  for (let index = 0; index < lower.length; index += 1) {
+    const executable = lower[index]!.split(/[\\/]/u).at(-1);
+    if (executable && shellNames.has(executable)) {
+      for (let option = index + 1; option < lower.length; option += 1) {
+        if (["-c", "--command"].includes(lower[option]!)) {
+          const command = values.slice(option + 1).join(" ").trim();
+          if (command) nested.push(command);
+          break;
+        }
+      }
+    }
+    if (lower[index] === "eval") {
+      const command = values.slice(index + 1).join(" ").trim();
+      if (command) nested.push(command);
+    }
+  }
+  return nested;
+}
+
+function evaluateCommandInternal(command: string, depth: number): PolicyResult {
+  const normalized = command.trim();
+  if (!normalized) return { decision: "deny", reason: "empty command" };
+  const lexical = lexShell(normalized);
+  if (lexical.error) return { decision: "deny", reason: `command could not be safely parsed: ${lexical.error}` };
+  return evaluateTokens(lexical.tokens, depth);
+}
+
+function evaluateTokens(tokens: readonly ShellToken[], depth: number): PolicyResult {
+  const canonical = tokens.map((token) => token.value).join(" ").trim();
+  if (!canonical) return { decision: "deny", reason: "empty command" };
+  const boundary = evaluateRepositoryBoundary(tokens, canonical, depth);
+  if (boundary) return boundary;
+  if (deniedPatterns.some((pattern) => pattern.test(canonical))) {
+    if (/\b(?:curl|wget)\b[\s\S]*(?:github|gitlab|bitbucket|registry\.npmjs)\b/iu.test(canonical)) {
+      return { decision: "deny", reason: "Worker has no remote repository or main/integration merge authority" };
+    }
+    if (/\bgit\b[\s\S]*\b(?:checkout|switch|branch|reset|restore|worktree|update-ref|symbolic-ref)\b[\s\S]*\b(?:main|master|trunk|integration|develop)\b/iu.test(canonical)) {
+      return { decision: "deny", reason: "Worker cannot switch to or mutate a protected integration branch" };
+    }
+    if (/\b(?:npm|pnpm|yarn)\b[\s\S]*\bpublish\b/iu.test(canonical)) {
+      return { decision: "deny", reason: "package publication belongs to the protected release workflow" };
+    }
     return { decision: "deny", reason: "command matches a prohibited destructive pattern" };
   }
-  if (reviewPatterns.some((pattern) => pattern.test(normalized))) {
-    return { decision: "review", reason: "command requires explicit human approval" };
+  return { decision: "allow", reason: "command is allowed for unattended local development" };
+}
+
+function lexShell(input: string): { tokens: ShellToken[]; error?: string } {
+  const tokens: ShellToken[] = [];
+  let value = "";
+  let dynamic = false;
+  let started = false;
+  let quote: "single" | "double" | undefined;
+  const flush = (): void => {
+    if (!started) return;
+    tokens.push({ value, operator: false, dynamic });
+    value = "";
+    dynamic = false;
+    started = false;
+  };
+  const pushOperator = (operator: string): void => {
+    flush();
+    tokens.push({ value: operator, operator: true, dynamic: false });
+  };
+  for (let index = 0; index < input.length; index += 1) {
+    const character = input[index]!;
+    const next = input[index + 1];
+    if (quote === "single") {
+      if (character === "'") quote = undefined;
+      else value += character;
+      started = true;
+      continue;
+    }
+    if (quote === "double") {
+      if (character === '"') quote = undefined;
+      else if (character === "\\" && next === "\n") index += 1;
+      else if (character === "\\" && next !== undefined && /[\\"$`]/u.test(next)) { value += next; index += 1; }
+      else { value += character; if (character === "$" || character === "`") dynamic = true; }
+      started = true;
+      continue;
+    }
+    if (character === "'") { quote = "single"; started = true; continue; }
+    if (character === '"') { quote = "double"; started = true; continue; }
+    if (character === "\\") {
+      if (next === "\n") index += 1;
+      else if (next !== undefined) { value += next; index += 1; }
+      started = true;
+      continue;
+    }
+    if (/\s/u.test(character)) { flush(); continue; }
+    if (character === "$" || character === "`") { dynamic = true; value += character; started = true; continue; }
+    // Brace, tilde and pathname expansion can change command names, targets or
+    // Git refs after this lexical pass. Treat all unquoted expansion markers as
+    // dynamic rather than attempting to model Bash's expansion order.
+    if ("*?[]{}~".includes(character)) { dynamic = true; value += character; started = true; continue; }
+    if (";&|<>".includes(character)) {
+      const operator = next && ((character === "&" && next === "&") || (character === "|" && next === "|") || (character === ">" && next === ">") || (character === "<" && next === "<"))
+        ? `${character}${next}`
+        : character;
+      pushOperator(operator);
+      if (operator.length === 2) index += 1;
+      continue;
+    }
+    value += character;
+    started = true;
   }
-  return { decision: "allow", reason: "command is outside the default high-risk set" };
+  if (quote) return { tokens, error: "unterminated quote" };
+  flush();
+  return { tokens };
 }
 
+/**
+ * Keep the approval argument for persisted v0.5.x records and embedding API
+ * compatibility. It is intentionally not required for local review patterns;
+ * only hard-denied capability boundaries fail this assertion.
+ */
 export function assertSafeWorkerCommand(
   command: string,
   args: readonly string[] = [],
-  approval?: { actor: "human"; reason: string },
+  _approval?: { actor: "human"; reason: string },
 ): void {
   const result = evaluateCommand(command, args);
   if (result.decision === "deny") {
     throw new Error(`Worker command blocked by policy (deny): ${result.reason}`);
   }
-  if (result.decision === "review" && (!approval || approval.actor !== "human" || !approval.reason.trim())) {
-    throw new Error(`Worker command blocked by policy (review): ${result.reason}`);
-  }
 }

package/src/reviewer.ts

@@ -130,7 +130,16 @@ ${boundedJson(input.acceptance)}
 REPOSITORY STATUS:
 ${boundText(redactText(input.evidence.status), 8_000)}
 
-REPOSITORY DIFF (HEAD-RELATIVE, UNTRUSTED):
+REPOSITORY BASE:
+${redactText(input.evidence.baseRef ?? "(unavailable; review current evidence)")}
+
+LOCAL BRANCH:
+${redactText(input.evidence.branch ?? "(detached or unavailable)")}
+
+COMMITS AFTER BASELINE (UNTRUSTED):
+${boundText(redactText(input.evidence.commits ?? "(none)"), 8_000)}
+
+REPOSITORY DIFF (BASELINE-RELATIVE, UNTRUSTED):
 ${boundText(redactText(input.evidence.diff), 16_000)}
 
 UNTRACKED FILE EVIDENCE (UNTRUSTED):
@@ -159,6 +168,22 @@ function textFromMessage(content: unknown): string {
     .join("");
 }
 
+export function normalizeReviewReport(value: unknown, round: number): ReviewReport {
+  try {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return invalidReview("invalid Reviewer output: result must be an object", round, new Date().toISOString());
+    }
+    const report = value as { verdict?: unknown; summary?: unknown; findings?: unknown };
+    if (typeof report.verdict !== "string" || typeof report.summary !== "string" || !report.summary.trim() || !Array.isArray(report.findings)) {
+      return invalidReview("invalid Reviewer output: result must include verdict, summary and findings", round, new Date().toISOString());
+    }
+    const encoded = JSON.stringify(value);
+    return parseReview(encoded ?? "", round);
+  } catch (error) {
+    return invalidReview(`invalid Reviewer output: ${error instanceof Error ? error.message : String(error)}`, round, new Date().toISOString());
+  }
+}
+
 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);

package/src/state.ts

@@ -2,14 +2,15 @@ import type { SupervisorState } from "./types.ts";
 
 const transitions: Record<SupervisorState, readonly SupervisorState[]> = {
   idle: ["starting"],
-  starting: ["running", "failed", "stopped"],
-  running: ["waiting", "paused", "verifying", "failed", "stopped"],
-  waiting: ["running", "paused", "verifying", "failed", "stopped"],
-  paused: ["running", "stopped", "failed"],
-  verifying: ["completed", "running", "failed", "stopped"],
+  starting: ["running", "blocked", "failed", "stopped"],
+  running: ["waiting", "paused", "verifying", "blocked", "failed", "stopped"],
+  waiting: ["running", "paused", "verifying", "blocked", "failed", "stopped"],
+  paused: ["running", "blocked", "stopped", "failed"],
+  verifying: ["completed", "running", "blocked", "failed", "stopped"],
   completed: ["idle"],
+  blocked: ["idle"],
   failed: ["idle"],
-  stopped: ["idle"],
+  stopped: ["idle", "blocked"],
 };
 
 export class InvalidTransitionError extends Error {