pi-agenticoding/03: guard manual handoff requests

Author: grzegorznowak

CHANGELOG.md

@@ -9,9 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- 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 `handoff.automaticEnabled` raw settings support with JSON boolean values. Missing settings default to automatic handoff enabled; `false` suppresses automatic handoff guidance and blocks direct agent-initiated handoff unless an explicit `/handoff <direction>` request is pending.
 - 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 waits behind the scenes when the assistant is streaming, then enables the `handoff` tool and starts a fresh handoff turn once idle.
+- Manual `/handoff <direction>` remains available even when automatic handoff is disabled: it records the operator request, sends the handoff prompt, and lets the guarded `handoff` tool compact that requested turn.
+
+### Fixed
+
+- Queued manual `/handoff` follow-up prompts can no longer be preempted by an older agent turn's automatic handoff call before the generated user turn starts.
+- Global `handoff.automaticEnabled` saves now write through a same-directory temporary file and rename over the target, preserving the previous settings file if replacement fails.
 
 ## [0.3.0] - 2026-05-23
 
@@ -114,4 +119,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [0.3.0]: https://github.com/agenticoding/pi-agenticoding/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/agenticoding/pi-agenticoding/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/agenticoding/pi-agenticoding/releases/tag/v0.1.0
-

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 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 auto-sends `Proceed.` after successful compaction.
+Settings are read from `~/.pi/agent/settings.json` and `<project>/.pi/settings.json`, with project settings overriding global settings. When automatic handoff is disabled, handoff-call guidance is removed from normal turns and direct `handoff` tool calls are rejected unless they are satisfying an explicit operator `/handoff <direction>` request. The tool remains registered; the setting is enforced by runtime guards rather than provider-schema removal.
 
-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.
+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 prompt guidance on future fresh agent turns, while direct handoff tool calls are checked against the effective setting at execution time. Edit or remove project overrides manually.
 
 **Rule of thumb:** The notebook holds reusable learned knowledge. Handoff carries the remaining situational context.
 

agenticoding.test.ts

@@ -1,7 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgenticodingState } from "../state.js";
 import { STATUS_KEY_HANDOFF } from "../tui.js";
-import { updateHandoffToolAvailability } from "./availability.js";
 
 export function emitHandoffDiagnostic(
 	pi: ExtensionAPI,
@@ -14,8 +13,17 @@ export function emitHandoffDiagnostic(
 	}
 }
 
+export function clearPendingHandoffCompaction(state: AgenticodingState, ctx: ExtensionContext): void {
+	state.pendingHandoff = null;
+	state.pendingRequestedHandoff = null;
+	state.pendingRequestedHandoffPrompt = null;
+	if (ctx.hasUI) {
+		ctx.ui.setStatus?.(STATUS_KEY_HANDOFF, undefined);
+	}
+}
+
 export async function clearStaleRequestedHandoff(
-	pi: ExtensionAPI,
+	_pi: ExtensionAPI,
 	state: AgenticodingState,
 	ctx: ExtensionContext,
 ): Promise<void> {
@@ -28,5 +36,4 @@ export async function clearStaleRequestedHandoff(
 	if (ctx.hasUI) {
 		ctx.ui.setStatus?.(STATUS_KEY_HANDOFF, undefined);
 	}
-	await updateHandoffToolAvailability(pi, state, ctx);
 }

handoff/availability.ts

@@ -8,14 +8,24 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgenticodingState } from "../state.js";
 import { STATUS_KEY_HANDOFF } from "../tui.js";
