@grrrck/pi-clear 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-10-30
+
+### Added
+
+- `/hand-off` asks **who writes the hand-off prompt** before it picks the destination model: *This agent — full context and tools* (the existing behavior, first in the list so Enter keeps it), *Fresh pass — current model*, or *Fresh pass — another model…*.
+- A **fresh pass** writer: one out-of-band `modelRegistry.complete()` call over a minimal reconstruction of the conversation (user text, assistant text, one-line tool-call hints, file-operation footer; no tool output, no thinking) that can use a cheap model and does not inherit the session's context window. It has no tool access.
+- Fresh-pass transcript budget keeps the opening message and the newest turns, elides the middle with a `[... <n> turns omitted — <k> chars ...]` marker, and notifies how much was dropped. Default `200000` characters; `0` disables it.
+- The fresh pass asks for the writer model's thinking level, with the provider default preselected; models without reasoning controls skip the dialog. A standing preference for it comes from `handoff.summarizerThinkingLevel` in the config file.
+- Command flags `--fresh` and `--live`: parsed off the front of the command args, with the rest still pre-filling the steering editor. Passing both is refused before any dialog. There is no command-arg model flag — the model that writes the prompt comes from the config file or the picker.
+- Optional settings in `<agent-dir>/pi-clear.json` (`handoff.summarizerModel`, `handoff.askSummarizerModel`, `handoff.summarizerThinkingLevel`, `handoff.maxSourceChars`), read once per session; a malformed file warns and is ignored.
+- CLI flags `--hand-off-summarizer=<provider/model>` and `--hand-off-max-source-chars=<n>`.
+- Every hand-off prompt, from either writer, now starts with a provenance comment naming the source session: `<!-- Handed off from pi session <id> -->`. It is added by the extension after the prompt is written, so the writing model cannot reword it.
+- `scripts/minimal-transcript.test.mjs`: offline tests for the fresh-pass serializer, budget, file lists, provenance, and command-arg parsing.
+- `scripts/fresh-pass-flow.test.mjs`: offline tests for the whole `/hand-off` flow with mocked pi APIs — both writers, the writer thinking picker and its config preference, trimming, rejection, and the flag conflict.
+
+### Changed
+
+- `scripts/rpc-handoff-smoke-test.py` scripts the new writer picker and adds a `/hand-off --fresh` scenario that asserts no agent turn starts and that the provenance comment carries the previous session id.
+
 ## [0.3.1] - 2026-10-27
 
 ### Fixed

package/README.md

