@ssweens/pi-handoff 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssweens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# pi-handoff
+
+![pi-handoff command](screenshot.png)
+
+```bash
+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.
+
+## 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
+- **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)
+
+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 now implement this for teams as well
+/handoff execute phase one of the plan
+/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
+
+### Agent-Initiated Handoff
+
+The model can also create handoffs when you explicitly ask:
+
+```
+"Please hand this off to a new session to implement the fix"
+"Create a handoff to execute phase one"
+```
+
+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
+
+### 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**.
+
+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
+
+If you decline, normal compaction proceeds as usual.
+
+**Requires `compaction.enabled = true`** (the default). When auto-compaction is disabled, this hook never fires — use `/handoff` manually instead.
+
+### `session_query` Tool — Cross-Session Context
+
+The model can query parent sessions for details not in the handoff summary:
+
+```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?")
+```
+
+**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.
+
+**Size guard:** Large parent sessions are truncated (keeping the most recent context) to prevent exceeding context limits during the query.
+
+## Handoff Format
+
+Generated handoffs follow a structured format adapted from Pi's compaction system, filtered through the user's stated goal:
+
+```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
+
+## Constraints & Preferences
+- Requirements or preferences the user stated
+
+## Progress
+### Done
+- [x] Completed work relevant to the goal
+
+### In Progress
+- [ ] Partially completed work
+
+### Blocked
+- Open issues or blockers
+
+## 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 | ✅ |
+
+## How It Differs from Compaction
+
+| | 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 |
+
+## Session Navigation
+
+Use pi's built-in `/resume` command to switch between sessions. Handoff creates sessions with descriptive names based on your goal.
+
+## 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
+
+No configuration required. The extension uses your current model for both handoff generation and session queries.
+
+### Optional: Dedicated Query Model
+
+To use a smaller/faster model for session queries (reducing cost), you can modify `session-query.ts` to use a different model:
+
+```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;
+```
+
+## License
+
+MIT

package/extensions/handoff.ts