-import { temporarilyActivateHandoffTool, updateHandoffToolAvailability } from "./availability.js";
-import { emitHandoffDiagnostic } from "./cleanup.js";
+
+function clearPendingManualHandoffStartFailure(state: AgenticodingState, ctx: { hasUI?: boolean; ui?: { setStatus?: (key: string, status: string | undefined) => void; notify?: (message: string, level: "error") => void } }, error: unknown): void {
+	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",
+		);
+	}
+}
 
 export function registerHandoffCommand(pi: ExtensionAPI, state: AgenticodingState): void {
 	pi.registerCommand("handoff", {
 		description:
 			"Ask the LLM to draft a handoff brief that completes the picture from " +
-			"your direction, then perform the handoff manually.",
+			"your direction, then perform the requested handoff.",
 
 		handler: async (args, ctx) => {
 			const direction = args.trim();
@@ -24,44 +34,14 @@ export function registerHandoffCommand(pi: ExtensionAPI, state: AgenticodingStat
 				return;
 			}
 
-			let isIdle = typeof ctx.isIdle === "function" ? ctx.isIdle() : true;
-			if (!isIdle) {
-				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;
-			}
-
-			const prompt = `Handoff direction: ${direction}\n\nPrepare a handoff in the current session. First, save any durable reusable knowledge that aligns with the direction above to the notebook: findings worth keeping, constraints discovered, decisions made, or other grounding future contexts will need. Then draft a concise but sufficiently detailed handoff brief capturing only the remaining situational context: current state, blockers, unresolved questions, failed paths worth avoiding, and next steps. The next context will read the notebook on demand, so do not duplicate notebook content in the brief. Use any structure that makes the next work unambiguous. Reference notebook pages by name when relevant. After drafting the brief, you must call the \`handoff\` tool with the brief as its task so the session actually compacts. Do not answer with only prose; if the \`handoff\` tool is unavailable, say that manual handoff cannot compact because the handoff tool is unavailable.`;
+			const prompt = `Handoff direction: ${direction}\n\nPrepare a handoff in the current session. First, save any durable reusable knowledge that aligns with the direction above to the notebook: findings worth keeping, constraints discovered, decisions made, or other grounding future contexts will need. Then draft a concise but sufficiently detailed handoff brief capturing only the remaining situational context: current state, blockers, unresolved questions, failed paths worth avoiding, and next steps. The next context will read the notebook on demand, so do not duplicate notebook content in the brief. Use any structure that makes the next work unambiguous. Reference notebook pages by name when relevant. After drafting the brief, you must call the \`handoff\` tool with the brief as its task so the session actually compacts. Do not answer with only prose.`;
 			state.pendingRequestedHandoff = {
 				direction,
 				enforcementAttempts: 0,
 				toolCalled: false,
 				awaitingAgentTurn: true,
 			};
 			state.pendingRequestedHandoffPrompt = prompt;
-			const activated = temporarilyActivateHandoffTool(pi);
-			if (!activated) {
-				state.pendingRequestedHandoff = null;
-				state.pendingRequestedHandoffPrompt = null;
-				const message = "Manual /handoff cannot compact because the handoff tool could not be activated for the next agent turn.";
-				emitHandoffDiagnostic(pi, ctx, message, "error");
-				return;
-			}
 
 			// Show live progress indicator in footer
 			if (ctx.hasUI && ctx.ui.theme) {
@@ -71,18 +51,14 @@ export function registerHandoffCommand(pi: ExtensionAPI, state: AgenticodingStat
 				);
 			}
 
-			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);
-			});
+			const isIdle = typeof ctx.isIdle === "function" ? ctx.isIdle() : true;
+			try {
+				void Promise.resolve(pi.sendUserMessage(prompt, isIdle ? undefined : { deliverAs: "followUp" })).catch((error) => {
+					clearPendingManualHandoffStartFailure(state, ctx, error);
+				});
+			} catch (error) {
+				clearPendingManualHandoffStartFailure(state, ctx, error);
+			}
 		},
 	});
 }

handoff/cleanup.ts

@@ -9,7 +9,6 @@ import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-wor
 import type { AgenticodingState } from "../state.js";
 import { clearActiveNotebookTopic } from "../notebook/topic.js";
 import { STATUS_KEY_HANDOFF } from "../tui.js";
