@underactive/pi-topping-web-tools 0.2.7 → 0.2.9

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## [Unreleased]
 
+## [0.2.9] - 2026-10-16
+
+### Added
+
+- Optional `toolExposure` setting (`direct` default, or `codemode` / `deferred`) in `~/.pi/agent/pi-topping-web-tools/settings.json`. All three tools share the `pi-topping-web-tools` namespace. At each session start, a non-`direct` mode activates the loader it needs with `pi.setActiveTools()`: `codemode` for `codemode`, and `tool_search` (or `codemode` when `tool_search` is not registered) for `deferred`. `defaultTools` needs no `+codemode` / `+tool_search` entry. When `--tools` or `--exclude-tools` leaves the loader out, the extension notifies once instead.
+- README settings profiles for default direct tools, codemode-minimal (`inlineBudget: 0`), and deferred + `tool_search`. Clarified that a large `inlineBudget` moves declarations into the `codemode` description instead of shrinking them.
+
+### Changed
+
+- Tested against pi 1.2.0. No break: the 1.2.0 breaking changes (`before_agent_start` for `triggerTurn` runs, busy session during run start, theme schema validation, `pi mcp list --json` shape) touch APIs and resources this package does not use.
+- Bumped the pinned `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` devDependencies from 1.1.0 to 1.2.0.
+- Tested against pi 1.3.0. No break: the extension-facing declaration surface (`ExtensionAPI`, `ToolDefinition`, `ExtensionContext`, `ExtensionUIContext`) is unchanged, pi-ai only adds optional `ToolCall.argumentsError`, and pi-tui is unchanged. Provider, `/share`, and model-switching changes do not reach these tools.
+- Bumped the pinned `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` devDependencies from 1.2.0 to 1.3.0.
+
+### Fixed
+
+- `web_browser`: the `mode`, `state`, `cookies[].sameSite`, and `dialogAction` parameter schemas now pass `as const` arrays to `StringEnum`, so their inferred types are the literal unions instead of `string`. This fixes four `tsc` errors; runtime validation is unchanged.
+
+## [0.2.8] - 2026-10-12
+
+### Added
+
+- Documented that the default `codemode.inlineBudget` (3000 estimated tokens) leaves `web_browser` out of the `codemode.mode: "only"` tool listing when it is loaded with `fetch_markdown`, `pdf_extract`, and the built-in `read`, `bash`, `edit`, and `write`, and the budget that fits them.
+- Documented how a codemode script inspects a saved screenshot with `tools.read` and `image()` on pi 1.0.4+, and the fallback on older hosts.
+
+### Changed
+
+- Tested against pi 1.1.0. No break: the 1.0.4 and 1.1.0 extension-facing changes are additive (`ToolLoadout.getPromptGuidelines()`, and `durationMs` and `outputPad` on the tool render context), and codemode now lists each tool's prompt guidelines with its declaration, which is why `web_browser` no longer fits the default `codemode.inlineBudget` in `only` mode.
+- Bumped the pinned `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` devDependencies from 1.0.3 to 1.1.0.
+- `web_browser`: the codemode screenshot guideline now tells a script to save the screenshot with `toFile=true`, read the file with `tools.read({ path })`, and pass the resulting image block to `image()`. This needs pi 1.0.4+, where `read` returns an image block for image files. A script that calls `web_browser` still receives only text, because the tool declares no output schema.
+
+### Fixed
+
+- `fetch_markdown`, `pdf_extract`, `web_browser`: a forged `</untrusted-content>` closing tag in fetched or page text is now escaped to `<\/untrusted-content` instead of deleted. Deletion could reassemble a real closer from split text such as `</untrusted-</untrusted-contentcontent>`, so hostile text could end the fence early and be read as trusted text. The match is case-insensitive, and the fence-escape tests now assert exactly one closing tag.
+- `fetch_markdown`, `pdf_extract`, `web_browser`: an expanded result preview drops terminal control characters from its body before styling, so a page cannot emit an OSC 52 clipboard write or another escape sequence while a result is drawn. `web_browser` also replaces control characters with spaces in a page title and in a tool error message.
+- `web_browser`: the `navigate` result now puts the status line before an `<untrusted-content>` fence that holds only the page title, and the `list_tabs` result is fenced the same way, because a tab title comes from the page. Both results held page-controlled text outside a fence before.
+
 ## [0.2.7] - 2026-10-05
 
 ### Changed

package/README.md

@@ -54,13 +54,76 @@ Start with `fetch_markdown` for efficient static content; use `web_browser` when
 | `pdf_extract` | Extract the text layer from a remote or local PDF, with page markers |
 | `web_browser` | Headless Chromium automation — navigate, click, type, screenshot, evaluate, logs, cookies |
 
