@ssweens/pi-handoff 1.0.0 → 1.1.0

package/README.md

@@ -6,62 +6,27 @@
 pi install @ssweens/pi-handoff
 ```
 
-Context handoff extension for [pi](https://github.com/badlogic/pi-mono). Transfer context to a new session with a structured summary — the agent can trigger handoffs, or they happen automatically on compaction.
+Context handoff extension for [pi](https://github.com/badlogic/pi-mono). Transfer context to a new session with a structured summary — three entry points, one UX.
 
 ## Features
 
-- **User preview/editing** — Review and edit the handoff draft before submission
-- **Agent-callable handoff tool** — The model can initiate handoffs when explicitly asked
-- **Auto-handoff on compaction** — Uses Pi's preparation data so summaries won't overflow
-- **Structured format** — Bullet list with code pointers (path:line or path#Symbol)
-- **Parent session query** — `session_query` tool for looking up details from parent sessions
-- **Auto-inject skill** — Detects `Parent session:` references and enables query instructions automatically
+- **`/handoff <goal>`** — User-initiated context transfer to a focused new session
+- **Agent-callable tool** — The model can initiate handoffs when explicitly asked
+- **Auto-handoff on compaction** — Offered as an alternative when context gets full
+- **Parent session query** — `session_query` tool for looking up details from prior sessions
+- **Programmatic file tracking** — Read/modified files extracted from tool calls (same as pi's compaction)
+- **Structured format** — Aligned with pi's compaction format (Goal, Constraints, Progress, Key Decisions, Next Steps, Critical Context)
 - **System prompt hints** — The model knows about handoffs and suggests them proactively
-- **Session naming** — New sessions named based on handoff goal
 
 ## Installation
 
-### From npm
-
 ```bash
 pi install @ssweens/pi-handoff
 ```
 
-### From git (global)
-
-```bash
-pi install git:github.com/ssweens/pi-handoff
-```
-
-### From git (project-local)
-
-```bash
-pi install -l git:github.com/ssweens/pi-handoff
-```
-
-### Try without installing
-
-```bash
-pi -e git:github.com/ssweens/pi-handoff
-```
-
-### From local path (development)
+## Usage
 
-Add to your settings (`~/.pi/agent/settings.json` or `.pi/settings.json`):
-
-```json
-{
-  "packages": [
-    "/path/to/pi-handoff"
-  ]
-}
-```
-
-## Features
-
-### `/handoff <goal>` — Context Transfer
-
-When your conversation gets long or you want to branch off to a focused task:
+### `/handoff <goal>`
 
 ```
 /handoff now implement this for teams as well
@@ -69,155 +34,114 @@ When your conversation gets long or you want to branch off to a focused task:
 /handoff check other places that need this fix
 ```
 
-This:
-1. Analyzes your current conversation
-2. Generates a structured handoff summary with:
-   - Key decisions and approaches (as bullet points)
-   - Relevant files with code pointers
-   - Clear task description based on your goal
-3. Opens an editor for you to review/modify the draft
-4. Creates a new session with parent tracking
-5. Sets up the prompt ready to submit
+**What happens:**
+1. LLM generates a structured handoff prompt from your conversation
+2. New session opens
+3. Prompt appears in the editor for review
+4. Press Enter to send — agent starts working
 
 ### Agent-Initiated Handoff
 
-The model can also create handoffs when you explicitly ask:
+Ask the model directly:
 
 ```
