@anthodev/pi-tools-style 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-tools-style contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+<h1 align="center">pi-tools-style</h1>
+
+<p align="center"><strong>Give Pi tool activity clear, theme-aware structure without changing how tools run.</strong></p>
+
+`pi-tools-style` adds rounded frames, tool-specific icons, and live running indicators to Pi tool calls and direct shell commands. It decorates the output Pi already produces instead of replacing tool definitions or renderers.
+
+Built-in tools, MCP integrations, AFT, and third-party extensions keep control of their schemas, permissions, prompts, execution backends, and rendered content. When an output cannot be framed safely, the extension leaves it untouched.
+
+## Highlights
+
+- **Presentation without ownership** — wraps existing TUI output and never registers or replaces a tool.
+- **Theme-aware borders** — assigns semantic Pi theme colors by tool category and follows theme changes live.
+- **Three icon modes** — uses portable ASCII labels by default, richer Nerd Font glyphs when enabled, or icon-free titles.
+- **Live running state** — animates the title while a model tool call is still executing, then removes the spinner on completion.
+- **Terminal-correct sizing** — measures visible ANSI width before padding, truncating, or drawing borders.
+- **Renderer-friendly composition** — preserves Pi, AFT, MCP, and extension-provided output inside the frame.
+- **Image-safe fallback** — skips Kitty, iTerm2, and Sixel rows instead of corrupting terminal image sequences.
+- **Reload-safe state** — keeps wrappers and runtime configuration idempotent across `/reload`.
+
+## What it looks like
+
+ASCII mode stays readable in any terminal:
+
+```text
+╭─ [F] | read / ───────────────────────╮
+│ Reading README.md                    │
+╰──────────────────────────────────────╯
+```
+
+Nerd Font mode uses tool-specific glyphs and Braille spinner frames:
+
+```text
+╭─  | read ⠹ ─────────────────────────╮
+│ Reading README.md                    │
+╰──────────────────────────────────────╯
+```
+
+Once execution finishes, the spinner disappears and the title remains stable:
+
+```text
+╭─  | read ───────────────────────────╮
+│ README content                       │
+╰──────────────────────────────────────╯
+```
+
+Direct `!` and `!!` commands use the same frame with a `shell` title. Slash-command output remains unchanged because Pi does not expose one uniform transcript component for slash commands.
+
+## Installation
+
+The current release targets Pi `0.84.x` and requires Node.js 22 or newer.
+
+To install this checkout as a local Pi package:
+
+```bash
+cd /absolute/path/to/pi-tools-style
+npm install --legacy-peer-deps
+pi install "$(pwd)"
+```
+
+Pi stores the package in user settings and references the directory directly, so local changes become available after `/reload` or a restart.
+
+To install it only for the current project, run this from that project:
+
+```bash
+pi install -l /absolute/path/to/pi-tools-style
+```
+
+To try the extension without installing it:
+
+```bash
+pi -e /absolute/path/to/pi-tools-style/index.ts
+```
+
+Once the package is published to npm, it can also be installed with:
+
+```bash
+pi install npm:@anthodev/pi-tools-style
+```
+
+## Usage
+
+Boxes start enabled. Manage them from Pi with:
+
+```text
+/tools-style
+/tools-style on
+/tools-style off
+/tools-style icons ascii
+/tools-style icons nerd-font
+/tools-style icons off
+/tstyle
+```
+
+`/tools-style` toggles framing. `/tstyle` is a short alias with the same arguments. The explicit `on` and `off` forms set the desired state without depending on its current value.
+
+Icon mode persists in `~/.pi/agent/config/tools-style.json`. ASCII remains the package default; Nerd Font mode can be enabled once for terminals that provide the required glyphs. `icons off` keeps frames and the ASCII running spinner, but removes the static icon and its `|` separator from titles.
+
+```json
+{
+  "iconMode": "nerd-font"
+}
+```
+
+Set `PI_TOOLS_STYLE=0` before startup to load the extension with framing disabled.
+
+## Icons and running indicators
+
+Common tools receive dedicated icons, while unknown tools fall back to their semantic category.
+
+| Purpose | ASCII | Nerd Font | Examples |
+| --- | --- | --- | --- |
+| Read a file | `[F]` | `` | `read`, `read_symbol` |
+| Write a file | `[W]` | `` | `write` |
+| Edit content | `[E]` | `` | `replace`, `apply_patch` |
+| Run a command | `[$]` | `` | `bash`, shell tools |
+| Search | `[?]` | `` | `symbol_search`, `grep` |
+| Use the web | `[@]` | `` | `web_search`, browser tools |
+| Fetch content | `[v]` | `` | `fetch_content` |
+| Call MCP | `[M]` | `` | `mcp`, `mcpScript` |
+| Orchestrate work | `[*]` | `` | `workflow`, `subagent` |
+| Track tasks | `[#]` | `` | `todo` |
+| Ask the user | `[!]` | `` | `ask_user`, confirmation tools |
+| Show diagnostics | `[D]` | `` | `lsp_diagnostics`, `lens_diagnostics` |
+| Unknown tool | `[T]` | `` | third-party fallback |
+
+While a model tool call is active, ASCII mode cycles through `| / - \` and Nerd Font mode cycles through `⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏`. One shared timer drives all active titles and stops after completion, interruption, box disablement, stale transcript removal, or session shutdown.
+
+## Theme-aware palette
+
+Borders resolve their color from the active Pi theme on every render. Switching themes therefore updates existing tool categories without reloading the extension.
+
+| Category | Typical tools | Pi theme token |
+| --- | --- | --- |
+| Inspect | reads, searches, reports, diagnostics | `mdLink` |
+| Mutate | writes, edits, create/update/delete operations | `warning` |
+| Execute | bash, shell, tests, terminal commands | `bashMode` |
+| External | web, fetch, MCP, browser, GitHub, Slack | `syntaxType` |
+| Orchestrate | workflow, subagent, Ralph, todo | `customMessageLabel` |
+| Interact | ask, question, confirm, select | `accent` |
+| Other | unknown third-party tools | `borderMuted` |
+
+## How it works
+
+Pi `0.84.x` does not expose public render middleware around `ToolExecutionComponent` and `BashExecutionComponent`. `pi-tools-style` therefore installs a narrow wrapper around their existing `render()` methods.
+
+The wrapper asks the previous renderer to draw at the frame's inner width, removes only paired outer horizontal rules, and then adds ANSI-aware chrome. It does not call `pi.registerTool()`, replace tool definitions, or intercept execution.
+
+Configuration and animation state live behind `Symbol.for()` keys. Reloading updates the active configuration without stacking wrappers or leaving duplicate timers behind. Any incompatibility or decoration error falls back to Pi's original full-width renderer.
+
+## Compatibility and limits
+
+- Pi `0.84.x` is the supported target. Private TUI internals may change in later releases.
+- The render wrapper is necessarily unsupported until Pi exposes public, composable render middleware.
+- Kitty, iTerm2, and Sixel image output remains unboxed by design.
+- Slash commands remain outside the current scope because their transcript output has no uniform component.
+- Another extension can replace this wrapper if it overwrites component rendering without composing with the previous renderer.
+- Unsupported renderer shapes fail open rather than affecting tool execution.
+
+## Development
+
+Install dependencies and run the complete verification suite with:
+
+```bash
+npm install --legacy-peer-deps
+npm run check
+npm pack --dry-run --json
+```
+
+`npm run check` runs TypeScript validation and the Vitest suite. Tests cover frame width, ANSI output, terminal images, native and AFT rule removal, category colors, icon modes, persisted settings, spinner lifecycle, real `ToolExecutionComponent` integration, render composition, reload idempotence, fail-open behavior, and the no-`registerTool()` contract.
+
+`--legacy-peer-deps` avoids an npm 10.9.8 Arborist failure observed while resolving the development peer dependency graph.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,156 @@
+import {
+	BashExecutionComponent,
+	ToolExecutionComponent,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+	installRenderDecorator,
+	isRenderDecoratorEnabled,
+	setRenderDecoratorEnabled,
+	type InstallStatus,
+} from "./src/render-decorator.js";
+import { formatToolTitle } from "./src/tool-icon.ts";
+import {
+	clearToolSpinners,
+	toolSpinnerFrame,
+} from "./src/tool-spinner.ts";
+import {
+	getIconMode,
+	isIconMode,
+	loadSettings,
+	saveIconMode,
+} from "./src/settings.ts";
+import {
+	createCategoryBorderStyle,
+	createToolBorderStyle,
+	setThemeProvider,
+	type BorderStyle,
+} from "./src/tool-category.js";
+
+const TOOL_RENDER_KEY = Symbol.for("pi-tools-style:tool-render");
+const SHELL_RENDER_KEY = Symbol.for("pi-tools-style:shell-render");
+
+export interface InstallationResult {
+	shell: InstallStatus;
+	tools: InstallStatus;
+}
+
+export function installToolsStyle(): InstallationResult {
+	const enabled = process.env.PI_TOOLS_STYLE !== "0";
+
+	const tools = installRenderDecorator(ToolExecutionComponent, {
+		enabled,
+		key: TOOL_RENDER_KEY,
+		styleBorderFor: toolBorderStyle,
+		title: toolTitle,
+		trimOuterRules: true,
+	});
+	const shell = installRenderDecorator(BashExecutionComponent, {
+		enabled,
+		key: SHELL_RENDER_KEY,
+		styleBorderFor: () => createCategoryBorderStyle("execute"),
+		title: () => formatToolTitle("shell", getIconMode()),
+		trimOuterRules: true,
+	});
+
+	return { shell, tools };
+}
+
+export default function toolsStyleExtension(pi: ExtensionAPI): void {
+	const installation = installToolsStyle();
+	pi.on("session_start", async (_event, context) => {
+		clearToolSpinners();
+		await loadSettings();
+		setThemeProvider(() => context.ui.theme);
+	});
+	pi.on("session_shutdown", () => {
+		clearToolSpinners();
+		setThemeProvider(undefined);
+		return Promise.resolve();
+	});
+
+	const command = {
+		description: "Configure tool boxes and icon mode",
+		handler: async (args, context) => {
+			const [action = "", value, ...extra] = args
+				.trim()
+				.toLowerCase()
+				.split(/\s+/u);
+			const notifyUsage = (): void => {
+				context.ui.notify(
+					"Usage: /tools-style [on|off|icons ascii|icons nerd-font|icons off]",
+					"warning",
+				);
+			};
+
+			if (action === "icons") {
+				if (!isIconMode(value) || extra.length > 0) {
+					notifyUsage();
+					return;
+				}
+
+				await saveIconMode(value);
+				context.ui.notify(`Tool icons: ${value}.`);
+				return;
+			}
+
+			if (
+				(action !== "" && action !== "on" && action !== "off") ||
+				value !== undefined
+			) {
+				notifyUsage();
+				return;
+			}
+
+			if (
+				installation.tools === "unsupported" ||
+				installation.shell === "unsupported"
+			) {
+				context.ui.notify(
+					"Tool boxes unavailable: incompatible Pi renderer internals.",
+					"warning",
+				);
+				return;
+			}
+
+			const current = isRenderDecoratorEnabled(TOOL_RENDER_KEY);
+			const enabled = resolveRequestedState(action, current);
+
+			setRenderDecoratorEnabled(TOOL_RENDER_KEY, enabled);
+			setRenderDecoratorEnabled(SHELL_RENDER_KEY, enabled);
+			if (!enabled) clearToolSpinners();
+			context.ui.notify(`Tool boxes ${enabled ? "enabled" : "disabled"}.`);
+		},
+	} satisfies Parameters<ExtensionAPI["registerCommand"]>[1];
+
+	pi.registerCommand("tools-style", command);
+	pi.registerCommand("tstyle", {
+		...command,
+		description: "Alias for /tools-style",
+	});
+}
+
+function resolveRequestedState(requested: string, current: boolean): boolean {
+	if (requested === "on") return true;
+	if (requested === "off") return false;
+	return !current;
+}
+
+function toolName(component: ToolExecutionComponent): string {
+	const candidate = (component as unknown as { toolName?: unknown }).toolName;
+	return typeof candidate === "string" && candidate.length > 0
+		? candidate
+		: "tool";
+}
+
+function toolTitle(component: ToolExecutionComponent): string {
+	const mode = getIconMode();
+	const title = formatToolTitle(toolName(component), mode);
+	const spinner = toolSpinnerFrame(component, mode);
+	return spinner ? `${title} ${spinner}` : title;
+}
+
+function toolBorderStyle(component: ToolExecutionComponent): BorderStyle {
+	return createToolBorderStyle(toolName(component));
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@anthodev/pi-tools-style",
+  "version": "0.1.0",
+  "description": "Presentation-only boxes for Pi tool calls and shell commands",
+  "keywords": ["pi-package", "pi-extension", "tui", "tools"],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Anthodev/pi-tools-style.git"
+  },
+  "homepage": "https://github.com/Anthodev/pi-tools-style#readme",
+  "bugs": {
+    "url": "https://github.com/Anthodev/pi-tools-style/issues"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test",
+    "pack:check": "npm pack --dry-run --json",
+    "prepublishOnly": "npm run check"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.x",
+    "@earendil-works/pi-tui": "0.84.x"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
+    "@types/node": "24.12.0",
+    "typescript": "5.9.3",
+    "vitest": "4.1.9"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/frame.ts

@@ -0,0 +1,132 @@
+import {
+	stripTerminalSequences,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+
+const RESET = "\u001b[0m";
+const DEFAULT_PADDING = 1;
+const MINIMUM_FRAME_WIDTH = 5;
+const HORIZONTAL_RULE = /^[─━═╌╍┄┅┈┉-]+$/u;
+const TERMINAL_IMAGE_SEQUENCES = [
+	"\u001b_G", // Kitty graphics protocol
+	"\u001b]1337;File=", // iTerm2 inline images
+	"\u001bPq", // Sixel device control string
+	"\u0090q", // Eight-bit Sixel device control string
+] as const;
+
+export interface FrameOptions {
+	horizontalPadding?: number;
+	styleBorder?: (value: string) => string;
+	title?: string;
+}
+
+export function frameContentWidth(
+	width: number,
+	horizontalPadding = DEFAULT_PADDING,
+): number {
+	const padding = normalizePadding(horizontalPadding);
+	return Math.max(0, Math.floor(width) - 2 - padding * 2);
+}
+
+export function frameLines(
+	sourceLines: readonly string[],
+	width: number,
+	options: FrameOptions = {},
+): string[] {
+	const lines = [...sourceLines];
+	const outerWidth = Math.floor(width);
+	const padding = normalizePadding(options.horizontalPadding);
+
+	if (
+		lines.length === 0 ||
+		outerWidth < MINIMUM_FRAME_WIDTH ||
+		containsTerminalImage(lines)
+	) {
+		return lines;
+	}
+
+	const contentWidth = frameContentWidth(outerWidth, padding);
+	if (contentWidth < 1) return lines;
+
+	const styleBorder = options.styleBorder ?? identity;
+	const horizontalPadding = " ".repeat(padding);
+	const top = renderTopBorder(outerWidth, options.title, styleBorder);
+	const bottom = styleBorder(`╰${"─".repeat(outerWidth - 2)}╯`);
+	const body = lines.map((line) => {
+		const content = truncateToWidth(line, contentWidth, "");
+		const remaining = Math.max(0, contentWidth - visibleWidth(content));
+
+		const reset = content.includes("\u001b") ? RESET : "";
+		return `${styleBorder("│")}${horizontalPadding}${content}${reset}${" ".repeat(
+			remaining,
+		)}${horizontalPadding}${styleBorder("│")}`;
+	});
+
+	return [top, ...body, bottom];
+}
+
+export function containsTerminalImage(lines: readonly string[]): boolean {
+	return lines.some((line) =>
+		TERMINAL_IMAGE_SEQUENCES.some((sequence) => line.includes(sequence)),
+	);
+}
+
+export function trimOuterRules(sourceLines: readonly string[]): string[] {
+	const lines = [...sourceLines];
+
+	const firstRuleIndex =
+		lines.length > 1 &&
+		stripTerminalSequences(lines[0] ?? "").trim() === "" &&
+		isHorizontalRule(lines[1] ?? "")
+			? 1
+			: 0;
+	const lastRuleIndex = lines.length - 1;
+
+	if (
+		firstRuleIndex < lastRuleIndex &&
+		isHorizontalRule(lines[firstRuleIndex] ?? "") &&
+		isHorizontalRule(lines[lastRuleIndex] ?? "")
+	) {
+		return lines.slice(firstRuleIndex + 1, lastRuleIndex);
+	}
+
+	return lines;
+}
+
+function renderTopBorder(
+	width: number,
+	rawTitle: string | undefined,
+	styleBorder: (value: string) => string,
+): string {
+	const title = normalizeTitle(rawTitle);
+	const maxTitleWidth = Math.max(0, width - 6);
+
+	if (!title || maxTitleWidth < 1) {
+		return styleBorder(`╭${"─".repeat(width - 2)}╮`);
+	}
+
+	const visibleTitle = truncateToWidth(title, maxTitleWidth, "");
+	const prefix = `╭─ ${visibleTitle} `;
+	const fill = "─".repeat(Math.max(1, width - visibleWidth(prefix) - 1));
+	return `${styleBorder(prefix)}${styleBorder(fill)}${styleBorder("╮")}`;
+}
+
+function isHorizontalRule(line: string): boolean {
+	const visible = stripTerminalSequences(line).trim();
+	return visible.length > 0 && HORIZONTAL_RULE.test(visible);
+}
+
+function normalizePadding(value: number | undefined): number {
+	if (value === undefined || !Number.isFinite(value)) return DEFAULT_PADDING;
+	return Math.max(0, Math.floor(value));
+}
+
+function normalizeTitle(value: string | undefined): string {
+	if (!value) return "";
+	return stripTerminalSequences(value).replace(/\s+/gu, " ").trim();
+}
+
+function identity(value: string): string {
+	return value;
+}

package/src/render-decorator.ts

@@ -0,0 +1,155 @@
+import {
+	containsTerminalImage,
+	frameContentWidth,
+	frameLines,
+	trimOuterRules,
+	type FrameOptions,
+} from "./frame.js";
+
+interface Renderable {
+	render(width: number): string[];
+}
+
+type RenderableConstructor<T extends Renderable = Renderable> = abstract new (
+	...args: never[]
+) => T;
+
+type RenderFunction = (this: Renderable, width: number) => string[];
+type DecoratedPrototype = Renderable & Record<symbol, unknown>;
+
+export interface RenderDecoratorConfig<T extends Renderable = Renderable>
+	extends Omit<FrameOptions, "title"> {
+	enabled?: boolean;
+	key: symbol;
+	styleBorderFor?: (
+		instance: T,
+	) => NonNullable<FrameOptions["styleBorder"]>;
+	title?: (instance: T) => string | undefined;
+	trimOuterRules?: boolean;
+}
+
+export type InstallStatus = "already-installed" | "installed" | "unsupported";
+
+interface StoredConfig extends Omit<RenderDecoratorConfig, "enabled"> {
+	enabled: boolean;
+}
+
+export function installRenderDecorator<T extends Renderable>(
+	component: RenderableConstructor<T>,
+	config: RenderDecoratorConfig<T>,
+): InstallStatus {
+	const prototype = component.prototype as DecoratedPrototype;
+
+	if (prototype[config.key] === true) {
+		storeConfig(config);
+		return "already-installed";
+	}
+
+	const renderOriginal = resolveOriginalRenderer(prototype);
+	if (!renderOriginal) return "unsupported";
+
+	storeConfig(config);
+
+	Object.defineProperty(prototype, "render", {
+		configurable: true,
+		value: createDecoratedRenderer(config.key, renderOriginal),
+		writable: true,
+	});
+	Object.defineProperty(prototype, config.key, {
+		configurable: false,
+		value: true,
+		writable: false,
+	});
+
+	return "installed";
+}
+
+export function isRenderDecoratorEnabled(key: symbol): boolean {
+	return readConfig(key)?.enabled ?? false;
+}
+
+export function setRenderDecoratorEnabled(key: symbol, enabled: boolean): void {
+	const current = readConfig(key);
+	if (current) Reflect.set(globalThis, key, { ...current, enabled });
+}
+
+function resolveOriginalRenderer(
+	prototype: DecoratedPrototype,
+): RenderFunction | undefined {
+	if (Object.hasOwn(prototype, "render")) {
+		const ownRenderer = prototype.render;
+		return typeof ownRenderer === "function" ? ownRenderer : undefined;
+	}
+
+	const parent = Object.getPrototypeOf(prototype) as Renderable | null;
+	if (typeof parent?.render !== "function") return undefined;
+
+	return function renderInherited(width: number): string[] {
+		const currentParent = Object.getPrototypeOf(prototype) as Renderable | null;
+		return typeof currentParent?.render === "function"
+			? currentParent.render.call(this, width)
+			: [];
+	};
+}
+
+function createDecoratedRenderer(
+	key: symbol,
+	renderOriginal: RenderFunction,
+): RenderFunction {
+	return function decoratedRender(width: number): string[] {
+		const current = readConfig(key);
+		if (!current?.enabled) return renderOriginal.call(this, width);
+
+		const innerWidth = frameContentWidth(width, current.horizontalPadding);
+		if (innerWidth < 1) return renderOriginal.call(this, width);
+
+		const rendered = renderOriginal.call(this, innerWidth);
+		if (containsTerminalImage(rendered)) {
+			return renderOriginal.call(this, width);
+		}
+
+		try {
+			return decorateLines(this, rendered, width, current);
+		} catch {
+			return renderOriginal.call(this, width);
+		}
+	};
+}
+
+function decorateLines(
+	instance: Renderable,
+	rendered: readonly string[],
+	width: number,
+	config: StoredConfig,
+): string[] {
+	const lines = config.trimOuterRules
+		? trimOuterRules(rendered)
+		: [...rendered];
+	const title = config.title?.(instance);
+	const options: FrameOptions = {};
+
+	if (config.horizontalPadding !== undefined) {
+		options.horizontalPadding = config.horizontalPadding;
+	}
+	const styleBorder = config.styleBorderFor?.(instance) ?? config.styleBorder;
+	if (styleBorder !== undefined) {
+		options.styleBorder = styleBorder;
+	}
+	if (title) options.title = title;
+
+	return frameLines(lines, width, options);
+}
+
+function storeConfig<T extends Renderable>(
+	config: RenderDecoratorConfig<T>,
+): void {
+	const stored: StoredConfig = {
+		...config,
+		enabled: config.enabled ?? true,
+	} as StoredConfig;
+	Reflect.set(globalThis, config.key, stored);
+}
+
+function readConfig(key: symbol): StoredConfig | undefined {
+	return Reflect.get(globalThis, key) as StoredConfig | undefined;
+}

package/src/settings.ts

@@ -0,0 +1,65 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import type { IconMode } from "./tool-icon.js";
+
+interface ToolsStyleSettings {
+	iconMode: IconMode;
+}
+
+const SETTINGS_KEY = Symbol.for("pi-tools-style:settings");
+const DEFAULT_SETTINGS: Readonly<ToolsStyleSettings> = {
+	iconMode: "ascii",
+};
+
+export function getIconMode(): IconMode {
+	return getSettings().iconMode;
+}
+
+export function setIconMode(iconMode: IconMode): void {
+	Reflect.set(globalThis, SETTINGS_KEY, {
+		iconMode,
+	} satisfies ToolsStyleSettings);
+}
+
+export async function loadSettings(path = getSettingsPath()): Promise<void> {
+	setIconMode(DEFAULT_SETTINGS.iconMode);
+
+	try {
+		const parsed = JSON.parse(await readFile(path, "utf8")) as {
+			iconMode?: unknown;
+		};
+		if (isIconMode(parsed.iconMode)) setIconMode(parsed.iconMode);
+	} catch {
+		// Missing or malformed user config intentionally falls back to ASCII.
+	}
+}
+
+export async function saveIconMode(
+	iconMode: IconMode,
+	path = getSettingsPath(),
+): Promise<void> {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify({ iconMode }, null, 2)}\n`, "utf8");
+	setIconMode(iconMode);
+}
+
+function getSettingsPath(): string {
+	return join(getAgentDir(), "config", "tools-style.json");
+}
+
+function getSettings(): ToolsStyleSettings {
+	const current = Reflect.get(globalThis, SETTINGS_KEY) as
+		| ToolsStyleSettings
+		| undefined;
+	if (current) return current;
+
+	const initial = { ...DEFAULT_SETTINGS };
+	Reflect.set(globalThis, SETTINGS_KEY, initial);
+	return initial;
+}
+
+export function isIconMode(value: unknown): value is IconMode {
+	return value === "ascii" || value === "nerd-font" || value === "off";
+}

