@narumitw/pi-chrome-devtools 0.50.1 → 0.51.0

package/README.md

@@ -26,10 +26,11 @@ This package is inspired by [`chrome-devtools-mcp`](https://github.com/ChromeDev
   explicit endpoint overrides.
 - Retries briefly while Chrome is starting and reports actionable endpoint errors.
 - Shows statusline activity only while Chrome DevTools tools are running.
-- Provides a state-first `/chrome-devtools` menu for tool access, browser status, setup, and help.
-- Stages menu-based tool changes for exact review before one confirmed apply.
+- Keeps one loader tool active and exposes matching browser capabilities only when the agent needs them.
+- Provides a state-first `/chrome-devtools` menu for tool availability, browser status, setup, and help.
+- Stages menu-based availability changes for exact review before one confirmed apply.
 - Uses `@narumitw/pi-tui-kit` for width-safe TUI menus and equivalent RPC dialogs.
-- Persists the selected Chrome DevTools tools across Pi restarts.
+- Persists the Chrome DevTools lazy-load catalog across Pi restarts.
 
 ## 📦 Install
 
@@ -143,12 +144,31 @@ removes their temporary profiles. It never closes user-started browsers or remot
 
 ## 🛠️ Pi tools
 
+- `chrome_devtools_load` — find and load browser capabilities relevant to a task.
 - `chrome_devtools_list_pages` — list inspectable Chrome tabs/pages.
 - `chrome_devtools_select_page` — select the active page for later tool calls.
 - `chrome_devtools_navigate` — navigate a page to a URL; if no page exists, create one first.
 - `chrome_devtools_evaluate` — evaluate JavaScript in the selected page.
 - `chrome_devtools_screenshot` — capture a PNG screenshot and save it as a PNG file.
 
+### Lazy tool loading
+
+All six tools are registered, but only `chrome_devtools_load` starts active for this extension.
+
+The loader accepts a task-oriented `query`, matches it against the five capability tools, and adds matching available tools without removing any active Pi tool.
+
+Loaded capability tools remain active for the rest of the session unless the user makes them unavailable through `/chrome-devtools`.
+
+Pi uses native deferred tool references on compatible Anthropic and OpenAI models.
+
+Other models receive Pi's safe fallback: the newly active definitions appear in the normal tool list on the next model request.
+
+The capability tools omit active-only prompt snippets so a lazy load does not rebuild the system prompt prefix.
+
+The saved `tools` array controls which capabilities the loader may expose.
+
+An empty array leaves the loader active but makes every browser capability unavailable.
+
 ### Screenshot files
 
 `chrome_devtools_screenshot` always saves the captured PNG to disk. If `savePath` is omitted,
@@ -182,14 +202,14 @@ to read the saved path, for example `read({ path: "artifacts/homepage.png" })`.
 /chrome-devtools
 ```
 
-Opens a menu that shows the current browser-tool count, whether that selection is saved, the
-configured endpoint, the observed managed-browser state, and any settings or launch warning before
-you choose an action. The five actions stay on one level:
+Opens a menu that shows the lazy catalog size, whether that catalog is saved, the configured
+endpoint, the observed managed-browser state, and any settings or launch warning before you choose
+an action. The five actions stay on one level:
 
-- **Choose browser tools…** — stage any combination of the five capabilities, then review the exact
-  enabled/disabled result before selecting **Apply tool changes**.
-- **Enable all browser tools…** or **Disable all browser tools…** — preview the context-appropriate
-  bulk change before applying it.
+- **Choose available browser tools…** — stage any combination of the five capabilities, then review
+  the exact available/unavailable result before selecting **Apply tool changes**.
+- **Make all browser tools available…** or **Make all browser tools unavailable…** — preview the
+  context-appropriate bulk change before applying it.
 - **Browser status** — inspect runtime, endpoint, launch mode, and the last launch attempt without
   probing the endpoint or starting Chrome.
 - **Settings & setup** — inspect effective files, sources, trust, reload steps, and recovery guidance.
@@ -200,8 +220,8 @@ friendly task labels while retaining their raw `chrome_devtools_*` identity in t
 Toggles remain a command-local draft. **Review changes** previews the exact effect, **Apply tool
 changes** saves it, and Cancel, Escape, Ctrl+C, disposal, or session replacement discards an
 unconfirmed draft without changing runtime tools or settings. A failed apply restores the previous
-active-tool state, preserves the settings file, retains the draft for retry, and reports how to
-recover.
+availability and loaded-tool state, preserves the settings file, retains the draft for retry, and
+reports how to recover.
 
 Direct subcommands are also available:
 
@@ -221,14 +241,15 @@ Compatibility aliases remain available: `toggle` and `select` mean `tools`, `on`
 - `help` shows command usage.
 - `quickstart` shows the configured CDP endpoint, endpoint source, auto-launch mode, browser
   candidates, last launch attempt, and launch hints.
-- `status` shows runtime tool state, persisted selection, settings file path, endpoint source,
-  launch mode, last launch attempt, and active non-Chrome tool count.
-- `tools` opens the same staged, width-safe selection and review flow used by the menu.
+- `status` shows available and loaded capability counts, loader state, the persisted catalog,
+  settings file path, endpoint source, launch mode, last launch attempt, and active non-Chrome tool
+  count.
+- `tools` opens the same staged, width-safe availability and review flow used by the menu.
 - `toggle` and `select` are compatibility aliases for `tools`.
-- `enable` immediately enables and saves all `chrome_devtools_*` tools for future turns; `on` is a
+- `enable` makes all five capability tools available to the loader and saves that catalog; `on` is a
   compatibility alias.
-- `disable` immediately disables and saves all `chrome_devtools_*` tools for future turns; `off` is a
-  compatibility alias. The slash command remains available.
+- `disable` makes all five capability tools unavailable and saves the empty catalog; `off` is a
+  compatibility alias. The slash command and `chrome_devtools_load` remain available.
 
 The menu, `tools`, `help`, `quickstart`, and `status` require TUI or RPC mode so their result is
 observable. TUI uses keyboard navigation and injected Pi keybindings; RPC receives equivalent
@@ -236,19 +257,20 @@ standard dialogs. In print and JSON modes, interactive and informational routes
 instead of silently opening unavailable UI. The immediate `enable`/`disable` routes remain available
 for deterministic non-interactive use.
 
-The selected tool names are saved to:
+The available capability names are saved to:
 
 ```text
 ${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-chrome-devtools.json
 ```
 
-When the file is missing or invalid, the extension preserves Pi's current active-tool policy
-instead of enabling tools by itself. A valid saved selection is restored on Pi startup and
-`/reload`. A missing file is created by the first confirmed menu apply or successful direct
-selection change. Within one Pi process, selection saves run in invocation order, reread the latest
-valid document, and preserve unknown fields. Malformed JSON or invalid recognized fields make menu
-mutation unavailable and block direct saves without replacement; a failed save restores the prior
-Chrome DevTools tool selection while preserving other extensions' current tools.
+When the file is missing or invalid, the extension preserves Pi's current Chrome DevTools
+availability policy instead of replacing it. A valid saved catalog is restored on Pi startup and
+`/reload`, while its capability definitions remain deferred. A missing file is created by the first
+confirmed menu apply or successful direct availability change. Within one Pi process, catalog saves
+run in invocation order, reread the latest valid document, and preserve unknown fields. Malformed
+JSON or invalid recognized fields make menu mutation unavailable and block direct saves without
+replacement; a failed save restores the prior Chrome DevTools availability and loaded-tool state
+while preserving other extensions' current tools.
 
 Compatibility: older versions used `pi-chrome-devtools-settings.json`. A legacy-only file remains
 readable with a warning and is never modified automatically; rename it to
@@ -271,6 +293,7 @@ packages/pi-chrome-devtools/
 ├── src/
 │   ├── index.ts            # Pi package entrypoint
 │   ├── chrome-devtools.ts  # Extension registration and command orchestration
+│   ├── lazy-tools.ts       # Deferred capability catalog and loader tool
 │   └── *.ts                # Package-local browser, CDP, tool, and storage modules
 ├── README.md
 ├── LICENSE

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-chrome-devtools",
-	"version": "0.50.1",
+	"version": "0.51.0",
 	"description": "Pi extension that exposes Chrome DevTools Protocol tools.",
 	"type": "module",
 	"license": "MIT",

package/src/chrome-devtools.ts

@@ -1,10 +1,15 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { shutdownManagedBrowser } from "./browser-manager.js";
+import {
+	availableChromeDevtoolsTools,
+	configureLazyChromeDevtoolsTools,
+	createChromeDevtoolsLoadTool,
+	initializeAvailableChromeDevtoolsTools,
+} from "./lazy-tools.js";
 import { applyRuntimeBrowserSettings, state } from "./runtime.js";
 import { loadSettings } from "./settings.js";
 import {
 	allChromeDevtoolsTools,
-	applyChromeDevtoolsTools,
 	buildCommandGuide,
 	buildQuickstartMessage,
 	buildToolStatusMessage,
@@ -27,12 +32,12 @@ const COMMAND_COMPLETIONS = [
 	{ value: "help", label: "help", description: "Show command usage" },
 	{ value: "quickstart", label: "quickstart", description: "Show endpoint and launch help" },
 	{ value: "status", label: "status", description: "Show tool and settings status" },
-	{ value: "tools", label: "tools", description: "Select Chrome DevTools tools" },
+	{ value: "tools", label: "tools", description: "Choose lazy-loadable Chrome DevTools tools" },
 	{ value: "toggle", label: "toggle", description: "Alias for tools" },
 	{ value: "select", label: "select", description: "Compatibility alias for tools" },
-	{ value: "enable", label: "enable", description: "Enable all Chrome DevTools tools" },
+	{ value: "enable", label: "enable", description: "Make all Chrome DevTools tools available" },
 	{ value: "on", label: "on", description: "Compatibility alias for enable" },
-	{ value: "disable", label: "disable", description: "Disable all Chrome DevTools tools" },
+	{ value: "disable", label: "disable", description: "Make all Chrome DevTools tools unavailable" },
 	{ value: "off", label: "off", description: "Compatibility alias for disable" },
 ];
 export default function chromeDevtools(pi: ExtensionAPI) {
@@ -41,11 +46,13 @@ export default function chromeDevtools(pi: ExtensionAPI) {
 	pi.registerTool(navigateTool);
 	pi.registerTool(evaluateTool);
 	pi.registerTool(screenshotTool);
+	pi.registerTool(createChromeDevtoolsLoadTool(pi));
 
 	pi.registerCommand("chrome-devtools", {
 		description: "Open Chrome DevTools help and tool controls",
 		getArgumentCompletions: (prefix) => commandCompletions(prefix),
 		handler: async (args, ctx) => {
+			initializeAvailableChromeDevtoolsTools(pi);
 			const generation = state.sessionGeneration;
 			await handleChromeDevtoolsCommand(pi, args, ctx, generation);
 		},
@@ -53,6 +60,7 @@ export default function chromeDevtools(pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => {
 		const generation = ++state.sessionGeneration;
+		initializeAvailableChromeDevtoolsTools(pi);
 		replaceSessionController("Chrome DevTools session replaced");
 		state.shuttingDown = false;
 		state.settingsNotice = undefined;
@@ -69,9 +77,11 @@ export default function chromeDevtools(pi: ExtensionAPI) {
 		for (const warning of settings.warnings) {
 			ctx.ui.notify(sanitizeChromeDevtoolsDisplay(warning), "warning");
 		}
-		if (settings.kind === "loaded" && settings.settings.tools) {
-			applyChromeDevtoolsTools(pi, settings.settings.tools);
-		}
+		const availableTools =
+			settings.kind === "loaded" && settings.settings.tools
+				? settings.settings.tools
+				: availableChromeDevtoolsTools(pi);
+		configureLazyChromeDevtoolsTools(pi, availableTools);
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
@@ -120,10 +130,10 @@ async function handleChromeDevtoolsCommand(
 			return;
 		}
 		case "enable":
-			await updateChromeDevtoolsTools(pi, ctx, allChromeDevtoolsTools(), "enabled all");
+			await updateChromeDevtoolsTools(pi, ctx, allChromeDevtoolsTools(), "made all available");
 			return;
 		case "disable":
-			await updateChromeDevtoolsTools(pi, ctx, [], "disabled all");
+			await updateChromeDevtoolsTools(pi, ctx, [], "made all unavailable");
 			return;
 	}
 
@@ -185,6 +195,7 @@ export {
 	isLocalDevToolsHost,
 	quoteCommandPart,
 } from "./browser-manager.js";
+export { CHROME_DEVTOOLS_LOAD_TOOL_NAME } from "./lazy-tools.js";
 export { parseConfiguredPort } from "./runtime.js";
 export {
 	hasParentPathSegment,

package/src/lazy-tools.ts

@@ -0,0 +1,143 @@
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { CHROME_DEVTOOLS_TOOL_NAMES, type ChromeDevToolsToolName } from "./tool-names.js";
+
+export const CHROME_DEVTOOLS_LOAD_TOOL_NAME = "chrome_devtools_load";
+
+const AVAILABLE_TOOLS_STORE = Symbol.for("@narumitw/pi-chrome-devtools.available-tools-store");
+type ChromeDevtoolsGlobal = typeof globalThis & {
+	[AVAILABLE_TOOLS_STORE]?: WeakMap<ExtensionAPI, Set<ChromeDevToolsToolName>>;
+};
+const sharedGlobal = globalThis as ChromeDevtoolsGlobal;
+const existingAvailableToolsStore = sharedGlobal[AVAILABLE_TOOLS_STORE];
+const availableToolsByApi =
+	existingAvailableToolsStore ?? new WeakMap<ExtensionAPI, Set<ChromeDevToolsToolName>>();
+if (!existingAvailableToolsStore) sharedGlobal[AVAILABLE_TOOLS_STORE] = availableToolsByApi;
+
+const SEARCH_TEXT: Record<ChromeDevToolsToolName, string> = {
+	chrome_devtools_list_pages: "list open inspectable chrome browser pages tabs targets",
+	chrome_devtools_select_page: "select choose active chrome browser page tab target",
+	chrome_devtools_navigate: "navigate open create chrome browser page url website",
+	chrome_devtools_evaluate: "evaluate run javascript expression dom inspect chrome browser page",
+	chrome_devtools_screenshot: "capture screenshot png image visual chrome browser page",
+};
+
+export function initializeAvailableChromeDevtoolsTools(pi: ExtensionAPI) {
+	if (availableToolsByApi.has(pi)) return;
+	const activeTools = new Set(pi.getActiveTools());
+	setAvailableTools(
+		pi,
+		CHROME_DEVTOOLS_TOOL_NAMES.filter((name) => activeTools.has(name)),
+	);
+}
+
+export function configureLazyChromeDevtoolsTools(
+	pi: ExtensionAPI,
+	availableTools: readonly ChromeDevToolsToolName[],
+) {
+	setAvailableTools(pi, availableTools);
+	const nonCapabilityTools = pi
+		.getActiveTools()
+		.filter((name) => !CHROME_DEVTOOLS_TOOL_NAMES.includes(name as ChromeDevToolsToolName));
+	pi.setActiveTools(unique([...nonCapabilityTools, CHROME_DEVTOOLS_LOAD_TOOL_NAME]));
+}
+
+export function applyAvailableChromeDevtoolsTools(
+	pi: ExtensionAPI,
+	availableTools: readonly ChromeDevToolsToolName[],
+) {
+	const available = setAvailableTools(pi, availableTools);
+	const active = pi
+		.getActiveTools()
+		.filter(
+			(name) =>
+				!CHROME_DEVTOOLS_TOOL_NAMES.includes(name as ChromeDevToolsToolName) ||
+				available.has(name as ChromeDevToolsToolName),
+		);
+	pi.setActiveTools(unique([...active, CHROME_DEVTOOLS_LOAD_TOOL_NAME]));
+}
+
+export function availableChromeDevtoolsTools(pi: ExtensionAPI) {
+	const available = availableToolsByApi.get(pi) ?? new Set();
+	return CHROME_DEVTOOLS_TOOL_NAMES.filter((name) => available.has(name));
+}
+
+export function createChromeDevtoolsLoadTool(pi: ExtensionAPI) {
+	return defineTool({
+		name: CHROME_DEVTOOLS_LOAD_TOOL_NAME,
+		label: "Chrome DevTools: Load Tools",
+		description:
+			"Find and enable Chrome DevTools browser tools relevant to a task. Loaded tools remain available for the session.",
+		promptSnippet: "Load Chrome DevTools browser capabilities on demand",
+		promptGuidelines: [
+			"Use chrome_devtools_load when a task requires inspecting or controlling a Chrome browser and the needed chrome_devtools_* capability is not active.",
+		],
+		parameters: Type.Object({
+			query: Type.String({
+				description: "Browser capability or task to find tools for.",
+				maxLength: 500,
+			}),
+			limit: Type.Optional(
+				Type.Integer({
+					description: "Maximum tools to load. Defaults to 3.",
+					minimum: 1,
+					maximum: 5,
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, signal) {
+			signal?.throwIfAborted();
+			const available = new Set(availableChromeDevtoolsTools(pi));
+			const matches = matchChromeDevtoolsTools(params.query, params.limit ?? 3, available);
+			const active = pi.getActiveTools();
+			const activeSet = new Set(active);
+			const added = matches.filter((name) => !activeSet.has(name));
+			if (added.length > 0) {
+				pi.setActiveTools(unique([...active, ...added]));
+			}
+
+			const text =
+				matches.length === 0
+					? "No available Chrome DevTools tools matched the query."
+					: added.length > 0
+						? `Loaded Chrome DevTools tools: ${added.join(", ")}`
+						: `Matching Chrome DevTools tools are already loaded: ${matches.join(", ")}`;
+			return {
+				content: [{ type: "text" as const, text }],
+				details: { matches, added },
+			};
+		},
+	});
+}
+
+function matchChromeDevtoolsTools(
+	query: string,
+	limit: number,
+	available: ReadonlySet<ChromeDevToolsToolName>,
+) {
+	const terms = query
+		.toLowerCase()
+		.split(/[^a-z0-9]+/)
+		.filter((term) => term.length >= 2);
+	if (terms.length === 0) return [];
+	return CHROME_DEVTOOLS_TOOL_NAMES.filter((name) => available.has(name))
+		.map((name, index) => ({
+			name,
+			index,
+			score: terms.reduce((score, term) => score + (SEARCH_TEXT[name].includes(term) ? 1 : 0), 0),
+		}))
+		.filter((match) => match.score > 0)
+		.sort((left, right) => right.score - left.score || left.index - right.index)
+		.slice(0, limit)
+		.map((match) => match.name);
+}
+
+function setAvailableTools(pi: ExtensionAPI, availableTools: readonly ChromeDevToolsToolName[]) {
+	const available = new Set(availableTools);
+	availableToolsByApi.set(pi, available);
+	return available;
+}
+
+function unique(values: readonly string[]) {
+	return [...new Set(values)];
+}

package/src/menu.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, runMenu, runTask } from "@narumitw/pi-tui-kit";
 import { browserLifecycleState, devToolsEndpoint, launchModeLabel } from "./browser-manager.js";
+import { availableChromeDevtoolsTools } from "./lazy-tools.js";
 import { state } from "./runtime.js";
 import { loadSettings, type SettingsLoadResult } from "./settings.js";
 import { CHROME_DEVTOOLS_TOOL_NAMES, type ChromeDevToolsToolName } from "./tool-names.js";
@@ -75,8 +76,8 @@ export async function showChromeDevtoolsMenu(
 				items: [
 					{
 						id: "tools",
-						label: "Choose browser tools…",
-						description: "Select what Pi may do in Chrome.",
+						label: "Choose available browser tools…",
+						description: "Choose which capabilities the loader may expose.",
 						disabled: Boolean(current.mutationBlockedReason),
 						disabledReason: current.mutationBlockedReason,
 						action: "tools",
@@ -85,8 +86,8 @@ export async function showChromeDevtoolsMenu(
 						id: "bulk",
 						label:
 							current.activeTools.length === CHROME_DEVTOOLS_TOOL_NAMES.length
-								? "Disable all browser tools…"
-								: "Enable all browser tools…",
+								? "Make all browser tools unavailable…"
+								: "Make all browser tools available…",
 						description:
 							current.activeTools.length === CHROME_DEVTOOLS_TOOL_NAMES.length
 								? "Preview 0 of 5; other active tools stay enabled."
@@ -250,8 +251,8 @@ export async function showChromeDevtoolsToolWorkflow(
 				kind: "review",
 				title: "Review tool changes",
 				lines: [
-					`Current: ${current.accepted.size}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
-					`Proposed: ${current.draft.size}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
+					`Currently available: ${current.accepted.size}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
+					`Proposed availability: ${current.draft.size}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
 				],
 				content: buildToolReview(current),
 				format: { kind: "text" },
@@ -307,7 +308,7 @@ export async function showChromeDevtoolsToolWorkflow(
 				current.draft = new Set(selectedTools);
 				current.applied = true;
 				ctx.ui.notify(
-					`Saved: ${selectedTools.length} of ${CHROME_DEVTOOLS_TOOL_NAMES.length} browser tools enabled.`,
+					`Saved: ${selectedTools.length} of ${CHROME_DEVTOOLS_TOOL_NAMES.length} browser tools available to lazy-load.`,
 					"info",
 				);
 				return { kind: "close" };
@@ -363,7 +364,7 @@ function buildMenuSnapshot(pi: ExtensionAPI, settings: SettingsLoadResult): Menu
 				? "not saved"
 				: arraysEqual(activeTools, persistedTools)
 					? "saved"
-					: "runtime differs from saved selection";
+					: "runtime catalog differs from saved catalog";
 	const settingsWarning = [
 		...new Set([settings.notice, state.settingsNotice].filter(Boolean)),
 	].join("\n");
@@ -379,7 +380,7 @@ function buildMenuSnapshot(pi: ExtensionAPI, settings: SettingsLoadResult): Menu
 
 function mainStateLines(snapshot: MenuSnapshot) {
 	return sanitizeLines([
-		`Tools: ${snapshot.activeTools.length} of ${CHROME_DEVTOOLS_TOOL_NAMES.length} enabled · ${snapshot.persistenceLabel}`,
+		`Lazy catalog: ${snapshot.activeTools.length} of ${CHROME_DEVTOOLS_TOOL_NAMES.length} available · ${snapshot.persistenceLabel}`,
 		`Browser: ${browserLifecycleSummary()}`,
 		`Endpoint: ${devToolsEndpoint()}`,
 		...(snapshot.settingsWarning ? [`Settings warning: ${snapshot.settingsWarning}`] : []),
@@ -406,7 +407,7 @@ function toolDraftLines(current: ToolWorkflowState) {
 		return sanitizeLines([`Unavailable: ${current.mutationBlockedReason}`]);
 	const changes = symmetricDifferenceSize(current.accepted, current.draft);
 	return [
-		`Current accepted: ${current.accepted.size}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
+		`Currently available: ${current.accepted.size}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
 		changes === 0
 			? "No unapplied changes · Escape cancels"
 			: `${changes} unapplied ${changes === 1 ? "change" : "changes"} · Escape cancels`,
@@ -415,25 +416,26 @@ function toolDraftLines(current: ToolWorkflowState) {
 }
 
 function buildToolReview(current: ToolWorkflowState) {
-	const enabled = CHROME_DEVTOOLS_TOOL_NAMES.filter((name) => current.draft.has(name));
-	const disabled = CHROME_DEVTOOLS_TOOL_NAMES.filter((name) => !current.draft.has(name));
+	const available = CHROME_DEVTOOLS_TOOL_NAMES.filter((name) => current.draft.has(name));
+	const unavailable = CHROME_DEVTOOLS_TOOL_NAMES.filter((name) => !current.draft.has(name));
 	return sanitizeChromeDevtoolsDisplay(
 		[
-			`Current browser tools: ${current.accepted.size}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
-			`Proposed browser tools: ${current.draft.size}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
+			`Current available browser tools: ${current.accepted.size}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
+			`Proposed available browser tools: ${current.draft.size}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
 			"",
-			"Enabled after apply:",
-			...(enabled.length > 0
-				? enabled.map((name) => `  - ${TOOL_PRESENTATION[name].label} (${name})`)
+			"Available to lazy-load after apply:",
+			...(available.length > 0
+				? available.map((name) => `  - ${TOOL_PRESENTATION[name].label} (${name})`)
 				: ["  - none"]),
 			"",
-			"Disabled after apply:",
-			...(disabled.length > 0
-				? disabled.map((name) => `  - ${TOOL_PRESENTATION[name].label} (${name})`)
+			"Unavailable after apply:",
+			...(unavailable.length > 0
+				? unavailable.map((name) => `  - ${TOOL_PRESENTATION[name].label} (${name})`)
 				: ["  - none"]),
 			"",
 			"Other active Pi tools remain unchanged.",
-			"The accepted selection is saved for future sessions.",
+			"Newly available tools remain deferred until chrome_devtools_load selects them.",
+			"The accepted availability policy is saved for future sessions.",
 		].join("\n"),
 	);
 }
@@ -447,8 +449,7 @@ function updateSnapshotAfterApply(
 }
 
 function activeChromeTools(pi: ExtensionAPI) {
-	const active = new Set(pi.getActiveTools());
-	return CHROME_DEVTOOLS_TOOL_NAMES.filter((toolName) => active.has(toolName));
+	return availableChromeDevtoolsTools(pi);
 }
 
 function orderedTools(tools: ReadonlySet<ChromeDevToolsToolName>) {

package/src/tool-selector.ts

@@ -10,6 +10,11 @@ import {
 	launchHint,
 	launchModeLabel,
 } from "./browser-manager.js";
+import {
+	applyAvailableChromeDevtoolsTools,
+	availableChromeDevtoolsTools,
+	CHROME_DEVTOOLS_LOAD_TOOL_NAME,
+} from "./lazy-tools.js";
 import { state } from "./runtime.js";
 import { loadSettings, saveSettings, settingsFilePath } from "./settings.js";
 import { CHROME_DEVTOOLS_TOOL_NAMES, type ChromeDevToolsToolName } from "./tool-names.js";
@@ -25,8 +30,9 @@ function formatError(error: unknown) {
 }
 
 interface ToolStatusSummary {
-	runtimeStatus: "enabled" | "disabled" | "partial";
-	activeChromeToolCount: number;
+	availabilityStatus: "enabled" | "disabled" | "partial";
+	availableChromeToolCount: number;
+	loadedChromeToolCount: number;
 	activeNonChromeToolCount: number;
 }
 
@@ -43,7 +49,7 @@ export async function updateChromeDevtoolsTools(
 	if (result !== "saved" || generation !== state.sessionGeneration) return;
 	const status = await buildToolStatusMessage(pi);
 	if (generation !== state.sessionGeneration) return;
-	ctx.ui.notify(`Chrome DevTools tools ${action}.\n\n${status}`, "info");
+	ctx.ui.notify(`Chrome DevTools lazy catalog ${action}.\n\n${status}`, "info");
 }
 
 export async function setSelectedChromeDevtoolsTools(
@@ -92,7 +98,7 @@ async function transactSelectedToolsNow(
 	expectedActiveTools?: readonly ChromeDevToolsToolName[],
 ): Promise<ToolSelectionSaveResult> {
 	if (expectedGeneration !== state.sessionGeneration) return "failed";
-	if (expectedActiveTools && !arraysEqual(activeChromeDevtoolsTools(pi), expectedActiveTools)) {
+	if (expectedActiveTools && !arraysEqual(availableChromeDevtoolsTools(pi), expectedActiveTools)) {
 		ctx.ui.notify(
 			"Browser tool selection changed while review was open. Review the current state, then apply again.",
 			"warning",
@@ -100,6 +106,7 @@ async function transactSelectedToolsNow(
 		return "active-tools-changed";
 	}
 	const previousActiveTools = pi.getActiveTools();
+	const previousAvailableTools = availableChromeDevtoolsTools(pi);
 	try {
 		applyChromeDevtoolsTools(pi, selectedTools);
 		await persistSettings(selectedTools);
@@ -107,10 +114,14 @@ async function transactSelectedToolsNow(
 	} catch (error) {
 		let rollbackError: unknown;
 		try {
-			const previousChromeTools = previousActiveTools.filter((name) =>
+			applyAvailableChromeDevtoolsTools(pi, previousAvailableTools);
+			const currentNonChromeTools = pi
+				.getActiveTools()
+				.filter((name) => !CHROME_DEVTOOLS_TOOL_NAMES.includes(name as ChromeDevToolsToolName));
+			const previousLoadedChromeTools = previousActiveTools.filter((name) =>
 				CHROME_DEVTOOLS_TOOL_NAMES.includes(name as ChromeDevToolsToolName),
-			) as ChromeDevToolsToolName[];
-			applyChromeDevtoolsTools(pi, previousChromeTools);
+			);
+			pi.setActiveTools(unique([...currentNonChromeTools, ...previousLoadedChromeTools]));
 		} catch (caught) {
 			rollbackError = caught;
 		}
@@ -127,11 +138,6 @@ async function transactSelectedToolsNow(
 	}
 }
 
-function activeChromeDevtoolsTools(pi: ExtensionAPI) {
-	const active = new Set(pi.getActiveTools());
-	return CHROME_DEVTOOLS_TOOL_NAMES.filter((toolName) => active.has(toolName));
-}
-
 function arraysEqual<T>(left: readonly T[], right: readonly T[]) {
 	return left.length === right.length && left.every((value, index) => value === right[index]);
 }
@@ -140,29 +146,32 @@ export function applyChromeDevtoolsTools(
 	pi: ExtensionAPI,
 	selectedTools: readonly ChromeDevToolsToolName[],
 ) {
-	const activeToolNames = pi.getActiveTools();
-	const chromeToolNames = new Set<string>(CHROME_DEVTOOLS_TOOL_NAMES);
-	const activeNonChromeToolNames = activeToolNames.filter((name) => !chromeToolNames.has(name));
-	pi.setActiveTools(unique([...activeNonChromeToolNames, ...selectedTools]));
+	applyAvailableChromeDevtoolsTools(pi, selectedTools);
 }
 
 function getToolStatusSummary(pi: ExtensionAPI): ToolStatusSummary {
 	const chromeToolNames = new Set<string>(CHROME_DEVTOOLS_TOOL_NAMES);
 	const activeToolNames = new Set(pi.getActiveTools());
-	const activeChromeToolCount = CHROME_DEVTOOLS_TOOL_NAMES.filter((name) =>
+	const loadedChromeToolCount = CHROME_DEVTOOLS_TOOL_NAMES.filter((name) =>
 		activeToolNames.has(name),
 	).length;
+	const availableChromeToolCount = availableChromeDevtoolsTools(pi).length;
 	const activeNonChromeToolCount = Array.from(activeToolNames).filter(
-		(name) => !chromeToolNames.has(name),
+		(name) => !chromeToolNames.has(name) && name !== CHROME_DEVTOOLS_LOAD_TOOL_NAME,
 	).length;
-	const runtimeStatus =
-		activeChromeToolCount === CHROME_DEVTOOLS_TOOL_NAMES.length
+	const availabilityStatus =
+		availableChromeToolCount === CHROME_DEVTOOLS_TOOL_NAMES.length
 			? "enabled"
-			: activeChromeToolCount === 0
+			: availableChromeToolCount === 0
 				? "disabled"
 				: "partial";
 
-	return { runtimeStatus, activeChromeToolCount, activeNonChromeToolCount };
+	return {
+		availabilityStatus,
+		availableChromeToolCount,
+		loadedChromeToolCount,
+		activeNonChromeToolCount,
+	};
 }
 
 export async function buildToolStatusMessage(pi: ExtensionAPI) {
@@ -170,8 +179,10 @@ export async function buildToolStatusMessage(pi: ExtensionAPI) {
 	const persistedSetting = await persistedSettingLabel();
 	return sanitizeChromeDevtoolsDisplay(
 		[
-			`Chrome DevTools tools: ${formatRuntimeStatus(summary)}`,
-			`Persisted selection: ${persistedSetting}`,
+			`Chrome DevTools tools available to lazy-load: ${formatRuntimeStatus(summary)}`,
+			`Loaded capability tools this session: ${summary.loadedChromeToolCount}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
+			`Loader: ${pi.getActiveTools().includes(CHROME_DEVTOOLS_LOAD_TOOL_NAME) ? "active" : "inactive"}`,
+			`Persisted lazy catalog: ${persistedSetting}`,
 			...browserSettingsStatusLines(),
 			...(state.settingsNotice ? [`Settings note: ${state.settingsNotice}`] : []),
 			`Other active tools preserved: ${summary.activeNonChromeToolCount}`,
@@ -276,10 +287,10 @@ export function buildCommandGuide() {
 		"/chrome-devtools help — show command usage",
 		"/chrome-devtools quickstart — show endpoint and launch help",
 		"/chrome-devtools status — show tool and settings status",
-		"/chrome-devtools tools — select individual Chrome DevTools tools",
+		"/chrome-devtools tools — choose tools available to lazy-load",
 		"/chrome-devtools toggle|select — compatibility aliases for tools",
-		"/chrome-devtools enable|on — enable all Chrome DevTools tools immediately",
-		"/chrome-devtools disable|off — disable all Chrome DevTools tools immediately",
+		"/chrome-devtools enable|on — make all Chrome DevTools tools available to lazy-load",
+		"/chrome-devtools disable|off — make all Chrome DevTools capability tools unavailable",
 	].join("\n");
 }
 
@@ -292,7 +303,7 @@ export function orderedChromeDevtoolsTools(selectedTools: ReadonlySet<ChromeDevT
 }
 
 function formatRuntimeStatus(summary: ToolStatusSummary) {
-	return `${summary.runtimeStatus} (${summary.activeChromeToolCount}/${CHROME_DEVTOOLS_TOOL_NAMES.length} active)`;
+	return `${summary.availabilityStatus} (${summary.availableChromeToolCount}/${CHROME_DEVTOOLS_TOOL_NAMES.length} available)`;
 }
 
 async function persistedSettingLabel() {
@@ -308,9 +319,10 @@ async function persistedSettingLabel() {
 
 function formatPersistedSelection(tools: readonly ChromeDevToolsToolName[]) {
 	if (tools.length === CHROME_DEVTOOLS_TOOL_NAMES.length) {
-		return `all enabled (${tools.length}/${CHROME_DEVTOOLS_TOOL_NAMES.length} selected)`;
+		return `all available (${tools.length}/${CHROME_DEVTOOLS_TOOL_NAMES.length} selected)`;
 	}
-	if (tools.length === 0) return `all disabled (0/${CHROME_DEVTOOLS_TOOL_NAMES.length} selected)`;
+	if (tools.length === 0)
+		return `all unavailable (0/${CHROME_DEVTOOLS_TOOL_NAMES.length} selected)`;
 	return `${tools.length}/${CHROME_DEVTOOLS_TOOL_NAMES.length} selected: ${tools.join(", ")}`;
 }
 

package/src/tools.ts

@@ -18,7 +18,6 @@ export const listPagesTool = defineTool({
 	name: CHROME_DEVTOOLS_TOOL_NAMES[0],
 	label: "Chrome DevTools: List Pages",
 	description: "List Chrome tabs/pages from a running Chrome DevTools Protocol endpoint.",
-	promptSnippet: "List Chrome tabs/pages available over Chrome DevTools Protocol",
 	parameters: Type.Object({}),
 	renderCall: renderToolCall("list pages"),
 	renderResult: renderTextResult,
@@ -34,7 +33,6 @@ export const selectPageTool = defineTool({
 	name: CHROME_DEVTOOLS_TOOL_NAMES[1],
 	label: "Chrome DevTools: Select Page",
 	description: "Select the active Chrome page for later chrome_devtools_* tool calls.",
-	promptSnippet: "Select the Chrome tab/page to inspect or control",
 	parameters: Type.Object({
 		pageId: Type.String({ description: "Page id from chrome_devtools_list_pages." }),
 	}),
@@ -56,7 +54,6 @@ export const navigateTool = defineTool({
 	label: "Chrome DevTools: Navigate",
 	description:
 		"Navigate a Chrome page to a URL through Chrome DevTools Protocol, creating a page first if none is available.",
-	promptSnippet: "Navigate the selected or first Chrome tab to a URL, creating one if needed",
 	parameters: Type.Object({
 		url: Type.String({ description: "URL to navigate to." }),
 		pageId: Type.Optional(
@@ -88,7 +85,6 @@ export const evaluateTool = defineTool({
 	name: CHROME_DEVTOOLS_TOOL_NAMES[3],
 	label: "Chrome DevTools: Evaluate",
 	description: "Evaluate JavaScript in a Chrome page through Chrome DevTools Protocol.",
-	promptSnippet: "Evaluate JavaScript in the selected Chrome tab",
 	parameters: Type.Object({
 		expression: Type.String({ description: "JavaScript expression to evaluate." }),
 		pageId: Type.Optional(
@@ -121,7 +117,6 @@ export const screenshotTool = defineTool({
 	name: CHROME_DEVTOOLS_TOOL_NAMES[4],
 	label: "Chrome DevTools: Screenshot",
 	description: "Capture a PNG screenshot from a Chrome page through Chrome DevTools Protocol.",
-	promptSnippet: "Capture a screenshot from the selected Chrome tab",
 	parameters: Type.Object({
 		pageId: Type.Optional(
 			Type.String({ description: "Optional page id. Defaults to selected or first page." }),