fix: preserve Pi dreamer system prompts on retry

Co-Authored-By: Alfonso <alfonso@cortexkit.io>

Author: ualtinok

packages/pi-plugin/src/dreamer/index.test.ts

@@ -382,6 +382,42 @@ describe("Pi dreamer wiring", () => {
 		expect(onAdjunctsRefreshNeeded).not.toHaveBeenCalled();
 	});
 
+	test("preserves transient status when a child rejects before producing output", async () => {
+		db = createDb();
+		let capturedClient: CapturedDreamClient | null = null;
+		__test.setStartDreamScheduleTimerFactory(async (registration) => {
+			capturedClient = registration.client as unknown as CapturedDreamClient;
+			return mock(() => {});
+		});
+		__test.setPiSubagentRunnerFactory(
+			() =>
+				({
+					run: mock(async () => ({
+						ok: false,
+						reason: "invalid_prompt",
+						transient: true,
+						error: "zero-tool prompt missing",
+						durationMs: 0,
+					})),
+				}) as never,
+		);
+
+		registerPiDreamerProject(
+			dreamerOptions({
+				database: db,
+				projectIdentity: "git:pi-transient-child",
+			}),
+		);
+		const client = requireCapturedClient(capturedClient);
+		const created = (await client.session.create({})) as { id: string };
+		await expect(
+			client.session.prompt({
+				path: { id: created.id },
+				body: { system: "system", parts: [{ text: "run dreamer" }] },
+			}),
+		).rejects.toMatchObject({ transient: true });
+	});
+
 	test("unregister before timer promise resolves invokes timer cleanup when it eventually resolves", async () => {
 		db = createDb();
 		const timerCleanup = mock(() => {});

packages/pi-plugin/src/dreamer/index.ts

@@ -308,9 +308,13 @@ function createPiDreamerClient(opts: PiDreamerOptions): DreamTimerClient {
 			try {
 				const result = await runPromise;
 				if (!result.ok) {
-					throw new Error(
+					const error = new Error(
 						`Pi dreamer subagent failed (${result.reason}): ${result.error}`,
 					);
+					if (result.transient) {
+						(error as Error & { transient?: boolean }).transient = true;
+					}
+					throw error;
 				}
 				dreamSession.messages = [
 					makeMessage("user", [{ type: "text", text: userMessage }]),

packages/pi-plugin/src/subagent-runner.test.ts

@@ -618,6 +618,34 @@ describe("subagent-runner pure helpers", () => {
 });
 
 describe("PiSubagentRunner spawn lifecycle", () => {
+	it("refuses to spawn known zero-tool agents without a system prompt", async () => {
+		const spawnImpl = mock(() => {
+			throw new Error("spawn must not be reached");
+		});
+		// Replace the runner's test seam with a throwing spawn so this assertion
+		// proves the guard runs before any child process is created.
+		const guardedRunner = new PiSubagentRunner({
+			piBinary: "pi-test",
+			spawnImpl: spawnImpl as never,
+		});
+
+		for (const agent of ["dreamer-classifier", "dreamer-reviewer"]) {
+			const result = await guardedRunner.run({
+				...baseOptions,
+				agent,
+				systemPrompt: "  \n\t",
+			});
+			expect(result).toEqual({
+				ok: false,
+				reason: "invalid_prompt",
+				transient: true,
+				error: `zero-tool Pi subagent "${agent}" requires a non-empty system prompt`,
+				durationMs: expect.any(Number),
+			});
+		}
+		expect(spawnImpl).not.toHaveBeenCalled();
+	});
+
 	it("treats a terminal stop turn as success even when drain SIGTERM closes the child", async () => {
 		const child = createMockChild();
 		const { runner } = runnerWith(child);

packages/pi-plugin/src/subagent-runner.ts

@@ -276,6 +276,12 @@ const STRICT_TOOL_ALLOWLIST: ReadonlyMap<string, readonly string[]> = new Map(
 	STRICT_TOOL_ALLOWLIST_ENTRIES,
 );
 
+const ZERO_TOOL_PROMPT_REQUIRED_AGENTS: ReadonlySet<string> = new Set(
+	STRICT_TOOL_ALLOWLIST_ENTRIES.filter(([, tools]) => tools.length === 0).map(
+		([agent]) => agent,
+	),
+);
+
 const KNOWN_PI_SUBAGENT_AGENTS = [
 	"magic-context-historian",
 	"historian",
@@ -539,15 +545,18 @@ export class PiSubagentRunner implements SubagentRunner {
 			}
 			return result;
 		}
+
 		const failBeforeSpawn = (
 			reason: Extract<SubagentRunResult, { ok: false }>["reason"],
 			error: string,
+			transient = false,
 		): SubagentRunResult => {
 			const result: SubagentRunResult = {
 				ok: false,
 				reason,
 				error,
 				durationMs: Date.now() - startTime,
+				...(transient ? { transient: true } : {}),
 			};
 			try {
 				recordAccounting(result);
@@ -560,6 +569,20 @@ export class PiSubagentRunner implements SubagentRunner {
 			return result;
 		};
 
+		// A zero-tool child cannot receive its task instructions unless a system
+		// prompt is provided. Refuse before spawning so Pi cannot substitute a
+		// persisted user-mode prompt.
+		if (
+			ZERO_TOOL_PROMPT_REQUIRED_AGENTS.has(options.agent) &&
+			options.systemPrompt.trim().length === 0
+		) {
+			return failBeforeSpawn(
+				"invalid_prompt",
+				`zero-tool Pi subagent "${options.agent}" requires a non-empty system prompt`,
+				true,
+			);
+		}
+
 		// Large prompts (e.g. a ~50K-token historian chunk ≈ 200 KB) overflow
 		// Linux's per-argv-entry limit (MAX_ARG_STRLEN, 128 KiB) and make spawn()
 		// fail with E2BIG. Windows is stricter: CreateProcess caps the ENTIRE
@@ -1486,4 +1509,5 @@ export const __test = {
 	DREAMER_ACTION_AGENTS,
 	KNOWN_PI_SUBAGENT_AGENTS,
 	STRICT_TOOL_ALLOWLIST,
+	ZERO_TOOL_PROMPT_REQUIRED_AGENTS,
 };

packages/plugin/src/shared/model-suggestion-retry.test.ts

@@ -6,7 +6,11 @@ import {
 } from "./model-suggestion-retry";
 
 type PromptCall = {
-    body: { model?: { providerID: string; modelID: string } };
+    body: {
+        model?: { providerID: string; modelID: string };
+        system?: string;
+        [key: string]: unknown;
+    };
     signal?: AbortSignal;
 };
 
@@ -338,6 +342,42 @@ describe("promptSyncWithValidatedOutputRetry", () => {
         expect(messages).toHaveBeenCalledTimes(1);
     });
 
+    test("preserves body.system when a failed Pi-shaped attempt mutates its body", async () => {
+        const prompt = mock(async (args: PromptCall) => {
+            if (prompt.mock.calls.length === 1) {
+                // Reproduce a facade/SDK that consumes the request body before
+                // rejecting the primary model. The fallback must not inherit
+                // that mutation and spawn without its task prompt.
+                delete args.body.system;
+                throw new Error("primary failed");
+            }
+            return {};
+        });
+        const client = createClient(prompt);
+        const systemPrompt = "CLASSIFY_SYSTEM_PROMPT";
+
+        await promptSyncWithValidatedOutputRetry(
+            client,
+            {
+                path: { id: "ses-classify" },
+                body: {
+                    agent: "dreamer-classifier",
+                    system: systemPrompt,
+                    parts: [{ type: "text", text: "classify" }],
+                },
+            },
+            {
+                fallbackModels: ["anthropic/claude-sonnet-4-6"],
+                fetchOutput: async () => "fallback-output",
+                validateOutput: (output: string) => output,
+            },
+        );
+
+        expect(prompt).toHaveBeenCalledTimes(2);
+        expect((prompt.mock.calls[0]?.[0] as PromptCall).body.system).toBeUndefined();
+        expect((prompt.mock.calls[1]?.[0] as PromptCall).body.system).toBe(systemPrompt);
+    });
+
     test("empty first model tries the next fallback", async () => {
         const prompt = mock(async () => ({}));
         const messages = mock(async () =>

packages/plugin/src/shared/model-suggestion-retry.ts

@@ -23,6 +23,15 @@ export type PromptArgs = {
     [key: string]: unknown;
 };
 
+/**
+ * Keep a prompt body independent from SDK/client mutation. Some prompt facades
+ * normalize or consume request bodies while handling a failed attempt; fallback
+ * attempts must start from the original system prompt and request body every time.
+ */
+function copyPromptArgs(args: PromptArgs, body: PromptBody): PromptArgs {
+    return { ...args, body: { ...body } };
+}
+
 export interface PromptAttemptInfo {
     /** Human-readable model label used in logs ("primary" or "provider/model"). */
     label: string;
@@ -280,16 +289,21 @@ async function attemptOnce(
     callContext: string,
     label: string,
 ): Promise<void> {
+    // Keep this snapshot separate from the object passed to the client. A
+    // failed prompt facade may rewrite its request body before rejecting; the
+    // model-suggestion retry still needs the original system prompt.
+    const originalBody = { ...args.body };
+    const attemptArgs = copyPromptArgs(args, originalBody);
     try {
-        await promptWithTimeout(client, args, timeoutMs, signal);
+        await promptWithTimeout(client, attemptArgs, timeoutMs, signal);
         return;
     } catch (error) {
         // If non-retryable (abort, overflow, timeout), bubble up immediately.
         // Don't even try suggestion retry — caller needs the original error.
         if (isNonRetryable(error, signal)) throw error;
 
         const suggestion = parseModelSuggestion(error);
-        if (!suggestion || !args.body.model) {
+        if (!suggestion || !originalBody.model) {
             // No suggestion available — caller's fallback loop will decide
             // whether to try the next chain entry.
             throw error;
@@ -302,16 +316,13 @@ async function attemptOnce(
 
         await promptWithTimeout(
             client,
-            {
-                ...args,
-                body: {
-                    ...args.body,
-                    model: {
-                        providerID: suggestion.providerID,
-                        modelID: suggestion.suggestion,
-                    },
+            copyPromptArgs(args, {
+                ...originalBody,
+                model: {
+                    providerID: suggestion.providerID,
+                    modelID: suggestion.suggestion,
                 },
-            },
+            }),
             timeoutMs,
             signal,
         );
@@ -340,20 +351,25 @@ export async function promptSyncWithModelSuggestionRetry(
     const timeoutMs = options.timeoutMs ?? 300_000;
     const callContext = options.callContext ?? "subagent";
     const fallbacks = options.fallbackModels ?? [];
+    // Snapshot the body before the first client call. The Pi facade and the
+    // OpenCode SDK both receive this same shape, and either may mutate it while
+    // handling a failed request. Fallbacks must never inherit that mutation.
+    const baseBody = { ...args.body };
+    const baseArgs = copyPromptArgs(args, baseBody);
 
     // Attempt 0 = whatever the agent or explicit body.model resolves to.
     // Subsequent attempts override body.model with each fallback in order.
     const explicitPrimaryLabel =
-        args.body.model?.providerID && args.body.model.modelID
-            ? `${args.body.model.providerID}/${args.body.model.modelID}`
+        baseBody.model?.providerID && baseBody.model.modelID
+            ? `${baseBody.model.providerID}/${baseBody.model.modelID}`
             : "primary";
 
     let lastError: unknown = null;
 
     try {
         await attemptOnce(
             client,
-            args,
+            baseArgs,
             timeoutMs,
             options.signal,
             callContext,
@@ -385,10 +401,10 @@ export async function promptSyncWithModelSuggestionRetry(
         }
 
         const label = `${parsed.providerID}/${parsed.modelID}`;
-        const attemptArgs: PromptArgs = {
-            ...args,
-            body: { ...args.body, model: parsed },
-        };
+        const attemptArgs = copyPromptArgs(baseArgs, {
+            ...baseBody,
+            model: parsed,
+        });
 
         try {
             await attemptOnce(client, attemptArgs, timeoutMs, options.signal, callContext, label);
@@ -453,10 +469,15 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
     const timeoutMs = options.timeoutMs ?? 300_000;
     const callContext = options.callContext ?? "subagent";
     const fallbacks = options.fallbackModels ?? [];
+    // Snapshot the body before the first client call. The Pi facade and the
+    // OpenCode SDK both receive this same shape, and either may mutate it while
+    // handling a failed request. Fallbacks must never inherit that mutation.
+    const baseBody = { ...args.body };
+    const baseArgs = copyPromptArgs(args, baseBody);
 
     const explicitPrimaryLabel =
-        args.body.model?.providerID && args.body.model.modelID
-            ? `${args.body.model.providerID}/${args.body.model.modelID}`
+        baseBody.model?.providerID && baseBody.model.modelID
+            ? `${baseBody.model.providerID}/${baseBody.model.modelID}`
             : "primary";
     const totalAttempts = fallbacks.length + 1;
 
@@ -466,7 +487,7 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
     try {
         return await attemptAndValidate(
             client,
-            args,
+            baseArgs,
             timeoutMs,
             options.signal,
             callContext,
@@ -475,7 +496,7 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
                 attemptIndex: 0,
                 isFallback: false,
                 totalAttempts,
-                model: args.body.model,
+                model: baseBody.model,
             },
             options,
         );
@@ -501,10 +522,10 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
         }
 
         const label = `${parsed.providerID}/${parsed.modelID}`;
-        const attemptArgs: PromptArgs = {
-            ...args,
-            body: { ...args.body, model: parsed },
-        };
+        const attemptArgs = copyPromptArgs(baseArgs, {
+            ...baseBody,
+            model: parsed,
+        });
         const attempt: PromptAttemptInfo = {
             label,
             attemptIndex: i + 1,

packages/plugin/src/shared/subagent-runner.ts

@@ -159,6 +159,7 @@ export type SubagentProgressEvent =
  *   reported as `ok: false, reason: "no_assistant"` so callers can try fallback
  *   models instead of accepting an unusable success.
  * - `reason`: failure category, one of:
+ *     - `"invalid_prompt"`: a known zero-tool child was given no system prompt
  *     - `"timeout"`: hit `timeoutMs` before the child finished
  *     - `"abort"`: caller's `signal` was triggered
  *     - `"model_failed"`: every configured model + fallback returned an error
@@ -194,6 +195,7 @@ export type SubagentRunResult =
     | {
           ok: false;
           reason:
+              | "invalid_prompt"
               | "timeout"
               | "abort"
               | "model_failed"
@@ -204,6 +206,8 @@ export type SubagentRunResult =
               | "parse_failed";
           error: string;
           durationMs: number;
+          /** True when the caller should retry the task rather than advance its schedule. */
+          transient?: boolean;
           meta?: Record<string, unknown>;
       };