@mrclrchtr/supi-review 2.8.0 → 3.0.0

package/src/tool/agent-review-tools.ts

@@ -1,342 +1,301 @@
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  buildSessionContext,
-  DEFAULT_MAX_BYTES,
-  DEFAULT_MAX_LINES,
-  type ExtensionAPI,
-  formatSize,
-  truncateHead,
-} from "@earendil-works/pi-coding-agent";
-import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
+import { buildSessionContext, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { StatusSpinner } from "@mrclrchtr/supi-core/status-spinner";
 import { loadReviewConfig } from "../config.ts";
-import { isCommitObjectId, summarizeReviewSnapshot } from "../git.ts";
-import { serializeSessionContext } from "../history/collect.ts";
-import { CURRENT_SESSION_REVIEW_MODEL, resolveAgentReviewModel } from "../model.ts";
-import { ReviewPlanStore } from "../session/review-plan-store.ts";
-import type {
-  BriefEvaluation,
-  PreparedAgentReviewDetails,
-  ReviewProgress,
-  ReviewTargetSpec,
-} from "../types.ts";
-import { formatBriefSynthesisFailureCopy } from "../ui/format-content.ts";
-import { formatAgentReviewBatch, formatPreparedAgentReview } from "../ui/review-tool-format.ts";
-import {
-  type AgentReviewProgressDetails,
-  renderPrepareReviewCall,
-  renderPrepareReviewResult,
-  renderRunReviewCall,
-  renderRunReviewResult,
-} from "../ui/review-tool-renderer.ts";
+import { summarizeReviewSnapshot } from "../git.ts";
+import { collectPlannerContext } from "../history/collect.ts";
+import { resolveAgentReviewModel } from "../model.ts";
+import type { ReviewPlanStore } from "../session/review-plan-store.ts";
+import { renderPrepareCall, renderPrepareResult } from "../tui/prepare.ts";
+import { renderRunCall, renderRunResult } from "../tui/run.ts";
+import type { ReviewBatchDetails, ReviewTargetSpec, ReviewTaskResult } from "../types.ts";
 import {
-  type PrepareAgentReviewInput,
-  prepareAgentReviewSchema,
-  type RunAgentReviewInput,
-  runAgentReviewSchema,
+  type PrepareReviewToolInput,
+  parsePrepareReviewToolInput,
+  parseRunReviewToolInput,
+  prepareReviewSchema,
+  runReviewSchema,
 } from "./agent-review-schemas.ts";
-import { prepareAgentReviewPlan, runAgentReviewBatch } from "./agent-review-workflow.ts";
-import { formatChildLifecycleTrace } from "./child-lifecycle-trace.ts";
-import {
-  PREPARE_REVIEW_TOOL_NAME,
-  prepareReviewPromptGuidelines,
-  prepareReviewPromptSnippet,
-  prepareReviewToolDescription,
-  RUN_REVIEW_TOOL_NAME,
-  runReviewToolDescription,
-} from "./guidance.ts";
-
-const TOOL_OUTPUT_CONTRACT =
-  " Output is truncated at 2,000 lines or 50KB; full Markdown is saved to a temporary file when truncated.";
-
-/** Register the two-stage agent-driven Session-Aware Review tools. */
-export function registerAgentReviewTools(
-  pi: ExtensionAPI,
-  planStore = new ReviewPlanStore(),
-): void {
-  pi.registerTool({
-    name: PREPARE_REVIEW_TOOL_NAME,
-    label: "Prepare Review",
-    description: prepareReviewToolDescription + TOOL_OUTPUT_CONTRACT,
-    promptSnippet: prepareReviewPromptSnippet,
-    promptGuidelines: prepareReviewPromptGuidelines,
-    parameters: prepareAgentReviewSchema,
-    // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
-      const input = params as PrepareAgentReviewInput;
-      const configuredModelId = loadReviewConfig(ctx.cwd).agentModel;
-      const model = resolveAgentReviewModel(ctx, configuredModelId);
-      if (!model) {
-        if (configuredModelId === CURRENT_SESSION_REVIEW_MODEL) {
-          throw new Error("No current session model is available for review preparation.");
-        }
-        throw new Error(
-          `Configured agent review model "${configuredModelId}" is not available in Pi's scoped model set. Choose another model in /supi-settings.`,
-        );
-      }
-
-      const target = parseTarget(input);
-      const sessionContext = buildSessionContext(
-        ctx.sessionManager.getEntries(),
-        ctx.sessionManager.getLeafId(),
-      );
-      const serializedContext = serializeSessionContext(sessionContext.messages);
-      const note = input.note?.trim() || undefined;
+import { pageText } from "./output-page.ts";
+import { prepareReview, runReview } from "./review-workflow.ts";
 
-      pi.events.emit("supi:working:start", { source: "supi-review" });
-      try {
-        const outcome = await prepareAgentReviewPlan({
-          cwd: ctx.cwd,
-          target,
-          note,
-          serializedContext,
-          model,
-          signal,
-          planStore,
-          onProgress: (progress) => {
-            onUpdate?.({
-              content: [{ type: "text", text: "Synthesizing review brief…" }],
-              details: prepareProgressDetails(progress),
-            });
-          },
-        });
-        if (outcome.kind !== "prepared") {
-          throw new Error(formatPreparationFailure(outcome));
-        }
-
-        const details: PreparedAgentReviewDetails = {
-          kind: "review-prepared",
-          planId: outcome.plan.id,
-          briefPromptVersion: outcome.plan.briefPromptVersion,
-          generatedBrief: outcome.plan.generatedBrief,
-          snapshot: summarizeReviewSnapshot(outcome.plan.snapshot),
-          snapshotFingerprint: outcome.plan.snapshotFingerprint,
-          modelId: outcome.plan.model.canonicalId,
-        };
-        activateRunTool(pi);
-        return toolResult(formatPreparedAgentReview(details), details, PREPARE_REVIEW_TOOL_NAME);
-      } finally {
-        pi.events.emit("supi:working:end", { source: "supi-review" });
-      }
-    },
-    renderCall(args, theme) {
-      return renderPrepareReviewCall(args, theme);
-    },
-    renderResult(result, { expanded }, theme) {
-      return renderPrepareReviewResult(result, expanded, theme);
-    },
-  });
-
-  pi.registerTool({
-    name: RUN_REVIEW_TOOL_NAME,
-    label: "Run Review",
-    description: runReviewToolDescription + TOOL_OUTPUT_CONTRACT,
-    parameters: runAgentReviewSchema,
-    // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
-      const input = params as RunAgentReviewInput;
-      const progress = createBatchProgress(input.reviewers.map((reviewer) => reviewer.id.trim()));
-
-      pi.events.emit("supi:working:start", { source: "supi-review" });
-      try {
-        const outcome = await runAgentReviewBatch({
-          cwd: ctx.cwd,
-          planId: input.planId,
-          critique: input.critique,
-          revisedBrief: input.revisedBrief,
-          reviewers: input.reviewers,
-          signal,
-          planStore,
-          onBriefEvaluation: (evaluation) => {
-            recordBriefCritique(ctx.cwd, evaluation, input.reviewers.length);
-          },
-          onReviewerProgress: (reviewerId, reviewerProgress) => {
-            progress.reviewers[reviewerId] = reviewerProgress;
-            onUpdate?.({
-              content: [
-                {
-                  type: "text",
-                  text: `Running reviewers… ${progress.completed}/${progress.total} completed`,
-                },
-              ],
-              details: batchProgressDetails(progress),
-            });
-          },
-          onReviewerDone: (reviewerId) => {
-            progress.completed++;
-            progress.reviewers[reviewerId] = {
-              ...(progress.reviewers[reviewerId] ?? { turns: 0, toolUses: 0 }),
-              currentFocus: undefined,
-            };
-            onUpdate?.({
-              content: [
-                {
-                  type: "text",
-                  text: `Running reviewers… ${progress.completed}/${progress.total} completed`,
-                },
-              ],
-              details: batchProgressDetails(progress),
-            });
-          },
-        });
-        if (outcome.kind !== "completed") throw new Error(outcome.reason);
-
-        return toolResult(
-          formatAgentReviewBatch(outcome.details),
-          outcome.details,
-          RUN_REVIEW_TOOL_NAME,
-        );
-      } finally {
-        pi.events.emit("supi:working:end", { source: "supi-review" });
-      }
-    },
-    renderCall(args, theme, context) {
-      return renderRunReviewCall(args, context.expanded, theme);
-    },
-    renderResult(result, { expanded }, theme) {
-      return renderRunReviewResult(result, expanded, theme);
-    },
-  });
-
-  pi.on("session_start", () => {
-    planStore.clear();
-    deactivateRunTool(pi);
-  });
-  pi.on("session_shutdown", () => {
-    planStore.clear();
-  });
+function target(input: PrepareReviewToolInput["target"]): ReviewTargetSpec {
+  return (input ?? { kind: "working-tree" }) as ReviewTargetSpec;
 }
 
