@siuver/omp-debug-mode 0.1.5 → 0.1.6

package/src/state.ts

@@ -5,12 +5,11 @@ export const DEBUG_ENTRY = "com.omp.debug-mode.state";
 export const DEBUG_CONTEXT_TYPE = "debug-mode-context";
 
 /**
- * Whose move it is. `investigating` is the agent's turn; every other stage
- * belongs to the user. `open` exists because a round that settled without
- * closing still needs a reply, and that is not the same as the reproduction
- * gate — conflating the two is what makes an unclosed round look like a pause.
+ * Whose move it is, and nothing else. There is exactly one user stage: a turn
+ * the agent has handed back is the user's regardless of how well the agent
+ * closed the round, so command legality never depends on protocol compliance.
  */
-export type Stage = "investigating" | "open" | "awaiting_evidence" | "cleaning_up";
+export type Stage = "investigating" | "user_turn" | "cleaning_up";
 
 export type EvidenceMethod = "agent_inspection" | "runtime_probe" | "user_report" | "user_artifact";
 
@@ -54,8 +53,12 @@ export interface EvidenceObservation {
 	addedAt: number;
 }
 
-/** Why a settled round is open instead of gated. Drives the `open` widget. */
-export type OpenReason = "awaiting_reply" | "probes_missing" | "unclosed";
+/**
+ * How the agent handed the turn back. This is wording and guidance only: every
+ * mode is the same `user_turn` stage and allows the same commands, so a mode
+ * the agent got wrong can never make a legitimate command illegal.
+ */
+export type HandoffMode = "reproduce" | "capture" | "question" | "incomplete";
 
 /**
  * One evidence round. Round membership is structural: everything scoped to a
@@ -70,9 +73,17 @@ export interface Round {
 	reproductionSteps: string[];
 	/** Ledger ids of probes introduced while this round was investigating. */
 	probeIds: string[];
-	/** Separate budgets: a probe nudge must not consume the closing-tag budget. */
-	nudges: { tags: number; probes: number };
-	openReason: OpenReason | null;
+	/** Separate budgets: a probe nudge must not consume the closing one. */
+	nudges: { handoff: number; probes: number };
+	/**
+	 * A reminder went out and no tool call has landed since. One reminder per
+	 * round of visible progress: a model that answers every reminder with more
+	 * prose would otherwise spend the whole budget and delay the user by three
+	 * turns to reach the same handoff.
+	 */
+	awaitingProgress: boolean;
+	/** Set while the round sits with the user; null while the agent has the turn. */
+	handoff: HandoffMode | null;
 }
 
 export interface DebugSession {
@@ -110,8 +121,9 @@ export function blankRound(index: number, runId: string | null): Round {
 		plan: null,
 		reproductionSteps: [],
 		probeIds: [],
-		nudges: { tags: 0, probes: 0 },
-		openReason: null,
+		nudges: { handoff: 0, probes: 0 },
+		awaitingProgress: false,
+		handoff: null,
 	};
 }
 
@@ -143,8 +155,19 @@ export function logFileFor(session: DebugSession, run: string | null = activeRun
 	return resolveRunLogFile(session.debugDir, run, activeRunId(session));
 }
 
+/**
+ * Every probe the ledger still finds on disk, session-wide. Instrumentation
+ * deliberately outlives the round that installed it — the methodology keeps
+ * probes in place across a fix so the verification round can reuse them — so a
+ * round-scoped count would report "nothing instrumented" on exactly the rounds
+ * that are best instrumented.
+ */
+export function liveProbeCount(session: DebugSession): number {
+	return session.probes.length;
+}
+
 /** Probes this round introduced that are still in the ledger (i.e. still on disk). */