-"Please hand this off to a new session to implement the fix"
-"Create a handoff to execute phase one"
+"Please hand this off to a new session"
 ```
 
-The agent uses the `handoff` tool, which defers the handoff until after the current turn completes (so the tool result is properly recorded in the old session). In tool/hook contexts, it creates a new session file and rebases the active agent context to start at the handoff prompt, so the next turn runs with the handed-off context instead of the old oversized history.
-
-### System Prompt Awareness
-
-The extension injects handoff awareness into the system prompt. The model knows:
-- `/handoff` exists and when to suggest it
-- Handoffs after planning sessions are especially effective — clear context and start fresh with the plan
-- At high context usage, it should suggest a handoff rather than losing context
+The agent calls the `handoff` tool. Session switch is deferred until the current turn completes, then the same flow: new session → prompt in editor → press Enter.
 
 ### Auto-Handoff on Compaction
 
-When auto-compaction triggers (context exceeds the compaction threshold), the extension intercepts and offers a choice: **handoff to a new session** or **compact in place**.
+When context gets full and auto-compaction triggers, you're offered a choice:
+
+```
+Context is 92% full. What would you like to do?
+> Handoff to new session
+  Compact context
+  Continue without either
+```
 
-If you choose handoff:
-1. A summary is generated (same structured format as `/handoff`)
-2. You review/edit the handoff prompt
-3. A new session is created with the summary, old session preserved
-4. The agent continues in the new session
+Select "Handoff" → same flow: LLM generates prompt → new session → prompt in editor → press Enter. If you cancel or it fails, compaction proceeds as normal.
 
-If you decline, normal compaction proceeds as usual.
+### Querying Parent Sessions
 
-**Requires `compaction.enabled = true`** (the default). When auto-compaction is disabled, this hook never fires — use `/handoff` manually instead.
+Handoff prompts include a parent session reference:
 
-### `session_query` Tool — Cross-Session Context
+```
+/skill:pi-session-query
 
-The model can query parent sessions for details not in the handoff summary:
+**Parent session:** `/path/to/old-session.jsonl`
 
-```typescript
-session_query("/path/to/parent/session.jsonl", "What files were modified?")
-session_query("/path/to/parent/session.jsonl", "What approach was chosen for authentication?")
+## Goal
+...
 ```
 
-**Auto-injection:** When a user message contains a `**Parent session:**` reference, the extension prepends `/skill:pi-session-query` inline with the prompt body (single-submit flow, no extra Enter round-trip). No manual directive needed in handoff prompts.
+The `session_query` tool lets the model look up details from the parent session without loading the full conversation:
 
-**Size guard:** Large parent sessions are truncated (keeping the most recent context) to prevent exceeding context limits during the query.
+```typescript
+session_query("/path/to/session.jsonl", "What files were modified?")
+session_query("/path/to/session.jsonl", "What approach was chosen?")
+```
 
 ## Handoff Format
 
-Generated handoffs follow a structured format adapted from Pi's compaction system, filtered through the user's stated goal:
+Aligned with pi's compaction format, with programmatic file tracking appended:
 
 ```markdown
-# <goal>
-
-**Parent session:** `/path/to/session.jsonl`
-
 ## Goal
-What the user wants to accomplish in the new thread.
-
-## Key Decisions
-- **Decision 1**: Rationale (path/to/file.ts:42)
-- **Decision 2**: Rationale
+What the user wants to accomplish.
 
 ## Constraints & Preferences
-- Requirements or preferences the user stated
+- Requirements or preferences stated
 
 ## Progress
 ### Done
-- [x] Completed work relevant to the goal
+- [x] Completed work
 
 ### In Progress
-- [ ] Partially completed work
+- [ ] Current work
 
 ### Blocked
-- Open issues or blockers
+- Open issues
 
-## Files
-- path/to/file1.ts (modified)
-- path/to/file2.ts (read)
-
-## Task
-Clear, actionable next steps based on the goal.
-```
-
-The `/skill:pi-session-query` directive is auto-injected when this prompt is submitted (detected via the `**Parent session:**` marker).
-
-## Architecture Comparison
-
-| Feature | pi-amplike | mina | pi-handoff |
-|---------|-----------|------|------------|
-| `/handoff` command | ✅ | ✅ | ✅ |
-| Agent-callable tool | ✅ | ❌ | ✅ |
-| User preview/edit | ❌ | ✅ | ✅ |
-| Auto-handoff on compact | ❌ | ❌ | ✅ |
-| Parent query tool | ✅ | ✅ | ✅ |
-| Structured bullets | ❌ | ✅ | ✅ |
-| Code pointers | ❌ | ✅ | ✅ |
-| Auto-detect parent ref | ❌ | ✅ | ✅ |
-| System prompt hints | ❌ | ✅ | ✅ |
-| Session naming | ❌ | ❌ | ✅ |
-| Query size guard | ❌ | ✅ | ✅ |
-| Deferred tool switch | ✅ | N/A | ✅ |
+## Key Decisions
+- **Decision**: Rationale (path/to/file.ts:42)
 
-## How It Differs from Compaction
+## Next Steps
+1. What should happen next
 