-All three tools are `direct`-exposure and pi activates those on registration (`defaultActive` defaults to true), so nothing needs to be enabled.
+By default all three tools use `direct` exposure. Pi activates those on registration (`defaultActive` defaults to true), so a default install needs no extra `defaultTools` entry.
+
+### Tool exposure (optional)
+
+A single setting controls how the model reaches all three tools. It does not change host allowlists, permission prompts, or `--exclude-tools` / `defaultTools` filtering. Set it in `~/.pi/agent/pi-topping-web-tools/settings.json` (no TUI control):
+
+```json
+{
+  "toolExposure": "direct"
+}
+```
+
+| `toolExposure` | Tool `exposure` | Loader the extension activates |
+|----------------|-----------------|--------------------------------|
+| `direct` (default) | `direct`, active on register | None |
+| `codemode` | `codemode` | `codemode` |
+| `deferred` | `deferred` | `tool_search`, or `codemode` when `tool_search` is not available |
+
+All three tools share the `pi-topping-web-tools` namespace so `searchTools()` and `describeNamespace("pi-topping-web-tools")` can find them when they are not listed inline.
+
+Needs pi ≥0.99.0 for `codemode` / `tool_search` / `exposure`. Screenshot inspection from a script needs pi ≥1.0.4 (`toFile=true`, then `tools.read` and `image()`).
+
+At every session start (startup, reload, new, resume, and fork), the extension activates the loader with `pi.setActiveTools()`, as Pi's MCP support does for MCP servers. You do not need `+codemode` or `+tool_search` in `defaultTools`. The loader is a session-wide Pi tool, so the model can also use it for the other tools in the session, not only for these three. `--tools` and `--exclude-tools` unregister a loader they leave out. The extension does not activate that loader. It notifies once at session start instead, because the model cannot reach the tools.
+
+`codemode.mode: "only"` is a session-wide Pi setting. While it is on, the model must call bash/read/edit/write through `codemode` as well, not only these web tools. `--tools` still applies, for example `pi --tools +codemode,-web_browser`.
 
 ### Enabling and disabling tools
 
 - To hide a tool for a session, name it in `--exclude-tools` (or start with `--no-tools` and re-add what you want with `--tools`).
 - To change the startup set in your `settings.json`, use `defaultTools`. Bare names **replace** pi's defaults, so write `"+fetch_markdown"` to add a tool without dropping `read`, `bash`, `edit`, and `write`. On pi 0.99.2+, `/reload` activates tools **newly added** to `defaultTools` without a restart. The reverse does not follow: a tool **removed** from `defaultTools` stays active until you restart, and a tool you turned off during the session stays off. `--tools`, `--no-tools`, and `--no-builtin-tools` still override the setting, on reload as well.
 
+### Settings profiles for smaller prompts
+
+These snippets go in `~/.pi/agent/settings.json`. They are optional. Default installs can omit them.
+
+**Default (unchanged).** Direct tools. No codemode. Full tool schemas stay in the prompt.
+
+**Codemode-minimal.** Hide direct declarations and keep the `codemode` description small. `inlineBudget: 0` lists namespaces only. Scripts find tools with `searchTools()` / `describeTool()` / `describeNamespace()`. `inlineBudget: 4096` (or more) instead copies the full seven-tool catalog into the `codemode` description. That **moves** the schemas; it does not shrink them. Use `0` (or a small budget such as `512` for `fetch_markdown` / `pdf_extract` only) when the goal is fewer prompt tokens.
+
+```json
+{
+  "defaultTools": ["+codemode"],
+  "codemode.mode": "only",
+  "codemode.inlineBudget": 0
+}
+```
+
+With `toolExposure` still `direct`, `mode: "only"` hides the active declarations while they stay callable from scripts. Set `"toolExposure": "codemode"` in the extension settings file if you also want these three tools off the active set unless a loader activates them.
+
+**Deferred + tool_search.** Register the tools as `deferred` and let `tool_search` load a schema on the next turn. The extension activates `tool_search`, so `~/.pi/agent/settings.json` needs no change.
+
+`~/.pi/agent/pi-topping-web-tools/settings.json`:
+
+```json
+{
+  "toolExposure": "deferred"
+}
+```
+
+### Codemode tool listing
+
+With `codemode.mode: "only"`, pi hides the direct declarations of active tools, so the model calls them from `codemode` scripts, and the `codemode` description lists each callable tool instead, with its prompt guidelines on pi 1.0.4+. Listed tools share `codemode.inlineBudget`, which defaults to 3000 estimated tokens (characters / 4); tools that do not fit are left out and are reached with `searchTools()` or `describeTool()`. `0` lists only namespaces. On pi 1.0.4+, the seven-tool catalog `fetch_markdown`, `pdf_extract`, `web_browser`, plus built-in `read`, `bash`, `edit`, and `write` needs about 3,700 tokens as of pi 1.1.0 — `web_browser` alone is about 1,600, the largest section — so the default budget drops `web_browser` from that list. Set the budget to 4096 or more if you use `only` and want every tool inline; real sessions that load more extensions need more. Use `0` when you want the smallest `codemode` description.
+
+```json
+{
+  "codemode.mode": "only",
+  "codemode.inlineBudget": 4096
+}
+```
+
 ## `fetch_markdown`
 
 Complements pi's built-in search-backed `web_fetch` with a lightweight, keyless fetch path for public documentation, READMEs, and articles:
