pi-squad 0.7.2 → 0.15.0

package/src/index.ts

@@ -12,12 +12,15 @@
 
 import * as path from "node:path";
 import * as fs from "node:fs";
-import { Type } from "@sinclair/typebox";
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Squad, Task, SquadConfig, PlannerOutput } from "./types.js";
-import { DEFAULT_SQUAD_CONFIG } from "./types.js";
-import { Scheduler, type SchedulerEvent } from "./scheduler.js";
+import { DEFAULT_SQUAD_CONFIG, THINKING_LEVELS } from "./types.js";
+import { Scheduler, type SchedulerEvent, type SchedulerSpawnContext } from "./scheduler.js";
 import { runPlanner } from "./planner.js";
+import { validatePlan, PLAN_STRUCTURE_RULES } from "./plan-rules.js";
+import { ADVISOR_SYSTEM_PROMPT, buildAdvisorConsultText, type AdvisorConsultInput } from "./advisor.js";
+import { completeSimple, type Message, type TextContent } from "@earendil-works/pi-ai";
 import { SquadPanel, type SquadPanelResult } from "./panel/squad-panel.js";
 import { setupSquadWidget, type SquadWidgetState } from "./panel/squad-widget.js";
 import * as store from "./store.js";
@@ -36,11 +39,143 @@ let activeSquadId: string | null = null;
 /** Whether an overlay panel is currently open (prevents double-open) */
 let overlayOpen = false;
 /** Stored ExtensionContext for widget updates from background scheduler events */
-let uiCtx: import("@mariozechner/pi-coding-agent").ExtensionContext | null = null;
+let uiCtx: import("@earendil-works/pi-coding-agent").ExtensionContext | null = null;
 /** Component-based widget state + controls */
 const widgetState: SquadWidgetState = { squadId: null, enabled: true };
 let widgetControls: { requestUpdate: () => void; dispose: () => void } | null = null;
 