package/src/tool-category.ts

@@ -0,0 +1,163 @@
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+
+export type ToolCategory =
+	| "execute"
+	| "external"
+	| "inspect"
+	| "interact"
+	| "mutate"
+	| "orchestrate"
+	| "other";
+
+export type BorderStyle = (value: string) => string;
+type ThemeProvider = () => Theme;
+
+const THEME_PROVIDER_KEY = Symbol.for("pi-tools-style:theme-provider");
+const DIM = "\u001b[2m";
+const RESET_DIM = "\u001b[22m";
+
+const CATEGORY_THEME_COLOR: Record<ToolCategory, ThemeColor> = {
+	execute: "bashMode",
+	external: "syntaxType",
+	inspect: "mdLink",
+	interact: "accent",
+	mutate: "warning",
+	orchestrate: "customMessageLabel",
+	other: "borderMuted",
+};
+
+const EXTERNAL_NAMESPACES = new Set([
+	"api",
+	"browser",
+	"fetch",
+	"github",
+	"http",
+	"jira",
+	"linear",
+	"mcp",
+	"slack",
+	"source",
+	"web",
+]);
+const ORCHESTRATION_NAMES = new Set([
+	"manage_todo_list",
+	"ralph_done",
+	"ralph_start",
+	"subagent",
+	"subagent_supervisor",
+	"subagent_wait",
+	"todo",
+	"workflow",
+	"workflow_control",
+]);
+const INTERACTION_TERMS = new Set([
+	"ask",
+	"confirm",
+	"prompt",
+	"question",
+	"questionnaire",
+	"select",
+]);
+const EXECUTION_TERMS = new Set([
+	"bash",
+	"build",
+	"command",
+	"exec",
+	"execute",
+	"run",
+	"shell",
+	"terminal",
+	"test",
+]);
+const MUTATION_TERMS = new Set([
+	"add",
+	"apply",
+	"create",
+	"delete",
+	"edit",
+	"mark",
+	"patch",
+	"remove",
+	"replace",
+	"set",
+	"undo",
+	"update",
+	"write",
+]);
+const INSPECTION_TERMS = new Set([
+	"diagnostics",
+	"find",
+	"get",
+	"grep",
+	"inspect",
+	"lens",
+	"list",
+	"lsp",
+	"query",
+	"read",
+	"report",
+	"resolve",
+	"search",
+	"show",
+	"status",
+	"symbol",
+]);
+
+export function classifyTool(toolName: string): ToolCategory {
+	const normalized = normalizeToolName(toolName);
+	const terms = normalized.split("_").filter(Boolean);
+	const namespace = terms[0] ?? "";
+
+	if (EXTERNAL_NAMESPACES.has(namespace)) return "external";
+	if (ORCHESTRATION_NAMES.has(normalized)) return "orchestrate";
+	if (terms.some((term) => INTERACTION_TERMS.has(term))) return "interact";
+	if (terms.some((term) => EXECUTION_TERMS.has(term))) return "execute";
+	if (terms.some((term) => MUTATION_TERMS.has(term))) return "mutate";
+	if (terms.some((term) => INSPECTION_TERMS.has(term))) return "inspect";
+	return "other";
+}
+
+export function createToolBorderStyle(toolName: string): BorderStyle {
+	return createCategoryBorderStyle(classifyTool(toolName));
+}
+
+export function createCategoryBorderStyle(category: ToolCategory): BorderStyle {
+	const theme = readTheme();
+	if (!theme) return dimBorder;
+
+	const color = CATEGORY_THEME_COLOR[category];
+	return (value) => theme.fg(color, value);
+}
+
+export function setThemeProvider(provider: ThemeProvider | undefined): void {
+	if (provider) {
+		Reflect.set(globalThis, THEME_PROVIDER_KEY, provider);
+		return;
+	}
+	Reflect.deleteProperty(globalThis, THEME_PROVIDER_KEY);
+}
+
+function readTheme(): Theme | undefined {
+	const provider = Reflect.get(globalThis, THEME_PROVIDER_KEY) as
+		| ThemeProvider
+		| undefined;
+	if (!provider) return undefined;
+
+	try {
+		return provider();
+	} catch {
+		return undefined;
+	}
+}
+
+function normalizeToolName(toolName: string): string {
+	return toolName
+		.replace(/([a-z\d])([A-Z])/gu, "$1_$2")
+		.replace(/[^a-zA-Z\d]+/gu, "_")
+		.replace(/^_+|_+$/gu, "")
+		.toLowerCase();
+}
+
+function dimBorder(value: string): string {
+	return `${DIM}${value}${RESET_DIM}`;
+}