@@ -142,7 +205,7 @@ When `screenshot` returns an inline result (`toFile` omitted or `false`), `web_b
 
 `toFile=true` and `/browser-screenshot` save the original PNG to disk and put only the path and dimensions in the tool result. The file is resized only if a later `read` or `@file` attachment sends it to the model.
 
-In codemode, a tool result exposes only its text blocks, so an inline `screenshot` reaches the script as its caption with no image bytes. Call `screenshot` directly from the session, or pass `toFile=true` and read the saved path from the script.
+In codemode, a tool without an output schema, such as `web_browser`, resolves to its text blocks only, so an inline `screenshot` reaches the script as its caption with no image bytes. To let a script inspect a screenshot, take it with `toFile=true` and read the saved path: on pi 1.0.4+, `tools.read({ path })` resolves an image file to an image block, and `image()` adds that block to the script output. On pi before 1.0.4, `read` resolves an image file to only its `Read image file [...]` caption, so the pixels are not reachable from a script; on those hosts, call `screenshot` as a direct tool call instead of from a script.
 
 The resize fields are:
 
@@ -186,7 +249,7 @@ This matches pi's documented example. It leaves a default 1280×720 viewport scr
 - Every HTTP(S) document, script, image, XHR/fetch, beacon, and other routed request is checked against the live preapproved, session, and durable permissions before the request is sent. Path-scoped preapprovals remain path-scoped; session and durable grants remain exact-origin grants except that bare and `www.` host variants are treated as equivalent.
 - Redirect responses are inspected before Chromium receives them. Approved top-level redirects, including simple bare-domain ↔ `www.` redirects, are followed one gated hop at a time. During `navigate`, a redirect to an unapproved URL returns `Blocked: redirect to <origin> requires approval`; redirects triggered by later page interactions are blocked and reported in network logs. Redirected subresources are blocked rather than followed and also appear in network logs.
 - WebSocket handshakes use the same live permission check. Service workers are disabled so they cannot bypass request routing.
-- Client-side navigation and popup destinations are gated. A blocked popup is closed without becoming active, and a blocked same-tab navigation returns to the prior approved page.
+- Client-side navigation and popup destinations are gated. A blocked popup is closed without becoming active, and a blocked same-tab navigation returns to the prior approved page. Approved popups become active only after their main-frame navigation commits.
 - `data:` and `blob:` subresources are allowed because they do not create network egress, while top-level `data:`/`blob:` documents are denied. `file:` documents require approval for the target path; local-file subresources are allowed only from an approved local-file page.
 - Decision errors fail closed. Route handlers never prompt; call `navigate` on a blocked target to use the normal approval prompt. Blocks are reported by `get_network_logs` as `blocked by egress policy`.
 
@@ -245,13 +308,13 @@ Commands:
 
 ## Security model (shared)
 
-- **Preapproved hosts**: common documentation and dev sites are allowed without prompting. The allowlist lives in `src/permissions.ts` and is shared by both tools.
+- **Preapproved hosts**: common documentation and dev sites are allowed without prompting. The allowlist lives in `src/permissions.ts` and is shared by all three tools.
 - **User confirmation**: other hosts prompt Allow once / Allow for this session / Allow for 1 day / Allow for 1 week / Allow for 30 days / Deny. For `web_browser` navigation, Allow once becomes a browser-session grant because request-level enforcement must authorize the loaded document's later requests.
 - **Tool annotations**: on pi 0.99+, `fetch_markdown` and `pdf_extract` declare `readOnlyHint` and `openWorldHint`, and `web_browser` declares `openWorldHint` with `readOnlyHint: false`, for permission extensions that confirm calls by hint. The host confirmation above applies regardless of how another extension treats the hints.
 - **URL validation**: all tools reject embedded credentials and overlong URLs. `fetch_markdown` and `pdf_extract` additionally reject loopback, private, and link-local hosts and any non-HTTP(S) scheme on a `url`. `web_browser` accepts `localhost`, private IPs, and `file://` paths so it can drive local dev servers and local HTML — each still prompts for confirmation unless session-approved or covered by a saved durable grant.
 - **Local file resolution**: `pdf_extract` resolves a `path` through `realpath` before any check, so a symlink pointing outside the working directory is treated as outside and prompts. Directories, FIFOs, and devices are rejected, and the size limit is enforced from `stat` before any bytes are read. `web_browser` `upload_file` follows the same rule: files outside the working directory prompt for confirmation (session-scoped) before they are read.
 - **Isolated browser context and routed egress**: each session uses a fresh Chromium context (no shared profile/cookies with your system browser). HTTP(S) requests, redirect targets, client navigations, popups, and WebSocket connections are checked against live `web_browser` permissions; service workers are disabled.
-- **Untrusted content boundary**: `fetch_markdown` results are wrapped in `<untrusted-content url="…">` tags, and `pdf_extract` results in `<untrusted-content source="…">`, so the model treats fetched page and document text as data, not instructions.
+- **Untrusted content boundary**: `fetch_markdown` results and `web_browser` page-derived results are wrapped in `<untrusted-content url="…">` tags, and `pdf_extract` results in `<untrusted-content source="…">`, so the model treats fetched page and document text as data, not instructions.
 - **PDF resource limits**: extraction is bounded by download size, page count, and a timeout. Because the bundled PDF.js runs on the event loop rather than a worker, the timeout bounds extraction across its await points but cannot interrupt a fully synchronous parse — the size and page caps are the primary defence.
 
 ## Limitations
@@ -263,10 +326,6 @@ Commands:
 - Playwright routing covers HTTP(S) and WebSockets, not browser transports such as WebRTC; OS-level egress sandboxing remains outside this extension's scope.
 - `pdf_extract` reads only an existing text layer; scanned documents need OCR, which is out of scope.
 