-function parseTarget(input: PrepareAgentReviewInput): ReviewTargetSpec {
-  const target = input.target;
-  if (!target) return { kind: "working-tree" };
-  if (target.kind === "working-tree") {
-    if (target.base || target.sha) {
-      throw new Error('target.base and target.sha must be omitted for "working-tree".');
+function formatPrepared(plan: {
+  id: string;
+  snapshot: { title: string; changedFiles: string[] };
+  plannerDraft?: { sharedContext?: string; tasks: Array<{ id: string; instructions: string }> };
+}): string {
+  const lines = [
+    "# Review Plan Prepared",
+    "",
+    `Plan ID: ${plan.id}`,
+    `Target: ${plan.snapshot.title}`,
+    `Files changed: ${plan.snapshot.changedFiles.length}`,
+  ];
+  if (plan.plannerDraft) {
+    lines.push("", "## Planner Draft");
+    if (plan.plannerDraft.sharedContext) lines.push("", plan.plannerDraft.sharedContext);
+    for (const task of plan.plannerDraft.tasks) {
+      lines.push("", `### ${task.id}`, task.instructions);
     }
-    return { kind: "working-tree" };
+    lines.push("", "Call supi_review_run with an explicit accept-draft or use-review decision.");
+  } else {
+    lines.push("", "Call supi_review_run with a use-review decision containing one to four tasks.");
   }
-  if (target.kind === "branch") {
-    if (target.sha) throw new Error('target.sha must be omitted when target.kind is "branch".');
-    const base = target.base?.trim();
-    if (!base) throw new Error('target.base is required when target.kind is "branch".');
-    if (base.startsWith("-")) {
-      throw new Error("target.base must name a local branch, not a Git option.");
-    }
-    return { kind: "branch", base };
+  return lines.join("\n");
+}
+
+function formatTaskResult(result: ReviewTaskResult): string[] {
+  const lines = [
+    "",
+    `## ${result.taskId}`,
+    `Model: ${result.modelId}`,
+    `Packet SHA-256: ${result.packetHash}`,
+  ];
+  if (result.status === "failed") return [...lines, `Status: failed (${result.failureCode})`];
+  if (result.status === "canceled") return [...lines, "Status: canceled"];
+  if (result.status === "timeout") {
+    return [...lines, `Status: timeout (${result.timeoutMs} ms)`];
   }
-  if (target.base) throw new Error('target.base must be omitted when target.kind is "commit".');
-  const sha = target.sha?.trim();
-  if (!sha) throw new Error('target.sha is required when target.kind is "commit".');
-  if (!isCommitObjectId(sha)) {
-    throw new Error("target.sha must be a hexadecimal commit object id (7–64 characters).");
+  lines.push(`Verdict: ${result.verdict.toUpperCase()}`, "", result.summary);
+  for (const finding of result.findings) {
+    lines.push(
+      "",
+      `- ${finding.title} [${finding.blocksAcceptance ? "blocking" : "non-blocking"}; impact ${finding.impact}; effort ${finding.effort}; confidence ${finding.confidence}]`,
+      ...(finding.location
+        ? [
+            `  Location: ${finding.location.path}:${finding.location.startLine}-${finding.location.endLine}`,
+          ]
+        : []),
+      `  ${finding.description}`,
+    );
   }
-  return { kind: "commit", sha };
+  return lines;
 }
 
-function formatPreparationFailure(
-  outcome: Exclude<Awaited<ReturnType<typeof prepareAgentReviewPlan>>, { kind: "prepared" }>,
-): string {
-  if (outcome.kind === "no-snapshot") return outcome.reason;
-
-  const { result } = outcome;
-  const trace = result.diagnostics?.lifecycleTrace;
-  return trace
-    ? `${formatBriefSynthesisFailureCopy(result)}\n\n${formatChildLifecycleTrace(trace)}`
-    : formatBriefSynthesisFailureCopy(result);
+export function formatReviewBatch(details: ReviewBatchDetails): string {
+  const lines = [
+    "# Review Complete",
+    "",
+    `Mode: ${details.mode}`,
+    `Provenance: ${details.provenance}`,
+    `Target: ${details.snapshot.title}`,
+  ];
+  if (details.planning) {
+    lines.push(
+      `Planner: ${details.planning.modelId} (protocol ${details.planning.promptVersion})`,
+      `Planner decision: ${details.planning.decision}`,
+    );
+  }
+  for (const result of details.results) lines.push(...formatTaskResult(result));
+  return lines.join("\n");
 }
 
-function activateRunTool(pi: ExtensionAPI): void {
-  const active = pi.getActiveTools();
-  if (active.includes(RUN_REVIEW_TOOL_NAME)) return;
-  pi.setActiveTools([...active, RUN_REVIEW_TOOL_NAME]);
+function resolveModels(ctx: Parameters<Parameters<ExtensionAPI["registerTool"]>[0]["execute"]>[4]) {
+  const config = loadReviewConfig(ctx.cwd);
+  const reviewer = resolveAgentReviewModel(ctx, config.agentModel);
+  const planner = resolveAgentReviewModel(ctx, config.plannerModel);
+  if (!reviewer)
+    throw new Error(`Configured reviewer model "${config.agentModel}" is unavailable.`);
+  return { reviewer, planner, config };
 }
 
-function deactivateRunTool(pi: ExtensionAPI): void {
-  const active = pi.getActiveTools();
-  if (!active.includes(RUN_REVIEW_TOOL_NAME)) return;
-  pi.setActiveTools(active.filter((name) => name !== RUN_REVIEW_TOOL_NAME));
-}
+/**
+ * Wraps onUpdate to also update a StatusSpinner with progress counts.
+ * Returns the adapted callback that both updates the spinner and calls onUpdate.
+ */
+function wireSpinnerToProgress(
+  // biome-ignore lint/suspicious/noExplicitAny: tool execute ctx type is narrower than ExtensionContext
+  ctx: any,
+  // biome-ignore lint/suspicious/noExplicitAny: onUpdate callback type varies per tool
+  onUpdate: any,
+  startMessage = "Reviewing…",
+): {
+  statusSpinner: StatusSpinner;
+  wrappedUpdate: (result: {
+    content: Array<{ type: "text"; text: string }>;
+    details: Record<string, unknown>;
+  }) => void;
+} {
+  const statusSpinner = new StatusSpinner(ctx, "supi-review");
+  statusSpinner.start(startMessage);
 
-function prepareProgressDetails(progress: ReviewProgress): AgentReviewProgressDetails {
-  return {
-    kind: "review-progress",
-    phase: "prepare",
-    completed: 0,
-    total: 1,
-    reviewers: { synthesis: progress },
+  let completedCount = 0;
+  let totalCount = 0;
+  const wrappedUpdate = (result: {
+    content: Array<{ type: "text"; text: string }>;
+    details: Record<string, unknown>;
+  }) => {
+    const details = result.details as { completedCount?: number; totalCount?: number };
+    completedCount = details.completedCount ?? completedCount;
+    totalCount = details.totalCount ?? totalCount;
+    const label =
+      totalCount > 0
+        ? `Reviewing… (${completedCount} of ${totalCount} tasks complete)`
+        : "Reviewing…";
+    statusSpinner.update(label);
+    onUpdate?.(result);
   };
+  return { statusSpinner, wrappedUpdate };
 }
 
-interface BatchProgressState {
-  completed: number;
-  total: number;
-  reviewers: Record<string, ReviewProgress>;
+/** Compute the initial task count for the progress indicator. */
+function initialTaskCount(
+  input: ReturnType<typeof parseRunReviewToolInput>,
+  planStore: ReviewPlanStore,
+): number {
+  if (input.mode === "direct") return input.review?.tasks?.length ?? 1;
+  if (input.decision?.kind === "use-review") return input.decision.review?.tasks?.length ?? 0;
+  if (input.decision?.kind === "accept-draft") {
+    return planStore.peek(input.planId)?.plannerDraft?.tasks.length ?? 0;
+  }
+  return 0;
 }
 
-function createBatchProgress(reviewerIds: string[]): BatchProgressState {
-  return {
-    completed: 0,
-    total: reviewerIds.length,
-    reviewers: Object.fromEntries(
-      reviewerIds.map((id) => [id, { turns: 0, toolUses: 0 } satisfies ReviewProgress]),
-    ),
+/** Factory for the supi_review_run execute function with animated status-bar spinner. */
+function makeRunReviewExecute(
+  planStore: ReviewPlanStore,
+): NonNullable<Parameters<ExtensionAPI["registerTool"]>[0]["execute"]> {
+  // biome-ignore lint/complexity/useMaxParams: Pi ToolDefinition execute signature
+  return async (_id, params, signal, onUpdate, ctx) => {
+    const input = parseRunReviewToolInput(params);
+
+    const { statusSpinner, wrappedUpdate } = wireSpinnerToProgress(ctx, onUpdate);
+
+    const taskCount = initialTaskCount(input, planStore);
+    wrappedUpdate({
+      content: [{ type: "text", text: "Starting review…" }],
+      details: taskCount > 0 ? { completedCount: 0, totalCount: taskCount } : {},
+    });
+
+    try {
+      const outcome =
+        input.mode === "direct"
+          ? await runReview({
+              mode: "direct",
+              cwd: ctx.cwd,
+              target: input.target,
+              review: input.review,
+              reviewerModel: resolveModels(ctx).reviewer,
+              signal,
+              onUpdate: wrappedUpdate,
+            })
+          : await runReview({
+              mode: "prepared",
+              cwd: ctx.cwd,
+              planId: input.planId,
+              decision: input.decision,
+              planStore,
+              signal,
+              onUpdate: wrappedUpdate,
+            });
+      if (outcome.kind !== "completed") throw new Error(outcome.reason);
+      return {
+        content: [{ type: "text", text: pageText(formatReviewBatch(outcome.details)).text }],
+        details: outcome.details,
+      };
+    } finally {
+      statusSpinner.stop();
+    }
   };
 }
 
-function batchProgressDetails(progress: BatchProgressState): AgentReviewProgressDetails {
-  return {
-    kind: "review-progress",
-    phase: "review",
-    completed: progress.completed,
-    total: progress.total,
-    reviewers: { ...progress.reviewers },
-  };
+/** Throw an actionable error from a non-prepared outcome. */
+function throwPrepareFailure(
+  outcome: { kind: string; reason?: string } & Record<string, unknown>,
+): never {
+  if (outcome.kind === "no-target")
+    throw new Error(outcome.reason ?? "No reviewable changes found.");
+  const result = outcome.result as { kind: string; failureCode?: string; timeoutMs?: number };
+  const diagnostic =
+    result.kind === "failed"
+      ? result.failureCode
+      : result.kind === "timeout"
+        ? `timeout (${result.timeoutMs} ms)`
+        : result.kind;
+  throw new Error(`Planner failed: ${diagnostic}`);
 }
 
-function recordBriefCritique(
-  cwd: string,
-  evaluation: BriefEvaluation,
-  reviewerCount: number,
-): void {
-  recordDebugEvent({
-    source: "supi-review",
-    level: "info",
-    category: "brief-critique",
-    message: `Main agent submitted a brief critique with verdict ${evaluation.critique.verdict}`,
-    cwd,
-    data: {
-      planId: evaluation.planId,
-      briefPromptVersion: evaluation.briefPromptVersion,
-      verdict: evaluation.critique.verdict,
-      findingCount: evaluation.critique.findings.length,
-      reviewerCount,
-      modelId: evaluation.synthesizerModelId,
-      snapshotFingerprint: evaluation.snapshotFingerprint,
+/** Register optional preparation and universal direct/prepared execution tools. */
+export function registerAgentReviewTools(pi: ExtensionAPI, planStore: ReviewPlanStore): void {
+  pi.registerTool({
+    name: "supi_review_prepare",
+    label: "Prepare Review",
+    description: "Create a one-shot Review Plan, optionally with a lightweight Planner Draft.",
+    promptSnippet: "Prepare an optional one-shot code review plan",
+    promptGuidelines: [
+      "Use supi_review_prepare only when a caller wants to inspect or request a Planner Draft before execution.",
+      "Use supi_review_run in direct mode when the current skill or agent already knows the review tasks.",
+    ],
+    parameters: prepareReviewSchema,
+    renderCall: renderPrepareCall,
+    renderResult: renderPrepareResult,
+    // biome-ignore lint/complexity/useMaxParams: Pi ToolDefinition execute signature
+    async execute(_id, params, signal, onUpdate, ctx) {
+      const input = parsePrepareReviewToolInput(params);
+      const models = resolveModels(ctx);
+      if ((input.planning ?? "none") === "suggest" && !models.planner) {
+        throw new Error(`Configured Planner model "${models.config.plannerModel}" is unavailable.`);
+      }
+
+      const { statusSpinner, wrappedUpdate } = wireSpinnerToProgress(
+        ctx,
+        onUpdate,
+        "Preparing review…",
+      );
+
+      try {
+        const session = buildSessionContext(
+          ctx.sessionManager.getEntries(),
+          ctx.sessionManager.getLeafId(),
+        );
+        const outcome = await prepareReview({
+          cwd: ctx.cwd,
+          target: target(input.target),
+          planning: input.planning ?? "none",
+          plannerContext: collectPlannerContext(session.messages),
+          reviewerModel: models.reviewer,
+          plannerModel: models.planner,
+          planStore,
+          signal,
+          onUpdate: wrappedUpdate,
+        });
+        if (outcome.kind !== "prepared") throwPrepareFailure(outcome);
+        return {
+          content: [{ type: "text", text: pageText(formatPrepared(outcome.plan)).text }],
+          details: {
+            kind: "review-prepared",
+            planId: outcome.plan.id,
+            snapshot: summarizeReviewSnapshot(outcome.plan.snapshot),
+            reviewerModelId: outcome.plan.reviewerModel.canonicalId,
+            plannerDraft: outcome.plan.plannerDraft,
+            plannerModelId: outcome.plan.plannerModelId,
+            plannerPromptVersion: outcome.plan.plannerPromptVersion,
+          },
+        };
+      } finally {
+        statusSpinner.stop();
+      }
     },
-    rawData: evaluation,
   });
-}
 
-function toolResult<TDetails>(content: string, details: TDetails, toolName: string) {
-  const truncation = truncateHead(content, {
-    maxLines: DEFAULT_MAX_LINES,
-    maxBytes: DEFAULT_MAX_BYTES,
+  pi.registerTool({
+    name: "supi_review_run",
+    label: "Run Review",
+    description: "Run one to four caller-defined review tasks directly or from a prepared plan.",
+    promptSnippet: "Run independent read-only code review tasks",
+    promptGuidelines: [
+      "Use supi_review_run directly when a skill or the main agent already has complete review task instructions.",
+      "Repository stability from invocation through completion is a caller precondition for supi_review_run.",
+    ],
+    parameters: runReviewSchema,
+    renderCall: renderRunCall,
+    renderResult: renderRunResult,
+    execute: makeRunReviewExecute(planStore),
   });
-  if (!truncation.truncated) {
-    return { content: [{ type: "text" as const, text: truncation.content }], details };
-  }
 
-  const dir = mkdtempSync(join(tmpdir(), "supi-review-"));
-  const file = join(dir, `${toolName}.md`);
-  writeFileSync(file, content, { encoding: "utf-8", mode: 0o600 });
-  const note =
-    `\n\n[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines ` +
-    `(${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). ` +
-    `Full output saved to: ${file}]`;
-  return {
-    content: [{ type: "text" as const, text: truncation.content + note }],
-    details,
-  };
+  pi.on("session_start", () => planStore.clear());
+  pi.on("session_shutdown", () => planStore.clear());
 }

package/src/tool/child-failure-diagnostics.ts

@@ -65,7 +65,7 @@ export function createEarlyCancellationDiagnostics(): ChildFailureDiagnostics {
 
 /** Generate static parent-facing copy for a host-owned child failure code. */
 export function formatChildFailureCopy(stage: ChildStage, code: ChildFailureCode): string {
-  const label = stage === "brief-synthesis" ? "Brief synthesis" : "Reviewer";
+  const label = stage === "planner" ? "Planner" : "Reviewer";
   switch (code) {
     case "session-creation-failed":
       return `${label} session could not be created.`;

package/src/tool/child-resource-loader.ts

@@ -0,0 +1,37 @@
+import { DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+/** Loader and settings manager preconfigured for an isolated child session. */
+export interface IsolatedChildResources {
+  loader: DefaultResourceLoader;
+  settingsManager: SettingsManager;
+}
+
+/**
+ * Build child-session resources with no ambient settings or discovered prompt
+ * content. Compaction and retries stay disabled so provider limits apply to the
+ * original packet directly.
+ */
+export function createIsolatedChildResources(
+  cwd: string,
+  protocolPrompt: string,
+  agentDir = process.env.PI_CODING_AGENT_DIR || "",
+): IsolatedChildResources {
+  const settingsManager = SettingsManager.inMemory({
+    compaction: { enabled: false },
+    retry: { enabled: false },
+  });
+  const loader = new DefaultResourceLoader({
+    cwd,
+    agentDir,
+    settingsManager,
+    noExtensions: true,
+    noSkills: true,
+    noPromptTemplates: true,
+    noThemes: true,
+    noContextFiles: true,
+    appendSystemPrompt: [protocolPrompt],
+    systemPromptOverride: () => undefined,
+    appendSystemPromptOverride: () => [protocolPrompt],
+  });
+  return { loader, settingsManager };
+}