@f5xc-salesdemos/xcsh 18.86.1 → 18.87.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.86.1",
+	"version": "18.87.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -50,12 +50,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "18.86.1",
-		"@f5xc-salesdemos/pi-agent-core": "18.86.1",
-		"@f5xc-salesdemos/pi-ai": "18.86.1",
-		"@f5xc-salesdemos/pi-natives": "18.86.1",
-		"@f5xc-salesdemos/pi-tui": "18.86.1",
-		"@f5xc-salesdemos/pi-utils": "18.86.1",
+		"@f5xc-salesdemos/xcsh-stats": "18.87.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.87.0",
+		"@f5xc-salesdemos/pi-ai": "18.87.0",
+		"@f5xc-salesdemos/pi-natives": "18.87.0",
+		"@f5xc-salesdemos/pi-tui": "18.87.0",
+		"@f5xc-salesdemos/pi-utils": "18.87.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.86.1",
-	"commit": "e6c9853663bf3961d2e4d4ea6fd443d1b1c52e57",
-	"shortCommit": "e6c9853",
+	"version": "18.87.0",
+	"commit": "501462242a4bc87a7ec923eac5f796e2d7791069",
+	"shortCommit": "5014622",
 	"branch": "main",
-	"tag": "v18.86.1",
-	"commitDate": "2026-05-28T23:13:26Z",
-	"buildDate": "2026-05-28T23:35:41.443Z",
+	"tag": "v18.87.0",
+	"commitDate": "2026-05-29T05:57:38Z",
+	"buildDate": "2026-05-29T06:18:32.519Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/e6c9853663bf3961d2e4d4ea6fd443d1b1c52e57",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.86.1"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/501462242a4bc87a7ec923eac5f796e2d7791069",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.87.0"
 };

package/src/modes/components/bash-execution.ts

@@ -3,10 +3,16 @@
  */
 
 import { sanitizeText } from "@f5xc-salesdemos/pi-natives";
-import { Container, ImageProtocol, Loader, Spacer, TERMINAL, Text, type TUI } from "@f5xc-salesdemos/pi-tui";
+import { Container, Image, Loader, Spacer, Text, type TUI } from "@f5xc-salesdemos/pi-tui";
 import { getSymbolTheme, highlightCode, theme } from "../../modes/theme/theme";
 import { formatTruncationMetaNotice, type TruncationMeta } from "../../tools/output-meta";
-import { getSixelLineMask, isSixelPassthroughEnabled, sanitizeWithOptionalSixelPassthrough } from "../../utils/sixel";
+import { resolveImageOptions } from "../../tools/render-utils";
+import {
+	extractITerm2ImageData,
+	getImageLineMask,
+	isImagePassthroughEnabled,
+	sanitizeWithImagePassthrough,
+} from "../../utils/image-passthrough";
 import { sanitizeErrorMessage } from "../utils/sanitize-error-message";
 import { DynamicBorder } from "./dynamic-border";
 import { truncateToVisualLines } from "./visual-truncate";
