@oh-my-pi/pi-coding-agent 13.5.1 → 13.5.2

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [13.5.2] - 2026-03-01
+
+### Added
+
+- Added `checkpoint` tool to create context checkpoints before exploratory work, allowing you to investigate with many intermediate tool calls and minimize context cost afterward
+- Added `rewind` tool to end an active checkpoint and replace intermediate exploration messages with a concise investigation report
+- Added `checkpoint.enabled` setting to control availability of the checkpoint and rewind tools
+- Added `render_mermaid` tool to convert Mermaid graph source into ASCII diagram output
+- Added `renderMermaid.enabled` setting to control availability of the render_mermaid tool
+
+### Changed
+
+- Changed Mermaid rendering from PNG images to ASCII diagrams in theme rendering
+- Changed `prerenderMermaid()` function to synchronously render ASCII instead of asynchronously rendering PNG
+
 ## [13.5.0] - 2026-03-01
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "13.5.1",
+	"version": "13.5.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -41,12 +41,12 @@
 	},
 	"dependencies": {
 		"@mozilla/readability": "^0.6",
-		"@oh-my-pi/omp-stats": "13.5.1",
-		"@oh-my-pi/pi-agent-core": "13.5.1",
-		"@oh-my-pi/pi-ai": "13.5.1",
-		"@oh-my-pi/pi-natives": "13.5.1",
-		"@oh-my-pi/pi-tui": "13.5.1",
-		"@oh-my-pi/pi-utils": "13.5.1",
+		"@oh-my-pi/omp-stats": "13.5.2",
+		"@oh-my-pi/pi-agent-core": "13.5.2",
+		"@oh-my-pi/pi-ai": "13.5.2",
+		"@oh-my-pi/pi-natives": "13.5.2",
+		"@oh-my-pi/pi-tui": "13.5.2",
+		"@oh-my-pi/pi-utils": "13.5.2",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/config/settings-schema.ts

@@ -460,11 +460,29 @@ export const SETTINGS_SCHEMA = {
 			description: "Enable the ast_edit tool for structural AST rewrites",
 		},
 	},
+	"renderMermaid.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tools",
+			label: "Enable Render Mermaid",
+			description: "Enable the render_mermaid tool for Mermaid-to-ASCII rendering",
+		},
+	},
 	"notebook.enabled": {
 		type: "boolean",
 		default: true,
 		ui: { tab: "tools", label: "Enable Notebook", description: "Enable the notebook tool for notebook editing" },
 	},
