pi-agent-browser-native 0.1.6 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.0 - 2026-04-12
+
+### Changed
+- `batch` now reuses the richer standalone renderers, so batched snapshots keep the compact main-content-first view and batched screenshots keep inline image attachments instead of degrading to raw JSON-ish text
+- the tool schema now uses `sessionMode: "auto" | "fresh"` instead of the old implicit-session boolean so agents have a first-class way to request a fresh profiled/debug launch, and blocked startup-scoped reuse errors now include structured recovery hints
+- plain-text inspection commands like `agent_browser --help` and `--version` are now always allowed, removing the old prompt-dependent inspection gate and making the inspection contract local and predictable
+- navigation actions like `click`, `dblclick`, `back`, `forward`, and `reload` now include lightweight post-action title/url summaries when the wrapper can address the active session, reducing guess-and-check follow-up snapshots
+- compact snapshot rendering is leaner by default: fewer additional sections, fewer refs, smaller role summaries, and the raw spill path now stays in `details.fullOutputPath` instead of dominating the visible snapshot body
+- README and injected tool guidance now include a compact agent quick start with the core call shapes for `open` + `snapshot`, `click` + re-snapshot, `batch`, `eval --stdin`, and fresh profiled launches
+
+### Migration notes
+- replace any use of `useActiveSession` with `sessionMode`
+- use `sessionMode: "fresh"` when you need a new `--profile`, `--session-name`, or `--cdp` launch after the implicit session is already active
+
 ## 0.1.6 - 2026-04-12
 
 ### Changed

package/README.md

@@ -87,6 +87,67 @@ This avoids duplicate `agent_browser` registrations if you also have the publish
 
 The native tool exposed to the agent is named `agent_browser`.
 
+The primary session control parameter is `sessionMode`:
+
+- `"auto"` (default) reuses the implicit `pi`-scoped session when possible
+- `"fresh"` skips that implicit session so startup-scoped flags like `--profile`, `--session-name`, and `--cdp` can launch a fresh upstream session
+
+## Agent quick start
+
+### Mental model
+
+- `args` — exact CLI args after `agent-browser`
+- `stdin` — raw stdin only for `batch` and `eval --stdin`
+- `sessionMode`
+  - `"auto"` — default, reuse the implicit `pi`-scoped session
+  - `"fresh"` — skip the implicit session for a new profile/debug launch
+
+### Common call shapes
+
+Open a page, then take an interactive snapshot:
+
+```json
+{ "args": ["open", "https://example.com"] }
+{ "args": ["snapshot", "-i"] }
+```
+
+Click a ref, then re-snapshot after navigation or a major DOM change:
+
+```json
+{ "args": ["click", "@e2"] }
+{ "args": ["snapshot", "-i"] }
+```
+
+Run a multi-step browser flow in one tool call:
+
+```json
+{ "args": ["batch"], "stdin": "[[\"open\",\"https://example.com\"],[\"snapshot\",\"-i\"]]" }
+```
+
+Evaluate page JavaScript via stdin:
+
+```json
+{ "args": ["eval", "--stdin"], "stdin": "document.title" }
+```
+
+Start a fresh profiled launch after you already used the implicit session:
+
+```json
+{ "args": ["--profile", "Default", "open", "https://example.com/account"], "sessionMode": "fresh" }
+```
+
+Name a new upstream session explicitly when you want to keep reusing it:
+
+```json
+{ "args": ["--session", "auth-flow", "open", "https://example.com"] }
+```
+
+### First useful prompt in a fresh `pi` session
+
+```text
+Use the agent_browser tool to open https://react.dev and then take an interactive snapshot.
+```
+
 ## Local development
 
 Do not track or rely on a repo-local `.pi/extensions/agent-browser.ts` autoload shim for this package. When the package is also installed globally, that creates a duplicate `agent_browser` registration and blocks `pi` startup from this working directory.
@@ -116,14 +177,40 @@ Validated workflow examples:
 - run `batch` with JSON via `stdin`
 - run `eval --stdin`
 - take a screenshot with inline attachment support
-- inspect `agent_browser --help` and `--version`
+- inspect `agent_browser --help` and `--version` via the tool's plain-text inspection fallback
+
+Inspection commands like `agent_browser --help` and `--version` are always supported. They return plain text and are useful for debugging or capability checks, but they are not required for normal browsing workflows.
 
 Current cautions:
 - passing `--profile` is an explicit upstream choice; this extension does not add its own profile-cloning or isolation layer
-- startup-scoped flags like `--profile`, `--session-name`, and `--cdp` are for the first command that launches a session; if the implicit session is already active, the extension returns a validation error instead of silently letting upstream ignore those flags
+- startup-scoped flags like `--profile`, `--session-name`, and `--cdp` are for the first command that launches a session; if the implicit session is already active, retry that call with `sessionMode: "fresh"` or provide an explicit `--session ...` for the new launch
 - implicit `piab-*` sessions are extension-managed convenience sessions; they are best-effort closed on `pi` shutdown, get an idle timeout to reduce stale background daemons, and clean up private temp spill artifacts on shutdown
 - explicit upstream sessions like `--session`, `--profile`, `--session-name`, and `--cdp` are treated as user-managed and are not auto-closed by the extension
 
+### Switching from public browsing to a fresh profile/debug launch
+
+A common agent workflow is:
+
+1. browse a public page with the default implicit session
+2. then switch to a fresh authenticated/profile/debug launch
+
+Use `sessionMode: "fresh"` for that transition instead of relying on the implicit session:
+
+```json
+{
+  "args": ["--profile", "Default", "open", "https://example.com/account"],
+  "sessionMode": "fresh"
+}
+```
+
+If you want to name the new upstream session yourself, pass an explicit session instead:
+
+```json
+{
+  "args": ["--session", "auth-flow", "--profile", "Default", "open", "https://example.com/account"]
+}
+```
+
 ## Docs
 
 - [`docs/REQUIREMENTS.md`](docs/REQUIREMENTS.md) — product requirements and constraints

package/docs/ARCHITECTURE.md

@@ -59,17 +59,19 @@ The published package should exclude agent-only and superseded repo materials su
 
 ### Default
 
-If the caller does not provide `--session`, the extension should use an implicit session name derived from the current `pi` session id.
+If the caller does not provide `--session`, the extension should default to `sessionMode: "auto"` and use an implicit session name derived from the current `pi` session id.
 
 Why:
 - works out of the box
 - gives continuity across calls
 - avoids forcing the agent to invent session names for basic browsing
 