-### Popups and navigation
-
-Same-tab client navigation and popups are checked against the live `web_browser` permissions. Unapproved document requests are aborted before reaching the target; blocked popups are closed without becoming active, while a blocked same-tab navigation returns to the prior approved page. Approved popups become active only after their main-frame navigation commits.
-
 ## Development
 
 Requires Node >= 22.19 (tests run TypeScript directly via `node --test`).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@underactive/pi-topping-web-tools",
-	"version": "0.2.7",
+	"version": "0.2.9",
 	"description": "Pi extensions for the web: fetch_markdown (URL to markdown, cached, keyless), pdf_extract (PDF text extraction) and web_browser (headless Playwright automation), sharing a preapproved-host allowlist.",
 	"keywords": ["pi-package", "pi-extension"],
 	"license": "MIT",
@@ -53,9 +53,9 @@
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "1.0.3",
-		"@earendil-works/pi-coding-agent": "1.0.3",
-		"@earendil-works/pi-tui": "1.0.3",
+		"@earendil-works/pi-ai": "1.3.0",
+		"@earendil-works/pi-coding-agent": "1.3.0",
+		"@earendil-works/pi-tui": "1.3.0",
 		"@types/node": "^24.0.0",
 		"@types/turndown": "^5.0.5",
 		"typebox": "^1.3.3",

package/src/fetch-markdown.ts

@@ -13,6 +13,7 @@ import { getBrowserHeaders } from "./browser-headers.ts";
 import { isPreapprovedHost, permissionKey } from "./permissions.ts";
 import { requestHostPermission } from "./permission-prompt.ts";
 import { BoundedPreview, clipField, resultText } from "./render-preview.ts";
+import { attachExposureLoader, registerWebTool } from "./tool-exposure.ts";
 import { MAX_URL_LENGTH, isLocalOrPrivateHost, upgradeHttpToHttps } from "./web-browser/permissions.ts";
 
 const MAX_HTTP_CONTENT_LENGTH = 25 * 1024 * 1024;
@@ -513,7 +514,7 @@ To complete your request, I need to fetch content from the redirected URL. Pleas
 
 		const offset = Math.max(0, Math.floor(params.offset ?? 0));
 		const slice = sliceContent(response.content, offset);
-		const sanitizedText = slice.text.replaceAll("</untrusted-content", "");
+		const sanitizedText = slice.text.replaceAll(/<\/(untrusted-content)/gi, "<\\/$1");
 		const safeUrl = params.url.replaceAll('"', "%22");
 		const wrappedText = `<untrusted-content url="${safeUrl}">\n${sanitizedText}\n</untrusted-content>`;
 
