@xynogen/pix-toolbox 0.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@xynogen/pix-toolbox",
+	"version": "0.1.0",
+	"description": "Pi tool — gated tool toggle UI (/toolbox)",
+	"type": "module",
+	"main": "src/index.ts",
+	"scripts": {
+		"test": "bun test"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"src/index.ts"
+		]
+	},
+	"keywords": [
+		"pi",
+		"pi-package",
+		"pi-extension",
+		"toolbox"
+	],
+	"author": "xynogen",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xynogen/pix-mono.git",
+		"directory": "packages/pix-toolbox"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	}
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./toolbox.js";

package/src/toolbox.test.ts

@@ -0,0 +1,314 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import registerToolbox, {
+	buildRows,
+	parseTargets,
+	renderList,
+	type ToggleOps,
+	type ToolRow,
+	toggleTool,
+} from "./toolbox.ts";
+
+// ─── Fixtures ───────────────────────────────────────────────────────────────
+
+const toolInfo = (name: string, source = "builtin") =>
+	({
+		name,
+		description: `${name} does things.`,
+		parameters: {},
+		sourceInfo: { source, path: "", scope: "user", origin: "package" },
+	}) as never;
+
+const mcpToolInfo = (name: string) => toolInfo(name, "mcp:context7");
+
+// ─── buildRows ──────────────────────────────────────────────────────────────
+
+describe("buildRows", () => {
+	test("excludes core tools (bash, edit, read, write)", () => {
+		const rows = buildRows([
+			toolInfo("bash"),
+			toolInfo("edit"),
+			toolInfo("read"),
+			toolInfo("write"),
+			toolInfo("grep"),
+			toolInfo("ls"),
+		]);
+		expect(rows.map((r) => r.name)).toEqual(["grep", "ls"]);
+		expect(rows.every((r) => !r.mcp)).toBe(true);
+	});
+
+	test("flags MCP tools", () => {
+		const rows = buildRows([mcpToolInfo("ctx_search")]);
+		expect(rows[0].mcp).toBe(true);
+	});
+
+	test("empty input returns empty", () => {
+		expect(buildRows([])).toEqual([]);
+	});
+});
+
+// ─── parseTargets ───────────────────────────────────────────────────────────
+
+describe("parseTargets", () => {
+	test("splits on commas, spaces, newlines", () => {
+		expect(parseTargets("ls, find  grep\nfetch")).toEqual([
+			"ls",
+			"find",
+			"grep",
+			"fetch",
+		]);
+	});
+
+	test("dedupes", () => {
+		expect(parseTargets("ls, ls")).toEqual(["ls"]);
+	});
+
+	test("empty yields empty", () => {
+		expect(parseTargets("")).toEqual([]);
+		expect(parseTargets("  , ")).toEqual([]);
+	});
+});
+
+// ─── renderList ─────────────────────────────────────────────────────────────
+
+describe("renderList", () => {
+	const rows: ToolRow[] = [
+		{ name: "read", description: "Read files.", mcp: false },
+		{ name: "grep", description: "Search files.", mcp: false },
+		{ name: "ctx", description: "MCP search.", mcp: true },
+	];
+	const isActive = (n: string) => n === "read";
+
+	test("shows status for each tool", () => {
+		const out = renderList(rows, isActive);
+		expect(out).toContain("✓ active  read");
+		expect(out).toContain("# gated  grep");
+		expect(out).toContain("# gated  ctx");
+		expect(out).toContain("[MCP]");
+	});
+
+	test("filters by query", () => {
+		const out = renderList(rows, isActive, "grep");
+		expect(out).toContain("grep");
+		expect(out).not.toContain("read");
+	});
+
+	test("no match message", () => {
+		const out = renderList(rows, isActive, "zzz");
+		expect(out).toContain('No tools matched "zzz"');
+	});
+
+	test("empty rows", () => {
+		expect(renderList([], isActive)).toContain("No tools registered");
+	});
+});
+
+// ─── toggleTool ─────────────────────────────────────────────────────────────
+
+describe("toggleTool", () => {
+	const rows: ToolRow[] = [
+		{ name: "read", description: "Read.", mcp: false },
+		{ name: "grep", description: "Search.", mcp: false },
+	];
+
+	test("enable calls onActivate", () => {
+		let called = "";
+		const ops: ToggleOps = {
+			onActivate: (n) => {
+				called = n;
+				return true;
+			},
+			onDeactivate: () => false,
+			isActive: () => false,
+		};
+		const msg = toggleTool("enable", "grep", rows, ops);
+		expect(called).toBe("grep");
+		expect(msg).toContain("Enabled grep");
+	});
+
+	test("disable calls onDeactivate", () => {
+		let called = "";
+		const ops: ToggleOps = {
+			onActivate: () => false,
+			onDeactivate: (n) => {
+				called = n;
+				return true;
+			},
+			isActive: () => true,
+		};
+		const msg = toggleTool("disable", "read", rows, ops);
+		expect(called).toBe("read");
+		expect(msg).toContain("Disabled read");
+	});
+
+	test("unknown tool returns error", () => {
+		const ops: ToggleOps = {
+			onActivate: () => false,
+			onDeactivate: () => false,
+			isActive: () => false,
+		};
+		expect(toggleTool("enable", "nope", rows, ops)).toContain("Unknown");
+	});
+
+	test("already active returns already message", () => {
+		const ops: ToggleOps = {
+			onActivate: () => false,
+			onDeactivate: () => false,
+			isActive: () => true,
+		};
+		expect(toggleTool("enable", "read", rows, ops)).toContain("already");
+	});
+
+	test("already gated returns already message", () => {
+		const ops: ToggleOps = {
+			onActivate: () => false,
+			onDeactivate: () => false,
+			isActive: () => false,
+		};
+		expect(toggleTool("disable", "read", rows, ops)).toContain("already");
+	});
+});
+
+// ─── Integration: /toolbox command ──────────────────────────────────────────
+
+// Isolate from real ~/.pi/agent/toolbox.json on disk
+let tmpAgentDir: string;
+beforeAll(() => {
+	tmpAgentDir = mkdtempSync(join(tmpdir(), "toolbox-test-"));
+	process.env.PI_CODING_AGENT_DIR = tmpAgentDir;
+});
+afterAll(() => {
+	delete process.env.PI_CODING_AGENT_DIR;
+	try {
+		rmSync(tmpAgentDir, { recursive: true });
+	} catch {
+		// temp dir may already be gone — safe to ignore
+	}
+});
+
+function makeHost(toolNames: string[]) {
+	const handlers: Record<string, Array<(p: unknown) => unknown>> = {};
+	let active: string[] = [...toolNames];
+	const commands: Array<{ name: string; handler: Function }> = [];
+	const pi = {
+		on(ev: string, fn: (p: unknown) => unknown) {
+			(handlers[ev] ??= []).push(fn);
+		},
+		emit(ev: string, payload: unknown, ctx?: unknown) {
+			return Promise.all(
+				(handlers[ev] ?? []).map((f) => (f as Function)(payload, ctx)),
+			);
+		},
+		getAllTools() {
+			return toolNames.map((name) => ({
+				name,
+				description: `${name} does things.`,
+				parameters: {},
+				sourceInfo: { source: "builtin" },
+			}));
+		},
+		getActiveTools() {
+			return active;
+		},
+		setActiveTools(names: string[]) {
+			active = [...names];
+		},
+		getCommands() {
+			return [];
+		},
+		appendEntry() {},
+		registerTool() {},
+		registerCommand(name: string, def: { handler: Function }) {
+			commands.push({ name, handler: def.handler });
+		},
+	} as never;
+	const emit = (ev: string, payload: unknown, ctx?: unknown) =>
+		Promise.all((handlers[ev] ?? []).map((f) => (f as Function)(payload, ctx)));
+	return {
+		pi,
+		emit,
+		getActive: () => active,
+		command: (name: string) => commands.find((c) => c.name === name),
+	};
+}
+
+function makeCtx() {
+	const notes: Array<{ text: string; level?: string }> = [];
+	const ctx = {
+		ui: {
+			notify(text: string, level?: string) {
+				notes.push({ text, level });
+			},
+		},
+	} as never;
+	return { ctx, notes };
+}
+
+describe("/toolbox command", () => {
+	const ALL = ["read", "write", "bash", "grep", "find"];
+
+	async function boot() {
+		const host = makeHost(ALL);
+		registerToolbox(host.pi);
+		// session_start triggers init
+		await host.emit("session_start", {}, {});
+		return host;
+	}
+
+	test("registers a /toolbox command", async () => {
+		const host = await boot();
+		expect(host.command("toolbox")).toBeDefined();
+	});
+
+	test("bare /toolbox falls back to listing when no custom UI", async () => {
+		const host = await boot();
+		const { ctx, notes } = makeCtx();
+		await host.command("toolbox")?.handler("", ctx);
+		expect(notes.length).toBe(1);
+		// only non-core tools shown, all start active
+		expect(notes[0].text).toContain("✓ active  grep");
+		expect(notes[0].text).toContain("✓ active  find");
+		// core tools excluded from toolbox
+		expect(notes[0].text).not.toContain("  read");
+		expect(notes[0].text).not.toContain("  bash");
+	});
+
+	test("/toolbox list shows non-core tools with status", async () => {
+		const host = await boot();
+		const { ctx, notes } = makeCtx();
+		await host.command("toolbox")?.handler("list", ctx);
+		expect(notes[0].text).toContain("grep");
+		expect(notes[0].text).toContain("find");
+		expect(notes[0].text).not.toContain("  bash");
+	});
+
+	test("/toolbox list <query> filters", async () => {
+		const host = await boot();
+		const { ctx, notes } = makeCtx();
+		await host.command("toolbox")?.handler("list fin", ctx);
+		expect(notes[0].text).toContain("find");
+		expect(notes[0].text).not.toContain("✓ active  read");
+	});
+
+	test("opens interactive picker when ctx.ui.custom exists", async () => {
+		const host = await boot();
+		let customCalled = 0;
+		const notes: Array<{ text: string; level?: string }> = [];
+		const ctx = {
+			ui: {
+				notify(text: string, level?: string) {
+					notes.push({ text, level });
+				},
+				async custom() {
+					customCalled++;
+					return null;
+				},
+			},
+		} as never;
+		await host.command("toolbox")?.handler("", ctx);
+		expect(customCalled).toBe(1);
+		expect(notes.length).toBe(0);
+	});
+});