package/src/tool-icon.ts

@@ -0,0 +1,155 @@
+import { classifyTool, type ToolCategory } from "./tool-category.js";
+
+export type IconMode = "ascii" | "nerd-font" | "off";
+
+type IconKind =
+	| "bug"
+	| "download"
+	| "edit"
+	| "file"
+	| "globe"
+	| "list"
+	| "plug"
+	| "question"
+	| "save"
+	| "search"
+	| "sitemap"
+	| "terminal"
+	| "wrench";
+
+const ASCII_ICONS: Record<IconKind, string> = {
+	bug: "[D]",
+	download: "[v]",
+	edit: "[E]",
+	file: "[F]",
+	globe: "[@]",
+	list: "[#]",
+	plug: "[M]",
+	question: "[!]",
+	save: "[W]",
+	search: "[?]",
+	sitemap: "[*]",
+	terminal: "[$]",
+	wrench: "[T]",
+};
+
+const NERD_FONT_ICONS: Record<IconKind, string> = {
+	bug: "", // nf-fa-bug
+	download: "", // nf-fa-cloud_download
+	edit: "", // nf-fa-edit
+	file: "", // nf-fa-file
+	globe: "", // nf-fa-globe
+	list: "", // nf-fa-list
+	plug: "", // nf-fa-plug
+	question: "", // nf-fa-question_circle
+	save: "", // nf-fa-save
+	search: "", // nf-fa-search
+	sitemap: "", // nf-fa-sitemap
+	terminal: "", // nf-fa-terminal
+	wrench: "", // nf-fa-wrench
+};
+
+const CATEGORY_ICON: Record<ToolCategory, IconKind> = {
+	execute: "terminal",
+	external: "globe",
+	inspect: "search",
+	interact: "question",
+	mutate: "edit",
+	orchestrate: "sitemap",
+	other: "wrench",
+};
+
+const DIAGNOSTIC_TERMS = new Set(["diagnostics", "lens", "lsp"]);
+const EDIT_TERMS = new Set(["edit", "patch", "replace"]);
+const QUESTION_TERMS = new Set(["ask", "confirm", "question"]);
+const SEARCH_TERMS = new Set(["find", "grep", "search", "symbol"]);
+const EXECUTION_TERMS = new Set([
+	"bash",
+	"command",
+	"exec",
+	"execute",
+	"run",
+	"shell",
+	"terminal",
+]);
+
+export function formatToolTitle(toolName: string, mode: IconMode): string {
+	if (mode === "off") return toolName;
+	return `${iconForTool(toolName, mode)} | ${toolName}`;
+}
+
+function iconForTool(
+	toolName: string,
+	mode: Exclude<IconMode, "off">,
+): string {
+	const kind = resolveIconKind(toolName);
+	return mode === "nerd-font" ? NERD_FONT_ICONS[kind] : ASCII_ICONS[kind];
+}
+
+function resolveIconKind(toolName: string): IconKind {
+	const normalized = normalizeToolName(toolName);
+	const terms = normalized.split("_").filter(Boolean);
+	const namespace = terms[0] ?? "";
+
+	return (
+		resolveDocumentIcon(normalized, terms) ??
+		resolveExternalIcon(normalized, namespace) ??
+		resolveOrchestrationIcon(normalized, namespace) ??
+		resolveActionIcon(terms) ??
+		CATEGORY_ICON[classifyTool(toolName)]
+	);
+}
+
+function resolveDocumentIcon(
+	normalized: string,
+	terms: readonly string[],
+): IconKind | undefined {
+	if (hasAnyTerm(terms, DIAGNOSTIC_TERMS)) return "bug";
+	if (normalized === "read" || normalized.startsWith("read_")) return "file";
+	if (normalized === "write") return "save";
+	if (hasAnyTerm(terms, EDIT_TERMS)) return "edit";
+	return undefined;
+}
+
+function resolveExternalIcon(
+	normalized: string,
+	namespace: string,
+): IconKind | undefined {
+	if (namespace === "fetch" || normalized === "get_search_content") {
+		return "download";
+	}
+	if (["web", "browser", "github", "slack"].includes(namespace)) {
+		return "globe";
+	}
+	return namespace === "mcp" ? "plug" : undefined;
+}
+
+function resolveOrchestrationIcon(
+	normalized: string,
+	namespace: string,
+): IconKind | undefined {
+	if (normalized === "manage_todo_list") return "sitemap";
+	if (["workflow", "subagent", "ralph"].includes(namespace)) return "sitemap";
+	return namespace === "todo" ? "list" : undefined;
+}
+
+function resolveActionIcon(terms: readonly string[]): IconKind | undefined {
+	if (hasAnyTerm(terms, QUESTION_TERMS)) return "question";
+	if (hasAnyTerm(terms, SEARCH_TERMS)) return "search";
+	return hasAnyTerm(terms, EXECUTION_TERMS) ? "terminal" : undefined;
+}
+
+function hasAnyTerm(
+	terms: readonly string[],
+	candidates: ReadonlySet<string>,
+): boolean {
+	return terms.some((term) => candidates.has(term));
+}
+
+function normalizeToolName(toolName: string): string {
+	return toolName
+		.replace(/([a-z\d])([A-Z])/gu, "$1_$2")
+		.replace(/[^a-zA-Z\d]+/gu, "_")
+		.replace(/^_+|_+$/gu, "")
+		.toLowerCase();
+}

