@oh-my-pi/pi-coding-agent 5.5.0 → 5.6.7

package/src/modes/interactive/controllers/input-controller.ts

@@ -59,16 +59,28 @@ export class InputController {
 		this.ctx.ui.onDebug = () => this.ctx.handleDebugCommand();
 		this.ctx.editor.onCtrlL = () => this.ctx.showModelSelector();
 		this.ctx.editor.onCtrlR = () => this.ctx.showHistorySearch();
-		this.ctx.editor.onCtrlO = () => this.toggleToolOutputExpansion();
 		this.ctx.editor.onCtrlT = () => this.ctx.toggleTodoExpansion();
 		this.ctx.editor.onCtrlG = () => this.openExternalEditor();
 		this.ctx.editor.onQuestionMark = () => this.ctx.handleHotkeysCommand();
 		this.ctx.editor.onCtrlV = () => this.handleImagePaste();
-		this.ctx.editor.onAltUp = () => this.handleDequeue();
 
 		// Wire up extension shortcuts
 		this.registerExtensionShortcuts();
 
+		const expandToolsKeys = this.ctx.keybindings.getKeys("expandTools");
+		this.ctx.editor.onCtrlO = expandToolsKeys.includes("ctrl+o") ? () => this.toggleToolOutputExpansion() : undefined;
+		for (const key of expandToolsKeys) {
+			if (key === "ctrl+o") continue;
+			this.ctx.editor.setCustomKeyHandler(key, () => this.toggleToolOutputExpansion());
+		}
+
+		const dequeueKeys = this.ctx.keybindings.getKeys("dequeue");
+		this.ctx.editor.onAltUp = dequeueKeys.includes("alt+up") ? () => this.handleDequeue() : undefined;
+		for (const key of dequeueKeys) {
+			if (key === "alt+up") continue;
+			this.ctx.editor.setCustomKeyHandler(key, () => this.handleDequeue());
+		}
+
 		this.ctx.editor.onChange = (text: string) => {
 			const wasBashMode = this.ctx.isBashMode;
 			this.ctx.isBashMode = text.trimStart().startsWith("!");
@@ -122,13 +134,33 @@ export class InputController {
 
 			if (!text) return;
 
+			const runner = this.ctx.session.extensionRunner;
+			let inputImages = this.ctx.pendingImages.length > 0 ? [...this.ctx.pendingImages] : undefined;
+
+			if (runner?.hasHandlers("input")) {
+				const result = await runner.emitInput(text, inputImages, "interactive");
+				if (result?.handled) {
+					this.ctx.editor.setText("");
+					this.ctx.pendingImages = [];
+					return;
+				}
+				if (result?.text !== undefined) {
+					text = result.text.trim();
+				}
+				if (result?.images !== undefined) {
+					inputImages = result.images;
+				}
+			}
+
+			if (!text) return;
+
 			// Handle slash commands
 			if (text === "/settings") {
 				this.ctx.showSettingsSelector();
 				this.ctx.editor.setText("");
 				return;
 			}
-			if (text === "/model") {
+			if (text === "/model" || text === "/models") {
 				this.ctx.showModelSelector();
 				this.ctx.editor.setText("");
 				return;
@@ -246,7 +278,11 @@ export class InputController {
 					try {
 						const content = fs.readFileSync(skillPath, "utf-8");
 						const body = content.replace(/^---\n[\s\S]*?\n---\n/, "").trim();
-						const message = args ? `${body}\n\n---\n\nUser: ${args}` : body;
+						const metaLines = [`Skill: ${skillPath}`];
+						if (args) {
+							metaLines.push(`User: ${args}`);
+						}
+						const message = `${body}\n\n---\n\n${metaLines.join("\n")}`;
 						await this.ctx.session.prompt(message);
 					} catch (err) {
 						this.ctx.showError(`Failed to load skill: ${err instanceof Error ? err.message : String(err)}`);
@@ -288,7 +324,7 @@ export class InputController {
 			if (this.ctx.session.isStreaming) {
 				this.ctx.editor.addToHistory(text);
 				this.ctx.editor.setText("");
-				const images = this.ctx.pendingImages.length > 0 ? [...this.ctx.pendingImages] : undefined;
+				const images = inputImages && inputImages.length > 0 ? [...inputImages] : undefined;
 				this.ctx.pendingImages = [];
 				await this.ctx.session.prompt(text, { streamingBehavior: "steer", images });
 				this.ctx.updatePendingMessagesDisplay();
@@ -317,7 +353,7 @@ export class InputController {
 
 			if (this.ctx.onInputCallback) {
 				// Include any pending images from clipboard paste
-				const images = this.ctx.pendingImages.length > 0 ? [...this.ctx.pendingImages] : undefined;
+				const images = inputImages && inputImages.length > 0 ? [...inputImages] : undefined;
 				this.ctx.pendingImages = [];
 				this.ctx.onInputCallback({ text, images });
 			}

package/src/modes/interactive/interactive-mode.ts

@@ -19,8 +19,9 @@ import {
 import chalk from "chalk";
 import type { AgentSession, AgentSessionEvent } from "../../core/agent-session";
 import type { ExtensionUIContext } from "../../core/extensions/index";
+import type { CompactOptions } from "../../core/extensions/types";
 import { HistoryStorage } from "../../core/history-storage";
-import type { KeybindingsManager } from "../../core/keybindings";
+import { KeybindingsManager } from "../../core/keybindings";
 import { logger } from "../../core/logger";
 import type { SessionContext, SessionManager } from "../../core/session-manager";
 import { getRecentSessions } from "../../core/session-manager";
@@ -71,6 +72,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	public session: AgentSession;
 	public sessionManager: SessionManager;
 	public settingsManager: SettingsManager;
+	public keybindings: KeybindingsManager;
 	public agent: AgentSession["agent"];
 	public voiceSupervisor: VoiceSupervisor;
 	public historyStorage?: HistoryStorage;
@@ -126,8 +128,9 @@ export class InteractiveMode implements InteractiveModeContext {
 	private cleanupUnsubscribe?: () => void;
 	private readonly version: string;
 	private readonly changelogMarkdown: string | undefined;
-	private readonly lspServers: Array<{ name: string; status: "ready" | "error"; fileTypes: string[] }> | undefined =
+	public readonly lspServers: Array<{ name: string; status: "ready" | "error"; fileTypes: string[] }> | undefined =
 		undefined;
+	public mcpManager?: import("../../core/mcp/index").MCPManager;
 	private readonly toolUiContextSetter: (uiContext: ExtensionUIContext, hasUI: boolean) => void;
 
 	private readonly commandController: CommandController;
@@ -144,23 +147,25 @@ export class InteractiveMode implements InteractiveModeContext {
 		changelogMarkdown: string | undefined = undefined,
 		setToolUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void = () => {},
 		lspServers: Array<{ name: string; status: "ready" | "error"; fileTypes: string[] }> | undefined = undefined,
+		mcpManager?: import("../../core/mcp/index").MCPManager,
 	) {
 		this.session = session;
 		this.sessionManager = session.sessionManager;
 		this.settingsManager = session.settingsManager;
+		this.keybindings = KeybindingsManager.inMemory();
 		this.agent = session.agent;
 		this.version = version;
 		this.changelogMarkdown = changelogMarkdown;
 		this.toolUiContextSetter = setToolUIContext;
 		this.lspServers = lspServers;
+		this.mcpManager = mcpManager;
 
-		this.ui = new TUI(new ProcessTerminal());
+		this.ui = new TUI(new ProcessTerminal(), this.settingsManager.getShowHardwareCursor());
 		this.chatContainer = new Container();
 		this.pendingMessagesContainer = new Container();
 		this.statusContainer = new Container();
 		this.todoContainer = new Container();
 		this.editor = new CustomEditor(getEditorTheme());
-		this.editor.setUseTerminalCursor(true);
 		this.editor.onAutocompleteCancel = () => {
 			this.ui.requestRender(true);
 		};
@@ -226,6 +231,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		const hookCommands: SlashCommand[] = (this.session.extensionRunner?.getRegisteredCommands() ?? []).map((cmd) => ({
 			name: cmd.name,
 			description: cmd.description ?? "(hook command)",
+			getArgumentCompletions: cmd.getArgumentCompletions,
 		}));
 
 		// Convert custom commands (TypeScript) to SlashCommand format
@@ -259,6 +265,8 @@ export class InteractiveMode implements InteractiveModeContext {
 	async init(): Promise<void> {
 		if (this.isInitialized) return;
 
+		this.keybindings = await KeybindingsManager.create();
+
 		// Register session manager flush for signal handlers (SIGINT, SIGTERM, SIGHUP)
 		this.cleanupUnsubscribe = registerAsyncCleanup(() => this.sessionManager.flush());
 
@@ -295,8 +303,34 @@ export class InteractiveMode implements InteractiveModeContext {
 				fileTypes: s.fileTypes,
 			})) ?? [];
 
-		// Add welcome header
-		const welcome = new WelcomeComponent(this.version, modelName, providerName, recentSessions, lspServerInfo);
+		const startupQuiet = this.settingsManager.getStartupQuiet();
+
+		if (!startupQuiet) {
+			// Add welcome header
+			const welcome = new WelcomeComponent(this.version, modelName, providerName, recentSessions, lspServerInfo);
+
+			// Setup UI layout
+			this.ui.addChild(new Spacer(1));
+			this.ui.addChild(welcome);
+			this.ui.addChild(new Spacer(1));
+
+			// Add changelog if provided
+			if (this.changelogMarkdown) {
+				this.ui.addChild(new DynamicBorder());
+				if (this.settingsManager.getCollapseChangelog()) {
+					const versionMatch = this.changelogMarkdown.match(/##\s+\[?(\d+\.\d+\.\d+)\]?/);
+					const latestVersion = versionMatch ? versionMatch[1] : this.version;
+					const condensedText = `Updated to v${latestVersion}. Use ${theme.bold("/changelog")} to view full changelog.`;
+					this.ui.addChild(new Text(condensedText, 1, 0));
+				} else {
+					this.ui.addChild(new Text(theme.bold(theme.fg("accent", "What's New")), 1, 0));
+					this.ui.addChild(new Spacer(1));
+					this.ui.addChild(new Markdown(this.changelogMarkdown.trim(), 1, 0, getMarkdownTheme()));
+					this.ui.addChild(new Spacer(1));
+				}
+				this.ui.addChild(new DynamicBorder());
+			}
+		}
 
 		// Set terminal title if session already has one (resumed session)
 		const existingTitle = this.sessionManager.getSessionTitle();
@@ -304,28 +338,6 @@ export class InteractiveMode implements InteractiveModeContext {
 			setTerminalTitle(`pi: ${existingTitle}`);
 		}
 
-		// Setup UI layout
-		this.ui.addChild(new Spacer(1));
-		this.ui.addChild(welcome);
-		this.ui.addChild(new Spacer(1));
-
-		// Add changelog if provided
-		if (this.changelogMarkdown) {
-			this.ui.addChild(new DynamicBorder());
-			if (this.settingsManager.getCollapseChangelog()) {
-				const versionMatch = this.changelogMarkdown.match(/##\s+\[?(\d+\.\d+\.\d+)\]?/);
-				const latestVersion = versionMatch ? versionMatch[1] : this.version;
-				const condensedText = `Updated to v${latestVersion}. Use ${theme.bold("/changelog")} to view full changelog.`;
-				this.ui.addChild(new Text(condensedText, 1, 0));
-			} else {
-				this.ui.addChild(new Text(theme.bold(theme.fg("accent", "What's New")), 1, 0));
-				this.ui.addChild(new Spacer(1));
-				this.ui.addChild(new Markdown(this.changelogMarkdown.trim(), 1, 0, getMarkdownTheme()));
-				this.ui.addChild(new Spacer(1));
-			}
-			this.ui.addChild(new DynamicBorder());
-		}
-
 		this.ui.addChild(this.chatContainer);
 		this.ui.addChild(this.pendingMessagesContainer);
 		this.ui.addChild(this.statusContainer);
@@ -344,6 +356,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		// Start the UI
 		this.ui.start();
 		this.isInitialized = true;
+		this.ui.requestRender(true);
 
 		// Set initial terminal title (will be updated when session title is generated)
 		this.ui.terminal.setTitle("π");
@@ -369,6 +382,15 @@ export class InteractiveMode implements InteractiveModeContext {
 
 		// Initial top border update
 		this.updateEditorTopBorder();
+
+		if (!startupQuiet) {
+			const templateNames = this.session.promptTemplates.map((template) => template.name).sort();
+			if (templateNames.length > 0) {
+				const preview = templateNames.slice(0, 3).join(", ");
+				const suffix = templateNames.length > 3 ? ` +${templateNames.length - 3} more` : "";
+				this.showStatus(`Loaded prompt templates: ${preview}${suffix}`);
+			}
+		}
 	}
 
 	async getUserInput(): Promise<{ text: string; images?: ImageContent[] }> {
@@ -510,6 +532,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		// Emit shutdown event to hooks
 		await this.session.emitCustomToolSessionEvent("shutdown");
 
+		if (this.isInitialized) {
+			await this.ui.waitForRender();
+		}
+
 		this.stop();
 		process.exit(0);
 	}
@@ -654,8 +680,8 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.commandController.handleCompactCommand(customInstructions);
 	}
 
-	executeCompaction(customInstructions?: string, isAuto?: boolean): Promise<void> {
-		return this.commandController.executeCompaction(customInstructions, isAuto);
+	executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<void> {
+		return this.commandController.executeCompaction(customInstructionsOrOptions, isAuto);
 	}
 
 	openInBrowser(urlOrPath: string): void {

package/src/modes/interactive/theme/theme-schema.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "http://json-schema.org/draft-07/schema#",
-	"title": "Pi Coding Agent Theme",
-	"description": "Theme schema for OMP coding agent",
+	"title": "OMP Coding Agent Theme",
+	"description": "Theme schema for the OMP coding agent",
 	"type": "object",
 	"required": ["name", "colors"],
 	"properties": {

package/src/modes/interactive/types.ts

@@ -3,8 +3,10 @@ import type { AssistantMessage, ImageContent, Message } from "@oh-my-pi/pi-ai";
 import type { Component, Container, Loader, Spacer, Text, TUI } from "@oh-my-pi/pi-tui";
 import type { AgentSession, AgentSessionEvent } from "../../core/agent-session";
 import type { ExtensionUIContext } from "../../core/extensions/index";
+import type { CompactOptions } from "../../core/extensions/types";
 import type { HistoryStorage } from "../../core/history-storage";
 import type { KeybindingsManager } from "../../core/keybindings";
+import type { MCPManager } from "../../core/mcp/index";
 import type { SessionContext, SessionManager } from "../../core/session-manager";
 import type { SettingsManager } from "../../core/settings-manager";
 import type { VoiceSupervisor } from "../../core/voice-supervisor";
@@ -45,9 +47,12 @@ export interface InteractiveModeContext {
 	session: AgentSession;
 	sessionManager: SessionManager;
 	settingsManager: SettingsManager;
+	keybindings: KeybindingsManager;
 	agent: AgentSession["agent"];
 	voiceSupervisor: VoiceSupervisor;
 	historyStorage?: HistoryStorage;
+	mcpManager?: MCPManager;
+	lspServers?: Array<{ name: string; status: "ready" | "error"; fileTypes: string[] }>;
 
 	// State
 	isInitialized: boolean;
@@ -140,7 +145,7 @@ export interface InteractiveModeContext {
 	handleArminSaysHi(): void;
 	handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;
 	handleCompactCommand(customInstructions?: string): Promise<void>;
-	executeCompaction(customInstructions?: string, isAuto?: boolean): Promise<void>;
+	executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<void>;
 	openInBrowser(urlOrPath: string): void;
 
 	// Selector handling

package/src/modes/interactive/utils/ui-helpers.ts

@@ -340,7 +340,8 @@ export class UiHelpers {
 				const queuedText = theme.fg("dim", `${entry.label}: ${entry.message}`);
 				this.ctx.pendingMessagesContainer.addChild(new TruncatedText(queuedText, 1, 0));
 			}
-			const hintText = theme.fg("dim", `${theme.tree.hook} Alt+Up to edit`);
+			const dequeueKey = this.ctx.keybindings.getDisplayString("dequeue") || "Alt+Up";
+			const hintText = theme.fg("dim", `${theme.tree.hook} ${dequeueKey} to edit`);
 			this.ctx.pendingMessagesContainer.addChild(new TruncatedText(hintText, 1, 0));
 		}
 	}

package/src/modes/print-mode.ts

@@ -58,6 +58,9 @@ export async function runPrintMode(session: AgentSession, options: PrintModeOpti
 				appendEntry: (customType, data) => {
 					session.sessionManager.appendCustomEntry(customType, data);
 				},
+				setLabel: (targetId, label) => {
+					session.sessionManager.appendLabelChange(targetId, label);
+				},
 				getActiveTools: () => session.getActiveToolNames(),
 				getAllTools: () => session.getAllToolNames(),
 				setActiveTools: (toolNames: string[]) => session.setActiveToolsByName(toolNames),
@@ -77,9 +80,19 @@ export async function runPrintMode(session: AgentSession, options: PrintModeOpti
 				abort: () => session.abort(),
 				hasPendingMessages: () => session.queuedMessageCount > 0,
 				shutdown: () => {},
+				getContextUsage: () => session.getContextUsage(),
+				compact: async (instructionsOrOptions) => {
+					const instructions = typeof instructionsOrOptions === "string" ? instructionsOrOptions : undefined;
+					const options =
+						instructionsOrOptions && typeof instructionsOrOptions === "object"
+							? instructionsOrOptions
+							: undefined;
+					await session.compact(instructions, options);
+				},
 			},
 			// ExtensionCommandContextActions - commands invokable via prompt("/command")
 			{
+				getContextUsage: () => session.getContextUsage(),
 				waitForIdle: () => session.agent.waitForIdle(),
 				newSession: async (options) => {
 					const success = await session.newSession({ parentSession: options?.parentSession });
@@ -96,6 +109,14 @@ export async function runPrintMode(session: AgentSession, options: PrintModeOpti
 					const result = await session.navigateTree(targetId, { summarize: options?.summarize });
 					return { cancelled: result.cancelled };
 				},
+				compact: async (instructionsOrOptions) => {
+					const instructions = typeof instructionsOrOptions === "string" ? instructionsOrOptions : undefined;
+					const options =
+						instructionsOrOptions && typeof instructionsOrOptions === "object"
+							? instructionsOrOptions
+							: undefined;
+					await session.compact(instructions, options);
+				},
 			},
 			// No UI context
 		);
@@ -157,4 +178,6 @@ export async function runPrintMode(session: AgentSession, options: PrintModeOpti
 			else resolve();
 		});
 	});
+
+	await session.dispose();
 }

package/src/modes/rpc/rpc-mode.ts

@@ -289,6 +289,9 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 				appendEntry: (customType, data) => {
 					session.sessionManager.appendCustomEntry(customType, data);
 				},
+				setLabel: (targetId, label) => {
+					session.sessionManager.appendLabelChange(targetId, label);
+				},
 				getActiveTools: () => session.getActiveToolNames(),
 				getAllTools: () => session.getAllToolNames(),
 				setActiveTools: (toolNames: string[]) => session.setActiveToolsByName(toolNames),
@@ -310,9 +313,19 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 				shutdown: () => {
 					shutdownState.requested = true;
 				},
+				getContextUsage: () => session.getContextUsage(),
+				compact: async (instructionsOrOptions) => {
+					const instructions = typeof instructionsOrOptions === "string" ? instructionsOrOptions : undefined;
+					const options =
+						instructionsOrOptions && typeof instructionsOrOptions === "object"
+							? instructionsOrOptions
+							: undefined;
+					await session.compact(instructions, options);
+				},
 			},
 			// ExtensionCommandContextActions - commands invokable via prompt("/command")
 			{
+				getContextUsage: () => session.getContextUsage(),
 				waitForIdle: () => session.agent.waitForIdle(),
 				newSession: async (options) => {
 					const success = await session.newSession({ parentSession: options?.parentSession });
@@ -330,6 +343,14 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 					const result = await session.navigateTree(targetId, { summarize: options?.summarize });
 					return { cancelled: result.cancelled };
 				},
+				compact: async (instructionsOrOptions) => {
+					const instructions = typeof instructionsOrOptions === "string" ? instructionsOrOptions : undefined;
+					const options =
+						instructionsOrOptions && typeof instructionsOrOptions === "object"
+							? instructionsOrOptions
+							: undefined;
+					await session.compact(instructions, options);
+				},
 			},
 			createExtensionUIContext(),
 		);

package/src/prompts/agents/reviewer.md

@@ -43,7 +43,7 @@ You are a senior engineer reviewing a proposed code change. Your goal: identify
 4. Call `report_finding` for each issue
 5. Call `complete` with your verdict — **review is incomplete until `complete` is called**
 
-Bash is read-only: `git diff`, `git log`, `git show`, `gh pr diff`. No file modifications or builds.
+Bash is read-only here: `git diff`, `git log`, `git show`, `gh pr diff`. No file modifications or builds.
 
 # What to Flag
 

package/src/prompts/system/system-prompt.md

@@ -67,6 +67,7 @@ This matters. Get it right.
 
 Every tool is a choice. The wrong choice is friction. The right choice is invisible.
 
+{{#has tools "bash"}}
 ### What bash IS for
 File and system operations:
 - `mv`, `cp`, `rm`, `ln -s` — moving, copying, deleting, symlinking
@@ -95,6 +96,35 @@ Specialized tools exist. Use them.
 {{#has tools "edit"}}- Content-addressed edits: `edit` finds text. Use bash for position/pattern (append, line N, regex).{{/has}}
 {{#has tools "git"}}- Git operations: `git` tool has guards. Bash git has none.{{/has}}
 
+{{/has}}
+
+{{#has tools "python"}}
+### What python IS for
+Python is your scripting language. Bash is for build tools and system commands only.
+
+**Use Python for:**
+- Loops, conditionals, any multi-step logic
+- Text processing (sorting, filtering, column extraction, regex)
+- File operations (copy, move, concat, batch transforms)
+- Displaying content to the user
+- Anything you'd write a bash script for
+
+**Use bash only for:**
+- Build commands: `cargo`, `npm`, `make`, `docker`
+- Git operations (when git tool unavailable)
+- System commands with no Python equivalent
+
+The prelude provides shell-like helpers: `cat()`, `sed()`, `rsed()`, `find()`, `grep()`, `batch()`.
+Do not write bash loops, sed pipelines, or awk scripts. Write Python.
+
+### Python for user-facing output
+When the user asks you to display, concatenate, merge, or transform content:
+→ Python. One operation. Clean output.
+
+Do not read files individually just to print them back. That's mechanical and wasteful.
+Read/grep are for YOUR reconnaissance. Python is for THE USER's request.
+{{/has}}
+
 ### Hierarchy of trust
 The most constrained tool is the most trustworthy.
 
@@ -104,7 +134,8 @@ The most constrained tool is the most trustworthy.
 {{#has tools "read"}}4. **read** — content truth{{/has}}
 {{#has tools "edit"}}5. **edit** — surgical change{{/has}}
 {{#has tools "git"}}6. **git** — versioned change with safety{{/has}}
-7. **bash** — everything else ({{#unless (includes tools "git")}}git, {{/unless}}npm, docker, make, cargo)
+{{#has tools "bash"}}7. **bash** — everything else ({{#unless (includes tools "git")}}git, {{/unless}}npm, docker, make, cargo){{/has}}
+{{#unless (includes tools "bash")}}{{#has tools "python"}}7. **python** — stateful scripting and REPL work{{/has}}{{/unless}}
 
 {{#has tools "lsp"}}
 ### LSP knows what grep guesses

package/src/prompts/tools/python.md

@@ -0,0 +1,91 @@
+Executes Python code in an IPython kernel (session or per-call) with optional timeout.
+
+## When to use Python
+
+**Use Python for user-facing operations:**
+- Displaying, concatenating, or merging files → `cat(*paths)`
+- Batch transformations across files → `batch(paths, fn)`, `rsed()`
+- Formatted output, tables, summaries
+- Any loop, conditional, or multi-step logic
+- Anything you'd write a bash script for
+
+**Use specialized tools for YOUR reconnaissance:**
+- Reading to understand code → Read tool
+- Searching to locate something → Grep tool
+- Finding files to identify targets → Find tool
+
+The distinction: Read/Grep/Find gather info for *your* decisions. Python executes *the user's* request.
+
+**Prefer Python over bash for:**
+- Loops and iteration → Python for-loops, not bash for/while
+- Text processing → `sed()`, `cols()`, `sort_lines()`, not sed/awk/cut
+- File operations → prelude helpers, not mv/cp/rm commands
+- Conditionals → Python if/else, not bash [[ ]]
+
+**Shell commands:** Use `sh()` or `run()`, never raw `subprocess`:
+```python
+# Good
+sh("bun run check")
+run("cargo build --release")
+
+# Bad - never use subprocess directly
+import subprocess
+subprocess.run(["bun", "run", "check"], ...)
+```
+
+## Prelude helpers
+
+All helpers auto-print results and return values for chaining.
+
+{{#if categories.length}}
+{{#each categories}}
+### {{name}}
+```
+{{#each functions}}
+{{name}}{{signature}}
+    {{docstring}}
+{{/each}}
+```
+
+{{/each}}
+{{else}}
+(Documentation unavailable — Python kernel failed to start)
+{{/if}}
+
+## Examples
+
+```python
+# Concatenate all markdown files in docs/
+cat(*find("*.md", "docs"))
+
+# Mass rename: foo -> bar across all .py files
+rsed(r'\bfoo\b', 'bar', glob_pattern="*.py")
+
+# Process files in batch
+batch(find("*.json"), lambda p: json.loads(p.read_text()))
+
+# Sort and deduplicate lines
+sort_lines(read("data.txt"), unique=True)
+
+# Extract columns 0 and 2 from TSV
+cols(read("data.tsv"), 0, 2, sep="\t")
+```
+
+## Notes
+
+- Code executes as IPython cells; users see the full cell output (including rendered figures, tables, etc.)
+- Kernel persists for the session by default; per-call mode uses a fresh kernel each call. Use `reset: true` to clear state when session mode is active
+- Use `workdir` parameter instead of `os.chdir()` in tool call
+- Use `plt.show()` to display figures
+- Use `display()` from IPython.display for rich output (HTML, Markdown, images, etc.)
+- Output streams in real time, truncated after 50KB
+
+## Rich output rendering
+
+The user sees output like a Jupyter notebook—rich displays are fully rendered:
+- `display(JSON(data))` → interactive JSON tree
+- `display(HTML(...))` → rendered HTML
+- `display(Markdown(...))` → formatted markdown
+- `plt.show()` → inline figures
+
+**You will see object repr** (e.g., `<IPython.core.display.JSON object>`) **but the user sees the rendered output.** Trust that `display()` calls work correctly—do not assume the user sees only the repr.