feat: register ImageShowTool as a proper buildTool with prompt + UI

Convert ImageShowTool from standalone utilities to a full Tool definition
using buildTool(), add prompt.ts for LLM-facing description, and refactor
UI.tsx into tool render functions. Standalone executable moved to
standalone.tsx to avoid side effects on import.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/tools/ImageShowTool/ImageShowTool.ts

@@ -1,5 +1,17 @@
+import { z } from 'zod/v4'
 import { Jimp } from "jimp";
+import { buildTool, type ToolDef } from '../../Tool.js'
 import { loadImageFromUrl } from "../../ink-picture/utils/jimpURL.ts";
+import { lazySchema } from '../../utils/lazySchema.js'
+import type { PermissionDecision } from '../../utils/permissions/PermissionResult.js'
+import { IMAGE_SHOW_TOOL_NAME, DESCRIPTION } from './prompt.js'
+import {
+  getToolUseSummary,
+  renderToolResultMessage,
+  renderToolUseMessage,
+} from './UI.js'
+
+// ── Utility functions (kept for standalone UI and external use) ──
 
 export const CELL_WIDTH = 8;
 export const CELL_HEIGHT = 16;
@@ -46,3 +58,125 @@ export function calculateDimensions(
     pixelHeight: finalH_pixels,
   };
 }
