@dyyz1993/pi-coding-agent 0.70.5 → 0.74.4

package/docs/usage.md

@@ -0,0 +1,277 @@
+# Using Pi
+
+This page collects day-to-day usage details that do not fit on the quickstart page.
+
+## Interactive Mode
+
+<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
+
+The interface has four main areas:
+
+- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions
+- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
+- **Editor** - where you type; border color indicates the current thinking level
+- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model
+
+The editor can be replaced temporarily by built-in UI such as `/settings` or by custom extension UI.
+
+### Editor Features
+
+| Feature | How |
+|---------|-----|
+| File reference | Type `@` to fuzzy-search project files |
+| Path completion | Press Tab to complete paths |
+| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
+| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
+| Shell command | `!command` runs and sends output to the model |
+| Hidden shell command | `!!command` runs without sending output to the model |
+| External editor | Ctrl+G opens `$VISUAL` or `$EDITOR` |
+
+See [Keybindings](keybindings.md) for all shortcuts and customization.
+
+## Slash Commands
+
+Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
+
+| Command | Description |
+|---------|-------------|
+| `/login`, `/logout` | Manage OAuth or API-key credentials |
+| `/model` | Switch models |
+| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
+| `/settings` | Thinking level, theme, message delivery, transport |
+| `/resume` | Pick from previous sessions |
+| `/new` | Start a new session |
+| `/name <name>` | Set session display name |
+| `/session` | Show session file, ID, messages, tokens, and cost |
+| `/tree` | Jump to any point in the session and continue from there |
+| `/fork` | Create a new session from a previous user message |
+| `/clone` | Duplicate the current active branch into a new session |
+| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
+| `/copy` | Copy last assistant message to clipboard |
+| `/export [file]` | Export session to HTML |
+| `/share` | Upload as private GitHub gist with shareable HTML link |
+| `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
+| `/hotkeys` | Show all keyboard shortcuts |
+| `/changelog` | Display version history |
+| `/quit` | Quit pi |
+
+## Message Queue
+
+You can submit messages while the agent is still working:
+
+- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
+- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
+- **Escape** aborts and restores queued messages to the editor.
+- **Alt+Up** retrieves queued messages back to the editor.
+
+On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want pi to receive the shortcut.
+
+Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
+
+## Sessions
+
+Sessions are saved automatically to `~/.pi/agent/sessions/`, organized by working directory.
+
+```bash
+pi -c                  # Continue most recent session
+pi -r                  # Browse and select a session
+pi --no-session        # Ephemeral mode; do not save
+pi --session <path|id> # Use a specific session file or session ID
+pi --fork <path|id>    # Fork a session into a new session file
+```
+
+Useful session commands:
+
+- `/session` shows the current session file and ID.
+- `/tree` navigates the in-file session tree and can summarize abandoned branches.
+- `/fork` creates a new session from an earlier user message.
+- `/clone` duplicates the current active branch into a new session file.
+- `/compact` summarizes older messages to free context.
+
+See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
+
+## Context Files
+
+Pi loads `AGENTS.md` or `CLAUDE.md` at startup from:
+
+- `~/.pi/agent/AGENTS.md` for global instructions
+- parent directories, walking up from the current working directory
+- the current directory
+
+Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
+
+### System Prompt Files
+
+Replace the default system prompt with:
+
+- `.pi/SYSTEM.md` for a project
+- `~/.pi/agent/SYSTEM.md` globally
+
+Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
+
+## Exporting and Sharing Sessions
+
+Use `/export [file]` to write a session to HTML.
+
+Use `/share` to upload a private GitHub gist with a shareable HTML link.
+
+If you use pi for open source work and want to publish sessions for model, prompt, tool, and evaluation research, see [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). It publishes sessions to Hugging Face datasets.
+
+## CLI Reference
+
+```bash
+pi [options] [@files...] [messages...]
+```
+
+### Package Commands
+
+```bash
+pi install <source> [-l]     # Install package, -l for project-local
+pi remove <source> [-l]      # Remove package
+pi uninstall <source> [-l]   # Alias for remove
+pi update [source|self|pi]   # Update pi and packages; skips pinned packages
+pi update --extensions       # Update packages only
+pi update --self             # Update pi only
+pi update --extension <src>  # Update one package
+pi list                      # List installed packages
+pi config                    # Enable/disable package resources
+```
+
+See [Pi Packages](packages.md) for package sources and security notes.
+
+### Modes
+
+| Flag | Description |
+|------|-------------|
+| default | Interactive mode |
+| `-p`, `--print` | Print response and exit |
+| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
+| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
+| `--export <in> [out]` | Export a session to HTML |
+
+In print mode, pi also reads piped stdin and merges it into the initial prompt:
+
+```bash
+cat README.md | pi -p "Summarize this text"
+```
+
+### Model Options
+
+| Option | Description |
+|--------|-------------|
+| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
+| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
+| `--api-key <key>` | API key, overriding environment variables |
+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
+| `--list-models [search]` | List available models |
+
+### Session Options
+
+| Option | Description |
+|--------|-------------|
+| `-c`, `--continue` | Continue the most recent session |
+| `-r`, `--resume` | Browse and select a session |
+| `--session <path\|id>` | Use a specific session file or partial UUID |
+| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
+| `--session-dir <dir>` | Custom session storage directory |
+| `--no-session` | Ephemeral mode; do not save |
+
+### Tool Options
+
+| Option | Description |
+|--------|-------------|
+| `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
+| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
+| `--no-tools`, `-nt` | Disable all tools |
+
+Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
+
+### Resource Options
+
+| Option | Description |
+|--------|-------------|
+| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
+| `--no-extensions` | Disable extension discovery |
+| `--skill <path>` | Load a skill; repeatable |
+| `--no-skills` | Disable skill discovery |
+| `--prompt-template <path>` | Load a prompt template; repeatable |
+| `--no-prompt-templates` | Disable prompt template discovery |
+| `--theme <path>` | Load a theme; repeatable |
+| `--no-themes` | Disable theme discovery |
+| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
+
+Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
+
+```bash
+pi --no-extensions -e ./my-extension.ts
+```
+
+### Other Options
+
+| Option | Description |
+|--------|-------------|
+| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
+| `--append-system-prompt <text>` | Append to system prompt |
+| `--verbose` | Force verbose startup |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show version |
+
+### File Arguments
+
+Prefix files with `@` to include them in the message:
+
+```bash
+pi @prompt.md "Answer this"
+pi -p @screenshot.png "What's in this image?"
+pi @code.ts @test.ts "Review these files"
+```
+
+### Examples
+
+```bash
+# Interactive with initial prompt
+pi "List all .ts files in src/"
+
+# Non-interactive
+pi -p "Summarize this codebase"
+
+# Non-interactive with piped stdin
+cat README.md | pi -p "Summarize this text"
+
+# Different model
+pi --provider openai --model gpt-4o "Help me refactor"
+
+# Model with provider prefix
+pi --model openai/gpt-4o "Help me refactor"
+
+# Model with thinking level shorthand
+pi --model sonnet:high "Solve this complex problem"
+
+# Limit model cycling
+pi --models "claude-*,gpt-4o"
+
+# Read-only mode
+pi --tools read,grep,find,ls -p "Review the code"
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PI_CODING_AGENT_DIR` | Override config directory; default is `~/.pi/agent` |
+| `PI_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
+| `PI_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
+| `PI_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
+| `PI_SKIP_VERSION_CHECK` | Skip the Pi version update check at startup. This prevents the `pi.dev` latest-version request |
+| `PI_TELEMETRY` | Override install/update telemetry: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
+| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
+| `VISUAL`, `EDITOR` | External editor for Ctrl+G |
+
+## Design Principles
+
+Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
+
+It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
+
+For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).

package/examples/extensions/README.md

@@ -38,7 +38,6 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `built-in-tool-renderer.ts` | Custom compact rendering for built-in tools (read, bash, edit, write) while keeping original behavior |
 | `minimal-mode.ts` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |
 | `truncated-tool.ts` | Wraps ripgrep with proper output truncation (50KB/2000 lines) |
-| `antigravity-image-gen.ts` | Generate images via Google Antigravity with optional save-to-disk modes |
 | `ssh.ts` | Delegate all tools to a remote machine via SSH using pluggable operations |
 | `subagent/` | Delegate tasks to specialized subagents with isolated context windows |
 
@@ -126,7 +125,6 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 |-----------|-------------|
 | `custom-provider-anthropic/` | Custom Anthropic provider with OAuth support and custom streaming implementation |
 | `custom-provider-gitlab-duo/` | GitLab Duo provider using pi-ai's built-in Anthropic/OpenAI streaming via proxy |
-| `custom-provider-qwen-cli/` | Qwen CLI provider with OAuth device flow and OpenAI-compatible models |
 
 ### External Dependencies
 
@@ -140,7 +138,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 See [docs/extensions.md](../../docs/extensions.md) for full documentation.
 
 ```typescript
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@dyyz1993/pi-coding-agent";
 import { Type } from "typebox";
 
 export default function (pi: ExtensionAPI) {
@@ -182,7 +180,7 @@ export default function (pi: ExtensionAPI) {
 
 **Use StringEnum for string parameters** (required for Google API compatibility):
 ```typescript
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@dyyz1993/pi-ai";
 
 // Good
 action: StringEnum(["list", "add"] as const)

package/examples/extensions/border-status-editor.ts

@@ -0,0 +1,150 @@
+import {
+	CustomEditor,
+	type ExtensionAPI,
+	type ExtensionContext,
+	type KeybindingsManager,
+} from "@dyyz1993/pi-coding-agent";
+import type { Component, EditorTheme, TUI } from "@dyyz1993/pi-tui";
+import { truncateToWidth, visibleWidth } from "@dyyz1993/pi-tui";
+
+function fitBorder(
+	left: string,
+	right: string,
+	width: number,
+	border: (text: string) => string,
+	fill: (text: string) => string = border,
+): string {
+	if (width <= 0) return "";
+	if (width === 1) return border("─");
+
+	let leftText = left;
+	let rightText = right;
+	const fixedWidth = 2;
+	const minimumGap = 3;
+
+	while (
+		fixedWidth + visibleWidth(leftText) + visibleWidth(rightText) + minimumGap > width &&
+		visibleWidth(rightText) > 0
+	) {
+		rightText = truncateToWidth(rightText, Math.max(0, visibleWidth(rightText) - 1), "");
+	}
+	while (
+		fixedWidth + visibleWidth(leftText) + visibleWidth(rightText) + minimumGap > width &&
+		visibleWidth(leftText) > 0
+	) {
+		leftText = truncateToWidth(leftText, Math.max(0, visibleWidth(leftText) - 1), "");
+	}
+
+	const gapWidth = Math.max(0, width - fixedWidth - visibleWidth(leftText) - visibleWidth(rightText));
+	return `${border("─")}${leftText}${fill("─".repeat(gapWidth))}${rightText}${border("─")}`;
+}
+
+function formatCwd(cwd: string): string {
+	const home = process.env.HOME;
+	if (home && cwd.startsWith(home)) {
+		return `~${cwd.slice(home.length)}`;
+	}
+	return cwd;
+}
+
+function formatContext(ctx: ExtensionContext): string {
+	const usage = ctx.getContextUsage();
+	const contextWindow = usage?.contextWindow ?? ctx.model?.contextWindow;
+	if (!contextWindow || !usage || usage.percent === null) {
+		return "ctx ?";
+	}
+	return `ctx ${Math.round(usage.percent)}%/${(contextWindow / 1000).toFixed(0)}k`;
+}
+
+function formatThinking(level: string): string {
+	return level === "off" ? "off" : level;
+}
+
+class EmptyFooter implements Component {
+	render(): string[] {
+		return [];
+	}
+
+	invalidate(): void {}
+}
+
+export default function (pi: ExtensionAPI) {
+	let isWorking = false;
+	let spinnerIndex = 0;
+	let spinnerTimer: ReturnType<typeof setInterval> | undefined;
+	let activeTui: TUI | undefined;
+	const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+	const stopSpinner = () => {
+		if (spinnerTimer) {
+			clearInterval(spinnerTimer);
+			spinnerTimer = undefined;
+		}
+	};
+
+	pi.on("agent_start", () => {
+		isWorking = true;
+		stopSpinner();
+		spinnerTimer = setInterval(() => {
+			spinnerIndex = (spinnerIndex + 1) % spinnerFrames.length;
+			activeTui?.requestRender();
+		}, 80);
+		activeTui?.requestRender();
+	});
+
+	pi.on("agent_end", () => {
+		isWorking = false;
+		stopSpinner();
+		activeTui?.requestRender();
+	});
+
+	pi.on("session_shutdown", () => {
+		stopSpinner();
+		activeTui = undefined;
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		ctx.ui.setWorkingVisible(false);
+		ctx.ui.setFooter(() => new EmptyFooter());
+
+		let branch: string | undefined;
+
+		const refreshBranch = async () => {
+			const result = await pi.exec("git", ["branch", "--show-current"], { cwd: ctx.cwd }).catch(() => undefined);
+			const stdout = result?.stdout.trim();
+			branch = stdout && stdout.length > 0 ? stdout : undefined;
+			activeTui?.requestRender();
+		};
+		void refreshBranch();
+
+		class BorderStatusEditor extends CustomEditor {
+			constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) {
+				super(tui, theme, keybindings, { paddingX: 0 });
+				activeTui = tui;
+			}
+
+			render(width: number): string[] {
+				const lines = super.render(width);
+				if (lines.length < 2) return lines;
+
+				const thm = ctx.ui.theme;
+				const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "no model";
+				const thinking = pi.getThinkingLevel();
+				const topLeft = isWorking ? thm.fg("accent", ` ${spinnerFrames[spinnerIndex]} `) : "";
+				const topRight = "";
+				const bottomLeft = thm.fg("muted", ` ${model} · ${formatThinking(thinking)} `);
+				const bottomRight = thm.fg(
+					"muted",
+					` ${formatContext(ctx)} · ${formatCwd(ctx.cwd)}${branch ? ` (${branch})` : ""} `,
+				);
+				const borderColor = (text: string) => this.borderColor(text);
+
+				lines[0] = fitBorder(topLeft, topRight, width, borderColor);
+				lines[lines.length - 1] = fitBorder(bottomLeft, bottomRight, width, borderColor);
+				return lines;
+			}
+		}
+
+		ctx.ui.setEditorComponent((tui, theme, keybindings) => new BorderStatusEditor(tui, theme, keybindings));
+	});
+}

package/examples/extensions/commands.ts

@@ -57,8 +57,8 @@ export default function commandsExtension(pi: ExtensionAPI) {
 			const selected = await ctx.ui.select("Available Commands", items);
 
 			// If user selected a command (not a header), offer to show its path
-			if (selected && !selected.startsWith("---")) {
-				const cmdName = selected.split(" - ")[0].slice(1); // Remove leading /
+			if (selected && typeof selected === "string" && !selected.startsWith("---")) {
+				const cmdName = selected.split(" - ")[0].slice(1);
 				const cmd = commands.find((c) => c.name === cmdName);
 				if (cmd?.sourceInfo.path) {
 					const showPath = await ctx.ui.confirm(cmd.name, `View source path?\n${cmd.sourceInfo.path}`);

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.69.25",
+  "version": "0.74.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.69.25",
+      "version": "0.74.4",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.69.25",
+  "version": "0.74.4",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.69.25",
+  "version": "0.74.4",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-qwen-cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-qwen-cli",
   "private": true,
-  "version": "0.69.25",
+  "version": "0.69.26",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/dynamic-resources/dynamic.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+	"$schema": "https://raw.githubusercontent.com/dyyz1993/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
 	"name": "dynamic-resources",
 	"vars": {
 		"cyan": "#00d7ff",

package/examples/extensions/git-checkpoint.ts

@@ -40,7 +40,7 @@ export default function (pi: ExtensionAPI) {
 			"No, keep current code",
 		]);
 
-		if (choice?.startsWith("Yes")) {
+		if (typeof choice === "string" && choice.startsWith("Yes")) {
 			await pi.exec("git", ["stash", "apply", ref]);
 			ctx.ui.notify("Code restored to checkpoint", "info");
 		}

package/examples/extensions/handoff.ts

@@ -12,6 +12,7 @@
  * The generated prompt appears as a draft in the editor for review/editing.
  */
 
+import type { AgentMessage } from "@dyyz1993/pi-agent-core";
 import { complete, type Message } from "@dyyz1993/pi-ai";
 import type { ExtensionAPI, SessionEntry } from "@dyyz1993/pi-coding-agent";
 import { BorderedLoader, convertToLlm, serializeConversation } from "@dyyz1993/pi-coding-agent";
@@ -38,6 +39,44 @@ Files involved:
 ## Task
 [Clear description of what to do next based on user's goal]`;
 
+function entryToMessage(entry: SessionEntry): AgentMessage | undefined {
+	if (entry.type === "message") {
+		return entry.message;
+	}
+	if (entry.type === "compaction") {
+		return {
+			role: "compactionSummary",
+			summary: entry.summary,
+			tokensBefore: entry.tokensBefore,
+			timestamp: new Date(entry.timestamp).getTime(),
+		};
+	}
+	return undefined;
+}
+
+function getHandoffMessages(branch: SessionEntry[]): AgentMessage[] {
+	let compactionIndex = -1;
+	for (let i = branch.length - 1; i >= 0; i--) {
+		if (branch[i].type === "compaction") {
+			compactionIndex = i;
+			break;
+		}
+	}
+	if (compactionIndex < 0) {
+		return branch.map(entryToMessage).filter((message) => message !== undefined);
+	}
+
+	const compaction = branch[compactionIndex];
+	const firstKeptIndex =
+		compaction.type === "compaction" ? branch.findIndex((entry) => entry.id === compaction.firstKeptEntryId) : -1;
+	const compactedBranch = [
+		compaction,
+		...(firstKeptIndex >= 0 ? branch.slice(firstKeptIndex, compactionIndex) : []),
+		...branch.slice(compactionIndex + 1),
+	];
+	return compactedBranch.map(entryToMessage).filter((message) => message !== undefined);
+}
+
 export default function (pi: ExtensionAPI) {
 	pi.registerCommand("handoff", {
 		description: "Transfer context to a new focused session",
@@ -58,11 +97,9 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			// Gather conversation context from current branch
-			const branch = ctx.sessionManager.getBranch();
-			const messages = branch
-				.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
-				.map((entry) => entry.message);
+			// Gather conversation context from current branch. If the branch was compacted,
+			// include the compaction summary plus entries from firstKeptEntryId onward.
+			const messages = getHandoffMessages(ctx.sessionManager.getBranch());
 
 			if (messages.length === 0) {
 				ctx.ui.notify("No conversation to hand off", "error");
@@ -135,19 +172,20 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			// Create new session with parent tracking
+			// Create new session with parent tracking. Use the replacement-session
+			// context for post-switch UI work; the original ctx is stale after a
+			// successful session replacement.
 			const newSessionResult = await ctx.newSession({
 				parentSession: currentSessionFile,
+				withSession: async (replacementCtx) => {
+					replacementCtx.ui.setEditorText(editedPrompt);
+					replacementCtx.ui.notify("Handoff ready. Submit when ready.", "info");
+				},
 			});
 
 			if (newSessionResult.cancelled) {
 				ctx.ui.notify("New session cancelled", "info");
-				return;
 			}
-
-			// Set the edited prompt in the main editor for submission
-			ctx.ui.setEditorText(editedPrompt);
-			ctx.ui.notify("Handoff ready. Submit when ready.", "info");
 		},
 	});
 }

package/examples/extensions/plan-mode/index.ts

@@ -265,7 +265,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
 			"Refine the plan",
 		]);
 
-		if (choice?.startsWith("Execute")) {
+		if (typeof choice === "string" && choice.startsWith("Execute")) {
 			planModeEnabled = false;
 			executionMode = todoItems.length > 0;
 			pi.setActiveTools(NORMAL_MODE_TOOLS);

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "1.0.0",
+	"version": "1.4.4",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "1.0.0",
+			"version": "1.4.4",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}
@@ -62,9 +62,9 @@
 			}
 		},
 		"node_modules/lodash-es": {
-			"version": "4.17.22",
-			"resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.22.tgz",
-			"integrity": "sha512-XEawp1t0gxSi9x01glktRZ5HDy0HXqrM0x5pXQM98EaI0NxO6jVM7omDOxsuEo5UIASAnm2bRp1Jt/e0a2XU8Q==",
+			"version": "4.18.1",
+			"resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.18.1.tgz",
+			"integrity": "sha512-J8xewKD/Gk22OZbhpOVSwcs60zhd95ESDwezOFuA3/099925PdHJ7OFHNTGtajL3AlZkykD32HykiMo+BIBI8A==",
 			"license": "MIT"
 		},
 		"node_modules/shell-quote": {

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "1.0.0",
+	"version": "1.4.4",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",