@@ -0,0 +1,365 @@
+/**
+ * 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
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+import { complete, type Message } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, 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
+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.
+
+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]
+
+## Progress
+### Done
+- [x] [Completed work relevant to the goal]
+
+### In Progress
+- [ ] [Partially completed work]
+
+### Blocked
+- [Open issues or blockers, if any]
+
+## Files
+- path/to/file1.ts (modified)
+- path/to/file2.ts (read)
+
+## Task
+[Clear, actionable description of what to do next based on the goal. Ordered steps if appropriate.]
+
+Rules:
+- Be concise. Every bullet earns its place.
+- Preserve exact file paths, function names, and error messages.
+- 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 = `
+## 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);
+}
+
+/**
+ * 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";
+
+/**
+ * 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.";
+	}
+
+	if (!ctx.model) {
+		return "No model selected.";
+	}
+
+	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);
+
+		if (messages.length === 0) {
+			return "No conversation to hand off.";
+		}
+
+		conversationText = serializeConversation(convertToLlm(messages));
+	}
+
+	const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+	// 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...`);
+		loader.onAbort = () => done(null);
+
+		const doGenerate = async () => {
+			const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+
+			const userMessage: Message = {
+				role: "user",
+				content: [
+					{
+						type: "text",
+						text: `## Conversation History\n\n${conversationText}\n\n## Goal for New Thread\n\n${goal}`,
+					},
+				],
+				timestamp: Date.now(),
+			};
+
+			const response = await complete(
+				ctx.model!,
+				{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+				{ apiKey, signal: loader.signal },
+			);
+
+			if (response.stopReason === "aborted") {
+				return null;
+			}
+
+			return response.content
+				.filter((c): c is { type: "text"; text: string } => c.type === "text")
+				.map((c) => c.text)
+				.join("\n");
+		};
+
+		doGenerate()
+			.then(done)
+			.catch((err) => {
+				console.error("Handoff generation failed:", err);
+				done(null);
+			});
+
+		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);
+	}
+
+	// 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 (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 });
+	}
+
+	pi.setSessionName(goalToSessionName(goal));
+
+	return undefined;
+}
+
+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.
+	pi.on("session_switch", async (event, ctx) => {
+		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");
+			pendingHandoffText.delete(parentSession);
+		}
+	});
+
+	// --- System prompt hint ---
+	// Inject handoff awareness into the system prompt so the model
+	// can proactively suggest handoffs at high context usage.
+	pi.on("before_agent_start", async (event, _ctx) => {
+		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.
+	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 choice = await ctx.ui.select(
+			`Context is ${pctStr} full. What would you like to do?`,
+			["Handoff to new session", "Compact context", "Continue without either"],
+		);
+
+		if (choice === "Compact context" || choice === undefined) return;
+		if (choice === "Continue without either") return { cancel: true };
+
+		// Build context from preparation data — already the right subset
+		const { preparation } = event;
+		const conversationText = serializeConversation(
+			convertToLlm(preparation.messagesToSummarize),
+		);
+
+		let contextForHandoff = "";
+		if (preparation.previousSummary) {
+			contextForHandoff += `## Previous Context\n\n${preparation.previousSummary}\n\n`;
+		}
+		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");
+			return;
+		}
+
+		return { cancel: true };
+	});
+
+	// --- /handoff command ---
+	pi.registerCommand("handoff", {
+		description: "Transfer context to a new focused session",
+		handler: async (args, ctx) => {
+			const goal = args.trim();
+			if (!goal) {
+				ctx.ui.notify("Usage: /handoff <goal for new thread>", "error");
+				return;
+			}
+
+			const error = await performHandoff(pi, ctx, goal);
+			if (error) {
+				ctx.ui.notify(error, "error");
+			}
+		},
+	});
+
+	// --- handoff tool (agent-callable) ---
+	pi.registerTool({
+		name: "handoff",
+		label: "Handoff",
+		description:
+			"Transfer context to a new focused session. ONLY use this when the user explicitly asks for a handoff. Provide a goal describing what the new session should focus on.",
+		parameters: Type.Object({
+			goal: Type.String({ description: "The goal/task for the new session" }),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const error = await performHandoff(pi, ctx, params.goal, "tool");
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: error ?? "Handoff queued. Switching to a new session with the generated prompt.",
+					},
+				],
+			};
+		},
+	});
+
+}

package/extensions/session-query.ts

@@ -0,0 +1,219 @@
+/**
+ * Session Query Extension - Query previous pi sessions
+ *
+ * Provides a tool the model can use to query past sessions for context,
+ * decisions, code changes, or other information.
+ *
+ * Works with handoff: when a handoff prompt includes "Parent session: <path>",
+ * the model can use this tool to look up details from that session.
+ *
+ * Based on pi-amplike's session-query, enhanced with:
+ * - Better error handling
+ * - Rendered results with markdown support
+ * - Session metadata in response
+ */
+
+import { complete, type Message } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, SessionEntry } from "@mariozechner/pi-coding-agent";
+import {
+	SessionManager,
+	convertToLlm,
+	serializeConversation,
+	getMarkdownTheme,
+} from "@mariozechner/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+import * as fs from "node:fs";
+
+// Maximum characters of serialized conversation to send to the query LLM.
+// Prevents blowing context when the parent session is very large.
+// ~100k chars ≈ ~25-30k tokens for most models — leaves room for the
+// question, system prompt, and answer within a 128k context window.
+const MAX_SESSION_CHARS = 100_000;
+
+const QUERY_SYSTEM_PROMPT = `Extract information relevant to the question from the session history.
+Return a concise answer using bullet points where appropriate.
+Use code pointers (path/to/file.ts:42 or path/to/file.ts#functionName) when referencing specific code.
+If the information is not in the session, say so clearly.`;
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "session_query",
+		label: (params) => `Query Session: ${params.question}`,
+		description:
+			"Query a previous pi session file for context, decisions, or information. Use when you need to look up what happened in a parent session or any other session. The sessionPath should be the full path to a .jsonl session file.",
+
+		parameters: Type.Object({
+			sessionPath: Type.String({
+				description:
+					"Full path to the session file (e.g., /home/user/.pi/agent/sessions/.../session.jsonl)",
+			}),
+			question: Type.String({
+				description:
+					"What you want to know about that session (e.g., 'What files were modified?' or 'What approach was chosen?')",
+			}),
+		}),
+
+		renderResult(result, _options, theme) {
+			const container = new Container();
+
+			if (result.content && result.content[0]?.text) {
+				const text = result.content[0].text;
+
+				// Check for error format
+				if (result.details?.error) {
+					container.addChild(new Text(theme.fg("error", text), 0, 0));
+					return container;
+				}
+
+				// Parse structured response: **Query:** question\n\n---\n\nanswer
+				const match = text.match(/\*\*Query:\*\* (.+?)\n\n---\n\n([\s\S]+)/);
+
+				if (match) {
+					const [, query, answer] = match;
+					container.addChild(new Text(theme.bold("Query: ") + theme.fg("accent", query), 0, 0));
+					container.addChild(new Spacer(1));
+					// Render the answer as markdown
+					container.addChild(
+						new Markdown(answer.trim(), 0, 0, getMarkdownTheme(), {
+							color: (text: string) => theme.fg("toolOutput", text),
+						}),
+					);
+				} else {
+					// Fallback for other formats
+					container.addChild(new Text(theme.fg("toolOutput", text), 0, 0));
+				}
+
+				// Show metadata if available
+				if (result.details?.messageCount) {
+					const truncNote = result.details.truncated ? ", truncated" : "";
+					container.addChild(new Spacer(1));
+					container.addChild(
+						new Text(
+							theme.fg("dim", `(${result.details.messageCount} messages in session${truncNote})`),
+							0,
+							0,
+						),
+					);
+				}
+			}
+
+			return container;
+		},
+
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			const { sessionPath, question } = params;
+
+			// Helper for error returns
+			const errorResult = (text: string) => ({
+				content: [{ type: "text" as const, text }],
+				details: { error: true },
+			});
+
+			// Validate session path
+			if (!sessionPath.endsWith(".jsonl")) {
+				return errorResult(
+					`Error: Invalid session path. Expected a .jsonl file, got: ${sessionPath}`,
+				);
+			}
+
+			// Check if file exists
+			if (!fs.existsSync(sessionPath)) {
+				return errorResult(`Error: Session file not found: ${sessionPath}`);
+			}
+
+			onUpdate?.({
+				content: [
+					{
+						type: "text",
+						text: `Querying session: ${question}`,
+					},
+				],
+				details: { status: "loading", question },
+			});
+
+			// Load the session
+			let sessionManager: SessionManager;
+			try {
+				sessionManager = SessionManager.open(sessionPath);
+			} catch (err) {
+				return errorResult(`Error loading session: ${err}`);
+			}
+
+			// Get conversation from the session
+			const branch = sessionManager.getBranch();
+			const messages = branch
+				.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
+				.map((entry) => entry.message);
+
+			if (messages.length === 0) {
+				return {
+					content: [{ type: "text" as const, text: "Session is empty - no messages found." }],
+					details: { empty: true },
+				};
+			}
+
+			// Serialize the conversation, truncating if too large
+			const llmMessages = convertToLlm(messages);
+			let conversationText = serializeConversation(llmMessages);
+			let truncated = false;
+
+			if (conversationText.length > MAX_SESSION_CHARS) {
+				// Keep the tail (most recent context) — more likely to be relevant
+				conversationText = "…[earlier messages truncated]…\n\n"
+					+ conversationText.slice(-MAX_SESSION_CHARS);
+				truncated = true;
+			}
+
+			// Use LLM to answer the question
+			if (!ctx.model) {
+				return errorResult("Error: No model available to analyze the session.");
+			}
+
+			try {
+				const apiKey = await ctx.modelRegistry.getApiKey(ctx.model);
+
+				const userMessage: Message = {
+					role: "user",
+					content: [
+						{
+							type: "text",
+							text: `## Session Conversation\n\n${conversationText}\n\n## Question\n\n${question}`,
+						},
+					],
+					timestamp: Date.now(),
+				};
+
+				const response = await complete(
+					ctx.model,
+					{ systemPrompt: QUERY_SYSTEM_PROMPT, messages: [userMessage] },
+					{ apiKey, signal },
+				);
+
+				if (response.stopReason === "aborted") {
+					return {
+						content: [{ type: "text" as const, text: "Query was cancelled." }],
+						details: { cancelled: true },
+					};
+				}
+
+				const answer = response.content
+					.filter((c): c is { type: "text"; text: string } => c.type === "text")
+					.map((c) => c.text)
+					.join("\n");
+
+				return {
+					content: [{ type: "text" as const, text: `**Query:** ${question}\n\n---\n\n${answer}` }],
+					details: {
+						sessionPath,
+						question,
+						messageCount: messages.length,
+						truncated,
+					},
+				};
+			} catch (err) {
+				return errorResult(`Error querying session: ${err}`);
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@ssweens/pi-handoff",
+  "version": "1.0.0",
+  "description": "Enhanced handoff extension for pi - context management for agentic coding workflows",
+  "keywords": [
+    "pi-package"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "ssweens",
+  "files": [
+    "extensions/",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "screenshot.png"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions"
+    ],
+    "skills": [
+      "skills"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  }
+}

package/skills/pi-session-query/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: pi-session-query
+description: Query previous pi sessions to retrieve context, decisions, code changes, or other information. Use when you need to look up what happened in a parent session or any other session file.
+disable-model-invocation: true
+---
+
+# Pi Session Query
+
+Query pi session files to retrieve context from past conversations.
+
+This skill is automatically invoked in handed-off sessions when you need to look up details from the parent session.
+
+## When to Use
+
+- When the handoff summary references a "Parent session" path
+- When you need specific details not included in the handoff summary
+- When you need to verify a decision or approach from the parent session
+- When you need file paths or code snippets from earlier work
+
+## Usage
+
+Use the `session_query` tool:
+
+```
+session_query(sessionPath, question)
+```
+
+**Parameters:**
+- `sessionPath`: Full path to the session file (provided in the "Parent session:" line)
+- `question`: Specific question about that session
+
+## Examples
+
+```typescript
+// Find what files were changed
+session_query("/path/to/session.jsonl", "What files were modified?")
+
+// Get approach details
+session_query("/path/to/session.jsonl", "What approach was chosen for authentication?")
+
+// Get specific code decisions
+session_query("/path/to/session.jsonl", "What error handling pattern was used?")
+
+// Summarize key decisions
+session_query("/path/to/session.jsonl", "Summarize the key decisions made")
+```
+
+## Best Practices
+
+1. **Be specific** - Ask targeted questions for better results
+2. **Reference code** - Ask about specific files or functions when relevant
+3. **Verify before assuming** - If the handoff summary seems incomplete, query for details
+4. **Don't over-query** - The handoff summary should have most context; query only when needed
+
+## How It Works
+
+The tool loads the referenced session file, extracts the conversation history, and uses the LLM to answer your question based on its contents. This allows context retrieval without loading the full parent session into your context window.