+
+// ── Tool definition ──
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    src: z.string().describe('Image source — local file path or HTTPS URL'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    src: z.string().describe('The image source that was displayed'),
+    success: z.boolean().describe('Whether the image was displayed successfully'),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+
+export const ImageShowTool = buildTool({
+  name: IMAGE_SHOW_TOOL_NAME,
+  searchHint: 'display an image in the terminal',
+  maxResultSizeChars: 10_000,
+  shouldDefer: true,
+  async description(input) {
+    const { src } = input as { src: string }
+    try {
+      const url = new URL(src)
+      return `Codev wants to display image from ${url.hostname}`
+    } catch {
+      return `Codev wants to display image: ${src}`
+    }
+  },
+  userFacingName() {
+    return 'Image'
+  },
+  getToolUseSummary,
+  getActivityDescription(input) {
+    const { src } = input as { src: string }
+    try {
+      const url = new URL(src)
+      return `Showing image from ${url.hostname}`
+    } catch {
+      return `Showing image: ${src}`
+    }
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  async checkPermissions(_input, _context): Promise<PermissionDecision> {
+    return {
+      behavior: 'allow',
+      updatedInput: _input,
+      decisionReason: { type: 'other', reason: 'ImageShowTool is read-only' },
+    }
+  },
+  async prompt(_options) {
+    return DESCRIPTION
+  },
+  async validateInput(input) {
+    const { src } = input
+    if (!src || src.trim().length === 0) {
+      return {
+        result: false,
+        message: 'Error: "src" is required and cannot be empty.',
+        meta: { reason: 'missing_src' },
+        errorCode: 1,
+      }
+    }
+    return { result: true }
+  },
+  renderToolUseMessage,
+  renderToolResultMessage,
+  async call({ src }) {
+    try {
+      const image = await loadImage(src)
+      const dims = calculateDimensions(
+        image.bitmap.width,
+        image.bitmap.height,
+        80,
+      )
+      void dims
+      return {
+        data: {
+          src,
+          success: true,
+        } satisfies Output,
+      }
+    } catch (error) {
+      return {
+        data: {
+          src,
+          success: false,
+        } satisfies Output,
+      }
+    }
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: [
+        {
+          type: 'text',
+          text: output.success
+            ? `Image displayed: ${output.src}`
+            : `Failed to display image: ${output.src}`,
+        },
+      ],
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

src/tools/ImageShowTool/UI.tsx

@@ -1,76 +1,57 @@
-#!/usr/bin/env bun
-/**
- * Visual test: display a local image or URL using ink-picture + Ink.
- */
-
-import { useEffect, useState } from "react";
-import { render, Box, Text, useApp } from "ink";
-import Image, { InkPictureProvider } from "../../ink-picture/index.ts";
-import {
-  getImagePath,
-  isUrl,
-  loadImage,
-  calculateDimensions,
-  type ImageDimensions,
-} from "./ImageShowTool.ts";
-
-const args = process.argv.slice(2);
-const IMAGE_PATH = getImagePath(args);
-
-function App() {
-  const { exit } = useApp();
-  const [dimensions, setDimensions] = useState<ImageDimensions | null>(null);
-  const [err, setErr] = useState(false);
-
-  useEffect(() => {
-    (async () => {
-      try {
-        const image = await loadImage(IMAGE_PATH);
-        const dims = calculateDimensions(
-          image.bitmap.width,
-          image.bitmap.height,
-          process.stdout.columns ?? 80
-        );
-        setDimensions(dims);
-      } catch (e) {
-        console.error(e);
-        setErr(true);
-        exit();
-      }
-    })();
-  }, [exit]);
+import React from 'react'
+import { MessageResponse } from '../../components/MessageResponse.js'
+import { Box, Text } from '../../ink.js'
+
+export function renderToolUseMessage(
+  { src }: { src?: string },
+  { verbose }: { theme?: string; verbose: boolean },
+): React.ReactNode {
+  if (!src) return null
+  if (verbose) return `src: "${src}"`
+  return src
+}
 
-  useEffect(() => {
-    const handleSigint = () => exit();
-    process.on("SIGINT", handleSigint);
-    return () => {
-      process.off("SIGINT", handleSigint);
-    };
-  }, [exit]);
+export function renderToolUseProgressMessage(): React.ReactNode {
+  return (
+    <MessageResponse height={1}>
+      <Text dimColor>Rendering image…</Text>
+    </MessageResponse>
+  )
+}
 
-  if (err) {
-    return <Text color="red">Failed to fetch: {IMAGE_PATH}</Text>;
+export function renderToolResultMessage(
+  { src, success }: { src: string; success: boolean },
+  _progressMessages: unknown[],
+  { verbose }: { verbose: boolean },
+): React.ReactNode {
+  if (!success) {
+    return (
+      <MessageResponse height={1}>
+        <Text color="red">Failed to display: {src}</Text>
+      </MessageResponse>
+    )
   }
-
-  if (!dimensions) {
-    return <Text>Loading...</Text>;
+  if (verbose) {
+    return (
+      <Box flexDirection="column">
+        <MessageResponse height={1}>
+          <Text>
+            Image displayed: <Text bold>{src}</Text>
+          </Text>
+        </MessageResponse>
+      </Box>
+    )
   }
-
   return (
-    <Box flexDirection="column">
-      <InkPictureProvider>
-        <Image
-          src={IMAGE_PATH}
-          width={dimensions.width}
-          height={dimensions.height}
-          pixelWidth={dimensions.pixelWidth}
-          pixelHeight={dimensions.pixelHeight}
-          alt={isUrl(IMAGE_PATH) ? "url-image" : "local-image"}
-        />
-      </InkPictureProvider>
-    </Box>
-  );
+    <MessageResponse height={1}>
+      <Text>
+        Image displayed: <Text bold>{src}</Text>
+      </Text>
+    </MessageResponse>
+  )
 }
 
-const { waitUntilExit } = render(<App />);
-await waitUntilExit();
+export function getToolUseSummary(input: { src?: string } | undefined): string | null {
+  if (!input?.src) return null
+  return input.src.length > 80 ? input.src.slice(0, 77) + '...' : input.src
+}

src/tools/ImageShowTool/prompt.ts

@@ -0,0 +1,33 @@
+export const IMAGE_SHOW_TOOL_NAME = 'ImageShow'
+
+export const DESCRIPTION = `
+ImageShow — Display images directly in the terminal.
+
+This tool renders PNG/JPEG/GIF/WebP images in the terminal using Kitty sixel protocol via ink-picture. It supports both local file paths and HTTPS URLs.
+
+**When to use this tool:**
+- User asks to display, view, or show an image
+- Search results include image thumbnails that should be displayed inline
+- User references a local image path or URL and wants to see it
+- Any situation where visual inspection of an image is helpful
+
+**Input:**
+- \`src\`: Image source — either a local file path (e.g. \`/home/user/pic.png\`) or a HTTPS URL (e.g. \`https://example.com/image.jpg\`)
+
+**Supported formats:** PNG, JPEG, GIF, WebP
+
+**Usage examples:**
+- Display a local image: \`src: "/home/yuki/Pictures/wallpaper.jpg"\`
+- Display a remote image: \`src: "https://example.com/photo.png"\`
+- Display Google Street View: \`src: "https://maps.googleapis.com/maps/api/streetview?size=800x400&location=37.7749,-122.4194&key=..."\`
+
+**Rendering details:**
+- Image width is auto-calculated as ~16.18% of terminal width (golden ratio)
+- Height is derived from aspect ratio, with a minimum of 3 character cells
+- Supports sixel-capable terminals (Kitty, WezTerm, etc.)
+
+**Combining with other tools:**
+- WebSearch results with images → ImageShow displays them inline automatically
+- LocationTool place photos → ImageShow renders them
+- WebFetchTool image URLs → ImageShow displays the fetched content
+`

src/tools/ImageShowTool/standalone.tsx

@@ -0,0 +1,83 @@
+#!/usr/bin/env bun
+/**
+ * Standalone visual test: display a local image or URL using ink-picture + Ink.
+ *
+ * Usage:
+ *   bun run src/tools/ImageShowTool/standalone.tsx [path|url]
+ *
+ * Examples:
+ *   bun run src/tools/ImageShowTool/standalone.tsx ~/Pictures/image.png
+ *   bun run src/tools/ImageShowTool/standalone.tsx https://example.com/image.jpg
+ */
+
+import { useEffect, useState } from "react";
+import { render, Box, Text, useApp } from "ink";
+import Image, { InkPictureProvider } from "../../ink-picture/index.ts";
+import {
+  getImagePath,
+  isUrl,
+  loadImage,
+  calculateDimensions,
+  type ImageDimensions,
+} from "./ImageShowTool.ts";
+
+const args = process.argv.slice(2);
+const IMAGE_PATH = getImagePath(args);
+
+function App() {
+  const { exit } = useApp();
+  const [dimensions, setDimensions] = useState<ImageDimensions | null>(null);
+  const [err, setErr] = useState(false);
+
+  useEffect(() => {
+    (async () => {
+      try {
+        const image = await loadImage(IMAGE_PATH);
+        const dims = calculateDimensions(
+          image.bitmap.width,
+          image.bitmap.height,
+          process.stdout.columns ?? 80
+        );
+        setDimensions(dims);
+      } catch (e) {
+        console.error(e);
+        setErr(true);
+        exit();
+      }
+    })();
+  }, [exit]);
+
+  useEffect(() => {
+    const handleSigint = () => exit();
+    process.on("SIGINT", handleSigint);
+    return () => {
+      process.off("SIGINT", handleSigint);
+    };
+  }, [exit]);
+
+  if (err) {
+    return <Text color="red">Failed to fetch: {IMAGE_PATH}</Text>;
+  }
+
+  if (!dimensions) {
+    return <Text>Loading...</Text>;
+  }
+
+  return (
+    <Box flexDirection="column">
+      <InkPictureProvider>
+        <Image
+          src={IMAGE_PATH}
+          width={dimensions.width}
+          height={dimensions.height}
+          pixelWidth={dimensions.pixelWidth}
+          pixelHeight={dimensions.pixelHeight}
+          alt={isUrl(IMAGE_PATH) ? "url-image" : "local-image"}
+        />
+      </InkPictureProvider>
+    </Box>
+  );
+}
+
+const { waitUntilExit } = render(<App />);
+await waitUntilExit();