@@ -582,7 +583,8 @@ To complete your request, I need to fetch content from the redirected URL. Pleas
 export default function (pi: ExtensionAPI) {
 	const sessionPermissions = new Map<string, "allow" | "deny">();
 
-	pi.registerTool(fetchMarkdownTool);
+	registerWebTool(pi, fetchMarkdownTool);
+	attachExposureLoader(pi);
 
 	pi.on("tool_call", async (event, ctx) => {
 		if (event.toolName !== "fetch_markdown") return undefined;

package/src/pdf-extract.ts

@@ -3,15 +3,16 @@
 import { defineTool, formatSize, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { LRUCache } from "lru-cache";
-import { basename, isAbsolute, relative, resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import { readFile, realpath, stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
 import { extractText, getDocumentProxy } from "unpdf";
 import { combineSignals } from "./abort-utils.ts";
-import { isPreapprovedHost, permissionKey } from "./permissions.ts";
+import { isInsideCwd, isPreapprovedHost, permissionKey } from "./permissions.ts";
 import { requestHostPermission } from "./permission-prompt.ts";
 import { BoundedPreview, clipField, resultText } from "./render-preview.ts";
+import { attachExposureLoader, registerWebTool } from "./tool-exposure.ts";
 import { getWithPermittedRedirects, isPermittedRedirect, sliceContent, validateURL } from "./fetch-markdown.ts";
 import { upgradeHttpToHttps } from "./web-browser/permissions.ts";
 
@@ -110,11 +111,6 @@ export function parsePageRange(spec: string, totalPages: number): number[] {
 	return [...selected].sort((a, b) => a - b);
 }
 
-export function isInsideCwd(resolvedPath: string): boolean {
-	const rel = relative(process.cwd(), resolvedPath);
-	return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
-}
-
 type LocalPdfTarget = {
 	path: string;
 	mtimeMs: number;
@@ -369,7 +365,7 @@ Usage notes:
 
 		const offset = Math.max(0, Math.floor(params.offset ?? 0));
 		const slice = sliceContent(body, offset);
-		const sanitizedText = slice.text.replaceAll(/<\/untrusted-content/gi, "");
+		const sanitizedText = slice.text.replaceAll(/<\/(untrusted-content)/gi, "<\\/$1");
 		const safeSource = source.replaceAll('"', "%22");
 
 		return {
@@ -433,7 +429,8 @@ Usage notes:
 export default function (pi: ExtensionAPI) {
 	const sessionPermissions = new Map<string, "allow" | "deny">();
 
-	pi.registerTool(pdfExtractTool);
+	registerWebTool(pi, pdfExtractTool);
+	attachExposureLoader(pi);
 
 	pi.on("tool_call", async (event, ctx) => {
 		if (event.toolName !== "pdf_extract") return undefined;

package/src/permissions.ts

@@ -6,6 +6,8 @@
  * hostname/path-prefix (matches the prefix and its descendants).
  */
 
+import { isAbsolute, relative } from "node:path";
+
 export const PREAPPROVED_HOSTS = new Set([
 	"platform.claude.com",
 	"code.claude.com",
@@ -115,6 +117,11 @@ const { HOSTNAME_ONLY, PATH_PREFIXES } = (() => {
 	return { HOSTNAME_ONLY: hosts, PATH_PREFIXES: paths };
 })();
 
+export function isInsideCwd(resolvedPath: string): boolean {
+	const rel = relative(process.cwd(), resolvedPath);
+	return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
 export function permissionKey(url: string): string {
 	try {
 		const parsed = new URL(url);

package/src/render-preview.ts

@@ -70,9 +70,10 @@ export class BoundedPreview implements Component {
 		const { theme } = options;
 		this.header = options.header;
 		this.cut = options.body.length > MAX_PREVIEW_CHARS;
-		// Slice the raw text before styling so the cap never cuts an escape sequence. Every logical
+		// Slice the text before styling so the cap never cuts an escape sequence. Every logical
 		// line takes at least one row, so one line past the cap is enough for the skip to register.
 		this.body = options.body
+			.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "")
 			.slice(0, MAX_PREVIEW_CHARS)
 			.split("\n", MAX_VISUAL_PREVIEW_LINES + 1)
 			.map((line) => theme.fg("dim", line))

package/src/tool-exposure.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared ToolExposure + namespace for fetch_markdown, pdf_extract, and web_browser.
+ * Default remains Pi's direct registration. Other modes are opt-in via settings.json.
+ */
+
+import { getAgentDir, type ExtensionAPI, type ToolDefinition, type ToolExposure, type ToolNamespace } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type WebToolsExposureMode = "direct" | "codemode" | "deferred";
+
+export const WEB_TOOLS_NAMESPACE: ToolNamespace = {
+	name: "pi-topping-web-tools",
+	description: "Keyless fetch_markdown, pdf_extract, and headless web_browser.",
+	instructions: [
+		"Use fetch_markdown for public HTML documentation, READMEs, and articles when you want turndown markdown and a 15-minute cache.",
+		"Use pdf_extract for a remote or local PDF. fetch_markdown and web_fetch cannot read PDF text.",
+		"Use web_browser for JavaScript-rendered pages, local servers, screenshots, and interaction.",
+		"Host allowlist and permission prompts still apply. Exposure only changes how the model sees the tools, not what they may execute.",
+		"See the package README sections for fetch_markdown, pdf_extract, and web_browser.",
+	].join("\n"),
+};
+
+const MAX_SETTINGS_BYTES = 64 * 1024;
+
+export function settingsPath(): string {
+	return process.env.PI_WEB_TOOLS_SETTINGS_FILE ?? join(getAgentDir(), "pi-topping-web-tools", "settings.json");
+}
+
+export function parseToolExposureMode(value: unknown): WebToolsExposureMode {
+	if (value === "codemode" || value === "deferred" || value === "direct") {
+		return value;
+	}
+	return "direct";
+}
+
+export function loadToolExposureMode(path: string = settingsPath()): WebToolsExposureMode {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf-8");
+	} catch {
+		return "direct";
+	}
+
+	if (Buffer.byteLength(raw) > MAX_SETTINGS_BYTES) {
+		return "direct";
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return "direct";
+	}
+
+	if (typeof parsed !== "object" || parsed === null) {
+		return "direct";
+	}
+
+	return parseToolExposureMode((parsed as { toolExposure?: unknown }).toolExposure);
+}
+
+export function webToolPresentation(mode: WebToolsExposureMode = loadToolExposureMode()): {
+	exposure: ToolExposure;
+	namespace: ToolNamespace;
+} {
+	return {
+		exposure: mode,
+		namespace: WEB_TOOLS_NAMESPACE,
+	};
+}
+
+export function registerWebTool(pi: ExtensionAPI, tool: ToolDefinition): void {
+	pi.registerTool({ ...tool, ...webToolPresentation() });
+}
+
+let didNotifyPrerequisites = false;
+
+export function _resetExposureNoticeForTests(): void {
+	didNotifyPrerequisites = false;
+}
+
+/** Loader tools that reach tools with this exposure, in the order to activate them. */
+function exposureLoaders(mode: WebToolsExposureMode): readonly string[] {
+	if (mode === "codemode") return ["codemode"];
+	if (mode === "deferred") return ["tool_search", "codemode"];
+	return [];
+}
+
+/**
+ * The registered loader tool to activate so the model can reach the web tools, or undefined when a
+ * loader is already active or none is registered. `--tools` and `--exclude-tools` unregister tools,
+ * so an excluded loader is never activated.
+ */
+export function exposureLoaderToActivate(
+	mode: WebToolsExposureMode,
+	activeTools: readonly string[],
+	registeredTools: readonly string[],
+): string | undefined {
+	const loaders = exposureLoaders(mode);
+	if (loaders.some((name) => activeTools.includes(name))) return undefined;
+	return loaders.find((name) => registeredTools.includes(name));
+}
+
+export function exposurePrerequisiteNotice(
+	mode: WebToolsExposureMode,
+	activeTools: readonly string[],
+): string | undefined {
+	if (mode === "direct") return undefined;
+	if (exposureLoaders(mode).some((name) => activeTools.includes(name))) return undefined;
+	if (mode === "codemode") {
+		return 'pi-topping-web-tools toolExposure is "codemode", but the codemode tool is not available, so the model cannot reach the tools. Check --tools and --exclude-tools, or set toolExposure to "direct".';
+	}
+	return 'pi-topping-web-tools toolExposure is "deferred", but neither tool_search nor codemode is available, so the model cannot reach the tools. Check --tools and --exclude-tools, or set toolExposure to "direct".';
+}
+
+/**
+ * On every session start, activate the loader tool the configured exposure needs, as Pi's MCP support
+ * does for MCP servers. Notify once when no loader can be activated.
+ */
+export function attachExposureLoader(pi: ExtensionAPI): void {
+	pi.on("session_start", (_event, ctx) => {
+		const mode = loadToolExposureMode();
+		if (mode === "direct") return;
+		if (typeof pi.getActiveTools !== "function") return;
+		const active = pi.getActiveTools();
+		const loader = exposureLoaderToActivate(mode, active, pi.getAllTools().map((tool) => tool.name));
+		if (loader) pi.setActiveTools([...active, loader]);
+		if (didNotifyPrerequisites) return;
+		const message = exposurePrerequisiteNotice(mode, pi.getActiveTools());
+		if (!message) return;
+		didNotifyPrerequisites = true;
+		if (ctx.hasUI) {
+			ctx.ui.notify(message, "warning");
+		}
+	});
+}

package/src/web-browser/browser-manager.ts

@@ -866,7 +866,7 @@ export class BrowserManager {
 		const snippet = await this.pageSnippet(page);
 		const frameNote = frame ? ` within frame "${frame}"` : "";
 		const safeUrl = page.url().replaceAll('"', "%22");
-		return `No element matches selector "${selector}"${frameNote}. ${diagnostics}\nPage snippet:\n<untrusted-content url="${safeUrl}">\n${snippet.replaceAll("</untrusted-content", "")}\n</untrusted-content>`;
+		return `No element matches selector "${selector}"${frameNote}. ${diagnostics}\nPage snippet:\n<untrusted-content url="${safeUrl}">\n${snippet.replaceAll(/<\/(untrusted-content)/gi, "<\\/$1")}\n</untrusted-content>`;
 	}
 
 	private async ensureLaunched(): Promise<void> {

package/src/web-browser/index.ts

@@ -9,7 +9,6 @@ import {
 	DEFAULT_MAX_LINES,
 	formatSize,
 	truncateHead,
-	withFileMutationQueue,
 } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
@@ -25,7 +24,6 @@ import {
 	type NavigateResult,
 	type NetworkEntry,
 	type ScreenshotResult,
-	type SetCookieParam,
 	type TabInfo,
 } from "./browser-manager.ts";
 import { buildOriginChecker } from "./egress-policy.ts";
@@ -33,10 +31,10 @@ import { checkUrlPermission, upgradeHttpToHttps, validateURL } from "./permissio
 import { requestHostPermission } from "../permission-prompt.ts";
 import { BoundedPreview, clipField, resultText } from "../render-preview.ts";
 import { listGrants } from "../permission-store.ts";
-import { permissionKey } from "../permissions.ts";
-import { isInsideCwd } from "../pdf-extract.ts";
+import { isInsideCwd, permissionKey } from "../permissions.ts";
 import { suppressNotifications } from "../env.ts";
 import { publishBrowserState, registerBrowserFeeds } from "./feeds.ts";
+import { attachExposureLoader, webToolPresentation } from "../tool-exposure.ts";
 
 const ACTIONS = [
 	"navigate",
@@ -135,9 +133,11 @@ function formatTabs(tabs: TabInfo[]): string {
 		.join("\n");
 }
 
+const sanitizeTitle = (title: string) => clipField(title.replace(/[\u0000-\u001f\u007f]/g, " "));
+
 function wrapUntrustedContent(url: string, text: string): string {
 	const safeUrl = url.replaceAll('"', "%22");
-	const safeText = text.replaceAll(/<\/untrusted-content/gi, "");
+	const safeText = text.replaceAll(/<\/(untrusted-content)/gi, "<\\/$1");
 	return `<untrusted-content url="${safeUrl}">\n${safeText}\n</untrusted-content>`;
 }
 
@@ -157,6 +157,13 @@ async function resolveLocalFilePath(input: string): Promise<string> {
 	}
 }
 
+async function writeTempFile(name: string, data: string | Buffer): Promise<string> {
+	const tempDir = await mkdtemp(join(tmpdir(), "pi-web-browser-"));
+	const tempFile = join(tempDir, name);
+	await writeFile(tempFile, data, { mode: 0o600 });
+	return tempFile;
+}
+
 async function truncateTextResult(
 	text: string,
 	details: WebBrowserDetails,
@@ -170,12 +177,7 @@ async function truncateTextResult(
 	const outDetails = { ...details, bytes: truncation.totalBytes };
 
 	if (truncation.truncated) {
-		const tempDir = await mkdtemp(join(tmpdir(), "pi-web-browser-"));
-		const tempFile = join(tempDir, "output.txt");
-		await withFileMutationQueue(tempFile, async () => {
-			await writeFile(tempFile, text, { encoding: "utf-8", mode: 0o600 });
-		});
-
+		const tempFile = await writeTempFile("output.txt", text);
 		outDetails.fullOutputPath = tempFile;
 
 		const truncatedLines = truncation.totalLines - truncation.outputLines;
@@ -190,16 +192,6 @@ async function truncateTextResult(
 	return { text: resultText, details: outDetails };
 }
 
-async function saveScreenshotToTempFile(shot: ScreenshotResult): Promise<string> {
-	const tempDir = await mkdtemp(join(tmpdir(), "pi-web-browser-"));
-	const tempFile = join(tempDir, "screenshot.png");
-	const buf = Buffer.from(shot.data, "base64");
-	await withFileMutationQueue(tempFile, async () => {
-		await writeFile(tempFile, buf, { mode: 0o600 });
-	});
-	return tempFile;
-}
-
 function browserStatus(ctx: ExtensionContext, text: string, tone: "success" | "muted"): string {
 	return ctx.ui.theme.fg(tone, `browser: ${text}`);
 }
@@ -237,6 +229,7 @@ export default function (pi: ExtensionAPI) {
 		return manager;
 	};
 	registerBrowserFeeds(pi);
+	attachExposureLoader(pi);
 
 	pi.on("session_start", async (_event, ctx) => {
 		const info = await getConfiguredBrowserManager().getPageInfoAsync();
@@ -293,7 +286,7 @@ export default function (pi: ExtensionAPI) {
 				"Web Browser:",
 				`  Status: ${info.isOpen ? "open" : "closed"}`,
 				`  URL: ${info.url ? clipField(info.url) : "(none)"}`,
-				`  Title: ${info.title ? clipField(info.title.replace(/[\u0000-\u001f\u007f]/g, " ")) : "(none)"}`,
+				`  Title: ${info.title ? sanitizeTitle(info.title) : "(none)"}`,
 				`  Tabs open: ${info.tabCount}`,
 				`  Console messages: ${info.consoleCount}`,
 				`  Network issues: ${info.networkCount}`,
@@ -325,15 +318,18 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			const shot = await browser.screenshot({ fullPage: true });
-			const tempFile = await saveScreenshotToTempFile(shot);
+			const tempFile = await writeTempFile("screenshot.png", Buffer.from(shot.data, "base64"));
 			const dims = `${shot.width}×${shot.height}`;
 			ctx.ui.notify(`Screenshot saved to: ${tempFile}\nDimensions: ${dims} (full page)`, "info");
 		},
 	});
 
+	const presentation = webToolPresentation();
 	pi.registerTool({
 		name: "web_browser",
 		label: "Web Browser",
+		exposure: presentation.exposure,
+		namespace: presentation.namespace,
 		promptSnippet:
 			"Automate a headless browser to navigate sites, click/type, capture screenshots, evaluate JS, and read console logs.",
 		promptGuidelines: [
@@ -343,7 +339,7 @@ export default function (pi: ExtensionAPI) {
 			"Use get_content only when DOM structure or attributes are needed; it returns raw HTML.",
 			"On SPA sites, use wait_for after navigate (selector/state or networkidle) before click/type.",
 			"Use screenshot for visual verification (requires a vision-capable model); use toFile=true to save PNG to disk instead of base64.",
-			"Image content is not visible to a codemode script: a script receives only a tool result's text blocks, so a screenshot taken from one returns its caption without the pixels. Call screenshot directly, or with toFile=true to get a file path the script can read.",
+			"Image content is not visible to a codemode script for tools without an output schema, such as web_browser. For a screenshot, call web_browser with action screenshot and toFile=true; its result starts with 'Screenshot saved to: <path>'. On pi 1.0.4+, pass that path to tools.read({ path }), then pass its image block to image(); on earlier hosts, call screenshot directly instead of from a script.",
 			"Use get_console_logs when JavaScript errors or console output may explain page behavior.",
 			"Use get_network_logs when failed, egress-blocked, or 4xx/5xx requests may explain page behavior. Navigate directly to a blocked origin to request approval.",
 			"Use set_cookies to inject cookies for authenticated flows after manual login.",
@@ -398,7 +394,7 @@ export default function (pi: ExtensionAPI) {
 				Type.Number({ description: "Tab index to switch to, from list_tabs (action: switch_tab)" }),
 			),
 			dialogAction: Type.Optional(
-				StringEnum(["accept", "dismiss"], {
+				StringEnum(["accept", "dismiss"] as const, {
 					description:
 						"How to resolve future JS dialogs (alert/confirm/prompt) for the rest of the session (action: set_dialog_behavior, default dismiss)",
 				}),
@@ -427,13 +423,13 @@ export default function (pi: ExtensionAPI) {
 				Type.Number({ description: "Viewport height in pixels (action: set_viewport)" }),
 			),
 			mode: Type.Optional(
-				StringEnum(["fill", "press"], {
+				StringEnum(["fill", "press"] as const, {
 					description:
 						"Typing mode (action: type, default fill). fill clears the field first; press types key-by-key and appends to existing input.",
 				}),
 			),
 			state: Type.Optional(
-				StringEnum(["visible", "hidden", "attached", "detached"], {
+				StringEnum(["visible", "hidden", "attached", "detached"] as const, {
 					description: "Wait state (action: wait_for, default visible)",
 				}),
 			),
@@ -462,7 +458,7 @@ export default function (pi: ExtensionAPI) {
 						path: Type.Optional(Type.String()),
 						httpOnly: Type.Optional(Type.Boolean()),
 						secure: Type.Optional(Type.Boolean()),
-						sameSite: Type.Optional(StringEnum(["Strict", "Lax", "None"])),
+						sameSite: Type.Optional(StringEnum(["Strict", "Lax", "None"] as const)),
 					}),
 					{ description: "Cookies to set (action: set_cookies); each needs url or domain+path" },
 				),
@@ -475,7 +471,7 @@ export default function (pi: ExtensionAPI) {
 		annotations: { readOnlyHint: false, openWorldHint: true },
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			const action = params.action as WebBrowserAction;
+			const action = params.action;
 			const timeout = params.timeout;
 
 			onUpdate?.({ content: [{ type: "text", text: `${action}…` }], details: { action } });
@@ -513,13 +509,14 @@ export default function (pi: ExtensionAPI) {
 						const result: NavigateResult = await mgr.navigate(upgraded, { timeout, signal });
 						syncBrowserOpen(ctx, result.url);
 
-						const text = `Navigated to ${result.url}\nTitle: ${result.title}${result.statusCode ? `\nStatus: ${result.statusCode}` : ""}`;
+						const title = sanitizeTitle(result.title);
+						const text = `Navigated to ${result.url}${result.statusCode ? `\nStatus: ${result.statusCode}` : ""}\n${wrapUntrustedContent(result.url, `Title: ${title}`)}`;
 						return {
 							content: [{ type: "text", text }],
 							details: {
 								action,
 								url: result.url,
-								title: result.title,
+								title,
 								// A same-document navigation has no response; omit the key rather than storing undefined.
 								...(result.statusCode !== undefined ? { statusCode: result.statusCode } : {}),
 								bytes: Buffer.byteLength(text),
@@ -541,14 +538,14 @@ export default function (pi: ExtensionAPI) {
 						const dimsNote = `${dims}${shot.fullPage ? " (full page)" : ""}`;
 
 						if (params.toFile) {
-							const tempFile = await saveScreenshotToTempFile(shot);
+							const tempFile = await writeTempFile("screenshot.png", Buffer.from(shot.data, "base64"));
 							const text = `Screenshot saved to: ${tempFile}\nDimensions: ${dimsNote}`;
 							return {
 								content: [{ type: "text", text }],
 								details: {
 									action,
 									url: info.url,
-									title: info.title,
+									title: sanitizeTitle(info.title),
 									screenshotDims: dims,
 									fullOutputPath: tempFile,
 								} satisfies WebBrowserDetails,
@@ -570,7 +567,7 @@ export default function (pi: ExtensionAPI) {
 							details: {
 								action,
 								url: info.url,
-								title: info.title,
+								title: sanitizeTitle(info.title),
 								screenshotDims: dims,
 							} satisfies WebBrowserDetails,
 						};
@@ -603,7 +600,7 @@ export default function (pi: ExtensionAPI) {
 						const msg = await mgr.fill(params.selector, params.text, {
 							timeout,
 							signal,
-							mode: params.mode as "fill" | "press" | undefined,
+							mode: params.mode,
 							frame: params.frame,
 						});
 						return {
@@ -734,7 +731,7 @@ export default function (pi: ExtensionAPI) {
 						}
 						const msg = await mgr.waitFor({
 							selector: params.selector,
-							state: params.state as "visible" | "hidden" | "attached" | "detached" | undefined,
+							state: params.state,
 							networkidle: params.networkidle,
 							timeout,
 							signal,
@@ -829,7 +826,7 @@ export default function (pi: ExtensionAPI) {
 								};
 							}
 						}
-						await mgr.setCookies(params.cookies as SetCookieParam[], { signal });
+						await mgr.setCookies(params.cookies, { signal });
 						const text = `Set ${params.cookies.length} cookie(s).`;
 						return {
 							content: [{ type: "text", text }],
@@ -936,7 +933,7 @@ export default function (pi: ExtensionAPI) {
 					}
 
 					case "set_dialog_behavior": {
-						const dialogAction = (params.dialogAction as "accept" | "dismiss" | undefined) ?? "dismiss";
+						const dialogAction = params.dialogAction ?? "dismiss";
 						mgr.setDialogBehavior(dialogAction, params.promptText);
 						const text = `Dialogs will be ${dialogAction}ed${params.promptText ? ` (prompt text: "${params.promptText}")` : ""}.`;
 						return {
@@ -962,8 +959,9 @@ export default function (pi: ExtensionAPI) {
 					case "list_tabs": {
 						const tabs = await mgr.listTabs();
 						const text = formatTabs(tabs);
+						const info = await mgr.getPageInfoAsync();
 						return {
-							content: [{ type: "text", text }],
+							content: [{ type: "text", text: wrapUntrustedContent(info.url, text) }],
 							details: {
 								action,
 								tabCount: tabs.length,
@@ -1044,7 +1042,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (details.error) {
-				return new Text(theme.fg("error", clipField(details.error)), 0, 0);
+				return new Text(theme.fg("error", clipField(details.error.replace(/[\u0000-\u001f\u007f]/g, " "))), 0, 0);
 			}
 
 			const imageBlock = result.content.find((c) => c.type === "image");
@@ -1069,7 +1067,7 @@ export default function (pi: ExtensionAPI) {
 						"success",
 						`Navigated — ${
 							details.title
-								? clipField(details.title.replace(/[\u0000-\u001f\u007f]/g, " "))
+								? sanitizeTitle(details.title)
 								: clipField(details.url ?? "ok")
 						}`,
 					);