@xynogen/pix-toolbox 0.1.16 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xynogen
+
+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

@@ -4,12 +4,19 @@ Pi tool — gated tool toggle UI (`/toolbox`).
 
 ## What it does
 
-Registers a `/toolbox` slash command — a TUI fuzzy-search picker listing every registered tool (built-in, extension, MCP). Toggle tools on/off to control which are described in the system prompt via `pi.setActiveTools()`.
+Registers a `/toolbox` slash command — a TUI fuzzy-search picker listing every registered tool (built-in, extension, MCP), split into **Tools** and **MCP** tabs. Each tool has one of three states:
 
-- Toggling only affects **prompt visibility** — all tools stay callable via their function definitions.
-- Four tools (`bash`, `edit`, `read`, `write`) are protected and can't be disabled.
-- Gate state persists to `~/.pi/agent/toolbox.json`.
-- Headless subcommands: `/toolbox enable <names>`, `/toolbox disable <names>`, `/toolbox list [query]`.
+| State | Mark | Meaning |
+|---|---|---|
+| enabled | `✓` | Declared in the system prompt. |
+| deferred | `~` | Not declared. `tool_search` loads it on demand. Only for tools with `deferred` exposure. |
+| disabled | `#` | Not declared, and every call is blocked, also through `tool_search` or `codemode`. |
+
+Keys: `tab` switch tab · `↑↓` navigate · `ctrl+e` enable · `ctrl+f` defer · `ctrl+d` disable · `space` cycle · any other key types into the search.
+
+- Four tools (`bash`, `edit`, `read`, `write`) are protected and stay enabled.
+- State persists to `~/.pi/agent/toolbox.json`. Only changes from the default are saved: `disabledTools` (tools you disabled) and `loadedTools` (deferred tools you enabled). A newly installed tool keeps its default. A legacy `enabledTools` file is migrated on the next session start.
+- Headless subcommands: `/toolbox enable|defer|disable <names>`, `/toolbox list [query]`.
 
 ## Install
 
@@ -17,18 +24,22 @@ Registers a `/toolbox` slash command — a TUI fuzzy-search picker listing every
 pi install npm:@xynogen/pix-toolbox
 ```
 
-> Standalone/opt-in — **not** bundled by [`@xynogen/pix-core`](https://www.npmjs.com/package/@xynogen/pix-core). A power-user tool-toggle UI, installed only if you want it.
+> Standalone and opt-in. [`@xynogen/pix-core`](https://www.npmjs.com/package/@xynogen/pix-core) does not bundle it. It is a power-user tool-toggle UI.
 
 ## Full distro
 
-Source: [github.com/xynogen/pix-mono](https://github.com/xynogen/pix-mono)
-
-To install the complete pix suite (all packages + Pi itself):
+This package is part of [Pix](https://github.com/xynogen/pix-mono). The installer sets up Pi and the full distro. See [Install](https://github.com/xynogen/pix-mono#install) for the notes for each OS.
 
 ```bash
+# Linux / macOS
 curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh
 ```
 
+```powershell
+# Windows
+irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-toolbox",
-	"version": "0.1.16",
+	"version": "0.2.0",
 	"description": "Pi tool — gated tool toggle UI (/toolbox)",
 	"type": "module",
 	"main": "src/index.ts",
@@ -35,7 +35,7 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@xynogen/pix-pretty": "^1.11.2"
+		"@xynogen/pix-pretty": "^1.29.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",

package/src/index.ts

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

package/src/toolbox.ts

@@ -2,17 +2,17 @@
  * 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.
+ * registered tool (built-in and MCP). Each tool has one of three states:
+ *   enabled  — declared in the system prompt (pi.setActiveTools)
+ *   deferred — not declared; tool_search loads it on demand (deferred exposure only)
+ *   disabled — not declared and blocked, even through tool_search or codemode
  *
  * Also supports headless usage:
- *   /toolbox enable <names>   — enable tool(s) by name
- *   /toolbox disable <names>  — disable tool(s) by name
+ *   /toolbox enable|defer|disable <names>
  *   /toolbox list [query]     — text search (no picker)
  */
 
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type {
@@ -23,7 +23,6 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import {
-	decodeKittyPrintable,
 	fuzzyFilter,
 	Input,
 	Key,
@@ -55,13 +54,26 @@ export interface ToolRow {
 	description: string;
 	mcp: boolean;
 	source?: string;
+	exposure?: string;
 }
 
+export type ToolState = "enabled" | "deferred" | "disabled";
+export const TOOL_STATES: readonly ToolState[] = ["enabled", "deferred", "disabled"];
+
 /** Callbacks for toggleTool / renderList — test seam. */
 export interface ToggleOps {
-	isActive: (name: string) => boolean;
-	onActivate: (name: string) => boolean;
-	onDeactivate: (name: string) => boolean;
+	stateOf: (name: string) => ToolState;
+	/** Returns false when the tool is already in that state. */
+	setState: (name: string, state: ToolState) => boolean;
+}
+
+/** Only tools registered with `deferred` exposure can be found by tool_search. */
+export const canDefer = (row: ToolRow): boolean => row.exposure === "deferred";
+
+/** Next state for the space key. Skips `deferred` when the tool cannot be deferred. */
+export function nextState(row: ToolRow, current: ToolState): ToolState {
+	const states = TOOL_STATES.filter((s) => s !== "deferred" || canDefer(row));
+	return states[(states.indexOf(current) + 1) % states.length] ?? "enabled";
 }
 
 // ─── Helpers ────────────────────────────────────────────────────────────────
@@ -70,16 +82,25 @@ function isMcpTool(info: ToolInfo): boolean {
 	return /mcp/i.test(info.sourceInfo?.source ?? "");
 }
 
-export function buildRows(tools: ToolInfo[]): ToolRow[] {
-	return tools
+/**
+ * Normal tools first, MCP tools last. Inside a group: enabled, deferred, disabled,
+ * then by name. Without `stateOf`, the registered exposure stands in for the state.
+ */
+export function buildRows(tools: ToolInfo[], stateOf?: (name: string) => ToolState): ToolRow[] {
+	const rows = 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));
+			exposure: t.exposure ?? "direct",
+		}));
+	const rank = (r: ToolRow): number =>
+		TOOL_STATES.indexOf(stateOf?.(r.name) ?? (r.exposure === "deferred" ? "deferred" : "enabled"));
+	return rows.sort(
+		(a, b) => Number(a.mcp) - Number(b.mcp) || rank(a) - rank(b) || a.name.localeCompare(b.name),
+	);
 }
 
 const firstSentence = (desc: string): string => {
@@ -100,9 +121,15 @@ export function parseTargets(raw: string): string[] {
 	return out;
 }
 
+const STATUS: Record<ToolState, string> = {
+	enabled: "✓ enabled",
+	deferred: "~ deferred",
+	disabled: "# disabled",
+};
+
 export function renderList(
 	rows: ToolRow[],
-	isActive: (name: string) => boolean,
+	stateOf: (name: string) => ToolState,
 	query?: string,
 ): string {
 	const filtered = query
@@ -117,53 +144,144 @@ export function renderList(
 		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}`;
-	});
+	const lines: string[] = [];
+	let group = "";
+	for (const row of filtered) {
+		const nextGroup = row.mcp ? "MCP" : "Tools";
+		if (group !== nextGroup) {
+			group = nextGroup;
+			lines.push(`${lines.length ? "\n" : ""}${group}:`);
+		}
+		const kind = row.mcp ? "MCP" : "tool";
+		lines.push(`${STATUS[stateOf(row.name)]}  ${row.name}  [${kind}]  ${row.description}`);
+	}
 	return lines.join("\n");
 }
 
+const DONE: Record<ToolState, string> = {
+	enabled: "now in the prompt",
+	deferred: "tool_search loads it on demand",
+	disabled: "blocked",
+};
+
 export function toggleTool(
-	action: "enable" | "disable",
+	state: ToolState,
 	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.`;
+	if (CORE_TOOLS.has(name) && state !== "enabled")
+		return `${name} is a core tool. It stays enabled.`;
+	if (state === "deferred" && !canDefer(row))
+		return `${name} has direct exposure. tool_search cannot find it, so it cannot be deferred.`;
+	if (!ops.setState(name, state)) return `${name} is already ${state}.`;
+	return `${name} ${state} — ${DONE[state]}.`;
 }
 
 // ─── Persistence ───────────────────────────────────────────────────────────
 
+/**
+ * Persisted gate state. Only changes from the default are saved, so a newly
+ * installed tool keeps its default (direct → enabled, deferred → deferred).
+ * `disabledTools` holds tools the user disabled. `loadedTools` holds deferred
+ * tools the user enabled, so they are declared on every session start.
+ * `enabledTools` is the legacy form (an allow-list that hid every tool
+ * installed later); it is read once and migrated on the next write.
+ */
 interface ToolboxState {
-	enabledTools: string[];
+	disabledTools?: string[];
+	loadedTools?: string[];
+	enabledTools?: string[];
 }
 
 function getStatePath(): string {
 	return join(getAgentDir(), "toolbox.json");
 }
 
+const isStringArray = (v: unknown): v is string[] =>
+	Array.isArray(v) && v.every((x) => typeof x === "string");
+
+/**
+ * MCP codemode tools are named as JS identifiers now (`mcp__my-srv__a-b` → `mcp__my_srv__a_b`).
+ * Map saved names to that form so a disabled tool stays disabled. When `known` lacks that form,
+ * the tool collided or passed 64 chars and carries a hash suffix. Rebuild it from the old name.
+ * Keep in sync with pix-mcp `codemodeToolName` (packages cannot import each other).
+ */
+export function migrateToolName(name: string, known?: ReadonlySet<string>): string {
+	if (!name.startsWith("mcp__")) return name;
+	const plain = name.replace(/[^A-Za-z0-9_]/g, "_");
+	if (!known || known.has(plain)) return plain;
+	// Server and tool names can both hold `__`, so try every split. Only a known name matches.
+	for (let split = name.indexOf("__", 5); split >= 0; split = name.indexOf("__", split + 1)) {
+		const key = `${name.slice(5, split)}\0${name.slice(split + 2)}`;
+		const hash = createHash("sha256").update(key).digest("hex").slice(0, 8);
+		const hashed = `${plain.slice(0, 64 - hash.length - 1)}_${hash}`;
+		if (known.has(hashed)) return hashed;
+	}
+	return plain;
+}
+
+/**
+ * Disabled tool names from a saved state, or undefined when it holds none.
+ * A legacy allow-list maps to "every known non-core tool not in it".
+ */
+export function disabledFromState(raw: unknown, allNames: string[]): string[] | undefined {
+	const state = raw as ToolboxState | undefined;
+	if (isStringArray(state?.disabledTools)) {
+		const known = new Set(allNames);
+		return state.disabledTools
+			.map((n) => migrateToolName(n, known))
+			.filter((n) => !CORE_TOOLS.has(n));
+	}
+	if (isStringArray(state?.enabledTools)) {
+		const enabled = new Set(state.enabledTools);
+		return allNames.filter((n) => !enabled.has(n) && !CORE_TOOLS.has(n));
+	}
+	return undefined;
+}
+
+/** Deferred tool names the user chose to load on every session start. */
+export function loadedFromState(raw: unknown, allNames: string[] = []): string[] {
+	const loaded = (raw as ToolboxState | undefined)?.loadedTools;
+	const known = new Set(allNames);
+	return isStringArray(loaded) ? loaded.map((n) => migrateToolName(n, known)) : [];
+}
+
+const exposureOf = (tool: ToolInfo): string => tool.exposure ?? "direct";
+
 // ─── State ──────────────────────────────────────────────────────────────────
 
 function createState(pi: ExtensionAPI) {
-	let enabledTools = new Set<string>();
+	let disabledTools = new Set<string>();
+	let loadedTools = new Set<string>();
 	let initialized = false;
 
+	function isDeferred(name: string): boolean {
+		try {
+			const tool = pi.getAllTools().find((t) => t.name === name);
+			return tool ? exposureOf(tool) === "deferred" : false;
+		} catch {
+			return false;
+		}
+	}
+
+	function allNames(): string[] {
+		try {
+			return (pi.getAllTools() ?? []).map((t) => t.name);
+		} catch (err) {
+			console.warn("toolbox: getAllTools failed:", err);
+			return [];
+		}
+	}
+
 	function persist(): void {
+		const data: ToolboxState = { disabledTools: [...disabledTools].sort() };
+		if (loadedTools.size) data.loadedTools = [...loadedTools].sort();
 		// Write to session so state survives branch navigation within a session
 		try {
-			pi.appendEntry<ToolboxState>("toolbox-config", {
-				enabledTools: [...enabledTools],
-			});
+			pi.appendEntry<ToolboxState>("toolbox-config", data);
 		} catch (err) {
 			console.warn("toolbox: persist failed:", err);
 		}
@@ -171,126 +289,103 @@ function createState(pi: ExtensionAPI) {
 		try {
 			const sp = getStatePath();
 			mkdirSync(dirname(sp), { recursive: true });
-			writeFileSync(sp, JSON.stringify({ enabledTools: [...enabledTools] }, null, 2), "utf-8");
+			writeFileSync(sp, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
 		} catch (err) {
 			console.warn("toolbox: file persist failed:", err);
 		}
 	}
 
-	/** Load previously persisted enabled tool names from disk. */
-	function loadFromFile(): string[] | undefined {
+	/** Raw persisted state from disk, or undefined when absent/corrupt. */
+	function loadFromFile(): { raw: unknown; legacy: boolean } | 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;
+			return { raw, legacy: !isStringArray(raw?.disabledTools) };
 		} catch {
-			// File doesn't exist, is corrupt, or we're in a test env without getAgentDir
+			// corrupt, or a test env without getAgentDir
+			return undefined;
 		}
-		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;
-		}
-
+	/** Latest toolbox-config entry in the session, or undefined. */
+	function loadFromSession(ctx: ExtensionContext): unknown {
+		if (!ctx?.sessionManager) return undefined;
 		// 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;
-			}
+		let saved: unknown;
+		for (const entry of ctx.sessionManager.getEntries()) {
+			if (entry.type === "custom" && entry.customType === "toolbox-config") saved = entry.data;
 		}
-
-		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();
+		return saved;
 	}
 
-	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);
+	function restoreFromBranch(ctx: ExtensionContext): void {
+		// Prefer file-based persistence (survives across sessions), then session
+		// entries (survive branch navigation), then nothing disabled (first run).
+		const names = allNames();
+		const file = loadFromFile();
+		const fromFile = file ? disabledFromState(file.raw, names) : undefined;
+		const fromSession = fromFile ? undefined : loadFromSession(ctx);
+		const disabled = fromFile ?? disabledFromState(fromSession, names) ?? [];
+		disabledTools = new Set(disabled);
+		loadedTools = new Set(loadedFromState(fromFile ? file?.raw : fromSession, names));
 		initialized = true;
 		apply();
-		persist();
+		// Migrate a legacy allow-list file to the disabled-list form.
+		if (file?.legacy && fromFile) persist();
 	}
 
-	function apply(): void {
+	/** Rebuild the active set. `drop` removes one tool that apply() would otherwise keep. */
+	function apply(drop?: string): void {
 		if (!initialized) return;
 		try {
-			pi.setActiveTools([...enabledTools]);
+			const tools = pi.getAllTools();
+			const active = new Set(pi.getActiveTools());
+			if (drop) active.delete(drop);
+			pi.setActiveTools(
+				tools
+					.filter(
+						(tool) =>
+							!disabledTools.has(tool.name) &&
+							(["direct", "model-only"].includes(exposureOf(tool)) ||
+								loadedTools.has(tool.name) ||
+								active.has(tool.name)),
+					)
+					.map((tool) => tool.name),
+			);
 		} catch (err) {
 			console.warn("toolbox: setActiveTools failed:", err);
 		}
 	}
 
-	function isActive(name: string): boolean {
-		return enabledTools.has(name);
+	function stateOf(name: string): ToolState {
+		if (disabledTools.has(name)) return "disabled";
+		if (pi.getActiveTools().includes(name)) return "enabled";
+		return isDeferred(name) ? "deferred" : "disabled";
 	}
 
-	function onActivate(name: string): boolean {
-		if (!initialized) return false;
-		if (enabledTools.has(name)) return false;
-		enabledTools.add(name);
-		apply();
+	function setState(name: string, next: ToolState): boolean {
+		if (!initialized || stateOf(name) === next) return false;
+		if (CORE_TOOLS.has(name) && next !== "enabled") return false;
+		if (next === "deferred" && !isDeferred(name)) return false;
+		if (next === "disabled") disabledTools.add(name);
+		else disabledTools.delete(name);
+		if (next === "enabled" && isDeferred(name)) loadedTools.add(name);
+		else loadedTools.delete(name);
+		apply(next === "enabled" ? undefined : name);
 		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,
+		stateOf,
+		setState,
+		isDisabled: (name: string) => initialized && disabledTools.has(name),
+		/** tool_search activates its matches. Re-apply so a disabled match drops out. */
+		reapply: () => apply(),
 	};
 }
 
@@ -310,19 +405,27 @@ export default function registerToolbox(pi: ExtensionAPI): void {
 		state.restoreFromBranch(ctx);
 	});
 
+	// Disabled means unreachable: block direct and codemode calls, and undo a tool_search load.
+	pi.on("tool_call", async (event) => {
+		if (!state.isDisabled(event.toolName)) return;
+		return {
+			block: true,
+			reason: `${event.toolName} is disabled in /toolbox. Ask the user to enable it.`,
+		};
+	});
+	pi.on("tool_execution_end", async (event) => {
+		if (event.toolName === "tool_search") state.reapply();
+	});
+
 	function getRows(): ToolRow[] {
 		try {
-			return buildRows(pi.getAllTools() ?? []);
+			return buildRows(pi.getAllTools() ?? [], state.stateOf);
 		} catch {
 			return [];
 		}
 	}
 
-	const ops: ToggleOps = {
-		isActive: state.isActive,
-		onActivate: state.onActivate,
-		onDeactivate: state.onDeactivate,
-	};
+	const ops: ToggleOps = { stateOf: state.stateOf, setState: state.setState };
 
 	async function showPicker(ctx: {
 		ui: {
@@ -348,20 +451,23 @@ export default function registerToolbox(pi: ExtensionAPI): void {
 					theme.fg("text", key) + theme.fg("muted", ` ${action}`);
 				const guideSep = theme.fg("muted", " · ");
 
-				type RowState = "active" | "gated";
-				const stateOf = (name: string): RowState => (ops.isActive(name) ? "active" : "gated");
+				// Marker + color per state. The text tag keeps state readable without color.
+				const LOOK: Record<ToolState, { mark: string; color: "success" | "accent" | "warning" }> = {
+					enabled: { mark: "✓", color: "success" },
+					deferred: { mark: "~", color: "accent" },
+					disabled: { mark: "#", color: "warning" },
+				};
 
 				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("muted", r.name);
-					const kind = mute(`[${r.mcp ? "MCP" : "tool"}]`);
-					return `${marker} ${name}  ${kind}`;
+					const s = ops.stateOf(r.name);
+					const look = LOOK[s];
+					const name = s === "enabled" ? theme.fg("success", r.name) : theme.fg("muted", r.name);
+					return `${theme.fg(look.color, look.mark)} ${name}`;
 				};
 
 				const descFor = (r: ToolRow): string => {
-					const active = stateOf(r.name) === "active";
-					const tag = active ? theme.fg("success", "active") : theme.fg("warning", "gated");
+					const s = ops.stateOf(r.name);
+					const tag = theme.fg(LOOK[s].color, s.padEnd(8));
 					return `${tag} ${mute("·")} ${r.description || "(no description)"}`;
 				};
 
@@ -402,6 +508,16 @@ export default function registerToolbox(pi: ExtensionAPI): void {
 					selectedIndex: number;
 				};
 
+				const TABS = ["Tools", "MCP"] as const;
+				let tab: (typeof TABS)[number] = "Tools";
+				const inTab = (it: SelectItem) => (byValue.get(it.value)?.mcp === true) === (tab === "MCP");
+				const tabBar = () =>
+					TABS.map((name) => {
+						const n = rows.filter((r) => r.mcp === (name === "MCP")).length;
+						const label = `  ${name} (${n})  `;
+						return name === tab ? theme.fg(accent, theme.bold(label)) : mute(label);
+					}).join(mute("│"));
+
 				const search = new Input();
 				let statusText = "";
 				const pager = new ModalPager();
@@ -417,34 +533,37 @@ export default function registerToolbox(pi: ExtensionAPI): void {
 					tui.requestRender?.();
 				};
 
-				const doToggle = (action: "enable" | "disable") => {
+				const setSelected = (next: ToolState | "cycle") => {
 					const sel = list.getSelectedItem();
-					if (!sel) return;
-					const msg = toggleTool(action, sel.value, rows, ops);
-					statusText = theme.fg("dim", msg);
+					const row = sel && byValue.get(sel.value);
+					if (!row) return;
+					const target = next === "cycle" ? nextState(row, ops.stateOf(row.name)) : next;
+					statusText = theme.fg("dim", toggleTool(target, row.name, rows, ops));
 					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();
+					const items = internal.items.filter(inTab);
 					internal.filteredItems =
 						query.length === 0
-							? internal.items
+							? items
 							: fuzzyFilter(
-									internal.items,
+									items,
 									query,
 									(it: SelectItem) => `${it.value} ${it.description ?? ""}`,
 								);
 					internal.selectedIndex = 0;
 					list.invalidate();
 				};
+				applyFilter("");
+
+				const switchTab = (direction: -1 | 1) => {
+					tab = TABS[(TABS.indexOf(tab) + direction + TABS.length) % TABS.length] ?? "Tools";
+					statusText = "";
+					applyFilter(search.getValue?.() ?? "");
+					pager.followSelection();
+				};
 
 				list.onSelect = () => done(null);
 				list.onCancel = () => done(null);
@@ -455,16 +574,23 @@ export default function registerToolbox(pi: ExtensionAPI): void {
 						const mw = modalWidth(w);
 						const inner = mw - 4; // CHROME = 2 border + 2 padding
 						const footer = statusText ? ["", statusText] : [""];
+						// maxVisible = all items, so list line i is filteredItems[i].
+						const body = list.render(inner);
+						const selLine = internal.selectedIndex;
 						footer.push(
-							guide("↑↓", "navigate") +
+							guide("tab", "switch tab") +
+								guideSep +
+								guide("↑↓", "navigate") +
 								guideSep +
 								guide("←→/PgUp/PgDn", "inspect") +
 								guideSep +
-								guide("e", "enable") +
+								guide("^E", "enable") +
+								guideSep +
+								guide("^F", "defer") +
 								guideSep +
-								guide("d", "disable") +
+								guide("^D", "disable") +
 								guideSep +
-								guide("space", "toggle") +
+								guide("space", "cycle") +
 								guideSep +
 								guide("esc", "close"),
 						);
@@ -474,15 +600,14 @@ export default function registerToolbox(pi: ExtensionAPI): void {
 							minHeight: MIN_MODAL_HEIGHT,
 							header: [
 								theme.fg(accent, theme.bold("🧰  Toolbox")),
+								tabBar(),
+								"",
 								theme.fg("dim", "Search:"),
 								...search.render(inner),
 								"",
 							],
-							body: list.render(inner),
-							selectedBodyRange: pager.selectedRange({
-								start: internal.selectedIndex,
-								end: internal.selectedIndex + 1,
-							}),
+							body,
+							selectedBodyRange: pager.selectedRange({ start: selLine, end: selLine + 1 }),
 							footer,
 							bodyOffset: pager.bodyOffset,
 							color: (s) => theme.fg(accent, s),
@@ -507,25 +632,23 @@ export default function registerToolbox(pi: ExtensionAPI): void {
 						} 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 if (matchesKey(data, Key.shift(Key.tab))) {
+							switchTab(-1);
+						} else if (matchesKey(data, Key.tab)) {
+							switchTab(1);
+						} else if (matchesKey(data, Key.space)) {
+							setSelected("cycle");
+						} else if (matchesKey(data, Key.ctrl("e"))) {
+							setSelected("enabled");
+						} else if (matchesKey(data, Key.ctrl("f"))) {
+							setSelected("deferred");
+						} else if (matchesKey(data, Key.ctrl("d"))) {
+							setSelected("disabled");
 						} 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?.() ?? "");
-									pager.followSelection();
-								}
-							} else {
-								search.handleInput?.(data);
-								applyFilter(search.getValue?.() ?? "");
-								pager.followSelection();
-							}
+							// Every other key goes to the search. Ctrl hotkeys never collide with typed text.
+							search.handleInput?.(data);
+							applyFilter(search.getValue?.() ?? "");
+							pager.followSelection();
 						}
 						list.invalidate();
 						tui.requestRender?.();
@@ -538,13 +661,20 @@ export default function registerToolbox(pi: ExtensionAPI): void {
 
 	pi.registerCommand("toolbox", {
 		description:
-			"Toggle tools on/off. ↑↓ navigate, e/d enable/disable, space toggle. " +
-			"Headless: /toolbox enable|disable <names>, /toolbox list [query]",
+			"Set each tool to enabled, deferred or disabled. tab Tools/MCP, ↑↓ navigate, " +
+			"ctrl+e/f/d enable/defer/disable, space cycle. " +
+			"Headless: /toolbox enable|defer|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 VERBS: Record<string, ToolState> = {
+				enable: "enabled",
+				defer: "deferred",
+				disable: "disabled",
+			};
+			const target = verb ? VERBS[verb] : undefined;
+			if (verb && target) {
 				const targets = parseTargets(raw.slice(verb.length).trim());
 				if (!targets.length) {
 					ctx.ui.notify(
@@ -554,14 +684,14 @@ export default function registerToolbox(pi: ExtensionAPI): void {
 					return;
 				}
 				const rows = getRows();
-				const msg = targets.map((t) => toggleTool(verb, t, rows, ops)).join("\n");
+				const msg = targets.map((t) => toggleTool(target, 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");
+				ctx.ui.notify(renderList(getRows(), ops.stateOf, query), "info");
 				return;
 			}
 
@@ -569,7 +699,7 @@ export default function registerToolbox(pi: ExtensionAPI): void {
 				// SAFETY: The runtime command context satisfies showPicker's narrowed UI contract.
 				await showPicker(ctx as unknown as Parameters<typeof showPicker>[0]);
 			} else {
-				ctx.ui.notify(renderList(getRows(), ops.isActive), "info");
+				ctx.ui.notify(renderList(getRows(), ops.stateOf), "info");
 			}
 		},
 	});