+/** Reviewer instructions appended to squad-completed notifications —
+ * makes the main session behave like the QA/verification agents do. */
+const REVIEW_INSTRUCTIONS =
+	"Before reporting success to the user, REVIEW the work like a QA agent would: " +
+	"(1) check task outputs for QA verdicts (## Verdict: PASS/FAIL) and verification evidence (commands + results); " +
+	"(2) if a task claimed done without evidence, run its Verify command yourself; " +
+	"(3) report to the user what was verified (with evidence) and flag anything unverified — don't just relay the summary.";
+
+/**
+ * Resolve a model string (or null = session default) to its context window.
+ * Reads uiCtx lazily so it always uses the live session's registry.
+ */
+function resolveContextWindow(model: string | null): number | undefined {
+	const ctx = uiCtx;
+	if (!ctx) return undefined;
+	try {
+		if (!model) return ctx.model?.contextWindow;
+		// Strip a :<thinking> suffix if present
+		let clean = model;
+		const lastColon = model.lastIndexOf(":");
+		if (lastColon > 0 && (THINKING_LEVELS as readonly string[]).includes(model.slice(lastColon + 1))) {
+			clean = model.slice(0, lastColon);
+		}
+		const all = ctx.modelRegistry.getAll();
+		const slash = clean.indexOf("/");
+		if (slash > 0) {
+			const provider = clean.slice(0, slash);
+			const id = clean.slice(slash + 1);
+			const m = all.find((x) => x.provider === provider && x.id === id);
+			if (m) return m.contextWindow;
+		}
+		return all.find((x) => x.id === clean)?.contextWindow;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Main session's current model as "provider/id", if known */
+function getMainSessionModel(): string | undefined {
+	try {
+		const m = uiCtx?.model;
+		return m ? `${m.provider}/${m.id}` : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Main session's current thinking level (set inside the extension entry, needs `pi`) */
+let getMainSessionThinking: () => string | undefined = () => undefined;
+
+/**
+ * Resolve the effective squad defaults from ~/.pi/squad/settings.json.
+ * "main" follows the live main session; "pi-default" leaves values unset
+ * (child pi resolves its own default); anything else is an explicit value.
+ */
+function resolveSquadDefaults(): { model?: string; thinking?: string } {
+	const settings = store.loadSquadSettings();
+	let model: string | undefined;
+	if (settings.defaultModel === "main") model = getMainSessionModel();
+	else if (settings.defaultModel !== "pi-default") model = settings.defaultModel;
+	let thinking: string | undefined;
+	if (settings.defaultThinking === "main") thinking = getMainSessionThinking();
+	else if (settings.defaultThinking !== "pi-default") thinking = settings.defaultThinking;
+	return { model, thinking };
+}
+
+/**
+ * Consult the advisor model in-process via pi-ai (no subprocess).
+ * Returns advice text or null when disabled/unresolvable.
+ */
+async function consultAdvisor(input: AdvisorConsultInput): Promise<string | null> {
+	const ctx = uiCtx;
+	if (!ctx) return null;
+	const settings = store.loadSquadSettings();
+	if (!settings.advisor.enabled) return null;
+
+	try {
+		// Resolve advisor model: "main" = the main session's live model object
+		let model = settings.advisor.model === "main" ? ctx.model : undefined;
+		if (!model && settings.advisor.model !== "main") {
+			const ref = settings.advisor.model;
+			const slash = ref.indexOf("/");
+			if (slash > 0) model = ctx.modelRegistry.find(ref.slice(0, slash), ref.slice(slash + 1));
+		}
+		if (!model) {
+			logError("squad-advisor", `advisor model "${settings.advisor.model}" not resolvable`);
+			return null;
+		}
+
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok || !auth.apiKey) {
+			logError("squad-advisor", `no auth for advisor model ${model.provider}/${model.id}`);
+			return null;
+		}
+
+		const userMessage: Message = {
+			role: "user",
+			content: [{ type: "text", text: buildAdvisorConsultText(input) }],
+			timestamp: Date.now(),
+		} as Message;
+
+		const response = await completeSimple(
+			model,
+			{ systemPrompt: ADVISOR_SYSTEM_PROMPT, messages: [userMessage] },
+			{
+				apiKey: auth.apiKey,
+				headers: auth.headers,
+				maxTokens: settings.advisor.maxTokens,
+				reasoning: settings.advisor.reasoning as never,
+			},
+		);
+
+		const text = response.content
+			.filter((b): b is TextContent => b.type === "text")
+			.map((b) => b.text)
+			.join("\n")
+			.trim();
+		debug("squad-advisor", `consulted ${model.provider}/${model.id} for ${input.taskId}: in=${response.usage?.input ?? 0} out=${response.usage?.output ?? 0}`);
+		return text || null;
+	} catch (error) {
+		logError("squad-advisor", `consult failed: ${(error as Error).message}`);
+		return null;
+	}
+}
+
+/** Spawn context shared by all Scheduler instances */
+const schedulerSpawnContext: SchedulerSpawnContext = {
+	resolveContextWindow,
+	getDefaultModelThinking: resolveSquadDefaults,
+	consultAdvisor,
+};
+
 /** Get the active scheduler (for the focused squad) */
 function getActiveScheduler(): Scheduler | null {
 	if (!activeSquadId) return null;
@@ -56,6 +191,15 @@ export default function (pi: ExtensionAPI) {
 	// Don't load in child agent processes (prevent recursive squad-in-squad)
 	if (process.env.PI_SQUAD_CHILD === "1") return;
 
+	// Wire main-session thinking lookup (needs `pi`, guarded against stale API)
+	getMainSessionThinking = () => {
+		try {
+			return pi.getThinkingLevel();
+		} catch {
+			return undefined;
+		}
+	};
+
 	// Bootstrap default agents on first load
 	const defaultsDir = path.join(path.dirname(new URL(import.meta.url).pathname), "agents", "_defaults");
 	store.bootstrapAgents(defaultsDir);
@@ -97,6 +241,7 @@ export default function (pi: ExtensionAPI) {
 				taskLines,
 				`</squad_status>`,
 				`You have an active squad. Use squad_message to talk to agents, squad_status for details, squad_modify to change tasks.`,
+				`Do NOT poll squad_status in a loop or sleep-wait — the squad wakes you automatically on completion, failure, or escalation. Keep helping the user with other work, or end your turn and stay idle.`,
 			].join("\n");
 
 			return {
@@ -115,6 +260,8 @@ export default function (pi: ExtensionAPI) {
 			`The squad tool decomposes work into tasks, assigns specialist agents, and runs them in parallel.`,
 			`When in doubt about whether a task is complex enough, prefer using squad — it handles the coordination for you.`,
 			allAgents.length > 0 ? `Available agents: ${agentList}. When providing tasks, the "agent" field must be one of these names.` : ``,
+			`When you provide tasks yourself, you take the planner's role — follow its rules: contract/design task first for shared interfaces, final QA task for user-facing changes, 3-7 tasks, first task(s) with empty depends.`,
+			`Structure descriptions as: Goal (outcome first), Context (files to read), Output (deliverable), Boundaries (what must not change), Verify (proving command).`,
 			`</squad_hint>`,
 		].filter(Boolean).join("\n");
 
@@ -139,16 +286,29 @@ export default function (pi: ExtensionAPI) {
 			"Do NOT use for simple single-file changes, quick bug fixes, or tasks a single agent can handle in a few minutes.",
 			"When in doubt about complexity, use squad — it's better to parallelize than to do everything sequentially.",
 			"Non-blocking: returns immediately with the plan while agents work in background.",
+			"If you provide tasks yourself (skipping the planner agent), follow the same rules the planner follows:",
+			PLAN_STRUCTURE_RULES.replace(/\n- /g, " ").replace(/^- /, ""),
+			"Plans are validated on submission — structural errors are rejected, rule violations come back as warnings.",
 		].join(" "),
+		promptSnippet: "squad({ goal, tasks?, agents? }): decompose complex work into parallel specialist agents → non-blocking, monitor via squad_status",
+		promptGuidelines: [
+			"Use squad when work spans 2+ concerns (backend+frontend+tests+docs) or has natural parallelism",
+			"Skip squad for single-file changes, quick fixes, or anything one agent finishes in minutes",
+			"Providing tasks yourself makes you the planner — follow the planner rules (contract task first, final QA task, 3-7 tasks)",
+			"Act on ⚠️ plan warnings in the response — fix with squad_modify or address at review",
+			"After starting a squad: report the plan and END YOUR TURN — never poll squad_status or sleep-wait; squad events wake you automatically",
+			"When the squad completes, review evidence like a QA agent before reporting success",
+		],
 		parameters: Type.Object({
 			goal: Type.String({ description: "What the squad should accomplish" }),
 			agents: Type.Optional(
 				Type.Record(
 					Type.String(),
 					Type.Object({
-						model: Type.Optional(Type.String()),
+						model: Type.Optional(Type.String({ description: "Model override (e.g. 'github-copilot/claude-sonnet-5')" })),
+						thinking: Type.Optional(Type.String({ description: "Thinking level: off, minimal, low, medium, high, xhigh, max" })),
 					}),
-					{ description: "Agent roster with optional model overrides. Keys must match agent names in .pi/squad/agents/" },
+					{ description: "Agent roster with optional model/thinking overrides. Keys must match agent names in .pi/squad/agents/" },
 				),
 			),
 			tasks: Type.Optional(
@@ -156,11 +316,12 @@ export default function (pi: ExtensionAPI) {
 					Type.Object({
 						id: Type.String(),
 						title: Type.String(),
-						description: Type.Optional(Type.String()),
+						description: Type.Optional(Type.String({ description: "Structure as: Goal (outcome first, not steps), Context (files/contracts to read), Output (deliverable), Boundaries (what must NOT change), Verify (command that proves it works). Include only the parts that help." })),
 						agent: Type.String(),
 						depends: Type.Optional(Type.Array(Type.String())),
+						inheritContext: Type.Optional(Type.Boolean({ description: "Fork the current pi session so the agent inherits this conversation's full context. Use ONLY when the task depends on decisions/details discussed here that can't be restated briefly. Costly (agent pays the whole history as input each turn) and auto-skipped when the session exceeds 50% of the agent model's context window — prefer restating key context in the description." })),
 					}),
-					{ description: "Pre-defined task breakdown. If provided, skips the planner agent." },
+					{ description: "Pre-defined task breakdown. If provided, skips the planner agent. Scope tasks to required work only — no optional polish." },
 				),
 			),
 			config: Type.Optional(
@@ -171,21 +332,25 @@ export default function (pi: ExtensionAPI) {
 		}),
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			if (!squadEnabled) return { content: [{ type: "text" as const, text: "Squad is disabled. Use /squad enable to re-enable." }] };
+			if (!squadEnabled) return { content: [{ type: "text" as const, text: "Squad is disabled. Use /squad enable to re-enable." }], details: undefined };
 			if (!uiCtx) uiCtx = ctx;
 
 			// Check if the user cancelled before we start
-			if (signal?.aborted) return { content: [{ type: "text" as const, text: "Cancelled." }] };
+			if (signal?.aborted) return { content: [{ type: "text" as const, text: "Cancelled." }], details: undefined };
 
 			// Multiple squads can run concurrently — no guard needed
 
+			// Resolve to absolute: the fork happens later from a child process whose
+			// cwd may differ (e.g. when a relative --session-dir was used).
+			const rawSessionFile = ctx.sessionManager.getSessionFile();
+			const sessionFile = rawSessionFile ? path.resolve(rawSessionFile) : null;
 			const squadId = store.makeTaskId(params.goal);
 			if (store.squadExists(squadId)) {
 				const uniqueId = `${squadId}-${Date.now().toString(36)}`;
-				return await startSquad(uniqueId, params, ctx.cwd, squadSkillPaths, pi);
+				return await startSquad(uniqueId, params, ctx.cwd, squadSkillPaths, pi, sessionFile);
 			}
 
-			return await startSquad(squadId, params, ctx.cwd, squadSkillPaths, pi);
+			return await startSquad(squadId, params, ctx.cwd, squadSkillPaths, pi, sessionFile);
 		},
 	});
 
@@ -196,7 +361,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "squad_status",
 		label: "Squad Status",
-		description: "Check current squad status, task progress, and recent activity.",
+		description: "Check current squad status, task progress, and recent activity. Do NOT call this in a loop or after sleep-waits — squad completion/failure/escalations wake you automatically. Use only when the user asks for a status update or after being woken by a squad event.",
 		parameters: Type.Object({
 			squadId: Type.Optional(Type.String({ description: "Specific squad ID (default: most recent)" })),
 		}),
@@ -211,7 +376,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (!id) {
-				return { content: [{ type: "text" as const, text: "No squads found. Use the squad tool to start one." }] };
+				return { content: [{ type: "text" as const, text: "No squads found. Use the squad tool to start one." }], details: undefined };
 			}
 
 			// If scheduler is running, force a context refresh
@@ -220,7 +385,7 @@ export default function (pi: ExtensionAPI) {
 
 			const context = store.loadContext(id);
 			if (!context) {
-				return { content: [{ type: "text" as const, text: `Squad '${id}' not found or has no context yet.` }] };
+				return { content: [{ type: "text" as const, text: `Squad '${id}' not found or has no context yet.` }], details: undefined };
 			}
 
 			const taskLines = Object.entries(context.tasks)
@@ -247,7 +412,7 @@ export default function (pi: ExtensionAPI) {
 				taskLines,
 			].join("\n");
 
-			return { content: [{ type: "text" as const, text: summary }] };
+			return { content: [{ type: "text" as const, text: summary }], details: undefined };
 		},
 	});
 
@@ -268,7 +433,7 @@ export default function (pi: ExtensionAPI) {
 		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
 			const activeScheduler = getActiveScheduler();
 			if (!activeScheduler || !activeSquadId) {
-				return { content: [{ type: "text" as const, text: "No active squad." }] };
+				return { content: [{ type: "text" as const, text: "No active squad." }], details: undefined };
 			}
 
 			let taskId = params.taskId;
@@ -279,13 +444,13 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (!taskId) {
-				return { content: [{ type: "text" as const, text: "Could not determine target task. Provide taskId or an agent name that is currently running." }] };
+				return { content: [{ type: "text" as const, text: "Could not determine target task. Provide taskId or an agent name that is currently running." }], details: undefined };
 			}
 
 			const sent = await activeScheduler!.sendHumanMessage(taskId, params.message);
 			const status = sent ? "delivered" : "queued for when the agent starts";
 
-			return { content: [{ type: "text" as const, text: `Message ${status}: "${params.message}"` }] };
+			return { content: [{ type: "text" as const, text: `Message ${status}: "${params.message}"` }], details: undefined };
 		},
 	});
 
@@ -296,7 +461,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "squad_modify",
 		label: "Squad Modify",
-		description: "Modify the running squad: add_task, cancel_task, pause, resume, cancel (entire squad).",
+		description: "Modify the running squad: add_task, cancel_task, complete_task (mark done + schedule dependents), pause, resume (also recovers failed squads), cancel (entire squad).",
 		parameters: Type.Object({
 			action: Type.Union(
 				[
@@ -304,6 +469,7 @@ export default function (pi: ExtensionAPI) {
 					Type.Literal("cancel_task"),
 					Type.Literal("pause_task"),
 					Type.Literal("resume_task"),
+					Type.Literal("complete_task"),
 					Type.Literal("pause"),
 					Type.Literal("resume"),
 					Type.Literal("cancel"),
@@ -311,6 +477,7 @@ export default function (pi: ExtensionAPI) {
 				{ description: "Action to perform" },
 			),
 			taskId: Type.Optional(Type.String({ description: "Task ID for task-specific actions" })),
+			output: Type.Optional(Type.String({ description: "Result summary for complete_task (what was accomplished)" })),
 			task: Type.Optional(
 				Type.Object({
 					id: Type.String(),
@@ -318,8 +485,8 @@ export default function (pi: ExtensionAPI) {
 					description: Type.Optional(Type.String()),
 					agent: Type.String(),
 					depends: Type.Optional(Type.Array(Type.String())),
-				}),
-				{ description: "Task definition for add_task" },
+					inheritContext: Type.Optional(Type.Boolean({ description: "Fork the current pi session so the agent inherits this conversation's context (see squad tool docs for caveats)" })),
+				}, { description: "Task definition for add_task" }),
 			),
 		}),
 
@@ -328,16 +495,16 @@ export default function (pi: ExtensionAPI) {
 			if (params.action === "resume") {
 				// Find a squad to resume: use activeSquadId or find the latest paused one
 				const squadId = activeSquadId || store.findActiveSquads()
-					.filter((s) => s.cwd === ctx.cwd && s.status === "paused")
+					.filter((s) => s.cwd === ctx.cwd && (s.status === "paused" || s.status === "failed"))
 					.sort((a, b) => b.created.localeCompare(a.created))[0]?.id;
 
 				if (!squadId) {
-					return { content: [{ type: "text" as const, text: "No paused squad found to resume." }] };
+					return { content: [{ type: "text" as const, text: "No paused or failed squad found to resume." }], details: undefined };
 				}
 
 				// Create a fresh scheduler if needed
 				if (!schedulers.has(squadId)) {
-					const scheduler = new Scheduler(squadId, squadSkillPaths);
+					const scheduler = new Scheduler(squadId, squadSkillPaths, schedulerSpawnContext);
 					schedulers.set(squadId, scheduler);
 					activeSquadId = squadId;
 
@@ -358,11 +525,13 @@ export default function (pi: ExtensionAPI) {
 									.join("\n");
 								const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
 								const s = schedulers.get(squadId); if (s) s.updateContext();
+								// followUp + triggerTurn: wake an idle main agent to review;
+								// if it's mid-conversation with the human, deliver after it finishes
 								pi.sendMessage({
 									customType: "squad-completed",
-									content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\nSummary:\n${summary}\n\nTotal cost: $${totalCost.toFixed(4)}`,
+									content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\nSummary:\n${summary}\n\nTotal cost: $${totalCost.toFixed(4)}\n\n${REVIEW_INSTRUCTIONS}`,
 									display: true,
-								});
+								}, { triggerTurn: true, deliverAs: "followUp" });
 								schedulers.delete(squadId);
 								forceWidgetUpdate();
 								break;
@@ -375,7 +544,7 @@ export default function (pi: ExtensionAPI) {
 									customType: "squad-failed",
 									content: `[squad] Squad "${squadId}" has stalled. ${done.length}/${tasks.length} done, ${failed.length} failed.\nFailed: ${failed.map((t) => `${t.id}: ${t.error?.slice(0, 100)}`).join("; ")}`,
 									display: true,
-								}, { triggerTurn: true });
+								}, { triggerTurn: true, deliverAs: "followUp" });
 								forceWidgetUpdate();
 								break;
 							}
@@ -398,17 +567,32 @@ export default function (pi: ExtensionAPI) {
 
 				const tasks = store.loadAllTasks(squadId);
 				const done = tasks.filter(t => t.status === "done").length;
-				return { content: [{ type: "text" as const, text: `Squad "${squadId}" resumed (${done}/${tasks.length} done). Agents restarting in background.` }] };
+				return { content: [{ type: "text" as const, text: `Squad "${squadId}" resumed (${done}/${tasks.length} done). Agents restarting in background.` }], details: undefined };
 			}
 
+			const activeScheduler = getActiveScheduler();
 			if (!activeScheduler || !activeSquadId) {
-				return { content: [{ type: "text" as const, text: "No active squad. Use squad_modify with action 'resume' to resume a paused squad, or start a new one with the squad tool." }] };
+				return { content: [{ type: "text" as const, text: "No active squad. Use squad_modify with action 'resume' to resume a paused squad, or start a new one with the squad tool." }], details: undefined };
 			}
 
 			switch (params.action) {
 				case "add_task": {
 					if (!params.task) {
-						return { content: [{ type: "text" as const, text: "Provide a task definition for add_task." }] };
+						return { content: [{ type: "text" as const, text: "Provide a task definition for add_task." }], details: undefined };
+					}
+					// Validate against the live squad: deps must exist, agent must exist
+					const existing = store.loadAllTasks(activeSquadId);
+					const existingIds = new Set(existing.map((t) => t.id));
+					if (existingIds.has(params.task.id)) {
+						return { content: [{ type: "text" as const, text: `Task id '${params.task.id}' already exists in this squad.` }], details: undefined };
+					}
+					const badDeps = (params.task.depends || []).filter((d) => !existingIds.has(d));
+					if (badDeps.length > 0) {
+						return { content: [{ type: "text" as const, text: `Unknown dependency task(s): ${badDeps.join(", ")}. Existing tasks: ${[...existingIds].join(", ")}` }], details: undefined };
+					}
+					if (!store.loadAgentDef(params.task.agent, ctx.cwd)) {
+						const available = store.loadAllAgentDefs(ctx.cwd).filter((a) => !a.disabled).map((a) => a.name).join(", ");
+						return { content: [{ type: "text" as const, text: `Unknown agent '${params.task.agent}'. Available: ${available}` }], details: undefined };
 					}
 					const task: Task = {
 						id: params.task.id,
@@ -417,6 +601,7 @@ export default function (pi: ExtensionAPI) {
 						agent: params.task.agent,
 						status: "pending",
 						depends: params.task.depends || [],
+						...(params.task.inheritContext ? { inheritContext: true } : {}),
 						created: store.now(),
 						started: null,
 						completed: null,
@@ -426,27 +611,37 @@ export default function (pi: ExtensionAPI) {
 					};
 					store.createTask(activeSquadId, task);
 					activeScheduler.updateContext();
-					return { content: [{ type: "text" as const, text: `Task '${task.id}' added.` }] };
+					return { content: [{ type: "text" as const, text: `Task '${task.id}' added.` }], details: undefined };
 				}
 
 				case "cancel_task": {
-					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }] };
+					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }], details: undefined };
 					await activeScheduler.cancelTask(params.taskId);