-import { updateHandoffToolAvailability } from "./availability.js";
 
 function getImpossibleKeptId(branchEntries: SessionEntry[]): string {
 	const leaf = branchEntries[branchEntries.length - 1];
@@ -32,7 +31,6 @@ export function registerHandoffCompaction(pi: ExtensionAPI, state: AgenticodingS
 		if (ctx.hasUI) {
 			ctx.ui.setStatus(STATUS_KEY_HANDOFF, undefined);
 		}
-		await updateHandoffToolAvailability(pi, state, ctx);
 
 		return {
 			compaction: {

handoff/command.ts

@@ -12,8 +12,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { AgenticodingState } from "../state.js";
-import { STATUS_KEY_HANDOFF } from "../tui.js";
-import { updateHandoffToolAvailability } from "./availability.js";
+import { resolveHandoffAutomaticAvailability } from "../settings.js";
+import { clearPendingHandoffCompaction } from "./cleanup.js";
 
 /**
  * Build the enriched task that becomes the compaction summary.
@@ -47,42 +47,30 @@ export function registerHandoffTool(
 		name: "handoff",
 		label: "Handoff",
 		description:
-			"Replace the active context with a compact task brief at the end of " +
-			"the current turn while keeping full history in the session file. Handoff clears the active notebook topic so the next clean context can assign a fresh one.\n\n" +
-			"WHEN TO USE:\n" +
-			"  1. Context past ~30% and the current job is no longer cleanly " +
-			"represented near the front of attention.\n" +
-			"  2. Context is filled with mechanics irrelevant to what comes " +
-			"next (research traces, planning deliberation, dead ends).\n" +
-			"  3. The current job is complete and a new distinct task starts.\n\n" +
-			"Rule: one context, one job. When the job changes, call handoff.\n\n" +
-			"AFTER HANDOFF the LLM sees:\n" +
-			"  • System prompt + context primer\n" +
-			"  • The handoff task — the distilled next work at the top of context\n" +
-			"  • All notebook pages — durable grounding accessible via notebook_read / notebook_index",
-
-		promptSnippet: "Pivot to a new job via deliberate handoff compaction",
-		promptGuidelines: [
-			"Before handoff, promote any missing durable grounding knowledge that the next context will need to the notebook. " +
-				"Then draft a concise but sufficiently detailed brief with the distilled next task and immediate starting state for the next clean context. The active notebook topic will reset after handoff, so the next context should assign a fresh topic from the brief or user direction.",
-		],
+			"Performs authorized context compaction with a supplied task brief. " +
+			"Availability is enforced at execution time by extension state and settings.",
 
 		executionMode: "sequential",
 
 		parameters: Type.Object({
 			task: Type.String({
 				description:
-					"What to do next. A concise but sufficiently detailed handoff brief. " +
-					"This becomes the FIRST thing the LLM sees after handoff. Capture the distilled next task, " +
-					"immediate starting state, blockers, failed paths worth avoiding, and relevant notebook page names. " +
-					"The notebook is the long-term grounding store; this brief should carry only the remaining situational context.",
+					"Task brief to place at the start of the next compacted context when this handoff request is authorized.",
 			}),
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const availability = await updateHandoffToolAvailability(pi, state, ctx);
+			const availability = await resolveHandoffAutomaticAvailability(ctx);
 			const manualRequest = state.pendingRequestedHandoff;
-			if (!availability.automaticEnabled && !manualRequest) {
+			const awaitingManualRequest = manualRequest?.awaitingAgentTurn === true;
+			const activeManualRequest = manualRequest?.awaitingAgentTurn === false ? manualRequest : null;
+			if (awaitingManualRequest) {
+				return {
+					content: [{ type: "text", text: "A manual /handoff request is queued, but its generated user turn has not started yet. No compaction was started." }],
+					details: { automaticEnabled: availability.automaticEnabled, manualRequest: "awaiting_agent_turn" },
+				};
+			}
+			if (!availability.automaticEnabled && !activeManualRequest) {
 				if (ctx.hasUI) {
 					ctx.ui.notify("Automatic handoff is disabled by handoff.automaticEnabled=false; use the explicit /handoff <direction> command to request a manual handoff.", "warning");
 				}
@@ -94,23 +82,22 @@ export function registerHandoffTool(
 
 			const enrichedTask = buildEnrichedTask(params.task);
 			state.pendingHandoff = { task: enrichedTask, source: "tool" };
-			if (manualRequest) {
-				manualRequest.toolCalled = true;
+			if (activeManualRequest) {
+				activeManualRequest.toolCalled = true;
+			}
+			try {
+				ctx.compact({
+					onComplete: () => {
+						pi.sendUserMessage("Proceed.");
+					},
+					onError: () => {
+						clearPendingHandoffCompaction(state, ctx);
+					},
+				});
+			} catch (error) {
+				clearPendingHandoffCompaction(state, ctx);
+				throw error;
 			}
-			ctx.compact({
-				onComplete: () => {
-					pi.sendUserMessage("Proceed.");
-				},
-				onError: () => {
-					state.pendingHandoff = null;
-					state.pendingRequestedHandoff = null;
-					state.pendingRequestedHandoffPrompt = null;
-					if (ctx.hasUI) {
-						ctx.ui.setStatus(STATUS_KEY_HANDOFF, undefined);
-					}
-					void updateHandoffToolAvailability(pi, state, ctx);
-				},
-			});
 
 			return {
 				content: [{ type: "text", text: "Handoff started." }],