package/src/tool-spinner.ts

@@ -0,0 +1,111 @@
+import type { IconMode } from "./tool-icon.js";
+
+interface SpinnerUi {
+  requestRender?: () => void;
+}
+
+interface ToolSpinnerTarget {
+  executionStarted?: unknown;
+  isPartial?: unknown;
+  ui?: SpinnerUi;
+}
+
+interface SpinnerRuntime {
+  frameIndex: number;
+  targets: Map<object, number>;
+  timer: NodeJS.Timeout | undefined;
+}
+
+const SPINNER_RUNTIME_KEY = Symbol.for("pi-tools-style:tool-spinner");
+const FRAME_INTERVAL_MS = 80;
+const STALE_TARGET_MS = 2_000;
+const ASCII_FRAMES = ["|", "/", "-", "\\"] as const;
+const NERD_FONT_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+
+export function toolSpinnerFrame(
+  target: object,
+  mode: IconMode,
+): string | undefined {
+  const runtime = getRuntime();
+  if (!isExecuting(target)) {
+    runtime.targets.delete(target);
+    stopTickerIfIdle(runtime);
+    return undefined;
+  }
+
+  runtime.targets.set(target, Date.now());
+  ensureTicker(runtime);
+  const frames = mode === "nerd-font" ? NERD_FONT_FRAMES : ASCII_FRAMES;
+  return frames[runtime.frameIndex % frames.length];
+}
+
+export function clearToolSpinners(): void {
+  const runtime = getRuntime();
+  if (runtime.timer) clearInterval(runtime.timer);
+  runtime.timer = undefined;
+  runtime.frameIndex = 0;
+  runtime.targets.clear();
+}
+
+function ensureTicker(runtime: SpinnerRuntime): void {
+  if (runtime.timer) return;
+
+  runtime.timer = setInterval(() => tick(runtime), FRAME_INTERVAL_MS);
+  runtime.timer.unref?.();
+}
+
+function tick(runtime: SpinnerRuntime): void {
+  runtime.frameIndex += 1;
+  const now = Date.now();
+  const activeUis = new Set<SpinnerUi>();
+
+  for (const [target, lastSeenAt] of runtime.targets) {
+    if (!isExecuting(target) || now - lastSeenAt > STALE_TARGET_MS) {
+      runtime.targets.delete(target);
+      continue;
+    }
+    const ui = readTarget(target).ui;
+    if (ui) activeUis.add(ui);
+  }
+
+  for (const ui of activeUis) {
+    try {
+      ui.requestRender?.();
+    } catch {
+      // Presentation failure must never affect tool execution.
+    }
+  }
+
+  stopTickerIfIdle(runtime);
+}
+
+function stopTickerIfIdle(runtime: SpinnerRuntime): void {
+  if (runtime.targets.size > 0 || !runtime.timer) return;
+  clearInterval(runtime.timer);
+  runtime.timer = undefined;
+  runtime.frameIndex = 0;
+}
+
+function isExecuting(target: object): boolean {
+  const fields = readTarget(target);
+  return fields.executionStarted === true && fields.isPartial === true;
+}
+
+function readTarget(target: object): ToolSpinnerTarget {
+  return target as ToolSpinnerTarget;
+}
+
+function getRuntime(): SpinnerRuntime {
+  const current = Reflect.get(globalThis, SPINNER_RUNTIME_KEY) as
+    | SpinnerRuntime
+    | undefined;
+  if (current) return current;
+
+  const runtime: SpinnerRuntime = {
+    frameIndex: 0,
+    targets: new Map(),
+    timer: undefined,
+  };
+  Reflect.set(globalThis, SPINNER_RUNTIME_KEY, runtime);
+  return runtime;
+}