package/src/toolbox.ts

@@ -0,0 +1,570 @@
+/**
+ * toolbox.ts — /toolbox command for user-driven tool gating
+ *
+ * Registers a `/toolbox` slash command that opens a TUI picker listing every
+ * registered tool (built-in and MCP). The user can toggle tools on/off —
+ * this controls which tools are described in the system prompt via
+ * pi.setActiveTools(). All tools remain callable via function definitions
+ * regardless of prompt visibility.
+ *
+ * Also supports headless usage:
+ *   /toolbox enable <names>   — enable tool(s) by name
+ *   /toolbox disable <names>  — disable tool(s) by name
+ *   /toolbox list [query]     — text search (no picker)
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	Theme,
+	ToolInfo,
+} from "@earendil-works/pi-coding-agent";
+import { DynamicBorder, getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	decodeKittyPrintable,
+	fuzzyFilter,
+	Input,
+	Key,
+	type KeybindingsManager,
+	matchesKey,
+	type SelectItem,
+	SelectList,
+	Text,
+	type TUI,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+/** Tools that can never be disabled — always prompt-visible. */
+export const CORE_TOOLS: ReadonlySet<string> = new Set([
+	"bash",
+	"edit",
+	"read",
+	"write",
+]);
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ToolRow {
+	name: string;
+	description: string;
+	mcp: boolean;
+	source?: string;
+}
+
+/** Callbacks for toggleTool / renderList — test seam. */
+export interface ToggleOps {
+	isActive: (name: string) => boolean;
+	onActivate: (name: string) => boolean;
+	onDeactivate: (name: string) => boolean;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function isMcpTool(info: ToolInfo): boolean {
+	return /mcp/i.test(info.sourceInfo?.source ?? "");
+}
+
+export function buildRows(tools: ToolInfo[]): ToolRow[] {
+	return tools
+		.filter((t) => !CORE_TOOLS.has(t.name))
+		.map((t) => ({
+			name: t.name,
+			description: firstSentence(t.description ?? ""),
+			mcp: isMcpTool(t),
+			source: t.sourceInfo?.source,
+		}))
+		.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const firstSentence = (desc: string): string => {
+	const clean = (desc ?? "").replace(/\s+/g, " ").trim();
+	const m = clean.match(/^.*?[.!?](?=\s|$)/);
+	return (m ? m[0] : clean).slice(0, 120);
+};
+
+export function parseTargets(raw: string): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const t of raw.split(/[\s,]+/)) {
+		const name = t.trim();
+		if (!name || seen.has(name)) continue;
+		seen.add(name);
+		out.push(name);
+	}
+	return out;
+}
+
+export function renderList(
+	rows: ToolRow[],
+	isActive: (name: string) => boolean,
+	query?: string,
+): string {
+	const filtered = query
+		? rows.filter(
+				(r) =>
+					r.name.toLowerCase().includes(query.toLowerCase()) ||
+					r.description.toLowerCase().includes(query.toLowerCase()),
+			)
+		: rows;
+
+	if (!filtered.length) {
+		return query ? `No tools matched "${query}".` : "No tools registered.";
+	}
+
+	const lines = filtered.map((r) => {
+		const status = isActive(r.name) ? "✓ active" : "# gated";
+		const kind = r.mcp ? "MCP" : "tool";
+		return `${status}  ${r.name}  [${kind}]  ${r.description}`;
+	});
+	return lines.join("\n");
+}
+
+export function toggleTool(
+	action: "enable" | "disable",
+	name: string,
+	rows: ToolRow[],
+	ops: ToggleOps,
+): string {
+	const row = rows.find((r) => r.name === name);
+	if (!row) return `Unknown tool "${name}".`;
+
+	if (action === "enable") {
+		const did = ops.onActivate(name);
+		return did
+			? `Enabled ${name} — now prompt-visible.`
+			: `${name} is already active.`;
+	}
+	const did = ops.onDeactivate(name);
+	return did
+		? `Disabled ${name} — hidden from prompt.`
+		: `${name} is already gated.`;
+}
+
+// ─── Persistence ───────────────────────────────────────────────────────────
+
+interface ToolboxState {
+	enabledTools: string[];
+}
+
+function getStatePath(): string {
+	return join(getAgentDir(), "toolbox.json");
+}
+
+// ─── State ──────────────────────────────────────────────────────────────────
+
+function createState(pi: ExtensionAPI) {
+	let enabledTools = new Set<string>();
+	let initialized = false;
+
+	function persist(): void {
+		// Write to session so state survives branch navigation within a session
+		try {
+			pi.appendEntry<ToolboxState>("toolbox-config", {
+				enabledTools: [...enabledTools],
+			});
+		} catch (err) {
+			console.warn("toolbox: persist failed:", err);
+		}
+		// Write to disk so state survives across completely new sessions
+		try {
+			const sp = getStatePath();
+			mkdirSync(dirname(sp), { recursive: true });
+			writeFileSync(
+				sp,
+				JSON.stringify({ enabledTools: [...enabledTools] }, null, 2),
+				"utf-8",
+			);
+		} catch (err) {
+			console.warn("toolbox: file persist failed:", err);
+		}
+	}
+
+	/** Load previously persisted enabled tool names from disk. */
+	function loadFromFile(): string[] | undefined {
+		try {
+			const sp = getStatePath();
+			if (!existsSync(sp)) return undefined;
+			const raw = JSON.parse(readFileSync(sp, "utf-8")) as ToolboxState;
+			if (Array.isArray(raw?.enabledTools)) return raw.enabledTools;
+		} catch {
+			// File doesn't exist, is corrupt, or we're in a test env without getAgentDir
+		}
+		return undefined;
+	}
+
+	function restoreFromBranch(ctx: ExtensionContext): void {
+		// Prefer file-based persistence (survives across sessions).
+		// Fall back to session entries (survives branch navigation within a session).
+		// Fall back to full enable (first run).
+		const fileSaved = loadFromFile();
+		if (fileSaved) {
+			const validNames = new Set((pi.getAllTools() ?? []).map((t) => t.name));
+			enabledTools = new Set(
+				fileSaved.filter((n) => validNames.has(n) || CORE_TOOLS.has(n)),
+			);
+			for (const ct of CORE_TOOLS) enabledTools.add(ct);
+			initialized = true;
+			apply();
+			return;
+		}
+
+		// Fall back to plain init if sessionManager is unavailable (e.g. tests / headless)
+		if (!ctx?.sessionManager) {
+			ensureInit();
+			return;
+		}
+
+		// getEntries() returns ALL entries in the session file — unlike getBranch()
+		// which only walks ancestors. Custom entries appended via appendCustomEntry
+		// are children of the leaf, not ancestors.
+		const allEntries = ctx.sessionManager.getEntries();
+		let saved: string[] | undefined;
+
+		for (const entry of allEntries) {
+			if (entry.type === "custom" && entry.customType === "toolbox-config") {
+				const data = entry.data as ToolboxState | undefined;
+				if (data?.enabledTools) saved = data.enabledTools;
+			}
+		}
+
+		if (saved) {
+			const validNames = new Set((pi.getAllTools() ?? []).map((t) => t.name));
+			enabledTools = new Set(
+				saved.filter((n) => validNames.has(n) || CORE_TOOLS.has(n)),
+			);
+			for (const ct of CORE_TOOLS) enabledTools.add(ct);
+		} else {
+			const names = (pi.getAllTools() ?? []).map((t) => t.name);
+			enabledTools = new Set(names);
+		}
+		initialized = true;
+		apply();
+		// Persist to disk on first init so future sessions pick it up
+		persist();
+	}
+
+	function ensureInit(): void {
+		if (initialized) return;
+		let names: string[] = [];
+		try {
+			names = (pi.getAllTools() ?? []).map((t) => t.name);
+		} catch (err) {
+			console.warn("toolbox: getAllTools failed:", err);
+		}
+		if (!names.length) return;
+		enabledTools = new Set(names);
+		initialized = true;
+		apply();
+		persist();
+	}
+
+	function apply(): void {
+		if (!initialized) return;
+		try {
+			pi.setActiveTools([...enabledTools]);
+		} catch (err) {
+			console.warn("toolbox: setActiveTools failed:", err);
+		}
+	}
+
+	function isActive(name: string): boolean {
+		return enabledTools.has(name);
+	}
+
+	function onActivate(name: string): boolean {
+		if (!initialized) return false;
+		if (enabledTools.has(name)) return false;
+		enabledTools.add(name);
+		apply();
+		persist();
+		return true;
+	}
+
+	function onDeactivate(name: string): boolean {
+		if (!initialized) return false;
+		if (CORE_TOOLS.has(name)) return false;
+		const did = enabledTools.delete(name);
+		if (did) {
+			apply();
+			persist();
+		}
+		return did;
+	}
+
+	return {
+		ensureInit,
+		restoreFromBranch,
+		isActive,
+		onActivate,
+		onDeactivate,
+	};
+}
+
+// ─── Registration ───────────────────────────────────────────────────────────
+
+export default function registerToolbox(pi: ExtensionAPI): void {
+	const state = createState(pi);
+
+	// Defer init until tools are registered — session_start fires after all extensions load.
+	// Try to restore persisted state; fall back to full init if no config found.
+	pi.on("session_start", async (_event, ctx) => {
+		state.restoreFromBranch(ctx);
+	});
+
+	// Re-restore when navigating branch history
+	pi.on("session_tree", async (_event, ctx) => {
+		state.restoreFromBranch(ctx);
+	});
+
+	function getRows(): ToolRow[] {
+		try {
+			return buildRows(pi.getAllTools() ?? []);
+		} catch {
+			return [];
+		}
+	}
+
+	const ops: ToggleOps = {
+		isActive: state.isActive,
+		onActivate: state.onActivate,
+		onDeactivate: state.onDeactivate,
+	};
+
+	async function showPicker(ctx: {
+		ui: {
+			custom: <T>(f: unknown) => Promise<T>;
+			notify: (m: string, t?: "info" | "warning" | "error") => void;
+		};
+	}): Promise<void> {
+		await ctx.ui.custom<null>(
+			(
+				tui: TUI,
+				theme: Theme,
+				_kb: KeybindingsManager,
+				done: (r: null) => void,
+			) => {
+				const accent = "accent";
+				const mute = (s: string) => theme.fg("muted", s);
+				const container = new Container();
+
+				type RowState = "active" | "gated";
+				const stateOf = (name: string): RowState =>
+					ops.isActive(name) ? "active" : "gated";
+
+				const labelFor = (r: ToolRow): string => {
+					const active = stateOf(r.name) === "active";
+					const marker = active ? " " : theme.fg("warning", "#");
+					const name = active
+						? theme.fg("success", r.name)
+						: theme.fg("dim", r.name);
+					const kind = mute(`[${r.mcp ? "MCP" : "tool"}]`);
+					return `${marker} ${name}  ${kind}`;
+				};
+
+				const descFor = (r: ToolRow): string => {
+					const active = stateOf(r.name) === "active";
+					const tag = active
+						? theme.fg("success", "active")
+						: theme.fg("warning", "gated");
+					return `${tag} ${mute("·")} ${r.description || "(no description)"}`;
+				};
+
+				const rows = getRows();
+				const byValue = new Map<string, ToolRow>();
+				const toItem = (r: ToolRow): SelectItem => {
+					byValue.set(r.name, r);
+					return {
+						value: r.name,
+						label: labelFor(r),
+						description: descFor(r),
+					};
+				};
+
+				const allItems = rows.map(toItem);
+				const widest = allItems.reduce(
+					(w, it) => Math.max(w, visibleWidth(it.label)),
+					0,
+				);
+
+				const list = new SelectList(
+					allItems,
+					Math.min(allItems.length, 14),
+					{
+						selectedPrefix: (t: string) => theme.fg(accent, t),
+						selectedText: (t: string) => theme.fg(accent, t),
+						description: (t: string) => t,
+						scrollInfo: (t: string) => theme.fg("dim", t),
+						noMatch: (t: string) => theme.fg("warning", t),
+					},
+					{
+						minPrimaryColumnWidth: widest + 2,
+						maxPrimaryColumnWidth: widest + 2,
+					},
+				);
+
+				const internal = list as unknown as {
+					items: SelectItem[];
+					filteredItems: SelectItem[];
+					selectedIndex: number;
+				};
+
+				const search = new Input();
+				const statusLine = new Text("");
+
+				const refreshLabels = () => {
+					for (const it of internal.items) {
+						const r = byValue.get(it.value);
+						if (!r) continue;
+						it.label = labelFor(r);
+						it.description = descFor(r);
+					}
+					list.invalidate();
+					container.invalidate();
+					tui.requestRender?.();
+				};
+
+				const doToggle = (action: "enable" | "disable") => {
+					const sel = list.getSelectedItem();
+					if (!sel) return;
+					const msg = toggleTool(action, sel.value, rows, ops);
+					statusLine.setText(theme.fg("muted", msg));
+					refreshLabels();
+				};
+
+				const flipSelected = () => {
+					const sel = list.getSelectedItem();
+					if (!sel) return;
+					if (stateOf(sel.value) === "active") doToggle("disable");
+					else doToggle("enable");
+				};
+
+				const applyFilter = (q: string) => {
+					const query = q.trim();
+					internal.filteredItems =
+						query.length === 0
+							? internal.items
+							: fuzzyFilter(
+									internal.items,
+									query,
+									(it: SelectItem) => `${it.value} ${it.description ?? ""}`,
+								);
+					internal.selectedIndex = 0;
+					list.invalidate();
+					container.invalidate();
+				};
+
+				list.onSelect = () => done(null);
+				list.onCancel = () => done(null);
+				search.onEscape = () => done(null);
+
+				container.addChild(
+					new DynamicBorder((s: string) => theme.fg(accent, s)),
+				);
+				container.addChild(
+					new Text(theme.fg(accent, theme.bold("🧰  Toolbox"))),
+				);
+				container.addChild(new Text(theme.fg("muted", "Search:")));
+				container.addChild(search);
+				container.addChild(list);
+				container.addChild(statusLine);
+				container.addChild(
+					new Text(
+						theme.fg(
+							"dim",
+							"↑↓ navigate · e enable · d disable · space toggle · esc close",
+						),
+					),
+				);
+				container.addChild(
+					new DynamicBorder((s: string) => theme.fg(accent, s)),
+				);
+
+				return {
+					render(w: number) {
+						return container.render(w);
+					},
+					invalidate() {
+						container.invalidate();
+					},
+					handleInput(data: string) {
+						if (matchesKey(data, Key.up) || matchesKey(data, Key.down)) {
+							list.handleInput?.(data);
+						} else if (
+							matchesKey(data, Key.enter) ||
+							matchesKey(data, Key.escape)
+						) {
+							done(null);
+							return;
+						} else if (
+							matchesKey(data, Key.space) ||
+							matchesKey(data, Key.tab)
+						) {
+							flipSelected();
+						} else {
+							const printable = decodeKittyPrintable(data);
+							if (printable !== undefined) {
+								if (printable === "e") {
+									doToggle("enable");
+								} else if (printable === "d") {
+									doToggle("disable");
+								} else {
+									search.handleInput?.(data);
+									applyFilter(search.getValue?.() ?? "");
+								}
+							} else {
+								search.handleInput?.(data);
+								applyFilter(search.getValue?.() ?? "");
+							}
+						}
+						container.invalidate();
+						tui.requestRender?.();
+					},
+				};
+			},
+		);
+	}
+
+	pi.registerCommand("toolbox", {
+		description:
+			"Toggle tools on/off. ↑↓ navigate, e/d enable/disable, space toggle. " +
+			"Headless: /toolbox enable|disable <names>, /toolbox list [query]",
+		handler: async (args, ctx) => {
+			const raw = (args ?? "").trim();
+			const verb = raw.split(/\s+/, 1)[0]?.toLowerCase();
+
+			if (verb === "enable" || verb === "disable") {
+				const targets = parseTargets(raw.slice(verb.length).trim());
+				if (!targets.length) {
+					ctx.ui.notify(
+						`/toolbox ${verb} needs a tool name, e.g. /toolbox ${verb} grep`,
+						"warning",
+					);
+					return;
+				}
+				const rows = getRows();
+				const msg = targets
+					.map((t) => toggleTool(verb, t, rows, ops))
+					.join("\n");
+				ctx.ui.notify(msg, "info");
+				return;
+			}
+
+			if (verb === "list") {
+				const query = raw.slice(verb.length).trim() || undefined;
+				ctx.ui.notify(renderList(getRows(), ops.isActive, query), "info");
+				return;
+			}
+
+			if (typeof ctx.ui.custom === "function") {
+				await showPicker(ctx as unknown as Parameters<typeof showPicker>[0]);
+			} else {
+				ctx.ui.notify(renderList(getRows(), ops.isActive), "info");
+			}
+		},
+	});
+}