pi-agenticoding/03: make manual handoff seamless

Author: grzegorznowak

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Breaking:** handoff no longer auto-sends `Proceed.` after compaction and no longer supports configurable auto-resume. The superseded `handoff.resumeBehavior` (`"wait"`/`"proceed"`) setting is ignored.
 - Added `handoff.automaticEnabled` raw settings support with JSON boolean values. Missing settings default to automatic handoff enabled; `false` removes the agent-facing handoff tool and handoff-call guidance during normal turns while preserving explicit `/handoff <direction>`.
 - Added the extension-owned `/agenticoding-settings` TUI panel for automatic handoff availability. TUI saves are global-only to `~/.pi/agent/settings.json`, preserve unrelated settings keys, persist real booleans, and visibly warn when a project override masks the global value.
-- Manual `/handoff <direction>` now refuses while the assistant is streaming and tells the operator to retry once idle. This reflects Pi's tool-schema snapshot semantics and missing fresh-turn lifecycle hooks for queued follow-up turns.
+- Manual `/handoff <direction>` now waits behind the scenes when the assistant is streaming, then enables the `handoff` tool and starts a fresh handoff turn once idle. Visible `agenticoding-handoff-diagnostic` conversation messages have been removed from this flow.
 
 ## [0.3.0] - 2026-05-23
 

README.md