+	"checkpoint.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tools",
+			label: "Enable Checkpoint/Rewind",
+			description: "Enable the checkpoint and rewind tools for context checkpointing",
+		},
+	},
 	"fetch.enabled": {
 		type: "boolean",
 		default: true,

package/src/debug/index.ts

@@ -27,6 +27,11 @@ const DEBUG_MENU_ITEMS: SelectItem[] = [
 	{ value: "memory", label: "Report: memory issue", description: "Heap snapshot + bundle" },
 	{ value: "logs", label: "View: recent logs", description: "Show last 50 log entries" },
 	{ value: "system", label: "View: system info", description: "Show environment details" },
+	{
+		value: "transcript",
+		label: "Export: TUI transcript",
+		description: "Write visible TUI conversation to a temp txt",
+	},
 	{ value: "clear-cache", label: "Clear: artifact cache", description: "Remove old session artifacts" },
 ];
 
@@ -95,6 +100,9 @@ export class DebugSelectorComponent extends Container {
 			case "system":
 				await this.#handleViewSystemInfo();
 				break;
+			case "transcript":
+				await this.#handleTranscriptExport();
+				break;
 			case "clear-cache":
 				await this.#handleClearCache();
 				break;
@@ -323,6 +331,9 @@ export class DebugSelectorComponent extends Container {
 		this.ctx.ui.requestRender();
 	}
 
+	async #handleTranscriptExport(): Promise<void> {
+		await this.ctx.handleDebugTranscriptCommand();
+	}
 	async #handleOpenArtifacts(): Promise<void> {
 		const sessionFile = this.ctx.sessionManager.getSessionFile();
 		if (!sessionFile) {

package/src/modes/controllers/command-controller.ts

@@ -28,6 +28,7 @@ import type { AuthStorage } from "../../session/auth-storage";
 import { createCompactionSummaryMessage } from "../../session/messages";
 import { outputMeta } from "../../tools/output-meta";
 import { resolveToCwd } from "../../tools/path-utils";
+import { replaceTabs } from "../../tools/render-utils";
 import { getChangelogPath, parseChangelog } from "../../utils/changelog";
 import { openPath } from "../../utils/open";
 
@@ -70,6 +71,25 @@ export class CommandController {
 		}
 	}
 
+	async handleDebugTranscriptCommand(): Promise<void> {
+		try {
+			const width = Math.max(1, this.ctx.ui.terminal.columns);
+			const renderedLines = this.ctx.chatContainer.render(width).map(line => replaceTabs(Bun.stripANSI(line)));
+			const rendered = renderedLines.join("\n").trimEnd();
+			if (!rendered) {
+				this.ctx.showError("No messages to dump yet.");
+				return;
+			}
+			const tmpPath = path.join(os.tmpdir(), `${Snowflake.next()}-tmp.txt`);
+			await Bun.write(tmpPath, `${rendered}\n`);
+			this.ctx.showStatus(`Debug transcript written to:\n${tmpPath}`);
+		} catch (error: unknown) {
+			this.ctx.showError(
+				`Failed to write debug transcript: ${error instanceof Error ? error.message : "Unknown error"}`,
+			);
+		}
+	}
+
 	async handleShareCommand(): Promise<void> {
 		const tmpFile = path.join(os.tmpdir(), `${Snowflake.next()}.html`);
 		const cleanupTempFile = async () => {

package/src/modes/interactive-mode.ts

@@ -947,6 +947,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#commandController.handleDumpCommand();
 	}
 
+	handleDebugTranscriptCommand(): Promise<void> {
+		return this.#commandController.handleDebugTranscriptCommand();
+	}
+
 	handleShareCommand(): Promise<void> {
 		return this.#commandController.handleShareCommand();
 	}

package/src/modes/theme/mermaid-cache.ts

@@ -1,88 +1,48 @@
-import {
-	extractMermaidBlocks,
-	type MermaidImage,
-	type MermaidRenderOptions,
-	renderMermaidToPng,
-} from "@oh-my-pi/pi-tui";
-import { logger } from "@oh-my-pi/pi-utils";
+import { extractMermaidBlocks, logger, renderMermaidAsciiSafe } from "@oh-my-pi/pi-utils";
 
-const cache = new Map<bigint, MermaidImage>();
-const pending = new Map<bigint, Promise<MermaidImage | null>>();
+const cache = new Map<bigint, string>();
 const failed = new Set<bigint>();
 
-const defaultOptions: MermaidRenderOptions = {
-	theme: "dark",
-	backgroundColor: "transparent",
-};
-
 let onRenderNeeded: (() => void) | null = null;
 
 /**
- * Set callback to trigger TUI re-render when mermaid images become available.
+ * Set callback to trigger TUI re-render when mermaid ASCII renders become available.
  */
 export function setMermaidRenderCallback(callback: (() => void) | null): void {
 	onRenderNeeded = callback;
 }
 
 /**
- * Get a pre-rendered mermaid image by hash.
+ * Get a pre-rendered mermaid ASCII diagram by hash.
  * Returns null if not cached or rendering failed.
  */
-export function getMermaidImage(hash: bigint): MermaidImage | null {
+export function getMermaidAscii(hash: bigint): string | null {
 	return cache.get(hash) ?? null;
 }
 
 /**
- * Pre-render all mermaid blocks in markdown text.
- * Renders in parallel, deduplicates concurrent requests.
- * Calls render callback when new images are cached.
+ * Render all mermaid blocks in markdown text.
+ * Caches results and calls render callback when new diagrams are available.
  */
-export async function prerenderMermaid(
-	markdown: string,
-	options: MermaidRenderOptions = defaultOptions,
-): Promise<void> {
+export function prerenderMermaid(markdown: string): void {
 	const blocks = extractMermaidBlocks(markdown);
 	if (blocks.length === 0) return;
 
-	const promises: Promise<boolean>[] = [];
+	let hasNew = false;
 
 	for (const { source, hash } of blocks) {
 		if (cache.has(hash) || failed.has(hash)) continue;
 
-		let promise = pending.get(hash);
-		if (!promise) {
-			promise = renderMermaidToPng(source, options);
-			pending.set(hash, promise);
+		const ascii = renderMermaidAsciiSafe(source);
+		if (ascii) {
+			cache.set(hash, ascii);
+			hasNew = true;
+		} else {
+			failed.add(hash);
 		}
-
-		promises.push(
-			promise
-				.then(image => {
-					pending.delete(hash);
-					if (image) {
-						cache.set(hash, image);
-						failed.delete(hash);
-						return true;
-					}
-					failed.add(hash);
-					return false;
-				})
-				.catch(error => {
-					pending.delete(hash);
-					failed.add(hash);
-					logger.warn("Mermaid render failed", {
-						hash,
-						error: error instanceof Error ? error.message : String(error),
-					});
-					return false;
-				}),
-		);
 	}
 
-	const results = await Promise.all(promises);
-	const newImages = results.some(added => added);
-
-	if (newImages && onRenderNeeded) {
+	if (hasNew && onRenderNeeded) {
 		try {
 			onRenderNeeded();
 		} catch (error) {
@@ -107,5 +67,4 @@ export function hasPendingMermaid(markdown: string): boolean {
 export function clearMermaidCache(): void {
 	cache.clear();
 	failed.clear();
-	pending.clear();
 }

package/src/modes/theme/theme.ts

@@ -16,7 +16,7 @@ import chalk from "chalk";
 import darkThemeJson from "./dark.json" with { type: "json" };
 import { defaultThemes } from "./defaults";
 import lightThemeJson from "./light.json" with { type: "json" };
-import { getMermaidImage } from "./mermaid-cache";
+import { getMermaidAscii } from "./mermaid-cache";
 
 // ============================================================================
 // Symbol Presets
@@ -2340,7 +2340,7 @@ export function getMarkdownTheme(): MarkdownTheme {
 		underline: (text: string) => theme.underline(text),
 		strikethrough: (text: string) => chalk.strikethrough(text),
 		symbols: getSymbolTheme(),
-		getMermaidImage,
+		getMermaidAscii,
 		highlightCode: (code: string, lang?: string): string[] => {
 			const validLang = lang && nativeSupportsLanguage(lang) ? lang : undefined;
 			try {

package/src/modes/types.ts

@@ -154,6 +154,7 @@ export interface InteractiveModeContext {
 	handleChangelogCommand(showFull?: boolean): Promise<void>;
 	handleHotkeysCommand(): void;
 	handleDumpCommand(): Promise<void>;
+	handleDebugTranscriptCommand(): Promise<void>;
 	handleClearCommand(): Promise<void>;
 	handleForkCommand(): Promise<void>;
 	handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;

package/src/prompts/tools/checkpoint.md

@@ -0,0 +1,16 @@
+Creates a context checkpoint before exploratory work so you can later rewind and keep only a concise report.
+
+Use this when you need to investigate with many intermediate tool calls (read/grep/find/lsp/etc.) and want to minimize context cost afterward.
+
+Rules:
+- You **MUST** call `rewind` before yielding after starting a checkpoint.
+- You **MUST** provide a clear `goal` explaining what you are investigating.
+- You **MUST NOT** call `checkpoint` while another checkpoint is active.
+- Not available in subagents.
+
+Typical flow:
+1. `checkpoint(goal: …)`
+2. Perform exploratory work
+3. `rewind(report: …)` with concise findings
+
+After rewind, intermediate checkpoint messages are removed from active context and replaced by the report.

package/src/prompts/tools/render-mermaid.md

@@ -0,0 +1,9 @@
+Convert Mermaid graph source into ASCII diagram output.
+
+Parameters:
+- `mermaid` (required): Mermaid graph text to render.
+- `config` (optional): JSON render configuration (spacing and layout options).
+Behavior:
+- Returns ASCII diagram text.
+- Saves full ASCII output to an artifact URL (`artifact://<id>`) when artifact storage is available.
+- Returns an error when the Mermaid input is invalid or rendering fails.

package/src/prompts/tools/rewind.md

@@ -0,0 +1,13 @@
+Ends an active checkpoint and rewinds context back to that checkpoint, replacing intermediate exploration with your report.
+
+Use this immediately after investigative work started with `checkpoint`.
+
+Requirements:
+- `report` is **REQUIRED** and must be concise, factual, and actionable.
+- Include key findings, decisions, and any unresolved risks.
+- Do not include raw scratch logs unless essential.
+- You **MUST** call this before yielding if a checkpoint is active.
+
+Behavior:
+- If no checkpoint is active, this tool errors.
+- On success, the session rewinds and keeps your report as retained context.

package/src/sdk.ts

@@ -806,6 +806,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		getCompactContext: () => session.formatCompactContext(),
 		getTodoPhases: () => session.getTodoPhases(),
 		setTodoPhases: phases => session.setTodoPhases(phases),
+		getCheckpointState: () => session.getCheckpointState(),
+		setCheckpointState: state => session.setCheckpointState(state ?? undefined),
 		allocateOutputArtifact: async toolType => {
 			try {
 				return await sessionManager.allocateArtifactPath(toolType);

package/src/session/agent-session.ts

@@ -84,6 +84,7 @@ import planModeActivePrompt from "../prompts/system/plan-mode-active.md" with {
 import planModeReferencePrompt from "../prompts/system/plan-mode-reference.md" with { type: "text" };
 import ttsrInterruptTemplate from "../prompts/system/ttsr-interrupt.md" with { type: "text" };
 import type { SecretObfuscator } from "../secrets/obfuscator";
+import type { CheckpointState } from "../tools/checkpoint";
 import { outputMeta } from "../tools/output-meta";
 import { resolveToCwd } from "../tools/path-utils";
 import type { PendingActionStore } from "../tools/pending-action";
@@ -373,6 +374,8 @@ export class AgentSession {
 	#promptInFlight = false;
 	#obfuscator: SecretObfuscator | undefined;
 	#pendingActionStore: PendingActionStore | undefined;
+	#checkpointState: CheckpointState | undefined = undefined;
+	#pendingRewindReport: string | undefined = undefined;
 	#promptGeneration = 0;
 	#providerSessionState = new Map<string, ProviderSessionState>();
 
@@ -513,6 +516,11 @@ export class AgentSession {
 		if (event.type === "turn_end" && this.#ttsrManager) {
 			this.#ttsrManager.incrementMessageCount();
 		}
+		if (event.type === "turn_end" && this.#pendingRewindReport) {
+			const report = this.#pendingRewindReport;
+			this.#pendingRewindReport = undefined;
+			await this.#applyRewind(report);
+		}
 
 		// TTSR: Check for pattern matches on assistant text/thinking and tool argument deltas
 		if (event.type === "message_update" && this.#ttsrManager?.hasRules()) {
@@ -674,7 +682,7 @@ export class AgentSession {
 			if (event.message.role === "toolResult") {
 				const { toolName, details, isError, content } = event.message as {
 					toolName?: string;
-					details?: { path?: string; phases?: TodoPhase[] };
+					details?: { path?: string; phases?: TodoPhase[]; report?: string; startedAt?: string };
 					isError?: boolean;
 					content?: Array<TextContent | ImageContent>;
 				};
@@ -704,6 +712,23 @@ export class AgentSession {
 						{ deliverAs: "nextTurn" },
 					);
 				}
+				if (toolName === "checkpoint" && !isError) {
+					const checkpointEntryId = this.sessionManager.getEntries().at(-1)?.id ?? null;
+					this.#checkpointState = {
+						checkpointMessageCount: this.agent.state.messages.length,
+						checkpointEntryId,
+						startedAt: details?.startedAt ?? new Date().toISOString(),
+					};
+					this.#pendingRewindReport = undefined;
+				}
+				if (toolName === "rewind" && !isError && this.#checkpointState) {
+					const detailReport = typeof details?.report === "string" ? details.report.trim() : "";
+					const textReport = content?.find(part => part.type === "text")?.text?.trim() ?? "";
+					const report = detailReport || textReport;
+					if (report.length > 0) {
+						this.#pendingRewindReport = report;
+					}
+				}
 			}
 		}
 
@@ -723,11 +748,18 @@ export class AgentSession {
 				if (didRetry) return; // Retry was initiated, don't proceed to compaction
 			}
 
+			if (msg.stopReason === "aborted" && this.#checkpointState) {
+				this.#checkpointState = undefined;
+				this.#pendingRewindReport = undefined;
+			}
 			const compactionTask = this.#checkCompaction(msg);
 			this.#trackPostPromptTask(compactionTask);
 			await compactionTask;
 			// Check for incomplete todos (unless there was an error or abort)
 			if (msg.stopReason !== "error" && msg.stopReason !== "aborted") {
+				if (this.#enforceRewindBeforeYield()) {
+					return;
+				}
 				await this.#checkTodoCompletion();
 			}
 		}
@@ -1678,6 +1710,17 @@ export class AgentSession {
 		this.#planReferencePath = path;
 	}
 
+	getCheckpointState(): CheckpointState | undefined {
+		return this.#checkpointState;
+	}
+
+	setCheckpointState(state: CheckpointState | undefined): void {
+		this.#checkpointState = state;
+		if (!state) {
+			this.#pendingRewindReport = undefined;
+		}
+	}
+
 	/**
 	 * Inject the plan mode context message into the conversation history.
 	 */
@@ -3238,6 +3281,54 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			}
 		}
 	}
+	#enforceRewindBeforeYield(): boolean {
+		if (!this.#checkpointState || this.#pendingRewindReport) {
+			return false;
+		}
+		const reminder = [
+			"<system-warning>",
+			"You are in an active checkpoint. You MUST call rewind with your investigation findings before yielding. Do NOT yield without completing the checkpoint.",
+			"</system-warning>",
+		].join("\n");
+		this.agent.appendMessage({
+			role: "developer",
+			content: [{ type: "text", text: reminder }],
+			timestamp: Date.now(),
+		});
+		this.#scheduleAgentContinue({ generation: this.#promptGeneration });
+		return true;
+	}
+
+	async #applyRewind(report: string): Promise<void> {
+		const checkpointState = this.#checkpointState;
+		if (!checkpointState) {
+			return;
+		}
+		const safeCount = Math.max(0, Math.min(checkpointState.checkpointMessageCount, this.agent.state.messages.length));
+		this.agent.replaceMessages(this.agent.state.messages.slice(0, safeCount));
+		try {
+			this.sessionManager.branchWithSummary(checkpointState.checkpointEntryId, report, {
+				startedAt: checkpointState.startedAt,
+			});
+		} catch (error) {
+			logger.warn("Rewind branch checkpoint missing, falling back to root", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+			this.sessionManager.branchWithSummary(null, report, { startedAt: checkpointState.startedAt });
+		}
+		const details = { startedAt: checkpointState.startedAt, rewoundAt: new Date().toISOString() };
+		this.agent.appendMessage({
+			role: "custom",
+			customType: "rewind-report",
+			content: report,
+			display: false,
+			details,
+			timestamp: Date.now(),
+		});
+		this.sessionManager.appendCustomMessageEntry("rewind-report", report, false, details);
+		this.#checkpointState = undefined;
+		this.#pendingRewindReport = undefined;
+	}
 	/**
 	 * Check if agent stopped with incomplete todos and prompt to continue.
 	 */

package/src/slash-commands/builtin-registry.ts

@@ -394,7 +394,7 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<BuiltinSlashCommandSpec> = [
 	},
 	{
 		name: "debug",
-		description: "Write debug log (TUI state and messages)",
+		description: "Open debug tools selector",
 		handle: (_command, runtime) => {
 			runtime.ctx.showDebugSelector();
 			runtime.ctx.editor.setText("");

package/src/tools/checkpoint.ts

@@ -0,0 +1,128 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import { type Static, Type } from "@sinclair/typebox";
+import { renderPromptTemplate } from "../config/prompt-templates";
+import checkpointDescription from "../prompts/tools/checkpoint.md" with { type: "text" };
+import rewindDescription from "../prompts/tools/rewind.md" with { type: "text" };
+import type { ToolSession } from ".";
+import type { OutputMeta } from "./output-meta";
+import { ToolError } from "./tool-errors";
+import { toolResult } from "./tool-result";
+
+export interface CheckpointState {
+	/** Number of in-memory messages at checkpoint (AFTER checkpoint tool result is appended) */
+	checkpointMessageCount: number;
+	/** Session entry ID at checkpoint (for session tree branching) */
+	checkpointEntryId: string | null;
+	/** Timestamp */
+	startedAt: string;
+}
+
+const checkpointSchema = Type.Object({
+	goal: Type.String({ description: "What you are investigating and why" }),
+});
+
+type CheckpointParams = Static<typeof checkpointSchema>;
+
+const rewindSchema = Type.Object({
+	report: Type.String({ description: "Concise investigation findings to retain after rewind" }),
+});
+
+type RewindParams = Static<typeof rewindSchema>;
+
+export interface CheckpointToolDetails {
+	goal: string;
+	startedAt: string;
+	meta?: OutputMeta;
+}
+
+export interface RewindToolDetails {
+	report: string;
+	rewound: boolean;
+	meta?: OutputMeta;
+}
+
+function isTopLevelSession(session: ToolSession): boolean {
+	const depth = session.taskDepth;
+	return depth === undefined || depth === 0;
+}
+
+export class CheckpointTool implements AgentTool<typeof checkpointSchema, CheckpointToolDetails> {
+	readonly name = "checkpoint";
+	readonly label = "Checkpoint";
+	readonly description: string;
+	readonly parameters = checkpointSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {
+		this.description = renderPromptTemplate(checkpointDescription);
+	}
+
+	static createIf(session: ToolSession): CheckpointTool | null {
+		if (!isTopLevelSession(session)) return null;
+		return new CheckpointTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: CheckpointParams,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<CheckpointToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<CheckpointToolDetails>> {
+		if (!isTopLevelSession(this.session)) {
+			throw new ToolError("Checkpoint not available in subagents.");
+		}
+		if (this.session.getCheckpointState?.()) {
+			throw new ToolError("Checkpoint already active.");
+		}
+		const startedAt = new Date().toISOString();
+		return toolResult<CheckpointToolDetails>({ goal: params.goal, startedAt })
+			.text(
+				[
+					"Checkpoint created.",
+					`Goal: ${params.goal}`,
+					"Run your investigation, then call rewind with a concise report.",
+				].join("\n"),
+			)
+			.done();
+	}
+}
+
+export class RewindTool implements AgentTool<typeof rewindSchema, RewindToolDetails> {
+	readonly name = "rewind";
+	readonly label = "Rewind";
+	readonly description: string;
+	readonly parameters = rewindSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {
+		this.description = renderPromptTemplate(rewindDescription);
+	}
+
+	static createIf(session: ToolSession): RewindTool | null {
+		if (!isTopLevelSession(session)) return null;
+		return new RewindTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: RewindParams,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<RewindToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<RewindToolDetails>> {
+		if (!isTopLevelSession(this.session)) {
+			throw new ToolError("Checkpoint not available in subagents.");
+		}
+		if (!this.session.getCheckpointState?.()) {
+			throw new ToolError("No active checkpoint.");
+		}
+		const report = params.report.trim();
+		if (report.length === 0) {
+			throw new ToolError("Report cannot be empty.");
+		}
+		return toolResult<RewindToolDetails>({ report, rewound: true })
+			.text(["Rewind requested.", "Report captured for context replacement."].join("\n"))
+			.done();
+	}
+}

package/src/tools/index.ts

@@ -22,6 +22,7 @@ import { BashTool } from "./bash";
 import { BrowserTool } from "./browser";
 import { CalculatorTool } from "./calculator";
 import { CancelJobTool } from "./cancel-job";
+import { type CheckpointState, CheckpointTool, RewindTool } from "./checkpoint";
 import { ExitPlanModeTool } from "./exit-plan-mode";
 import { FetchTool } from "./fetch";
 import { FindTool } from "./find";
@@ -30,6 +31,7 @@ import { NotebookTool } from "./notebook";
 import { wrapToolWithMetaNotice } from "./output-meta";
 import { PythonTool } from "./python";
 import { ReadTool } from "./read";
+import { RenderMermaidTool } from "./render-mermaid";
 import { ResolveTool } from "./resolve";
 import { reportFindingTool } from "./review";
 import { loadSshTool } from "./ssh";
@@ -54,6 +56,7 @@ export * from "./bash";
 export * from "./browser";
 export * from "./calculator";
 export * from "./cancel-job";
+export * from "./checkpoint";
 export * from "./exit-plan-mode";
 export * from "./fetch";
 export * from "./find";
@@ -63,6 +66,7 @@ export * from "./notebook";
 export * from "./pending-action";
 export * from "./python";
 export * from "./read";
+export * from "./render-mermaid";
 export * from "./resolve";
 export * from "./review";
 export * from "./ssh";
@@ -143,6 +147,10 @@ export interface ToolSession {
 	setTodoPhases?: (phases: TodoPhase[]) => void;
 	/** Pending action store for preview/apply workflows */
 	pendingActionStore?: import("./pending-action").PendingActionStore;
+	/** Get active checkpoint state if any. */
+	getCheckpointState?: () => CheckpointState | undefined;
+	/** Set or clear active checkpoint state. */
+	setCheckpointState?: (state: CheckpointState | null) => void;
 }
 
 type ToolFactory = (session: ToolSession) => Tool | null | Promise<Tool | null>;
@@ -150,6 +158,7 @@ type ToolFactory = (session: ToolSession) => Tool | null | Promise<Tool | null>;
 export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	ast_grep: s => new AstGrepTool(s),
 	ast_edit: s => new AstEditTool(s),
+	render_mermaid: s => new RenderMermaidTool(s),
 	ask: AskTool.createIf,
 	bash: s => new BashTool(s),
 	python: s => new PythonTool(s),
@@ -162,6 +171,8 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	notebook: s => new NotebookTool(s),
 	read: s => new ReadTool(s),
 	browser: s => new BrowserTool(s),
+	checkpoint: CheckpointTool.createIf,
+	rewind: RewindTool.createIf,
 	task: TaskTool.create,
 	cancel_job: CancelJobTool.createIf,
 	await: AwaitTool.createIf,
@@ -281,12 +292,14 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "grep") return session.settings.get("grep.enabled");
 		if (name === "ast_grep") return session.settings.get("astGrep.enabled");
 		if (name === "ast_edit") return session.settings.get("astEdit.enabled");
+		if (name === "render_mermaid") return session.settings.get("renderMermaid.enabled");
 		if (name === "notebook") return session.settings.get("notebook.enabled");
 		if (name === "fetch") return session.settings.get("fetch.enabled");
 		if (name === "web_search") return session.settings.get("web_search.enabled");
 		if (name === "lsp") return session.settings.get("lsp.enabled");
 		if (name === "calc") return session.settings.get("calc.enabled");
 		if (name === "browser") return session.settings.get("browser.enabled");
+		if (name === "checkpoint" || name === "rewind") return session.settings.get("checkpoint.enabled");
 		if (name === "task") {
 			const maxDepth = session.settings.get("task.maxRecursionDepth") ?? 2;
 			const currentDepth = session.taskDepth ?? 0;

package/src/tools/render-mermaid.ts

@@ -0,0 +1,67 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import { type MermaidAsciiRenderOptions, renderMermaidAscii } from "@oh-my-pi/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import { renderPromptTemplate } from "../config/prompt-templates";
+import renderMermaidDescription from "../prompts/tools/render-mermaid.md" with { type: "text" };
+import type { ToolSession } from "./index";
+
+const renderMermaidSchema = Type.Object({
+	mermaid: Type.String({ description: "Mermaid graph source text" }),
+	config: Type.Optional(
+		Type.Object({
+			useAscii: Type.Optional(Type.Boolean()),
+			paddingX: Type.Optional(Type.Number()),
+			paddingY: Type.Optional(Type.Number()),
+			boxBorderPadding: Type.Optional(Type.Number()),
+		}),
+	),
+});
+
+type RenderMermaidParams = Static<typeof renderMermaidSchema>;
+
+function sanitizeRenderConfig(config: MermaidAsciiRenderOptions | undefined): MermaidAsciiRenderOptions | undefined {
+	if (!config) return undefined;
+	return {
+		useAscii: config.useAscii,
+		boxBorderPadding:
+			config.boxBorderPadding === undefined ? undefined : Math.max(0, Math.floor(config.boxBorderPadding)),
+		paddingX: config.paddingX === undefined ? undefined : Math.max(0, Math.floor(config.paddingX)),
+		paddingY: config.paddingY === undefined ? undefined : Math.max(0, Math.floor(config.paddingY)),
+	};
+}
+export interface RenderMermaidToolDetails {
+	artifactId?: string;
+}
+
+export class RenderMermaidTool implements AgentTool<typeof renderMermaidSchema, RenderMermaidToolDetails> {
+	readonly name = "render_mermaid";
+	readonly label = "RenderMermaid";
+	readonly description: string;
+	readonly parameters = renderMermaidSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {
+		this.description = renderPromptTemplate(renderMermaidDescription);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: RenderMermaidParams,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<RenderMermaidToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<RenderMermaidToolDetails>> {
+		const ascii = renderMermaidAscii(params.mermaid, sanitizeRenderConfig(params.config));
+		const { path: artifactPath, id: artifactId } =
+			(await this.session.allocateOutputArtifact?.("render_mermaid")) ?? {};
+		if (artifactPath) {
+			await Bun.write(artifactPath, ascii);
+		}
+
+		const artifactLine = artifactId ? `\n\nSaved artifact: artifact://${artifactId}` : "";
+		return {
+			content: [{ type: "text", text: `${ascii}${artifactLine}` }],
+			details: { artifactId },
+		};
+	}
+}