-| | Compaction (`/compact`) | Handoff (`/handoff`) | Auto-Handoff |
-|---|---|---|---|
-| **Purpose** | Reduce context size | Transfer to focused task | Context full → new session |
-| **Trigger** | Automatic or `/compact` | User types `/handoff` | Intercepts auto-compaction |
-| **Continues** | Same session | New session | New session |
-| **Context** | Lossy summary | Goal-directed summary | Goal-directed summary |
-| **Parent access** | Lost | Queryable via `session_query` | Queryable via `session_query` |
-| **Use case** | General context overflow | Task branching | Preserve old session on overflow |
+## Critical Context
+- Data or references needed to continue
 
-## Session Navigation
+<read-files>
+src/config.ts
+</read-files>
 
-Use pi's built-in `/resume` command to switch between sessions. Handoff creates sessions with descriptive names based on your goal.
+<modified-files>
+src/handler.ts
+src/auth.ts
+</modified-files>
+```
 
 ## Components
 
 | Component | Type | Description |
 |-----------|------|-------------|
-| [handoff.ts](extensions/handoff.ts) | Extension | `/handoff` command, `handoff` tool, auto-handoff on compaction, system prompt hints |
-| [session-query.ts](extensions/session-query.ts) | Extension | `session_query` tool for the model (with size guard) |
-| [pi-session-query/SKILL.md](skills/pi-session-query/SKILL.md) | Skill | Instructions for using `session_query` |
-
-## Configuration
+| [handoff.ts](extensions/handoff.ts) | Extension | `/handoff` command, `handoff` tool, compact hook, system prompt hints |
+| [session-query.ts](extensions/session-query.ts) | Extension | `session_query` tool for querying parent sessions |
+| [pi-session-query/](skills/pi-session-query/SKILL.md) | Skill | Instructions for using `session_query` |
 
-No configuration required. The extension uses your current model for both handoff generation and session queries.
+## Architecture
 
-### Optional: Dedicated Query Model
+Three entry points, one outcome:
 
-To use a smaller/faster model for session queries (reducing cost), you can modify `session-query.ts` to use a different model:
+| Entry Point | Context Type | Session Creation |
+|-------------|-------------|-----------------|
+| `/handoff` command | `ExtensionCommandContext` | `ctx.newSession()` (full reset) |
+| `handoff` tool | `ExtensionContext` | Deferred to `agent_end` via raw `sessionManager.newSession()` |
+| Compact hook | `ExtensionContext` | Raw `sessionManager.newSession()` (no agent loop running) |
 
-```typescript
-// In session-query.ts execute function, replace:
-const model = ctx.model;
-
-// With a specific model lookup:
-const model = ctx.modelRegistry.find("anthropic", "claude-3-haiku") ?? ctx.model;
-```
+All three end the same way: prompt in editor of new session → user presses Enter → agent starts.
 
 ## License
 

package/extensions/handoff.ts

@@ -1,44 +1,32 @@
 /**
  * Handoff Extension
  *
- * Transfers conversation context to a new focused session via:
- * - /handoff <goal> command
- * - Agent-callable handoff tool
- * - Auto-handoff option when Pi triggers compaction
+ * Transfers conversation context to a new focused session.
+ * Three entry points, one UX: generate prompt → new session → prompt in editor → user sends.
  *
- * The compaction hook uses Pi's preparation data (messagesToSummarize,
- * previousSummary) instead of the full conversation, so the summary
- * generation won't overflow the context window.
+ * Entry points:
+ *   /handoff <goal>           — user-initiated command
+ *   handoff tool              — agent-initiated (deferred to agent_end)
+ *   session_before_compact    — offered when context is full (deferred via raw sessionManager)
  *
- * Usage:
- *   /handoff now implement this for teams as well
- *   /handoff execute phase one of the plan
- *   /handoff check other places that need this fix
- *
- * The generated prompt appears as a draft in the editor for review/editing.
- * The agent can also invoke the handoff tool when the user explicitly requests it.
+ * The generated prompt always lands in the editor of the new session for review.
+ * User presses Enter to send it.
  */
 
 import { complete, type Message } from "@mariozechner/pi-ai";
-import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@mariozechner/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+	SessionEntry,
+} from "@mariozechner/pi-coding-agent";
 import { BorderedLoader, convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 
-// Store pending handoff text to be set in new session after switch
-// Key: parent session file path, Value: handoff text to set in editor
-const pendingHandoffText = new Map<string, string>();
-
-// Handoff generation system prompt.
-//
-// Combines Pi's structured compaction format (Goal, Progress, Decisions,
-// Constraints) with handoff-specific goal filtering, code pointers from
-// mina, and an explicit Task section.
-//
-// Key differences from Pi compaction:
-// - Goal-directed: everything is filtered through the user's stated goal
-// - Code pointers: path:line and path#Symbol references in context
-// - Task section: actionable next steps framed by the goal
-// - Anti-continuation guard: prevent the summarizer from responding to the history
+// ---------------------------------------------------------------------------
+// System prompts
+// ---------------------------------------------------------------------------
+
 const SYSTEM_PROMPT = `You are a context transfer assistant. Read the conversation and produce a structured handoff summary for the stated goal. The new thread must be able to proceed without the old conversation.
 
 Do NOT continue the conversation. Do NOT respond to any questions in the history. ONLY output the structured summary.