-					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' cancelled.` }] };
+					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' cancelled.` }], details: undefined };
 				}
 
 				case "pause_task": {
-					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }] };
+					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }], details: undefined };
 					await activeScheduler.pauseTask(params.taskId);
-					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' paused.` }] };
+					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' paused.` }], details: undefined };
 				}
 
 				case "resume_task": {
-					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }] };
+					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }], details: undefined };
 					activeScheduler.resumeTask(params.taskId).catch((err) => {
 						logError("squad", `Resume task error: ${(err as Error).message}`);
 					});
-					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' resumed.` }] };
+					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' resumed.` }], details: undefined };
+				}
+
+				case "complete_task": {
+					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }], details: undefined };
+					try {
+						await activeScheduler.completeTask(params.taskId, params.output);
+					} catch (err) {
+						return { content: [{ type: "text" as const, text: `complete_task failed: ${(err as Error).message}` }], details: undefined };
+					}
+					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' marked done — dependents unblocked and scheduled.` }], details: undefined };
 				}
 
 				case "pause": {
@@ -456,13 +651,10 @@ export default function (pi: ExtensionAPI) {
 						store.saveSquad(squad);
 					}
 					await activeScheduler.stop();
-					return { content: [{ type: "text" as const, text: "Squad paused. Use squad_modify with action 'resume' to continue." }] };
+					return { content: [{ type: "text" as const, text: "Squad paused. Use squad_modify with action 'resume' to continue." }], details: undefined };
 				}
 