-### Explicit upstream sessions
+### Explicit upstream sessions and fresh launches
 
 If the caller provides `--session`, `--profile`, `--cdp`, or similar upstream flags, the extension should respect them with minimal interference.
 
+The tool should also expose a first-class `sessionMode: "fresh"` escape hatch so agents can intentionally skip the implicit session and launch a fresh upstream session without inventing a fixed explicit session name.
+
 ### Ownership
 
 V1 ownership rule:
@@ -92,7 +94,9 @@ The extension should surface that clearly and avoid hidden restart behavior in v
 
 That means explicit startup-scoping flags like `--profile`, `--session-name`, and `--cdp` should remain explicit upstream choices instead of being wrapped in extra hidden restart or cloning logic.
 
-If the implicit session is already active and one of those startup-scoped flags appears again, the extension should fail clearly instead of silently sending a command shape that upstream would ignore.
+If the implicit session is already active and one of those startup-scoped flags appears again while `sessionMode` is still `"auto"`, the extension should fail clearly instead of silently sending a command shape that upstream would ignore.
+
+That failure should include a structured recovery hint pointing to `sessionMode: "fresh"` as the first-line fix, while still allowing an explicit `--session` when the caller wants to name the new upstream session.
 
 ## Preferring the native tool
 

package/docs/TOOL_CONTRACT.md

@@ -32,7 +32,7 @@ The tool also needs an operating playbook, not just a capability list. The model
 {
   "args": ["open", "https://example.com"],
   "stdin": "optional raw stdin content",
-  "useActiveSession": true
+  "sessionMode": "auto"
 }
 ```
 
@@ -69,15 +69,20 @@ Examples:
 { "args": ["batch"], "stdin": "[[\"open\",\"https://example.com\"],[\"snapshot\",\"-i\"]]" }
 ```
 
-### `useActiveSession`
+### `sessionMode`
 
-- type: `boolean`
+- type: `"auto" | "fresh"`
 - optional
-- default: `true`
+- default: `"auto"`
 
 Behavior:
 - if `args` already include `--session`, upstream session choice wins
-- otherwise the extension prepends its implicit active session when `useActiveSession` is `true`
+- `"auto"` prepends the implicit active session when appropriate
+- `"fresh"` skips the implicit session so startup-scoped flags like `--profile`, `--session-name`, or `--cdp` can launch a fresh upstream session
+
+Recommended use:
+- use `"auto"` for the common browse/snapshot/click flow inside one `pi` session
+- use `"fresh"` when switching from an already-active implicit session to a new profile/debug/auth launch without inventing a fixed explicit session name
 
 ## Wrapper behavior
 
@@ -87,8 +92,8 @@ The extension should:
 - parse JSON output into tool details
 - handle observed JSON result shapes, including the array returned by `batch --json`
 - allow plain-text fallback for inspection commands like `--help` and `--version`
-- discourage exploratory inspection calls unless the user explicitly asks or debugging requires them
-- deflect normal-task `--help` inspection back into the standard browser workflow instead of letting the model relearn the tool from scratch each session
+- support those inspection commands unconditionally so the tool contract stays local and predictable
+- still describe normal browser workflows in guidance so models do not overuse inspection for routine tasks
 - surface stderr and non-zero exits clearly
 - attach images when the result points to a screenshot-like artifact
 
@@ -104,7 +109,8 @@ Primary content should be:
 
 Examples:
 - small `snapshot` results should include the actual snapshot text
-- oversized `snapshot` results should switch to a compact view that preserves the primary content, nearby sections, high-value refs, and a path to the spilled full raw snapshot
+- oversized `snapshot` results should switch to a compact view that preserves the primary content, nearby sections, and a trimmed set of high-value refs, while exposing the full raw snapshot path via `details.fullOutputPath`
+- successful navigation actions like `click`, `back`, `forward`, and `reload` should include a lightweight post-action title/url summary when the wrapper can address the active session
 - `tab list` should include a readable tab summary
 - `screenshot` should include the saved-path summary plus the inline image attachment when available
 