@@ -127,9 +127,9 @@ To make handoff human-driven only, set `handoff.automaticEnabled` to `false` in
 }
 ```
 
-Settings are read from `~/.pi/agent/settings.json` and `<project>/.pi/settings.json`, with project settings overriding global settings. When automatic handoff is disabled, the agent-facing `handoff` tool and handoff-call guidance are removed from normal turns. The explicit operator command `/handoff <direction>` still works from an idle prompt: it temporarily enables the tool for that fresh requested handoff, compacts, restores the disabled state, and then waits for your next input. If the assistant is already streaming, `/handoff` will refuse with a diagnostic and ask you to retry once idle because Pi cannot add new tools to an already-snapshotted agent run or fire fresh-turn lifecycle hooks for queued follow-ups.
+Settings are read from `~/.pi/agent/settings.json` and `<project>/.pi/settings.json`, with project settings overriding global settings. When automatic handoff is disabled, the agent-facing `handoff` tool and handoff-call guidance are removed from normal turns. The explicit operator command `/handoff <direction>` still works from idle or busy prompts: if the assistant is streaming, it waits behind the scenes until the current run is idle, temporarily enables the tool for a fresh requested handoff turn, compacts, restores the disabled state, and then waits for your next input.
 
-Run `/agenticoding-settings` to change the global value from the TUI. It saves global-only to `~/.pi/agent/settings.json`, preserves unrelated JSON keys, shows the effective runtime value separately, and warns when a project override masks the global value. Setting changes affect future fresh agent turns; they do not alter the tool schema of an in-flight queued follow-up. Edit or remove project overrides manually.
+Run `/agenticoding-settings` to change the global value from the TUI. It saves global-only to `~/.pi/agent/settings.json`, preserves unrelated JSON keys, shows the effective runtime value separately, and warns when a project override masks the global value. Setting changes affect future fresh agent turns; manual `/handoff` uses that same rule by waiting for idle before enabling the tool and starting its own fresh turn. Edit or remove project overrides manually.
 
 Migration note: the superseded PR-only `handoff.resumeBehavior` (`"wait"`/`"proceed"`) setting is ignored and cannot trigger automatic continuation. Remove it when convenient.
 

agenticoding.test.ts

@@ -646,23 +646,44 @@ test("manual slash handoff restores deactivated handoff after success error or s
 	});
 });
 
-test("manual slash handoff refuses busy requests and asks the operator to retry once idle", async () => {
+test("manual slash handoff waits for busy runs then starts a fresh handoff turn", async () => {
 	await withIsolatedSettings(async ({ cwd }) => {
 		await writeSettingsFile(join(cwd, ".pi", "settings.json"), { handoff: { automaticEnabled: false } });
 		const pi = new MockPi();
 		registerAgenticoding(pi as any);
+		const deferred = createDeferred();
+		let idle = false;
+		let waitCalls = 0;
 
-		await pi.commands.get("handoff")!.handler("implement auth", { cwd, hasUI: false, isIdle: () => false });
+		const command = pi.commands.get("handoff")!.handler("implement auth", {
+			cwd,
+			hasUI: false,
+			isIdle: () => idle,
+			waitForIdle: async () => {
+				waitCalls += 1;
+				await deferred.promise;
+				idle = true;
+			},
+		});
 
+		await Promise.resolve();
+		assert.equal(waitCalls, 1);
 		assert.equal(pi.activeTools.includes("handoff"), false);
 		assert.deepEqual(pi.sentUserMessages, []);
-		assert.equal(pi.sentMessages[0]?.message.customType, "agenticoding-handoff-diagnostic");
-		assert.match(pi.sentMessages[0]?.message.content, /currently streaming/);
-		assert.match(pi.sentMessages[0]?.message.content, /Retry \/handoff once the assistant is idle/);
+		assert.deepEqual(pi.sentMessages, []);
+
+		deferred.resolve();
+		await command;
+
+		assert.ok(pi.activeTools.includes("handoff"));
+		assert.equal(pi.sentUserMessages.length, 1);
+		assert.equal(pi.sentUserMessages[0].options, undefined);
+		assert.match(pi.sentUserMessages[0].content, /Handoff direction: implement auth/);
+		assert.deepEqual(pi.sentMessages, []);
 	});
 });
 
-test("manual slash handoff reports a diagnostic instead of prompting prose when handoff cannot be activated", async () => {
+test("manual slash handoff reports only a UI error when handoff cannot be activated", async () => {
 	const pi = new MockPi();
 	(pi as any).setActiveTools = undefined;
 	const state = createState();
@@ -679,7 +700,7 @@ test("manual slash handoff reports a diagnostic instead of prompting prose when
 	assert.deepEqual(pi.sentUserMessages, []);
 	assert.equal(notifications[0].level, "error");
 	assert.match(notifications[0].message, /could not be activated/);
-	assert.equal(pi.sentMessages[0].message.customType, "agenticoding-handoff-diagnostic");
+	assert.deepEqual(pi.sentMessages, []);
 });
 
 test("handoff automatic setting is documented in README", async () => {
@@ -1086,7 +1107,7 @@ test("turn_end fallback clears stale requested handoff status", async () => {
 	assert.equal(statuses.get(STATUS_KEY_HANDOFF), undefined);
 	assert.equal(notifications[0].level, "warning");
 	assert.match(notifications[0].message, /did not call the handoff tool/);
-	assert.equal(pi.sentMessages.at(-1)?.message.customType, "agenticoding-handoff-diagnostic");
+	assert.deepEqual(pi.sentMessages, []);
 });
 
 test("session_start new clears stale handoff status and warning widget", async () => {
@@ -1232,7 +1253,7 @@ test("buildNudge handles null percent and boundary hints before topic guidance",
 	assert.match(noTopic, /No active notebook topic is set/);
 });
 
-test("watchdog stale requested handoff cleanup emits a visible context diagnostic", async () => {
+test("watchdog stale requested handoff cleanup avoids conversation diagnostics", async () => {
 	const pi = new MockPi();
 	const state = createState();
 	state.pendingRequestedHandoff = { direction: "implement auth", enforcementAttempts: 0, toolCalled: false, awaitingAgentTurn: false };
@@ -1255,8 +1276,7 @@ test("watchdog stale requested handoff cleanup emits a visible context diagnosti
 	assert.equal(state.pendingRequestedHandoff, null);
 	assert.equal(notifications[0].level, "warning");
 	assert.match(notifications[0].message, /did not call the handoff tool/);
-	assert.equal(pi.sentMessages[0].message.customType, "agenticoding-handoff-diagnostic");
-	assert.match(pi.sentMessages[0].message.content, /did not call the handoff tool/);
+	assert.deepEqual(pi.sentMessages, []);
 	assert.deepEqual(pi.sentUserMessages, []);
 });
 

handoff/cleanup.ts

@@ -7,10 +7,6 @@ export function buildMissingRequestedHandoffDiagnostic(direction: string): strin
 	return `Manual /handoff did not compact for direction "${direction}" because the assistant did not call the handoff tool. The temporary handoff tool activation has been cleared.`;
 }
 
-export function buildBusyRequestedHandoffDiagnostic(direction: string): string {
-	return `Manual /handoff was not queued for direction "${direction}" because the assistant is currently streaming. Retry /handoff once the assistant is idle so Pi can start a fresh turn with the handoff tool available.`;
-}
-
 export function emitHandoffDiagnostic(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
@@ -20,11 +16,6 @@ export function emitHandoffDiagnostic(
 	if (ctx.hasUI) {
 		ctx.ui.notify?.(message, level);
 	}
-	pi.sendMessage({
-		customType: "agenticoding-handoff-diagnostic",
-		content: message,
-		display: true,
-	});
 }
 
 export async function clearStaleRequestedHandoff(

handoff/command.ts

@@ -8,8 +8,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgenticodingState } from "../state.js";
 import { STATUS_KEY_HANDOFF } from "../tui.js";
-import { temporarilyActivateHandoffTool } from "./availability.js";
-import { buildBusyRequestedHandoffDiagnostic, emitHandoffDiagnostic } from "./cleanup.js";
+import { temporarilyActivateHandoffTool, updateHandoffToolAvailability } from "./availability.js";
+import { emitHandoffDiagnostic } from "./cleanup.js";
 
 export function registerHandoffCommand(pi: ExtensionAPI, state: AgenticodingState): void {
 	pi.registerCommand("handoff", {
@@ -24,9 +24,25 @@ export function registerHandoffCommand(pi: ExtensionAPI, state: AgenticodingStat
 				return;
 			}
 
-			const isIdle = typeof ctx.isIdle === "function" ? ctx.isIdle() : true;
+			let isIdle = typeof ctx.isIdle === "function" ? ctx.isIdle() : true;
 			if (!isIdle) {
-				emitHandoffDiagnostic(pi, ctx, buildBusyRequestedHandoffDiagnostic(direction), "warning");
+				if (ctx.hasUI && ctx.ui.theme) {
+					ctx.ui.setStatus?.(
+						STATUS_KEY_HANDOFF,
+						ctx.ui.theme.fg("accent", "\uD83E\uDD1D Handoff pending"),
+					);
+				}
+				if (typeof ctx.waitForIdle === "function") {
+					await ctx.waitForIdle();
+				}
+				isIdle = typeof ctx.isIdle === "function" ? ctx.isIdle() : true;
+			}
+
+			if (!isIdle) {
+				if (ctx.hasUI) {
+					ctx.ui.setStatus?.(STATUS_KEY_HANDOFF, undefined);
+					ctx.ui.notify?.("Manual /handoff is waiting for the assistant to become idle before starting a fresh handoff turn.", "warning");
+				}
 				return;
 			}
 
@@ -55,10 +71,18 @@ export function registerHandoffCommand(pi: ExtensionAPI, state: AgenticodingStat
 				);
 			}
 
-			pi.sendUserMessage(
-				prompt,
-				isIdle ? undefined : { deliverAs: "followUp" },
-			);
+			void Promise.resolve(pi.sendUserMessage(prompt)).catch(async (error) => {
+				state.pendingRequestedHandoff = null;
+				state.pendingRequestedHandoffPrompt = null;
+				if (ctx.hasUI) {
+					ctx.ui.setStatus?.(STATUS_KEY_HANDOFF, undefined);
+					ctx.ui.notify?.(
+						`Manual /handoff could not start: ${error instanceof Error ? error.message : String(error)}`,
+						"error",
+					);
+				}
+				await updateHandoffToolAvailability(pi, state, ctx);
+			});
 		},
 	});
 }