-				case "resume": {
-					// Handled above (before the activeScheduler guard)
-					return { content: [{ type: "text" as const, text: "Squad resumed." }] };
-				}
+				// Note: "resume" is handled above, before the activeScheduler guard.
 
 				case "cancel": {
 					await activeScheduler.stop();
@@ -473,11 +665,11 @@ export default function (pi: ExtensionAPI) {
 					}
 					schedulers.delete(activeSquadId);
 					activeSquadId = null;
-					return { content: [{ type: "text" as const, text: "Squad cancelled." }] };
+					return { content: [{ type: "text" as const, text: "Squad cancelled." }], details: undefined };
 				}
 
 				default:
-					return { content: [{ type: "text" as const, text: `Unknown action: ${params.action}` }] };
+					return { content: [{ type: "text" as const, text: `Unknown action: ${params.action}` }], details: undefined };
 			}
 		},
 	});
@@ -553,7 +745,7 @@ export default function (pi: ExtensionAPI) {
 					}
 
 					if (activeSquadId) {
-						openPanel(ctx, schedulers.get(activeSquadId) || new Scheduler(activeSquadId, squadSkillPaths), activeSquadId);
+						openPanel(ctx, schedulers.get(activeSquadId) || new Scheduler(activeSquadId, squadSkillPaths, schedulerSpawnContext), activeSquadId);
 					}
 					return { consume: true };
 				}