-export function liveProbeIds(session: DebugSession, round: Round = currentRound(session)): string[] {
+export function roundProbeIds(session: DebugSession, round: Round = currentRound(session)): string[] {
 	return round.probeIds.filter(id => session.probes.some(probe => probe.id === id));
 }
 
@@ -152,6 +175,13 @@ export function declaresRuntimeProbe(round: Round): boolean {
 	return (round.plan ?? []).some(request => request.method === "runtime_probe");
 }
 
+/** The plan asks the user to report or capture something themselves. */
+export function needsUserCapture(round: Round): boolean {
+	return (round.plan ?? []).some(
+		request => request.method === "user_report" || request.method === "user_artifact",
+	);
+}
+
 /** Requests whose method is satisfied by the agent alone, so they never gate on the user. */
 export function hasNonProbeEvidence(round: Round): boolean {
 	return (round.plan ?? []).some(request => request.method !== "runtime_probe");
@@ -258,26 +288,64 @@ export function resolveRun(
 }
 
 /**
- * Keep only the newest copy of a custom-type injection. `before_agent_start`
- * re-injects a fresh blackboard every turn; `context` runs afterwards on the
- * combined history, so deleting every match would drop the copy that was just
- * added and the model would never see it.
+ * Leave the context holding exactly one, current copy of a custom-type
+ * injection: drop every stale copy and rewrite the survivor's content.
+ *
+ * Both halves are load-bearing. `before_agent_start` appends a fresh copy every
+ * prompt, so keeping all of them would grow the context without bound — but it
+ * does not fire at all when the host resumes the agent loop itself, so a turn
+ * started by a reminder or a nudge would otherwise read whatever the previous
+ * turn was told. Rewriting here, where the request is actually assembled, is
+ * the only point that no path into the model can skip.
+ *
+ * Returns null when the context already says the right thing, so an unchanged
+ * request is passed through untouched.
  */
-export function keepLatestCustomType<M extends { role?: string; customType?: string }>(
+export function syncCustomType<M extends { role?: string; customType?: string; content?: unknown }>(
 	messages: readonly M[],
 	customType: string,
-): M[] {
+	content: string | null,
+): M[] | null {
+	const isCopy = (message: M | undefined): boolean =>
+		message?.role === "custom" && message.customType === customType;
 	let last = -1;
+	let copies = 0;
+	for (let i = 0; i < messages.length; i++) {
+		if (!isCopy(messages[i])) continue;
+		last = i;
+		copies++;
+	}
+	if (last < 0) return null;
+	const rewrite = content !== null && messages[last]?.content !== content;
+	if (copies === 1 && !rewrite) return null;
+	const kept: M[] = [];
 	for (let i = 0; i < messages.length; i++) {
-		const message = messages[i];
-		if (message?.role === "custom" && message.customType === customType) last = i;
+		const message = messages[i] as M;
+		if (!isCopy(message)) {
+			kept.push(message);
+			continue;
+		}
+		if (i !== last) continue;
+		kept.push(rewrite ? ({ ...message, content } as M) : message);
 	}
-	if (last < 0) return [...messages];
-	return messages.filter((message, index) => !(message.role === "custom" && message.customType === customType && index !== last));
+	return kept;
 }
 
-const STAGES: readonly Stage[] = ["investigating", "open", "awaiting_evidence", "cleaning_up"];
-const OPEN_REASONS: readonly OpenReason[] = ["awaiting_reply", "probes_missing", "unclosed"];
+const STAGES: readonly Stage[] = ["investigating", "user_turn", "cleaning_up"];
+const HANDOFF_MODES: readonly HandoffMode[] = ["reproduce", "capture", "question", "incomplete"];
+
+/** Pre-`user_turn` stage names and the handoff each one implied. */
+const LEGACY_STAGES: Readonly<Record<string, { stage: Stage; handoff: HandoffMode | null }>> = {
+	open: { stage: "user_turn", handoff: null },
+	awaiting_evidence: { stage: "user_turn", handoff: "reproduce" },
+};
+
+/** Pre-`handoff` reasons, mapped onto the mode that carries the same guidance. */
+const LEGACY_HANDOFFS: Readonly<Record<string, HandoffMode>> = {
+	awaiting_reply: "question",
+	probes_missing: "incomplete",
+	unclosed: "incomplete",
+};
 
 function asArray<T>(value: unknown): T[] {
 	return Array.isArray(value) ? (value as T[]) : [];
@@ -287,6 +355,12 @@ function asRecord(value: unknown): Record<string, unknown> {
 	return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : {};
 }
 
+function reviveHandoff(raw: unknown): HandoffMode | null {
+	if (typeof raw !== "string") return null;
+	if (HANDOFF_MODES.includes(raw as HandoffMode)) return raw as HandoffMode;
+	return LEGACY_HANDOFFS[raw] ?? null;
+}
+
 function reviveRound(raw: unknown, fallbackIndex: number): Round {
 	const record = asRecord(raw);
 	const nudges = asRecord(record.nudges);
@@ -297,18 +371,26 @@ function reviveRound(raw: unknown, fallbackIndex: number): Round {
 		reproductionSteps: asArray<string>(record.reproductionSteps),
 		probeIds: asArray<string>(record.probeIds),
 		nudges: {
-			tags: typeof nudges.tags === "number" ? nudges.tags : 0,
-			probes: typeof nudges.probes === "number" ? nudges.probes : 0,
+			// `tags` is the pre-tool budget name, when prose was still a closure.
+			handoff: numberOr(nudges.handoff, numberOr(nudges.tags, 0)),
+			probes: numberOr(nudges.probes, 0),
 		},
-		openReason: OPEN_REASONS.includes(record.openReason as OpenReason) ? (record.openReason as OpenReason) : null,
+		// Never restored: no agent turn survives a restart, so nothing is pending.
+		awaitingProgress: false,
+		handoff: reviveHandoff(record.handoff ?? record.openReason),
 	};
 }
 
+function numberOr(value: unknown, fallback: number): number {
+	return typeof value === "number" ? value : fallback;
+}
+
 /**
- * Rebuild persisted state, tolerating the pre-`rounds` layout so a session that
- * was mid-debug across an upgrade keeps working. An unrecognised stage resolves
- * to `open`: the conservative reading is that the agent owes the user something,
- * not that the user owes a reproduction.
+ * Rebuild persisted state, tolerating the pre-`user_turn` stage names and the
+ * pre-`rounds` layout so a session that was mid-debug across an upgrade keeps
+ * working. Anything unrecognised — including a persisted `investigating`, since
+ * no agent turn survives a restore — resolves to `user_turn`, because the user
+ * must always be able to act on a restored investigation.
  */
 export function reviveState(data: unknown): DebugState {
 	const record = asRecord(data);
@@ -317,21 +399,23 @@ export function reviveState(data: unknown): DebugState {
 	const debugDir = typeof record.debugDir === "string" ? record.debugDir : null;
 	const probes = asArray<Probe>(record.probes);
 	const logCounts = asRecord(record.logCounts) as Record<string, number>;
-	const stageRaw = typeof record.stage === "string" ? record.stage : legacyStage(record.phase);
-	const stage = STAGES.includes(stageRaw as Stage) ? (stageRaw as Stage) : "open";
+	const restored = restoreStage(record);
 
 	const rounds = Array.isArray(record.rounds)
 		? record.rounds.map((round, i) => reviveRound(round, i + 1))
 		: [legacyRound(record, probes)];
+	const resolved = rounds.length > 0 ? rounds : [blankRound(1, null)];
+	const last = resolved[resolved.length - 1] as Round;
+	if (restored.stage === "user_turn" && last.handoff === null) {
+		resolved[resolved.length - 1] = { ...last, handoff: restored.handoff ?? "incomplete" };
+	}
 
 	return {
 		active: true,
-		// No agent turn survives a restore, so a persisted `investigating` stage
-		// would strand the user waiting for a turn that will never resume.
-		stage: stage === "investigating" ? "open" : stage,
+		stage: restored.stage,
 		problem,
 		debugDir,
-		rounds: rounds.length > 0 ? rounds : [blankRound(1, null)],
+		rounds: resolved,
 		probes,
 		runHistory: asArray<string>(record.runHistory),
 		logCounts,
@@ -342,7 +426,18 @@ export function reviveState(data: unknown): DebugState {
 	};
 }
 
-function legacyStage(phase: unknown): Stage {
+function restoreStage(record: Record<string, unknown>): { stage: Stage; handoff: HandoffMode | null } {
+	const raw = typeof record.stage === "string" ? record.stage : legacyPhase(record.phase);
+	const legacy = LEGACY_STAGES[raw];
+	if (legacy) return legacy;
+	// A persisted `investigating` cannot be resumed: no agent turn survives a
+	// restore, so honouring it would strand the user with every command refused.
+	if (raw !== "investigating" && STAGES.includes(raw as Stage)) return { stage: raw as Stage, handoff: null };
+	return { stage: "user_turn", handoff: null };
+}
+
+/** Collapse the original `phase` field onto the stage name it became. */
+function legacyPhase(phase: unknown): string {
 	if (phase === "waiting") return "awaiting_evidence";
 	if (phase === "cleanup") return "cleaning_up";
 	return "open";
@@ -360,11 +455,63 @@ function legacyRound(record: Record<string, unknown>, probes: readonly Probe[]):
 		plan: requests.length > 0 ? requests.map(({ round: _round, ...rest }) => rest) : null,
 		reproductionSteps: asArray<string>(record.reproductionSteps),
 		probeIds: probes.filter(probe => probe.round === index).map(probe => probe.id),
-		nudges: { tags: typeof record.gateNudges === "number" ? record.gateNudges : 0, probes: 0 },
-		openReason: null,
+		nudges: { handoff: numberOr(record.gateNudges, 0), probes: 0 },
+		awaitingProgress: false,
+		handoff: null,
 	};
 }
 
+/** The closing requirements of the current round, as observed facts. */
+export function roundFacts(session: DebugSession, round: Round = currentRound(session)): string {
+	const plan = round.plan ? `${round.plan.length} request(s)` : "MISSING";
+	const steps = round.reproductionSteps.length > 0 ? `${round.reproductionSteps.length} step(s)` : "MISSING";
+	return `evidence plan: ${plan}, reproduction steps: ${steps}, live probes: ${liveProbeCount(session)}`;
+}
+
+/**
+ * Whose turn it is and what closing the round still requires, stated to the
+ * model. The model drives these transitions, so leaving the stage out is what
+ * lets it announce a reproduction while the round is still its own.
+ */
+export function stageBriefing(session: DebugSession): string {
+	const round = currentRound(session);
+	const facts = `Round ${round.index} facts — ${roundFacts(session, round)}.`;
+	if (session.stage === "cleaning_up") {
+		return `Turn owner: AGENT (cleanup). Remove every probe, verify the ledger is empty, then summarize. ${facts}`;
+	}
+	if (session.stage === "user_turn") {
+		// Written to be true whichever way this turn started. The context is
+		// assembled before a user message is announced, so this text cannot know
+		// which case it is in — but the model can see its own transcript, so the
+		// test it is given is one it can actually apply.
+		//
+		// Three triggers land here, and only the first one is the user's: a reply,
+		// the request that follows the `hand_off_to_user` call in the same turn
+		// (a tool call never ends a turn, so this one is unavoidable), and a host
+		// continuation. The last two need the same answer, so they are described
+		// together rather than as a list of causes to match against.
+		return (
+			`Turn owner: USER. Round ${round.index} was handed back as "${round.handoff ?? "incomplete"}" and is NOT closed. ${facts} ` +
+			"The user has not run /debug-proceed. Check what started this turn before you do anything else. " +
+			"If a user message is part of it, the round is yours again: answer it, then call hand_off_to_user to " +
+			"re-close the round — never assume the earlier handoff still stands. " +
+			"If nothing in this turn came from the user, nothing has changed since the handoff: you are either " +
+			"finishing the turn in which you just called hand_off_to_user, or you were resumed by a reminder or " +
+			"another automatic continuation. Either way the user has not acted, no reproduction has run, and no new " +
+			"observation exists. Do not read logs, do not analyze, do not resume the plan. Write one short line " +
+			"addressed to the user — what to do now, and that /debug-proceed comes after they reproduce (or " +
+			"/debug-done if the bug is already fixed) — then end the turn. Never report " +
+			"that you were reminded and never restate this briefing back to them."
+		);
+	}
+	return (
+		`Turn owner: AGENT. Round ${round.index} is yours and you must close it before you stop. ${facts} ` +
+		"Close it by calling hand_off_to_user: that call is what moves the session into the user's hands. " +
+		"Prose telling the user to reproduce does not change the state, and a turn that stops without that call is " +
+		"sent straight back to you to make it."
+	);
+}
+
 export function blackboard(session: DebugSession, evidenceDescription = "(none)"): string {
 	const round = currentRound(session);
 	const probes = session.probes.map(p => `${p.id} (${p.file}, round ${p.round})`).join("\n  ") || "(none)";
@@ -372,7 +519,9 @@ export function blackboard(session: DebugSession, evidenceDescription = "(none)"
 		.map(([run, n]) => `${run}: ${n}`)
 		.join(", ") || "(none yet)";
 	return `\
-[DEBUG MODE ACTIVE — round ${round.index}]
+[DEBUG MODE ACTIVE — round ${round.index} · stage ${session.stage}]
+
+${stageBriefing(session)}
 
 Problem under investigation:
 ${session.problem}

package/src/tools.ts

@@ -1,12 +1,16 @@
-import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
-import { describeEvidence } from "./evidence";
-import { describeHypotheses, summarizeHypotheses } from "./log-files";
+import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { describeEvidence, validateEvidenceRequests } from "./evidence";
+import { type HypothesisTally, describeHypotheses, summarizeHypotheses } from "./log-files";
+import { HANDOFF_TOOL } from "./methodology";
 import { type LedgerScan, describeLedger } from "./probes";
 import {
 	type DebugState,
+	type EvidenceRequest,
 	type EvidenceView,
+	type HandoffMode,
 	activeRunId,
 	allRequests,
+	currentRound,
 	logFileFor,
 	resolveRun,
 } from "./state";
@@ -23,19 +27,185 @@ function noMatch(kind: string, id: string, available: readonly string[]): string
 	return `No ${kind} matches ${JSON.stringify(id)}. Known ${kind}s: ${list}.`;
 }
 
+/** An explicit round closure, already validated against the ledger contract. */
+export interface HandoffRequest {
+	mode: Exclude<HandoffMode, "incomplete">;
+	steps: string[];
+	plan: EvidenceRequest[] | null;
+}
+
+export type HandoffOutcome = { ok: true; summary: string } | { ok: false; error: string };
+
+/** The four tools this package registers. Named so activation can add/remove them as a set. */
+export const DEBUG_TOOL_NAMES = [
+	HANDOFF_TOOL,
+	"get_debug_logs",
+	"list_debug_probes",
+	"list_debug_evidence",
+] as const;
+
+export type DebugToolName = (typeof DEBUG_TOOL_NAMES)[number];
+
+/**
+ * The enabled-tool list that should follow debug-mode's session flag.
+ * `null` means the current set already matches, so the host must not be poked.
+ */
+export function nextActiveTools(current: readonly string[], debugActive: boolean): string[] | null {
+	const wanted: readonly string[] = DEBUG_TOOL_NAMES;
+	if (debugActive) {
+		if (wanted.every(name => current.includes(name))) return null;
+		return [...new Set([...current, ...wanted])];
+	}
+	if (wanted.every(name => !current.includes(name))) return null;
+	return current.filter(name => !wanted.includes(name));
+}
+
 export interface DebugToolDeps {
 	getState(): DebugState;
 	refreshLogCounts(): void;
 	readRunLines(run: string): string[];
 	/** Rescan the probe ledger and fold the result back into session state. */
 	syncLedger(): Promise<LedgerScan>;
+	/** Apply an explicit handoff; returns the reason when the machine refuses. */
+	handOff(request: HandoffRequest, ctx: ExtensionContext): HandoffOutcome;
+}
+
+/**
+ * Discoverable tools are removed from the top-level schema and only surfaced
+ * through tool search, so a tool the injected contract orders by name — above
+ * all the handoff, which is the only way a round reaches the user — has to be
+ * essential once it is active. `defaultInactive` keeps them out of ordinary
+ * sessions: they are registered at plugin load, but the host does not put them
+ * in the model's schema until `/debug-mode` starts (or a resumed session is
+ * already in debug mode). Both fields reached `ToolDefinition` after the
+ * version this package type-checks against, hence the spread instead of
+ * inline keys.
+ */
+const SESSION_TOOL: { loadMode?: "essential"; defaultInactive?: boolean } = {
+	loadMode: "essential",
+	defaultInactive: true,
+};
+
+/** Named so every `get_debug_logs` exit reports the same details shape. */
+interface DebugLogDetails {
+	run: string | null;
+	file: string | null;
+	count: number;
+	hypotheses?: HypothesisTally[];
+}
+
+interface RejectedCall {
+	content: { type: "text"; text: string }[];
+	isError: true;
+}
+
+/**
+ * Refuse to read logs while the round is with the user. Stated as a fact about
+ * the world rather than a permission error, because the model's mistake is
+ * believing a reproduction already ran, not believing it is allowed to look.
+ */
+function userTurnRefusal(round: number): string {
+	return (
+		`Round ${round} is still with the user and they have not run /debug-proceed, so no reproduction has run and ` +
+		"nothing has been captured since the handoff. This turn was not started by the user — it is a reminder or " +
+		"an automatic continuation. Do not analyze anything: say you are still waiting for the user and end the turn."
+	);
+}
+
+/**
+ * A refused handoff must read as a repair instruction, not as a failure: the
+ * agent still holds the turn and can fix the call before it stops.
+ */
+function reject(reason: string): RejectedCall {
+	return {
+		content: [{ type: "text", text: `Handoff rejected — ${reason} Nothing was recorded; the round is still yours.` }],
+		isError: true,
+	};
 }
 
 export function registerDebugTools(pi: ExtensionAPI, deps: DebugToolDeps): void {
 	const z = pi.zod;
-	const { getState, refreshLogCounts, readRunLines, syncLedger } = deps;
+	const { getState, refreshLogCounts, readRunLines, syncLedger, handOff } = deps;
+
+	const planEntry = z.object({
+		id: z.string().describe("Request id, unique within the plan (e.g. E1)"),
+		hypothesisIds: z.array(z.string()).describe("Every hypothesis this single evidence action settles"),
+		method: z
+			.enum(["agent_inspection", "runtime_probe", "user_report", "user_artifact"])
+			.describe("Cheapest reliable method, in that priority order"),
+		title: z.string().describe("Short title for the request"),
+		rationale: z
+			.string()
+			.describe(
+				"Why this method is decisive; for user_report/user_artifact, why BOTH autonomous inspection and model-added probes cannot answer it",
+			),
+		instructions: z.array(z.string()).describe("Actionable capture/report steps"),
+		artifactHint: z.string().optional().describe("Expected file kind; only for user_artifact"),
+	});
+
+	pi.registerTool({
+		...SESSION_TOOL,
+		name: HANDOFF_TOOL,
+		label: "Hand Off To User",
+		description:
+			"Close the current debug round and hand the session to the user. This call — not your prose — is what moves debug mode into the user's turn: it renders the steps in the user's widget, makes /debug-proceed available, and records the evidence plan. Call it as the last action of every round. An invalid argument is rejected with the exact problem so you can fix it without ending the turn.",
+		parameters: z.object({
+			mode: z
+				.enum(["reproduce", "capture", "question"])
+				.describe(
+					'"reproduce": the user must run the app so the probes record. "capture": the user only supplies a report or a file. "question": you need an answer before you can plan.',
+				),
+			steps: z
+				.array(z.string())
+				.optional()
+				.describe(
+					"Numbered actions the USER performs now (reproduce, capture, restart), one per entry. Never include agent work such as installing probes, reading logs or analyzing results. Required unless mode is question.",
+				),
+			plan: z
+				.array(planEntry)
+				.optional()
+				.describe(
+					"Evidence plan covering EVERY open hypothesis. Required unless mode is question or the round already recorded a plan.",
+				),
+		}),
+		// Deliberately the cheapest tier: the call touches no file and no command,
+		// only who owns the turn. On the `write` tier an approval policy can put a
+		// prompt in front of the one action every round is required to end with,
+		// and a declined or interrupted prompt is indistinguishable from a model
+		// that never called it.
+		approval: "read",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const state = getState();
+			if (!state.active) return { content: [{ type: "text", text: INACTIVE_TEXT }], isError: true };
+			const mode = params.mode as HandoffRequest["mode"];
+			const steps = (params.steps ?? []).map(step => step.trim()).filter(step => step.length > 0);
+			if (mode !== "question" && steps.length === 0) {
+				return reject(`mode "${mode}" needs steps: list what the user does now, one action per entry.`);
+			}
+
+			let plan: EvidenceRequest[] | null = null;
+			if (params.plan !== undefined) {
+				const validation = validateEvidenceRequests(params.plan);
+				if (!validation.ok) return reject(`${validation.error}.`);
+				plan = validation.requests;
+			}
+			if (mode !== "question" && plan === null && currentRound(state).plan === null) {
+				return reject(
+					`mode "${mode}" needs plan: this round has no evidence plan yet, so nothing would link what the user captures to a hypothesis.`,
+				);
+			}
+
+			const outcome = handOff({ mode, steps, plan }, ctx);
+			if (!outcome.ok) return reject(outcome.error);
+			return {
+				content: [{ type: "text", text: outcome.summary }],
+				details: { mode, steps: steps.length, plan: plan?.length ?? 0 },
+			};
+		},
+	});
 
 	pi.registerTool({
+		...SESSION_TOOL,
 		name: "get_debug_logs",
 		label: "Get Debug Logs",
 		description:
@@ -49,14 +219,25 @@ export function registerDebugTools(pi: ExtensionAPI, deps: DebugToolDeps): void
 		async execute(_toolCallId, params) {
 			refreshLogCounts();
 			const state = getState();
+			const noRun: DebugLogDetails = { run: null, file: null, count: 0 };
 			if (!state.active) {
-				return { content: [{ type: "text", text: INACTIVE_TEXT }], details: { run: null, file: null, count: 0 } };
+				return { content: [{ type: "text", text: INACTIVE_TEXT }], details: noRun };
+			}
+			// The round is with the user, so this turn cannot be one they started:
+			// a reply flips the stage back before any tool can run. Reading logs
+			// here would analyze a reproduction that has not happened yet.
+			if (state.stage === "user_turn") {
+				return {
+					content: [{ type: "text", text: userTurnRefusal(currentRound(state).index) }],
+					details: noRun,
+					isError: true,
+				};
 			}
 			const selection = resolveRun(params, state.runHistory, activeRunId(state), state.logCounts);
 			if (!selection.run) {
 				return {
 					content: [{ type: "text", text: `(${selection.note ?? "no debug run is available"})` }],
-					details: { run: null, file: null, count: 0 },
+					details: noRun,
 				};
 			}
 
@@ -79,14 +260,18 @@ export function registerDebugTools(pi: ExtensionAPI, deps: DebugToolDeps): void
 			const body =
 				lines.join("\n") ||
 				"(no logs captured — the instrumented path may not have executed, the build may be stale, the path may be wrong, or the file append may have failed)";
-			return {
-				content: [{ type: "text", text: header + body }],
-				details: { run, file: logFileFor(state, run), count: lines.length, hypotheses: tallies },
+			const details: DebugLogDetails = {
+				run,
+				file: logFileFor(state, run),
+				count: lines.length,
+				hypotheses: tallies,
 			};
+			return { content: [{ type: "text", text: header + body }], details };
 		},
 	});
 
 	pi.registerTool({
+		...SESSION_TOOL,
 		name: "list_debug_probes",
 		label: "List Debug Probes",
 		description:
@@ -104,6 +289,7 @@ export function registerDebugTools(pi: ExtensionAPI, deps: DebugToolDeps): void
 	});
 
 	pi.registerTool({
+		...SESSION_TOOL,
 		name: "list_debug_evidence",
 		label: "List Debug Evidence",
 		description: