pi-chrome 0.15.3 → 0.15.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable user-facing changes to `pi-chrome`.
 
+## 0.15.5 — 2026-05-14
+
+- **Chrome control authorization.** `chrome_*` tools are locked until the user runs `/chrome authorize` in the current Pi session. Grants can be one command, 15 minutes, 1 hour, or the session; `/chrome revoke` locks control again and `/chrome status` shows auth state.
+- **Browser-origin bridge hardening.** The loopback bridge no longer sends wildcard CORS headers. `/command` accepts only local-process requests, while extension polling/result endpoints reject non-extension browser origins, blocking ordinary web pages from driving or draining the bridge through `127.0.0.1`.
+
+## 0.15.4 — 2026-05-14
+
+- **Quiet renamed to background.** Public UX now uses `/chrome background [on|off|toggle|status]` and docs/status say “run in background” instead of “quiet mode”.
+
+## 0.15.3 — 2026-05-14
+
+- **Chrome real input only.** Public trusted/synthetic mode controls were removed. Interactive tools now always use Chrome's real input layer; `/chrome clicks` and public `trusted` parameters are gone.
+
 ## 0.15.2 — 2026-05-13
 
 - **Recipe prompts rewritten in user-language.** Earlier recipes leaked tool names into the `You:` prompts ("Use `chrome_tab list` to find my GitHub notifications tab…"), implying users need to know the tool catalog before they can ask anything. Prompts now read as natural intent; the agent trace below each one still shows the `chrome_*` primitives the agent picked. Affects the 30-second try-this block, all 3 hero recipes (PR triage / Linear standup / Bug repro), and 3 of the 6 collapsed recipes (auth-only data pull, network forensics, file upload).

package/README.md

@@ -34,10 +34,11 @@ Then in Pi:
 
 On macOS this opens `chrome://extensions`, reveals the bundled `browser-extension/` folder in Finder, and copies its path to your clipboard. In Chrome: **Developer mode** → **Load unpacked** → paste the path. Done.
 
-Verify:
+Verify and authorize current Pi session:
 
 ```text
 /chrome doctor
+/chrome authorize
 ```
 
 ```text
@@ -134,7 +135,7 @@ You:    [files the ticket with the folder attached]
 | Uses your real signed-in Chrome | ✅ extension in your profile      | ❌ throwaway profile           | ⚠️ requires `--remote-debug`  | ❌ throwaway profile           |
 | Re-login required               | **Never**                         | Every run                     | Sometimes                     | Every run                     |
 | **Multiple agents drive the same Chrome at once** | ✅ shared bridge | ❌ port collisions             | ❌                             | ❌                             |
-| Watch agent work, live          | ✅ default; toggle quiet          | ❌ headless or new window      | ⚠️ debugger banner always     | ❌ new window                  |
+| Watch agent work, live          | ✅ default; run in background optional | ❌ headless or new window      | ⚠️ debugger banner always     | ❌ new window                  |
 | Real browser input              | ✅ always for input tools         | ✅                             | ✅                             | ✅                             |
 | Network/console capture         | ✅ built-in                       | ✅                             | ✅                             | ⚠️ via extensions             |
 | **Honest result envelopes¹**    | ✅                                 | ⚠️                            | ❌                             | ❌                             |
@@ -185,23 +186,38 @@ Each tool is documented inline in Pi — agents see the parameters and gotchas (
 
 `pi-chrome` drives interactive controls through Chrome's real input layer: clicks, typing, fill, keys, hover, drag, scroll, and touch. Under the hood it uses `chrome.debugger` / CDP, so input satisfies normal user-activation gates. Chrome may show the *"Pi Chrome Connector started debugging this browser"* banner while attached.
 
-### Background / watch modes
+### Authorization
+
+Chrome control is locked by default. Before any agent can use `chrome_*` tools, explicitly authorize the current Pi session:
+
+```text
+/chrome authorize          # authorize until this Pi session exits
+/chrome authorize once     # allow one Chrome command
+/chrome authorize 15m      # allow for 15 minutes
+/chrome revoke             # lock again
+/chrome status             # shows connection + auth + background
+```
+
+This protects your signed-in Chrome profile from accidental agent use. The loopback bridge also rejects browser-origin command requests so arbitrary web pages cannot call into `127.0.0.1:17318` through CORS.
+
+### Run in background / watch modes
 
 By default, every `chrome_*` call focuses Chrome and activates the target tab so you can **watch the agent work** — invaluable for demos, debugging, and first-time confidence.
 
 ```text
-/chrome quiet          # toggle for the whole session
-/chrome quiet on       # explicit
-/chrome quiet off      # explicit
+/chrome background          # toggle for the whole session
+/chrome background on       # run in background
+/chrome background off      # bring Chrome forward so you can watch
 ```
 
-Per-call `background: true` wins over the session toggle.
+Per-call `background: true` wins over the session setting.
 
 ### Diagnostics
 
 - `/chrome doctor` — single command: connectivity, extension version, bridge owner, version drift, MAIN-world helper injection, `chrome_evaluate("1+1") === 2`, fingerprint flags.
 - `/chrome onboard` — guided first-time setup.
-- `/chrome quiet status` — current watch/background setting.
+- `/chrome authorize status` — current Chrome-control authorization state.
+- `/chrome background status` — current watch/background setting.
 
 If the loaded Chrome extension is older than `pi-chrome` on disk, `/chrome doctor` tells you to reload it from `chrome://extensions`.
 
@@ -248,9 +264,9 @@ If you build a competing tool, please open a PR with your scores. We benchmark i
 
 **Unpacked on purpose.** A Web Store extension cannot talk to a local bridge controlled by another tool on the same machine — so pi-chrome ships its bridge as an inspectable, MIT-licensed folder you load once with Developer Mode. Every line is yours to read in [`extensions/chrome-profile-bridge/browser-extension/`](./extensions/chrome-profile-bridge/browser-extension). `/chrome doctor` reports the loaded extension version and warns when it drifts from your installed `pi-chrome`.
 
-The companion extension runs in the Chrome profile where you install it and has broad tab/scripting permissions. Only install it from a package source you trust.
+The companion extension runs in the Chrome profile where you install it and has broad tab/scripting permissions. Only install it from a package source you trust. Even after install, `chrome_*` tools stay locked until you run `/chrome authorize` in Pi. Use `/chrome revoke` to lock them again.
 
-The Pi side listens on `127.0.0.1:17318` by default. Override before starting Pi:
+The Pi side listens on `127.0.0.1:17318` by default and rejects browser-origin command requests; ordinary web pages cannot use CORS to drive the bridge. Override before starting Pi:
 
 ```bash
 PI_CHROME_BRIDGE_PORT=17319 pi

package/SECURITY.md

@@ -9,13 +9,14 @@ Open a GitHub issue prefixed with `[security]` at https://github.com/tianrendong
 `pi-chrome` is a developer tool you install knowingly. It is **not** designed to defend against:
 
 - Hostile pages running in your Chrome trying to detect or escape automation. (Standard browser security boundaries still apply, but a hostile page that already runs in your tab can do anything that page can already do.)
-- Other processes on your local machine. The bridge binds to `127.0.0.1:17318` (loopback only) but **does not authenticate** local callers. Any process running as your user can issue commands. If your threat model includes hostile local processes, run pi-chrome on a separate user account.
+- Other processes on your local machine. The bridge binds to `127.0.0.1:17318` (loopback only) and chrome_* tools require `/chrome authorize` inside Pi, but the bridge does not authenticate arbitrary non-browser local callers. If your threat model includes hostile local processes running as you, run pi-chrome on a separate user account.
 
 `pi-chrome` **is** designed to:
 
 - Never exfiltrate page state to the network. All communication is loopback (`127.0.0.1`).
 - Surface every action with an honest result envelope so the agent can't silently do the wrong thing.
-- Require explicit opt-in for trusted-input mode (`/chrome clicks on` or `trusted: true`), which uses `chrome.debugger` and shows Chrome's banner.
+- Keep Chrome control locked until the user explicitly runs `/chrome authorize` in the current Pi session.
+- Reject browser-origin command requests to the loopback bridge so ordinary web pages cannot use CORS to drive Chrome.
 
 ## The companion extension
 
@@ -24,8 +25,9 @@ The Chrome extension under `extensions/chrome-profile-bridge/browser-extension/`
 ## Defaults
 
 - Loopback bridge only. No remote port. No telemetry.
-- Synthetic events first; trusted CDP only when explicitly enabled.
-- Quiet mode optional; tab/window focus is observable (the user can see Pi acting).
+- Chrome real input layer for interactive controls.
+- Chrome control locked by default; `/chrome authorize` unlocks current Pi session, `/chrome revoke` locks it again.
+- Run-in-background optional; tab/window focus is observable by default (the user can see Pi acting).
 
 ## Override the port
 

package/docs/COMPARISON.md

@@ -126,7 +126,7 @@ Yes — you can export cookies and replay them, or point Playwright at your exis
 Different security boundary, not strictly safer.
 
 - **CDP-based tools** require `chrome --remote-debugging-port=...`. That port is unauthenticated and exposes the whole browser to any local process. Easy to misconfigure.
-- **pi-chrome** runs through an extension you install yourself with broad permissions (tabs, scripting, debugger, webNavigation). The bridge listens on `127.0.0.1:17318` loopback only. **Only install the bundled extension if you trust the source you got the npm package from.**
+- **pi-chrome** runs through an extension you install yourself with broad permissions (tabs, scripting, debugger, webNavigation). The bridge listens on `127.0.0.1:17318` loopback only, rejects browser-origin command requests, and keeps chrome_* tools locked until `/chrome authorize` is run in the current Pi session. **Only install the bundled extension if you trust the source you got the npm package from.**
 
 If your threat model excludes extensions with broad permissions, neither approach is a fit — you want a sandboxed CI runner.
 

package/docs/EXAMPLES.md

@@ -1,6 +1,6 @@
 # pi-chrome examples
 
-Real, useful agent prompts. Drop any of these into Pi after running `/chrome onboard`. Each one uses Chrome tabs and accounts you already have.
+Real, useful agent prompts. Drop any of these into Pi after running `/chrome onboard` and `/chrome authorize`. Each one uses Chrome tabs and accounts you already have.
 
 ## Daily workflow
 

package/docs/FAQ.md

@@ -24,11 +24,13 @@ That's Chrome's built-in warning when an extension uses `chrome.debugger`. pi-ch
 
 ## Can a malicious page escape and access my other tabs?
 
-No — pages cannot directly talk to extensions. Commands flow agent → local bridge (`127.0.0.1:17318`) → extension → tab. The bridge binds to loopback only. The risk surface is **other local processes** that could connect to `127.0.0.1:17318` and impersonate Pi. If that's in your threat model, run pi-chrome on a separate user account.
+No — pages cannot directly talk to extensions. Commands flow agent → local bridge (`127.0.0.1:17318`) → extension → tab. The bridge binds to loopback only and rejects browser-origin command requests, so ordinary web pages cannot use CORS to drive it.
+
+Chrome control is also locked per Pi session until you run `/chrome authorize`; `/chrome revoke` locks it again. The remaining risk surface is **other local processes running as you** that can connect to loopback and imitate Pi. If that's in your threat model, run pi-chrome in a separate OS user account.
 
 ## Can multiple Pi sessions use it at once?
 
-Yes. The first session opens the local bridge; later sessions detect it and pipe their commands through the same bridge. Planner + worker + audit can all drive the same Chrome concurrently.
+Yes. The first session opens the local bridge; later sessions detect it and pipe their commands through the same bridge. Each Pi session must be authorized with `/chrome authorize` before its chrome_* tools work.
 
 ## Why can't this be on the Chrome Web Store?
 

package/extensions/chrome-profile-bridge/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Pi Chrome Connector",
-  "version": "0.15.3",
+  "version": "0.15.5",
   "description": "Lets Pi control tabs in Chrome via a local connector at 127.0.0.1.",
   "permissions": [
     "tabs",

package/extensions/chrome-profile-bridge/index.ts

@@ -127,12 +127,32 @@ function readRequestBody(request: IncomingMessage): Promise<string> {
 	});
 }
 
+function corsHeadersFor(request: IncomingMessage): Record<string, string> {
+	const origin = String(request.headers.origin ?? "");
+	if (!origin.startsWith("chrome-extension://")) return {};
+	return {
+		"access-control-allow-origin": origin,
+		"access-control-allow-methods": "GET,POST,OPTIONS",
+		"access-control-allow-headers": "content-type",
+		"access-control-expose-headers": "x-pi-chrome-version",
+		"vary": "origin",
+	};
+}
+
+function isBrowserOriginAllowed(request: IncomingMessage): boolean {
+	const origin = String(request.headers.origin ?? "");
+	if (origin) return origin.startsWith("chrome-extension://");
+	const secFetchSite = String(request.headers["sec-fetch-site"] ?? "");
+	return !secFetchSite || secFetchSite === "none" || secFetchSite === "same-origin";
+}
+
+function isLocalProcessRequest(request: IncomingMessage): boolean {
+	return !request.headers.origin && !request.headers["sec-fetch-site"];
+}
+
 function sendJson(response: ServerResponse, status: number, body: unknown, extraHeaders?: Record<string, string>): void {
 	response.writeHead(status, {
 		"content-type": "application/json; charset=utf-8",
-		"access-control-allow-origin": "*",
-		"access-control-allow-methods": "GET,POST,OPTIONS",
-		"access-control-allow-headers": "content-type",
 		"cache-control": "no-store",
 		...(extraHeaders ?? {}),
 	});
@@ -278,16 +298,25 @@ class ChromeProfileBridge {
 	}
 
 	private async handle(request: IncomingMessage, response: ServerResponse): Promise<void> {
+		const url = new URL(request.url ?? "/", this.url);
+		const corsHeaders = corsHeadersFor(request);
 		if (request.method === "OPTIONS") {
-			sendJson(response, 200, { ok: true });
+			if (!isBrowserOriginAllowed(request)) {
+				sendJson(response, 403, { ok: false, error: "browser origin not allowed" });
+				return;
+			}
+			sendJson(response, 200, { ok: true }, corsHeaders);
 			return;
 		}
-		const url = new URL(request.url ?? "/", this.url);
 		if (request.method === "GET" && url.pathname === "/status") {
 			sendJson(response, 200, this.status());
 			return;
 		}
 		if (request.method === "POST" && url.pathname === "/command") {
+			if (!isLocalProcessRequest(request)) {
+				sendJson(response, 403, { ok: false, error: "Chrome commands are accepted only from local Pi processes" });
+				return;
+			}
 			const body = JSON.parse(await readRequestBody(request)) as {
 				action?: string;
 				params?: Record<string, unknown>;
@@ -306,6 +335,10 @@ class ChromeProfileBridge {
 			return;
 		}
 		if (request.method === "GET" && url.pathname === "/next") {
+			if (!isBrowserOriginAllowed(request)) {
+				sendJson(response, 403, { ok: false, error: "browser origin not allowed" });
+				return;
+			}
 			this.lastSeenAt = Date.now();
 			this.clientName = url.searchParams.get("name") ?? undefined;
 			let aborted = false;
@@ -334,23 +367,27 @@ class ChromeProfileBridge {
 				command
 					? { type: "command", command, expectedExtensionVersion: currentVersion }
 					: { type: "none", expectedExtensionVersion: currentVersion },
-				{ "x-pi-chrome-version": currentVersion },
+				{ ...corsHeaders, "x-pi-chrome-version": currentVersion },
 			);
 			return;
 		}
 		if (request.method === "POST" && url.pathname === "/result") {
+			if (!isBrowserOriginAllowed(request)) {
+				sendJson(response, 403, { ok: false, error: "browser origin not allowed" });
+				return;
+			}
 			this.lastSeenAt = Date.now();
 			const result = JSON.parse(await readRequestBody(request)) as BridgeResult;
 			const pending = this.pending.get(result.id);
 			if (!pending) {
-				sendJson(response, 404, { ok: false, error: "unknown command id" });
+				sendJson(response, 404, { ok: false, error: "unknown command id" }, corsHeaders);
 				return;
 			}
 			clearTimeout(pending.timer);
 			this.pending.delete(result.id);
 			if (result.ok) pending.resolve(result.result);
 			else pending.reject(new Error(result.error ?? "Chrome extension command failed"));
-			sendJson(response, 200, { ok: true });
+			sendJson(response, 200, { ok: true }, corsHeaders);
 			return;
 		}
 		sendJson(response, 404, { error: "not found" });
@@ -399,6 +436,46 @@ export default function (pi: ExtensionAPI): void {
 
 	const bridge = new ChromeProfileBridge(DEFAULT_HOST, DEFAULT_PORT);
 	let backgroundDefault = false;
+	let chromeAuthorizedUntil: number | "session" | undefined;
+	let chromeAuthorizedCalls: number | undefined;
+
+	const authSummary = (): string => {
+		if (chromeAuthorizedUntil === "session") return "authorized for this session";
+		if (typeof chromeAuthorizedUntil === "number") {
+			const remainingMs = chromeAuthorizedUntil - Date.now();
+			if (remainingMs > 0) {
+				const minutes = Math.ceil(remainingMs / 60_000);
+				return `authorized for ${chromeAuthorizedCalls === 1 ? "one Chrome command" : `~${minutes}m`}`;
+			}
+		}
+		return "locked";
+	};
+
+	const chromeControlAuthorized = (): boolean => {
+		if (chromeAuthorizedUntil === "session") return true;
+		if (typeof chromeAuthorizedUntil === "number" && chromeAuthorizedUntil > Date.now()) return true;
+		chromeAuthorizedUntil = undefined;
+		chromeAuthorizedCalls = undefined;
+		return false;
+	};
+
+	const requireChromeControlAuthorized = (): void => {
+		if (!chromeControlAuthorized()) {
+			throw new Error("Chrome control locked. Ask the user to run /chrome authorize before using chrome_* tools.");
+		}
+		if (chromeAuthorizedCalls !== undefined) {
+			chromeAuthorizedCalls -= 1;
+			if (chromeAuthorizedCalls <= 0) {
+				chromeAuthorizedUntil = undefined;
+				chromeAuthorizedCalls = undefined;
+			}
+		}
+	};
+
+	const authorizedBridgeSend = (action: string, params: Record<string, unknown>, timeoutMs = DEFAULT_TIMEOUT_MS): Promise<unknown> => {
+		requireChromeControlAuthorized();
+		return bridge.send(action, params, timeoutMs);
+	};
 
 	// Translate the public `background` parameter (default false = visible/foreground) into the
 	// service worker's wire-level `foreground` flag, accepting legacy `foreground` as a fallback.
@@ -420,8 +497,8 @@ export default function (pi: ExtensionAPI): void {
 		ctx.ui.setStatus("chrome", `Chrome bridge :${DEFAULT_PORT}`);
 		ctx.ui.notify(
 			status.mode === "client"
-				? `pi-chrome connected (sharing the Chrome connection an earlier pi session opened).`
-				: `pi-chrome is ready and waiting for the Chrome companion to connect. Run /chrome onboard to install it.`,
+				? `pi-chrome connected (sharing the Chrome connection an earlier pi session opened). Run /chrome authorize before using chrome_* tools.`
+				: `pi-chrome is ready and waiting for the Chrome companion to connect. Run /chrome onboard to install it, then /chrome authorize to allow chrome_* tools.`,
 			"info",
 		);
 	});
@@ -442,13 +519,14 @@ Capability model (important):
 - Tool results include \`pageMutated\`, \`defaultPrevented\`, \`elementVisible\`, \`occludedBy\`, and (for type/fill) \`valueMatches\`. If an action result indicates no page change or occlusion, inspect current page state instead of repeating blindly.
 
 Usage rules:
-1. \`chrome_snapshot\` before clicking/typing; pass \`uid\` over \`selector\`.
-2. \`includeSnapshot=true\` on click/type/fill to verify in one round trip.
-3. If \`chrome_evaluate\` returns null when you expected a value, the expression evaluated to null/undefined in the page; surface the value via \`JSON.stringify\` to confirm.
-4. \`chrome_navigate\` supports an optional \`initScript\` that runs at document_start in MAIN world for the next navigation (good for seeding localStorage or stubbing Date.now).
-5. By default chrome_* tools focus Chrome so the user can watch; pass \`background=true\` or run /chrome quiet to silence the whole session.
-6. If you hit a native file-picker or privileged browser prompt gate, tell the user; generic clicks/typing/CSP gates are handled by Chrome input.
-7. Run /chrome doctor when in doubt about connectivity or capabilities.
+1. If a chrome_* tool says Chrome control is locked, ask the user to run \`/chrome authorize\` before retrying.
+2. \`chrome_snapshot\` before clicking/typing; pass \`uid\` over \`selector\`.
+3. \`includeSnapshot=true\` on click/type/fill to verify in one round trip.
+4. If \`chrome_evaluate\` returns null when you expected a value, the expression evaluated to null/undefined in the page; surface the value via \`JSON.stringify\` to confirm.
+5. \`chrome_navigate\` supports an optional \`initScript\` that runs at document_start in MAIN world for the next navigation (good for seeding localStorage or stubbing Date.now).
+6. By default chrome_* tools focus Chrome so the user can watch; pass \`background=true\` or run /chrome background on for session-wide background execution.
+7. If you hit a native file-picker or privileged browser prompt gate, tell the user; generic clicks/typing/CSP gates are handled by Chrome input.
+8. Run /chrome doctor when in doubt about connectivity or capabilities.
 </chrome-profile-bridge>`;
 		return { systemPrompt: event.systemPrompt + primer };
 	});
@@ -517,9 +595,9 @@ Usage rules:
 		ctx.ui.notify(lines.join("\n"), "info");
 	};
 
-	// Quiet (Chrome focus) handler. No args = toggle. Explicit on/off/status.
-	const QUIET_DESC: Record<string, string> = {
-		on: "pi-chrome works in the background; Chrome won't pop up or steal focus.",
+	// Run-in-background (Chrome focus) handler. No args = toggle. Explicit on/off/status.
+	const BACKGROUND_DESC: Record<string, string> = {
+		on: "pi-chrome runs in the background; Chrome won't pop up or steal focus.",
 		off: "Chrome pops to the front and switches tabs so you can watch what pi-chrome is doing.",
 	};
 
@@ -528,7 +606,7 @@ Usage rules:
 		const currentLabel = backgroundDefault ? "on" : "off";
 
 		if (arg === "status") {
-			ctx.ui.notify(`Quiet mode is ${currentLabel}. ${QUIET_DESC[currentLabel]}`, "info");
+			ctx.ui.notify(`Run in background is ${currentLabel}. ${BACKGROUND_DESC[currentLabel]}`, "info");
 			return;
 		}
 
@@ -536,12 +614,48 @@ Usage rules:
 		else if (arg === "off" || arg === "false" || arg === "0") backgroundDefault = false;
 		else if (arg === "toggle" || arg === "") backgroundDefault = !backgroundDefault;
 		else {
-			ctx.ui.notify(`Unknown quiet mode '${arg}'. Pick one of: on | off | toggle | status.`, "warning");
+			ctx.ui.notify(`Unknown background setting '${arg}'. Pick one of: on | off | toggle | status.`, "warning");
 			return;
 		}
 
 		const nextLabel = backgroundDefault ? "on" : "off";
-		ctx.ui.notify(`Quiet mode → ${nextLabel}. ${QUIET_DESC[nextLabel]}`, "info");
+		ctx.ui.notify(`Run in background → ${nextLabel}. ${BACKGROUND_DESC[nextLabel]}`, "info");
+	};
+
+	const authorizeHandler = async (ctx: ExtensionContext, args: string) => {
+		const arg = (args || "").trim().toLowerCase() || "session";
+		if (arg === "status") {
+			ctx.ui.notify(`Chrome control auth: ${authSummary()}.`, "info");
+			return;
+		}
+		const options: Record<string, { label: string; until: number | "session"; calls?: number }> = {
+			once: { label: "one Chrome command", until: Date.now() + 10 * 60_000, calls: 1 },
+			"15m": { label: "15 minutes", until: Date.now() + 15 * 60_000 },
+			"1h": { label: "1 hour", until: Date.now() + 60 * 60_000 },
+			session: { label: "this Pi session", until: "session" },
+		};
+		const grant = options[arg];
+		if (!grant) {
+			ctx.ui.notify("Unknown authorize duration. Pick one of: once | 15m | 1h | session | status.", "warning");
+			return;
+		}
+		const ok = await ctx.ui.confirm(
+			"Authorize pi-chrome control?",
+			`This Pi session will be allowed to inspect and control your existing Chrome profile for ${grant.label}.\n\nChrome actions use your signed-in browser state and real input. Only approve if you trust the current agent/task.`,
+		);
+		if (!ok) {
+			ctx.ui.notify("Chrome control remains locked.", "info");
+			return;
+		}
+		chromeAuthorizedUntil = grant.until;
+		chromeAuthorizedCalls = grant.calls;
+		ctx.ui.notify(`Chrome control authorized for ${grant.label}.`, "info");
+	};
+
+	const revokeHandler = (ctx: ExtensionContext) => {
+		chromeAuthorizedUntil = undefined;
+		chromeAuthorizedCalls = undefined;
+		ctx.ui.notify("Chrome control locked. Run /chrome authorize to allow chrome_* tools again.", "info");
 	};
 
 	const onboardHandler = async (ctx: ExtensionContext) => {
@@ -579,7 +693,8 @@ Usage rules:
 		} catch {
 			parts.push(`✗ Chrome not responding`);
 		}
-		parts.push(`quiet: ${backgroundDefault ? "on" : "off"}`);
+		parts.push(`auth: ${authSummary()}`);
+		parts.push(`background: ${backgroundDefault ? "on" : "off"}`);
 		return parts.join(" · ");
 	};
 
@@ -591,14 +706,14 @@ Usage rules:
 	// the last value also saves; Esc / 'q' closes. The description below changes with the
 	// current value so users always see what the active setting means.
 	const openSettingsDialog = async (ctx: ExtensionContext): Promise<void> => {
-		const quietItem: SettingItem = {
-			id: "quiet",
-			label: "Quiet mode",
+		const backgroundItem: SettingItem = {
+			id: "background",
+			label: "Run in background",
 			currentValue: backgroundDefault ? "on" : "off",
 			values: ["on", "off"],
-			description: QUIET_DESC[backgroundDefault ? "on" : "off"] ?? "",
+			description: BACKGROUND_DESC[backgroundDefault ? "on" : "off"] ?? "",
 		};
-		const items: SettingItem[] = [quietItem];
+		const items: SettingItem[] = [backgroundItem];
 
 		await ctx.ui.custom<void>((_tui, theme, _kb, done) => {
 			const container = new Container();
@@ -611,10 +726,10 @@ Usage rules:
 				Math.min(items.length + 2, 8),
 				getSettingsListTheme(),
 				(id, newValue) => {
-					if (id === "quiet") {
+					if (id === "background") {
 						backgroundDefault = newValue === "on";
-						quietItem.currentValue = newValue;
-						quietItem.description = QUIET_DESC[newValue] ?? "";
+						backgroundItem.currentValue = newValue;
+						backgroundItem.description = BACKGROUND_DESC[newValue] ?? "";
 						list.invalidate();
 					}
 				},
@@ -632,7 +747,7 @@ Usage rules:
 
 	pi.registerCommand("chrome", {
 		description:
-			"All pi-chrome controls in one place.\n  /chrome status   — one-line snapshot of connection + quiet mode.\n  /chrome doctor   — full health check.\n  /chrome onboard  — install the Chrome companion extension.\n  /chrome quiet  [on|off|status|toggle] — whether Chrome pops to the front when pi-chrome acts.\nRun with no arguments for an interactive picker that shows current state.",
+			"All pi-chrome controls in one place.\n  /chrome authorize [once|15m|1h|session|status] — allow this Pi session to use chrome_* tools.\n  /chrome revoke   — lock Chrome control.\n  /chrome status   — one-line snapshot of connection, auth, and background setting.\n  /chrome doctor   — full health check.\n  /chrome onboard  — install the Chrome companion extension.\n  /chrome background [on|off|status|toggle] — whether pi-chrome runs without focusing Chrome.\nRun with no arguments for an interactive picker that shows current state.",
 		getArgumentCompletions: (prefix) => {
 			const raw = prefix;
 			const trimmedRight = raw.replace(/\s+$/, "");
@@ -649,17 +764,27 @@ Usage rules:
 			let candidates: Item[] = [];
 			if (path.length === 0) {
 				candidates = [
-					{ fullValue: "status", label: "status", description: "One-line summary: connection + quiet mode." },
+					{ fullValue: "authorize", label: "authorize", description: "Allow this Pi session to use chrome_* tools." },
+					{ fullValue: "revoke", label: "revoke", description: "Lock Chrome control for this Pi session." },
+					{ fullValue: "status", label: "status", description: "One-line summary: connection, auth, and background setting." },
 					{ fullValue: "doctor", label: "doctor", description: "Full health check. Tells you if Chrome is connected and what's wrong if it isn't." },
 					{ fullValue: "onboard", label: "onboard", description: "Install the Chrome companion extension (first-time setup)." },
-					{ fullValue: "quiet", label: "quiet", description: "Should Chrome pop to the front when pi-chrome acts, or work silently?" },
+					{ fullValue: "background", label: "background", description: "Run pi-chrome in the background without focusing Chrome?" },
+				];
+			} else if (path[0] === "authorize" && path.length === 1) {
+				candidates = [
+					{ fullValue: "authorize once", label: "once", description: "Authorize one Chrome command." },
+					{ fullValue: "authorize 15m", label: "15m", description: "Authorize Chrome control for 15 minutes." },
+					{ fullValue: "authorize 1h", label: "1h", description: "Authorize Chrome control for 1 hour." },
+					{ fullValue: "authorize session", label: "session", description: "Authorize Chrome control until this Pi session exits." },
+					{ fullValue: "authorize status", label: "status", description: "Show Chrome control authorization state." },
 				];
-			} else if (path[0] === "quiet" && path.length === 1) {
+			} else if (path[0] === "background" && path.length === 1) {
 				candidates = [
-					{ fullValue: "quiet on", label: "on", description: "Work silently. Chrome stays in the background. Your editor keeps focus." },
-					{ fullValue: "quiet off", label: "off", description: "Bring Chrome to the front so you can watch (default)." },
-					{ fullValue: "quiet toggle", label: "toggle", description: "Flip whichever way it's currently set." },
-					{ fullValue: "quiet status", label: "status", description: "Show the current setting." },
+					{ fullValue: "background on", label: "on", description: "Run in background. Chrome stays in the background. Your editor keeps focus." },
+					{ fullValue: "background off", label: "off", description: "Bring Chrome to the front so you can watch (default)." },
+					{ fullValue: "background toggle", label: "toggle", description: "Flip whichever way it's currently set." },
+					{ fullValue: "background status", label: "status", description: "Show the current setting." },
 				];
 			}
 			if (candidates.length === 0) return null;
@@ -676,21 +801,22 @@ Usage rules:
 			const [head, ...rest] = tokens;
 			const subArgs = rest.join(" ");
 			switch (head) {
+				case "authorize": return authorizeHandler(ctx, subArgs);
+				case "revoke": return revokeHandler(ctx);
 				case "status": return statusHandler(ctx);
 				case "doctor": return doctorHandler(ctx);
 				case "onboard": return onboardHandler(ctx);
-				case "quiet":
-				case "background": // legacy alias
+				case "background":
 					return backgroundHandler(ctx, subArgs);
 				case "settings": {
 					// Legacy nested form: /chrome settings background ...
 					const [setting, ...settingArgs] = rest;
 					if (setting === "background") return backgroundHandler(ctx, settingArgs.join(" "));
-					ctx.ui.notify(`'/chrome settings' was removed. Use /chrome quiet directly.`, "warning");
+					ctx.ui.notify(`'/chrome settings' was removed. Use /chrome background directly.`, "warning");
 					return;
 				}
 				default:
-					ctx.ui.notify(`Unknown subcommand '${head}'. Try: /chrome status | doctor | onboard | quiet.`, "warning");
+					ctx.ui.notify(`Unknown subcommand '${head}'. Try: /chrome authorize | revoke | status | doctor | onboard | background.`, "warning");
 			}
 		},
 	});
@@ -710,7 +836,7 @@ Usage rules:
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx): Promise<ToolTextResult> {
 			if (params.url && bridge.connected) {
-				const result = await bridge.send("tab.new", { url: params.url }, DEFAULT_TIMEOUT_MS);
+				const result = await authorizedBridgeSend("tab.new", { url: params.url }, DEFAULT_TIMEOUT_MS);
 				return { content: [{ type: "text", text: `Chrome bridge connected; opened ${params.url}` }], details: { status: bridge.status(), result } };
 			}
 			return {
@@ -745,7 +871,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send(`tab.${params.action}`, params, DEFAULT_TIMEOUT_MS);
+			const result = await authorizedBridgeSend(`tab.${params.action}`, params, DEFAULT_TIMEOUT_MS);
 			if (params.action === "list") {
 				const tabs = result as Array<{ id: number; title: string; url: string; active: boolean; windowId: number }>;
 				const text = tabs.map((tab) => `${tab.id}\t${tab.active ? "*" : " "}\t${tab.title || "(untitled)"}\t${tab.url}`).join("\n") || "No tabs.";
@@ -776,7 +902,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const snapshot = await bridge.send(
+			const snapshot = await authorizedBridgeSend(
 				"page.snapshot",
 				withBackground({ ...params, maxElements: params.maxElements ?? MAX_ELEMENTS }),
 				DEFAULT_TIMEOUT_MS,
@@ -806,7 +932,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.navigate", withBackground(params), (params.timeoutMs ?? 15_000) + 2_000);
+			const result = await authorizedBridgeSend("page.navigate", withBackground(params), (params.timeoutMs ?? 15_000) + 2_000);
 			return { content: [{ type: "text", text: `Navigated to ${params.url}${params.initScript ? " (with initScript)" : ""}` }], details: { result: result as Json } };
 		},
 	});
@@ -830,7 +956,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const value = await bridge.send("page.evaluate", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const value = await authorizedBridgeSend("page.evaluate", withBackground(params), DEFAULT_TIMEOUT_MS);
 			const text = value === undefined
 				? "undefined"
 				: typeof value === "string"
@@ -863,7 +989,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const raw = await bridge.send("page.click", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const raw = await authorizedBridgeSend("page.click", withBackground(params), DEFAULT_TIMEOUT_MS);
 			const result = (params.includeSnapshot ? (raw as { result: unknown }).result : raw) as Json;
 			const summary = summarizeActionResult(result);
 			const target = params.uid ?? params.selector ?? `${params.x},${params.y}`;
@@ -895,7 +1021,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const raw = await bridge.send("page.type", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const raw = await authorizedBridgeSend("page.type", withBackground(params), DEFAULT_TIMEOUT_MS);
 			const result = (params.includeSnapshot ? (raw as { result: unknown }).result : raw) as Json;
 			const summary = summarizeActionResult(result);
 			const into = params.uid || params.selector ? ` into ${params.uid ?? params.selector}` : "";
@@ -927,7 +1053,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const raw = await bridge.send("page.fill", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const raw = await authorizedBridgeSend("page.fill", withBackground(params), DEFAULT_TIMEOUT_MS);
 			const result = (params.includeSnapshot ? (raw as { result: unknown }).result : raw) as Json;
 			const summary = summarizeActionResult(result);
 			const into = params.uid || params.selector ? ` into ${params.uid ?? params.selector}` : "";
@@ -962,7 +1088,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const raw = await bridge.send("page.key", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const raw = await authorizedBridgeSend("page.key", withBackground(params), DEFAULT_TIMEOUT_MS);
 			const result = (params.includeSnapshot ? (raw as { result: unknown }).result : raw) as Json;
 			const summary = summarizeActionResult(result);
 			const base = `Pressed ${params.key}.`;
@@ -987,7 +1113,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.waitFor", params, (params.timeoutMs ?? 10_000) + 2_000);
+			const result = await authorizedBridgeSend("page.waitFor", params, (params.timeoutMs ?? 10_000) + 2_000);
 			return { content: [{ type: "text", text: `Observed ${params.kind}: ${params.value}` }], details: { result: result as Json } };
 		},
 	});
@@ -1008,7 +1134,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.console.list", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const result = await authorizedBridgeSend("page.console.list", withBackground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: truncateText(safeJson(result)) }], details: { result: result as Json } };
 		},
 	});
@@ -1030,7 +1156,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.network.list", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const result = await authorizedBridgeSend("page.network.list", withBackground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: truncateText(safeJson(result)) }], details: { result: result as Json } };
 		},
 	});
@@ -1050,7 +1176,7 @@ Usage rules:
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.network.get", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const result = await authorizedBridgeSend("page.network.get", withBackground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: truncateText(safeJson(result)) }], details: { result: result as Json } };
 		},
 	});
@@ -1080,7 +1206,7 @@ Usage rules:
 			const cwd = workspaceCwd(ctx);
 			const defaultPath = join(cwd, ".pi", "chrome-screenshots", `${new Date().toISOString().replace(/[:.]/g, "-")}.${format}`);
 			const outputPath = params.path ? resolve(cwd, params.path) : defaultPath;
-			const result = (await bridge.send("page.screenshot", withBackground(params), params.fullPage ? 120_000 : DEFAULT_TIMEOUT_MS)) as {
+			const result = (await authorizedBridgeSend("page.screenshot", withBackground(params), params.fullPage ? 120_000 : DEFAULT_TIMEOUT_MS)) as {
 				dataUrl?: string;
 				tab?: unknown;
 				fullPage?: boolean;
@@ -1130,7 +1256,7 @@ Usage rules:
 			background: Type.Optional(Type.Boolean()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.hover", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const result = await authorizedBridgeSend("page.hover", withBackground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: `Hovered ${params.uid ?? params.selector ?? `${params.x},${params.y}`}` }], details: { result: result as Json } };
 		},
 	});
@@ -1156,7 +1282,7 @@ Usage rules:
 			background: Type.Optional(Type.Boolean()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.drag", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const result = await authorizedBridgeSend("page.drag", withBackground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: `Dragged from ${params.fromUid ?? params.fromSelector} to ${params.toUid ?? params.toSelector}` }], details: { result: result as Json } };
 		},
 	});
@@ -1178,7 +1304,7 @@ Usage rules:
 			background: Type.Optional(Type.Boolean()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.tap", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const result = await authorizedBridgeSend("page.tap", withBackground(params), DEFAULT_TIMEOUT_MS);
 			const target = params.uid ?? params.selector ?? `${params.x},${params.y}`;
 			return { content: [{ type: "text", text: `Tapped ${target} (touch)` }], details: { result: result as Json } };
 		},
@@ -1201,7 +1327,7 @@ Usage rules:
 			background: Type.Optional(Type.Boolean()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.scroll", withBackground(params), DEFAULT_TIMEOUT_MS);
+			const result = await authorizedBridgeSend("page.scroll", withBackground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: `Scrolled dy=${params.deltaY ?? 0} dx=${params.deltaX ?? 0}` }], details: { result: result as Json } };
 		},
 	});
@@ -1223,7 +1349,7 @@ Usage rules:
 		async execute(_id, params, _signal, _onUpdate, ctx): Promise<ToolTextResult> {
 			const cwd = workspaceCwd(ctx);
 			const paths = params.paths.map((p) => resolve(cwd, p));
-			const result = await bridge.send("page.upload", withBackground({ ...params, paths }), DEFAULT_TIMEOUT_MS);
+			const result = await authorizedBridgeSend("page.upload", withBackground({ ...params, paths }), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: `Uploaded ${paths.length} file(s) to ${params.uid ?? params.selector}` }], details: { result: result as Json } };
 		},
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-chrome",
-	"version": "0.15.3",
+	"version": "0.15.5",
 	"scripts": {
 		"version": "node scripts/sync-manifest-version.js",
 		"prepublishOnly": "node scripts/sync-manifest-version.js"