@linimin/pi-letscook 0.1.62 → 0.1.64

package/README.md

@@ -34,8 +34,8 @@ Then run `/reload` in Pi.
 2. Run `/reload` in Pi.
 3. In the main chat, either implement directly with the agent or refine the concrete repo change you want.
 4. When you want workflow mode, run `/cook`.
-5. Review the synthesized startup brief and choose **Start** or **Cancel**.
-6. Later, run `/cook` again to resume from canonical state or confirm a synthesized replacement or next-round startup brief.
+5. Review the startup brief and choose **Start** or **Cancel**.
+6. Later, run `/cook` again to resume from canonical state or confirm a replacement or next-round handoff.
 
 ```text
 /cook
@@ -46,20 +46,20 @@ Then run `/reload` in Pi.
 | If you want to... | Do this |
 |---|---|
 | Implement directly without workflow | Ask in ordinary chat and let the agent modify the repo directly |
-| Start a tracked workflow | Discuss the concrete repo change in the main chat, then run `/cook` when you want workflow to begin |
+| Start a tracked workflow | Discuss the concrete repo change in ordinary chat, then run `/cook` when you want workflow mode |
 | Continue the current workflow | Run `/cook` |
-| Refocus or start the next round | Discuss the new concrete repo change in the main chat, then run `/cook` when you want a new startup brief synthesized |
+| Refocus or start the next round | Discuss the new concrete repo change in ordinary chat, then run `/cook` when you want workflow mode |
 
 ## What `/cook` expects
 
-- enough recent main-chat discussion for `/cook` to synthesize a concrete startup brief when you explicitly invoke it
-- a mission that is concrete enough to anchor bounded repo work rather than planning-only discussion
+- enough current task context for a primary-agent handoff synthesis step to produce a concrete workflow startup handoff
+- a mission and first slice concrete enough for the primary-agent handoff step to author a truthful implementation-startable handoff
 - acceptance and verification intent that can support a truthful first workflow round
 - README/CHANGELOG updates still count as concrete repo changes
-- assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts still do not count unless they can be turned into a concrete startup brief
-- optional explicit `cook_handoff` capsules may still be consumed as a compatibility intake path, but they are no longer required for new-workflow or next-round entry
+- assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts still do not count unless the primary-agent handoff step turns them into a concrete `cook_handoff` capsule
+- `/cook` first prefers a fresh explicit `cook_handoff` capsule when one already exists, but otherwise calls the primary-agent handoff synthesis step in the same `/cook` entry
 
-If `/cook` cannot derive a concrete startup brief, it fails closed, leaves canonical `.agent/**` state unchanged, and tells you to refine the mission, first slice, or verification intent in the main chat before rerunning `/cook`.
+If the primary-agent handoff step still cannot prepare a concrete handoff, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to refine the mission, first slice, or verification intent in the main chat before rerunning `/cook`.
 
 If a fresh explicit handoff exists but is still workflow-worthy rather than implementation-startable, `/cook` also fails closed instead of silently treating that capsule as planning support or canonical workflow state.
 
@@ -69,16 +69,16 @@ If you pass inline arguments to `/cook`, it also fails closed and tells you to m
 
 Only explicit `/cook` enters workflow mode. Ordinary prompts stay in the main chat and go straight to the primary agent.
 
-Ordinary chat can still directly implement repo changes. `/cook` is for the cases where you want workflow control rather than just implementation help.
+Ordinary chat can still directly implement repo changes. `/cook` is for the cases where you want workflow control rather than just implementation help, and the primary agent should prepare the handoff before you run it.
 
-When you explicitly run `/cook`, it synthesizes a startup brief from recent discussion using primary-agent-style context, then asks you to **Start** or **Cancel** before rewriting canonical workflow state.
+When you explicitly run `/cook`, it first checks for a fresh explicit primary-agent handoff. If one is missing, it calls a same-entry primary-agent handoff synthesis step from the current task context, then asks you to **Start** or **Cancel** before rewriting canonical workflow state.
 
-Optional explicit `/cook` capsules may still be used as compatibility startup intake, but they are not required for new-workflow or next-round entry.
+Explicit `/cook` capsules are still valid startup intake, but they are no longer the only path because `/cook` can synthesize the primary-agent handoff in the same entry when needed.
 
 Important behavior:
 - `/cook` is an optional workflow boundary and manual entry point
-- startup and next-round entry stay confirm-first, deriving startup from explicit user `/cook` entry plus recent discussion when needed
-- active workflows resume from canonical `.agent/**` state unless `/cook` synthesizes or receives a concrete replacement mission
+- startup and next-round entry stay confirm-first, using explicit primary-agent handoff data when present and otherwise running the primary-agent handoff synthesis step in the same `/cook` entry
+- active workflows resume from canonical `.agent/**` state unless a concrete replacement handoff is available or synthesized in the same `/cook` entry
 - explicit slash commands other than `/cook` continue normally in the main chat
 - ordinary main-chat discussion may clarify, propose, or directly implement repo changes without entering workflow mode
 
@@ -94,13 +94,13 @@ I want to add login redirect handling and tests.
 
 ## What happens when you run `/cook`
 
-`/cook` first checks for a fresh explicit primary-agent handoff capsule as a compatibility intake path. If none is present, `/cook` synthesizes a startup brief from recent discussion using primary-agent-style context. New-workflow entry and done-workflow next-round entry still fail closed when that synthesis is too weak or planning-only. When a workflow is already active and no concrete replacement mission is available, `/cook` resumes from canonical `.agent/**` state. None of this prevents ordinary-chat implementation when you choose not to enter workflow mode.
+`/cook` first checks for a fresh explicit primary-agent handoff capsule. New-workflow entry and done-workflow next-round entry use that handoff when it already exists; otherwise `/cook` calls a same-entry primary-agent handoff synthesis step, then immediately continues to Start / Cancel if the generated handoff is concrete enough. Active workflows still resume canonical state by default unless a concrete replacement handoff is available or synthesized in the same `/cook` entry. None of this prevents ordinary-chat implementation when you choose not to enter workflow mode.
 
 | Repo state | What you'll see |
 |---|---|
-| No workflow yet | `/cook` synthesizes a startup brief from recent discussion and asks you to choose **Start** or **Cancel**. A fresh explicit handoff capsule may still be used if present. Weak, unreliable, stale, planning-only, or non-startable intake still fails closed. |
-| Active workflow exists | Usually a resume of the current workflow from canonical `.agent/**` state. If `/cook` finds a different concrete replacement mission from a compatibility capsule or deferred synthesis, it shows a chooser first and only rewrites canonical state after you confirm the replacement. Ambiguous intake stays conservative. |
-| Previous workflow is `done` | `/cook` can synthesize the next implementation round from recent discussion behind **Start** or **Cancel**. Weak or planning-only next-round intake still fails closed. |
+| No workflow yet | `/cook` consumes a fresh explicit primary-agent handoff when one already exists, or synthesizes one from the primary-agent view in the same entry, then asks you to choose **Start** or **Cancel**. Stale, planning-only, or non-startable handoffs still fail closed. |
+| Active workflow exists | Usually a resume of the current workflow from canonical `.agent/**` state. If a concrete replacement handoff exists already or is synthesized in the same `/cook` entry and points to a different mission, `/cook` shows a chooser first and only rewrites canonical state after you confirm the replacement. Ambiguous or missing replacement handoff stays conservative. |
+| Previous workflow is `done` | `/cook` can start the next implementation round from a fresh explicit primary-agent handoff or from the same-entry primary-agent handoff synthesis step behind **Start** or **Cancel**. Weak or planning-only next-round handoffs still fail closed. |
 
 ## Confirmation and fail-closed behavior
 

package/extensions/completion/driver.ts

@@ -38,7 +38,7 @@ type ContextProposalAlternate = {
 	analysis: ContextProposalAnalysis;
 	goalText: string;
 	basisPreview: string;
-	source: "session" | "analyst" | "handoff_capsule" | "deferred_primary_agent_handoff";
+	source: "session" | "analyst" | "handoff_capsule";
 };
 
 type ContextProposal = ContextProposalAlternate & {
@@ -60,7 +60,7 @@ type CookContextProposalResult = {
 	blockedFailureMessage?: string;
 };
 
-function buildCookStartupDerivationFailureMessage(deps: CompletionDriverDeps, prefix?: string): string {
+function buildCookStartupBriefRequiredMessage(deps: CompletionDriverDeps, prefix?: string): string {
 	const requirement = deps.structuredDiscussionFailureDetail;
 	return prefix ? `${prefix} ${requirement}` : requirement;
 }
@@ -72,10 +72,9 @@ type ActiveWorkflowProposalAssessment = {
 	blockedFailureMessage?: string;
 	reason:
 		| "matching_mission"
-		| "no_replacement_proposal"
-		| "explicit_handoff_replacement"
-		| "deferred_replacement"
-		| "replacement_not_startable";
+		| "missing_explicit_handoff"
+		| "fresh_explicit_handoff"
+		| "fresh_explicit_handoff_not_startable";
 };
 
 type ExistingWorkflowChooserOptions = {
@@ -183,6 +182,7 @@ function buildCookStructuredDiscussionFailureMessage(deps: CompletionDriverDeps,
 	return prefix ? `${prefix} ${deps.structuredDiscussionFailureDetail}` : deps.structuredDiscussionFailureDetail;
 }
 
+
 export function completionContinuationFingerprint(snapshot: CompletionStateSnapshot): string | undefined {
 	if (asString(snapshot.state?.continuation_policy) !== "continue") return undefined;
 	const nextMandatoryRole = asString(snapshot.state?.next_mandatory_role);
@@ -321,23 +321,23 @@ async function assessActiveWorkflowProposalRouting(
 ): Promise<ActiveWorkflowProposalAssessment> {
 	const currentMission = currentMissionAnchor(snapshot);
 	const projectName = path.basename(snapshot.files.root);
-	const derived = await deps.deriveCookContextProposal(ctx, projectName);
-	if (derived.blockedFailureMessage) {
+	const proposalResult = await deps.deriveCookContextProposal(ctx, projectName);
+	if (proposalResult.blockedFailureMessage) {
 		const assessment: ActiveWorkflowProposalAssessment = {
 			action: "blocked",
 			currentMissionAnchor: currentMission,
-			blockedFailureMessage: derived.blockedFailureMessage,
-			reason: "replacement_not_startable",
+			blockedFailureMessage: proposalResult.blockedFailureMessage,
+			reason: "fresh_explicit_handoff_not_startable",
 		};
 		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 		return assessment;
 	}
-	const proposal = derived.proposal;
+	const proposal = proposalResult.proposal;
 	if (!proposal) {
 		const assessment: ActiveWorkflowProposalAssessment = {
 			action: "continue",
 			currentMissionAnchor: currentMission,
-			reason: "no_replacement_proposal",
+			reason: "missing_explicit_handoff",
 		};
 		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 		return assessment;
@@ -356,7 +356,7 @@ async function assessActiveWorkflowProposalRouting(
 		action: "refocus",
 		currentMissionAnchor: currentMission,
 		proposal,
-		reason: proposal.source === "handoff_capsule" ? "explicit_handoff_replacement" : "deferred_replacement",
+		reason: "fresh_explicit_handoff",
 	};
 	deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 	return assessment;
@@ -536,14 +536,14 @@ export async function runCookEntry(
 	if (!snapshot) {
 		const root = findRepoRoot(cwd) ?? cwd;
 		const projectName = path.basename(root);
-		const derived = await deps.deriveCookStartupProposal(ctx, projectName);
+		const derived = await deps.deriveCookContextProposal(ctx, projectName);
 		if (derived.blockedFailureMessage) {
 			deps.emitCommandText(ctx, derived.blockedFailureMessage, "info");
 			return;
 		}
 		const proposal = derived.proposal;
 		if (!proposal) {
-			deps.emitCommandText(ctx, buildCookStartupDerivationFailureMessage(deps), "info");
+			deps.emitCommandText(ctx, buildCookStartupBriefRequiredMessage(deps), "info");
 			return;
 		}
 		const decision = await deps.confirmContextProposal(ctx, proposal, {
@@ -581,14 +581,14 @@ export async function runCookEntry(
 	if (!goal) {
 		if (workflowDone) {
 			const projectName = path.basename(snapshot.files.root);
-			const derived = await deps.deriveCookStartupProposal(ctx, projectName);
+			const derived = await deps.deriveCookContextProposal(ctx, projectName);
 			if (derived.blockedFailureMessage) {
 				deps.emitCommandText(ctx, derived.blockedFailureMessage, "info");
 				return;
 			}
 			const proposal = derived.proposal;
 			if (!proposal) {
-				deps.emitCommandText(ctx, buildCookStartupDerivationFailureMessage(deps, "The previous completion workflow is already done."), "info");
+				deps.emitCommandText(ctx, buildCookStartupBriefRequiredMessage(deps, "The previous completion workflow is already done."), "info");
 				return;
 			}
 			const decision = await deps.confirmContextProposal(ctx, proposal, {
@@ -610,13 +610,7 @@ export async function runCookEntry(
 				buildAdvisoryStartupBrief({ proposal, analysis: decision.analysis }),
 			);
 			snapshot = (await loadCompletionSnapshot(snapshot.files.root)) ?? snapshot;
-			deps.emitCommandText(
-				ctx,
-				proposal.source === "handoff_capsule"
-					? `Started a new completion workflow round from explicit primary-agent handoff: ${decision.missionAnchor}`
-					: `Started a new completion workflow round from deferred primary-agent handoff: ${decision.missionAnchor}`,
-				"info",
-			);
+			deps.emitCommandText(ctx, `Started a new completion workflow round from explicit primary-agent handoff: ${decision.missionAnchor}`, "info");
 		} else {
 			const assessment = await assessActiveWorkflowProposalRouting(ctx, snapshot, deps);
 			if (assessment.action === "blocked") {
@@ -627,29 +621,20 @@ export async function runCookEntry(
 				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps);
 				return;
 			}
-			const explicitReplacement = assessment.reason === "explicit_handoff_replacement";
-			const deferredReplacement = assessment.reason === "deferred_replacement";
+			const explicitReplacement = assessment.reason === "fresh_explicit_handoff";
 			const decision = await confirmExistingWorkflowProposal(ctx, snapshot, assessment.proposal, deps, {
 				intro: explicitReplacement
 					? "A fresh explicit primary-agent handoff proposes replacing the current workflow. Choose how /cook should proceed:"
-					: deferredReplacement
-						? "A deferred primary-agent handoff synthesized from your recent discussion proposes replacing the current workflow. Choose how /cook should proceed:"
-						: "A replacement workflow is ready. Choose how /cook should proceed:",
+					: "A replacement workflow is ready. Choose how /cook should proceed:",
 				proposedMissionLabel: explicitReplacement
 					? "Proposed mission from explicit primary-agent handoff"
-					: deferredReplacement
-						? "Proposed mission from deferred primary-agent handoff"
-						: "Proposed mission",
+					: "Proposed mission",
 				refocusChoiceLabel: explicitReplacement
 					? "Start new workflow from explicit primary-agent handoff\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."
-					: deferredReplacement
-						? "Start new workflow from deferred primary-agent handoff\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."
-						: "Start new workflow\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state.",
+					: "Start new workflow\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state.",
 				alternateChoiceLabel: explicitReplacement
 					? "Start alternate workflow from explicit primary-agent handoff\n\nReview this alternate replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."
-					: deferredReplacement
-						? "Start alternate workflow from deferred primary-agent handoff\n\nReview this alternate replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."
-						: undefined,
+					: undefined,
 				comparison: "strict",
 			});
 			if (!decision) {
@@ -662,11 +647,9 @@ export async function runCookEntry(
 			}
 			const selectedProposal = decision.proposal;
 			const proposalDecision = await deps.confirmContextProposal(ctx, selectedProposal, {
-				title: explicitReplacement
+				title: assessment.reason === "fresh_explicit_handoff"
 					? "Start the replacement workflow from this explicit startup brief?"
-					: deferredReplacement
-						? "Start the replacement workflow from this deferred startup brief?"
-						: "Start the replacement workflow from this startup brief?",
+					: "Start the replacement workflow from this startup brief?",
 			});
 			if (!proposalDecision) {
 				deps.emitCommandText(ctx, buildCookCancellationMessage("Cancelled replacement workflow proposal", deps), "info");
@@ -686,11 +669,9 @@ export async function runCookEntry(
 			snapshot = (await loadCompletionSnapshot(snapshot.files.root)) ?? snapshot;
 			deps.emitCommandText(
 				ctx,
-				explicitReplacement
+				assessment.reason === "fresh_explicit_handoff"
 					? `Refocused completion mission from explicit primary-agent handoff to: ${proposalDecision.missionAnchor}`
-					: deferredReplacement
-						? `Refocused completion mission from deferred primary-agent handoff to: ${proposalDecision.missionAnchor}`
-						: `Refocused completion mission to: ${proposalDecision.missionAnchor}`,
+					: `Refocused completion mission to: ${proposalDecision.missionAnchor}`,
 				"info",
 			);
 		}

package/extensions/completion/index.ts

@@ -17,7 +17,6 @@ import {
 	assessMissionAnchor,
 	collectRecentDiscussionEntries,
 	collectRecentSessionMessages,
-	deriveCookContextProposalFromRecentDiscussion,
 	assessLatestCookHandoffProposal,
 	finalizeContextProposalAnalysis,
 	isWeakMissionAnchor,
@@ -25,7 +24,6 @@ import {
 	missionAnchorsStrictlyEquivalent,
 	normalizeMissionAnchorText,
 	resolveContextProposalConfirmationAction,
-	retagContextProposalSource,
 	stripCodeBlocks,
 } from "./proposal";
 import type {
@@ -49,7 +47,7 @@ import {
 	maybeWriteContextProposalSnapshot,
 } from "./prompt-surfaces";
 import { toolCallBlockReason } from "./policy-guards";
-import { analyzeContextProposalWithAgent, runCompletionRole } from "./role-runner";
+import { analyzeContextProposalWithAgent, generateCookHandoffWithAgent, runCompletionRole } from "./role-runner";
 import {
 	applyLiveRoleEvent,
 	buildInlineRunningLines,
@@ -135,10 +133,9 @@ type ActiveWorkflowProposalAssessment = {
 	blockedFailureMessage?: string;
 	reason:
 		| "matching_mission"
-		| "no_replacement_proposal"
-		| "explicit_handoff_replacement"
-		| "deferred_replacement"
-		| "replacement_not_startable";
+		| "missing_explicit_handoff"
+		| "fresh_explicit_handoff"
+		| "fresh_explicit_handoff_not_startable";
 };
 
 function completionTestWorkflowActionOverride(): "continue" | "refocus" | "cancel" | undefined {
@@ -212,7 +209,7 @@ function maybeWriteTestSnapshot(targetPath: string | undefined, content: string)
 
 const COOK_MAIN_CHAT_RERUN_GUIDANCE = "Discuss changes in the main chat and rerun /cook.";
 const COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL =
-	"/cook failed closed because it could not derive a concrete startup brief from recent discussion. Clarify the mission, first slice, or verification intent in the main chat, then rerun /cook.";
+	"/cook failed closed because the primary-agent handoff step could not prepare a concrete startup handoff from the current task context. Clarify the mission, first slice, or verification intent in the main chat, then rerun /cook.";
 
 function isWorkflowDone(snapshot: CompletionStateSnapshot | undefined): boolean {
 	return asString(snapshot?.state?.continuation_policy) === "done";
@@ -379,15 +376,37 @@ function stripCookHandoffBlocks(text: string): string {
 	return text.replace(COOK_HANDOFF_BLOCK_REGEX, " ").replace(/\s+/g, " ").trim();
 }
 
-async function deriveCookRecentDiscussionProposal(
+async function deriveCookStartupProposal(
 	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
 	projectName: string,
-): Promise<ContextProposal | undefined> {
+): Promise<CookContextProposalResult> {
+	const recentMessages = collectRecentSessionMessages(ctx, { isRecord, asString, asNumber, isStaleContextError });
+	const explicitHandoff = assessLatestCookHandoffProposal(recentMessages, projectName, {
+		asString,
+		asStringArray,
+		assessMissionAnchor,
+		normalizeMissionAnchorText,
+		isWeakMissionAnchor,
+		missionAnchorsStrictlyEquivalent,
+		stripCodeBlocks,
+	});
+	if (explicitHandoff.status === "startable") return { proposal: explicitHandoff.proposal };
+	if (explicitHandoff.status === "fresh_but_not_startable") {
+		return { blockedFailureMessage: explicitHandoff.message };
+	}
+	return {};
+}
+
+async function deriveCookContextProposal(
+	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
+	projectName: string,
+): Promise<CookContextProposalResult> {
+	const explicit = await deriveCookStartupProposal(ctx, projectName);
+	if (explicit.proposal || explicit.blockedFailureMessage) return explicit;
 	const recentMessages = collectRecentSessionMessages(ctx, { isRecord, asString, asNumber, isStaleContextError });
 	const recentEntries = recentMessages
-		.filter((entry) => (entry.role === "user" || entry.role === "custom") && !entry.isCommand)
-		.filter((entry) => !/```cook_handoff\b/i.test(entry.text))
-		.slice(0, 8)
+		.filter((entry) => !entry.isCommand && (entry.role === "user" || entry.role === "assistant" || entry.role === "custom" || entry.role === "summary"))
+		.slice(0, 12)
 		.map((entry) => ({ role: entry.role, text: stripCookHandoffBlocks(entry.text) }))
 		.filter((entry) => entry.text.length > 0);
 	const snapshot = await loadCompletionSnapshot(getCtxCwd(ctx));
@@ -403,50 +422,22 @@ async function deriveCookRecentDiscussionProposal(
 			`verification summary: ${asString(snapshot.verificationEvidence?.summary) ?? "(none)"}`,
 		]
 		: [];
-	const proposal = await deriveCookContextProposalFromRecentDiscussion(projectName, recentEntries, {
-		asString,
-		asStringArray,
-		workflowContext: snapshot
-			? {
-				currentMissionAnchor:
-					asString(snapshot.state?.mission_anchor) ?? asString(snapshot.plan?.mission_anchor) ?? asString(snapshot.active?.mission_anchor),
-				latestCompletedSlice: asString(snapshot.state?.latest_completed_slice),
-				latestVerifiedSlice: asString(snapshot.state?.latest_verified_slice),
-				activeSliceGoal: asString(snapshot.active?.goal),
-				activeSliceWhyNow: asString(snapshot.active?.why_now),
-				verificationGoal: asString(snapshot.verificationEvidence?.goal),
-				verificationSummary: asString(snapshot.verificationEvidence?.summary),
-				continuationPolicy: asString(snapshot.state?.continuation_policy),
-			}
-			: undefined,
-		analyzeContextProposal: async (entries) =>
-			await analyzeContextProposalWithAgent({
-				ctx,
-				projectName,
-				recentEntries: entries,
-				workflowContextLines,
-				liveRoleActivityByRoot,
-				completionStatusKey: COMPLETION_STATUS_KEY,
-				safeUiCall,
-				getCtxCwd,
-				getCtxHasUI,
-				getCtxUi,
-			}),
-		assessMissionAnchor,
-		isWeakMissionAnchor,
-		missionAnchorsStrictlyEquivalent,
-		normalizeMissionAnchorText,
-		stripCodeBlocks,
+	const raw = await generateCookHandoffWithAgent({
+		ctx,
+		projectName,
+		recentEntries,
+		workflowContextLines,
+		liveRoleActivityByRoot,
+		completionStatusKey: COMPLETION_STATUS_KEY,
+		safeUiCall,
+		getCtxCwd,
+		getCtxHasUI,
+		getCtxUi,
 	});
-	return retagContextProposalSource(proposal, "deferred_primary_agent_handoff");
-}
-
-async function deriveCookStartupProposal(
-	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
-	projectName: string,
-): Promise<CookContextProposalResult> {
-	const recentMessages = collectRecentSessionMessages(ctx, { isRecord, asString, asNumber, isStaleContextError });
-	const explicitHandoff = assessLatestCookHandoffProposal(recentMessages, projectName, {
+	if (!raw) return {};
+	const generated = assessLatestCookHandoffProposal([
+		{ role: "assistant", text: raw, messageId: "generated-primary-agent-handoff", timestampMs: Date.now(), isCommand: false },
+	], projectName, {
 		asString,
 		asStringArray,
 		assessMissionAnchor,
@@ -455,18 +446,9 @@ async function deriveCookStartupProposal(
 		missionAnchorsStrictlyEquivalent,
 		stripCodeBlocks,
 	});
-	if (explicitHandoff.status === "startable") return { proposal: explicitHandoff.proposal };
-	if (explicitHandoff.status === "fresh_but_not_startable") {
-		return { blockedFailureMessage: explicitHandoff.message };
-	}
-	return { proposal: await deriveCookRecentDiscussionProposal(ctx, projectName) };
-}
-
-async function deriveCookContextProposal(
-	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
-	projectName: string,
-): Promise<CookContextProposalResult> {
-	return await deriveCookStartupProposal(ctx, projectName);
+	if (generated.status === "startable") return { proposal: generated.proposal };
+	if (generated.status === "fresh_but_not_startable") return { blockedFailureMessage: generated.message };
+	return {};
 }
 
 async function confirmContextProposal(
@@ -942,7 +924,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		structuredDiscussionFailureDetail: COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL,
 		mainChatRerunGuidance: COOK_MAIN_CHAT_RERUN_GUIDANCE,
 		cookCommandSpec: {
-			description: "/cook workflow: optionally enter tracked workflow mode, synthesize a startup brief from explicit /cook entry, resume the current workflow from canonical state, or confirm a replacement mission",
+			description: "/cook workflow: start or replace workflow only from an explicit primary-agent handoff, or resume the current workflow from canonical state",
 		},
 		buildContextProposalContinuationReason,
 		completionKickoff,

package/extensions/completion/prompt-surfaces.ts

@@ -32,7 +32,8 @@ export function buildCookHandoffBoundaryReminder(): string {
 		"/cook is optional workflow mode for resumability, review, audit, canonical .agent state, or deliberate multi-session control; it is not required just to edit repo files in ordinary chat.",
 		"If the user wants direct implementation now, stay in ordinary chat and help directly instead of blocking on /cook.",
 		"If the user asks follow-up questions or wants to keep refining scope, continue helping naturally in ordinary chat.",
-		"If the user explicitly runs /cook, /cook will synthesize a startup brief from recent discussion using primary-agent-style context, then show Start/Cancel confirmation before canonical workflow state is rewritten.",
+		"If the user explicitly runs /cook, the extension should call a primary-agent handoff synthesis step from the current task context, then show Start/Cancel confirmation without making the user rerun /cook.",
+		"Do not expect /cook to infer or guess startup intent from recent discussion alone; /cook should use explicit primary-agent handoff data, whether it already exists or is synthesized in the same /cook entry.",
 		"Only provide a preview startup brief or ```cook_handoff``` capsule in ordinary chat when the user explicitly asks for that preview behavior.",
 		"Any preview capsule is startup intake for /cook only: do not present it as canonical .agent state, an active slice, or a persistent repo contract.",
 		"When you continue in ordinary chat, do not pretend /cook already started and do not silently rewrite discussion into canonical workflow state.",

package/extensions/completion/role-runner.ts

@@ -67,6 +67,8 @@ export type AnalyzeContextProposalWithAgentParams = {
 	getCtxUi: <T extends { ui: any }>(ctx: T) => any | undefined;
 };
 
+export type GenerateCookHandoffWithAgentParams = AnalyzeContextProposalWithAgentParams;
+
 const AGENT_HOME = path.join(os.homedir(), ".pi", "agent");
 const EXTENSION_DIR = typeof __dirname === "string" ? __dirname : process.cwd();
 const PACKAGE_ROOT_CANDIDATE = path.resolve(EXTENSION_DIR, "..", "..");
@@ -94,6 +96,18 @@ const CONTEXT_PROPOSAL_ANALYST_SYSTEM_PROMPT = [
 const STARTUP_ANALYST_ROLE = "cook-proposal-analyst";
 const ANALYST_HEARTBEAT_MS = 5_000;
 
+const PRIMARY_AGENT_HANDOFF_SYSTEM_PROMPT = [
+	"You are the primary agent preparing an explicit /cook handoff after the user already chose workflow mode.",
+	"Return either exactly one fenced ```cook_handoff JSON block or one brief plain sentence explaining why no concrete handoff can be prepared.",
+	"If you can prepare a handoff, the JSON must use kind cook_handoff, source primary_agent, and handoff_kind implementation_workflow_handoff.",
+	"When the user has clearly accepted a concrete assistant-proposed slice, carry that slice forward into the handoff instead of broadening or re-guessing the mission.",
+	"Do not make /cook infer or rediscover the mission from recent discussion later; author the handoff now from the primary-agent view of the task.",
+	"Do not emit markdown commentary before or after the capsule.",
+	"If the task is not concrete enough for implementation workflow, do not invent the slice.",
+	"A valid implementation-ready handoff must include mission, scope, constraints or non_goals, acceptance, risks, notes, first_slice_goal, first_slice_non_goals, implementation_surfaces, verification_commands, and why_this_slice_first.",
+].join(" ");
+const PRIMARY_AGENT_HANDOFF_ROLE = "cook-primary-agent-handoff";
+
 class StartupAnalystOverlay extends Container {
 	private readonly border: DynamicBorder;
 	private readonly title: Text;
@@ -309,6 +323,97 @@ async function runContextProposalAnalystSubprocess(params: AnalyzeContextProposa
 	return await run();
 }
 
+function serializeRecentConversationEntries(entries: RecentDiscussionEntry[]): string {
+	return entries
+		.slice()
+		.reverse()
+		.map((entry, index) => `[${index + 1}] ${entry.role.toUpperCase()}\n${entry.text}`)
+		.join("\n\n");
+}
+
+function buildPrimaryAgentHandoffPrompt(projectName: string, recentEntries: RecentDiscussionEntry[], workflowContextLines: string[] = []): string {
+	const lines = [
+		`Project: ${projectName}`,
+		"",
+		"Recent session transcript:",
+		serializeRecentConversationEntries(recentEntries),
+	];
+	if (workflowContextLines.length > 0) lines.push("", "Canonical workflow context:", ...workflowContextLines);
+	lines.push(
+		"",
+		"Task:",
+		"The user explicitly invoked /cook. Prepare the primary-agent handoff that /cook should consume immediately for Start/Cancel confirmation.",
+	);
+	return lines.join("\n");
+}
+
+async function runPrimaryAgentHandoffSubprocess(params: GenerateCookHandoffWithAgentParams): Promise<string | undefined> {
+	const { ctx, projectName, recentEntries } = params;
+	const modelArg = contextProposalAnalystModelArg(ctx.model);
+	if (!modelArg) return undefined;
+	const cwd = params.getCtxCwd(ctx);
+	const runCwd = findCompletionRoot(cwd) ?? findRepoRoot(cwd) ?? cwd;
+	const prompt = buildPrimaryAgentHandoffPrompt(projectName, recentEntries, params.workflowContextLines ?? []);
+	const systemPromptTemp = await writeTempFile(runCwd, "pi-cook-primary-agent-handoff-", PRIMARY_AGENT_HANDOFF_SYSTEM_PROMPT);
+	const args: string[] = ["--mode", "json", "-p", "--no-session", "--no-extensions", "--append-system-prompt", systemPromptTemp.filePath, "--model", modelArg, prompt];
+	const invocation = getPiInvocation(args);
+	const liveActivity = createLiveRoleActivity(PRIMARY_AGENT_HANDOFF_ROLE);
+	liveActivity.progress = "Preparing primary-agent /cook handoff";
+	liveActivity.currentAction = "Authoring explicit startup handoff from current task context";
+	liveActivity.assistantSummary = liveActivity.progress;
+	try {
+		const output = await new Promise<string | undefined>((resolve) => {
+			const proc = spawn(invocation.command, invocation.args, {
+				cwd: runCwd,
+				env: process.env,
+				stdio: ["ignore", "pipe", "pipe"],
+				shell: false,
+			});
+			let buffer = "";
+			const messages: RoleMessage[] = [];
+			const processLine = (line: string) => {
+				if (!line.trim()) return;
+				try {
+					const event = JSON.parse(line) as JsonRecord;
+					applyLiveRoleEvent(liveActivity, event, messages);
+				} catch {
+					// ignore malformed lines
+				}
+			};
+			proc.stdout.on("data", (chunk) => {
+				buffer += chunk.toString();
+				const lines = buffer.split("\n");
+				buffer = lines.pop() ?? "";
+				for (const line of lines) processLine(line);
+			});
+			proc.stderr.on("data", () => {
+				// ignore stderr unless no assistant output arrives
+			});
+			proc.on("close", (code) => {
+				if (buffer.trim()) processLine(buffer);
+				resolve(code === 0 ? liveActivity.lastAssistantText?.trim() || undefined : undefined);
+			});
+			proc.on("error", () => resolve(undefined));
+		});
+		return output;
+	} finally {
+		await fsp.rm(systemPromptTemp.dir, { recursive: true, force: true });
+	}
+}
+
+export async function generateCookHandoffWithAgent(params: GenerateCookHandoffWithAgentParams): Promise<string | undefined> {
+	if (process.env.PI_COMPLETION_DISABLE_PRIMARY_HANDOFF_SYNTHESIS === "1") return undefined;
+	const testOutput = asString(process.env.PI_COMPLETION_PRIMARY_HANDOFF_OUTPUT);
+	if (testOutput) return testOutput;
+	if (params.recentEntries.length === 0) return undefined;
+	try {
+		return await runPrimaryAgentHandoffSubprocess(params);
+	} catch (error) {
+		console.warn("[completion] primary-agent handoff generation failed", error);
+		return undefined;
+	}
+}
+
 export async function analyzeContextProposalWithAgent(params: AnalyzeContextProposalWithAgentParams): Promise<ContextProposal | undefined> {
 	if (process.env.PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST === "1") return undefined;
 	const testOutput = asString(process.env.PI_COMPLETION_CONTEXT_PROPOSAL_ANALYST_OUTPUT);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.62",
+  "version": "0.1.64",
   "description": "Pi package for long-running completion workflows with canonical .agent state, role-based subagents, continuity, and verification helpers.",
   "license": "MIT",
   "private": false,