@@ -59,6 +65,7 @@ export class BashExecutionComponent extends Container {
 	#chunkGate = false;
 	#contentContainer: Container;
 	#headerText: Text;
+	#imageComponent?: Image;
 
 	constructor(
 		private readonly command: string,
@@ -202,11 +209,8 @@ export class BashExecutionComponent extends Container {
 		// Apply preview truncation based on expanded state
 		const previewLogicalLines = availableLines.slice(-PREVIEW_LINES);
 		const hiddenLineCount = availableLines.length - previewLogicalLines.length;
-		const sixelLineMask =
-			TERMINAL.imageProtocol === ImageProtocol.Sixel && isSixelPassthroughEnabled()
-				? getSixelLineMask(availableLines)
-				: undefined;
-		const hasSixelOutput = sixelLineMask?.some(Boolean) ?? false;
+		const imageLineMask = isImagePassthroughEnabled() ? getImageLineMask(availableLines) : undefined;
+		const hasImageOutput = imageLineMask?.some(Boolean) ?? false;
 
 		// Rebuild content container
 		this.#contentContainer.clear();
@@ -214,16 +218,22 @@ export class BashExecutionComponent extends Container {
 		// Command header
 		this.#contentContainer.addChild(this.#headerText);
 
-		// Output
+		// Render extracted image via the Image component (proper height calculation)
+		if (this.#imageComponent && this.#status !== "running") {
+			this.#contentContainer.addChild(new Spacer(1));
+			this.#contentContainer.addChild(this.#imageComponent);
+		}
+
+		// Output (text lines, excluding image lines which are handled above)
 		if (availableLines.length > 0) {
 			// Try to syntax-highlight structured output (e.g. JSON)
-			const highlightedLines = hasSixelOutput ? undefined : highlightIfStructured(availableLines);
+			const highlightedLines = hasImageOutput ? undefined : highlightIfStructured(availableLines);
 
-			if (this.#expanded || hasSixelOutput) {
+			if (this.#expanded || hasImageOutput) {
 				const displayText = highlightedLines
 					? highlightedLines.join("\n")
 					: availableLines
-							.map((line, index) => (sixelLineMask?.[index] ? line : theme.fg("muted", line)))
+							.map((line, index) => (imageLineMask?.[index] ? line : theme.fg("muted", line)))
 							.join("\n");
 				this.#contentContainer.addChild(new Text(`\n${displayText}`, 1, 0));
 			} else {
@@ -249,7 +259,7 @@ export class BashExecutionComponent extends Container {
 			const statusParts: string[] = [];
 
 			// Show how many lines are hidden (collapsed preview)
-			if (hiddenLineCount > 0 && !hasSixelOutput) {
+			if (hiddenLineCount > 0 && !hasImageOutput) {
 				statusParts.push(theme.fg("dim", `… ${hiddenLineCount} more lines (ctrl+o to expand)`));
 			}
 
@@ -285,16 +295,38 @@ export class BashExecutionComponent extends Container {
 
 	#clampLinesPreservingSixel(lines: string[]): string[] {
 		if (lines.length === 0) return [];
-		const sixelLineMask = getSixelLineMask(lines);
-		if (!sixelLineMask.some(Boolean)) {
+		const imageLineMask = getImageLineMask(lines);
+		if (!imageLineMask.some(Boolean)) {
 			return lines.map(line => this.#clampDisplayLine(line));
 		}
-		return lines.map((line, index) => (sixelLineMask[index] ? line : this.#clampDisplayLine(line)));
+		return lines.map((line, index) => (imageLineMask[index] ? line : this.#clampDisplayLine(line)));
 	}
 
 	#setOutput(output: string): void {
-		const clean = sanitizeWithOptionalSixelPassthrough(output, sanitizeText);
+		const clean = sanitizeWithImagePassthrough(output, sanitizeText);
 		this.#outputLines = clean ? this.#clampLinesPreservingSixel(clean.split("\n")) : [];
+
+		// If the output contains iTerm2 image data, extract it and create an
+		// Image component for proper height calculation instead of raw passthrough.
+		this.#imageComponent = undefined;
+		if (isImagePassthroughEnabled()) {
+			const imageData = extractITerm2ImageData(output);
+			if (imageData) {
+				this.#imageComponent = new Image(
+					imageData.base64,
+					imageData.mimeType,
+					{ fallbackColor: (s: string) => theme.fg("muted", s) },
+					resolveImageOptions(),
+				);
+				// Strip image lines and trailing empty lines so they don't
+				// render as extra whitespace below the image
+				const mask = getImageLineMask(this.#outputLines);
+				this.#outputLines = this.#outputLines.filter((_, i) => !mask[i]);
+				while (this.#outputLines.length > 0 && this.#outputLines[this.#outputLines.length - 1] === "") {
+					this.#outputLines.pop();
+				}
+			}
+		}
 	}
 
 	/**

package/src/modes/components/tool-execution.ts

@@ -34,7 +34,7 @@ import { formatExpandHint, replaceTabs, resolveImageOptions, truncateToWidth } f
 import { toolRenderers } from "../../tools/renderers";
 import { renderStatusLine } from "../../tui";
 import { convertToPng } from "../../utils/image-convert";
-import { sanitizeWithOptionalSixelPassthrough } from "../../utils/sixel";
+import { sanitizeWithImagePassthrough } from "../../utils/image-passthrough";
 import { renderDiff } from "./diff";
 
 function ensureInvalidate(component: unknown): Component {
@@ -676,7 +676,7 @@ export class ToolExecutionComponent extends Container {
 
 		let output = textBlocks
 			.map((c: any) => {
-				return sanitizeWithOptionalSixelPassthrough(c.text || "", sanitizeText);
+				return sanitizeWithImagePassthrough(c.text || "", sanitizeText);
 			})
 			.join("\n");
 

package/src/prompts/tools/display-image.md

@@ -0,0 +1,23 @@
+Displays an image inline in the terminal conversation. Shows the image visually if the terminal supports it, or opens it in the system image viewer as a fallback.
+
+<instruction>
+- Use this when you want to show an image to the user (screenshot, diagram, generated image, photo)
+- Use `inspect_image` instead when you need to analyze or extract information from an image
+- Provide `path` to the local image file (absolute or relative to working directory)
+- Optional `caption` adds descriptive text below the image
+</instruction>
+
+<examples>
+- Show a screenshot:
+  - `{"path":"screenshots/dashboard.png","caption":"Current dashboard layout"}`
+- Display a generated diagram:
+  - `{"path":"output/architecture.png"}`
+- Show a photo with context:
+  - `{"path":"assets/logo.png","caption":"Current brand logo"}`
+</examples>
+
+<output>
+- Returns the image as an inline image block when the terminal supports image protocols
+- Falls back to opening the image in the system image viewer (Preview.app, xdg-open)
+- Supports PNG, JPEG, GIF, and WEBP formats
+</output>

package/src/prompts/tools/inspect-image.md

@@ -21,8 +21,8 @@ Inspects an image file with a vision-capable model and returns compact text anal
 </examples>
 
 <output>
-- Returns text-only analysis from the vision model
-- No image content blocks are returned in tool output
+- Returns the image inline (when the terminal supports image protocols) alongside the text analysis
+- The image is displayed first, followed by the vision model's text analysis
 </output>
 
 <critical>

package/src/session/streaming-output.ts

@@ -1,6 +1,6 @@
 import { sanitizeText } from "@f5xc-salesdemos/pi-natives";
 import { formatBytes } from "../tools/render-utils";
-import { sanitizeWithOptionalSixelPassthrough } from "../utils/sixel";
+import { sanitizeWithImagePassthrough } from "../utils/image-passthrough";
 
 // =============================================================================
 // Constants
@@ -565,9 +565,14 @@ export class OutputSink {
 	/**
 	 * Push a chunk of output. The buffer management and onChunk callback run
 	 * synchronously. File sink writes are deferred and serialized internally.
+	 *
+	 * Raw chunks are accumulated unsanitized. Sanitization happens once in
+	 * dump() over the complete buffer so that image protocol escape sequences
+	 * split across multiple small chunks (a shell artefact) are preserved.
+	 * The onChunk streaming callback also receives raw data; setComplete()
+	 * replaces the streaming display with the sanitized final output.
 	 */
 	push(chunk: string): void {
-		chunk = sanitizeWithOptionalSixelPassthrough(chunk, sanitizeText);
 		if (this.#maskSecrets) chunk = this.#maskSecrets(chunk);
 
 		// Throttled onChunk: only call the callback when enough time has passed.
@@ -693,9 +698,10 @@ export class OutputSink {
 
 		if (this.#file) await this.#file.sink.end();
 
-		// Safety net: re-mask the concatenated buffer to catch secret values
-		// that were split across chunk boundaries during streaming.
-		const raw = `${noticeLine}${this.#buffer}`;
+		// Sanitize the complete buffer in one pass so image protocol escape
+		// sequences that were split across chunks are correctly detected.
+		const sanitized = sanitizeWithImagePassthrough(this.#buffer, sanitizeText);
+		const raw = `${noticeLine}${sanitized}`;
 		const output = this.#maskSecrets ? this.#maskSecrets(raw) : raw;
 
 		return {

package/src/tools/bash-interactive.ts

@@ -15,7 +15,7 @@ import xterm from "@xterm/headless";
 import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
 import type { Theme } from "../modes/theme/theme";
 import { OutputSink, type OutputSummary } from "../session/streaming-output";
-import { sanitizeWithOptionalSixelPassthrough } from "../utils/sixel";
+import { sanitizeWithImagePassthrough } from "../utils/image-passthrough";
 import { formatStatusIcon, replaceTabs } from "./render-utils";
 
 export interface BashInteractiveResult extends OutputSummary {
@@ -26,7 +26,7 @@ export interface BashInteractiveResult extends OutputSummary {
 
 function normalizeCaptureChunk(chunk: string): string {
 	const normalized = chunk.replace(/\r\n/gu, "\n").replace(/\r/gu, "\n");
-	return sanitizeWithOptionalSixelPassthrough(normalized, sanitizeText);
+	return sanitizeWithImagePassthrough(normalized, sanitizeText);
 }
 
 const XtermTerminal = xterm.Terminal;

package/src/tools/bash.ts

@@ -19,7 +19,7 @@ import { SECRET_ENV_PATTERNS, type SecretObfuscator } from "../secrets";
 import { DEFAULT_MAX_BYTES, TailBuffer } from "../session/streaming-output";
 import { renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
-import { getSixelLineMask } from "../utils/sixel";
+import { getImageLineMask } from "../utils/image-passthrough";
 import type { ToolSession } from ".";
 import { type BashInteractiveResult, runInteractiveBashPty } from "./bash-interactive";
 import { checkBashInterception } from "./bash-interceptor";
@@ -807,7 +807,7 @@ export const bashToolRenderer = {
 
 				const rawOutputLines = displayOutput.split("\n");
 				const sixelLineMask =
-					TERMINAL.imageProtocol === ImageProtocol.Sixel ? getSixelLineMask(rawOutputLines) : undefined;
+					TERMINAL.imageProtocol === ImageProtocol.Sixel ? getImageLineMask(rawOutputLines) : undefined;
 				const hasSixelOutput = sixelLineMask?.some(Boolean) ?? false;
 
 				// Build truncation warning

package/src/tools/display-image-renderer.ts

@@ -0,0 +1,96 @@
+import type { Component } from "@f5xc-salesdemos/pi-tui";
+import { Text } from "@f5xc-salesdemos/pi-tui";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import { CachedOutputBlock, F5_TOOL_BORDER_COLOR, renderStatusLine } from "../tui";
+import { addSection, formatErrorMessage, shortenPath } from "./render-utils";
+
+const TOOL_TITLE = "Display Image";
+
+interface DisplayImageRenderArgs {
+	path?: string;
+	caption?: string;
+}
+
+interface DisplayImageRendererDetails {
+	imagePath: string;
+	mimeType: string;
+	displayMethod: "inline" | "external";
+}
+
+interface DisplayImageRendererResult {
+	content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+	details?: DisplayImageRendererDetails;
+	isError?: boolean;
+}
+
+export const displayImageToolRenderer = {
+	renderCall(args: DisplayImageRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const rawPath = args.path ?? "";
+		const pathDisplay = rawPath ? shortenPath(rawPath) : "...";
+		const description = uiTheme.fg("muted", pathDisplay);
+		const text = renderStatusLine({ icon: "pending", title: TOOL_TITLE, description }, uiTheme);
+		return new Text(text, 0, 0);
+	},
+
+	renderResult(
+		result: DisplayImageRendererResult,
+		options: RenderResultOptions,
+		uiTheme: Theme,
+		args?: DisplayImageRenderArgs,
+	): Component {
+		const details = result.details;
+		const isError = result.isError === true;
+
+		if (isError && !details) {
+			const errorText = result.content?.find(c => c.type === "text")?.text;
+			return new Text(formatErrorMessage(errorText, uiTheme), 0, 0);
+		}
+
+		const rawPath = details?.imagePath ?? args?.path ?? "";
+		const pathDisplay = rawPath ? shortenPath(rawPath) : "image";
+		const sections: Array<{ label?: string; lines: string[] }> = [];
+		const meta: string[] = [];
+
+		if (details?.mimeType) meta.push(uiTheme.fg("dim", details.mimeType));
+		if (details?.displayMethod === "external") meta.push(uiTheme.fg("dim", "external viewer"));
+
+		if (isError) {
+			const errorText = result.content?.find(c => c.type === "text")?.text ?? "Unknown error";
+			addSection(sections, "Error", [uiTheme.fg("error", errorText)], uiTheme);
+		} else {
+			const textContent = result.content?.filter(c => c.type === "text");
+			if (textContent?.length) {
+				for (const block of textContent) {
+					if (block.text) {
+						addSection(sections, "", [uiTheme.fg("toolOutput", `  ${block.text}`)], uiTheme);
+					}
+				}
+			}
+		}
+
+		const header = renderStatusLine(
+			{
+				title: TOOL_TITLE,
+				titleColor: "contentAccent",
+				description: pathDisplay,
+				meta: meta.length > 0 ? meta : undefined,
+			},
+			uiTheme,
+		);
+
+		const outputBlock = new CachedOutputBlock();
+		return {
+			render(width: number): string[] {
+				const state = options.isPartial ? "pending" : isError ? "error" : "success";
+				return outputBlock.render({ header, state, sections, width, borderColor: F5_TOOL_BORDER_COLOR }, uiTheme);
+			},
+			invalidate() {
+				outputBlock.invalidate();
+			},
+		};
+	},
+
+	mergeCallAndResult: true,
+	inline: true,
+};

package/src/tools/display-image.ts

@@ -0,0 +1,109 @@
+import type {
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@f5xc-salesdemos/pi-agent-core";
+import type { ImageContent, TextContent } from "@f5xc-salesdemos/pi-ai";
+import { TERMINAL } from "@f5xc-salesdemos/pi-tui/terminal-capabilities";
+import { prompt } from "@f5xc-salesdemos/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import displayImageDescription from "../prompts/tools/display-image.md" with { type: "text" };
+import {
+	ImageInputTooLargeError,
+	type LoadedImageInput,
+	loadImageInput,
+	MAX_IMAGE_INPUT_BYTES,
+} from "../utils/image-loading";
+import { openImageExternal } from "../utils/image-viewer";
+import type { ToolSession } from "./index";
+import { ToolError } from "./tool-errors";
+
+const displayImageSchema = Type.Object(
+	{
+		path: Type.String({ description: "Filesystem path to an image file" }),
+		caption: Type.Optional(Type.String({ description: "Caption text shown below the image" })),
+	},
+	{ additionalProperties: false },
+);
+
+export type DisplayImageParams = Static<typeof displayImageSchema>;
+
+export interface DisplayImageToolDetails {
+	imagePath: string;
+	mimeType: string;
+	displayMethod: "inline" | "external";
+}
+
+export class DisplayImageTool implements AgentTool<typeof displayImageSchema, DisplayImageToolDetails> {
+	readonly name = "display_image";
+	readonly label = "DisplayImage";
+	readonly description: string;
+	readonly parameters = displayImageSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {
+		this.description = prompt.render(displayImageDescription);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: DisplayImageParams,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<DisplayImageToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<DisplayImageToolDetails>> {
+		if (this.session.settings.get("images.blockImages")) {
+			throw new ToolError("Image display is disabled by settings (images.blockImages=true).");
+		}
+
+		let imageInput: LoadedImageInput | null;
+		try {
+			imageInput = await loadImageInput({
+				path: params.path,
+				cwd: this.session.cwd,
+				autoResize: this.session.settings.get("images.autoResize"),
+				maxBytes: MAX_IMAGE_INPUT_BYTES,
+			});
+		} catch (error) {
+			if (error instanceof ImageInputTooLargeError) {
+				throw new ToolError(error.message);
+			}
+			throw error;
+		}
+
+		if (!imageInput) {
+			throw new ToolError("display_image only supports PNG, JPEG, GIF, and WEBP files detected by file content.");
+		}
+
+		const content: (TextContent | ImageContent)[] = [];
+		let displayMethod: "inline" | "external";
+
+		if (TERMINAL.imageProtocol) {
+			content.push({ type: "image", data: imageInput.data, mimeType: imageInput.mimeType });
+			displayMethod = "inline";
+		} else {
+			const opened = await openImageExternal(imageInput.resolvedPath);
+			const msg = opened
+				? `Opened ${imageInput.resolvedPath} in system image viewer.`
+				: `Could not open ${imageInput.resolvedPath} — no inline image protocol and external viewer failed.`;
+			content.push({ type: "text", text: msg });
+			displayMethod = "external";
+		}
+
+		if (params.caption) {
+			content.push({ type: "text", text: params.caption });
+		}
+
+		return {
+			content,
+			details: {
+				imagePath: imageInput.resolvedPath,
+				mimeType: imageInput.mimeType,
+				displayMethod,
+			},
+		};
+	}
+}
+
+export { displayImageToolRenderer } from "./display-image-renderer";

package/src/tools/index.ts

@@ -27,6 +27,7 @@ import { CalculatorTool } from "./calculator";
 import { CancelJobTool } from "./cancel-job";
 import { type CheckpointState, CheckpointTool, RewindTool } from "./checkpoint";
 import { DebugTool } from "./debug";
+import { DisplayImageTool } from "./display-image";
 import { ExitPlanModeTool } from "./exit-plan-mode";
 import { FindTool } from "./find";
 import {
@@ -79,6 +80,7 @@ export * from "./calculator";
 export * from "./cancel-job";
 export * from "./checkpoint";
 export * from "./debug";
+export * from "./display-image";
 export * from "./exit-plan-mode";
 export * from "./find";
 export * from "./gemini-image";
@@ -246,6 +248,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	lsp: LspTool.createIf,
 	notebook: s => new NotebookTool(s),
 	read: s => new ReadTool(s),
+	display_image: s => new DisplayImageTool(s),
 	inspect_image: s => new InspectImageTool(s),
 	browser: s => new BrowserTool(s),
 	checkpoint: CheckpointTool.createIf,

package/src/tools/inspect-image.ts

@@ -160,7 +160,10 @@ export class InspectImageTool implements AgentTool<typeof inspectImageSchema, In
 		}
 
 		return {
-			content: [{ type: "text", text }],
+			content: [
+				{ type: "image", data: imageInput.data, mimeType: imageInput.mimeType },
+				{ type: "text", text },
+			],
 			details: {
 				model: `${model.provider}/${model.id}`,
 				imagePath: imageInput.resolvedPath,

package/src/tools/renderers.ts

@@ -18,6 +18,7 @@ import { bashToolRenderer } from "./bash";
 import { browserRenderer } from "./browser-renderer";
 import { calculatorToolRenderer } from "./calculator";
 import { debugToolRenderer } from "./debug";
+import { displayImageToolRenderer } from "./display-image-renderer";
 import { findToolRenderer } from "./find";
 import { ghRunWatchToolRenderer } from "./gh-renderer";
 import { ghToolsRenderer } from "./gh-tools-renderer";
@@ -61,6 +62,7 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	grep: grepToolRenderer as ToolRenderer,
 	lsp: lspToolRenderer as ToolRenderer,
 	notebook: notebookToolRenderer as ToolRenderer,
+	display_image: displayImageToolRenderer as ToolRenderer,
 	inspect_image: inspectImageToolRenderer as ToolRenderer,
 	// Lazy getter to break circular dependency: renderers.ts <- read.ts
 	get read(): ToolRenderer {

package/src/tui/output-block.ts

@@ -3,7 +3,7 @@
  */
 import { ImageProtocol, padding, TERMINAL, visibleWidth, wrapTextWithAnsi } from "@f5xc-salesdemos/pi-tui";
 import type { Theme, ThemeColor } from "../modes/theme/theme";
-import { getSixelLineMask } from "../utils/sixel";
+import { getImageLineMask } from "../utils/image-passthrough";
 import type { State } from "./types";
 import type { RenderCache } from "./utils";
 import { getStateBgColor, Hasher, padToWidth, truncateToWidth } from "./utils";
@@ -96,7 +96,7 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 			);
 		}
 		const allLines = section.lines.flatMap(l => l.split("\n"));
-		const sixelLineMask = TERMINAL.imageProtocol === ImageProtocol.Sixel ? getSixelLineMask(allLines) : undefined;
+		const sixelLineMask = TERMINAL.imageProtocol === ImageProtocol.Sixel ? getImageLineMask(allLines) : undefined;
 		for (let lineIndex = 0; lineIndex < allLines.length; lineIndex++) {
 			const line = allLines[lineIndex]!;
 			if (sixelLineMask?.[lineIndex]) {

package/src/utils/image-passthrough.ts

@@ -0,0 +1,118 @@
+import { TERMINAL } from "@f5xc-salesdemos/pi-tui/terminal-capabilities";
+
+// -- Start sequence detection regexes --
+
+const SIXEL_START_REGEX = /\x1bP(?:[0-9;]*)q/u;
+// Match all iTerm2 image sequences: File=, MultipartFile=, FilePart=, FileEnd
+const ITERM2_START_REGEX = /\x1b\]1337;(?:File=|MultipartFile=|FilePart=|FileEnd)/u;
+const KITTY_START_REGEX = /\x1b_G/u;
+
+// -- Full sequence matching regexes (for placeholder/restore) --
+
+const SIXEL_SEQUENCE_REGEX = /\x1bP(?:[0-9;]*)q[\s\S]*?(?:\x1b\\|\x07)/gu;
+// Match all iTerm2 image OSC sequences through their terminator (BEL or ST).
+// Covers File= (inline), MultipartFile= (multipart start), FilePart= (chunks), FileEnd.
+const ITERM2_SEQUENCE_REGEX = /\x1b\]1337;(?:File=|MultipartFile=|FilePart=|FileEnd)[\s\S]*?(?:\x07|\x1b\\)/gu;
+const KITTY_SEQUENCE_REGEX = /\x1b_G[^\x1b]*\x1b\\/gu;
+
+const SIXEL_END_SEQUENCE = "\x1b\\";
+const SIXEL_END_BELL = "\x07";
+
+const PLACEHOLDER_PREFIX = "__OMP_IMAGE_SEQUENCE_";
+
+export function isImagePassthroughEnabled(): boolean {
+	return TERMINAL.imageProtocol !== null;
+}
+
+export function containsImageSequence(text: string): boolean {
+	return SIXEL_START_REGEX.test(text) || ITERM2_START_REGEX.test(text) || KITTY_START_REGEX.test(text);
+}
+
+export function isImageLine(line: string): boolean {
+	return containsImageSequence(line);
+}
+
+export function getImageLineMask(lines: string[]): boolean[] {
+	let inSixelSequence = false;
+	return lines.map(line => {
+		const hasSixelStart = SIXEL_START_REGEX.test(line);
+		const hasIterm2 = ITERM2_START_REGEX.test(line);
+		const hasKitty = KITTY_START_REGEX.test(line);
+
+		if (hasSixelStart) {
+			inSixelSequence = true;
+		}
+
+		const isImage = inSixelSequence || hasIterm2 || hasKitty;
+
+		if (inSixelSequence && (line.includes(SIXEL_END_SEQUENCE) || line.includes(SIXEL_END_BELL))) {
+			inSixelSequence = false;
+		}
+
+		return isImage;
+	});
+}
+
+/**
+ * Extracts base64 image data from iTerm2 multipart sequences in raw output.
+ * Returns the reassembled base64 string and detected mime type, or null
+ * if no multipart image is found.
+ */
+export function extractITerm2ImageData(text: string): { base64: string; mimeType: string } | null {
+	if (!ITERM2_START_REGEX.test(text)) return null;
+
+	// Check for single-part File= first
+	const singleMatch = text.match(/\x1b\]1337;File=([^:]*):([A-Za-z0-9+/=\s]+)(?:\x07|\x1b\\)/u);
+	if (singleMatch) {
+		const base64 = singleMatch[2].replace(/\s/g, "");
+		const mimeType = detectMimeFromBase64(base64);
+		return { base64, mimeType };
+	}
+
+	// Reassemble multipart: collect all FilePart payloads in order
+	const partRegex = /\x1b\]1337;FilePart=([A-Za-z0-9+/=\s]+)(?:\x07|\x1b\\)/gu;
+	const parts: string[] = [];
+	for (;;) {
+		const match = partRegex.exec(text);
+		if (!match) break;
+		parts.push(match[1].replace(/\s/g, ""));
+	}
+
+	if (parts.length === 0) return null;
+
+	const base64 = parts.join("");
+	const mimeType = detectMimeFromBase64(base64);
+	return { base64, mimeType };
+}
+
+function detectMimeFromBase64(base64: string): string {
+	const header = base64.slice(0, 12);
+	if (header.startsWith("iVBOR")) return "image/png";
+	if (header.startsWith("/9j/")) return "image/jpeg";
+	if (header.startsWith("R0lGO")) return "image/gif";
+	if (header.startsWith("UklGR")) return "image/webp";
+	return "image/png";
+}
+
+export function sanitizeWithImagePassthrough(text: string, sanitize: (text: string) => string): string {
+	if (!isImagePassthroughEnabled() || !containsImageSequence(text)) {
+		return sanitize(text);
+	}
+
+	const preservedSequences: string[] = [];
+
+	let tokenized = text;
+	for (const regex of [SIXEL_SEQUENCE_REGEX, ITERM2_SEQUENCE_REGEX, KITTY_SEQUENCE_REGEX]) {
+		tokenized = tokenized.replace(regex, match => {
+			const token = `${PLACEHOLDER_PREFIX}${preservedSequences.length}__`;
+			preservedSequences.push(match);
+			return token;
+		});
+	}
+
+	const sanitized = sanitize(tokenized);
+	return sanitized.replace(/__OMP_IMAGE_SEQUENCE_(\d+)__/gu, (_, indexText: string) => {
+		const index = Number.parseInt(indexText, 10);
+		return preservedSequences[index] ?? "";
+	});
+}

package/src/utils/image-viewer.ts

@@ -0,0 +1,17 @@
+/**
+ * Opens an image in the system's default image viewer.
+ * Returns true if the viewer was launched successfully.
+ */
+export async function openImageExternal(path: string): Promise<boolean> {
+	const command = process.platform === "darwin" ? "open" : "xdg-open";
+	try {
+		const proc = Bun.spawn([command, path], {
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+		await proc.exited;
+		return proc.exitCode === 0;
+	} catch {
+		return false;
+	}
+}

package/src/utils/sixel.ts

@@ -1,69 +0,0 @@
-import { $env, $flag } from "@f5xc-salesdemos/pi-utils";
-
-const SIXEL_START_REGEX = /\x1bP(?:[0-9;]*)q/u;
-const SIXEL_END_SEQUENCE = "\x1b\\";
-const SIXEL_END_BELL = "\x07";
-const SIXEL_SEQUENCE_REGEX = /\x1bP(?:[0-9;]*)q[\s\S]*?(?:\x1b\\|\x07)/gu;
-const SIXEL_PLACEHOLDER_PREFIX = "__OMP_SIXEL_SEQUENCE_";
-
-/**
- * Returns whether SIXEL passthrough is explicitly enabled.
- *
- * Both gates must be enabled to preserve SIXEL control sequences:
- * - PI_FORCE_IMAGE_PROTOCOL=sixel
- * - PI_ALLOW_SIXEL_PASSTHROUGH=1
- */
-export function isSixelPassthroughEnabled(): boolean {
-	const forcedProtocol = $env.PI_FORCE_IMAGE_PROTOCOL?.trim().toLowerCase();
-	return forcedProtocol === "sixel" && $flag("PI_ALLOW_SIXEL_PASSTHROUGH");
-}
-/** Returns true when the text contains a SIXEL start sequence. */
-export function containsSixelSequence(text: string): boolean {
-	return SIXEL_START_REGEX.test(text);
-}
-
-/**
- * Returns a boolean mask indicating which lines belong to a SIXEL sequence block.
- * Supports multi-line SIXEL payloads generated by libsixel.
- */
-export function getSixelLineMask(lines: string[]): boolean[] {
-	let inSequence = false;
-	return lines.map(line => {
-		const hasStart = containsSixelSequence(line);
-		if (hasStart) {
-			inSequence = true;
-		}
-		const isSixelLine = inSequence;
-		if (inSequence && (line.includes(SIXEL_END_SEQUENCE) || line.includes(SIXEL_END_BELL))) {
-			inSequence = false;
-		}
-		return isSixelLine;
-	});
-}
-
-/** Returns true when the line contains a SIXEL start sequence. */
-export function isSixelLine(line: string): boolean {
-	return containsSixelSequence(line);
-}
-
-/**
- * Sanitizes text while preserving embedded SIXEL sequences when passthrough is enabled.
- */
-export function sanitizeWithOptionalSixelPassthrough(text: string, sanitize: (text: string) => string): string {
-	if (!isSixelPassthroughEnabled() || !containsSixelSequence(text)) {
-		return sanitize(text);
-	}
-
-	const preservedSequences: string[] = [];
-	const tokenized = text.replace(SIXEL_SEQUENCE_REGEX, match => {
-		const token = `${SIXEL_PLACEHOLDER_PREFIX}${preservedSequences.length}__`;
-		preservedSequences.push(match);
-		return token;
-	});
-
-	const sanitized = sanitize(tokenized);
-	return sanitized.replace(/__OMP_SIXEL_SEQUENCE_(\d+)__/gu, (_, indexText: string) => {
-		const index = Number.parseInt(indexText, 10);
-		return preservedSequences[index] ?? "";
-	});
-}