@@ -116,6 +122,7 @@ Recommended details:
 {
   "args": ["snapshot", "-i"],
   "effectiveArgs": ["--session", "pi-abc123", "--json", "snapshot", "-i"],
+  "sessionMode": "auto",
   "sessionName": "pi-abc123",
   "usedImplicitSession": true,
   "data": {
@@ -136,7 +143,8 @@ For oversized snapshots, details should switch to a compact metadata object and
 
 Worth doing in v1:
 - screenshots → inline image attachment
-- snapshots → origin + ref count + main-content-first compact preview, with full raw snapshot spill files when the inline result would otherwise be too large
+- snapshots → origin + ref count + main-content-first compact preview, with the raw snapshot spill path kept in `details.fullOutputPath` when the inline result would otherwise be too large
+- navigation actions like `click`, `back`, `forward`, and `reload` → lightweight post-action title/url summary when available
 - tab lists → compact summary/table
 - stream status → enabled/connected/port summary
 
@@ -158,7 +166,7 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 - clean up private temp spill artifacts owned by the implicit session on shutdown
 - treat explicit upstream session choices like `--session`, `--profile`, `--session-name`, and `--cdp` as user-managed
 - pass explicit `--profile` straight through to upstream `agent-browser`; no profile-cloning or isolation layer is added in v1
-- if startup-scoped flags like `--profile`, `--session-name`, or `--cdp` are supplied after the implicit session is already active, return a validation error instead of silently relying on upstream to ignore them
+- if startup-scoped flags like `--profile`, `--session-name`, or `--cdp` are supplied after the implicit session is already active while `sessionMode` is `"auto"`, return a validation error with a structured recovery hint that recommends `sessionMode: "fresh"`
 
 ## Non-goals
 

package/extensions/agent-browser/index.ts

@@ -27,21 +27,29 @@ import {
 } from "./lib/runtime.js";
 import { cleanupSecureTempArtifacts } from "./lib/temp.js";
 
+const DEFAULT_SESSION_MODE = "auto" as const;
+
 const AGENT_BROWSER_PARAMS = Type.Object({
 	args: Type.Array(Type.String({ description: "Exact agent-browser CLI arguments, excluding the binary name." }), {
 		description: "Exact agent-browser CLI arguments, excluding the binary name and any shell operators.",
 		minItems: 1,
 	}),
 	stdin: Type.Optional(Type.String({ description: "Optional raw stdin content for commands like eval --stdin or batch." })),
-	useActiveSession: Type.Optional(
-		Type.Boolean({
-			description: "When true and no explicit --session is present, inject the implicit session for this pi session.",
-			default: true,
+	sessionMode: Type.Optional(
+		Type.Union([Type.Literal("auto"), Type.Literal("fresh")], {
+			description:
+				"Session handling mode. `auto` reuses the implicit pi-scoped session when possible. `fresh` skips the implicit session so startup-scoped flags like --profile, --session-name, or --cdp can launch a fresh upstream session.",
+			default: DEFAULT_SESSION_MODE,
 		}),
 	),
 });
 const PROJECT_RULE_PROMPT =
 	"Project rule: when browser automation is needed, prefer the native `agent_browser` tool. Do not run direct `agent-browser` bash commands unless the user explicitly asks for a bash-oriented workflow or browser-integration debugging.";
+const QUICK_START_GUIDELINES = [
+	"Quick start mental model: args are the exact agent-browser CLI args after the binary; stdin is only for batch and eval --stdin; sessionMode=fresh starts a fresh upstream launch when you need new --profile, --session-name, or --cdp state.",
+	"Common first calls: { args: [\"open\", \"https://example.com\"] } then { args: [\"snapshot\", \"-i\"] }; after navigation, use { args: [\"click\", \"@e2\"] } then { args: [\"snapshot\", \"-i\"] }.",
+	"Common advanced calls: { args: [\"batch\"], stdin: \"[[\\\"open\\\",\\\"https://example.com\\\"],[\\\"snapshot\\\",\\\"-i\\\"]]\" }, { args: [\"eval\", \"--stdin\"], stdin: \"document.title\" }, and { args: [\"--profile\", \"Default\", \"open\", \"https://example.com/account\"], sessionMode: \"fresh\" }.",
+] as const;
 const BRAVE_SEARCH_PROMPT_GUIDELINE =
 	"When a non-empty BRAVE_API_KEY is available in the current environment, prefer the Brave Search API via bash/curl to discover specific destination URLs, then open the chosen URL with agent_browser instead of browsing a search engine results page just to find the target.";
 const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
@@ -49,6 +57,7 @@ const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 	"For authenticated or user-specific content like feeds, inboxes, dashboards, and accounts, prefer --profile Default on the first browser call and let the implicit session carry continuity. Use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser.",
 	"Do not invent fixed explicit session names for routine tasks. Use the implicit session unless you truly need multiple isolated browser sessions in the same conversation.",
 	"When using --profile, --session-name, or --cdp, put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.",
+	"If you already used the implicit session and now need startup-scoped flags like --profile, --session-name, or --cdp, retry with sessionMode set to fresh or pass an explicit --session for the new launch.",
 	"If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <n> / snapshot -i to recover state before retrying different URLs or fallback strategies. Only use wait with an explicit argument like milliseconds, --load, --url, --fn, or --text.",
 	"For feed, timeline, or inbox reading tasks, focus on the main timeline/list region and read the first item there rather than unrelated composer or sidebar content.",
 	"For read-only browsing tasks, prefer extracting the answer from the current snapshot, structured ref labels, or eval --stdin on the current page before navigating away. Only click into media viewers, detail routes, or new pages when the current view does not contain the needed information.",
@@ -62,7 +71,8 @@ const TOOL_PROMPT_GUIDELINES_SUFFIX = [
 	"Do not fall back to osascript, AppleScript, or generic browser-driving bash commands when this tool can do the job.",
 	"Pass exact agent-browser CLI arguments in args, excluding the binary name.",
 	"Use stdin for commands like eval --stdin and batch instead of shell heredocs.",
-	"Let the implicit session handle the common path unless you explicitly need upstream flags like --session, --profile, or --cdp.",
+	"Let the implicit session handle the common path unless you explicitly need a fresh launch for upstream flags like --profile, --session-name, or --cdp.",
+	"Use sessionMode=fresh when switching from an existing implicit session to a new profile/debug launch without inventing a fixed explicit session name.",
 ] as const;
 
 function buildMissingBinaryMessage(): string {
@@ -92,15 +102,81 @@ function isPlainTextInspectionArgs(args: string[]): boolean {
 	return args.includes("--help") || args.includes("-h") || args.includes("--version") || args.includes("-V");
 }
 
-function buildInspectionDeflectionMessage(): string {
-	return [
-		"Do not inspect agent_browser help for a normal browser task.",
-		"Use the workflow directly:",
-		"1. open the target URL",
-		"2. snapshot -i",
-		"3. interact using refs and re-snapshot after navigation or major DOM changes",
-		"For authenticated or user-specific content like feeds, inboxes, dashboards, or accounts, start with an authenticated strategy such as --profile Default on the first browser call and let the implicit session carry continuity. Use --auto-connect only if profile-based reuse is unavailable.",
-	].join("\n");
+const NAVIGATION_SUMMARY_COMMANDS = new Set(["back", "click", "dblclick", "forward", "reload"]);
+
+interface NavigationSummary {
+	title?: string;
+	url?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function shouldCaptureNavigationSummary(command: string | undefined, data: unknown): boolean {
+	return (
+		command !== undefined &&
+		NAVIGATION_SUMMARY_COMMANDS.has(command) &&
+		(!isRecord(data) || (typeof data.title !== "string" && typeof data.url !== "string"))
+	);
+}
+
+function extractStringResultField(data: unknown, fieldName: "title" | "url"): string | undefined {
+	if (typeof data === "string") {
+		const text = data.trim();
+		return text.length > 0 ? text : undefined;
+	}
+	if (!isRecord(data) || typeof data[fieldName] !== "string") {
+		return undefined;
+	}
+	const text = data[fieldName].trim();
+	return text.length > 0 ? text : undefined;
+}
+
+async function collectNavigationSummary(options: {
+	cwd: string;
+	sessionName?: string;
+	signal?: AbortSignal;
+}): Promise<NavigationSummary | undefined> {
+	const { cwd, sessionName, signal } = options;
+	if (!sessionName) return undefined;
+
+	const readField = async (fieldName: "title" | "url"): Promise<string | undefined> => {
+		const processResult = await runAgentBrowserProcess({
+			args: ["--json", "--session", sessionName, "get", fieldName],
+			cwd,
+			signal,
+		});
+		if (processResult.aborted || processResult.spawnError || processResult.exitCode !== 0) {
+			return undefined;
+		}
+		const parsed = await parseAgentBrowserEnvelope({
+			stdout: processResult.stdout,
+			stdoutPath: processResult.stdoutSpillPath,
+		});
+		try {
+			if (parsed.parseError || parsed.envelope?.success === false) {
+				return undefined;
+			}
+			return extractStringResultField(parsed.envelope?.data, fieldName);
+		} finally {
+			if (processResult.stdoutSpillPath) {
+				await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);
+			}
+		}
+	};
+
+	const title = await readField("title");
+	const url = await readField("url");
+	if (!title && !url) return undefined;
+	return { title, url };
+}
+
+function mergeNavigationSummaryIntoData(data: unknown, navigationSummary: NavigationSummary): unknown {
+	if (isRecord(data)) {
+		return { ...data, navigationSummary };
+	}
+	return { navigationSummary, result: data };
 }
 
 function buildSharedBrowserPlaybookGuidelines(hasBraveApiKey: boolean): string[] {
@@ -115,6 +191,9 @@ function buildBrowserSystemPromptAppendix(hasBraveApiKey: boolean): string {
 	return [
 		PROJECT_RULE_PROMPT,
 		"",
+		"Quick start:",
+		...QUICK_START_GUIDELINES.map((guideline) => `- ${guideline}`),
+		"",
 		"Browser operating playbook:",
 		...buildSharedBrowserPlaybookGuidelines(hasBraveApiKey).map((guideline) => `- ${guideline}`),
 	].join("\n");
@@ -123,6 +202,7 @@ function buildBrowserSystemPromptAppendix(hasBraveApiKey: boolean): string {
 function buildToolPromptGuidelines(hasBraveApiKey: boolean): string[] {
 	return [
 		...TOOL_PROMPT_GUIDELINES_PREFIX,
+		...QUICK_START_GUIDELINES,
 		...buildSharedBrowserPlaybookGuidelines(hasBraveApiKey),
 		...TOOL_PROMPT_GUIDELINES_SUFFIX,
 	];
@@ -194,16 +274,6 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		promptGuidelines: toolPromptGuidelines,
 		parameters: AGENT_BROWSER_PARAMS,
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			const promptPolicy = buildPromptPolicy(getLatestUserPrompt(ctx.sessionManager.getBranch()));
-			if (!promptPolicy.allowAgentBrowserInspection && isPlainTextInspectionArgs(params.args)) {
-				const errorText = buildInspectionDeflectionMessage();
-				return {
-					content: [{ type: "text", text: errorText }],
-					details: { args: params.args, inspectionBlocked: true },
-					isError: true,
-				};
-			}
-
 			const validationError = validateToolArgs(params.args);
 			if (validationError) {
 				return {
@@ -213,10 +283,11 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				};
 			}
 
+			const sessionMode = params.sessionMode ?? DEFAULT_SESSION_MODE;
 			const executionPlan = buildExecutionPlan(params.args, {
 				implicitSessionActive,
 				implicitSessionName,
-				useActiveSession: params.useActiveSession ?? true,
+				sessionMode,
 			});
 
 			if (executionPlan.validationError) {
@@ -224,6 +295,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					content: [{ type: "text", text: executionPlan.validationError }],
 					details: {
 						args: params.args,
+						sessionMode,
+						sessionRecoveryHint: executionPlan.recoveryHint,
 						startupScopedFlags: executionPlan.startupScopedFlags,
 						validationError: executionPlan.validationError,
 					},
@@ -235,6 +308,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				content: [{ type: "text", text: `Running agent-browser ${buildInvocationPreview(executionPlan.effectiveArgs)}` }],
 				details: {
 					effectiveArgs: executionPlan.effectiveArgs,
+					sessionMode,
 					sessionName: executionPlan.sessionName,
 					usedImplicitSession: executionPlan.usedImplicitSession,
 				},
@@ -257,6 +331,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					details: {
 						args: params.args,
 						effectiveArgs: executionPlan.effectiveArgs,
+						sessionMode,
 						spawnError: processResult.spawnError.message,
 					},
 					isError: true,
@@ -268,12 +343,28 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					stdout: processResult.stdout,
 					stdoutPath: processResult.stdoutSpillPath,
 				});
+				let presentationEnvelope = parsed.envelope;
 				const processSucceeded = !processResult.aborted && !processResult.spawnError && processResult.exitCode === 0;
 				const plainTextInspection = isPlainTextInspectionArgs(params.args) && processSucceeded && parsed.parseError !== undefined;
 				const envelopeSuccess = plainTextInspection ? true : parsed.envelope?.success !== false;
 				const parseSucceeded = plainTextInspection || parsed.parseError === undefined;
 				const succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
 
+				let navigationSummary: NavigationSummary | undefined;
+				if (succeeded && shouldCaptureNavigationSummary(executionPlan.commandInfo.command, parsed.envelope?.data)) {
+					navigationSummary = await collectNavigationSummary({
+						cwd: ctx.cwd,
+						sessionName: executionPlan.sessionName,
+						signal,
+					});
+					if (navigationSummary && presentationEnvelope) {
+						presentationEnvelope = {
+							...presentationEnvelope,
+							data: mergeNavigationSummaryIntoData(presentationEnvelope.data, navigationSummary),
+						};
+					}
+				}
+
 				implicitSessionActive = resolveImplicitSessionActiveState({
 					command: executionPlan.commandInfo.command,
 					priorActive: implicitSessionActive,
@@ -300,7 +391,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					: await buildToolPresentation({
 							commandInfo: executionPlan.commandInfo,
 							cwd: ctx.cwd,
-							envelope: parsed.envelope,
+							envelope: presentationEnvelope,
 							errorText,
 					  });
 
@@ -308,16 +399,22 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					content: presentation.content,
 					details: {
 						args: params.args,
+						batchSteps: presentation.batchSteps,
 						command: executionPlan.commandInfo.command,
 						subcommand: executionPlan.commandInfo.subcommand,
 						data: presentation.data,
 						error: parsed.envelope?.error,
+						navigationSummary,
 						effectiveArgs: executionPlan.effectiveArgs,
 						exitCode: processResult.exitCode,
 						fullOutputPath: presentation.fullOutputPath,
+						fullOutputPaths: presentation.fullOutputPaths,
 						imagePath: presentation.imagePath,
+						imagePaths: presentation.imagePaths,
 						parseError: parsed.parseError,
+						sessionMode,
 						sessionName: executionPlan.sessionName,
+						sessionRecoveryHint: executionPlan.recoveryHint,
 						startupScopedFlags: executionPlan.startupScopedFlags,
 						stderr: processResult.stderr || undefined,
 						stdout: parseSucceeded ? undefined : processResult.stdout,

package/extensions/agent-browser/lib/results/presentation.ts

@@ -9,9 +9,17 @@
 import { readFile, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 
-import type { CommandInfo } from "../runtime.js";
+import { parseCommandInfo, type CommandInfo } from "../runtime.js";
 import { buildSnapshotPresentation, formatRawSnapshotText, formatSnapshotSummary } from "./snapshot.js";
-import { type AgentBrowserBatchResult, type AgentBrowserEnvelope, type ToolPresentation, isRecord, parsePositiveInteger, stringifyUnknown } from "./shared.js";
+import {
+	type AgentBrowserBatchResult,
+	type AgentBrowserEnvelope,
+	type BatchStepPresentationDetails,
+	type ToolPresentation,
+	isRecord,
+	parsePositiveInteger,
+	stringifyUnknown,
+} from "./shared.js";
 
 const IMAGE_EXTENSION_TO_MIME_TYPE: Record<string, string> = {
 	".gif": "image/gif",
@@ -23,6 +31,13 @@ const IMAGE_EXTENSION_TO_MIME_TYPE: Record<string, string> = {
 
 const INLINE_IMAGE_MAX_BYTES_ENV = "PI_AGENT_BROWSER_INLINE_IMAGE_MAX_BYTES";
 const DEFAULT_INLINE_IMAGE_MAX_BYTES = 5 * 1_024 * 1_024;
+const NAVIGATION_SUMMARY_COMMANDS = new Set(["back", "click", "dblclick", "forward", "reload"]);
+const NAVIGATION_SUMMARY_FIELD = "navigationSummary";
+
+interface NavigationSummary {
+	title?: string;
+	url?: string;
+}
 
 function getImageMimeType(filePath: string): string | undefined {
 	const extension = filePath.toLowerCase().slice(filePath.lastIndexOf("."));
@@ -90,24 +105,213 @@ function getScreenshotSummary(data: Record<string, unknown>): string | undefined
 	return typeof data.path === "string" ? `Saved image: ${data.path}` : undefined;
 }
 
-function formatBatchContent(data: AgentBrowserBatchResult[]): string {
-	return data
-		.map((item, index) => {
-			const command = Array.isArray(item.command) ? item.command.join(" ") : `step-${index + 1}`;
-			if (item.success === false) {
-				return `${command}\nError: ${stringifyUnknown(item.error)}`;
-			}
-			return `${command}\n${stringifyUnknown(item.result)}`;
-		})
+function isNavigationObservableCommand(command: string | undefined): boolean {
+	return command !== undefined && NAVIGATION_SUMMARY_COMMANDS.has(command);
+}
+
+function isNavigationSummary(value: unknown): value is NavigationSummary {
+	return isRecord(value) && (typeof value.title === "string" || typeof value.url === "string");
+}
+
+function getNavigationSummary(data: Record<string, unknown>): NavigationSummary | undefined {
+	const candidate = data[NAVIGATION_SUMMARY_FIELD];
+	return isNavigationSummary(candidate) ? candidate : undefined;
+}
+
+function formatNavigationSummary(summary: NavigationSummary): string | undefined {
+	const title = typeof summary.title === "string" && summary.title.trim().length > 0 ? summary.title.trim() : undefined;
+	const url = typeof summary.url === "string" && summary.url.trim().length > 0 ? summary.url.trim() : undefined;
+	if (!title && !url) return undefined;
+	if (title && url) return `${title}\n${url}`;
+	return title ?? url;
+}
+
+function stripNavigationSummary(data: Record<string, unknown>): Record<string, unknown> {
+	const { [NAVIGATION_SUMMARY_FIELD]: _navigationSummary, ...rest } = data;
+	return rest;
+}
+
+function formatNavigationActionResult(data: Record<string, unknown>): string | undefined {
+	const actionData = stripNavigationSummary(data);
+	const lines: string[] = [];
+	if (typeof actionData.clicked === "string" || typeof actionData.clicked === "boolean") {
+		lines.push(`Clicked: ${String(actionData.clicked)}`);
+	}
+	if (typeof actionData.href === "string") {
+		lines.push(`Href: ${actionData.href}`);
+	}
+	if (typeof actionData.navigated === "boolean") {
+		lines.push(`Navigated: ${actionData.navigated}`);
+	}
+	if (lines.length > 0) {
+		return lines.join("\n");
+	}
+
+	const actionText = stringifyUnknown(actionData).trim();
+	if (actionText.length === 0 || actionText === "{}") {
+		return undefined;
+	}
+	return actionText;
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function getPresentationText(presentation: ToolPresentation): string {
+	return presentation.content
+		.filter((part): part is Extract<ToolPresentation["content"][number], { type: "text" }> => part.type === "text")
+		.map((part) => part.text.trim())
+		.filter((text) => text.length > 0)
 		.join("\n\n");
 }
 
+function getPresentationImages(presentation: ToolPresentation): Array<Extract<ToolPresentation["content"][number], { type: "image" }>> {
+	return presentation.content.filter(
+		(part): part is Extract<ToolPresentation["content"][number], { type: "image" }> => part.type === "image",
+	);
+}
+
+function getPresentationPaths(options: {
+	primaryPath?: string;
+	secondaryPaths?: string[];
+}): string[] {
+	return options.secondaryPaths ?? (options.primaryPath ? [options.primaryPath] : []);
+}
+
+function formatBatchStepCommand(command: string[] | undefined, index: number): string {
+	return command && command.length > 0 ? command.join(" ") : `step-${index + 1}`;
+}
+
+function formatBatchStepError(error: unknown): string {
+	const errorText = stringifyUnknown(error).trim();
+	return errorText.length > 0 ? `Error: ${errorText}` : "Error: batch step failed.";
+}
+
+async function buildBatchStepPresentation(options: {
+	cwd: string;
+	index: number;
+	item: AgentBrowserBatchResult;
+}): Promise<{ details: BatchStepPresentationDetails; presentation: ToolPresentation }> {
+	const { cwd, index, item } = options;
+	const command = isStringArray(item.command) ? item.command : undefined;
+	const commandText = formatBatchStepCommand(command, index);
+
+	if (item.success === false) {
+		const errorText = formatBatchStepError(item.error);
+		const presentation: ToolPresentation = {
+			content: [{ type: "text", text: errorText }],
+			summary: errorText,
+		};
+		return {
+			details: {
+				command,
+				commandText,
+				data: item.error,
+				index,
+				success: false,
+				summary: errorText,
+				text: errorText,
+			},
+			presentation,
+		};
+	}
+
+	const presentation = await buildToolPresentation({
+		commandInfo: parseCommandInfo(command ?? []),
+		cwd,
+		envelope: { data: item.result, success: true },
+	});
+	const fullOutputPaths = getPresentationPaths({
+		primaryPath: presentation.fullOutputPath,
+		secondaryPaths: presentation.fullOutputPaths,
+	});
+	const imagePaths = getPresentationPaths({
+		primaryPath: presentation.imagePath,
+		secondaryPaths: presentation.imagePaths,
+	});
+	const text = getPresentationText(presentation) || presentation.summary;
+
+	return {
+		details: {
+			command,
+			commandText,
+			data: presentation.data,
+			fullOutputPath: fullOutputPaths[0],
+			fullOutputPaths: fullOutputPaths.length > 0 ? fullOutputPaths : undefined,
+			imagePath: imagePaths[0],
+			imagePaths: imagePaths.length > 0 ? imagePaths : undefined,
+			index,
+			success: true,
+			summary: presentation.summary,
+			text,
+		},
+		presentation,
+	};
+}
+
+async function buildBatchPresentation(options: {
+	cwd: string;
+	data: AgentBrowserBatchResult[];
+	summary: string;
+}): Promise<ToolPresentation> {
+	const { cwd, data, summary } = options;
+	const steps: Array<{ details: BatchStepPresentationDetails; presentation: ToolPresentation }> = [];
+	for (const [index, item] of data.entries()) {
+		steps.push(await buildBatchStepPresentation({ cwd, index, item }));
+	}
+
+	const images = steps.flatMap((step) => getPresentationImages(step.presentation));
+	const fullOutputPaths = steps.flatMap((step) => getPresentationPaths({
+		primaryPath: step.presentation.fullOutputPath,
+		secondaryPaths: step.presentation.fullOutputPaths,
+	}));
+	const imagePaths = steps.flatMap((step) => getPresentationPaths({
+		primaryPath: step.presentation.imagePath,
+		secondaryPaths: step.presentation.imagePaths,
+	}));
+	const text =
+		steps.length === 0
+			? "(no batch steps)"
+			: steps
+				.map(({ details, presentation }) => {
+					const inlineImageCount = getPresentationImages(presentation).length;
+					const lines = [`Step ${details.index + 1} — ${details.commandText}`];
+					if (details.text.length > 0) {
+						lines.push(details.text);
+					}
+					if (inlineImageCount > 0) {
+						lines.push(`(${inlineImageCount} inline image attachment${inlineImageCount === 1 ? "" : "s"} below)`);
+					}
+					return lines.join("\n");
+				})
+				.join("\n\n");
+
+	return {
+		batchSteps: steps.map((step) => step.details),
+		content: [{ type: "text", text }, ...images],
+		data,
+		fullOutputPath: fullOutputPaths[0],
+		fullOutputPaths: fullOutputPaths.length > 0 ? fullOutputPaths : undefined,
+		imagePath: imagePaths[0],
+		imagePaths: imagePaths.length > 0 ? imagePaths : undefined,
+		summary,
+	};
+}
+
 function formatSummary(commandInfo: CommandInfo, data: unknown): string {
 	if (Array.isArray(data) && commandInfo.command === "batch") {
 		const successCount = data.filter((item) => isRecord(item) && item.success !== false).length;
 		return `Batch: ${successCount}/${data.length} succeeded`;
 	}
 	if (isRecord(data)) {
+		const navigationSummary = getNavigationSummary(data);
+		if (navigationSummary && isNavigationObservableCommand(commandInfo.command)) {
+			const navigationText = formatNavigationSummary(navigationSummary);
+			if (navigationText) {
+				return `${commandInfo.command ?? "navigation"} → ${navigationText.split("\n", 1)[0] ?? navigationText}`;
+			}
+		}
 		if (commandInfo.command === "snapshot") {
 			return formatSnapshotSummary(data);
 		}
@@ -136,9 +340,6 @@ function formatSummary(commandInfo: CommandInfo, data: unknown): string {
 }
 
 function formatContentText(commandInfo: CommandInfo, data: unknown): string {
-	if (Array.isArray(data) && commandInfo.command === "batch") {
-		return formatBatchContent(data as AgentBrowserBatchResult[]);
-	}
 	if (typeof data === "string") {
 		return data;
 	}
@@ -149,6 +350,15 @@ function formatContentText(commandInfo: CommandInfo, data: unknown): string {
 		return stringifyUnknown(data);
 	}
 
+	const navigationSummary = getNavigationSummary(data);
+	if (navigationSummary && isNavigationObservableCommand(commandInfo.command)) {
+		const navigationText = formatNavigationSummary(navigationSummary);
+		if (navigationText) {
+			const actionText = formatNavigationActionResult(data);
+			return actionText ? `${actionText}\n\nCurrent page:\n${navigationText}` : `Current page:\n${navigationText}`;
+		}
+	}
+
 	if (commandInfo.command === "snapshot") {
 		return formatRawSnapshotText(data);
 	}
@@ -232,13 +442,15 @@ export async function buildToolPresentation(options: {
 	const data = envelope?.data;
 	const summary = formatSummary(commandInfo, data);
 	const presentation =
-		commandInfo.command === "snapshot" && isRecord(data)
-			? await buildSnapshotPresentation(data)
-			: {
-					content: [{ type: "text" as const, text: formatContentText(commandInfo, data) }],
-					data,
-					summary,
-			  };
+		commandInfo.command === "batch" && Array.isArray(data)
+			? await buildBatchPresentation({ cwd, data: data as AgentBrowserBatchResult[], summary })
+			: commandInfo.command === "snapshot" && isRecord(data)
+				? await buildSnapshotPresentation(data)
+				: {
+						content: [{ type: "text" as const, text: formatContentText(commandInfo, data) }],
+						data,
+						summary,
+				  };
 
 	const imagePath = extractImagePath(cwd, data);
 	if (!imagePath) {

package/extensions/agent-browser/lib/results/shared.ts

@@ -19,11 +19,28 @@ export interface AgentBrowserBatchResult {
 	success?: boolean;
 }
 
+export interface BatchStepPresentationDetails {
+	command?: string[];
+	commandText: string;
+	data?: unknown;
+	fullOutputPath?: string;
+	fullOutputPaths?: string[];
+	imagePath?: string;
+	imagePaths?: string[];
+	index: number;
+	success: boolean;
+	summary: string;
+	text: string;
+}
+
 export interface ToolPresentation {
+	batchSteps?: BatchStepPresentationDetails[];
 	content: Array<{ text: string; type: "text" } | { data: string; mimeType: string; type: "image" }>;
 	data?: unknown;
 	fullOutputPath?: string;
+	fullOutputPaths?: string[];
 	imagePath?: string;
+	imagePaths?: string[];
 	summary: string;
 }
 

package/extensions/agent-browser/lib/results/snapshot.ts

@@ -12,11 +12,13 @@ import { type ToolPresentation, compareRefIds, countLines, isRecord, normalizeWh
 const SNAPSHOT_INLINE_MAX_CHARS = 6_000;
 const SNAPSHOT_INLINE_MAX_LINES = 80;
 const SNAPSHOT_INLINE_MAX_REFS = 60;
-const SNAPSHOT_PRIMARY_PREVIEW_LINES = 10;
-const SNAPSHOT_SECTION_PREVIEW_LINES = 4;
-const SNAPSHOT_MAX_ADDITIONAL_SECTIONS = 5;
-const SNAPSHOT_KEY_REF_MAX_LINES = 20;
-const SNAPSHOT_OTHER_REF_MAX_LINES = 12;
+const SNAPSHOT_PRIMARY_PREVIEW_LINES = 8;
+const SNAPSHOT_SECTION_PREVIEW_LINES = 2;
+const SNAPSHOT_MAX_ADDITIONAL_SECTIONS = 2;
+const SNAPSHOT_KEY_REF_MAX_LINES = 8;
+const SNAPSHOT_OTHER_REF_MAX_LINES = 4;
+const SNAPSHOT_ROLE_COUNT_MAX_ENTRIES = 4;
+const SNAPSHOT_FALLBACK_PREVIEW_MAX_LINES = 12;
 const SNAPSHOT_NAME_MAX_CHARS = 96;
 const SNAPSHOT_LINE_MAX_CHARS = 140;
 const SNAPSHOT_SPILL_FILE_PREFIX = "pi-agent-browser-snapshot";
@@ -165,7 +167,12 @@ function formatRoleCounts(roleCounts: Record<string, number>): string | undefine
 		if (right[1] !== left[1]) return right[1] - left[1];
 		return getRolePriority(left[0]) - getRolePriority(right[0]);
 	});
-	return ordered.map(([role, count]) => `${role} ${count}`).join(", ");
+	const visibleEntries = ordered.slice(0, SNAPSHOT_ROLE_COUNT_MAX_ENTRIES).map(([role, count]) => `${role} ${count}`);
+	const omittedEntries = Math.max(0, ordered.length - visibleEntries.length);
+	if (omittedEntries > 0) {
+		visibleEntries.push(`+${omittedEntries} more`);
+	}
+	return visibleEntries.join(", ");
 }
 
 function parseSnapshotLines(snapshot: string): SnapshotLine[] {
@@ -373,10 +380,10 @@ function buildSegmentPreview(segment: SnapshotSegment, maxLines: number): Snapsh
 
 function buildFallbackSnapshotOutline(snapshotLines: SnapshotLine[]): SnapshotPreview {
 	const selected = new Set<number>();
-	for (let index = 0; index < snapshotLines.length && selected.size < 6; index += 1) {
+	for (let index = 0; index < snapshotLines.length && selected.size < 4; index += 1) {
 		if (!isNoiseSnapshotLine(snapshotLines[index])) selected.add(index);
 	}
-	for (let index = 0; index < snapshotLines.length && selected.size < 18; index += 1) {
+	for (let index = 0; index < snapshotLines.length && selected.size < SNAPSHOT_FALLBACK_PREVIEW_MAX_LINES; index += 1) {
 		const line = snapshotLines[index];
 		if (isNoiseSnapshotLine(line)) continue;
 		if (SNAPSHOT_SIGNAL_ROLES.has(line.role) || line.ref || line.name.length > 0) {
@@ -385,7 +392,7 @@ function buildFallbackSnapshotOutline(snapshotLines: SnapshotLine[]): SnapshotPr
 	}
 	const chosenLines = [...selected]
 		.sort((left, right) => left - right)
-		.slice(0, 18)
+		.slice(0, SNAPSHOT_FALLBACK_PREVIEW_MAX_LINES)
 		.map((index) => snapshotLines[index]);
 	return {
 		omittedCount: Math.max(0, snapshotLines.length - chosenLines.length),
@@ -508,6 +515,8 @@ export async function buildSnapshotPresentation(data: Record<string, unknown>):
 	const snapshotSegments = useStructuredPreview ? buildSnapshotSegments(snapshotLines) : [];
 	const primarySegment = useStructuredPreview ? choosePrimarySegment(snapshotSegments) : undefined;
 	const additionalSegments = useStructuredPreview ? chooseAdditionalSegments(snapshotSegments, primarySegment) : [];
+	const additionalSegmentCount = useStructuredPreview && primarySegment ? Math.max(0, snapshotSegments.length - 1) : 0;
+	const omittedAdditionalSectionCount = Math.max(0, additionalSegmentCount - additionalSegments.length);
 	const primaryPreview = primarySegment ? buildSegmentPreview(primarySegment, SNAPSHOT_PRIMARY_PREVIEW_LINES) : undefined;
 	const additionalPreviews = additionalSegments
 		.map((segment) => ({
@@ -548,11 +557,9 @@ export async function buildSnapshotPresentation(data: Record<string, unknown>):
 	const lines: string[] = [
 		`Origin: ${origin}`,
 		`Refs: ${refEntries.length}`,
-		...(roleCountsText ? [`Roles: ${roleCountsText}`] : []),
+		...(roleCountsText ? [`Top roles: ${roleCountsText}`] : []),
 		"",
-		fullOutputPath
-			? `Compact snapshot view. Full raw snapshot: ${fullOutputPath}`
-			: `Compact snapshot view. Full raw snapshot unavailable: ${spillErrorText ?? "temp spill file could not be created."}`,
+		"Compact snapshot view.",
 	];
 
 	if (fallbackPreview) {
@@ -581,6 +588,9 @@ export async function buildSnapshotPresentation(data: Record<string, unknown>):
 					lines.push(`- ... (${preview.omittedCount} more lines in this section)`);
 				}
 			});
+			if (omittedAdditionalSectionCount > 0) {
+				lines.push(`- ... (${omittedAdditionalSectionCount} more sections omitted)`);
+			}
 		}
 	}
 
@@ -589,11 +599,16 @@ export async function buildSnapshotPresentation(data: Record<string, unknown>):
 		lines.push("", "Other refs:", ...otherRefEntries.map(formatCompactRef));
 	}
 	if (omittedOtherRefs > 0) {
-		lines.push(
-			`- ... (${omittedOtherRefs} additional refs ${fullOutputPath ? "in the full snapshot file" : "were omitted with the full raw snapshot"})`,
-		);
+		lines.push(`- ... (${omittedOtherRefs} additional refs omitted)`);
 	}
 
+	lines.push(
+		"",
+		fullOutputPath
+			? "Full raw snapshot path is available in details.fullOutputPath."
+			: `Full raw snapshot unavailable: ${spillErrorText ?? "temp spill file could not be created."}`,
+	);
+
 	return {
 		content: [{ type: "text", text: lines.join("\n") }],
 		data: {
@@ -603,6 +618,7 @@ export async function buildSnapshotPresentation(data: Record<string, unknown>):
 			previewMode: fallbackPreview ? "outline" : "structured",
 			spillError: spillErrorText,
 			previewRefIds: [...previewRefIds],
+			additionalSectionsOmitted: omittedAdditionalSectionCount,
 			previewSections: [
 				...(primarySegment
 					? [

package/extensions/agent-browser/lib/runtime.ts

@@ -16,13 +16,6 @@ const IMPLICIT_SESSION_IDLE_TIMEOUT_ENV = "PI_AGENT_BROWSER_IMPLICIT_SESSION_IDL
 const IMPLICIT_SESSION_CLOSE_TIMEOUT_ENV = "PI_AGENT_BROWSER_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS";
 const DEFAULT_IMPLICIT_SESSION_IDLE_TIMEOUT_MS = 15 * 60 * 1000;
 const DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS = 5_000;
-const INSPECTION_ALLOW_PATTERNS = [
-	/\bagent[_ -]?browser\s+--(?:help|version)\b/i,
-	/\bagent[_ -]?browser\b.*\b(?:help|version|docs?|documentation|tool contract|tool guidance|tool description)\b/i,
-	/\b(?:help|version|docs?|documentation|tool contract|tool guidance|tool description)\b.*\bagent[_ -]?browser\b/i,
-	/\bdebug(?:ging)?\b.*\b(?:agent[_ -]?browser|agent_browser|browser integration)\b/i,
-	/\bwhy\s+(?:isn't|is not|doesn't|does not)\b.*\b(?:agent[_ -]?browser|agent_browser)\b/i,
-];
 const LEGACY_BASH_ALLOW_PATTERNS = [
 	/\b(?:bash-oriented workflow|bash workflow)\b/i,
 	/\b(?:use|via|through|with)\s+bash\b/i,
@@ -62,9 +55,19 @@ export interface CommandInfo {
 	subcommand?: string;
 }
 
+export type SessionMode = "auto" | "fresh";
+
+export interface SessionRecoveryHint {
+	exampleArgs: string[];
+	exampleParams: { args: string[]; sessionMode: "fresh" };
+	reason: string;
+	recommendedSessionMode: "fresh";
+}
+
 export interface ExecutionPlan {
 	commandInfo: CommandInfo;
 	effectiveArgs: string[];
+	recoveryHint?: SessionRecoveryHint;
 	sessionName?: string;
 	startupScopedFlags: string[];
 	usedImplicitSession: boolean;
@@ -72,7 +75,6 @@ export interface ExecutionPlan {
 }
 
 export interface PromptPolicy {
-	allowAgentBrowserInspection: boolean;
 	allowLegacyAgentBrowserBash: boolean;
 }
 
@@ -177,7 +179,6 @@ export function getStartupScopedFlags(args: string[]): string[] {
 
 export function buildPromptPolicy(prompt: string): PromptPolicy {
 	return {
-		allowAgentBrowserInspection: INSPECTION_ALLOW_PATTERNS.some((pattern) => pattern.test(prompt)),
 		allowLegacyAgentBrowserBash: LEGACY_BASH_ALLOW_PATTERNS.some((pattern) => pattern.test(prompt)),
 	};
 }
@@ -212,21 +213,29 @@ export function getLatestUserPrompt(branch: unknown[]): string {
 
 export function buildExecutionPlan(
 	args: string[],
-	options: { implicitSessionActive: boolean; implicitSessionName: string; useActiveSession: boolean },
+	options: { implicitSessionActive: boolean; implicitSessionName: string; sessionMode: SessionMode },
 ): ExecutionPlan {
 	const commandInfo = parseCommandInfo(args);
 	const explicitSessionName = extractExplicitSessionName(args);
 	const startupScopedFlags = getStartupScopedFlags(args);
 	const effectiveArgs = args.includes("--json") ? [] : ["--json"];
+	let recoveryHint: SessionRecoveryHint | undefined;
 	let sessionName = explicitSessionName;
 	let usedImplicitSession = false;
 	let validationError: string | undefined;
 
-	if (!explicitSessionName && options.useActiveSession) {
+	if (!explicitSessionName && options.sessionMode === "auto") {
 		if (options.implicitSessionActive && startupScopedFlags.length > 0) {
+			recoveryHint = {
+				exampleArgs: args,
+				exampleParams: { args, sessionMode: "fresh" },
+				reason:
+					"Startup-scoped flags like --profile, --session-name, and --cdp need a fresh upstream launch once the implicit session is already active.",
+				recommendedSessionMode: "fresh",
+			};
 			validationError = [
 				`The current implicit agent-browser session is already running, so startup-scoped flags ${startupScopedFlags.join(", ")} would be ignored by upstream agent-browser.`,
-				"Reuse the existing implicit session without those flags, or start a fresh upstream session explicitly with `--session ...` (or `useActiveSession: false`) for a new launch.",
+				"Retry this call with `sessionMode: \"fresh\"` to force a fresh upstream launch, or pass an explicit `--session ...` if you want to name the new session yourself.",
 			].join(" ");
 		} else {
 			effectiveArgs.push("--session", options.implicitSessionName);
@@ -240,6 +249,7 @@ export function buildExecutionPlan(
 	return {
 		commandInfo,
 		effectiveArgs,
+		recoveryHint,
 		sessionName,
 		startupScopedFlags,
 		usedImplicitSession,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",