@@ -3,7 +3,7 @@
 A [pi](https://github.com/earendil-works/pi) extension with two commands:
 
 - `/clear` — start a fresh session **without losing your model**
-- `/hand-off` — hand the conversation to another model with a prompt written by the current agent
+- `/hand-off` — hand the conversation to another model with a prompt written by the current agent, or by a cheap one-off "fresh pass"
 
 ## Why?
 
@@ -29,7 +29,7 @@ pi -e npm:@grrrck/pi-clear
 
 ```text
 /clear
-/hand-off [steering instructions]
+/hand-off [--fresh | --live] [steering instructions]
 ```
 
 ## `/clear` behavior
@@ -48,17 +48,77 @@ Because the model is applied with `pi.setModel()`, it's recorded in the new sess
 
 When `/hand-off` runs, the extension:
 
+0. **chooses who writes the hand-off prompt** — see [Choosing the writer](#choosing-the-writer). The picker is skipped when `--fresh` or `--live` was passed
 1. waits for the agent to become idle if needed
-2. opens a model picker, then a thinking level picker, then a steering editor pre-filled with any text you typed after `/hand-off`. Defaults are sensible: the current model and thinking level are preselected, so pressing Enter at each step keeps them. The model picker respects your session's model scoping (`--models` / `enabledModels`, the same set `/scoped-models` shows) and offers a Tab toggle between scoped and all models. In non-TUI modes it falls back to plain dialogs: the scoped list when configured, otherwise a two-level provider → model pick so the dialog never floods the screen
-3. sends the current agent a message asking it to write its **next message as the hand-off prompt** — instructions to the next agent, with no preamble or postamble
-4. captures that final assistant message, starts a new session, applies the model and thinking level you picked, and inserts the hand-off prompt into the editor via `ctx.ui.setEditorText()`
+2. opens a model picker, then a thinking level picker, then a steering editor pre-filled with any text you typed after `/hand-off` (and its flags). Defaults are sensible: the current model and thinking level are preselected, so pressing Enter at each step keeps them. The model picker respects your session's model scoping (`--models` / `enabledModels`, the same set `/scoped-models` shows) and offers a Tab toggle between scoped and all models. In non-TUI modes it falls back to plain dialogs: the scoped list when configured, otherwise a two-level provider → model pick so the dialog never floods the screen
+3. writes the hand-off prompt with the chosen writer — the live agent, or a single off-screen model call over a minimal reconstruction of the conversation
+4. prepends a provenance comment naming the source session, starts a new session, applies the model and thinking level you picked, and inserts the prompt into the editor via `ctx.ui.setEditorText()`
 5. stops there: the prompt sits in the editor for you to review, edit, and submit yourself
 
-Cancelling any dialog aborts the hand-off before anything is sent to the agent. If the agent doesn't produce a hand-off prompt, the extension stays in the current session and reports an error.
+Cancelling any dialog aborts the hand-off before anything is sent. If the writer doesn't produce a prompt, the extension stays in the current session and reports why.
 
-The `/hand-off` request is recorded in the current session's transcript, and the hand-off prompt sits in the new session's editor — it becomes the first user message once you review and submit it.
+On the live-agent path the request itself is recorded in the current session's transcript; either way, the hand-off prompt sits in the new session's editor — it becomes the first user message once you review and submit it.
 
-Two limitations worth knowing: if you queue another message while the agent is writing the hand-off prompt, the capture may pick up the wrong response — avoid queueing during generation. And `/clear` and `/hand-off` guard against running at the same time.
+Two limitations worth knowing: on the live-agent path, if you queue another message while the agent is writing the hand-off prompt, the capture may pick up the wrong response — avoid queueing during generation. And `/clear` and `/hand-off` guard against running at the same time.
+
+### Choosing the writer
+
+There is deliberately no configured default: which writer to use depends on the conversation in front of you, so `/hand-off` asks every time.
+
+| Writer | How it writes the prompt |
+|---|---|
+| **This agent — full context and tools** (first, so Enter keeps the old behavior) | The current agent writes its next message as the hand-off prompt. It sees the whole transcript and keeps its tools. |
+| **Fresh pass — current model** | One out-of-band `modelRegistry.complete()` call over a *minimal reconstruction* of the conversation: your messages, the assistant's visible text, and one-line hints for tool calls. No tool output, no thinking, and a head+tail character budget. **No tool access.** |
+| **Fresh pass — another model…** | Same, but you pick the model that writes the prompt first (a cheap, fast model is a good choice). |
+
+The fresh pass exists because the live agent's prompt inherits the session's whole context window: an old or long conversation may no longer fit, and a session whose model lost auth can still be handed off. Because it never reads tool output, it is told to have the next agent verify anything it cannot see in the transcript.
+
+When the writer model supports reasoning, the fresh pass also asks for its **thinking level**, with **provider default** preselected — so pressing Enter passes straight through. Set a standing preference with `handoff.summarizerThinkingLevel` in the config file; the picker then preselects that level instead, and the level is passed to the model as `reasoning`. Models without reasoning controls skip the dialog entirely.
+
+Fresh pass flags and limits:
+
+- `--fresh` skips the writer picker and uses the fresh pass; `--live` skips it and uses the current agent. Passing both is refused before any dialog opens.
+- There is no command-arg model flag: if you want a specific model to write the prompt, set it in the [config file](#configuration) (or pick it from the menu).
+- The source is the post-compaction view of the session, so a compacted conversation is summarized from its summary rather than from nothing.
+- Trimming keeps the opening message, the newest turns, and a contiguous run after the opening message; the middle is replaced by `[... <n> turns omitted — <k> chars ...]` and you get a notification saying how much was dropped. Raise the budget with the settings below if that happens.
+
+### Session provenance
+
+Every hand-off prompt (from either writer) starts with a comment naming the session it came from:
+
+```markdown
+<!-- Handed off from pi session 01a18da2-4eff-73b9-846d-5fd4c156e52e -->
+```
+
+It's a comment, so it doesn't read as part of the task and stays visible in the editor for you to check. The extension adds it after the prompt is written, so the writing model can't reword or drop it.
+
+## Configuration
+
+Optional settings live in `<agent-dir>/pi-clear.json` (`~/.pi/agent`, or `$PI_CODING_AGENT_DIR`), read once per session:
+
+```json
+{
+  "handoff": {
+    "summarizerModel": "anthropic/claude-haiku-4-5",
+    "askSummarizerModel": true,
+    "summarizerThinkingLevel": "low",
+    "maxSourceChars": 200000
+  }
+}
+```
+
+- `summarizerModel` — preselected in the writer-model picker, and offered as its own `Fresh pass — <model>` entry in the writer picker.
+- `askSummarizerModel: false` — with `summarizerModel` set, skip the writer-model picker entirely and always use that model.
+- `summarizerThinkingLevel` — preselected in the writer's thinking-level picker: `"default"` (or `"off"`) for the provider default, otherwise `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. The dialog stays available either way.
+- `maxSourceChars` — characters of conversation sent to the fresh pass (default `200000`, about 50k tokens). `0` disables the budget.
+
+A malformed file is reported as a warning and ignored. The same knobs are available per pi launch as CLI flags:
+
+```sh
+pi --hand-off-summarizer=anthropic/claude-haiku-4-5 --hand-off-max-source-chars=400000
+```
+
+Precedence: pi CLI flag > config file > built-in default. On the command line, only the writer choice (`--fresh` / `--live`) is available — a model ID belongs in the config file or the picker.
 
 ## Notes
 
@@ -70,7 +130,9 @@ Two limitations worth knowing: if you queue another message while the agent is w
 
 pi tears down the current runtime when a session is replaced, and extension instances are recreated for the new session. Session-bound objects can't be reused across that boundary, and the post-switch context has no model setter — but the replacement happens within the same process. So both commands capture state as plain data in a `globalThis` property, and the new session's extension instance consumes it on `session_start` (reason `new`) and applies it with `pi.setModel()` (plus `ctx.ui.setEditorText()` for the hand-off prompt). The handoff is consumed exactly once, so it can never leak into a later session.
 
-`/hand-off` captures the agent's response by watching the `agent_end` event while the hand-off request is in flight, using per-instance state that dies with the session — only the final payload crosses into the new session via `globalThis`.
+`/hand-off` captures the live agent's response by watching the `agent_end` event while the hand-off request is in flight, using per-instance state that dies with the session — only the final payload crosses into the new session via `globalThis`.
+
+The fresh pass never sends a message to the agent at all: it calls `ctx.modelRegistry.complete()` once with a system prompt and a single user message built from `buildSessionProjection().messages`, runs the reply through the same validation as the live path (`stopReason === "stop"`, non-empty, surrounding fences stripped), and carries the result across the same `globalThis` handoff.
 
 ## Development
 
@@ -80,14 +142,17 @@ Load the extension directly for local testing:
 pi -e ./index.ts
 ```
 
-There are also RPC smoke tests that verify the behavior end-to-end by starting pi in RPC mode:
+There are also smoke tests that verify the behavior end-to-end by starting pi in RPC mode:
 
 ```sh
 python3 scripts/rpc-smoke-test.py          # /clear keeps model + thinking level
-python3 scripts/rpc-handoff-smoke-test.py  # /hand-off full flow, dialogs included
+python3 scripts/rpc-handoff-smoke-test.py  # /hand-off, both writers, dialogs included
+node --test scripts/model-picker.test.mjs          # offline: model picker behavior
+node --test scripts/minimal-transcript.test.mjs    # offline: fresh-pass transcript + budget
+node --test scripts/fresh-pass-flow.test.mjs       # offline: /hand-off flow, both writers
 ```
 
-Both require at least two models with configured auth.
+The RPC smoke tests require at least two models with configured auth, and they make **real, billed model requests**. The `node --test` scripts need neither.
 
 ## Related extensions
 

package/index.ts

@@ -15,17 +15,32 @@
  *
  * `/hand-off`: hand the conversation to another model.
  *
- * 1. The user runs `/hand-off` (optionally with steering text after it).
- * 2. A dialog flow collects the destination model and thinking level, then
- *    opens an editor pre-filled with the steering text.
- * 3. The extension sends the current agent a custom message asking it to
- *    write its next message as a hand-off prompt for the next model — no
- *    preamble, no postamble.
- * 4. When the run ends, the final assistant message is captured, the session
- *    is replaced, the chosen model and thinking level are applied, and the
- *    hand-off prompt is inserted into the editor.
+ * 1. The user runs `/hand-off`, optionally with `--fresh` or `--live` and
+ *    steering text after them.
+ * 2. A dialog flow asks who writes the hand-off prompt, then collects the
+ *    destination model and thinking level, then opens an editor pre-filled
+ *    with the remaining command args.
+ * 3. The hand-off prompt is written by one of two writers:
+ *    - the **live agent** (default, first in the picker): the extension sends
+ *      the current agent a custom message asking it to write its next message
+ *      as the hand-off prompt, and `agent_end` captures the final assistant
+ *      message. It sees the whole transcript and keeps tool access.
+ *    - the **fresh pass**: a single out-of-band `modelRegistry.complete()`
+ *      call over a *minimal reconstruction* of the conversation (no tool
+ *      output, no thinking, head+tail budget), so long or stale sessions can
+ *      still be handed off, and a cheap model can do the writing. It has no
+ *      tool access, and its thinking level is chosen separately (provider
+ *      default preselected).
+ * 4. The extension prepends a provenance comment naming the source session
+ *    (both writers), replaces the session, applies the chosen model and
+ *    thinking level, and inserts the prompt into the editor.
  * 5. The user reviews, edits, and submits the prompt themselves.
  *
+ * Settings live in `<agent-dir>/pi-clear.json` (read once per
+ * `session_start`); CLI flags `--hand-off-max-source-chars` and
+ * `--hand-off-summarizer` override the file. Without a configured writer
+ * model, `/hand-off` just asks: there is no command-arg model flag.
+ *
  * Mechanism:
  *   Both commands capture state as plain data into a `globalThis` property.
  *   Session replacement (`ctx.newSession()`) tears down the current runtime
@@ -40,11 +55,15 @@
  *   into the editor with `ctx.ui.setEditorText()`.
  */
 
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import type {
 	ExtensionAPI,
+	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { BorderedLoader, DynamicBorder, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Container, fuzzyFilter, Input, SelectList, Text, type SelectItem } from "@earendil-works/pi-tui";
 
 // Model and thinking-level types, derived from the API surface because the
@@ -87,6 +106,14 @@ const THINKING_LEVELS: ThinkingLevel[] = [
 
 const HANDOFF_CUSTOM_TYPE = "pi-clear:hand-off-request";
 
+/**
+ * Reasoning levels offered for the fresh pass. "off" is not offered: it means
+ * the same thing as the provider default here, because the option is omitted
+ * either way.
+ */
+const WRITER_REASONING_LEVELS: ThinkingLevel[] = THINKING_LEVELS.filter((level) => level !== "off");
+const WRITER_DEFAULT_REASONING_LABEL = "provider default";
+
 function sameModel(a: AnyModel | undefined, b: AnyModel | undefined): boolean {
 	return !!a && !!b && a.provider === b.provider && a.id === b.id;
 }
@@ -120,6 +147,14 @@ interface PickedModel {
 	thinkingLevel?: ThinkingLevel;
 }
 
+/** How the model pickers label themselves and which model they treat as current. */
+interface ModelPickerOptions {
+	/** Preselected model; defaults to the session's model. */
+	current?: AnyModel;
+	title?: string;
+	providerTitle?: string;
+}
+
 async function selectModel(
 	ctx: ExtensionContext,
 	models: AnyModel[],
@@ -151,20 +186,54 @@ async function selectThinkingLevel(ctx: ExtensionContext): Promise<ThinkingLevel
 	return index === -1 ? undefined : ordered[index];
 }
 
+/**
+ * Thinking level for the fresh pass writer. The provider default comes first and
+ * is preselected unless the config file pins a level, so pressing Enter keeps
+ * today's behavior and the dialog is a no-op for most runs.
+ */
+async function selectWriterReasoningLevel(
+	ctx: ExtensionContext,
+	preselected: ThinkingLevel | undefined,
+): Promise<{ reasoning?: ThinkingLevel } | undefined> {
+	const ordered = preselected
+		? [preselected, ...WRITER_REASONING_LEVELS.filter((level) => level !== preselected)]
+		: [...WRITER_REASONING_LEVELS];
+	const options: Array<{ reasoning?: ThinkingLevel; label: string }> = ordered.map((level) => ({
+		reasoning: level,
+		label: `${level}${level === preselected ? "  (current)" : ""}`,
+	}));
+	if (preselected) {
+		options.push({ label: WRITER_DEFAULT_REASONING_LABEL });
+	} else {
+		options.unshift({ label: `${WRITER_DEFAULT_REASONING_LABEL}  (current)` });
+	}
+
+	const labels = options.map((option) => option.label);
+	const chosen = await ctx.ui.select("Thinking level for the hand-off writer", labels);
+	if (chosen === undefined) return undefined;
+	const index = labelIndex(chosen, labels);
+	return index === -1 ? undefined : { reasoning: options[index].reasoning };
+}
+
 /**
  * Non-interactive fallback (RPC mode has no custom components): scoped
  * models in one dialog when scoping is configured, otherwise a two-level
  * provider → model pick over the auth-configured catalogue.
  */
-async function pickTargetModelFallback(ctx: ExtensionContext): Promise<PickedModel | undefined> {
-	const current = ctx.model;
+async function pickTargetModelFallback(
+	ctx: ExtensionContext,
+	options: ModelPickerOptions = {},
+): Promise<PickedModel | undefined> {
+	const current = options.current ?? ctx.model;
+	const title = options.title ?? "Hand off to model";
+	const providerTitle = options.providerTitle ?? "Hand off to provider";
 	const scoped = ctx.scopedModels.map((scoped) => scoped.model);
 
 	if (scoped.length > 0) {
 		// Keep the current model selectable and preselected even when scoping
 		// excludes it.
 		const models = current && !scoped.some((m) => sameModel(m, current)) ? [current, ...scoped] : scoped;
-		const model = await selectModel(ctx, models, "Hand off to model", current);
+		const model = await selectModel(ctx, models, title, current);
 		return model ? { model } : undefined;
 	}
 
@@ -190,13 +259,13 @@ async function pickTargetModelFallback(ctx: ExtensionContext): Promise<PickedMod
 
 	const providerLabels = providers.map((p) => `${p}  (${byProvider.get(p)!.length} models)`);
 	const providerChoice =
-		providers.length === 1 ? providerLabels[0] : await ctx.ui.select("Hand off to provider", providerLabels);
+		providers.length === 1 ? providerLabels[0] : await ctx.ui.select(providerTitle, providerLabels);
 	if (providerChoice === undefined) return undefined;
 	const providerIndex = labelIndex(providerChoice, providerLabels);
 	if (providerIndex === -1) return undefined;
 	const providerName = providers[providerIndex];
 
-	const model = await selectModel(ctx, byProvider.get(providerName) ?? [], "Hand off to model", current);
+	const model = await selectModel(ctx, byProvider.get(providerName) ?? [], title, current);
 	return model ? { model } : undefined;
 }
 
@@ -204,8 +273,12 @@ async function pickTargetModelFallback(ctx: ExtensionContext): Promise<PickedMod
  * `/model`-style model picker (TUI mode only): a searchable list with Tab to
  * toggle between the session's scoped models and the full catalogue.
  */
-async function pickTargetModelTui(ctx: ExtensionContext): Promise<PickedModel | undefined> {
-	const current = ctx.model;
+async function pickTargetModelTui(
+	ctx: ExtensionContext,
+	options: ModelPickerOptions = {},
+): Promise<PickedModel | undefined> {
+	const current = options.current ?? ctx.model;
+	const title = options.title ?? "Hand off to model";
 	const allEntries: PickedModel[] = ctx.modelRegistry.getAvailable().map((model) => ({ model }));
 	if (allEntries.length === 0) {
 		ctx.ui.notify("No models available to hand off to", "error");
@@ -279,7 +352,7 @@ async function pickTargetModelTui(ctx: ExtensionContext): Promise<PickedModel |
 				theme.fg(
 					"accent",
 					theme.bold(
-						`Hand off to model — ${scope === "scoped" ? `scoped (${scopedEntries.length})` : `all (${allEntries.length})`}`,
+						`${title} — ${scope === "scoped" ? `scoped (${scopedEntries.length})` : `all (${allEntries.length})`}`,
 					),
 				),
 			);
@@ -331,12 +404,17 @@ async function pickTargetModelTui(ctx: ExtensionContext): Promise<PickedModel |
  *
  * TUI mode gets a `/model`-style searchable picker with Tab to toggle
  * between scoped and all models; other modes fall back to plain dialogs.
+ * The same picker also chooses the fresh pass's writer model, with the
+ * title and preselected model supplied by the caller.
  */
-async function pickTargetModel(ctx: ExtensionContext): Promise<PickedModel | undefined> {
+async function pickTargetModel(
+	ctx: ExtensionContext,
+	options: ModelPickerOptions = {},
+): Promise<PickedModel | undefined> {
 	if (ctx.mode === "tui") {
-		return pickTargetModelTui(ctx);
+		return pickTargetModelTui(ctx, options);
 	}
-	return pickTargetModelFallback(ctx);
+	return pickTargetModelFallback(ctx, options);
 }
 
 /** Extract the text content of an agent message, ignoring thinking blocks and tool calls. */
@@ -371,12 +449,679 @@ function buildHandoffRequest(steering: string): string {
 	return lines.join("\n");
 }
 
+// ============================================================================
+// Fresh pass: one out-of-band model call over a minimal reconstruction
+// ============================================================================
+
+const HANDOFF_SYSTEM_PROMPT = `You are a context transfer assistant. You will receive a minimal reconstruction of a long conversation between a user and an AI agent, and you must write the hand-off message that starts the next session.
+
+Do not continue the conversation. Do not answer questions in it.
+
+The reconstruction is lossy: tool output, thinking, and file contents are omitted, and a middle section may be elided. Do not assert file contents or the state of the working tree from memory — when something cannot be verified from the transcript, tell the next agent to verify it.`;
+
+const DEFAULT_COVERAGE =
+	"Cover the conversation thoroughly: the current task and goal, what has been done so far (with concrete file paths, commands, and decisions), and exactly what to do next.";
+
+/** Characters of conversation sent to the fresh pass (~50k tokens at 200k). */
+const DEFAULT_MAX_SOURCE_CHARS = 200_000;
+/** Share of the budget kept from the newest end of the conversation. */
+const TAIL_SOURCE_SHARE = 0.6;
+/** Share of the budget kept contiguously after the opening message. */
+const HEAD_SOURCE_SHARE = 0.4;
+const USER_MESSAGE_MAX_CHARS = 8_000;
+const ASSISTANT_MESSAGE_MAX_CHARS = 4_000;
+const SUMMARY_MAX_CHARS = 8_000;
+const NOTE_MAX_CHARS = 2_000;
+const HINT_MAX_CHARS = 200;
+
+/** A projected session message, viewed loosely: only fields the serializer reads. */
+interface TranscriptSource {
+	role?: string;
+	content?: unknown;
+	customType?: string;
+	summary?: string;
+	command?: string;
+	/** `!!` bash executions: never sent to a model, so never sent to the writer. */
+	excludeFromContext?: boolean;
+}
+
+interface ContentBlock {
+	type?: string;
+	text?: string;
+	name?: string;
+	arguments?: unknown;
+}
+
+/** One rendered unit of the minimal transcript; the budget never splits a block. */
+interface TranscriptBlock {
+	text: string;
+	/** Marks the opening user message, which the budget always keeps. */
+	anchor?: boolean;
+}
+
+interface TranscriptResult {
+	text: string;
+	/** Blocks dropped from the middle of the conversation, 0 when nothing was dropped. */
+	omittedTurns: number;
+	/** Characters those blocks would have contributed. */
+	droppedChars: number;
+}
+
+function contentBlocks(content: unknown): ContentBlock[] {
+	if (typeof content === "string") return [{ type: "text", text: content }];
+	if (!Array.isArray(content)) return [];
+	const blocks: ContentBlock[] = [];
+	for (const block of content) {
+		if (typeof block === "object" && block !== null) blocks.push(block as ContentBlock);
+	}
+	return blocks;
+}
+
+/** Visible text only: thinking, tool calls, and images are dropped. */
+function visibleText(content: unknown): string {
+	return contentBlocks(content)
+		.filter((block) => block.type === "text" && typeof block.text === "string")
+		.map((block) => block.text!.trim())
+		.filter((text) => text.length > 0)
+		.join("\n");
+}
+
+function toolCallsOf(content: unknown): ContentBlock[] {
+	return contentBlocks(content).filter(
+		(block) => block.type === "toolCall" && typeof block.name === "string",
+	);
+}
+
+function stringArg(args: unknown, key: string): string | undefined {
+	if (typeof args !== "object" || args === null) return undefined;
+	const value = (args as Record<string, unknown>)[key];
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function firstStringArg(args: unknown): string | undefined {
+	if (typeof args !== "object" || args === null) return undefined;
+	for (const value of Object.values(args as Record<string, unknown>)) {
+		if (typeof value === "string" && value.trim()) return value.trim();
+	}
+	return undefined;
+}
+
+/** Keep both ends of an over-long text, and say how much was cut. */
+function truncateMiddle(text: string, maxChars: number): string {
+	if (maxChars <= 0 || text.length <= maxChars) return text;
+	const headChars = Math.floor(maxChars * TAIL_SOURCE_SHARE);
+	const tailChars = maxChars - headChars;
+	const removed = text.length - maxChars;
+	return `${text.slice(0, headChars)}\n[... ${removed} chars truncated ...]\n${text.slice(text.length - tailChars)}`;
+}
+
+/** One line naming a tool call and its target — never its result. */
+export function formatToolHint(name: string, args: unknown): string {
+	const path = stringArg(args, "path");
+	switch (name) {
+		case "read":
+		case "edit":
+		case "write":
+			return path ? `${name} ${path}` : name;
+		case "bash": {
+			const command = stringArg(args, "command")?.split("\n")[0].trim() ?? "";
+			return command ? `bash: ${command.slice(0, HINT_MAX_CHARS)}` : "bash";
+		}
+		case "grep": {
+			const pattern = stringArg(args, "pattern");
+			if (!pattern) return "grep";
+			return path ? `grep: /${pattern}/ in ${path}` : `grep: /${pattern}/`;
+		}
+		case "ls":
+			return path ? `ls: ${path}` : "ls";
+		case "find": {
+			const pattern = stringArg(args, "pattern");
+			if (pattern && path) return `find: ${pattern} in ${path}`;
+			if (path) return `find: ${path}`;
+			return pattern ? `find: ${pattern}` : "find";
+		}
+		default: {
+			const detail = path ?? firstStringArg(args);
+			return detail ? `tool: ${name} ${detail.slice(0, HINT_MAX_CHARS)}` : `tool: ${name}`;
+		}
+	}
+}
+
+interface FileLists {
+	readFiles: string[];
+	modifiedFiles: string[];
+}
+
+/** Same rules pi uses for compaction: read-only files, then written/edited ones. */
+function fileListsFromMessages(messages: readonly TranscriptSource[]): FileLists {
+	const read = new Set<string>();
+	const written = new Set<string>();
+	const edited = new Set<string>();
+	for (const message of messages) {
+		if (message.role !== "assistant") continue;
+		for (const call of toolCallsOf(message.content)) {
+			const path = stringArg(call.arguments, "path");
+			if (!path) continue;
+			if (call.name === "read") read.add(path);
+			else if (call.name === "write") written.add(path);
+			else if (call.name === "edit") edited.add(path);
+		}
+	}
+	const modified = new Set([...edited, ...written]);
+	return {
+		readFiles: [...read].filter((file) => !modified.has(file)).sort(),
+		modifiedFiles: [...modified].sort(),
+	};
+}
+
+function formatFileLists(lists: FileLists): string {
+	const sections: string[] = [];
+	if (lists.readFiles.length > 0) sections.push(`<read-files>\n${lists.readFiles.join("\n")}\n</read-files>`);
+	if (lists.modifiedFiles.length > 0) {
+		sections.push(`<modified-files>\n${lists.modifiedFiles.join("\n")}\n</modified-files>`);
+	}
+	return sections.join("\n\n");
+}
+
+/**
+ * Render the conversation as labelled blocks: visible text, tool-call hints,
+ * summaries, and notes. Tool results, thinking, and stale hand-off requests
+ * are dropped outright.
+ */
+export function renderTranscriptBlocks(messages: readonly TranscriptSource[]): TranscriptBlock[] {
+	const blocks: TranscriptBlock[] = [];
+	let sawUserMessage = false;
+
+	for (const message of messages) {
+		switch (message.role) {
+			case "user": {
+				const text = visibleText(message.content);
+				if (!text) break;
+				blocks.push({
+					text: `[User]: ${truncateMiddle(text, USER_MESSAGE_MAX_CHARS)}`,
+					anchor: !sawUserMessage,
+				});
+				sawUserMessage = true;
+				break;
+			}
+			case "assistant": {
+				const text = visibleText(message.content);
+				if (text) {
+					blocks.push({ text: `[Assistant]: ${truncateMiddle(text, ASSISTANT_MESSAGE_MAX_CHARS)}` });
+				}
+				const hints = toolCallsOf(message.content).map((call) => formatToolHint(call.name!, call.arguments));
+				if (hints.length > 0) blocks.push({ text: `[tools]:\n${hints.join("\n")}` });
+				break;
+			}
+			case "toolResult":
+				// Tool output never shapes the hand-off: it is the bulk of a transcript
+				// and the writer is told to have the next agent verify state itself.
+				break;
+			case "custom": {
+				if (message.customType === HANDOFF_CUSTOM_TYPE) break;
+				const text = visibleText(message.content);
+				if (text) blocks.push({ text: `[Note]: ${truncateMiddle(text, NOTE_MAX_CHARS)}` });
+				break;
+			}
+			case "compactionSummary":
+			case "branchSummary": {
+				const summary = typeof message.summary === "string" ? message.summary.trim() : "";
+				if (summary) {
+					blocks.push({
+						text: `[Summary of earlier conversation]: ${truncateMiddle(summary, SUMMARY_MAX_CHARS)}`,
+					});
+				}
+				break;
+			}
+			case "bashExecution": {
+				if (message.excludeFromContext) break;
+				const command = typeof message.command === "string" ? message.command.trim() : "";
+				if (command) blocks.push({ text: `[User ran]: ${truncateMiddle(command, NOTE_MAX_CHARS)}` });
+				break;
+			}
+			default:
+				break;
+		}
+	}
+
+	return blocks;
+}
+
+/**
+ * Keep the head and the tail of the conversation within `maxChars`, dropping
+ * the middle and leaving an elision marker in its place. `maxChars <= 0`
+ * disables the budget.
+ */
+export function applyTranscriptBudget(blocks: readonly TranscriptBlock[], maxChars: number): TranscriptResult {
+	const parts = blocks.map((block) => block.text);
+	const joinBlocks = (items: string[]) => items.join("\n\n");
+	const full = joinBlocks(parts);
+	if (maxChars <= 0 || full.length <= maxChars) {
+		return { text: full, omittedTurns: 0, droppedChars: 0 };
+	}
+
+	// Head: everything up to and including the opening user message, always kept.
+	const anchor = blocks.findIndex((block) => block.anchor);
+	const anchorIndex = anchor === -1 ? 0 : anchor;
+	let headChars = parts.slice(0, anchorIndex + 1).reduce((sum, part) => sum + part.length + 2, 0);
+
+	// Tail: newest first, up to 60% of the budget.
+	const tailBudget = Math.floor(maxChars * TAIL_SOURCE_SHARE);
+	let tailStart = parts.length;
+	let tailChars = 0;
+	for (let i = parts.length - 1; i > anchorIndex; i--) {
+		const cost = parts[i].length + 2;
+		if (tailChars + cost > tailBudget) break;
+		tailChars += cost;
+		tailStart = i;
+	}
+	// Never drop the newest block: it is the most valuable one, and message-level
+	// caps normally keep it well inside the tail budget.
+	if (tailStart === parts.length && parts.length > anchorIndex + 1) tailStart = parts.length - 1;
+
+	// Gap: oldest first, contiguous from just after the head, while the head
+	// budget lasts.
+	const headBudget = Math.floor(maxChars * HEAD_SOURCE_SHARE);
+	let gapEnd = anchorIndex;
+	while (gapEnd + 1 < tailStart && headChars + parts[gapEnd + 1].length + 2 <= headBudget) {
+		headChars += parts[gapEnd + 1].length + 2;
+		gapEnd += 1;
+	}
+
+	const omitted = parts.slice(gapEnd + 1, tailStart);
+	const droppedChars = omitted.reduce((sum, part) => sum + part.length + 2, 0);
+	const kept = [...parts.slice(0, gapEnd + 1)];
+	if (omitted.length > 0) kept.push(`[... ${omitted.length} turns omitted — ${droppedChars} chars ...]`);
+	kept.push(...parts.slice(tailStart));
+
+	return { text: joinBlocks(kept), omittedTurns: omitted.length, droppedChars };
+}
+
+/** Minimal reconstruction of the conversation plus the file-operation footer. */
+export function buildMinimalTranscript(
+	messages: readonly TranscriptSource[],
+	maxChars: number = DEFAULT_MAX_SOURCE_CHARS,
+): TranscriptResult {
+	const budget = applyTranscriptBudget(renderTranscriptBlocks(messages), maxChars);
+	const fileLists = formatFileLists(fileListsFromMessages(messages));
+	if (!fileLists) return budget;
+	return { ...budget, text: budget.text ? `${budget.text}\n\n${fileLists}` : fileLists };
+}
+
+/** The single user message of the fresh pass. */
+export function buildFreshPassUserMessage(transcript: string, steering: string): string {
+	return [
+		"## Conversation (minimal reconstruction)",
+		transcript,
+		"",
+		"## What the hand-off must cover",
+		steering.trim() || DEFAULT_COVERAGE,
+		"",
+		"Requirements for your output:",
+		'- Written as instructions to the next agent ("you"), not a report about the past.',
+		"- Assume zero prior context: current task and goal, what was done so far with concrete file paths, commands, and decisions, and exactly what to do next.",
+		"- Name the files worth opening first.",
+		"- Reply with ONLY the hand-off message: no preamble, no postamble, no fences.",
+	].join("\n");
+}
+
+// ============================================================================
+// Session provenance (both writers)
+// ============================================================================
+
+/**
+ * HTML comment naming the session a hand-off came from, so the next agent can
+ * look it up when the prompt is not enough. It is a comment, not prose, so it
+ * does not read as part of the task, and it stays visible in the editor.
+ */
+export function buildProvenanceComment(sessionId: string | undefined): string {
+	const id = sessionId?.trim();
+	return id ? `<!-- Handed off from pi session ${id} -->` : "";
+}
+
+/** Prepends the provenance comment; called right before `writeHandoff()`. */
+function withSessionProvenance(prompt: string, ctx: ExtensionContext): string {
+	const comment = buildProvenanceComment(ctx.sessionManager.getSessionId());
+	return comment ? `${comment}\n\n${prompt}` : prompt;
+}
+
+// ============================================================================
+// Fresh pass generation
+// ============================================================================
+
+/** Options for the one-shot writer call; `reasoning` is only set when supported. */
+interface WriterRequestOptions {
+	signal?: AbortSignal;
+	cacheRetention: "none";
+	sessionId: string;
+	reasoning?: ThinkingLevel;
+}
+
+interface WriterOutcome {
+	prompt?: string;
+	error?: string;
+	cancelled?: boolean;
+}
+
+/** Strip a fence that wraps the whole reply, leaving inner code blocks alone. */
+function stripSurroundingFence(text: string): string {
+	const trimmed = text.trim();
+	if (!trimmed.startsWith("```") || !trimmed.endsWith("```")) return trimmed;
+	const withoutOpen = trimmed.replace(/^```[^\n]*\n?/, "");
+	return withoutOpen.slice(0, withoutOpen.lastIndexOf("```")).trim();
+}
+
+function checkWrittenPrompt(response: { stopReason?: string; errorMessage?: string; content?: unknown }): WriterOutcome {
+	if (response.stopReason === "aborted") return { cancelled: true };
+	if (response.stopReason !== "stop") {
+		const detail = response.errorMessage ? `: ${response.errorMessage}` : "";
+		return { error: `stopped with reason "${response.stopReason}"${detail}` };
+	}
+	const text = stripSurroundingFence(visibleText(response.content));
+	if (!text) return { error: "returned an empty prompt" };
+	return { prompt: text };
+}
+
+function reportWriterOutcome(ctx: ExtensionContext, outcome: WriterOutcome, label: string): string | undefined {
+	if (outcome.prompt) return outcome.prompt;
+	if (outcome.cancelled) {
+		ctx.ui.notify("Hand-off cancelled", "info");
+		return undefined;
+	}
+	ctx.ui.notify(
+		`Hand-off writer (${label}) ${outcome.error ?? "failed"}; staying in this session`,
+		"error",
+	);
+	return undefined;
+}
+
+/**
+ * Run the fresh pass: one `complete()` call over the minimal transcript.
+ * TUI mode gets a cancellable loader; other modes get a notification.
+ */
+async function generateFreshPassPrompt(
+	ctx: ExtensionContext,
+	model: AnyModel,
+	transcript: string,
+	steering: string,
+	reasoning: ThinkingLevel | undefined,
+): Promise<string | undefined> {
+	const userMessage = {
+		role: "user" as const,
+		content: [{ type: "text" as const, text: buildFreshPassUserMessage(transcript, steering) }],
+		timestamp: Date.now(),
+	};
+
+	const attempt = async (signal?: AbortSignal): Promise<WriterOutcome> => {
+		const options: WriterRequestOptions = { signal, cacheRetention: "none", sessionId: randomUUID() };
+		// Providers default when the option is absent, and models without
+		// reasoning controls would reject it; pi's own summarization does the
+		// same check before setting the level.
+		if (reasoning && model.reasoning) options.reasoning = reasoning;
+		try {
+			const response = await ctx.modelRegistry.complete(
+				model,
+				{ systemPrompt: HANDOFF_SYSTEM_PROMPT, messages: [userMessage] },
+				options,
+			);
+			return checkWrittenPrompt(response);
+		} catch (err) {
+			return { error: `failed: ${err instanceof Error ? err.message : String(err)}` };
+		}
+	};
+
+	const label = `${model.provider}/${model.id}`;
+
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(`Writing the hand-off prompt with ${label}…`, "info");
+		return reportWriterOutcome(ctx, await attempt(), label);
+	}
+
+	let aborted = false;
+	let outcome: WriterOutcome | undefined;
+	const prompt = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+		// Abort and completion can race; `done` must only be called once.
+		let finished = false;
+		const finish = (value: string | null) => {
+			if (finished) return;
+			finished = true;
+			done(value);
+		};
+		const loader = new BorderedLoader(tui, theme, `Writing the hand-off prompt with ${label}…`);
+		loader.onAbort = () => {
+			aborted = true;
+			finish(null);
+		};
+		void attempt(loader.signal).then((result) => {
+			outcome = result;
+			finish(result.prompt ?? null);
+		});
+		return loader;
+	});
+
+	if (prompt) return prompt;
+	if (aborted) {
+		ctx.ui.notify("Hand-off cancelled", "info");
+		return undefined;
+	}
+	return reportWriterOutcome(ctx, outcome ?? { error: "returned no prompt" }, label);
+}
+
+// ============================================================================
+// Command arguments, writer choice, and settings
+// ============================================================================
+
+interface ParsedHandoffArgs {
+	writer?: "live" | "fresh";
+	/** Everything after the leading flags: the steering-editor prefill. */
+	steering: string;
+	error?: string;
+}
+
+/** Parse leading `/hand-off` flags; the first unrecognized token starts the steering text. */
+export function parseHandoffArgs(args: string): ParsedHandoffArgs {
+	const tokens = args.split(/\s+/).filter(Boolean);
+	const parsed: ParsedHandoffArgs = { steering: "" };
+	let index = 0;
+
+	for (; index < tokens.length; index++) {
+		const token = tokens[index];
+		if (token === "--fresh" || token === "--live") {
+			const writer = token === "--fresh" ? "fresh" : "live";
+			if (parsed.writer && parsed.writer !== writer) {
+				return { ...parsed, error: "--fresh and --live cannot be combined; nothing was sent" };
+			}
+			parsed.writer = writer;
+			continue;
+		}
+		break;
+	}
+
+	parsed.steering = tokens.slice(index).join(" ");
+	return parsed;
+}
+
+export interface HandoffSettings {
+	summarizerModel?: string;
+	askSummarizerModel?: boolean;
+	/** Thinking level for the fresh pass; absent means the provider default. */
+	summarizerThinkingLevel?: ThinkingLevel;
+	maxSourceChars?: number;
+}
+
+const SETTINGS_FILE_NAME = "pi-clear.json";
+const FLAG_MAX_SOURCE_CHARS = "hand-off-max-source-chars";
+const FLAG_SUMMARIZER = "hand-off-summarizer";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Read `<agent-dir>/pi-clear.json`; a malformed file is a warning, not a failure. */
+export function loadHandoffSettings(path: string = join(getAgentDir(), SETTINGS_FILE_NAME)): {
+	settings: HandoffSettings;
+	warning?: string;
+} {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (err) {
+		if ((err as { code?: string }).code === "ENOENT") return { settings: {} };
+		return { settings: {}, warning: `pi-clear: could not read ${path}: ${messageOf(err)}` };
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		return { settings: {}, warning: `pi-clear: ignoring malformed ${path}: ${messageOf(err)}` };
+	}
+
+	if (!isRecord(parsed) || !isRecord(parsed.handoff)) {
+		return { settings: {}, warning: `pi-clear: ignoring ${path}: expected a "handoff" object` };
+	}
+
+	const handoff = parsed.handoff;
+	const settings: HandoffSettings = {};
+	const problems: string[] = [];
+
+	if (handoff.summarizerModel !== undefined) {
+		if (typeof handoff.summarizerModel === "string" && handoff.summarizerModel.includes("/")) {
+			settings.summarizerModel = handoff.summarizerModel.trim();
+		} else {
+			problems.push('"summarizerModel" must be a "provider/model" string');
+		}
+	}
+	if (handoff.summarizerThinkingLevel !== undefined) {
+		const value = handoff.summarizerThinkingLevel;
+		// "default" (and "off") mean "leave the choice to the provider", the same
+		// as omitting the key.
+		if (value === "default" || value === "off") {
+			// Nothing to record.
+		} else if (typeof value === "string" && WRITER_REASONING_LEVELS.includes(value as ThinkingLevel)) {
+			settings.summarizerThinkingLevel = value as ThinkingLevel;
+		} else {
+			problems.push(
+				`"summarizerThinkingLevel" must be "default" or one of ${WRITER_REASONING_LEVELS.join(", ")}`,
+			);
+		}
+	}
+	if (handoff.askSummarizerModel !== undefined) {
+		if (typeof handoff.askSummarizerModel === "boolean") settings.askSummarizerModel = handoff.askSummarizerModel;
+		else problems.push('"askSummarizerModel" must be true or false');
+	}
+	if (handoff.maxSourceChars !== undefined) {
+		if (typeof handoff.maxSourceChars === "number" && Number.isFinite(handoff.maxSourceChars) && handoff.maxSourceChars >= 0) {
+			settings.maxSourceChars = Math.floor(handoff.maxSourceChars);
+		} else {
+			problems.push('"maxSourceChars" must be a number >= 0');
+		}
+	}
+
+	return problems.length > 0
+		? { settings, warning: `pi-clear: ignoring ${path} ${problems.join(", ")}` }
+		: { settings };
+}
+
+function messageOf(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+/** Command arg > pi CLI flag > config file > built-in default. */
+export function resolveMaxSourceChars(flagValue: unknown, settings: HandoffSettings): number {
+	if (typeof flagValue === "string" && flagValue.trim()) {
+		const fromFlag = Number(flagValue);
+		if (Number.isFinite(fromFlag) && fromFlag >= 0) return Math.floor(fromFlag);
+	}
+	if (settings.maxSourceChars !== undefined) return settings.maxSourceChars;
+	return DEFAULT_MAX_SOURCE_CHARS;
+}
+
+/** `118234` → `118k`, for the trimming notice. */
+function formatChars(chars: number): string {
+	if (chars < 1000) return String(chars);
+	if (chars < 1_000_000) return `${Math.round(chars / 1000)}k`;
+	return `${(chars / 1_000_000).toFixed(1)}M`;
+}
+
+type WriterChoice = { kind: "live" } | { kind: "fresh"; model: AnyModel };
+
+interface WriterOptions {
+	/** From `--fresh` / `--live`; skips the writer picker. */
+	writer?: "live" | "fresh";
+	/** Model pinned by command arg, pi flag, or config. */
+	pinnedModel?: AnyModel;
+	/** Whether the summarizer model picker still needs to open. */
+	askSummarizer: boolean;
+}
+
+const WRITER_LIVE_LABEL = "This agent — full context and tools";
+const WRITER_FRESH_OTHER_LABEL = "Fresh pass — another model…";
+
+/** Pick the hand-off writer: the live agent, or a fresh pass with a chosen model. */
+async function chooseWriter(ctx: ExtensionContext, options: WriterOptions): Promise<WriterChoice | undefined> {
+	const withCurrentModel = (): WriterChoice | undefined => {
+		const model = options.pinnedModel ?? ctx.model;
+		if (!model) {
+			ctx.ui.notify("No current model to write the hand-off; pick another model", "error");
+			return undefined;
+		}
+		return { kind: "fresh", model };
+	};
+
+	const askForModel = async (): Promise<WriterChoice | undefined> => {
+		if (!options.askSummarizer) return withCurrentModel();
+		const picked = await pickTargetModel(ctx, {
+			current: options.pinnedModel ?? ctx.model,
+			title: "Hand-off writer model",
+			providerTitle: "Hand-off writer provider",
+		});
+		if (!picked) return undefined;
+		if (!ctx.modelRegistry.hasConfiguredAuth(picked.model)) {
+			ctx.ui.notify(
+				`No auth configured for ${picked.model.provider}/${picked.model.id}; staying in this session`,
+				"error",
+			);
+			return undefined;
+		}
+		return { kind: "fresh", model: picked.model };
+	};
+
+	if (options.writer === "live") return { kind: "live" };
+	if (options.writer === "fresh") return askForModel();
+
+	const labels = [
+		WRITER_LIVE_LABEL,
+		options.pinnedModel
+			? `Fresh pass — ${options.pinnedModel.provider}/${options.pinnedModel.id}`
+			: "Fresh pass — current model",
+		WRITER_FRESH_OTHER_LABEL,
+	];
+	const chosen = await ctx.ui.select("Who writes the hand-off prompt?", labels);
+	if (chosen === undefined) return undefined;
+
+	switch (labelIndex(chosen, labels)) {
+		case 0:
+			return { kind: "live" };
+		case 1:
+			return withCurrentModel();
+		case 2:
+			return askForModel();
+		default:
+			return undefined;
+	}
+}
+
 export default function (pi: ExtensionAPI) {
 	// In-session state for the hand-off capture; fresh per extension instance,
 	// so it never leaks into a replacement session.
 	let awaitingHandoff = false;
 	let capturedPrompt: string | undefined;
 	let flowInProgress = false;
+	// Config file contents, refreshed on every `session_start` (the file is read
+	// once per session, not per hand-off). The pi CLI flag is read per hand-off
+	// so it works even if a command somehow runs before `session_start`.
+	let handoffSettings: HandoffSettings = {};
 
 	/**
 	 * Apply a captured model and thinking level, reporting problems as
@@ -409,6 +1154,67 @@ export default function (pi: ExtensionAPI) {
 		}
 	}
 
+	/** Ask the live agent to write its next message as the hand-off prompt. */
+	async function captureFromLiveAgent(
+		ctx: ExtensionCommandContext,
+		steering: string,
+	): Promise<string | undefined> {
+		awaitingHandoff = true;
+		capturedPrompt = undefined;
+		try {
+			await pi.sendMessage(
+				{
+					customType: HANDOFF_CUSTOM_TYPE,
+					content: buildHandoffRequest(steering),
+					display: true,
+				},
+				{ triggerTurn: true },
+			);
+			await ctx.waitForIdle();
+		} finally {
+			awaitingHandoff = false;
+		}
+
+		if (!capturedPrompt) {
+			ctx.ui.notify("The agent did not produce a hand-off prompt; staying in this session", "error");
+			return undefined;
+		}
+		return capturedPrompt;
+	}
+
+	/** One fresh pass over the minimal transcript; notifies when it trims. */
+	async function captureFromFreshPass(
+		ctx: ExtensionContext,
+		writer: WriterChoice & { kind: "fresh" },
+		reasoning: ThinkingLevel | undefined,
+		steering: string,
+	): Promise<string | undefined> {
+		const messages = ctx.sessionManager.buildSessionProjection().messages;
+		const maxSourceChars = resolveMaxSourceChars(pi.getFlag(FLAG_MAX_SOURCE_CHARS), handoffSettings);
+		const source = buildMinimalTranscript(messages, maxSourceChars);
+		if (!source.text.trim()) {
+			ctx.ui.notify("No conversation to hand off", "error");
+			return undefined;
+		}
+		if (source.omittedTurns > 0) {
+			ctx.ui.notify(
+				`Hand-off source trimmed: ${source.omittedTurns} earlier turns omitted (~${formatChars(source.droppedChars)} chars dropped)`,
+				"info",
+			);
+		}
+		return generateFreshPassPrompt(ctx, writer.model, source.text, steering, reasoning);
+	}
+
+	pi.registerFlag(FLAG_MAX_SOURCE_CHARS, {
+		description:
+			"pi-clear: max characters of conversation sent to the /hand-off writer (0 disables the budget)",
+		type: "string",
+	});
+	pi.registerFlag(FLAG_SUMMARIZER, {
+		description: "pi-clear: model that writes /hand-off prompts, as provider/model",
+		type: "string",
+	});
+
 	pi.registerCommand("clear", {
 		description: "Start a fresh session, keeping the current model and thinking level",
 		handler: async (_args, ctx) => {
@@ -448,59 +1254,97 @@ export default function (pi: ExtensionAPI) {
 
 	pi.registerCommand("hand-off", {
 		description:
-			"Hand the conversation to another model: pick the next model and thinking level, the agent writes the hand-off prompt, and it lands pre-filled in a fresh session's editor",
+			"Hand the conversation to another model: choose who writes the hand-off prompt (this agent or a fresh pass), pick the next model and thinking level, then review the prompt in a fresh session",
 		handler: async (args, ctx) => {
+			if (flowInProgress) {
+				ctx.ui.notify("A hand-off is already in progress", "warning");
+				return;
+			}
 			try {
-				if (flowInProgress) {
-					ctx.ui.notify("A hand-off is already in progress", "warning");
+				flowInProgress = true;
+
+				const parsed = parseHandoffArgs(args);
+				if (parsed.error) {
+					ctx.ui.notify(parsed.error, "error");
 					return;
 				}
-				flowInProgress = true;
+
 				if (!ctx.isIdle()) {
 					ctx.ui.notify("Waiting for the agent to finish before handing off", "info");
 					await ctx.waitForIdle();
 				}
 
-				// 1. Pick the destination model.
+				// Writer model: pi CLI flag > config file. There is no command-arg
+				// flag; without a configured preference the picker just opens.
+				const flagSummarizer = pi.getFlag(FLAG_SUMMARIZER);
+				const summarizerSpec =
+					(typeof flagSummarizer === "string" && flagSummarizer.trim() ? flagSummarizer.trim() : undefined) ??
+					handoffSettings.summarizerModel;
+				const pinnedModel = summarizerSpec
+					? ctx.modelRegistry.find(
+							summarizerSpec.slice(0, summarizerSpec.indexOf("/")),
+							summarizerSpec.slice(summarizerSpec.indexOf("/") + 1),
+						)
+					: undefined;
+				if (summarizerSpec && !pinnedModel) {
+					ctx.ui.notify(
+						`Hand-off writer model ${summarizerSpec} is not available; choose one instead`,
+						"warning",
+					);
+				}
+				// A pi CLI flag is not asked about again; a config-file model is only
+				// silently accepted when `askSummarizerModel` is false.
+				const pinnedByFlag = typeof flagSummarizer === "string";
+				const askSummarizer =
+					!pinnedModel || (!pinnedByFlag && handoffSettings.askSummarizerModel !== false);
+
+				// 1. Choose who writes the hand-off prompt, and (for the fresh pass)
+				// how hard that model should think.
+				const writer = await chooseWriter(ctx, {
+					writer: parsed.writer,
+					pinnedModel,
+					askSummarizer,
+				});
+				if (!writer) return;
+
+				let writerReasoning: ThinkingLevel | undefined;
+				if (writer.kind === "fresh" && writer.model.reasoning) {
+					const chosen = await selectWriterReasoningLevel(ctx, handoffSettings.summarizerThinkingLevel);
+					if (!chosen) return;
+					writerReasoning = chosen.reasoning;
+				}
+
+				// 2. Pick the destination model.
 				const target = await pickTargetModel(ctx);
 				if (!target) return;
 
-				// 2. Pick the thinking level (a scoped `model:level` entry pins it).
+				// 3. Pick the thinking level (a scoped `model:level` entry pins it).
 				const level = target.thinkingLevel ?? (await selectThinkingLevel(ctx));
 				if (level === undefined) return;
 
-				// 3. Collect steering instructions, pre-filled from /hand-off args.
+				// 4. Collect steering instructions, pre-filled from the remaining args.
 				const steering = await ctx.ui.editor(
-					"Steering for the hand-off prompt (sent to the current agent)",
-					args.trim(),
+					writer.kind === "live"
+						? "Steering for the hand-off prompt (sent to the current agent)"
+						: "Steering for the hand-off prompt (sent to the hand-off writer)",
+					parsed.steering.trim(),
 				);
 				if (steering === undefined) return;
 
-				// 4. Ask the current agent to write the hand-off prompt.
-				awaitingHandoff = true;
-				capturedPrompt = undefined;
-				await pi.sendMessage(
-					{
-						customType: HANDOFF_CUSTOM_TYPE,
-						content: buildHandoffRequest(steering),
-						display: true,
-					},
-					{ triggerTurn: true },
-				);
-				await ctx.waitForIdle();
-				awaitingHandoff = false;
+				// 5. Write the hand-off prompt with the chosen writer.
+				const prompt =
+					writer.kind === "live"
+						? await captureFromLiveAgent(ctx, steering)
+						: await captureFromFreshPass(ctx, writer, writerReasoning, steering);
+				if (!prompt) return;
 
-				if (!capturedPrompt) {
-					ctx.ui.notify("The agent did not produce a hand-off prompt; staying in this session", "error");
-					return;
-				}
-
-				// 5. Carry everything across session replacement as plain data.
+				// 6. Carry everything across session replacement as plain data, with
+				// the provenance comment added here (never by the writer model).
 				writeHandoff({
 					provider: target.model.provider,
 					modelId: target.model.id,
 					thinkingLevel: level,
-					prompt: capturedPrompt,
+					prompt: withSessionProvenance(prompt, ctx),
 				});
 
 				const result = await ctx.newSession();
@@ -537,6 +1381,10 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("session_start", async (event, ctx) => {
+		const loaded = loadHandoffSettings();
+		handoffSettings = loaded.settings;
+		if (loaded.warning) ctx.ui.notify(loaded.warning, "warning");
+
 		if (event.reason !== "new") return;
 
 		const handoff = takeHandoff();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@grrrck/pi-clear",
-	"version": "0.3.1",
+	"version": "0.4.0",
 	"description": "Pi extension that starts a fresh session with /clear while keeping your current model and thinking level, and hands conversations off between models with /hand-off",
 	"keywords": [
 		"pi-package",