@ilya-lesikov/pi-pi 0.4.0 → 0.6.0

package/3p/pi-ask-user/index.ts

@@ -111,15 +111,35 @@ type AskResponse =
       text: string;
    };
 
+// Reason a question was cancelled. Only "user" (a deliberate top-level ESC)
+// should abort the LLM turn; "timeout" and "signal" are programmatic and must not.
+type CancelReason = "user" | "timeout" | "signal";
+
+// Sentinel returned through the UI/askUser boundary to carry a cancel reason.
+// Distinct from a plain AskResponse so callers can disambiguate cancel vs answer.
+interface AskCancel {
+   __cancel: true;
+   reason: CancelReason;
+}
+
+function makeCancel(reason: CancelReason): AskCancel {
+   return { __cancel: true, reason };
+}
+
+export function isCancel(value: unknown): value is AskCancel {
+   return typeof value === "object" && value !== null && (value as AskCancel).__cancel === true;
+}
+
 interface AskToolDetails {
    question: string;
    context?: string;
    options: QuestionOption[];
    response: AskResponse | null;
    cancelled: boolean;
+   cancelReason?: CancelReason;
 }
 
-type AskUIResult = AskResponse;
+type AskUIResult = AskResponse | AskCancel;
 
 function normalizeOptions(options: AskOptionInput[]): QuestionOption[] {
    return options
@@ -983,7 +1003,6 @@ class WrappedSingleSelectList implements Component {
  */
 class AskComponent extends Container {
    private question: string;
-   private context?: string;
    private options: QuestionOption[];
    private allowMultiple: boolean;
    private allowFreeform: boolean;
@@ -1003,7 +1022,6 @@ class AskComponent extends Container {
    // Static layout components
    private titleText: Text;
    private questionText: Text;
-   private contextComponent?: Component;
    private modeContainer: Container;
    private helpText: Text;
 
@@ -1026,7 +1044,7 @@ class AskComponent extends Container {
 
    constructor(
       question: string,
-      context: string | undefined,
+      _context: string | undefined,
       options: QuestionOption[],
       allowMultiple: boolean,
       allowFreeform: boolean,
@@ -1041,7 +1059,6 @@ class AskComponent extends Container {
       super();
 
       this.question = question;
-      this.context = context;
       this.options = options;
       this.allowMultiple = allowMultiple;
       this.allowFreeform = allowFreeform;
@@ -1067,17 +1084,9 @@ class AskComponent extends Container {
 
       this.questionText = new Text("", 1, 0);
       this.addChild(this.questionText);
-
-      if (this.context) {
-         this.addChild(new Spacer(1));
-         const mdTheme = safeMarkdownTheme();
-         if (mdTheme) {
-            this.contextComponent = new Markdown("", 1, 0, mdTheme);
-         } else {
-            this.contextComponent = new Text("", 1, 0);
-         }
-         this.addChild(this.contextComponent);
-      }
+      // The interactive dialogue intentionally omits a separate context block:
+      // the model output rendered above carries the detail. Only a short, dimmed
+      // question line is shown here to keep the prompt scannable (see LOCKED #2).
 
       this.addChild(new Spacer(1));
 
@@ -1140,29 +1149,19 @@ class AskComponent extends Container {
    private countStaticLines(width: number): number {
       const titleLines = 1;
       const questionLines = this.countWrappedLines(this.question, width);
-      const contextLines = this.context ? 1 + this.countWrappedLines(this.context, width) : 0;
       const helpLines = 1;
       const borderLines = 2;
-      const spacerLines = this.context ? 6 : 5;
-      return borderLines + spacerLines + titleLines + questionLines + contextLines + helpLines;
+      const spacerLines = 5;
+      return borderLines + spacerLines + titleLines + questionLines + helpLines;
    }
 
    private updateStaticText(): void {
       const theme = this.theme;
       const title = this.mode === "comment" ? "Optional comment" : "Question";
       this.titleText.setText(theme.fg("accent", theme.bold(title)));
-      this.questionText.setText(theme.fg("text", theme.bold(this.question)));
-      if (this.contextComponent && this.context) {
-         if (this.contextComponent instanceof Markdown) {
-            (this.contextComponent as Markdown).setText(
-               `**Context:**\n${this.context}`,
-            );
-         } else {
-            (this.contextComponent as Text).setText(
-               `${theme.fg("accent", theme.bold("Context:"))}\n${theme.fg("dim", this.context)}`,
-            );
-         }
-      }
+      // Dimmed, non-bold so it stays visually subordinate to the "Question" title
+      // (accent+bold) above and the richer model output rendered before the dialogue.
+      this.questionText.setText(theme.fg("dim", this.question));
    }
 
    private updateHelpText(): void {
@@ -1171,7 +1170,7 @@ class AskComponent extends Container {
          ? literalHint(theme, this.shortcuts.overlayToggle.spec, "hide")
          : null;
       const commentHint = this.allowComment && !this.shortcuts.commentToggle.disabled
-         ? literalHint(theme, this.shortcuts.commentToggle.spec, "toggle context")
+         ? literalHint(theme, this.shortcuts.commentToggle.spec, "add text")
          : null;
       if (this.mode === "freeform" || this.mode === "comment") {
          const alternateCancelKeys = this.keybindings
@@ -1236,7 +1235,7 @@ class AskComponent extends Container {
          this.shortcuts.commentToggle,
       );
       list.onSubmit = (result) => this.handleSelectionSubmit([result], list.isCommentEnabled());
-      list.onCancel = () => this.onDone(null);
+      list.onCancel = () => this.onDone(makeCancel("user"));
       list.onEnterFreeform = () => this.showFreeformMode();
 
       this.singleSelectList = list;
@@ -1254,7 +1253,7 @@ class AskComponent extends Container {
          this.keybindings,
          this.shortcuts.commentToggle,
       );
-      list.onCancel = () => this.onDone(null);
+      list.onCancel = () => this.onDone(makeCancel("user"));
       list.onSubmit = (result) => this.handleSelectionSubmit(result, list.isCommentEnabled());
       list.onEnterFreeform = () => this.showFreeformMode();
 
@@ -1389,7 +1388,7 @@ class AskComponent extends Container {
          }
 
          if (this.keybindings.matches(data, "tui.select.cancel")) {
-            this.onDone(null);
+            this.onDone(makeCancel("user"));
             return;
          }
 
@@ -1490,14 +1489,14 @@ export async function askUser(
       overlayToggleKey?: string | null;
       commentToggleKey?: string | null;
    },
-): Promise<AskResponse | null> {
+): Promise<AskResponse | AskCancel | null> {
    const {
       question,
       context,
       options: rawOptions = [],
       allowMultiple = false,
       allowFreeform = true,
-      allowComment = false,
+      allowComment = true,
       timeout,
       signal,
       overlay,
@@ -1544,11 +1543,11 @@ export async function askUser(
    try {
       const customFactory = (tui: TUI, theme: Theme, keybindings: KeybindingsManager, done: (result: AskUIResult | null) => void) => {
          if (signal) {
-            const onAbort = () => done(null);
+            const onAbort = () => done(makeCancel("signal"));
             signal.addEventListener("abort", onAbort, { once: true });
          }
          if (timeout && timeout > 0) {
-            setTimeout(() => done(null), timeout);
+            setTimeout(() => done(makeCancel("timeout")), timeout);
          }
          return new AskComponent(
             question,
@@ -1604,11 +1603,12 @@ export default function(pi: ExtensionAPI) {
       name: "ask_user",
       label: "Ask User",
       description:
-         "Ask the user a question with optional multiple-choice answers. Use this to gather information interactively. Ask exactly one focused question per call. Before calling, gather context with tools (read/web/ref) and pass a short summary via the context field.",
+         "Ask the user a question with optional multiple-choice answers. Use this to gather information interactively. Ask exactly one focused question per call. Keep the `question` SHORT — one scannable line; put any reasoning, findings, or detail in your message BEFORE the call, not in the question itself.",
       promptSnippet:
-         "Ask the user one focused question with optional multiple-choice answers to gather information interactively",
+         "Ask the user one short, focused question with optional multiple-choice answers to gather information interactively",
       promptGuidelines: [
-         "Before calling ask_user, gather context with tools (read/web/ref) and pass a short summary via the context field.",
+         "Keep the `question` field SHORT — a single scannable line (ideally under ~100 chars). The dialogue de-emphasizes it; the user reads your detail from the message rendered above the dialogue.",
+         "Put context, reasoning, and findings in your assistant message BEFORE calling ask_user — do NOT pack them into the `question` field.",
          "Use ask_user when the user's intent is ambiguous, when a decision requires explicit user input, or when multiple valid options exist.",
          "Ask exactly one focused question per ask_user call.",
          "Do not combine multiple numbered, multipart, or unrelated questions into one ask_user prompt.",
@@ -1618,7 +1618,7 @@ export default function(pi: ExtensionAPI) {
       // (potentially with side effects) before the user sees the prompt.
       executionMode: "sequential",
       parameters: Type.Object({
-         question: Type.String({ description: "The question to ask the user" }),
+         question: Type.String({ description: "The question to ask the user. Keep it SHORT — one scannable line. Put detail/reasoning in your message above the dialogue, not here." }),
          context: Type.Optional(
             Type.String({
                description: "Relevant context to show before the question (summary of findings)",
@@ -1645,7 +1645,7 @@ export default function(pi: ExtensionAPI) {
             Type.Boolean({ description: "Add a freeform text option. Default: true" }),
          ),
          allowComment: Type.Optional(
-            Type.Boolean({ description: "Collect an optional comment after selecting one or more options. Default: false" }),
+            Type.Boolean({ description: "Collect an optional comment to append after selecting one or more options. Default: true" }),
          ),
          displayMode: Type.Optional(
             StringEnum(["overlay", "inline"] as const, {
@@ -1683,7 +1683,7 @@ export default function(pi: ExtensionAPI) {
             options: rawOptions = [],
             allowMultiple = false,
             allowFreeform = true,
-            allowComment = false,
+            allowComment = true,
             displayMode,
             overlayToggleKey,
             commentToggleKey,
@@ -1712,7 +1712,7 @@ export default function(pi: ExtensionAPI) {
             });
          }
 
-         let result: AskResponse | null;
+         let result: AskResponse | AskCancel | null;
          try {
             result = await askUser(ctx, {
                question,
@@ -1737,11 +1737,27 @@ export default function(pi: ExtensionAPI) {
             };
          }
 
-         if (result === null) {
-            pi.events.emit("ask:cancelled", { question, context: normalizedContext, options });
+         if (result === null || isCancel(result)) {
+            // Only a deliberate top-level user ESC carries reason "user"; timeout and
+            // programmatic signal aborts must NOT abort the LLM turn. A bare null
+            // (e.g. empty submit) is treated as non-user.
+            const cancelReason: CancelReason | undefined = isCancel(result) ? result.reason : undefined;
+            pi.events.emit("ask:cancelled", {
+               question,
+               context: normalizedContext,
+               options,
+               reason: cancelReason,
+            });
             return {
                content: [{ type: "text" as const, text: "User cancelled the question" }],
-               details: { question, context: normalizedContext, options, response: null, cancelled: true } as AskToolDetails,
+               details: {
+                  question,
+                  context: normalizedContext,
+                  options,
+                  response: null,
+                  cancelled: true,
+                  cancelReason,
+               } as AskToolDetails,
             };
          }
 

package/3p/pi-subagents/src/agent-manager.ts

@@ -47,6 +47,8 @@ interface SpawnOptions {
   onTurnEnd?: (turnCount: number) => void;
   validateCompletion?: () => string | undefined;
   maxValidationRetries?: number;
+  /** toolCallId of the parent tool call that spawned this subagent (for trace correlation). */
+  toolCallId?: string;
 }
 
 export class AgentManager {
@@ -120,6 +122,7 @@ export class AgentManager {
   private startAgent(id: string, record: AgentRecord, { pi, ctx, type, prompt, options }: SpawnArgs) {
     record.status = "running";
     record.startedAt = Date.now();
+    if (options.toolCallId && !record.toolCallId) record.toolCallId = options.toolCallId;
     if (options.isBackground) this.runningBackground++;
     this.onStart?.(record);
 
@@ -156,6 +159,10 @@ export class AgentManager {
       onTextDelta: options.onTextDelta,
       validateCompletion: options.validateCompletion,
       maxValidationRetries: options.maxValidationRetries,
+      subagentId: id,
+      subagentType: type,
+      subagentDescription: options.description,
+      parentToolCallId: options.toolCallId ?? record.toolCallId,
       onSessionCreated: (session) => {
         record.session = session;
         // Flush any steers that arrived before the session was ready
@@ -283,6 +290,7 @@ export class AgentManager {
           if (activity.type === "end") record.toolUses++;
         },
         signal,
+        subagentId: id,
       });
       record.status = "completed";
       record.result = responseText;

package/3p/pi-subagents/src/agent-runner.ts

@@ -24,6 +24,72 @@ import type { SubagentType, ThinkingLevel } from "./types.js";
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
 
+const TRACER_KEY = Symbol.for("pi-pi:tracer");
+const SUBAGENT_SESSION_KEY = Symbol.for("pi-pi:subagent-session");
+
+interface PiPiTracer {
+  openSubagent(meta: {
+    subagentId: string;
+    type?: string;
+    description?: string;
+    parentToolCallId?: string;
+    parentSubagentId?: string;
+    depth: number;
+    systemPrompt?: string;
+    effectivePrompt?: string;
+  }): void;
+  traceSubagent(subagentId: string, kind: string, payload: Record<string, unknown>): void;
+}
+
+function getTracer(): PiPiTracer | undefined {
+  return (globalThis as any)[TRACER_KEY];
+}
+
+function subagentDepth(): number {
+  const marker = (globalThis as any)[SUBAGENT_SESSION_KEY];
+  return typeof marker?.depth === "number" ? marker.depth : 1;
+}
+
+function traceSubagentEvent(subagentId: string | undefined, event: AgentSessionEvent, turnIndex: number): void {
+  if (!subagentId) return;
+  const tracer = getTracer();
+  if (!tracer) return;
+  try {
+    switch (event.type) {
+      case "agent_start":
+        tracer.traceSubagent(subagentId, "agent_start", {});
+        break;
+      case "agent_end":
+        tracer.traceSubagent(subagentId, "agent_end", { messages: (event as any).messages, willRetry: (event as any).willRetry });
+        break;
+      case "turn_start":
+        tracer.traceSubagent(subagentId, "turn_start", { turnIndex });
+        break;
+      case "turn_end":
+        tracer.traceSubagent(subagentId, "turn_end", { turnIndex, message: (event as any).message, toolResults: (event as any).toolResults });
+        break;
+      case "message_start":
+        tracer.traceSubagent(subagentId, "message_start", { turnIndex, message: (event as any).message });
+        break;
+      case "message_update":
+        tracer.traceSubagent(subagentId, "message_update", { turnIndex, assistantMessageEvent: (event as any).assistantMessageEvent });
+        break;
+      case "message_end":
+        tracer.traceSubagent(subagentId, "message_end", { turnIndex, message: (event as any).message });
+        break;
+      case "tool_execution_start":
+        tracer.traceSubagent(subagentId, "tool_execution_start", { turnIndex, toolCallId: (event as any).toolCallId, toolName: (event as any).toolName, args: (event as any).args });
+        break;
+      case "tool_execution_update":
+        tracer.traceSubagent(subagentId, "tool_execution_update", { turnIndex, toolCallId: (event as any).toolCallId, toolName: (event as any).toolName, args: (event as any).args, partialResult: (event as any).partialResult });
+        break;
+      case "tool_execution_end":
+        tracer.traceSubagent(subagentId, "tool_execution_end", { turnIndex, toolCallId: (event as any).toolCallId, toolName: (event as any).toolName, result: (event as any).result, isError: (event as any).isError });
+        break;
+    }
+  } catch {}
+}
+
 /** Default max turns. undefined = unlimited (no turn limit). */
 let defaultMaxTurns: number | undefined;
 
@@ -109,6 +175,11 @@ export interface RunOptions {
    */
   validateCompletion?: () => string | undefined;
   maxValidationRetries?: number;
+  /** Correlation IDs for session tracing. */
+  subagentId?: string;
+  subagentType?: string;
+  subagentDescription?: string;
+  parentToolCallId?: string;
 }
 
 export interface RunResult {
@@ -171,6 +242,8 @@ export async function runAgent(
 
   // Resolve working directory: worktree override > parent cwd
   const effectiveCwd = options.cwd ?? ctx.cwd;
+  // Shared marker with extensions/orchestrator/index.ts (SUBAGENT_SESSION_KEY).
+  // Canonical shape is { depth: number }; a legacy boolean true is tolerated as depth 1.
   const subagentSessionKey = Symbol.for("pi-pi:subagent-session");
   const previousSubagentSession = (globalThis as any)[subagentSessionKey];
   const previousDepth = typeof previousSubagentSession === "object" && previousSubagentSession !== null
@@ -178,7 +251,10 @@ export async function runAgent(
     : previousSubagentSession
       ? 1
       : 0;
-  const subagentSessionState = { depth: previousDepth + 1 };
+  const parentSubagentId = typeof previousSubagentSession === "object" && previousSubagentSession !== null
+    ? (previousSubagentSession as { subagentId?: string }).subagentId
+    : undefined;
+  const subagentSessionState = { depth: previousDepth + 1, subagentId: options.subagentId };
   (globalThis as any)[subagentSessionKey] = subagentSessionState;
 
   try {
@@ -332,16 +408,7 @@ export async function runAgent(
 
     let currentMessageText = "";
     const unsubTurns = session.subscribe((event: AgentSessionEvent) => {
-      if (event.type === "session_shutdown") {
-      }
-      if (event.type === "agent_start") {
-      }
-      if (event.type === "turn_start") {
-      }
-      if (event.type === "message_start") {
-      }
-      if (event.type === "tool_execution_start") {
-      }
+      traceSubagentEvent(options.subagentId, event, turnCount);
       if (event.type === "turn_end") {
         turnCount++;
         const msg = (event as any).message;
@@ -385,6 +452,21 @@ export async function runAgent(
       }
     }
 
+    if (options.subagentId) {
+      try {
+        getTracer()?.openSubagent({
+          subagentId: options.subagentId,
+          type: options.subagentType ?? type,
+          description: options.subagentDescription,
+          parentToolCallId: options.parentToolCallId,
+          parentSubagentId,
+          depth: subagentDepth(),
+          systemPrompt,
+          effectivePrompt,
+        });
+      } catch {}
+    }
+
     try {
       await session.prompt(effectivePrompt);
 
@@ -436,23 +518,34 @@ export async function runAgent(
 export async function resumeAgent(
   session: AgentSession,
   prompt: string,
-  options: { onToolActivity?: (activity: ToolActivity) => void; signal?: AbortSignal } = {},
+  options: { onToolActivity?: (activity: ToolActivity) => void; signal?: AbortSignal; subagentId?: string } = {},
 ): Promise<string> {
   const collector = collectResponseText(session);
   const cleanupAbort = forwardAbortSignal(session, options.signal);
 
-  const unsubToolUse = options.onToolActivity
-    ? session.subscribe((event: AgentSessionEvent) => {
-        if (event.type === "tool_execution_start") options.onToolActivity!({ type: "start", toolName: event.toolName });
-        if (event.type === "tool_execution_end") options.onToolActivity!({ type: "end", toolName: event.toolName });
-      })
-    : () => {};
+  // Seed from prior assistant turns so resumed turn indexes don't collide with
+  // the turns already written to this subagent's trace file.
+  let resumeTurnCount = session.messages.filter((m) => m.role === "assistant").length;
+  const unsubTrace = session.subscribe((event: AgentSessionEvent) => {
+    traceSubagentEvent(options.subagentId, event, resumeTurnCount);
+    if (event.type === "turn_end") resumeTurnCount++;
+    if (options.onToolActivity) {
+      if (event.type === "tool_execution_start") options.onToolActivity({ type: "start", toolName: event.toolName });
+      if (event.type === "tool_execution_end") options.onToolActivity({ type: "end", toolName: event.toolName });
+    }
+  });
+
+  if (options.subagentId) {
+    try {
+      getTracer()?.traceSubagent(options.subagentId, "resume_start", { prompt });
+    } catch {}
+  }
 
   try {
     await session.prompt(prompt);
   } finally {
     collector.unsubscribe();
-    unsubToolUse();
+    unsubTrace();
     cleanupAbort();
   }
 

package/3p/pi-subagents/src/index.ts

@@ -397,6 +397,7 @@ Use get_subagent_result for full output.`,
       durationMs,
       modelId,
       tokens,
+      toolCallId: record.toolCallId,
     };
   }
 
@@ -960,6 +961,7 @@ Guidelines:
           thinkingLevel: thinking,
           isBackground: true,
           isolation,
+          toolCallId,
           ...bgCallbacks,
         });
 
@@ -1069,6 +1071,7 @@ Guidelines:
         inheritContext,
         thinkingLevel: thinking,
         isolation,
+        toolCallId,
         ...fgCallbacks,
       });
 

package/extensions/orchestrator/agents/brainstorm-reviewer.ts

@@ -1,38 +1,51 @@
-import type { PiPiConfig } from "../config.js";
-import { TOOL_ROUTING, ALL_CBM_TOOLS, EXA_TOOLS, WORKING_PRINCIPLES_READONLY, COMMUNICATION } from "./tool-routing.js";
+import type { VariantConfig } from "../config.js";
+import { loadAllContextFiles } from "../context.js";
+import { resolveModel, getModelInfo } from "../model-registry.js";
+import type { RepoInfo } from "../repo-utils.js";
+import { buildRepoContext } from "./repo-context.js";
+import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-routing.js";
 
 export function createBrainstormReviewerAgent(
   variant: string,
-  config: PiPiConfig,
+  variants: Record<string, VariantConfig>,
   taskArtifacts: { userRequest: string; research: string; artifacts?: { name: string; content: string }[] },
   outputPath: string,
+  contextDirs: string[],
+  phase?: string,
+  repos: RepoInfo[] = [],
 ) {
-  const variantConfig = config.brainstormReviewers[variant];
+  const variantConfig = variants[variant];
   if (!variantConfig) {
     throw new Error(`Unknown brainstorm-reviewer variant: ${variant}`);
   }
+  const contextFiles = loadAllContextFiles(contextDirs, "brainstormReviewer", "system", phase, getModelInfo(variantConfig.model));
+  const contextBlock = contextFiles.map((f) => f.content).join("\n\n");
+  const repoContext = buildRepoContext(repos);
 
   return {
     frontmatter: {
       description: `Brainstorm reviewer (${variant} variant, pi-pi)`,
       tools: `read, grep, find, bash, write, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
-      model: variantConfig.model,
+      model: resolveModel(variantConfig.model),
       thinking: variantConfig.thinking,
-      max_turns: variantConfig.maxTurns ?? 120,
+      max_turns: 120,
       prompt_mode: "replace",
     },
     prompt: [
-      "You are a research reviewer. Your job is to verify the thoroughness and accuracy of brainstorm research artifacts.",
+      // --- static prefix (cacheable) ---
+      "<constraints>",
+      "You are a research reviewer. You verify the thoroughness and accuracy of brainstorm research artifacts. You are a GAP-FINDER, not a perfectionist — approve by default, reject only for critical gaps (maximum 3).",
+      "These rules override your default helpfulness. Strict compliance is required.",
+      "You are READ-ONLY: you MUST NOT implement or modify any file except the single review .md file named below. You MUST write it before finishing.",
+      "Your review MUST begin with the verdict on the VERY FIRST LINE: `VERDICT: APPROVE` or `VERDICT: NEEDS_WORK`.",
+      "</constraints>",
       "",
-      "You are a GAP-FINDER, not a perfectionist.",
-      "Approve by default. Reject only for critical gaps — maximum 3.",
+      PRINCIPLES_BLOCK,
       "",
-      WORKING_PRINCIPLES_READONLY,
-      "",
-      COMMUNICATION,
-      "",
-      TOOL_ROUTING,
+      TOOLS_BLOCK,
       "",
+      ...(contextBlock ? ["<project_context>", contextBlock, "</project_context>", ""] : []),
+      "<task>",
       "# Your job:",
       "1. Read USER_REQUEST.md and RESEARCH.md provided below",
       "2. INDEPENDENTLY investigate the codebase to verify claims and find gaps",
@@ -45,23 +58,22 @@ export function createBrainstormReviewerAgent(
       "- Separation: does USER_REQUEST.md contain only user-stated info (no agent findings leaked in)?",
       "- Structure: do both files follow the required format?",
       "",
-      "# Format your review as:",
+      "# Format your review with the verdict on the VERY FIRST LINE, then findings:",
+      "VERDICT: APPROVE | NEEDS_WORK",
       "- GAPS: (missing information that would block planning)",
       "- INACCURACIES: (claims that don't match the code)",
       "- SUGGESTIONS: (improvements, not required)",
-      "- VERDICT: APPROVE or NEEDS_WORK (with reason)",
       "",
       "subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
     '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
     '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
     "Spawn multiple Explore agents in parallel for broad searches.",
+      "</task>",
       "",
       "# MANDATORY: Write your review to this exact file using the write tool:",
       `  ${outputPath}`,
       "",
-      "Your task is NOT complete until this file exists. Do NOT finish without writing it.",
-      "You MUST NOT write to any other file. Only write .md files inside .pp/state/.",
-      "Do NOT implement, fix, or modify any source code — you are a reviewer, not an implementer.",
+      "You MUST write only to the review file above. Do NOT write to any other file.",
       "",
       "=== USER REQUEST ===",
       taskArtifacts.userRequest,
@@ -74,6 +86,7 @@ export function createBrainstormReviewerAgent(
             ...taskArtifacts.artifacts.flatMap((a) => [`=== ${a.name} ===`, a.content, ""]),
           ]
         : []),
+      ...(repoContext ? [repoContext] : []),
       "",
       "The artifacts above are already in your context. Do NOT re-read them from disk.",
     ].join("\n"),