pi-claude-supervisor 0.6.0 → 0.7.0

package/src/hooks/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Contract between the Claude Code hook relay (a tiny script configured in
+ * Claude's hook settings) and the Supervisor's hook server. Claude Code runs the
+ * relay for every hook event of an interactive session; the relay forwards the
+ * event over a unix socket and prints the reply as Claude's hook output.
+ */
+
+export type ClaudeHookEventName =
+  | "SessionStart"
+  | "SessionEnd"
+  | "UserPromptSubmit"
+  | "PreToolUse"
+  | "PermissionRequest"
+  | "Stop"
+  | "StopFailure"
+  | "Notification";
+
+/** The subset of Claude Code hook input the Supervisor consumes (all fields untrusted). */
+export interface ClaudeHookEvent {
+  hook_event_name: ClaudeHookEventName;
+  session_id: string;
+  cwd: string;
+  transcript_path?: string;
+  permission_mode?: string;
+  /** SessionStart */
+  source?: string;
+  /** SessionEnd */
+  reason?: string;
+  /** UserPromptSubmit */
+  prompt?: string;
+  /** PreToolUse / PermissionRequest */
+  tool_name?: string;
+  tool_input?: unknown;
+  tool_use_id?: string;
+  /** Stop */
+  last_assistant_message?: string;
+  stop_hook_active?: boolean;
+  /** StopFailure (an API/model error ended the turn; no Stop fires) */
+  error?: unknown;
+  /** Notification */
+  notification_type?: string;
+  message?: string;
+}
+
+export interface HookRelayRequest {
+  version: 1;
+  /** Relay process identity; ppid is the Claude Code process. */
+  pid: number;
+  ppid: number;
+  /** Inherited from Claude's environment when it runs inside tmux. */
+  tmuxPane?: string;
+  event: ClaudeHookEvent;
+}
+
+/**
+ * The Supervisor's answer. `undefined`/empty means "no decision": the relay
+ * prints nothing and Claude Code proceeds with its own permission mode.
+ */
+export interface HookRelayReply {
+  /** PreToolUse / PermissionRequest */
+  permissionDecision?: "allow" | "deny" | "ask";
+  permissionDecisionReason?: string;
+  /** Stop: keep Claude working with this instruction instead of ending the turn. */
+  block?: boolean;
+  blockReason?: string;
+}
+
+/** Hook events the relay waits for a reply on; the rest are fire-and-forget. */
+export const BLOCKING_HOOK_EVENTS: ReadonlySet<ClaudeHookEventName> = new Set(["PreToolUse", "PermissionRequest", "Stop"]);
+
+/** How long Claude waits for the relay before treating the hook as undecided. */
+export const HOOK_TIMEOUT_SECONDS = 180;
+
+/**
+ * Socket routing: one socket per Pi process under `<stateDir>/hooks/`, plus a
+ * per-cwd symlink `<stateDir>/hooks/by-cwd/<sha256(cwd)>` created when the
+ * Supervisor takes the cwd lease, so a relay only needs the cwd to find its
+ * supervisor and a cwd with no supervisor is a no-op.
+ */
+export interface HookEventSource {
+  /** Route every event whose canonical cwd matches to this handler until unsubscribed. */
+  subscribe(cwd: string, handler: (request: HookRelayRequest) => Promise<HookRelayReply | undefined>): Promise<() => Promise<void>>;
+}

package/src/index.ts

@@ -1,24 +1,71 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { accessSync, chmodSync, constants as fsConstants, lstatSync, mkdirSync } from "node:fs";
-import { readFile, realpath } from "node:fs/promises";
+import { chmod, mkdir, readFile, realpath, rename, rm, writeFile } 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 { Supervisor, type DecisionSessionClosedInfo, type HumanInterventionNotice, type SupervisorProgress, type SupervisorTokenUsage } from "./supervisor.ts";
 import { evaluateCommand } from "./policy.ts";
 import { HumanWebhookNotifier } from "./notifications.ts";
-import { autonomyDefaults, loadSupervisorEnvironment } from "./config.ts";
+import { autoInstallHooks, autonomyDefaults, closeWorkerOnCompletion, decisionCompactionTokens, decisionModel, decisionSessionRetentionDays, eventLogMaxBytes, loadSupervisorEnvironment, progressHeartbeatMs, reviewTimeoutMs, reviewerModel, tmuxMode, workerAutocompactTokens, workerMcpConfigPath, workerModel } 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";
 import { PiReadOnlyReviewer } from "./reviewer.ts";
+import { resolvePiModel } from "./pi-model.ts";
+import type { PiModel } from "./decision-worker.ts";
+import { HookServer, hookSocketDirectory } from "./hooks/server.ts";
+import { installUserHooks, uninstallUserHooks } from "./hooks/install.ts";
+import { writeHookSettingsFile } from "./hooks/settings.ts";
+import { HOOK_RELAY_SCRIPT, hookRelayCommand } from "./hooks/relay.ts";
 import type { TaskSpec, WorkerHandle } from "./types.ts";
 
+/** Substring that marks a hook command entry as ours; kept in sync with src/hooks/install.ts's RELAY_MARKER. */
+const RELAY_HOOK_MARKER = "/hooks/relay.js";
+
+function claudeUserSettingsPath(): string {
+  return join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude"), "settings.json");
+}
+
+/** `src/hooks/install.ts` does not export its relay-script writer; this mirrors it for an owned launch's static relay path. */
+async function writeRelayScript(path: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, HOOK_RELAY_SCRIPT, { encoding: "utf8", mode: 0o600, flag: "wx" });
+  await rename(temporary, path);
+  await chmod(path, 0o600);
+}
+
+/** True when the user's Claude Code settings already register our relay for at least one hook event. */
+async function userHooksInstalled(settingsPath: string): Promise<boolean> {
+  let raw: string;
+  try {
+    raw = await readFile(settingsPath, "utf8");
+  } catch {
+    return false;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return false;
+  }
+  const hooks = parsed && typeof parsed === "object" ? (parsed as { hooks?: unknown }).hooks : undefined;
+  if (!hooks || typeof hooks !== "object") return false;
+  return Object.values(hooks as Record<string, unknown>).some((groups) =>
+    Array.isArray(groups) && groups.some((group) =>
+      group && typeof group === "object" && Array.isArray((group as { hooks?: unknown }).hooks)
+      && (group as { hooks: unknown[] }).hooks.some((entry) =>
+        entry && typeof entry === "object" && typeof (entry as { command?: unknown }).command === "string"
+        && (entry as { command: string }).command.includes(RELAY_HOOK_MARKER)
+        && /(?:^|\s)(?:'[^']*\/hooks\/relay\.js'|"[^"]*\/hooks\/relay\.js"|\S*\/hooks\/relay\.js)$/u.test((entry as { command: string }).command.trim()))));
+}
+
 /**
  * Pi Claude Supervisor.
  *
@@ -58,13 +105,82 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
     format: process.env.PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_FORMAT === "wecom" ? "wecom" : "generic",
     secret: process.env.PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_SECRET,
   });
+  const onHumanRequired = (ctx: ExtensionContext) => async (notice: HumanInterventionNotice): Promise<void> => {
+    if (ctx.hasUI) notify(ctx, `Human required: ${notice.reason}${notice.question ? ` — ${notice.question}` : ""}${notice.attach ? ` (${notice.attach})` : ""}`, "warning");
+    // The person who just typed into the session does not need a WeCom alert
+    // telling them so; outbound notices are for decisions nobody is present for.
+    if (humanWebhook.enabled && notice.source !== "worker_prompt") {
+      try { await humanWebhook.notify(notice); }
+      catch (error) { console.error(`pi-claude-supervisor human intervention webhook failed: ${redactText(error instanceof Error ? error.message : String(error))}`); }
+    }
+  };
+  // Hook-driven interactive tmux supervision: the real Claude TUI reports its
+  // events (Stop, permission prompts, AskUserQuestion, human input) through
+  // Claude Code hooks relayed over a unix socket. See docs/architecture.md.
+  const interactiveHooksEnabled = transport === "tmux" && tmuxMode() === "interactive";
+  const hookServer = interactiveHooksEnabled ? new HookServer({ directory: hookSocketDirectory(stateDir) }) : undefined;
+  const relayPath = join(hookSocketDirectory(stateDir), "relay.js");
+  let hookServerReady: Promise<void> | undefined;
+  // Adoption needs the relay in the user's own Claude settings (a running
+  // Claude only picks hooks up from live-reloaded settings files). Installing
+  // at extension load rather than at npm install time keeps it under the
+  // operator's explicit transport configuration, idempotent, and reversible
+  // with /supervise uninstall-hooks; the relay is a ~1 ms no-op when no
+  // Supervisor is listening, so leaving it installed costs nothing.
+  let hookInstallNotice: string | undefined;
+  if (hookServer) {
+    hookServerReady = (async () => {
+      await writeRelayScript(relayPath);
+      await hookServer.listen();
+      if (autoInstallHooks()) {
+        try {
+          const installed = await installUserHooks({ stateDir, settingsPath: claudeUserSettingsPath() });
+          if (installed.changed) hookInstallNotice = `Installed the Claude Code hook relay in ${installed.settingsPath} so running sessions can be adopted (PI_CLAUDE_SUPERVISOR_AUTO_INSTALL_HOOKS=0 disables this; /supervise uninstall-hooks removes it)`;
+        } catch (error) {
+          console.error(`pi-claude-supervisor automatic hook install failed: ${redactText(error instanceof Error ? error.message : String(error))}`);
+        }
+      }
+    })();
+    hookServerReady.catch((error) => {
+      console.error(`pi-claude-supervisor hook server startup failed: ${redactText(error instanceof Error ? error.message : String(error))}`);
+    });
+  }
   const leaseDir = process.env.PI_CLAUDE_SUPERVISOR_CWD_LEASE_DIR ?? join(homedir(), ".pi", "agent", "claude-supervisor", "cwd-leases");
   assertRuntimeDirectory(stateDir, "state");
   assertRuntimeDirectory(leaseDir, "lease");
-  const events = new EventLog(join(stateDir, "events.jsonl"));
+  const events = new EventLog(join(stateDir, "events.jsonl"), { maxBytes: eventLogMaxBytes() });
   const decisionStore = new DecisionSessionStore(join(stateDir, "decision-sessions"));
+  const retentionDays = decisionSessionRetentionDays();
+  if (retentionDays > 0) {
+    void decisionStore.prune({ maxAgeMs: retentionDays * 86_400_000 }).catch((error) => {
+      console.error(`pi-claude-supervisor decision session retention prune failed: ${redactText(error instanceof Error ? error.message : String(error))}`);
+    });
+  }
   const cwdLeaseStore = new CwdLeaseStore(leaseDir);
-  const reviewer = automation ? new PiReadOnlyReviewer() : undefined;
+  const decisionModelSpec = decisionModel();
+  const reviewerModelSpec = reviewerModel();
+  // Resolve once and cache the promise so a misconfigured model fails closed on
+  // every subsequent start/recover rather than silently falling back.
+  let decisionPiModelPromise: Promise<PiModel | undefined> | undefined;
+  // Resolve each model once, but forget a rejected resolution so a transient
+  // failure (or a corrected env file) does not poison the rest of the process.
+  const resolveDecisionPiModel = (): Promise<PiModel | undefined> => {
+    if (!decisionPiModelPromise) {
+      const attempt = resolvePiModel(decisionModelSpec);
+      decisionPiModelPromise = attempt;
+      attempt.catch(() => { if (decisionPiModelPromise === attempt) decisionPiModelPromise = undefined; });
+    }
+    return decisionPiModelPromise;
+  };
+  let reviewerPiModelPromise: Promise<PiModel | undefined> | undefined;
+  const getReviewer = async (): Promise<PiReadOnlyReviewer> => {
+    if (!reviewerPiModelPromise) {
+      const attempt = resolvePiModel(reviewerModelSpec);
+      reviewerPiModelPromise = attempt;
+      attempt.catch(() => { if (reviewerPiModelPromise === attempt) reviewerPiModelPromise = undefined; });
+    }
+    return new PiReadOnlyReviewer({ timeoutMs: reviewTimeoutMs(), model: await reviewerPiModelPromise });
+  };
   const sessions = new Map<string, Supervisor>();
   const cwdLeases = new Map<string, CwdLeaseHandle>();
   const cleanupRequiredTasks = new Set<string>();
@@ -72,6 +188,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
   const pendingCwds = new Set<string>();
   const pendingStarts = new Set<Promise<void>>();
   const pendingStartSessions = new Set<Supervisor>();
+  const unconfirmedSweepAttempts = new Map<string, number>();
   let activeTaskId: string | undefined;
   let shuttingDown = false;
   let shutdownPromise: Promise<void> | undefined;
@@ -96,6 +213,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
   };
   const activeSessions = () => [...sessions.entries()].filter(([, session]) =>
     ["starting", "running", "waiting", "paused"].includes(session.state));
+  const tmuxModeLabel = (): string | undefined => (adapter.capabilities().transport === "tmux" ? tmuxMode() : undefined);
   const releaseLease = async (taskId: string): Promise<boolean> => {
     const lease = cwdLeases.get(taskId);
     if (!lease) return false;
@@ -112,7 +230,11 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
     sessions.delete(taskId);
     reservedCwds.delete(taskId);
     cleanupRequiredTasks.delete(taskId);
+    unconfirmedSweepAttempts.delete(taskId);
     if (activeTaskId === taskId) activeTaskId = undefined;
+    if (interactiveHooksEnabled) {
+      void rm(join(hookSocketDirectory(stateDir), `settings-${taskId}.json`), { force: true }).catch(() => {});
+    }
   };
   const releaseSettledReservations = async (): Promise<void> => {
     for (const [taskId, session] of sessions) {
@@ -123,17 +245,32 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
         if (await releaseLease(taskId)) forgetSession(taskId);
         continue;
       }
+      // A stuck session is otherwise polled at 1 Hz forever; back off to once
+      // every 10 sweeps after the first 10 unconfirmed attempts.
+      const attempts = unconfirmedSweepAttempts.get(taskId) ?? 0;
+      if (!(attempts < 10 || attempts % 10 === 0)) {
+        unconfirmedSweepAttempts.set(taskId, attempts + 1);
+        continue;
+      }
       try {
         const status = await adapter.getStatus(session.handle);
         const adoptedDetachConfirmed = detached
           && session.handle.ownership === "adopted"
           && !status.running;
-        const cleanupConfirmed = status.processGroupCleaned === true || adoptedDetachConfirmed;
-        if (!status.running && cleanupConfirmed && !status.cleanupError && (!status.cgroupError || status.cgroupRequired === false)) {
+        // A hand-back (owned interactive `release()`) leaves the Worker
+        // intentionally running; `detached` is its own cleanup confirmation
+        // and does not wait for `!status.running`.
+        const handedBackConfirmed = status.detached === true;
+        const cleanupConfirmed = status.processGroupCleaned === true || adoptedDetachConfirmed || handedBackConfirmed;
+        if ((handedBackConfirmed || !status.running) && cleanupConfirmed && !status.cleanupError && (!status.cgroupError || status.cgroupRequired === false)) {
           if (await releaseLease(taskId)) forgetSession(taskId);
+          else unconfirmedSweepAttempts.set(taskId, attempts + 1);
+        } else {
+          unconfirmedSweepAttempts.set(taskId, attempts + 1);
         }
       } catch {
         // Keep the reservation when cleanup status cannot be confirmed.
+        unconfirmedSweepAttempts.set(taskId, attempts + 1);
       }
     }
   };
@@ -146,8 +283,8 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
   const workerCleanupConfirmed = async (handle: NonNullable<Supervisor["handle"]>): Promise<boolean> => {
     try {
       const status = await adapter.getStatus(handle);
-      return !status.running
-        && status.processGroupCleaned === true
+      return (status.detached === true || !status.running)
+        && (status.processGroupCleaned === true || status.detached === true)
         && !status.cleanupError
         && (!status.cgroupError || status.cgroupRequired === false);
     } catch {
@@ -155,6 +292,14 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
     }
   };
   const stopSession = async (session: Supervisor, reason: string, releasePersistent = false, preserveDecisionSession = false): Promise<void> => {
+    // Already handed back to the operator (a kept-open interactive session,
+    // or an adopted session released earlier in this same shutdown pass) and
+    // this call is itself a hand-back sweep (`releasePersistent`, used only
+    // at shutdown): there is nothing left to stop, and polling for
+    // `!running` would wait out the deadline against a Worker that is alive
+    // on purpose. An explicit `/supervise stop` (`releasePersistent` false)
+    // must still fall through so it can kill a kept-open session on request.
+    if (session.released && releasePersistent) return;
     const handle = session.handle;
     const persistent = adapter.capabilities().persistentSession && Boolean(handle);
     const taskId = session.task?.taskId;
@@ -232,17 +377,28 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           const fileSpec = specPath ? await readTaskSpecFile(specPath, ctx.cwd) : undefined;
           const spec = fileSpec ?? { autonomy: autonomyDefaults() };
           const goal = fileSpec?.goal ?? task;
-          // Adopted sessions are explicit manual compatibility controls. They
+          // Adopted sessions are explicit manual compatibility controls; they
           // never enter the automatic Reviewer/decision loop, even when the
-          // extension is globally configured for unattended starts.
-          const taskAutomation = operation !== "adopt-tmux" && automation && spec.autonomy.unattended;
+          // extension is globally configured for unattended starts — except
+          // in interactive tmux mode, where an adopted session reports its
+          // own events through hooks exactly like an owned one.
+          const taskAutomation = (operation !== "adopt-tmux" || tmuxMode() === "interactive") && automation && spec.autonomy.unattended;
+          const interactive = taskAutomation && adapter.capabilities().transport === "tmux" && tmuxMode() === "interactive";
           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");
+          if (operation === "adopt-tmux" && interactive && !await userHooksInstalled(claudeUserSettingsPath())) {
+            await hookServerReady?.catch(() => {});
+            if (!await userHooksInstalled(claudeUserSettingsPath())) throw new Error("run /supervise install-hooks first so the adopted session can report its events");
+          }
           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);
           const approval: { actor: "human"; reason: string } | undefined = undefined;
           if (policy.decision === "deny") throw new Error(`Worker command denied: ${policy.reason}`);
+          // Resolve models before any lease/reservation state is mutated below, so
+          // a misconfigured model spec fails closed without leaking a reservation.
+          const decisionPiModel = await resolveDecisionPiModel();
+          const reviewer = taskAutomation ? await getReviewer() : undefined;
           if (shuttingDown) throw new Error("Pi session is shutting down");
           const cwdKey = await canonicalCwd(ctx.cwd);
           await releaseSettledReservations();
@@ -263,19 +419,30 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           }
           pendingCwds.add(cwdKey);
           const session = new Supervisor(adapter, events, {
-            reviewer: taskAutomation ? reviewer : undefined,
+            reviewer,
+            reviewTimeoutMs: reviewTimeoutMs(),
+            progressHeartbeatMs: progressHeartbeatMs(),
+            decisionModel: decisionPiModel,
+            decisionCompactionTokens: decisionCompactionTokens(),
             onCandidate: async (notice) => {
-              if (ctx.hasUI) notify(ctx, `Candidate ${notice.status}: ${notice.reason}`, notice.status === "ready" ? "info" : "warning");
+              if (ctx.hasUI) notify(ctx, `Candidate ${notice.status}: ${notice.reason}${formatUsageSuffix(notice.usage)}`, notice.status === "ready" ? "info" : "warning");
               if (humanWebhook.enabled) {
                 try { await humanWebhook.notifyCandidate(notice); }
                 catch (error) { console.error(`pi-claude-supervisor candidate webhook failed: ${redactText(error instanceof Error ? error.message : String(error))}`); }
               }
             },
+            onHumanRequired: onHumanRequired(ctx),
           });
           pendingStartSessions.add(session);
           let startupCleanupCompleted = false;
+          const hookSettingsPath = interactive && !tmuxSession ? join(hookSocketDirectory(stateDir), `settings-${taskId}.json`) : undefined;
           const startOperation = (async () => {
             try {
+              if (interactive) {
+                if (!hookServer || !hookServerReady) throw new Error("interactive tmux supervision requires PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux");
+                await hookServerReady;
+                if (hookSettingsPath) await writeHookSettingsFile(hookSettingsPath, hookRelayCommand(relayPath));
+              }
               const handle = await session.start({
                 taskId,
                 onProgress: progress(ctx),
@@ -287,7 +454,14 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 env: selectedWorkerEnvironment(taskAutomation),
                 approval,
                 automation: taskAutomation,
+                interactive,
+                hookSource: interactive ? hookServer : undefined,
+                hookSettingsPath,
+                keepWorkerOnCompletion: interactive ? !closeWorkerOnCompletion() : undefined,
                 retainCgroupUntilLeaseRelease: taskAutomation,
+                workerArgOptions: taskAutomation
+                  ? { model: workerModel(), autocompactTokens: workerAutocompactTokens(), mcpConfigPath: workerMcpConfigPath() }
+                  : undefined,
                 onWorkerStartup: taskAutomation
                   ? async (startupHandle) => {
                       await lease.updateWorker({
@@ -364,7 +538,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                     ...(current?.recoveryWorker ? { recoveryWorker: current.recoveryWorker } : {}),
                   });
                 },
-                onDecisionSessionProgress: (info) => decisionStore.update(info.taskId, { turn: info.turn, repairRound: info.repairRound, ...(info.lastFindingSignature ? { lastFindingSignature: info.lastFindingSignature } : {}) }),
+                onDecisionSessionProgress: (info) => decisionStore.update(info.taskId, { turn: info.turn, repairRound: info.repairRound, workerCostUsd: info.workerCostUsd, ...(info.lastFindingSignature ? { lastFindingSignature: info.lastFindingSignature } : {}) }),
                 onDecisionSessionClosed: handleDecisionSessionClosed,
               });
               const startedTaskId = session.task?.taskId;
@@ -489,6 +663,15 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           if (policy.decision === "deny") throw new Error(`Worker command denied: ${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");
+          // The decision-session record does not persist whether the original
+          // task was interactive; the current transport/mode configuration is
+          // used instead, so it must not change between start and recovery.
+          const recoveryInteractive = automaticRecovery && adapter.capabilities().transport === "tmux" && tmuxMode() === "interactive";
+          const recoveryHookSettingsPath = recoveryInteractive ? join(hookSocketDirectory(stateDir), `settings-${record.taskId}.json`) : undefined;
+          // Resolve models before any lease/recovery state is mutated below, so a
+          // misconfigured model spec fails closed without leaking a reservation.
+          const decisionPiModel = await resolveDecisionPiModel();
+          const reviewer = automaticRecovery ? await getReviewer() : undefined;
           const approval = record.approval;
           const lease = await cwdLeaseStore.acquire(cwdKey, record.taskId, adapter.capabilities().transport, {
             startup: automaticRecovery,
@@ -516,19 +699,29 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           }
           pendingCwds.add(cwdKey);
           const session = new Supervisor(adapter, events, {
-            reviewer: automaticRecovery ? reviewer : undefined,
+            reviewer,
+            reviewTimeoutMs: reviewTimeoutMs(),
+            progressHeartbeatMs: progressHeartbeatMs(),
+            decisionModel: decisionPiModel,
+            decisionCompactionTokens: decisionCompactionTokens(),
             onCandidate: async (notice) => {
-              if (ctx.hasUI) notify(ctx, `Candidate ${notice.status}: ${notice.reason}`, notice.status === "ready" ? "info" : "warning");
+              if (ctx.hasUI) notify(ctx, `Candidate ${notice.status}: ${notice.reason}${formatUsageSuffix(notice.usage)}`, notice.status === "ready" ? "info" : "warning");
               if (humanWebhook.enabled) {
                 try { await humanWebhook.notifyCandidate(notice); }
                 catch (error) { console.error(`pi-claude-supervisor candidate webhook failed: ${redactText(error instanceof Error ? error.message : String(error))}`); }
               }
             },
+            onHumanRequired: onHumanRequired(ctx),
           });
           pendingStartSessions.add(session);
           const recoveryOperation = (async () => {
             let startedHandle: WorkerHandle | undefined;
             try {
+              if (recoveryInteractive) {
+                if (!hookServer || !hookServerReady) throw new Error("interactive tmux supervision requires PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux");
+                await hookServerReady;
+                if (recoveryHookSettingsPath) await writeHookSettingsFile(recoveryHookSettingsPath, hookRelayCommand(relayPath));
+              }
               const handle = await session.start({
                 taskId: record.taskId,
                 onProgress: progress(ctx),
@@ -545,7 +738,14 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 env: selectedWorkerEnvironment(automaticRecovery),
                 approval,
                 automation: automaticRecovery,
+                interactive: recoveryInteractive,
+                hookSource: recoveryInteractive ? hookServer : undefined,
+                hookSettingsPath: recoveryHookSettingsPath,
+                keepWorkerOnCompletion: recoveryInteractive ? !closeWorkerOnCompletion() : undefined,
                 retainCgroupUntilLeaseRelease: automaticRecovery,
+                workerArgOptions: automaticRecovery
+                  ? { model: workerModel(), autocompactTokens: workerAutocompactTokens(), mcpConfigPath: workerMcpConfigPath() }
+                  : undefined,
                 onWorkerStartup: automaticRecovery
                   ? async (startupHandle) => {
                       await lease.updateWorker({
@@ -591,6 +791,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 initialTurn: record.turn,
                 initialRepairRound: record.repairRound,
                 initialFindingSignature: record.lastFindingSignature,
+                initialWorkerCostUsd: record.workerCostUsd,
                 decisionSessionFile: record.decisionSessionFile,
                 decisionSessionDir: decisionStore.directory,
                 onDecisionSessionReady: async (info) => {
@@ -623,7 +824,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                     ...(current.recoveryWorker ? { recoveryWorker: current.recoveryWorker } : {}),
                   });
                 },
-                onDecisionSessionProgress: (info) => decisionStore.update(info.taskId, { turn: info.turn, repairRound: info.repairRound, ...(info.lastFindingSignature ? { lastFindingSignature: info.lastFindingSignature } : {}) }),
+                onDecisionSessionProgress: (info) => decisionStore.update(info.taskId, { turn: info.turn, repairRound: info.repairRound, workerCostUsd: info.workerCostUsd, ...(info.lastFindingSignature ? { lastFindingSignature: info.lastFindingSignature } : {}) }),
                 onDecisionSessionClosed: handleDecisionSessionClosed,
               });
               startedHandle = handle;
@@ -704,14 +905,24 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           }
         } else if (operation === "sessions") {
           const recoverable = await decisionStore.list({ activeOnly: true });
-          message = formatSessions(sessions, recoverable);
+          message = formatSessions(sessions, recoverable, tmuxModeLabel());
+          const quarantined = await cwdLeaseStore.quarantined();
+          if (quarantined.length > 0) {
+            message += `\nQuarantined cwd lease records (${quarantined.length}) in ${leaseDir}/quarantine: ${redactText(quarantined.join(", "))}`;
+          }
         } else if (operation === "status") {
           const { session, sessionId } = resolveSession(sessions, activeTaskId, rest, true);
           message = session
-            ? `task=${sessionId} state=${session.state} worker=${session.handle?.id ?? "none"}`
-            : formatSessions(sessions, await decisionStore.list({ activeOnly: true }));
+            ? `task=${sessionId} state=${session.state} worker=${session.handle?.id ?? "none"}${tmuxModeLabel() ? ` mode=${tmuxModeLabel()}` : ""} ${formatUsageDetail(session.usage)}`
+            : formatSessions(sessions, await decisionStore.list({ activeOnly: true }), tmuxModeLabel());
         } else if (operation === "capabilities") {
           message = JSON.stringify(adapter.capabilities(), null, 2);
+        } else if (operation === "install-hooks" || operation === "uninstall-hooks") {
+          const settingsPath = claudeUserSettingsPath();
+          const result = operation === "install-hooks"
+            ? await installUserHooks({ stateDir, settingsPath })
+            : await uninstallUserHooks({ stateDir, settingsPath });
+          message = `${operation}: ${result.changed ? "updated" : "already up to date"} ${result.settingsPath}`;
         } else if (operation === "poll" && rest[0] === "all") {
           const reports = await Promise.all(activeSessions().map(async ([taskId, session]) => {
             const result = await session.poll();
@@ -752,9 +963,10 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           } else if (operation === "resume-auto") {
             await session.resumeAutomation(); message = `Automatic decisions resumed: ${sessionId}.`;
           } else {
-            throw new Error("Usage: /supervise start|adopt-tmux|recover [--takeover]|sessions|status|poll [all|taskId]|send [taskId]|pause [taskId]|resume [taskId]|stop [taskId]|verify [taskId]|approve [taskId] <allow|deny>|takeover [taskId]|resume-auto [taskId]|capabilities");
+            throw new Error("Usage: /supervise start|adopt-tmux|recover [--takeover]|sessions|status|poll [all|taskId]|send [taskId]|pause [taskId]|resume [taskId]|stop [taskId]|verify [taskId]|approve [taskId] <allow|deny>|takeover [taskId]|resume-auto [taskId]|capabilities|install-hooks|uninstall-hooks");
           }
         }
+        if (hookInstallNotice) { notify(ctx, hookInstallNotice); hookInstallNotice = undefined; }
         notify(ctx, message);
       } catch (error) {
         notify(ctx, error instanceof Error ? error.message : String(error), "warning");
@@ -788,6 +1000,18 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
       }
       const results = await Promise.allSettled([...sessions.values()].map((session) => stopSession(session, "Pi session shutdown", true, true)));
       await releaseSettledReservations();
+      if (hookServer) {
+        try {
+          // listen() may still be in flight (e.g. shutdown racing startup, or
+          // a task that never reached an interactive start); close() only
+          // tears down the socket once #server is set, so an unawaited
+          // listen() here would leak an open listening socket forever.
+          if (hookServerReady) await hookServerReady.catch(() => {});
+          await hookServer.close();
+        } catch (error) {
+          console.error(`pi-claude-supervisor hook server shutdown failed: ${redactText(error instanceof Error ? error.message : String(error))}`);
+        }
+      }
       const failures = [...startupFailures, ...results.filter((result): result is PromiseRejectedResult => result.status === "rejected")];
       if (failures.length > 0) {
         for (const failure of failures) console.error(`pi-claude-supervisor shutdown cleanup failed: ${redactText(failure.reason instanceof Error ? failure.reason.message : String(failure.reason))}`);
@@ -832,15 +1056,32 @@ function requiresWorkerCleanup(error: unknown): boolean {
   return Boolean(error && typeof error === "object" && (error as { workerCleanupRequired?: unknown }).workerCleanupRequired === true);
 }
 
-function formatSessions(sessions: Map<string, Supervisor>, recoverable: DecisionSessionRecord[] = []): string {
+function formatSessions(sessions: Map<string, Supervisor>, recoverable: DecisionSessionRecord[] = [], tmuxModeLabel?: string): string {
+  const modeSuffix = tmuxModeLabel ? ` mode=${tmuxModeLabel}` : "";
   const active = [...sessions.entries()]
-    .map(([taskId, session]) => `${taskId} state=${session.state} cwd=${session.task?.cwd ?? "-"} worker=${session.handle?.id ?? "-"}`);
+    .map(([taskId, session]) => `${taskId} state=${session.state} cwd=${session.task?.cwd ?? "-"} worker=${session.handle?.id ?? "-"}${modeSuffix}`);
   const pending = recoverable
     .filter((record) => !sessions.has(record.taskId))
-    .map((record) => `${record.taskId} state=recoverable recovery=${record.recoveryState} cwd=${record.cwd} worker=${record.recoveryWorker?.id ?? "-"}`);
+    .map((record) => `${record.taskId} state=recoverable recovery=${record.recoveryState} cwd=${record.cwd} worker=${record.recoveryWorker?.id ?? "-"}${modeSuffix}`);
   return [...active, ...pending].join("\n") || "No task sessions.";
 }
 
+function tokenTotal(tokens: { input: number; output: number; cacheRead: number; cacheWrite: number }): number {
+  return tokens.input + tokens.output + tokens.cacheRead + tokens.cacheWrite;
+}
+
+function formatUsageDetail(usage: SupervisorTokenUsage): string {
+  const workerTokens = tokenTotal(usage.workerTokens);
+  const piTokens = tokenTotal(usage.decision) + tokenTotal(usage.reviewer);
+  return `cost=$${usage.workerCostUsd.toFixed(2)} workerTurns=${usage.workerTurns} workerTokens=${workerTokens} piTokens=${piTokens} decisionCalls=${usage.decision.calls} reviewerCalls=${usage.reviewer.calls}`;
+}
+
+function formatUsageSuffix(usage?: SupervisorTokenUsage): string {
+  if (!usage) return "";
+  const piTokens = tokenTotal(usage.decision) + tokenTotal(usage.reviewer);
+  return ` (worker $${usage.workerCostUsd.toFixed(2)}, Pi ${piTokens} tokens)`;
+}
+
 function selectedWorkerEnvironment(automatic = false): NodeJS.ProcessEnv {
   if (automatic) return automaticWorkerEnvironment(process.env);
   const result: NodeJS.ProcessEnv = {};

package/src/json-extract.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+export 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;
+}
+
+export 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;
+}