@@ -585,6 +777,8 @@ export default function (pi: ExtensionAPI) {
 				{ value: "all", label: "all", description: "List all squads, select to activate" },
 				{ value: "select", label: "select", description: "Pick a squad to view (interactive)" },
 				{ value: "agents", label: "agents", description: "List, view, or edit agent definitions" },
+				{ value: "defaults", label: "defaults", description: "Default model/thinking for agents (follow main session, pi default, or fixed)" },
+				{ value: "advisor", label: "advisor", description: "Advisor-first rescue for stuck agents (on/off, model, limits)" },
 				{ value: "msg", label: "msg", description: "Send message to agent: /squad msg [agent] text" },
 				{ value: "widget", label: "widget", description: "Toggle live widget" },
 				{ value: "panel", label: "panel", description: "Toggle overlay panel" },
@@ -677,7 +871,7 @@ export default function (pi: ExtensionAPI) {
 						}
 					}
 					if (activeSquadId) {
-						const sched = schedulers.get(activeSquadId) || new Scheduler(activeSquadId, squadSkillPaths);
+						const sched = schedulers.get(activeSquadId) || new Scheduler(activeSquadId, squadSkillPaths, schedulerSpawnContext);
 						openPanel(ctx, sched, activeSquadId);
 					}
 					return;