@@ -48,10 +36,6 @@ Use this EXACT format:
 ## Goal
 [The user's goal for the new thread — what they want to accomplish.]
 
-## Key Decisions
-- **[Decision]**: [Brief rationale]
-- Use code pointers (path/to/file.ts:42 or path/to/file.ts#functionName) where relevant
-
 ## Constraints & Preferences
 - [Any requirements, constraints, or preferences the user stated]
 - [Or "(none)" if none were mentioned]
@@ -66,12 +50,16 @@ Use this EXACT format:
 ### Blocked
 - [Open issues or blockers, if any]
 
-## Files
-- path/to/file1.ts (modified)
-- path/to/file2.ts (read)
+## Key Decisions
+- **[Decision]**: [Brief rationale]
+- Use code pointers (path/to/file.ts:42 or path/to/file.ts#functionName) where relevant
+
+## Next Steps
+1. [Ordered list of what should happen next, filtered by the stated goal]
 
-## Task
-[Clear, actionable description of what to do next based on the goal. Ordered steps if appropriate.]
+## Critical Context
+- [Any data, examples, or references needed to continue]
+- [Or "(none)" if not applicable]
 
 Rules:
 - Be concise. Every bullet earns its place.
@@ -79,85 +67,89 @@ Rules:
 - Only include information relevant to the stated goal — discard unrelated context.
 - Output the formatted content only. No preamble, no filler.`;
 
-// System prompt fragment injected via before_agent_start.
-// Teaches the model about handoffs so it can suggest them proactively.
-const HANDOFF_SYSTEM_HINT = `
+export const HANDOFF_SYSTEM_HINT = `
 ## Handoff
 
 Use \`/handoff <goal>\` to transfer context to a new focused session.
 Handoffs are especially effective after planning — clear the context and start a new session with the plan you just created.
 At high context usage, suggest a handoff rather than losing important context.`;
 
-/**
- * Generate a session name from the goal (slug format)
- */
-function goalToSessionName(goal: string): string {
-	return goal
-		.toLowerCase()
-		.replace(/[^a-z0-9\s-]/g, "")
-		.trim()
-		.replace(/\s+/g, "-")
-		.slice(0, 50);
-}
+// ---------------------------------------------------------------------------
+// File operation tracking (mirrors pi's compaction/utils.ts approach)
+// ---------------------------------------------------------------------------
 
-/**
- * Handoff modes:
- * - "command": User-initiated via /handoff
- * - "tool": Agent-initiated via handoff tool
- * - "compactHook": Triggered from session_before_compact
- *
- * All modes follow the same flow: generate summary → editor review → new session → input box → user sends
- */
-type HandoffMode = "command" | "tool" | "compactHook";
+interface FileOps {
+	read: Set<string>;
+	written: Set<string>;
+	edited: Set<string>;
+}
 
-/**
- * Core handoff logic shared by the /handoff command, the handoff tool,
- * and the auto-handoff compaction hook.
- *
- * Returns an error string on failure, or undefined on success.
- */
-async function performHandoff(
-	pi: ExtensionAPI,
-	ctx: ExtensionContext,
-	goal: string,
-	mode: HandoffMode = "command",
-	preBuiltContext?: string,
-): Promise<string | undefined> {
-	if (!ctx.hasUI) {
-		return "Handoff requires interactive mode.";
-	}
+function createFileOps(): FileOps {
+	return { read: new Set(), written: new Set(), edited: new Set() };
+}
 
-	if (!ctx.model) {
-		return "No model selected.";
+/** Extract file paths from tool calls in assistant messages. */
+function extractFileOpsFromMessage(message: any, fileOps: FileOps): void {
+	if (message.role !== "assistant") return;
+	if (!Array.isArray(message.content)) return;
+
+	for (const block of message.content) {
+		if (block?.type !== "toolCall" || !block.arguments || !block.name) continue;
+		const path = typeof block.arguments.path === "string" ? block.arguments.path : undefined;
+		if (!path) continue;
+
+		switch (block.name) {
+			case "read":
+				fileOps.read.add(path);
+				break;
+			case "write":
+				fileOps.written.add(path);
+				break;
+			case "edit":
+				fileOps.edited.add(path);
+				break;
+		}
 	}
+}
 
-	let conversationText: string;
-
-	if (preBuiltContext) {
-		// compactHook: context already built from preparation data
-		conversationText = preBuiltContext;
-	} else {
-		// command/tool: gather full conversation (context isn't full yet)
-		const branch = ctx.sessionManager.getBranch();
-		const messages = branch
-			.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
-			.map((entry) => entry.message);
+/** Compute read-only and modified file lists, append to summary as XML tags. */
+function appendFileOperations(summary: string, messages: any[]): string {
+	const fileOps = createFileOps();
+	for (const msg of messages) extractFileOpsFromMessage(msg, fileOps);
 
-		if (messages.length === 0) {
-			return "No conversation to hand off.";
-		}
+	const modified = new Set([...fileOps.edited, ...fileOps.written]);
+	const readFiles = [...fileOps.read].filter((f) => !modified.has(f)).sort();
+	const modifiedFiles = [...modified].sort();
 
-		conversationText = serializeConversation(convertToLlm(messages));
+	const sections: string[] = [];
+	if (readFiles.length > 0) {
+		sections.push(`<read-files>\n${readFiles.join("\n")}\n</read-files>`);
 	}
+	if (modifiedFiles.length > 0) {
+		sections.push(`<modified-files>\n${modifiedFiles.join("\n")}\n</modified-files>`);
+	}
+
+	return sections.length > 0 ? `${summary}\n\n${sections.join("\n\n")}` : summary;
+}
 
-	const currentSessionFile = ctx.sessionManager.getSessionFile();
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
 
-	// Generate the handoff prompt with loader UI
-	const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
-		const loader = new BorderedLoader(tui, theme, `Generating handoff summary...`);
+/**
+ * Generate a handoff prompt via LLM with a loader UI.
+ * Returns the prompt text, or null if cancelled/failed.
+ */
+async function generateHandoffPrompt(
+	conversationText: string,
+	goal: string,
+	ctx: ExtensionContext,
+): Promise<string | null> {
+	return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+		const loader = new BorderedLoader(tui, theme, "Generating handoff prompt...");
 		loader.onAbort = () => done(null);
 
-		const doGenerate = async () => {
+		const run = async () => {
 			const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
 
 			const userMessage: Message = {
@@ -165,7 +157,7 @@ async function performHandoff(
 				content: [
 					{
 						type: "text",
-						text: `## Conversation History\n\n${conversationText}\n\n## Goal for New Thread\n\n${goal}`,
+						text: `## Conversation History\n\n${conversationText}\n\n## User's Goal for New Thread\n\n${goal}`,
 					},
 				],
 				timestamp: Date.now(),
@@ -177,9 +169,7 @@ async function performHandoff(
 				{ apiKey, signal: loader.signal },
 			);
 
-			if (response.stopReason === "aborted") {
-				return null;
-			}
+			if (response.stopReason === "aborted") return null;
 
 			return response.content
 				.filter((c): c is { type: "text"; text: string } => c.type === "text")
@@ -187,7 +177,7 @@ async function performHandoff(
 				.join("\n");
 		};
 
-		doGenerate()
+		run()
 			.then(done)
 			.catch((err) => {
 				console.error("Handoff generation failed:", err);
@@ -196,102 +186,123 @@ async function performHandoff(
 
 		return loader;
 	});
+}
 
-	if (result === null) {
-		return "Handoff cancelled.";
-	}
-
-	// Build the full prompt with parent reference
-	let fullPrompt = `# ${goal}\n\n`;
-
-	if (currentSessionFile) {
-		fullPrompt += `**Parent session:** \`${currentSessionFile}\`\n\n`;
-	}
-
-	fullPrompt += result;
-
-	// Prepend session-query skill if parent session present
-	const messageToSend = /\*\*Parent session:\*\*/.test(fullPrompt)
-		? `/skill:pi-session-query ${fullPrompt}`
-		: fullPrompt;
-
-	// Store the handoff text for the session_switch event to pick up
-	// We use the parent session file as key since that's what we pass to newSession
-	if (currentSessionFile) {
-		pendingHandoffText.set(currentSessionFile, messageToSend);
-	}
+/**
+ * Gather conversation from the current branch.
+ * Returns serialized text + raw messages (for file op extraction), or null if empty.
+ */
+function gatherConversation(ctx: ExtensionContext): { text: string; messages: any[] } | null {
+	const branch = ctx.sessionManager.getBranch();
+	const messages = branch
+		.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
+		.map((entry) => entry.message);
 
-	// Create new session immediately
-	// Use ctx.newSession if available (command mode), otherwise use sessionManager directly
-	if ("newSession" in ctx && typeof ctx.newSession === "function") {
-		const newSessionResult = await ctx.newSession({
-			parentSession: currentSessionFile,
-		});
+	if (messages.length === 0) return null;
 
-		if (newSessionResult.cancelled) {
-			// Clean up pending text if cancelled
-			if (currentSessionFile) {
-				pendingHandoffText.delete(currentSessionFile);
-			}
-			return "New session cancelled.";
-		}
-	} else {
-		// Tool/hook contexts: create session directly via session manager
-		const sessionManager = ctx.sessionManager as any;
-		sessionManager.newSession({ parentSession: currentSessionFile });
-	}
+	return { text: serializeConversation(convertToLlm(messages)), messages };
+}
 
-	pi.setSessionName(goalToSessionName(goal));
+/**
+ * Wrap a handoff prompt with the parent session reference and session-query skill.
+ * Enables the new session to query the old one for details not in the summary.
+ */
+function wrapWithParentSession(prompt: string, parentSessionFile: string | null): string {
+	if (!parentSessionFile) return prompt;
 
-	return undefined;
+	return `/skill:pi-session-query\n\n**Parent session:** \`${parentSessionFile}\`\n\n${prompt}`;
 }
 
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+
 export default function (pi: ExtensionAPI) {
-	// --- Session switch handler ---
-	// When switching to a new session (e.g., after handoff), check if there's
-	// pending handoff text to set in the editor.
+	// -- Shared state for tool/hook deferred handoff (pi-amplike pattern) -----
+	//
+	// Tool and compact-hook contexts have ExtensionContext (ReadonlySessionManager),
+	// not ExtensionCommandContext. They can't call ctx.newSession().
+	//
+	// Instead they store the prompt and defer the session switch:
+	// - Tool: deferred to agent_end (after agent loop completes)
+	// - Compact hook: deferred immediately via raw sessionManager.newSession()
+	//   (safe because no agent loop is running during compaction)
+	//
+	// Both paths use handoffTimestamp + context event filter to hide old messages
+	// from the LLM after the raw session switch (since agent.state.messages
+	// isn't cleared by sessionManager.newSession()).
+
+	let pendingHandoff: { prompt: string; parentSession: string | undefined } | null = null;
+	let handoffTimestamp: number | null = null;
+
+	// -- State for command path (full ctx.newSession() reset) -----------------
+	// Command path uses ctx.newSession() which fires session_switch properly.
+	// Store prompt keyed by parent session for the session_switch handler.
+	const pendingHandoffText = new Map<string, string>();
+
+	// ── session_switch ──────────────────────────────────────────────────────
+	// Set editor text for command-path handoffs + clear context filter.
 	pi.on("session_switch", async (event, ctx) => {
+		// Any proper session switch clears the context filter
+		handoffTimestamp = null;
+
 		if (event.reason !== "new" || !ctx.hasUI) return;
 
-		// Get the parent session from the session header
 		const header = ctx.sessionManager.getHeader();
 		const parentSession = header?.parentSession;
 		if (!parentSession) return;
 
-		// Check if there's pending handoff text for this parent session
 		const text = pendingHandoffText.get(parentSession);
 		if (text) {
 			ctx.ui.setEditorText(text);
-			ctx.ui.notify("Handoff ready - edit if needed and press Enter to send", "info");
+			ctx.ui.notify("Handoff ready — edit if needed, press Enter to send", "info");
 			pendingHandoffText.delete(parentSession);
 		}
 	});
 
-	// --- System prompt hint ---
-	// Inject handoff awareness into the system prompt so the model
-	// can proactively suggest handoffs at high context usage.
+	// ── context filter ──────────────────────────────────────────────────────
+	// After a raw sessionManager.newSession() (tool/hook path), old messages
+	// remain in agent.state.messages. Filter them by timestamp so the LLM
+	// only sees new-session messages.
+	pi.on("context", (event) => {
+		if (handoffTimestamp === null) return;
+
+		const newMessages = event.messages.filter((m: any) => m.timestamp >= handoffTimestamp);
+		if (newMessages.length > 0) {
+			return { messages: newMessages };
+		}
+	});
+
+	// ── agent_end: deferred session switch for tool path ────────────────────
+	pi.on("agent_end", (_event, ctx) => {
+		if (!pendingHandoff) return;
+
+		const { prompt, parentSession } = pendingHandoff;
+		pendingHandoff = null;
+
+		handoffTimestamp = Date.now();
+		(ctx.sessionManager as any).newSession({ parentSession });
+
+		// Defer to next macrotask so the agent loop cleanup completes first
+		setTimeout(() => {
+			if (ctx.hasUI) {
+				ctx.ui.setEditorText(prompt);
+				ctx.ui.notify("Handoff ready — edit if needed, press Enter to send", "info");
+			}
+		}, 0);
+	});
+
+	// ── before_agent_start: system prompt hint ──────────────────────────────
 	pi.on("before_agent_start", async (event, _ctx) => {
-		return {
-			systemPrompt: event.systemPrompt + HANDOFF_SYSTEM_HINT,
-		};
+		return { systemPrompt: event.systemPrompt + HANDOFF_SYSTEM_HINT };
 	});
 
-	// --- Auto-handoff on compaction ---
-	// When auto-compaction triggers, offer handoff as an alternative.
-	// Uses event.preparation (messagesToSummarize, previousSummary) — the
-	// manageable subset Pi already prepared — instead of re-gathering the
-	// full conversation that caused the compaction in the first place.
+	// ── session_before_compact: offer handoff ───────────────────────────────
 	pi.on("session_before_compact", async (event, ctx) => {
 		if (!ctx.hasUI || !ctx.model) return;
 
-		// Skip if a handoff was just initiated - the new session is already being created
-		const currentSessionFile = ctx.sessionManager.getSessionFile();
-		if (currentSessionFile && pendingHandoffText.has(currentSessionFile)) {
-			return;
-		}
-
 		const usage = ctx.getContextUsage();
-		const pctStr = usage ? `${Math.round(usage.percent)}%` : "high";
+		const pctStr = usage?.percent != null ? `${Math.round(usage.percent)}%` : "high";
 
 		const choice = await ctx.ui.select(
 			`Context is ${pctStr} full. What would you like to do?`,
@@ -301,7 +312,7 @@ export default function (pi: ExtensionAPI) {
 		if (choice === "Compact context" || choice === undefined) return;
 		if (choice === "Continue without either") return { cancel: true };
 
-		// Build context from preparation data — already the right subset
+		// Build context from preparation data
 		const { preparation } = event;
 		const conversationText = serializeConversation(
 			convertToLlm(preparation.messagesToSummarize),
@@ -313,16 +324,51 @@ export default function (pi: ExtensionAPI) {
 		}
 		contextForHandoff += `## Recent Conversation\n\n${conversationText}`;
 
-		const error = await performHandoff(pi, ctx, "Continue current work", "compactHook", contextForHandoff);
-		if (error) {
-			ctx.ui.notify(`Handoff failed: ${error}. Compacting instead.`, "warning");
+		// Generate handoff prompt
+		let prompt: string | null;
+		try {
+			prompt = await generateHandoffPrompt(contextForHandoff, "Continue current work", ctx);
+		} catch (err) {
+			ctx.ui.notify(
+				`Handoff failed: ${err instanceof Error ? err.message : String(err)}. Compacting instead.`,
+				"warning",
+			);
+			return;
+		}
+
+		if (prompt === null) {
+			ctx.ui.notify("Handoff cancelled. Compacting instead.", "warning");
+			return;
+		}
+
+		// Append programmatic file tracking from the messages being summarized
+		prompt = appendFileOperations(prompt, preparation.messagesToSummarize);
+
+		// Switch session via raw sessionManager (safe — no agent loop running)
+		const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+		// Wrap with parent session reference + session-query skill
+		prompt = wrapWithParentSession(prompt, currentSessionFile ?? null);
+
+		try {
+			handoffTimestamp = Date.now();
+			(ctx.sessionManager as any).newSession({ parentSession: currentSessionFile });
+		} catch (err) {
+			handoffTimestamp = null;
+			ctx.ui.notify(
+				`Session switch failed: ${err instanceof Error ? err.message : String(err)}. Compacting instead.`,
+				"warning",
+			);
 			return;
 		}
 
+		ctx.ui.setEditorText(prompt);
+		ctx.ui.notify("Handoff ready — edit if needed, press Enter to send", "info");
+
 		return { cancel: true };
 	});
 
-	// --- /handoff command ---
+	// ── /handoff command ─────────────────────────────────────────────────────
 	pi.registerCommand("handoff", {
 		description: "Transfer context to a new focused session",
 		handler: async (args, ctx) => {
@@ -332,14 +378,46 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			const error = await performHandoff(pi, ctx, goal);
-			if (error) {
-				ctx.ui.notify(error, "error");
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected.", "error");
+				return;
+			}
+
+			const conv = gatherConversation(ctx);
+			if (!conv) {
+				ctx.ui.notify("No conversation to hand off.", "error");
+				return;
+			}
+
+			let prompt = await generateHandoffPrompt(conv.text, goal, ctx);
+			if (prompt === null) {
+				ctx.ui.notify("Handoff cancelled.", "info");
+				return;
+			}
+
+			// Append programmatic file tracking (read/modified from tool calls)
+			prompt = appendFileOperations(prompt, conv.messages);
+
+			const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+			// Wrap with parent session reference + session-query skill
+			prompt = wrapWithParentSession(prompt, currentSessionFile ?? null);
+
+			if (currentSessionFile) {
+				pendingHandoffText.set(currentSessionFile, prompt);
+			}
+
+			const result = await ctx.newSession({ parentSession: currentSessionFile ?? undefined });
+
+			if (result.cancelled) {
+				if (currentSessionFile) pendingHandoffText.delete(currentSessionFile);
+				ctx.ui.notify("New session cancelled.", "info");
+				return;
 			}
 		},
 	});
 
-	// --- handoff tool (agent-callable) ---
+	// ── handoff tool ─────────────────────────────────────────────────────────
 	pi.registerTool({
 		name: "handoff",
 		label: "Handoff",
@@ -350,16 +428,42 @@ export default function (pi: ExtensionAPI) {
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const error = await performHandoff(pi, ctx, params.goal, "tool");
+			if (!ctx.hasUI) {
+				return { content: [{ type: "text" as const, text: "Handoff requires interactive mode." }] };
+			}
+			if (!ctx.model) {
+				return { content: [{ type: "text" as const, text: "No model selected." }] };
+			}
+
+			const conv = gatherConversation(ctx);
+			if (!conv) {
+				return { content: [{ type: "text" as const, text: "No conversation to hand off." }] };
+			}
+
+			let prompt = await generateHandoffPrompt(conv.text, params.goal, ctx);
+			if (prompt === null) {
+				return { content: [{ type: "text" as const, text: "Handoff cancelled." }] };
+			}
+
+			prompt = appendFileOperations(prompt, conv.messages);
+
+			const currentSessionFile = ctx.sessionManager.getSessionFile();
+			prompt = wrapWithParentSession(prompt, currentSessionFile ?? null);
+
+			// Defer session switch to agent_end
+			pendingHandoff = {
+				prompt,
+				parentSession: currentSessionFile ?? undefined,
+			};
+
 			return {
 				content: [
 					{
 						type: "text" as const,
-						text: error ?? "Handoff queued. Switching to a new session with the generated prompt.",
+						text: "Handoff initiated. The session will switch after the current turn completes.",
 					},
 				],
 			};
 		},
 	});
-
 }

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@ssweens/pi-handoff",
-  "version": "1.0.0",
+  "version": "1.1.0",
+  "scripts": {
+    "test": "bun test tests/",
+    "test:watch": "bun test --watch tests/"
+  },
   "description": "Enhanced handoff extension for pi - context management for agentic coding workflows",
   "keywords": [
     "pi-package"