@@ -884,6 +1078,92 @@ export default function (pi: ExtensionAPI) {
 					return;
 				}
 
+				case "defaults": {
+					const settings = store.loadSquadSettings();
+					const mainModel = getMainSessionModel() || "(unknown)";
+					const mainThinking = getMainSessionThinking() || "(unknown)";
+					const fmtPolicy = (v: string, live: string) =>
+						v === "main" ? `follow main session (now: ${live})` : v === "pi-default" ? "pi default" : v;
+
+					const which = await ctx.ui.select(
+						`Squad defaults — model: ${fmtPolicy(settings.defaultModel, mainModel)} | thinking: ${fmtPolicy(settings.defaultThinking, mainThinking)}`,
+						["Change default model", "Change default thinking", "Cancel"],
+					);
+					if (!which || which === "Cancel") return;
+
+					if (which === "Change default model") {
+						const choice = await ctx.ui.select("Default model for squad agents", [
+							`Follow main session (now: ${mainModel})`,
+							"pi default (child pi resolves its own)",
+							"Custom model…",
+						]);
+						if (!choice) return;
+						if (choice.startsWith("Follow")) settings.defaultModel = "main";
+						else if (choice.startsWith("pi default")) settings.defaultModel = "pi-default";
+						else {
+							const custom = await ctx.ui.input("Model id (e.g. openai-codex/gpt-5.6-terra)", settings.defaultModel === "main" || settings.defaultModel === "pi-default" ? "" : settings.defaultModel);
+							if (!custom || !custom.trim()) return;
+							settings.defaultModel = custom.trim();
+						}
+						store.saveSquadSettings(settings);
+						ctx.ui.notify(`Squad default model → ${fmtPolicy(settings.defaultModel, mainModel)}`, "info");
+					} else {
+						const choice = await ctx.ui.select("Default thinking for squad agents", [
+							`Follow main session (now: ${mainThinking})`,
+							"pi default (child pi resolves its own)",
+							...THINKING_LEVELS,
+						]);
+						if (!choice) return;
+						if (choice.startsWith("Follow")) settings.defaultThinking = "main";
+						else if (choice.startsWith("pi default")) settings.defaultThinking = "pi-default";
+						else settings.defaultThinking = choice;
+						store.saveSquadSettings(settings);
+						ctx.ui.notify(`Squad default thinking → ${fmtPolicy(settings.defaultThinking, mainThinking)}`, "info");
+					}
+					return;
+				}
+
+				case "advisor": {
+					const settings = store.loadSquadSettings();
+					const adv = settings.advisor;
+					const mainModelLabel = getMainSessionModel() || "(unknown)";
+					const modelLabel = adv.model === "main" ? `main session (now: ${mainModelLabel})` : adv.model;
+
+					const choice = await ctx.ui.select(
+						`Squad advisor — ${adv.enabled ? "ON" : "OFF"} | model: ${modelLabel} | ${adv.maxCallsPerTask} calls/task, ${adv.reasoning} reasoning`,
+						[adv.enabled ? "Disable advisor" : "Enable advisor", "Change advisor model", "Change max calls per task", "Change reasoning effort", "Cancel"],
+					);
+					if (!choice || choice === "Cancel") return;
+
+					if (choice.startsWith("Disable") || choice.startsWith("Enable")) {
+						adv.enabled = !adv.enabled;
+						ctx.ui.notify(`Squad advisor ${adv.enabled ? "enabled — stuck agents get a strong-model rescue before escalating" : "disabled — stuck agents escalate directly"}`, "info");
+					} else if (choice === "Change advisor model") {
+						const sel = await ctx.ui.select("Advisor model", [`Follow main session (now: ${mainModelLabel})`, "Custom model…"]);
+						if (!sel) return;
+						if (sel.startsWith("Follow")) adv.model = "main";
+						else {
+							const custom = await ctx.ui.input("Advisor model (provider/id)", adv.model === "main" ? "" : adv.model);
+							if (!custom || !custom.trim()) return;
+							adv.model = custom.trim();
+						}
+						ctx.ui.notify(`Advisor model → ${adv.model}`, "info");
+					} else if (choice === "Change max calls per task") {
+						const n = await ctx.ui.input("Max advisor calls per task", String(adv.maxCallsPerTask));
+						const parsed = n ? Number.parseInt(n, 10) : NaN;
+						if (!Number.isFinite(parsed) || parsed < 0) return;
+						adv.maxCallsPerTask = parsed;
+						ctx.ui.notify(`Advisor max calls/task → ${parsed}`, "info");
+					} else {
+						const lvl = await ctx.ui.select("Advisor reasoning effort", ["minimal", "low", "medium", "high", "xhigh"]);
+						if (!lvl) return;
+						adv.reasoning = lvl;
+						ctx.ui.notify(`Advisor reasoning → ${lvl}`, "info");
+					}
+					store.saveSquadSettings(settings);
+					return;
+				}
+
 				case "agents": {
 					const agentArg = parts[1];
 					const allAgents = store.loadAllAgentDefs(ctx.cwd);
@@ -895,7 +1175,7 @@ export default function (pi: ExtensionAPI) {
 							return;
 						}
 						const options = allAgents.map((a) => {
-							const model = a.model ? ` [${a.model}]` : " [default]";
+							const model = a.model ? ` [${a.model}${a.thinking ? `:${a.thinking}` : ""}]` : a.thinking ? ` [default:${a.thinking}]` : " [default]";
 							const status = a.disabled ? " ✗ disabled" : "";
 							return `${a.name} — ${a.role}${model}${status}`;
 						});
@@ -911,6 +1191,7 @@ export default function (pi: ExtensionAPI) {
 							"View details",
 							"Edit in editor",
 							"Change model",
+							"Change thinking",
 							"Toggle tools (restrict/unrestrict)",
 							disableLabel,
 							"Cancel",
@@ -924,6 +1205,7 @@ export default function (pi: ExtensionAPI) {
 								`Role: ${agent.role}`,
 								`Description: ${agent.description}`,
 								`Model: ${agent.model || "(default)"}`,
+								`Thinking: ${agent.thinking || "(default)"}`,
 								`Tools: ${agent.tools ? agent.tools.join(", ") : "(all)"}`,
 								`Tags: ${agent.tags.join(", ")}`,
 								``,
@@ -953,6 +1235,14 @@ export default function (pi: ExtensionAPI) {
 								store.saveAgentDef(agent);
 								ctx.ui.notify(`${agent.name} model → ${agent.model || "(default)"}`, "info");
 							}
+						} else if (action === "Change thinking") {
+							const levels = ["(default)", ...THINKING_LEVELS];
+							const level = await ctx.ui.select(`Thinking level for ${agent.name}`, levels);
+							if (level !== undefined) {
+								agent.thinking = level === "(default)" ? null : level;
+								store.saveAgentDef(agent);
+								ctx.ui.notify(`${agent.name} thinking → ${agent.thinking || "(default)"}`, "info");
+							}
 						} else if (action === disableLabel) {
 							agent.disabled = !agent.disabled;
 							store.saveAgentDef(agent);
@@ -986,6 +1276,7 @@ export default function (pi: ExtensionAPI) {
 							`${agent.name} — ${agent.role}${status}`,
 							`${agent.description}`,
 							`Model: ${agent.model || "(default)"}`,
+							`Thinking: ${agent.thinking || "(default)"}`,
 							`Tools: ${agent.tools ? agent.tools.join(", ") : "(all)"}`,
 							`Tags: ${agent.tags.join(", ")}`,
 						].join("\n");
@@ -1003,7 +1294,7 @@ export default function (pi: ExtensionAPI) {
 						activateSquadView(direct.id, ctx);
 						return;
 					}
-					ctx.ui.notify(`Unknown: /squad ${sub}. Try: list, all, select, widget, panel, cancel, clear`, "warning");
+					ctx.ui.notify(`Unknown: /squad ${sub}. Try: list, all, select, agents, defaults, msg, widget, panel, cancel, clear, cleanup`, "warning");
 			}
 		},
 	});
@@ -1019,7 +1310,7 @@ export default function (pi: ExtensionAPI) {
  * Returns the selected squad or undefined if cancelled.
  */
 async function pickSquad(
-	ctx: import("@mariozechner/pi-coding-agent").ExtensionContext | import("@mariozechner/pi-coding-agent").ExtensionCommandContext,
+	ctx: import("@earendil-works/pi-coding-agent").ExtensionContext | import("@earendil-works/pi-coding-agent").ExtensionCommandContext,
 	squads: Squad[],
 	showProject = false,
 ): Promise<Squad | undefined> {
@@ -1046,7 +1337,7 @@ async function pickSquad(
  * Sets activeSquadId, starts widget, shows notification.
  * Does NOT start a scheduler (view-only unless squad needs resuming).
  */
-function activateSquadView(squadId: string, ctx: import("@mariozechner/pi-coding-agent").ExtensionContext | import("@mariozechner/pi-coding-agent").ExtensionCommandContext): void {
+function activateSquadView(squadId: string, ctx: import("@earendil-works/pi-coding-agent").ExtensionContext | import("@earendil-works/pi-coding-agent").ExtensionCommandContext): void {
 	const squad = store.loadSquad(squadId);
 	if (!squad) {
 		ctx.ui.notify(`Squad '${squadId}' not found`, "error");
@@ -1088,7 +1379,7 @@ function forceWidgetUpdate(): void {
  * that resolves when done() is called. The panel calls done() on close.
  */
 function openPanel(
-	ctx: import("@mariozechner/pi-coding-agent").ExtensionContext,
+	ctx: import("@earendil-works/pi-coding-agent").ExtensionContext,
 	scheduler: Scheduler,
 	squadId: string,
 ): void {
@@ -1151,19 +1442,21 @@ async function startSquad(
 	squadId: string,
 	params: {
 		goal: string;
-		agents?: Record<string, { model?: string }>;
+		agents?: Record<string, { model?: string; thinking?: string }>;
 		tasks?: Array<{
 			id: string;
 			title: string;
 			description?: string;
 			agent: string;
 			depends?: string[];
+			inheritContext?: boolean;
 		}>;
 		config?: { maxConcurrency?: number };
 	},
 	cwd: string,
 	skillPaths: string[],
 	pi: ExtensionAPI,
+	sessionFile: string | null = null,
 ) {
 	let plan: PlannerOutput;
 
@@ -1188,27 +1481,33 @@ async function startSquad(
 			}
 		}
 	} else {
-		// Run planner to generate task breakdown
+		// Run planner to generate task breakdown (squad default policy as fallback)
 		try {
-			plan = await runPlanner({ goal: params.goal, cwd });
+			const defaults = resolveSquadDefaults();
+			plan = await runPlanner({ goal: params.goal, cwd, fallbackModel: defaults.model, fallbackThinking: defaults.thinking });
 		} catch (error) {
-			return {
-				content: [
-					{ type: "text" as const, text: `Failed to plan: ${(error as Error).message}` },
-				],
-				isError: true,
-			};
+			// Throwing marks the tool result as an error for the LLM (returning isError is ignored in current pi)
+			throw new Error(`Failed to plan: ${(error as Error).message}`);
 		}
 	}
 
 	// Merge agent roster
-	const agents: Record<string, { model?: string }> = { ...plan.agents };
+	const agents: Record<string, { model?: string; thinking?: string }> = { ...plan.agents };
 	if (params.agents) {
 		for (const [name, entry] of Object.entries(params.agents)) {
 			agents[name] = { ...agents[name], ...entry };
 		}
 	}
 
+	// Validate the plan — same enforcement for main-session and planner plans.
+	// Errors block squad creation; warnings are reported back to the plan author.
+	const validation = validatePlan(plan.tasks);
+	if (validation.errors.length > 0) {
+		throw new Error(
+			`Plan rejected:\n- ${validation.errors.join("\n- ")}\n\nFix the task list and call squad again.`,
+		);
+	}
+
 	// Create squad
 	const config: SquadConfig = {
 		...DEFAULT_SQUAD_CONFIG,
@@ -1221,6 +1520,7 @@ async function startSquad(
 		status: "running",
 		created: store.now(),
 		cwd,
+		sessionFile,
 		agents,
 		config,
 	};
@@ -1236,6 +1536,7 @@ async function startSquad(
 			agent: taskDef.agent,
 			status: taskDef.depends.length === 0 ? "pending" : "blocked",
 			depends: taskDef.depends,
+			...(taskDef.inheritContext ? { inheritContext: true } : {}),
 			created: store.now(),
 			started: null,
 			completed: null,
@@ -1243,22 +1544,14 @@ async function startSquad(
 			error: null,
 			usage: { inputTokens: 0, outputTokens: 0, cost: 0, turns: 0 },
 		};
-
-		// Mark tasks with unmet deps as blocked
-		if (task.depends.length > 0) {
-			const allDepsMet = task.depends.every((depId) =>
-				plan.tasks.some((t) => t.id === depId),
-			);
-			if (!allDepsMet) {
-				task.status = "pending"; // deps reference external tasks, treat as ready
-			}
-		}
+		// Note: unknown dependency references are hard validation errors above,
+		// so blocked tasks here always have resolvable deps.
 
 		store.createTask(squadId, task);
 	}
 
 	// Start scheduler
-	const scheduler = new Scheduler(squadId, skillPaths);
+	const scheduler = new Scheduler(squadId, skillPaths, schedulerSpawnContext);
 	schedulers.set(squadId, scheduler);
 	activeSquadId = squadId;
 
@@ -1286,13 +1579,16 @@ async function startSquad(
 					completedSched.updateContext();
 				}
 
+				// followUp + triggerTurn: wake an idle main agent to review; if it's
+				// mid-conversation with the human, deliver after it finishes
 				pi.sendMessage({
 					customType: "squad-completed",
 					content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\n` +
 						`Summary:\n${summary}\n\n` +
-						`Total cost: $${totalCost.toFixed(4)}`,
+						`Total cost: $${totalCost.toFixed(4)}\n\n` +
+						REVIEW_INSTRUCTIONS,
 					display: true,
-				});
+				}, { triggerTurn: true, deliverAs: "followUp" });
 
 				// Clear scheduler but keep activeSquadId so squad_status still works
 				schedulers.delete(squadId);
@@ -1312,7 +1608,7 @@ async function startSquad(
 						`Failed: ${failed.map((t) => `${t.id}: ${t.error?.slice(0, 100)}`).join("; ")}\n` +
 						`Use squad_status for details or squad_modify to adjust.`,
 					display: true,
-				}, { triggerTurn: true });
+				}, { triggerTurn: true, deliverAs: "followUp" });
 				forceWidgetUpdate();
 				break;
 			}
@@ -1352,9 +1648,14 @@ async function startSquad(
 		content: [
 			{
 				type: "text" as const,
-				text: `Squad "${squadId}" started with ${plan.tasks.length} tasks.\n\n${taskSummary}\n\nAgents are working in the background. Use squad_status to check progress.`,
+				text: `Squad "${squadId}" started with ${plan.tasks.length} tasks.\n\n${taskSummary}${
+					validation.warnings.length > 0
+						? `\n\n⚠️ Plan warnings (fix with squad_modify, or address at review):\n- ${validation.warnings.join("\n- ")}`
+						: ""
+				}\n\nAgents work in the background — you will be woken automatically when the squad completes, fails, or needs help. Report this plan to the user and END YOUR TURN now. Do NOT poll squad_status, do NOT sleep-wait, do NOT loop.`,
 			},
 		],
+		details: undefined,
 	};
 }